Add Method (Columns Collection)

The Add method creates and returns a new Column object in the Columns collection.

Syntax

Set objColumn = objColumnsColl.Add(pszDisplayName, varProperty, lWidth, lFlags, lInsertAfter [, varType] )

objColumn

On successful return, contains the new Column object.

objColumnsColl

Required. The Columns collection object.

pszDisplayName

Required. String. The display name to be assigned to the new Column object.

varProperty

Required. Variant (Long or String). The property tag for the predefined or user-defined property, or the custom name of the user-defined property, that is to be rendered in the new Column object.

lWidth

Required. Long. The absolute width of the new Column object. An added column is always handled as if it were in a custom view, even if it is added to a persistent view, so the width is never treated as relative.

lFlags

Required. Long. The flags specifying certain display attributes of the new Column object. For a description of these flags, see the Column object’s Flags property.

lInsertAfter

Required. Long. The Index value of the column after which the new Column object is to be added to the collection. If this parameter is 0, the new column is added at the beginning of the collection. If lInsertAfter is greater than the size of the collection, the new column is added at the end.

varType

Optional (required for user-defined properties). Long. The property type of the property to be rendered in the new Column object. The varType parameter is only needed for custom properties, because the property type of a predefined property is already included in its property tag, which is passed in the varProperty parameter.

Remarks

The pszDisplayName, varProperty, lWidth, lFlags, and lInsertAfter parameters correspond to the Name, Property, Width, Flags, and Index properties of the new Column object, except that the new column’s Index is greater by 1 than the lInsertAfter parameter.

The first column in the collection has an Index value of 1, and the last has an Index equal to the size of the collection in the Count property. If the value of the lInsertAfter parameter exceeds the collection’s size, the new column is added with an Index greater by 1 than the previous size. If lInsertAfter is less than the previous size, the Index values of all columns after the new column are incremented by 1. In all cases, the collection’s Count is incremented by 1.

The varProperty parameter designates the property to be rendered in the column. The parameter can be a long integer specifying the property by property tag, or a string specifying it by custom name. In both cases it corresponds to the Property property. Predefined properties are always specified by tag, while user-defined properties can be specified by either tag or name.

If the varProperty parameter is a custom property name, it can optionally be prefixed with a GUID string identifying its property set. In this case, the GUID should be enclosed in braces. For more information and examples, see Using Named Properties.

The allowable values for the varType parameter are listed in the Field object's Type property.

If you are rendering a calendar view, the value of the lWidth parameter is ignored, although it is still required. The CalendarView object makes its own calculations for column widths based on the values of its Mode and NumberOfUnits properties.