molib documentation

Languages Available: français español

CLASS

moApplication

NAME

Instance -- return the application instance
Done -- signal that you won't call Instance() anymore

VERSION

Version: 1.2.0

SYNOPSIS

moApplicationSPtr Instance(void);
void Done(void);

DESCRIPTION

This function returns the application instance. It is a static function which creates a singleton.

An application instance is unique.

Once you are done with this singleton, call the Done() function. It will release the application instance and mark the function as done (i.e. the Instance() function will fail).

RETURN VALUE

Instance() returns a smart pointer to an application instance

SEE ALSO

Constructor, SetArgs, Run, Terminate

BUGS

The Instance() function is NOT multi-thread safe when first called. We assume that the function will be called at least once before threads which has a chance to also call this function are created.

The Done() function is NOT multi-thread safe. It should be called after all the child threads joined the parent thread.

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication

NAME

Constructor -- initialize an application
Destructor -- clean up an application object

VERSION

Version: 1.2.0

SYNOPSIS

private:
moApplication(void);
virtual ~moApplication(void);

DESCRIPTION

This function initializes an moApplication object.

This function is private. You can at most have one application instance. This one is retrieved with the Instance() function call. That function will have the right to create an moApplication object.

SEE ALSO

Instance

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication

NAME

SetName -- set the name of the application
GetName -- get the name of the application
GetFilename -- get the name of the application to use as a filename

SetVersion -- set the application version (i.e. "2" or "3.2.6b")
GetVersion -- get the application version

VERSION

Version: 1.2.0

SYNOPSIS

void SetName(const moWCString& name);
const moWCString& GetName(void) const;
const moWCString& GetFilename(void) const;

void SetVersion(const moWCString& version);
const moWCString& GetVersion(void) const;

void SetCopyright(const moWCString& copyright);
const moWCString& GetCopyright(void) const;

PARAMETERS

name -- the new name of the application
version -- the new application version
copyright -- the application copyright (1 line)

DESCRIPTION

The SetName() defines the name of the application.

The SetVersion() defines the version of the application.

This name and version will be used as the default for different directories and filenames such as the ~/.<name>-<version> user directory.

The SetCopyright() defines the copyright of the application. It is expected to be one line.

The GetName() function returns the last name which was defined with SetName().

The GetVersion() function returns the last version which was defined with SetVersion(). By default it is set to 1.0.

The GetCopyright() function returns the last copyright which was defined with SetCopyright(). By default it is set to an empty string.

The GetFilename() function returns the name of the application fixed to work as a filename (i.e. the spaces are replaced with underscores, letters are changed to lowercase under Unices, etc.) This will always be one name (no slash).

RETURN VALUE

The GetName() function returns a constant string reference
to the name of the application.

SEE ALSO

GetConfiguration

BUGS

It is strongly suggested that you don't change the name as the application runs.

The GetFilename() doesn't yet handle all the possible invalid directory or file names.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication

NAME

SetRootPath -- set the root to use by the application
GetRootPath -- get the root path of the application
SetApplicationPath -- set the application path
GetApplicationPath -- get the application path
GetUserPath -- get user path to visible files
GetPrivateUserPath -- get user path to hidden files
ResetUserPath -- Reset the internal user path so you can remake it more than one during a run
ResetPrivateUserPath -- Reset the internal private user path so you can remake it more than one during a run
SetManufacturer -- set the name of the manufacturer of the product
GetManufacturer -- set the name of the manufacturer of the product

VERSION

Version: 1.2.0

SYNOPSIS

void SetRootPath(const moWCString& root_path);
const moWCString& GetRootPath(void) const;
void SetApplicationPath(const moWCString& application_path);
const moWCString& GetApplicationPath(bool docs = false);
const moWCString& GetUserPath(void);
const moWCString& GetPrivateUserPath(bool append_version = true);
void SetManufacturer(const moWCString& name);
const moWCString& GetManufacturer(void) const;

PARAMETERS

root_path - the path to the root tree used by the application
application_path - where the application data was installed
docs - when set to true, return the path to the documentations
name - the name of the manufacturer

DESCRIPTION

The root path is used to install the application in a sub-directory which isn't the root (/). For instance you may compile your application in:

/home/alexis/my_app

And you install it in a sub-directory named BUILD. In this case, the root path should be set to:

/home/alexis/my_app/BUILD

Note that thought the application root path will be set to that path, there is nothing which forces any functions other than the functions available in the moApplication to actually make use of that root path. It is up to the application developers to make sure they make use of this path.

It is possible to set the root path using the SetRootPath() function, setting the MO_ROOTPATH environment variable before to start your application or using the --root-path command line option. The latter will not be available if you call the SetOptions() function with the use_default_options parameter set to false.

Note that the SetRootPath() will canonilize the path so it is a valid path for the system you are running on. For instance, under MS-Windows, a drive letter will be prepended if none are specified in the input string. Also, a root path is always forced to start with a slash (/).

The RootPath() should only be used in development while your application doesn't yet reside at the right place on your disk (it will be once you install it). Once your application is installed, the root path automatically becomes a single slash (/).

If you want to use a path to some read-only data specific to your application, you need to use the application path. You can change the application path using the SetApplicationPath() function and retrieve it with the GetApplicationPath() function. This path uses the root path Sub-directories can be defined under the application path using the information in the application configuration file (see GetConfiguration() for more information).

Note that the directory pointed by the GetApplicationPath() will in most cases be read-only. It should always be considered that way. The sub-directories will be created and initialized and installation time.

By default, the application path is built from a path found in the configuration file and the application name. When the configuration file doesn't define the paths, then the system makes an attempt to find the application directory and uses that instead.

Under MS-Windows, the default path is the path to the application less one directory. It is expected that this will be something like this:

C:\Program File\<manufacturer>\<application name>\<version>\

Note that the application binary is expected to be like this:

C:\Program File\<manufacturer>\<application name>\<version>\bin\<application name>.exe

Under Unix systems, the user path is &x24;HOME and the private user path is built from &x24;HOME, the name of the application and the version:

user path: &x24;HOME private: &x24;HOME/.<application name>-<version>

Under MS-Windows, we first test for the &x24;HOME environment variable. If you have that variable set, then it will use it exactly like under Unix systems (the private directory will be marked hidden at installation time).

When the &x24;HOME environment variable doesn't exist, a shell MS-Windows function is used instead (SHGetFolderPath). That function is used with CSIDL_APPDATA for private user data and CSIDL_PERSONAL for the regular user data.

In general, the CSIDL_APPDATA will translate to a hidden folder as follow:

C:\Documents and Settings\<username>\Application Data\<manufacturer>\<application name>\<version>\

CSIDL_PERSONAL is translated to:

C:\My Documents\<application name>

Note that My Documents is a virtual folder and usually the function will transform that folder name to a physical name. (i.e. C:\Documents and Settings\<username>\My Documents\<appname>)

It is not possible to set the user paths since these can't be changed.

Because MS-Windows requires the user and application data to be saved under a directory structure including the name of the manufacturer, we have two functions to handle that name: SetManufacturer() and GetManufacturer(). The default name is "Made to Order Software Corporation".

The application version is expected to be defined with the SetVersion() function.

By default, the version is used to create the paths. It is possible to avoid having the version in the path by setting the no_version boolean parameter to false.

RETURN VALUE

The GetRootPath() function returns a constant string reference
to the root path of the application.

The GetApplicationPath() function returns a constant string
reference to the application path.

The GetUserPath() function returns a constant string reference
to the user home directory. Saving files here will ensure that
these files are visible to the user.

The GetPrivateUserPath() function returns a constant string
reference to a user directory which is hidden. This is usually
a good place to save data that the application wants to
remember such as the position and sizes of windows, the color
preferences, the special control keys setup, etc.

The GetManufacturer() function returns a constant string
reference to the manufacturer name.

SEE ALSO

GetConfiguration, SetName, GetName

BUGS

When an MS-DOS root path starts with a drive letter and a colon but no slash (/), then a slash is added right after the colon. This may not be what you expect. It is required that the root path be a full path.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication

NAME

SetOptions -- defines the argc and argv parameters
Option - retrieve an option
GetOpt - retrieve the application moGetOpt object

VERSION

Version: 1.2.0

SYNOPSIS

void SetOptions(const moWCString& accept, int argc,
const char *argv[], bool use_default_options = true);
moGetOpt::moOptionSPtr Option(const moWCString& name) const;
moGetOpt::moOptionSPtr Option(unsigned long identifier) const;
moGetOptSPtr GetOpt(void) const;

PARAMETERS

accepts - what options are to be accepted
argc - the number of arguments in argv
argv - a null terminate array of strings
use_default_options - whether the internal options are used
name - name of an option to retrieve
identifier - the identifier of an option to retrieve

DESCRIPTION

This function setups the list of command line arguments in the application object. The arguments will be transformed in an array of options which you can access with the Option() functions.

This should be done before calling the Run() function.

It is strongly suggested that you don't use the SetOptions() function to setup other arguments than the command line arguments. For other purposes, you can create your own moGetOpt object that you can manage as required. Note that calling the SetOptions() a second time wipes out the first list of arguments which will be replaced by the new list.

The SetOptions() will add its own set of flags as defined here:

--config <filename> --app-name <name> --root-path <path>

The --config specifies an alternate configuration filename and path. By default, the application name is used. The --app-name changes the name of the application. This is used so directories such as ~/.<app-name> can be changed. The --root-path defines the root directory for the application. This is practical if you want to install the application in a path other than /. The data used by the application will be searched with the root path prepended.

Retrieve the options found on the command line by calling the Option() functions or retrieving the moGetOpt object. The Option() functions work like the functions of the same name in the moGetOpt object. These are just helper functions here.

EXAMPLES

The following shows you an example of usage:

int main(int argc, const char *argv[])
{
static const char accept[] = {
"11 -v;"
"12 -> 11 --verbose;"
};
moApplicationSPtr app = moApplication::Instance();
app->SetOptions(accept, argc, argv);
app->Run();
return 0;
}

int foo(void)
{
...
moApplicationSPtr app = moApplication::Instance();
moGetOpt::moOptionSPtr opt = app->GetOption(11);
if(opt) {
// verbose (-v or --verbose) was specified on the command line
...
}
...
}

NOTES

This SetOptions() function will NOT return (because it will call exit(1) directly) if it finds an error in the list of arguments (missing parameters, misunderstood parameter, etc.).

SEE ALSO

Instance, moWaitHandler class moGetOpt constructor documentation for flag features

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication

NAME

GetConfiguration -- returns a reference to the app. configuration
LoadPropBag -- load a bag of properties

VERSION

Version: 1.2.0

SYNOPSIS

moPropBagRef GetConfiguration(void);
int LoadPropBag(const moWCString& name, moPropBagRef prop_bag);

DESCRIPTION

The GetConfiguration() function returns a reference to a property bag of the application configuration.

The first time the GetConfiguration() function is called, it reads a property bag XML file. The file will never be read a second time (this may be changed at a later date if we want to support servers configuration which can change while running).

The name of the configuration file is defined as follow:

/<root path>/etc/<application name>.xml

The name of the application needs to be defined or this function throws an exception.

The root path can be empty in which case "/" is considered to be the root path.

The LoadPropBag() function can be used to load other XML files as required. These use the root and the application data path and the .xml extension is added when no extension exists. The data path will be defined in the configuration file.

SEE ALSO

SetName(), SetOptions()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication

NAME

Run -- runs the application
Dispatch -- runs the existing messages

VERSION

Version: 1.2.0

SYNOPSIS

int Run(void);
void DispatchAll(void);

DESCRIPTION

The Run() function runs the application by calling the event pipes at all time. This has the effect of emptying the pipes and waiting for new events.

Internally, we accept Broadcasted events.

Externally, the user can declare an moWaitHandler and register it with AddWaitHandler (and later remove it with RemoveWaitHandler). Whenever the application is idle (no more events are present in the pipe), it will call the Wait() function of the wait handlers.

The DispatchAll() function empties the event pipes. Once idle, it calls the user Wait() function and then checks the event pipes again. If still empty, the function returns, otherwise the process is repeated.

SEE ALSO

Instance, moWaitHandler class

BUGS

You cannot call the Run() function with a bare pointer to the application.

Please, use a smart pointer to save your copy of the application object before to call the Run() function.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication

NAME

AddWaitHandler -- attach a wait handler to the application
RemoveWaitHandler -- remove a wait handler from the application
CallWaitHandlers -- call all the wait handlers
CallDoneHandlers -- call the Done() function of all the wait handlers

VERSION

Version: 1.2.0

SYNOPSIS

void AddWaitHandler(const moWaitHandler& handler);
void RemoveWaitHandler(const moWaitHandler& handler);

private:
void CallWaitHandlers(void);

DESCRIPTION

The AddWaitHandler() function will be used to add one or more wait handler to the application. The same handler can be added multiple times, though it is strongly suggested that you don't do so.

By default, the application will call the Wait() function of the broadcast pipe. In effect, it will wait for an internal event to be received.

The RemoveWaitHandler() can be called to remove a handler which was previously added with AddWaitHandler(). If the same handler was added multiple times, you need to remove it the same number of times.

The CallWaitHandlers() function is automatically called by the Run() function whenever the application is idle. In order for the list of wait handlers to work in a multi-thread environment and to allow the use of the AddWaitHandler() & RemoveWaitHandler() functions from within a Wait() function, the current list of wait handlers is copied before their Wait() functions are called. While the copy is performed, the same mutex as used to add and remove handlers is locked.

Note that newly added handlers won't be executed until the next time the CallWaitHandlers() is called. Similarly, removing a handler which wasn't called yet won't prevent that handler from being called until the next time CallWaitHandlers() is called.

The handlers are not sorted automatically. Instead, they are added one after another as the user defines them. The handlers are called in the order the user defined them. At this time there isn't a way to insert a new handler at a specific position.

SEE ALSO

Run

BUGS

Your application will hang if this function is called and no other thread is running and there is no wait handler recorded.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication

NAME

Terminate -- ask the application to stop

VERSION

Version: 1.2.0

SYNOPSIS

void Terminate(bool force = false);

DESCRIPTION

The Terminate() function can either terminate right away (i.e. force is set to true) or post a message to all the receivers to request a termination of the application.

When the force flag is not set to true, a receiver will usually check whether the user really wants to quit (with a window such as: "Do you really want to quit?" "Yes"/"No"), and if so, that function will call Terminate() again this time with the force flag set to true.

SEE ALSO

Run(), moApplicationEvent class

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication::moWaitHandler

NAME

Destructor -- necessary for there are virtual functions

VERSION

Version: 1.2.0

SYNOPSIS

virtual ~moWaitHandler();

DESCRIPTION

Cleans up a wait handler object.

SEE ALSO

Run()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication::moWaitHandler

NAME

Wait -- a Wait() handler function

VERSION

Version: 1.2.0

SYNOPSIS

virtual void Wait(void) = 0;

DESCRIPTION

The Wait() function of registered moWaitHandler's are called whenever the thread running the moApplication Run() function is idle.

The moWaitHandler class needs to be derived for the Wait() function to do something useful.

SEE ALSO

Run()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication::moWaitHandler

NAME

Done -- empty function

VERSION

Version: 1.2.0

SYNOPSIS

virtual void Done(void);

DESCRIPTION

The Done() function is called right before the Run() function returns. It can clean up your objects as required.

SEE ALSO

Run()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplication::moWaitHandler

NAME

Compare -- used to find wait handlers in a list

VERSION

Version: 1.2.0

SYNOPSIS

virtual compare_t Compare(const moBase& object) const;

DESCRIPTION

The Compare() function will return one of the comparison result as defined in the moBase. Note that we save the wait handlers in a non-sorted list (in order to keep them in the order the users registers them).

The Compare() calls the ComparePtr() function.

SEE ALSO

Run()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplicationEvent

NAME

Destructor -- need a destructor because we have virtual functions
GetClassName -- return the name of this event class

VERSION

Version: 1.2.0

SYNOPSIS

virtual ~PostTerminate();
const char *GetClassName(void) const;

DESCRIPTION

Clean up the application event object.

SEE ALSO

PostTerminate()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moApplicationEvent

NAME

PostTerminate -- post the terminate event

VERSION

Version: 1.2.0

SYNOPSIS

void PostTerminate(moEventPipeBroadcast *broadcast);

DESCRIPTION

The PostTerminate() function is used by the moApplication::Terminate() function to request all the receivers to terminate.

This doesn't actually shutdown the application. It only broadcast the termination signal to all the objects. Calling moApplication::Terminate() with true from one of these signal handler will really terminate the application.

SEE ALSO

moApplication::Terminate()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox