home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / programming / removeda / !RemoveDa / !TaskInfo < prev    next >
Text File  |  1998-08-19  |  19KB  |  449 lines
  1.                       ________________________________
  2.  
  3.                          TaskInfo 1.06 (20 Jun 1998)
  4.                       ________________________________
  5.  
  6.  
  7.                           Written by Jonathan Brady
  8.                          for Sliced Software, © 1998
  9.  
  10. _____________________________________________________________________________
  11.  
  12.  Introduction
  13.  
  14.   TaskInfo is a utility for adding to the taskmanager menu, and for supplying
  15. interactive help for those menus.  It can also be used to change the name of
  16. a task as given in the task manager display.
  17. _____________________________________________________________________________
  18.  
  19.  Usage
  20.  
  21.   Load TaskInfo by double-clicking on it's icon in a filer window.  Once
  22. loaded it will sit in the background waiting for you to click the menu button
  23. in the task display window, this starts the chain of wimp messages and
  24. service calls off.
  25.  
  26. Note 1 : All pointers used should be to locations in the RMA or a dynamic
  27. areas which is readable in user mode (protection level 0 or 1).  This is
  28. mentioned further down the help file but some people seem to forget.
  29.  
  30. Note 2 : All task handles should only rely on the 2 LSB of the word i.e.
  31. (Task handle AND &FFFF).
  32.  
  33. Note 3 : You should ensure that version 1.06 is loaded with any program,
  34. versions prior to 1.04 had several bugs in them, and versions 1.04 and 1.05
  35. would not work on the RISC OS 3.5 and 3.6 taskmanagers.
  36.  
  37. Wimp Messages
  38. =============
  39.  
  40.   There are three wimp messages issued by this utility in an effort to
  41. provide the menu system :
  42.  
  43. Message_TaskInfoOpen (&4F6C0)
  44. -------------------- --------
  45.  
  46.         r1+20 Call type
  47.         r1+24 Item type
  48.         r1+28 Item number (task handle, dynamic area number)
  49.         r1+32 Pointer to menu flags of main item in taskmanager menu
  50.         r1+36 Pointer to string that will be displayed in menu
  51.         r1+40 Pointer to name of item (tasks and dynamic areas only)
  52.  
  53.   There are three possible call types :
  54.  
  55.         0 - PreGlobal  :  Global call to all tasks, used to replace menus
  56.                          provided by a task, and for all other item types.
  57.         1 - Task       :  Direct call to task for menus (only available for
  58.                          tasks, and only for task whose name the menu is
  59.                          opened over, therefore no need to check task handle
  60.                          just whether call type is 1)
  61.         2 - PostGlobal :  Global call to all tasks if task does not respond
  62.                  to call type 1, used to provide menu for tasks which
  63.                  don't do themselves, so if a later version of the
  64.                  task does that will be used instead.
  65.  
  66.   Call types 1 and 2 are only issued when a task name is clicked over in the
  67. display, they are issued in sequence, and the sequence stops when a reply is
  68. received.
  69.  
  70.   Item numbers are as follows :
  71.  
  72.          1      Application tasks header
  73.          2      System memory allocation header
  74.          3      Module tasks header
  75.          4      Dynamic area header
  76.          5      Tasks and module tasks
  77.          8      Wimpslot next
  78.         10      Wimpslot free
  79.         12      Screen memory
  80.         13      Cursor/System/Sound
  81.         14      System heap/stack
  82.         15      Module area
  83.         16      Font cache
  84.         17      System sprites
  85.         18      RAM disc
  86.         19      Applications (free)
  87.         20      Applications (used)
  88.         21      System workspace
  89.         22      Total memory
  90.         23      Module area free
  91.         24      Module area largest block
  92.         25      Dynamic areas
  93.         
  94.   Before replying to this message a task can adjust the menu flags pointed to
  95. by r1+32 to display a tick, make the item writable etc. (although why you
  96. would want to I have no idea).  The string that will be displayed in the menu
  97. can be altered, either by changing the pointer at r1+36 or altering the block
  98. pointed to by it, the maximum length of this string can be is 40 bytes
  99. including a null terminator.
  100.  
  101.   This call will be received as reason code 18 (User_Message_Recorded), and
  102. to reply send the message back altered as necessary as reason code 17
  103. (User_Message).  When a task replies the string will be copied across to the
  104. menu, the menu item will be unshaded, and the generate warning when submenu
  105. opened bit will be set.
  106.  
  107.   The following messages are only sent to a task if it replies to this
  108. message, therefore there is no need to check the item type or number for the
  109. following messages if the task only supports one type of menu, if it supports
  110. more than one then this will be necessary.
  111.  
  112. Message_TaskInfoMenuWarning (&4F6C1)
  113. --------------------------- --------
  114.  
  115.         r1+20 Item type
  116.         r1+24 Item number
  117.         r1+28 Pointer to menu flags of main item in taskmanager menu
  118.         r1+32 X coordinate of top left of new submenu
  119.         r1+36 Y coordinate of top left of new submenu
  120.         r1+40 Main menu selected item number (should always be 2)
  121.         r1+44 First submenu selected item number
  122.         ...
  123.         r1+.. -1 to terminate list
  124.  
  125.   TaskInfo sends this message when it receives a Message_MenuWarning (&400C0)
  126. from the Wimp, this is only sent to the task which replied to the previous
  127. Message_TaskInfoOpen (&4F6C0).
  128.  
  129.   This call will be received as reason code 18 (User_Message_Recorded), and
  130. to reply a Message_MenuWarning (&400C0) should be formatted using the
  131. information given and a new submenu pointer, this should then be sent back as
  132. reason code 17 (User_Message) after copying my_ref to your_ref to acknowledge
  133. the message.  The submenu should be contained in the RMA or a dynamic area
  134. which is readable in user mode (protection level 0 or 1).
  135.  
  136.   If this call is not replied to the standard quit submenu will be opened
  137. instead (which can be a bit confusing for items other than tasks).
  138.  
  139. Note : All menus created using this system for tasks should still have a quit
  140. option in order to maintain consistency within the taskmanager, however the
  141. task will have to act upon it itself as the taskmanager will no longer send
  142. a Message_Quit (0), or Message_PreQuit (8).  A task should still support the
  143. quit messages however in case TaskInfo is not loaded.
  144.  
  145. Message_TaskInfoMenuSelection (&4F6C2)
  146. ----------------------------- --------
  147.  
  148.         r1+20 Item type
  149.         r1+24 Item number
  150.         r1+28 Pointer to menu flags of main item in taskmanager menu
  151.         r1+32 Main menu selected item number (always 2)
  152.         r1+36 First submenu selected item number
  153.         ...
  154.         r1+.. -1 to terminate list
  155.  
  156.   This message is sent when a menuselection is made, this is only sent to the
  157. task which replied to the previous Message_TaskInfoOpen (&4F6C0).  The
  158. information given should be used to perform the relevant action.
  159.  
  160.   This call will be received as reason code 17 (User_Message), and there is
  161. no need to (and there should not be a) reply to this message.
  162.  
  163. Message_TaskInfoHelpRequest (&4F6C3)
  164. --------------------------- --------
  165.  
  166.         r1+20 Item type
  167.         r1+24 Item number
  168.         r1+28 Task handle of interactive help application
  169.         r1+32 Pointer to menu flags of main item in taskmanager menu
  170.         r1+36 Main menu selected item number (always 2)
  171.         r1+40 First submenu selected item number
  172.         ...
  173.         r1+.. -1 to terminate list
  174.  
  175.   This message is sent when TaskInfo receives a Message_HelpRequest (&502)
  176. from a help application, this is only sent to the task which replied to the
  177. previous Message_TaskInfoOpen (&4F6C0).  The information given should be used
  178. to supply the relevant interactive help.
  179.  
  180.   This call will be received as reason code 18 (User_Message_Recorded), and
  181. to reply the call should be sent back as reason code 17 (User_Message), with
  182. the interactive help text replacing the data from r1+36 upwards.
  183.  
  184.   If this call is not replied to a standard 'Move the pointer right to open
  185. the submenu for ...' will be used for the main menu item (and therefore a
  186. reply should not be made for the main menu item unless there is a need to
  187. change this), and for all other menu items a standard 'Sorry there is no help
  188. available for this menu item.' will be used.
  189.  
  190. Message_TaskInfoChangeName (&4F6C4)
  191. -------------------------- --------
  192.  
  193.     r1+20 Task handle whose name is to be changed
  194.     r1+24 Null terminated string containing new name (max. length 330 OS
  195.         units (approx 22 characters)
  196.  
  197.   This message can be sent (to the TaskManager) as reason code 17
  198. (User_Message) to initiate the change of a tasks name to that given.
  199.   
  200.   Note : This wimp message is only supplied for completeness the service call
  201. method should be used to initiate a name change where possible (in fact this
  202. message once received initiates that system itself).
  203.  
  204. Service Calls
  205. =============
  206.  
  207.   There is only one service call (with four reason codes) issued by this
  208. utility to provide the menu system and change task names :
  209.  
  210. Service_TaskInfo (&80780)
  211. -------------------------
  212.  
  213. The registers for reason codes 0-3 are as follows (unless otherwise stated) :
  214.  
  215.         r1 = &80780
  216.         r2 = Reason code
  217.         r3 = Pointer to wimp message block
  218.         r4 = Item type
  219.         r5 = Item number
  220.         r6 = Pointer to menu flags of main item in taskmanager menu
  221.         Other registers depend on reason code
  222.  
  223.   These service calls are called immediately before the associated wimp
  224. message.  If the service call is claimed by setting r1=0 on exit the wimp
  225. message is not called.  All reason codes are issued no matter whether or not
  226. the wimp system has been replied to or a claim is made using the service
  227. calls (except TaskInfo_Open call type 2 which is not issued if a previous
  228. call with a lower call type has been claimed or replied to by either service
  229. or wimp calls, but only for the associated chain of calls).
  230.  
  231.   To change any data the values in the registers r4 upwards must be changed
  232. for the benefit of other modules (unless the call is claimed), but to have
  233. any real effect the block pointed to by r3 must be changed.
  234.  
  235. TaskInfo_Open (Reason code 0)
  236. -----------------------------
  237.  
  238.         r2 = 0
  239.         r3 = Pointer to start of actual message (ie r1+20)
  240.         r7 = Call type (Only PreGlobal (0) and PostGlobal (2))
  241.  
  242.   A claim here should only be used to prevent the wimp task from receiving
  243. the message completely.  Ie to completely prevent a task from using TaskInfo.
  244.  
  245. TaskInfo_MenuWarning (Reason code 1)
  246. ------------------------------------
  247.  
  248.         r2 = 1
  249.         r3 = Pointer to start of actual message (ie r1+20)
  250.  
  251.   This call is issued to add a menu to the system in place of any wimp menu
  252. whether the default or a TaskInfo menu.  To specify the submenu pointer it
  253. must be stored at r3+8, and then the call claimed by setting r1 to 0.  The
  254. submenu should be held in RMA.
  255.  
  256. TaskInfo_MenuSelection (Reason code 2)
  257. --------------------------------------
  258.  
  259.         r2 = 2
  260.         r3 = Pointer to start of actual message (ie r1+20)
  261.  
  262.   This call can be used either to replace the actions of an existing menu
  263. (either the default menu or a task menu, but only if certain of the exact
  264. structure of the menu), or to provide a completely different menu.  It is
  265. expected however for it to be used to provide an action for the main menu
  266. option.
  267.   Claiming the call by setting r1 to 0 will prevent either the default
  268. option or the task options from being executed.
  269.  
  270. TaskInfo_HelpRequest (Reason code 3)
  271. ------------------------------------
  272.  
  273.         r2 = 3
  274.         r3 = Pointer to actual start of block (ie r1)
  275.  
  276.   This call is used to provide interactive help for a menu option, if this
  277. call is claimed then the message should be placed at r3+20 with a null
  278. terminator, and the length of the message + 20 should be placed at r3,
  279. finally the call should be claimed by setting r1 to 0.
  280.  
  281. TaskInfo_ChangeName (Reason code 4)
  282. -----------------------------------
  283.  
  284.     r1 = &80780
  285.     r2 = 4
  286.     r3 = Task handle of task whose name is being changed
  287.     r4 = Pointer to current task name
  288.     r5 = Pointer to new task name requested
  289.  
  290.   This call is issued when a request to change the name of a task is
  291. received, in order to change the new name of the task there are two options
  292. available :
  293.  
  294. 1) Change the name pointed to by r4 and claim the call
  295. 2) Change the pointer in r5 and let the call continue
  296.  
  297. Note : The maximum length of the task name is 330 OS units (approx. 22
  298. characters), excluding the null terminator.
  299.  
  300. The following service reason code can be used to initiate the change of a
  301. task name, it should only be issued and should not be intercepted/altered in
  302. any way.
  303.  
  304. TaskInfo_ChangeNameInit (Reason code 5)
  305. ---------------------------------------
  306.  
  307.     r1 = &80780
  308.     r2 = 5
  309.     r3 = Task handle of task whose name is being changed
  310.     r5 = Pointer to new task name (does not have to be in RMA)
  311.  
  312. Note : For both the service call and wimp methods of task name changing no
  313. error will be returned if the task does not exist.
  314. _____________________________________________________________________________
  315.  
  316.  Licence
  317.  
  318.   This software is copyrighted work of Jonathan Brady, it is supplied
  319. “as is”; using it is entirely at your own risk.  I make no warranty as to
  320. the fitness of this software for any purpose.  This software may be passed
  321. on to other people as long as the following conditions are met:
  322.  
  323.   1) Copies may be passed between private individuals as long as this is
  324.      done free of charge.
  325.  
  326.   2) It may be distributed by public domain libraries, as long as no more
  327.      than £2.00 is charged for a 800Kb (E format) disk of P.D. software
  328.      containing TaskInfo and no more than £2.50 is charged for a 1.6Mb (F
  329.      format disk).  If charges are higher than this, then my permission must
  330.      be obtained first.
  331.  
  332.   3) It may be distributed by remote databases such as FTP sites or mail
  333.      servers on the Internet or bulletin boards, as long as no charge is
  334.      made for downloading it (other than the cost of the phone call).
  335.  
  336.   4) It may be distributed by any other method (including magazine discs)
  337.      provided that my permission has been obtained first.
  338.  
  339.   5) The copyright remains mine at all times.
  340.  
  341.   6) The software is distributed intact and unchanged.  Or in other words
  342.      the module must be accompanied by this help file (the example programs
  343.      need not be included).
  344.   
  345.   7) The software can be distributed with any package (including commercial
  346.      packages) free of charge (but see condition 6).  There is no need to
  347.      inform me when distributing with any package, but it would be polite.
  348.  
  349.   8) An acknowledgement would be appreciated in the documentation of any
  350.      package that the software is distributed with, stating that the
  351.      software can be used by the package, and that the software copyright
  352.      belongs to me.
  353. _____________________________________________________________________________
  354.  
  355.  Versions
  356.  
  357. 1.00 (13 Mar 1998)
  358.      - Works fine on RISC OS 3.7 taskmanager not tested on anything else.
  359.      - Warning when menu clicked in task display window.
  360.      - Warning when submenu opened in from above menu.
  361.      - Interactive help system for menus implemented.
  362.  
  363. 1.01 (14 Mar 1998)
  364.      - Code tidied up slightly, unused routines removed.
  365.      - Different text displayed for area headers to other items in system.
  366.      - Tested and works with RISC OS 3.6 taskmanager.
  367.      - Tested and does not work on RISC OS 3.11 taskmanager.
  368.  
  369. 1.02 (15 Mar 1998)
  370.      - First release version.
  371.      - Works on RISC OS 3.11 taskmanager.
  372.  
  373. 1.03 (18 Mar 1998)
  374.      - Second release version.
  375.      - Error if clicked at very bottom of work area fixed.
  376.      - Error if menu closed just after menuwarning message sent fixed.
  377.      - If submenu warning ignored for items other than tasks standard quit
  378.      menu is no longer displayed.
  379.      - Menu selection message no longer sent if submenu warning not replied
  380.      to.
  381.      - Service call system added.
  382.  
  383. 1.04 (13 Apr 1998)
  384.      - Menu item positioning system altered to use same system TaskManager
  385.      uses.
  386.      - Now uses TaskManager version number when calculating item numbers
  387.      instead of RISC OS version number, to solve problems with people using
  388.      new TaskManager on old versions of RISC OS (I'm just guessing the
  389.      version numbers so please report any further problems).
  390.      - Select and adjust click bugs fixed (ie now they are ignored).
  391.      - Menu flags changed back to standard flags each time menu opened.
  392.  
  393. 1.05 (27 Apr 1998)
  394.      - Third release version.
  395.      - Can now be installed before the desktop due to new filter system,
  396.      needs WimpSWIve though.
  397.      - TaskDemo2 included (BASIC version of TaskDemo).
  398.      - Templates added to demo applications
  399.      - Service handler code fixed.
  400.      - There appears to be a problem with RISC OS 3.6 (reported by David
  401.      Thomas), possibly RISC OS 3.5 too.
  402.  
  403. 1.06 (09 Jun 1998)
  404.      - Fourth release version.
  405.      - Task name changing system added.
  406.      - Redraw of taskmanager window when task name changed narrowed down to
  407.      name only.
  408.      - TaskDemo3 included to demonstrate name changing system, this is not
  409.      the intended use for this facility, but I thought it would be a fairly
  410.      interesting example.  It is intended for use in displaying program
  411.      status.
  412.      - Bug which stopped quit option working when TaskInfo_MenuWarning was
  413.      not replied to fixed.
  414.      - TaskDemo2 and TaskDemo3 now use MessageTrans.
  415.      - Fixed bug introduced in version 1.04 which stopped TaskInfo working
  416.      with RISC OS 3.5 and 3.6 (well I did say I was just guessing the version
  417.      numbers).
  418.      - There appears to be a problem with pre RISC OS 3.5 machines and the
  419.      new filter installation system introduced in version 1.05, until this is
  420.      fixed the new installation system has been removed from the release
  421.      version.  A copy incorporating the new installation system can be
  422.      obtained from the author on request.
  423. _____________________________________________________________________________
  424.   
  425.  To do list
  426.  
  427.   Tidy code up.
  428.   Support MessageTrans for TaskDemo.
  429.   Demo application in C - Does anyone want this?
  430.   Small C library to facilitate code writing?
  431.   New installation system fix for RISC OS 3.11
  432.   Test with new FilterManager (version 0.18).
  433. _____________________________________________________________________________
  434.  
  435.  Contact Addresses
  436.  
  437.   If you have any comments, bug reports, suggestions for future versions or
  438. anything else don't hesitate to contact me at :
  439.  
  440.   Mail:  Mr J.T.J. Brady
  441.          147 Higher Bebington Road
  442.          Higher Bebington
  443.          Wirral
  444.          Merseyside
  445.          L63 2PN
  446.  
  447.   Email: taskinfo@sliced.demon.co.uk
  448.  
  449.   WWW:   http://www.sliced.demon.co.uk/