extra/ui/operations/operations-docs.factor

   1 USING: ui.commands help.markup help.syntax ui.gadgets words
   2 kernel hashtables strings classes quotations sequences
   3 ui.gestures ;
   4 IN: ui.operations
   5
   6 : $operations ( element -- )
   7     >quotation call
   8     f f operations>commands
   9     command-map. ;
  10
  11 : $operation ( element -- )
  12     first +keyboard+ word-prop gesture>string $snippet ;
  13
  14 HELP: +keyboard+
  15 { $description "A key which may be set in the hashtable passed to " { $link define-operation } ". The value is a gesture." } ;
  16
  17 HELP: +primary+
  18 { $description "A key which may be set in the hashtable passed to " { $link define-operation } ". If set to a true value, this operation becomes the default operation performed when a presentation matching the operation's predicate is clicked with the mouse." } ;
  19
  20 HELP: operation
  21 { $description "An abstraction for an operation which may be performed on a presentation."
  22 $nl
  23 "Operations have the following slots:"
  24 { $list
  25     { { $link operation-predicate } " - a quotation with stack effect " { $snippet "( obj -- ? )" } }
  26     { { $link operation-command } " - a " { $link word } }
  27     { { $link operation-translator } " - a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } }
  28     { { $link operation-hook } " - a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } }
  29     { { $link operation-listener? } " - a boolean" }
  30 } } ;
  31
  32 HELP: operation-gesture
  33 { $values { "operation" operation } { "gesture" "a gesture or " { $link f } } }
  34 { $description "Outputs the keyboard gesture associated with the operation." } ;
  35
  36 HELP: operations
  37 { $var-description "Global variable holding a vector of " { $link operation } " instances. New operations can be added with " { $link define-operation } "." } ;
  38
  39 HELP: object-operations
  40 { $values { "obj" object } { "operations" "a sequence of " { $link operation } " instances" } }
  41 { $description "Outputs a sequence of operations applicable to the given object, by testing each defined operation's " { $link operation-predicate } " quotation in turn." } ;
  42
  43 HELP: primary-operation
  44 { $values { "obj" object } { "operation" "an " { $link operation  } " or " { $link f } } }
  45 { $description "Outputs the operation which should be invoked when a presentation of " { $snippet "obj" } " is clicked." } ;
  46
  47 HELP: secondary-operation
  48 { $values { "obj" object } { "operation" "an " { $link operation  } " or " { $link f } } }
  49 { $description "Outputs the operation which should be invoked when a " { $snippet "RET" } " is pressed while a presentation of " { $snippet "obj" } " is selected in a list." } ;
  50
  51 HELP: define-operation
  52 { $values { "pred" "a quotation with stack effect " { $snippet "( obj -- ? )" } } { "command" word } { "flags" hashtable } }
  53 { $description "Defines an operation on objects matching the predicate. The hashtable can contain the following keys:"
  54     { $list
  55         { { $link +listener+ } " - if set to a true value, the operation will run in the listener" }
  56         { { $link +description+ } " - can be set to a string description of the operation" }
  57         { { $link +primary+ } " - if set to a true value, the operation will be output by " { $link primary-operation } " when applied to an object satisfying the predicate" }
  58         { { $link +secondary+ } " - if set to a true value, the operation will be output by " { $link secondary-operation } " when applied to an object satisfying the predicate" }
  59         { { $link +keyboard+ } " - can be set to a keyboard gesture; the guesture will be used by " { $link define-operation-map } }
  60     }
  61 } ;
  62
  63 HELP: define-operation-map
  64 { $values { "class" "a class word" } { "group" string } { "blurb" "a " { $link string } " or " { $link f } } { "object" object } { "hook" "a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } } { "translator" "a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } } }
  65 { $description "Defines a command map named " { $snippet "group" } " on " { $snippet "class" } " consisting of operations applicable to " { $snippet "object" } ". The hook quotation is applied to the target gadget; the translator quotation is applied to the result of the hook. Finally the result of the translator is passed to the operation. A distinction is drawn between the hook and the translator because for listener operations, the hook runs in the event loop and the translator runs in the listener. This avoids polluting the listener output with large prettyprinted gadgets and long quotations." } ;
  66
  67 HELP: $operations
  68 { $values { "element" "a sequence" } }
  69 { $description "Converts the element to a quotation and calls it; the resulting quotation must have stack effect " { $snippet "( -- obj )" } ". Prints a list of operations applicable to the object, together with keyboard shortcuts." } ;
  70
  71 HELP: $operation
  72 { $values { "element" "a sequence containing a single word" } }
  73 { $description "Prints the keyboard shortcut associated with the word, which must have been previously defined as an operation by a call to " { $link define-operation } "." } ;
  74
  75 ARTICLE: "ui-operations" "Operations"
  76 "Operations are commands performed on presentations."
  77 { $subsection operation }
  78 { $subsection define-operation }
  79 { $subsection primary-operation }
  80 { $subsection secondary-operation }
  81 { $subsection define-operation-map }
  82 "When documenting gadgets, operation documentation can be automatically generated:"
  83 { $subsection $operations }
  84 { $subsection $operation } ;
  85
  86 ABOUT: "ui-operations"