tbx  0.7.6
Classes | Public Types | Public Member Functions | List of all members
tbx::TaskWindow Class Reference

Class to start a child task in a RISC OS task window. More...

#include <taskwindow.h>

Public Types

enum  Options { ALLOW_CONTROL =1, DISPLAY =2, QUIT =4 }
 Task window run options. More...
 

Public Member Functions

 TaskWindow ()
 Uninitialised task window. More...
 
 TaskWindow (std::string command, std::string name, int wimp_slot=0, unsigned int options=0)
 Construct a task window. More...
 
 ~TaskWindow ()
 Destructor, remove interest in the task window. More...
 
const std::string & command () const
 Get the command run by this task window. More...
 
void command (const std::string &command)
 Set the command run by this task window. More...
 
const std::string & name () const
 Get the task name for the task window. More...
 
void name (const std::string &name)
 Set the name of the task window Changing this will have no effect on a currently running task window. More...
 
int wimp_slot () const
 Get the wimp slot size in KB for the task window.
 
void wimp_slot (int slot)
 Set the wimp slot for the task window Changing this will have no effect on a currently running task window. More...
 
unsigned int options () const
 The options applied when the task window is executed. More...
 
void options (unsigned int new_opts)
 Set the options when the task window is executed Changing this will have no effect on a currently running task window. More...
 
bool running () const
 Check if task window is running. More...
 
unsigned int child_task () const
 task id of the child task. More...
 
void add_started_listener (TaskWindowStartedListener *listener)
 Add listener to detect when the child task is started. More...
 
void remove_started_listener (TaskWindowStartedListener *listener)
 Remove listener to detect when the child task is started. More...
 
void add_finished_listener (TaskWindowFinishedListener *listener)
 Add listener to detect when the child task has finished. More...
 
void remove_finished_listener (TaskWindowFinishedListener *listener)
 Remove listener to detect when the child task has finished. More...
 
void add_output_listener (TaskWindowOutputListener *listener)
 Add listener to capture output from the child task. More...
 
void remove_output_listener (TaskWindowOutputListener *listener)
 Remove listener to detect output from the child task. More...
 
void run ()
 Run the child task. More...
 
void send_input (const char *text, int size=-1)
 Send input to the task window. More...
 
void send_input (const std::string &text)
 Send input to the task window. More...
 
void suspend ()
 Suspend the current child task. More...
 
void resume ()
 Resume the current child task after it has been suspended with a call to suspend. More...
 
void kill ()
 Kill the current child task. More...
 

Detailed Description

Class to start a child task in a RISC OS task window.

Member Enumeration Documentation

◆ Options

Task window run options.

Enumerator
ALLOW_CONTROL 

Allow control characters to be sent to the output.

DISPLAY 

Show the taskwindow output window before any output comes from the task.

QUIT 

Quit the task windo wht the child task finishes.

Constructor & Destructor Documentation

◆ TaskWindow() [1/2]

tbx::TaskWindow::TaskWindow ( )

Uninitialised task window.

At least the command must be set before calling run.

◆ TaskWindow() [2/2]

tbx::TaskWindow::TaskWindow ( std::string  command,
std::string  name,
int  wimp_slot = 0,
unsigned int  options = 0 
)

Construct a task window.

Call the run method to start the task window

Parameters
commandcommand to run
namename of the child task
wimp_slotsize in KB of the wimp slot for the task or 0 to use the Next slot from the RISC OS task manager.
optionsone or more of the Options enum or 0 for none.

◆ ~TaskWindow()

tbx::TaskWindow::~TaskWindow ( )

Destructor, remove interest in the task window.

The destructor does not stop a running task, just removes any listeners.

Member Function Documentation

◆ add_finished_listener()

void tbx::TaskWindow::add_finished_listener ( TaskWindowFinishedListener listener)

Add listener to detect when the child task has finished.

Parameters
listenerlistener to add

◆ add_output_listener()

void tbx::TaskWindow::add_output_listener ( TaskWindowOutputListener listener)

Add listener to capture output from the child task.

One or more of these listeners must be added before the task window is run or the output will go to an external window.

Parameters
listenerlistener to add

◆ add_started_listener()

void tbx::TaskWindow::add_started_listener ( TaskWindowStartedListener listener)

Add listener to detect when the child task is started.

Parameters
listenerlistener to add

◆ child_task()

unsigned int tbx::TaskWindow::child_task ( ) const
inline

task id of the child task.

This is zero until the task has started and zero again once if finishes.

Returns
child task id or 0.

◆ command() [1/2]

const std::string& tbx::TaskWindow::command ( ) const
inline

Get the command run by this task window.

Returns
task window command

◆ command() [2/2]

void tbx::TaskWindow::command ( const std::string &  command)
inline

Set the command run by this task window.

Changing this will have no effect on a currently running task window

Parameters
commandcommand to run

◆ kill()

void tbx::TaskWindow::kill ( )

Kill the current child task.

Exceptions
std::logic_errorif the task has not been started

◆ name() [1/2]

const std::string& tbx::TaskWindow::name ( ) const
inline

Get the task name for the task window.

Returns
the task window name

◆ name() [2/2]

void tbx::TaskWindow::name ( const std::string &  name)
inline

Set the name of the task window Changing this will have no effect on a currently running task window.

Parameters
namethe name for the task window

◆ options() [1/2]

unsigned int tbx::TaskWindow::options ( ) const
inline

The options applied when the task window is executed.

zero or more of the Options enum,

◆ options() [2/2]

void tbx::TaskWindow::options ( unsigned int  new_opts)
inline

Set the options when the task window is executed Changing this will have no effect on a currently running task window.

Parameters
new_optsone or more of the options enum.

◆ remove_finished_listener()

void tbx::TaskWindow::remove_finished_listener ( TaskWindowFinishedListener listener)

Remove listener to detect when the child task has finished.

Parameters
listenerto remove

◆ remove_output_listener()

void tbx::TaskWindow::remove_output_listener ( TaskWindowOutputListener listener)

Remove listener to detect output from the child task.

Parameters
listenerto remove

◆ remove_started_listener()

void tbx::TaskWindow::remove_started_listener ( TaskWindowStartedListener listener)

Remove listener to detect when the child task is started.

Parameters
listenerto remove

◆ resume()

void tbx::TaskWindow::resume ( )

Resume the current child task after it has been suspended with a call to suspend.

Exceptions
std::logic_errorif the task has not been started

◆ run()

void tbx::TaskWindow::run ( )

Run the child task.

At least one listener (of any type) must be added before calling this method for the running() and child_task() field to be updated.

If any listeners are added then output from the task window will be directed to this application. Use the output listener to process this output.

If no listeners are added the task will be run by an external application. As mentioned above in this case this application has no knowledge of the state of the child task.

Exceptions
std::logic_errorif the command to run has not been set, or the command is already running.
tbx::OsErrorcall to start the task failed

◆ running()

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

Check if task window is running.

A task window is running from the time the run function is called until it finishes.

Returns
true if the task window is running

◆ send_input() [1/2]

void tbx::TaskWindow::send_input ( const char *  text,
int  size = -1 
)

Send input to the task window.

You can only send up to 232 chars this way. Use the normal Wimp data transfer to send more characters.

Parameters
textto send.
numberof characters to send or -1 to count the length of a 0 terminated string.
Exceptions
std::logic_errorif you try to send an empty string, a string with too many characters, or to a child task that hasn't started.

◆ send_input() [2/2]

void tbx::TaskWindow::send_input ( const std::string &  text)

Send input to the task window.

You can only send up to 232 chars this way. Use the normal Wimp data transfer to send more characters.

Parameters
textto send.
Exceptions
std::logic_errorif you try to send and empty string, a string with too many characters, or to a child task that hasn't started.

◆ suspend()

void tbx::TaskWindow::suspend ( )

Suspend the current child task.

Exceptions
std::logic_errorif the task has not been started

◆ wimp_slot()

void tbx::TaskWindow::wimp_slot ( int  slot)
inline

Set the wimp slot for the task window Changing this will have no effect on a currently running task window.

Parameters
slotwimp slot size in KB for the task window

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