RISC DISC 1

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

/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / PopUps / Docs / 5 < prev next >

Wrap

Text File | 1993-05-24 | 16.8 KB | 387 lines

Adding your own PopUp Handler ============================= You may add your own PopUp handlers to the PopUp Server application, either to provide new PopUp types, or to provide a different implementation for an existing PopUp type. Your code may be written in any language from which you can get linkable AOF output (C, assembler). The basic procedure is as follows: Write the .c code for your handler, e.g. _ProgInfo.c Provide in this, an extern handler_info HandlerInfo_ProgInfo which describes your handler, and includes a pointer to it's entry function, etc. Then edit HandlerTab.c - add a line to the list: HandlerInfo_Proginfo, Edit PopUps.h - add a prototype for your HandlerInfo: extern handler_info HandlerInfo_ProgInfo; Compile this code, and link it with DeskLib 2.00 or later. Supplied functions/constants ============================ The PopUp Server supplies a few special functions for you to use instead of DeskLib functions, or to do special PopUp-related things, as well as some predefined constants which you should use to make your code more easily fixed if changes occur. These are defined at the bottom of Server.h and are listed again below. DO NOT use any functions/variables that are not listed here! /* SendState * Packages the given PopUp-specific data section of the application params * into a message_PopUpState, and sends it back to the client task. */ extern void SendState(void *statedata, int statesize); /* ImDragging * If you wish to start a drag operation in your handler, you MUST call * this function as you do so - this tells the server that you are the * handler to call back when the drag finishes - if you do not call this * then the server will not call you (and will fail to process the drag * finish event) */ extern void ImDragging(void); /* SetIconText * Equivalent to DeskLib's Icon_SetText, with one VERY IMPORTANT difference * - it handles strings terminated with CR (13) instead of NUL (0), which * may be passed in from BASIC and assembler client tasks. * You therefore MUST use this version instead of Icon_SetText!!! */ extern void SetIconText(window_handle w, icon_handle i, char *text); #define Icon_SetText SetIconText /* ShowStaticPopUp * If you are providing a static PopUp, you will need to open it at * the x and y position requested by the user. To make this easier, * and help to share such code, this function is provided, which simply * opens the given window at the given top-left position. * (i.e. use ShowStaticPopUp(ctrl->basewindow, ctrl->openx, ctrl->openy); * * This call will also repel your window approximately 64 OS units away * from the edges of the screen, which ensures that the iconbar is always * visible, and is generally much nicer than opening hard up against an * edge of the screen. */ extern void ShowStaticPopUp(window_handle window, int openx, int openy); /* KillMe * Will kill off the current PopUp * If a PopUp wishes to let everyone know that it has closed, then * it MUST call KillMe(). This should only be necessary on event_CLOSE * Wimp events, or if a 'cancel' button is clicked, etc. * (You do not need to call this function if you are told to close with * a REASON_CLOSE) * * If you do not call this function, then you will continue to recieve * WIMP events, and will tie up one static-instantiation slot. (bad) * * VERY IMPORTANT NOTE: * This call removes your PopUp instantiation information, which means * after the call you cannot rely on the passed-in ctrl block and * private workspace any more. (The former may have been changed and the * latter WILL have been deallocated). This should therefore be the very * last thing in your code before you return control for the last time. */ extern void KillMe(void); /* Template_RMAFind * Roughly the same as Template_Find * However it actually clones into malloc() and RMA static memory chunks * so that the indirected data is always paged in. * THIS SHOULD ONLY be called if your PopUp is to be shown as a MENU LEAF * (because otherwise you will most likely be overwriting/overwritten by * another PopUp in these static memory areas) * i.e. only use it: * if ((ctrl->appflags & APPFLAGS_ISLEAF) != 0) * If this is not the case, or if it is a Static PopUp, then use the normal * Template_Find or Template_Clone. * * This function only guarantees 1024 bytes of space for indirected icon * data. If you need more than this (shame on you!) you will need to * alter the constant at the top of Template.c */ extern window_block *Template_RMAFind(char *name); /* For REASON_OPEN, the pollblock contains a PopUpOpen message. * The definition of this includes the message header, the PopUp handle, * then the application parameter block header, followed (at offset 48 into * the complete WIMP message) by the PopUp-specific data. * Note that the pollblock includes a word at the front (event type), so * this shifts our data to offset 52 within the passed pollblock, * i.e. ((int) pollblock)+52 is the base address of the PopUp specific data */ #define POPUP_DATA_OFFSET 52 For examples, see the enclosed source code, and preferably use it as a template/shell for your own code to ensure you do everything right. Your handler function ===================== It should be farly straightforward to see what is going on in the supplied PopUp sources. The basics are as follows, though: You supply a single handler function, which is called with 4 parameters: R0 (parameter 0) = reason code R1 (parameter 1) = control block R2 (parameter 2) = private workspace R3 (parameter 3) = Wimp poll event description block These parameters are described below. Static PopUps, being 'permanent' windows (they only go away when explicitly closed), can possibly allow several of the same type of PopUp to be open at once (e.g. both Draw and Edit could be displaying a FontSelect at once) Thus, static PopUp handlers should be able to handle multiple instantiations. To help this along, your handler is called with a different control block and workspace area for each PopUp type - USE THEM! Do NOT store window-specific data in static storage- use the provided workspace block. Reason code ----------- This number tells your handler function why it is being called. Currently there are 3 reason codes defined (plus some proposed ones). They are: Reason code = 0 (open) You must create a new PopUp window according to the data passed in the Wimp poll event description block (which contains a complete Message_PopUpOpen - popup specific data starts at (event block) + 48) You should fill in appropriate sections of the control block (see below) such as the window handle and the poll mask before you exit. To exit, you return TRUE if you succeeded in creating the PopUp, else FALSE MENU LEAF PopUp Ensure the window does not have a close icon Duplicate the template using Template_FindRMA - if you do not do this, the WIMP stupidly looks in the wrong place for indirected icon data in the wrong application's workspace, and will crash your client! Create the window, but DO NOT SHOW IT - the server will do this for you. MENU STANDALONE PopUp Ensure that the window does have a close icon If you do not supply a STATIC PopUp, then you may use Template_Find to save memory - otherwise, you must use Template_Clone. Create the window, but DO NOT SHOW IT - the server will do this for you. STATIC PopUp Use Template_Clone to create your windows (though Template_Find will suffice if the window contains NO indirected data) Create AND OPEN the window. (Statics may use panes, so the server can't make assumptions about how to open the PopUp for you) Use ShowStaticPopUp() to open the window, to share existing code. Reason code = 1 (Close) Simply Wimp_DeleteWindow your window. You MUST NOT close the menu tree, as this call is used to remove your PopUp as the user moves the mouse from one menu item to another! Remember to call KillMe(); Reason code = 2 (Wimp Event) You must try to process the Wimp event passed to you (parameter 3). If you succeed in processing the event, return TRUE, else FALSE. Note that you may get events intended for OTHER PopUps - you MUST check if the event really applies to the PopUp window referenced in the control block, and return FALSE if it is not your window! Events will only be given to you if your poll mask allows it. Events you fail to handle (and NULLs) will be passed on to the next PopUp handler until somebody handles them. If nobody handles it, a default action may be performed by the server (see below). IMPORTANT NOTES 1 If your window is not 'auto-redraw', you MUST supply a redraw handler, or else an attempt to open your PopUp will result in the machine locking up. (Check also that you have enabled event_REDRAW) 2 If you ever start a Wimp drag operation in your event handler, you MUST invoke ImDragging(); so that the server knows where to deliver the related drag-finish event. If you don't call this function, the drag-finish event will NOT be delivered to you. In your event_USERDRAG handler, you can assume that the event IS yours, as you'll only ever get this event if you call ImDragging as you start a drag. Obviously, you should only call ImDragging if you start a drag! (See _SaveAs.c for an example of a PopUp using drags) P.S. Please use Icon_DragASprite where possible (code is already linked into the application, and DragASprite looks good - it will do an ordinary drag for you under RO2, or if DragASpr is not configured on) 3 If nobody handles the event, the following default action is taken: event_OPEN: Wimp_OpenWindow(&event->data.openblock); event_KEY: Wimp_ProcessKey(event->data.key.code); 4 If the event causes you to close the PopUp, then remember to call KillMe() to let the server know the PopUp is closed. 5 VERY VERY important - Menu PopUps Whenever you delete your window, you MUST ensure that the menu 'containing' your window has been closed. In many circumstances you can just Wimp_CreateMenu((menu_block *) -1, 0, 0); to kill the menu before Wimp_DeleteWindow(), but in some cases you should check if your window is open - if it IS open, you need to kill the menu before you can Wimp_DeleteWindow. Failure to Close the menu first will result in the WIMP crashing. Closing when it has been closed may result in you killing off another (unrelated) menu (e.g. if your window is closed by a click outside the window, that click could create a NEW menu before you are called to close the window) Control Block ------------- This contains some useful information about how to open the PopUp, and is where you must store relevant information for the server to use. The control block is laid out as follows: event_pollmask pollmask - You must keep this updated with a Wimp_Poll style PollMask - mask out all events you don't want, for efficient operation. window_handle basewindow; - You must store the (BASE) window handle here for the Server to use. task_handle clienttask; - read-only: The client's taskhandle int openx, openy; - read only: The x/y position you should open the window at (top left corner) char appflags; - read-only: The application flag byte as described in the application parameter block details. NOTE that you will get one such work area for EACH PopUp INSTANTIATION that you are controlling (i.e if the server asks you for 2 static PopUps, you will be called with two different ctrl and private workspace blocks) Private Workspace ----------------- In the structure used to link your handler to the server, the last item is a 'private workspace size'. For each PopUp requested, a new chunk of memory is allocated for the relevant handler to use, and is passed in to that handler as it's private workspace. NOTE that you will get one such work area for EACH PopUp INSTANTIATION that you are controlling (i.e if the server asks you for 2 static PopUps, you will be called with two different ctrl and private workspace blocks) (See _Magnify.c for an example PopUp which uses the private workspace to provide multiple STATIC (and 1 MENU) instantiations) Event data ---------- This is a normal DeskLib event_pollblock structure. That is, the first word contains the reasoncode returned by Wimp_Poll, and the remainder of the block contains the event-specific data returned by that SWI. It comes to you in entirely uncensored form. If you do not handle the event, or if it is a NULL event, you MUST return with the block unchanged. Adding your own PopUp Server ============================ The PopUpManager module has the ability to use a different aplication as a server for each PopUp type it knows of. This allows you to write new server application(s) which replace old PopUps and/or provide new ones - in this way, you can add assembler or BASIC handlers without having to be able to link them into the supplied server application. A PopUp server may also be a relocatable module, which may happen in the future with the base set of standard PopUps. The PopUp interface has been carefully designed to go through the manager module to allow this sort of flexibility in how PopUps are served. A PopUp server is very simple to write, especially if you write a dedicated server for each PopUp (minimising the amount of generic 'handle multiple PopUp types' code you have to write). It is basically a WIMP application which includes PopUp handler(s). When it starts up, it registers each handler in turn with the PopUpManager (SWI PopUp_Register), replacing any existing handlers for those PopUp types. On exit, it calls PopUp_Deregister for each supplied handler to inform the manager that they are no longer supported by a server. The supplied PopUp Server plus two PopUps were written in less than a day. (Though admittedly, I had written similar things a few times before during development of the system, so knew exactly what to do!) The server must provide a list of PopUp instantiations, indexed by the PopUp handle that the PopUp Manager generates on PopUp_Open. Of course, if you provide only a single Menu PopUp, you need not hassle yourself with multiple instantiations etc. When the server recieves a Message_PopUpOpen, a Message PopUpClose, or a WIMP event, it adjusts its lists appropriately, and calls the appropriate handler with a reason code of 0 (open), 1 (close) or 2 (Wimp event). When processing Wimp Events, you should check for important events such as a quit message, and if you then have not processed the event, pass it on to the handlers - use of an event mask for each handler can make this quite efficient. Pass the event around ueach instantiation until a handler has handled it (though pass NULLs to all handlers which haven't masked them out) After calling the (0) Open Handler, you must check if the PopUp is a Menu PopUp - if it is, you must do the following: IF PopUp is NOT a menu leaf THEN SYS "Wimp_CreateMenu",,popupwindow, openx, openy ELSE Send PopUpRequest message to client task with message!20 = popupwindow message!24 = openx message!28 = openy ENDIF The last detail is that the WIMP was not designed with PopUps in mind, and so the PopUp Manager has been designed around several rather difficult features (all of which are perfectly reasonable under normal use). One, you see above - the WIMP won't let us attach our window to another task's menu tree, so we must (currently) request that the application attaches the window on our behalf using the PopUpRequest message. The only other one that need concern you is that the WIMP assumes that any window in the menu tree belongs to the menu's creator - this would be fine, except that it means that when looking for indirected data, the WIMP looks in the WRONG application's memory slot! This has suitably undesirable effects. The only way to fix this (currently) is to allocate enough memory in the RMA to hold all indirected data. Luckily, very little is needed, as the only time this is a problem is with MENU LEAF PopUps. As only one such PopUp is ever open, we only ever need to store one such PopUp's data in the RMA. (Standalone MENU and STATIC PopUps work fine, as the whole window/menu-tree belongs to the PopUpManager in these cases)