****************************************************************************
**************************** CREG0009.TXT **********************************
****************************************************************************
This document, written by Jim Sare (a member Borland's volunteer tech
support crew, called TeamB) in response to questions in the VDBASE forum on
Compuserve. 

This has to do with using your own icons (custom bitmaps) on the Control
Palette to represent your own classes. It's fairly detailed ...

-------------
The basic techniques shown should work in VdBASE 7.x through dBASE Plus, 
although this was originally written for 5.x. I (Ken Mayer) have modified 
this to match the fields in the table in Visual dBASE 7.x and later versions. 
A few fields in VdBASE 5.x aren't in the table in VdBASE 7.x (I removed 
the descriptions from here, and modified the fieldNames that changed 
in the descriptions), and the one in 7.x has a couple of new fields ...   
08/27/1998

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

----> ...I don't know how to put controls that I create with dBASE code in 
this table. Is this only for DLL-based controls? Do you have any 
documentation on this feature?

This one is a bit of work to figure out and it's not documented very well.
Also, because this is a rather abstract subject in the current VdB release,
many are not even aware that they can use custom bitmaps on the Control
Palette to represent their own custom classes. So at the risk of giving you
some information you might already know, I'd like to seize the opportunity
here to provide a mini-tutorial for the benefit of everyone. Here's 
everything I know on the subject.

By default, the Control Palette displays the default bitmap for the base 
class that your custom class is subclassed from. CREG0009.DBF is in the
\Designer\Form subdirectory of the dBASE home directory
(\PROGRAM FILES\DBASE\PLUS\DESIGNER\FORM\CREG0009.DBF).

NOTE: This filename will be different based on what language dBASE is using.
      English:     CREG0009.dbf // default
      German:      CREG0007.dbf
      Spanish:     CREG000A.dbf
      Italian:     CREG0010.dbf
      Japanese:    CREG0011.dbf

This file is a standard, nonindexed dBASE table. By adding entries to this
file, you can specify a custom bitmap to appear in the Control Palette for
custom control classes that you have loaded via Set Procedure To 
MyCtrls.CC or via File | Set Up Custom Controls from the main menu when 
the Form Designer is active.

CREG0009.DBF already has entries to support the classes contained in
DATABUTTONS.CC, REPORT.CC and SEEKER.CC which help to serve as an 
example of how to add your custom bitmaps to the Control Palette for 
your own custom classes.

These are the fields contained in CREG0009.DBF in the order that they 
appear in the table structure, with a description of the purpose of 
each field:

CLASSNAME    CHARACTER   32   N
Set this field to the ClassName for each class contained in your CC 
files for which you have a custom bitmap. You do not need to provide a 
custom bitmap for each custom class. For those custom classes that 
have the custom bitmap properly specified in this table, the custom 
bitmap will be used. For those custom classes that you currently have 
loaded but have not specified an associated custom bitmap in this table, 
the custom class will still appear on the Control Palette with the 
default bitmap. Note that the actual ClassName will appear on the 
Control Palette with only the first letter capitalized regardless of 
how the ClassName is specified in CREG0009.DBF or in the CC file.
Note also that the spelling of the ClassName in CREG0009.DBF must 
match exactly with the spelling of the ClassName in the CC file except 
for capitalization.

FILENAME     CHARACTER   254  N
Set this field to the DLL FILENAME which contains the desired bitmap. 
If memory serves correctly, it supports including the path as well as 
the FILENAME. Also, I believe it supports long FILENAMEs if using Win95. 
Note however that this field is 254 characters. You would run into 
limitations using a fully qualified pathname with a long FILENAME. 
If no pathname is specified (this is how I use it), I believe the 
search order is 
   \PROGRAM FILES\DBASE\PLUS\DESIGNER\FORM followed by the same
order as that used for searching for any DLL using LOAD DLL.

BITMAPID    NUMERIC     5    N
Set this field to specify the bitmap to be used when the custom class is 
not selected in the Control Palette. This would be the numeric ID of the 
bitmap as it is named/labeled in the DLL which contains the bitmap. Note 
that because this is a numeric field, you cannot use descriptive names 
for your bitmaps in the DLL containing the bitmap.

If you use the VdB default transparent color (dark purple, 128,0,128 in RGB
order in decimal or 0x800080) for the background of the bitmap specified in
UPBMPID, the bitmap background color will be the same as that used for the
background of the default bitmaps used by VdB. This will make the bitmap
background color change when you change the ButtonFace color using the 
Colors settings in Windows Control Panel.

XOFFSET     NUMERIC     5    N
VdB supports 'split' or 'composite' bitmaps (ie; multiple images contained
in a single bitmap) for use on the control palette the same as it supports
'split' bitmaps in PushButton.UpBitmap/DownBitmap/DisabledBitmap properties.
This field specifies the offset, in pixels, from the top-left corner of the
composite bitmap of the origin of the up bitmap contained within the 
composite bitmap. This offset is referenced from zero (ie; pixels 0-19 
horizontally would be the width of the first 20-pixel bitmap, pixels 20-39 
would represent the width of the second 20-pixel bitmap, etc. For example, 
if you have a bitmap in a DLL that is 40 pixels wide and 20 pixels high 
which is a 'composite' bitmap containing a bitmap for the up position and 
a bitmap for the down position, set this value to 0 to specify the origin 
of first bitmap in the composite bitmap. If you are not using 'split' 
bitmaps, leave XOFFSET blank or set it to zero.

The preexisting entries in CREG0009.DBF for the custom classes contained 
in DATABUTTONS.CC are based on a 'split' bitmap contained in CREG.DLL. 

YOFFSET     NUMERIC     5    N
This field is like XOFFSET above, but is used to specify the vertical 
offset of the origin of the up bitmap contained in a 'split' bitmap. If 
you are not using 'split' bitmaps, leave YOFFSET blank or set it to zero.

WIDTH        NUMERIC     5    N
This field is used to specify the width of the bitmap. This field applies
whether or not you are using 'split' bitmaps. Set this field to the width 
of the bitmap in pixels referenced from one (ie; if the bitmap is 20 
pixels wide, set this field to 20).

HEIGHT       NUMERIC     5    N
This field is used to specify the height of the bitmap. This field applies
whether or not you are using 'split' bitmaps. Set this field to the height 
of the bitmap in pixels referenced from one (ie; if the bitmap is 20 pixels 
high, set this field to 20).

Note that the largest bitmap that I have been able to successfully display 
on the Control Palette is 20 pixels wide and 20 pixels high. I have not 
seen a published specification for this, but I believe this to be the 
actual limit. I have successfully used smaller bitmaps (horizontally/
vertically) as well.

CATEGORY     CHARACTER   32   N
Use this field to specify a different tab in the Control Palette on 
which to display the custom class. For example, setting this field to 
'My Custom' (without the quotes) will place the custom class on a 
separate tab in the Control Palette with the caption 'My custom'. Note 
that spaces are allowed and only the first character is capitalized 
even though I specified the first and third characters as capitalized. 
If you leave this field blank, the custom class will appear on the 
default 'Custom' tab in the Control Palette. Also, if you misspell the 
ClassName in CREG0009.DBF in comparison to how the ClassName appears 
in the CC file, the class will appear on the default 'Custom' tab in
the Control Palette.

ORDER        NUMERIC     2    N
This is the order in which the control appears on the palette. Don't know
what will happen if you specify two controls with the same order value -- 
might prove intresting ... The first control on the palette should be 1, the
next should be 2, etc. (KJM)

DESIGNER     CHARACTER   1    N
Which design surface? If you want this to display in the Form designer
use the letter F, in the Report designer, the letter R, the only 
other option I've seen is "N" and I have no idea what it means. (KJM)

================
The bitmap specified in CREG0009.DBF must be contained in a DLL (or if 
it can be contained in a BMP file, then I don't know how to make it 
work <g>).

Others' experience may be different, but the best tool I have found for
creating and editing bitmaps contained in a DLL or BMP file is Borland's
Resource Workshop. I have not had any difficulty creating bitmaps using RW
that did not faithfully reproduce properly in VdB.

A few additional notes regarding custom controls. To use custom controls 
most efficiently in VdB:

1. Edit VDB.INI (DB2K.INI or PLUS.INI) and remove all CCx= lines from 
   VDB.INI and save.
2. When you begin design of a new form, from the Command window,
   Set Procedure To MyFile.CC Additive
   for all of the custom classes that you will be using on the form that 
   have not already been loaded via previous Set Procedure To... 
   statements. Alternatively, you can drag the necessary CC files from 
   the Navigator and drop them on the Command window. Or you can 
   double-click the CC file in the Navigator to load it.
3. Design the form. The Form Designer will place the required Set Procedure
   To... statements in the form's constructor code even though they are not
   listed in VDB.INI.
4. If you do not use a class from one of the currently loaded CC files 
   in your form, the Form Designer does not stream a Set Procedure To... 
   statement for that CC file even though the CC file is loaded.

>From there (the original form design session) on out, the CC files will be
loaded only when the form is run or loaded back into the Form Designer.
Removing the CC files from VDB.INI will not affect any existing forms
since they already contain the necessary Set Procedure To... statements. 
Also, removing the CC files from VDB.INI has the added benefit of allowing 
VdB to start a little quicker because it does not have to load all of the 
CC files when it starts.

Jim Sare

