Table cell properties

cell_properties = record_id

Assign a record structure to an table for the purpose of storing properties for each column in the table.

Most values in the cell properties record are for use with editable tables only. However, the cell_width, heading_type and heading_event fields can also be used with a non-editable table.

The record_id is the identifier of a !record structure with the following form:

!record record_id {

     cell_type,,i4[numcols]

     list_field,,p[numcols]

     drop_size,,i4[numcols]

     list_size,,i4[numcols]

     cell_style,,i4[numcols]

     cell_mode,,i4[numcols]

     cell_caption,,a###[numcols]

     cell_caption_pen,,i2[numcols]

     cell_width,,i2[numcols]

     heading_type,,u1[numcols]

     heading_event,,p[numcols]

     heading_image,,a###[numcols]

     heading_tooltip,,a###[numcols]

}

numcols is the number of columns in the table.

It is only necessary to define the fields that the program uses. However, the names and types of the fields that are included must be exactly as specified.

The properties that can be set are as follows:

cell_type	Edit type for cells in the column. When a table is created, all the columns have the default type, TCT_READONLY, which means that cells in that column cannot be edited by the user. The cell_type property is used to set a column to an editable type. The available edit types allow a cell to be edited using a textbox, checkbox button, list button type listbox or list edit type listbox. See Listbox type. Column numbering starts at 1, the far left column. The possible values for cell_type, which are defined in <sculptor.h>, are: TCT_READONLY Cells in the column are read-only. This is the default. TCT_TEXTBOX Edit using a textbox. The table_check_input() function can be used to test whether there is unsaved input in a textbox type table cell. TCT_LISTEDIT Edit using a LIST_EDIT type listbox. TCT_LISTBUTTON Edit using a LIST_BUTTON type listbox. TCT_CHECKBOX Cells in the column are to contain a checkbox. When a box is checked, the cell that contains it is assigned the value 1; when it is unchecked, the value 0. When displaying a table, Sculptor checks any box whose cell contains a value greater than 0. When the user checks or unchecks a cell, the EV_VALIDATE event is sent, with the new value as the fifth argument. See Table events and functions. To create a read-only checkbox column, assign the cell_mode EM_READONLY. TCT_DYNAMIC The type will be set dynamically whenever the cell receives focus. This generates the EV_FOCUS_CELL event. The table event function must set the edit type required. If it leaves the edit type as TCT_DYNAMIC, the cell remains uneditable, but another opportunity will be given to assign an editable type the next time it receives focus. See Table events and functions.
list_field	Array field containing the list of permitted values. This property is only relevant if the cell_type is TCT_LISTBUTTON or TCT_LISTEDIT. Note that list_field is a pointer type field, so the syntax used to assign the array field is: list_field[column] = &fieldname
drop_size	Number of visible rows for the listbox. The default is 5. This property is only relevant if the cell_type is TCT_LISTBUTTON or TCT_LISTEDIT.
list_size	Maximum size for the list. This property can be useful if the list_field is an array but not all elements are to be listed. This property is only relevant if the cell_type is TCT_LISTBUTTON or TCT_LISTEDIT.
cell_style	Style flags. The flags available correspond to the edit type for the column. See Textbox style, Listbox style.
cell_mode	Edit mode flags. The flags available correspond to the edit type for the column. See Textbox edit mode, Listbox edit mode. Note that EM_READONLY can be used in a TCT_CHECKBOX column to specify read-only checkboxes in an editable table.
cell_caption	Help caption for cells in the column.
cell_caption_pen	Pen for the display of the help caption.
cell_width	The required cell width. If this is zero, then the default width, based on the heading and linked field, is used. A non-zero value defines the required width in pixels. Negative values are reserved for future use. The cell_width property can be used with non-editable tables. If the width of the cell is less than the width of the linked field, the text scrolls horizontally. The table must be created after a cell_width is assigned. Since Sculptor version 6.0.5 has been enhanced to accept a new value TGD_NOCOLUMN (-2) that means the column will not be shown.
heading_type	The column heading type. Set to 0 for a standard, text heading, or to one of the values below to use a button as the column heading. If a text heading is used, the text is set by the table display_object and the colours by setting the label background and foreground colours. THCT_BUTTON Standard push button using the default colours. Column heading text is defined l by the table display_object. THCT_IMAGEBUTTON An image only button. The image is assigned by the heading_image field. THCT_TEXTIMAGEBUTTON An image button with text. The column heading text appears to the left of the image. The image is assigned by the heading_image field. Column heading text is defined by the table display_object. THCT_COLOURBUTTON A coloured button with text. The colours are assigned by the table colour property record. The button type can be combined with TBHT_FLAG_FLATBORDER to specify a button with a flat border, for example: heading_type[2] = THCT_BUTTON | TBHT_FLAG_FLATBORDER If a button is used as the column heading type, a heading control function can be specified in the heading_event (see below). The heading_type property can be used with non-editable tables.
heading_event	The event function for the heading control. This is only relevant if the heading_type is one of the button values. Currently the only event that is generated is EV_BUTTON_CLICKED. The heading_event property can be used with non-editable tables. Note that the heading_event is a pointer type field, so the syntax used to assign the event function is: heading_event[column] = &func_id
heading_image	The pathname of a graphic image to be used as the column heading. This is for use with columns whose heading_type is THCT_IMAGEBUTTON or THCT_COLOURIMAGEBUTTON. The path may contain environment variables. The heading height is scaled to accommodate the image size.
heading_tooltip	A tooltip to be displayed when the mouse is moved over the column heading.

To set the properties of a cell at run time, assign the required values to the appropriate field elements before the cell gains focus.

NOTES

• This property was introduced in Sculptor 5.3. In earlier releases of Sculptor (V 5.0 onwards) the cell_type, list_field and drop_size properties could be assigned by means of the table_set_type() function. This function is still supported but should be treated as obsolescent. The cell_properties clause is now the recommended method for assigning values to editable cells.

• Prior to Sculptor 5.8.9, THCT_BUTTON was the only button type available and it was then known as TCT_BUTTON.

• The function table_set_default_data() can be used to set a default value for all the cells in a column, to be displayed whenever the cell is edited.

• If the edit mode flag EM_READONLY is set, cells in the table cannot be edited. This flag also prevents the user from selecting or deselecting lines in the table.

---

EXAMPLE

!record CellProps {
     cell_type,,i4[4]
     list_field,,p[4]
     drop_size,,i4[4]
     list_size,,i4[4]
     cell_style,,i4[4]
     cell_mode,,i4[4]
     cell_caption,,a100[4]
     cell_caption_pen,,i2[4]
     cell_width,,i2[4]
     heading_type,,u1[4]
     heading_event,,p[4]
     heading_image,,a255[4]
     heading_tooltip,,a255[4]
}

!temp NameArray,,a20[20]
!temp TotNames,,i2

+window winmain at 1,1 {
     +table AddTable at 8,3 {
          cell_properties = CellProps
          other table clauses
     }
}

!function SetCellProps() {
     CellProps.cell_type[1] = TCT_LISTBUTTON
     CellProps.list_field[1] = &NameArray     /* list_field is a pointer type */
     CellProps.drop_size[1] = 10
     CellProps.list_size[1] = TotNames
     CellProps.cell_caption[1] = "Select a name"
     heading_type[1] = THCT_BUTTON
     heading_event[1] = &EvAddTableHeading    /* heading_event is also a pointer  */
     other columns
}

---

RELATED TOPICS

Tables

Table colour record

Editing table values at run time