Custom Properties for VB Controls and Forms
-------------------------------------------

Well, not really "properties" like .Text or .ListIndex, but at 
least a way to associate values with a particular visual object 
and get them later, using a text key.  It's simple to use, and 
(hopefully) simple to understand.  Here are the four procedures 
used:

For controls:
    cpSet MyControl, MyPropertyName, MyPropertyValue
    variable = cpGet(MyControl, MyPropertyName)

For forms:
    cpSetForm MyForm, MyPropertyName, MyPropertyValue
    variable = cpGetForm(MyForm, MyPropertyName)

You use cpSet/cpSetForm to set the custom property values, and 
cpGet/cpGetForm to retrieve the values.

----------------------------------------------------------------
Quick Example:  (NOTE: No, I don't think this is a GOOD use of 
                       Custom Properties, but it's illustrative)

This subroutine will "blink" the BackColor of any control (that 
has a BackColor property).  Each call to BlinkButton will change 

    Sub BlinkButton(ctlBlinker as Control)
        If cpGet(ctlBlinker,"Lights") = "On" then
            ctlBlinker.BackColor = 0&
            cpSet ctlBlinker, "Lights", "Off"
        Else
            ctlBlinker.BackColor = &HFFFFFF&
            cpSet ctlBlinker, "Lights", "On"
        End If
    End Sub

----------------------------------------------------------------
Why would you want to use Custom Properties?

    1. Pass information between forms.
    2. They allow better design of generic routines.
    3. You can avoid form-level variables and global variables.
    4. They make your life easier.
    5. VB3 doesn't have a "HasFocus" property.
    6. Your data is so ad hoc, you don't know the property name 
       at design-time.
    8. You're using dynamic forms.

----------------------------------------------------------------
Why wouldn't you want to use Custom Properties?
    1. They may be slower than other methods.
    2. They can't handle binary data.

----------------------------------------------------------------
How do Custom Properties work?

Custom Properties are stored in a control's (or form's) .Tag 
property, in a "keyed list".  If you make these calls:

    cpSet MyControl, "CustProp1", "Value1"
    cpSet MyControl, "CustProp2", "Value2"
    cpSet MyControl, "CustProp3", "Value3"

Then MyControl.Tag value ends up looking something like this:

    ~CustProp1=Value1~CustProp2=Value2~CustProp3=Value3~

    NOTE: the tilde (~) is actually a chr$(26), but chr$(26) 
          doesn't go into text.

Custom Property accepts and returns all Values as variants, so 
you can pass in numeric data without hassle.  Doing a cpGet on 
an uninitialized custom property will return a variant 
zero-length string.

----------------------------------------------------------------
How do I use Custom Properties?

Add CUSTPROP.BAS to your VB3 project.
Start calling cpSet, cpGet, cpSetForm, cpGetForm.

----------------------------------------------------------------
What are some limitations of Custom Properties?

1. Custom Properties can't handle binary data.  As long as you 
   stick to the regular VB data types, you'll be OK.  In other 
   words, strings, integers, longs, singles, doubles, and 
   variants are alright.  But strings of BMP data retrieved via 
   API calls would be a bad idea.  Specifically, if you pass any 
   string values with chr$(26), you could have trouble.
2. Since the .Tag property is used, it can't be used by anything 
   else.  For that control.
3. Since the .Tag property is used, the conrol must have a .Tag 
   property.
4. Since the .Tag property is used, storage is limited to 64K 
   of custom property names and values.
5. You should load your forms before calling cpSetForm or 
   cpGetForm.  Otherwise, the form load event will occur in the 
   middle of the Custom Property code.

----------------------------------------------------------------
Things that have been done with Custom Properties.

1. In a VB-based routine to 3D-ize forms, a custom property was 
   used to determine how to draw the border around controls 
   (inset, raised, or none).
2. For text controls, a HasFocus custom property is very useful.
3. Tracking when the value of a textbox has changed (custom 
   property: IsDirty or HasChanged).
4. To flag that the value of a textbox is going to be changed, 
   and the normal logic in the textbox_Change routine should be 
   skipped (custom property: InChange).
5. To remember Ini file settings associated with a control's 
   value (custom property: IniSection).

----------------------------------------------------------------
Legal Stuff, at least sort of.

You may use Custom Properties in your VB work.  You may change 
Custom Properties, and then use it in your work.  You may give 
Custom Properties to others, as long as you haven't changed it 
and you include all files which you received and you don't 
charge anything for it.  "Don't charge" means exactly that.  No 
selling.  No exacting "service fees" or "processing charges".  

You don't owe me any money.

You may study the code used to create Custom Properties and 
make use of the ideas and techniques in your future work.

You may contact me with any questions, inquiries and criticisms.
You may not expect me to have all the answers.

Steve Bliss
75620,47  or  75620.47@COMPUSERVE.COM
