                                MLISTBOX.VBX

MLISTBOX.VBX is a custom control for Microsoft Visual Basic which provides
support for extended- and multiple-selection listboxes as well as the
standard single-selection listboxes that are built into Visual Basic.

This product is (pseudo) shareware.  Information on distribution rights is
provided at the end of this file.

I welcome any comments, criticisms, suggestions, etc.  I can be reached
via e-mail at:

        warninm@prism.cs.orst.edu

Mike Warning
2/16/91


                          HOW TO USE CUSTOM CONTROLS

For those of you unfamiliar with using custom controls in Visual Basic, it is
really easy.  First, copy the file ending with .VBX to your windows
directory.  The start up Visual Basic and select 'Add File...' from the 
'File' menu.  Locate the custom control file (.VBX file) that you wish to
use and select it, then click 'OK'.  The icon representing the custom control
should appear in the toolbox window and may be used just like any of the
standard controls.  If you then save your project, the custom control will
be reloaded automatically the next time you open your project.


                                  REFERENCE

Since I have made every effort to preserve the functionality of the original
single-selection listbox in my version, I will only address those properties
that are new or that I have expanded.  For information on the standard
properties not covered here, refer to the Visual Basic documentation.

Note that when I refer to 'multiple-selection listboxes' below, I really
mean 'multiple- or extended-selection listboxes'.


Empty -
    When reading this property, a TRUE will be returned if the listbox is    
    empty, otherwise a FALSE will be returned.  Writing any value to this
    property will force the listbox to reset, discarding any items that
    it contains.

    Example:
        ...
        mlistbox1.Empty = TRUE          ' Clear listbox
        ...


FindString -
    This property is used to find strings in a listbox.  When this property
    is set, the 'FindIndex' property may then be checked to find the index
    of the first string in the listbox matching the FindString.  After
    a string is found, this property will reset to the value of the string
    in the listbox.

    FindString will reset to null ("") if there is no string in the listbox
    matching the value that you gave it.

    Example:                            
        ...
        mlistbox1.FindString = "J"      ' Find an item beginning with "J"
        If mlistbox1.FindString = "John" Then
        ...

    See Also:
        FindIndex


FindIndex -
    This property hold the index of the string found using FindString.  It
    will be set to -1 if there is no matching string.

    Example:
        ...
        mlistbox1.FindString = "J"      ' Find an item beginning with "J"
        If mlistbox1.FindIndex = -1 then        ' There isn't any
        ...

    See Also:
        FindString


hWnd -
    This property is the window handle associated with the listbox and is
    exactly like the 'hWnd' property that forms have.  This function is
    useful when a window handle must be passed to a Windows API function
    or other DLL function.

    Example:
        ...
        word = GetWindowWord(mlistbox1.hWnd, GWW_ID)
        ...


ItemData -
    This property associates a long-integer value with an item in the 
    listbox.  For example, if you have a listbox containing names, you could
    put there ages (or whatever) in the ItemData for a particular item.

    This property is similar to the standard 'Tag' property, except that
    it is numeric, and each item in the control can have it's own data.

    Example:
        ...
        mlistbox.ItemData(3) = 34
        ...


ListIndex -
    For single-selection listboxes, ListIndex returns the index of the 
    currently selected item.  For multiple-selection listboxes, ListIndex
    returns the index of the last item that the user clicked on, the
    'Selected' property may then be used to find out if that item is 
    currently selected or not.

    If there is no current selection, single-selection listboxes will
    return -1.  If no selection has ever been made, multiple-selection
    listboxes will return 0.

    NOTE:  The Windows SDK says that this should not work for multiple-
    selection listboxes; however, it seems to work fine under Windows 3.0.
    Therefore, I cannot guarantee that this property will work correctly
    for multiple-selection listboxes under future versions of Windows.

    Example:
        ...
        If mlistbox1.ListIndex = -1 then     
        ...


SelCount -
    Returns the number of selected items in the listbox.

    Example:
        ...
        For i=1 to mlistbox1.SelCount - 1
        ...

    See Also:
        SelCount, Selected


Selected -
    When read, this property returns a TRUE if the item is selected, 
    otherwise a FALSE is returned.

    When writing, this property may be used to select (or deselect) an
    item in the listbox.  For single-selection listboxes, if another item
    is currently selected, the selection will change to a new item.  Also,
    an item cannot be deselected in a single-selection listbox using this
    property (use ListIndex instead).

    Example:
        ...
        for i=0 to mlistbox1.SelCount - 1
            mlistbox1.Selected =  TRUE          ' select every item
        next
        ...

    See Also:
        SelCount, SelList, ListIndex


SelList -
    The property is an array that contains the indexes of the currently
    selected items in the listbox.  The first selected item is SelList(0), 
    etc.

    Example:
        ...
        For i=0 to mlistbox1.SelCount - 1
            if mlistbox1.list(mlistbox1.SelList(i)) = "John" then
        ...

    See Also:
        SelCount, Selected


Style -
    This property sets the style of the listbox (single-, extended-, or
    multiple-selection).

    Style = 0: single-selection.  This type of listbox may only have one
               item selected at a time.
    Style = 1: extended-selection.  This type of listbox may have more than
               one item selected.  The user must hold down the 'CTRL' or
               'SHIFT' keys while clicking the mouse to select more than
               one item
    Style = 2: multiple-selection.  This type of listbox may have more than
               one item selected.  The user does not need to hold down any
               keys while selecting items.

    You should probably set the Style property at design time.  While you
    may change the Style at run-time, doing so clears out the contents of
    the listbox.

    Example:
        CONST EXTENDED_SELECTION = 1
        ...
        mlistbox1.Style = EXTENDED_SELECTION
        ...


Text -
    For single-selection listboxes, Text returns the currently selected item
    in the listbox.  For multiple-selection listboxes the item that was most
    recently clicked is returned, you can then use the 'Selected', and 
    'ListIndex' properties to determine if the item is selected or not.

    NOTE:  The Windows SDK says that this should not work for multiple-
    selection listboxes; however, it seems to work fine under Windows 3.0.
    Therefore, I cannot guarantee that this property will work correctly
    for multiple-selection listboxes under future versions of Windows.

    Example: 
        ...
        if (mlistbox1.text = "John") then
        ...

    See Also:
        ListIndex, Selected


TopIndex -
    Sets the index of the item that is at the top of the listbox.   If you
    try to set the top index to an item number less than 0, the listbox
    will start from item 0.  If you try to use an index that is to high
    the listbox will not change.

    Example:
        ...
        mlistbox1.TopIndex = mlistbox1.TopIndex + 1     ' Scroll by one line
        ...


                                PROPERTIES                                
                                
This is a comprehensive list of all properties supported by the control:

    CtlName     Index       BackColor   ForeColor   Left
    Top         Width       Height      MousePointer
    TabIndex    TabStop     DragIcon    DragMode    Enabled
    Parent      Tag         Visible     FontName    FontBold
    FontItalic  FontStrikethru          FontSize    FontUnder
    ListCount   SelCount    ListIndex   TopIndex    List
    Empty       SelList     Style       Text        Sorted
    Selected    FindString  FindIndex   ItemData    hWnd

                                  EVENTS

    Click       DblClick    DragDrop    DragOver    GotFocus
    KeyDown     KeyPress    KeyUp       LostFocus   MouseDown
    MouseMove   MouseUp

                                 METHODS

    AddItem     RemoveItem  Refresh     Load        Unload


                            DISTRIBUTION RIGHTS

You are free to distribute this product separately from a product of your
own, as long as you distribute both this file, and the custom control file
(MLISTBOX.VBX).

If you wish to use this product in one of your own products, your rights
depend on what sort of product it is:

Public Domain:  i.e. not for profit, you ask no monetary fee for someone
to use your product.  In this case, you are free to distribute this control
as much as you wish.

Shareware:  i.e. requesting that the user send you some money if they 
like/use your product.  In this case, please send me a postcard of your
home town or some feature thereabouts.

Commercial:  i.e. for profit.  In this case, please contact me (see below),
and we can arrange some mutually beneficial agreement.


I may be reached either through e-mail at:

    warninm@prism.cs.orst.edu

or through regular mail at:

    Mike Warning
    6015 202nd St. S.W. #14
    Lynnwood, WA 98036

If you wish a prompt reply, please use e-mail.  I do not actually live at
the mailing address above, and it may take weeks/months to get anything to
me that is sent there.

