home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / windows / b007_1 / Docs / 4%a0PopUps < prev    next >
Text File  |  1993-05-25  |  13KB  |  309 lines
  1. Defined PopUp handlers
  2. ======================
  3.  
  4. The following are all of the PopUp TYPES which are currently defined.
  5.   (If you wish to write your own PopUp check if there is another PopUp TYPE
  6.   which you can emulate, so you can replace that other PopUp, rather than
  7.   creating a completely new type with a new interface. This will maximise the
  8.   interconnectability of applications and PopUps.
  9.  
  10.   If you are designing a new type of PopUp, then please consider the interface
  11.   carefully, and try to make it as generalised as possible (within reason!)
  12.   so that similar PopUps can be written to provide similar functions without
  13.   compatability problems)
  14.  
  15. The currently defined PopUp types are listed below. Note that the name
  16. given is the PopUp identifier string to pass in to PopUp_Open.
  17.  
  18.  menu PopUps
  19.     Magnify       Standard magnifier (ratio setting device, e.g "1:2")
  20.     Print         Simple 'Print' dialogue (as in !Draw)
  21.     ProgInfo      Program Information window (display only)
  22.     Report        Multitasking problem/message reporting window
  23.     SaveAs        Standard save-as window (file icon, writable, OK button)
  24.     TrueColour    Colour picker for picking a TRUE colour (full 24-bit RGB)
  25.     WimpColour    Colour picker for picking a WIMP colour (16 colours)
  26.  
  27.     SetValue      Window allowing you to set a value in some manner
  28.                   (Possibly a writable, a slider, etc)
  29.  
  30.   static PopUps
  31.     FontSelect    Font selector window
  32.  
  33. These PopUp types are controlled by the 'popup specific' portion of the
  34. application parameter block that you pass to SWI "PopUp_Open".
  35. This 'popup specific' data is also the layout used in Message_PopUpStatus.
  36.  
  37.  
  38. Magnify
  39. -------
  40.  
  41. This is a simple magnifier PopUp. Note that by Acorn's definition, a magnifier
  42. should cause an instant effect if the 'bump' arrows are clicked. Thus, the
  43. magnifier PopUp will send you a PopUpState message whenever such an action
  44. occurs - do not assume that such a message signals that the PopUp is closed!
  45.  
  46. The magnifier can be opened as either a MENU or STATIC PopUp
  47.  
  48. Block extension:
  49.     R0 + 24  Multiplier part of fractional magnification
  50.     R0 + 28  Divisor part of fractional magnification
  51.  
  52.     R0 + 32  Minimum multiplier value
  53.     R0 + 36  Maximum multiplier value
  54.  
  55.     R0 + 40  Minimum divisorr value
  56.     R0 + 44  Maximum divisor value
  57.  
  58.     R0 + 48  Title string for magnifier window.
  59.              This should be no more than 12 chars including the terminator,
  60.              (in fact, less than that as the window title area is quite small)
  61.  
  62. The multiplier is not allowed outside the bounds of min_mul and max_mul.
  63. The divisor is not allowed outside the bounds of min_div and max_div.
  64. (These values are all INCLUSIVE)
  65. It is up to you to ensure that the limits have reasonable values.
  66.  
  67.  
  68. Print
  69. -----
  70.  
  71. This supplies a simple 'print' dialogue similar to the one in !Draw.
  72. It displays the name of the current printer driver (or 'No printer driver
  73. installed' type message), allows the user to enter the number of copies
  74. to print, and has an OK button to initiate the print.
  75.  
  76. This PopUp can only be shown as a MENU PopUp.
  77.  
  78. If a printer driver is running and the user clicks OK, the state will be
  79. returned to you indicating the number of copies to print. On receipt of this
  80. message you should print.
  81.  
  82. The block extension contains:
  83.     R0 + 24  (word) number of copies to print. You should set this to 1
  84.              initially.
  85.  
  86.  
  87. ProgInfo
  88. --------
  89.  
  90. This simply supplies a standard Program Information window.
  91.  
  92. ProgInfo can only be opened as a MENU PopUp.
  93.  
  94. The block extension contains 4 0/CR-terminated strings which must be no
  95. longer than 32 characters (including the terminator):
  96.  
  97.     R0 + 24  Program name   [Frooble                        ]
  98.     R0 + 56  Purpose        [To provide desktop froobles    ]
  99.     R0 + 88  Author name    [© Copyright 1993 J.Williams    ]
  100.     R0 + 120 Version number [1.00 (01 Apr 1993)             ]
  101.  
  102. This PopUp is a display-only PopUp, i.e. it will never send you a PopUpState
  103. message. Thus, you may open it with SWI "PopUp_Open", and completely forget
  104. about it.
  105.  
  106.  
  107. Report
  108. ------
  109.  
  110. Report can be opened as a MENU or STATIC popup.
  111. Opening it as a Menu LEAF is generally regarded as silly (to be precise,
  112. it will fail to open at all)
  113.  
  114. This supplies a window similar to the Wimp_ReportError dialogue. However,
  115. there are several significant differences: You can set the Ok/Cancel text, the
  116. window is a 'menu' PopUp, so can be cancelled with escape/click-outside, etc,
  117. and most importantly this PopUp multitasks while it is operating.
  118.  
  119. You ideally should call this PopUp from a function which includes its own
  120. Wimp_Poll loop - this can then 'vet' WIMP events and only allow 'safe' events
  121. (such as redraws) through to your normal event handlers. You should continue
  122. in this special event loop until the Report PopUp is removed.
  123.  
  124. The block extension contains:
  125.     R0 + 24: Flags: Set bit 1 to have a cancel button, and bit 2 to have
  126.              an OK button. Valid flags are therefore:
  127.                1 = cancel only
  128.                2 = ok only
  129.                3 = both OK and cancel
  130.              Invalid flags will be treated as a '3'.
  131.              The top 24 bits of the flagword should be set to a value which
  132.              is unique and meaningful to you. (This should be used to
  133.              handle re-entrant error reporting). i.e. to set a value of
  134.              1, and get OK & cancel, set flags to (1 << 8) + 3
  135.  
  136.     R0 + 28: Text for 'OK' button (not more than 11 chars + terminator)
  137.     R0 + 40: Text for 'Cancel' button (not more than 11 chars + terminator)
  138.     R0 + 52: Application name for titlebar ("Message from <application>")
  139.              (not more than 11 chars + terminator)
  140.              If this string is blank (the first char is a terminator) then
  141.              the titlebar will read 'Message' or something similar.
  142.     R0 + 64: Brief message for the user. This will be wrapped over several
  143.              lines if necessary. (Not more than 187 characters + terminator)
  144.  
  145. This PopUp will return a Message_PopUpState whenever it is closed to let
  146. you know when you can resume normal polling. The message body in this case
  147. will contain:
  148.     block + 20  PopUp handle (as usual)
  149.     block + 24  "Report" (As usual, the PopUp id string, 12 characters)
  150.     block + 36  bits 0-7 (block!36 AND &FF) are the return flags:
  151.                          1 = Cancel was selected
  152.                          2 = OK was selected
  153.                 The top 24 bits return the id number you passed in originally
  154.  
  155.  
  156. SaveAs
  157. ------
  158.  
  159. SaveAs gives a standard 'save as' box, allowing file drag or ok click to save.
  160. SaveAs can only be opened as a MENU PopUp. 
  161.  
  162. The block extension for Save as includes two strings, both either 0 or CR (13)
  163. terminated.
  164.  
  165.     R0 + 24  12 character string: Name of icon sprite to display in window
  166.              Note - the icon sprite should exist in the WIMP sprite pool.
  167.              If this sprite is not available, "file_xxx" will be used instead.
  168.     R0 + 36  String to place into filename writable icon
  169.              (max length 196 characters including terminator)
  170.  
  171.     This will start a DragASprite drag of the icon, and send you a PopUpState
  172.     message with the following data in it:
  173.  
  174.        block + 20  PopUp handle (as usual)
  175.        block + 24  PopUp type/name string ("SaveAs")
  176.  
  177.        block + 36  flag word:
  178.                    bit 0 (value &01):  0 = file dragged, 1 = OK clicked
  179.                    bit 1 (value &02):  SHIFT key status - 1 means SHIFT was
  180.                                        held down when the drag was started.
  181.        block + 40  reserved
  182.        block + 44  zero-terminated file name string copied back out of the
  183.                    save-as windows writable icon. If the file icon was dragged,
  184.                    this is a leaf-name, else it is the full writable contents.
  185.                    This string will have all illegal filename characters
  186.                    either removed or replaced by legal chars.
  187.  
  188.     To save data, you thus will open a SaveAs PopUp, and when you recieve
  189.     the above message, you will use GetPointerState to read the pointer
  190.     position, and can then build a message_datasave to initiate further
  191.     action for the save. Note that the filename already occurs at block + 44,
  192.     to make it convenient to build a message_datasave around it in the block.
  193.  
  194.     (C programmers - if using RISC OS Lib, you can call a function like
  195.     "xfersend" when you recieve this message, and it will immediately start
  196.     the transfer when it realises that the mouse button is not down - it
  197.     won't start another drag)
  198.  
  199.     The flag indicating SHIFT key status is intended for the following use:
  200.       In the filer, dragging a file icon between windows results in a copy
  201.       of the file being made. By holding down SHIFT, the file is moved
  202.       instead, so that the source file is removed. The SaveAs window is
  203.       supposed to be like a small filer window, so it seems reasonable that
  204.       the operation of "save and then close the document" should take place
  205.       if you shift-drag from the window. This is a handy 'short cut', and
  206.       is very intuitive (as it simply makes the SaveAs window more consistent
  207.       with the rest of the desktop). It is also a difficult action to
  208.       apply by accident. Note however, that the document should only be closed
  209.       if the file is 'safe', i.e. successfully saved to a non-temporary
  210.       location.
  211.  
  212.     NOTES:
  213.     1 If the user 'drops' that save-as icon into the save-as window, nothing
  214.       will happen (the window stays open). However, if it is dropped elsewhere
  215.       you will get the state message - you should check (handle) the case
  216.       where the user has dragged to another of your windows/menus etc.
  217.  
  218.     2 If the user clicks OK/presses return, the PopUp will check if the
  219.       file name in the writable looks like a full pathname (This is currently
  220.       a very simple check - does the text include a '.' character): If not,
  221.       it will report an error using the 'Report' PopUp (To save, drag icon
  222.       to directory viewer), and will NOT return a state message to you.
  223.       (i.e. if you get a state message, just go ahead and save)
  224.  
  225.     3 The SaveAs window has a validation string to stop the user entering
  226.       invalid characters such as @#%^&*
  227.       The SaveAs PopUp also scans the filename string before returning it
  228.       to you, replacing spaces (invalid in filenames) with hard-space
  229.       characters (which are valid in filenames), etc.
  230.       Exactly what this scan does is implementation defined, but it is likely
  231.       to do more in the future to make filenames 'foolproof' for you.
  232.       (i.e. if you get a state message, just go ahead and save!)
  233.  
  234.     4 SaveAs will do a DragASprite, if that is configured on.
  235.       Under RISC OS 2, or if DragASprite is disabled, SaveAs will do a
  236.       normal 'dotted box' drag.
  237.       Well, actually, the dotted box seems to be missing under RISC OS 2,
  238.       and I can't make it appear... This may improve in a future release.
  239.  
  240.  
  241. TrueColour
  242. ----------
  243.  
  244. TrueColour can be opened as a MENU or STATIC PopUp.
  245.  
  246. This provides a 'true colour' (24-bit RGB) colour picker, which allows picking
  247. of colours from a 16-million colour palette, plus up to 256 transparency levels
  248.  
  249. The user can swap between several different colour models in some manner
  250. (radio buttons or the like). The setting of colour model when the window is
  251. closed should be remembered by the application as the default setting the
  252. next time it is opened.
  253.  
  254. The application can also define initial colours and recieve resulting colours
  255. back in any of the supported formats, and the PopUp will handle the
  256. conversions necessary between the displayed and returned formats.
  257.  
  258. More options for which colour model to use may become available as this
  259. colour picker is extended, but the current models are:
  260.  
  261.   No.    | Colour model
  262.   -------|-----------------
  263.   &00000 | RGB            [With no transparency options at all]
  264.   &00001 | HSV
  265.   &00002 | CMYK
  266.  
  267.   &10000 | RGB            [With 'none' colour option]
  268.   &10001 | HSV
  269.   &10002 | CMYK
  270.  
  271.   &20000 | RGB            [With 256 levels of transparency]
  272.   &20001 | HSV
  273.   &20002 | CMYK
  274.  
  275. Block extension (3 words):
  276.     R0 + 24  Colour model number (as defined above)
  277.     R0 + 28  Colour as represented in the given colour model (see below)
  278.     R0 + 32  Transparency value (0 = not transparent, 255 = totally seethrough)
  279.  
  280. Colour Representation
  281.   RGB:  Colourtrans style colour word, with transparency represented by the
  282.         bottom byte (0 = no transparency, &FF = totally transparent)
  283.         R0 + 28: &BBGGRRTT  (one byte each for B, G, R, and T)
  284.                             (yes, the transparency info is duplicated)
  285.  
  286.   CMYK: R0 + 28: &CCMMYYKK
  287.  
  288.   HSV:  R0 + 28: &HHHHSSVV  Hue: 0..360, Saturation: 0..255, Value 0..255
  289.  
  290.  
  291.  
  292. WimpColour
  293. ----------
  294.  
  295. This provides a small square window divided into 16 coloured squares, one
  296. for each WIMP colour. A dot is drawn on the current selection. Users may
  297. choose any WIMP colour. Each time a different colour is selected, a
  298. PopUpStatus message is sent to the client application, containing the new
  299. colour.
  300.  
  301. WimpColour can only be opened as a MENU PopUp.
  302.  
  303. Block extension:
  304.     R0 + 24 (byte) WIMP colour number (integer in range 0..15 inclusive)
  305.  
  306. Note that if the WIMP colour number supplied is outside the range 0..15,
  307. then the WimpColour PopUp will default to the last value it displayed -
  308. this of course may have been from another program using PopUps!
  309.