ImageCombo class

An ImageCombo is a combo box whose items can each show a picture, and be indented, so that the list can show a folder tree or a list of files with their icons. The pictures come from an ImageList control.

An image combo box in which the folder Letters is selected, with the picture of a folder beside its name
ImageList1.ListImages.Add , "red", ColorSquare(vbRed)
ImageList1.ListImages.Add , "blue", ColorSquare(vbBlue)
ImageCombo1.ImageList = ImageList1
ImageCombo1.ComboItems.Add , "r", "Red", "red"
ImageCombo1.ComboItems.Add , "b", "Blue", "blue"
ImageCombo1.ComboItems("b").Selected = True
Debug.Print ImageCombo1.Text; ImageCombo1.ComboItems.Count
' Output:
' Blue 2

ColorSquare in the samples of this page is a function of the program’s own that returns a bitmap of one color, 16 pixels wide and high.

The control stands in place of the ImageCombo of the Microsoft common controls (MSCOMCTL.OCX). It is made of the combo box with pictures that Windows provides. It differs from ComboBoxW in its items: they are objects in the ComboItems collection, each with a picture, an indentation and a number of its own, and not the texts that AddItem adds.

Of the common members, the control has every member under Name and place, Window handles, Font and visual styles, Mouse, Keyboard and focus, Dragging the control, OLE drag and drop and Right-to-left. Its Click and DblClick have a meaning of their own, and its mouse events give the position in twips.

Its sub-objects have pages of their own:

The styles

Style is set at design time and decides what the control is made of:

Style The control
ImcStyleDropDownCombo A text box with an arrow button. The list drops down when the user presses the button. The user types any text or picks an item.
ImcStyleSimpleCombo A text box with the list always open below it. The user types any text or picks an item.
ImcStyleDropDownList A field that shows the selected item, with an arrow button. The user picks an item and cannot type a text of their own.

The first two have a text box, whose window is hWndEdit. The members that work on the text box, such as SelStart and MaxLength, do nothing useful on an ImcStyleDropDownList control, which has none.

A new control has the style ImcStyleDropDownCombo, no image list and no item, and shows its own name as its text.

The pictures

The control takes its pictures from an ImageList control, which a program assigns to ImageList. The list must hold pictures at the time of the assignment: the combo box then shares the image list of Windows that the ImageList control holds, so a picture added later is shown as well. Giving the list to a control has the rules about an empty list.

Each item names its picture by its number in the ImageList, from 1, or by its key. ImcComboItem.Image is the picture the item shows, and ImcComboItem.SelImage the picture it shows while it is the selected item, in the text box and in the list. A number of 0 means no picture, and for SelImage the picture of Image.

How the control finds a picture by its key depends on what the program assigned to ImageList. With the ImageList control itself, or with its name, the control asks that list. With the handle that hImageList returns, there is no list to ask, so an item then names its pictures by number only:

ImageList1.ListImages.Add , "red", ColorSquare(vbRed)
ImageList1.ListImages.Add , "blue", ColorSquare(vbBlue)
ImageCombo1.ImageList = ImageList1.hImageList
ImageCombo1.ComboItems.Add , , "Blue", 2           ' a number: fine
On Error Resume Next
ImageCombo1.ComboItems.Add , , "Red", "red"        ' a key: no list to look it up in
Debug.Print Err.Number
' Output:
'  35601

Where the ImageCombo and the ImageList are on the same form, a program can also assign the name of the ImageList as a string:

ImageCombo1.ImageList = "ImageList1"

ShowImages turns the pictures off, and AllowImageHighlight decides whether the picture of the selected item is drawn highlighted. The height of an item in the list is at least the height of the pictures of the list, which GetItemHeight returns.

The items

ComboItems returns the collection of the items. Its Add method puts an item into the list with its text, its key, its pictures and its indentation, and the items are numbered from 1 in the order of the list. Indentation is the indentation that a new item gets, in widths of a picture, so that a list can show levels as a tree does.

Dim Item As ImcComboItem
With ImageCombo1
    .ComboItems.Add , "root", "Documents"
    .Indentation = 1                                  ' for the items added from here on
    .ComboItems.Add , "a", "Letters"
    .ComboItems.Add , "b", "Notes"
    .ComboItems.Add , "c", "Todo", , , 2              ' an indentation of its own
    For Each Item In .ComboItems
        Debug.Print Item.Index; Item.Key; Item.Indentation
    Next
End With
' Output:
'  1 root 0
'  2 a 1
'  3 b 1
'  4 c 2

A program removes an item with Remove and all items with Clear.

The selection and the text

SelectedItem is the selected item, or Nothing. Text is the text in the text box. The two are separate: selecting an item puts its text into the text box, but a text assigned to Text selects no item, even when an item has that text.

With ImageCombo1
    .ComboItems.Add , "a", "Alpha"
    .ComboItems.Add , "b", "Beta"
    .Text = "Beta"
    Debug.Print TypeName(.SelectedItem)
    .ComboItems("b").Selected = True
    Debug.Print .SelectedItem.Key & " " & .Text
    .ComboItems.Clear
    Debug.Print "[" & .Text & "] " & TypeName(.SelectedItem)
End With
' Output:
' Nothing
' b Beta
' [Beta] Nothing

Clear and Remove take the items out of the list and leave the text in the text box as it is.

Selecting an item, by the user or by Selected or SelectedItem, raises Change first, because the text box takes the item’s text, and then Click. Selecting the item that is selected already raises Change only. Assigning a text to Text raises Change. Removing the selection with Set .SelectedItem = Nothing raises Change and Click. A control with the style ImcStyleDropDownList has no text box and raises no Change.

Private Sub ImageCombo1_Click()
    ' Another item is selected.
    Debug.Print "item "; ImageCombo1.SelectedItem.Index
End Sub

Private Sub ImageCombo1_Change()
    ' The text in the text box is another text.
    Debug.Print "text is now "; ImageCombo1.Text
End Sub

FindItem returns the item that has a text, for a program that looks an item up by its text.

Ending the edit

The user edits the text box of an ImcStyleDropDownCombo control, or of an ImcStyleSimpleCombo control, in turns. BeginEdit is raised when the user starts one by clicking in the text box or moving the focus into it. EndEdit is raised when the user finishes it: by pressing the Enter key or the Esc key, by moving the focus to another control, or by opening the drop-down list. The event says whether the text was changed, which item the user chose, if any, the text, and why the edit ended.

NewIndex counts the items from 0, as Windows does, so the item that ComboItems numbers 1 is 0 here, and NewIndex is -1 when the text is not that of an item. The drop-down list that opens raises DropDown, and then EndEdit with the reason ImcEndEditReasonDropDown.

Private Sub ImageCombo1_EndEdit(ByVal Changed As Boolean, ByVal NewIndex As Long, ByVal NewText As String, ByVal Reason As ImcEndEditReasonConstants)
    If Reason = ImcEndEditReasonReturn And Changed Then
        Debug.Print "the user typed "; NewText
    End If
End Sub

The drop-down list

DroppedDown says whether the list is open, and opens or closes it. The control raises DropDown before the list opens, which is the moment to fill a list that depends on something else, and CloseUp when it has closed.

An image combo box with its list dropped down: Documents, and indented under it the folders Letters and Reports and the files Holiday.jpg and Notes.txt, each with its picture. Letters is selected.

The list shows MaxDropDownItems items at most without scrolling, and is as wide as the control unless DropDownWidth is wider. TopItem is the item at the top of the list, and Scroll is raised when it changes.

Properties

AllowImageHighlight

Whether the picture of an item is drawn highlighted while the item is selected or has the focus. A member of ImcAllowImageHighlightConstants. Default: ImcAllowImageHighlightAlways. It decides for the text box and the list separately.

A value that is not a member raises run-time error 380.

BackColor

The background color of the text box and of the list. OLE_COLOR. A new control has vbWindowBackground.

ComboItems

The items of the control. An ImcComboItems collection, read-only.

The least width of the drop-down list, in the scale units of the control’s container. Single. The list is never narrower than the control. A negative value raises run-time error 380. On an ImcStyleSimpleCombo control, which has no drop-down list, the property raises run-time error 5.

DroppedDown

Whether the drop-down list is open. Boolean. An assignment opens or closes it. See The drop-down list.

EllipsisFormat

Whether a text that is wider than the control is shortened and ends in an ellipsis. A member of ImcEllipsisFormatConstants. Default: ImcEllipsisFormatNone. It has an effect when the program has visual styles.

A value that is not a member raises run-time error 380.

ExtendedUI

Whether the control uses the extended keyboard interface of the Windows combo box. Boolean. Default: False. With True the Down Arrow key opens the list, the F4 key does not, and the mouse wheel does not change the selection while the list is closed. It has no effect on an ImcStyleSimpleCombo control.

ForeColor

The color of the text in the text box and in the list. OLE_COLOR. A control newly drawn on a form has black.

hWndCombo

The handle of the combo box inside the control, which holds the text box and the list. LongPtr, read-only. hWnd is the handle of the control of Windows that holds the combo box and its pictures.

hWndEdit

The handle of the text box inside the control. LongPtr, read-only. It is 0 on an ImcStyleDropDownList control.

hWndList

The handle of the list. LongPtr, read-only.

IMEMode

The state of the Input Method Editor while the text box has the focus. A member of CCIMEModeConstants. Default: CCIMEModeNoControl. Another value raises run-time error 380.

ImageList

The image list that gives the items their pictures. Variant. Default: none. See The pictures.

An assignment takes the ImageList control, the name of an ImageList control on the same form as a String, or a handle, a Long or a LongPtr, such as hImageList returns. A name that no ImageList control of the form has, and an ImageList control with no picture, leave the control without an image list, with no error. An object that is not an ImageList raises run-time error 35610, and a value of another type raises 13.

Reading the property returns the ImageList control, when it was assigned as a control or by name, and the handle, when it was assigned as one. With none it returns Nothing.

Indentation

The indentation that an item gets when it is added without one, in widths of a picture of the image list. Long. Default: 0. Items already in the list keep theirs.

A negative value raises run-time error 380.

Locked

Whether the user is kept from changing the text and the selection. Boolean. Default: False.

With True the text box takes no typing, and the list does not respond to the keyboard or to the mouse on its items. The program can still assign Text and select items.

MaxDropDownItems

The greatest number of items that the drop-down list shows without scrolling. Integer. Default: 9.

A value less than 1 or greater than 30 raises run-time error 380.

MaxLength

The greatest number of characters that the text box takes, from the user and from an assignment to Text. Long. Default: 0, with which the limit is 259 characters.

An assignment of a longer text loses what is beyond the limit. A negative value raises run-time error 380.

OLEDragMode

Whether the user can drag the selected item out of the control. A member of OLEDragConstants. Default: vbOLEDragManual, with which only OLEDrag starts a drag. With vbOLEDragAutomatic a drag of the picture in the text box, which raises ItemDrag, carries the text of the selected item as text, to copy or to move. Another value raises run-time error 380.

OLEDraggedItem

The item that an OLE drag started from ItemDrag carries. An ImcComboItem, read-only. It is Nothing while no such drag is going on. A handler of ItemDrag that calls OLEDrag can read it in OLEStartDrag and in the events after it.

ScrollTrack

Whether the list scrolls while the user drags the scroll box of its scroll bar. Boolean. Default: True. With False the list scrolls when the user releases the scroll box.

SelectedItem

The selected item. An ImcComboItem, or Nothing when no item is selected. An assignment with Set selects the item, and Set .SelectedItem = Nothing removes the selection. It raises Click when the selection changes. See The selection and the text.

SelLength

The number of characters selected in the text box. Long. A negative value raises run-time error 380. It does nothing on an ImcStyleDropDownList control.

SelStart

The position where the selection in the text box starts, counted from 0, or the position of the caret when nothing is selected. Long. An assignment puts the caret there and selects nothing. A negative value raises run-time error 380. It does nothing on an ImcStyleDropDownList control.

SelText

The selected text of the text box. String. An assignment replaces the selection, or inserts the text at the caret. On an ImcStyleDropDownList control the property raises run-time error 380.

ShowImages

Whether the text box and the list show the pictures of the items. Boolean. Default: True. With False neither the text box nor the list shows the pictures.

Style

What the control is made of. A member of ImcStyleConstants. Default: ImcStyleDropDownCombo. See The styles.

It is set at design time. At run time an assignment raises run-time error 382, and a value that is not a member raises 380.

Text

The text in the text box. String. It is the control’s default property. A control newly drawn on a form has its own name.

On an ImcStyleDropDownCombo or ImcStyleSimpleCombo control an assignment puts the text into the text box, cut to MaxLength, raises Change and selects no item.

On an ImcStyleDropDownList control the text is that of the selected item, and an empty string when none is selected. An assignment selects the first item that has this text, regardless of case, and a text that no item has raises run-time error 383.

TopItem

The item at the top of the list. An ImcComboItem. An assignment with Set scrolls the list so that the item is at its top, and raises Scroll when that changes the top item. Nothing raises run-time error 380.

Reading the property of a control with no item raises run-time error 9.

Methods

FindItem

Returns the first item that has a text, or Nothing when there is none. The search does not regard case.

Syntax: object.FindItem( Text [, Index [, Partial [, Wrap ] ] ] ) As ImcComboItem

Text
required A String: the text to look for.
Index
optional A Long: the number of the item where the search starts, which is the first item looked at. The default, 0, starts at the first item. A negative number, or one greater than the number of items in a list that has items, raises run-time error 380.
Partial
optional A Boolean: True finds an item whose text contains Text, False (the default) one whose whole text is Text.
Wrap
optional A Boolean: True goes on from the first item when the search reaches the end of the list without a match. The default is False.

An item with an empty text is never found. A call on a list with no item returns Nothing, whatever Index is.

GetItemHeight

Returns the height of an item in the drop-down list, in the scale units of the control’s container, as a Single. It is the height of the text, or the height of the pictures of the image list when they are higher.

Syntax: object.GetItemHeight

A picture 40 pixels high makes an item at least 40 pixels high.

Events

BeginEdit

Raised when the user starts to edit the text, by clicking in the text box or moving the focus into it. See Ending the edit.

Syntax: object_BeginEdit( )

Change

Raised when the text in the text box has changed: by the user’s typing, by an assignment to Text, by a change of the text of the selected item, and by the selection of an item or its removal, as The selection and the text says. An ImcStyleDropDownList control has no text box and does not raise it.

Syntax: object_Change( )

Click

Raised when another item has been selected, or the selection has been removed: by the user, with the mouse or the keyboard, or by Selected or SelectedItem.

Syntax: object_Click( )

CloseUp

Raised when the drop-down list has closed.

Syntax: object_CloseUp( )

DblClick

Raised when the user double-clicks an item in the list of an ImcStyleSimpleCombo control. The other styles do not raise it.

Syntax: object_DblClick( )

Raised when the drop-down list is about to open.

Syntax: object_DropDown( )

EndEdit

Raised when the user has finished editing the text. See Ending the edit.

Syntax: object_EndEdit( Changed As Boolean, NewIndex As Long, NewText As String, Reason As ImcEndEditReasonConstants )

Changed
True when the user has changed the text.
NewIndex
The item the user chose, counted from 0, or -1 when the text is not that of an item.
NewText
The text in the text box.
Reason
Why the edit ended, a member of ImcEndEditReasonConstants.

ItemDrag

Raised when the user starts to drag the picture of the selected item in the text box, holding the left or the right mouse button. With OLEDragMode set to vbOLEDragAutomatic the control also starts an OLE drag for a drag with the left button.

Syntax: object_ItemDrag( ByVal Item As ImcComboItem, ByVal Button As Integer )

Item
The selected item.
Button
vbLeftButton or vbRightButton, members of MouseButtonConstants.

MouseDown, MouseMove, MouseUp

As the common events of these names, but X and Y are in twips, whatever the scale units of the control’s container, and are measured from the top left corner of the control.

Scroll

Raised when the list has scrolled, so that another item is at its top.

Syntax: object_Scroll( )

ImcStyleConstants

The values of Style.

Three image combos with the folder items, Letters selected: ImcStyleDropDownCombo is a box with Letters and its folder picture and a button with an arrow, ImcStyleSimpleCombo is a box with the text Letters over its open list, in which Letters is highlighted, and ImcStyleDropDownList is a gray box with Letters and its picture and the arrow button
Member Value Description
ImcStyleDropDownCombo 0 A text box and a list that drops down.
ImcStyleSimpleCombo 1 A text box and a list that is always open.
ImcStyleDropDownList 2 A list that drops down, and no text box.

ImcEndEditReasonConstants

The values of the Reason argument of EndEdit.

Member Value Description
ImcEndEditReasonLostFocus 1 The focus moved to another control.
ImcEndEditReasonReturn 2 The user pressed the Enter key.
ImcEndEditReasonEscape 3 The user pressed the Esc key.
ImcEndEditReasonDropDown 4 The drop-down list opened.

ImcEllipsisFormatConstants

The values of EllipsisFormat.

Member Value Description
ImcEllipsisFormatNone 0 A text that is too wide is cut at the edge.
ImcEllipsisFormatEnd 1 A text that is too wide ends in an ellipsis.

ImcAllowImageHighlightConstants

The values of AllowImageHighlight.

Member Value Description
ImcAllowImageHighlightAlways 0 The picture is highlighted in the text box and in the list.
ImcAllowImageHighlightNever 1 The picture is never highlighted.
ImcAllowImageHighlightListOnly 2 The picture is highlighted in the list only.
ImcAllowImageHighlightComboOnly 3 The picture is highlighted in the text box only.

See Also