home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / haswinlib / info / haswin < prev    next >
Encoding:
Text File  |  1991-02-04  |  12.4 KB  |  256 lines
  1.  
  2.        +------------------------------------------------------------+
  3.        |         This manual describes the function of the HASWIN   |
  4.        | library and explains how the library may be intergrated    |
  5.        | into a user application.  It is hoped that the programmer  |
  6.        | will use the HASWIN interface as a whole since all the     |
  7.        | routines a programmer will ever require are built into the |
  8.        | library, and not "mix-and-match" HASWIN routines with his  |
  9.        | own code and direct calls to WIMP and RISCOS SWIs.  The    |
  10.        | manual expects the reader to have a good knowledge of the  |
  11.        | WIMP and RISCOS as it applies to graphics and the user     |
  12.        | environment.  It is best to use the "RISC OS Programmers   |
  13.        | Reference Manual" (especially chapters on VDU Drivers,     |
  14.        | Sprites, Memory Management, and The Window Manager) in     |
  15.        | conjunction with this manual since the manual uses terms   |
  16.        | that are explained there.                                  |
  17.        +------------------------------------------------------------+
  18.  
  19.  
  20.                       The HASWIN window library.
  21.                      ===========================
  22.                       Copyright H.A. Shaw 1990.
  23.                      ===========================
  24.  
  25.         The HASWIN library provides a comprehsnsive set of routines
  26. designed to simplify the writing of complex WIMP based programs.  The
  27. Archimedes WIMP, running under RISCOS requires some complex programming
  28. techniques in order to realise its full potential.  The HASWIN routines
  29. simplify user programs by hiding all the complex data structures and
  30. programming required.
  31.  
  32.         HASWIN consists of one file at ANSI C source code level and an
  33. object code library file.  The source file, an include file called haswin.h,
  34. provides all the routine and data structure definitions required, and
  35. includes any other files as needed.  The Object code library file, haswin.o,
  36. contains the actual routines.  Nearly all of these routines and data
  37. structures are given header definitions in the include file, but some data
  38. structures and routines in "haswin.o" are used internally by HASWIN and are
  39. therefore not defined.  These routines will not be explained here.  The
  40. Object code file was created using the following programs:
  41.  
  42.                 Norcroft RISC OS ARM C vsn 3.00 [Jul 12 1989]
  43.                 (HASWIN has been sucessfully compiler using:
  44.                  "Norcroft ARM C (with debugger support) 2.01A Jul 14 1988")
  45.                 libfile: library file library tool
  46.                 objlib: object file library tool
  47.  
  48.         HASWIN provides and maintains the Archimedes screen by replacing the
  49. physical screen and WIMP system with its own routines.  Programs should
  50. allow HASWIN to provide all access to the screen environment and should not
  51. call any of the Arthur, RISCOS or WIMP routines directly.  The HASWIN
  52. routines generally follow the guidelines in the Application Notes for WIMP
  53. programmers on pages 1300-1330 of Volume III of the RISC OS Programmer's
  54. Reference Manual.  Therefore a "standard" user interface is provided by all
  55. HASWIN programs that usually behaves exactly the way a user expects if he
  56. is used to using the Application programs provided by Acorn themselves.  Any
  57. differences between the user interface provided by HASWIN applications and
  58. that of Acorn derived programs is usually due to HASWIN providing
  59. considerably more functions.  HASWIN can therefore be considered as
  60. providing a superset of the user interface provided by the routines in the
  61. "RISC_OSLib" library supplied with Release III of the Acornsoft ANSI C
  62. compiler, and used by Acorn derived code written in C.  The "RISC_OSLib"
  63. library does, however, cover the drawing of text within windows, copying
  64. the contents of windows, and dialogue boxes.  HASWIN does not cover these
  65. issues since it is designed to provide the programmer only with windows,
  66. icons, menus, pointers and carets.  What these things mean, or contain, is
  67. the concern of the programmer alone.  HASWIN does, however, provide simple
  68. text and graphics overlays to a window with simple routines to allow user
  69. data to be put into a window and then automatically redrawn by HASWIN as the
  70. window scrolls and moves.
  71.  
  72.         To a programmer the screen appears to be made up of a number of
  73. data structures representing windows, icons, menus, carets and the mouse
  74. pointer.  The user program tells the HASWIN library how these items are
  75. related and HASWIN deals with everything, only returning to the user
  76. program when its intervention is required.  In order to do this HASWIN
  77. has to take some of the C identifier and pre-processor namespaces for its
  78. own use.  Since the namespaces are very large this is not considered a
  79. problem.  Of course it is the responsibility of the programmer to prevent
  80. namespace clashes with HASWIN.  HASWIN uses the namespace as follows:
  81.  
  82.         1)      *ALL* identifiers starting with the string "haswin_" are
  83.                 reserved to the HASWIN library but may be used by the user
  84.                 programmer if they are defined in the library include file
  85.                 "haswin.h".
  86.         2)      *ALL* identifiers starting with the string "graphics_" are
  87.                 reserved to the HASWIN library but may be used by the user
  88.                 programmer if they are defined in the library include file
  89.                 "haswin.h".
  90.         3)      *ALL* #defined constants starting with the string "SPRITE_",
  91.                 and containing the string "AREA" anywhere within them are
  92.                 reserved to the HASWIN library but may be used (but not
  93.                 altered) by the user programmer if they are defined in the
  94.                 library include file "haswin.h".
  95.         4)      *ALL* #defined constants starting with the strings "CARET_",
  96.                 "graphics_", "HASWIN_", "ICON_", "MESSAGE_", "POINTER_",
  97.                 "VDUVAR_", or "WINDOW_", are reserved to the HASWIN library
  98.                 but may be used by the user programmer (but not altered) if
  99.                 they are defined in the library include file "haswin.h".
  100.         5)      The #defined constants in the list below are reserved by the
  101.                 HASWIN library, but may be used (but not altered) in user
  102.                 programs.  They are defined in the library include file
  103.                 "haswin.h".
  104.                         ICONBAR_LEFT
  105.                         ICONBAR_RIGHT
  106.                         OS_Byte
  107.                         OS_Word
  108.                         OS_File
  109.                         OS_Args
  110.                         OS_GBPB
  111.                         OS_GetEnv
  112.                         OS_Heap
  113.                         OS_FSControl
  114.                         OS_Sprite_operation
  115.                         OS_ReadVduVariables
  116.                         OS_ReadMonotonicTime
  117.                         OS_Plot
  118.                         OS_Read_mem_map_info
  119.                         OS_Read_mem_map_entries
  120.                         OS_WriteI
  121.                         SWI_X
  122.                         TASK_MAXNAME
  123.         6)      *ALL* identifiers starting with the string "_haswin_" are
  124.                 reserved to the HASWIN library and are for internal use only.
  125.                 The user program *MUST NOT* use them.
  126.         7)      The "struct" identifiers in the list below are reserved by
  127.                 the HASWIN library, but may be used in user programs.  They
  128.                 are defined in the library include file "haswin.h".
  129.                         buffer
  130.                         caret
  131.                         icon
  132.                         menu
  133.                         palette
  134.                         pointer
  135.                         text
  136.                         window
  137.         8)      The "typedef" identifiers in the list below are reserved by
  138.                 the HASWIN library, but may be used in user programs.  They
  139.                 are defined in the library include file "haswin.h".
  140.                         buffer
  141.                         caret
  142.                         icon
  143.                         menu
  144.                         palette
  145.                         pointer
  146.                         text
  147.                         window
  148.         9)      The function identifiers in the list below are reserved by
  149.                 the HASWIN library, they may not be used in user programs.
  150.                 They are not defined in the library include file "haswin.h".
  151.                         asciilen()
  152.                         atoint()
  153.                         strqcpy()
  154.                         strnqcpy()
  155.                         filemousebutton()
  156.  
  157.         In fact HASWIN only uses the identifiers whose names appear in the
  158. list headed number 9 above and the library include file "haswin.h" as
  159. globals.  The programmer may use any identifier not specifically defined in
  160. "haswin.h" or the list headed number 9 above but is warned that this can be
  161. dangerous and is certainly not going to allow the user program to be upward
  162. compatable to future releases of HASWIN.
  163.  
  164.         The HASWIN library is divided into groups of routines, each of which
  165. deals with one of the elements that form a Window Environment.  Each of
  166. these groups has an information file associated with it.  The groups (and
  167. information files) are as follows:
  168.         carets, drawing, files, fonts, icons, the kernel, memory management,
  169.         menus, palettes, pointers, polling, ram transfers, setting up,
  170.         sprites, templates, text, windows.
  171.  
  172.  
  173.         HASWIN programs benefit from some standardisation in the approch of
  174. the programmer to writing WIMP applications.  In general terms a HASWIN
  175. program looks like the following...
  176.  
  177.  
  178. #include <haswin.h>
  179.  
  180. /*
  181.  * routines to deal with the various things that can happen in the WIMP
  182.  * environment that HASWIN cannot deal with itself.  A single routine can
  183.  * deal with a particular event in as many windows, icons or menus as
  184.  * required, but can only deal with one sort of event.  User routines are
  185.  * always passed enough information by HASWIN for them to work out which
  186.  * window, icon or menu their event has occured in.  The user can provide
  187.  * routines to handle the following events:
  188.  *
  189.  * Routines to open windows.
  190.  * Routines to draw windows,
  191.  * Routines to drag windows,
  192.  * Routines to handle mouse operations in windows,
  193.  * Routines to drag icons,
  194.  * Routines to handle mouse operations with icons,
  195.  * Routines to create menu text strings.
  196.  * Routines to take menu selections, as text strings, and process them
  197.  * Routines to save user data into files.
  198.  * Routines to load user data from files.
  199.  * Routines to handle application launches using double-clicks on files of
  200.  * specific filetypes.
  201.  * Routines to save user data using direct RAM transfers.
  202.  * Routines to load user data using direct RAM transfers.
  203.  *
  204.  * Finally the user can provide a single user poll routine that will be
  205.  * called by HASWIN for all and any event, even if other routines exist to
  206.  * handle it.  The user poll routine must determine which events to ignore
  207.  * itself.
  208.  */
  209.  
  210. main(int argc, char **argv) {
  211.         /*
  212.          * code to handle command line arguments
  213.          */
  214.  
  215.         /*
  216.          * code to initialise the required parts of HASWIN, the task itself,
  217.          * file handling, direct RAM transfers, the user heap, error
  218.          * handlers, etc.
  219.          */
  220.  
  221.         /*
  222.          * code to read in the program's resorces.  Sprite files, template
  223.          * files etc.
  224.          */
  225.  
  226.         /*
  227.          * code to create the data structures for the windows, icons, menus,
  228.          * pointers and carets the program will use.
  229.          */
  230.  
  231.         /*
  232.          * code to link the user routines into their respective events in the
  233.          * data structures HASWIN has created for the windows, icons, menus,
  234.          * pointers and carets the program will use.
  235.          */
  236.  
  237.         for (;;) {
  238.                 haswin_poll();
  239.                 /*
  240.                  * code to do any repeating processing required.
  241.                  */
  242.         }
  243. }
  244.  
  245.         The program structure above is very general, and under most
  246. conditions not all parts will be required.  Much time and trouble has gone
  247. into HASWINs fallback conditions, ie. what HASWIN does when something happens
  248. that HASWIN cannot handle and that the user has provided no routine for.
  249. It is hoped that HASWINs fallback conditions are sufficient for most
  250. programs, and a programmer should never have to write a "dummy" routine for
  251. HASWIN to call so that HASWIN does nothing, instead of its own default
  252. action.  Therefore the programmer should need to write routines to handle
  253. only special cases.  All the default actions should be performed by HASWIN
  254. itself.
  255.  
  256.