home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / vista_1 / !Manual_manual_task < prev    next >
Encoding:
Text File  |  1996-01-25  |  28.8 KB  |  844 lines
  1. <html>
  2. <title>Task</title>
  3. <h1>Task</h1>
  4.  
  5. <h2>Synposis</h2>
  6. <p>
  7. <pre>
  8.       class Task
  9.          {
  10.          public:
  11.             enum <a href="file:task#events">events</a>
  12.             enum <a href="file:task#buttons">buttons</a>
  13.             enum <a href="file:task#messages">Messages</a>
  14.             <a href="file:task#ct1">Task</a> (char *taskname, char *applname, char *spritename, 
  15.                   char *iconmenu = NULL, int pri = 0, int position = -1,
  16.                   int wimp_version = 200, int *message_list = 0) ;
  17.             <a href="file:task#ct2">Task</a> (char *taskname, char *applname,int wimp_version = 310, int *message_list = 0) ;
  18.             <a href="file:task#ct3">Task</a> (char *taskname, char *applname, Icon *iconbar, 
  19.                   char *iconmenu = NULL, int pri = 0, int position = -1,
  20.                   int wimp_version = 200, int *message_list = 0) ;
  21.             virtual <a href="file:task#dt">~Task</a>() ;
  22.             void <a href="file:task#set_mask">set_mask</a>(int m) ;
  23.             void <a href="file:task#run">run</a>() ;
  24.             void <a href="file:task#exit">exit</a>(int status = 0) ;
  25.             void <a href="file:task#spawn">spawn</a>(char *coomand...) ;
  26.             void <a href="file:task#sleep1">sleep</a> (ThreadResource *, int pri = THREAD_BASE_PRIORITY) ;
  27.             void <a href="file:task#sleep2">sleep</a> (int time) ;
  28.             void <a href="file:task#yield">yield</a>() ;
  29.             void <a href="file:task#add_window">add_window</a> (Window *w) ;
  30.             void <a href="file:task#remove_window">remove_window</a> (Window *w) ;
  31.             void <a href="file:task#delete_window">delete_window</a> (Window *w) ;
  32.             void <a href="file:task#delete_deferred">delete_deferred</a> (DeferredDelete *) ;
  33.             Window *<a href="file:task#find_window">find_window</a> (int handle) ;
  34.             void *<a href="file:task#find_template">find_template</a> (char *name) ;
  35.             Menu *<a href="file:task#find_menu">find_menu</a> (char *name) ;
  36.             virtual char *<a href="file:task#get_iconbar_menu">get_iconbar_menu</a> (int icon) ;
  37.             virtual void <a href="file:task#menu">menu</a> (MenuItem items[]) ;
  38.             virtual void <a href="file:task#click">click</a> (int x, int y, int buttons, int icon) ;
  39.             char *<a href="file:task#lookup">lookup</a> (char *token) ;
  40.             void <a href="file:task#send_message">send_message</a> (events event, int action, int &task, 
  41.                                int &my_ref, int your_ref, int data_length, 
  42.                                void *data, int icon = 0)  ;
  43.             void <a href="file:task#print">print</a> (char *format,...) ;
  44.             virtual void <a href="file:task#pre_menu">pre_menu</a> (Menu *menu) ;
  45.             void <a href="file:task#register_drag">register_drag</a> (Window *dragger, int id) ;
  46.             void <a href="file:task#register_object_drag">register_object_drag</a> (Object *dragger, int id) ;
  47.             void <a href="file:task#add_receiver">add_receiver</a> (Channel *channel, int message) ;
  48.             void <a href="file:task#remove_receiver">remove_receiver</a> (Channel *channel, int message) ;
  49.             receiver *<a href="file:task#find_receiver">find_receiver</a> (int message, int your_ref) ;
  50.             int <a href="file:task#open_font">open_font</a> (char *name, int xisize, int ysize) ;
  51.             void <a href="file:task#close_font">close_font</a> (int handle) ;
  52.             void <a href="file:task#enter_critical">enter_critical </a>() ;
  53.             void <a href="file:task#exit_critical">exit_critical</a>() ;
  54.             void *<a href="file:task#find_sprite">find_sprite</a> (char *name) ;
  55.             virtual void <a href="file:task#poll_word_non_zero">poll_word_non_zero</a> (int *poll_word, int contents) ;
  56.             void <a href="file:task#set_menu">set_menu</a> (Menu *menu, Icon *icon) ;
  57.             void <a href="file:task#set_menu">set_menu</a> (Menu *menu, Object *object) ;
  58.             void <a href="file:task#set_menu">set_menu</a> (Menu *menu, Window *window) ;            
  59.             virtual char *<a href="file:task#help">help</a> (int mx, int my, int button, int window, int icon) ;
  60.             void <a href="file:task#show_threads">show_threads</a>() ;
  61.             events <a href="file:task#last_event">last_event</a> ;
  62.             int <a href="file:task#last_event_data">last_event_data</a>[256 / sizeof (int)] ;
  63.             int <a href="file:task#xeigfactor">xeigfactor</a> ;
  64.             int <a href="file:task#yeigfactor">yeigfactor</a> ;
  65.             Icon *<a href="file:task#iconbar_icon">iconbar_icon</a> ;
  66.             DebugWin *<a href="file:task#debug">debug</a> ;
  67.             char *<a href="file:task#program">program</a> ;
  68.             int <a href="file:task#handle">handle</a> ;
  69.             char <a href="file:task#country">country</a>[50] ;
  70.          } ;
  71. </pre>
  72.  
  73. <h2>Description</h2>
  74.  
  75. This class represents a WIMP task.  A task is a program which is running
  76. under the control of the RISC OS WIMP module.  The facilities provided
  77. by this class allow full control over the behaviour of the WIMP task.
  78. <p>
  79. Although this is not an abstract class, it is designed to be used as
  80. a base class for another class which provides some of the application
  81. specific facilities.  If there are no facilities which cannot be provided
  82. by the default action of the class then the Task class may be used on
  83. its own.
  84. <p>
  85. If a class is derived from this class it can provide all or some of the
  86. following facilities by supplying an appropriate function which will
  87. replace the default behaviour of the Task class.
  88. <p>
  89. <ul>
  90. <li>Menu creation
  91. <p>
  92. The derived class will be given a chance to provide a menu for an iconbar
  93. click.  The function to provide is 'get_iconbar_menu'.
  94. <li>Menu modification
  95. <p>   
  96. The derived class is given the chance to modify any of the entries
  97. of a menu before it is displayed.  The function to provide is 'pre_menu'
  98. <li>Menu clicks
  99. <p>   
  100. The derived class is informed of clicks on the iconbar menu by a call
  101. to the function 'menu'.
  102. <li>Iconbar clicks
  103. <p>
  104. The derived class is informed of clicks on the iconbar icon by a call
  105. to the function 'click'.
  106. </ul>   
  107. <p>
  108. The derived class should also contain the definitions for the windows used
  109. in the task.  The constructor for the derived class should create all the
  110. windows (but not necessarily open them) and assign these to variables
  111. within the derived class.  The destructor should delete these windows.
  112. <p>
  113. If the mouse is clicked over an icon, object or window, then that icon,
  114. object or window gets priority over the task when dealing with the click.
  115. This allows a window to set up its own menu and click handlicg code.
  116.  
  117. <p>
  118.  
  119. <h2>Example</h2>
  120.  
  121. This example derives a class called 'Game' from the Task class.  It provides
  122. a default menu for the iconbar, and responds to clicks on that menu.  It
  123. also responds to iconbar icon clicks.  The game consists of one main
  124. window.  The iconbar menu contains 2 entries: 'New game' for starting
  125. a new game, and 'Quit'.
  126. <p>
  127. The Window class is described later.
  128. <pre>
  129.  
  130. //
  131. // game example 1
  132. //
  133.  
  134.  
  135. #include "Vista:vista.h"
  136.  
  137. class Game : public Task
  138.    {
  139.    public:
  140.       Game() ;                                         // construct the task
  141.       ~Game() ;                                        // destruct it
  142.       void menu (MenuItem items[]) ;                   // menu click
  143.       void click (int x, int y, int button, int icon) ;// iconbar click   
  144.  
  145.       void start() ;                                   // start a new game
  146.       
  147.       enum MenuEntries                                 // menu entries
  148.          {
  149.          NEWGAME,                                      // New game
  150.          QUIT                                          // Quit
  151.          } ;
  152.          
  153.    private:
  154.       Window *main_window ;                            // my main window
  155.    } ;
  156.  
  157.  
  158. Game::Game() 
  159.    : Task ("New game", "Game", "!Game", "main_menu")
  160.    {
  161.    main_window = new Window (this, "main") ;
  162.    }
  163.  
  164. Game::~Game()
  165.    {
  166.    delete main_window ;
  167.    }   
  168.  
  169. void Game::click (int x, int y, int button, int icon)
  170.    {
  171.    if (button & Task::BLEFT)
  172.       main_window->do_open() ;
  173.    }
  174.    
  175. void Game::menu (MenuItem items[])
  176.    {
  177.    switch (items[0])
  178.       {
  179.       case NEWGAME:
  180.          start() ;
  181.          break ;
  182.       case QUIT:   
  183.          exit() ;
  184.          break ;
  185.       }
  186.    }
  187.  
  188. Game *game ;
  189.  
  190. main()
  191.    {
  192.    game = new Game() ;
  193.    game->run() ;
  194.    }
  195.    
  196. </pre>
  197.   
  198. <h2>Members</h2>
  199.  
  200. This section describes the main interface functions and data of the Task 
  201. class.  There are other members which are used internally and are not
  202. of interest here.
  203.  
  204. <p>
  205. <a name="events"></a>
  206. <h3>Task::events</h3>
  207.  
  208. This is an enumeration containing the various event codes returned to the
  209. task from Wimp_Poll.  Each code begins with the letter 'E' and is followed
  210. by a an abbreviation for the event (eg EPTRLEAVE - pointer leaving event)
  211.    
  212. <p>   
  213. <a name="buttons"></a>
  214. <h3>Task::buttons</h3>
  215.  
  216. This is an enumeration containing constants for the button states returned
  217. by the OS.  Each starts with the letter 'B'.  Example: BDRAGLEFT - left drag
  218. button type)
  219.  
  220.  
  221. <p>   
  222. <a name="messages"></a>
  223.  
  224. <h3>Task::Messages</h3>
  225.  
  226. An enumeration for the various known message codes.  The names are as
  227. defined in the PRMs and most start with the word 'Message_'. Example:
  228. Message_DataLoadAck.
  229.  
  230.  
  231. <p>   
  232. <a name="ct1"></a>
  233.  
  234. <h3>Task::Task (char *taskname, 
  235.                   char *applname, 
  236.                   char *spritename, 
  237.                   char *iconmenu,
  238.                   int pri,
  239.                   int position,
  240.                   int wimp_version,
  241.                   int *message_list)</h3>
  242.  
  243. This constructor makes a task class suitable for running under RISC OS that
  244. has an icon on the icon bar.  The parameters are:
  245. <p>
  246. <pre>
  247.  
  248.    taskname:       The name which appears on the Task Display window
  249.    applname:       The name of the application.  This is used to construct
  250.                    the application directory variables by appending $Dir (
  251.                    and possibly $Path)
  252.    spritename:     The name of the sprite in the WIMP sprite pool which will
  253.                    be displayed on the icon bar
  254.    iconmenu:       The name of a menu which will be used if the user clicks
  255.                    'menu' over the iconbar icon.  This is optional and
  256.                    if it is omitted then no menu will be supplied by
  257.                    default
  258.    pri:            The priority for the iconbar icon
  259.    position:       Position information for the iconbar icon
  260.    wimp_version:   The version of the WIMP under which the task is
  261.                    designed to run.  This determines the behavious of
  262.                    the task with respect to the various WIMP versions.  The
  263.                    value is as specified in the PRM.
  264.    message_list:   This is a pointer to a list of words terminated
  265.                    by a word of 0.  It is used in versions of the WIMP
  266.                    greater than or equal to 310 and contains a list
  267.                    of message ids meaningful to the task.
  268.  
  269. </pre>
  270.  
  271. By creating a class using this constructor it is prepared to run as a full
  272. task under RISC OS.
  273. <pre>
  274.  
  275. Example: 
  276.  
  277. Task *game = new Task ("Wonderful game", "Game", "game", "game_menu") ;
  278.  
  279. </pre>
  280. This is the most common Task constructor of the 3 available.  It is used
  281. when the task is a 'normal' WIMP task with an icon on the icon bar.  The
  282. last 4 parameters are used to control the advanced aspects of
  283. task and icon creation detailed in the PRMs.
  284.  
  285.  
  286. <p>   
  287. <a name="ct2"></a>
  288.  
  289. <h3>Task::Task (char *taskname, 
  290.                   char *applname, 
  291.                   int wimp_version,
  292.                   int *message_list)</h3>
  293.  
  294. This constructor makes a task class suitable for running under RISC OS that
  295. does not have an icon on the icon bar.  The parameters are:
  296. <pre>
  297.  
  298.    taskname:       The name which appears on the Task Display window
  299.    applname:       The name of the application.  This is used to construct
  300.                    the application directory variables by appending $Dir (
  301.                    and possibly $Path)
  302.    wimp_version:   The version of the WIMP under which the task is
  303.                    designed to run.  This determines the behavious of
  304.                    the task with respect to the various WIMP versions.  The
  305.                    value is as specified in the PRM.
  306.    message_list:   This is a pointer to a list of words terminated
  307.                    by a word of 0.  It is used in versions of the WIMP
  308.                    greater than or equal to 310 and contains a list
  309.                    of message ids meaningful to the task.
  310.  
  311. Example: 
  312.  
  313. Task *game = new Task ("Silly clock", "Clock") ;
  314.  
  315. </pre>
  316. This constructor creates a task which does not have an icon on the
  317. icon bar.
  318. <p>   
  319. <a name="ct3"></a>
  320.  
  321. <h3>Task::Task (char *taskname, 
  322.                   char *applname, 
  323.                   Icon *iconbar, 
  324.                   char *iconmenu,
  325.                   int pri,
  326.                   int position,
  327.                   int wimp_version,
  328.                   int *message_list)</h3>
  329.  
  330. This constructor makes a task class suitable for running under RISC OS that
  331. has an icon on the icon bar.  The parameters are:
  332. <pre>
  333.  
  334.    taskname:       The name which appears on the Task Display window
  335.    applname:       The name of the application.  This is used to construct
  336.                    the application directory variables by appending $Dir (
  337.                    and possibly $Path)
  338.    iconbar:        A pointer to an Icon object to use as the icon bar icon.
  339.    iconmenu:       The name of a menu which will be used if the user clicks
  340.                    'menu' over the iconbar icon.  This is optional and
  341.                    if it is omitted then no menu will be supplied by
  342.                    default
  343.    pri:            The priority for the iconbar icon
  344.    position:       Position information for the iconbar icon
  345.    wimp_version:   The version of the WIMP under which the task is
  346.                    designed to run.  This determines the behavious of
  347.                    the task with respect to the various WIMP versions.  The
  348.                    value is as specified in the PRM.
  349.    message_list:   This is a pointer to a list of words terminated
  350.                    by a word of 0.  It is used in versions of the WIMP
  351.                    greater than or equal to 310 and contains a list
  352.                    of message ids meaningful to the task.
  353.  
  354.  
  355. </pre>
  356.  
  357. This constructor is similar to 3.1.4 except that it takes a pointer to
  358. a preexisting Icon object.  This is usefiul if you need to access the
  359. icon to modify it (like the Alarm application supplied with the computer)
  360.  
  361. <p>   
  362. <a name="dt"></a>
  363.  
  364. <h3>Task::~Task()</h3>
  365.  
  366. This is the class destructor.  It is called when the class goes out of
  367. scope or is deleted.  It simply closes all the open windows and fonts.
  368.  
  369.  
  370. <p>   
  371. <a name="set_mask"></a>
  372.  
  373. <h3>Task::set_mask (int mask)</h3>
  374.  
  375. This function sets the polling mask for Wimp_Poll to the value given.  The
  376. polling mask is used to prevent certain events being delivered to the task.
  377. For full details, see the PRM.
  378. <p>
  379. Example:
  380. <pre>
  381.  
  382. game->set_mask (1 << ENULL) ;   // disable NULL events
  383.  
  384. </pre>
  385.  
  386. NB. By default, NULL events are not delivered to the task except
  387. when there are preempted threads running.
  388.  
  389. <p>   
  390. <a name="run"></a>
  391. <h3>Task::run()</h3>
  392.  
  393. This function sets the task running.  It will not return until the task
  394. has been stopped by a call to the 'stop' function (see below).  The task
  395. runs by entering a loop calling Wimp_Poll and acting on the events passed
  396. to it.
  397.  
  398.  
  399. <p>   
  400. <a name="exit"></a>
  401. <h3>Task::exit (int status = 0)</h3>
  402.  
  403. This function causes the task to exit immediately with the status given.
  404. The default value for status is 0.  It results in a call to the Shared
  405. C Library function 'exit'.
  406.  
  407. <p>   
  408. <a name="spawn"></a>
  409. <h3>Task::spawn (char *command...</h3>
  410.  
  411. This function is used to create a new task which runs the command constructed
  412. from the printf style format string and a list of arguments.  This function
  413. <b>must</b> be used to spawn a new task and not the SWI Wimp_StartTask
  414. as it is necessary to stop the threads before wht WIMP switches out the
  415. task.
  416. <p>
  417. For example, this command will open a filer window at the coordinates
  418. (x,y) and showing small icons.
  419. <pre>
  420.  
  421. task->spawn ("filer_opendir %s %d %d -si",dirname, x, y) ;
  422.  
  423. </pre>
  424.  
  425. <p>   
  426. <a name="sleep1"></a>
  427. <h3>Task::sleep (ThreadResource *, int pri = THREAD_BASE_PRIORITY)</h3>
  428.  
  429. This function causes the current thread to sleep until the given
  430. resource is available.  The most common use of this is to sleep
  431. until another thread has terminated.  See the section on Threads
  432. for more detail on Threads and Resources.
  433.  
  434. <p>   
  435. <a name="sleep2"></a>
  436. <h3> Task::sleep (int time)</h3>
  437.  
  438. This causes the current thread to sleep for a specified number of
  439. centiseconds.  The purpose is to cause a delay in the processing
  440. of the thread.  It could be used to implement a timing loop for,
  441. say, a clock.
  442.  
  443. <p>   
  444. <a name="yield"></a>
  445. <h3> Task::yield()</h3>
  446.  
  447. This function causes the current thread to give up the processor
  448. in favour of the next available thread.  By judicious use of the
  449. yield function when there is nothing for a thread to do, the
  450. performance of the task can be maintained.  You should never
  451. put a thread into a tight loop as this causes a noticible 
  452. degradation in performance of the machine.  See the section
  453. on Threads for more detail.
  454.  
  455.  
  456. <p>   
  457. <a name="add_window"></a>
  458. <h3> Task::add_window (Window *w)</h3>
  459.  
  460. This function adds a window to the list of known windows in the task.  When
  461. a window is known to a task, the task can invoke the appropriate virtual
  462. functions when certain events task place.  All windows must be added to the
  463. task in order for Vista to operate correctly.  This is done automatically
  464. by the Window constructors.
  465.  
  466.  
  467.  
  468. <p>   
  469. <a name="remove_window"></a>
  470. <h3> Task::remove_window (Window *w)</h3>
  471.  
  472. This function removes a window from a task.  It must be called when a
  473. window is deleted and is done automatically by the Window destructor.
  474.  
  475. <p>   
  476. <a name="delete_window"></a>
  477. <h3> Task::delete_window (Window *w)</h3>
  478.  
  479. One of the inherent problems with object based event processing
  480. systems is how to delete the windows.  Usually, the program
  481. knows to delete a window from a user action such as a mouse
  482. click.  However, if the window is deleted from here, the
  483. system will crash beacuse you are actually 'in' the window
  484. you are deleting.  This function is provided to allow the
  485. deletion of windows from within the window itself.  The actual
  486. deletion does not occur until the thread has finished.
  487.  
  488.  
  489. <p>   
  490. <a name="delete_deferred"></a>
  491. <h3> Task::delete_deferred (DeferredDelete *)</h3>
  492.  
  493. This function is used to signify the deletion of an object
  494. that cannot be deleted right away.  Examples of such objects
  495. are Windows and Threads which cannot delete themselves.  An`
  496. object registered by use of this function will be deleted when
  497. the thread which caused the deletion has terminated.
  498.  
  499. <p>   
  500. <a name="find_window"></a>
  501. <h3> Task::find_window (int handle)</h3>
  502.  
  503. This function searches the list of known windows for that whose WIMP handle
  504. is given.  The result is NULL if the window doesn't exist, otherwise
  505. a pointer to the Window found is returned.
  506.  
  507.  
  508.  
  509. <p>   
  510. <a name="find_template"></a>
  511. <h3> Task::find_template (char *name)</h3>
  512.  
  513. This function is used internally by the task to find the template associated
  514. with a window upon window creation.  It searches the list of known 
  515. templates for the name given.
  516.  
  517.  
  518.  
  519. <p>   
  520. <a name="find_menu"></a>
  521. <h3> Task::find_menu(char *name)</h3>
  522.  
  523. This function is used to find the Menu class associated with a given
  524. name.  If returns NULL if the menu wasn't found, or a pointer to a menu
  525. otherwise.
  526.  
  527.  
  528.  
  529. <p>   
  530. <a name="get_iconbar_menu"></a>
  531. <h3> Task::get_iconbar_menu (int icon)</h3>
  532.  
  533. This virtual function is called when a task has not been given a default
  534. iconbar menu (in the Task constructor).  The idea is that the user should
  535. derive a new class from the Task class which will provide this function
  536. if the iconbar menu is not known at task startup time.  It gives the
  537. flexibility for dynamic iconbar menus.
  538.  
  539.  
  540.  
  541. <p>   
  542. <a name="menu"></a>
  543. <h3> Task::menu (MenuItems items[])</h3>
  544.  
  545. This virtual function must be provided by a derived class and is called
  546. when the user selects a menu option from the iconbar menu (either default
  547. or user provided).  It is passes an array of MenuItem classes which 
  548. may be used by the function to determine the appropriate action.
  549.  
  550.  
  551.  
  552. <p>   
  553. <a name="click"></a>
  554. <h3> Task::click (int x, int y, int buttons, int icon)</h3>
  555.  
  556. This virtual function must be provided by a derived class and is called 
  557. when the user clicks the mouse buttons (either Select or Adjust) which is
  558. not over a window in a task.  This will happen when the user clicks
  559. over the iconbar icon.  The parameters are those returned to the
  560. task from the WIMP (see the PRM)
  561.  
  562.  
  563.  
  564. <p>   
  565. <a name="lookup"></a>
  566. <h3> Task::lookup (char *token)</h3>
  567.  
  568. This function is used to provide a translation for a message token.  The
  569. task maintains a set of messages internally (from the Messages file) and
  570. this function does a lookup on this list.  It returns the text associated
  571. with the token if it exists, otherwise it returns the token it was given.
  572.  
  573.  
  574.  
  575. <p>   
  576. <a name="send_message"></a>
  577. <h3>Task::send_message (events event, int action, 
  578.                            int &task, int &my_ref, 
  579.                            int your_ref, int data_length, 
  580.                            void *data, int icon = 0)</h3>
  581.  
  582. This function is used to send a message to another task.  It simply
  583. calls the WIMP routine Wimp_SendMessage.
  584.  
  585.  
  586.  
  587. <p>   
  588. <a name="print"></a>
  589. <h3> Task::print (char *format ...)</h3>
  590.  
  591. This function takes a printf style format string and creates an error
  592. window on the screen containing the text (and parameters) created
  593. from the format string.  The function will return when the user
  594. clicks OK in the error box.  It is useful for debugging and presenting
  595. errors on the screen.
  596.  
  597.  
  598.  
  599. <p>   
  600. <a name="pre_menu"></a>
  601. <h3> Task::pre_menu (Menu *menu)</h3>
  602.  
  603. This virtual function may be provided by a derived class and is called when
  604. the user clicks menu over the iconbar menu.  It gives the derived class
  605. a chance to change any of the menu entries before the menu appears on
  606. the screen.  It is passed a pointer to the Menu class which will be
  607. displayed.  The derived class can then do anything to that menu (except
  608. delete it of course), such as printing to an entry or changing the number
  609. of entries.
  610.  
  611.  
  612.  
  613. <p>   
  614. <a name="register_drag"></a>
  615. <h3> Task::register_drag (Window *dragger, int id)</h3>
  616.  
  617. This function is used to register the fact that a window has caused a
  618. drag to occur.  The task will inform the window when the drag has completed.
  619. The 'id' parameter passed is passed on to the window when the drag completes
  620. so that the window can determine the origin of the drag.
  621.  
  622.  
  623. <p>   
  624. <a name="register_object_drag"></a>
  625. <h3> Task::register_object_drag (Object *dragger, int id)</h3>
  626.  
  627. This is similar to the register_drag function ecxept the drag
  628. events are passed to an Object inside a window instead of a
  629. window itself.
  630.  
  631.  
  632. <p>   
  633. <a name="add_receiver"></a>
  634. <h3> Task::add_receiver (Channel *channel, int message)</h3>
  635.  
  636. This function is used to inform the task that a particular Channel class
  637. is interested in the any messages whose id is 'message'.  The channel
  638. will be informed when any such message arrives at the task.
  639.  
  640.  
  641.  
  642. <p>   
  643. <a name="remove_receiver"></a>
  644. <h3> Task::remove_receiver (Channel *channel, int message)</h3>
  645.  
  646. This function is used to remove a Channel's interest in receiving message
  647. of the given id.  It should be called when a Channel is being deleted.
  648.  
  649.  
  650. <p>   
  651. <a name="open_font"></a>
  652. <h3> Task::open_font (char *name, int xsize, int ysize)</h3>
  653.  
  654. This function opens a font (using Font_FindFont) and returns a handle to the
  655. caller.  
  656.  
  657.  
  658.  
  659. <p>   
  660. <a name="close_font"></a>
  661. <h3> Task::close_font(int handle)</h3>
  662.  
  663. This function closes the font whose handle is given as the parameter.
  664.  
  665.  
  666.  
  667. <p>   
  668. <a name="enter_critical"></a>
  669. <h3> Task::enter_critical()</h3>
  670.  
  671. This function must be called when it is important that a thread must not be
  672. interrupted.  It is used in situations like the ubiquitous GetRectangle
  673. loop to redraw a window where the thread must complete its task before
  674. being interrupted.  By calling this function you are stopping all the
  675. threads except the calling thread.
  676.  
  677.  
  678. <p>   
  679. <a name="exit_critical"></a>
  680. <h3> Task::exit_critical()</h3>
  681.  
  682. This function is the opposite of enter_critical as it restarts the
  683. stopped threads.
  684.  
  685.  
  686. <p>   
  687. <a name="find_sprite"></a>
  688. <h3> Task::find_sprite(char *name)</h3>
  689.  
  690. This utility function can be used to find the address of a sprite 
  691. in the WIMP sprite pool.  This facility seems to have been omitted from
  692. the operating system.  It returns the address of the sprite found.
  693.  
  694.  
  695. <p>   
  696. <a name="poll_word_non_zero"></a>
  697. <h3> Task::poll_word_non_zero(int *poll_word, int contents)</h3>
  698.  
  699. This is called when the event POLLWORDNONZERO is returned from
  700. Wimp_Poll.  See the PRM for more details.
  701.  
  702. <p>   
  703. <a name="set_menu"></a>
  704. <h3> Task::set_menu (Menu *menu, Icon *icon),set_menu (Menu *menu, Object *object),
  705.            set_menu (Menu *menu, Window *window) </h3>
  706.  
  707. These three functions are used to set up the task so that a menu selection
  708. is routed to the appropriate icon, object or window.  When the user clicks
  709. 'menu' over an icon, object or window the task is normally set up to deal
  710. with the menu selection.  However, if a menu is created (using display_menu)
  711. from an event other than a menu click, the task needs to be informed of this
  712. fact so that it can distribute the selection.  So, if you display a menu
  713. from something other than a menu click (say a select click), then one
  714. of these functions must be called.
  715.  
  716. <p>
  717. <a name="help"></a>
  718. <h3 Task::help (int mx, int my, int buttons, int window, int icon) </h3>
  719.  
  720. This function is called when the task is being asked for help.  It is called
  721. when none of the windows are prepared to help or when the mouse is not
  722. over a window owned by the task (the Iconbar icon say).
  723. <p>
  724. The function should return a pointer to the help string to be
  725. printed by the interactive help application.  If no help
  726. is available, just return NULL.  This is a virtual function
  727. so each derived class may provide its own help by providing
  728. this function.
  729. <p>
  730. The parameters are as passed in the WIMP HelpRequest message.  See the
  731. PRM for details.
  732.  
  733. <p>
  734. <a name="show_threads"></a>
  735. <h3 Task::show_threads() </h3>
  736.  
  737. This function writes a listing of the current threads into the debug
  738. window (if a template called 'debug' exists in the templates file).
  739. The listing shows each of the threads with the following information:
  740. <p>
  741. <ul>
  742. <li>NAME: The name of the thread
  743. <li>STATE: The current thread state.  States are:
  744.    <ol>
  745.    <li>IDLE: The thread is not doing anything
  746.    <li>READY: The thread is ready to run and will be scheduled soon
  747.    <li>RUNNING: The thread is the currently running thread
  748.    <li>SLEEPING: The thread is waiting for a resource to become available
  749.    <li>STOPPED: The thread has been stopped and can be resumed
  750.    <li>DEAD: The thread is dead and cannot be resumed
  751.    </ol>
  752. <li>PRI: The current priority of the thread.  The lower the number, the
  753. higher the priority
  754. <li>BPRI: The base priority of the thread
  755. <li>CPU: The number of centiseconds of (decayed) cputime
  756. <li>ACCCPU: The accumulated number of centiseconds for the thread (not meaningful for 
  757. the "main" thread)
  758. </ul>
  759.  
  760. <p>   
  761. <a name="last_event"></a>
  762. <h3> Task::last_event</h3>
  763.  
  764. This variable hold the code of the last event to be passed to the task
  765.  
  766.  
  767.  
  768. <p>   
  769. <a name="last_event_data"></a>
  770. <h3> Task::last_event_data</h3>
  771.  
  772. This variable is a buffer holding the event data for the last event passed
  773. to the task.
  774.  
  775.  
  776. <p>   
  777. <a name="xeigfactor"></a>
  778. <h3> Task::xeigfactor</h3>
  779.  
  780. This is the number of places an X coordinate must be shifted left in order
  781. to calculate an OS unit from a pixel unit.  See the PRM.
  782.  
  783.  
  784. <p>   
  785. <a name="yeigfactor"></a>
  786. <h3> Task::yeigfactor</h3>
  787.  
  788. This is the Y equivalent of xeigfactor.
  789.  
  790.  
  791.  
  792. <p>   
  793. <a name="iconbar_icon"></a>
  794. <h3> Task::iconbar_icon</h3>
  795.  
  796. This is a pointer to the Icon used to hold the icon on the iconbar.
  797. It can be used by the program to modify the icon.
  798.  
  799.  
  800. <p>   
  801. <a name="debug"></a>
  802. <h3> Task::debug</h3>
  803.  
  804. This is a pointer to a debug output window.  It may be used by a task to
  805. write debug information to a window using a printf style call.  The
  806. call 'task->debug->print()' may be used to print to the window.  It will
  807. open on the screen if it is not open or has been closed.
  808.  
  809. Another method of writing to the debug window is by using the 'dprintf'
  810. function.  This takes the same parameters as printf and is at global
  811. scope so there is no need to know the task before calling it.
  812.  
  813. The debug facility requires the existence of a window called 'debug'
  814. within the template file.
  815.  
  816.  
  817.  
  818. <p>   
  819. <a name="program"></a>
  820. <h3> Task::program</h3>
  821.  
  822. This variable is the name of the current program.  It is the application
  823. name passed to the contstructor.
  824.  
  825.  
  826.  
  827. <p>   
  828. <a name="handle"></a>
  829. <h3> Task::handle</h3>
  830.  
  831. This is the WIMP handle given to the task when it initialises.  It should
  832. not be modified.
  833.  
  834.  
  835.  
  836. <p>   
  837. <a name="country"></a>
  838. <h3> Task::country</h3>
  839.  
  840. This is the name of the country in which the resources may be found.  It
  841. is read from the 'Country' file in the 'Resources' directory.
  842.  
  843.  
  844.