Grids

Purpose:	Display a table in a grid format. Use an existing VisualNEO for Windows Rectangle object to serve as host for the grid. You can customize the appearance of the grid using dbpSetGridProperties, dbpSetGridBackground, dbpSetFieldProperties, dbpSetColumnTitles, dbpSetColumnWidths and dbpSetRowHeight.
Category:	Grids
Syntax:	dbpShowGrid "database id" "table" "rectangle" database id The name assigned to the database containing the table you want to display. table The name of the table to display. rectangle The name of an existing VisualNEO for Windows Rectangle object. The Rectangle will serve as a host for the table grid. Use VisualNEO for Windows's Tool Palette to create a Rectangle object on the page in your publication where you want the grid to appear. After executing dbpShowGrid, the grid will appear within the boundaries of the Rectangle object. The grid is only visible when the publication is running. Rectangle object before dbpShowGrid: Rectangle object after dbpShowGrid:
Example:	dbpShowGrid "AddrBook" "Contacts" "Rectangle1"
SQL Equivalent:	N/A

Purpose:	Remove a grid previously displayed with the dbpShowGrid action.
Category:	Grids
Syntax:	dbpHideGrid "database id" "table" database id The name assigned to the database containing the table. table The name of the table whose grid you want to hide.
Example:	dbpHideGrid "AddrBook" "Contacts"
SQL Equivalent:	N/A

Purpose:

Customize the visual appearance and behavioral properties of a grid.

Category:

Grids

Syntax:

dbpSetGridProperties "database id" "table" "properties"

database id

The name assigned to the database containing the table.

table

The name of the table whose grid you want to customize.

properties

This is a compound parameter and can contain any combination of the following items:

Color=color

The color used for the background of the grid cells in odd numbered rows. See Defining Colors and dbpSetGridBackground.

Font=font

The font name, size, style and character set of the font used for the grid cells. See Defining Fonts.

FontColor=color

The color used for the grid cell text in odd numbered rows. See Defining Colors.

AlternateRowColor=color

The color used for the background of the grid cells in even numbered rows. See Defining Colors.

AlertnateRowFontColor=color

The color used for the grid cell text in even numbered rows. See Defining Colors.

RowHeight=number

The height (in pixels) of the grid's rows.

TitleColor=topcolor+bottomcolor

The color used for the background of the column headings. This can be either a single color to create a solid fill or two colors to create a gradient fill. To create a gradient, separate the top and bottom colors with a plus (+) sign. See Defining Colors.

TitleFont=font

The font name, size, style and character set of the font used for the column headings. See Defining Fonts.

TitleFontColor=color

The color used for the column heading text. See Defining Colors.

TitleRowHeight=number

The height (in pixels) of the column heading row.

HighlightColor=topcolor+bottomcolor

The color used for the background of the selected cell. This can be either a single color to create a solid fill or two colors to create a gradient fill. To create a gradient, separate the top and bottom colors with a plus (+) sign. See Defining Colors.

HighlightFontColor=color

The color used for the selected cell's text. See Defining Colors.

EditColor=color

The color used for the background of the cell being edited. See Defining Colors.

EditFontColor=color

The color used for the text in the cell being edited. See Defining Colors.

ShowTitles=yes/no

Yes = display the column heading row. No = do not display the column heading row.

3DTitles=yes/no

Yes = add a 3D shadow effect to the column heading row and indicator column. No = no 3D effect.

ShowGraphics=yes/no

Yes = display picture fields in the grid. No = don't display picture fields.

ShowIndicator=yes/no

Yes = display an indicator along the left side of the grid identifying the active row. No = do not display an indicator.

ShowColumnLines=yes/no

Yes = draw vertical lines between columns. No = do not draw lines between columns.

ShowRowLines=yes/no

Yes = draw horizontal lines between rows. No = do not draw lines between rows.

GridLineWidth=number

The thickness (in pixels) of the grid lines.

GridLineColor=color

The color of the grid lines. See Defining Colors.

AllowRowResize=yes/no

Yes = user may use the mouse to manually adjust the row height. No = user is prohibited from adjusting the row height.

AllowColumnResize=yes/no

Yes = user may use the mouse to manually adjust the column widths. No = user is prohibited from adjusting the column widths.

AllowColumnSort=yes/no

Yes = the user can sort the table by clicking on the column headings. No = user cannot sort the table.

ConfirmDelete=yes/no

Yes = requires user confirmation when clicking the delete button in a grid's navigation bar. No = no confirmation required for deletes. The confirmation dialog can be customized using the dbpTranslateHints action.

ReadOnly=yes/no

Yes = the table cannot be edited from the grid. No = grid allows editing.

EditOnly=yes/no

Yes = existing records in the table can be edited, but no new records can be added from the grid. No = allow new records to be added from the grid.

RowSelect=yes/no

Yes = the entire row will appear selected. No = only individual cells can be selected. When RowSelect=Yes, the grid does not permit editing.

ShowScrollBars=value

This option determines whether the grid includes horizontal and vertical scroll bars. Value may be one of the following:

Auto	Display both horizontal and vertical scroll bars (if needed).
Horizontal	Display only the horizontal scroll bar (if needed).
Vertical	Display only the vertical scroll bar (if needed).
None	Do not display scroll bars.

ShowNavigationBar=yes/no

Yes = display a navigation bar at the bottom of the grid. No = do not display a navigation bar.

GetDefaultValues=yes/no

Yes = when a new record is created, attempt to retrieve the default field values from the database server. No = do not retrieve the default values.

Note: Normally, a database server will not apply default field values (defined with dbpCreateTable) until a record is posted. When using a grid to insert new records, this behavior causes fields to appear empty instead of displaying their default values. Only when the record is posted will the default values display.

When GetDefaultValues = Yes, NeoDBpro will attempt to retrieve and apply the default values for each field at the time the record is inserted. Setting GetDefaultValues to "No" tells NeoDBpro to let the database server handle default field values normally.

You can override the server's default field values with the DefaultValue property of the dbpSetFieldProperties action.

OnDoubleClick=subroutine

The name of a subroutine from your publication's Subroutine Action. The subroutine specified here will be executed whenever the user double clicks anywhere within the grid. You can use the dbpGetActiveField action in the subroutine to determine which field was clicked if needed. Subroutines are entered from the Actions page of VisualNEO for Windows's Book Properties screen.

Separate multiple items in a compound variable with semicolons (;). Because of the large number of options, it is recommended that you use the wizard provided for the dbpSetGridProperties Action.

Example:

dbpSetGridProperties "AddrBook" "Contacts" "Color=White;AlternateRowColor=Silver"

dbpShowGrid "AddrBook" "Contacts" "Rectangle1"

SQL Equivalent:

N/A

Purpose:	Specify an image to serve as the grid's background. The background image will override the background color settings specified in dbpSetGridProperties. If the image is smaller than the grid, it will be tiled. To restore the grid's normal appearance, leave the file name parameter blank.
Category:	Grids
Syntax:	dbpSetGridBackground "database id" "table" "image file" database id The name assigned to the database. table The name of the table. image file The name of the image file to use as the grid's background. Supported image formats are bmp, gif, tiff, png and jpeg. Leave this parameter blank to clear the background image.
Example:	dbpSetGridBackground "AddrBook" "Contacts" "C:\Images\PolishedSteel.png"
SQL Equivalent:	N/A

Purpose:

Define the formatting and edit properties of a field.

Category:

Grids

Syntax:

dbpSetFieldProperties "database id" "table" "field" "properties"

database id

The name assigned to the database.

table

The name of the table containing the field you want to modify.

field

The name of the field to modify.

properties

This is a compound parameter and can contain any combination of the following items:

Alignment=value	Alignment method used to display the field's contents. Can be either Left, Right or Center.
TitleAlignment=value	Alignment method used to display the field's column header. Can be either Left, Right or Center.
PickList=list items	A list of possible values that can be selected by the user for input into the field. When editing in grid mode, a field that has been assigned a pick list will function like a combo box allowing the user to select list items from a drop down window.
DropDownRows=number	The size (in lines) of the PickList drop down window.
DisplayFormat=value	This option can be used to specify the display format used for date/time and numeric field types. The display format affects the appearance of the field values in both the grid and VisualNEO for Windows field variables. See Formatting Fields for more information.
EditMask=mask	A validation mask used to restrict what can be entered into the field. Any invalid characters entered are rejected. Leave this item blank to allow any characters to be entered. See "Text Entry Field Tool > Validation Mask" in VisualNEO for Windows's Help file for information on constructing an edit mask.
DefaultValue=value	A default value to be assigned to the field when a new record is created. This value must be compatible with the field's type. Note: This value takes precedence over any default values for the field implemented on the database server (defined with dbpCreateTable) See also dbpSetGridProperties > GetDefaultValues.
ValidChars=chars	A list of characters (letters, numbers or punctuation) that can be entered into the field. Leave this item blank to allow any characters to be entered.
ColumnWidth=number	The width (in pixels) of the field's column in the grid.
ReadOnly=yes/no	Yes = the field cannot be edited from the grid. No = grid allows editing.
Visible=yes/no	Yes = the field is displayed in the grid. No = the field does not appear in the grid.

Separate multiple items in a compound variable with semicolons (;).

Example:

dbpSetFieldProperties "MySQL" "Table1" "[ListBox6]" "Alignment=Left;TitleAlignment=Left; PickList=Apple,Orange,Cherry,Grape,Pear,Strawberry; DropDownRows=7;EditMask=;ValidChars=;ColumnWidth=30;ReadOnly=No;Visible=Yes"

SQL Equivalent:

N/A

Purpose:	Returns the name of the field in the grid that is highlighted or active.
Category:	Grids
Syntax:	dbpGetActiveField "database id" "table" "variable" database id The name assigned to the database. table The name of the table. variable The name of the variable where the name of the active field will be stored.
Example:	dbpGetActiveField "AddrBook" "Contacts" "[SelField]" If "[SelField]" ">" "" dbpSort "AddrBook" "Contacts" "[SelField] ASC" EndIf
SQL Equivalent:	N/A

Purpose:	Customize the titles that appear at the top of each column in a grid. A grid contains one vertical column for each field in the table. By default, the column titles are the same as the field names, which can sometimes be a little cryptic. You can use this action to change only the column titles without affecting the names of the fields.
Category:	Grids
Syntax:	dbpSetColumnTitles "database id" "table" "titles" database id The name assigned to the database. table The name of the table. titles A list containing the original field name, an equal sign and the title to be assigned to each column. Separated multiple items with a semicolon character (;). For example, the column titles for a table containing six fields (FIRSTNAME, LASTNAME, STREET, CITY, STATE, ZIP) might look like this: "FIRSTNAME=First Name;LASTNAME=Last Name;STREET=Street;CITY=City;STATE=State;ZIP=Postal Code" It is not necessary to include every field in the list. You can shorten the action by including only the field's that you want to change. Field's not in the list will retain their existing column titles. For example: "FIRSTNAME=First Name;LASTNAME=Last Name;ZIP=Postal Code"
Example:	dbpSetColumnTitles "AddrBook" "Contacts" "FirstName=First Name;LastName=Last Name;State=State/Prov;Zip=Postal Code"
SQL Equivalent:	N/A

Purpose:	Specify the order in which columns/fields appear in the grid.
Category:	Grids
Syntax:	dbpSetColumnOrder "database id" "table" "field list" database id The name assigned to the database. table The name of the table. field list A list of the field names in the order you want them to appear in the grid. Each field name must be separated by a semicolon character (;). You can hide a field by omitting its name from the list.
Example:	dbpSetColumnOrder "AddrBook" "Contacts" "LastName;FirstName;Company;City;Street;State;Zip;Country;Telephone;EMail; WebSite;Comments"
SQL Equivalent:	N/A

Purpose:	Set the width of each column/field in the grid. If you have enabled the AllowColumnResize option in dbpSetGridProperties, you can combine this action with dbpGetColumnWidths to save and restore changes users make to grid columns.
Category:	Grids
Syntax:	dbpSetColumnWidths "database id" "table" "field list" database id The name assigned to the database. table The name of the table. field list A list containing the original field name, an equal sign and the width (in pixels) to be assigned to each column. Separated multiple items with a semicolon character (;). This is the same format returned by dbpGetColumnWidths. For example, the column with for a table containing six fields (FIRSTNAME, LASTNAME, STREET, CITY, STATE, ZIP) might look like this: "FIRSTNAME=50;LASTNAME=50;STREET=120;CITY=25;STATE=30;ZIP=35" It is not necessary to include every field in the list. You can shorten the action by including only the field's that you want to change. Field's not in the list will retain their existing column widths. For example: "FIRSTNAME=50;LASTNAME=50;STATE=30"
Example:	dbpSetColumnWidths "AddrBook" "Contacts" "FirstName=90;LastName=90;Company=90;Street=150;City=90;State=90;Zip=90; Country=90;Telephone=90;EMail=90;WebSite=90;Comments=350"
SQL Equivalent:	N/A

Purpose:	Get the width of each column/field in the grid.
Category:	Grids
Syntax:	dbpGetColumnWidths "database id" "table" "variable" database id The name assigned to the database. table The name of the table. variable The name of the variable where the column widths will be stored. The variable format will be identical to that used by the dbpSetColumnWidths action.
Example:	dbpGetColumnWidths "AddrBook" "Contacts" "[ColWidths]"
SQL Equivalent:	N/A

Purpose:	Set the height of all rows in the grid. Use dbpGetRowHeight to obtain the default row height.
Category:	Grids
Syntax:	dbpSetRowHeight "database id" "table" "height" database id The name assigned to the database. table The name of the table. height The height (in pixels) for all rows in the grid.
Example:	dbpSetRowHeight "AddrBook" "Contacts" "26"
SQL Equivalent:	N/A

Purpose:	Obtain the height of a single grid row. All rows in the grid are the same height, so only one number is returned. If you have enabled the AllowRowResize option in dbpSetGridProperties, this action can be combined with dbpSetRowHeight to save and restore changes to the row height made by users during the execution of your publication.
Category:	Grids
Syntax:	dbpGetRowHeight "database id" "table" "variable" database id The name assigned to the database. table The name of the table. variable The name of the variable where the row height will be stored.
Example:	dbpGetRowHeight "AddrBook" "Contacts" "[RowHeight]"
SQL Equivalent:	N/A

Purpose:	Obtain the width and height of the grid's client/display area. This information can be useful for calculating column widths and row heights. The client area includes the display portion of the grid excluding the indicator column and the scroll bars. Note: Settings applied to the grid with dbpSetGridProperties will be considered when calculating the client width and height.
Category:	Grids
Syntax:	dbpGetGridClientInfo "database id" "table" "width variable" "height variable database id The name assigned to the database. table The name of the table. width variable The name of the variable where the grid's client width will be stored. height variable The name of the variable where the grid's client height will be stored.
Example:	dbpGetGridClientInfo "AddrBook" "Contacts" "[cw]" "[ch]"
SQL Equivalent:	N/A

Purpose:	Identify a field from one table to be used as an input source for a field in another table. When editing in grid mode, a field that has been assigned a value list will function like a combo box allowing the user to select list items from a drop down window. This is similar to the dbpSetGridProperties' PickList option except that the contents of the list are derived from the contents of another table.
Category:	Grids
Syntax:	dbpDefineValueList "database id" "main table" "edit field" "list table" "data field" "display field" database id The name assigned to the database. main table The name of the main table containing the field to be edited. edit field The name of the field in the main table to receive input from the value list. list table The name of the table containing the field to be used as the source of the value list. data field The field in the source table containing the actual data that will be input into the edit field. display field The field or fields in the source table to be displayed in the value list combo box. This can be the same as the data field or a different field. Separate multiple display fields with semicolons (;).
Example:	The following example defines the contents of the States table as a value list for the State field of the Contacts table: dbpDefineValueList "AddrBook" "Contacts" "State" "States" "Abbr" "Name" When editing the Contacts table in grid mode, clicking on the State field will automatically display a list of states drawn from the contents of the States table:
SQL Equivalent:	N/A

Purpose:

Display a popup window containing a list of lookup items derived from a field in a table. This action is similar to dbpDefineValueList above, except that it does not require a grid. The popup value list can be used anywhere allowing the user to select list items from a drop down window. The selected item is stored in a variable.

Category:

Grids

Syntax:

dbpPopupValueList "database id" "list table" "data field" "display field" "properties" "variable"

database id

The name assigned to the database.

list table

The name of the table containing the field to be used as the source of the value list.

data field

The field in the source table containing the actual data that will be stored in the variable.

display field

The field or fields in the source table to be displayed in the popup window. This can be the same as the data field or a different field. Separate multiple display fields with semicolons (;).

properties

This is a compound parameter and can contain any combination of the following items:

Left=number	The coordinates of the popup window’s left corner (in pixels) relative to the publication window.
Top=number	The coordinates of the popup window’s top corner (in pixels) relative to the publication window.
Width=number	The width (in pixels) of the popup window.
RowCount=number	The number of lines to display in the list.

Separate multiple items in a compound variable with semicolons (;).

Example:

The following example displays a list of state names (display field) from the States table:

dbpPopupValueList "AddrBook" "States" "Abbr" "Name" "Left=216;Top=160;Width=96;RowCount=15" "[AddrBook.Contacts.State]"

The returned value will be the corresponding value from the Abbr field (data field). For example, if the user selects "California" from the popup list, the value stored in the variable will be "CA".

SQL Equivalent:

N/A