home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / s1 / shadowlib / ShadowLib / Manual next >
Text File  |  1994-05-16  |  9KB  |  260 lines
  1.                           ShadowLib Version 1.01
  2.  
  3.      This document is a manual file to accompany the BASIC V procedure 
  4.      library Shadows. It attempts to provide instructions for utili-
  5.      sing the library.
  6.  
  7.      Introduction
  8.      ------------
  9.           ShadowLib is a BASIC V procedure library containing a set of 
  10.      procedures to display a "shadow" behind a window during a drag 
  11.      when "instant effect" drags are configured.
  12.            ShadowLib has been tested successfully with RISC OS versions 
  13.      2, 3.00 and 3.1. 
  14.  
  15.      Licence
  16.      -------
  17.           ShadowLib is FREEWARE ie it may be freely distributed as long 
  18.      as no charge is made for it and it remains unchanged. I do not 
  19.      require that the documentation and demonstration application be 
  20.      distributed with the library BUT I do require that I am fully 
  21.      credited in your documentation and !Help file.
  22.           Note - at all times I, Simon J. Osborne, retain copyright on 
  23.      the library and its accompanying demonstration and documentation.
  24.  
  25.           This software is supplied as is and with no guarantee what so
  26.      ever. At no time shall the author be liable for any loss or damage
  27.      caused by the use, misuse or abuse of this application
  28.  
  29.      Important
  30.      ---------
  31.           Before detailing the use of the library please take note of 
  32.      the following important points :-
  33.  
  34.           All procedure names within the library begin Shadow_
  35.           All function names within the library begin Shadow_
  36.           All variable names within the library begin shadow_
  37.  
  38.           Thus any PROC/FN names beginning Shadow_ and any variable 
  39.      names beginning shadow_ should be treated as reserved and NOT 
  40.      used by your program.
  41.           Additionally when using the library DO NOT mask out NULL 
  42.      events in your calls to Wimp_Poll or Wimp_PollIdle.
  43.  
  44.      Limitations
  45.      -----------
  46.           Currently ShadowLib will only function for windows that have 
  47.      a title bar, and it only supports a single nested window.
  48.  
  49.      Use
  50.      ---
  51.           First load the library into your application by adding a 
  52.      line similar to the following near the beginning of your program :
  53.  
  54.           LIBRARY '<Application$Dir>.ShadowLib'
  55.  
  56.      To utilise the library your program should be something like this 
  57.      (this is a very rough approximation to show where the library 
  58.      should be called, for full details of the procedures see below) :
  59.  
  60.  
  61.      REM initialisation
  62.        LIBRARY '<Application$Dir>.ShadowLib'
  63.        PROCShadow_Init
  64.      .
  65.      .
  66.      REM poll loop
  67.        REPEAT
  68.          SYS "Wimp_Poll",0,poll_block% TO reason%
  69.          CASE reason% OF
  70.            .
  71.            .
  72.            WHEN 2 : PROCShadow_PreOpen
  73.                     SYS "Wimp_OpenWindow",,poll_block%
  74.                     PROCShadow_PostOpen(poll_block%,-1)
  75.            WHEN 3 : SYS "Wimp_CloseWindow",,poll_block%
  76.                     PROCShadow_Close(poll_block%)
  77.            .
  78.            .
  79.            .
  80.          ENDCASE
  81.          PROCShadow_Poll(reason%)
  82.        UNTIL finished
  83.      END
  84.  
  85.      Procedures 1 (Essential)
  86.      ------------------------
  87.           The following are descriptions of the above essential 
  88.      procedures and their parameters
  89.  
  90.      PROCShadow_Init
  91.  
  92.      Call:          This should be called once, and once only, after 
  93.                     the library has been loaded, and after a call to 
  94.                     SYS "Wimp_Initialise" but before the Wimp_Poll 
  95.                     loop is entered.
  96.  
  97.      Purpose:       Initialisation of the library and its variables 
  98.                     etc.
  99.  
  100.      Parameters:    None.
  101.  
  102.      PROCShadow_PreOpen
  103.  
  104.      Call:          After open window request but before calling 
  105.                     Wimp_OpenWindow.
  106.  
  107.      Purpose:       Check to determine if a drag is in progress.
  108.  
  109.      Parameters:    None.
  110.  
  111.      PROCShadow_PostOpen(poll_block%,handle%)
  112.  
  113.      Call:          After open window request and after call to 
  114.                     Wimp_OpenWindow.
  115.  
  116.      Purpose:       Update the windows shadow.
  117.  
  118.      Parameters:    Block returned by wimp_poll for open window 
  119.                     request, handle of nested sub-window in front of 
  120.                     this window or -1 for no sub-window.
  121.  
  122.      PROCShadow_Close(poll_block%)
  123.  
  124.      Call:          After close window request and call to 
  125.                     Wimp_CloseWindow.
  126.  
  127.      Purpose:       Remove shadow if required.
  128.  
  129.      Parameters:    Block returned by wimp_poll for close window 
  130.                     request.
  131.  
  132.      PROCShadow_Poll(reason%)
  133.  
  134.      Call:          At the end of the wimp poll loop, just before 
  135.                     looping back.
  136.  
  137.      Purpose:       House keeping.
  138.  
  139.      Parameters:    Reason code returned by Wimp_Poll.
  140.  
  141.      Procedures 2 (Optional)
  142.      -----------------------
  143.           The following are descriptions of procedures which are not 
  144.      essential to the operation of the library but are used to tune 
  145.      its operation.
  146.  
  147.      PROCShadow_On
  148.  
  149.      Call:          As required.
  150.  
  151.      Purpose:       Switch on shadowing of a dragged window. Note this 
  152.                     procedure is called automatically by 
  153.                     PROCShadow_Init.
  154.  
  155.      Parameters:    None
  156.  
  157.      PROCShadow_Off
  158.  
  159.      Call:          As required.
  160.  
  161.      Purpose:       Switch off shadowing of a dragged window.
  162.  
  163.      Parameters:    None.
  164.  
  165.      PROCShadow_SetEndDelay(delay%)
  166.  
  167.      Call:          After PROCShadow_Init, as required.
  168.  
  169.      Purpose:       Set delay at end of drag before shadow is removed.
  170.  
  171.      Parameters:    An integer delay, this is roughly the number of 
  172.                     passes through the wimp poll loop before the 
  173.                     shadow is removed. The default (set in 
  174.                     PROCShadow_Init) is 2.
  175.       
  176.      Notes, Further Limitations and Suggestions
  177.      ------------------------------------------
  178.           If your application contains any windows which are not 
  179.      redrawn solely by the wimp manager you should call 
  180.      PROCShadow_SetEndDelay and increase the delay otherwise the 
  181.      shadowing effect may be lost. This is particularly important if 
  182.      your application contains several windows which will generate 
  183.      redraw events and which can be moved over each other.
  184.  
  185.           The library does not shadow any menus opened by your 
  186.      application but, it will shadow any windows opened as sub-menus 
  187.      eg Info boxes.
  188.  
  189.           As shadowing a window will slow down a drag, you should 
  190.      should include an option to allow the user to switch the shadows 
  191.      off, this is particularly important on ARM2 machines where the 
  192.      slowing effect is more noticeable.
  193.  
  194.           Tool boxes attached to the bottom of a window will obscure 
  195.      the shadow, as will tool boxes attached to the right.
  196.  
  197.           On RISC OS 3/3.1 the use of larger than normal sprites for 
  198.      the window tools will also obscure the shadow.
  199.  
  200.           Sub-windows/tool boxes should be handled as followed, if 
  201.      you are using the Wimp Extension modules just called 
  202.      "WimpExt_OpenLinked" instead of "Wimp_OpenWindow" (assuming that 
  203.      you have previously linked the windows). If you are manually 
  204.      linking windows then either call PROCShadow_PostOpen immediately
  205.      after opening the main window or open the sub-window/tool box and 
  206.      call "Wimp_GetWindowState" for the main window before calling 
  207.      PROCShadow_PostOpen.
  208.  
  209.           It may be possible to have both a sub-window and a tool box 
  210.      if the tool box is "behind" the window it is attached to in the 
  211.      stack of windows. NB this has NOT been tested.
  212.  
  213.           Your program will almost certainly receive redraw events for 
  214.      the shadow window, these can be ignored.
  215.  
  216.      The Future
  217.      ----------
  218.           This is a short list of things which I intend to include in 
  219.      a future version of ShadowLib (If and when I get around to 
  220.      writing it):
  221.  
  222.                User selectable shadow colour.
  223.  
  224.                User selectable shadow offset.
  225.                     (For two reasons: to allow the shadow to be other 
  226.                     than bottom-right and to allow for tool boxes on 
  227.                     the bottom or right of a window)