Product Home • Class Index • Download

CK_Screen

CK_Object
   |
   +----CK_Screen

An application using the Chilkat SDK will run in one or more screens. A game application might have an intro screen, an options screen, a credits screen, the main playing screen, level-change screens, multi-player setup screens, etc. Each screen has a top-level component (CK_Component) which is usually a manager component such as a bulletin board (CK_BBoard) or row-column (CK_RowColumn). An application will start in one screen and can easily switch to another screen by calling the makeVisible() member function.

The CK_Screen class is designed to be used as a base class. Each screen in the application will be represented by an application-provided class that inherits CK_Screen. For example, the application might define a credits screen as shown below:

class CreditScreen : public CK_Screen
    {
    // The CreditsScreen will override some or all of the keyboard/mouse
    // callback functions.  This is explained below.
    ...
    };

The screen that is currently visible will receive keyboard and mouse input callbacks. The CK_Screen class has member functions that are intended to be overridden by an application defined screen class. For keyboard input, the application can override the following member functions:

	// Process a WM_KEYDOWN Windows message.
	virtual void processKeyDown(WPARAM wParam, LPARAM lParam);
	// Process a WM_CHAR Windows message.
	virtual void processChar(WPARAM wParam, LPARAM lParam);
	// Process a WM_KEYUP Windows message.
	virtual void processKeyUp(WPARAM wParam, LPARAM lParam);

All mouse input is handled by the componentCB() function, which can be overridden by the application's class. The componentCB() function will be called for all button clicks and mouse movement within the screen. The arguments to componentCB() identify the component in which the event occured, the type of event that occured, and user-defined arguments passed from the component to the callback. The componentCB() function is also called when the mouse enters and/or leaves any component.

	// Classes inheriting CK_Screen will override this member function
        // to hanndle mouse input.
        virtual void componentCB(CK_Component *comp,
	    int event, int arg1, int arg2) { }

The CK_Screen class also provides for cheat codes to be defined, and provides a cheat code callback that can be overridden. The callback is called whenever an application-specified cheat code is typed. The callback function is shown below. The cheat code that was typed is passed to the function.

	virtual void processCheatCode(const char *cheatCode) { }

The CK_Screen class can also be used as a dialog to be popped-up and popped-down over the application's currently visible screen. Dialogs behave in the same way as a normal screen, except that they are displayed on top of the currently visible screen. Dialogs are modal, and only one dialog may be popped-up at a time.

Ownership of Component Tree

A CK_Screen owns its component tree. If the CK_Screen is deleted, the component tree will also be deleted. Because of this, two screens should not share instances of components.

Observing the Component Tree

A CK_Screen observes its top-level component. If this component is deleted, the screen will become blank and the screen will no longer have a component tree.

Constructors

CK_Screen

Default constructor with no arguments.

CK_Screen(CK_Component *top)

Constructor that also sets the top-level component.

Public Methods

componentCB

Overridable callback for all mouse related events.

enteringScreen

Overrideable callback that is called just before switching the display to a screen.

getEventXY

Returns the screen coordinates of the last mouse event.

getWindow

Gets the handle to the window for the application.

isAltDown

Returns TRUE if the ALT key is currently held down.

isControlDown

Returns TRUE if the Control key is currently held down.

isDialog

Returns TRUE if the screen is a dialog.

isShiftDown

Returns TRUE if the SHIFT key is currently held down.

leavingScreen

Overridable callback that is called when switching the display to another screen.

makeVisible

Called to switch the display to another screen.

popdown

Pops down a dialog.

popup

Pops up a dialog.

processChar

Overrideable callback to process a WM_CHAR message.

processCheatCode

Overridable callback that is called when a registered cheat code is recognized.

processKeyDown

Overridable callback to process a WM_KEYDOWN message.

processKeyUp

Overridable callback to process a WM_KEYUP message.

registerCheatCode

Registers a cheat code that will be recognized when typed.

setCharCallback

Alternative way to get WM_CHAR messages.

setCheatCodeCallback

Alternative way to get cheat-code callbacks.

setCursor (v1.02)

Sets a custom cursor for the screen.

setDialog

Makes the screen a dialog.

setEnterScreenCallback

Alternative way to call an application function  just before the screen is entered.

setEventCallback

Alternative way to get mouse events.  Passes a pointer to a function that the CK_Screen object will call for mouse events.

setKeyDownCallback

Alternative way to get WM_KEYDOWN messages

setKeyUpCallback

Alternative way to get WM_KEYUP messages.

setLeaveScreenCallback

Alternative way to call an application function just before the screen is exited.

setTopComponent

Sets the top component for the screen.

• CK_Screen(void);

This is the default constructor. If a screen is created with this constructor, the top component must be set by calling setTopComponent() before the screen can be made visible.

• CK_Screen(CK_Component *top);

This constructor is the same as the default constructor, with the added feature of setting the top-level component.

Parameters

top

The top-level component of a component tree. Typically, this is a manager component such as a bulletin board (CK_BBoard) or row-column (CK_RowColumn).

• virtual void componentCB(CK_Component *comp, int event, int arg1, int arg2) { }

This function is called for each mouse event that occurs. By default, it does nothing. It is intended to be overridden by an application class that derives from CK_Screen. The application can then handle mouse events.

Parameters

comp

This is the component where the event occured.

event

The type of mouse event that occured. The possible types are:

enum ComponentEvents
{
CEV_MouseMove,
CEV_LeftButtonDown,
CEV_LeftButtonUp,
CEV_RightButtonDown,
CEV_RightButtonUp,
CEV_EnterComponent, // The mouse pointer enters the component.
CEV_LeaveComponent, // The mouse pointer leaves the component.
CEV_ScrollHandleMove
};

This enumeration is in ck_component.h. See Example 19 for an example that responds to CEV_EnterComponent and CEV_LeaveComponent.

arg1

The value of the CP_CallbackArg1 property of the component where the event occured.

arg2

The value of the CP_CallbackArg2 property of the component where the event occured.

• virtual void enteringScreen(void) { }

This function is called just before a screen is made visible. It is intended to be overridden by an application class derived from CK_Screen. This callback might be used to start the screen's animated bitmaps just before the screen becomes visible.

• void getEventXY(int &x, int &y) const;

Gets the screen pixel coordinates of the last mouse event that occured.

• HWND getWindow(void) const;

Returns the handle of the application's main window.

• BOOL isAltDown(void) const;

Returns TRUE if the ALT key is currently held down.

• BOOL isControlDown(void) const;

Returns TRUE if the Control key is currently held down.

• int isDialog(void) const;

Returns TRUE if the screen is a dialog.

• BOOL isShiftDown(void) const;

Returns TRUE if the SHIFT key is currently held down.

• virtual void leavingScreen(void) { }

This function is called when switching screens, just after a screen is made non-visible, and before the next screen is made visible. It is intended to be overridden by an application class derived from CK_Screen. This callback might be used to stop the screen's animated bitmaps just after the screen becomes non-visible.

• void makeVisible(void);

Makes the screen the currently visible screen. The screen becoming non-visible will have its leavingScreen() function called, and the screen becoming visible will have its enteringScreen() function called.

• void popdown(void);

Pops-down the dialog. If this is not the dialog that is popped up, then nothing will happen.

• void popup(void);

Pops-up the dialog. The dialog is modal, and no other dialog can already be popped up.

• virtual void processChar(WPARAM wParam, LPARAM lParam);

Called when a WM_CHAR Windows message is received. This function can be overridden by application classes derived from CK_Screen.

Parameters

wParam

This is the WPARAM parameter passed to the library's WindowProc that handles Windows messages.

lParam

This is the LPARAM parameter passed to the library's WindowProc that handles Windows messages.

• virtual void processCheatCode(const char *cheatCode) { }

Called when a registered cheat code is recognized. The application can register a cheat code by calling registerCheatCode(). This function is intended to be overridden by application classes derived from CK_Screen.

Parameters

cheatCode

The cheat code that was recognized. The cheat code is case sensitive.

• virtual void processKeyDown(WPARAM wParam, LPARAM lParam);

Called when a WM_KEYDOWN Windows message is received. This function can be overridden by application classes derived from CK_Screen.

Parameters

wParam

This is the WPARAM parameter passed to the library's WindowProc that handles Windows messages.

lParam

This is the LPARAM parameter passed to the library's WindowProc that handles Windows messages.

• virtual void processKeyUp(WPARAM wParam, LPARAM lParam);

Called when a WM_KEYUP Windows message is received. This function can be overridden by application classes derived from CK_Screen.

Parameters

wParam

This is the WPARAM parameter passed to the library's WindowProc that handles Windows messages.

lParam

This is the LPARAM parameter passed to the library's WindowProc that handles Windows messages.

• void registerCheatCode(const char *cheatCode);

Registers a cheat code with the screen. When the screen is visible, the library will recognize when the cheat code is typed, and will call the screen's processCheatCode() callback.

Parameters

cheatCode

The case-sensitive cheat code that is to be registered.

• void setCharCallback(void (*callback)(WPARAM wParam, LPARAM lParam));

Registers an application function that will be called when a WM_CHAR message is received.  Another way to get WM_CHAR messages is to create a new class that inherits CK_Screen, and provides an implementation for the processChar() member function.

Parameters

callback

A pointer to the application function to be called.

• void setCheatCodeCallback(void (*callback)(const char *cheatCode));

Registers an application function that will be called when a cheat code is recognized in the keyboard input.  Another way to get cheat-code notifications is to create a new class that inherits CK_Screen, and provides an implementation for the processCheatCode() member function.

Parameters

callback

A pointer to the application function to be called.

• void setCursor(CK_Cursor *cursor);

Sets a custom cursor for the screen.  Cursors can be static or animated, but must be 64x64 pixels or less in size.

Parameters

cursor

A pointer to a CK_Cursor object, which contains a CK_Bitmap and the x,y coordinates for the hotspot.   Since a CK_Bitmap can be either a CK_StaticBitmap or a CK_Animation, cursors can be static or animated, and can be any pixel depth.

• void setDialog(int is_a_dialog);

After the screen is created, this function can be called to make it a dialog. Dialogs are popped up by calling popup(), and popped down by calling popdown().

Parameters

is_a_dialog

If TRUE, then the screen is made a dialog. If FALSE, it is made a normal screen.

• void setEnterScreenCallback(void (*callback)(void));

Registers an application function that will be called just before the screen is made visible.  Another way to do this is to create a new class that inherits CK_Screen, and provides an implementation for the enteringScreen() member function.

Parameters

callback

A pointer to the application function to be called.

• void setEventCallback(void (*callback)(CK_Component *c,int event,int arg1,int arg2));

Registers an application function that will be called for all mouse events.   Another way to do this is to create a new class that inherits CK_Screen, and provides an implementation for the componentCB() member function.

Parameters

callback

A pointer to the application function to be called.

• void setKeyDownCallback(void (*callback)(WPARAM wParam, LPARAM lParam));

Registers an application function that will be called for WM_KEYDOWN events.   Another way to do this is to create a new class that inherits CK_Screen, and provides an implementation for the processKeyDown() member function.

Parameters

callback

A pointer to the application function to be called.

• void setKeyUpCallback(void (*callback)(WPARAM wParam, LPARAM lParam));

Registers an application function that will be called for WM_KEYUP events.   Another way to do this is to create a new class that inherits CK_Screen, and provides an implementation for the processKeyUp() member function.

Parameters

callback

A pointer to the application function to be called.

• void setLeaveScreenCallback(void (*callback)(void));

Registers an application function that will be called just before the screen is left (i.e. another screen is made visible).  Another way to do this is to create a new class that inherits CK_Screen, and provides an implementation for the leavingScreen() member function.

Parameters

callback

A pointer to the application function to be called.

• void setTopComponent(CK_Component *top);

Sets the screen's top-level component.

Parameters

top

The top-level component, typically a manager component such as a bulletin board (CK_BBoard) or a row-column (CK_RowColumn).