RISC DISC 1

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

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

Wrap

Text File | 1993-05-24 | 13.2 KB | 309 lines

Defined PopUp handlers ====================== The following are all of the PopUp TYPES which are currently defined. (If you wish to write your own PopUp check if there is another PopUp TYPE which you can emulate, so you can replace that other PopUp, rather than creating a completely new type with a new interface. This will maximise the interconnectability of applications and PopUps. If you are designing a new type of PopUp, then please consider the interface carefully, and try to make it as generalised as possible (within reason!) so that similar PopUps can be written to provide similar functions without compatability problems) The currently defined PopUp types are listed below. Note that the name given is the PopUp identifier string to pass in to PopUp_Open. menu PopUps Magnify Standard magnifier (ratio setting device, e.g "1:2") Print Simple 'Print' dialogue (as in !Draw) ProgInfo Program Information window (display only) Report Multitasking problem/message reporting window SaveAs Standard save-as window (file icon, writable, OK button) TrueColour Colour picker for picking a TRUE colour (full 24-bit RGB) WimpColour Colour picker for picking a WIMP colour (16 colours) SetValue Window allowing you to set a value in some manner (Possibly a writable, a slider, etc) static PopUps FontSelect Font selector window These PopUp types are controlled by the 'popup specific' portion of the application parameter block that you pass to SWI "PopUp_Open". This 'popup specific' data is also the layout used in Message_PopUpStatus. Magnify ------- This is a simple magnifier PopUp. Note that by Acorn's definition, a magnifier should cause an instant effect if the 'bump' arrows are clicked. Thus, the magnifier PopUp will send you a PopUpState message whenever such an action occurs - do not assume that such a message signals that the PopUp is closed! The magnifier can be opened as either a MENU or STATIC PopUp Block extension: R0 + 24 Multiplier part of fractional magnification R0 + 28 Divisor part of fractional magnification R0 + 32 Minimum multiplier value R0 + 36 Maximum multiplier value R0 + 40 Minimum divisorr value R0 + 44 Maximum divisor value R0 + 48 Title string for magnifier window. This should be no more than 12 chars including the terminator, (in fact, less than that as the window title area is quite small) The multiplier is not allowed outside the bounds of min_mul and max_mul. The divisor is not allowed outside the bounds of min_div and max_div. (These values are all INCLUSIVE) It is up to you to ensure that the limits have reasonable values. Print ----- This supplies a simple 'print' dialogue similar to the one in !Draw. It displays the name of the current printer driver (or 'No printer driver installed' type message), allows the user to enter the number of copies to print, and has an OK button to initiate the print. This PopUp can only be shown as a MENU PopUp. If a printer driver is running and the user clicks OK, the state will be returned to you indicating the number of copies to print. On receipt of this message you should print. The block extension contains: R0 + 24 (word) number of copies to print. You should set this to 1 initially. ProgInfo -------- This simply supplies a standard Program Information window. ProgInfo can only be opened as a MENU PopUp. The block extension contains 4 0/CR-terminated strings which must be no longer than 32 characters (including the terminator): R0 + 24 Program name [Frooble ] R0 + 56 Purpose [To provide desktop froobles ] R0 + 88 Author name [© Copyright 1993 J.Williams ] R0 + 120 Version number [1.00 (01 Apr 1993) ] This PopUp is a display-only PopUp, i.e. it will never send you a PopUpState message. Thus, you may open it with SWI "PopUp_Open", and completely forget about it. Report ------ Report can be opened as a MENU or STATIC popup. Opening it as a Menu LEAF is generally regarded as silly (to be precise, it will fail to open at all) This supplies a window similar to the Wimp_ReportError dialogue. However, there are several significant differences: You can set the Ok/Cancel text, the window is a 'menu' PopUp, so can be cancelled with escape/click-outside, etc, and most importantly this PopUp multitasks while it is operating. You ideally should call this PopUp from a function which includes its own Wimp_Poll loop - this can then 'vet' WIMP events and only allow 'safe' events (such as redraws) through to your normal event handlers. You should continue in this special event loop until the Report PopUp is removed. The block extension contains: R0 + 24: Flags: Set bit 1 to have a cancel button, and bit 2 to have an OK button. Valid flags are therefore: 1 = cancel only 2 = ok only 3 = both OK and cancel Invalid flags will be treated as a '3'. The top 24 bits of the flagword should be set to a value which is unique and meaningful to you. (This should be used to handle re-entrant error reporting). i.e. to set a value of 1, and get OK & cancel, set flags to (1 << 8) + 3 R0 + 28: Text for 'OK' button (not more than 11 chars + terminator) R0 + 40: Text for 'Cancel' button (not more than 11 chars + terminator) R0 + 52: Application name for titlebar ("Message from <application>") (not more than 11 chars + terminator) If this string is blank (the first char is a terminator) then the titlebar will read 'Message' or something similar. R0 + 64: Brief message for the user. This will be wrapped over several lines if necessary. (Not more than 187 characters + terminator) This PopUp will return a Message_PopUpState whenever it is closed to let you know when you can resume normal polling. The message body in this case will contain: block + 20 PopUp handle (as usual) block + 24 "Report" (As usual, the PopUp id string, 12 characters) block + 36 bits 0-7 (block!36 AND &FF) are the return flags: 1 = Cancel was selected 2 = OK was selected The top 24 bits return the id number you passed in originally SaveAs ------ SaveAs gives a standard 'save as' box, allowing file drag or ok click to save. SaveAs can only be opened as a MENU PopUp. The block extension for Save as includes two strings, both either 0 or CR (13) terminated. R0 + 24 12 character string: Name of icon sprite to display in window Note - the icon sprite should exist in the WIMP sprite pool. If this sprite is not available, "file_xxx" will be used instead. R0 + 36 String to place into filename writable icon (max length 196 characters including terminator) This will start a DragASprite drag of the icon, and send you a PopUpState message with the following data in it: block + 20 PopUp handle (as usual) block + 24 PopUp type/name string ("SaveAs") block + 36 flag word: bit 0 (value &01): 0 = file dragged, 1 = OK clicked bit 1 (value &02): SHIFT key status - 1 means SHIFT was held down when the drag was started. block + 40 reserved block + 44 zero-terminated file name string copied back out of the save-as windows writable icon. If the file icon was dragged, this is a leaf-name, else it is the full writable contents. This string will have all illegal filename characters either removed or replaced by legal chars. To save data, you thus will open a SaveAs PopUp, and when you recieve the above message, you will use GetPointerState to read the pointer position, and can then build a message_datasave to initiate further action for the save. Note that the filename already occurs at block + 44, to make it convenient to build a message_datasave around it in the block. (C programmers - if using RISC OS Lib, you can call a function like "xfersend" when you recieve this message, and it will immediately start the transfer when it realises that the mouse button is not down - it won't start another drag) The flag indicating SHIFT key status is intended for the following use: In the filer, dragging a file icon between windows results in a copy of the file being made. By holding down SHIFT, the file is moved instead, so that the source file is removed. The SaveAs window is supposed to be like a small filer window, so it seems reasonable that the operation of "save and then close the document" should take place if you shift-drag from the window. This is a handy 'short cut', and is very intuitive (as it simply makes the SaveAs window more consistent with the rest of the desktop). It is also a difficult action to apply by accident. Note however, that the document should only be closed if the file is 'safe', i.e. successfully saved to a non-temporary location. NOTES: 1 If the user 'drops' that save-as icon into the save-as window, nothing will happen (the window stays open). However, if it is dropped elsewhere you will get the state message - you should check (handle) the case where the user has dragged to another of your windows/menus etc. 2 If the user clicks OK/presses return, the PopUp will check if the file name in the writable looks like a full pathname (This is currently a very simple check - does the text include a '.' character): If not, it will report an error using the 'Report' PopUp (To save, drag icon to directory viewer), and will NOT return a state message to you. (i.e. if you get a state message, just go ahead and save) 3 The SaveAs window has a validation string to stop the user entering invalid characters such as @#%^&* The SaveAs PopUp also scans the filename string before returning it to you, replacing spaces (invalid in filenames) with hard-space characters (which are valid in filenames), etc. Exactly what this scan does is implementation defined, but it is likely to do more in the future to make filenames 'foolproof' for you. (i.e. if you get a state message, just go ahead and save!) 4 SaveAs will do a DragASprite, if that is configured on. Under RISC OS 2, or if DragASprite is disabled, SaveAs will do a normal 'dotted box' drag. Well, actually, the dotted box seems to be missing under RISC OS 2, and I can't make it appear... This may improve in a future release. TrueColour ---------- TrueColour can be opened as a MENU or STATIC PopUp. This provides a 'true colour' (24-bit RGB) colour picker, which allows picking of colours from a 16-million colour palette, plus up to 256 transparency levels The user can swap between several different colour models in some manner (radio buttons or the like). The setting of colour model when the window is closed should be remembered by the application as the default setting the next time it is opened. The application can also define initial colours and recieve resulting colours back in any of the supported formats, and the PopUp will handle the conversions necessary between the displayed and returned formats. More options for which colour model to use may become available as this colour picker is extended, but the current models are: No. | Colour model -------|----------------- &00000 | RGB [With no transparency options at all] &00001 | HSV &00002 | CMYK &10000 | RGB [With 'none' colour option] &10001 | HSV &10002 | CMYK &20000 | RGB [With 256 levels of transparency] &20001 | HSV &20002 | CMYK Block extension (3 words): R0 + 24 Colour model number (as defined above) R0 + 28 Colour as represented in the given colour model (see below) R0 + 32 Transparency value (0 = not transparent, 255 = totally seethrough) Colour Representation RGB: Colourtrans style colour word, with transparency represented by the bottom byte (0 = no transparency, &FF = totally transparent) R0 + 28: &BBGGRRTT (one byte each for B, G, R, and T) (yes, the transparency info is duplicated) CMYK: R0 + 28: &CCMMYYKK HSV: R0 + 28: &HHHHSSVV Hue: 0..360, Saturation: 0..255, Value 0..255 WimpColour ---------- This provides a small square window divided into 16 coloured squares, one for each WIMP colour. A dot is drawn on the current selection. Users may choose any WIMP colour. Each time a different colour is selected, a PopUpStatus message is sent to the client application, containing the new colour. WimpColour can only be opened as a MENU PopUp. Block extension: R0 + 24 (byte) WIMP colour number (integer in range 0..15 inclusive) Note that if the WIMP colour number supplied is outside the range 0..15, then the WimpColour PopUp will default to the last value it displayed - this of course may have been from another program using PopUps!