#include <applicat.h>

Inheritance diagram for owl::TApplication:

Public Member Functions
	TApplication (const tstring &name=tstring(), TModule &=owl::Module, TAppDictionary =0)
	TApplication (const tstring &name, HINSTANCE hInstance, HINSTANCE hPrevInstance, const tstring &cmdLine, int cmdShow, TModule &=owl::Module, TAppDictionary =0)
	~TApplication ()
TFrameWindow *	GetMainWindow ()
TDocManager *	GetDocManager ()
TLangId	GetLangId () const
void	SetLangId (TLangId landid)
void	ClearMainWindow ()
void	GetWinMainParams ()
HINSTANCE	GetPrevInstance () const
void	SetPrevInstance (HINSTANCE pi)
int	GetCmdShow () const
void	SetCmdShow (int cmdshow)
TCurrentEvent &	GetCurrentEvent ()
virtual bool	CanClose ()
virtual int	Run ()
virtual int	Start ()
virtual void	WaitOnObject (HANDLE handle, bool wait)
virtual void	ObjectSignaled (HANDLE, bool)
tstring	ConvertA2W (LPCSTR string)
TWindow *	GetWindowPtr (HWND hWnd) const
void	PostDispatchAction ()
bool	Find (TEventInfo &, TEqualOperator=0)
virtual int	MessageBox (HWND wnd, const tstring &text, const tstring &caption=tstring(), uint type=MB_OK)
virtual int	MessageBox (HWND wnd, LPCTSTR text, LPCTSTR caption=0, uint type=MB_OK)
int	MessageBox (HWND wnd, uint resId, const tstring &caption, uint type=MB_OK,...)
int	MessageBox (HWND wnd, uint resId, LPCTSTR caption=0, uint type=MB_OK,...)
virtual TTooltip *	GetTooltip () const
virtual void	EnableTooltip (bool enable=true)
Message queue loop & response functions
virtual int	MessageLoop ()
virtual bool	IdleAction (long idleCount)
virtual bool	ProcessMsg (MSG &msg)
virtual bool	ProcessAppMsg (MSG &msg)
Begin and end of a modal window's modal message loop
int	BeginModal (TWindow *window, int flags=MB_APPLMODAL)
void	EndModal (int result)
virtual void	PreProcessMenu (HMENU hMenubar)
Dead TWindow garbage collection
void	Condemn (TWindow *win)
void	Uncondemn (TWindow *win)
Static Public Member Functions
static void	SetWinMainParams (HINSTANCE hInstance, HINSTANCE hPrevInstance, const tstring &cmdLine, int cmdShow)
static tstring &	GetCmdLine ()
Protected Member Functions
virtual void	InitApplication ()
virtual void	InitInstance ()
virtual void	InitMainWindow ()
virtual int	TermInstance (int status)
void	SystemCommandTrace ()
bool	DiagIdleAction (long idleCount)
void	SetTooltip (TTooltip *tooltip)
TFrameWindow *	SetMainWindow (TFrameWindow *window)
TDocManager *	SetDocManager (TDocManager *docManager)

Detailed Description

Derived from TModule and TMsgThread and virtually derived from TEventHandler, TApplication acts as an object-oriented stand-in for an application module. TApplication and TModule supply the basic behavior required of an application. TApplication member functions create instances of a class, create main windows, and process messages.

To create an OLE-enabled Doc/View application, you need to derive your application from both TApplication and TOcAppHost.

Constructor & Destructor Documentation

owl::TApplication::TApplication	(	const tstring &	name = `tstring()`,
		TModule *&	module = `owl::Module`,
		TAppDictionary *	appDict = `0`
	)

Constructor for use in OwlMain(). Gets members from statics set earlier by a call to InitWinMainParams() in Owl's WinMain. Creates a new TApplication object named name. You can use owl::Module to specify the global module pointer that points to this application. The appDict parameter specifies which dictionary this application will insert itself into. To override the default ObjectWindows TAppDictionary object, pass a pointer to a user-supplied appDict object.

References owl::TAppDictionary::Add().

owl::TApplication::TApplication	(	const tstring &	name,
		HINSTANCE	instance,
		HINSTANCE	prevInstance,
		const tstring &	cmdLine,
		int	cmdShow,
		TModule *&	module = `owl::Module`,
		TAppDictionary *	appDict = `0`
	)

Constructor for use in user defined WinMain() when all the args are available Creates a TApplication object with the application name (name), the application instance handle (instance), the previous application instance handle (prevInstance), the command line invoked (cmdLine), and the main window show flag (cmdShow). The appDict parameter specifies which dictionary this application will insert itself into. To override the default ObjectWindows TAppDictionary object, pass a pointer to a user-supplied appDict object.

If you want to create your own WinMain, use this constructor because it provides access to the various arguments provided by WinMain. You can use module to to specify the global module pointer that points to this application.

owl::TApplication::~TApplication ( )

~TApplication destroys the TApplication object.

References owl::TWindow::Destroy(), owl::TAppDictionary::Remove(), and SetMainWindow().

Member Function Documentation

int owl::TApplication::BeginModal	(	TWindow *	window,
		int	flags = `MB_APPLMODAL`
	)

Called to begin a modal window's modal message loop. After determining which window to disable, BeginModal saves the current status of the window, disables the window, calls MessageLoop, and then reenables the window when the message loop is finished. The flags determine how BeginModal treats the window. flags can be one of the following values:

MB_APPLMODAL The window to be disabled (which is usually an ancestor of the modal window) is identified by window. If window is 0, no window is disabled.
MB_SYSTEMMODAL The window to become system modal is identified by window.
MB_TASKMODAL All top-level windows are disabled, and window is ignored.

BeginModal returns -1 if an error occurs.

References owl::TEnumInfo::Count, owl::TWindow::EnableWindow(), owl::TWindow::GetHandle(), MessageLoop(), owl::TEnumInfo::ModalWnd, and owl::TEnumInfo::Wnds.

bool owl::TApplication::CanClose ( ) [virtual]

Determine whether the application can be closed. Makes sure the MainWindow can close & doc manager can close. Returns true if it is OK for the application to close. By default, CanClose calls the CanClose member function of its main window and returns true if both the main window and the document manager (TDocManager) can be closed. If any of the CanClose functions return false, the application does not close.

This member function is seldom redefined; closing behavior is usually redefined in the main window's CanClose member function, if needed.

References owl::TWindow::CanClose(), owl::TEventHandler::Dispatch(), and owl::TEventHandler::Find().

void owl::TApplication::ClearMainWindow ( ) [inline]

Called by the main window (TFrameWindow) destructor to zero the MainWindow member.

void owl::TApplication::Condemn ( TWindow * win )

Condemn a window to be deleted the at the next available safe time. Adds the window to a normal single linked list Condemned windows should be removed if they are destructed in the mean time thru some other mechanism (i.e. stack, aggregate, etc)

References owl::TWindow::Next(), owl::TWindow::SetNext(), and owl::TWindow::SetParent().

tstring owl::TApplication::ConvertA2W ( LPCSTR string )

Jogy to prevent error C3204: '_alloca' cannot be called from within a catch block under VC.NET.

bool owl::TApplication::DiagIdleAction ( long idleCount ) [protected]

Called automatically from IdleAction if compiled with __TRACE or __WARN flag. If you use the retail version of OWL and would like to enable Diagnostic Windows you should override IdleAction and call this function.

References IdleAction().

void owl::TApplication::EndModal ( int result )

Cause the current modal message loop to break and have it return a result Re-enable the disabled windows here, if the EnumInfo is available.

References owl::TMsgThread::BreakMessageLoop, and owl::TMsgThread::MessageLoopResult.

bool owl::TApplication::Find	(	TEventInfo &	eventInfo,
		TEqualOperator	equal = `0`
	)		`[virtual]`

TApplication defers event handling to DocManager if one has been installed.

Because TApplication has no event table itself, it defers event handling to the DocManager. If a DocManager has been installed, Find calls TDocManager to handle events.

Reimplemented from owl::TEventHandler.

References owl::TEventHandler::Find(), owl::TEventHandler::TEventInfo::Object, and owl::TEventHandler::SearchEntries().

tstring & owl::TApplication::GetCmdLine ( ) [inline, static]

Return the command line of the application. Most programs do not need to call this because OwlMain has the parameters already parsed.

int owl::TApplication::GetCmdShow ( ) const [inline]

Retrieve the initial state of the main window.

TCurrentEvent & owl::TApplication::GetCurrentEvent ( ) [inline]

Return the current event from the message queue.

TDocManager * owl::TApplication::GetDocManager ( ) [inline]

Return the current document manager.

TLangId owl::TApplication::GetLangId ( ) const [inline]

Returns identifier of language used by application.

TFrameWindow * owl::TApplication::GetMainWindow ( ) [inline]

Return the current main window.

HINSTANCE owl::TApplication::GetPrevInstance ( ) const [inline]

Return the HINSTANCE of the previous running instance.

TTooltip * owl::TApplication::GetTooltip ( ) const [inline, virtual]

Get Tooltip.

TWindow * owl::TApplication::GetWindowPtr ( HWND hWnd ) const [inline]

Get the TWindow pointer belonging to this app given an hWnd.

Return the window pointer given a window's handle.

Retrieves a TWindow pointer associated with the handle to a window (hWnd), allowing more than one application to share the same HWND.

void owl::TApplication::GetWinMainParams ( ) [inline]

Retrieve the WinMain parameters.

Initializes a static instance of an application. ObjectWindows OwlMain uses this function to support static application instances.

References owl::TModule::InitModule().

bool owl::TApplication::IdleAction ( long idleCount ) [virtual]

Called each time there are no messages in the queue. Idle count is incremented each time, & zeroed when messages are pumped. Return whether or not more processing needs to be done. Default behavior is to give the main window an opportunity to do idle processing by invoking its IdleAction() member function when "idleCount" is 0

Reimplemented from owl::TMsgThread.

References DiagIdleAction(), and owl::TFrameWindow::IdleAction().

void owl::TApplication::InitApplication ( ) [protected, virtual]

Handle initialization for the first executing instance of the OWL application. Under Win32, every app instance is treated as the first. Derived classes can override this to perform app initialization, or they can use the derived class constructor. The following sample program calls InitApplication the first time an instance of the program begins.

 class TTestApp : public TApplication {
    public:
      TTestApp(): TApplication("Instance Tester")
        { strcpy(WindowTitle, "Additional Instance");}
    protected:
       char WindowTitle[20];
       void InitApplication() { strcpy(WindowTitle, "First Instance"); }
       void InitMainWindow() { MainWindow = new TFrameWindow(0, WindowTitle); }
 };
 static TTestApp App;

void owl::TApplication::InitInstance ( ) [protected, virtual]

Performs each instance initialization necessary for the application. Unlike InitApplication(), which is called for the first instance of an application, InitInstance is called whether or not there are other executing instances of the application. InitInstance calls InitMainWindow(), and then creates and shows the main window element by TWindow::Create and TWindow::Show. If the main window cannot be created, a TXInvalidMainWindow exception is thrown.

Note:: If you redefine this member function, be sure to explicitly call TApplication::InitInstance.

Reimplemented from owl::TMsgThread.

References owl::TMenu::AppendMenu(), owl::TWindow::Create(), owl::TWindow::GetHandle(), InitMainWindow(), owl::TXInvalidMainWindow::Raise(), owl::TWindow::SetFlag(), owl::TWindow::ShowWindow(), and owl::wfMainWindow.

void owl::TApplication::InitMainWindow ( ) [protected, virtual]

Initialize the application's main window. Derived classes should override this to construct, initialize and set the main window using SetMainWindow(). By default, InitMainWindow constructs a generic TFrameWindow object with the name of the application as its caption. You can redefine InitMainWindow to construct a useful main window object of TFrameWindow (or a class derived from TFrameWindow) and store it in MainWindow. The main window must be a top-level window; that is, it must be derived from TFrameWindow. A typical use is

 virtual void TMyApp_InitMainWindow(){
   SetMainWindow(TMyWindow(NULL, Caption));
 }

InitMainWindow can be overridden to create your own custom window.

References owl::TModule::GetName(), and SetMainWindow().

int owl::TApplication::MessageBox	(	HWND	wnd,
		LPCTSTR	text,
		LPCTSTR	caption = `0`,
		uint	type = `MB_OK`
	)		`[virtual]`

Open a modal message box, Under WIN32 the language id setting is used.

References owl::TModule::GetName().

int owl::TApplication::MessageLoop ( ) [virtual]

Operates the application's message loop, which runs during the lifetime of the application. MessageLoop queries for messages. If one is received, it processes it by calling ProcessAppMsg. If the query returns without a message, MessageLoop calls IdleAction to perform some processing during the idle time.

MessageLoop calls PumpWaitingMessages to get and dispatch waiting messages. MessageLoop can be broken if BreakMessageLoop is set by EndModal.

Reimplemented from owl::TMsgThread.

References owl::TMsgThread::BreakMessageLoop, ConvertA2W(), IdleAction(), owl::TMsgThread::MessageLoopResult, owl::TMsgThread::PumpWaitingMessages(), and owl::TXOwl::Unhandled().

void owl::TApplication::PostDispatchAction ( )

Call this function after each msg dispatch if TApplication's message loop is not used.

If TApplication's message loop is not used, this function should be called after each message is dispatched

References IdleAction().

void owl::TApplication::PreProcessMenu ( HMENU hMenubar ) [virtual]

Called by the main window to provide an oportunity to preprocess the main window's menubar before it is installed. Normally delegated to the doc manager to install a file menu as needed

References owl::TEventHandler::Dispatch(), owl::TWindow::DrawMenuBar(), and owl::TEventHandler::Find().

bool owl::TApplication::ProcessAppMsg ( MSG & msg ) [virtual]

Called after each message is pulled from the queue, and before it is dispatched. Return true if the message was handled completely here. Checks for any special processing that is required for modeless dialog box, accelerator, and MDI accelerator messages. Calls the virtual TWindow::PreProcessMsg function of the window receiving the message. If your application does not create modeless dialog boxes, does not respond to accelerators, and is not an MDI application, you can improve performance by overriding this member function to return false.

References GetWindowPtr(), owl::TWindow::IsChild(), owl::TWindow::IsWindow(), owl::TWindow::PreProcessMsg(), owl::TTooltip::RelayEvent(), and SystemCommandTrace().

bool owl::TApplication::ProcessMsg ( MSG & msg ) [virtual]

Called for each message that is pulled from the queue, to perform all translation & dispatching.

Return true to drop out of pump

Reimplemented from owl::TMsgThread.

References owl::TEventHandler::Dispatch(), Find(), and ProcessAppMsg().

int owl::TApplication::Run ( ) [virtual]

Run this application, return when application terminates.

Initialize instances, create and display their main window (calls InitApplication for the first executing instance and calls InitInstance for all instances). Run the application's message loop. Each of the virtual functions called are expected to throw an exception if there is an error. Exceptions that are not handled, i.e. status remains non-zero, are propagated out of this function. Msg queue is still flushed & TermInstance called. If an error occurs in the creation of a window, Run throws a TXWindow exception. If Status is assigned a nonzero value (which ObjectWindows uses to identify an error), a TXCompatibility exception is thrown.

Reimplemented from owl::TMsgThread.

References ConvertA2W(), owl::TMsgThread::FlushQueue(), InitApplication(), InitInstance(), owl::TMsgThread::LoopRunning, MessageLoop(), TermInstance(), and owl::TXOwl::Unhandled().

void owl::TApplication::SetCmdShow ( int cmdshow ) [inline]

Sets the initial state of the main window. Typically passed by the operating system.

TDocManager * owl::TApplication::SetDocManager ( TDocManager * docManager ) [protected]

Set (or resets) the document manager, return the previous one if present.

void owl::TApplication::SetLangId ( TLangId landid ) [inline]

Sets new language for use with application. Note that it only sets the variable LangId.

TFrameWindow * owl::TApplication::SetMainWindow ( TFrameWindow * window ) [protected]

Set (or reset) the main window. Return, but do not destroy the previous main window.

References owl::TWindow::ClearFlag(), owl::TWindow::GetExStyle(), owl::TWindow::GetHandle(), owl::TWindow::GetParentO(), owl::TWindow::SetExStyle(), owl::TWindow::SetFlag(), owl::TWindow::SetParent(), and owl::wfMainWindow.

void owl::TApplication::SetPrevInstance ( HINSTANCE pi ) [inline]

Set the previous instance. This should not be called by normal programs.

void owl::TApplication::SetTooltip ( TTooltip * tooltip ) [protected]

Assigns tooltip.

Set tooltip . Assume we now own the ToolTip.

References owl::TWindow::Create(), owl::TWindow::GetHandle(), owl::TWindow::GetParentO(), owl::TWindow::ModifyStyle(), owl::TWindow::SendMessage(), and owl::TWindow::SetParent().

void owl::TApplication::SetWinMainParams	(	HINSTANCE	hInstance,
		HINSTANCE	hPrevInstance,
		const tstring &	cmdLine,
		int	cmdShow
	)		`[inline, static]`

Set the data members with data from WinMain.

The ObjectWindows default WinMain function calls SetMainWinParams so that TApplication can store the parameters for future use. To construct an application instance, WinMain calls the OwlMain function that is in the user's code. As it is being constructed, the application instance can fill in the parameters using those set earlier by SetMainWinParams.

int owl::TApplication::Start ( ) [virtual]

Start this application and return immediately. Used for component DLLs.

Initializes instances, creating and displaying their main window (calls InitApplication for the first executing instance and calls InitInstance for all instances). Each of the virtual functions called are expected to throw an exception if there is an error. Does not run message loop.

References ConvertA2W(), InitApplication(), InitInstance(), and owl::TXOwl::Unhandled().

void owl::TApplication::SystemCommandTrace ( ) [protected]

Creates or destroyes the Diagnostic Windows. This function called from ProcessAppMsg() when OWL is compiled with __TRACE or __WARN options. If you would like to use Diagnostic windows with the release version of OWL you should add a menu item in System Menu with Id: SCM_TRACE =0xFEC0, and if the user presses it call SystemCommandTrace() to create the Diagnostic window.

References owl::TWindow::Create().

int owl::TApplication::TermInstance ( int status ) [protected, virtual]

Handle termination for each executing instance of the application. Called at the end of a Run() with the final return status.

Reimplemented from owl::TMsgThread.

void owl::TApplication::Uncondemn ( TWindow * win )

Remove a condemned window from the list.

References owl::TWindow::Next(), and owl::TWindow::SetNext().

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

D:/Work/OWLNext/Subversion/branches/632/include/owl/applicat.h
D:/Work/OWLNext/Subversion/branches/632/source/owlcore/applicat.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation