TW3ListBox

SmartCL.Controls.ListBox;

TW3ListBox = class(TW3Panel)

The Listbox control is implemented in the TW3ListBox class, which is defined in the w3listbox unit. It represents a flexible listbox control where each item can contain further graphic controls.

A sample code for this section is included in the ControlsListbox project. Further demos are included with the Smart distribution (ListboxControl and ColorListbox ).

Public methods:

    function  Add: Integer; overload;
    function  Add(s: string): Integer; overload;
    procedure Clear;
    procedure Delete(itemIndex: integer);
    function  IndexOf(item: TW3CustomControl): Integer;
    procedure Insert(itemIndex: integer); overload;
    procedure Insert(itemIndex: Integer; s: string); overload;
    procedure Resize; override;

Properties:

public
property AllowMoving: boolean read FAllowMoving write FAllowMoving; //default False
property Count: integer read GetCount;
propertyEnableAnimation: boolean read FEnableAnimation write FEnableAnimation; //default True
property HighlightedIndex: integer read GetHighlightedIndex;
property HighlightedItem: TW3CustomControl read FHighlightedItem;
property Items[idx: integer]: TW3CustomControl read GetItem; default;
property ItemClass: TW3CustomControlClass read FItemClass write FItemClass; //default TW3Panel
property ItemHeight: integer read FItemHeight write FItemHeight; //default 32
property InnerSpacing: integer read FInnerSpacing write FInnerSpacing; //default 3
property MovingItem: TW3CustomControl read FMovingItem write SetMovingItem;
property SelectedIndex: integer read GetSelectedIndex write SetSelectedIndex;
property SelectedItem: TW3CustomControl read FSelectedItem;
property Styles: TW3ListBoxStyles read FStyles;
property Text[idx: integer]: string read GetText;
published
property OnHighlighted: TItemSelectedEvent read FOnHighlighted write FOnHighlighted;
property OnMouseDown: TMouseDownEvent read FOnMouseDown write FOnMouseDown;
property OnMouseEnter: TMouseEnterEvent read FOnMouseEnter write FOnMouseEnter;
property OnMouseExit: TMouseExitEvent read FOnMouseExit write FOnMouseExit;
property OnMouseMove: TMouseMoveEvent read FOnMouseMove write FOnMouseMove;
property OnMouseUp: TMouseUpEvent read FOnMouseUp write FOnMouseUp;
property OnMouseWheel: TMouseWheelEvent read FOnMouseWheel write FOnMouseWheel;
property OnSelected: TItemSelectedEvent read FOnSelected write FOnSelected;
property OnTouchBegin: TTouchBeginEvent read FOnTouchBegin write FOnTouchBegin;
property OnTouchMove: TTouchMoveEvent read FOnTouchMove write FOnTouchMove;
property OnTouchEnd: TTouchEndEvent read FOnTouchEnd write FOnTouchEnd;

. AllowMoving

If set to True (default is False), user can move listbox items around with a mouse or a finger.

The mouse/finger must be pressed down and not moving for at least 750 ms, before the item

can be moved.

. Count

Returns the number of items in the listbox.

. EnableAnimation

If True (default), the component will animate item movement whenever an item is inserted

or deleted. If False, items will just snap into place.

. HighlightedIndex

Returns the index (0-based) of the item under the mouse cursor or -1 if no item is highlighted.

. HighlightedItem

Contains the item which is currently highlighted or nil if no item is highlighted.

. Items

Allows read-only access to listbox items. In Smart, a listbox item is actually one of the controls

so you can still modify the item's appearance by changing its properties.

. ItemClass

Contains a class name for items in the listbox. By default, this property is set to TW3Panel,

meaning that all items added to the listbox will actually be panel controls.

. ItemHeight

Specifies height for listbox items. Default is 32.

. InnerSpacing

Contains a spacing (in pixels) between the listbox boundaries and listbox items.

. MovingItem

Contains the item which is currently moved with a mouse or a finger. Contains nil if no item is being moved.

. SelectedIndex

Returns the index (0-based) of the item that is selected (was clicked with a mouse or touched with a finger). Returns -1 if no item is selected.

. SelectedItem

Contains the item which is currently selected or nil if no item is selected.

. Styles

Contains properties (described below) that change the listbox appearance.

. Text

Returns the Caption of the first TW3Label found in the item idx.

. OnHighlighted

Triggered when an item is highlighted.

. OnSelected

Triggered when an item is selected.

__________________________

ListBox Styles

SmartCL.Controls.ListBox;

TW3ListBoxStyles = class

The properties of the TW3ListBoxStyles change the listbox appearance. They are accessed through the TW3ListBox.Styles property.

Properties:

  public
    property Highlighted: string read FHighlighted write FHighlighted;          //default 'TW3Panel'
    property HighlightedColor: TColor
      read FHighlightedColor write FHighlightedColor;                           //default clNone
    property HighlightVisible: boolean
      read FHighlightVisible write FHighlightVisible;                           //default True
    property Moving: string read FMoving write FMoving;                         //default 'TW3Panel'
    property MovingColor: TColor read FMovingColor write FMovingColor;          //default clGrey
    property Item: string read FItem write FItem;                               //default 'TW3Panel'
    property ItemColor: TColor read FItemColor write FItemColor;                //default clNone
    property Selected: string read FSelected write FSelected;                   //default 'TW3Panel'
    property SelectedColor: TColor read FSelectedColor write FSelectedColor;    //default clNone;
    property SelectionVisible: boolean
      read FSelectionVisible write FSelectionVisible;                           //default True
    property Text: string read FText write FText;                               //default 'TW3Label'  end;

. Highlighted

Contains the style (default TW3Panel) that is applied to a highlighted item.

. HighlightedColor

Contains the colour (default clNone) that is applied to a highlighted item.

. HighlightVisible

Specifies whether the Highlighted and HighlightedColor styles are used whenever an item is to be highlighted (default True).

. Moving

Contains the style (default TW3Panel) that is applied to an item being moved around with a mouse or a finger.

. MovingColor

Contains the colour (default clGrey) that is applied to an item being moved around.

. Item

Contains the style (default TW3Panel) that is applied to a "normal" (not selected, highlighted or moving) listbox item.

. ItemColor

Contains the colour (default clNone) that is applied to a normal item.

. Selected

Contains the style (default TW3Panel) that is applied to a selected item.

. SelectedColor

Contains the colour (default clNone) that is applied to a selected item.

. SelectionVisible

Specifies whether the Selected and SelectedColor styles are used whenever an item is selected (default True).

. Text

Contains the style (default TW3Label) that is applied to a text item (created with the Add(s: string) function).

Useful inherited properties:

. Enabled

. Visible

. StyleClass

. Name, Left, Top, Width, Height

Unit: SmartCL.Controls.ListBox.pas

Hierarchy

TObject

TW3Panel

TW3ListBox

Properties
AllowMoving
Count
EnableAnimation
HighlightedIndex
HighlightedItem
InnerSpacing
Items
ItemClass
ItemHeight
MovingItem
SelectedIndex
SelectedItem
Styles
Text
Methods
Add
Clear
Delete
IndexOf
Insert
Events
OnHighlighted
OnSelected

Properties

AllowMoving

Specifies whether user is able to rearrange items by holding mouse button and moving mouse.

property AllowMoving: boolean read FAllowMoving write FAllowMoving;

When this property is set to True, user is able to click (tap) and hold to move position of items.

Remarks:

It is important to note that after changing Item’s position, actual position inside items array is also changed.

Appearance of currently moving item may be adjusted via Styles property.

Count

Determine number of items in control.

property Count: integer read GetCount;

EnableAnimation

Specify whether item will be animated when user finish with item moving.

property EnableAnimation: boolean read FEnableAnimation write              FEnableAnimation;

If this property is set to False, item being dragged will be automatically be placed on new position after user release button (tap). If set to True, item will be smoothly moved to new position allowing user to more easily identify new position of item. Also, other items being shifted will be animated while their position is changed.

HighlightedIndex

Identify index of item being hovered with mouse.

property HighlightedIndex: integer read GetHighlightedIndex;

HighlightedItem

property HighlightedItem: TW3CustomControl read FHighlightedItem;

InnerSpacing

Specifies space (in pixels) around item. Default value is 3.

property InnerSpacing: integer read FInnerSpacing write FInnerSpacing

Following image shows where spacing is applied:

Items

Identifies item at specified index (zero-based) inside items array (TObjectList).

property Items[idx: integer]: TW3CustomControl read GetItem; default;

Parameters:

idx

Integer

Index of item. This parameter is zero-based.

ItemClass

Specifies class used when new item is created, and added into array (via Add method). Default class used in Item’s creation process is TW3Panel, but other class may be specified.

property ItemClass: TW3CustomControlClass read FItemClass write FItemClass;

Even classes (components) such as TW3ToggleSwitch may be used to represent items:

W3ListBox1.ItemClass:= TW3ToggleSwitch;W3ListBox1.Add;

ItemHeight

Specifies vertical size of item. It is set when item is being added via Add method.

property ItemHeight: integer read FItemHeight write FItemHeight;

MovingItem

Identify item currently being moved. User may start item moving by holding mouse button (tap) over item. Item being moved will slightly change appearance to indicate moving state.

property MovingItem: TW3CustomControl read FMovingItem  write SetMovingItem;

SelectedIndex

Specifies index of currently selected item. Selected item will have different appearance than other items (which can customized with Styles property).

property SelectedIndex: integer read GetSelectedIndex  write SetSelectedIndex;

If value of property is changed, OnSelected event will occur. Changes to this property also take affect on SelectedItem property and vice-versa.

Remarks:

Setting this property to -1 will unselect all items.

SelectedItem

Identify currently selected item. User may change selected item by clicking on desired item, or via SelectedIndex property.

property SelectedItem: TW3CustomControl read FSelectedItem;

Styles

Identify object responsible for managing styles used for different item states, e.g. when item is selected, highlighted, or is currently moving.

property Styles: TW3ListBoxStyles read FStyles;

For each different state Color or CSS class may be set.

Example:

W3ListBox1.Styles.MovingColor:= clYellow;

To change "hover" color, set:

W3ListBox1.Styles.HighlightedColor:= clRed;

For more drastic changes, CSS class for each set can be set.

Examples:

W3ListBox1.Styles.Highlighted:= 'TW3Button';
W3ListBox1.Styles.Highlighted:= 'MyCSSStyle';

Text

Return Caption for item with specifies index.

property Text[idx: integer]: string read GetText;

Parameters:

idx

Integer

Index of item. This parameter is zero-based.

Remarks:

Only Caption of items added via Add method with string parameter will be returned. Overloaded version of Add method without string parameter doesn’t create TW3Label inside item, so using this property on that items have no effect.

Methods

Add

Create and add one new item at the end of items array. Second overloaded method also create TW3Label component inside item.

function Add: Integer; overload;function Add(s: string): Integer; overload;

Parameters:

string

Initial text to be placed inside child TW3Label component.

Following examples are showing differences between items created with this two overloaded methods.

W3ListBox1.Add;

Output:

<div id="OBJ34" class="TW3Panel" style="visibility: visible; display: inline-block; position: absolute; overflow: hidden; left: 3px; top: 3px; width: 150px; height: 32px; z-index: 4;"></div>

W3ListBox1.Add('Sample Item');

Output:

<div id="OBJ34" class="TW3Panel" style="visibility: visible; display: inline-block; position: absolute; overflow: hidden; left: 3px; top: 3px; width: 150px; height: 32px; z-index: 4;">  <fieldset id="OBJ35" class="TW3Label" ...>    <div id="OBJ36" class="TW3LabelText" ...>Sample Item</div>  </fieldset></div>

As may be seen, second overloaded method will create TW3Label for each item. In that case Text array property may be used to read Item’s caption.

Clear

Delete all items from items array. After calling this method, Count property will return zero.

procedure Clear;

Items will be deleted instantly, without animation. To delete item with animation, use Delete method instead.

Delete

Delete item with specified index. If EnableAnimation is True, other items will be smoothly moved to occupy space previously owned by item just being deleted.

procedure Delete(itemIndex: integer);

Parameters:

itemIndex

Integer

Index of item listed for deletion. This parameter is zero-based.

IndexOf

Return index (zero-based) of item.

function IndexOf(item: TW3CustomControl): Integer;

Insert

Insert item at specified position within items array. Unlike with Add method, items will be animated (if EnableAnimation is True) while new item occupy space.

procedure Insert(itemIndex: integer); overload;
procedure Insert(itemIndex: Integer; s: string); overload;

Parameters:

itemIndex

Integer

Position of newly added item. This parameter is zero-based.

string

Initial text to be placed inside child TW3Label component.

Similar to Add method, second overloaded parameter create a TW3Label object inside each item.

Example:

W3ListBox1.Insert(W3ListBox1.SelectedIndex, 'MyItem');

Events

OnHighlighted

Occurs when user move mouse over item.

property OnHighlighted: TItemSelectedEvent read FOnHighlighted  write FOnHighlighted;

OnSelected

Occurs when value of SelectedItem property is changed.

property OnSelected: TItemSelectedEvent read FOnSelected  write FOnSelected;

Parameters:

itemIndex

Integer

Index of currently selected item. This parameter is zero-based. If there is no selected item, value will be -1.