InsertAttrColumn Method (LISTVIEW)

d9.0, PLBCMP GUI Only

The InsertAttrColumn method adds a special column into a LISTVIEW object that specifies the foreground color, background color, and font attributes for individual column cells of a row. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A LISTVIEW object into which a special column is inserted.

return

Optional. A Numeric Variable that returns the new zero-based column number.

index

Required. A Numeric Variable or decimal number that specifies the zero-based position of the attribute column.

Flags Affected: OVER, ZERO

Note the following:

1. The data string stored into each item of the new column specifies a specially formatted set of attribute fields that define the foreground color, background color, and font of each column cell for the line item. The format of the attribute data strings must be given as follows:
   
   {default};{column1};{{column2};....;{columnx}
   
   Where:
   
   {default} - An optional field that defines the default foreground color, background color, and font indexes for this row. The {default} field is composed of three subfield indexes that reference attribute tables that have been setup for a LISTVIEW object.
   
   {column1} - An optional field that specifies the color and font attribute indexes that are used for column one of the row. This same field definition format applies for all columns that exist in the LISTVIEW object.

2. The string format for the {default} and {column} fields is defined as follows:

 

     {fgNDX},{bgNDX},{fontNDX}

 

Where:

 

{fgNDX}	This is a number between one (1) and twenty (20) that selects the foreground color from the color table that has been created for the LISTVIEW object.
{bgNDX}	This is a number between one (1) and twenty (20) that selects the background color from the color table that has been created for the LISTVIEW object.
{fontNDX)	This is a number between one (1) and twenty (20) that selects the font table that has been created for the LISTVIEW object

 

3. Some example attribute strings for the attribute column are below:

 

"1,1,1;2,3,4"

In this example, the default attribute field has specified an index value of 1 for the foreground color, the background color, and the font. This attribute also specifies that the first column of the LISTVIEW object is to use an index value of 2 for the foreground color, an index value of 3 for the background color, and an index value of 4 for the font. All subsequent columns are to use the default.

",2;1,3;;4"

In this example, the default attribute field has only specified an index value of 2 for the back ground color. In this case, the default foreground color and font are determined from the default attribute data settings that have been setup for the LISTVIEW object. For the first column of the LISTVIEW, the index value of one retrieves the foreground color while the index value of three retrieves the font used. The second column of the LISTVIEW is the default values. The third column of the LISTVIEW uses the index value of four to retrieve the foreground color. Again, all other attributes are specified by the default settings.

 

4. The general program logic flow to make use of the new LISTVIEW color/font features to control individual cell attributes is as follows:

 

1. Create a LISTVIEW object.

2. Use the InsertAttrColor, InsertAttrRGB, and InsertAttrFont methods to initialize the color and/or the font index tables for the LISTVIEW object.

3. Use the InsertAttrDefault method to set the default attribute settings for the LISTVIEW object.

4. Use the InsertAttrColumn method to put an attribute column into the LISTVIEW object.

5. Use the SetItemText method to set the attribute data strings for each row of the LISTVIEW where individual row cells are controlled. If an item in the attribute column does not have an attribute string, the default settings are used.

5. The attribute column is inserted with a width size of zero. This makes the column invisible to the users.

6. It is not recommended that the attribute column be sorted. This can cause indeterminate results due to the attribute data string format required to control each column cell for a line item.

7. Upon completion, {return} will contain the new column's zero-based value or -1 if the method fails.

8. If the value returned is zero, the ZERO Condition Flag is set.

9. If {return} is too small to contain result of the method, the OVER Condition Flag is set.

10. The {index} value cannot be zero. Otherwise, the {return} value is -1 to indicate a failure. The attribute column cannot be inserted as column zero because this creates a conflict when reporting the existence of the column using the GetAttributeColumn method.

11. For improved performance in the Application Server environment, do not specify the optional return value unless needed.

See Also: InsertAttrColor, InsertAttrDefault, InsertAttrFont, Example Code, Method Syntax, LISTVIEW Methods