tbx  0.7.3
application.h
1 /*
2  * tbx RISC OS toolbox library
3  *
4  * Copyright (C) 2010-2014 Alan Buckley All Rights Reserved.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a
7  * copy of this software and associated documentation files (the "Software"),
8  * to deal in the Software without restriction, including without limitation
9  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  * and/or sell copies of the Software, and to permit persons to whom the
11  * Software is furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included
14  * in all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22  * THE SOFTWARE.
23  */
24 
25 #ifndef TBX_APPLICATION_H
26 #define TBX_APPLICATION_H
27 
28 #include "object.h"
29 #include "messagefile.h"
30 
34 namespace tbx
35 {
36  class AutoCreateListener;
37  class Command;
38  class WimpUserMessageListener;
39  class WimpRecordedMessageListener;
40  class WimpAcknowledgeMessageListener;
41  class PreQuitListener;
42  class QuitListener;
43  class ModeChangedListener;
44  class PaletteChangedListener;
45  class SpriteArea;
46  class Timer;
47  class Loader;
48  class PrePollListener;
49  class PostPollListener;
50  class PostEventListener;
51  class UncaughtHandler;
52 
53  namespace res
54  {
55  class ResObject;
56  }
57 
79  {
80  public:
81  static const int MIN_WIMP_VERSION;
82  static const int *NO_MESSAGES;
83  static const int *ALL_MESSAGES;
84  static const int *NO_EVENTS;
85  static const int *ALL_EVENTS;
86 
87  Application(const char *task_directory,
88  int wimp_version = MIN_WIMP_VERSION,
89  const int *deliver_messages = ALL_MESSAGES,
90  const int *deliver_events = ALL_EVENTS);
91 
96  static Application *instance() {return _instance;}
97 
103  SpriteArea *sprite_area() const {return _sprite_area;}
104 
105  void run();
106 
107  void set_autocreate_listener(std::string template_name, AutoCreateListener *listener);
108  void clear_autocreate_listener(std::string template_name);
109 
110  void add_command(int command_id, Command *command);
111  void remove_command(int command_id, Command *command);
112 
113  void add_idle_command(Command *command);
114  void remove_idle_command(Command *command);
115 
116  void add_user_message_listener(int message_id, WimpUserMessageListener *listener);
117  void remove_user_message_listener(int message_id, WimpUserMessageListener *listener);
118  void add_recorded_message_listener(int message_id, WimpRecordedMessageListener *listener);
119  void remove_recorded_message_listener(int message_id, WimpRecordedMessageListener *listener);
122 
123  void add_prequit_listener(PreQuitListener *listener);
125 
126  void add_quit_listener(QuitListener *listener);
127  void remove_quit_listener(QuitListener *listener);
128 
131 
134 
135  void add_timer(int elapsed, Timer *timer);
136  void remove_timer(Timer *timer);
137 
138  void add_opener(Loader *loader, int file_type);
139  void remove_opener(Loader *loader, int file_type);
140 
141 
142  res::ResObject resource(std::string template_name);
143 
147  TaskHandle task_handle() const {return _task_handle;}
148 
149  std::string directory() const;
150 
154  const MessageFile &messages() const {return _messages;}
155 
162  void quit() {_running = false;}
171  bool running() const {return _running;}
172 
173  bool yield();
174 
175  void unix_file_name_translation(bool on);
176  bool unix_file_name_translation() const;
177  void unix_file_name_control(int flags);
178  int unix_file_name_control() const;
179 
180  void catch_poll_exceptions(bool on);
181  void uncaught_handler(UncaughtHandler *handler);
182  void set_pre_poll_listener(PrePollListener *listener);
185 
186  bool owns_window(WindowHandle window_handle, IconHandle icon_handle = 0);
187 
188  int start_wimp_task(std::string command);
189  void os_cli(std::string command);
190 
191  private:
192  bool _running;
193  TaskHandle _task_handle;
194  int _wimp_version;
195  SpriteArea *_sprite_area;
196  MessageFile _messages;
197 
198  static Application *_instance;
199  };
200 
206  inline Application *app() {return Application::instance();}
207 }
208 
209 #endif
210 
211 
void set_pre_poll_listener(PrePollListener *listener)
Set listener to run just before the internal call to Wimp_Poll.
Definition: application.cc:637
void clear_autocreate_listener(std::string template_name)
Clear the autocreate listener for the specified template.
Definition: application.cc:183
void add_prequit_listener(PreQuitListener *listener)
Add a listener for the pre quit message sent (usually) by the desktop.
Definition: application.cc:315
void remove_mode_changed_listener(ModeChangedListener *listener)
Remove mode changed listener.
Definition: application.cc:385
static const int * ALL_EVENTS
Deliver all toolbox events.
Definition: application.h:85
bool yield()
Allow other applications and events in this application to be run.
Definition: application.cc:152
void remove_timer(Timer *timer)
Remove the given timer.
Definition: application.cc:445
bool running() const
Check if application is running.
Definition: application.h:171
void os_cli(std::string command)
Run a command using the RISC OS Command Line interpreter.
Definition: application.cc:724
void add_timer(int elapsed, Timer *timer)
Add a timer to the application that will be called at a regular interval.
Definition: application.cc:435
std::string directory() const
Return the name of the directory that was used to initialised this application.
Definition: application.cc:517
void add_mode_changed_listener(ModeChangedListener *listener)
Listen for changes to the Desktop mode.
Definition: application.cc:375
Listener to handle WimpRecordedMessages (event code 18)
Definition: wimpmessagelistener.h:269
Base class for commands in tbx.
Definition: command.h:36
void set_post_poll_listener(PostPollListener *listener)
Set listener to look at the results of the internal call to Wimp_Poll.
Definition: application.cc:657
Listen for the pre quit message from the desktop.
Definition: prequitlistener.h:109
void remove_palette_changed_listener(PaletteChangedListener *listener)
Remove listener for changes to the desktop palette.
Definition: application.cc:419
void add_acknowledge_message_listener(int message_id, WimpAcknowledgeMessageListener *listener)
Add a listener for the given acknowledge message (event code 18)
Definition: application.cc:290
Class to provide a listener to allow processing before the call to wimp poll.
Definition: posteventlistener.h:47
void add_recorded_message_listener(int message_id, WimpRecordedMessageListener *listener)
Add a listener for the given recorded message (event code 18)
Definition: application.cc:268
void remove_quit_listener(QuitListener *listener)
Remove a quit listener.
Definition: application.cc:358
void add_quit_listener(QuitListener *listener)
Add a listener to process the Quit message.
Definition: application.cc:348
int WindowHandle
Type for WIMP windows handle.
Definition: handles.h:35
void add_idle_command(Command *command)
Add a command to be run when no events are being received from the desktop.
Definition: application.cc:224
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.
Definition: application.cc:79
Class to simplify handling of Quit WIMP message.
Definition: quitlistener.h:45
The main application class.
Definition: application.h:78
int start_wimp_task(std::string command)
Start a child task from this application.
Definition: application.cc:704
Interface to process uncaught exceptions in an application.
Definition: uncaughthandler.h:43
Listener to handle WimpAcnowledgeMessages (event code 19)
Definition: wimpmessagelistener.h:289
TaskHandle task_handle() const
Get WIMP task handle for application.
Definition: application.h:147
Listener to handle WimpUserMessages (event code 17)
Definition: wimpmessagelistener.h:252
void remove_idle_command(Command *command)
Remove a command to be run when no events are being received from the desktop.
Definition: application.cc:235
bool unix_file_name_translation() const
Check if some unix file name translations are being used.
Definition: application.cc:564
void quit()
Quit the application.
Definition: application.h:162
Class to provide a listener to allow processing before the call to wimp poll.
Definition: prepolllistener.h:47
void add_command(int command_id, Command *command)
Add a command to be run for the specified event ID.
Definition: application.cc:200
void add_opener(Loader *loader, int file_type)
Add a file opener.
Definition: application.cc:469
void uncaught_handler(UncaughtHandler *handler)
Report any uncaught exceptions to the given interface.
Definition: application.cc:620
static const int MIN_WIMP_VERSION
Minimum Wimp version TBX supports.
Definition: application.h:81
static const int * NO_MESSAGES
Don't deliver any wimp messages (except QUIT)
Definition: application.h:82
Class to handle file/data loading from the filer or an external application.
Definition: loader.h:179
Class to simplify handling of Quit WIMP message.
Definition: palettechangedlistener.h:44
void add_user_message_listener(int message_id, WimpUserMessageListener *listener)
Add a listener for the given user message (event code 17)
Definition: application.cc:246
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...
Definition: application.cc:173
int unix_file_name_control() const
Get the flags that control the unix file name translation process.
Definition: application.cc:582
static const int * NO_EVENTS
Don't deliver any toolbox event.
Definition: application.h:84
Callback class for a timer.
Definition: timer.h:42
int IconHandle
Type for WIMP icon handle.
Definition: handles.h:37
res::ResObject resource(std::string template_name)
Get a Resource object template from the main toolbox templates.
Definition: application.cc:497
static Application * instance()
Get the application instance.
Definition: application.h:96
void remove_acknowledge_message_listener(int message_id, WimpAcknowledgeMessageListener *listener)
Remove a listener for the given acknowledge message.
Definition: application.cc:301
SpriteArea * sprite_area() const
Get the sprite area.
Definition: application.h:103
static const int * ALL_MESSAGES
Deliver all messages.
Definition: application.h:83
void catch_poll_exceptions(bool on)
Catch any uncaught exceptions thrown during polling and show them in an error box.
Definition: application.cc:602
void add_palette_changed_listener(PaletteChangedListener *listener)
Add listener for changes to desktop palette.
Definition: application.cc:409
void set_post_event_listener(PostEventListener *listener)
Set listener to call after the event processing in TBX.
Definition: application.cc:676
void remove_opener(Loader *loader, int file_type)
Remove a file opener.
Definition: application.cc:483
bool owns_window(WindowHandle window_handle, IconHandle icon_handle=0)
Check if this application owns WIMP window/icon bar icon.
Definition: application.cc:688
Base Listener for auto create events.
Definition: autocreatelistener.h:41
int TaskHandle
Type for a Wimp Task.
Definition: handles.h:56
Base class for a resource object that can be edited.
Definition: resobject.h:52
Class to lookup token translations from a messages file.
Definition: messagefile.h:42
void run()
Run the main polling loop for the application.
Definition: application.cc:130
Class to simplify handling of Quit WIMP message.
Definition: modechangedlistener.h:44
void remove_command(int command_id, Command *command)
Remove a command.
Definition: application.cc:214
Class to provide a listener to allow inspection of the values returned from the Wimp_Poll call...
Definition: postpolllistener.h:42
Application * app()
Get the current application instance.
Definition: application.h:206
A SpriteArea holds zero or more user sprites.
Definition: sprite.h:231
void remove_prequit_listener(PreQuitListener *listener)
Remove a prequit listener.
Definition: application.cc:329
const MessageFile & messages() const
Return the default message file for this application.
Definition: application.h:154
void remove_user_message_listener(int message_id, WimpUserMessageListener *listener)
Remove a listener for the given user message.
Definition: application.cc:257
void remove_recorded_message_listener(int message_id, WimpRecordedMessageListener *listener)
Remove a listener for the given recorded message.
Definition: application.cc:279