home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / exampleCode / GLX / cutNpaste / README < prev   
Encoding:
Text File  |  1994-08-02  |  13.1 KB  |  291 lines
  1.  
  2.  
  3.                 README for cutnpaste subtree.
  4.  
  5.        (this is a bastardized ascii-version file of the CutPaste.show 
  6.     showcase file that lives in this same directory)
  7.  
  8.      ==============================================================+
  9.      This is a draft paper introducing cut and paste for SGI using the
  10.      Motif clipboard and ICCCM selection  mechanism.  The technology
  11.      is still under development and we are looking forward to your
  12.      feedback on how this strategy fits into your application.  
  13.      ==============================================================+
  14.      
  15.      =================================
  16.      Intro - general info
  17.      =================================
  18.      Cut and paste is a user interface model that allows applications 
  19.      to communicate data.  
  20.      
  21.      In current desktop implementations, most notably the Macintosh, 
  22.      Windows 3.0, and Motif interfaces, data is transferred within 
  23.      and across applications using an implicit "Clipboard" model.  
  24.      The user interface to this Clipboard is presented by three items 
  25.      in a pull-down Edit menu: "Cut", "Copy", and "Paste".  After 
  26.      data has been selected within an application,  the user can then 
  27.      "transfer" this data to the Clipboard by choosing Cut or Copy.  
  28.      Cut is used to "move" the selected data to the Clipboard,
  29.      removing it from the place it was originally selected within
  30.      the application.  Copy is used to "copy" the selected data to
  31.      the Clipboard, leaving the original selection intact within the
  32.      application.  At any point after a Cut or Copy into the Clipboard
  33.      has been performed, the user may "transfer" the data held in
  34.      the Clipboard back into the application by choosing Paste.  Note
  35.      that the user may perform the Cut/Copy and subsequent Paste either
  36.      within the same application , or across any two different 
  37.      applications which may be run on the system.
  38.      
  39.      Notice that the Clipboard model is really a conceptual model, 
  40.      which must be presented cleanly and clearly to the user, to allow 
  41.      them to focus on their challenging job at hand, without 
  42.      distracting them with the busywork details of operating their 
  43.      computer.  An important part of this conceptual model is the 
  44.      "correct" conversion of selected data as it is transferred from 
  45.      one application context to another.  Note that the actual 
  46.      implementation details of how this Clipboard and data transfer
  47.      model is coded internally may differ from the simplistic copying
  48.      model presented to the user.  However, the success of this style
  49.      of user interface depends upon the quality of its seamlessness
  50.      and simplicity from the user's point of view.
  51.      
  52.      Within the X Windows community, another user interface has 
  53.      gained widespread popularity for performing "quick transfers" of 
  54.      text data from one window to another.  This mouse-based 
  55.      shorthand allows text to be selected with the Left Mouse Button, 
  56.      and supports the quick copy of that selection into the window 
  57.      where the Middle Mouse Button is clicked.  Motif has incorporated 
  58.      this shorthand, Clipboard-free notion of "Primary Selection" and 
  59.      "Primary Transfer" alongside the more formal Clipboard model 
  60.      introduced above.  This shorthand model is more appropriate for 
  61.      experienced users, where the selected data is to be transferred 
  62.      immediately, and a Clipboard is not needed to preserve the data 
  63.      across intermediate selections, operations, or the comings and 
  64.      goings of various application windows.
  65.      
  66.      SGI has adopted the data transfer strategy outlined in the the 
  67.      OSF/Motif Style Guidelines document (section 3.2, "Selection 
  68.      Actions").  Motif 1.2 implements the user model described in 
  69.      that section, supporting both the shortcut style of Primary 
  70.      Selection-based transfers, as well as the more explicit 
  71.      Clipboard-based transfers.  This dual approach allows 
  72.      Motif-compliant applications to operate compatibly with a large 
  73.      base of existing X programs which expect selection-based 
  74.      transfers, and also to operate compatibly with the growing base 
  75.      of serious commercial end-user-oriented applications, which 
  76.      depend on an explicit Clipboard-based transfer model for ease
  77.      of use.  SGI is fostering this same approach for all programs
  78.      developed to run in its end-user environment, to confer these
  79.      same interoperability advantages to the users of all applications
  80.      found on the SGI platforms.  This approach is also in keeping
  81.      the Motif's acceptance by the ACE consortium.
  82.      
  83.      Motif text widgets implement the X selection mechanisms using the 
  84.      mouse to transfer the data through the XA_PRIMARY selection, the 
  85.      application programmer doesn't need to add any code to do this.  
  86.      The Motif 1.2 clipboard mechanism, an implementation which is 
  87.      ICCCM compliant, also provides the programmer with an easy 
  88.      interface for transferring data through an Edit menu.  This 
  89.      mechanism supports the Clipboard model described above, 
  90.      transferring data between applications via a 'system' clipboard.  
  91.      However, the application has the choice to either prestore the 
  92.      data on the clipboard or to retain the data until such time as it 
  93.      is actually requested by a Paste operation. This approach 
  94.      supports a more optimized method for  avoiding excessive and 
  95.      gratuitous copies of what may be massive data sets.  In addition, 
  96.      Motif is compatible with existing X applications that have coded 
  97.      cut and paste using the X selection mechanism with the 
  98.      XA_CLIPBOARD selection.
  99.      
  100.      The Motif clipboard conceptually works like this:  a user 
  101.      sketches out an area of interest and goes to the edit menu and 
  102.      chooses Copy.  The application then identifies the data selected, 
  103.      decides how many ways it can represent the data and then posts 
  104.      the data in those formats to the Motif clipboard - or posts a 
  105.      reference to the data format to say that it's available.  The 
  106.      user then chooses Paste from some application edit menu.  The 
  107.      requesting application then may inquire what formats the data 
  108.      is available in, choose the format that is most suitable for it, 
  109.      and then begin retrieving the data from the clipboard.  In the 
  110.      event that the application that last placed data on the Motif 
  111.      clipboard exits or dies, if the data was placed in the Motif 
  112.      clipboard, the data will persist.  If the data was posted to the 
  113.      clipboard by reference, when the application exits, it can 
  114.      choose whether or not to leave the data on the clipboard.
  115.      
  116.      The greatest benefit of using the Motif clipboard or the X 
  117.      selection model is that they  permit communication among clients 
  118.      on different operating systems,  file systems and network 
  119.      environments.  If you're not interested in being a Motif client, 
  120.      you can still have your application communicate on the desktop 
  121.      through cut and paste by programming in X or Xt the selection 
  122.      mechanism using the XA_PRIMARY and XA_CLIPBOARD selections.
  123.      
  124.      If you're interested in learning more about Motif some books to 
  125.      check are:  the OSF /Motif Programmer's Guide, the OSF/Motif 
  126.      Programmer's Reference, and the OSF/Motif Style Guide. Also, the 
  127.      "Motif Programming Manual" in the O'Riley Series (Volume 6).  For 
  128.      information on the underlying ICCCM and the X selection mechanism, 
  129.      the "Inter-Client Communication Conventions Manual;  Version 1.0;
  130.      MIT X Consortium  Standard" by David S. H. Rosenthal is the 
  131.      official document for ICCCM.  Xhibition holds a ICCCM Tutorial 
  132.      which is very informative.  There is also "X Toolkit Intrinsics 
  133.      Programming Manual" in the O'Riley Series (Volume 4).   "X Window 
  134.      System Toolkit" byPaul J. Asente & Ralph R. Swick is very helpful 
  135.      for toolkit applications.
  136.      
  137.      =======================================
  138.      Application Level Responsibilities:  UI
  139.      =======================================
  140.      You'll need some buttons and probably some pop-up menus when you 
  141.      implement the user interface.   Depending on your application, you 
  142.      may want at least a CUT, COPY, and PASTE button.  CUT and COPY 
  143.      will have the same behavior at the selection level, but CUT will 
  144.      alter the application database or display list and thereby remove 
  145.      the selected object from the screen.  You may already have a cut
  146.      and paste interface that works within your application.  If so,
  147.      you're most of the way there.
  148.      
  149.      ==================================
  150.      Copy or Cut
  151.      ==================================
  152.      
  153.      Two include files
  154.      that you'll need are:
  155.      
  156.      #include <Xm/Xm.h>
  157.      #include <Xm/CutPaste.h>
  158.      
  159.      XmClipboardStartCopy()
  160.      XmClipboardCopy()
  161.      XmClipboardEndCopy()
  162.      XmClipboardCopybyName()
  163.      
  164.      When the user chooses the Copy button, the application should 
  165.      notify Motif that it has some data that it would like to share.  
  166.      It does this through 
  167.      
  168.      
  169.      XmClipboardStartCopy(Display *display, Window window,
  170.                      XmString clip_label,
  171.                      Time timestamp,
  172.                      Widget widget,
  173.                      VoidProc callback,
  174.                      long *item_id);
  175.      
  176.      where the clip_label is the name of the application wishing to 
  177.      write to the clipboard - most likely built through 
  178.      
  179.      XmStringCreate("name", XmSTRING_DEFAULT_CHARSET);
  180.      
  181.      where timestamp is the time of the event that triggered the call - 
  182.      
  183.      XtLastTimestampProcessed(display)
  184.      ...
  185.      
  186.      and then data can be  prepared to be posted to the clipboard using
  187.      
  188.      XmClipboardCopy(Display *display,
  189.                  Window win,
  190.                  long item_id,
  191.                  char *format_name,
  192.                  char *buffer,
  193.                  unsigned long length,
  194.                  int private_id,
  195.                  int *data_id)
  196.      
  197.      for
  198.      each of the formats that the application wants to make available.
  199.       To notify Motif that the copy to temporary storage is finished
  200.      and to do the actual copy from the temporary storage area to
  201.      the clipboard, call,
  202.      
  203.      XmClipboardEndCopy(Display *display, Window win, long item_id)
  204.      
  205.      There are times when the amount of data to be posted to the 
  206.      clipboard is large and once there may never be used.  Motif 
  207.      provides for this circumstance by allowing applications to Copy 
  208.      by Name rather than posting the actual data thereby saving 
  209.      resources and improving performance.  When a request for the
  210.      data occurs, then the application is notified through the callback
  211.      provided in XmClipboardCopyStart -and that callback should call:
  212.      
  213.      XmClipboardCopyByName(Display *display,
  214.                  Window win,
  215.                  int data_id,
  216.                  char *buffer,
  217.                  unsigned long length,
  218.                  int private_id)
  219.      
  220.      to affect the actual transfer of the data in buffer to the 
  221.      clipboard so it can be pasted by the requesting application.
  222.      
  223.      
  224.      ==================================
  225.      Paste
  226.      ==================================
  227.      XmClipboardStartRetrieve()
  228.      XmClipboardRetrieve()
  229.      XmClipboardEndRetrieve()
  230.      
  231.      XmClipboardInquireCount()
  232.      XmClipboardInquireFormat()
  233.      XmClipboardInquireLength()
  234.      
  235.      When an application wants to paste data that is out on the clipboard,
  236.      it notifies Motif to begin the retrieval of data by
  237.      
  238.      XmClipboardStartRetrieve(Display *display,
  239.                  Window win,
  240.                  Timestamp timestamp)
  241.      
  242.      This routine locks the clipboard until XmClipboardEndRetrieve is called. 
  243.      Next,  the application can begin to make inquiries to see if
  244.      the clipboard data is in the format that it needs by using some
  245.      of the auxilliary Inquire functions.
  246.      
  247.      XmClipboardInquireCount
  248.      
  249.      returns the number of formats that are available for the next paste 
  250.      item in the clipboard.  It also returns the maximum length of the
  251.      format names posted - this is for use in the next routine.  The
  252.      application can now loop for count times to get the formats that
  253.      are available for the next paste item.
  254.      
  255.      XmClipboardInquireFormat
  256.      
  257.      returns the format name for a given index.  The application can 
  258.      check these formats for the most desirable match and then ask how 
  259.      much data is available by
  260.      
  261.      XmClipboardInquireLength
  262.      
  263.      and begin to retrieve the paste data with
  264.      
  265.      XmClipboard Retrieve( Display *display, Window window,
  266.                  char *format_name,
  267.                  char *buffer,
  268.                  unsigned long length,
  269.                  unsigned long *num_bytes,
  270.                  int *private_id)
  271.      
  272.      When the application gets the return value of ClipboardSuccess, it
  273.      knows that all of the data has been transferred and so should call
  274.      
  275.      XmClipboardEndRetrieve(Display *display, Window window)
  276.      
  277.      to signal to Motif that the copy is done and to remove the lock
  278.      from the clipboard.
  279.      
  280.      There are other auxilliary functions available to the Motif client to 
  281.      control the clipboard. They are:
  282.      
  283.      XmClipboardCancelCopy
  284.      XmClipboardUndoCopy
  285.      XmClipboardInquirePendingItems
  286.      XmClipboardLock
  287.      XmClipboardRegisterFormat
  288.      XmClipboardUnlock
  289.      XmClipboardWithdrawFormat
  290.      
  291.