basis/ui/clipboards/clipboards-docs.factor

   1 USING: ui.gadgets ui.gestures help.markup help.syntax strings ;
   2 IN: ui.clipboards
   3
   4 HELP: clipboard
   5 { $var-description "Global variable holding the system clipboard. By convention, text should only be copied to the clipboard via an explicit user action, for example by pressing " { $snippet "C+c" } "." }
   6 { $class-description "A mutable container for a single string implementing the " { $link "clipboard-protocol" } "." } ;
   7
   8 HELP: paste-clipboard
   9 { $values { "gadget" gadget } { "clipboard" "an object" } }
  10 { $contract "Arranges for the contents of the clipboard to be inserted into the gadget at some point in the near future via a call to " { $link user-input } ". The gadget must be grafted." } ;
  11
  12 HELP: copy-clipboard
  13 { $values { "string" string } { "gadget" gadget } { "clipboard" "an object" } }
  14 { $contract "Arranges for the string to be copied to the clipboard on behalf of the gadget. The gadget must be grafted." } ;
  15
  16 HELP: selection
  17 { $var-description "Global variable holding the system selection. By convention, text should be copied to the selection as soon as it is selected by the user." } ;
  18
  19 ARTICLE: "clipboard-protocol" "Clipboard protocol"
  20 "Custom gadgets that wish to interact with the clipboard must use the following two generic words to read and write clipboard contents:"
  21 { $subsections
  22     paste-clipboard
  23     copy-clipboard
  24 }
  25 "UI backends can either implement the above two words in the case of an asynchronous clipboard model (for example, X11). If direct access to the clipboard is provided (Windows, Mac OS X), the following two generic words may be implemented instead:"
  26 { $subsections
  27     clipboard-contents
  28     set-clipboard-contents
  29 }
  30 "However, gadgets should not call these words, since they will fail if only the asynchronous method of clipboard access is supported by the backend in use."
  31 $nl
  32 "Access to two clipboards is provided:"
  33 { $subsections
  34     clipboard
  35     selection
  36 }
  37 "These variables may contain clipboard protocol implementations which transfer data to and from the native system clipboard. However an UI backend may leave one or both of these variables in their default state, which is a trivial clipboard implementation internal to the Factor UI." ;
  38
  39 ABOUT: "clipboard-protocol"