basis/ui/gadgets/buttons/buttons-docs.factor

   1 USING: help.markup help.syntax ui.gadgets ui.gadgets.labels
   2 ui.pens kernel models classes ;
   3 IN: ui.gadgets.buttons
   4
   5 HELP: button
   6 { $class-description "A button is a " { $link gadget } " which responds to mouse clicks by invoking a quotation."
   7 $nl
   8 "A button's appearance can vary depending on the state of the mouse button if the " { $snippet "interior" } " or " { $snippet "boundary" } " slots are set to instances of " { $link button-pen } "."
   9 $nl
  10 "A button can be selected, which is distinct from being pressed. This state is held in the " { $snippet "selected?" } " slot, and is used by " { $link checkbox } " instances to render themselves when they're checked."
  11 $nl
  12 "A button can optionally display a message in the window's status bar whenever the mouse cursor hovers over the button. To enable this behavior, just set a string to the button's " { $snippet "tooltip" } " slot." } ;
  13
  14 HELP: <button>
  15 { $values { "label" gadget } { "quot" { $quotation "( button -- )" } } { "button" "a new " { $link button } } }
  16 { $description "Creates a new " { $link button } " which calls the quotation when clicked. The given gadget becomes the button's only child." } ;
  17
  18 HELP: <roll-button>
  19 { $values { "label" "a label specifier" } { "quot" { $quotation "( button -- )" } } { "button" button } }
  20 { $description "Creates a new " { $link button } " which is displayed with a solid border when it is under the mouse, informing the user that the gadget is clickable." } ;
  21
  22 HELP: <border-button>
  23 { $values { "label" "a label specifier" } { "quot" { $quotation "( button -- )" } } { "button" button } }
  24 { $description "Creates a new " { $link button } " with a border which is always visible. The button appearance changes in response to mouse gestures using a " { $link button-pen } "." } ;
  25
  26 HELP: <repeat-button>
  27 { $values { "label" object } { "quot" { $quotation "( button -- )" } } { "button" repeat-button } }
  28 { $description "Creates a new " { $link button } " derived from a " { $link <border-button> } " which calls the quotation every 100 milliseconds as long as the mouse button is held down." } ;
  29
  30 HELP: button-pen
  31 { $class-description "A class implementing the " { $link draw-boundary } " and " { $link draw-interior } " generic words by delegating to an object in one of four slots which depend on the state of the button being drawn:"
  32     { $list
  33         { { $snippet "plain"    } " - the button is inactive" }
  34         { { $snippet "rollover" } " - the button is under the mouse" }
  35         { { $snippet "pressed"  } " - the button is under the mouse and a mouse button is held down" }
  36         { { $snippet "selected" } " - the button is selected (see " { $link checkbox } ")" }
  37         { { $snippet "pressed-selected" } " - the button is selected and a mouse button is being held down (see " { $link checkbox } ")" }
  38     }
  39 "The " { $link <roll-button> } " and " { $link <border-button> } " words create " { $link button } " instances with specific " { $link button-pen } "s." } ;
  40
  41 HELP: <command-button>
  42 { $values { "target" object } { "gesture" "a gesture" } { "command" "a command" } { "button" "a new " { $link button } } }
  43 { $description "Creates a " { $link <border-button> } " which invokes the command on " { $snippet "target" } " when clicked." } ;
  44
  45 HELP: <toolbar>
  46 { $values { "target" object } { "toolbar" gadget } }
  47 { $description "Creates a row of " { $link <command-button> } " gadgets invoking commands on " { $snippet "target" } ". The commands are taken from the " { $snippet "\"toolbar\"" } " command group of each class in " { $snippet "classes" } "." } ;
  48
  49 ARTICLE: "ui.gadgets.buttons" "Button gadgets"
  50 "The " { $vocab-link "ui.gadgets.buttons" } " vocabulary implements buttons. Buttons respond to mouse clicks by invoking a quotation."
  51 { $subsections button }
  52 "There are many ways to create a new button:"
  53 { $subsections
  54     <button>
  55     <roll-button>
  56     <border-button>
  57     <repeat-button>
  58 }
  59 "Gadgets for invoking commands:"
  60 { $subsections
  61     <command-button>
  62     <toolbar>
  63 }
  64 "Button appearance can be customized:"
  65 { $subsections button-pen }
  66 "Button constructors take " { $emphasis "label specifiers" } " as input. A label specifier is either a string, an array of strings, a gadget or " { $link f } "."
  67 { $see-also <command-button> "ui-commands" } ;
  68
  69 ABOUT: "ui.gadgets.buttons"