home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / haswinlib / info / initialise < prev    next >
Encoding:
Text File  |  1991-02-04  |  8.4 KB  |  147 lines
  1.                       The HASWIN window library.
  2.                      ===========================
  3.                       Copyright H.A. Shaw 1990.
  4.                      ===========================
  5.  
  6. Initialising the HASWIN Library system.
  7. ----------------------------------------
  8.  
  9.         In order to start the HASWIN library system certain routines must
  10. be called at the begining of a user program.  There is a routine for each
  11. of the main parts of the HASWIN system.  These initialisation routines
  12. MUST be called BEFORE any of the facilities of their part of HASWIN are used.
  13. HASWIN routines check that they have been initialised before use.
  14.  
  15. int     haswin_initialise(char *name, int flags, int memory)
  16.         - This routine starts up the HASWIN library and registers the user
  17.           program as a task under the WIMP called "name".  The routine
  18.           loads the sprites and templates used by HASWIN and starts the error
  19.           handler and memorymanager by calling their initialisation routines.
  20.           Under normal conditions haswin_initialise() is all that is required
  21.           to get a program running sucessfully under the WIMP.
  22.         - "flags" is the logical OR of the following #defined constants:
  23.                 HASWIN_FLAGS_FASTPOLL
  24.                         - Normally haswin_poll() delays by a fixed time
  25.                           before returning a "Nothing" reason code.
  26.                           If this flag is set the haswin_poll() does not
  27.                           delay.  This makes response inside Poll loops
  28.                           faster, but uses more CPU time.
  29.                 HASWIN_FLAGS_HELPFUL
  30.                         - Respond automatically to HelpRequest messages from
  31.                           external programs (usually "!Help").  If set HASWIN
  32.                           will send the "helpmsg" string for the requested
  33.                           window or icon as a reply.  If clear the message is
  34.                           passed to the user poll routine.
  35.                 HASWIN_FLAGS_PROFILE
  36.                         - Produce profiling information.  Not implemented in
  37.                           this release.
  38.                 HASWIN_FLAGS_ONEPROG
  39.                         - If set check the full pathname of the user program
  40.                           and prevent the Filer from launching further copies
  41.                           of the program.  The user "autoload" routine is run
  42.                           instead.  Not implemented in this release.
  43.                 HASWIN_FLAGS_SETSLOT
  44.                         - If set respond to SetSlot messages by automatically
  45.                           altering the application memory slot size while
  46.                           running.  HASWINs memory allocator will correctly
  47.                           reduce the slot size until it reaches a point
  48.                           where data would be corrupted.
  49.                 HASWIN_FLAGS_SINGLE
  50.                         - If set do not multitask, but take over the entire
  51.                           CPU.  Not implemented in this release.
  52.                 HASWIN_FLAGS_VERBOSE
  53.                         - If set display internal error messages from within
  54.                           HASWIN.  These include unknown mouse operations
  55.                           and failures to find templates, sprites, windows or
  56.                           icons in internal tables.  
  57.         - If "memory" is non zero then the slot size is altered to the size
  58.           given (must be greater than the slot used to start the program in)
  59.           If the "HASWIN_FLAGS_SETSLOT" flag is set HASWIN will not allow
  60.           SetSlot messages to reduce the slot size below "memory".  The
  61.           memory space from the top of the slot used to start the program in
  62.           to the limit "memory" is given to the user heap as its initial
  63.           working space (though this may be altered later).
  64.         - After calling haswin_initialise() a user program may access the
  65.           following parts of the HASWIN system.
  66.           - Windows, Icons, Menus, Pointers, Carets.
  67.           - Window templates.
  68.           - HASWIN, WIMP or system Sprites.  (but not any user sprite areas)
  69.           - The main Polling routine haswin_poll().
  70.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  71.  
  72. int     haswin_fileinitialise()
  73.         - This routine initialises the file load/save/autoload system.  After
  74.           calling this routine the routines haswin_setloadfileroutine(),
  75.           haswin_setsavefileroutine(), haswin_setautoloadroutine(),
  76.           haswin_pushloadfileroutine(), haswin_pushsavefileroutine() and
  77.           haswin_pushautoloadroutine() may be used to inform HASWIN of the
  78.           presence of load, save and autoload routines and then File and
  79.           Save items will be automatically added to icons on the iconbar.
  80.           After calling this routine the windows "file_load" and "file_save"
  81.           may be accessed.  These are the file load and save windows.
  82.           Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  83.  
  84. int     haswin_initmemorymanager()
  85.         - This routine sets up the memory manager.  This is called by the
  86.           routine haswin_initialise() and therefore there should be no
  87.           reason for the user to call this routine directly.  Returns
  88.           HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  89.  
  90. int     haswin_initialiseuserheap(int size)
  91.         - This routine initialises the user heap above the program space.
  92.           The "size" given in bytes is rounded up to the next page and a
  93.           WIMP_SetSlot call used to move the memory space.  The user
  94.           heap must have enough free space at its end if the heap is to
  95.           be reduced in size.  This call may be used at any time to alter
  96.           the total amount of memory used by the user program and will
  97.           succeed if there is enough memory (memory size increasing) or if
  98.           the user heap has enough free space (memory size decreasing).
  99.           It returns the new total size of the user heap, or HASWIN_FALSE
  100.           on an error.
  101.  
  102.  
  103. Terminating the HASWIN Library system.
  104. ---------------------------------------
  105.  
  106.         It is possible that a user program might wish to release memory
  107. or other resorces at some time by shuting down the HASWIN library, either
  108. completly or partly.  HASWIN provides routines for this purpose.  After
  109. shuting down HASWIN can be restarted by calling the initialisation routines.
  110.  
  111. int     haswin_killmemorymanager()
  112.         - This routine removes the memory manager system from HASWIN.  After
  113.           this call none of the memory management routines will be allowed.
  114.           The routine haswin_exit() calls this routine and therefore there
  115.           should be no need for a user program to call this routine directly.
  116.           Some of HASWINs own internal routines will fail if the memory
  117.           manager is removed.
  118.  
  119. void    haswin_taskclosedown()
  120.         - This routine tells the WIMP that the task is closing down.  It is
  121.           removed from the WIMPs tables.  This is called by the routine
  122.           haswin_exit() and therefore there should be no need for the user
  123.           program to call this routine directly.  HASWIN does allow this to
  124.           be called without the user program then exiting, but what happens
  125.           if, for example, the user program then continues, and writes to
  126.           the screen, is unknown.
  127.  
  128. void    haswin_exit(int code)
  129.         - This is the standard way of terminating a user program that has
  130.           run under the HASWIN library.  When called the following happens.
  131.           1)  If an exit trap routine is defined it is called.  This allows
  132.               the user part of the program to terminate cleanly.
  133.           2)  All stacked templates are unstacked and closed.
  134.           3)  All stacked carets are unstacked and the caret is returned
  135.               to its owner when the program started (if possible).
  136.           4)  All stacked pointers are unstacked and the pointer reset to
  137.               "ptr_default", the default arrow pointer.  (This is WRONG,
  138.               the pointer should be returned to WHATEVER it was, but how?)
  139.           5)  All currently used fonts are finished with.
  140.           6)  The WIMP is shutdown by a call to haswin_taskclosedown()
  141.           7)  The memory manager is shutdown by a call to
  142.               haswin_killmemorymanager().
  143.           8)  The program is terminated by a call to the C builtin function
  144.               "exit()".  "code" is passed to exit as the return code for the
  145.               program.
  146.  
  147.