Category : BASIC Source Code
Archive   : GUI200.ZIP
Filename : PBGUI200.DOC

PBGUI TOOLKIT 2.00

Written By

James C. Fuller

For Use With

PowerBASIC 3.00

by

SPECTRA Publishing





The PBGUI TOOLKIT has been tested only on my machine. I take
no responsible for any problems that may occur from the use of
the routines in this toolkit.


The PBGUI TOOLKIT is a Shareware package that offers the
PowerBASIC programmer a library of sophisticated graphics rou-
tines to aid in the development of professional quality programs
for the commercial and shareware markets. Please read
REGISTER.DOC for information on pricing and the availability of
other products.


The number one problem I have encountered when using third
party add on libraries is the extensive recoding I needed to do
when a revised edition came out. Very often the number, order, or
type of parameters passed to the procedures changed, forcing me
to rewrite large sections of code. Many times I opted not to use
the updated libraries at all. I have addressed this problem by
using Global User Defined Data Types for a number of the proce-
dures. Another benefit of using TYPES is a reduction in coding
when several buttons with common attributes are created.


There is very limited error checking in this product. This was
done to keep the size of the library as small as possible, allow-
ing the programmer to use error checking during development while
removing it in a completed application.



This toolkit is NOT an MSWindows clone. It is primarily a
graphical library for presenting attractive and user friendly
screens for the purpose of gathering information.


The following is a list of the primary building blocks you
have to work with in developing your application. A more detailed
description of each of the functions follows.


< Windows >

These are STACK (Last In First Out) based The Active
window is the last window opened. To activate a previous-
ly created window you must close the active one. You may
open as many windows as conventional memory allows.


< Buttons >

Push Buttons
Radio Buttons
Check Boxes
Area Buttons





PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 1




< EditFields >

Data Input Areas


< ListBox >

A scrolling list picker.


< MessageBox >

An information window.

< Fonts >

A number of Bitmapped Fonts are included. There will be
an MSWindows program available that will convert MSWin-
dows fonts to my format.



< Drawing Tools >

Panel Up or Down (Raised or Etched)
ThreeDBox Up or Down
FilledThreeDBox Up or Down with optional color fill.
ThreeDline Up or Down
WindowLine plain line


< Color Control >

You have the ability to use any color you want and not be
limited to PowerBASIC's 63 palette colors.


























PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 2






The following is a list of the DATA TYPES that are used with this
library, and an explanation of their use.


TYPE WindowOpenType
handle AS INTEGER
row1 AS INTEGER
col1 AS INTEGER
row2 AS INTEGER
col2 AS INTEGER
BackColor AS INTEGER
LightColor AS INTEGER
DarkColor AS INTEGER
TextColor AS INTEGER
BorderColor AS INTEGER
Title AS STRING * 80
SaveBkgd AS INTEGER
END TYPE

handle:
Number of the window you are opening. Even though the
they are LIFO based, other routines rely on this number.
Use the WindowNext%() Function to retrieve the next
available handle.

row1:
Top row of window

col1:
Left edge of window. Windows will be aligned to the
nearest text column. col1 must be greater or equal to 8
to allow for a border.

row2:
Bottom row of window

col2:
Right edge of window.

BackColor:
Window background color

LightColor:
Window Highlight color

DarkColor:
Window Shadow color

BorderColor:
Window Border Color

Title:
Text string for Title (max 80 chars). End all text
strings with a CHR$(0).

Savebkgd:
If %TRUE Background is saved. IF %FALSE NOT saved.


PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 3




UNION FontIDUnion
Number AS INTEGER
FileName AS STRING * 8
END UNION

The FontID Union is used in ButtonOpenType.
FileName is used in version 2.00
example BOT.FontID.FileName="dub10"; where BOT is ButtonOpenType

=================================================================

TYPE ButtonOpenType
handle AS INTEGER
state AS INTEGER
text AS STRING * 30
row1 AS INTEGER
col1 AS INTEGER
row2 AS INTEGER
col2 AS INTEGER
ButtonType AS INTEGER
TextColor AS INTEGER
LightColor AS INTEGER
DarkColor AS INTEGER
BackColor AS INTEGER
FontID AS FontIDUnion
END TYPE

handle: Number of the Button you are opening

state:
Command Buttons
1 = Not Active
2 = Active

Radio Buttons
1 = Not Selected
2 = Selected

Check Boxes
1 = Not Checked
2 = Checked

text: String up to 30 characters for Button label

row1, col
row2, col2 Window coordinates of button

ButtonType: 1 = Command Button
2 = Check Box
3 = Radio Button
4 = Area Button

Colors: Same as WindowOpenType

FontID: Font Name example : BOT.FontID.Name = "f8"






PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 4




TYPE EditFieldOpenType
handle AS INTEGER
state AS INTEGER
text AS STRING * 80
row AS INTEGER
col AS INTEGER
ForeColor AS INTEGER
BackColor AS INTEGER
Length AS INTEGER
END TYPE


handle: Number of the EditField

state: %Active or %NotActive

text: text to display when EditField is Opened.
pad with SPACES to size in Length.

row: top row

col: left column

ForeColor: 0-15 Color of text.

BackColor: Color of EditField Background.

Length: Width of EditField in text columns

=================================================================

TYPE ListBoxDataType
row AS INTEGER
col AS INTEGER
height AS INTEGER
BoxBackColor AS INTEGER
BoxLightColor AS INTEGER
BoxDarkColor AS INTEGER
BoxTextColor AS INTEGER
ButBackColor AS INTEGER
ButLightColor AS INTEGER
ButDarkColor AS INTEGER
ButTextColor AS INTEGER
ActiveItems AS STRING * 256
END TYPE

row: top row

col: left column

height: Number of elements to display

BoxColors: Box Colors of the ListBox

ButColors: Colors of "OK" and "Cancel" Buttons

ActiveItems: use "0" for inactive "1" for Active




PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 5




TYPE MessageBoxDataType
BoxBackColor AS INTEGER
BoxLightColor AS INTEGER
BoxDarkColor AS INTEGER
BoxTextColor AS INTEGER
BoxBorderColor AS INTEGER
ButBackColor AS INTEGER
ButLightColor AS INTEGER
ButDarkColor AS INTEGER
ButTextColor AS INTEGER
FontID AS FontIDUnion
ButOneText AS STRING * 10
ButTwoText AS STRING * 10
END TYPE


I think the only things new are the ButOneText and ButTwoText.
These are CHR$(0) ending strings for the text on the buttons.
See the FUNCTION description for more information.

=================================================================

There are a number of GLOBAL variables that are used throughout
the library. The TYPES have already been described. These are the
GLOBAL names that are used for those types.

GLOBAL DATA TYPES

BOT AS ButtonOpenType
EFOT AS EditFieldOpenType
LBDT AS ListBoxDataType
MBDT AS MessageBoxDataType
WOT AS WindowOpenType


=================================================================

GLOBAL VARIABLES

Name Type Description

AveWidth BYTE Average Width of Font Character.
Bold BYTE IF %TRUE text is bold
CharSpace BYTE The space between characters
FontHeight BYTE The Height of Currently Loaded Font
FontLoaded INTEGER %TRUE if any Font is Loaded
FontPath STRING The Path where your fonts are located
Shadow BYTE %TRUE for Text Shadow %FALSE if none
ShadowColor INTEGER Color of Shadow
Raised BYTE %TRUE for Raised Text %FALSE for plain
RaisedColor INTEGER Highlight color for raised text.
MAXWindow INTEGER Maximum Number Of Windows
MAXButton INTEGER Maximum Number Of Buttons
MAXEditField INTEGER Maximum Number Of EditFields
WhichMouseButton BYTE 1=LEFT, 2=RIGHT






PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 6




Global Notes:

Do NOT alter AveWidth. It is used by the font drawing routine
for the SPACE. I only listed it here because it is in the
include file and you might be curious as to it's purpose.

I have included the MAX variables to keep memory use at the
minimum needed by an application.

When using Raised make sure Shadow = %FALSE. Raised uses the
ShadowColor for the shadow and by having Shadow = %TRUE it just
makes an unnecessary call to the Shadow routine.

The toolkit recognizes both left and right mouse clicks as the
same, but you can examine the global variable WhichMouseButton
in the Event loop and perform an action depending on which
button was clicked.

=================================================================

CONSTANTS

There also are a number of constants in the include file that
will be mentioned in the FUNCTION and SUB definitions. The
following is a list of those constants.

%TRUE = -1 %RadioButton = 3
%FALSE = 0 %AreaButton = 4
%UP = 0 %Active = 1
%DOWN = 1 %NotActive = 2
%VERT = 0 %MakeWindow = 1
%HORZ = 1 %MakeButton = 2
%CommandButton = 1 %MakeEditField = 2
%CheckBoxButton = 2



























PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 7




<<<< PBGUI TOOLKIT FUNCTIONS >>>>

================================================================

<< ButtonGetState >>

DESCRIPTION: Returns the State of a Button
SYNTAX : State% = ButtonGetState%(handle%)
ARGUMENTS : handle% = Button Number
COMMENTS :

================================================================

<< EditFieldGetState >>

DESCRIPTION: Returns the State of an EditField
SYNTAX : State% = EditFieldGetState%(handle%)
ARGUMENTS : handle% = EditField Number
COMMENTS:

================================================================

<< Event >>

DESCRIPTION: Returns an INTEGER reflecting the Type of Event
or the number of the (Button/EditField) that
triggered the Event.
SYNTAX : dummy% = Event%(EventType%)
ARGUMENTS : EventType% = one of the values from below.
COMMENT:

Return Values For:
Event(0)
1 A Button was selected
2 An EditField was selected
3 Enter Key
4 TAB Key
5 Shift TAB
6 Escape
-(X) Where X is an extended key code from
page 362 of the Reference Guide.
Event(1) Returns selected Button Number
Event(2) Returns selected EditField Number

================================================================

<< GetCurrentFont >>

DESCRIPTION: Returns the currently loaded font name.
SYNTAX : WhichFont$ = GetCurrentFont$
ARGUMENTS : None
COMMENT:









PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 8




<< GetEditField >>

DESCRIPTION: Returns an EditField's contents.
SYNTAX : String1$ = GetEditField$(handle%)
ARGUMENTS : handle% = EditFiled Number.
COMMENT:

================================================================

<< ListBox >>

DESCRIPTION: Creates a scrollable list box.
SYNTAX : Pick% = ListBox%(Items$())
ARGUMENTS : Items$() = list of items to be picked from.
COMMENTS : REDIM Items$() to the number of elements you
want before calling the function. Pick% re-
turns the item that was selected or 0 if the
cancel button was chosen. See the ListBoxData-

Type for other Data that ListBox requires and
the demo for use.

================================================================

<< LoadFont >>

DESCRIPTION: Loads a Font into memory.
SYNTAX : FontLoaded = LoadFont%(FontName$)
ARGUMENTS : FontName$ = File Name of Font file.
COMMENTS : Do not use extension in file name. LoadFont
expects an extension of "fnt". FontLoaded =
%FALSE if LoadFont cannot locate the file.

================================================================

<< LoadWindow >>

DESCRIPTION: Loads Screen and Window Data that was saved with
the SaveWindow SUB.
SYNTAX : Success% = LoadWindow(WindowFileName$)
ARGUMENTS : WindowFileName$ = Path and filename that was
used by SaveWindow to save Data. Returns %FALSE
if it fails %TRUE if successful.
COMMENTS :

================================================================

<< MessageBox >>

DESCRIPTION: Displays a Window with a message and either one
or two buttons.
SYNTAX : WhichButton% = MessageBox(Message$())
ARGUMENTS : Message$() = Lines to be displayed.
COMMENTS : REDIM Message$() to the number of lines of text
you wish to display. If you want just one
button make sure MBDT.ButTwoText = CHR$(0).
See MessageBoxDataType for other Data that
MessageBox requires and the demo for its use.




PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 9




<< WindowNext >>

DESCRIPTION: Returns the next available window handle.
SYNTAX : WOT.handle = WindowNext%
ARGUMENTS : None
COMMENTS:























































PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 10




<<<< PBGUI TOOLKIT SUBS >>>>

================================================================

<< ButtonSetState >>


DESCRIPTION: Sets the State of a Button.
SYNTAX : ButtonSetState handle%, State%
ARGUMENTS : handle% = Button number
State% = %Active or %NotActive
COMMENTS :

================================================================

<< ButtonToggleState >>

DESCRIPTION: Toggles the state of a Button
SYNTAX : ButtonToggleState handle%
ARGUMENTS : handle% = Button number
COMMENTS:

================================================================

<< ChangeButtonText >>

DESCRIPTION: Changes the text on a Button
SYNTAX : ChangeButtonText handle%, text$
ARGUMENTS : handle% = Button number
text$ = chr$(0) terminated string of new text
COMMENTS :

================================================================

<< CloseWindow >>

DESCRIPTION: Closes the last opened window.
SYNTAX : CloseWindow
ARGUMENTS : None
COMMENTS:

================================================================

<< ColorInit >>

DESCRIPTION: Sets up a default Palette of colors
SYNTAX : ColorInit
ARGUMENTS : None
COMMENTS : Colors >>
0 Black 10 Light Green
1 Light Gray 11 Green
2 Gray 12 Dark Green
3 Dark Gray 13 Yellow
4 Light Red 14 Cyan
5 Red 15 White
6 Dark Red
7 Light Blue
8 Blue
9 Dark Blue


PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 11




<< EditFieldSetState >>

DESCRIPTION: Sets the State of an EditField
SYNTAX : EditFieldSetState handle%, state%
ARGUMENTS : handle% = EditField number
state% = %Active or %NotActive
COMMENTS:

================================================================

<< EditFieldToggleState >>

DESCRIPTION: Toggles the EditField state
SYNTAX : EditFieldToggleState handle%
ARGUMENTS : handle% = EditField number
COMMENTS :

================================================================

<< EditFieldSetString >>

DESCRIPTION: Sets the EditField's contents
SYNTAX : EditFiledSetString handle%, EditString$
ARGUMENTS : handle% = EditField number
EditString$ = a chr$(0) terminated string
COMMENTS : see RedrawEditField

================================================================

<< FilledThreeDBox >>

DESCRIPTION: Draws a Filled 3D rectangle in a window
SYNTAX : FilledThreeDBox UpOrDown%, row1%, col1%, row2%,_
col2%,FillColor%
ARGUMENTS : UpOrDown% = %UP for raised, %DOWN for etched
row1% = top
col1% = left
row2% = bottom
col2% = right
FillColor% = fillcolor

================================================================

<< GetEvent >>

DESCRIPTION: Gets data from keyboard or mouse
SYNTAX : GetEvent StartEdit%
ARGUMENTS : StartEdit% = Beginning EditFiled
COMMENTS : Use in conjunction with Event%() FUNCTION












PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 12




<< GUILib >>

DESCRIPTION: Main routine for a number of functions
SYNTAX : GUILib Action%
ARGUMENTS : Action% = one of the following

%MakeWindow
%MakeButton
%MakeEditFiled

COMMENTS : This is the main routine for creating your
screens. Set the values in the corresponding
Data Types before calling. It was done this way
for flexibility in updating the library.

================================================================

<< Panel >>

DESCRIPTION: Draws a raised or etched rectangle
SYNTAX : Panel UpOrDown%, row1%, col1%, row2%, col2%, LW%
ARGUMENTS : UpOrDown% = %UP for raised %DOWN for etched
row1% = top
col1% = left
row2% = bottom
col2% = right
LW% = line thickness.
COMMENTS :

================================================================

<< Pallete >>

DESCRIPTION: Assign new colors to color registers ( 0 - 63 )
SYNTAX : Pallete Register??, red?, green?, blue?
ARGUMENTS : Register?? = 0-63
red?, green?, blue? = 0-255
COMMENTS : Notice the spelling- PaLLete for this routine.
PaLeTTe for the standard Basic call.
Make sure you map the register to the color you

want. Each of the registers can be mapped to any
of the 16 colors. I use 0-15 registers with 0-15
colors to make it simpler, but you can map any
register to any color.
EXAMPLE: PaLLete 22,54,67,88 - Change reg 22
PaLeTTe 2,22 - Map 22 to 2

================================================================

<< ReDrawEditField >>

DESCRIPTION: Redraws an EditField
SYNTAX : ReDrawEditField handle%
ARGUMENTS : handle% = EditField number
COMMENTS : Call this routine after you have changed the
EditFiled string with EditFieldSetString.





PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 13




<< SaveWindow >>

DESCRIPTION: Saves a screen and window data.
SYNTAX : SaveWindow FileName$
ARGUMENTS : FileName$ = The name of the file for saving.
COMMENTS : Use in conjunction with LoadWindow.


<< ThreeDBox >>

DESCRIPTION: Draws a 3D rectangle in a window
SYNTAX : ThreeDBox UpOrDown%, row1%, col1%, row2%, col2%
ARGUMENTS : UpOrDown% = %UP for raised, %DOWN for etched
row1% = top
col1% = left
row2% = bottom
col2% = right

================================================================

<< ThreeDLine >>

DESCRIPTION: Draws a 3D Line in a window
SYNTAX : ThreeDLine UpOrDown%, HorV%, row%, col%, Length%
ARGUMENTS : UpOrDown% = %UP for raised, %DOWN for etched
HorV% = %HORZ (horizontal), %VERT (vertical)
row%, col% = starting coordinates of line
Length% = length of the line

COMMENTS : coordinates are window based. 0,0 is upper left
corner of window.

================================================================

<< WindowInit >>

DESCRIPTION: Initializes the PBGUI TOOLKIT
SYNTAX : WindowInit
ARGUMENTS : None
COMMENTS : Must be called before any other PBGUI routine.

================================================================

<< WindowLine >>

DESCRIPTION: Draws a line in a window.
SYNTAX : WindowLine row%, col%, Length%, HorV%, LColor%
ARGUMENTS : row%, col% starting coordinates of line
Length% = length of the line
HorV% = %HORZ (horizontal), %VERT (vertical)
LColor% = color of line ( 0 -15 )
COMMENTS : coordinates are window based.









PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 14




<< WindowPrint >>

DESCRIPTION: Draws text on the current window.
SYNTAX : WindowPrint row%, col%, text$, colr%, Font%
ARGUMENTS : row%, col% starting coordinates of text
text$ = a chr$(0) terminated string$
colr% = color of text ( 0 -15 )
Font% Not used in this version
COMMENTS : uses last loaded font.

================================================================



<<<< MOUSE ROUTINES >>>>

================================================================

<< MouseHide >>

DESCRIPTION: Hides the Mouse cursor
SYNTAX : MouseHide
ARGUMENTS : None
COMMENTS :

================================================================

<< MouseShow >>

DESCRIPTION: Shows the Mouse cursor
SYNTAX : MouseShow
ARGUMENTS : None
COMMENTS :

================================================================

<< MouseBorder >>

DESCRIPTION: Sets a Min and Max bounds on mouse movement
SYNTAX : MouseBorder row1%, col1%, row2%, col2%
ARGUMENTS : row1%, col1%, row2%, col2% are the coordinates
of the mouse boundary.
COMMENTS : automatically called when a window is opened


















PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 15




<<< MISCELLANEOUS NOTES >>>

================================================================

Make sure PBGUIxxx.BI is $INCLUDED in all programs that use the
PBGUI routines.

I would like to take this opportunity to publicly thank Dan
Hunting for the use of his compression routines.

To get the effect of etched text set the ShadowColor to a light
color and have Shadow = TRUE%

If you notice that your cursor moves beyond the last character
of an EditFiled it's because you forgot to terminate the padded
text field with a CHR$(0).



================================================================

I can be reached via Compuserve in the PowerBASIC section of the
PCVENB forum or by EMAIL at 70117,1040 if you have any questions.






































PBGUI TOOLKIT 2.00 Copyright (c) 1993 James C. Fuller Page 16