ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / programming / taskinfo / !TaskInfo next >

Wrap

Text File | 1998-08-19 | 18.1 KB | 449 lines

________________________________ TaskInfo 1.06 (20 Jun 1998) ________________________________ Written by Jonathan Brady for Sliced Software, © 1998 _____________________________________________________________________________ Introduction TaskInfo is a utility for adding to the taskmanager menu, and for supplying interactive help for those menus. It can also be used to change the name of a task as given in the task manager display. _____________________________________________________________________________ Usage Load TaskInfo by double-clicking on it's icon in a filer window. Once loaded it will sit in the background waiting for you to click the menu button in the task display window, this starts the chain of wimp messages and service calls off. Note 1 : All pointers used should be to locations in the RMA or a dynamic areas which is readable in user mode (protection level 0 or 1). This is mentioned further down the help file but some people seem to forget. Note 2 : All task handles should only rely on the 2 LSB of the word i.e. (Task handle AND &FFFF). Note 3 : You should ensure that version 1.06 is loaded with any program, versions prior to 1.04 had several bugs in them, and versions 1.04 and 1.05 would not work on the RISC OS 3.5 and 3.6 taskmanagers. Wimp Messages ============= There are three wimp messages issued by this utility in an effort to provide the menu system : Message_TaskInfoOpen (&4F6C0) -------------------- -------- r1+20 Call type r1+24 Item type r1+28 Item number (task handle, dynamic area number) r1+32 Pointer to menu flags of main item in taskmanager menu r1+36 Pointer to string that will be displayed in menu r1+40 Pointer to name of item (tasks and dynamic areas only) There are three possible call types : 0 - PreGlobal : Global call to all tasks, used to replace menus provided by a task, and for all other item types. 1 - Task : Direct call to task for menus (only available for tasks, and only for task whose name the menu is opened over, therefore no need to check task handle just whether call type is 1) 2 - PostGlobal : Global call to all tasks if task does not respond to call type 1, used to provide menu for tasks which don't do themselves, so if a later version of the task does that will be used instead. Call types 1 and 2 are only issued when a task name is clicked over in the display, they are issued in sequence, and the sequence stops when a reply is received. Item numbers are as follows : 1 Application tasks header 2 System memory allocation header 3 Module tasks header 4 Dynamic area header 5 Tasks and module tasks 8 Wimpslot next 10 Wimpslot free 12 Screen memory 13 Cursor/System/Sound 14 System heap/stack 15 Module area 16 Font cache 17 System sprites 18 RAM disc 19 Applications (free) 20 Applications (used) 21 System workspace 22 Total memory 23 Module area free 24 Module area largest block 25 Dynamic areas Before replying to this message a task can adjust the menu flags pointed to by r1+32 to display a tick, make the item writable etc. (although why you would want to I have no idea). The string that will be displayed in the menu can be altered, either by changing the pointer at r1+36 or altering the block pointed to by it, the maximum length of this string can be is 40 bytes including a null terminator. This call will be received as reason code 18 (User_Message_Recorded), and to reply send the message back altered as necessary as reason code 17 (User_Message). When a task replies the string will be copied across to the menu, the menu item will be unshaded, and the generate warning when submenu opened bit will be set. The following messages are only sent to a task if it replies to this message, therefore there is no need to check the item type or number for the following messages if the task only supports one type of menu, if it supports more than one then this will be necessary. Message_TaskInfoMenuWarning (&4F6C1) --------------------------- -------- r1+20 Item type r1+24 Item number r1+28 Pointer to menu flags of main item in taskmanager menu r1+32 X coordinate of top left of new submenu r1+36 Y coordinate of top left of new submenu r1+40 Main menu selected item number (should always be 2) r1+44 First submenu selected item number ... r1+.. -1 to terminate list TaskInfo sends this message when it receives a Message_MenuWarning (&400C0) from the Wimp, this is only sent to the task which replied to the previous Message_TaskInfoOpen (&4F6C0). This call will be received as reason code 18 (User_Message_Recorded), and to reply a Message_MenuWarning (&400C0) should be formatted using the information given and a new submenu pointer, this should then be sent back as reason code 17 (User_Message) after copying my_ref to your_ref to acknowledge the message. The submenu should be contained in the RMA or a dynamic area which is readable in user mode (protection level 0 or 1). If this call is not replied to the standard quit submenu will be opened instead (which can be a bit confusing for items other than tasks). Note : All menus created using this system for tasks should still have a quit option in order to maintain consistency within the taskmanager, however the task will have to act upon it itself as the taskmanager will no longer send a Message_Quit (0), or Message_PreQuit (8). A task should still support the quit messages however in case TaskInfo is not loaded. Message_TaskInfoMenuSelection (&4F6C2) ----------------------------- -------- r1+20 Item type r1+24 Item number r1+28 Pointer to menu flags of main item in taskmanager menu r1+32 Main menu selected item number (always 2) r1+36 First submenu selected item number ... r1+.. -1 to terminate list This message is sent when a menuselection is made, this is only sent to the task which replied to the previous Message_TaskInfoOpen (&4F6C0). The information given should be used to perform the relevant action. This call will be received as reason code 17 (User_Message), and there is no need to (and there should not be a) reply to this message. Message_TaskInfoHelpRequest (&4F6C3) --------------------------- -------- r1+20 Item type r1+24 Item number r1+28 Task handle of interactive help application r1+32 Pointer to menu flags of main item in taskmanager menu r1+36 Main menu selected item number (always 2) r1+40 First submenu selected item number ... r1+.. -1 to terminate list This message is sent when TaskInfo receives a Message_HelpRequest (&502) from a help application, this is only sent to the task which replied to the previous Message_TaskInfoOpen (&4F6C0). The information given should be used to supply the relevant interactive help. This call will be received as reason code 18 (User_Message_Recorded), and to reply the call should be sent back as reason code 17 (User_Message), with the interactive help text replacing the data from r1+36 upwards. If this call is not replied to a standard 'Move the pointer right to open the submenu for ...' will be used for the main menu item (and therefore a reply should not be made for the main menu item unless there is a need to change this), and for all other menu items a standard 'Sorry there is no help available for this menu item.' will be used. Message_TaskInfoChangeName (&4F6C4) -------------------------- -------- r1+20 Task handle whose name is to be changed r1+24 Null terminated string containing new name (max. length 330 OS units (approx 22 characters) This message can be sent (to the TaskManager) as reason code 17 (User_Message) to initiate the change of a tasks name to that given. Note : This wimp message is only supplied for completeness the service call method should be used to initiate a name change where possible (in fact this message once received initiates that system itself). Service Calls ============= There is only one service call (with four reason codes) issued by this utility to provide the menu system and change task names : Service_TaskInfo (&80780) ------------------------- The registers for reason codes 0-3 are as follows (unless otherwise stated) : r1 = &80780 r2 = Reason code r3 = Pointer to wimp message block r4 = Item type r5 = Item number r6 = Pointer to menu flags of main item in taskmanager menu Other registers depend on reason code These service calls are called immediately before the associated wimp message. If the service call is claimed by setting r1=0 on exit the wimp message is not called. All reason codes are issued no matter whether or not the wimp system has been replied to or a claim is made using the service calls (except TaskInfo_Open call type 2 which is not issued if a previous call with a lower call type has been claimed or replied to by either service or wimp calls, but only for the associated chain of calls). To change any data the values in the registers r4 upwards must be changed for the benefit of other modules (unless the call is claimed), but to have any real effect the block pointed to by r3 must be changed. TaskInfo_Open (Reason code 0) ----------------------------- r2 = 0 r3 = Pointer to start of actual message (ie r1+20) r7 = Call type (Only PreGlobal (0) and PostGlobal (2)) A claim here should only be used to prevent the wimp task from receiving the message completely. Ie to completely prevent a task from using TaskInfo. TaskInfo_MenuWarning (Reason code 1) ------------------------------------ r2 = 1 r3 = Pointer to start of actual message (ie r1+20) This call is issued to add a menu to the system in place of any wimp menu whether the default or a TaskInfo menu. To specify the submenu pointer it must be stored at r3+8, and then the call claimed by setting r1 to 0. The submenu should be held in RMA. TaskInfo_MenuSelection (Reason code 2) -------------------------------------- r2 = 2 r3 = Pointer to start of actual message (ie r1+20) This call can be used either to replace the actions of an existing menu (either the default menu or a task menu, but only if certain of the exact structure of the menu), or to provide a completely different menu. It is expected however for it to be used to provide an action for the main menu option. Claiming the call by setting r1 to 0 will prevent either the default option or the task options from being executed. TaskInfo_HelpRequest (Reason code 3) ------------------------------------ r2 = 3 r3 = Pointer to actual start of block (ie r1) This call is used to provide interactive help for a menu option, if this call is claimed then the message should be placed at r3+20 with a null terminator, and the length of the message + 20 should be placed at r3, finally the call should be claimed by setting r1 to 0. TaskInfo_ChangeName (Reason code 4) ----------------------------------- r1 = &80780 r2 = 4 r3 = Task handle of task whose name is being changed r4 = Pointer to current task name r5 = Pointer to new task name requested This call is issued when a request to change the name of a task is received, in order to change the new name of the task there are two options available : 1) Change the name pointed to by r4 and claim the call 2) Change the pointer in r5 and let the call continue Note : The maximum length of the task name is 330 OS units (approx. 22 characters), excluding the null terminator. The following service reason code can be used to initiate the change of a task name, it should only be issued and should not be intercepted/altered in any way. TaskInfo_ChangeNameInit (Reason code 5) --------------------------------------- r1 = &80780 r2 = 5 r3 = Task handle of task whose name is being changed r5 = Pointer to new task name (does not have to be in RMA) Note : For both the service call and wimp methods of task name changing no error will be returned if the task does not exist. _____________________________________________________________________________ Licence This software is copyrighted work of Jonathan Brady, it is supplied “as is”; using it is entirely at your own risk. I make no warranty as to the fitness of this software for any purpose. This software may be passed on to other people as long as the following conditions are met: 1) Copies may be passed between private individuals as long as this is done free of charge. 2) It may be distributed by public domain libraries, as long as no more than £2.00 is charged for a 800Kb (E format) disk of P.D. software containing TaskInfo and no more than £2.50 is charged for a 1.6Mb (F format disk). If charges are higher than this, then my permission must be obtained first. 3) It may be distributed by remote databases such as FTP sites or mail servers on the Internet or bulletin boards, as long as no charge is made for downloading it (other than the cost of the phone call). 4) It may be distributed by any other method (including magazine discs) provided that my permission has been obtained first. 5) The copyright remains mine at all times. 6) The software is distributed intact and unchanged. Or in other words the module must be accompanied by this help file (the example programs need not be included). 7) The software can be distributed with any package (including commercial packages) free of charge (but see condition 6). There is no need to inform me when distributing with any package, but it would be polite. 8) An acknowledgement would be appreciated in the documentation of any package that the software is distributed with, stating that the software can be used by the package, and that the software copyright belongs to me. _____________________________________________________________________________ Versions 1.00 (13 Mar 1998) - Works fine on RISC OS 3.7 taskmanager not tested on anything else. - Warning when menu clicked in task display window. - Warning when submenu opened in from above menu. - Interactive help system for menus implemented. 1.01 (14 Mar 1998) - Code tidied up slightly, unused routines removed. - Different text displayed for area headers to other items in system. - Tested and works with RISC OS 3.6 taskmanager. - Tested and does not work on RISC OS 3.11 taskmanager. 1.02 (15 Mar 1998) - First release version. - Works on RISC OS 3.11 taskmanager. 1.03 (18 Mar 1998) - Second release version. - Error if clicked at very bottom of work area fixed. - Error if menu closed just after menuwarning message sent fixed. - If submenu warning ignored for items other than tasks standard quit menu is no longer displayed. - Menu selection message no longer sent if submenu warning not replied to. - Service call system added. 1.04 (13 Apr 1998) - Menu item positioning system altered to use same system TaskManager uses. - Now uses TaskManager version number when calculating item numbers instead of RISC OS version number, to solve problems with people using new TaskManager on old versions of RISC OS (I'm just guessing the version numbers so please report any further problems). - Select and adjust click bugs fixed (ie now they are ignored). - Menu flags changed back to standard flags each time menu opened. 1.05 (27 Apr 1998) - Third release version. - Can now be installed before the desktop due to new filter system, needs WimpSWIve though. - TaskDemo2 included (BASIC version of TaskDemo). - Templates added to demo applications - Service handler code fixed. - There appears to be a problem with RISC OS 3.6 (reported by David Thomas), possibly RISC OS 3.5 too. 1.06 (09 Jun 1998) - Fourth release version. - Task name changing system added. - Redraw of taskmanager window when task name changed narrowed down to name only. - TaskDemo3 included to demonstrate name changing system, this is not the intended use for this facility, but I thought it would be a fairly interesting example. It is intended for use in displaying program status. - Bug which stopped quit option working when TaskInfo_MenuWarning was not replied to fixed. - TaskDemo2 and TaskDemo3 now use MessageTrans. - Fixed bug introduced in version 1.04 which stopped TaskInfo working with RISC OS 3.5 and 3.6 (well I did say I was just guessing the version numbers). - There appears to be a problem with pre RISC OS 3.5 machines and the new filter installation system introduced in version 1.05, until this is fixed the new installation system has been removed from the release version. A copy incorporating the new installation system can be obtained from the author on request. _____________________________________________________________________________ To do list Tidy code up. Support MessageTrans for TaskDemo. Demo application in C - Does anyone want this? Small C library to facilitate code writing? New installation system fix for RISC OS 3.11 Test with new FilterManager (version 0.18). _____________________________________________________________________________ Contact Addresses If you have any comments, bug reports, suggestions for future versions or anything else don't hesitate to contact me at : Mail: Mr J.T.J. Brady 147 Higher Bebington Road Higher Bebington Wirral Merseyside L63 2PN Email: taskinfo@sliced.demon.co.uk WWW: http://www.sliced.demon.co.uk/