home *** CD-ROM | disk | FTP | other *** search
/ Really Useful CD 1 / ReallyUsefulCD1.iso / extras / progutils / baslib / baslibdoc / wimplib < prev   
Encoding:
Text File  |  1989-03-24  |  17.5 KB  |  579 lines
  1. Routine   : PROCclose_down
  2. Library   : WimpLib
  3. Purpose   : Shuts down the WIMP environment and   
  4.             generally restores things to normal   
  5. Source    : User
  6. Author    : Paul Hobbs
  7. Parameters:
  8.    None 
  9. Dependant Routines: 
  10.    None
  11. Global Variables:
  12.    None 
  13. Notes:
  14.    None 
  15. Routine   : FNcreatewindow(title$,flags%,fcol%, 
  16.             bcol%,maxx%,maxy%,l%,b%,r%,t%)
  17. Library   : WimpLib
  18. Purpose   : Creates a WIMP window 
  19. Source    : User
  20. Author    : Paul Hobbs
  21. Parameters:
  22.    title$   : text for window title bar
  23.    flags%   : various control flags, i.e. scroll 
  24.               bars or not etc
  25.    fcol%    : foreground colour of work area
  26.    bcol%    : background colour of work area
  27.    maxx%    : max work area extent x (+ve)
  28.    maxy%    : max work area extent y (+ve)
  29.    l%       : initial WAE x min
  30.    b%       : initial WAE y min
  31.    r%       : initial WAE x max
  32.    t%       : initial WAE y max  
  33. Dependant Routines:
  34.    None
  35. Global Variables:
  36.    block            : parameter block 
  37.    titlefgcol       : title bar fground colour
  38.    titlebgcol       : title bar bground colour
  39.    scrollbarfgcol   : scroll bar fground colour
  40.    scrollbarbgcol   : scroll bar bground colour
  41.    highlightbgcol   : title bar highlight when 
  42.                       window has input focus
  43. Notes: 
  44.    None
  45. Routine   : PROCupdatewindow(handle%,l%,b%,r%,t%)
  46. Library   : WimpLib
  47. Purpose   : Updates the specified area of the 
  48.             given window.
  49. Source    : User
  50. Author    : Paul Hobbs
  51. Parameters:
  52.    handle%  : handle of the window to update
  53.    l%       : WAE x min to update
  54.    b%       : WAE y min to update
  55.    r%       : WAE x max to update
  56.    t%       : WAE y max to update       
  57. Dependant Routines:
  58.    None
  59. Global Variables:
  60.    block            : parameter block  
  61. Notes: 
  62.    Ordinates are given in graphic units relative 
  63.    to the window origin (bottom left hand corner) 
  64. Routine   : PROCopenwindow(handle%,full%,front%)
  65. Library   : WimpLib
  66. Purpose   : Opens a previously created window 
  67. Source    : User
  68. Author    : Paul Hobbs
  69. Parameters:
  70.    handle%  : handle of the window to update
  71.    full%    : ? 
  72.    front%   : if TRUE window is on top of any 
  73.               others       
  74. Dependant Routines:
  75.    None
  76. Global Variables:
  77.    block            : parameter block  
  78. Notes: 
  79.    None 
  80. Routine   : PROCclosewindow(handle%) 
  81. Library   : WimpLib
  82. Purpose   : Temporarily closes the specified 
  83.             window which may be re-opened using 
  84.             PROCopenwindow(). 
  85. Source    : User
  86. Author    : Paul Hobbs
  87. Parameters:
  88.    handle%  : handle of the window to close 
  89. Dependant Routines:
  90.    FNoktoclosew(handle%)
  91. Global Variables:
  92.    block            : parameter block
  93. Notes: 
  94.    The function FNoktoclosew() appears in the main 
  95.    program and can be used to disallow window 
  96.    closing, multiple window closing  etc. It must 
  97.    be TRUE for the window to actually be closed.
  98. Routine   : PROCdeletewindow(handle%) 
  99. Library   : WimpLib
  100. Purpose   : Permanently removes the window whose 
  101.             handle is specified
  102. Source    : User
  103. Author    : Paul Hobbs
  104. Parameters:
  105.    handle%  : handle of the window to delete 
  106. Dependant Routines:
  107.    FNoktoclosew(handle%)
  108. Global Variables:
  109.    block            : parameter block
  110. Notes: 
  111.    The function FNoktoclosew() appears in the main 
  112.    program and can be used to disallow window 
  113.    closing, multiple window closing  etc. It must 
  114.    be TRUE for the window to actually be closed.
  115. Routine   : PROCcliprect(b, RETURN x1%,RETURN 
  116.             y1%,RETURN x2%,RETURN y2%) 
  117. Library   : WimpLib
  118. Purpose   : Sets up a graphics clip window? 
  119. Source    : User
  120. Author    : Paul Hobbs
  121. Parameters:
  122.    b        : address of parameter block    
  123. Dependant Routines:
  124.    PROClwaorigin(b,x0%,y0%)
  125. Global Variables:
  126.    None
  127. Notes: 
  128.    None 
  129. Routine   : FNpoll(mask%)
  130. Library   : WimpLib
  131. Purpose   : Central routine of any wimp program. 
  132.             Handles all user actions. 
  133. Source    : User
  134. Author    : Paul Hobbs
  135. Parameters:
  136.    mask%    : allows certain wimp events to be 
  137.               masked out. 0 means everything is 
  138.               allowed.
  139. Dependant Routines:
  140.    None
  141. Global Variables:
  142.    block            : parameter block
  143. Notes: 
  144.    None 
  145. Routine   : PROCaction(evnt%)
  146. Library   : WimpLib
  147. Purpose   : Handles events returned by FNpoll()
  148. Source    : User
  149. Author    : Paul Hobbs
  150. Parameters:
  151.    evnt%    : the event number
  152. Dependant Routines:
  153.    None
  154. Global Variables:
  155.    block            : parameter block
  156.    claimmenu$       : name of menu routine control 
  157.                       passes to on event nr 9
  158.    claimdrag$       : name of user drag routine 
  159.                       control passes to on event 
  160.                       nr 7
  161. Notes: 
  162.    None 
  163. Routine   : PROCicon_create(handle%,l%,b%,r%, 
  164.             t%,fgcol%,bgcol%,flags%,data$)
  165. Library   : WimpLib
  166. Purpose   : Creates an icon 
  167. Source    : Acorn User Sep 88
  168. Author    : Chris Adie
  169. Parameters:
  170.    handle%  : handle of the window the icon is in
  171.    l%       : xmin ordinate of icon
  172.    b%       : ymin ordinate of icon
  173.    r%       : xmax ordinate of icon
  174.    t%       : ymax ordinate of icon
  175.    fgcol%   : foreground colour of icon
  176.    bgcol%   : background colour of icon
  177.    flags%   : icon control flags
  178.    data$    : text or sprite name for icon
  179. Dependant Routines:
  180.    None
  181. Global Variables:
  182.    block            : parameter block
  183. Notes: 
  184.    Ordinates are relative to window origin in 
  185.    graphic units. An 'indirected' icon may be 
  186.    created by specifying the data in the form 
  187.    'address%,12'. This is evaluated as an address 
  188.    plus the number of characters in the icon. 
  189.    Offsets i.e. 'address%+10,12' may also be used.
  190. Routine   : PROCicon_deselect(handle%,iconh%)
  191. Library   : WimpLib
  192. Purpose   : Deselects a given icon in the 
  193.             specified window 
  194. Source    : Acorn User Sep 88
  195. Author    : Chris Adie
  196. Parameters:
  197.    handle%  : handle of the window the icon is in
  198.    iconh%   : handle of icon to deselect 
  199. Dependant Routines:
  200.    None
  201. Global Variables:
  202.    block            : parameter block  
  203. Notes: 
  204.    If a non selected icon handle (i.e. -1) is 
  205.    passed to the routine it is ignored.
  206. Routine   : PROCicon_select(handle%,iconh%)
  207. Library   : WimpLib
  208. Purpose   : Selects (highlights) a given icon in 
  209.             the specified window 
  210. Source    : Acorn User Sep 88
  211. Author    : Chris Adie
  212. Parameters:
  213.    handle%  : handle of the window the icon is in
  214.    iconh%   : handle of icon to select 
  215. Dependant Routines:
  216.    None
  217. Global Variables:
  218.    block            : parameter block  
  219. Notes: 
  220.    None
  221. Routine   : PROCicon_putdata(block,whandle%, 
  222.             ihandle%,data$,redraw)
  223. Library   : WimpLib
  224. Purpose   : Places a string into an icon data area 
  225.             to change the icon text or the name of 
  226.             the displayed sprite
  227. Source    : User
  228. Author    : Paul Hobbs
  229. Parameters:
  230.    block    : address of the data block to use
  231.    whandle% : handle of the window the icon is in
  232.    ihandle% : handle of icon to modify
  233.    data$    : the text to place in the icon or the 
  234.               new sprite name
  235.    redraw   : flag (TRUE=icon is redrawn 
  236.               immediately) 
  237. Dependant Routines:
  238.    None
  239. Global Variables:
  240.    None
  241. Notes: 
  242.    The redraw flag is provided as a selection of 
  243.    icons may be updated together and displayed 
  244.    with one redraw window call, or the window may 
  245.    be closed in which case the redraw will take 
  246.    place when it is opened.
  247. Routine   : FNicon_getdata(block,whandle%, 
  248.             ihandle%)
  249. Library   : WimpLib
  250. Purpose   : Returns a string from the requested 
  251.             icon which is either the text or the 
  252.             name of a sprite
  253. Source    : User
  254. Author    : Paul Hobbs
  255. Parameters:
  256.    block    : address of the data block to use
  257.    whandle% : handle of the window the icon is in
  258.    ihandle% : handle of icon to retrieve the data 
  259.               from
  260. Dependant Routines:
  261.    None
  262. Global Variables:
  263.    None
  264. Notes: 
  265.    None
  266. Routine   : PROCcaret_setposition(whandle%, 
  267.             ihandle%,xoff%,yoff%,height%,index%)
  268. Library   : WimpLib
  269. Purpose   : Sets the caret position within a 
  270.             window or a writeable icon
  271. Source    : User
  272. Author    : Paul Hobbs
  273. Parameters:
  274.    whandle% : window handle
  275.    ihandle% : icon handle
  276.    xoff%    : x offset of caret (within window)
  277.    yoff%    : y offset of caret (within window)
  278.    height%  : height of caret (OS coordinates)
  279.    index%   : index of caret inside string
  280. Dependant Routines:
  281.    None
  282. Global Variables:
  283.    None
  284. Notes: 
  285.    If the window handle is -1 then the caret is 
  286.    turned off. By setting height% to -1 the AWM 
  287.    calculates the x,y coordinates and the height 
  288.    from the window handle, the icon handle and the 
  289.    index into the string (an icon handle must be 
  290.    given). By setting index% to -1 the AWM will 
  291.    calculate the index and the caret height from 
  292.    the other data. A typical call for a writeable 
  293.    icon would be PROCcaret_setpostion(whandle%, 
  294.    ihandle%,-1,-1,-1,-1).
  295. Routine   : PROCicon_handleCR(block,lo%,hi%)    
  296. Library   : WimpLib
  297. Purpose   : Moves the input caret between 
  298.             writeable icons within the window 
  299.             passed to the routine in block!0
  300. Source    : User
  301. Author    : Paul Hobbs
  302. Parameters:
  303.    block    : address of the parameter block
  304.    whandle% : window handle
  305.    lo%      : lowest icon handle in the group
  306.    hi%      : highest icon handle in the group
  307. Dependant Routines:
  308.    PROCcaret_setposition()
  309. Global Variables:
  310.    None
  311. Notes: 
  312.    When defining the writeable icons within a 
  313.    window it is necessary to ensure that the icon 
  314.    handles are in sequence so that this routine 
  315.    can 'wrap round' the caret movement correctly. 
  316.    To move between writeable icons in ascending 
  317.    icon handle order the <RETURN> key is used. To 
  318.    move in descending order <SHIFT/RETURN> is 
  319.    used. block!0 should contain the window handle, 
  320.    and block!4 should contain the current icon 
  321.    handle.
  322. Routine   : PROCdefine_menu_text(text$,n,w,t,d, 
  323.    s,flags,sm,l)
  324. Library   : WimpLib
  325. Purpose   : Creates a text entry on a menu 
  326. Source    : Archive Vol 1 Issue 11
  327. Author    : Adrian Look
  328. Parameters:
  329.    text$    : menu text entry
  330.    n        : index number of menu entry
  331.    w        : if TRUE it is a writeable entry
  332.    t        : if TRUE entry is 'ticked'
  333.    d        : if TRUE entry has a dotted line 
  334.               after it
  335.    s        : if TRUE entry is non selectable
  336.    flags    : entry flags
  337.    sm       : number of sub menu
  338.    l        : if TRUE entry is the last in this 
  339.               menu
  340. Dependant Routines:
  341.    None
  342. Global Variables:
  343.    block            : parameter block
  344.    text$()          : menu text array
  345.    flags()          : flag array
  346.    submenu()        : submenu index array
  347.    flags            : constant
  348.    writeable        : constant
  349.    tick             : constant
  350.    dotted           : constant
  351.    last             : constant
  352.    shaded           : constant
  353. Notes: 
  354.    None 
  355. Routine   : PROCcreate_menu(title$,n,x,y)
  356. Library   : WimpLib
  357. Purpose   : Creates a text entry on a menu 
  358. Source    : Archive Vol 1 Issue 11
  359. Author    : Adrian Look
  360. Parameters:
  361.    title$   : title for menu (12 chars max)
  362.    n        : number of menu entries 
  363.    x        : initial x ordinate of menu             
  364.    y        : initial y ordinate of menu      
  365. Dependant Routines:
  366.    None
  367. Global Variables:
  368.    block            : parameter block
  369.    menu%            : menu parameter block
  370.    text$()          : menu text array
  371.    flags()          : flag array
  372.    submenu()        : submenu index array
  373.    flags()          : flag array
  374.    menu_title_fg    : title foreground
  375.    menu_title_bg    : title background
  376.    menu_work_fg     : work area foreground
  377.    menu_work_bg     : work area background
  378.    last             : constant -1
  379. Notes: 
  380.    None
  381. Routine   : PROCnewvals
  382. Library   : WimpLib
  383. Purpose   : Gets various global vars concerning 
  384.             the window whose handle has been used 
  385.             in a SYS "Wimp_GetWindowInfo" call
  386. Source    : Risc User Apr 88
  387. Author    : Felix Andrew 
  388. Parameters:
  389.    None
  390. Dependant Routines:
  391.    None 
  392. Global Variables:
  393.    gbx      : graphics window minx
  394.    gby      : graphics window miny
  395.    gtx      : graphics window maxx
  396.    gty      : graphics window maxy 
  397.    wbx      : work area minx
  398.    wtx      : work area maxx
  399.    wby      : work area miny
  400.    wty      : work area maxy
  401.    ebx      : ?
  402.    etx      : ?
  403.    ety      : ?
  404.    eby      : ?
  405.    xsc      : x scroll offset
  406.    ysc      : y scroll offset
  407.    hp       : ?
  408.    vp       : ?
  409. Notes: 
  410.    The origin of the window is set to the bottom 
  411.    left hand corner.
  412. Routine   : FNcreatedialog
  413. Library   : WimpLib
  414. Purpose   : Creates a dialog window and constrains 
  415.             the pointer until an icon has been 
  416.             selected.
  417. Source    : Acorn User Sep 88
  418. Author    : Chris Adie 
  419. Parameters:
  420.    None
  421. Dependant Routines:
  422.    PROCcreateicon(handle%,l%,b%,r%,t%,flags%, 
  423.    fgcol%,bgcol%,data$)
  424.    PROCopenwindow(handle%,full%,front%)
  425.    PROCmouserectangle(l%,b%,r%,t%)
  426. Global Variables:
  427.    claimdialog$     : owner of the dialog window
  428. Notes: 
  429.    Before calling this routine is is necessary to 
  430.    RESTORE the data pointer to a block of lines 
  431.    containing DATA items to define the window and
  432.    the icons i.e.
  433.  
  434.      1000REM owner  title  nicons  width height
  435.      1010DATA "test","title"," 3"," 200"," 300"
  436.      1020REM minx miny maxx maxxy bg fg flag data$
  437.      1030DATA "10","10","60","60","1","2","&F11D", 
  438.          "OK"
  439.      1040etc.......
  440.  
  441.    Flag data may be indirected, for example 
  442.    'address%,12'. The routine creates the window 
  443.    and the required icons. The 'owner' string is 
  444.    used to call FNclickdialog_owner(icon%) to 
  445.    handle mouse clicks in the window (in fact this 
  446.    is claimdialog$)
  447. Routine   : FNcreatealert(message$)
  448. Library   : WimpLib
  449. Purpose   : Creates an alert window using the 
  450.             supplied message
  451. Source    : Acorn User Sep 88
  452. Author    : Chris Adie 
  453. Parameters:
  454.    message  : the alert message
  455. Dependant Routines:
  456.    PROCcreateicon(handle%,l%,b%,r%,t%,flags%, 
  457.    fgcol%,bgcol%,data$)
  458.    PROCopenwindow(handle%,full%,front%)
  459.    PROCmouserectangle(l%,b%,r%,t%)
  460.    FNmax(a%,b%)   
  461. Global Variables:
  462.    oldmouseminx%    : previous min x of pointer
  463.    oldmouseminy%    : previous min y of pointer
  464.    oldmousemaxx%    : previous max x of pointer
  465.    oldmousemaxy%    : previous max y of pointer
  466.    alertmessage%    : address of buffer for text
  467. Notes: 
  468.    The text data is indirected and stored at 
  469.    alertmessage%. This should be dimensioned to 80 
  470.    bytes. The message is displayed in a window 
  471.    centred on the screen and a warning icon plus a 
  472.    'Continue' icon are also shown. The pointer 
  473.    cannot be moved outside the window and only by 
  474.    clicking on 'Continue' can the user close the 
  475.    alert window.
  476. Routine   : FNinit_helpwin(file$,bgcol%,fgcol%)
  477. Library   : WimpLib
  478. Purpose   : Takes an ASCII text file and converts 
  479.             the lines of text into icons, defining 
  480.             a window to hold them all.
  481. Source    : User
  482. Author    : Paul Hobbs
  483. Parameters:
  484.    file$            : the text file holding the 
  485.                       help text
  486.    bgcol%           : background colour of the 
  487.                       window
  488.    fgcol%           : text colour       
  489. Dependant Routines:
  490.    FNmem_subs()
  491.    PROCcreatewindow()
  492.    PROCcreateicon()
  493.    PROCopenwindow()
  494. Global Variables:
  495.    help_buffer      : storage area for help text
  496.    help_textloaded% : flag (TRUE or FALSE)
  497.    chX%             : x width of characters in 
  498.                       pixels
  499. Notes: 
  500.    The text data can be prepared using First Word 
  501.    Plus with the file saved as ASCII data. This 
  502.    makes the line end bytes &0A so the routine 
  503.    converts these (using FNmem_subs()) to &0Ds to 
  504.    aid using the data to create icons. The Risc 
  505.    User text editor could also be used if the line 
  506.    terminator is set to &0A. The routine can only 
  507.    be executed once, but help_textloaded% is used 
  508.    to ensure this is the case.
  509. Routine   : PROCopentemplate(filename$)
  510. Library   : WimpLib
  511. Purpose   : Opens a template file ready to load 
  512.             window definitions
  513. Source    : Archive November 1988 Page 37
  514. Author    : Adrian Look
  515. Parameters:
  516.    filename$        : the name of the template 
  517.                       file
  518. Dependant Routines:
  519.    None
  520. Global Variables:
  521.    None
  522. Notes: 
  523.    No checks are made to ensure that the file 
  524.    exists or that it is a valid template file.
  525. Routine   : FNloadtemplate(ident$)
  526. Library   : WimpLib
  527. Purpose   : Reads a window definition from a 
  528.             template file
  529. Source    : Archive November 1988 Page 37
  530. Author    : Adrian Look
  531. Parameters:
  532.    ident$           : the identifier of the 
  533.                       desired window definition
  534. Dependant Routines:
  535.    None
  536. Global Variables:
  537.    block            : parameter block
  538.    iptr%            : pointer to indirected 
  539.                       workspace
  540.    iend%            : pointer to end of indirected 
  541.                       workspace 
  542. Notes: 
  543.    After the routine has been called and providing 
  544.    the identifier was found the window workspace 
  545.    may be overwritten. Indirected workspace must 
  546.    be preserved until the window is disposed of, 
  547.    however. If the routine fails it will return a 
  548.    null result. Due to bugs (?) in the Archive 
  549.    template editor menu templates cannot be 
  550.    loaded.
  551. Routine   : PROCclosetemplate
  552. Library   : WimpLib
  553. Purpose   : Closes the current template file
  554. Source    : Archive November 1988 Page 37
  555. Author    : Adrian Look
  556. Parameters:
  557.    None
  558. Dependant Routines:
  559.    None
  560. Global Variables:
  561.    None
  562. Notes: 
  563.    Only one template file may be open at a time.
  564. Routine   : FNicon_decode(flag)
  565. Library   : WimpLib
  566. Purpose   : Displays in textual form the meaning 
  567.             of the icon flag specified
  568. Source    : The Micro User March 1989 Page 44
  569. Author    : Ken Down
  570. Parameters:
  571.    flag             : the flag to decode   
  572. Dependant Routines:
  573.    PROCdata_label_restore()
  574. Global Variables:
  575.    None
  576. Notes: 
  577.    Only of use when writing the program!
  578.  
  579.