basis/ui/commands/commands-docs.factor

   1 USING: accessors ui.gestures help.markup help.syntax strings kernel
   2 hashtables quotations words classes sequences namespaces
   3 arrays assocs ;
   4 IN: ui.commands
   5
   6 : command-map-row ( gesture command -- seq )
   7     [
   8         [ gesture>string , ]
   9         [
  10             [ command-name , ]
  11             [ command-word \ $link swap 2array , ]
  12             [ command-description , ]
  13             tri
  14         ] bi*
  15     ] { } make ;
  16
  17 : command-map. ( alist -- )
  18     [ command-map-row ] { } assoc>map
  19     { "Shortcut" "Command" "Word" "Notes" }
  20     [ \ $strong swap ] { } map>assoc prefix
  21     $table ;
  22
  23 : $command-map ( element -- )
  24     [ second (command-name) " commands" append $heading ]
  25     [
  26         first2 swap command-map
  27         [ blurb>> print-element ] [ commands>> command-map. ] bi
  28     ] bi ;
  29
  30 : $command ( element -- )
  31     reverse first3 command-map
  32     commands>> value-at gesture>string
  33     $snippet ;
  34
  35 HELP: +nullary+
  36 { $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." } ;
  37
  38 HELP: +listener+
  39 { $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." } ;
  40
  41 HELP: +description+
  42 { $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 } "." } ;
  43
  44 HELP: invoke-command
  45 { $values { "target" object } { "command" "a command" } }
  46 { $description "Invokes a command on the given target object." } ;
  47
  48 { invoke-command +nullary+ } related-words
  49
  50 HELP: command-name
  51 { $values { "command" "a command" } { "str" "a string" } }
  52 { $description "Outputs a human-readable name for the command." }
  53 { $examples
  54     { $example
  55         "USING: io ui.commands ;"
  56         "IN: scratchpad"
  57         ": com-my-command ;"
  58         "\\ com-my-command command-name write"
  59         "My Command"
  60     }
  61 } ;
  62
  63 HELP: command-description
  64 { $values { "command" "a command" } { "str/f" "a string or " { $link f } } }
  65 { $description "Outputs the command's description." } ;
  66
  67 { command-description +description+ } related-words
  68
  69 HELP: command-word
  70 { $values { "command" "a command" } { "word" word } }
  71 { $description "Outputs the word that will be executed by " { $link invoke-command } ". This is only used for documentation purposes." } ;
  72
  73 HELP: command-map
  74 { $values { "group" string } { "class" "a class word" } { "command-map" "a " { $link command-map } " or " { $link f } } }
  75 { $description "Outputs a named command map defined on a class." }
  76 { $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."
  77 $nl
  78 "Command maps are created by calling " { $link <command-map> } " or " { $link define-command-map } "." } ;
  79
  80 HELP: commands
  81 { $values { "class" "a class word" } { "hash" hashtable } }
  82 { $description "Outputs a hashtable mapping command map names to " { $link command-map } " instances." } ;
  83
  84 HELP: define-command-map
  85 { $values { "class" "a class word" } { "group" string } { "blurb" "a " { $link string } " or " { $link f } } { "pairs" "a sequence of gesture/word pairs" } }
  86 { $description
  87     "Defines a command map on the specified gadget class. The " { $snippet "specs" } " parameter is a sequence of pairs " { $snippet "{ gesture word }" } ". The words must be valid commands; see " { $link define-command } "."
  88 }
  89 { $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." } ;
  90
  91 HELP: $command-map
  92 { $values { "element" "a pair " { $snippet "{ class map }" } } }
  93 { $description "Prints a command map, where the first element of the pair is a class word and the second is a command map name." } ;
  94
  95 HELP: $command
  96 { $values { "element" "a triple " { $snippet "{ class map command }" } } }
  97 { $description "Prints the keyboard shortcut associated with " { $snippet "command" } " in the command map named " { $snippet "map" } " on the class " { $snippet "class" } "." } ;
  98
  99 HELP: define-command
 100 { $values { "word" word } { "hash" hashtable } }
 101 { $description "Defines a command. The hashtable can contain the following keys:"
 102     { $list
 103         { { $link +nullary+ } " - if set to a true value, the word must have stack effect " { $snippet "( -- )" } "; otherwise it must have stack effect " { $snippet "( target -- )" } }
 104         { { $link +listener+ } " - if set to a true value, the command will run in the listener" }
 105         { { $link +description+ } " - can be set to a string description of the command" }
 106     }
 107 } ;
 108
 109 HELP: command-string
 110 { $values { "gesture" "a gesture" } { "command" "a command" } { "string" string } }
 111 { $description "Outputs a string containing the command name followed by the gesture." }
 112 { $examples
 113     { $example
 114         "USING: io ui.commands ui.gestures ;"
 115         "IN: scratchpad"
 116         ": com-my-command ;"
 117         "T{ key-down f { C+ } \"s\" } \\ com-my-command command-string write"
 118         "My Command (C+s)"
 119     }
 120 } ;
 121
 122 ARTICLE: "ui-commands" "Commands"
 123 "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."
 124 { $subsection define-command }
 125 "Command groups are defined on gadget classes:"
 126 { $subsection define-command-map }
 127 "Commands can be introspected and invoked:"
 128 { $subsection commands }
 129 { $subsection command-map }
 130 { $subsection invoke-command }
 131 "Gadgets for invoking commands are documented in " { $link "ui.gadgets.buttons" } "."
 132 $nl
 133 "When documenting gadgets, command documentation can be automatically generated:"
 134 { $subsection $command-map }
 135 { $subsection $command } ;
 136
 137 ABOUT: "ui-commands"