tbx
0.7.5
|
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... | |
SpriteArea * | sprite_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 MessageFile & | messages () 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 Application * | instance () |
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. | |
The main application class.
Each application create one Application object, set up any initial commands and listeners and then call the run method.
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.
task_directory | The path to application directory |
wimp_version | The minimum WIMP version supported by the application. Defaults to MIN_WIMP_VERSION (310). |
deliver_messages | Integer array of message IDs that will be delivered to the application. Defaults to deliver all messages. Use:
|
deliver_events | Integer array of Toolbox event IDs that will be delivered to the application. Defaults to deliver all messages. Use:
|
void Application::add_acknowledge_message_listener | ( | int | message_id, |
WimpAcknowledgeMessageListener * | listener | ||
) |
Add a listener for the given acknowledge message (event code 18)
message_id | code to listen for. |
listener | to execute. |
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
command_id | The ID for the command |
command | The command to run. |
void Application::add_idle_command | ( | Command * | command | ) |
Add a command to be run when no events are being received from the desktop.
command | The command to add |
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.
listener | listener for mode change events |
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.
loader | the loader used to open the file |
file_type | the file type for the loader or -2 for any type. |
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.
listener | listener for palette change events |
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.
listener | the prequit listener to add |
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.
listener | quit listener to add |
void Application::add_recorded_message_listener | ( | int | message_id, |
WimpRecordedMessageListener * | listener | ||
) |
Add a listener for the given recorded message (event code 18)
message_id | code to listen for. |
listener | to execute. |
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.
elapsed | number of centiseconds between calls |
timer | - timer to add |
void Application::add_user_message_listener | ( | int | message_id, |
WimpUserMessageListener * | listener | ||
) |
Add a listener for the given user message (event code 17)
message_id | code to listen for. |
listener | to execute. |
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.
on | - true to catch the unhandled exceptions, false to let them through. |
void Application::clear_autocreate_listener | ( | std::string | template_name | ) |
Clear the autocreate listener for the specified template.
template_name | The name of the template. |
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.
|
inlinestatic |
Get the application instance.
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.
command | command to run |
OsError | command failed to run |
bool Application::owns_window | ( | WindowHandle | window_handle, |
IconHandle | icon_handle = 0 |
||
) |
Check if this application owns WIMP window/icon bar icon.
window_handle | WIMP window handle to test or -2 to check an icon bar |
icon_handle | to test (ignored if window handle is not -2) |
|
inline |
void Application::remove_acknowledge_message_listener | ( | int | message_id, |
WimpAcknowledgeMessageListener * | listener | ||
) |
Remove a listener for the given acknowledge message.
message_id | code to remove |
listener | to remove. |
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.
command_id | The command ID used for this command |
command | The command that was originally added |
void Application::remove_idle_command | ( | Command * | command | ) |
Remove a command to be run when no events are being received from the desktop.
command | the command to remove |
void Application::remove_mode_changed_listener | ( | ModeChangedListener * | listener | ) |
Remove mode changed listener.
listener | previously added listener for mode change events |
void Application::remove_opener | ( | Loader * | loader, |
int | file_type | ||
) |
Remove a file opener.
loader | the loader used to open the file to remove |
file_type | the file type for the loader or -2 for any type. |
void Application::remove_palette_changed_listener | ( | PaletteChangedListener * | listener | ) |
Remove listener for changes to the desktop palette.
listener | previously added listener for palette change events |
void Application::remove_prequit_listener | ( | PreQuitListener * | listener | ) |
Remove a prequit listener.
listener | the prequit listener to remove |
void Application::remove_quit_listener | ( | QuitListener * | listener | ) |
Remove a quit listener.
listener | to remove |
void Application::remove_recorded_message_listener | ( | int | message_id, |
WimpRecordedMessageListener * | listener | ||
) |
Remove a listener for the given recorded message.
message_id | code to remove |
listener | to remove. |
void Application::remove_timer | ( | Timer * | timer | ) |
Remove the given timer.
timer | Timer to remove |
void Application::remove_user_message_listener | ( | int | message_id, |
WimpUserMessageListener * | listener | ||
) |
Remove a listener for the given user message.
message_id | code to remove |
listener | to remove. |
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.
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.
|
inline |
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.
template_name | The name of the object template. |
listener | The auto create listener to call when an object for the specified template is called. |
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.
listener | Listener to report the poll results to. Set to 0 to remove the 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.
listener | Listener to report the poll results to. Set to 0 to remove the post 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.
listener | Listener to call prior to wimp poll. Set to 0 to remove the post poll listener. |
|
inline |
Get the sprite area.
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.
command | command line to start the task |
OsError | Start task failed |
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.
handler | The class to handle the uncaught exception or 0 to use the default uncaught exception handling. |
void Application::unix_file_name_control | ( | int | flags | ) |
Set flags to control the unix file name translation process.
flags | See the unixlib/local.h UnixLib header file RISCOSIFY flags. |
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.
on | true to turn on the file name translation, false to turn it off |
bool Application::unix_file_name_translation | ( | ) | const |
Check if some unix file name translations are being used.
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.
Any | exception generated by any of the events it calls. |