Monster Media 1994 #1/monster.zip/monster/PROG_BAS/MLIST.ZIP/READ.ME

Text File | 1994-02-06 | 26KB | 683 lines

***************************************************************************
*
*  McKean Consulting
*  Robin W. McKean
*  1042 Braddock Circle
*  Woodstock GA  30188
*
*  MLIST.VBX    V4.20.0000
*
*  Multi-Purpose List Box Control for Visual Basic 3.0
*
***************************************************************************

MLIST is a custom control for managing the way your data appears in a list
box.  MLIST is a property for property replacement of the standard List Box
control which comes with Visual Basic 3.0.  In addition, there are many more
features which MLIST can do that you can't do with the normal List Box.  Some
of these features are:

    * Set up owner draw columnar data in the list box.  This is NOT a
      MULTI-COLUMN list box.  MLIST now has this feature, but the MLIST
      List Box scrolls vertically, like a normal list box.  Your data is
      arranged in columns, with specific drawing flags setup for each
      "Drawing Region".  Think of each line as being broken up into
      different areas, each with its own drawing flags and data.

    * Make a drawing region a bitmap or a checkbox.  You have control
      over the entire list's bitmaps through the default bitmap property,
      or you can set individual lines bitmap properties.

    * Control individual line colors in the list box

    * Total control over the checked and unchecked states of lines

    * Now MLIST has aligned bitmaps as well.  You specifiy the bitmap,
      the text, and the alignment (top, bottom, right, left), and MLIST
      will draw the text and the bitmap in the area you define.

    * New in verions 4.00.  You can now have true MUTLIPLE COLUMN list
      boxes, with bitmaps and check boxes.  Multiple columns are set
      up through setting the LBS_MULTICOLUMN style for the list box.
      You control the width of each item.  This attribute differs in
      that each line has a certain width.  So it may take two or more
      columns of items to actually fill a line

    * Checking and Selecting a range of line items

    * Properties to find closest match and find exact matches in the
      list box.

    * Complete control over colors in the list box.  Colors can be
      set for normal lines, individual lines, normal highlight colors,
      and individual highlight colors.

    * MList V4.10 now has 3-D effects

    * You can now setup vertical and horizontal grids

    * Virtual List Boxes.  A notification event is sent when more data
      is required by the application.

***************************************************************************

This ZIP file contains:

    MLIST.VBX         VB version of the MLIST custom control
    PROJECT1.MAK    Sample project file for MLIST
    FORM1.FRM        Form used by the sample project
    READ.ME            This file
    PLUS.BMP        Bitmap used in example
    PAGE.BMP        Ditto

    FINDSTR.MAK        FindString and FindStringExact Demo
    FIND1.FRM        Form for FindString Demo

    VIRTUAL.MAK        Virtual List Box example
    VIRTUAL.FRM        Form for virtual list box

***************************************************************************

REGISTRATION

Time for the sob story.  This Multi-Column List Box is Shareware.  It is
NOT crippled in anyway.  When you download this custom control, you have
the same custom control that I am using in my everyday VB programming.
As a Shareware contributor, I am counting on the honor and moral fiber of
every person who downloads this custom control to do the right thing.  I
have contributed and participated in the Shareware arena for years now.
Your small contribution can make a difference to me and my family...

Right now, the maximum string size in the List Box is 255 characters.  Let me
know if this causes a problem.  I don't anticipate anyone needing to display
more than this number of characters to the screen.

If you like and appreciate this custom control...

  1)  Small time developers like me, send $10.00 to the address listed above
  2)  Corporate users send $15.00 to the address listed above
  3)  Register in the Compuserve SWREG forum ID 1585

Registered users may purchase the source...

  Send $35.00 to me at the above address.

  This control is written in C++ and has been compiled using both
  Borland C++ 3.1 and Visual C++ 1.5.

You may now register this control in the SWREG on Compuserve.  Type GO SWREG.
If you want the source, you will still have to write me...

Corporate users should register via mail or register twice in the SWREG
Forum, as many of you have already done.

***************************************************************************

WARRANTY

The control, as is, works the way that I want it to.  This does not mean
that it will work the way that you want it to.   Along those lines, I
totally disclaim that the control will do anything whatsoever.  This
includes any implied abilities and any WARRANTIES, including those for
SUITABILITY for a particular purpose, MERCHANTIBILITY, and all that other
bull crap.

***************************************************************************

PROGRAMMER'S NOTES (or, what I need to know to use this custom control)

The Multi-Column List Box is an enhanced List Box control.  The following
is a desciption of each additional control.  What it does, and how to
use it in your own VB programming.  For additional control properties, see
those for properties included in the standard list box control.  MLIST now
contains all standard controls.  The ones listed below are additions.

ItemHeight

This property is responsible for controlling the height of each individual
line item in the list box.  It defaults to 195 Twips, the height of the
font used by the standard list box.  You should adjust this height if you
change the font, font size, etc..

I'm not sure whether or not this property will change the height of the lines
after the list box has already been created.  I did not design the list box
control to have the height of the items change dynamically.  Set the height
of this item at design time, and the font, and your list box will be fine.
Experiment with this during run-time if you like, and let me know how it
works out, and how I can make this item work more to your liking.

DrawRegions

This item determines the number of drawing regions on each line.  This is
basically equivelent to the number of COLUMNS, but this list box will still
scroll like a normal list box.  When setting this property, the control
clears the flags for the draw regions and sets them to left aligned, single
line, and centered vertically.  Consult the Windows API for DrawText to
see what exactly these flags mean.

ItemLength

This is an indexed property which corresponds to the length of each drawing
region.  If you want a drawing region to be a specific length, set that
drawing region's length to the desired setting in twips.  For example...

    MList1.DrawRegions = 2
    MList.ItemLength(1) = 500
    MList.ItemLength(2) = 500

    ' Generates an out of index error
    MList1.ItemLength(0) = XXX
    MList1.ItemLength(3) = XXX

It is probably a good idea to set the lengths of all drawing regions when you
are changing the defaults.

DrawFlags

This is an indexed property which corresponds to the flags of each drawing
region.  If you want a drawing region to be drawn in a specific manner, set
that drawing region's flags to the desired settings.  For specific flags,
look up the DrawText API function in the Windows API Reference.  In the
following example, I setup two drawing regions and set the second drawing
region's flags to right justify the text.  In this example, the second
drawing region displays currency values.

    Const DT_RIGHT = 2
    Const DT_VCENTER = 4
    Const DT_SINGLELINE = 32

    MList1.DrawRegions = 2
    MList1.DrawFlags(2) = DT_RIGHT + DT_VCENTER + DT_SINGLELINE
    MList.ItemLength(1) = 500
    MList.ItemLength(2) = 500

If you are planning to include the '&' character in your strings, you
should include the DT_NOPREFIX flag to avoid the underline.  I do NOT
automatically add this flag for you, as I want you to have total control
over the flags.

ActiveRegion

Setting this property affects the next two properties.  It defines the
DrawingRegion (or index or column) that TextRegion and ListRegion will
return.  Perhaps an example is in order.

My list box is divided up into three columns, name, account number, dollar
amount.  I want to get the account number for the currently selected line
as well as the first item...

    MList1.ActiveRegion = 2
    aString$ = MList1.TextRegion    ' Gets 2nd column of current text
    bString$ = MList1.ListRegion(0)    ' 2nd column of item at index 0

TextRegion

This property will return the ActiveRegion in the currently selected text.
See the above "ActiveRegion".  Corresponds to a DrawRegion of the Text property.
These values can also be written to at run time.

ListRegion

This property will return the ActiveRegion in the item at the specific index.
See the above "ActiveRegion".  Corresponds to a DrawRegion of the List property.
These values can also be written to at run time.

DefPicture

This is the default bitmap to be displayed in the ImageRegion when a specific
bitmap has not been assigned to that items ItemPicture property.  Please see
the demo on setting your own default picture and ItemPicture properties.

ImageType

This determines what type of image we are dealing with in our image region.
If this property is set to 0, then the ImageRegion property is ignored and
only text is dislayed.  If this image type is valid, then a checkbox or
bitmap is displayed in the ImageRegion.

Note that when the image type is set to AlignBitmap, the normal drawing
regions no longer apply.  Anybody got a problem with that???

ImageRegion

This property specifies which region contains the image region.  This value
should be any number between 1 and the number of DrawRegions.  You may not
set this property to a value of less than zero or greater then DrawRegions.
When setting up your DrawRegions, the following is a good example:

    MList1.DrawRegions = 3
    MList1.ImageRegion = 1

    MList1.ItemLength(1) = 100        ' Bitmap is in here
    MList1.ItemLength(2) = 500
    MList1.ItemLength(3) = 750

    ' Don't leave a space for the ImageRegion in your strings
    MList1.AddItem "Region2" + Chr$(9) + "Region3"
    MList1.AddItem "Region22" + Chr$(9) + "Region33"

The ImageRegion is ignored when calculating the "piece" of text that goes in
that region.

Checked

This property is very similar to the Selected property.  In a Multi-Column
list box with the ImageType set 2 (CheckBox), this property will return to
you whether or not that line item is checked or not.  For example:

    For X% = 0 To MList1.ListCount - 1

        If MList1.Checked(X%) Then
            Debug.Print "I am Checked! "; X%
        Else
            Debug.Print "I am not checked! "; X%
        End If
    Next X%

    ' Check the first item
    MList1.Checked(0) = True

ItemPicture

This property is an array of pictures which correspond to the bitmaps for
each line item in the list box.  If this item is not set by you, then
the MList uses the DefPicture property.

    ' Change the first items picture in the list box
    MList1.ItemPicture(0) = Image1.Picture

ItemForeColor

This property is an array of color which correspond to the foreground color
for each line item in the list box.  If this item is not set by you, then
the MList uses the default foreground color property.

    ' Change the first items foreground color to white
    MList1.ItemForeColor(0) = RGB(255,255,255)

ItemBkColor

This property is an array of color which correspond to the background color
for each line item in the list box.  If this item is not set by you, then
the MList uses the default background color property.

    ' Change the first items background color to black
    MList1.ItemBkColor(0) = RGB(0,0,0)

Alignment

This property controls the placement of the bitmap when the image type is
set to 4, AlignBitmap.  See the demo for details, but basically the values
for this property are:

1 - Align the bitmap to the left, centered, then the text, centered
    vertically and left justified.
2 -    Align the bitmap on top, centered, then the text, centered
    horizontally and vertically.
3 - Align the bitmap to the right, centered, then the text, centered
    vertically and left justified.
4 -    Align the bitmap on bottom, centered, then the text, centered
    horizontally and vertically.

Note that when the image type is set to AlignBitmap, the normal drawing
regions no longer apply.  Anybody got a problem with that???

MultiColumn

This turns the list box into a true multiple column list box.  The list box
will scroll horizontal instead of vertical.  A default item width is provided,
but you, the developer, should override this property.  This property should
be set to true for multi-column, or false (the default) for normal list box
behavior.

ItemWidth

The property specifies the width of each line in a multiple column list box.
The width is set in Twips.  The normal drawing regions still apply, but I
can't think of a reason why someone would want to divide line items in a
column list box into more columns.

FindString

Setting this property will cause the list box to search for a string with
the closest match from the current ListIndex.  If one is found, that string
is set to the current ListIndex.  This is useful for moving items through
a list box while typing the string in an edit control, ie.  Search in Help.

FindStringExact

This property is the same as above, except that it will search for an exact
match.

RangeStart

This property marks the beginning line item for RangeSelected or RangeChecked.
The offset is 0 based, so the first item is 0.

RangeEnd

This property marks the ending line item for RangeSelected or RangeChecked.

RangeSelected

All items in the range RangeStart to RangeEnd are marked as selected in the
list box.  If the list box is not multi-select, then this is ignored.

    MList1.RangeStart = 0
    MList1.RangeEnd = 3
    MList1.RangeSelected = True

RangeChecked

All items in the range RangeStart to RangeEnd are marked as checked in the
list box.

    MList1.RangeStart = 0
    MList1.RangeEnd = 3
    MList1.RangeChecked = False

SetHzScroll

When all is said and done, and you are through setting up your list box, and
your columns extend past the displayable area of the list box, setting this
property to True will cause the MLIST control to add up all of the drawing
regions and add a horizontal scroll bar to the list box if one is neccessary.


HiliteForeColor,

This is the default foreground color to use when a line in the list box is
hilited.  If these colors are set, then the normal colors are ignored, and
the HiliteForeColor is used to draw the text, and HiliteBackColor is used
to draw the background.

You may force MList to use the default colors by setting this color equal
HiliteBackColor.

HiliteBackColor,

This is the default background color to use when a line in the list box is
hilited.  If these colors are set, then the normal colors are ignored, and
the HiliteForeColor is used to draw the text, and HiliteBackColor is used
to draw the background.

You may force MList to use the default colors by setting this color equal
HiliteForeColor.

ItemHiliteForeColor,

This is a property array, which corresponds to each line item in the list box.
Using this property, you can set the foreground and background hilited color
of individual line items.

    MList1.ItemHiliteForeColor(0) = RGB(0,0,0)
    MList1.ItemHiliteBackColor(0) = RGB(255,255,255)

ItemHiliteBackColor,

This is a property array, which corresponds to each line item in the list box.
Using this property, you can set the foreground and background hilited color
of individual line items.

    MList1.ItemHiliteForeColor(0) = RGB(0,0,0)
    MList1.ItemHiliteBackColor(0) = RGB(255,255,255)

MaskingColor

This color is used to mask out colors in your bitmaps when they are included
in your MList Box.  For example, lets say that you know you are not going
to use the color white in your bitmaps or list boxes, so, you can set all the
pixels in your bitmap, which you want to be transparent to white, and the
natural color of the list box will show through your bitmap wherever the color
white is.  Think of this as the transparent color, like in Icons, except you
get to determine what it is.

HorizontalGrids

Set this property to true, if you want to allow horizontal grid lines to be
drawn on your list box.

VerticalGrids

Set this property to true, if you want to allow vertical grid lines to be
drawn on your list box.

GridStyle

This determines what line style is used to draw the grid lines.  This didn't
quite turn out the way I wanted, but experiment if you like, and give me
some suggestions.

BorderStyle

This property controls the border style of the list box.  Valid values are normal,
raised, and inset.

RiseColor

This is the color of the rising edge of a 3-D list box.  Default color is white.

FallColor

This is the color of the falling edge of the 3-D list box.  The default color
is a dark grey color.

Version

This property was included by me to insure backwards compatibility.  You don't
need to be concerned with its use, as I use it for different things.

ExtendedSelect

This property will allow multiple select list boxes to be accessed via
extended selection.  This causes the listbox to be created with the
LBS_EXENDEDSEL style.  See the MS-Windows SDK help for more on extended
select.

GridColor

This property determines the color of the horizontal and vertical grids.
The default color is black.  I prefer light grey.

FindDirection

This property now determines which direction a FindString and
FindStringExact will search the list.  If set to 0, the search will
begin at the currently active ListIndex and search to the bottom of
the list.  If set to one, MList will begin at the current ListIndex
and search to the top of the list.

EnableVirtualMsgs

This property enables virtual messages.  Setting this property to True
causes a message to be sent to the VirtualMessage event whenever the
user approaches the beginning or end of the list.  These messages are
sent whether caused by a mouse or keyboard event.  See VirtualMessage
event for details.

VirtualMsgZone

This property determines when a virtual message event is sent.  This
property indicates then "zone" at the beggining and end of the list
that triggers the event.  For example, setting this property to 100,
would cause a VIRTUAL_END event to be sent to VirtualMessage when the
user got within a 100 lines of the end of the list box, and a
VIRTUAL_BEGIN event when the user gets within 100 lines of the begging
of the list box.  The event is only triggered if the user is heading
towards the respective end of the list box.

CheckStyle

This property deterines the type of "checkbox" displayed by a checkbox
style MList.  When this property is set to 0, the normal "cross/diagonal"
check box is used.  When set to one, a check mark is placed in the box
instead.

CheckColor

This property determines the color of the check mark.

***************************************************************************

New Events

SelChange()

This event is called whenever a selection in the list box is changed
either through the keyboard or the mouse.  You might want to use the
event instead of or in addition to the Click method if you want to
respond to selection changes when the user use the arrow keys instead
of the mouse.

SelCheck(Index As Integer, State As Integer)

This event is called whenever the checked status of a line in the list
box is changed.  The first parameter to this event is the Index
(line item) that has been effected.  The second parameter is the state
of the checked box.  It is either True or False.

VirtualMessage(Message As Integer)

This is my first attempt at a virtual list box, so please don't laugh.
I am basically providing the means by which to notify you when more
data is needed.  For now, you will have to keep track of your own data.

The following Message(s) are sent to this event:


    VIRTUAL_UP  - This should be defined as having a value of (1).  This
    message will be sent when you need to add items to the end of the
    list, because it is scrolling up.

    VIRTUAL_DOWN - This should be defined as having a value of (2).  This
    message will be sent when you need to add items to the beginning of
    the list, because it is scrolling down.

    VIRTUAL_END    - This is sent when the user is moving to the end of the
    list.  You should load whatever number of lines you need to, then
    MList will position ListIndex to the end of the list.  This item should
    be defined as (3).

    VIRTUAL_HOME - This is sent when the user is moving to the beginning of
    the list.  You should load whatever number of lines you need to, then
    MList will position ListIndex to the start of the list.  This item should
    be defined as (4).

MList will move the current ListIndex as Items are added to and removed from
the list.  You should try to cache all the items you will load in memory, then
add them to the list at one time.  Save off TopIndex and ListIndex, so that
you can restore them.  You will need to subtract or add the number of new
items loaded (and removed) depending on which direction you are moving in.
See the example for details.

There are no properties like VirtualListIndex, VirtualTopIndex, VirtualCount,
etc.  I am thinking hard about these, and hope to come up with an elegant
solution.  Any suggestions???

I guess what I have done is provide virtual capabilities while leaving most
of the implementation in your court.

***************************************************************************

FORMATTING STRINGS

You should place the Tab character between each column in your string.  The
following example formats a string for the DrawFlags example:

    MList1.AddItem "Robin W. McKean" + Chr$(9) + "$100.00"

The following string is for three columns:

    MList1.AddItem "Robin W. McKean"+Chr$(9)+"$100.00"+Chr$(9)+"True"

Remember, you do NOT have to include a column for the ImageRegion.  If
the ImageRegion property was 1 and the DrawRegions property was 3, then
the following line would work fine (3-1=2)

    MList1.AddItem "Robin W. McKean"+Chr$(9)+"$100.00"

***************************************************************************

REACHING THE AUTHOR

I can be reached via U.S. Mail at the address listed above.  You can reach
me via E-Mail at the following locations...

Compuserve:            Robin W. McKean
                    72622,1403

Shareware South:    Robin W. McKean
                    Atlanta, GA

I'm on CompuServe once or twice a day.  I check Shareware South about once
a week.

***************************************************************************

REVISION HISTORY

3.00.0000    Initial release of the MLIST.VBX Custom Control
3.01.0000    Fixed "Bad Index" error message when setting Selected
            property to True|False.
            Added ItemData property to control.
            Added ListIndex property to control.
            Fixed an apparent bug in the VB API that was passing right
            mouse button clicks to the Click event, but not the left
            mouse button.
3.02.0000    Fixed a ton of problems.  Namely, the page down didn't work.
            Delete current controls and rebuild to fix this problem.
            Added ALL default controls for the standard list box.
            Tested all of them before uploading.
3.03.0000    Fixed the index problem with the List property.  If anything,
            I am guilty of being over enthusiastic.  I apologize to those
            who got the previous version and thought it sucked.  Probably
            because it did.  I added bitmaps and checkboxes as well as
            the ability to change the color of a specific line.  You can
            also change the bitmap of a specific line item.
3.04.0000    Fixed the bug with setting the Checked property, and then not
            having the user be able to double click it or click the box
            to change it back.  Added the AlignBitmap image type and
            the Alignment property.
4.00.0000    Added the Multicolumn property and item width.  Added the
            FindString and FindStringExact properties for searching
            the list box.  Added the range properties for checking
            and selecting multiple line items.
4.01.0000    Removed the 64k limit.  MLIST will now allow more than 64k
            worth of data to be added to it.  Also, quit handling default
            methods, such as Move (which didn't work), Refresh, and others.
            Fixed problem with RemoveItem not deleting lines data.
            Changing the way MLIST handled strings did the job.
4.02.0000    Removed a bug which caused a GP fault when more than 16 drawing
            regions were requested by the user.  Reworked VB2.0 compatibility
            strategy.
4.10.0000    Added 3-D, rise and fall colors, and SelChange event.
4.11.0000    Hilighted lines will default to the system colors as controlled
            by the control panel.  User may still override useing the
            HiliteForeColor and HiliteBackColor.  Added the ExtendedSelect
            property.
4.20.0000    Tightened up the difference between a multi-select list box
            and a normal list box.  I added grid color, virtual messages,
            check marks in check boxes, SelChange events when ListIndex is
            changed, SelCheck for when an item is checked/unchecked.

***************************************************************************

ACKNOWLEDGEMENTS

I would like to thank Simon, Kevin, and Neil for their input.  A great C++
programmer does not a good VB programmer make...  Please, Please, Please,
take a few minutes to notify me if there are any bugs.  I hate bugs...

Thanks to Paul for the check box problem.

Thanks to Alex for providing info on VB 2.0 problems.

Thanks to Michael and David for color problems with hilighted text.

Thanks to Michael for extended select reminder.

Thanks to Stacy, Juha, Darren and Paul, who all made a big difference in
the quality of this release.

***************************************************************************