QGrid

Using the plug-in


Setting up a QGrid area

To set up a QGrid area you first have to draw one. The grid area is a normal 4D plug-in area object that can be set to be resizeable, have a background color, etc. Refer to the Command Reference for detailed usage information of each command by following the links. It is also adviseable that you first go through the pages describing how QGrid handles expressions and drag and drop.

Declare the number of cells

The first thing we have to declare is the number of cells in the grid. To do this we define a 4D number expression for QGrid to use each time it needs to calculate the number of cells in the grid area. The declaration of the size expression should be the first thing to do when setting up a QGrid area.

The definition is done using QG_SetNumCells. A suitable expression, i.e. one that calculates the number of cells, is expected as a parameter:

C_TEXT($xpression)

$xpression:="Records in selection([Images])"

$err:=QG_SetNumCells ($area;$xpression)

Describe cell geometry and appearance

QGrid lets you define the geometry and appearance of each cell. Cells may have a background picture that can be any 4D picture: field, variable, PICT resource, Picture Library item, or whatever.

In the snippet below you can see how QGrid makes your life easier when you use a background picture. Because we usually want background pictures to occupy the entire cell area, you don't need to set the cell size in pixels. Instead, pass -1 in both dimensions and QGrid will use the background size as the cell size:

GET PICTURE FROM LIBRARY(15445;$pict)

$w:=-1  `cell width equals bkg pict width
$h:=-1  `cell height equals bkg pict height
$format:=qg_PictScaledToFit

$err:=QG_SetCellOptions ($area;$w;$h;$pict;$format)

Define the picture object

In order to define the picture object you need to define a 4D picture expression that will be used for calculating the picture to be displayed, its position within the cell boundary, and, possibly, a picture formatting method.

Each time a grid cell needs to be displayed, QGrid calls the picture object's expression to calculate the picture to be displayed.

The picture object definition is done using QG_SetCellPicture.

Define the caption object and its style

In the same way as you defined the picture object, proceed and define the caption object. Of course the expression you supply must be a text expression and the format appropriate to text.

The caption object definition is done using QG_SetCellCaption.

The appearance of the caption text is defined using QG_SetCaptionStyle that lets you define the font, size, style, justification and colors:

$font:="Geneva"
$size:=9
$face:=Plain
$fJust:=qg_JustLeft
$fForeClr:=0x002266DD
$fBackClr:=qg_NoFillColor

$err:=QG_SetCaptionStyle ($area;$font;$size;$face;$fJust;$fForeClr;$fBackClr)

User selection options

QGrid lets you define how the grid will react to user selection. The default behavior is to allow multiple cells to be selected, and visualize the selection by a highlight of a red 2-pixel-stroke rectangle around each selected cell.

Using the QG_SetSelectionOptions command as in the snippet below, you can customize the selection allowance (multiple cells, one cell, no cell), as well as the precise width and color of the highlight rectangle. Use the constants that QGrid defines for this purpose; they will make your job easier and your code will be self-documented:

$option:=qg_SelectManyTiles
$color:=0x00FF8844
$width:=2

$err:=QG_SetSelectionOptions ($area;$option;$color;$width)

 

When you have set the grid to accept multiple selection, you can use the usual modifier keys together with the mouse in order to extend (Shift-click) or toggle (Cmd-click) a cell selection.

Intercepting events

QGrid allows you to intercept click, double-click and drop events on the grid area. To accomplish this, install a QGrid event handler method using the command QG_SetEventHandler. A sample snippet that installs an event handler for all three events looks like this:

$mask:=qg_TrapClickEvent+qg_TrapDoubleClickEvent+qg_TrapDropEvent

$err:=QG_SetEventHandler (xGrid;"P_QG_Handler_List";$mask)

 

The event handler is the only way for intercepting form events associated with the grid. Do not attempt to handle events in the grid area's object script (it will not work).