Grid Level Properties

Content Freeze

As of July 25th, 2023, there is a content freeze on this page.

These properties are used to describe a grid (or "subfile") item on a rich display. Grids are described within the "items" array of the format they appear in.

Identification

"id": Sets the ID of the grid.

"record format name": Identifies the record format that is used to access this grid from server code.

"description": Describes the record format.

"field type": Determines the type of control that is used to render the element.

Possible choices: "grid"

"value": Sets the initialization value for the current element.

Subfile Settings

"display subfile": This property tells the system when to display grid records. It represents the SFLDSP keyword.

Possible choices: "true", "false"

"display control record": This property tells the system when to display the subfile control record. It represents the SFLDSPCTL keyword.

Possible choices: "true", "false"

"initialize subfile": This property tells the system to initialize all records within the subfile. It represents the SFLINZ keyword.

Possible choices: "true", "false"

"subfile records not active": This property can be used together with the "initialize subfile" property to initialize a subfile with no active records. It represents the SFLRNA keyword.

Possible choices: "true", "false"

"delete subfile': This property tells the system when to delete the subfile area. It represents the SFLDLT keyword.

Possible choices: "true", "false"

"clear subfile": This property tells the system when to clear all records from the subfile. It represents the SFLCLR keyword.

Possible choices: "true", "false"

"subfile size": This property represents the SFLSIZ keyword, which specifies the number of records that can be placed into the subfile. However, if you program places a record with a relative record number larger than the SFLSIZ value into the subfile, the subfile is automatically extended to contain it (up to a maximum of 9999 records). If this property is not specified, the subfile page value plus one is used. The subfile page value is determined from the "number of rows" property minus the header row if it is present.

"subfile record number": This property identifies the scrollbar position when the subfile is first displayed. It represents the SFLRCDNBR keyword.

"position at top": When this property is set to true, the subfile record identified by the "subfile record number" property will display in the top row of the grid.

Possible choices: "true", "false"

"place cursor": When this property is set to true, the cursor is placed in the subfile record identified by the contents of the "subfile record number" property. The cursor is positioned at the first input-capable field in the subfile record.

Possible choices: "true", "false"

"subfile end": This property is used to indicate that a subfile with a paging bar has loaded all of its records. It represents the SFLEND keyword.

Possible choices: "true", "false"

"subfile next changed": This property is used to forces the user to correct program-detected typing errors in subfile records. The program can cause a record to be changed so that a get-next-changed operation must read the record again.

Possible choices: "true", "false"

"cursor record number": This property can be bound to a numeric field, which will return the relative record number of the record on which the cursor is located.

"cursor progression": This property determines the tab order for input elements within the subfile. It represents the SFLCSRPRG keyword.

Possible choices: "left to right", "top to bottom"

"subfile return rrn": This property can be bound to a numeric field, which will return the relative record number of the top visible record within a grid. It represents the SFLSCROLL keyword.

"subfile changed": Specifies a response indicator that is set on if the input data within the subfile is modified.

Message Subfile Settings

"subfile message key": This property specifies a field that is used to select messages from a program message queue for display. Your program places a message reference key in this field. The property represents the SFLMSGKEY keyword on a subfile record format.

"subfile program message queue": This property specifies a field that contains the name of the program message queue used to build a message subfile. It represents the SFLPGMQ keyword on a subfile record format.

"subfile control program message queue": This property specifies a field that contains the name of the program message queue used to build a message subfile when used in conjunction with the subfile initialize property. It represents the SFLPGMQ keyword on a subfile control record format.

Font and Text

"font family": The font face for the text inside the grid. To define a different font for each grid column, select Other... and specify a comma separated list of fonts.

Possible choices: "Arial", "Consolas", "Courier New", "Fantasy", "Georgia", "Monospace", "Tahoma", "Times New Roman", "Sans-Serif", "Serif", "Trebuchet MS", "Verdana", "Other..."

"font size": The size of the text inside the grid. To specify a different font size for each grid column, select Other... and specify a comma separated list of font sizes.

Possible choices: "8px", "9px", "10px", "11px", "12px", "13px", "14px", "15px", "16px", "17px", "18px", "19px", "20px", "21px", "22px", "23px", "24px", "25px", "26px", "27px", "28px", "29px", "30px", "Other..."

"font style": The style of the font in the grid. To specify a different font style for each grid column, select Other... and specify a comma separated list of font styles.

Possible choices: "normal", "italic", "oblique", "Other..."

"font variant": Normal or small caps. Small caps shows the text with all caps but same height as a lower case letter.

Possible choices: "normal", "small-caps", "Other..."

"font weight": Specifies the weight of the font inside the grid. To specify a different font weight for each grid column, select Other... and specify a comma separated list of font weights.

Possible choices: "normal", "bolder", "bold", "lighter", "100", "200", "300", "400", "500", "600", "700", "800", "900", "Other..."

"letter spacing": Spacing between each letter of a word. To specify a different value for each grid column, select Other... and specify a comma separated list of values.

Possible choices: "normal", "-3px", "-2px", "-1px", "0px", "1px", "2px", "3px", "4px", "5px", "6px", "7px", "8px", "9px", "10px", "11px", "12px", "13px", "14px", "15px", "16px", "17px", "18px", "19px", "20px", "Other..."

"text align": Alignment of text inside cells of the grid element. To specify a different alignment option for each grid column, select Other... and specify a comma separated list of values.

Possible choices: "left", "right", "center", "justify", "Other..."

"text decoration": Decoration of the text inside the grid. To specify a different value for each grid column, select Other... and specify a comma separated list of values.

Possible choices: "none", "underline", "overline", "line-through", "Other..."

"text transform": Transforms the default formatting of the text inside the grid. To specify a different value for each grid column, select Other... and specify a comma separated list of values.

Possible choices: "capitalize", "uppercase", "lowercase", "none", "Other..."

"word spacing": Spacing between each word in the cells of the grid. To specify a different value for each grid column, select Other... and specify a comma separated list of values.

Possible choices: "normal", "-3px", "-2px", "-1px", "0px", "1px", "2px", "3px", "4px", "5px", "6px", "7px", "8px", "9px", "10px", "11px", "12px", "13px", "14px", "15px", "16px", "17px", "18px", "19px", "20px", "21px", "22px", "23px", "24px", "25px", "Other..."

Header

"has header": Determines whether the grid has a header row.

Possible choices: "true", "false"

"header height": Specifies the height of the header row. This can also be specified by dragging the grid's top border with the mouse.

"header font family": The font face for the text inside the grid header row. To define a different font for each grid column, select Other... and specify a comma separated list of fonts.

Possible choices: "Arial", "Consolas", "Courier New", "Fantasy", "Georgia", "Monospace", "Tahoma", "Times New Roman", "Sans-Serif", "Serif", "Trebuchet MS", "Verdana", "Other..."

"header font size": The size of the text inside the grid header row. To specify a different font size for each grid column, select Other... and specify a comma separated list of font sizes.

Possible choices: "8px", "9px", "10px", "11px", "12px", "13px", "14px", "15px", "16px", "17px", "18px", "19px", "20px", "21px", "22px", "23px", "24px", "25px", "26px", "27px", "28px", "29px", "30px", "Other..."

"header font style": Specifies the style of the font inside the grid header row. To specify a different font style for each grid column, select Other... and specify a comma separated list of font styles.

Possible choices: "normal", "italic", "oblique", "Other..."

"header font weight": Specifies the weight of the font inside the grid header row. To specify a different font weight for each grid column, select Other... and specify a comma separated list of font weights.

Possible choices: "normal", "bolder", "bold", "lighter", "100", "200", "300", "400", "500", "600", "700", "800", "900", "Other..."

"header text align": Alignment of text inside the cells of the grid header row. To specify a different alignment option for each cell, select Other... and specify a comma separated list of values.

Possible choices: "left", "right", "center", "justify", "Other..."

"header font color": Defines the color of the text inside the header row. To define a different color for each grid cell in the header row, specify a comma separated list of color values.

"header background": Defines the background color of the header row. To define a different color for each grid cell in the header row, specify a comma separated list of color values.

"header image": Defines a repeating background image for the header row.

"column headings": Specifies a comma separated list of heading text for each column of the grid.

Colors

"odd row font color": Defines the color of text inside the odd rows of the grid. To define a different color for each grid column, specify a comma separated list of color values.

"odd row background": Defines the background color of the odd rows in the grid. To define a different color for each grid column, specify a comma separated list of color values.

"even row font color": Defines the color of text inside the even rows of the grid. To define a different color for each grid column, specify a comma separated list of color values.

"even row background": Defines the background color of the even rows in the grid. To define a different color for each grid column, specify a comma separated list of color values.

"row font color": Defines the color of text in an individual row. You can define a dynamic color for each record by binding this property to a field.

"row background": Defines the background color of an individual row. You can define a dynamic background color for each record by binding this property to a field.

"hover font color": Defines the color of text when the user hovers the mouse cursor over a grid row. To define a different color for each grid column, specify a comma separated list of color values.

"hover background": Defines the background color of a grid row when the user hovers the mouse cursor over it. To define a different color for each grid column, specify a comma separated list of color values.

"selection font color": Defines the color of text when the user selects a grid row.

"selection background": Defines the background color of a grid row when the user selects it.

Grid Settings

"number of rows": Specifies the number of rows in the grid, including the header row.

"number of columns": Specifies the number of columns in the grid.

"row height": Specifies the height that will be applied to each row, not including the header row. This can also be controlled by resizing the grid with the mouse.

"hover effect": Determines whether the grid rows will be highlighted when the user hovers the mouse over them.

Possible choices: "true", "false"

"hover image": Defines a repeating cell background image for the hover effect.

"row selection": Determines if rows within the grid can be selected by the user with a click of the mouse. Possible values are: none - rows cannot be selected single - only one row can be selected multiple (simple) - multiple rows can be selected by simply clicking on the rows multiple (extended) - multiple rows can be selected with the use of the Shift and Ctrl keys

Possible choices: "none", "single", "multiple (simple)", "multiple (extended)"

"selection field": This property must be bound to an indicator or a character field, which will be used to both set and return the selected state on each record. If a character field is specified, the selection value property will be used to populate the field when a row is selected.

"selection value": Specifies the value used to populate the selection field when a grid row is selected.

"selection image": Defines a repeating cell background image for row selection.

"column widths": Specifies a comma separated list of column widths for this grid.

"scrollbar": Determines the type of vertical scrollbar used to scroll through records within the grid. A sliding scrollbar scrolls freely, while a paging scrollbar scrolls one page of records at a time only.

Possible choices: "none", "sliding", "paging"

"scroll tool tip": Determines if the row number or the row number range should be displayed in a tool tip when the user scrolls through the data in the grid.

Possible choices: "none", "row number", "row range"

"propagate scroll events": When this property is false (which is the default) the grid handles any scroll wheel or swipe events sent to it so that they scroll the grid, but not the window that the grid is placed inside. If you enable this property, these events will be propagated, which allows mouse wheel and swipe events to scroll the grid's parent window.

Possible choices: "true", "false"

"sortable columns": Enables column sorting. If set to true, the user will be able to click on the column headings to resort the data.

Possible choices: "true", "false"

"default sort order": Specifies the default order for sortable columns. When the user clicks a column, the default sort order is used initially. To provide a different sort order for each grid column, select Other... and specify a comma separated list. Entries in the list can be abbreviated using the letter A for Ascending and D for Descending.

Possible choices: "Ascending", "Descending", "Other..."

"initial sort column": This property specifies the column used to for inital sorting. Each grid column is identified by a sequential index, starting with 0 for the first column, 1 for the second column, and so on. If the property is omitted or set to blanks, sorting is not initiated when the grid is first rendered.

"initial sort field": This property specifies the field name used to identify the column for initial sorting. If this property and the "initial sort column" property are omitted or set to blanks, sorting is not initiated when the grid is first rendered.

"column sort response": Specifies a response variable for server-side sorting. If omitted, client-side sorting is used. The response is a numeric value that represents a column in the grid. Each grid column is identified by a sequential index, starting with 0 for the first column, 1 for the second column, and so on. It is the responsibility of the program to keep track of the sort direction, and to display an up or down arrow in the appropriate column using the "initial sort column" and "default sort order" properties.

"Field Name Sort Response": Specifies a response variable to receive a field name used for server-side sorting. If omitted, client-side sorting is used. The response represents the name of the field bound to the first widget in a column of the grid. It is the responsibility of the program to keep track of the sort direction, and to display an up or down arrow in the appropriate column using the "initial sort field" and "default sort order" properties.

"resizable columns": Allows the user to resize grid columns at run time.

Possible choices: "true", "false"

"movable columns": Allows the user to rearrange grid columns at run time.

Possible choices: "true", "false"

"persist state": Specifies whether the grid state should be saved when the user sorts, moves, or resizes columns. When set to true, the state is saved to browser local storage with each user action, and automatically restored the next time the grid is displayed.

Possible choices: "true", "false"

"find option": Presents an option to search grid data when the grid heading is right-clicked.

Possible choices: "true", "false"

"filter option": Presents an option to filter grid data when the grid heading is right-clicked.

Possible choices: "true", "false"

"reset option": Presents an option to reset the persistent state for this grid when the grid heading is right-clicked.

Possible choices: "true", "false"

"export option": Presents an option to export grid data to Excel using the CSV format when the grid heading is right-clicked.

Possible choices: "true", "false"

"context menu id": Specifies the id of a Menu widget used to display a context menu when the user right-clicks a grid row.

Paging Bar

"show paging controls": Displays links for navigating to the previous page and the next page of records.

Possible choices: "true", "false"

"show page number": This property determines whether the page number should display within the paging bar.

Possible choices: "true", "false"

"initial page number": Specifies the initial page number to use when the page number is displayed within the paging bar. If not specified, page number 1 is used.

"show bar": Displays a bar at the bottom of the grid even if no paging bar elements are selected to be displayed. This can be used to show miscellaneous information such as column totals.

Possible choices: "true", "false"

"page down condition": Determines if the next page link is enabled.

"page down response": Specifies a response indicator that is returned to your program when the next page link is clicked.

"page up condition": Determines if the previous page link is enabled.

"page up response": Specifies a response indicator that is returned to your program when the previous page link is clicked.

"csv export": Displays a link allowing the user to export grid data to Excel using the CSV format.

Possible choices: "true", "false"

"xlsx export": Displays a link allowing the user to export grid data to Excel using the XLSX format.

Possible choices: "true","false"

"export file name": Defines the name of the download file used to export grid data to CSV or XLSX formats. The .xlsx or .csv extension is automatically appended to the name. If omitted, the record format name is used.

"export with headings": Specifies whether subfile headings should be exported as the first row of the CSV file.

Possible choices: "true", "false"

Row Folding

"fold multiple": The property determines the height of a collapsed row, which is calculated at by taking the row height property and dividing it by the fold multiple. The multiple represents the number of collapsed rows that can fit into one expanded row.

Possible choices: "2", "3", "4", "Other..."

"expanded": Determines if the rows are first displayed in expanded (also known as folded) mode.

Possible choices: "true", "false"

"collapsed": Determines if the rows are first displayed in collapsed (also known as truncated) mode.

Possible choices: "true", "false"

"return mode": This property can be bound to a field that will provide an indication of whether the grid rows were in expanded (also known as folded) mode or in collapsed (also known as truncated) mode on input.

"single row zoom": Determines if a zoom icon is shown on collapsed rows. Once the user clicks the icon, the row is expanded. All other rows remain collapsed.

Possible choices: "true", "false"

Grid Data

"database file": Database file to use for a grid that is tied directly to a database. You can specify a 'database file' or 'library/database file'. If library is omitted, the session's library list is used.

"database fields": A set of database field names to use to retrieve the data for a database-driven grid. The field names should be comma separated.

"selection criteria": Optional expression identifying which records should be retrieved from the database file.

"order by": Optional expression identifying which fields determine the order of the records retrieved from the database file.

"custom sql": Specifies an sql statement to use to retrieve the records for a database-driven grid.

"allow any select statement": Allows any valid SELECT SQL statement. If this is false (default), a row count is retrieved by running SELECT COUNT( *) FROM (your-custom-sql-property), so your "custom sql" property must work with that syntax. This prevents the use of common table expressions, the optimize clause, and a few other things. If set to true, the row count will be determined by running your statement as-is and looping through all rows to count them. Note: False performs better, but true allows a wider variety of SQL statements.

"parameter value": Value for parameter marker in "selection criteria" or "custom sql" property. Parameter markers are specified using a question mark. Profound UI will accept values from the client for any parameter marker values which are not bound to program fields. Parameter markers are numbered in order of occurence, from left to right. To specify multiple parameter marker values, right-click the property and select Add Another Parameter Value.

"data url": Sets the url to a Web service that returns JSON data for a database-driven grid.

"data transform function": The name of a JavaScript to be called to process the results of the "data url" program. This can be used to transform data from the program into the format expected by the grid widget.

Position

"left": Represents the x-coordinate of the current element.

"top": Represents the y-coordinate of the current element.

"height": Height of the grid.

"width": Width of the grid.

"expand to layout": If set to true, the grid will automatically expand to the full size of a layout container.

Possible choices: "true", "false"

"z index": The stacking order of the current element, expressed as an integer value. The element with the higher z index will overlay lesser elements.

"locked in place": If set to true, the grid cannot be moved or sized in the Visual Designer.

Possible choices: "true", "false"

Drag and Drop

"allow drag": This property determines if rows within the grid can be drag and dropped.

Possible choices: "true", "false"

"ondragstart": Initiates a client-side script when the user first starts to drag a row within the grid. Information about the drag and drop operation is provided using the global pui.dragDropInfo object.

"drop targets": Specifies a list of target element id's, which indentify where the row can be dropped.

"ondragenter": Initiates a client-side script when the user drags a row over a valid drop target. Information about the drag and drop operation is provided using the global pui.dragDropInfo object.

"ondragleave": Initiates a client-side script when the user moves a row out of a valid drop target during a drag operation. Information about the drag and drop operation is provided using the global pui.dragDropInfo object.

"ondrop": Initiates a client-side script when the mouse is released during a drag and drop operation. Information about the drag and drop operation is provided using the global pui.dragDropInfo object.

Tabs

"parent tab panel": This property specifies the id of the Tab Panel to which this element belongs. The property is set automatically when you drag and drop the element onto a Tab Panel.

"parent tab": This property specifies the tab index of the specific tab to which this element belongs. Each tab within a Tab Panel is identified by a sequential index, starting with 0 for the first tab, 1 for the second tab, and so on. The property is set automatically when you drag and drop the element onto a Tab Panel.

"parent field set": This property specifies the if of the Field Set Panel to which this element belongs. The property is set automatically when you drag and drop the element onto a Field Set Panel.

Borders

"border color": The color of the grid's outer borders and inner separators.

"border width": The thickness of the grid's outer borders and inner separators.

Possible choices: "0px", "1px", "2px", "3px", "4px", "5px", "Other..."

Padding

"padding bottom": Sets the distance between the bottom edge of a grid cell and the cell's content.

Possible choices: "0px", "1px", "2px", "3px", "4px", "5px", "6px", "7px", "8px", "9px", "Other..."

"padding left": Sets the distance between the left edge of a grid cell and the cell's content.

Possible choices: "0px", "1px", "2px", "3px", "4px", "5px", "6px", "7px", "8px", "9px", "Other..."

"padding right": Sets the distance between the right edge of a grid cell and the cell's content.

Possible choices: "0px", "1px", "2px", "3px", "4px", "5px", "6px", "7px", "8px", "9px", "Other..."

"padding top": Sets the distance between the top edge of a grid cell and the cell's content.

Possible choices: "0px", "1px", "2px", "3px", "4px", "5px", "6px", "7px", "8px", "9px", "Other..."

Misc

"css class": Defines a custom cascading style sheet class to assign to the element. To specify multiple classes, right-click the property and select Add Another CSS Class.

"tool tip": Defines the text to appear in a tool tip when the user hovers the mouse over this element.

"user defined data": Specifies user-defined general purpose data associated with the widget. To provide multiple user defined data values, right-click the property and select Add Another User Defined Value.

"visibility": Determines whether the element is visible or hidden.

Possible choices: "hidden", "visible"

Events

"ondbload": Initiates a client-side script when database data is loaded for a database-driven widget. An object named response will be defined that contains:

success: boolean true/false
id: the widget id
error: an object with "id", "text" and "text2" fields containing the error.

"onfilterchange": Initiates a client-side script when the filter has changed.

"onrowclick": Initiates a client-side script when a row within the grid is clicked. The script can determine the row number using the row variable.

"onrowdblclick": Initiates a client-side script when a row within the grid is double-clicked. The script can determine the row number using the row variable.

"onrowmouseover": Initiates a client-side script when the mouse is moved over a row within the grid. The script can determine the row number using the row variable.

"onrowmouseout": Initiates a client-side script when the mouse is moved off of a row within the grid. The script can determine the row number using the row variable.

"onpagedown": Initiates a client-side script when the user pages down using the grid's scrollbar. To prevent the grid's default paging action, the script must evaluate to false.

"onpageup": Initiates a client-side script when the user pages up using the grid's scrollbar. To prevent the grid's default paging action, the script must evaluate to false.

"onscroll": Initiates a client-side script when the user scrolls using the grid's scrollbar. The row variable in the script provides the top row of the grid.