Using the Grid Component in Desktop Applications - Feature Pack

To purchase this Feature Pack, please click here.


The Grid Component in Desktop Applications Feature Pack allows you to use a Grid Component in a Desktop application in two different ways:

  1. Embed a Grid Component into a Form
  2. Use Action Scripting to open a window that contains a Grid Component.


Watch Video - Embedded a Grid in a Form


Watch Video - Using Action Scripting to open a Grid Component in a Desktop Application - Part 1

Watch Video - Using Action Scripting to open a Grid Component in a Desktop Application - Part 2


Why Use a Grid Component in a Desktop Application?

There are several reasons why using a Grid Component in a Desktop application can be advantageous:


Embedding a Grid Component into a Form

When you embed a Grid component into a Form you can filter and/or link the Grid component. The filter and link can be static or dynamic.

With a dynamic filter and/or link, the filter and link parameter are dynamically calculated based on data shown in the current record in the Form. So, for example, if you have linked the Grid by matching the 'customerId' field in the Grid with the 'customerId' field shown in the Form, then as you navigate from one record in the Form to another, the records shown in the embedded Grid are automatically filtered based on the current value of the 'customerId' field in the Form.

On the other hand, with a static link or filter, the records in the Grid are filtered when the Form is opened, and when you navigate from one record in the Form to the next record, it has no impact on the records shown in the Grid.

Filtering and Linking

Both 'filtering' and 'linking' control the records shown in the Grid. When you 'link' a Grid you supply matching field pairs from the Form and the Grid. E.g. You specify that the 'fname' field in the Form matches the 'firstname' field in the Grid and the 'lname' field in the Form matches the 'lastname' field in the Grid. This filters the Grid so that only records that match the current record in the Form are shown, but in addition, (and very importantly) when you add a new record to the Grid, the linked fields ('firstname' and 'lastname' in this example) are automatically populated with the matching values in the Form (from 'fname' and 'lname' in this example).

On the other hand when you 'filter' the Grid, you supply a filter expression. When a new record is added into a 'filtered' Grid, no fields in the Grid are automatically filled in, and so the new record is not automatically 'linked' to a parent record.


How to Embed a Grid into a Form

To embed a Grid into a Form:

1. Put the form into Design mode

2. From the Form toolbox, select the 'SuperControl' tool.


3. Draw an area on the Form where you want the embedded Grid to appear.

    The 'Insert Supercontrol' dialog will appear.

4. Select the 'Embedded Grid Component' option.



    Next, the Genie appears where you can select the Grid and specify the link/filter.



5. Click the smart field button to specify the component name, filter, link, and override settings (if any).


In addition, you can specify the relative font size for the Grid. The default setting is 'Smaller' which make the Grid look consistent with the default font size on Form layouts.

The 'Background color mode' property allows you to control the background color of the window in which the Grid component is displayed. The choices are:




This is an important aesthetic issue because you need to keep in mind that a Form can use a gradient background. The Grid component, on the other hand does not have the ability to use a 'transparent' background, which would let the Form's gradient background 'shine through' and be visible as the Grid background. It is therefore recommended that you do not use a gradient background on the Form, but rather a solid color. If you then set the 'Background color mode' to 'FormColor' the Grid component will blend perfectly into the Form. The 'GridComponentColor' uses the color defined by the Grid style sheet.


The screenshot below shows a form based on the Customer table in Alphasports. A Grid that shows records from the Invoice_header table is embedded into the Form. The Grid is linked to the Form on the common 'customer_id' field so that the Grid is showing order that the current customer has placed. Because the Grid is linked to the current record, if a new record is added into the Grid, the new record will automatically inherit the 'customer_id' value from the Form.




Using Action Scripting to Open a Window Showing a Grid Component

In addition to embedding a Grid component in a Form, you can also use Action Scripting to put buttons on Forms that open Grid Components in windows, much like you use Action Scripting to put buttons on Forms that open other windows that contain other Forms.

To create a new action in an Action Script to open a Grid component, click the Add New Action button.

Select the 'Grid Components' category and the 'Open a Grid Component' action.



When you click OK, the builder appears:

The builder exposes a large number of properties, shown in the three screen shots below. Most of the properties are optional.

When you click the smart field next to the Grid component name property another builder opens, allowing you to select the Grid component  name, and specify the filter and/or link for the Grid component. If you are opening the Grid component from a button in a Form or Browse, you will typically want to link the Grid to the current record in the Form or Browse, or filter the Grid based on data in the current record.

Some of the more important properties are discussed below.







Property Description
Window type Allows you to specify if the pop-up window is modal, modeless, or a MDI window.


If you choose modeless or MDI the 'Allow multiple instances' property controls whether more than one instance of this window can be opened at a time.

Menu and Toolbar For MDI windows, allows you to specify a custom menu and toolbar to display for the window.
Stretchable - Height, Stretchable - Width Allows you to specify if the window can be resized. MDI windows can always be resized regardless of the setting for these properties.
Remember size, Remember position Alpha Five can remember the size and position of the window so that the next time you open it, it use the same size (if the window was stretchable) and position. In order to remember the size and position, you will specify the name of registry key where this data is to be stored. Be sure to give each window a unique name.
Refresh parent window If the script that opens the Grid component window is run from a button on a Form or Browse, and the pop-up window is Modal, you can specify that when the pop-up window containing the Grid is closed, the parent Form or Browse should be refreshed. This is useful if the Grid is editing the same record shown in the Form or Browse and you want the record shown in the Form or Browse to reflect any edit that were made in the Grid when the Grid is closed.
Prevent window close if Grid is dirty This allows you to stop a user from closing the window if the Grid contains unsaved edits. Otherwise, if the user closes the window without first saving their edits, the edits will be lost.
OnWindowClose, CanWindowClose events These two properties allow you to define Xbasic code to execute before and after the window is closed. The CanWindowClose event can prevent the user from closing the window if certain conditions have not been met.
Free-form Xdialog Sections These properties allow you to inject any Xdialog markup above, below, to the left or right of the Grid in the window.



Sending Commands to a Grid Component that is Embedded in a Form

The A5_sendCommandToEmbeddedGrid()  function allows you to use Xbasic to send commands to the embedded Grid component. More accurately, it allows you to send Javascript commands to the HTML page that hosts the embedded Grid component. The Javascript could execute any of the Grid object's methods.


A5_SendCommandToEmbeddedGrid(P EmbeddedGridObj, C JavascriptCommands)

When you place an embedded Grid in a form, the embedded Grid will have an Xbasic object name (distinct from the Grid object name). For example, the objectname might be 'xdialog1' ('xdialog' because the embedded Grid is actually built on top of an embedded Xdialog). You are, of course, free to change the object name if you wish by right clicking on the object in the Form editor.

Assume you want to put a button on the form to cause the embedded Grid to refresh. Here is the Xbasic for the button:


dim obj as p

'get a pointer to the container object for the embedded Grid

obj = topparent:xdialog1.this


If you want to call a method of the Grid object, you must use the {grid.object} placeholder to reference the embedded Grid object.