The Datafile PD-CD 4

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

/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsd / evntshell / Docs / Events < prev next >

Wrap

Text File | 1995-11-11 | 17.3 KB | 644 lines

PROCshell_AttachPaletteChangeHandler() Params => str function name Registers a function name to be called when a PaletteChange message is received. This occurs when the user has finished dragging the sliders on the Palette application, or when a new palette is loaded. It is also called when the handler is set up so that the user application can note the current parameters. Note that this message is not issued when the screen mode changes, so tasks interested in colour mapping changes should call PROCshell_AttachModeChangeHandler as well. User FN (PROCshell_AttachPaletteChangeHandler) Params => None This function is called when a PaletteChange message is received and also when PROCshell_AttachPaletteChangeHandler is called. -------------------------------------------------------- PROCshell_AttachModeChangeHandler() Params => str function name Registers a function name to be called when a ModeChange message is received. This allows the application to check any mode-specific parameters such as screen width etc. It is also called when the handler is set up so that the user application can note the current parameters. User FN (PROCshell_AttachModeChangeHandler) Params => None This function is called when a ModeChange message is received and also when PROCshell_AttachModeChangeHandler is called -------------------------------------------------------- PROCshell_AttachTaskInitialiseHandler() Params => str function name Registers a function name to be called when a TaskInitialise message is received. This allows the application to keep track of any new tasks started after it. User FN (PROCshell_AttachTaskInitialiseHandler) Params => None This function is called when a TaskInitialise message is received. -------------------------------------------------------- PROCshell_AttachTaskCloseDownHandler() Params => str function name Registers a function name to be called when a TaskCloseDown message is received.This message is sent when a task (other than the current one) is killed. User FN (PROCshell_AttachTaskCloseDownHandler) Params => None This function is called when a TaskCloseDown message is received. -------------------------------------------------------- PROCshell_AttachPane() Params => int window handle int pane handle int pane flags int x offset of pane relative to parent window int y offset of pane relative to parent window Pane Flags (PROCshell_AttachPane) 0 = attached to parent window work area 1 = not used 2 = attached to left edge 3 = attached to bottom edge 4 = attached to right edge 5 = attached to top edge If necessary the window flags of the pane window are changed so that the 'pane' bit is on and the 'moveable' bit is off, so that editing the template file is not required. -------------------------------------------------------- PROCshell_AttachDataLoad() Attaches a dataload handler to a window/icon pair. Params => int window handle int icon handle int filetype to recognise and optionally load (see no load flag) str function name bool no load flag Note that it is possible to call this function for the same window/icon pair more than once giving different filetypes (and function names if required) to allow the handling of multiple filetypes. User FN (PROCshell_AttachDataLoad) Params => int address file has been loaded at int filetype of file str full pathname of file int file size (from dataload message) Note that if the event was attached with the no load flag set to TRUE the address will be -1 and the user application is expected to actually load the file. DataLoad 'No Load' flag FALSE = data file is loaded in a heap block and the name and address is returned to the user application. TRUE = only the data file name and type is returned to the user application. This flag is provided for maximum flexibility when dealing with drag loads. When you are converting an existing program to run under the EvntShell system you may already have a working load routine. In this case set the flag to TRUE and when a drag load occurs your application will be told the filename, which may then be loaded and processed as required. When this flag is FALSE the library routines will reserve a memory block for the file and load it automatically. For the technical of you out there the library stores the status of the no load flag in the top bit of the filetype number. This will end in tears when RISC-OS 4 comes out... -------------------------------------------------------- PROCshell_AttachDataSave() Attaches a datasave handler to a window/icon pair. A typical use would be in a 'Save As' dialog box, the icon handle being that of the 'File Type' icon. Params => int window handle int icon handle int address of heapblock holding data or the estimated file size int file type for saved file int icon nr of filename icon str function name (optional if data is held in a heapblock) If icon 0 in the window is clicked on then a check is made that the filename icon contains a valid path name, generating an error if it does not. Note that the third parameter can point to a heap block containing the data to save which means that the data must exist in the block (or at least the block must exist and be the correct size) before this routine is called. If this parameter is >&8000 it is taken to be a pointer to the heap block , and the name of the function to perform the save is optional. The specified function will be called in this case. Alternatively this parameter can be an estimated file size (i.e. <&8000) in which case the user function may write directly into the file whose name is given as a parameter to the function. RAM transfer is not possible if this is the case. The button type of the filetype icon is automatically changed to click/drag. User FN (PROCshell_AttachDataSave) Params => str full filename of file This function is not called if the file is stored in a heap block. In this case the whole contents of the heap block are transferred. Estimated File Sizes It should (if other applications are written to the Acorn guidelines!) not matter if this estimate is inaccurate. However, file transfer will be a little faster if it is accurate and problems may occur with badly written applications if it is not. -------------------------------------------------------- PROCshell_AttachClickSelect() Params => int window handle int icon handle str function name User FN (PROCshell_AttachClickSelect) Params => int window handle int icon handle -------------------------------------------------------- PROCshell_AttachClickAdjust() Params => int window handle int icon handle str function name User FN (PROCshell_AttachClickAdjust) Params => int window handle int icon handle -------------------------------------------------------- PROCshell_AttachUserRedraw() Params => int window handle str function name A check is made to ensure that the 'Auto redraw' flag of the window is off, and the flag is cleared automatically if necessary (i.e. you don't have to use !FormEd or similar to set the flag correctly) User FN (PROCshell_AttachUserRedraw) Params => int address of block returned by redraw request int x origin of window (screen coords) int y origin of window (screen coords) The function to call when a redraw request is made. -------------------------------------------------------- PROCshell_AttachDrag() Params => int window handle int icon handle str function name User FN (FNshell_AttachDrag) Params => int window handle over which drag started int icon handle over which drag was started (-1 for no icon) -------------------------------------------------------- PROCshell_AttachHelpTag() Params => int window handle int icon handle str <message tag=>MessageTag> Note that any message tags found in icon validation strings override tags set up by this routine. -------------------------------------------------------- PROCWimpCloseDown Params => None Not used in EvntShell library - use <PROCshell_WimpCloseDown_I> instead. -------------------------------------------------------- PROCshell_WimpCloseDown_I Params => None Called when the application shuts down (the library calls this automatically) -------------------------------------------------------- PROCshell_AttachBumpHandler() Params => int window handle int icon handle (display value) int icon handle (increment value) int icon handle (decrement value) int lower limit int upper limit int step bool wrap flag str function name 1 (can be "") str function name 2 (can be "") Bump icons are the arrows that allow you to alter the value displayed in an icon (usually but not necessarily a writable one). Note that a click on a bump icon with ADJUST has the opposite effect to a click with SELECT. Pressing SHIFT while clicking on a bump icon will double the step value, CTRL will make the step 4 times larger, SHIFT and CTRL makes the step 8 times larger. User FN1 (PROCshell_AttachBumpHandler) Params => int value int mouse button pressed (SELECT = 4, ADJUST = 1 <= str converted value This function is called before the new value is placed in the display icon. An example would be converting an integer value to the format 0h00 (i.e hours and mins). DEF FN_dis_fn(val%) =STR$(val%DIV60)+"h"+RIGHT$("00"+STR$(val%MOD60),2) See the !VBase2 demo app. User FN2 (PROCshell_AttachBumpHandler) Params => str value to decode <= int converted value This function is called before the new value is placed in the display icon. An example would be converting a string "0h00" back to an integer value. DEF FN_decode_dis(val$) =VAL(val$)*60+VAL(RIGHT$(val$,2)) See the !VBase2 demo app. -------------------------------------------------------- PROCshell_AttachHotKey() Params => str key bool shift flag bool ctrl flag bool alt flag str window identifier int window handle str function name str function name Sets up a 'hotkey' event. Function keys F0-F11 (note NOT F12 as the task manager uses it under RISC-OS 3) are supported. User FN (PROCshell_AttachHotKey) Params => int window handle The function to call before opening the window. A function name of "" may be used if you don't need to call a function. This would normally be used to fill in icon fields and set the state of radio buttons User FN (PROCshell_AttachHotKey) Params => int window handle The function to call after opening the window. A function name of "" may be used if you don't need to call a function. Key (PROCshell_AttachHotKey) The key string normally consists of one ASCII character i.e. "R". When the ctrl flag is set this would cause the actions to be carried out when CTRL-R is pressed. The string may also contain "F1" to "F11" to allow function keys to be used. No checking is performed on the string. Window (PROCshell_AttachHotKey) The window identifier specifies the name of the window you want to appear when the keypress is received. This parameter is optional as you might not always want to open a window. The window is a 'dynamic' dialog box which will disappear when <ESC> is pressed and is opened in such a position that the mouse pointer is in the middle of the window (where possible). Window Handle (shell_AttachHotKey) When this is >0 then the window created will be static i.e. it will not be removed when the mouse is clicked outside it, or when <ESC> is pressed. -------------------------------------------------------- PROCshell_DoBackgroundTask Params => None Called everytime a null reason code is received -------------------------------------------------------- PROCshell_HandleUnknownMessage() Params => int address of message block Called every time an unknown message is received. -------------------------------------------------------- PROCshell_AttachCloseWindowHandler() Params => int window handle str function name Registers a function name to be called when an CloseWindow message is received. This is useful to prevent the window closing if so doing would involve loss of data. This message is issued when the window close icon is clicked on. User FN (PROCshell_AttachCloseWindowHandler) Params => None <= bool 0 to disallow close, non 0 to close -------------------------------------------------------- PROCshell_AttachOpenWindowHandler() Params => int window handle str function name Registers a function name to be called when an OpenWindow message is received. This is useful so that the application can set a flag to avoid doing window redraws while the window is closed for example. This message is issued when the window is dragged around the screen as well as when the program opens the window. You should avoid doing time consuming stuff in the function that is called therefore. User FN (PROCshell_AttachOpenWindowHandler) Params => None <= bool 0 to disallow open, non 0 to open -------------------------------------------------------- PROCshell_AttachPreQuitHandler() Params => str function name Registers a function name to be called when a PreQuit message is received. This gives the application a chance to save data or abort the shutdown. This message is issued when the task is quit from the Task Manager, or when CTRL-SHIFT-F12 is pressed (under RISC OS 3). User FN (PROCshell_AttachPreQuitHandler) Params => None <= bool non 0 to allow quit, 0 to cancel quit This function is called when a PreQuit message is received. -------------------------------------------------------- PROCshell_AttachColourPopupMenu() Params => int window handle int menu icon handle int display icon handle int menu handle str user function (optional) Provides for automatic updating of a display icon when a selection is made from the attached colour menu. If a user function name is not supplied then the display icon shows the selected menu item background colour. The button type of the menu icon is changed to 3 to ensure the menu opens when <SELECT> is used. -------------------------------------------------------- PROCshell_AttachPopupMenu() Params => int window handle int menu icon handle int display icon handle int menu handle str user function (optional) Provides for automatic updating of a display icon when a selection is made from the attached menu. If a user function name is not supplied then the display icon shows the selected menu item text. The button type of the menu icon is changed to 3 to ensure the menu opens when <SELECT> is used. -------------------------------------------------------- PROCshell_AttachPopupDatePicker() Params => int window handle int menu icon handle int display icon handle (may be -1) str notify FN (may be "") This popup displays a Calendar for the current month (although the month may be incremented and decremented) enabling the selection of a date. To use this popup two extension libraries must be loaded, CalLib and DatePick. This can be done as follows: void% = FNshell_InstallLib( "<EvntShell$Path> Extensions.CalLib" ) void% = FNshell_InstallLib( "<EvntShell$Path> Extensions.DatePick" ) In addition a template called 'datepicker' must exist in the loaded template file. This can be found in the !EvntShell application in the directory Resources.UK.Templates.2D and 3D. The appearance may be edited but the icons may not be renumbered. The message file must also include the following tokens: #message strings for CalLib monthstr:JanFebMarAprMayJunJulAugSepOctNovDec daystr:SunMonTueWedThuFriSat today:Today User FN (PROCshell_AttachPopupDatePicker) Params => str date in dd.mm.yy format This function is called when a valid selection has been made in the DatePicker popup. If this function is supplied then it is up to your application to act on the returned date. Otherwise the specified display icon is updated with the string. -------------------------------------------------------- FNEvnts_GetLastMouseButtonClicked() Params => None Returns the value of the last mouse button pressed. 4 = SELECT, 2 = MENU, 1 = ADJUST -------------------------------------------------------- PROCshell_AttachIconWatch() => int window handle int icon handle str function to call when value changes User FN (PROCshell_AttachIconWatch) => str new icon contents <= int no meaning -------------------------------------------------------- PROCshell_AttachMenuHelpTag() => str menu name int item handle str message tag This facility is only available under Risc OS 3 or later. --------------------------------------------------------