Navigation: TextEd > Extension and Scripts > Visual components >

TListBox, TCheckListBox

 

 

 

TListBox displays string in a scrollable list. Use TListBox to display a scrollable list of items that users can select, add, or delete. TListBox is a wrapper for the Windows listbox control.

 

In some examples we assume a list box has been created and is named "List1".

 

TListBox list = TListBox.Create(form);

TCheckListBox list = TCheckListBox.Create(form);

 


Properties



 

property TAlign Align;

Determines how the control aligns within its container (parent control).

 

enum TAlign {

  alNone,

  alTop,

  alBottom,

  alLeft,

  alRight,

  alClient,

  alCustom

};

 

Ex. list.Align = alNone;


 

property Bool AlignWithMargins;

Indicates whether a control should be constrained by margins. If AlignWithMargins is true, use the Margins property of the control to govern the spacing relative to other controls that are aligned with this one.


 

property TAnchors Anchors;

Specifies how the control is anchored to its parent.

 

enum TAnchorKind {

  akLeft,

  akTop,

  akRight,

  akBottom

};

 

Ex. list.Anchors = akLeft + akTop;


 

property Bool AutoComplete;

Determines whether the user can give focus to items by typing in the list. Use AutoComplete to specify whether the list box automatically updates the ItemIndex property in response to user keystrokes. When AutoComplete is true, the item with focus changes to the first item that begins with the sequence of characters that the user typed. As the user types more characters, ItemIndex may change to a later item because the string to match becomes longer.


 

property Int AutoCompleteDelay;

Specifies the delay between a key press and an attempt to autocomplete the field, given in milliseconds.


 

(TCheckListBox) property bool Checked[int Index];

Indicates which items are checked.


Ex.

if (list.Checked[0]) {

  // Do something...

}


 

property TColor Color;

Specifies the background color of the control. The color value can be an hexadecimal or a color constant.


 

Defined color constants are:

clAqua, clBlack, clBlue, clCream, clDkGray, clFuchsia, clGray, clGreen, clLime, clLtGray, clMaroon, clMedGray, clMoneyGreen, clNavy, clOlive, clPurple, clRed, clSilver, clSkyBlue, clTeal, clWhite, clYellow.


 

Defined system color constants:

clNone                     White on Windows 9x, Black on NT.

clScrollBar                Current color for the of scroll bar track.

clBackground               Current background color of the Windows desktop

clActiveCaption            Current color of the title bar of the active window

clInactiveCaption          Current color of the title bar of inactive windows

clMenu                     Current background color of menus

clWindow                   Current background color of windows

clWindowFrame              Current color of window frames

clMenuText                 Current color of text on menus

clWindowText               Current color of text in windows

clCaptionText              Current color of the text on the title bar of the active window

clActiveBorder             Current border color of the active window

clInactiveBorder           Current border color of inactive windows

clAppWorkSpace             Current color of the application workspace

clHighlight                Current background color of selected text

clHightlightText           Current color of selected text

clBtnFace                  Current color of a button face

clBtnShadow                Current color of a shadow cast by a button

clGrayText                 Current color of text that is dimmed

clBtnText                  Current color of text on a button

clInactiveCaptionText      Current color of the text on the title bar of an inactive window

clBtnHighlight             Current color of the highlighting on a button

cl3DDkShadow               Windows 95 or NT 4.0 only: Dark shadow for three-dimensional display elements

cl3DLight                  Windows 95 or NT 4.0 only: Light color for three-dimensional display elements (for edges facing the light source)

clInfoText                 Windows 95 or NT 4.0 only: Text color for tool tip controls

clInfoBk                   Windows 95 or NT 4.0 only: Background color for tool tip controls

clGradientActiveCaption    Windows 98 or Windows 2000: Right side color in the color gradient of an active window's title bar.

clActiveCaption            specifies the left side color.

clGradientInactiveCaption  Windows 98 or Windows 2000: Right side color in the color gradient of an inactive window's title bar. clInactiveCaption          specifies the left side color.

clDefault                  The default color for the control to which the color is assigned.


Ex. list.Color = 0x0000FF00;

Ex. list.Color = clGreen;


 

property int Columns;

Specifies the number of columns, in a multi-column list box, that are visible without having to scroll. Use Columns to specify the number of columns, in a multi-column list box, that are visible without having to use the horizontal scroll bar.

Multi-column list boxes have a horizontal scroll bar that allows users to view multiple columns as they wrap. The default value for Columns is 0, meaning that the list box is not multi-column. That is, users can scroll only vertically and the list of items will not wrap.


 

property Int Count;

Indicates the number of items in the list box. Use Count to determine the number of items in the list box.


 

property Bool Enabled;

Controls whether the control responds to mouse, keyboard, and timer events.


 

property TFont Font;

Controls the attributes of text written on or in the control. To change to a new font, specify a new TFont object. To modify a font, change the value of the Charset, Color, Height, Name, Pitch, Size, or Style of the TFont object.

 

Ex. list.Font.Size = 12;


 

property int Height;

Specifies the vertical size of the control in pixels.

 

Ex. list.Height = 16;


 

property String Hint;

Contains the text string that can appear when the user moves the mouse over the control.


 

property Int ItemHeight;

Specifies the height, in pixels, of the items in the listbox.


 

property int ItemIndex;

Specifies the index of the selected item. Read ItemIndex to determine which item is selected. The first item in the list has index 0, the second item has index 1, and so on. If no item is selected, the value of ItemIndex is -1.


 

property TStrings Items;

Provides access to the list of items (strings) in the list portion of the list box.

 

Ex. String s = List1.Items[0];

Ex. list.Items[0] = "Hello World!";


Common TStrings methods:

 

       function   int Add(const String S);                  // Adds a string at the end of the list.

       procedure      Clear();                              // Clear the entire list

       procedure      Delete(int Index);                    // Delete a string in the list

       function   int IndexOf(const String S);              // Returns the position of a string in the list.

       procedure      Insert(int Index, const String S);    // Insert string in a specific position

       procedure      LoadFromFile(const String FileName);  // Load strings from a file

       procedure      SaveToFile(const String FileName);    // Save strings to a file


 


 

property int Left;

Specifies the horizontal coordinate of the left edge of a component relative to its parent.


 

property TMargins Margins;

Specifies the margins for the control. TMargins help define the relative position between components on a form, and between the edges of the form and the component. For example, when you set a left margin for a component to 10 pixels, the component will not come closer than 10 pixels to the edge of the container, or to another component on the left edge. The number of pixels by which two components are separated is the sum of the pixels of both components.

TMargins have the class members top, bottom, left and right.

 

Ex. list.Margins.Left = 10;


 

property Bool MultiSelect;

Specifies whether the user can select more than one item. Use MultiSelect to specify whether the user can select more than one item. When MultiSelect is true, the user can select multiple items in the control, and the SelCount property indicates the number of selected items. When MultiSelect is false, the user can only select one item, which is indicated by the ItemIndex property.


 

property String Name;

Specifies the name of the component as referenced in code.


 

property TPadding Padding;

Specifies the padding of a control. Padding works similar to margins.


Ex. list.Padding.Left = 4;


 

property TWinControl Parent;

Use the Parent property to get or set the parent of this control. The parent of a control is the control that contains the control. For example, if an application includes three radio buttons in a group box, the group box is the parent of the three radio buttons, and the radio buttons are the child controls of the group box.

 

Ex.

TListBox List1 = TListBox.Create(form);

List1.Parent = form;

List1.Left = 8;


 

property Bool ParentColor;

To have a control use the same color as its parent control, set ParentColor to true. If ParentColor is false, the control uses its own Color property.


 

property Bool ParentFont;

Determines where a control looks for its font information.

To have a control use the same font as its parent control, set ParentFont to true. If ParentFont is false, the control uses its own Font property.


 

property TPopupMenu PopupMenu;

Identifies the pop-up menu associated with the control.


 

property int SelCount;

Indicates the number of selected items. Read SelCount to determine the number of items that are currently selected. If the value of the MultiSelect property is false, SelCount is always -1.


 

property Bool Selected[int Index];

Indicates whether a particular item is selected. Use Selected to query the state of a particular item in the list box. If the item specified by the Index parameter is selected in the list box, the value of the Selected property is true. If the specified item is not selected, Selected is false. Set Selected to change the currently selected item.

 

The Index parameter is the item referenced by its position in the list box, with the first item having an Index value of 0.

 

Ex.

       string s;

       for (int i = 0; i < List1.Count; i++) {

         if (List1.Selected[i]) {

           s = s + List1.Items[i];

         }

       }


 

property Bool ShowHint;

Determines whether the control displays a Help Hint when the mouse pointer rests momentarily on the control.


 

property Bool Sorted;

Determines whether the list portion of the combo box is sorted. Set Sorted to true to sort the items in the drop down list alphabetically. New items added to the list are inserted in the correct alphabetical position.


 

property TTabOrder TabOrder;

TabOrder is the order in which child windows are visited when the user presses the Tab key. The control with the TabOrder value of 0 is the control that has the focus when the form first appears.

 

Initially, the tab order is always the order in which the controls were added to the form. The first control added to the form has a TabOrder value of 0, the second is 1, the third is 2, and so on. Change this by changing the TabOrder property.  


 

property Bool TabStop;

Determines if the user can tab to a control.


 

property int Tag;

Stores an integer value as part of a component.


 

property int Top;

Specifies the Y coordinate of the top left corner of a control, relative to its parent or containing control in pixels.


 

property Boolean Visible;

Indicates whether the control is visible.


 

property int Width;

Specifies the horizontal size of the control or form in pixels.


 


Methods



 

constructor Create(TComponent AOwner) 

Creates and initializes a new TComboBox object.

 

Ex. TListBox List1 = TListBox.Create(form);


 

procedure Clear;

Remove all items from the list.


 

procedure ClearSelection;

Removes the selection, leaving all items unselected.


 

procedure Free;

Destroys an object and frees its associated memory, if necessary. Visual controls added to a form is automatically destroyed when the form closes.

 

Ex.

TForm form = new TForm(nil);

TListBox List1 = TListBox.Create(form);

...

List1.Free;


 

procedure Hide;

Hides the control.


 

procedure SelectAll;

Select all lines in the list box.


 

procedure Show;

Shows the control. Use Show to set the control's Visible property to true.


 


Events



 

OnClick 

Occurs when the user clicks the control.


Ex.

 

TForm form;

TListBox List1;

void List1Click(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);  

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnClick = &List1Click;

}


 

OnDblClick 

Occurs when the user double-clicks the left mouse button when the mouse pointer is over the control.


Ex.

 

TForm form;

TListBox List1;

void List1DblClick(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);  

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnDblClick = &List1DblClick;

}


 

OnEnter 

Occurs when a control receives the input focus. Use the OnEnter event handler to cause any special processing to occur when a control becomes active.


Ex.

 

TForm form;

TListBox List1;

void List1Enter(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnEnter = &List1Enter;

}


 

OnExit 

Occurs when the input focus shifts away from one control to another. Use the OnExit event handler to provide special processing when the control ceases to be active.


Ex.

 

TForm form;

TListBox List1;

void List1Exit(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnExit = &List1Exit;

}


 

OnKeyDown 

Occurs when a user presses any key while the control has focus.

 

(ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble) TShiftState;

 

Ex.

 

TForm form;

TListBox List1;

void List1KeyDown(TObject Sender, WORD &Key, TShiftState Shift)

{

  // Do some work here

  if (Key == VK_F1) {

    // F1 was pressed, lets do something...

 

  }

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnKeyDown = &List1KeyDown;

}


 

OnKeyPress 

Occurs when a key is pressed.


Ex.

 

TForm form;

TListBox List1;

void List1KeyPress(TObject Sender, char &Key)

{

  // Do something

}

 

{

  form = new TForm(nil);

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnKeyPress = &List1KeyPress;

}


 

OnKeyUp 

Occurs when the user releases a key that has been pressed.


(ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble) TShiftState;

 

Ex.

 

TForm form;

TListBox List1;

void List1KeyUp(TObject Sender, WORD &Key, TShiftState Shift)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnKeyUp = &List1KeyUp;

}


 

OnMouseDown 

Occurs when the user presses a mouse button with the mouse pointer over a control.


(ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble) TShiftState;

 

enum TMouseButton {

  mbLeft,

  mbRight,

  mbMiddle

};

 

Ex.

 

TForm form;

TListBox List1;

void List1MouseDown(TObject Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  // Do some work here if left mouse button was pressed

  if (Button == mbLeft) {

    // Left mouse button was pressed. Lets do something...

 

  }

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnMouseDown = &List1MouseDown;

}


 

OnMouseEnter 

Occurs when the user moves the mouse into a control.


Ex.

 

TForm form;

TListBox List1;

void List1MouseEnter(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnMouseEnter = &List1MouseEnter;

}


 

OnMouseLeave 

Occurs when the user moves the mouse outside of a control.


Ex.

 

TForm form;

TListBox List1;

void List1MouseLeave(TObject Sender)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnMouseLeave = &List1MouseLeave;

}


 

OnMouseMove 

Occurs when the user moves the mouse pointer while the mouse pointer is over a control.


Ex.

 

int FMouseX,FMouseY;

TForm form;

TListBox List1;

void List1MouseMove(TObject Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  // Do some work here

  FMouseX = X;

  FMouseY = Y;

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnMouseMove = &List1MouseMove;

}


 

OnMouseUp 

Occurs when the user releases a mouse button that was pressed with the mouse pointer over a component.

 

Ex.

 

TForm form;

TListBox List1;

void List1MouseUp(TObject Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  // Do some work here

}

 

{

  form = new TForm(nil);

 

  List1 = TListBox.Create(form);

  List1.Parent = form;

  List1.OnMouseUp = &List1MouseUp;

}


 


 


 


 


 


 

 

 

 

Copyright © 2022 Rickard Johansson