The Main Application

Taquis - PC Base FFT Spectrum Analyzers, Oscilloscopes, Data Analysis, Data Acquisition, and Application Frameworks

AtOne Application Framework
"A Framework working with you, not against you..."

Home
Features
Programming
License
Downloads
Directions

The Main Application

Every WIN32 application has a main entry point WinMain() which is called when the application is executed. In AtOne this entry point is used to instance a main application class which is a global single instance class used to manage the attributes common to any application. The class GuiApp is the application class which you may use as is, or more typically derive from and use as a container for the other key objects in your application. GuiApp has two methods which you are required to implement for every application you write: GuiApp::instanceApp() is a static member function that is used to create the instance of your GuiApp derived application object, and GuiApp::freeApp() is a static member function used to destroy that application object. GuiApp also has two virtual members GuiApp::initialise() and GuiApp::free() which you typically over-ride and use in your application class to allocate and free the objects within your application. The GuiApp class is,

class GuiApp
{
.
.
.

public:
GuiApp();
GuiApp(const string pAppName);
virtual ~GuiApp();

//These two methods must be defined by the application developer and are where
//the single instance of a GuiApp should be created.and destroyed
static void instanceApp();
static void freeApp();

void             flushMessageQueue(int nFlushcount = 20) const;
void             registerCallback(const OsiStringCallbackInstance& rCallbackInstance) const;
void             registerCallback(const OsdThreadMessageCallbackInstance& rCallbackInstance) const;
void             unRegisterCallback(const OsiStringCallbackInstance& rCallbackInstance) const;
void             unRegisterCallback(const OsdThreadMessageCallbackInstance& rCallbackInstance) const;
void             notifyNCHitTest(GuiWindow* pWindow, GuiPoint& rCursorPt, const string pHelpPopupText) const;
void             notifyLeftButtonDown(GuiWindow* pWindow) const;
void             help(int nId) const;
void             menuHelp(int nMenuId) const;
void             statusHelp(const string pStatusHelp) const;
void             helpOnHelp() const;
void             helpOnPartialString(const string pPartialString) const;
GuiHelp*         applicationHelp() const;
void             applicationHelp(GuiHelp* pAppHelp);
GuiStateManager* stateManager() const;
void             stateManager(GuiStateManager* pStateManager);
GuiPalette*      normalPalette() const;
GuiPalette*      alternativePalette() const;
void             normalPalette(GuiPalette* pPalette);
void             alternativePalette(GuiPalette* pPalette);
const OsiString& applicationPath() const;
const OsiString& applicationName() const;
void             applicationName(const string pAppName);
const OsiString& initialisationFileName() const;
void             initialisationFileName(const string pInitialisationFile);
const OsiString& commandLine() const;
GuiShowCommand   showCommand() const;
HINSTANCE        handleInstance() const;
void             quit(int nExitCode = 0) const;
void             registerWindow(HWND hWnd);
void             unRegisterWindow(HWND hWnd);
void             pushModalWindow(HWND hWnd);
void             popModalWindow();
void             isActive(bool bIsActive);
bool             isActive() const;

virtual bool initialise();
virtual bool free();
};

Though quite large, much of the information within GuiApp requires no alteration to build an application. Most of the attributes in GuiApp are the common features of all applications and are there as a convenience to you. A few public members in this class a not intended for general use and are there simply to implement certain application behaviour : notably notifyNCHitTest() and notifyLeftButtonDown() which implement tooltip help and registerWindow(), unRegisterWindow(), pushModalWindow() and popModalWindow() which implement dialog box modality.

The GuiApp class has a placeholder for the application name and the application initialisation file name (and path) since these attributes are typically required application wide along with the other attributes obtainable through WIN32 when the application executes, such as the instance handle, show command, and application path. Additionally GuiApp provides placeholders for application state information (GuiStateManager), application online help (GuiHelp) and application colour palettes (GuiPalette). Note that in the case of palettes and GuiApp has two because a typical application using palettes will generally use different palettes for drawing to the screen and printing. Once again this is a convenience feature for the application developer and need not be used. There are also two multi-cast callbacks available in GuiApp : OsiStringCallbackInstance which you can typically use to route textual messages from anywhere in your application to a status bar for example, and OsdThreadMessageCallbackInstance which you can use to map and process thread messages sent using the ::PostThreadMessage() function in WIN32.

Finally, you might wonder why there are two levels of application initialisation in AtOne (initialise() and instanceApp()). Essentially it was constructed in this fashion to allow the use of instrumentation / debugging code which would typically need to be initialised before the main application is constructed. The added flexibility is there to save you from difficulty under such circumstances.

To use this class to create your application simply derive a new application class from GuiApp, implement initialise() and free(), and implement GuiApp::instanceApp() and GuiApp::freeApp() to create and destroy the first instance of your new application class. You can find an example of this in the AtSpec Spectrum Analyzer case study.

Programming Windows

"We use Zeus for Windows and Watcom C/C++ 11.0 as our development environment of choice..."

Paavo Jumppanen
Creator of AtOne Application Framework