my-data: [ ["John" "Doe" NY 45] ["Erica" "Stone" CA 19 none "note 1"] ["James" "Cole" FL 5 "note 2"] ] view [ title "R3GUI demonstration" text-table 200x200 ["First name" #1 250 "Surname" #2 300 "Age" #4 50 number] my-data ]
First author: Boleslav Brezovsky, 7-Nov-2011
TEXT-TABLE style provides table that can be used for displaying database data etc. Each column of the table provides support for sorting and filtering data, can be assigned to different column of the source data, the source data can be referenced so all changes will be reflected in the table with simple update call. All table functions can be executed from GUI all called pragmatically.
TEXT-TABLE init-size [pair!] list-options [block!] list-data [block!]
Init size specifies table's size.
List-options specify columns settings. List-options contain one or more labels, each label can have width and column index specified. You can also specify datatype for each column.
column-name [string!] column-index [issue!] column-width [integer!] datatype [word!] Example: ["First name" #1 250 "Surname" #2 300 "Age" #4 50 number]
If index is not specified, columns are automatically enumerated from 1 up. If width is not specified, default value of 150px is used. Datatype specifies datatype used in column. These datatypes are not same as REBOL datatypes, they are adjust for use with TEXT-TABLE (see below).
List-data are actual data used for displaying. They can be referenced. If referenced data are changed, UPDATE-FACE TEXT-TABLE must be called to reflect changes.
Format of list-data is block of blocks, where each block is one row. Rows can have different length.
Example: [ ["John" "Doe" NY 45] ["Erica" "Stone" CA 19 none "note 1"] ["James" "Cole" FL 5 "note 2"] ]
TEXT-TABLE supports different datatypes as values. They are not same as REBOL datatypes, although most of them share same name. There are some special datatypes like TAGS not found in REBOL. If no datatype is specified, TEXT is used. Datatypes speciefies which editor to open, or which validator to use.
Currently supported datatypes are:
Basic datatype used for all values that haven't specified different datatype. TEXT opens standard field as an editor.
TAGS are stored as string! values in a block!. TAGS type opens tag editor.
Actors are the API of R3GUI. TEXT-TABLE uses some standard actors and also adds some custom actors to support all TEXT-TABLE functions. Currently implemented actors are:
Basic internal actor used when initializing GUI. Style user doesn't need to access this actor.
Basic actor used for setting table's values. There are several ways to set data, preferred way is to use SET-FACE function which calls the ON-SET actor. It's also possible to use ON-SET actor directly, but this will omit some data checks etc.
SET-FACE text-table active-row
Basic usage that will set active row (NOTE: this may change).
Because TEXT-TABLE is complex style with lots of different data, additional ways to input these data are implemented using the /fields refinement. Follows the list of all supported fields.
Basic field, works same as if no field is specified.
Set table's data. Usage:
SET-FACE/FIELD text-table table-data 'data
(NOTE: name of this field will change to better describe fuctionality.)
Set table's attributes. Usage:
SET-FACE/FIELD text-table attributes 'labels SET-FACE/FIELD text-table attributes 'atts ; proposed change of field name
For the dialect description, see above the LIST-OPTIONS.
Set table's state. State is object holding current table state (active filters, sorting, active row...). This state can be stored on disk for later use.
Basic actor and function for getting table's values. Preferred method is to use GET-FACE function, it's also possible to get values using ON-GET actor.
Will return active row number.
Basic internal actor that handles drawing of table data. ON-DRAW calls ON-DRAW-GRID which draws table's header and grid. After that, ON-DRAW-ROW is called for each visible row that calls ON-DRAW-CELL to draw each cell. All actors add draw code to the LAYOUT-BLOCK facet.
Basic actor handling resizing code.
Basic actor handling focusing code.
Basic actor handling keyboard bindings. See below for list of supported keys.
ARG: row index to remove.
Remove row from table data.
INTERNAL actor. Will open data editor of selected type. Uses ON-PLACE-EDITOR internal actor to determine editor placement.
ARG: Y position in pixels.
Return index of row under mouse cursor.
ARG: X position in pixels
Return index of column under mouse cursor.
ARG: column index [integer!], direction [UP DOWN anything-else]
Will sort table data. ON-SORT creates sorted index, original data are not changed.User can select by which column to sort and the direction of sort. Sort support |UP and DOWN directions, anything else (NONE is prefered but not required) will change the sorting index back to unsorted data.
ARG: visible index
Return index in data (Columns can be rearanged and ie. third visible column can be second in source data. This function will change visible index to real one).
ARG: NONE (turn off filtering) or [column-index [integer!] filter [block!]]
TODO: support multi-filters (filter with more than one column).
Will filter data according to a filter. Binds VALUE for filter which is cell's value that can be tested against filter.
Example: all values starting with "A":
all [ not none? value value/1 = #"a" ]
ARG: block of indexes
Return filtered view of table. NOTE: ON-GET-FLAT-VIEW actor will be removed soon.
ARG: number of lines to scroll [integer!] - positive: scroll down, negative: scroll up
Scroll table view by required number of lines.
ARG: record id [integer!]
Return value from table.
Will set value. NOTE: Value differs in TEXT-TABLE and TEXT-LIST, this actor hadles the differencies.
Used by DB handler to clear table all indexes.
Actor is called when value is set in editor.
Returns index of current value in list-data.
Returns filtered list-data.
Returns current filter settings.
Returns current settings of labels in list-labels format (see above).
Returns list-data at current row position.
Set index (highlight row) of list-data.
Set data for table.
Set column labels.
Set filter to use.
It's possible to use keyboard for TEXT-TABLE navigation and access. Here's list of supported keys:
TODO: screenshot of quick form editor.