Addons/gui/jgtkgrid
jgtkgrid
General Verb Data Options Types Actions Methods Events Utilities Class Popup menu Keyboard shortcuts Todo
General
jgtkgrid is a spreadsheet control for J7/JGTK, based on the GtkTreeView widget and GtkListStore object.
The aim is to have in J7 a replacement of the grid class available in J6.
Once installed, the addon is loaded with:
load 'gui/jgtkgrid'
The grid verb can display grids from the JGTK IDE.
The jgtkgrid class is used to create and manage grid objects in JGTK applications.
Verb
The grid verb is available in the 'z' locale. Usage:
[GRID_OPTIONS] grid GRID_DATA
Refer to Data and Options for a description of the arguments.
The verb displays a GTK window holding the grid and returns the numbered locale of the newly created object.
The returned locale can be used for further access to grid data and options. For example:
grid i.10 5 +-+ |3| +-+ appendrow_3_'' 0 getdata_3_'' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 0 0 0 0 0
When no options are given as left argument, the grid is displayed with default options.
These include the possibility to edit grid cells, sort columns, and perform other actions on rows, columns, grid.
A popup menu with the most common actions is activated by the right click of the mouse or Shift+Alt shortcut.
Some of such actions are also accessible through keyboard shortcuts: press Shift+F1 to get an help window.
The grid object (with related data) is automatically destroyed when the parent window is closed.
The following examples show how to create a grid, directly from the command line:
windows: pathtojbinaries\jconsole.exe -js "load 'gui/jgtkgrid'" "grid i.10 5" linux: pathtojbinaries/jconsole -js "load 'gui/jgtkgrid'" "grid i.10 5"
Data
Grid data are normally a rank-2 array (i.e. a 'table').
Data can be passed to the public grid verb or to the create method of jgtkgrid class
in the following forms:
- boxed table (being the boxed elements either characters or numbers)
- unboxed table (usually a numeric table)
- boxed list of columns, having each column the same number of items (this is also called an inverted table)
Regardless of how grid data are passed, internally they are always formatted and managed as a boxed table of characters;
negative numbers (integer or float) are formatted replacing underscore '_' with minus '-' sign.
The name of such array is T_BODY (with the proper locative).
A J script can use T_BODY to read data that are held in a grid, but must use other
Methods (like setrow, setcol, setcell, setdata) to write new grid data.
Also to read grid data, the preferred way is to access T_BODY through the method getdata,
which has the advantage to return the data in the same form they was initially passed
(i.e. boxed, unboxed or inverted table), converting back characters to numbers as appropriate.
grid (,.i:2);(,.i:_2) NB. grid data are passed as a list of columns +-+ |4| +-+ (100 100)setrow_4_ 2 NB. some data are modified 0 T_BODY_4_ NB. this is a boxed table of characters +---+---+ |-2 |2 | +---+---+ |-1 |1 | +---+---+ |100|100| +---+---+ |1 |-1 | +---+---+ |2 |-2 | +---+---+ getdata_4_'' NB. this returns an inverted table +---+---+ | _2| 2| | _1| 1| |100|100| | 1| _1| | 2| _2| +---+---+
See also in the Types section how cells are rendered in the grid,
depending by the type of data (numeric or string) held by each column.
Data are presented in the widget with some additional information, controlled by options, to help grid management:
- a left index column, not editable, holding progressive integers which are the row indexes
- a top header row, holding clickable column names or indexes
Options
jgtkgrid options control the visual appearance and the behaviour of the grid.
Most options can be initialized by the user when the grid is created, and then modified with the setoption method.
A J script can use directly the option names to read option values, but must use the setoption method to change option values.
Some options are automatically initialized by the initgrid method, and are just read-only parameters.
All modifiable options have default values, which are automatically set if the user does not provide custom values.
All verbs which accept options as argument (grid, initgrid, updategrid, setoption) expect options in packed form.
A pack can be either a two columns boxed table, where the first column holds option names and the second column option values,
or a boxed list with an even number of atoms, having a sequence like: option_0;value_0;option_1;value_1;...;option_N;value_N
All option names are uppercase names starting with 'C_' or with 'T_'
'C_OPTION' means that such option is a list of values, one for each column of the grid.
'T_OPTION' means that such option is a single value, related to the whole grid.
Also an option whose name starts with 'C_' can be passed by the user as a single value;
in this case that value is applied to all columns (and in case of strings the list is automatically boxed).
Read/Write Options
C_BACKCOLOR
Format: a boxed list of strings, each string representing a RGB color in hex form '#rrggbb'
Default value: '#ffffff' (white)
Function: the background color of each column
C_BACKSEL
Format: a boxed list of strings, each string representing a RGB color in hex form '#rrggbb'
Default value: '#cccccc' (light gray)
Function: the background color of each column, when it is selected
C_CHECK
Format: a list of boolean values
Default value: 1 (enabled)
Function: to execute control of numbers when the content of a numeric column is changed (by script or editing)
refer to Types section for details
C_EDIT
Format: a list of boolean values
Default value: 1 (enabled)
Function: to allow cell editing
C_EXEC
Format: a boxed list of strings
Default value: ']'
Function: to set a character that allows execution of a J sentence when editing a cell;
if the edited cell starts with this character, the following characters are evaluated, and the result will be the cell content;
an empty string disables this feature
C_EXPAND
Format: a list of boolean values
Default value: 1 (enabled)
Function: to allow columns auto-sizing for occupation of all available space
C_FONT
Format: a boxed list of strings, each string representing a font description in the form 'font-family size'
Default value: 'Monospace 10'
Function: the font description of each column
C_FORECOLOR
Format: a boxed list of strings, each string representing a RGB color in hex form '#rrggbb'
Default value: '#000000' (black)
Function: the foreground text color of each column
C_HALIGN
Format: a list of floats in the range 0 - 1 (0 for left, 0.5 for center, 1 for right)
Default value: 0.5 (center-align)
Function: the text alignment of each column header
C_HEAD
Format: a boxed list of strings, each string representing the text of a column header
Default value: progressive numbers (converted to strings), from 0 to number of columns-1
Function: the text to put in each column header
C_HFONT
Format: a boxed list of strings, each string representing a font description in the form 'font-family size'
Default value: 'Sans Bold 10'
Function: the font description of each column header
C_HFORECOLOR
Format: a boxed list of strings, each string representing a RGB color in hex form '#rrggbb'
Default value: '#000000' (black)
Function: the foreground text color of each column header
C_MAXWIDTH
Format: a list of integer values
Default value: 800
Function: to set the maximum column widths, in pixels
C_REORDCOL
Format: a list of boolean values
Default value: 1 (enabled)
Function: to allow columns reordering with drag and drop of column headers
C_RESIZE
Format: a list of boolean values
Default value: 1 (enabled)
Function: to allow columns resizing
C_SORTABLE
Format: a list of boolean values
Default value: 1 (enabled)
Function: to allow grid sorting by content of columns, by means of click on column headers;
first click selects column, second click sets ascending sort, third click sets descending sort
C_TYPE
Format: a list of complexes
Default value: 0 for strings (normal text entry), 2 for integers (default spin button)
Function: to define the types of cell renderers (real part) and the associated bounds (imaginary part)
refer to Types section for details
C_VISIBLE
Format: a list of boolean values
Default value: 1 (visible)
Function: to set columns visibility; the visibility does not affect grid content
(even if not visible, the column and related cells and values are still present in the grid)
C_XALIGN
Format: a list of floats in the range 0 - 1 (0 for left, 0.5 for center, 1 for right)
Default value: 0 for strings (left-align), 1 for numbers (right-align)
Function: the horizontal text alignment of each column
C_YALIGN
Format: a list of floats in the range 0 - 1 (0 for top, 0.5 for center, 1 for bottom)
Default value: 0 (top-align)
Function: the vertical text alignment of each column
T_BACKCOLOR
Format: a string representing a RGB color in hex form '#rrggbb'
Default value: '#555555' (dark gray)
Function: the background color of the index column
T_BOUND
Format: a boxed list of bounds
Default value: boxed empty string (meaning 'default bounds')
Function: to define spin buttons and combo lists used in cell renderers
refer to Types section for details
T_DEFSPIN
Format: a list of six or seven numbers
Default value: 0,_2147483647,2147483647,1,100,0
Function: to define the default adjustment for spin buttons
refer to Types section for details
T_DELIMITER
Format: a single ASCII character
Default value: | (vertical bar)
Function: the character used as field delimiter,
to be escaped when saving a grid as text file
T_FONT
Format: a string representing a font description in the form 'font-family size'
Default value: 'Monospace 10'
Function: the font description of the index column
T_FORECOLOR
Format: a string representing a RGB color in hex form '#rrggbb'
Default value: '#ffffff' (white)
Function: the foreground text color of the index column
T_HALIGN
Format: a float in the range 0 - 1 (0 for left, 0.5 for center, 1 for right)
Default value: 0.5 (center-align)
Function: the horizontal text alignment of index column header
T_HEAD
Format: a string representing the text of the index column header
Default value: empty string
Function: the text to put in the index column header
T_HFONT
Format: a string representing a font description in the form 'font-family size'
Default value: 'Sans Bold 10'
Function: the font description of the header of index column
T_HFORECOLOR
Format: a string representing a RGB color in hex form '#rrggbb'
Default value: '#000000' (black)
Function: the foreground text color for the header of index column
T_HVISIBLE
Format: a single boolean value
Default value: 1 (visible)
Function: to control visibility of column headers (the top row with clickable column names)
T_INDEX
Format: a single boolean value
Default value: 1 (visible)
Function: to control visibility of index column (the left read-only column with progressive numbers)
T_LINES
Format: an integer value from 0 to 3
Default value: 3 (all lines)
Function: to control visibility of grid lines: 0=no lines, 1=horizontal lines, 2=vertical lines, 3=all lines
T_MENU
Format: a boxed string or a boxed list of strings
Default value: <'all' (meaning 'all available commands')
Function: to control which commands are available in the popup menu
refer to Popup menu section for details
T_PATH
Format: a string holding an existing directory path
Default value: jpath '~user'
Function: to set the initial directory path for file dialogs
T_PFONT
Format: a string representing a font description in the form 'font-family size'
Default value: 'Monospace 10'
Function: the font description for printing and previews
T_REORDROW
Format: a single boolean value
Default value: 1 (enabled)
Function: to allow rows reordering with drag and drop (does not work well in Windows)
T_SETDATA
Format: a string
Default value: getdata"
Function: a string representing the data requested by user in update dialog
T_SETOPTION
Format: a string
Default value: 'T_LINES';0
Function: a string representing the options requested by user in setoption or update dialog
T_STDOUT
Format: a single boolean value
Default value: 0 (disabled)
Function: to enable smoutput as the default events handler; see also the Events section
T_TOOLTIP
Format: an integer value
Default value: minus infinite
Function: to select the column containing the tooltip text; minus infinite selects index column as tooltip, _1 disables tooltips
T_XALIGN
Format: a float in the range 0 - 1 (0 for left, 0.5 for center, 1 for right)
Default value: 1 (right-align)
Function: the horizontal text alignment of index column
T_YALIGN
Format: a float in the range 0 - 1 (0 for top, 0.5 for center, 1 for bottom)
Default value: 0 (top-align)
Function: the vertical text alignment of index column
Read-Only Options
C_COL
Format: a list of integers
Function: the GTK handlers of the GtkTreeViewColumn objects which populate the GtkTreeView widget
C_COMBO
Format: a list of integers
Function: the GTK handlers of the objects (GtkListStore or GtkAdjustment) used to define GtkCellRendererCombo and GtkCellRendererSpin
C_EMPTY
Format: a boxed list
Function: the empty row, with 0 in numeric columns, and empty strings in character columns
C_ISNUM
Format: a list of floats
Function: the content types of columns: 0=string, 1=integer, 1.5=float, 2=complex
C_LIST
Format: a list of integers
Function: the initial GTK handlers of the GtkTreeViewColumn objects which populate the GtkTreeView widget
C_POS
Format: a list of integers
Function: the initial positions of columns (used together with C_LIST to manage column movements)
C_REND
Format: a list of integers
Function: the GTK handlers of the GtkCellRenderer objects used by each GtkTreeViewColumn object
C_WIDGET
Format: a list of integers
Function: the GTK handlers of the GtkLabel widgets used as headers of each GtkTreeViewColumn object
T_COL
Format: an integer
Function: the GTK handler of the GtkTreeViewColumn object used as index column
T_EVENTFLAG
Format: an integer
Function: to manage grid events; a value of _1 is used to disable event handlers in some circumstancies
T_FIND
Format: a string
Function: the text to search requested by user in find dialogs
T_FOUND
Format: a string
Function: the text or cell (if boxed) found in last search
T_ICOL
Format: a boxed list of progressive integers, converted to strings
Function: the content of the index column
T_INVERTED
Format: a boolean value
Function: true if original data are passed as inverted table
T_MATCH
Format: a table of boolean values
Function: map of correspondance of T_FOUND inside T_BODY
T_OPTIONS
Format: a boxed list of strings
Function: the list of all names of available read/write options
T_POPUP
Format: an integer
Function: the GTK handler of the GtkMenu object used as popup menu
T_REND
Format: an integer
Function: the GTK handler of the GtkCellRenderer object used in the index column
T_REORDERED
Format: an integer
Function: auxiliary variable used when rows are reordered with drag and drop actions
T_SELECTION
Format: an integer
Function: the GTK handler of the GtkTreeSelection object (the current selection of GtkTreeView widget)
T_SELCOL
Format: an integer
Function: the index of the currently selected column, or _1 if no column is selected
T_SELROW
Format: an integer
Function: the index of the currently selected row, or _1 if no row is selected
T_SORTCOL
Format: an integer
Function: the index of te last sorted column (which has an active sort indicator)
T_STORE
Format: an integer
Function: the GTK handler of the GtkListStore object implementing the grid
T_TV
Format: an integer
Function: the GTK handler of the GtkTreeView widget implementing the grid
T_UNBOXED
Format: a boolean value
Function: true if original data are passed as unboxed table
T_VHCHECK
Format: a list of two integers
Function: the GTK handlers of the two check boxes controlling grid lines visibility
T_WIDGET
Format: an integer
Function: the GTK handler of the GtkLabel widget used as header of GtkTreeViewColumn object used as index column
Types
When a grid is initialized, each column of data is marked as numeric (if it holds just numbers)
or as string (if it holds characters, or a mix of characters and numbers).
Moreover, a numeric column is classified as integer, float or complex, depending by its content.
This information is automatically stored in C_ISNUM, which is a read-only option:
- (i{C_ISNUM)=0 --> column i is string
- (i{C_ISNUM)=1 --> column i is numeric/integer
- (i{C_ISNUM)=1.5 --> column i is numeric/float
- (i{C_ISNUM)=2 --> column i is numeric/complex
The alignment in the grid is right for numeric columns, left for string columns.
In addition to the alignment, C_ISNUM determines the default text renderer, that is used for cells editing:
- spin button for numeric/integer
- normal text entry for all other cases
Typing a non-numeric string in a cell which belongs to a numeric column, causes the automatic conversion of cell value to 0.
When a new row is appended or inserted in the grid, cells of numeric columns are filled with 0.
Anyway the default behaviours can be superseded by means of C_CHECK, C_XALIGN, C_TYPE and T_BOUND options, which are read/write options.
In particular C_TYPE and T_BOUND control the type and format of the text renderer used for cells editing, as decribed below.
C_TYPE is a complex number, whose real part selects the type of text renderer:
- ({.+.i{C_TYPE)=0 --> cells of column i have a normal text entry
- ({.+.i{C_TYPE)=1 --> cells of column i have a combo list
- ({.+.i{C_TYPE)=2 --> cells of column i have a spin button
in the last two cases, the imaginary part of C_TYPE is used as index of T_BOUND (which is a boxed list), where the contents of combo lists and spin buttons are defined;
if the indexed T_BOUND is a (boxed) empty string, a default combo list or a default spin button is used;
the default combo list is a list including all entries which are present in the column when the grid is initialized, plus a custom entry;
the default spin button is that defined by the option T_DEFSPIN (i.e. with a GtkAdjustment suitable for integer numbers).
In the following example:
]C_TYPE=: 0,1,2,1j1,2j2
0 1 2 1j1 2j2
]T_BOUND=: '';(<"0 i.25);0,_1000,1000,1,100,0,3
++------------------------------------------------------------------+----------------------+
||+-+-+-+-+-+-+-+-+-+-+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+|0 _1000 1000 1 100 0 3|
|||0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|| |
||+-+-+-+-+-+-+-+-+-+-+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+| |
++------------------------------------------------------------------+----------------------+
(pack('C_TYPE T_BOUND')) grid i.5 5
+-+
|3|
+-+
- column 0 has a normal text entry
- column 1 has a default combo list, because 0{T_BOUND is a boxed empty string
- column 2 has a default spin button, because 0{T_BOUND is a boxed empty string
- column 3 has a combo list whose content is defined by 1{T_BOUND
- column 4 has a spin button whose adjustment is defined by 2{T_BOUND
Combo lists can be used for all types of columns (including strings), while spin buttons are suitable only for integers and floats;
if the first atom of a combo list is a boxed empty string, the combo list will have a custom entry, otherwise not (as in column 3 of the above example);
the spin buttons are defined by 6 numbers to set the GtkAdjustment (initvalue,minvalue,maxvalue,step,pagestep,0), plus a 7th integer indicating the number of digits.
Actions
Actions (verbs) described below are executed when the user interacts with the grid using keyboard and/or mouse.
All these verbs are event callbacks, but most of them can also be used as methods, in scripts written by the user.
aboutdialog
Activated by popup menu or F1 shortcut;
presents a dialog window with information about jgtkgrid addon.
buttonpress
This is the event callback for mouse management;
the popup menu is shown against a right-click.
celledit
This is the event calbback when the user edits manually a grid cell.
collapse
Activated by popup menu (columns submenu);
set column auto-sizing for occupation of minimum space;
it is applied to selected column, or to all columns if none is selected.
colordialog
Activated by popup menu (tools sub-menu) or F11 shortcut;
presents a dialog window where to select grid colors.
columnchange
This is the event callback when the number of columns changes,
for example when some columns are deleted or reordered.
columnclick
This is the event callback when the user clicks on a column header;
it manages column selection and sorting.
drawpage
This is one of the event callbacks for printing management.
exitwin
Activated by popup menu or Alt+F4 shortcut;
closes the top-level window where the grid is contained.
expand
Activated by popup menu (columns submenu);
set column auto-sizing for occupation of all available space;
it is applied to selected column, or to all columns if none is selected.
filterdialog
Activated by popup menu (find sub-menu) or Shift+F5 shortcut;
presents a dialog window for filtering grid data by content of a column;
filtering function can be chosen from a default list, or can be customized;<
>
a preview of filtered result is available.
filterview
This verb supports the operation of filterdialog.
finddialog
Activated by popup menu (find sub-menu) or F3, Shift+F3, F4, Shift+F4 shortcuts,
when the T_FIND option is an empty string; presents a small
dialog window with just a GtkEntry widget, to input a search string.
findnextcell
Activated by popup menu (find sub-menu) or F4 shortcut;
selects the grid cell with the next occurrence of T_FIND (as whole cell).
findnexttext
Activated by popup menu (find sub-menu) or F3 shortcut;
selects the grid cell with the next occurrence of T_FIND (as text).
findprevcell
Activated by popup menu (find sub-menu) or Shift+F4 shortcut;
selects the grid cell with the previous occurrence of T_FIND (as whole cell).
findprevtext
Activated by popup menu (find sub-menu) or Shift+F3 shortcut;
selects the grid cell with the previous occurrence of T_FIND (as text).
findreplacedialog
Activated by popup menu (find sub-menu) or F5 shortcut;
presents a dialog window for interactive search and replace operations.
fold
Activated by popup menu (tools sub-menu);
fold text in selected column, if any, otherwise in all grid;
a dialog window asks for maximum text width (i.e. number of characters);
folding works only on non numeric columns with a normal text renderer.
fontdialog
Activated by popup menu (tools sub-menu) or F8 shortcut;
presents a dialog window where to select grid fonts.
frall
This is an event callback of findreplacedialog,
to replace all occurrences of searched text or cell.
frnext
This is an event callback of findreplacedialog,
to find the next occurrence of searched text or cell.
frprev
This is an event callback of findreplacedialog,
to find the previous occurrence of searched text or cell.
frsel
This is an event callback of findreplacedialog,
to replace the selected occurrence of searched text or cell.
helpdialog
Activated by popup menu or Shift+F1 shortcut;
presents a dialog window with the list of available keyboard shortcuts.
hlines
Activated by popup menu (grid sub-menu);
to enable or disable horizontal line visibility.
keypress
This is the event callback for keyboard shortcuts management;
it also manages cell selection through arrow keys.
makepopup
This verb is called by initgrid to build the popup menu;
the popup menu is activated by right click or Shift+Alt shortcut.
multieditdialog
Activated by popup menu (grid sub-menu) or Shift+Return shortcut;
presents a dialog window with a text area, where the user can edit a mullti-line cell.
opendialog
Activated by popup menu (tools sub-menu) or F6 shortcut;
presents a dialog window to open a grid from a text file (previously saved).
paginate
This is one of the event callbacks for printing management.
printbox
This is one of the event callbacks for printing management.
printdat
This is one of the event callbacks for printing management.
printdialog
Activated by popup menu (tools sub-menu) or F12 shortcut;
presents a dialog window for grid printing; first, a print preview is shown,
to define the format of text to be printed; then the system print dialog is shown,
including page setup, print selection and print settings (system depending).
printinv
This is one of the event callbacks for printing management.
printsep
This is one of the event callbacks for printing management.
rowchange
This is the event callback when the content of a grid row is changed.
rowdelete
This is the event callback when a grid row is deleted.
rowinsert
This is the event callback when a grid row is inserted.
savedialog
Activated by popup menu (tools sub-menu) or F7 shortcut;
presents a dialog window to save a grid as a text file;
the file is saved with T_DELIMITER as field separator,
and with LF (LineFeed) as record separator.
selchange
This is the event callback when the grid selection changes.
setoptiondialog
Activated by popup menu (tools sub-menu) or F2 shortcut;
presents a dialog window with a GtkEntry, where the user can type
custom grid options in packed form, to be passed to setoption verb.
unfold
Activated by popup menu (tools sub-menu);
unfold text in selected column, if any, otherwise in all grid;
a dialog window asks for the character(s) to be used for line-feed replacement;
unfolding works only on non numeric columns with a normal text renderer.
updatedialog
Activated by popup menu (tools sub-menu) or Shift+F2 shortcut;
presents a dialog window with two GtkEntry, where the user can type
custom grid options and grid data, to be passed to updategrid verb.
vlines
Activated by popup menu (grid sub-menu);
to enable or disable vertical line visibility.
zoomin
Activated by popup menu (tools sub-menu) or F10 shortcut;
increases font size of selected column, if any, otherwise of all grid.
zoomout
Activated by popup menu (tools sub-menu) or F9 shortcut;
reduces font size of selected column, if any, otherwise of all grid.
Methods
A complete set of methods are available to manage objects of jgtkgrid class.
All methods returns 0, because most of them are also used, in some circumstancies, as event handlers.
appendcopyrow
Monadic
Appends a copy of selected row (if any) as last row;
if no row is selected, do nothing;
if y is an empty string, the last row will be selected, otherwise current selection remains unchanged.
appendrow
Monadic / Dyadic
Appends one or more empty rows at the end of grid;
x is the number of rows to be appended (default 1);
if y is an empty string, the last row will be selected, otherwise current selection remains unchanged.
azsortcol
Monadic
Sorts data ascending for content of selected column, if any (moving rows).
azsortrow
Monadic
Sorts data ascending for content of selected row, if any (moving columns);
headers and renderers are sorted as well.
clipcopycell
Monadic
Copies selected cell (as unboxed text) to clipboard;
y is a pair or integers (row,col) indicating the cell to be copied;
if y is an empty string, the selected cell (if any) is copied.
clipcopycol
Monadic
Copies a column to clipboard (the cells, not the header);
y is an integer indicating the column to be copied;
if y is an empty string, the selected column (if any) is copied.
clipcopygrid
Monadic
Copies whole grid to clipboard.
clipcopyrow
Monadic
Copies a row to clipboard;
y is an integer indicating the row to be copied;
if y is an empty string, the selected row (if any) is copied.
clippastecell
Monadic
Pastes clipboard to selected cell (as unboxed text);
y is a pair or integers (row,col) indicating the cell to be written;
if y is an empty string, the selected cell (if any) is the destination.
clippastecol
Monadic
Pastes clipboard to a column;
y is an integer indicating the column to be written;
if y is an empty string, the selected column (if any) is the destination.
clippastegrid
Monadic
Pastes clipboard to whole grid.
clippasterow
Monadic
Pastes clipboard to a row;
y is an integer indicating the row to be written;
if y is an empty string, the selected row (if any) is the destination.
copycols
Monadic
Applies copy dyad # to grid columns;
y is an integer list indicating the columns to be copied.
copyrows
Monadic
Applies copy dyad # to grid rows;
y is an integer list indicating the rows to be copied.
cutcol
Monadic
Copies a column to clipboard and then delete it;
y is an integer indicating the column to be cut;
if y is an empty string, the selected col (if any) is cut.
cutrow
Monadic
Copies a row to clipboard and then delete it;
y is an integer indicating the row to be cut;
if y is an empty string, the selected row (if any) is cut.
deletecol
Monadic
Deletes a grid column;
y is an integer indicating the column to be deleted;
if y is an empty string, delete selected column.
deleterow
Monadic / Dyadic
Deletes one or more rows;
x is the number of rows to be deleted (default 1);
if y is an empty string, rows are deleted starting from selected row (if any);
otherwise rows are deleted starting from row y;
deleting more than one row, method stops if last row is reached.
dropcols
Monadic
Applies drop dyad }. to grid columns;
y is an integer indicating the columns to be dropped;
if y is an empty string, the columns before selected column are dropped.
droprows
Monadic
Applies drop dyad }. to grid rows;
y is an integer ibdicating the rows to be dropped;
if y is an empty string, the rows before selected row are dropped.
findnext
Dyadic
Selects a cell with matching text, searching forward;
y is a pair or integers (row,col) indicating the cell where to start the search;
if y is an empty string, the selected cell (if any) is the starting cell;
if no row/col is selected (_1), the search will start from the first row/col;
x is the string with the text to be searched;
if x is boxed the text must match whole cell.
findprev
Dyadic
Selects a cell with matching text, searching backward;
y is a pair or integers (row,col) indicating the cell where to start the search;
if y is an empty string, the selected cell (if any) is the starting cell;
if no row/col is selected (_1), the search will start from the last row/col;
x is the string with the text to be searched;
if x is boxed the text must match whole cell.
fromcols
Monadic
Applies from dyad { to grid columns;
y is an integer list indicating the columns selection.
fromrows
Monadic
Applies from dyad { to grid rows;
NB. y is an integer list indicating the rows selection.
getdata
Monadic / Dyadic
Returns grid content, converting to numbers numeric columns;
y is a list of integers indicating required columns;
if y is an empty string, all grid content is returned;
if y is boxed, the result is always a boxed table,
otherwise result is unboxed if original data was unboxed,
and result is an inverted table if original data was a boxed list of columns;
x is a scalar number to replace illegal numbers (default 0);
grid data can also be accessed directly through T_BODY, as a boxed table of characters.
initgrid
Monadic / Dyadic
This is the main method which sets-up the GtkTreeView widget;
y holds the grid data;
x holds grid options, in packed form;
users shoud not use this method in any case;
this method is used by create when a new jgtkgrid object is created,
or by the updategrid method when the GtkTreeView widget is updated.
insertcopyrow
Monadic
Inserts a copy of selected row (if any) before itself;
if no row is selected, do nothing.
insertrow
Monadic / Dyadic
Inserts one or more empty rows before an other row;
x is the number of rows to be inserted (default 1);
if y is an empty string, new rows are inserted before selected row (if any);
otherwise new rows are inserted before row y.
selectcell
Monadic
Selects a grid row and a grid column;
y is a pair or integers (row,col) indicating the cell to be selected;
if y is an empty string, unselect all.
selectcol
Monadic
Selects a grid column;
y is an integer indicating the column to be selected;
if y is _1 or an empty string, unselect selected column (if any);
multiple selections are not allowed.
selectrow
Monadic
Selects a grid row
y is an integer indicating the row to be selected;
if y is _1 or an empty string, unselect selected row (if any);
multiple selections are not allowed.
setcell
Monadic / Dyadic
Write data in a grid cell;
y is a pair or integers (row,col) indicating the cell to be written;
if y is an empty string, the selected cell (if any) is the destination;
x is the unboxed datum to be written (default empty string).
setcol
Monadic / Dyadic
Writes data in a grid column;
y is an integer indicating the column to be written;
if y is an empty string, the selected column (if any) is the destination;
x is the (boxed) list of data to be written (default empty string);
if necessary, provided data are re-shaped to fill the column.
setdata
Monadic / Dyadic
Writes data in the whole grid;
y is the number of rows to be filled;
if y is an empty string, the number of rows remains unchanged,
otherwise some rows are deleted or appended;
in all cases the number of columns cannot be modified (use updategrid for that);
if y is boxed, the check of numbers is not executed (useful for sorting);
x is the (boxed) array of data to be written (default empty string);
if necessary, provided data are re-shaped to fill the grid.
setoption
Monadic
Updates one ore more grid options;
y holds grid options to be set, in packed form;
this method is always required to change options,
in order to assure that the change has effect.
setrow
Monadic / Dyadic
Writes data in a grid row;
y is an integer indicating the row to be written;
if y is an empty string, the selected row (if any) is the destination;
x is the (boxed) list of data to be written (default empty string);
if necessary, provided data are re-shaped to fill the row.
sortcol
Monadic / Dyadic
Sorts data for content of a grid column (moving rows);
y is an integer indicating the column to be sorted;
if y is an empty string, the selected column is sorted;
x is 0 for grade-up (default), 1 for grade-down.
sortrow
Monadic / Dyadic
Sorts data for content of a grid row (moving columns);
headers and renderers are sorted as well;
y is an integer indicating the row to be sorted;
if y is an empty string, the selected row is sorted;
x is 0 for grade-up (default), 1 for grade-down.
takecols
Monadic
Applies take dyad {. to grid columns;
y is an integer indicating the columns to be taken;
if y is an empty string, the columns from 0 to selected column are taken.
takerows
Monadic
Applies take dyad {. to grid rows;
y is an integer indicating the rows to be taken;
if y is an empty string, the rows from 0 to selected row are taken.
unselectall
Monadic
unselects currently selected grid row and a grid column.
updategrid
Monadic / Dyadic
With this method it's possible to change completely the grid content and format;
y holds the new grid data;
x holds grid options, in packed form;
this is the method which allows to add or remove columns,
and to modify the types of cell renderers.
zasortcol
Monadic
Sorts data descending for content of selected column, if any (moving rows).
zasortrow
Monadic
Sorts data descending for content of selected row, if any (moving columns);
headers and renderers are sorted as well.
Test/Debug Methods
These methods are used only for debug purposes;
they provide access to grid data and options by means of GTK dll calls;
this is normally not necessary for the user, because data and options are always updated
automatically when some event occurs (i.e. T_BODY is constantly aligned with grid content).
getcell
Monadic
Returns the unboxed content of a grid cell.
getcol
Monadic
Returns a grid column as boxed list of characters.
getgrid
Monadic
Returns whole grid content as boxed table of characters.
getoption
Monadic
Returns the value of a grid option.
getrow
Monadic
Returns a grid row as boxed list of characters.
Events
When the user interacts with the grid by means of keyboard and/or mouse, the related events are locally managed by jgktgrid,
as described in the Actions section.
In order to allow an external management, for example when a cell is edited or, in general, when some change occurs in the grid,
the user can write his own events handler; this is a verb named handler and defined in the locale of the jgtkgrid object.
Whenever a change occurs in the grid, the handler verb is automatically called (if it exists).
Its argument is a boxed list of two atoms, having the form event-type;event-data
The first atom event-type is a (boxed) string indicating the type of event that has occurred.
The second atom event-data can be a (boxed) integer or a pair of integers or a string, detailing which change has occurred.
The possible calls of the handler verb are the following:
- handler 'sel-changed';row,col
- handler 'cell-changed';row,col
- handler 'row-deleted';row
- handler 'row-inserted';row
- handler 'row-changed';row
- handler 'column-changed';col
- handler 'columns-reord';columns
- handler 'grid-changed';rows,cols
- handler 'grid-updated';rows,cols
- handler 'option-set';option-name
Most actions on columns, with exception of reordering and copy-and-paste, result in a grid-updated event.
The grid-changed event occurs when the setdata method is used, while the grid-updated event
occurs when the updategrid method is used (i.e. the GtkTreeView widget is destroyed and then created again).
See also the example of handler verb provided in the script test/mygrid.ijs;
a default handler, which is the smoutput verb (just to see what's happening in the grid), can be enabled with the T_STDOUT option.
Utilities
The jgtkgrid.ijs script includes several dll calls to integrate those provided by the gui/gtk addon,
and some utilities which are used internally; in particular:
sr
dyadic
String replace
usage: (oldsubstr;newsubstr) sr string
can work also with numeric or boxed lists.
tostring
Monadic
Converts into a single string any J noun.
tostring1
Monadic
Like tostring, but uses - sign for negative numbers.
toflat
Monadic
Converts into a single string any J noun removing boxing characters.
tofloat
Monadic
Converts into a single float number any J noun.
to01
Monadic
Converts into a single float between 0 and 1 any J noun.
tocomplex
Monadic
Converts into a single complex number any J noun.
toint
Monadic
Converts into a single integer number any J noun.
tobool
Monadic
Converts into a single boolean value any J noun.
escape
Monadic/Dyadic
replaces x (optional), LF, CR, TAB, backslash with escape sequences \s, \n, \r, \t, \b.
unescape
Monadic/Dyadic
replaces escape sequences \s, \n, \r, \t, \b with x (optional), LF, CR, TAB, backslash.
isnum
Monadic
Check if a string represents a numeric value
inv2box
Monadic
Transforms a table from inverted to boxed format.
box2inv
Monadic
Transforms a table from boxed to inverted format.
pack
Monadic
Packs a boxed list of names in a two-columns table
(first column holds names, second column holds values).
unpack
Monadic
Unpacks names previously packed with pack verb.
clipwritej
Monadic / Dyadic
Modified version of clipwrite_jgtk_ verb;
y is the array to be written in clipboard (max rank=2);
x is the character used as delimiter between cells (default TAB);
boxed x forces conversion to strings (default);
unboxed x assumes that y is yet a boxed array of strings (like T_BODY);
rows are LF-delimited; TAB, CR, LF and backspace are escaped inside cells;
this allows correct paste in Excel only if cells don't include these characters;
use clipreadj to retrieve clipboard as boxed array of strings;
use clipread_jgtk_ to read clipboard as text.
clipreadj
Monadic
Modified version of clipread_jgtk_ verb;
reads as boxed array of strings the clipboard previously written with clipwritej;
y is the character used as delimiter between cells (default TAB).
getactive
Monadic
Returns cursor position (row,col) and current selection (sel);
y must be a GtkTreeView widget, having a GtkListStore as model.
setactive
Monadic
Sets cursor position (row,col) and current selection (sel)
in a GtkTreeView widget, having a GtkListStore as model;
y is a list with up to four integers (widget,row,col,sel).
getparent
Monadic
Returns the parent container of a GtkWidget
getwindow
Monadic
Returns the top level window of a GtkWidget
Class
An example of how use the jgtkgrid class in a generic JGTK application is provided in the script test/mygrid.ijs.
In general, a new jgtkgrid object is created by means of conew verb and then create method.
Then, the GtkTreeView widget is put in a GtkContainer (which is normally a GtkScrolled), and this one is put in a GtkWindow, together with all other widgets required for the application.
A proper handler verb should be written to handle grid Events, if necessary.
Other event handlers written for the widgets of the window can use jgtkgrid methods to interact with the grid.
The destroy method for the jgtkgrid object should be used inside the handler of the destroy event of the GtkWindow.
A script like test/mygrid.ijs can be launched as a stand-alone application directly from the command line
(i.e. without opening a J session on a terminal) with the following syntax:
windows: pathtojbinaries\jconsole.exe pathtojaddons\gui\jgtkgrid\test\mygrid.ijs linux: pathtojbinaries/jconsole pathtojaddons/gui/jgtkgrid/test/mygrid.ijs
The popup menu is accessible with the mouse right click, and allows to carry out common actions on the grid.
The content of popup menu can be customized by means of T_MENU option, which is a boxed list of string controlling the list of commands to be shown in the menu.
T_MENU can hold one or more of the following (boxed) strings:
all show all commands row show all row-related commands:copyrow pasterow cutrow deleterow appendrow insertrow appendcopyrow insertcopyrow takerows droprows azsortrow zasortrow unselectrow clearrow col show all column-related commands:copycol pastecol cutcol deletecol takecols dropcols azsortcol zasortcol expand collapse unselectcol clearcol grid show all grid-related commands:copygrid pastegrid unselectall cleargrid multiedit find show all find-related commands (to search for text or whole cell content):findnext findprev findnextcell findprevcell findreplace filter tools show all tools-related commands:open save print font color zoomin zoomout fold unfold setoption updategrid exit show the exit command to close the window any of the commands listed above
If a command in T_MENU is prefixed with an exclamation point (fo example !updategrid), the corresponding menu item is disabled.
Most of menu commands are self-explicative, because they refer to corresponding methods.
Row and column commands have effect only if a row or column is selected.
pasterow, pastecol, pastegrid should be used only after copyrow, copycol, copygrid respectively.
multiedit shows a dialog window where the user can edit the content of selected cell in a multi-line scrolled text area.
setoption shows a dialog window where the user can type an argument to be passed to setoption method
(i.e. a boxed list option_0;value_0;option_1;value_1;...;option_N;value_N).
updategrid shows a dialog window where the user can edit the left and right arguments (options and data)
to be passed to updategrid method, allowing a complete re-definition of grid format and content.
open, save, print and other tools show several dialog windows for grid management;
font, color, zoomin, zoomout, fold, unfold operate on selected column, if any, otherwise on all columns.
Keyboard shortcuts
When the grid has the focus on it, the following keyboard shortcuts are available:
Esc unselect all (equivalent to left-click on index column header) Return edit selected cell Ins insert row Del delete row Backspace delete column F1 show about dialog F2 show set option dialog F3 find next text F4 find next cell F5 show find and replace dialog F6 show open grid from file dialog F7 show save grid to file dialog F8 show font selection dialog F9 zoom out (reduce characters size) F10 zoom in (increase characters size) F11 show foreground color selection dialog F12 show print grid dialog Shift+Alt show popup menu Shift+Return multi-line edit dialog Shift+Ins append row Shift+Del clear row Shift+Backspace clear column Shift+F1 show help dialog Shift+F2 show update grid dialog Shift+F3 find previous text Shift+F4 find previous cell Shift+F5 filter dialog Ctrl+C copy row Ctrl+V paste row Ctrl+X cut row Ctrl+Shift+C copy column Ctrl+Shift+V paste column Ctrl+Shift+X cut column
The effective availability of shortcuts is controlled by the same option T_MENU, which controls the Popup menu.
Todo
- Hierarchical grids (based on GtkTreeStore)
- Multiple selections
- jgtkgrid sub-classes