home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / b / baslib2 / !Help next >
Encoding:
Text File  |  1993-01-16  |  15.6 KB  |  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.                   Poll_Open_Window_Request = 2
  181.                   Poll_Close_Window_Request = 3
  182.                   Poll_Pointer_Leaving_Window = 4
  183.                   Poll_Pointer_Entering_Window = 5
  184.                   Poll_Mouse_Click = 6
  185.                   Poll_User_Drag_Box = 7
  186.                   Poll_Key_Pressed = 8
  187.                   Poll_Menu_Selection = 9
  188.                   Poll_Scroll_Request = 10
  189.                   Poll_Lose_Caret = 11
  190.                   Poll_Gain_Caret = 12
  191.                   Poll_User_Message = 17
  192.                   Poll_User_Message_Recorded = 18
  193.                   Poll_User_Message_Acknowledged = 19
  194.  
  195.  
  196. Procedure:      PROCMessageAssign
  197.  
  198. Description:    Like the previous procedure, this one sets up a set of
  199.                 variables whose values take on the various message types
  200.                 which may be passed to the program via the WIMP. The list
  201.                 of assigned values is given below:
  202.                  Message_Quit = 0
  203.                  Message_DataSave = 1
  204.                  Message_DataSaveAck = 2
  205.                  Message_DataLoad = 3
  206.                  Message_DataLoadAck = 4
  207.                  Message_DataOpen = 5
  208.                  Message_RAMFetch = 6
  209.                  Message_RAMTransmit = 7
  210.                  Message_PreQuit = 8
  211.                  Message_PaletteChange = 9
  212.                  Message_FilerOpenDir = &400
  213.                  Message_FilerCloseDir = &401
  214.                  Message_RequestHelp = &502
  215.                  Message_Notify = &40040
  216.                  Message_MenuWarning = &400C0
  217.                  Message_ModeChange = &400C1
  218.                  Message_TaskInitialise = &400C2
  219.                  Message_TaskCloseDown = &400C3
  220.                  Message_SlotSize = &400C4
  221.                  Message_SetSlot = &400C5
  222.                  Message_TaskNameRq = &400C6
  223.                  Message_TaskNameIs = &400C7
  224.  
  225.  
  226. Procedure:      PROCWin_Open(win%, topleftx%, toplefty%, width%, height%)
  227.  
  228. Description:    This procedure acts as an interface to the "Wimp_OpenWindow" 
  229.                 call. The first argument "win%" is the window handle, the
  230.                 next two define the screen coordinate of the top left corner
  231.                 of the window, and the last two define the initial width and
  232.                 height of the window as displayed.
  233.  
  234.  
  235. Procedure:      PROCIcon_SetText(win%,icon%,text$)
  236.  
  237. Description:    Use this procedure to change the text stored in an icon. The
  238.                 first two parameters define the window handle and icon handle
  239.                 respectively. The third argument is the text string to insert
  240.                 into the icon's buffer. The procedure checks whether the icon
  241.                 contains an indirected text string or not, and stores the string
  242.                 appropriately. For non-indirected text, the string in text$ will
  243.                 be truncated to its first 12 characters, while for indirected
  244.                 text icons the string will be truncated to the length of the
  245.                 icon's buffer.
  246.  
  247.  
  248. Procedure:      FNIcon_ReadText(win%, icon%)
  249.  
  250. Description:    This function will return the as a text string the text stored
  251.                 in the icon identified by the window handle win% and the icon
  252.                 handle icon%.
  253.  
  254.  
  255. Procedure:      FNIcon_Select(icon%, win%)
  256.  
  257. Description:    Set an icon's selected bit in its flags word, and return the old
  258.                 value of the selected bit.
  259.  
  260.  
  261. Procedure:      FNIcon_Deselect(icon%, win%)
  262.  
  263. Description:    Deselect an icon and return the old value of the icon's selected
  264.                 bit.
  265.  
  266.  
  267. +--------------+ 
  268. | Text Windows | 
  269. +--------------+
  270.  
  271. This procedure library is the most complex in the set. It consists of
  272. procedures in two main classes; those designed to be called as Wimp_Poll
  273. event handlers, and those designed to create and manipulate text windows.
  274. The procedures require a window template to be created separately, using
  275. !FormEd for example, and the window must have the title "Textdisplay".
  276.  
  277. Procedure:      FNText_CreateTextObject(title$)
  278.  
  279. Description:    Initialise a window, from the template called "Textdisplay"
  280.                 in the applications Templates file, and prepare it for
  281.                 accepting lines of text. The function returns an integer
  282.                 value which is a text object handle to be used in calls to
  283.                 subsequent procedures and functions in the text library.
  284.                 The text window will have the title string passed as the
  285.                 argument title$.
  286.  
  287.  
  288. Procedure:      FNText_DeleteTextObject(objptr%)
  289.  
  290. Description:    This function deletes the text window object created by the
  291.                 previous function. All allocated memory is freed and the
  292.                 object cannot be referenced using its object handle any more.
  293.  
  294.  
  295. Procedure:      PROCText_appline(objptr%, line$)
  296.                 
  297. Description:    This procedure accepts an object handle created by a previous
  298.                 call to FNText_CreateTextObject, and a string containing a line
  299.                 of text. The line as added to the text window at the end of
  300.                 any current lines. If there are no lines displayed in the window,
  301.                 then line$ becomes the first line of the window.
  302.  
  303.  
  304. Procedure:      PROCText_LoadFile(objptr%, file$)
  305.  
  306. Description:    This procedure accepts an object handle created by a previous
  307.                 call to FNText_CreateTextObject, and a string containing the
  308.                 name of a file. The entire file is loaded and displayed in the
  309.                 referenced text window. It is assumed for sensible results that
  310.                 the file does contain text lines rather than binary
  311.                 information. 
  312.  
  313.  
  314. Procedure:      PROCText_DeleteLine(objptr%, line%)
  315.  
  316. Description:    This procedure is called to delete a single line from the text
  317.                 window. The first argument gives the handle of the text window,
  318.                 while the second is the line number (counting from 0) to delete.
  319.  
  320.  
  321. Procedure:      PROCText_init
  322.  
  323. Description:    This procedure must be called from a programs initialisation
  324.                 section, and certainly before any calls are made to the text window
  325.                 procedures and functions described above. It may be called while
  326.                 servicing the WIMP message Task_Initialise.
  327.  
  328.  
  329. Procedure:      PROCText_Redraw(block%)
  330.  
  331. Description:    This procedure is provided for use in the WIMP's strategy for
  332.                 redrawing windows. It performs all the screen updates necessary
  333.                 to refresh the text windows. The procedure should be called
  334.                 in the Wimp_Poll loop when a Redraw_Window_Request event is
  335.                 received; see the !Compare program for an example. The procedure
  336.                 is as short as possible and makes several optimisations to
  337.                 ensure that the redrawing of the window takes as little time
  338.                 as possible - all in BASIC too!
  339.  
  340.  
  341. Procedure:      PROCText_ModeInit
  342.  
  343. Description:    The routines used to display text use values which give the height
  344.                 and width of the characters on screen in pixels. These values are
  345.                 different for each mode, so it is important that on mode changes
  346.                 the new dimensions of characters are acted upon. This procedure is
  347.                 provided to perform all the necessary calculations based on the
  348.                 current screen mode. It should be placed in the main program in
  349.                 the section which deals with WIMP messages. The message type
  350.                 "Message_ModeChange" is sent to every program on a mode change,
  351.                 and when detected this procedure should be called; see the
  352.                 !Compare program for an example.
  353.