basis/ui/commands/commands-docs.factor

   1 USING: accessors ui.gestures help.markup help.syntax strings kernel
   2 hashtables quotations words classes sequences namespaces make
   3 arrays assocs ;
   4 IN: ui.commands
   5
   6 HELP: +nullary+
   7 { $description "A key which may be set in the hashtable passed to " { $link define-command } ". If set to a true value, the command does not take any inputs, and the value passed to " { $link invoke-command } " will be ignored. Otherwise, it takes one input." } ;
   8
   9 HELP: +listener+
  10 { $description "A key which may be set in the hashtable passed to " { $link define-command } ". If set to a true value, " { $link invoke-command } " will run the command in the listener. Otherwise it will run in the event loop." } ;
  11
  12 HELP: +description+
  13 { $description "A key which may be set in the hashtable passed to " { $link define-command } ". The value is a string displayed as part of the command's documentation by " { $link $command-map } "." } ;
  14
  15 HELP: invoke-command
  16 { $values { "target" object } { "command" "a command" } }
  17 { $description "Invokes a command on the given target object." } ;
  18
  19 { invoke-command +nullary+ } related-words
  20
  21 HELP: command-name
  22 { $values { "command" "a command" } { "str" string } }
  23 { $description "Outputs a human-readable name for the command." }
  24 { $examples
  25     { $example
  26         "USING: io ui.commands ;"
  27         "IN: scratchpad"
  28         ": com-my-command ( -- ) ;"
  29         "\\ com-my-command command-name write"
  30         "My Command"
  31     }
  32 } ;
  33
  34 HELP: command-description
  35 { $values { "command" "a command" } { "str/f" { $maybe string } } }
  36 { $description "Outputs the command's description." } ;
  37
  38 { command-description +description+ } related-words
  39
  40 HELP: command-word
  41 { $values { "command" "a command" } { "word" word } }
  42 { $description "Outputs the word that will be executed by " { $link invoke-command } ". This is only used for documentation purposes." } ;
  43
  44 HELP: command-map
  45 { $values { "group" string } { "class" "a class word" } { "command-map" { $maybe command-map } } }
  46 { $description "Outputs a named command map defined on a class." }
  47 { $class-description "A command map stores a group of related commands. The " { $snippet "commands" } " slot stores an association list mapping gestures to commands, and the " { $snippet "blurb" } " slot stores an optional one-line description string of this command map."
  48 $nl
  49 "Command maps are created by calling " { $link <command-map> } " or " { $link define-command-map } "." } ;
  50
  51 HELP: commands
  52 { $values { "class" "a class word" } { "hash" hashtable } }
  53 { $description "Outputs a hashtable mapping command map names to " { $link command-map } " instances." } ;
  54
  55 HELP: define-command-map
  56 { $values { "class" "a class word" } { "group" string } { "blurb" { $maybe string } } { "pairs" "a sequence of gesture/word pairs" } }
  57 { $description
  58     "Defines a command map on the specified gadget class. The " { $snippet "blurb" } " is an optional description. The " { $snippet "pairs" } " parameter is a sequence of pairs " { $snippet "{ gesture word }" } ". The " { $snippet "gesture" } " may be " { $link f } " if you are defining  a \"toolbar\" " { $snippet "group" } ". The " { $snippet "word" } "s must be valid commands; see " { $link define-command } "."
  59 }
  60 { $notes "Only one of " { $link define-command-map } " and " { $link set-gestures } " can be used on a given gadget class, since each word will overwrite the other word's definitions." } ;
  61
  62 HELP: $command-map
  63 { $values { "element" "a pair " { $snippet "{ class map }" } } }
  64 { $description "Prints a command map, where the first element of the pair is a class word and the second is a command map name." } ;
  65
  66 HELP: $command
  67 { $values { "element" "a triple " { $snippet "{ class map command }" } } }
  68 { $description "Prints the keyboard shortcut associated with " { $snippet "command" } " in the command map named " { $snippet "map" } " on the class " { $snippet "class" } "." } ;
  69
  70 HELP: define-command
  71 { $values { "word" word } { "hash" hashtable } }
  72 { $description "Defines a command. The hashtable can contain the following keys:"
  73     { $list
  74         { { $link +nullary+ } " - if set to a true value, the word must have stack effect " { $snippet "( -- )" } "; otherwise it must have stack effect " { $snippet "( target -- )" } }
  75         { { $link +listener+ } " - if set to a true value, the command will run in the listener" }
  76         { { $link +description+ } " - can be set to a string description of the command" }
  77     }
  78 } ;
  79
  80 ARTICLE: "ui-commands" "Commands"
  81 "Commands are an abstraction layered on top of gestures. Their main advantage is that they are identified by words and can be organized into " { $emphasis "command maps" } ". This allows easy construction of buttons and tool bars for invoking commands."
  82 { $subsections define-command }
  83 "Command groups are defined on gadget classes:"
  84 { $subsections define-command-map }
  85 "Commands can be introspected and invoked:"
  86 { $subsections
  87     commands
  88     command-map
  89     invoke-command
  90 }
  91 "Gadgets for invoking commands are documented in " { $link "ui.gadgets.buttons" } "."
  92 $nl
  93 "When documenting gadgets, command documentation can be automatically generated:"
  94 { $subsections
  95     $command-map
  96     $command
  97 } ;
  98
  99 ABOUT: "ui-commands"