home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / haswinlib / info / files < prev    next >
Encoding:
Text File  |  1991-02-04  |  14.5 KB  |  263 lines
  1.  
  2.                       The HASWIN window library.
  3.                      ===========================
  4.                       Copyright H.A. Shaw 1990.
  5.                      ===========================
  6.  
  7. File handling under the HASWIN system.
  8. ---------------------------------------
  9.  
  10.         The WIMP, and user programs running under it, should provide a
  11. uniform interface that allows information flow between programs.  This is
  12. done under HASWIN in the following way.  A user program is informas HASWIN
  13. of routines to be called to load or save files.  The HASWIN library handles
  14. the message passing between itself and the external filer task (that need
  15. not use the HASWIN library).  The user routines are called by HASWIN when
  16. required and are passed all the information required to perform the load or
  17. save operation.  HASWIN also monitors the launching of applications by the
  18. filer task and can trap particular filetypes, preventing the filer from
  19. launching the application and calling a user routine instead.
  20.  
  21.         The user routines are defined as follows:
  22.  
  23. int usersave(char *name, buffer *buff)
  24.         - This routine is called by HASWIN to save a file.  "buff" is either
  25.           0 or points to a buffer containing:
  26.               buff->i[ 0] - length of buffer (rounded to next word).
  27.               buff->i[ 1] - <depends upon how the file save was initiated>
  28.               buff->i[ 2] - <depends upon how the file save was initiated>
  29.               buff->i[ 3] - <depends upon how the file save was initiated>
  30.               buff->i[ 4] - <depends upon how the file save was initiated>
  31.               buff->i[ 5] - <depends upon how the file save was initiated>
  32.               buff->i[ 6] - <depends upon how the file save was initiated>
  33.               buff->i[ 7] - <depends upon how the file save was initiated>
  34.               buff->i[ 8] - <depends upon how the file save was initiated>
  35.               buff->i[ 9] - estimated file size.
  36.               buff->i[10] - file type.
  37.               buff->c[44] - first character of 0 terminated file name.
  38.           "name" points to the first character of the 0 terminated filename.
  39.           This is usually equal to "buff->c[44]".
  40.           If "buff" is non-zero then a file is to be saved and the buffer
  41.           and "name" contain all the required information to save it.  If
  42.           "buff" is zero then the external task has sent an acknowledgement
  43.           to confirm the correct transfer of a previous file to itself.
  44.         - The routine should return HASWIN_TRUE if the file has been saved
  45.           successfully and HASWIN_FALSE on some error.
  46.  
  47. int userload(char *name, buffer *buff)
  48.         - This routine is called by HASWIN to load a file.  "buff" is either
  49.           0 or points to a buffer containing:
  50.               buff->i[ 0] - length of buffer (rounded to next word).
  51.               buff->i[ 1] - <depends upon how the file load was initiated>
  52.               buff->i[ 2] - <depends upon how the file load was initiated>
  53.               buff->i[ 3] - <depends upon how the file load was initiated>
  54.               buff->i[ 4] - <depends upon how the file load was initiated>
  55.               buff->i[ 5] - <depends upon how the file load was initiated>
  56.               buff->i[ 6] - <depends upon how the file load was initiated>
  57.               buff->i[ 7] - <depends upon how the file load was initiated>
  58.               buff->i[ 8] - <depends upon how the file load was initiated>
  59.               buff->i[ 9] - estimated file size.
  60.               buff->i[10] - file type.
  61.               buff->c[44] - first character of 0 terminated file name.
  62.           "name" points to the first character of the 0 terminated filename.
  63.           This is usually equal to "buff->c[44]".
  64.           If "buff" is non-zero then a file is to be loadd and the buffer
  65.           and "name" contain all the required information to load it.  If
  66.           "buff" is zero then the external task has sent an acknowledgement
  67.           to confirm the correct transfer of a previous file to itself.
  68.         - The routine should return HASWIN_TRUE if the file has been loadd
  69.           successfully and HASWIN_FALSE on some error.
  70.  
  71. int autoload(char *name, buffer *buff)
  72.         - This routine is called by HASWIN when an application is to be
  73.           launched by a double click onto a file of a filetype HASWIN has
  74.           been told to watch out for.  "buff" is either 0 or points to a
  75.           buffer containing:
  76.               buff->i[ 0] - length of buffer (rounded to next word).
  77.               buff->i[ 1] - <depends upon how the launch was initiated>
  78.               buff->i[ 2] - <depends upon how the launch was initiated>
  79.               buff->i[ 3] - <depends upon how the launch was initiated>
  80.               buff->i[ 4] - 5
  81.               buff->i[ 5] - window handle of directory display containing
  82.                             file.
  83.               buff->i[ 6] - unused.
  84.               buff->i[ 7] - X-offset of file icon that was double clicked
  85.               buff->i[ 8] - Y-offset of file icon that was double clicked
  86.               buff->i[ 9] - 0
  87.               buff->i[10] - file type.
  88.               buff->c[44] - first character of 0 terminated file name.
  89.           "name" points to the first character of the 0 terminated filename.
  90.           This is usually equal to "buff->c[44]".
  91.         - The routine should return HASWIN_TRUE if successful and
  92.           HASWIN_FALSE on some error.
  93.  
  94.         Under normal conditions HASWIN is used in the following way to add
  95. automatic file loading and saving to it.
  96.         1)      The routine "haswin_fileinitialise()" is called once in the
  97.                 main program to setup the file loading "file_load" and file
  98.                 saving "file_save" windows.
  99.         2)      Once created the file loading and saving windows can be
  100.                 opened on the screen in the same wasy as any other windows.
  101.                 For example...
  102.                     haswin_reopenwindow(haswin_findwindowname("file_load"));
  103.                 ...will open the file loading window back whereever it had
  104.                 been opened last time.
  105.         3)      Once opened the main file icon may be dragged, the filename
  106.                 changed and the file type changed.
  107.         4)      A file save (call to the user save file routine) is triggered
  108.                 by the following...
  109.                 a)      Clicking in the "OK" icon of the "file_save" window.
  110.                 b)      Pressing <RETURN> while the filename icon of the
  111.                         "file_save" window has the input focus.
  112.                 c)      Dragging the main file icon to a filer directory
  113.                         window, or another application that allows
  114.                         inter-process file transfer.
  115.                 A file load (call to the user load file routine) is triggered
  116.                 by the following...
  117.                 a)      Clicking in the "OK" icon of the "file_load" window.
  118.                 b)      Pressing <RETURN> while the filename icon of the
  119.                         "file_load" window has the input focus.
  120.                 c)      An icon from a filer directory window being dragged
  121.                         to, and then "dropped" on an icon or window
  122.                         belonging to the program.
  123.                 Note that dragging the main file icon of the "file_load"
  124.                 window to a filer directory window, or another application
  125.                 that allows inter-process file transfer just sets the
  126.                 filename and does not start the file load operation.
  127.  
  128.         The file load and save operations are closely linked to the RAM
  129. transfer operations in the "ramtrans" part of the HASWIN library.
  130.  
  131.         HASWIN provides routines so that the user file load and save routines
  132. can be registered and manipulated.  Once a user load or save routine has
  133. been registered with HASWIN then menus created from icons on the icon bar
  134. will have the file loading and saving items added automatically.
  135.  
  136. void haswin_setsavefileroutine(int (*user)(char *, buffer *),
  137.                                char *name, char *type)
  138.         - Register the routine "user" as a routine to be called to save a
  139.           file. "name" is the default file leafname to be used in file save
  140.           windows or menu items, and "type" is the default filetype.  If
  141.           "user" is 0 then deregister any existing file saving user routine.
  142.  
  143. int haswin_pushsavefileroutine(int (*user)(char *, buffer *), char *name, char *type) {
  144.         - Push the current save routine and default leaf name and filetype
  145.           onto an internal stack and then register the routine "user" as a
  146.           routine to be called to save a file. "name" is the default file
  147.           leafname to be used in file save windows or menu items, and "type"
  148.           is the default filetype.  If "user" is 0 then register no user
  149.           routine.  Return HASWIN_TRUE if successful or HASWIN_FALSE on any
  150.           error.
  151.  
  152. int haswin_popsavefileroutine(void)
  153.         - Pull a save file routine, default leaf name and filetype from the
  154.           internal stack and re-regester them as the user save file routine,
  155.           default leaf name and filetype.  If the stack is empty register
  156.           no routine and return HASWIN_FALSE, otherwise return HASWIN_TRUE.
  157.  
  158. void haswin_setloadfileroutine(int (*user)(char *, buffer *),
  159.                                char *name, char *type)
  160.         - Register the routine "user" as a routine to be called to load a
  161.           file. "name" is the default file leafname to be used in file load
  162.           windows or menu items, and "type" is the default filetype.  If
  163.           "user" is 0 then deregister any existing file loading user routine.
  164.  
  165. int haswin_pushloadfileroutine(int (*user)(char *, buffer *), char *name, char *type) {
  166.         - Push the current load routine and default leaf name and filetype
  167.           onto an internal stack and then register the routine "user" as a
  168.           routine to be called to load a file. "name" is the default file
  169.           leafname to be used in file load windows or menu items, and "type"
  170.           is the default filetype.  If "user" is 0 then register no user
  171.           routine.  Return HASWIN_TRUE if successful or HASWIN_FALSE on any
  172.           error.
  173.  
  174. int haswin_poploadfileroutine(void)
  175.         - Pull a load file routine, default leaf name and filetype from the
  176.           internal stack and re-regester them as the user load file routine,
  177.           default leaf name and filetype.  If the stack is empty register
  178.           no routine and return HASWIN_FALSE, otherwise return HASWIN_TRUE.
  179.  
  180. void haswin_setautoloadroutine(int (*user)(char *, buffer *), char *type)
  181.         - Register the routine "user" as a routine to be called if a file of
  182.           type "type" is double-clicked and is therefore to be launched by
  183.           the filer.  If "user" is 0 then deregister any existing user
  184.           routine.
  185.  
  186. int haswin_pushautoloadroutine(int (*user)(char *, buffer *), char *type)
  187.         - Push the current autoload routine and monitored filetype onto an
  188.           internal stack and then register the routine "user" as a routine
  189.           to be called if a file of type "type" is double-clicked and is
  190.           therefore to be launched by the filer.  If "user" is 0 then
  191.           register no user routine.  Return HASWIN_TRUE if successful or
  192.           HASWIN_FALSE on any error.
  193.  
  194. int haswin_popautoloadroutine(void)
  195.         - Pull an autoload routine, and filetype to monitor from the
  196.           internal stack and re-regester them as the user autoload routine,
  197.           and monitored filetype.  If the stack is empty register no routine
  198.           and return HASWIN_FALSE, otherwise return HASWIN_TRUE.
  199.  
  200. void haswin_loadfilemugwatch(int direction)
  201.         - The load file window can have a small rotating wheel in its top
  202.           left corner that is used as a "mugwatch" (something for mugs to
  203.           watch!).  The way the wheel moves depends upon the value of
  204.           "direction".
  205.           direction  > 0   - move the wheel 45 degrees clockwise.
  206.           direction  < 0   - move the wheel 45 degrees anti-clockwise.
  207.           direction == 0   - remove the wheel from the window.
  208.  
  209. void haswin_savefilemugwatch(int direction)
  210.         - The save file window can have a small rotating wheel in its top
  211.           left corner that is used as a "mugwatch" (something for mugs to
  212.           watch!).  The way the wheel moves depends upon the value of
  213.           "direction".
  214.           direction  > 0   - move the wheel 45 degrees clockwise.
  215.           direction  < 0   - move the wheel 45 degrees anti-clockwise.
  216.           direction == 0   - remove the wheel from the window.
  217.  
  218. int haswin_fileinitialise()
  219.         - This must be called before using the load/save files system.  See
  220.           also the information on initialisation.
  221.  
  222. void haswin_decodefiletype(int type, char *str)
  223.         - Given a filetype number "type" fill the string "str" with the
  224.           textual version of the filetype.  The text is filled with spaces
  225.           make it 8 characters long.  If type is 0x1000 the text "Dir.    "
  226.           is used, and if type is 0x2000 the text "Appl.   " is used.
  227.           If the type is unknown the string is filled with 8 spaces.
  228.  
  229. int haswin_encodefiletype(char *str)
  230.         - Given a textual filetype "str" this routine returns the filetype
  231.           number or 0 if the text is not known.  The special string "Dir."
  232.           returns the number 0x1000 and "Appl." returns 0x2000.
  233.  
  234. int haswin_setfiletype(char *name, int type)
  235.         - Call RISC OS to set the file "name" to the filetype "type"
  236.           Return HASWIN_TRUE if successful or HASWIN_FALSE on some error.
  237.  
  238.  
  239.  
  240.         The HASWIN system allows certain file options to be set up to modify
  241.         the way HASWIN operates on files.  The file options are a set of
  242.         flags that may be set, cleared or read by the user program.  The
  243.         following options are defined.
  244.         HASWIN_OPTIONS_ADD - if set files are to be added when loaded or
  245.                              saved from the user program.  The user load
  246.                              and save routines should check this option
  247.                              using "haswin_getfileoptions()" and take the
  248.                              correct action themselves.  The user can alter
  249.                              this option by items in the menus automatically
  250.                              added by HASWIN.
  251.  
  252. int haswin_clearfileoptions(int new)
  253.         - Clear the file options given in "new".  Returns the new state of
  254.           the file options.
  255.  
  256. int haswin_getfileoptions()
  257.         - Return the current state of the file options.
  258.  
  259. int haswin_setfileoptions(int new)
  260.         - Set the file options given in "new".  Returns the new state of
  261.           the file options.
  262.  
  263.