J6/Grid/Events

Isigraph Events

The grid is drawn on an isigraph control, and events for the control are typically passed to the grid object. This can be set up automatically when the grid is initialized. You can also create your own event handlers.

The isigraph events supported are:

char copy mbldbl mbldown mblup mmove paste size undo

For example, suppose the form parent name is form and isigraph control id grid. Suppose also that the grid locale name is gridloc, i.e. the grid instance has been created as:

gridloc=: conew 'jzgrid'

Then event handlers are created as:

form_grid_mmove=: mmove__gridloc

Note that it is conventional to use the same name for the grid locale as for the isigraph control, but in these examples, different names are used.

Event handlers that are already defined are left unchanged. For example, you could create an event handler that did some processing, then called the corresponding grid event handler, as in:

form_grid_mmove=: 3 : 0
NB. add pre-processing code here
mmove__gridloc''
NB. add post-processing code here
)

Other Form Events

You should create explicit event handlers for form events that are to be handled by the grid. For example, if your form has a flip button that transposes the grid, then create a form handler as in:

form_flip_button=: flip__gridloc

Signalled Events

The grid can also pass events back to the form locale. To enable this, define a grid event handler with a name based on the isigraph control id, followed by _gridhandler . For example if the control id is g , then define verb g_gridhandler .

Before your gridhandler is called, a few global names are set for its convenience. Not all names are set for all handlers. The meanings of the variables are given in the following table, and the names of the variables that are set for each event are listed in the description of the event.

Row	Row number of the selected cell (negative values for column headers)
Col	Column number of selected cell (negative values for row labels)
Px	Horizontal cursor position in cell, as fraction (0=left, 1=right)
Py	Vertical cursor position in cell, as fraction (0=top, 1=bottom)
Ctrl	1 if CTRL was held down during the keypress/click
Shift	1 if SHIFT was held down during the keypress/click
Value	The subarray of CELLDATA corresponding to the selected region
Cell	The x,y position in the grid of the top-left of the selected region
Type	1 if cell is being typed into directly, 2 if cell is in edit mode
Text	Value of edited cell, as a string
Rws	A list of the row numbers that are to be fetched
Cls	A list of the column numbers that are to be fetched
Dim	The number of the axis along which the grid is to be sorted
Char	The character that was pressed

The events signalled are:

Mouse events (Px, Py, Row, Col, Ctrl, Shift are set for each):

click	mouse left click in grid
dblclick	mouse left double click in grid
rclick	mouse right click in grid
rdblclick	mouse right double click in grid

Other events (and the global names that are set):

change	after cells have changed and before CELLDATA is updated (Value, Cell)
changed	after CELLDATA is updated, following a change event (Value, Cell)
edit	immediately before the grid enters edit mode (Type, Text, Cell)
focus	when grid gets focus (no names set)
focuslost	when grid loses focus (no names set)
get	get data request in virtual mode (Rws, Cls)
gridsort	immediately before the grid is sorted (Row, Col, Dim)
key	key press, if not in edit mode or combo list selection (Char, Ctl, Shift)
mark	called each time a cell is marked, or the current mark is extended. The event is signalled after any grid updates are done, so that the grid has no further processing to do.

A single isigraph event may signal two grid events. For example, double click in an editable cell first signals the dblclick event, then the edit event.

A cell change also signals two events - change after cell is changed and before data is updated; and changed after the data is updated. Note that the changed event is part of cell change - it is not signalled if a write is called under program control, or if the gridhandler returns 0 (no further processing) after the change event.

The verbs that call the grid handler have the same name as the event name, and call the handler with an argument of the event name. You can examine the definition of the calling verb to see the state when the handler is called.

The result of the handler must be a boolean: 0=no further execution, 1=continue normal execution, if any. Where execution normally continues, it is in a verb with the name of the event suffixed with x.

(!) Note: if the handler calls another grid instance or gl2 based control, the calling grid may lose the gl2 context. In this case, set it back with glsel_jgl2_ gridid.

The following is a typical handler definition. In this case, when the grid enters edit mode, the text to be edited is replaced with the text shown:

grid_gridhandler=: 3 : 0
res=. 1 NB. typically want to continue processing
select. y
case. 'change' do.
  NB. code to handle grid change here
case. 'edit' do.
  Text__gridloc=: '123.45'
end.
res
)

The following is a typical calling definition in the code for the grid. Note that parameters are globally defined so they are available to the grid handler, and the final call to verb editx.

NB.  type = 1 or 2
NB.  text = initial text string
NB.  cell  = absolute cell reference
edit=: 3 : 0
'Type Text Cell'=: y
if. gridhandler 'edit' do.
  editx ''
end.
)