#include <cascade/app/CascadeApp.h>
Inheritance diagram for CascadeApp:
Public Types | |
| typedef bool() | EnumProc (const char *pAppName, int nAppPID, void *pClientData) |
Public Member Functions | |
| CascadeApp () | |
| virtual | ~CascadeApp () |
| int | Run (int argc, const char **argv) |
| void | Terminate (int nExitCode) |
| int | GetArgc () const |
| const char ** | GetArgv () const |
| const char * | GetAppName () const |
| int | GetAppPID () const |
| const char * | GetAppWormholeURL () const |
| void | SetFocusWindow (CascadeWindow *pWindow, bool bRedraw=true) |
| void | ClearFocusWindow (bool bRedraw=true) |
| CascadeWindow * | GetFocusWindow () |
| bool | IsActive () |
| void | Activate () |
| void | Activate (const char *pAppName, int nAppPID=0) |
| void | Deactivate () |
| void | RegisterInactiveKeyInterest (bool bInterest) |
| void | RegisterECPCommand (const CascadeString &command) |
| void | UnregisterECPCommand (const CascadeString &command) |
| void | RegisterForSignal (int nSignum) |
| void | UnregisterForSignal (int nSignum) |
Static Public Member Functions | |
| static CascadeApp * | GetApp () |
| static bool | MakeAppWormholeURL (int nAppPID, char *pBuff, u32 nBuffLen) |
| static bool | EnumerateApps (EnumProc *pEnumProc, void *pClientData) |
Protected Member Functions | |
| virtual void | OnAppInit () |
| virtual void | OnAppExit () |
| virtual void | OnActivate () |
| virtual void | OnDeactivate () |
| virtual void | OnKeyDown (u32 nKey) |
| virtual void | OnKeyDownInactive (u32 nKey) |
| virtual void | OnKeyUp (u32 nKey) |
| virtual void | OnKeyUpInactive (u32 nKey) |
| virtual void | OnMountMessage (const CascadeMountMessage &mountMessage) |
| virtual void | OnPowerMessage (const CascadePowerMessage &powerMessage) |
| virtual void | OnScreenMessage (const CascadeScreenMessage &screenMessage) |
| virtual void | OnWormholeMessage (const CascadeMessage &message) |
| virtual void | OnWidgetParametersChanged () |
| virtual void | OnECPCommand (const CascadeString &command, CascadeString &resultToSet) |
| virtual void | OnSignal (int nSignum) |
Protected Attributes | |
| CascadeWormhole | m_appWormhole |
Friends | |
| class | CascadeWindow |
| class | CascadeTimer |
| class | CascadeInput |
| class | CascadeAppMessageSink |
| class | CascadeMPEGPlayer |
Classes | |
| class | RepaintEntry |
| class | TimerEntry |
| class | WindowEntry |
CascadeApp is the class most Cascade developers will use once in their application :)
It is a very high-level class that provides a foundation for easy collaborative participation in the Cascade Runtime.
CascadeApp provides the following features:
CascadeApp is very easy to use. Simply instantiate your own CascadeApp derived class and Run() it. The CascadeApp base class will take control of the calling thread and call your CascadeApp derived class' virtual member functions when appropriate.
Example: A Hello World CascadeApp
// FILE: HelloWorldApp.cpp
#include <cascade/Cascade.h>
#include <stdio.h>
class HelloWorldApp : public CascadeApp
{
protected:
virtual void OnAppInit() { printf("Hello World.\\n"); Terminate(0); }
};
int main(int argc, const char ** argv)
{
HelloWorldApp myApp;
return myApp.Run(argc, argv);
}
In this example, we instantiate and Run() our app in function main. This is not a requirement but it is how 99% of CascadeApps will be run since it is a convenient place to do it. Once Run() is called, the process' main thread of execution is taken over by the CascadeApp base class. The CascadeApp base class waits for wormhole messages and dispatches them to virtual member functions in a tight message loop until Terminate() is called, at which point Run() relinquishes control back to the caller. All significant processing by the client is done in CascadeApp derived class virtual member functions.
Most app processing, then, occurs within the context of CascadeApp's tight message loop. While in this tight message loop, all CascadeApp virtual member function invocations are performed in response to the receipt of messages on the app's wormhole, m_appWormhole. The message loop looks something like this:
while (DispatchMessage(m_appWormhole.WaitForMessage())); | Note: | DispatchMessage() is a private CascadeApp function that decodes the received wormhole message and calls virtual member functions as appropriate. |
Once again, all of your overridden CascadeApp virtual member functions (save OnAppInit() and OnAppExit()) will be called from CascadeApp's tight message loop. This has the following implications:
When an app is the active app, it gets all of the CK_KEY messages dispatched in the system. When an app is not active, it receives no CK_KEY messages.
| Note: | There is a special mechanism to allow inactive apps to receive CK_KEY messages if they register interest. That mechanism is distinct from what we desribe here - more on that in a few moments. |
It is therefore apparant that whether or not an app is active determines whether or not all CK_KEY messages in the system are directed to it. Stated another way, it is the active app that the user is always currently interacting with. Once more, it is the active app that the user is always currently interacting with.
CK_KEY dispatch without a focus window:
If the active app has no CascadeWindow set as its focus window, then message dispatch is simple. Key Down CK_KEY messages are routed directly to the app's OnKeyDown() virtual member function. Similarly, Key Up CK_KEY messages are routed to the app's OnKeyUp() virtual member function.
Here now is the complete pseudo-code algorithm of CK_KEY dispatch:
let currWindow = my focus window
while (currWindow is not NULL)
{
call the curr window's OnKeyDown() or OnKeyUp() handler
did it return true? if so, then stop.
if not, then let currWindow = the parent of currWindow
}
// we've now given the focus window and all of its parents a crack
// at the message - no one handled it so call my version
call my OnKeyDown() or OnKeyUp()
|
|
Callback function for enumerating running CascadeApps in the system Clients provide their own EnumProc to the EnumerateApps() function. Your custom EnumProc will get called back by the EnumerateApps() function, one for each CascadeApp currently running in the system.
|
|
|
The 1::1 constructor - lightweight. This base class constructor is lightweight. It simply registers itself as the one and only one CascadeApp for this process. If you try to construct more than one instance of a CascadeApp in your process, you will purposefully crash.
|
|
|
Destructor. This base class destructor unregisters itself as the one and only one CascadeApp for this process, paving the way for a subsequent one and only one CascadeApp for this process to be constructed. |
|
||||||||||||
|
Makes a specific app in the system active This version of Activate() causes the app identified by pAppName with pid nAppPID to be activated. If nAppPID is zero, the first app named pAppName will be activated.
|
|
|
Sets the app to be the active app Activate() sets this app to be the active app. Only one CascadeApp running on the local system can be the active app at a time. When 1 particular CascadeApp is active, all other CascadeApps running on the system are inactive. When an app is active, it gets input key messages. Input key messages are sent to the active Cascade app and get dispatched by the CascadeApp base class to your app's virtual OnKeyDown() and OnKeyUp() functions. When an app it activated, it's OnActivate() member function will be called and the app will start receiving input key messages. |
|
|
Clears the app's focus window Call ClearFocusWindow() to clear the app's focus window. When anhas no focus window (as is the case after a call to ClearFocusWindow()), and is the active app then CK_KEY messages will be dispatched directly to OnKeyDown() and OnKeyUp().
|
|
|
Deactivates the app if it is active Deactivate() deactivates the app if it is the active app. The app that was most recently previously active becomes the active app. Deactivate() will cause the app's OnDeactivate() member function to be called. |
|
||||||||||||
|
Enumerates all running CascadeApps in the system. EnumerateApps() will call *pEnumProc for each CascadeApp currently running in the system. ***NOTE*** EnumerateApps is currently not implemented!
|
|
|
Returns the 1 and only 1 CascadeApp for this process. GetApp() returns the 1 and only 1 CascadeApp for this process.
|
|
|
Gets the app's name GetAppName() gets the app's name. A CascadeApp's name is the same as the name of the executable file that started the process that ran the app. Essentially this is argv[0] stripped of all path information.
|
|
|
Gets the app's pid GetAppName() gets the app's pid. A CascadeApp's pid is the process id of the process that called Run(). This usually the pid of your process' main thread.
|
|
|
Gets the app's wormhole URL GetAppWormholeURL() gets the app's wormhole url. This url is useful if you want to post a message to an app's wormhole. Alternatively you could call MakeAppWormholeURL() with an app's pid to have an app's wormhole URL copied into your string buffer.
|
|
|
Gets the argument count the app was started with GetArgc() gets the argument count that the app was started with. The argc returned is usually that which was passed in to function main.
|
|
|
Gets the argument variable array the app was started with. GetArgv() gets the argument variable array that the app was started with. The argv returned is usually that which was passed in to function main.
|
|
|
Gets the app's focus window Call GetFocusWindow() to get the current focus window of the app.
|
|
|
Tells whether or not the app is active. Call IsActive() to determine whether or not the app is the active app.
|
|
||||||||||||||||
|
Constructs a the url for the app wormole given the app PID. MakeAppWormholeURL() constructs a string containing the wormhole url for the referenced app's wormhole.
|
|
|
called when app has been activated OnActivate() is called whenever your app is activated. Override this method to provide app functionality to execute whenever your app is made active. Typical behavior is to dynamically compute the app's focus window (if required).
|
|
|
called when app is exiting OnAppExit() is called when the app exits (in response to a call to Terminate()). Perform final cleanup in OnAppExit().
|
|
|
The first entry point of your application OnAppInit() is called when an app starts (in response to a call to Run()). Perform your application's initialization here. The base class implementation of OnAppInit() does nothing. Your app will continue to run indefinitely until Terminate() is called. If your application's initialization fails, you should explicitly call Terminate() from within OnAppInit(). If your application performs a simple task and then exits (like ps, for example), then the last line of OnAppInit() should be a call to Terminate().
|
|
|
called when app has been deactivate OnDeactivate() is called whenever your app is deactivated. Override this method to provide app functionality to execute whenever your app is deactivated.
|
|
||||||||||||
|
called to allow subclasses to handle ECP commands OnECPCommand() is called by the CascadeApp base class whenever an ECP command that has been registered for by RegisterECPCommand() is received.
|
|
|
called to handle a key down message when active OnKeyDown() is called by the CascadeApp base class when it is the active app and has determined that no currently displayed window wants the key message.
|
|
|
called to notify receipt of a key down message when inactive OnKeyDownInactive() is called by the CascadeApp base class when it is the inactive app and you have registered interest in receiving key messages when you are inactive.
|
|
|
called to handle a key up message when active OnKeyUp() is called by the CascadeApp base class when it is the active app and has determined that no currently displayed window wants the key message.
|
|
|
called to notify receipt of a key up message when inactive OnKeyUpInactive() is called by the CascadeApp base class when it is the inactive app and you have registered interest in receiving key messages when you are inactive.
|
|
|
called to notify that a file system has been mounted or unmounted OnMountMessage() is called by the CascadeApp base class when a file system mount point has been added or removed.
|
|
|
called to notify that a power state change has occurred OnPowerMessage() is called by the CascadeApp base class when a power state change has occurred.
|
|
|
called to notify that the screen resolution has changed OnScreenMessage() is called by the CascadeApp base class when the screen resolution or output resolution has been modified.
|
|
|
called to allow subclasses to handle signals OnSignal() is called by the CascadeApp base class whenever a previously registered signal is raised. The default implementation does nothing for all signals except when SIGINT or SIGHUP are raised in the main app thread. When the main app thread receives SIGINT or SIGHUP, the base class implementation of OnSignal() calls Terminate(0) to gracefully shut down the app.
|
|
|
called when CascadeWidget UI parameters have changed OnWidgetParamtersChanged() gets called whenever the ui 'theme' paramters for widgets gets changed. The default implementation is to cause all app windows to be redrawn.
|
|
|
called to allow subclasses to process wormhole messages OnWormholeMessage() is called whenever the CascadeApp base class receives a wormhole message that it doesn't want to process directly. Override this function to process wormhole messages in your application.
Example:
class App1 : public CascadeApp { virtual void OnWormholeMessage(const CascadeMessage & message); };
class App2 : public App1 {
virtual void OnWormholeMessage(const CascadeMessage & message)
{
if (message.ID() == s_nMessageIDiCareAbout) { } // do something
else App1::OnWormholeMessage(message); // make sure my base class gets a crack.
} };
|
|
|
registers for receipt of an ECP command ECP stands for External Control Protocol and is the mechanism by which external devices can instruct your application to do things. A CascadeApp registers for receipt of an ECP command by calling RegisterECPCommand(). Any such ECP commands that are subsequently dispatched will be handled by your app's OnECPCommand() virtual member function.
|
|
|
registers for receipt of a signal RegisterForSignal() registers for receipt of signal nSignum which will be notified by the invocation of the app's OnSignal member function. By default, all CascadeApps have SIGINT and SIGHUP registered. The default base class implementation of OnSignal() calls Terminate(0) when SIGINT or SIGHUP is received by the main app thread.
|
|
|
Allows the app to receive key messages when inactive RegisterInactiveKeyInterest() is used to specify whether your app receives key message dispatch to its OnKeyDownInactive() and OnKeyUpInactive() handlers when it is inactive. The default behavior for CascadeApps is to not receive key message dispatch when inactive. RegisterInactiveKeyInterest() may be used to change this behavior.
|
|
||||||||||||
|
Starts the application. Run() is usually called from function main() in the following fashion:
int main(int argc, const char ** argv)
{
MyApp myApp;
return myApp.Run(argc, argv);
}
|
|
||||||||||||
|
Sets the app's focus window call SetFocusWindow() to set the app's focus window to pWindow. Each app has the ability to have up to 1 focus window. The focus window (if set) is the window to which the CascadeApp will first dispatch input messages it receives while it is the active application.
|
|
|
Stops the application. Terminate() posts a private quit message to the app effectively causing it to terminate with exit code nExitCode. Although Terminate() may be called at anytime by any thread after Run() has been called, it is usually called by the app itself from within its main thread (that which called Run()) when it wants to terminate.
|
|
|
unregisters for receipt of an ECP command UnregisterECPCommand() is used to unregister a previously registered ECP command.
|
|
|
unregisters for receipt of a signal Call UnregisterForSignal to unregister for reciept of a signal that you previously registered for.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
a wormhole you can use for sending and posting in your CascadeApp derived class m_appWormhole may be used to send and post messages from your app to other wormholes. Additionally you can post messages to yourself by calling m_appWormhole.PostMessage(GetAppWormholeURL(), ...);
|
1.4.1