home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / clipboard.doc < prev    next >
Text File  |  1992-09-01  |  8KB  |  225 lines
  1. TABLE OF CONTENTS
  2.  
  3. clipboard.device/CBD_CHANGEHOOK
  4. clipboard.device/CBD_CURRENTREADID
  5. clipboard.device/CBD_CURRENTWRITEID
  6. clipboard.device/CBD_POST
  7. clipboard.device/CMD_READ
  8. clipboard.device/CMD_UPDATE
  9. clipboard.device/CMD_WRITE
  10. clipboard.device/CBD_CHANGEHOOK               clipboard.device/CBD_CHANGEHOOK
  11.  
  12.    NAME
  13.     CBD_CHANGEHOOK -- Add or remove a clip change hook
  14.  
  15.    FUNCTION
  16.     CBD_CHANGEHOOK allows specification of a hook to be called
  17.     when the data on the clipboard has changed.
  18.  
  19.    IO REQUEST
  20.     io_Message    mn_ReplyPort set up
  21.     io_Device    preset by OpenDevice
  22.     io_Unit        preset by OpenDevice
  23.     io_Command    CBD_CHANGEHOOK
  24.     io_Length -     0 to remove, 1 to install this hook
  25.     io_Data -       struct Hook *, the clip change hook
  26.  
  27.    HOOK ENVIRONMENT
  28.        hook message - a ClipHookMsg, as defined in devices/clipboard.h
  29.            chm_Type - 0, indicating that the message has the
  30.                following fields:
  31.            chm_ClipID - the clip ID of the clip triggering the change
  32.        hook object - io_Unit
  33.  
  34. clipboard.device/CBD_CURRENTREADID         clipboard.device/CBD_CURRENTREADID
  35.  
  36.    NAME
  37.     CBD_CURRENTREADID - Determine the current read identifier.
  38.  
  39.    FUNCTION
  40.     CBD_CURRENTREADID fills the io_ClipID with a clip identifier that
  41.     can be compared with that of a post command: if greater than
  42.     the post identifier then the post data held privately by an
  43.     application is not valid for its own pasting.
  44.  
  45.    IO REQUEST
  46.     io_Message    mn_ReplyPort set up
  47.     io_Device    preset by OpenDevice
  48.     io_Unit        preset by OpenDevice
  49.     io_Command    CBD_CURRENTREADID
  50.  
  51.    RESULTS
  52.     io_ClipID    the ClipID of the current write is set
  53.  
  54. clipboard.device/CBD_CURRENTWRITEID       clipboard.device/CBD_CURRENTWRITEID
  55.  
  56.    NAME
  57.     CBD_CURRENTWRITEID -- Determine the current write identifier.
  58.  
  59.    FUNCTION
  60.     CBD_CURRENTWRITEID fills the io_ClipID with a clip identifier that
  61.     can be compared with that of a post command: if greater than
  62.     the post identifier then the post is obsolete and need never
  63.     be satisfied.
  64.  
  65.    IO REQUEST
  66.     io_Message    mn_ReplyPort set up
  67.     io_Device    preset by OpenDevice
  68.     io_Unit        preset by OpenDevice
  69.     io_Command    CBD_CURRENTWRITEID
  70.  
  71.    RESULTS
  72.     io_ClipID    the ClipID of the current write is set
  73.  
  74. clipboard.device/CBD_POST                           clipboard.device/CBD_POST
  75.  
  76.    NAME
  77.     CBD_POST -- Post availability of a clip to the clipboard.
  78.  
  79.    FUNCTION
  80.     Indicate to the clipboard device that data is available for
  81.     use by accessors of the clipboard.  This is intended to be
  82.     used when a cut is large, in a private data format, and/or
  83.     changing frequently, and it thus makes sense to avoid
  84.     converting it to an IFF form and writing it to the clipboard
  85.     unless another application wants it.  The post provides a
  86.     message port to which the clipboard device will send a satisfy
  87.     message if the data is required.
  88.  
  89.     If the satisfy message is received, the write associated with
  90.     the post must be performed.  The act of writing the clip
  91.     indicates that the message has been received: it may then be
  92.     re-used by the clipboard device, and so must actually be
  93.     removed from the satisfy message port so that the port is not
  94.     corrupted.
  95.  
  96.     If the application wishes to determine if a post it has
  97.     performed is still the current clip, it should check the
  98.     post's io_ClipID with that returned by the CBD_CURRENTREADID
  99.     command.  If the current read io_ClipID is greater, the clip
  100.     is not still current.
  101.     
  102.     If an application has a pending post and wishes to determine
  103.     if it should satisfy it (e.g. before it exits), it should
  104.     check the post's io_ClipID with that returned by the
  105.     CBD_CURRENTWRITEID command.  If the current write io_ClipID is
  106.     greater, there is no need to satisfy the post.
  107.  
  108.    IO REQUEST
  109.     io_Message    mn_ReplyPort set up
  110.     io_Device    preset by OpenDevice
  111.     io_Unit        preset by OpenDevice
  112.     io_Command    CBD_POST
  113.     io_Data        pointer to satisfy message port
  114.     io_ClipID    zero
  115.  
  116.    RESULTS
  117.     io_Error    non-zero if an error occurred
  118.     io_ClipID    the clip ID assigned to this post, to be used
  119.             in the write command if this is satisfied
  120.  
  121.  
  122. clipboard.device/CMD_READ                           clipboard.device/CMD_READ
  123.  
  124.    NAME
  125.     CMD_READ -- Read from a clip on the clipboard.
  126.  
  127.    FUNCTION
  128.     The read function serves two purposes.
  129.  
  130.     When io_Offset is within the clip, this acts as a normal read
  131.     request, and io_Data is filled with data from the clipboard.
  132.     The first read request should have a zero io_ClipID, which
  133.     will be filled with the ID assigned for this read.  Normal
  134.     sequential access from the beginning of the clip is achieved
  135.     by setting io_Offset to zero for the first read, then leaving
  136.     it untouched for subsequent reads.  If io_Data is null, then
  137.     io_Offset is incremented by io_Actual as if io_Length bytes
  138.     had been read: this is useful to skip to the end of file
  139.     by using a huge io_Length.
  140.  
  141.     When io_Offset is beyond the end of the clip, this acts as a
  142.     signal to the clipboard device that the application is
  143.     through reading this clip.  Realize that while an application
  144.     is in the middle of reading a clip, any attempts to write new
  145.     data to the clipboard are held off.  This read past the end
  146.     of file indicates that those operations may now be initiated.
  147.  
  148.    IO REQUEST
  149.     io_Message    mn_ReplyPort set up
  150.     io_Device    preset by OpenDevice
  151.     io_Unit        preset by OpenDevice
  152.     io_Command    CMD_READ
  153.     io_Length    number of bytes to put in data buffer
  154.     io_Data        pointer to buffer of data to fill, or null to
  155.             skip over data
  156.     io_Offset    byte offset of data to read
  157.     io_ClipID    zero if this is the initial read
  158.  
  159.    RESULTS
  160.     io_Error    non-zero if an error occurred
  161.     io_Actual    filled with the actual number of bytes read
  162.     io_Data        (the buffer now has io_Actual bytes of data)
  163.     io_Offset    updated to next read position, which is
  164.             beyond EOF if io_Actual != io_Length
  165.     io_ClipID    the clip ID assigned to this read: do not
  166.             alter for subsequent reads
  167.  
  168. clipboard.device/CMD_UPDATE                       clipboard.device/CMD_UPDATE
  169.  
  170.    NAME
  171.     CMD_UPDATE -- Terminate the writing of a clip to the clipboard.
  172.  
  173.    FUNCTION
  174.     Indicate to the clipboard that the previous write commands are
  175.     complete and can be used for any pending pastes (reads).  This
  176.     command cannot be issued while any of the write commands are
  177.     pending.
  178.  
  179.    IO REQUEST
  180.     io_Message    mn_ReplyPort set up
  181.     io_Device    preset by OpenDevice
  182.     io_Unit        preset by OpenDevice
  183.     io_Command    CMD_UPDATE
  184.     io_ClipID    the ClipID of the write
  185.  
  186.    RESULTS
  187.     io_Error    non-zero if an error occurred
  188.  
  189. clipboard.device/CMD_WRITE                         clipboard.device/CMD_WRITE
  190.  
  191.    NAME
  192.     CMD_WRITE -- Write to a clip on the clipboard.
  193.  
  194.    FUNCTION
  195.     This command writes data to the clipboard.  This data can be
  196.     provided sequentially by clearing io_Offset for the initial
  197.     write, and using the incremented value unaltered for
  198.     subsequent writes.  If io_Offset is ever beyond the current
  199.     clip size, the clip is padded with zeros.
  200.  
  201.     If this write is in response to a SatisfyMsg for a pending
  202.     post, then the io_ClipID returned by the CBD_POST command must
  203.     be used.  Otherwise, a new ID is obtained by clearing the
  204.     io_ClipID for the first write.  Subsequent writes must not
  205.     alter the io_ClipID.
  206.  
  207.    IO REQUEST
  208.     io_Message    mn_ReplyPort set up
  209.     io_Device    preset by OpenDevice
  210.     io_Unit        preset by OpenDevice
  211.     io_Command    CMD_WRITE
  212.     io_Length    number of bytes from io_Data to write
  213.     io_Data        pointer to block of data to write
  214.     io_Offset    usually zero if this is the initial write
  215.     io_ClipID    zero if this is the initial write, ClipID of
  216.             the Post if this is to satisfy a post
  217.  
  218.    RESULTS
  219.     io_Error    non-zero if an error occurred
  220.     io_Actual    filled with the actual number of bytes written
  221.     io_Offset    updated to next write position
  222.     io_ClipID    the clip ID assigned to this write: do not
  223.             alter for subsequent writes
  224.  
  225.