                            MANUAL.RW
                            =========


This file contains additions and corrections to the Resource
Workshop User's Guide, including support of Windows 3.1 and
Borland Windows Custom Controls (BWCC).

The Resource Workshop online documentation also includes these
files:

BWCCAPI.RW    Describes technical aspects of Borland Windows
              Custom Controls.

CUSTCNTL.RW   Describes creating Windows custom controls classes,
              with C and Pascal programming examples.

BWCCSTYL.RW   Describes general style guidelines for creating
              resources using BWCC.

Contents (lists only section and first subsection headings)
-----------------------------------------------------------

    1  Changes to the Resource Workshop User's Guide
         1.1     Introduction
         1.2     Chapter 2, Resource Workshop Basics
         1.3     Chapter 3, Working with projects and resources
         1.4     Chapter 4, Creating dialog boxes
         1.5     Chapter 5, Creating menus
         1.6     Chapter 6, Creating accelerators
         1.7     Chapter 8, Using the Paint editor
         1.8     Chapter 9, Creating icons
         1.9     Chapter 10, Creating cursors
         1.10    Chapter 11, Creating fonts
         1.11    Appendix A, Technical notes
    2  Changes for this release
         2.1     Visible option
         2.2     Windows version compatibility
         2.3     Dialog box positioning
    3  New features in Windows 3.1
         3.1     Style dialog boxes
         3.2     Icon sizes
         3.3     Version stamper
    4  Linker requirements
         4.1     BWCC.LIB
         4.2     BWCC.DLL
         4.3     BWCC and Object Windows Library (OWL)
    5  Borland Windows Custom Controls
         5.1     Using the custom dialog class
         5.2     Using the custom controls
         5.3     Customizing existing applications for BWCC
    6  Loading BWCC to enable Borland custom controls
    7  Sample exercise: Customizing an existing application
         7.1     Backing up the application
         7.2     Opening a project
         7.3     Editing the application's controls
         7.4     Saving and testing the project
    8  Tips on editing resources
         8.1     Accelerators
         8.2     Bitmaps
         8.3     Cursors
         8.4     Dialog boxes
         8.5     Icons
         8.6     Menus
         8.7     String tables


1        Changes to the Resource Workshop User's Guide
------------------------------------------------------

The following sections describe corrections to the Resource
Workshop User's Guide or changes to existing functionality.


1.1      Introduction
---------------------

p. 5     The following is current information for "How to contact
Borland":

    Phone/Command       Service
    -------------------------------------------------------------
    408-461-9144        Borland Pascal Technical Support, 6 a.m. 
                           to 5 p.m. PST
    800-822-4269        TechFax, 24-hour technical information to
                           fax machines (touch-tone phones only)
    408-439-9096        Borland File Download BBS (2400 baud)
    GO BORLAND          CompuServe
    JOIN BORLAND        BIX
    BORLAND             GEnie


1.2      Chapter 2, Resource Workshop basics
--------------------------------------------

p. 17    If you have a Pascal compiler, the demo file is called
RWPDEMO. If you have a C++ compiler, the demo file is RWCDEMO.

p. 25    If you have a Pascal compiler, put your identifiers in a
.PAS constant file.


1.3      Chapter 3, Working with projects and resources
-------------------------------------------------------

p. 33, step 2, last paragraph: The Resource|New and File|Add to
Project commands are not available for the .CUR, .ICO, .BMP, and
.FNT resource types.


1.4      Chapter 4, Creating dialog boxes
-----------------------------------------

p. 64    Change the first bullet in the bulleted list at the
bottom of the page to the following:

    - Resize the dialog box in either of the following ways:

         - Drag the appropriate edge or corner.

         - Select the dialog box by clicking the dialog box's
           title bar, and then choose Align|Size to display the
           Size Dialog dialog box. Enter width (CX) and height
           (CY) values in dialog units.  The size values apply to
           the outer dimensions of the dialog box.

p. 70    The following paragraph applies to Figure 4.6:

    If you install a custom control library containing custom
    controls whose Class is recognized by Resource Workshop, the
    Tools palette can have more than four columns. Bitmaps for
    these custom controls are added to the right side of the
    Tools palette. (See page 99 and the file CUSTCNTL.RW on the
    installation disk for more information on custom controls.)

p. 82    In the section "Aligning multiple controls," the command
is Align|Align, not Align|Align Controls.

p. 90    The following text accurately describes the scroll bar
alignment options:

None          The scroll bar fills the entire selection frame
              (default). If you resize the selection frame, you
              can distort the scroll bar.

Top Left      A horizontal scroll bar displays undistorted at the
              top of the selection frame and extends the full
              width of the frame. A vertical scroll bar displays
              undistorted at the left side of the selection frame
              and extends the full height of the frame.

Bottom Right  A horizontal scroll bar displays undistorted at the
              bottom of the selection frame and extends the full
              width of the frame. A vertical scroll bar displays
              undistorted at the right side of the selection
              frame and extends the full height of the frame.

p. 100   Add the following paragraphs to the first sentence after
"Adding a custom control":

    If you've added a custom control library whose Class is
    recognized by Resource Workshop and which has its own custom
    bitmaps, you can select your controls directly from the
    custom bitmaps on the right side of the Tools palette.

    If Resource Workshop doesn't recognize the Class of your
    custom controls, you must do the following to add them to
    your dialog boxes:

p. 103   In step 5, just above the figure, the last sentence of
the second paragraph should read:

    If you can't see it, select the Project window and then
    choose View|By File.

p. 106   The description of the Draft Drawing Type option in
Table 4.27 should read as follows:

    Draws each control as a rectangle with its control_ID in the
    center. This option also allows you to see the exact size of
    each control rectangle.

The following is the correct description of the Selection options
(Table 4.28):

Select Near Border      This option applies to clicking to select
                        controls.
                        On: You must click on the control's
                        border.
                        Off: You can click anywhere inside the
                        control's border.

Selection Rectangle     This option applies to dragging a
Surrounds               selection frame to select controls.
                        On: You must entirely surround the
                        control (or controls) with the selection
                        rectangle.
                        Off: The selection rectangle need only
                        touch the control (or controls).


1.5           Chapter 5, Creating menus
---------------------------------------

p. 119, Table 5.1: Use the EnableMenuItem function to change the
state of Enabled, Disabled, and Grayed menu items. Use the
CheckMenuItem function to change the state of Checked menu items.

p. 125   In the text below the figure, "Arrange List..." should
be "A&rrange List".

p. 126, Fig. 5.9: The illustration shows the menu before the new
items are inserted, not after. The figure will be corrected in
the next printing of the manual.

p. 136   The C header file (WDGCONST.H) would look like this:

    #define WMNU_LST 101
    #define WMNU_ADD 102
    #define WMNU_ASC 103
    #define WMNU_DESC 104

In addition, the #include for the C version of the file would be

    #include "wdgconst.h"

p. 137   In the last paragraph of step 4, the text should say:

    ...indicating that you can press Alt-W to display the Widgets
    menu.


1.6      Chapter 6, Creating acclereators
-----------------------------------------

p. 140   The figure shows incorrect identifiers for the first
four accelerators. The correct identifiers are, in order,
cm_Undo, cm_Cut, cm_Copy, and cm_Paste.


p. 153, step 6. The correct message text is "No duplicate key
values found".


1.7      Chapter 8, Using the Paint editor
------------------------------------------

p. 181, Table 8.1. The mouse actions for Zoom In and Zoom Out are
reversed. To zoom in, double-click on the Zoom icon; to zoom out,
Shift+double-click on the Zoom icon.

p. 188   The correct text for the second bullet is

    ...then choose Edit Foreground Color or Edit Background Color
    from the Icon or Bitmap menu, depending on which type of
    resource you're editing.

p. 189   In two places on this page, the text says "palette"
where it should say "device." In the section "Editing a color,"
the text in parentheses in the first paragraph should read

    (for a 16-color device, you might see a dithered color appear
    in this box)

The marginal notation at the bottom of the page refers to a
256-color palette. The Granted color matches the Requested color
on 256-color (or higher) devices, not palettes.

p. 190   The System button is enabled for devices that support
256 colors or more.


1.8      Chapter 9, Creating icons
----------------------------------

p. 202, Fig. 9.4 and surrounding text: The dialog box is called
New File Resource.


1.9      Chapter 10, Creating cursors
-------------------------------------

p. 224, Fig. 10.4 and surrounding text: The dialog box is called
New File Resource.


1.10     Chapter 12, Creating fonts
-----------------------------------

p. 243   The following paragraph should appear after Step 1 of
"Creating a new font resource":

    If you create a new project, you can choose the .RC, .RES, or
    .FNT format. If you choose .RES or .FNT, Resource Workshop
    automatically starts the Paint editor. The Source/Binary
    dialog box is not displayed.

In Step 2, the option you choose is called FONT, not .FNT. In
addition, the following might further clarify the Source and
Binary options:

    The Source option "embeds" the font resource in the current
    project; the font does not exist as a separate file and
    cannot be used in any other project. The Binary option saves
    the font resource as a separate file (with the .FNT
    extension) that is linked to the current project. You can
    link an .FNT file to other projects using the File|Add to
    Project command.

p. 244   The Paint editor tools appear on the right side of the
screen. (A similar error occurs on p. 255.)

p. 246   The following might further clarify the explanation of
the Stretch Current Chars option:

    When this option is checked, any changes you make to the
    width or height values in this dialog box will cause the
    width or height of existing characters to change accordingly.

p. 252   In Step 4 at the top of the page, the command is
File|Save Project or File|Save File As. File|Save Project
overwrites the current project; File|Save File As creates a new
project file, allowing you to keep your old version.

In the section "Saving the project," the command is File|Save
Project.

In the section "Saving a font resource as a file," the command is
Resource|Save Resource As, and the dialog box is called Save
Resource As. The first sentence in the section should read as
follows:

    Saving the entire project saves all resources in the project,
    not just the font resource you're working on.

p. 256   In Step 3, the two page references are inaccurate. In
the second paragraph, the correct page reference for the maximum
width value is to page 246. In the third paragraph, the correct
page reference for the break character is to page 247.


1.11     Appendix A, Technical notes
------------------------------------

p. 266   The preprocessor incompatibility between the Microsoft
Resource Compiler and the Resource Workshop compiler in handling
complex parameterized #defines no longer exists.

However, the Microsoft Resource Compiler and Resource Workshop
are still incompatible in several areas:

- interpretation of numbers with leading zeros

- the #undef preprocessor directive

- preprocessor token pasting

- expressions in resources IDs and resource type IDs

- hexadecimal numbers in resources IDs and resource type IDs

- complex constant expressions

- duplicate resource IDs

- resource IDs greater than 32767

- floating END statements

- floating operators in expressions

- missing operators in expressions

- parsing of the CAPTION statement

- macros in include directives

- valid characters in resource names


1.11.1   Numbers with leading zeros
-----------------------------------

Because of inconsistencies in the Microsoft Resource Compiler's
treatment of numbers with leading zeros, don't use them in
preprocessor expressions or identifiers. The Resource Workshop
compiler is consistent in interpreting as an octal number any
numeric constant preceded by a zero that's used as part of an
identifier or a preprocessor expression. However, the Microsoft
Resource Compiler interprets numbers with leading zeros in
preprocessor expressions as octal numbers, but interprets the
same numbers in identifiers as decimal numbers.

For example, the Microsoft Resource Compiler would interpret the
expression 010+1 as a 9 in the following preprocessor expression,
but as an 11 in the string table identifier.

    #if (9 == 010+1)
       STRINGTABLE
       BEGIN
           010+1, "Bug"
       END
    #endif


1.11.2   The #undef preprocessor directive
------------------------------------------

Resource Workshop has limited support for the #undef preprocessor
directive. You can use it only with #defines that are not
referenced by a resource. If you use #undef with a #define that's
been referenced, you get a fatal compiler error when compiling
the .RC file under Resource Workshop.

This restriction does not apply to the command-line resource
compiler.


1.11.3   Token pasting
----------------------

Resource Workshop does not support token pasting in preprocessor
statements. See the "Borland C++ Programmer's Guide" for more
information on token pasting.


1.11.4   Hexadecimal numbers in
         resource IDs and resource type IDs
-------------------------------------------

Resource Workshop supports hexadecimal numbers in resource IDs;
the Microsoft Resource Compiler does not. For example, the
following statement compiles correctly using Resource Workshop,
but fails using the Microsoft Resource Compiler:

    0x0001  ICON file.ico

The Microsoft Resource Compiler emits an icon resource with the
name "0x0001". Resource Workshop emits an icon resource with an
ID equal to 1.


1.11.5   Expressions in resource IDs and resource type IDs
----------------------------------------------------------

Resource Workshop supports expressions in resource IDs; the
Microsoft Resource Compiler does not. For example, the following
statement compiles correctly using Resource Workshop, but fails
using the Microsoft Resource Compiler:

    101 + 1000 BITMAP vga.bmp

The Microsoft Resource Compiler parses "101" as a resource ID,
"+" as a resource type name, "1000" as a file name, and then
fails. Resource Workshop correctly emits a bitmap resource with
an ID equal to 1101.


1.11.6   Complex constant expressions
-------------------------------------

Resource Workshop supports full C-language constant expressions
in place of a simple number anywhere in a resource script where a
number is allowed. The Microsoft Resource Compiler supports only
simple expressions. For example, the following expression is
correctly evaluated by Resource Workshop, but fails using the
Microsoft Resource Compiler:

    3 * (1 + 2) - 1

The most common example of this incompatibility is often seen in
ICON statements in DIALOG templates. The following statement
causes an error in Resource Workshop, but not in the Microsoft
Resource Compiler:

    ICON   3 -1, 10, 10, 0, 0

Resource Workshop interprets "3 -1" as an expression that
evaluates to 2. The Microsoft Resource compiler interprets "3 -1"
as two separate fields. If you add a comma after the first
number, both compilers interpret the statement correctly:

    ICON   3, -1, 10, 10, 0, 0

1.11.7   Duplicate resource IDs
-------------------------------

To allow resources to be accessed at run time, Resource Workshop
enforces the rule that resource IDs or names must be unique
within each resource type; the Microsoft Resource Compiler does
not. The following statements causes Resource Workshop to display
an error:

    1 ICON file1.ico
    1 ICON file2.ico


1.11.8   Resource IDs greater than 32767
----------------------------------------

Although the Microsoft documentation states that resource IDs can
be any number between 1 and 65535, you must actually use resource
IDs that fall between 1 and 32767 to ensure that the IDs are
unique. The reason is that resource binders like RLINK or the
Microsoft Resource Compiler OR all resource IDs with 0x8000 when
they build the resource directory in the executable file,
producing a value from 32768 to 65535.


1.11.9   Floating END statements
--------------------------------

Resource Workshop does not allow END statements with no
corresponding BEGIN. The Microsoft Resource Compiler allows these
statements. For example, the following script fragment causes an
error in Resource Workshop:

    1 RCDATA
    BEGIN
      0
    END

    END


1.11.10  Floating operators in expressions
------------------------------------------

Resource Workshop's expression parser does not allow "floating"
operators in constant expressions; the Microsoft Resource
Compiler does. For example, the following expression is flagged
as an error in Resource Workshop:

    WS_SYSMENU | WS_CAPTION |

To correct the error, merely remove the last bitwise OR operator:

    WS_SYSMENU | WS_CAPTION


1.11.11  Missing operators in expressions
-----------------------------------------

Resource Workshop's expression parser requires that all operators
required for an expression be present. The Microsoft Resource
Compiler assumes that a missing operator is a bitwise OR
operator. For example, the following expression is flagged as an
error in Resource Workshop:

    WS_SYSMENU  WS_CAPTION

To correct the error, add the bitwise OR operator:

    WS_SYSMENU | WS_CAPTION


1.11.12  Parsing of the CAPTION statement
-----------------------------------------

The Microsoft Resource Compiler is order-dependent in the way it
handles the CAPTION statement in a DIALOG template; the Resource
Workshop compiler is not. The following fragments illustrate this
difference:

    1 DIALOG 10, 10, 100, 100
    CAPTION "Caption"
    BEGIN
    END

    2 DIALOG 10, 10, 100, 100
    STYLE WS_POPUP
    CAPTION "Caption"
    BEGIN
    END

    3 DIALOG 10, 10, 100, 100
    CAPTION "Caption"
    STYLE WS_POPUP
    BEGIN
    END

In the first example, there is no explicit STYLE statement, and
both compilers default to WS_POPUP | WS_BORDER | WS_SYSMENU,
which is OR'd with WS_CAPTION. The style of the resulting DIALOG
template is

    WS_POPUP | WS_BORDER | WS_SYSMENU | WS_CAPTION

In the second example, the STYLE statement precedes the CAPTION
statement, and both compilers OR the two together. The style of
the resulting DIALOG template is

    WS_POPUP | WS_CAPTION

In the third example, the CAPTION statement precedes the STYLE
statement.

The Microsoft Resource Compiler, having encountered an explicit
STYLE statement, clears any preceding implicit or preset styles.
The resulting DIALOG template has the style

    WS_POPUP

By contrast, the Resource Workshop compiler ORs the CAPTION and
STYLE statements to produce a DIALOG template with the style

    WS_CAPTION | WS_POPUP


1.11.13  Macros in include directives
-------------------------------------

Resource Workshop does not support macro expansion in include
directives. For example, the following fragment causes a compile
error:

    #define MYFILE "afile.h"

    #include MYFILE


1.11.14  Support of the CTLDATA statement
-----------------------------------------

Resource Workshop supports the CTLDATA statement for use with
custom controls. The CTLDATA statement is described in the online
file CUSTCNTL.RW. The Microsoft Resource Compiler does not
support CTLDATA.


1.11.15  Valid characters in resource names
-------------------------------------------

Resource Workshop follows standard C-language practice for valid
characters in resource names. It accepts any alphanumeric
characters in the ANSI character set (including accented
non-English-language characters like "‚"), plus the underscore.
Nonalphanumeric characters like slash, backslash, or the plus
sign are not valid. The resource name must start with a letter or
the underscore; it cannot start with a number.

The Microsoft Resource Compiler does not restrict resource names
to alphanumeric characters.


2        Changes for this release
---------------------------------

This section describes the changes made for this release of
Resource Workshop.


2.1      Visible option
-----------------------

The style dialog boxes for buttons, list boxes, group boxes,
combo boxes, static controls, and text controls (including static
text) have a check box option called Visible.

By default, this option is checked on (WS_VISIBLE), and the
control appears when the dialog box is first displayed. If the
option is turned off (NOT WS_VISIBLE), the control does not
appear. In that case, the application can call the ShowWindow
function at run time to display the hidden control.


2.2      Windows version compatibility
--------------------------------------

You can specify the target Windows version in the
File|Preferences dialog box.  Note that .RES and .EXE files
targeted for Windows 3.1 are not backward-compatible with Windows
3.0.

If the .RES file is targeted to Windows 3.1, you cannot use the
Windows 3.0 version of RC.EXE to bind your resources to the
application. You must use Borland tools or version 3.1 of the
Microsoft Resource Compiler.


2.3      Dialog box positioning
-------------------------------

For dialog boxes that use the WS_OVERLAPPED style, Windows allows
you to leave the positioning of a dialog box to Windows itself.
The Size Dialog dialog box (Align|Size) has a radio button called
Set by Windows, which appears in the Horizontal Size column when
the selected control is a dialog box frame.

If you click Set by Windows, the X-position field is
automatically blanked out. Resource Workshop puts a value of
0x8000 into the X field (although not displayed on the screen),
which tells Windows that it has charge of positioning the dialog
box.

This option is generally used for dialog box frames that are used
as main windows.


3        New features in Windows 3.1
------------------------------------

The following sections describe changes to Resource Workshop that
reflect new features in Windows 3.1.


3.1      Style dialog boxes
---------------------------

The following check box options implemented in Windows 3.1 have
been added to three of the style dialog boxes.

List Box Style

    Scroll bar always   The list box always displays a vertical
                        scroll bar, regardless of the number of
                        items it contains. The WINDOWS.H constant
                        for this style is LBS_DISABLENOSCROL.

Combo Box Style

    Vertical scroll     The combo box always displays a vertical
    always              scroll bar, regardless of the number of
                        items it contains. The WINDOWS.H constant
                        for this style is CBS_DISABLENOSCROL.

Edit Text Style

    Read only           The text is set to read-only. The
                        WINDOWS.H constant for this style is
                        ES_READONLY.

    Want return         A multiline edit text control accepts a
                        carriage return to force a line break.
                        The carriage return goes to the
                        Defpushbutton if keyboard focus is NOT in
                        the edit text control. The WINDOWS.H
                        constant for this style is ES_WANTRETURN.


3.2      Icon sizes
-------------------

Windows 3.1 supports icons in three sizes: 32x32 and 32x16 (also
supported in Windows 3.0), plus 64x64.  The New Icon Image dialog
box, illustrated in Figures 3.14 and 9.5 in the Resource Workshop
User's Guide, now includes the new 64x64 option.  In reading
Chapter 9, "Creating Icons," keep in mind that this new image
size is now supported.


3.3      Version stamper
------------------------

Resource Workshop now supports VERSIONINFO, the version stamper
for Windows 3.1 .EXE files. For a detailed description of
VERSIONINFO, see the Resource Workshop online Help file.


4        Linker requirements
----------------------------

The following sections describe some special requirements for
linking. See also section 9 for a description of Resource
Workshop's command-line linker and compilers.


4.1      BWCC.LIB
-----------------

You must link your program first with the import library BWCC.LIB
and then with IMPORT.LIB, both of which are contained in the LIB
subdirectory specified by the Install program. The order in which
you use these two library files is critical: BWCC.LIB must
precede IMPORT.LIB.


4.2      BWCC.DLL
-----------------

Make the dynamic link library BWCC.DLL available for your
application to use at run time by locating it in one of the
following places:

- the same directory as your application's .EXE file

- the Windows startup or system directory

- a directory in your PATH


4.3      BWCC and Object Windows Library (OWL)
----------------------------------------------

If you use the DLL version of OWL, you must load BWCC.DLL
explicitly.  To do so, insert the following code into WinMain
before the code that invokes the Application Run method:

    HANDLE hDLL:
      hDLL = LoadLibrary ("BWCC.DLL");

At the end of WinMain, insert this line of code:

    if (hDLL) FreeLibrary ("BWCC.DLL");


5        Borland Windows Custom Controls
----------------------------------------

The Borland Windows Custom Controls (BWCC) library contains a
custom dialog class and a set of custom controls (buttons, check
boxes, group shading boxes, and the like). BWCC adds to the
visual impact of your dialog boxes and optimize their
functionality.


5.1      Using the custom dialog class
--------------------------------------

The custom dialog class, BORDLG, works on both a visual and a
functional level.

- It improves the appearance of your dialog window by painting
  the background with a brush that varies according to the target
  display device. For screens of VGA and higher resolution, the
  background is a fine grid of perpendicular white lines, giving
  the effect of "chiseled steel." For EGA and monochrome screens,
  the background is white.

- It optimizes the drawing of dialog boxes by calling the custom
  control drawing routines directly, instead of waiting for
  Windows to paint the controls. This eliminates the typical
  sluggish drawing of dialog boxes.

To use the custom dialog class, enter "bordlg" as the Class in
the Window Style dialog box.


5.2      Using the custom controls
----------------------------------

The custom controls give the dialog box visual impact, with
several of them adding a three-dimensional effect. To the
end-user, they function in the same manner as the standard
Windows controls, although they include several technical
enhancements (described later).

The following is a brief description of the custom controls.
Detailed descriptions are given later in this file.

Group shade        A recessed, shaded rectangular box used to
                   group other controls. It differs from the
                   standard group box by giving an impression of
                   depth.

Borland            A family of push buttons with several highly
push button        visual bitmapped symbols, plus an owner-draw
                   option. The BWCC push buttons are larger than
                   most standard Windows push buttons.

Borland            A raised diamond-shaped radio button. When the
radio button       button is clicked, a black diamond appears in
                   its center, and the button shading reverses,
                   giving the impression that the button has been
                   pushed down. There is also an owner-draw
                   option.

Borland            A raised check box that displays a check mark
check box          instead of an "X." There is also an owner-draw
                   option.

Bitmap             A bitmap that can display a splash panel, or a
                   non-modifiable image that remains on the
                   dialog box.

Horizontal/        Horizontal and vertical dividing lines that
Vertical dip       give the impression of being etched into the
                   surface of the dialog box. You can convert the
                   dips to horizontal and vertical bumps, which
                   appear to be raised above the surface of the
                   dialog box.


5.2.1    Button and check box messages
--------------------------------------

The BWCC push buttons, radio buttons, and check boxes have the
following functional enhancements over the standard Windows
controls:

- They include an additional level of parent window notification
  and control over keyboard focus and tab movement. If you choose
  the Parent Notify option in the control's style dialog box, the
  control sends the following messages (as appropriate) at run
  time:

  BBN_SETFOCUS          Indicates to the parent window that the
                        push button, radio button, or check box
                        has gained keyboard focus through an
                        action other than a mouse click.

  BBN_SETFOCUSMOUSE     Indicates to the parent window that the
                        push button, radio button, or check box
                        has gained keyboard focus through a mouse
                        click.

  BBN_GOTATAB           Indicates to the parent window that the
                        user has pressed the Tab key while the
                        push button, radio button, or check box
                        has keyboard focus. The parent can
                        intervene in the processing of the
                        keystroke by returning a nonzero value.

  BBN_GOTABTAB          Indicates to the parent window that the
                        user has pressed Shift-Tab (back-tab)
                        while the push button, radio button, or
                        check box has keyboard focus. The parent
                        can intervene in the processing of the
                        keystroke by returning a nonzero value.

- They include an owner-draw option so that the parent window can
  draw the push button, radio button, or check box. The
  owner-drawn control will look different from standard Windows
  controls, but will have the standard behavior of that class of
  control.


5.2.2    Using the BWCC style dialog boxes
------------------------------------------

There are four style dialog boxes for the BWCC controls:

- Borland Button Style

- Borland Radio Button Style

- Borland Check Box Style

- Borland Shade Style

Each has a control window for entering a Caption and a Control
ID.  The button style and check box style dialog boxes have
Attributes options for Tab Stop, Disabled, Group, and Border
(described in the Resource Workshop User's Guide), as well as
Visible, Parent Notify, and Owner Draw (described earlier in this
file). The shade style dialog box's only Attribute option is
Group.

The next four sections describe the features unique to each of
the style dialog boxes.


5.2.2.1  Borland Button Style dialog box
----------------------------------------

This dialog box allows you to choose from the three button types:
Pushbutton, Defpushbutton, and Bitmap.

By default, Pushbutton is the selected option. A Defpushbutton
has a bold border to identify it to the end-user as the "default
button," which is executed when the user presses the Enter key.
(The one exception occurs when keyboard focus is in an Edit Text
control for which the Want Return flag has been set. See Section
3.1 of this file.)

The following Control ID values and images are predefined for the
BWCC button controls:

   ID  button      image
  ---  ------      -----------------
    1  OK          green check mark
    2  Cancel      red X
    3  Abort       panic button
    4  Retry       slot machine
    5  Ignore      55 mph speed-limit sign
    6  Yes         green check mark
    7  No          red circle-slash
  998  Help        blue question mark
    -  Button      generic "Button" text - uses next available
                   Control ID

If you choose the Bitmap option, you can insert an image (based
on its Control ID) into the button image. To read in a bitmap:

1.  Use the Button control to add the generic BWCC button to your
    dialog box. Note its Control ID.

2.  Switch to the Paint editor and create a bitmap image. (See
    page 234 for information about creating bitmaps.)

3.  In the Paint editor, choose Resource|Rename.

    If you have a screen of VGA resolution or higher, add 1000 to
    the Control ID, and enter this value into the New Name field.
    For EGA or monochrome screens, add 2000 to the Control ID,
    and enter this value into the New Name field. Choose OK.

6.  Close the Paint editor and return to the Dialog editor. The
    bitmap will then appear in the BWCC button.


5.2.2.2  Borland Radio Button Style dialog box
----------------------------------------------

This dialog box lists two button styles:

Auto radio button  BWCC and Windows combine to handle
                   highlighting the selected button and
                   deselecting the other buttons. This is the
                   default option.

Radio button       The application must call the CheckDlgButton
                   function to send a BM_SETCHECK message to
                   highlight the selected button and deselect the
                   other buttons.


5.2.2.3  Borland Check Box Style dialog box
-------------------------------------------

This dialog box lists two check box styles:

Auto check box     BWCC and Windows combine to handle checking
                   the selected box. This is the default option.

Check box          The application must call the CheckRadioButton
                   function to send a BM_SETCHECK message to
                   check the selected box.


5.2.2.4  Borland Shade Style dialog box
---------------------------------------

You can use this dialog box to convert a vertical or horizontal
dip (described in section 5.2 of this file) to a vertical or
horizontal bump. Dips are primarily intended to act as separators
in the dialog box background; bumps are intended as separators in
gray shade boxes.

To convert a vertical dip to a vertical bump,

1.  Use the Vertical Dip control to add the dip to your dialog
    box.

2.  Locate and size the dip as you want it.

3.  Double-click on the dip to display the Borland Shade Style
    dialog box.

4.  Click the Vertical Bump radio button and then click OK.

To convert a horizontal dip to a horizontal bump, follow the same
series of steps using the Horizontal Dip tool and the Horizontal
Bump radio button.


5.3      Customizing existing applications for BWCC
---------------------------------------------------

Resource Workshop allows you to customize existing Windows
applications with Borland-style custom controls (3D buttons,
dialog boxes with the "chiseled steel" look, and so on). There
are two steps to this process:

1.  Modify your WIN.INI file to load the Borland Windows Custom
    Control (BWCC) library each time you start Windows.

2.  Edit the application in Resource Workshop to change user
    interface features like dialog boxes, menus, icons, and so
    on.

The next two sections describe these steps in greater detail.


6        Loading BWCC to enable Borland custom controls
-------------------------------------------------------

The BWCC library, which provides support for Borland-style custom
controls, must be loaded before an application can use BWCC's
features.

Edit the WIN.INI file (located in the Windows main directory) so
that Windows loads the file LOADBWCC.EXE into memory at start up.
The installation program places LOADBWCC.EXE in the language
compiler directory (the default location is \BORLANDC\BIN) and
adds this directory to your PATH.

Add LOADBWCC.EXE to the beginning of the list of files that
appear after the "LOAD=" statement. For example, if the LOAD
statement in your WIN.INI file looks like this:

    LOAD=NWPOPUP.EXE

the statement must be changed to this:

    LOAD=loadbwcc.exe NWPOPUP.EXE

LOADBWCC.EXE must appear first in the statement, to ensure that
BWCC is loaded into memory before any modified applications are
executed.

If you edit WIN.INI from within Windows, you must exit and
restart Windows to actually load LOADBWCC.EXE.


7        Sample exercise: Customizing an existing application
-------------------------------------------------------------

This section gives an overview of the steps typically involved in
modifying an existing application--in this case, the Windows
Program Manager.

Resource Workshop operates on projects, which are made up of one
or more resources. Because a Windows application contains a
collection of resources, you can open the application itself as a
project and then modify its resources.


7.1      Backing up the application
-----------------------------------

You should always edit backup copies of an application. Only
replace the original when you're satisfied that the modified
version functions correctly.

To make a backup copy of PROGMAN.EXE (Program Manager),

1.  In the Program Manager's Main window, double-click the DOS
    Prompt icon.

2.  At the DOS command line, switch to the C:\WINDOWS directory.

3.  Type "copy PROGMAN.EXE MYSHELL.EXE" and press the Enter key.

4.  Return to Windows by typing "exit" and pressing the Enter
    key.


7.2      Opening a project
--------------------------

To open the Program Manager as a project in Resource Workshop,

1.  Choose File|Open Project to display the Open Project dialog
    box.

2.  Display the list of types by pressing the button for the File
    Type drop-down list box. Select EXE Application from the
    list.

3.  Use the Directories box to change to the directory containing
    MYSHELL.EXE.

4.  Double-click on the file name in the Files list box to load
    MYSHELL.EXE as the project.


7.3      Editing the application's controls
-------------------------------------------

Now that you've loaded the application into Resource Workshop,
you can use the Dialog editor, Menu editor, Accelerator editor,
String editor, or Paint editor to customize the application. The
editors are discussed in the Resource Workshop User's Guide.

In this exercise, you'll use the Dialog editor to convert one of
the dialog boxes in the Program Manager to use BWCC.

NOTE: When it appears in the body of a paragraph, text that you
enter from the keyboard is set off by quotation marks. Unless you
are explicitly told to do so, do NOT include the quotation marks
in the text you enter.


7.3.1    Starting the Dialog editor
-----------------------------------

With MYSHELL.EXE loaded as the current project, you see the
Project window appear with "myshell.exe" as the title. This
window displays a list of the resources contained in the Program
Manager: a menu, several dialogs, a few string tables, an
accelerator table, and a number of icons. You can edit any one of
these resources by double-clicking it or by highlighting it and
choosing Resource|Edit.

Select dialog number 3 by locating the "Dialog" section of the
resource list and double-clicking "3". The dialog editor loads
the New Program Object dialog box (displayed when the user
chooses the Program Manager's File|New command).

When the Dialog editor appears, you can begin editing the dialog
box. The tasks you'll perform in this exercise include

- Changing the dialog box's class to the Borland style

- Changing the size of the dialog box

- Recessing and aligning the controls

- Changing the radio buttons to BWCC

- Replacing the buttons with BWCC buttons

- Aligning the buttons

- Saving and testing the edited dialog box


7.3.2    Changing the dialog's class name
-----------------------------------------

To convert the New Program Object dialog box to a Borland-style
dialog box, you must first change its class name.

1.  Double-click on the New Program Object dialog box's title bar
    to display the Window Style dialog box.

2.  Press the Tab key to move the cursor to the Class text
    control.

3.  Enter the following as the Class:

       BorDlg

    Click OK to exit the dialog box.

The New Program Object dialog box now has the BWCC
"chiseled-steel" background.


7.3.3    Sizing and rearranging the dialog box
----------------------------------------------

Now change the size and layout of the dialog box to make room for
the "group shade" and the BWCC buttons. (The group shade is a
recessed area you place behind the two radio buttons to give the
dialog box the appearance of depth.)

1.  Select the dialog box by clicking on its title bar or edge.
    (If the dialog box is already selected, skip this step.)

2.  Drag the bottom border down about two inches.

3.  Deselect the dialog box frame by clicking anywhere in the
    empty Dialog editor workspace outside the dialog box itself.
    (Use this same technique whenever you are instructed to
    deselect something.)

4.  Shift-click on each of the dialog box's buttons (OK, Cancel,
    and Help) to select them. Delete them by pressing the Del
    key. (The BWCC buttons are larger than standard Windows
    buttons. You will replace the buttons in a later set of
    steps.)

5.  Select the "New" group and press the Del key to delete it.
    You will replace it shortly.

The gray background of the two radio buttons extends well past
the text strings. Make the background smaller by doing this:

1.  Select the "Program Group" radio button.

2.  Drag the right edge of its selection frame to the left, until
    it's close to the text.

3.  Shift-click to select the other radio button. Both should now
    be selected.

4.  Choose Align|Size, and choose the Horizontal Size|Shrink to
    Smallest option from the Size Controls dialog box.

5.  With both radio buttons still selected (and their gray
    backgrounds now the same size), click the Horizontal Center
    in Dialog tool (third from the left in the top row of
    alignment tools).

6.  To make room for the new "New" text string, press the
    down-arrow key several times to move the radio buttons down
    in the dialog box. Press the Enter key when the radio buttons
    are where you want them.


7.3.4    Adding the group shade
-------------------------------

To make the controls appear recessed, add the group shade.

1.  Click the group shade tool (in the upper right corner of the
    Tools palette).

2.  Move the crosshair cursor above and to the left of the radio
    buttons. Don't start so far above the radio buttons that
    there won't be room for the "New" text string. Click to place
    the group shade box.

3.  Drag the lower right corner of the group shade box until it
    surrounds the radio buttons. Make it large enough that the
    radio buttons don't appear crowded inside.

4.  Click the Horizontal Center in Dialog tool (third from the
    left in the top row of the Alignment tools) to center the
    group shade in the dialog box.


7.3.5    Adding the text string
-------------------------------

To add the "New" text string above the group shade box,

1.  Click the Text Static Tool (the large letter T in the third
    column from the left of the Tools Palette).

2.  Move the crosshair to a point directly above the upper left
    corner of the group shade box. Click to place the static
    text.

3.  Drag the right edge of the static text frame to the right
    until it is not quite as wide as the group shade box.

4.  Double-click on the static text to display the Static Style
    dialog box.

5.  Type " New" (with one leading blank space) as the Caption,
    and click OK to close the dialog box.

6.  With the static text still selected, Shift-click to select
    the group shade box too.

7.  Choose Align|Size and then Grow to Largest from the Size
    Controls dialog box.

8.  Deselect everything by clicking in the empty work area
    outside the dialog box frame. Note how the static text
    appears to be slightly longer than the group shade because of
    the white edge on the right side of the group shade.

9.  Click to select the static text.

10. Drag its right edge one grid increment to the right. (You'll
    see the selection frame "snap" to the new position.)

11. At this time, you can also drag the static text down closer
    to the group shade, if necessary, to leave just a single dark
    line between the static text and the group shade.

    Deselect the static text if you need to check its position.


7.3.6    Converting the radio buttons
-------------------------------------

To convert the "Program Group" radio button to BWCC,

1.  Hold down the Ctrl key as you double-click the radio button.
    The Generic Control Style dialog box is displayed.

2.  Change the Class from "BUTTON" to "BorRadio" and then click
    OK. The quotes are required, but the text is not case
    sensitive.

Repeat these steps for the "Program Item" radio button.


7.3.7    Adding a horizontal dip
--------------------------------

Borland dialog boxes use a horizontal dip (see section 5.2 of
this file) to separate the exit buttons (OK, Cancel, and others)
from the rest of the controls.  To add a horizontal dip

1.  Click the Horizontal Dip tool (second from the top in the
    BWCC column in the Tools palette).

2.  Click the crosshair at the left edge of the dialog box frame,
    about a quarter of an inch below the group shade box. Note
    that the horizontal dip does not extend the full width of the
    dialog box.

3.  Choose Align|Size and then choose the Horizontal Size|Width
    of Dialog option.


7.3.8    Replacing the buttons
------------------------------

To replace the dialog box's buttons with BWCC buttons,

1.  Select the BWCC Button tool (in the middle of the fourth
    column of the Tools palette).

2.  Locate the crosshair at the point where you want the upper
    left corner of the first button (the OK button), and click.
    At this point, all the new buttons will simply say "Button".

    If the dialog box is not large enough for the new buttons,
    drag the bottom border to make more room.

3.  Move the mouse to the right, locate the pointer arrow at the
    point where you want the upper left corner of the second
    button (Cancel), and click the RIGHT mouse button. By doing
    so, you duplicate the most recently added control (in this
    case, the first button).

4.  Repeat step 3 to place the third button (Help). When you are
    done, you should have a horizontal row of three buttons.
    Don't worry about how neat the row is.

To convert the first button to a BWCC OK button with the green
check mark,

1.  Double-click on the left button to display the Borland Button
    Style dialog box.

2.  Type the following (in all uppercase letters) as the Control
    ID:

       IDOK

    You can also enter 1 as the Control ID.

3.  Select Defpushbutton as the Button Type to make OK the
    default push button.

4.  Click the Group check box in the Attributes. (The button
    should now be set to both Tab Stop and Group.)

5.  Click OK to change the button to the Borland-style OK button.

To convert the second button to a BWCC Cancel button with the red
X,

1.  Double-click on the second button to display the Borland
    Button Style dialog box.

    Type the following (in all uppercase letters) as the Control
    ID:

       IDCANCEL

    You can also enter 2 as the Control ID.

2.  Click the Group check box in the Attributes. (The button
    should now be set to both Tab Stop and Group.)

3.  Click OK to change the button to the Borland-style Cancel
    button.

To modify the last button for Help,

1.  Double-click on the last button to display the Borland Button
    Style dialog box.

    Type the following as the Caption:

       &Help

    (The ampersand puts an underscore under the "H," so the user
    can get Help by pressing the Alt-H key combination.)

2.  Tab to Control ID and enter "126". (This was the button's
    original control ID and is required for the user to be able
    to access Help successfully.)

3.  Click the Group check box in the Attributes. (The button
    should now be set to both Tab Stop and Group.)

4.  Click OK to exit the dialog box.

To align the buttons relative to each other and to center them in
the dialog box, first select them by dragging a selection frame.
Make sure nothing else is selected. Then use the Align menu
commands or the Alignment tools.

To use the Align menu commands,

1.  Choose Align|Align to display the Align Controls dialog box.
    Choose the Vertical Alignment|Centers option and click OK.
    This command aligns the buttons in a single row.

2.  Choose Align|Array to display the Form Control Into an Array
    dialog box. Set Rows to 1, Columns to 3, and Order to "Left
    to right." Click OK. This command spaces the buttons evenly
    relative to each other.

3.  If there is too much space at the bottom of the dialog box,
    now is the time to drag the buttons up nearer to the gray
    shade and to drag the bottom edge of the dialog box up.

4.  Choose Align|Align again. Choose the Horizontal
    Alignment|Center In Dialog option and click OK. This command
    centers the buttons horizontally in the dialog box.

To use the Alignment tools,

1.  Click the Vertical Alignment|Centers tool, the vertical
    double-headed arrow without line segments (second from the
    left, bottom row). This tool aligns the buttons in a single
    row.

2.  Click the Duplicate tool (in the left column of the Tools
    palette, second from the bottom). In the Form Control Into an
    Array dialog box, set Rows to 1, Columns to 3, and Order to
    "Left to right." Click OK. This tool spaces the buttons
    evenly relative to each other.

3.  If there is too much space at the bottom of the dialog box,
    now is the time to drag the buttons up nearer to the gray
    shade and to drag the bottom edge of the dialog box up.

4.  Click the Horizontal Alignment|Center in Dialog tool, the
    horizontal double-headed arrow with line segments at each end
    (third from the left, top row). This tool centers the buttons
    horizontally in the dialog box.


7.4      Saving and testing the project
---------------------------------------

You have now completed your modifications to the Program
Manager's New Program Object dialog box. To save your work,
choose File|Save Project.

To test the modified dialog box in Resource Workshop, choose
Options|Test Dialog or click the Test tool.

You can also run MYSHELL.EXE from Windows to see how the new
dialog box looks under the Program Manager. Choose File|Run, and
set the command line to "C:\WINDOWS\MYSHELL.EXE" (or give the
path to your Windows directory, if it is not on drive C). In this
case, you are actually running a second "copy" of the Program
Manager. When you are finished, choose File|Exit Windows to
return to your initial "copy" of the Program Manager.


8        Tips on editing resources
----------------------------------

This section discusses considerations to keep in mind when
editing resources of existing applications.


8.1      Accelerators
---------------------

If you add an accelerator, make sure it returns the same ID value
as its corresponding menu command. If you don't, the accelerator
will either execute the wrong command or do nothing.


8.2      Bitmaps
----------------

You may modify existing bitmaps in an application, but you may
not delete them.

Do not add new bitmaps. In most cases, the application will not
be able to use them.


8.3      Cursors
----------------

You may modify existing cursors in an application, but you may
not delete them.

Do not add new cursors. In most cases, the application will not
be able to use them.


8.4      Dialog boxes
---------------------

You can reposition items in a dialog box and convert controls to
their Borland custom control counterparts.

As you edit, be sure not to change the type of control associated
with each control ID value. For example, if control ID 100 is a
check box, don't change it to a radio button. The application
will still treat it as a check box.

In most cases you can remove controls that are not directly tied
to the application's functionality. For example, you can usually
remove a caption, a static text item that has no effect on how
the application works; but you can't remove an edit control,
which does affect how the application works.

Never add new controls. The application will not be able to use
them.


8.5      Icons
--------------

You may modify existing icons in an application, but you may not
delete them.

Do not add new icons. In most cases, the application will not be
able to use them.


8.6      Menus
--------------

With most applications, you can safely move commands within a
menu. Don't, however, move commands from one menu to another.
(For example, don't move the Open command from the File menu to
the Edit menu.) If you do, the application might be unable to
display context-sensitive Help or to check or uncheck the menu
commands.

Never change the order of the menus in the menu bar. For example,
if File is the first menu, don't make it the second.


8.7      String tables
----------------------

Use caution when editing existing string tables. Some programs
load the strings into buffers of fixed size, and adding text to
an existing string could overflow the buffer.

Never add new strings. The application will not be able to use
them.
