home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / pascal / !Pascal / h / xfersend < prev   
Encoding:
Text File  |  1992-02-09  |  11.3 KB  |  255 lines
  1. (* Title:   xfersend.h
  2.  * Purpose: general purpose export of data by dragging icon
  3.  *
  4.  *)
  5.  
  6. #ifndef __xfersend_h
  7. #define __xfersend_h
  8.  
  9. #ifndef __wimp_h
  10. #include "wimp.h"
  11. #endif
  12.                                       
  13.  
  14. (******************* CALLER-SUPPLIED FUNCTION TYPES ************************)
  15.  
  16. (* ------------------------ xfersend_saveproc ------------------------------
  17.  * Description:   A function of this type should save to the given file and
  18.  *                return TRUE if successful. Handle is passed to the
  19.  *                function by xfersend().
  20.  *
  21.  * Parameters:    char *filename -- file to be saved
  22.  *                void *handle -- the handle you passed to xfersend()
  23.  * Returns:       The function must return TRUE if save was successful.
  24.  * Other Info:    none.
  25.  *
  26.  *)
  27. type xfersend_saveproc = ^function saveproc(filename : string;
  28.                                         handle : pointer) : boolean;
  29.  
  30.  
  31. (* ----------------------- xfersend_sendproc -------------------------------
  32.  * Description:   A function of this type should call xfersend_sendbuf() 
  33.  *                to send one "buffer-full" of data no bigger than
  34.  *                *maxbuf.
  35.  *
  36.  * Parameters:    void *handle -- handle which was passed to xfersend
  37.  *                int *maxbuf -- size of receiver's buffer
  38.  * Returns:       The function must return TRUE if data was successfully 
  39.  *                transmitted.
  40.  * Other Info:    Note: Your sendproc will be called by functions in the
  41.  *                xfersend module to do an in-core data transfer, on 
  42.  *                receipt of MRAMFetch messages from the receiving 
  43.  *                application. If xfersend_sendbuf() returns FALSE, then
  44.  *                return FALSE **IMMEDIATELY**.
  45.  *
  46.  *)
  47. type xfersend_sendproc = ^function sendproc(handle : pointer;
  48.                                         var maxbuf : integer) : boolean; 
  49.  
  50.  
  51. (* --------------------------- xfersend_printproc --------------------------
  52.  * Description:   A function of this type should either print the file
  53.  *                directly, or save it into the given filename, from
  54.  *                where it will be printed by the printer application.
  55.  *
  56.  * Parameters:    char *filename -- file to save into, for printing
  57.  *                void *handle -- handle that was passed to xfersend()
  58.  * Returns:       The function should return either the file type of the
  59.  *                file it saved, or one of the reason codes #defined below.
  60.  *               
  61.  * Other Info:    This is called if the file icon has been dragged onto a
  62.  *                printer application.
  63.  *
  64.  *)
  65. type xfersend_printproc = ^function printproc(filename : string;
  66.                                         handle : pointer) : integer;
  67.  
  68. const xfersend_printPrinted = -1;    (* file dealt with internally *)
  69.       xfersend_printFailed  = -2;    (* had an error along the way *)
  70.  
  71. (* The saveproc should report any errors it encounters itself. If saving
  72.    to a file, it should convert the data into a type that can be printed by
  73.    the printer application (i.e. text). *)
  74.  
  75.  
  76. (*************************** LIBRARY FUNCTIONS *****************************)
  77.  
  78.  
  79. (* ----------------------------- xfersend ----------------------------------
  80.  * Description:   Allows the user to export application data, by icon drag.
  81.  *
  82.  * Parameters:    int filetype -- type of file to save to
  83.  *                char *name -- suggested file name
  84.  *                int estsize -- estimated size of the file
  85.  *                xfersend_saveproc -- caller-supplied function for saving
  86.  *                                     application data to a file
  87.  *                xfersend_sendproc -- caller-supplied function for in-core
  88.  *                                     data transfer (if application is able
  89.  *                                     to do this)
  90.  *                xfersend_printproc -- caller-supplied function for printing
  91.  *                                      application data, if "icon" is
  92.  *                                      dragged onto printer application
  93.  *                wimp_eventstr *e --  the event which started the export
  94.  *                                     (usually mouse drag)
  95.  *                void *handle -- handle to be passed to handler functions.
  96.  * Returns:       TRUE if data exported successfully.
  97.  * Other Info:    You should typically call this function in a window's
  98.  *                event handler, when you get a "mouse drag" event.
  99.  *                See the "saveas.c" code for an example of this.
  100.  *                xfersend deals with the complexities of message-passing
  101.  *                protocols to achieve the data transfer. Refer to the above
  102.  *                typedefs for an explanation of what the three 
  103.  *                caller-supplied functions should do.
  104.  *                If "name" is 0 then a default name of "Selection" is
  105.  *                supplied.
  106.  *                If you pass 0 as the xfersend_sendproc, then no in-core
  107.  *                data transfer will be attempted
  108.  *                If you pass 0 as the xfersend_printproc, then the file
  109.  *                format for printing is assumed to be the same as for saving
  110.  *                The estimated file size is not essential, but may improve
  111.  *                performance.
  112.  *
  113.  *)
  114. function xfersend(filetype : integer;
  115.                 name : string;
  116.                 estsize : integer;
  117.                 saveproc : xfersend_saveproc;
  118.                 sendproc : xfersend_sendproc;
  119.                 printproc : xfersend_printproc;
  120.                 e : wimp_eventstr_ptr;
  121.                 handle : pointer) : boolean; extern;
  122.  
  123.  
  124. (* ----------------------------- xfersend_pipe ------------------------------
  125.  * Description:   Allows the user to export application data, without an
  126.  *                icon drag.
  127.  *
  128.  * Parameters:    int filetype -- type of file to save to
  129.  *                char *name -- suggested file name
  130.  *                int estsize -- estimated size of the file
  131.  *                xfersend_saveproc -- caller-supplied function for saving
  132.  *                                     application data to a file
  133.  *                xfersend_sendproc -- caller-supplied function for in-core
  134.  *                                     data transfer (if application is able
  135.  *                                     to do this)
  136.  *                xfersend_printproc -- caller-supplied function for printing
  137.  *                                      application data, if "icon" is
  138.  *                                      dragged onto printer application
  139.  *                void *handle -- handle to be passed to handler functions.
  140.  *                wimp_t task  -  handle of task to pass data to.
  141.  * Returns:       TRUE if data exported successfully.
  142.  * Other Info:    This function works similarly to xfersend, except it is
  143.  *                not normally used as the result of an icon drag.
  144.  *                Typical use may be to export data to another application
  145.  *                (using the same technique as xfersend), following a
  146.  *                request for data from that application (maybe as a result
  147.  *                of receiving an application-specific wimp message).
  148.  *
  149.  *)
  150. function xfersend_pipe(filetype : integer;
  151.                 name : string;
  152.                 estsize : integer;
  153.                 saveproc : xfersend_saveproc;
  154.                 sendproc : xfersend_sendproc;
  155.                 printproc : xfersend_printproc;
  156.                 handle : pointer;
  157.                 task : wimp_t) : boolean; extern;
  158.  
  159.  
  160. (* ------------------------ xfersend_sendbuf -------------------------------
  161.  * Description:   Sends the given buffer to a receiver.
  162.  *
  163.  * Parameters:    char *buffer -- the buffer to be sent
  164.  *                int size -- the number of characters placed in the buffer
  165.  * Returns:       TRUE if send was successful.
  166.  * Other Info:    This function should be called by the caller-supplied
  167.  *                xfersend_sendproc (if such exists) to do in-core data
  168.  *                transfer (see notes on xfersend_sendproc above).
  169.  *
  170.  *)
  171. function xfersend_sendbuf(buffer : string; size: integer) : boolean; extern;
  172.  
  173.  
  174. (* ------------------------ xfersend_file_is_safe --------------------------
  175.  * Description:   Informs caller if the file's name can be reliably assumed
  176.  *                not to change (during data transfer!!)
  177.  *
  178.  * Parameters:    void
  179.  * Returns:       TRUE if file is "safe".
  180.  * Other Info:    See also the xferrecv module.
  181.  *
  182.  *)
  183. function xfersend_file_is_safe : boolean; extern;
  184.  
  185. (* Returns TRUE if file recipient will not modify it; changing the
  186.    window title of the file can be done conditionally on this result. This
  187.    can be called within your xfersend_saveproc,sendproc, or printproc,
  188.    or immediately after the main xfersend. *)
  189.  
  190. (* ---------------------------- xfersend_set_fileissafe --------------------
  191.  * Description:   Allows caller to set an indication of whether a file's
  192.  *                name will remain unchanged during data transfer.
  193.  *
  194.  * Parameters:    BOOL value -- TRUE means file is safe.
  195.  * Returns:       void.
  196.  * Other Info:    none.
  197.  *
  198.  *)
  199. procedure xfersend_set_fileissafe(value : boolean); extern;
  200.  
  201. (* --------------------------- xfersend_close_on_xfer ----------------------
  202.  * Description:   Tells xfersend whether to close "parent" window after
  203.  *                icon-drag export.
  204.  *
  205.  * Parameters:    BOOL do_we_close -- TRUE means close window after export.
  206.  *                wimp_w w -- handle of window to close (presumably "parent"
  207.  *                            window.
  208.  * Returns:       void.
  209.  * Other Info:    The default is to not close the window after export.
  210.  *                Once used, this function should be called before each
  211.  *                call to xfersend().
  212.  *
  213.  *)
  214. procedure xfersend_close_on_xfer(do_we_close : boolean; w : wimp_w); extern;
  215.  
  216.  
  217. (* --------------------------- xfersend_clear_unknowns ----------------------
  218.  * Description:   Removes any unknown event processors registered by xfersend
  219.  *                or xfersend_pipe.
  220.  *
  221.  * Parameters:    void.
  222.  * Returns:       void.
  223.  * Other Info:    xfersend and xfersend_pipe use unknown event processors to
  224.  *                deal with inter-application data transfer.  These may be
  225.  *                left around after completion of the transfer (especially if
  226.  *                the transfer failed).  This function should be called when it
  227.  *                is known that the transfer has ended.
  228.  *
  229.  *)
  230. procedure xfersend_clear_unknowns; extern;
  231.  
  232.  
  233. (* --------------------------- xfersend_read_last_ref -----------------------
  234.  * Description:   Returns the my_ref value of the last wimp_MDATASAVE or
  235.  *                wimp_MDATALOAD message sent by xfersend or xfersend_pipe.
  236.  *
  237.  * Parameters:    void.
  238.  * Returns:       integer message reference
  239.  * Other Info:    After saving a file to another application (ie. where the
  240.  *                resulting file is not 'safe', the my_ref value of the
  241.  *                final wimp_MDATALOAD should be stored with the document
  242.  *                data, so that if a wimp_MDATASAVED is received, the
  243.  *                document can be marked unmodified.  If the document is
  244.  *                modified after being saved, the last_ref value should be
  245.  *                reset to 0, so that a subsequent wimp_MDATASAVED message
  246.  *                will not cause the document to be marked unmodified.
  247.  *                NB: If RAM transfer is used, the my_ref of the datasave
  248.  *                message should be stored instead.
  249.  *)
  250. function xfersend_read_last_ref : integer; extern;
  251.  
  252. #endif
  253.  
  254. (* end xfersend.h *)
  255.