tbx  0.7.5
Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
tbx::Application Class Reference

The main application class. More...

#include <application.h>

Public Member Functions

 Application (const char *task_directory, int wimp_version=MIN_WIMP_VERSION, const int *deliver_messages=ALL_MESSAGES, const int *deliver_events=ALL_EVENTS)
 Initialise the application. More...
 
SpriteAreasprite_area () const
 Get the sprite area. More...
 
void run ()
 Run the main polling loop for the application. More...
 
void set_autocreate_listener (std::string template_name, AutoCreateListener *listener)
 Set the AutoCreateListener to be called when an object with the specified template is created. More...
 
void clear_autocreate_listener (std::string template_name)
 Clear the autocreate listener for the specified template. More...
 
void add_command (int command_id, Command *command)
 Add a command to be run for the specified event ID. More...
 
void remove_command (int command_id, Command *command)
 Remove a command. More...
 
void add_idle_command (Command *command)
 Add a command to be run when no events are being received from the desktop. More...
 
void remove_idle_command (Command *command)
 Remove a command to be run when no events are being received from the desktop. More...
 
void add_user_message_listener (int message_id, WimpUserMessageListener *listener)
 Add a listener for the given user message (event code 17) More...
 
void remove_user_message_listener (int message_id, WimpUserMessageListener *listener)
 Remove a listener for the given user message. More...
 
void add_recorded_message_listener (int message_id, WimpRecordedMessageListener *listener)
 Add a listener for the given recorded message (event code 18) More...
 
void remove_recorded_message_listener (int message_id, WimpRecordedMessageListener *listener)
 Remove a listener for the given recorded message. More...
 
void add_acknowledge_message_listener (int message_id, WimpAcknowledgeMessageListener *listener)
 Add a listener for the given acknowledge message (event code 18) More...
 
void remove_acknowledge_message_listener (int message_id, WimpAcknowledgeMessageListener *listener)
 Remove a listener for the given acknowledge message. More...
 
void add_prequit_listener (PreQuitListener *listener)
 Add a listener for the pre quit message sent (usually) by the desktop. More...
 
void remove_prequit_listener (PreQuitListener *listener)
 Remove a prequit listener. More...
 
void add_quit_listener (QuitListener *listener)
 Add a listener to process the Quit message. More...
 
void remove_quit_listener (QuitListener *listener)
 Remove a quit listener. More...
 
void add_mode_changed_listener (ModeChangedListener *listener)
 Listen for changes to the Desktop mode. More...
 
void remove_mode_changed_listener (ModeChangedListener *listener)
 Remove mode changed listener. More...
 
void add_palette_changed_listener (PaletteChangedListener *listener)
 Add listener for changes to desktop palette. More...
 
void remove_palette_changed_listener (PaletteChangedListener *listener)
 Remove listener for changes to the desktop palette. More...
 
void add_timer (int elapsed, Timer *timer)
 Add a timer to the application that will be called at a regular interval. More...
 
void remove_timer (Timer *timer)
 Remove the given timer. More...
 
void add_opener (Loader *loader, int file_type)
 Add a file opener. More...
 
void remove_opener (Loader *loader, int file_type)
 Remove a file opener. More...
 
res::ResObject resource (std::string template_name)
 Get a Resource object template from the main toolbox templates. More...
 
TaskHandle task_handle () const
 Get WIMP task handle for application.
 
std::string directory () const
 Return the name of the directory that was used to initialised this application. More...
 
const MessageFilemessages () const
 Return the default message file for this application.
 
void quit ()
 Quit the application. More...
 
bool running () const
 Check if application is running. More...
 
bool yield ()
 Allow other applications and events in this application to be run. More...
 
void unix_file_name_translation (bool on)
 Turn on or off UnixLib's automatic translation of unix style file names. More...
 
bool unix_file_name_translation () const
 Check if some unix file name translations are being used. More...
 
void unix_file_name_control (int flags)
 Set flags to control the unix file name translation process. More...
 
int unix_file_name_control () const
 Get the flags that control the unix file name translation process.
 
void catch_poll_exceptions (bool on)
 Catch any uncaught exceptions thrown during polling and show them in an error box. More...
 
void uncaught_handler (UncaughtHandler *handler)
 Report any uncaught exceptions to the given interface. More...
 
void set_pre_poll_listener (PrePollListener *listener)
 Set listener to run just before the internal call to Wimp_Poll. More...
 
void set_post_poll_listener (PostPollListener *listener)
 Set listener to look at the results of the internal call to Wimp_Poll. More...
 
void set_post_event_listener (PostEventListener *listener)
 Set listener to call after the event processing in TBX. More...
 
bool owns_window (WindowHandle window_handle, IconHandle icon_handle=0)
 Check if this application owns WIMP window/icon bar icon. More...
 
int start_wimp_task (std::string command)
 Start a child task from this application. More...
 
void os_cli (std::string command)
 Run a command using the RISC OS Command Line interpreter. More...
 

Static Public Member Functions

static Applicationinstance ()
 Get the application instance. More...
 

Static Public Attributes

static const int MIN_WIMP_VERSION = 310
 Minimum Wimp version TBX supports.
 
static const int * NO_MESSAGES = (int *)0
 Don't deliver any wimp messages (except QUIT)
 
static const int * ALL_MESSAGES = all
 Deliver all messages.
 
static const int * NO_EVENTS = (int *)0
 Don't deliver any toolbox event.
 
static const int * ALL_EVENTS = all
 Deliver all toolbox events.
 

Detailed Description

The main application class.

Each application create one Application object, set up any initial commands and listeners and then call the run method.

int main()
{
Application my_app("<MyApp$Dir>");
// Add commands and listeners here
my_app.run();
return 0;
}

Constructor & Destructor Documentation

◆ Application()

Application::Application ( const char *  task_directory,
int  wimp_version = MIN_WIMP_VERSION,
const int *  deliver_messages = ALL_MESSAGES,
const int *  deliver_events = ALL_EVENTS 
)

Initialise the application.

If the application can not be initialised this will report the error and then exit the program.

Parameters
task_directoryThe path to application directory
wimp_versionThe minimum WIMP version supported by the application. Defaults to MIN_WIMP_VERSION (310).
deliver_messagesInteger array of message IDs that will be delivered to the application. Defaults to deliver all messages. Use:
  • ALL_MESSAGES - to deliver all messages.
  • NO_MESSAGES - to deliver no messages
deliver_eventsInteger array of Toolbox event IDs that will be delivered to the application. Defaults to deliver all messages. Use:
  • ALL_EVENTS - to deliver all toolbox events.
  • NO_EVENTS - to deliver no toolbox events

Member Function Documentation

◆ add_acknowledge_message_listener()

void Application::add_acknowledge_message_listener ( int  message_id,
WimpAcknowledgeMessageListener listener 
)

Add a listener for the given acknowledge message (event code 18)

Parameters
message_idcode to listen for.
listenerto execute.

◆ add_command()

void Application::add_command ( int  command_id,
Command command 
)

Add a command to be run for the specified event ID.

Multiple commands can be added for the same event ID.

For more details on command IDs, events and commands see the topic The tbx event system

Parameters
command_idThe ID for the command
commandThe command to run.

◆ add_idle_command()

void Application::add_idle_command ( Command command)

Add a command to be run when no events are being received from the desktop.

Parameters
commandThe command to add

◆ add_mode_changed_listener()

void Application::add_mode_changed_listener ( ModeChangedListener listener)

Listen for changes to the Desktop mode.

This message is used if you need to know anything about changes to the screen.

When the mode changes the WIMP redraws all the windows so this event normally only used when sizes depend on pixel rather than OS sizes or eigen factors or colours are cached.

Parameters
listenerlistener for mode change events

◆ add_opener()

void Application::add_opener ( Loader loader,
int  file_type 
)

Add a file opener.

A file opener is called when a file of a given type is double clicked in the filer.

The file opener uses the same Loader class as a file loader so the same loader can be shared, but note it only fills in the file type, file name and from filer fields.

If the type is set to -2 you must implement the accept_file member of the Loader or this application will intercept all files.

Parameters
loaderthe loader used to open the file
file_typethe file type for the loader or -2 for any type.

◆ add_palette_changed_listener()

void Application::add_palette_changed_listener ( PaletteChangedListener listener)

Add listener for changes to desktop palette.

This message is sent if the desktop palette utility changes the colour palette.

It it normally only needed if an application has to change internal colour tables.

Note though that the palette utility automatically forces a redraw of the whole screen if any of the WIMP's standard colours change their logical mapping, so applications don't have to take further action if they are just using WIMP colours.

It is not generated on a mode change so you need to listen to that event as well.

Parameters
listenerlistener for palette change events

◆ add_prequit_listener()

void Application::add_prequit_listener ( PreQuitListener listener)

Add a listener for the pre quit message sent (usually) by the desktop.

This message gives the application a chance to refuse to quit if it has unsaved documents.

Parameters
listenerthe prequit listener to add

◆ add_quit_listener()

void Application::add_quit_listener ( QuitListener listener)

Add a listener to process the Quit message.

The quit message is sent when the desktop wants the application to close. At this point the application does not have a choice and must close.

The application class will drop out of its run method after these messages have been processed and the program should exit.

Use a prequit listener to object to the desktop closing down the application.

Parameters
listenerquit listener to add

◆ add_recorded_message_listener()

void Application::add_recorded_message_listener ( int  message_id,
WimpRecordedMessageListener listener 
)

Add a listener for the given recorded message (event code 18)

Parameters
message_idcode to listen for.
listenerto execute.

◆ add_timer()

void Application::add_timer ( int  elapsed,
Timer timer 
)

Add a timer to the application that will be called at a regular interval.

Timers are only processed when there are no other events so they will not necessarily be delivered exactly on time.

Parameters
elapsednumber of centiseconds between calls
timer- timer to add

◆ add_user_message_listener()

void Application::add_user_message_listener ( int  message_id,
WimpUserMessageListener listener 
)

Add a listener for the given user message (event code 17)

Parameters
message_idcode to listen for.
listenerto execute.

◆ catch_poll_exceptions()

void Application::catch_poll_exceptions ( bool  on)

Catch any uncaught exceptions thrown during polling and show them in an error box.

If this is off, uncaught exceptions will close the program.

This defaults to true so an end user will get an indication if something goes wrong.

It is useful to turn it off during development so a full stack trace of the error is shown in stdout.

Parameters
on- true to catch the unhandled exceptions, false to let them through.

◆ clear_autocreate_listener()

void Application::clear_autocreate_listener ( std::string  template_name)

Clear the autocreate listener for the specified template.

Parameters
template_nameThe name of the template.

◆ directory()

std::string Application::directory ( ) const

Return the name of the directory that was used to initialised this application.

RISC OS 5 always returns this as a path, so may have appended a '.' to the name. RISC OS 4.0.2 doesn't do this.

For consistency this function returns it in the RISC OS 5 format whatever the OS.

◆ instance()

static Application* tbx::Application::instance ( )
inlinestatic

Get the application instance.

Returns
Pointer to current application

◆ os_cli()

void Application::os_cli ( std::string  command)

Run a command using the RISC OS Command Line interpreter.

Warning: This method should only be used for module commands, any command that runs another program will replace the program that calls it and never return.

Use start_wimp_task to run another program, leaving this program running.

Parameters
commandcommand to run
Exceptions
OsErrorcommand failed to run

◆ owns_window()

bool Application::owns_window ( WindowHandle  window_handle,
IconHandle  icon_handle = 0 
)

Check if this application owns WIMP window/icon bar icon.

Parameters
window_handleWIMP window handle to test or -2 to check an icon bar
icon_handleto test (ignored if window handle is not -2)

◆ quit()

void tbx::Application::quit ( )
inline

Quit the application.

The application will quit once it returns to the main polling loop inside the run() method.

◆ remove_acknowledge_message_listener()

void Application::remove_acknowledge_message_listener ( int  message_id,
WimpAcknowledgeMessageListener listener 
)

Remove a listener for the given acknowledge message.

Parameters
message_idcode to remove
listenerto remove.

◆ remove_command()

void Application::remove_command ( int  command_id,
Command command 
)

Remove a command.

The event is only removed if the command ID and the command match a previously added command.

Parameters
command_idThe command ID used for this command
commandThe command that was originally added

◆ remove_idle_command()

void Application::remove_idle_command ( Command command)

Remove a command to be run when no events are being received from the desktop.

Parameters
commandthe command to remove

◆ remove_mode_changed_listener()

void Application::remove_mode_changed_listener ( ModeChangedListener listener)

Remove mode changed listener.

Parameters
listenerpreviously added listener for mode change events

◆ remove_opener()

void Application::remove_opener ( Loader loader,
int  file_type 
)

Remove a file opener.

Parameters
loaderthe loader used to open the file to remove
file_typethe file type for the loader or -2 for any type.

◆ remove_palette_changed_listener()

void Application::remove_palette_changed_listener ( PaletteChangedListener listener)

Remove listener for changes to the desktop palette.

Parameters
listenerpreviously added listener for palette change events

◆ remove_prequit_listener()

void Application::remove_prequit_listener ( PreQuitListener listener)

Remove a prequit listener.

Parameters
listenerthe prequit listener to remove

◆ remove_quit_listener()

void Application::remove_quit_listener ( QuitListener listener)

Remove a quit listener.

Parameters
listenerto remove

◆ remove_recorded_message_listener()

void Application::remove_recorded_message_listener ( int  message_id,
WimpRecordedMessageListener listener 
)

Remove a listener for the given recorded message.

Parameters
message_idcode to remove
listenerto remove.

◆ remove_timer()

void Application::remove_timer ( Timer timer)

Remove the given timer.

Parameters
timerTimer to remove

◆ remove_user_message_listener()

void Application::remove_user_message_listener ( int  message_id,
WimpUserMessageListener listener 
)

Remove a listener for the given user message.

Parameters
message_idcode to remove
listenerto remove.

◆ resource()

res::ResObject Application::resource ( std::string  template_name)

Get a Resource object template from the main toolbox templates.

The return value should not be saved as the resource it points to is not guaranteed to exist the same for the lifetime of the application.

◆ run()

void Application::run ( )

Run the main polling loop for the application.

Once the application has been initialised the program should call this routine to process the events.

The routine will not return until the quit method is called from an event listener or command or the event id 0x82a91 (This is the id of the Quit event from the quit dialog) is received.

See also
quit

◆ running()

bool tbx::Application::running ( ) const
inline

Check if application is running.

The application is considered to be running after a call to run() until a call to quit() or the WIMP quit message is received

Returns
true

◆ set_autocreate_listener()

void Application::set_autocreate_listener ( std::string  template_name,
AutoCreateListener listener 
)

Set the AutoCreateListener to be called when an object with the specified template is created.

This function is used to capture the object handle of an auto created object so it can be used to add event handlers or stored for later use.

Objects are auto created when the toolbox resources are loaded if the auto create flag was set in the toolbox resource file.

Parameters
template_nameThe name of the object template.
listenerThe auto create listener to call when an object for the specified template is called.

◆ set_post_event_listener()

void Application::set_post_event_listener ( PostEventListener listener)

Set listener to call after the event processing in TBX.

There can only be one of these listeners. It is called after Wimp_Poll and any event processing.

The parameters past to the post event listener may have been changed by the event processing. (Though this is usually not the case).

This is an advanced routine and should be used sparingly.

Parameters
listenerListener to report the poll results to. Set to 0 to remove the post poll listener.

◆ set_post_poll_listener()

void Application::set_post_poll_listener ( PostPollListener listener)

Set listener to look at the results of the internal call to Wimp_Poll.

There can only be one of these listeners. It is called immediately after Wimp_Poll before any other processing.

Care must be taken in the PostPollListener so as not to cause problems for the processing that follows this.

The call is mainly provided to help with debugging of the messages received by the application by the Wimp.

Parameters
listenerListener to report the poll results to. Set to 0 to remove the post poll listener.

◆ set_pre_poll_listener()

void Application::set_pre_poll_listener ( PrePollListener listener)

Set listener to run just before the internal call to Wimp_Poll.

There can only be one of these listeners. It is called immediately before Wimp_Poll.

This is an advanced routine and should be used sparingly.

Parameters
listenerListener to call prior to wimp poll. Set to 0 to remove the post poll listener.

◆ sprite_area()

SpriteArea* tbx::Application::sprite_area ( ) const
inline

Get the sprite area.

Returns
sprite area or 0 if no area

◆ start_wimp_task()

int Application::start_wimp_task ( std::string  command)

Start a child task from this application.

This call returns when the task called calls Wimp_Poll or after it finishes.

Parameters
commandcommand line to start the task
Returns
handle of task started if it's still alive or 0
Exceptions
OsErrorStart task failed

◆ uncaught_handler()

void Application::uncaught_handler ( UncaughtHandler handler)

Report any uncaught exceptions to the given interface.

catch_poll_exceptions must be on for the given routine to be called.

Setting the handler to 0 (the default), will just show a simple message in an error box and leave the application running.

Parameters
handlerThe class to handle the uncaught exception or 0 to use the default uncaught exception handling.

◆ unix_file_name_control()

void Application::unix_file_name_control ( int  flags)

Set flags to control the unix file name translation process.

Parameters
flagsSee the unixlib/local.h UnixLib header file RISCOSIFY flags.

◆ unix_file_name_translation() [1/2]

void Application::unix_file_name_translation ( bool  on)

Turn on or off UnixLib's automatic translation of unix style file names.

By default TBX applications have the unix file name translation turned off.

When turned on this uses the default processing.

See also
unix_file_name_control to tune how the details of the translation
Parameters
ontrue to turn on the file name translation, false to turn it off

◆ unix_file_name_translation() [2/2]

bool Application::unix_file_name_translation ( ) const

Check if some unix file name translations are being used.

Returns
true if any unix file name translation is in force.

◆ yield()

bool Application::yield ( )

Allow other applications and events in this application to be run.

Idle commands and timers should be used in preference to this method.

This command will repeatedly poll the WIMP and dispatch messages and events for this application until there are no messages waiting.

Returns
true if the application is still running or false if it should quit
Exceptions
Anyexception generated by any of the events it calls.

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