AddItem Method (Visual FoxPro)
Adds a new item to a ComboBox or ListBox control, optionally making it possible for you to specify the item's index.
Control.AddItem(cItem [, nIndex] [, nColumn])
Parameters
cItem
Specifies the string expression to add to the control.nIndex
Specifies the position where the item is placed in the control. If you supply a valid value for the optional nIndex, cItem is placed at that position within the control. If you specify an nIndex that already exists, the item is inserted at that position and all items below that item are moved down one position in the list portion of the ComboBox or ListBox control.If you omit nIndex and the Sorted property is set to True (.T.), cItem is added in alphabetic sort order. If you omit nIndex and the Sorted property is set to False (.F.), cItem is added to the end of the list portion of the ComboBox or ListBox control.
nColumn
Specifies the column of the control to which the new item is added. The default is 1.
Remarks
Use the AddItem method or AddListItem method when the RowSourceType property is set to 0 (None).
Each item added to a ComboBox or ListBox has two identification numbers assigned to it:
nItemID, an integer corresponding to the unique ID of the item in the control: the first item corresponds to nItemID = 1 unless another nItemID is specified.
nIndex, an integer corresponding to the order in which items are displayed by the control: the first item in the control corresponds to nIndex = 1.
The AddItem method always inserts a new row into a multicolumn ComboBox or ListBox. After a row has been inserted, columns in that row should be populated using the .List(.NewIndex, nColumn) syntax.
The backslash ("\") is treated as a special character when used in the expression for an item. The following rules apply for this character:
You can disable an item in a list box or combo box by adding a single backslash to the beginning of the expression. When you disable an item using a backslash, it is disabled for mouse access only, however, a user can still access that item using the keyboard. To disable the item from mouse and keyboard access, preface the entry with both backslash and close bracket characters ("\]").
Any multiple of two backslashes used in the expression is displayed as a single backslash. For example, one or two backslashes used together will display as one, and three or four backslashes together will display as two. The following example code contains a list box item containing a Universal Naming Convention (UNC) path. The code displays in the list box as \\MyServer\MyMachine\MyFolder.
MyForm.List1.AddItem("\\\\MyServer\\MyMachine\\MyFolder")If the expression begins with multiple backslashes, the item is not disabled. If you want to disable an item that begins with multiple backslashes, add a backslash and a close bracket (]) to the beginning of the item. For example, the following disables the UNC path item in the list box.
MyForm.List1.AddItem("\]\\\MyServer\\MyMachine\\MyFolder")To include a separator line, use a backslash followed by a hyphen as the item to add to the list box. For example, the following code adds a separator line to a list box.
MyForm.List1.AddItem("\-")
Example
This example demonstrates using the AddItem and AddListItem methods to add values to the ListItem array. Both proper and improper ways of populating a combo box are shown for clarity.
PUBLIC ofrmListExamples
ofrmListExamples=NEWOBJECT("frmListExamples")
ofrmListExamples.Show
RETURN
DEFINE CLASS frmListExamples AS form
DataSession = 2
Top = 0
Left = 0
Height = 262
Width = 325
Caption = "List and ListItem Array Example"
Name = "frmListExamples"
ADD OBJECT shape1 AS shape WITH ;
Top = 43, ;
Left = 32, ;
Height = 76, ;
Width = 261, ;
SpecialEffect = 0, ;
Name = "Shape1"
ADD OBJECT cbolistbad AS combobox WITH ;
ColumnCount = 3, ;
ColumnWidths = "100,100,50", ;
Height = 22, ;
Left = 111, ;
Sorted = .T., ;
Style = 2, ;
TabIndex = 1, ;
Top = 53, ;
Width = 147, ;
Name = "cboListBad"
ADD OBJECT cbolistitem AS combobox WITH ;
ColumnCount = 3, ;
ColumnWidths = "100,100,50", ;
Left = 34, ;
Sorted = .T., ;
Style = 2, ;
TabIndex = 3, ;
Top = 154, ;
Name = "cboListItem"
ADD OBJECT label1 AS label WITH ;
FontBold = .T., ;
Caption = "Using the List Array:", ;
Height = 17, ;
Left = 34, ;
Top = 24, ;
Width = 176, ;
TabIndex = 7, ;
Name = "Label1"
ADD OBJECT label2 AS label WITH ;
FontBold = .T., ;
Caption = "Using the ListItem Array:", ;
Height = 17, ;
Left = 34, ;
Top = 135, ;
Width = 173, ;
TabIndex = 8, ;
Name = "Label2"
ADD OBJECT cbolistgood AS combobox WITH ;
ColumnCount = 3, ;
ColumnWidths = "100,100,50", ;
Height = 22, ;
Left = 111, ;
Sorted = .T., ;
style = 2, ;
TabIndex = 2, ;
Top = 86, ;
Width = 147, ;
Name = "cboListGood"
ADD OBJECT label3 AS label WITH ;
Alignment = 1, ;
Caption = "Wrong!", ;
Height = 17, ;
Left = 51, ;
Top = 56, ;
Width = 47, ;
TabIndex = 9, ;
Name = "Label3"
ADD OBJECT label4 AS label WITH ;
Alignment = 1, ;
Caption = "Right!", ;
Height = 17, ;
Left = 58, ;
Top = 89, ;
Width = 40, ;
TabIndex = 10, ;
Name = "Label4"
PROCEDURE cbolistbad.Init
WITH This
.AddItem( 'Cleveland' )
.AddItem( 'Ohio', .NewIndex, 2 )
.AddItem( '44122', .NewIndex, 3 )
.AddItem( 'Caversham' )
.AddItem( 'England', .NewIndex, 2 )
.AddItem( 'RG4 8BX', .NewIndex, 3 )
.AddItem( 'Buffalo' )
.AddItem( 'New York', .NewIndex, 2 )
.AddItem( '14228', .NewIndex, 3 )
.AddItem( 'Milwaukee' )
.AddItem( 'Wisconsin', .NewIndex, 2 )
.AddItem( '43225', .NewIndex, 3 )
.AddItem( 'International Falls')
.AddItem( 'Minnesota', .NewIndex, 2 )
.AddItem( '42666', .NewIndex, 3 )
ENDWITH
ENDPROC
PROCEDURE cbolistgood.Init
WITH This
.AddItem( 'Cleveland' )
.List[.NewIndex, 2] = 'Ohio'
.List[.NewIndex, 3] = '44122'
.AddItem( 'Caversham' )
.List[.NewIndex, 2] = 'England'
.List[.NewIndex, 3] = 'RG4 8BX'
.AddItem( 'Buffalo' )
.List[.NewIndex, 2] = 'New York'
.List[.NewIndex, 3] = '14228'
.AddItem( 'Milwaukee' )
.List[.NewIndex, 2] = 'Wisconsin'
.List[.NewIndex, 3] = '43225'
.AddItem( 'International Falls' )
.List[.NewIndex, 2] = 'Minnesota'
.List[.NewIndex, 3] = '42666'
ENDWITH
ENDPROC
PROCEDURE cbolistitem.Init
WITH This
.AddListitem( 'Cleveland' )
.AddListItem( 'Ohio', .NewItemID, 2 )
.AddListItem( '44122', .NewItemID, 3 )
.AddListItem( 'Caversham' )
.AddListItem( 'England', .NewItemID, 2 )
.AddListItem( 'RG4 8BX', .NewItemID, 3 )
.AddListItem( 'Buffalo' )
.AddListItem( 'New York', .NewItemID, 2 )
.AddListItem( '14228', .NewItemID, 3 )
.AddListItem( 'Milwaukee' )
.AddListItem( 'Wisconsin', .NewItemID, 2 )
.AddListItem( '43225', .NewItemID, 3 )
.AddListItem( 'International Falls')
.AddListItem( 'Minnesota', .NewItemID, 2 )
.AddListItem( '42666', .NewItemID, 3 )
ENDWITH
ENDPROC
ENDDEFINE
See Also
Reference
ListIndex Property (Visual FoxPro)