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 on each command.

Before going further, make sure to have read the pages on expressions and drag and drop.

Then, follow these steps, ideally in the order they are presented below:

Step 1: Describe cell geometry and background

Cells may have a background picture which can be any picture that 4D can handle.

To instruct QGrid that the background picture should occupy the entire cell, pass -1 in both dimensions. Here's how the code looks like:

   // Load the cell background picture from the resources folder
C_TEXT($cellImagePath)
$cellImagePath:=Get 4D folder(Current resources folder)+"Cells"+Folder separator+"Cell.png"
ASSERT(Test path name($cellImagePath)=Is a document)

C_PICTURE($cellPict)
READ PICTURE FILE($cellImagePath;$cellPict)
ASSERT(OK=1)

   // Configure the cell
C_LONGINT($cellWidth;$cellHeight;$err)

$cellWidth:=-1// Cell width equals background pict width
$cellHeight:=-1// Cell height equals background pict height

$err:=QG_SetCellOptions (xGrid;$cellWidth;$cellHeight;$cellPict;qg_PictScaledToFit)
ASSERT($err=qg_noErr)

Step 2: Define the grid's layout

In this step you may define cell spacing, to give your cells some breathing space, as well as the alignment of the cells within the area.

   // Configure other layout characteristics of the plug-in area
   // Leave 10 pixels of space between the cells horizontally and vertically
$err:=QG_SetCellSpacing (xGrid;10;10)
ASSERT($err=qg_noErr)

   // Align cells to the top-left of the plug-in area
$err:=QG_SetAreaAlignment (xGrid;qg_AlignHorzLeft;qg_AlignVertTop)
ASSERT($err=qg_noErr)

Step 3: Configure the picture object

The picture object houses the cell's image content, which in turn is obtained using the picture expression. The picture expression is called each time QGrid needs to display a cell.

The picture object definition is done using QG_SetCellPicture.

Besides the image that will be shown in the picture object, you will at least need to define the picture object's position within the cell:

   // Configure the picture object

C_TEXT($pictExpression)
$pictExpression:="DB_GetGridPicture(gQGCurrentCell)"

C_LONGINT($pictLeft;$pictTop;$pictRight;$pictBottom;$display)
$pictLeft:=10
$pictTop:=10
$pictRight:=130
$pictBottom:=130

$display:=qg_PictXScaledToFitPropCenter

$err:=QG_SetCellPicture (xGrid;$pictExpression;$pictLeft;$pictTop;$pictRight;$pictBottom;$display)
ASSERT($err=qg_noErr)

Step 4: Configure the caption object

In the same way you defined the picture object, now define the caption object. The caption expression must obviously return text, and its formatting should be appropriate for text.

The caption object definition is done using QG_SetCellCaption.

Caption style is configured using QG_SetCaptionFont, QG_SetCaptionColors and QG_SetCaptionAlignment:

   // Configure the caption object

C_TEXT($captExpression)
$captExpression:="DB_GetGridCaption(gQGCurrentCell)"

C_LONGINT($captLeft;$captTop;$captRight;$captBottom)
$captLeft:=140
$captTop:=10
$captRight:=260
$captBottom:=130

$err:=QG_SetCellCaption (xGrid;$captExpression;$captLeft;$captTop;$captRight;$captBottom;"")
ASSERT($err=qg_noErr)

   // Set caption font depending on platform
C_LONGINT($platform)
PLATFORM PROPERTIES($platform)

If ($platform=Windows)
   $err:=QG_SetCaptionFont (xGrid;"Segoe UI";8;0)
Else 
   $err:=QG_SetCaptionFont (xGrid;"Lucida Grande";10;0)
End if 
ASSERT($err=qg_noErr)

   // Set caption text color to 50% gray, background to transparent
$err:=QG_SetCaptionColors (xGrid;0x007F7F7F;qg_NoFillColor)
ASSERT($err=qg_noErr)

   // Align text to the left and center vertically
$err:=QG_SetCaptionAlignment (xGrid;qg_AlignHorzLeft;qg_AlignVertCenter)
ASSERT($err=qg_noErr)

Step 5: Configure user selection options

QGrid can be programmed to support user selection in various ways. The default behavior is to allow for a single cell to be selected at a time, and visualize the selection with a red 2-pixels-wide rectangle around the selected cell.

Using QG_SetSelectionOptions you can customize all selection options: how many cells are allowed for selection (one, many, none), and how the selection is visualized (width and color of the rectangle). Using the constants that QGrid defines for this purpose, will make your life easier and your code self-documenting:

   // Configure cell selection options
   // Multi-cell selection mode, red selection frame 4 pixels thick
$err:=QG_SetSelectionOptions (xGrid;qg_SelectManyCells;0x00FF0000;4)
ASSERT($err=qg_noErr)

NOTE When the grid is set up for multiple selection, the usual modifier keys can be used together with the mouse in order to extend (Shift-click) or toggle (Cmd-click) the selection of cells.

Step 6: Configure the Drag and Drop feedback

QGrid supports drag and drop from/to any suitable 4D object using 4D's mechanism that you're probably familiar with.

The visual feedback of the drag and drop operation on a droppable QGrid area can be customized to suit your taste:

   // Configure drag and drop feedback

   // Set the drag caret to 2 pixels thick, blue, decorated, blinking.
$err:=QG_SetDragOptions (xGrid;qg_UseBlinkingCaret | qg_UseDecoratedCaret;2;0x00FF;30)
ASSERT($err=qg_noErr)

Step 7: Grid events

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

   // Configure the event handler

$err:=QG_SetEventHandler (xGrid;qg_TrapClickEvent | qg_TrapDoubleClickEvent;"DB_GRID_EVENT")
ASSERT($err=qg_noErr)

WARNING 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)!

Step 8: Declare the number of cells

Finally, complete the setup procedure by supplying the number of cells in the grid. To do this, define a 4D expression yielding a numeric result, which QGrid will use each time it needs to calculate the number of cells.

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

   // Configure the number of cells

C_TEXT($expression)
$expression:="Records in selection([Photos])"

$err:=QG_SetNumCells (xGrid;$expression)
ASSERT($err=qg_noErr)