CascadeInput Class Reference

used to dispatch input commands to Cascade Applications More...

#include <cascade/app/CascadeInput.h>

List of all members.

Public Types
enum	MouseButton { kMouseButtonLeft = 0, kMouseButtonRight = 1, kMouseButtonMiddle = 2 }
Static Public Member Functions
static void	DispatchKeyDown (u32 nKey)
static void	DispatchKeyUp (u32 nKey)
static void	DispatchMouseButtonDown (MouseButton button, u16 x, u16 y)
static void	DispatchMouseButtonUp (MouseButton button, u16 x, u16 y)
static void	DispatchMouseButtonDoubleClick (MouseButton button, u16 x, u16 y)
static void	DispatchMouseMove (u16 x, u16 y)
static void	DispatchECPCommand (const CascadeString &command, CascadeString &resultToSet)
static void	NotifyScreenActivity ()

---

Detailed Description

used to dispatch input commands to Cascade Applications

Skip the description

CascadeInput is a class that consists entirely of static member functions which allow you to dispatch various forms of input into the Cascade Application input dispatch system.

There are three types of input that can be dispatched using CascadeInput:

1. CK_KEY Events
   
   
2. Mouse Events
   
   
3. External Control Protocol (ECP) Commands

CK_KEY Events

The first type of input that can be dispatched with CascadeInput is key input. Key codes, also known as CK_KEY codes, are dispatched using the DispatchKeyDown() and DispatchKeyUp() functions. These functions dispatch the key message using a private internal wormhole to post the key message into the CascadeApp message dispatch system. Since the key messages are posted to asynchronously, clients of CascadeInput are assured that they won't be stalled in any way by the CascadeInput CK_KEY message dispatch system.

When a CK_KEY message is dispatched, it ends up being handled by the CascadeApp class.

See:	DispatchKeyDown(), DispatchKeyUp(), CascadeApp, CascadeApp::OnKeyDown(), CascadeApp::OnKeyUp()

Here's a brief example of using CascadeInput to dispatch a CK_KEY message:

stopper: a program to dispatch the CK_STOP key

    // File: stopper.cpp
    #include <cascade/Cascade.h>

    int main(int argc, const char ** argv)
    {
        CascadeInput::DispatchKeyDown(CK_STOP);
        CascadeInput::DispatchKeyUp(CK_STOP);
        return 0;
    }
    

Most dispatchers of CK_KEY codes will be device listeners that want to, for example, convert IR or keyboard scan codes into CK_KEY codes and dispatch them. Any program, however can dispatch CK_KEY messages into the CascadeApp input message system using CascadeInput.

Mouse Events

CascadeInput is also used to dispatch mouse events with the various DispatchMouse... functions. Mouse messages are dispatched in the same asynchronous manner as CK_KEY messages. Mouse messages, however, are note currently handled by class CascadeApp so mouse messages dispatched by CascadeInput currently have no effect.

See:	DispatchMouseButtonDown(), DispatchMouseButtonUp(), DispatchMouseButtonDoubleClick(), DispatchMouseMove()

ECP Commands

ECP stands for External Control Protocol. ECP Commands are used to instruct applications to do things with a simple string command that produces a simple string result. An ECP command is therefore just a string command which produces a string result. ECP commands are dispatched to CascadeApps using CascadeInput. Let's take a look at an example:

poweroff: a program to turn the power off using an ECP command

    // File: poweroff.cpp
    #include <cascade/Cascade.h>

    int main(int argc, const char ** argv)
    {
        CascadeString command("power off");
        CascadeString result;
        CascadeInput::DispatchECPCommand(command, result);
        if (result == "power is off") printf("The power is now off.\\n");
        else printf("Could not turn the power off.\\n");
    }
    

This program illustrates several concepts:

1. ECP commands are simple space separated strings. The first word in the string is the command. Any subsequent words in the string are command arguments. In this example, 'power' is the command and 'off' is the argument.
2. The command name portion of the command string must not contain any spaces as the space is the separator between a command and its arguments.
3. ECP commands, unlike CK_KEY and mouse messages, are dispatched synchronously. This is so the command can be executed by the target application and the result string filled in before the call to DispatchECPCommand() returns.
4. The format of ECP command strings and result strings is arbitrary and should follow the common conventions or protocol part of ECP. Said protocol is not yet defined or documented.
5. The mechanism of ECP command dispatch and handling is independent of the protocol.

When an ECP command is dispatched, it ends up being handled by the CascadeApp that has most recently registered to handle the command. Once an app has registered to handle an ECP command, its OnECPCommand() virtual member function is called to handle the ECP command.

See:	DispatchECPCommand(), CascadeApp, CascadeApp::RegisterECPCommand(), CascadeApp::OnECPCommand()

---

class CascadeInput

---

Member Enumeration Documentation

enum CascadeInput::MouseButton

a type representing a mouse button MouseButton is used as an argument to the mouse button dispatch functions. See also: DispatchMouseButtonDown(), DispatchMouseButtonDoubleClick(), DispatchMouseButtonUp() Enumeration values: kMouseButtonLeft  the left mouse button kMouseButtonRight  the right mouse button kMouseButtonMiddle  the middle mouse button

---

Member Function Documentation

static void CascadeInput::DispatchECPCommand (  const CascadeString &  command, CascadeString &  resultToSet )  [static]

dispatches an ECP command DispatchECPCommand() is used to dispatch an ECP command into the dispatch system. Parameters: command  the command to dispatch resultToSet  a string to receive the result See also: ECP Commands

static void CascadeInput::DispatchKeyDown (  u32  nKey  )  [static]

dispatches a key down CK_KEY message DispatchKeyDown() is used to dispatch a CK_KEY key down message to the CascadeApp input message dispatch subsystem. Parameters: nKey  The id of the CK_KEY to dispatch See also: CascadeKeyDefs.h

static void CascadeInput::DispatchKeyUp (  u32  nKey  )  [static]

dispatches a key up CK_KEY message DispatchKeyUp() is used to dispatch a CK_KEY key up message to the CascadeApp input message dispatch subsystem. Parameters: nKey  The id of the CK_KEY to dispatch See also: CascadeKeyDefs.h

static void CascadeInput::DispatchMouseButtonDoubleClick (  MouseButton  button, u16  x, u16  y )  [static]

dispatches a mouse button double-click message DispatchMouseButtonDoubleClick() is used to dispatch a mouse button double-click message to the CascadeApp input message dispatch subsystem. Parameters: button  The id of the button this message applies to x  The current x coordinate of the mouse position y  The current y coordinate of the mouse position See also: CascadeInput::MouseButton Note: Currently the CascadeApp input message dispatch system ignores mouse messages. The proper sequence of mouse button message dispatch in the case of a mouse button double-click is to first dispatch a mouse button down, followed by a mouse button double-click, followed by a mouse button up. This is illustrated by the following code fragment: u16 x = 0; u16 y = 0; CascadeInput::MouseButton button = CascadeInput::kMouseButtonLeft; CascadeInput::DispatchMouseButtonDown(button, x, y); CascadeInput::DispatchMouseButtonDoubleClick(button, x, y); CascadeInput::DispatchMouseButtonUp(button, x, y); In other words, do not dispatch a mouse button up in between a mouse button down and a mouse button double-click message.

static void CascadeInput::DispatchMouseButtonDown (  MouseButton  button, u16  x, u16  y )  [static]

dispatches a mouse button down message DispatchMouseButtonDown() is used to dispatch a mouse button down message to the CascadeApp input message dispatch subsystem. Parameters: button  The id of the button this message applies to x  The current x coordinate of the mouse position y  The current y coordinate of the mouse position See also: CascadeInput::MouseButton Note: Currently the CascadeApp input message dispatch system ignores mouse messages.

static void CascadeInput::DispatchMouseButtonUp (  MouseButton  button, u16  x, u16  y )  [static]

dispatches a mouse button up message DispatchMouseButtonUp() is used to dispatch a mouse button up message to the CascadeApp input message dispatch subsystem. Parameters: button  The id of the button this message applies to x  The current x coordinate of the mouse position y  The current y coordinate of the mouse position See also: CascadeInput::MouseButton Note: Currently the CascadeApp input message dispatch system ignores mouse messages.

static void CascadeInput::DispatchMouseMove (  u16  x, u16  y )  [static]

dispatches a mouse move message DispatchMouseMove() is used to dispatch a mouse move message to the CascadeApp input message dispatch subsystem. Parameters: x  The new x coordinate of the mouse position y  The new y coordinate of the mouse position Note: Currently the CascadeApp input message dispatch system ignores mouse messages.

static void CascadeInput::NotifyScreenActivity (   )  [static]

---

The documentation for this class was generated from the following file:

• CascadeInput.h

---