Copyright: (c) 1996 Steve Bannister


Contents
SBList OLE Control (Shareware)

SBList is a 32-bit custom list box, incorporating most of the features of the standard Windows list box but with many extra features :

•	Add a bitmap to any list item, in any position

•	Change font attributes within an item

•	Change color within an item

•	Click event fires with right mouse button

•	Will display horizontal & vertical lines

•	Multiple lines per list item

•	Powerful tab positioning

•	Set background color for individual items

•	Set highlight colors

•	Assign a string to each item as well as standard long data type


AddItem

This method adds entries to the list box. The first parameter contains the text to be added, the second is optional and contains the index number. If the second parameter is omitted the item will be added to the end of the list, or if the Sorted property is set then it will be inserted into the correct position. Text entries can be formatted

Examples:

SBList1.AddItem “Hello”

SBList1.AddItem “World” , 34


AddPacket

This method allows all elements of a list item to be added at once. The first parameter is the list index. If this value is -1 then the new item will be added to the end of the list, or if the sorted property is True it is inserted into the appropriate position. The second parameter is the text item to be put into the list and third is the item text. Fourth and subsequent parameters are optional. Fourth is item data, fifth is a picture, and sixth is the items background color.

Example:

SBList1.AddPacket -1, “UK”, “London”, 3, Image1.Picture, RGB(0,0,0)

SBList1.AddPacket 15, “USA”, “Washington DC”, 987


AddPicture

This method adds a new list item containing just a bitmap, icon, or metafile. The first parameter refers to the picture, which can either be the Picture property of another control, or the LoadPicture function. The second optional parameter is the list index which if omitted adds the picture to the end of the list.

Examples:

SBList1.AddPicture Picture1.Picture

SBList1.AddPicture LoadPicture(“me.bmp”) , 7


Appearance

Set to True to give the list box a 3D style border.


BackColor

Sets the background color for the list box. The background color of individual list items can be set using the ItemBackColor property.


Border

This boolean property selects whether a border is drawn around the list box, when it’s appearance is flat (set to 0).


Cell

This read-only, run-time property returns the part of a list item between 2 tab positions. If cell 0 is specified then the start of text up to (but not including) the first tab position is returned. A tab position is placed by ASCII code 9. The first parameter contains the cell number, the second optional parameter contains the list index. If this parameter is omitted, the currently selected item is used. If no item is selected a run-time error will occur. The text returned is stripped of escape codes.

Example:

a$ = SBList1.Cell(4,1)

b$ = SBList1.Cell(3)


CenterV

The Boolean property specifies whether text entries are printed vertically centered (True), or at a position specified by the TextTop property.


Clear

This method is used to remove all items from the list box

Example:

SBList1.Clear


Click

Private Sub SBList1_Click(ByVal Button As Integer, ByVal X As Integer, ByVal Y As Integer)

This event is fired when the mouse is clicked on a list item. The Button parameter returned indicates which button was used to click : 1 for left button, 2 for right button, and -1 if fired from code. The X and Y parameters contain the position, in pixels, of the mouse pointer within the image. If there is no image or the mouse pointer is not over the image, then -1 is returned in both parameters. The click event can be fired from code if the ListIndex is set, and the FireClick property is true.


ClipText

This Boolean property, if set, causes text to be truncated at tab positions, specified using the TabWidth property. If not set, it is possible for text to be superimposed upon one another.


Credits

Special thanks to Andrew Groom for providing the accompanying demonstration program, and for his invaluable feedback during the development of this control.


DblClick

Private Sub SBList1_DblClick(ByVal Button As Integer)

This event is fired when the user double clicks a list item. The Button parameter indicates which mouse button was used : 1 for left, 2 for right.


DotsHorizontal

This Boolean property specifies whether horizontal lines are draw solid (False) or dotted (True).


DotsVertical

This Boolean property specifies whether horizontal lines are draw solid (False) or dotted (True).


DragDrop DragOver
DragDrop, DragOver

As standard.


DragIcon

As standard.


DragMode

As standard.


Ellipsis

This Boolean property indicates whether an ellipsis (...) is drawn where text is truncated at tab positions. This only applies if the ClipText property is true.


Enabled

As standard.


EscapeChr

This property contains the ASCII value for escape characters that may be embedded within list items to alter the appearance of the following text. The default value is 92 which corresponds to a backwards slash. See formatting for further details.


FireClick

This Boolean property determines whether the click event is fired when the ListIndex property is changed. Its default setting is True.


Font

This property specifies what font text items will appear in. Font attributes can be altered by the use of escape codes, see formatting for further details.


ForeColor

This property specifies what color list items will appear as. The color can be altered by the use of escape codes, see formatting for further details.


ForeColor1

This property specifies the color text will appear as after escape code 1. The default is blue.


ForeColor2

This property specifies the color text will appear as after escape code 2. The default is red.


ForeColor3

This property specifies the color text will appear as after escape code 3.	The default is green.


ForeColor4

This property specifies the color text will appear as after escape code 4.	The default is cyan.


GotFocus LostFocus
GotFocus, LostFocus

As standard.


Height

As standard.


HelpContextID

As standard.


HighBackColor

This property specifies what background color appears on a selected item.


HighForeColor

This property specifies what color text appears as when selected.


HighLeft

This property sets the indentation, in pixels,  of the highlight bar. By default it is set to 0, the highlight bar is flush left.


hWnd

This run-time, read-only property returns the window handle of the list box.


Index

As standard.


IntegralHeight

This boolean property acts in the same way as a standard listbox IntegralHeight.


ItemBackColor

This run-time property is used to alter the background color from the default color specified by BackColor. The parameter specifies which item’s back color is to be altered.

Example:

SBList1.ItemBackColor(3) = RGB(128,128,128)


ItemData

This run-time property allows a long value to be attached to any list item. The value is not displayed. The parameter is the list index.

Examples:

SBList1.ItemData(56) = 1996

a& = SBList1.ItemData(100)


ItemHeight

This property specifies the height, in pixels, of a list box item. If the value is set to 0 (default) then the height is obtained from the selected font.


ItemPicture

This write-only property adds or changes an item’s picture. The method is especially suited to situations where one picture is replaced by another of the same size, in which case the new picture is drawn directly over the existing one with no list box refresh. If the pictures are of different sizes then a refresh will occur.

Example:

Set SBList1.ItemPicture(12) = Picture2.Picture


ItemText

This run-time property allows a string value to be attached to any list item. The value is not displayed. The parameter is the list index.

Examples:

SBList1.ItemData(56) = “Hello World”

a$ = SBList1.ItemData(100)


KeyDown KeyUp KeyPress
KeyDown,  KeyUp, KeyPress

As standard.


Left

As standard.


LineColor

This property specifies what color any horizontal and vertical lines are.


LineHorizontal

This property specifies the position of a horizontal line, drawn the width of the list box in each list item. The values that can be assigned are :

-2	Line is drawn at the bottom

-1	Line is drawn at the top

0	No line is drawn

1 or more	The vertical pixel position


LineVertical

This run-time property allows up to 32 vertical lines to be displayed. The parameter contains a line index between 0 and 31, and the value is the pixel position of the line. A value of -1 indicates no line is drawn.

Examples:

SBList1.LineVertical(1) = 35


List

This run-time property allows list box entries to be read or replaced. The parameter is the list index.

Examples:

SBList1.List(1) = “Hello World”

x$ = SBList1.List(84)


ListCount

This run-time, read-only property returns the number of items in the list box.


ListIndex

This run-time property sets or reads the index of the currently selected item. If no item is selected it returns -1.


ListRaw

This run-time, read-only property returns the contents of a list item, with any escape codes removed. The parameter contains the list index.

Example:

a$ = SBList1.ListRaw(45)


MouseIcon

As standard.


Mousepointer

As standard.


MouseDown MouseUp MouseMove
MouseDown, MouseUp, MouseMove

As standard.


Name

As standard. At design time, this value appears in the top left of the list box.


NewIndex

This run-time, read-only property contains the index number of the most recently added item. It is set to -1 if any items have been removed.


PicLeft

This property specifies the number of pixels between the left border and the left edge of an embedded picture


PicTop

This property specifies the number of pixels between the top of an item and the top edge of an embedded picture. It is ignored if the CenterV property is set.


Refresh

This method causes the list box display to redraw itself.

Example:

SBList1.Refresh


RemoveItem

This method removes a single item from the list box. The parameter is the list box index.

Example:

SBList1.RemoveItem 34


RightButton

This Boolean property specifies whether the right mouse button can be used to click and select list box items.


ShowFocus

This Boolean property specifies whether a focus rectangle is displayed whenever the list box has the focus. Its default is True, which matches the behaviour of a standard list box.


Sorted

This Boolean property specifies whether items added to the list box are sorted or not. Any escape characters are ignored for the purposes of sorting.


TabDots

This boolean property specifies whether dots are drawn between columns of text, as specified by the TabWidth property. This only has effect when the ClipText property is true.


TabIndex

As standard.


TabLines

A Boolean property, which if set will cause vertical lines to be drawn at tab positions specified with the TabWidth property. If set, any values stored using LineVertical are ignored.


TabStop

As standard.


TabWidth

This run-time property can specify the position of up to 32 tab stops. The parameter contains the tab index, the value contains the number of pixels from the left border. Each occurrence of ASCII character 9 within an item jumps to the next tab position, which means text may jump backwards if text extends over a tab position. This can be useful for multi-line text items.

Example:

SBList1.TabWidth(0) = 100


Tag

As standard.


Text

This run-time, read-only parameter returns the item of the currently selected item. If no item is selected it returns an empty string.

Example:

a$ = SBList1.Text


TextLeft

This property specifies the number of pixels between the left border and the start of text. If set to -1 then the text starts 2 pixels to the right of the picture, or 2 pixels right of the border if no picture is set. The default is -1.


TextTop

This property specifies the number of pixels between the top of a list item and the top edge of the text. If is ignored if the CenterV property is set.


Top

As standard.


TopIndex

This run-time property sets or reads the index number of the top most visible item.

Examples:

SBList1.TopIndex = 23

b& = SBList1.TopIndex


Visible

As standard.


WhatsThisHelpID

As standard.


Width

As standard.


Text Formatting

Unlike a standard list box, each list box item in SBList may contain text comprised of different font styles and colors, and can be wrapped onto 2 or more lines within each item space. To change the attribute or color, embed an escape character followed by a single character which determines the style of the following text. These characters are:

B / b	Bold on/off

U / u	Underline on/off

I / i	Italic on/off

S / s	Strikethru on/off

0	Change color to ForeColor.

1 / 2 / 3 / 4	Change color to ForeColor1/2/3/4.

n	Throw a new line, equivalent to Chr$(10).

t	Tab character, equivalent to Chr$(9).

Example:

“Hello \2\UWorld” appears as “Hello World”.

If you need to display an escape character then enter 2 consecutive ones, for instance \\ displays as \.


Release notes

1.2	HighLeft property

IntegralHeight property

Border property

Ellipsis property

Double escape character displays one escape chr.

Added \n for new line & \t for tab

Bug fixes

1.1	MouseIcon and Mousepointer properties added.

Bug fixes

1.0	First release.

Known problems

Items can not be entered into a listbox until it has been loaded and made visible. If it is then made invisible, it will still operate correctly. If you need items loaded whilst not first displaying the control, then set its position to outside of the form.


 Registration

This version of SBList is shareware, and must be registered before it can be distributed with your applications. By registering you will automatically receive all later versions when they are released (see note below) , and get lifetime support for this product. The registered version will not display the message box when used in run-time, which the shareware version does occasionally to remind you to register.

The price for registering is 25 US dollars (or 15 GB pounds) per licence. One licence is required for each PC that will be using SBList in the development environment. Once registered, no further royalties are payable, and there are no restrictions on re-distribution.

Payment may be made either by check, international money order, bank transfer, or cash. I do accept currencies other than US dollars or GB pounds, please contact me for details. Checks or money orders should be made out in the currency of the bank branch printed on the check. Please contact me for details if you wish to pay by bank transfer.

Checks or international money orders should be made payable to Steve Bannister.

Payment should be sent to:

Steve Bannister

41 Milton Street

Northampton

NN2 7JG

England

Please specify if you prefer to receive the files by e-mail, post, or your FTP site.

If you have any queries or comments you may e-mail me at

s.bannister@pobox.com

(or s.bannister@open.ac.uk)

Note: You will receive all future releases of SBList only if you choose to receive the files by e-mail or FTP.

Source code for this OCX is available for purchase upon request.


Legal Notice

SBLIST OCX VERSION 1.2  1996 STEVE BANNISTER

THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  THE

AUTHOR DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING

THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DAMAGES WHATSOEVER

INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS

PROFITS OR SPECIAL DAMAGES, EVEN IF THE AUTHOR HAS BEEN ADVISED OF

THE POSSIBILITY OF SUCH DAMAGES.