ListBox C#

Windows Controls: The List Box

Introduction to List Boxes

A list box presents a list of items to choose from. Each item displays on a line. Here is an example of a list box:

The user makes a selection by clicking an item in the list. Once clicked, the item or line on which the mouse landed becomes highlighted, indicating that it is the current choice. After an item has been selected, to make a different selection, the user would click another. The user can also press the up and down arrow keys to navigate through the list and make a selection.

A list box can also be configured to allow multiple selections.

One of the main reasons for using a list box is to display a list of items to the user. Sometimes the list would be very large. If the list is longer than the available space on the control, the control would be equipped with a scroll bar that allows the user to navigate up and down to access all items of the list. You will have the option of deciding how many items to display on the list.

Practical Learning:Introducing List Boxes

1. Start Embarcadero RAD Studio
2. To create a new application, on the main menu, click File -> New -> VCL Forms Application - C++Builder
3. In the Object Inspector, change the following properties:
   Caption: Solo Musical Instrument Store
   Name: frmMusicalStore
   Position: poScreenCenter
4. To save the project, on the main menu, click File -> Save All
5. Click New Folder
6. Type MusicalInstrumentStore1 as the name of the folder and press Enter twice to display the contents of that folder
7. Change the unit file to MusicalStore and click Save
8. Change the project name to MusicalInstrumentStore and click Save
9. To create an XML file, on the main menu, click File -> New -> Other...
10. In the left list, click Web Documents
11. In the right list, click XML File

12. Click OK
13. Complete the file with a few items as follows: 581705 Guitars Electric Gibson Les Paul Vintage Mahogany Electric Guitar 745.95 724475 Bass Electric 4-String Epiphone Thunderbird IV Bass 325.85 902735 Keyboards Synthesizers Alesis QS8.2 88 Key Synthesizer 825.50 793500 Guitars Acoustic Gretsch Guitars G100 Synchromatic Archtop Acoustic Guitar 595.95 297300 Drums Drum Set Pulse Pro 5-Piece Drum Set with Cymbals 395.95 931805 Keyboards Pianos Roland RD-700SX Digital Piano 2195.00 37940 Accessories Cables Mogami Gold AES/EBU Interconnect Cable with Neutrik XLR 45.85 207485 Guitars Acoustic-Electric Ibanez V Series V70CE Dreadnought Cutaway Acoustic-Electric Guitar 225.50 927358 Guitars Electric Schecter C-1 Hellraiser Electric Guitar 650.00 508384 Keyboards Synthesizers Roland V Synth GT Elastic Audio Synthesizer Keyboard 2895.50
14. To save the file, on the Standard toolbar, click the Save All button
15. Change the file name to StoreItems and click Save
16. Display the form
17. From the Internet section of the Tool Palette, click TXmlDocumentand click the form
18. In the Object Inspector, change the control's name to xdcStoreItems
19. Click FileName then click its ellipsis button
20. Locate the StoreItems.xml file, click it, and click Open
21. Click the Active check box to make it True
22. Save all

To support list boxes, the VCL provides a class named TListBox. The TListBox class is immediately derived from the TCustomListBox class that actually holds its characteristics as a list-based control. The TListBox and the TCustomListBox classes are defined in the StdCtrls.hpp library.

As we will see in later sections, a list box can be made to allow a user to select more than one item at a time. To support this, the TCustomListBox class is derived from a class named TCustomMultiSelectListControl. To support list-based controls, the VCL provides the TCustomListControl that is the parent of TCustomMultiSelectListControl. Both the TCustomMultiSelectListControl and the TCustomListControl classes are defined in the Controls.hpp header file. The TCustomListControl class derives from TWinControl:

To visuall add a list box to your application, in the Standard section of the Tool Palette, click the TListBox controland click the form.

To dynamically create a list box, declare a pointer to a TListBox class and use the new operator to allocate memory for the variable. Also, the constructor of the TListBox needs to know the component that owns the control; this is usually the host or container of the list box. This can be done as follows:

//--------------------------------------------------------------------------- void __fastcall TForm1::CreateTheList[] { TListBox* Liste = new TListBox[this]; Liste->Parent = Form1; } //---------------------------------------------------------------------------

If the list box will be positioned on another type of container, such as a panel called Panel1, you can create it as follows:

//--------------------------------------------------------------------------- void __fastcall TForm1::CreateTheList[] { TListBox* Liste = new TListBox[this]; Liste->Parent = Panel1; } //---------------------------------------------------------------------------

If you create the list box in a function, a method, or an event, the list will exist only inside of that function: you cannot manipulate it from another function, method, or event. If you want the control to be accessed by many functions declare a TListBox variable in the header file of the form where the control will be hosted.. Here is an example:

//--------------------------------------------------------------------------- #ifndef Unit1H #define Unit1H //--------------------------------------------------------------------------- #include #include #include #include //--------------------------------------------------------------------------- class TForm1 : public TForm { __published: // IDE-managed Components private: // User declarations TListBox *Listing; public: // User declarations __fastcall TForm1[TComponent* Owner]; }; //--------------------------------------------------------------------------- extern PACKAGE TForm1 *Form1; //--------------------------------------------------------------------------- #endif

After declaring the control, you should initialize it in the form�s constructor. This allows you to specify the container that will host the control:

//--------------------------------------------------------------------------- __fastcall TForm1::TForm1[TComponent* Owner] : TForm[Owner] { Listing = new TListBox[Form1]; Listing->Parent = Form1; } //---------------------------------------------------------------------------

When an application terminates, C++Builder takes care of destroying all of the objects that are part of the application. If the objects were created at design time, they are owned by the form. Since the form is owned by the application, the application would destroy the form including its hosted controls. If a control was placed on another container such as a panel, the panel is owned by the form and the form by the application. The destruction would still be smooth when the application executes. If you dynamically create a control, you must specify the owner of the control; otherwise the program would not compile. Since you will have specified the owner or container of the control, when the application exits, the compiler would destroy the form and its control, which would include the control you dynamically created. Therefore, you do not have to worry about the state of the dynamic controls when your application exits. This does not mean that your application would never produce a memory leak, but it would be highly unlikely.

If you want to explicitly destroy your dynamically created object, the best place to destroy a global object is to use the delete operator on the OnDestroy event of the form:

//--------------------------------------------------------------------------- void __fastcall TForm1::FormDestroy[TObject *Sender] { delete Listing; Listing = NULL; } //---------------------------------------------------------------------------

Practical Learning: Creating Combo Boxes

1. Design the form as follows:
   

   Control Caption ColCount FixedxCols Kind Name TGroupBox Item Selection TLabel Item Category: Label Item Type: TListBox lbxItemsCategories TListBox lbxItemsTypes TGroupBox Available Items TStringGrid 3 0 grdAvailableItems TBitBtn bkClose

2. Save all

Characteristics of a List Box

After adding a list box to a container, you can move it by clicking and dragging the control. You can also resize it using any of the techniques we learned to add, position, move, and resize controls on a component. If the list will cover many items, design it so its height can display 8 items at a time. Otherwise, for a list of 8 or less items, use only the necessary height that would accommodate all of the items.

If you are programmatically creating the control, you can specify its Windows characteristics as you see fit. Here is an example:

//--------------------------------------------------------------------------- __fastcall TForm1::TForm1[TComponent* Owner] : TForm[Owner] { Listing = new TListBox[Form1]; Listing->Parent = Form1; Listing->Left = 120; Listing->Top = 80; } //---------------------------------------------------------------------------

If you change the Color property of the ListBox control, its whole background would appear with that color. If you want each item to have its own color, you would have to change the style of the list and properly configure it.

If you position the control on a form whose DockSite property is set to true with the control having a DragKind property dkDock and the DragMode property set to dmAutomatic, the user will be able to move the control and position it anywhere inside the form.

Adding an Item to the List

The most fundamental and the most obvious aspect of a list box is the list of items it contains. To support the list of items of this control, the TCustomListBox class is equipped with a property named Items, which is of type TStrings:

__property Classes::TStrings * Items = {read=FItems,write=SetItems};

If you know the list of items for the control, there are two easy ways you can create it. At design time, on the Object Inspector, you can click the Items property to reveal its ellipsis button on the right field . To create the list, click this button to call the String List Editor, type each item desired, on its own line by pressing Enter:

To programmatically add the items to a list box, use the TStrings::Add[] method and the item as argument. If the list were empty, the new items would be added to the list. If the list already contained one or more items, the new items would be added, by default, to the end of the existing one[s]. Here is an example of creating a list of items or adding new ones to a list:

//--------------------------------------------------------------------------- void __fastcall TForm1::FormCreate[TObject *Sender] { Listing->Items->Add[L"C++Builder"]; Listing->Items->Add[L"Delphi"]; Listing->Items->Add[L"JBuilder"]; Listing->Items->Add[L"Kylix"]; } //---------------------------------------------------------------------------

Alternatively, to add an item or items to a list box, you can call the Win32 API�s SendMessage[] function with the LP_ADDSTRING as the message. The wParam argument is not used and can be passed as 0. The string to add must be null-terminated and must be cast to LPARAM. Here is an example:

//--------------------------------------------------------------------------- void __fastcall TForm1::FormCreate[TObject *Sender] { SendMessage[Listing->Handle, LB_ADDSTRING, 0, [LPARAM][L"Edem Kodjo"]]; } //---------------------------------------------------------------------------

The items of a list box are UnicodeString objects created from the TStrings class. This allows you to use the properties of the TStrings class.

The Columns of a List Box

When you create a list of items, they appear in one range of columns. If the number of items exceeds the height, a scrollbar would appear on the control. One alternative you can use is to span the list on more than one column. To support this, the TCustomListBox class provides the Columns property:

__property int Columns = {read=FColumns,write=SetColumns};

By default, the Columns value is set to 0, which means the items appear in one column.

Adding a Horizontal Scroll Bar to the Control

During introduction, we saw that if a List Box includes more items than the vertical size, which is the Height property, allows displaying, the control would be equipped with a vertical scroll that would allow the user to move up and down and access the whole list. If at least one of the items is wider than the control can display, this might not be obvious to the user. You would have to provide the control with a horizontal scroll bar. The Win32 provides a SendMessage[] function that can take care of this. Here is an example:

//--------------------------------------------------------------------------- void __fastcall TForm1::FormCreate[TObject *Sender] { SendMessage [Listing->Handle, LB_SETHORIZONTALEXTENT, 200, 0]; } //---------------------------------------------------------------------------

When the items have been added to a list box, they [the items] are managed through the TStrings class. In the list box, each item holds a position, also called its index, which is an integral. The index of the first item from top has a value of 0; the second item from top has an index of 1, and so on. To recognize the index of an item, the TCustomListControl class provides the ItemIndex property:

__property int ItemIndex = {read=GetItemIndex,write=SetItemIndex};

The TCustomListControl::ItemIndex is a property that identifies which item is selected in a list-based control. This is a property of highly particular interest. If you try performing an operation that requires that an item be selected and no item is selected, the program would throw an error. If no item is availble in the list, the TCustomListControl::ItemIndex has a value of �1.

Inserting an Item in the List

As opposed to adding an item to the [end of the] list box, you can insert a new item at a certain position. To do this, you can call the Insert[] method of the TStrings class. For example, to insert an item in the 2nd position you can write code such as:

//--------------------------------------------------------------------------- void __fastcall TForm1::btnAddSecondClick[TObject *Sender] { Listing->Items->Insert[1, "Delphi Prism"]; } //---------------------------------------------------------------------------

The most regular operation users perform on a list box is to select items. This selection is performed by the user clicking one of the items. Using code, you can also select an item in the list. This is done by assign the item's index to the ItemIndex property. For example, to select the 6th item of the list, you could write the code as:

//--------------------------------------------------------------------------- void __fastcall TForm1::Button1Click[TObject *Sender] { lstCountries->ItemIndex = 6; } //---------------------------------------------------------------------------

When performing your operations, sometimes you will want to find out if a particular item is selected. You can do this using the ordinal position of the item. For example, to find out if the 3rd item is selected, you can write:

//--------------------------------------------------------------------------- void __fastcall TForm1::Button7Click[TObject *Sender] { if[ lstCountries->ItemIndex == 2] Panel1->Caption = "The third item is selected"; } //---------------------------------------------------------------------------

If an item is selected, you can allow the user to perform an operation on it. If a string [that is, any string] is not selected, most operations would fail and the program would crash. Therefore, usually you should make sure an item is selected. An item is selected when the value of the TCustomListBox::ItemIndex integer value is not negative. Operations include displaying the selected item of the list box to an edit box:

//--------------------------------------------------------------------------- void __fastcall TForm1::Button6Click[TObject *Sender] { // First find out whether an item is selected if[lstCountries->ItemIndex != -1] // Put the selected item in the edit Edit1->Text = lstCountries->Items->Strings[lstCountries->ItemIndex]; } //---------------------------------------------------------------------------

inserting a new string above the selected item:

//--------------------------------------------------------------------------- void __fastcall TForm1::Button6Click[TObject *Sender] { lstCountries->Items->Insert[lstCountries->ItemIndex, Edit1->Text]; } //---------------------------------------------------------------------------

or under the selected string:

//--------------------------------------------------------------------------- void __fastcall TForm1::Button6Click[TObject *Sender] { lstCountries->Items->Insert[lstCountries->ItemIndex + 1, Edit1->Text]; } //---------------------------------------------------------------------------

Many times during your design, you will allow users to add or delete items to or from a list box. One way you will do this is to create a list of items originating from another list; this allows you to control the items the user can select from a list before continuing with the issue at hand. Embarcadero RAD Studio ships with a dialog box completely configured to handle this transaction.

To allow two list boxes to exchange data, you provide the appropriate buttons. If only one list will be used as the source, provide one button that could allow the user to select an item. It is also a good idea to allow the user to select and add all items at once. Also important is the ability for the user to remove mistakenly selected items. Over all, these kinds of list boxes handle their transactions through the use of four buttons: two are used to exchange one item at a time from one list to another, two to exchange all items from one list to another.

To get a dialog box that makes it easy to exchange items between two list boxes, display the New Items dialog box and select Dual List Box:

After clicking OK, you would receive a dialog box with two list boxes and all the code would be written for you:

As mentioned already, the user mostly interacts with a list box by selecting an item. At any time you can find out whether a particular item has been selected. This is done using the TCustomListBox::Selected Boolean property:

__property bool Selected = {read=GetSelected,write=SetSelected};