EditTables - The COLUMNS Sub-Object (Part 1)

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

When used without an index the COLUMNS object supports the following properties:

This property simply returns the number of columns in an EditTable:

ColCount = Get_Property( CtrlEntID : ".COLUMNS", "COUNT" )

When used without an index the COLUMNS object supports the following  methods:

This method appends a new column to the EditTable control:

   InsertPos = Exec_Method( CtrlEntID : "COLUMNS", "APPEND", ColStruct )

The method returns the 1-based position index of the new column, or 0 if not successful.

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

CELLSTYLE method

This method deletes the specified column from the EditTable control:

   ColStruct = Exec_Method( CtrlEntID : "COLUMNS", "DELETE", DeletePos )

The method returns a column structure representing the EditTable column that has been deleted, or null if unsuccessful.

This method inserts a new column into the EditTable control at the specified position:

   InsertPos = Exec_Method( CtrlEntID : "COLUMNS", "INSERT", InsertPos, |
                            ColStruct )

The method returns the 1-based position index of the newly inserted column, or 0 if unsuccessful. MOVE method

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)

Equates for this structure can be found the PS_EDITTABLE_EQUATES insert record, all with the prefix "PS_EDT_INSPOS_".

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

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)