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

   1 USING: help.markup help.syntax ui.commands kernel ;
   2 IN: ui.gadgets.tables
   3
   4 ARTICLE: "ui.gadgets.tables.renderers" "Table row renderer protocol"
   5 "Table gadgets use a row renderer to display rows and do a few other things."
   6 $nl
   7 "Renderers are usually instances of singleton classes, since they don't need any state of their own. Renderers are required to implement a single generic word:"
   8 { $subsections row-columns }
   9 "Renderers can also implement the following optional generic words for additional row information:"
  10 { $subsections
  11     row-color
  12     row-value
  13     row-value?
  14 }
  15 "The following optional generic words allow the renderer to provide some information about the display of all rows:"
  16 { $subsections
  17     prototype-row
  18     column-alignment
  19     filled-column
  20     column-titles
  21 } ;
  22
  23 ARTICLE: "ui.gadgets.tables.selection" "Table row selection"
  24 "A few slots in the table gadget concern row selection:"
  25 { $slots
  26   { "selection" { " - if set to a model, the values of the currently selected row or rows, as determined by a " { $link row-value } " call to the renderer, is stored in this model. See " { $link "models" } "." } }
  27   { "selection-index" { " - if set to a model, the indices of the currently selected rows." } }
  28   { "selection-required?" { " - if set to a true value, the table ensures that some row is always selected, if the model is non-empty. If set to " { $link f } ", a state where nothing is selected is permitted to occur. The default is " { $link f } "." } }
  29 }
  30 "Some words for row selection:"
  31 { $subsections
  32     selected-row
  33     (selected-row)
  34 } ;
  35
  36 ARTICLE: "ui.gadgets.tables.actions" "Table row actions"
  37 "When the user double-clicks on a row, or presses " { $command table "row" row-action } " while a row is selected, optional action and hook quotations are invoked. The action receives the row value and the hook receives the table gadget itself. These quotations are stored in the " { $slot "action" } " and " { $snippet "hook" } " slots of a table, respectively."
  38 $nl
  39 "If the " { $slot "single-click?" } " slot is set to a true value, then single-clicking on a row will invoke the row action. The default value is " { $link f } "."
  40 $nl
  41 "The row action can also be invoked programmatically:"
  42 { $subsections row-action } ;
  43
  44 ARTICLE: "ui.gadgets.tables.config" "Table gadget configuration"
  45 "Various slots in the table gadget can be set to change the appearance and behavior of the table gadget."
  46 { $slots
  47   { "gap" }
  48   { "focus-border-color" }
  49   { "mouse-color" }
  50   { "column-line-color" }
  51   { "takes-focus?" }
  52 } ;
  53
  54 ARTICLE: "ui.gadgets.tables.example" "Table gadget example"
  55 "The " { $vocab-link "color-table" } " vocabulary implements a simple application which demonstrates table gadgets. It lists all the colors in the " { $snippet "rgb.txt" } " database shipped with " { $vocab-link "colors.constants" } " in a table. Rows are highlighted with their actual color, and columns show the red, green, and blue components. Column titles are supplied." ;
  56
  57 ARTICLE: "ui.gadgets.tables" "Table gadgets"
  58 "The " { $vocab-link "ui.gadgets.tables" } " vocabulary implements table gadgets. Table gadgets display a grid of values, with each row's columns generated by a renderer object."
  59 $nl
  60 "Tables display a model as a series of rows. The model must be a sequence, and a " { $emphasis "renderer" } " creates a sequence of columns for each row. Tables are built from and inherit all features of " { $link "ui.gadgets.line-support" } "."
  61 { $command-map table "row" }
  62 "The class of tables:"
  63 { $subsections
  64     table
  65     table?
  66 }
  67 "Creating new tables:"
  68 { $subsections
  69     <table>
  70     "ui.gadgets.tables.renderers"
  71     "ui.gadgets.tables.selection"
  72     "ui.gadgets.tables.actions"
  73     "ui.gadgets.tables.example"
  74 } ;
  75
  76 ABOUT: "ui.gadgets.tables"