TW3ListBox

From Smart Mobile Studio
Jump to: navigation, search


Unit: UnitName.pas


Hierarchy
TObject
TW3TagObj
TW3Component
TW3MovableControl
TW3CustomControl
TW3Panel
TW3ListBox


Properties
Property-icon.png AllowMoving
Property-icon.png Count
Property-icon.png EnableAnimation
Property-icon.png HighlightedIndex
Property-icon.png HighlightedItem
Property-icon.png InnerSpacing
Property-icon.png Items
Property-icon.png ItemClass
Property-icon.png ItemHeight
Property-icon.png MovingItem
Property-icon.png SelectedIndex
Property-icon.png SelectedItem
Property-icon.png Styles
Property-icon.png Text
Methods
Method-icon.png Add
Method-icon.png Clear
Method-icon.png Delete
Method-icon.png IndexOf
Method-icon.png Insert
Events
Event-icon.png OnHighlighted
Event-icon.png OnSelected


Properties

Property-icon.png 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.


Property-icon.png Count

Determine number of items in control.

property Count: integer read GetCount;


Property-icon.png 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.


Property-icon.png HighlightedIndex

Identify index of item being hovered with mouse.

property HighlightedIndex: integer read GetHighlightedIndex;


Property-icon.png HighlightedItem

property HighlightedItem: TW3CustomControl read FHighlightedItem;

Property-icon.png 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:

TW3ListBox InnerSpacing


Property-icon.png 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.


Property-icon.png 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;


Property-icon.png ItemHeight

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

property ItemHeight: integer read FItemHeight write FItemHeight;


Property-icon.png 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;


Property-icon.png 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.


Property-icon.png SelectedItem

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

property SelectedItem: TW3CustomControl read FSelectedItem;


Property-icon.png 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;

TW3ListBox 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';


Property-icon.png 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

Method-icon.png 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:

s

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.


Method-icon.png 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.


Method-icon.png 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.


Method-icon.png IndexOf

Return index (zero-based) of item.

function IndexOf(item: TW3CustomControl): Integer;


Method-icon.png 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.

s

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

Event-icon.png OnHighlighted

Occurs when user move mouse over item.

property OnHighlighted: TItemSelectedEvent read FOnHighlighted
  write FOnHighlighted;


Event-icon.png 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.