EditTables - The COLUMNS Sub-Object (Part 1)
Published 10 JAN 2020 at 05:59:41PM
Further to the last post on EditTable sub-objects, the next set of articles will provide an overview of the COLUMNS sub-object, which gives run-time access to the properties and methods of EditTable columns. The COLUMNS sub-object can be used in two ways: Indexed and non-indexed.
- When using the COLUMNS sub-object with an index you are referring to a specific column in the control
- When using the COLUMNS sub-object in a non-indexed fashion you are referring to the collection of columns in the control as a whole.
E.g:
// Using COLUMNS with an index to get the VISIBLE property of // column 2 ColVis = Get_Property( ctrlEntID : ".COLUMNS", "VISIBLE", 2 ) ColVis = @CtrlEntID.Columns{2}->Visible // Using COLUMNS without an index to get the number of columns // in the control ColCount = Get_Property( ctrlEntID : ".COLUMNS", "COUNT" ) ColCount = @CtrlEntID.Columns->Count
In this post we'll start by taking a look at the "non-indexed" COLUMNS interface has the following API: The non-indexed COLUMNS properties are:
- COUNT
The non-indexed COLUMNS methods are:
- APPEND
- CELLGLYPH
- CELLIMAGE
- CELLSTYLE
- DELETE
- INSERT
- MOVE
Non-Indexed COLUMNS object properties
When used without an index the COLUMNS object supports the following properties:
COUNT property
This property simply returns the number of columns in an EditTable:
ColCount = Get_Property( CtrlEntID : ".COLUMNS", "COUNT" )
Non-Indexed COLUMNS object methods
When used without an index the COLUMNS object supports the following methods:
APPEND method
This method appends a new column to the EditTable control:
InsertPos = Exec_Method( CtrlEntID : "COLUMNS", "APPEND", ColStruct )
Parameter | Description |
ColStruct | A dynamic array containing the Column Structure definition (see below) |
The method returns the 1-based position index of the new column, or 0 if not successful.
CELLGLYPH method
This method displays a glyph for all data cells or the header cell in the column:
prevGlyph = Exec_Method( CtrlEntID : "COLUMNS", "CELLGLYPH", | ColNo, StateID, HeaderCell, newGlyph )
CELLIMAGE method
Parameter | Description |
DeletePos | The 1-based index of the column to delete |
CELLSTYLE method
Parameter | Description |
DeletePos | The 1-based index of the column to delete |
DELETE method
This method deletes the specified column from the EditTable control:
ColStruct = Exec_Method( CtrlEntID : "COLUMNS", "DELETE", DeletePos )
Parameter | Description |
DeletePos | The 1-based index of the column to delete |
The method returns a column structure representing the EditTable column that has been deleted, or null if unsuccessful.
INSERT method
This method inserts a new column into the EditTable control at the specified position:
InsertPos = Exec_Method( CtrlEntID : "COLUMNS", "INSERT", InsertPos, | ColStruct )
Parameter | Description |
InsertPos | The 1-based index to insert the new column at, or "-1" to append. |
ColStruct | A dynamic array containing a Column Structure as described above. |
The method returns the 1-based position index of the newly inserted column, or 0 if unsuccessful. MOVE method
Parameter | Description |
DeletePos | The 1-based index of the column to delete |
EditTable Column Structure
Some of the methods described below, such as the APPEND and INSERT methods, require one or more structures that describe the column to be added to an EditTable, so we'll describe these here before we go any further. The main structure we need is the Column Structure, which is an @fm-delimited array formatted as follows:
<1> HeaderText <2> CellProperties ("ETCLS_" style bits, or @vm'd property array) <3> CellDataLength <4> DisplayWidth <5> HeaderProperties ("ETCHS_" style bits, or @vm'd property array) <6> HeaderFont (@svm-delimited) <7> HeaderToolTip <8> CellDropDownList (@vm-delimited) <9> CellFont (@svm-delimited) <10> CellToolTip <11> CellCueBanner <12> CellEditMask (@vm-delimited) <13> CellValidChars <14> CellButton (@vm-delimited; Text, Width)
Field | Description |
<1> | HeaderText: contains the text to display in the column header. |
<2> | CellProperties: Describes the attributes of the data cells in the column. This can be a bitmask value (i.e a set of "ETCLS_" style bits), or an @vm'd array of actual property values (see "EditCell Attributes" below). |
<3> | CellDataLength: Specifies the maximum amount of data (in characters) that cells in the column can contain. This should be a integer greater than zero. This limit can be exceeded at runtime so no data is lost, but performance is better if the value here is accurate. This attribute is required. |
<4> | DisplayWidth: Specifies the display width of the column. |
<5> | HeaderProperties: Describes the attributes of the header cell for the column. This can be a bitmask value (i.e a set of "ETCHS_" style bits), or an @vm'd array of actual property values (see "EditCell Attributes" below). |
<6> | HeaderFont: Specifies the font to use for the column header cell. This is a standard @svm-delimited FONT property structure. |
<7> | HeaderTooltip: Contains the text for the column header tooltip. |
<8> | CellDropDownList: If the data cells in the column are DropDown-type cells, this field contains an @vm-delimited array of items used to populate the dropped list. |
<9> | CellFont: Specifies the font to use for data cells in the column. This is a standard @svm-delimited FONT property structure. |
<10> | CellToolTip: Contains the text for the tooltip displayed for data cells in the column. |
<11> | CellCueBanner: Contains the cue-banner text displayed for empty data cells in the column. |
<12> | CellEditMask: Contains an @vm-delimited array of edit-mask attributes to use when validating text entered into the column's data cells (See the EditLine EDITMASK property for more details on edit masks). |
<13> | CellValidChars: Contains a sequence of characters that are allowed to be entered into the column's data cells (See the EditLine VALIDCHARS property for more details on validation characters). |
<14> | CellButton: If the data cells in the column have an Options button, this field contains an @vm-delimited array defining the button text and width: <0,1> Text <0,2> Width |
Equates for this structure can be found the PS_EDITTABLE_EQUATES insert record, all with the prefix "PS_EDT_INSPOS_".
EditTable Cell Attributes - bitmask or property array?
In previous versions of OpenInsight some header and data cell attributes were defined by setting a series of "COLSTYLE" (column-style) bits together as a bitmask value in a single field when creating the column. While we still support this method of defining cell properties we also added another way which is more in line with "normal" Basic+ programming techniques - i.e. using a dynamic array (we'll call it a "property array" here) rather than a C++ style bitmasks, and you can choose which method suits you best. As noted above the Column Structure has two fields that can use a bitmask or a property array:
- CellProperties
- HeaderProperties
(The bitmask values for a data cell (CellProperties) are prefixed "ETCLS_" and defined in the PS_EDITTABLE_EQUATES insert record, while the bitmask values for the column header cell (HeaderProperties) are prefixed "ETCHS_" and are defined in the same record.) The structure for the @-vm delimited CellProperties array is as follows:
<0,1> CellType (CELLTYPE property value) <0,2> EditMode (EDITMODE property value) <0,3> TextAlign (TEXTALIGN property value) <0,4> TextCase (TEXTCASE property value) <0,5> CheckBoxAlign (TEXTALIGN property value) <0,6> OptionsButton T/F <0,7> PasswordStyle T/F <0,8> DrawHTML T/F <0,9> ShowEllipses T/F <0,10> MultiLine T/F <0,11> ScrollBars (SCROLLBARS property value) <0,12> AutoScroll T/F <0,13> WordWrap T/F <0,14> GlyphAlign (IMAGEALIGN property value) <0,15> Reserved N/a <0,16> Skipped T/F
Field | Description |
<0,1> | CellType: Specifies the type of data cells in the column: * Normal (0) * CheckBox (1) * Button (2) * DropDownList (3) * DropDownEdit (4) |
<0,2> | EditMode: Specifies the edit status of data cells in the column: * Default (-1) * Disabled (0) * Protected (1) * ReadOnly (2) * Enabled (3) |
<0,3> | TextAlign: Specifies the alignment of text in the column's data cells: * TopLeft (0) * TopCenter (1) * TopRight (2) * CenterLeft (3) * Centered (4) * CenterRight (5) * BottomLeft (6) * BottomCenter (7) * BottomRight (8) |
<0,4> | TextCase: Specifies the case of text entered into data cells: * Mixed (0) * Lower (1) * Upper (2) |
<0,5> | CheckBoxAlign: Specifies the alignment of CheckBox type data cells in the column: * CenterLeft (3 or "L") * Centered (4 or "C" * CenterRight (5 or "R") |
<0,6> | OptionsButton: If TRUE$ and the cell is a "Normal" type then an options button is displayed for data cells in the column. |
<0,7> | PasswordStyle: If TRUE$ then text entered into a data cell is displayed like a standard EditLine control with the Password property set, i.e. the letters in the text are obscured. |
<0,8> | DrawHTML: If TRUE$ then enable "HTML-like" formatting for data cells in the column. |
<0,9> | ShowEllipses: If TRUE$ then any data cell text that cannot fit within the boundaries of the cell when displayed is truncated and ellipses added (the full text string is always preserved - the truncation applies to the display only). |
<0,10> | MultiLine: If TRUE$ then a user may enter multiple lines of text when editing the contents of the column's data cells. |
<0,11> | ScrollBars: If the column data cells are marked as MultiLine this setting controls how scrollbars are displayed when the cell is being edited: * None (0) * Horizontal (1) * Vertical (2) * Both (3) |
<0,12> | AutoScroll: If the column data cells are marked as MultiLine, setting this value to TRUE$ automatically scrolls text up one page when the user presses the ENTER key on the last line when editing. |
<0,13> | WordWrap: If the column data cells are marked as MultiLine, setting this value to TRUE$ ensures that text in the cell is word-wrapped (and will not horizontally scroll when being edited). |
<0,14> | GlyphAlign: Specifies the alignment of glyphs in the column's data cells: * TopLeft (0) * TopCenter (1) * TopRight (2) * CenterLeft (3) * Centered (4) * CenterRight (5) * BottomLeft (6) * BottomCenter (7) * BottomRight (8) |
<0,15> | Reserved for future use. |
<0,16> | Skipped: If TRUE$ then data cells in the columns are "skipped" and cannot be edited. |
The structure for the @-vm delimited HeaderProperties array is as follows:
<0,1> CellType (CELLTYPE property value) <0,2> Hidden T/F <0,3> Resizable T/F <0,4> TextAlign (TEXTALIGN property value) <0,5> CheckBoxAlign (TEXTALIGN property value) <0,6> DrawHTML T/F <0,7> ShowEllipses T/F <0,8> MultiLine T/F <0,9> WordWrap T/F <0,10> GlyphAlign (IMAGEALIGN property value)
Field | Description |
<0,1> | CellType: Specifies the type of header cell for the column: * Normal (0) * CheckBox (1) * Button (2) |
<0,2> | Hidden: If TRUE$ then the column will not be displayed in the EditTable. |
<0,3> | Resizable: If TRUE$ then the user is allowed to resize the column with the mouse at runtime. |
<0,4> | TextAlign: Specifies the alignment of text in the column header cell: * TopLeft (0) * TopCenter (1) * TopRight (2) * CenterLeft (3) * Centered (4) * CenterRight (5) * BottomLeft (6) * BottomCenter (7) * BottomRight (8) |
<0,5> | CheckBoxAlign: Specifies the alignment of the CheckBox if the header cell is a CheckBox type: * CenterLeft (3 or "L") * Centered (4 or "C" * CenterRight (5 or "R") |
<0,6> | DrawHTML: If TRUE$ then enable "HTML-like" formatting for the column header cell. |
<0,7> | ShowEllipses: If TRUE$ then any header cell text that cannot fit within the boundaries of the cell when displayed is truncated and ellipses added (the full text string is always preserved - the truncation applies to the display only). |
<0,8> | MultiLine: If TRUE$ then multiple lines of text may be displayed in the column's header cell. |
<0,9> | WordWrap: If the header cell is marked as MultiLine, setting this value to TRUE$ ensures that text in the cell is word-wrapped. |
<0,10> | GlyphAlign: Specifies the alignment of glyphs in the column's header cell: * TopLeft (0) * TopCenter (1) * TopRight (2) * CenterLeft (3) * Centered (4) * CenterRight (5) * BottomLeft (6) * BottomCenter (7) * BottomRight (8) |