basis/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( -- obj )
   8     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     { { $snippet "predicate" } " - a quotation with stack effect " { $snippet "( obj -- ? )" } }
  26     { { $snippet "command" } " - a " { $link word } }
  27     { { $snippet "translator" } " - a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } }
  28     { { $snippet "hook" } " - a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } }
  29     { { $snippet "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 " { $snippet "predicate" } " quotation in turn." } ;
  42
  43 HELP: primary-operation
  44 { $values { "obj" object } { "operation" { $maybe operation } } }
  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" { $maybe operation } } }
  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" { $quotation "( 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 gesture 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" { $maybe string } } { "object" object } { "translator" { $quotation "( 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 translator quotation is applied to the target gadget, and the result of the translator is passed to the operation." } ;
  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 { $subsections
  78     operation
  79     define-operation
  80     primary-operation
  81     secondary-operation
  82     define-operation-map
  83 }
  84 "When documenting gadgets, operation documentation can be automatically generated:"
  85 { $subsections
  86     $operations
  87     $operation
  88 } ;
  89
  90 ABOUT: "ui-operations"