                              TOOLBAR Ver. 1.0



1. 0  INTRODUCTION

        TOOLBAR is an object class that was designed to enhance your
Clipper programs in presenting a toolbar for easier selection of program
options.

        TOOLBAR allows you to present a toolbar in either a horizontal
or vertical manner.  It allows logical grouping of like options with a
separator between logical groups. In addition, it displays button help
messages directly beside, over or under the button itself similar to
toolbars found in MicroSoft software such as Excel.

2.0   REGISTRATION

        TOOLBAR is not public domain, nor is it free software.  You are
granted a limited license to use this product on a trial basis.  You are
also granted a license to copy TOOLBAR, along with the documentation,
for the trial use by other users.  TOOLBAR has not been intentionally
crippled or limited in its functionality in any way.  If you wish to
continue using the product, you must send $25(US) to:

                        Bryan Duchesne
                        95 Kimberly Street
                        Fredericton, NB  E3A 5V6
                        CANADA

If you would like an original disk or an update to the latest release
of the software, please add $5 for shipping and handling.

You may also register this software via Compuserve by referencing ID
Number 8549.  GO PCNET to access the Shareware register function.

The source code for the object file, TOOLBAR.OBJ is available for a
cost of $50(US) including shipping and handling.

We encourage you to copy TOOLBAR and share it with anyone who might be
interested in adding this great graphical add-on to their programs.


3.0  GETTING STARTED

3.1  REQUIREMENTS -
                IBM compatible PC 386/486/Pentium
                Clipper 5.3
                Class(y) 2.4 or better

TOOLBAR is designed to run under Clipper 5.3 graphics mode ONLY.

To use TOOLBAR, simply copy the TOOLBAR files as follows:

        TBARSYS.OBJ         \CLIP53\OBJ
        TBARSYS.PRG         \CLIP53\OBJ
        TOOLBAR.OBJ         \CLIP53\OBJ
        TOOLBAR.CH          \CLIP53\INCLUDE

To include TOOLBAR in your programs, include TBARSYS and TOOLBAR in your
FILE list and be sure to include CLASSY in your LIB list.

3.2  BITMAPS INCLUDED

As in other Clipper 5.3 graphic programs, the BMP files must reside in
the directory in which the application using them resides.

Included in this package are a number of BMP files contained in file
TBARDEMO.BML for some of the more commonly used button bitmap images.
Also included is an "empty" button which you can use as a base for
creating your own bitmap buttons.

To customize your own bitmaps, use Windows Paintbrush program.  Each
bitmap is a 24 x 24 pixel bitmap. There is an "empty" button pattern
that you can use to create your own custom buttons.  Be sure you
"save as" another file name.

To simplify organization of your bitmaps, use the Clipper utility
program RES2BML to create your own bitmap library.

3.3  DEMO PROGRAM

Included in this package is a demo program TBARDEMO.PRG which may be
compiled and run to demostrate how toolbar can be presented.

Compile the demo program with the /N switch and link the resulting
object with Classy.lib.  For example:

     CLIPPER TBARDEMO /N
     EXOSPACE FI TBARDEMO,TBARSYS,TOOLBAR LIB CLASSY

4.0  PROGRAM SYNTAX

4.1  TOOLBAR INSTANCE VARIABLES

   VAR    frame        (assignable)
   --------------------------------
   Specifies the frame type to place around the toolbar when displayed.
   These are the standard box types defined in BOX.CH or in LLIBG.CH.

   VAR    framecol     (assignable)
   --------------------------------
   Specifies the color of the frame

   VAR    pushblock    (assignable)
   --------------------------------
   Specifies the code block to executed on a "hit". See AddItem Method.

   VAR    orient       (assignable)
   --------------------------------
   Specifies the orientation of the toolbar.  See Init Method.

   VAR    top          (assignable)
   --------------------------------
   Specifies the top row for the display.  See Init Method.

   VAR    left         (assignable)
   --------------------------------
   Specifies the left column for the display. See Init Method

   VAR    exitstate    (assignable)
   --------------------------------
   Specifies the exitstate as one of:

          TBAR_EXIT
          TBAR_NOEXIT

   See demo program and TBARSYS.PRG for examples of usage.

4.2  TOOLBAR METHODS

   METHOD init
   -----------
   This method is used to create a new toolbar object.

   The syntax is:

     ToolBar():new( <nTop>,<nLeft>,<nOrient> ) -> oBar

     <nTop>    is the top row of the toolbar
     <nLeft>   is the left column of the toolbar
     <nOrient> is the orientation of the toolbar as one of:
                 TBAR_HORIZONTAL
                 TBAR_VERTICAL

     This method returns the new toolbar object.

   METHOD display
   --------------
     This method passes no parameters and is used to display the
     toolbar on the screen.

     Syntax:

       oBar:display()

   METHOD close
   ------------
     This method passes no parameters and is used to remove the toolbar
     from the screen.

     Syntax:

       oBar:close()

   METHOD additem
   ---------------
     This method is used to add a toolbar item to the toolbar.

     Syntax is one of two forms:

     a) Add a button to the toolbar

        oBar:AddItem(<cBmpFile>, <bPushBlock>, <cMessage>) -> self

        <cBmpFile>   is the name of the BMP file to add
        <bPushBlock> is the code block to execute when the button on
                     the toolbar is selected.
        <cMessage>   is the message to display

     b) Add a separator to the toolbar

        oBar:AddItem( TBAR_SEPARATOR )

        For horizontally oriented toolbars, this will add a blank
        column after the last defined toolbar button.

        For vertically oriented toolbars, this will add a blank row
        after the last defined toolbar button.

   METHOD hittest
   --------------
     This method is used to indicate if a "hit" (i.e. the left mouse
     button as pushed) was made on a button located at the
     coordinates given.

        Syntax:

          oBar:hitTest( <nRow>, <nCol> ) -> <nHitCode>

        <nRow>     is the screen row to test.
        <nCol>     is the screen column to test.
        <nHitCode> is the standard hitTest code returned by the Clipper
                   pushbutton class hitTest.

   METHOD scantest
   ---------------
     This method is used to indicate if the mouse cursor is passing
     over a button located at the coordinates given.

        Syntax:

          oBar:scanTest( <nRow>, <nCol> ) -> <nHitCode>

        <nRow>     is the screen row to test.
        <nCol>     is the screen row and column to test.
        <nHitCode> is the standard hitTest code returned by the Clipper
                   pushbutton class hitTest.

5.0  USING TBARSYS.PRG

TBARSYS.PRG is a standard modal process for the toolbar.  It contains
all the necessary code to run the TOOLBAR in a fashion similar to
Clipper Getsys and MenuSys programs. To use this process, insert the
call to TBARSYS in your program where the toolbar is to operate.

Syntax:

   TBarModal( <oBar>, <cMsgColor>, <nMsgPos> ) -> NIL

   <oBar>      is the toolbar object to be run.
   <cMsgColor> is the message foreground and background color set.
   <nMsgPos>   is the relative positioning of the message expressed as
               one of:

      TBAR_MSG_TOP    displays the message over the toolbar button
      TBAR_MSG_BOTTOM display the message below the toolbar button
      TBAR_MSG_LEFT   displays the message to the left of the toolbar
                      button
      TBAR_MSG_RIGHT  displays the message to the right of the toolbar
                      button.

      (See TOOLBAR.CH for these definitions)

6.0  NOTICES

Clipper and Class(y) are registered trademarks of Computer Associates
International and AppSolutions Inc.  Excel and Paintbrush are registered
trademarks of MicroSoft Inc.

This documentation must accompany the TOOLBAR software when copying
for others.

If the source code for TOOLBAR is ordered, the original code remains
the property of Bryan Duchesne and as such, is copyrighted and may NOT
be distributed with any copy of the software.  It may be modified to
suit the individual needs but cannot be distributed in any form either
printed or electronic.

7.0  DISCLAIMER

Bryan Duchesne shall not be liable for any damages, whether direct,
indirect, special or consequential arising from the use or failure of
this program to operate in the manner desired by the user.

Bryan Duchesne
CompuServe: 76511,1036
Program and documentation Copyright (C) 1995, Bryan Duchesne
