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     row-summary
  15 }
  16 "The following optional generic words allow the renderer to provide some information about the display of all rows:"
  17 { $subsections
  18     prototype-row
  19     column-alignment
  20     filled-column
  21     column-titles
  22 } ;
  23
  24 ARTICLE: "ui.gadgets.tables.selection" "Table row selection"
  25 "A few slots in the table gadget concern row selection:"
  26 { $slots
  27   { "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" } "." } }
  28   { "selection-index" { "if set to a model, the indices of the currently selected rows." } }
  29   { "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 } "." } }
  30 }
  31 "Some words for row selection:"
  32 { $subsections
  33     selected-row
  34     (selected-row)
  35 } ;
  36
  37 ARTICLE: "ui.gadgets.tables.actions" "Table row actions"
  38 "When the user double-clicks on a row, or presses " { $command table "row" row-action } ", optional action and hook quotations are invoked. The action receives the row value (if any was selected) and the hook receives the table gadget itself. These quotations are stored in the " { $slot "action" } " and " { $snippet "hook" } " slots of a table, respectively."
  39 $nl
  40 "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 } "."
  41 $nl
  42 "The row action can also be invoked programmatically:"
  43 { $subsections row-action } ;
  44
  45 ARTICLE: "ui.gadgets.tables.config" "Table gadget configuration"
  46 "Various slots in the table gadget can be set to change the appearance and behavior of the table gadget."
  47 { $slots
  48   { "gap" f }
  49   { "focus-border-color" f }
  50   { "mouse-color" f }
  51   { "column-line-color" f }
  52   { "takes-focus?" f }
  53 } ;
  54
  55 ARTICLE: "ui.gadgets.tables.example" "Table gadget example"
  56 "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." ;
  57
  58 ARTICLE: "ui.gadgets.tables" "Table gadgets"
  59 "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."
  60 $nl
  61 "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" } "."
  62 { $command-map table "row" }
  63 "The class of tables:"
  64 { $subsections
  65     table
  66     table?
  67 }
  68 "Creating new tables:"
  69 { $subsections
  70     <table>
  71     "ui.gadgets.tables.renderers"
  72     "ui.gadgets.tables.selection"
  73     "ui.gadgets.tables.actions"
  74     "ui.gadgets.tables.example"
  75 } ;
  76
  77 ABOUT: "ui.gadgets.tables"