Difference between revisions of "TORListBox"

Revision as of 22:22, 22 July 2008

CPRS Delphi Controls Stuff

TORListBox is a listbox that is derived from the standard TListBox. It supports all of the properties associated with the standard list box an adds the following:

TORListBox Properties

• Delimiter Used conjuction with the Pieces property. This is the character used to delimit the pieces. The default is ^.

• DisplayText Run-time only. Contains the list of strings displayed by the list box. If the Pieces or TabPosition properties have been used, DisplayText[Index] returns the string as formatted for display. The Items property, on the other hand, always returns the entire string as it was passed in. DisplayText is read only.

• ItemTipColor Sets the background color of ItemTips. The default is the window background color. Some may wish to change this to clInfoText.

• ItemTipEnable Enables the display of ItemTips in response to mouse movement or keyboard navigation through the list box. ItemTips are similar to ToolTips. They display small framed windows that contain the entire text of the list box item. This is useful if the listbox is too narrow to show the entire text

• ItemIEN Run-time only. Returns as a variant the contents of the first piece of the currently selected item.

• LongList When true, causes the list box to operate in ‘Long List’ mode. When in this mode, only a small portion of the list is loaded into the listbox at a given time. Whenever the list is scrolled such that another portion of the list is needed, the OnNeedData event is triggered. When in LongList mode, a separate scrollbar is used to navigate the list. This scrollbar has 100 positions which are mapped to an alphabetic sequence.

• Pieces A comma delimited list of integers (for example, "2,7,3") which identifies which string pieces of Items[Index] should be displayed in the list box. If this field is left blank (the default), all pieces of the item string are displayed. The Delimiter property may be used to change the character on which string pieces are scanned.

• References Run-time only. Contains a list of variants that are stored with items in the list box. Each list box item may have one value of any type associated with it. This value may be changed or viewed in the References lists (for example, References[ItemIndex]). This operates similar to the Items.Objects list. But by storing variants, it allows the user to store a value to be associated with the listbox item without needing create and free an object.

• ShowHint Works like ShowHint in a regular listbox. However, the hint timer can be used by the ItemTip feature if this is set to true. So, if ShowHint is true (it is not necessary to have any text in the Hint property itself), the ItemTip will delay slightly before showing an ItemTip when the mouse first enters the listbox. This can eliminate some flickering.

• TabPositions A comma delimted list of integers(for example, "8,20,45") which identifies the character positions within the list box at which tab stops should be set. When used in conjuction with the Pieces property, the pieces will be tabbed out to the character positions listed in TabPositions. The positions must be in ascending order. Character positions are based on the average character width of the font - not the maximum character width.

• UniqueAutoComplete when set to true. The auto complete functionality of the combobox will only work on unique entries in the list. Also this only functions correctly when LongList = False.

TORListBox Methods

• function AddReference(const S: string; AReference: Variant): Integer;

Adds an item to a listbox and stores a value to be associated with it. The result of the function is the index at which the item was added. For example,

 lstTest.AddReference(‘a display string’, MyIDNum);
 

When lstTest is clicked, the value of MyIDNum can be retrieved by looking in References,

 with lstTest do ID := References[ItemIndex];

• procedure InsertReference(Index: Integer; const S: string; AReference: Variant);

Inserts an item in a listbox at the position specified by Index and stores a value to be associated with that item.

• function IndexOfReference(AReference: Variant): Integer;

Given a value, returns the first index in References that matches it.

• procedure ClearTop;

Clears the items that have been added to a long list box by the application (not items added by a call to OnNeedData).

• procedure ForDataUse(AList: TStrings);

If you have a list of items that should be added to a listbox in response to the OnNeedData event, you can pass the list into the listbox using the ForDataUse method. This method will automatically determine whether the items need to be added to the bottom of the listbox (because the use is scrolling down) or whether the items should be inserted at the top of the listbox (at the InsertAt position, because the user is scrolling up).

• procedure InitLongList(const StartAt: string);

Tells a long list box to load the initial set of items (it makes the first call to OnNeedData). Normally an empty string is passed as the parameter, unless you want to initially display the list at somewhere other than the starting position.

TORListBox Events

• OnNeedData called whenever the listbox needs more items. The procedure generated by this event looks something like:

 procedure TFrom1.ListBox1NeedData(Sender: TObject; 
                                   const StartFrom: string; 
                                   direction, InsertAt: Integer);

where -

• • Sender is the listbox that generated the event.
  • StartFrom is a string that contains the text of the last item that was visible in the listbox. If you are using $ORDER, this is the string that you should start from. Use Direction to tell whether you should use the normal or reverse $ORDER.
  • Direction is a set of codes that specifies which direction the user is moving through the listbox. llForward means the user is moving forward (i.e., pressing the scroll down button). llReverse means the user is moving backwards (i.e., pressing the scroll up button).
  • InsertAt is the position at which items should be inserted in the listbox. If the user is moving forwards through the listbox, you should ignore InsertAt and simply add items to the listbox - ListBox1.Items.Add(x).

However, if the user is moving backwards (Direction = llReverse), you should insert items using InsertAt - ListBox1.Items.Insert(InsertAt, x).