87 lines
5.4 KiB
Factor
87 lines
5.4 KiB
Factor
USING: ui.commands help.markup help.syntax ui.gadgets words
|
|
kernel hashtables strings classes quotations sequences
|
|
ui.gestures ;
|
|
IN: ui.operations
|
|
|
|
: $operations ( element -- )
|
|
>quotation call
|
|
f f operations>commands
|
|
command-map. ;
|
|
|
|
: $operation ( element -- )
|
|
first +keyboard+ word-prop gesture>string $snippet ;
|
|
|
|
HELP: +keyboard+
|
|
{ $description "A key which may be set in the hashtable passed to " { $link define-operation } ". The value is a gesture." } ;
|
|
|
|
HELP: +primary+
|
|
{ $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." } ;
|
|
|
|
HELP: operation
|
|
{ $description "An abstraction for an operation which may be performed on a presentation."
|
|
$nl
|
|
"Operations have the following slots:"
|
|
{ $list
|
|
{ { $link operation-predicate } " - a quotation with stack effect " { $snippet "( obj -- ? )" } }
|
|
{ { $link operation-command } " - a " { $link word } }
|
|
{ { $link operation-translator } " - a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } }
|
|
{ { $link operation-hook } " - a quotation with stack effect " { $snippet "( obj -- newobj )" } ", or " { $link f } }
|
|
{ { $link operation-listener? } " - a boolean" }
|
|
} } ;
|
|
|
|
HELP: operation-gesture
|
|
{ $values { "operation" operation } { "gesture" "a gesture or " { $link f } } }
|
|
{ $description "Outputs the keyboard gesture associated with the operation." } ;
|
|
|
|
HELP: operations
|
|
{ $var-description "Global variable holding a vector of " { $link operation } " instances. New operations can be added with " { $link define-operation } "." } ;
|
|
|
|
HELP: object-operations
|
|
{ $values { "obj" object } { "operations" "a sequence of " { $link operation } " instances" } }
|
|
{ $description "Outputs a sequence of operations applicable to the given object, by testing each defined operation's " { $link operation-predicate } " quotation in turn." } ;
|
|
|
|
HELP: primary-operation
|
|
{ $values { "obj" object } { "operation" "an " { $link operation } " or " { $link f } } }
|
|
{ $description "Outputs the operation which should be invoked when a presentation of " { $snippet "obj" } " is clicked." } ;
|
|
|
|
HELP: secondary-operation
|
|
{ $values { "obj" object } { "operation" "an " { $link operation } " or " { $link f } } }
|
|
{ $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." } ;
|
|
|
|
HELP: define-operation
|
|
{ $values { "pred" "a quotation with stack effect " { $snippet "( obj -- ? )" } } { "command" word } { "flags" hashtable } }
|
|
{ $description "Defines an operation on objects matching the predicate. The hashtable can contain the following keys:"
|
|
{ $list
|
|
{ { $link +listener+ } " - if set to a true value, the operation will run in the listener" }
|
|
{ { $link +description+ } " - can be set to a string description of the operation" }
|
|
{ { $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" }
|
|
{ { $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" }
|
|
{ { $link +keyboard+ } " - can be set to a keyboard gesture; the guesture will be used by " { $link define-operation-map } }
|
|
}
|
|
} ;
|
|
|
|
HELP: define-operation-map
|
|
{ $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 } } }
|
|
{ $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." } ;
|
|
|
|
HELP: $operations
|
|
{ $values { "element" "a sequence" } }
|
|
{ $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." } ;
|
|
|
|
HELP: $operation
|
|
{ $values { "element" "a sequence containing a single word" } }
|
|
{ $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 } "." } ;
|
|
|
|
ARTICLE: "ui-operations" "Operations"
|
|
"Operations are commands performed on presentations."
|
|
{ $subsection operation }
|
|
{ $subsection define-operation }
|
|
{ $subsection primary-operation }
|
|
{ $subsection secondary-operation }
|
|
{ $subsection define-operation-map }
|
|
"When documenting gadgets, operation documentation can be automatically generated:"
|
|
{ $subsection $operations }
|
|
{ $subsection $operation } ;
|
|
|
|
ABOUT: "ui-operations"
|