home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / b / baslib2 / !Help next >
Text File  |  1993-01-16  |  16KB  |  353 lines
  1. @(#)BasLib      1.1     1993
  2. (c) Copyright 1992,1993 Chris Corbett
  3. All sources acknowledged.
  4.  
  5. This software is distributed free of charge and may be used without
  6. restriction as long as the following conditions are adhered to:
  7.  
  8.  i) No charge must be made for re-distribution
  9. ii) All files must be included, especially this !Help file
  10.     with the copyright notice.
  11.  
  12. All helpful suggestions for changes, improvements, bug fixes etc.
  13. gratefully received. Additions to the library is encouraged, especially
  14. if I get a copy too!
  15.  
  16. ##############################################################################
  17.  
  18.  
  19. Introduction to Basic Library
  20. =============================
  21.  
  22. This directory contains a set of BASIC procedure libraries which implement
  23. some common tasks in programs designed for the WIMP. 
  24. Most routines have been collected from PD and magazine sources and modified,
  25. added to, improved etc. to produce this library. The files in this directory
  26. and their contents are:
  27.  
  28. Debug:          Procedures to support the !Debug application (from RISC
  29.                 user?) 
  30. Error:          Error handling procedures (not finished!)
  31. Malloc:         Memory allocation modelled after UNIX 
  32. Menus:          Support procedures for WIMP menus, modification of original
  33.                 described in BAU 1990.
  34. Text:           Procedures to support text windows.
  35. Win:            Procedures for window creation support.
  36.  
  37. The procedures contained in each library are described in more detail in the
  38. following sections. To use any library in a BASIC program, use a LIBRARY
  39. statement as illustrated below:
  40.         LIBRARY "<Basic$Lib>.Malloc"
  41.         LIBRARY "<Basic$Lib>.Menus"
  42.         LIBRARY "<Basic$Lib>.Debug"
  43.         LIBRARY "<Basic$Lib>.Win"
  44. - where <Basic$Lib> is a system variable which defines the location of the
  45. libraries.
  46.  
  47. +-----------+
  48. |  Malloc   |
  49. +-----------+
  50.  
  51. Procedure:      FNmalloc(size%)
  52.  
  53. Description:    Allocate a block of memory of size% bytes, starting on a
  54.                 word boundary. A pointer to the allocated memory is returned
  55.                 as an integer value. If the memory could not be allocated
  56.                 then a value of -1 is returned.
  57.  
  58.  
  59. Procedure:      FNcalloc(size%)
  60.  
  61. Description:    Same as above, except that the allocated memory block is
  62.                 cleared to zero before returning to the calling program.
  63.  
  64.  
  65. Procedure:      FNfree(ptr%)
  66.  
  67. Description:    Frees the memory previously allocated by Fnmalloc or
  68.                 FNcalloc above. The argument must be a valid pointer
  69.                 returned from a previous call to either of these functions.
  70.  
  71.  
  72. +-----------+
  73. |  Menus    |
  74. +-----------+
  75.  
  76. Procedure:      FNMenus_Load(menufile$)
  77.  
  78. Description:    Load a textual description of a menu structure into memory
  79.                 from the file menufile$. The structure of the menu data file
  80.                 and the code that handles it is derived from an article in
  81.                 BAU magazine, March 1990 issue. A syntactic definition of
  82.                 the file structure is:
  83.                   <menu file> ::= <menu> | <menu file>
  84.                   <menu>      ::= <Menu title><item list><CR>
  85.                   <menu title>::= [ASCII 32 .. ASCII 127]
  86.                   <item list> ::= <menu item><CR> | <item list>
  87.                   <menu item> ::= <*>|< >|<-> <itemname> <action>
  88.                   <itemname>  ::= [ASCII 32 .. ASCII 127]
  89.                   <action>    ::= <!><windowname> |
  90.                                   <@><submenu>    |
  91.                                   <*><writeable>  |
  92.                                   <{><wimpflags>  |
  93.                                   <\><function> (address of menu item passed)
  94.                   <windowname>::= [Basic integer variable]
  95.                   <submenu>   ::= <menu>
  96.                   <writeable> ::= <function><,><fieldlen><,><validation>
  97.                   <wimpflags> ::= [0..2^32-1]
  98.                   <function>  ::= [Basic function name - 'FN']<funcargs>
  99.                   <funcargs>  ::= [(][&]|[&,..] (Use & to pass address of menu icon)
  100.                   <fieldlen>  ::= [0..80]|[(0..80)"_"]
  101.                   <validation>::= [As PRM pp 1184-1186]
  102.                 It is recommended that all menu definition files are given the
  103.                 name "menus". Please refer to the example program !Compare
  104.                 which uses an example of menus. A much more detailed example
  105.                 may be found in the !Yadfs application.
  106.                 FNMenus_Load will return 1 if the menus file was loaded
  107.                 successfully. Loading the file prepares it for use by the 
  108.                 remaining procedures described below. If the file does not
  109.                 exist than error number &101 will be raised.
  110.  
  111.  
  112.  
  113. Procedure:      FNMenus_Build(title$, height%)
  114.  
  115. Description:    Build a WIMP menu structure for the menu whose title is title$.
  116.                 The menu of that name must exist in the file previously loaded
  117.                 by the FNMenus_load function. If the menu does not exist than 
  118.                 an error is raised, via the basic ERROR statement. If the menu
  119.                 is found it is formatted into the structure required by the WIMP
  120.                 ready for display to the user. A pointer to the constructed
  121.                 menu block is returned as an integer. In addition, the second
  122.                 argument to the function, height%, is declared as a RETURN value,
  123.                 and it is set to the full height of the constructed menu in pixels.
  124.  
  125. Procedure:      PROCMenus_Select(block%, menu$)
  126.  
  127. Description:    Call this procedure from within the WIMP Poll loop to decode
  128.                 the menu item selected and perform the action defined. The
  129.                 first parameter is a pointer to the WIMP control block
  130.                 filled in by the Wimp_Poll call. The second parameter is the
  131.                 name of the menu currently being displayed - this must be
  132.                 remembered in the calling program and passed to this
  133.                 routine. Typically, each time a user opens a menu by
  134.                 clicking "menu" over an application window, the program
  135.                 should open the menu and save the menu name in a variable
  136.                 ready to pass on to this procedure. An example can be found
  137.                 in the !Compare application.
  138.  
  139.  
  140.  
  141. +-----------+
  142. |   Win     |
  143. +-----------+
  144.  
  145. Procedure:      FNWin_Create(template$, window$, RETURN winaddr%)
  146.  
  147. Description:    Create a window structure in memory given the window name
  148.                 and the name of the template file. The structure created is
  149.                 as required by a Wimp_Openwindow call. Thus function
  150.                 automatically calculates the memory requirements to store
  151.                 the window data and all its indirected strings. I assumes,
  152.                 of course, that you have constructed your window template
  153.                 file using the !FormEd application.
  154.                 The function returns the window handle of the created window
  155.                 ready for use in subsequent open and close window
  156.                 operations. The RETURN parameter, "winaddr%", is used to 
  157.                 return the address in memory of the start of the window
  158.                 block. This can be used in a program to modify window
  159.                 attributes or icon attributes which are part of the window
  160.                 definition.
  161.  
  162.  
  163. Procedure:      FNisind(flag%)
  164.  
  165. Description:    This function checks the indirected bits in the icon flag
  166.                 word passed as the parameter. It returns TRUE if the flag%
  167.                 value indicates that the icon contains indirected data, 
  168.                 otherwise it returns false.
  169.  
  170.  
  171. Procedure:      PROCPollAssign
  172.  
  173. Description:    This procedure sets a group of variable names to the values
  174.                 returned in a Wimp_Poll loop. This is a convenience call
  175.                 that allows readable names to be used inside the CASE
  176.                 statement of the Wimp_poll procedure when decoding the
  177.                 return value. The values assigned are listed below:
  178.                   Poll_Null_Reason_Code = 0
  179.                   Poll_Redraw_Window_Request = 1
  180.