Stars of Shareware: Programmierung/SOURCE.mdf/programm/msdos/c/objease3/docs/objeas30.doc

Text File | 1994-05-18 | 140.2 KB | 4,834 lines

                            ObjectEase 3.0
              (c) Copyright 1992,94 - David S. Reinhart
                 1004 Marticville Rd.Pequea, PA 17565
                           [phone]
                            CIS 71572,304




What Is ObjectEase?

    ObjectEase is a set of libraries designed to work specifically with
Borland(c) C++ compilers which will allow you, the programmer, to EASILY
incorporate user interface objects into your programs, saving you a
tremendous amount of coding time, and giving your programs a more
professional appearance.

    ObjectEase libraries are broken into two groups...  a library for TEXT
mode interfaces, and a separate library for GRAPHICS based interfaces.  The
libraries are supplied in only the LARGE memory model.  If you need to use
these libraries in programs compiled under another memory model, then you
have two choices.  First, you can recompile your entire project under the
large memory model which will allow you to link with the ObjectEase
libraries.  Second, if your program must remain in another memory model,
you must purchase the source code for the ObjectEase libraries, and
recompile the source under the desired memory model.  Prices for the source
code are listed in the REGISTER.DOC file, included with this package.


The ObjectEase Philosophy

    This is the third release of the ObjectEase libraries.  I have taken
the suggestions of registered users, along with my own ideas for expansion
of the libraries, and combined them into what I feel is a fantastic bargain
in high quality C++ libraries.

    So how come you can register my libraries for such a low price when
comparable commercial libraries cost hundreds of dollars?  Well, partly
because I am the only programmer involved in the creation of these
libraries.  I am not dependent on their income to pay other employees, only
to supplement my own income.  Also, it is because these libraries are
generic...  what I mean is...well it's like this.  You can use a button
object in your graphics application.  It performance is all you really need
right out of the library.  But, if you want to say...  change the font on
the buttons, you need to purchase the source and make the change yourself.
This was done on purpose.  I have provided high quality, easily used
classes.  They are very flexible as is, but if you want the utmost in
flexibility, then spend the few extra dollars and purchase the source.
That way, you can make whatever modifications you desire.  I'm sure you'll
agree that the prices for the source modules are also quite reasonable.


What's new in ObjectEase 3.0

    Good question...I'm glad you asked.  Just about everything.  Firstly,
each class has been coded in its own separate source module.  What this
means for you is smaller .EXE files. In v2.0 there was only one source
module for the entire library.  Therefore, when you linked in the library,
you linked in the ENTIRE library, not just the parts that your program
used.  I see this as a shortcoming in Borland's linker, but at any rate it
won't happen anymore.  Only the code for the classes you actually use in
your program will be linked into the executable.

    There have been enhancements to just about all of the existing classes
from v2.0.  Things that you used to have to purchase source to do can now
be done with the distributed version of the libraries.  Some classes, menus
in particular have been completely recoded.  Menus are now MUCH easier to
use for both the programmer, and the end user.  The old menu classes have
still been included in the code for compatibility, but you'll want to use
the new menu classes in any new projects.

    New classes in both the TEXT and GRAPHICS versions of the libraries
include:

    - SCROLL BARS
    - LIST BOXES
    - DIRECTORY BOXES
    - MESSAGE BOXES
    - PCX FILE DISPLAYING (graphics only)
    - NEW MENU CLASSES
    - WINDOWS (in graphics mode, similar to a commercial product
                you'll recognize)

There's more, I'm sure, but thoughts escape me at the moment...

    By the way, the video bios library has NOT changed since the last
version, mostly because I have not needed to do anything new with this
portion of the code for my own purposes.


THANK YOU's

    I would most certainly like to thank all of you who have become
registered users of versions 1.0 and 2.0 of the ObjectEase libraries.
Without you and your support there would not be a version 3.0.  I really
had no idea how many people might register this software with me when I
first began distributing via the shareware method, but the response has far
exceeded and expectations I might have had.  Thank you all!

    I would also like to thank my wife, Lynn, who has put up with me
spending countless hours typing computer gibberish into my PC while she and
the children tried to go about life in a normal manner.  Thank you Lynn,
Kenny, and Amanda.  Without you and your support this project would not
have reached completion.




On to the good stuff...

    This manual is broken into three parts.  The first part describes the
classes in the TUI library.  The second part describes the GUI library, and
finally the VIDBIOS library is described in part three.

    If you can't seem to grasp the meaning of a particular function from
this documentation, try looking at the sample code.  If all else fails,
feel free to give me a call.  I'll give a limited amount of phone support
to unregistered users.






                         TUI library reference

    The TUI.LIB library provides a complete set of TEXT mode user interface
objects, as well as some supplemental functions that you'll find most
useful.  The classes are described in the following section, with the
standalone function calls being described first.


Standalone Function Calls

void vprintat(int col,int row,int fore,int back,char *,...);

    This functions works very similarly to the standard prinf function,
    however, it writes directly to video memory, making output extremely
    fast. The col and row parameters specify the starting position of the
    string, and the fore and back parameters represent the colors in which
    the string will be output.

    example:    int d=100;
                vprintat(1,1,14,0,"%d",d);

void vprintc(int row,int fore,int back,char *,...);

    This function is that same as vprintat, however, it centers the text on
    the row provided in the row parameter.

    example:    char name[10];
                strcpy(name."David");
                vprintc(1,14,0,"%s",name);


void printat(int col,int row,int fore,int back,char *);

    This function is also like vprintat, however, no formatting is done.
    Only strings can be provided in the char * parameter.

    example:    printat(1,1,14,0,"Sample Text");

void printc(int row,int fore,int back,char *);

    This function is similar to vprintc, however, no formatting is
    provided. Only strings can be provided in the char * parameter.  The
    text is centered in the specified row.

    example:    printc(1,14,0,"Centered Text");
                void cprintat(int col,int row,int fore,int back,char *,...)


    This function works the same as vprintat.  It provides formatting, and
    additionally, it moves the cursor to the position at the end of the
    string.

    example:    cprintat(1,1,14,0,"Cusrsor is at the end");

void cprintc(int row,int fore,int back,char *,...);

    Same as cprintat, however, text is centered on the specified row.

    example:    cprintc(1,14,0,"Centered text");

void clear(char ch,int fore,int back);

    This function fills the screen with the specified char in the specified
    colors.

    example:    clear(176,14,4);

void cursoron();

    Turns the text mode cursor on.

    example:    cursoron();

void cursoroff();

    Turns the text mode cursor off.

    example:    cursoroff();

void settext(int fore,int back);

    Sets the text output to the specified colors.  This is the same as
    calling both the textcolor and textbackground functions with the
    appropriate parameters.

    example:    SetText(7,0);

void chsattr(int fore,int back);

    This function changes the foreground and background attributes of the
    entire screen.  EVERYTHING on the screen will be displayed in these
    colors after this call.

    example:    chsattr(7,0);

void chcattr(int col,int row,int length,int fore,int back);

    This function changes length characters starting at col,row to the
    specified foreground and background colors.  This function is used by
    the library for such things as moving menu bars highlights (old style
    menus only).

    example:    chcattr(1,1,80,14,0);

void dlay(int ticks);

    This is an alternative to the delay() function.  The ticks parameter
    represents timer ticks which occur normally at 18.2 times/second.

    example:    dlay(9); //delays 1/2 second

long getticks();

    This function return a long value which represents the current time in
    timer ticks.  This value starts at 0 each midnight and increments
    throughout the day.

    example:    long currticks;
                currticks=getticks();

int altkey();

    This function returns 1 if the ALT key is pressed at the time of the
    function call, 0 otherwise.

    example:    if(altkey()) {
                ...
                 }

int ctrlkey();

    This function returns 1 if the CTRL key is pressed at the time of the
    function call, 0 otherwise.

    example:    if(ctrlkey()) {
                ...
                 }

int lshiftkey();

    This function returns 1 if the LEFT SHIFT key is pressed at the time of
    the function call, 0 otherwise.

    example:    if(lshiftkey()) {
                ...
                 }

int rshiftkey();

    This function returns 1 if the RIGHT SHIFT key is pressed at the time
    of the function call, 0 otherwise.

    example:    if(rshiftkey()) {
                ...
                 }


void flushkeys();

    This function clears the typeahead buffer

    example:    flushkeys();

unsigned char getvidmode();

    The return value of this function represents the current video mode.
    It can be compared with the Borland defined constants C40, C80, etc...

    example:    unsigned char vidmode;
                vidmode=getvidmode();

unsigned char alt_to_asc(unsigned char);

    Use this function if you are checking for certain ALT key/character
    combinations.  It will return one of the values defined at the top of
    the TUI.h header file...ALTA through ALT0.

    example:    ch=getch();
                ch=alt_to_asc(ch);
                switch(ch) {
                ...
                 }

void smover(int row,int startpos,int endpos,int fgd,int bgd,char *string);

    This function causes the text string specified by string to move across
    the screen starting at startpos and ending at endpos on row row, and in
    the specified foreground and background colors.

    example:    smover(1,1,72,15,0,">>---->");

    This example moves the string >>----> from 1 to 72 on row 1.

void smovel(int row,int startpos,int endpos,int fgd,int bgd,char *string);

    Same as smover, however the string is moved to the left rather than to
    the right.

void smoveu(int col,int startpos,int endpos,int fgd,int bgd,char *string);

    Same as smover, however the string is moved upward in the column
    specied by col.

void smoved(int col,int startpos,int endpos,int fgd,int bgd,char *string);

    Same as smoveu, however, the string is moved downward rather than
    upward in the specified column.





                            Mcursor


    The following data and functions are all part of the Mcursor
class, which handles mouse functionality in both the text and graphics
modes.  Certain mouse functions are different, however, in the different
video modes.

Global Variables

    _MX An integer value representing the current x value of the mouse.
This varible is updated with every call to get_status().  The LBP() and
RBP() function call call get_status().

    _MY An integer value representing the current y value of the mouse.
This varible is updated with every call to get_status().  The LBP() and
RBP() function call call get_status().

    Using the above variable to get the mouse position can improve program
performance because a function call is not necessary to retrive these
values.

void far mhandler();
    This is the interrupt handler for the mouse which allows
    capturing such mouse events as double clicks.

MCursor the_mouse
    Since the mouse is used by other classes a global MCursor
    variable is defined in the library.  To use the mouse in your
    programs simply declare "extern Mcursor the_mouse" at the top of
    your source module(s).


Members - PRIVATE

int shown
    Indicates whether the mouse cursor is currently visible or not.

int xpos
    The current x position of the mouse cursor.

int ypos
    The current y position of the mouse cursor.

void mouse_interrupt();
    The current procedure acting as the mouse handler.

int m1
    Used as the AX register variable in mouse calls.

int m2
    Used as the BX register variable in mouse calls.

int m3
    Used as the CX register variable in mouse calls.

int m4
    Used as the DX register variable in mouse calls.

int button
    Represents the button being pressed or tested, left or right.

int count
    Keeps track of the number of times a button has been pressed.

int disabled
    If this variable is 1 the mouse cannot be shown.

int handler_installed
    This value is 1 if the mouse handler has been installed, 0 if not.

int eventmask
    Specifies which events the mouse handler captures.  By
    default only left mouse button presses are captured.

void ClearHandler()
    This function disables the mouse handler.

void InstallHandler()
    This function installs the mouse handler.  The mouse handler is
    installed by default by the arm() function.

Members - PUBLIC

Mcursor()
    The default constructor.

~Mcursor()
    The default destructor.

int init()
    Call to initialize the mouse at the beginning of your program. If the
    return value is 0, there is no mouse present.

    example:    extern Mcursor the_mouse;
                int mouse_present;
                mouse_present=the_mouse.init();

void get_status()
    This function returns the current state of the mouse buttons.  It is
    not normally called by the programmer.

void show()
    This function makes the mouse cursor visible if it has not been
    disabled by a call to unarm();

void hide()
    This function makes the mouse cursor invisible.

void set_hor_bounds(int min,int max)
    This function sets the bounds of mouse movement on the x axis.  The
    min value represents the left boundary of mouse movement, and the max
    value represents the right boundary.

void set_ver_bounds(int min,int max)
    This function sets the bounds of mouse movement on the y axis.  The
    min value represents the top boundary of mouse movement, and the max
    value represents the bottom boundary.

void conditional_off(int x1,int y1,int x2,int y2)
    This function makes the mouse cursor invisible when it is in the
    rectangle bounded by x1,y1,x2,y2.

void position(int x,int y)
    This function moves the mouse cursor to the screen position defined in
    x,y.

int LBP()
    Returns 1 if the left mouse button is currently pressed, 0 otherwise.

int RBP()
    Returns 1 if the right mouse button is currently pressed, 0 otherwise.

int mousex()
    This function returns the current x coordinate of the mouse cursor.
    Use the global value _MX to avoid this function call.

int mousey()
    This function returns the current y coordinate of the mouse cursor.
    Use the global value _MY to avoid this function call.

int mx()
    Same as mousex().

int my()
    Same as mousey().

void unarm()
    This function turns makes the mouse cursor invisible and does not
    allow it to be re-shown by the show() call.  To re-show the cursor
    you must call arm().

void arm()
    This function shows the mouse cursor and allows future calls to show()
    to do the same.

int LBDCLK()
    This function returns 1 if the left mouse button has been double
    clicked, 0 otherwise.  The left mouse button must be pressed twice
    within 1/2 second (9 timer ticks) for LBDCLK to return 1.

long thistick
    Represents the current timer tick at the time of the mouse event.  Not
    normally used by the programmer.

long prevtick
    Represents the timer tick at the time of the previous mouse event.
    Not normally used by the programmer.

int doubleclicked
    This value is checked by the LBDCLK() function.  It is set by the
    mouse handler.  Not normally used by the programmer.




                            Twindow

    The following functions and data members comprise the Twindow class.
The Twindow is used for creating popup windows on the text screen.  All
underlying screen elements are saved in a buffer which is later redisplayed
when, and if, the Twindow object is removed from the screen.

Members - PRIVATE

int x
    The left x screen coordinate of the window.

int y
    The top y screen coordinate of the window.

int x1
    The right x coordinate of the window.

int y1
    The bottom y coordinate of the window.

int fgd
    The color to be used for the foreground of the window.  Borders and
    titles are drawn in the foreground color.

int bgd
    The color to be used for the window background.

int shad
    If this value is non-zero the window will have a shadow cast under it
    and to one side.  The shaddirection member variable indicate to
    which side the shadow will be cast.

int shadcolor
    The color in which any text within the shadow area will be displayed.

int size
    The size of the buffer required to hold the underlying screen image.

char id[15]
    The title to be displayed on the window.

int existtitle
    This variable is non-zero if the window has a title.

int bordertype
    This variable represents the border style of the window.
    Use the global defines SINGLE and DOUBLE for this comparison.

int shown
    This variable is non-zero if the window is currently displayed on the
    screen.

unsigned char *save
    This is the pointer to the buffer in which underlying screen data is
    saved.

Members - PUBLIC

Twindow();
    The default constructor.

~Twindow();
    The default destructor.  The destructor will free any associated
    memory before destroying the object.

void getstyle();
    This function is used internally by the class to determine which
    character shapes to use to display the window border.

void init(int xpos,int ypos,int x1pos,int y1pos,int fore,int back,int
            shadow,int shadowcolor,int shadowdir=0);

    This function must be called after declaring a variable of type
Twindow to initialize the object.  The window positions and colors a
specified in this call.  Specifying a value of 1 for the shadow parameter
will cause the window to be displayed with a shadow.  The shadowcolor
parameter specified the color of any text which falls within the shadow
area.  The shadowdir parameter specifies the direction in which the shadow
will fall.  This parameter does not need to be specified and will default
to a shadow falling on the left side of the window.  To cause the shadow
to fall to the right side of the window, specify a 1 for this value.

    example:    Twindow theWindow;
                theWindow.init(10,10,71,20,14,4,1,8,1);

    This example initializes a window with an upper left coordinate of
    10,10,and a lower right coordinate of 71,20.  The foreground color is
    yellow(14) on a background of red(4).  It will have a shadow with text
    falling in the shadow displayed as dark gray(8).  The shadow will be
    cast to the right.

void border();
    Causes the border of the window to be (re)drawn.

void setborder(int style);
    Use this function to specify the border style, SINGLE or DOUBLE)
    before calling the show() member function.  Use the global defines
    SINGLE and DOUBLE for the style parameter.

int getborder()
    Returns the current border style, SINGLE or DOUBLE.  Use the global
    defines SINGLE and DOUBLE for this comparison.

void cfgd(int fore);
    Use this function to change the foreground color of the window.  The
    border() function must be called to redraw the border in the new color.
    The fore parameter represents the color to change to.

void cbgd(int back);
    Use this function to change the background color of the window.  The
    fill() function must be called to redraw the background in the new
    color.  The back parameter represents the color tochange to.

int getfgd();
    Returns the current foreground color.

int getbgd()
    Returns the current background color.

void fill();
    Causes the interior of the window to be drawn.  This function
    can be called to clear a widow which has been filled with text.

void divider(int direction,int style,int offset);
    Causes a divider to be drawn across the window.  Use the global
    defines HOR and VER for the direction parameter.  Use the global
    defines SINGLE and DOUBLE for the style parameter.  offset represents
    the distance from the top or left of the window to place the divider.

void show();
    Displays the window on the screen.

void zoom();
    Use instead of the show() function to cause the window to be zoomed
    horizontally onto the screen.

void hide();
    Use this function to remove the window from the screen.  The memory
    used to hold the underlying screen image is not freed by a call to
    hide().

void elim();
    This function frees the memory associated with the window. The default
    destructor calls elim() to free this memory before destroying
    the Twindow object.

void title(char[15]);
    This function specifies a title to be placed on the top border of the
    window.  The title is limited to 14 chars.

int istitle();
    Returns non-zero if the window has a title.

int isshown()
    Returns non-zero if the window is currently displayed on the screen.

int isx();
    Returns the left x coordinate of the window.

int isy();
    Returns the top y coordinate of the window.

int isx1();
    Returns the right x coordinate of the window.

int isy1();
    Returns the bottom y coordinate of the window.

int issize();
    Returns the size of the buffer required for holding the underlying
    screen image.

void wprintat(int x,int y,int fgd,int bgd,char *text);
    This function prints the text parameter at coordinates x,y, relative
    to the upper left Twindow coordinate using the respective fgd and bgd
    colors.

void wprintc(int y,int fgd,int bgd,char *text);
    This function prints the text parameter on row y, respective to the
    top of the Twindow, in the specified fgd and bgd colors.

int hit();
    This function returns non-zero if the mouse cursor is currently within
    the bounds of the Twindow object.



                            TMENU

    The Tmenu class has been retained in version 3.0 of the ObjectEase
libraries for compatibility only.  A new menu class, called simply 'menu',
has been developed and should be used for all menuing purposes because of
its greatly enhanced functionality, and ease of use for both the programmer
and the end user.

    Class Tmenu is inherited from Twindow, and therefore inherits much of
the functionaly of a Twindow object.

Members - PRIVATE

int itemcount
    The number of items contained in the menu.

itemarray items
    An array of text items representing the text within the
    menu.

int hifore
    The foreground color of a highlighted menu selection.

int hiback
    The background color of a highlighted menu selection.

int menuchoice
    The value that will be returned to the caller representing the index
    into the menu of the chosen selection.

Members - PUBLIC

void init(int itemcnt,itemarray item,int xpos,int ypos,int width,int fore,
            int back,int hfore,int hback,int shadow,int shadowcolor);

    Call this function to initialize a Tmenu object after declaring a
    variable of this type.  The itemcnt parameter represents the number of
    items in the menu. The item parameter is an array of type itemarray
    and contains the strings to be displayed in the menu.  Index 0 of this
    array must not be used. xpos and ypos indicate the upper left corner
    of the Tmenu on the screen. Width represents the width of the menu
    window.  This variable must be large enough to accomodate the longest
    text string to be displayed within the menu.  The fore and back
    parameters represent the colors of a menu item that is not currently
    highlighted.  The hfore and hback parameters represent the colors in
    which to display a highlighted menu option.  If the shadow parameter is
    non_zero the menu will be displayed with a shadow cast to the right.
    The shadow color parameter represents the color in which text within
    the shadow area will be displayed.

    example:    itemarray items;
                strcpy(items[1],"Selection #1");
                strcpy(items[2],"Last Selection");

                Tmenu theMenu;
                theMenu.init(2,items,10,10,20,15,1,14,5,1,8);

int show(int seconds=0);
    This function displays and activates the menu. It will not return
    until either the RETURN or the ENTER key has been pressed.  The return
    value is the index into the itemarray array of the highlighted menu
    selection.  If the ESCAPE key is pressed the function returns 27.
    Optionally a parameter of seconds can be supplied which will
    cause the menu to time out and return 255.

void move(int newx,int newy)
    This function moves the menu to the newly specified x,y coordinates on
    the screen.  The new coordinates will not take effect until the next
    time the menu is displayed.




                            TSTRING

    A Tstring object can be used to easily retrieve textual information
from the users of your program.  Tstring objects supply a visual editing
field on the screen and can format the text for all caps if so desired.
Two descendants of the Tstring class, Tnumeral and Tdate,
provide specialized classes for capturing formatted numeric and date input.


Supporting Functions

    Though not part of the formal class, the following three functions
provide support for the string formatting functions of Tstring objects.
These functions can be used for other purposes by the programmer.

void beep();
    Causes a beep on the computer speaker indicating that the key
    being pressed cannot be inserted into the Tstring object at the
    current position.

char *strdel(char *orig,int pos);
    This function deletes 1 character from the supplied char * orig at the
    position pos and returns a pointer to the new string.

char *strins(char *orig,int pos,char ch);
    This function inserts the char ch into the text string orig at
    position pos and returns a pointer to the new string.


Members - PRIVATE

char laststring[81]
    This array contains the string as it is being entered and edited by
    the user.

char bar[81]
    This array contains the characters used to display the input field on
    the screen.

int xpos
    The position of the cursor in releation to the left coordinate of the
    input field.

int x
    The left coordinate of the input field.

int y
    The top coordinate of the input field.

int length
    The length of the input field.  The string that is input and returned
    cannot be longer than this value.  Tstrings cannot scroll the text that
    is input into them.

int ucase
    If this value is 1 the text will be converted to uppercase as it is
    enetered.

int escape
    This value is set to 1 if the ESCAPE key is pressed while the Tstring
    is receiving input.

int retrn
    This value is set to 1 if the ENTER key is pressed while the Tstring
    is receiving input.

int tab
    This value is set to 1 if the TAB key is pressed while the Tstring is
    receiving input.

int uparrow
    This value is set to 1 if the UP ARROW key is pressed while the
    Tstring is receiving input.

int dnarrow
    This value is set to 1 if the DOWN ARROW key is pressed while the
    Tstring is receiving input.

int shown
    This value is 1 if the Tstring object is currently displayed on
    the screen.

int barred
    This value is 1 if the input field has been displayed on the screen.

int firstchar
    This value is true each time the Tstring is activated until a key has
    been pressed.

int infgd
    This value represents the foreground color of the input field.

int inbgd
    This value represents the background color of the input field.

Members - PUBLIC

Tstring();
    The default constructor.

~Tstring();
    The default destructor.

void init(int xpos,int ypos,int len,int uppercase)
    This function must be called to initialize a Tstring object after a
variable of this type has been declared.  The xpos and ypos parameters
represent the left and top coordinates of the input field on the screen.
The len parameter represents the length of the input field.  If the
uppercase parameter is non-zero the text will be converted to uppercase as
it is entered into the input field.

    example:    Tstring theString;
                theString.init(10,10,20,0);

void draw_bar();
    This function is called internally by the Tstring object to draw the
    input field on the screen.

void show();
    This functions displays the input field on the screen.

void input();
    This functions checks to see if a character is waiting to be placed
    into the input field.  If so it processes the character appropriately.
    If not, it returns immediately.  This function can be used to provide a
    sort of multitasking.

    example:    int i=0;
                int done=0;
                Tstring theString;

                while(!done) {
                    theString.input();
                    i++;
                    vprintat(1,1,14,0,"%d",i);
                    }

void get_input()
    This function will receive input into the Tstring object until either
    the ENTER ot the ESCAPE key has been pressed.

void get_form_input()
    This function will receive input into the Tstring object until either
    the ENTER, ESCAPE, TAB, UP ARROW, or DOWN ARROW key has     been pressed.

void get_form_mouse_input()
    This funtion works the same as get_form_input() and in addition will
    return it the left mouse button is pressed while the mouse cursor is
    positioned within the input field.

void reset()
    Clears the input string.

void preset(char *text)
    This function allows a string to be inserted into the input field
    before it is displayed on the screen.

void erase()
    This function visually clears an input field.

char *getstring()
    Use this function to return a pointer to the string contained within
    the Tstring object.

    example:    Tstring theString;
                theString.init(10,10,20,0);
                theString.get_input();

                vprintat(1,1,14,0,"%s",theString.getstring());

int escapehit();
    Returns 1 if the ESCAPE key was pressed while editing the Tstring
    field.

int returnhit();
    Returns 1 if the ENTER key was pressed while editing the Tstring
    field.

int tabhit();
    Returns 1 if the TAB key was pressed while editing the Tstring field.

int uparrowhit();
    Returns 1 if the UP ARROW key was pressed while editing the Tstring
    field.

int dnarrowhit();
    Returns 1 if the DOWN ARROW key was pressed while editing the Tstring
    field.

int isshown();
    Returns 1 if the Tstring field is currently displayed on the screen.

int isbarred();
    Returns 1 if the input field has been displayed on the screen.

int hit();
    Returns 1 if the mouse cursor is currently within the Tstring field.

void setincolors(int fgd,int bgd);
    Sets the foreground and background colors of the input field.  By
    default these colors are yellow(14) on blue(1).



                            TNUMERAL

    A Tnumeral object functions very much like a Tstring object, except
that it has been specialized for the input and return of numeric data.
Almost all of the same member functions are used.  Those that differ from,
or are in addition to Tstring are listed here:

Members - PROTECTED

int real;
    This value is 1 if the value being entered is a float value, 0
    otherwise.

Members - PUBLIC

void init(int xloc,int yloc,int length,int int_or_float);
    xloc and yloc specify the coordinates of the left and top of the input
    field.  Length specifies the maximum length of the numeric string to
    be input. int_or_float should be 0 to indicate that the value to be
    entered is an integer, or 1 to indicate the value will be a float.
    Float values can include the '.'  character.  Both ints and floats can
    include a '-' sign.

float getfloat();
    Returns a float value representing the text string in the input field.

int getint();
    Returns and int representing the text in the input field.

long getlong()
    Returns a long representing the text in the input field.




                            TDATE

    Like Tnumeral, Tdate is a derivative of the Tstring class, but in this
case has been specialized for the input of date values.  Again, all of the
member functions from Tstring can be utilized.  Following are those that
differ.

Members - PROTECTED

int date_ok;
    This value is 1 if the date entered is a valid date, 0 otherwise.

Members - PUBLIC

void init(int xloc,int yloc);
    xloc and yloc specift the starting coordinates of the input field.

void validate();
    Not normally called by the programmer.  The class uses this function
    to verfify that the date entered is a valid date.

int verified();
    Returns 1 if the date entered has been validated, 0 otherwise.

char * getdatestring();
    Returns a char * that points to a text string representing the data
    entered.  If the date field contains the characters "12/31/93" then
    the string that is referenced will also contain the string
    "12/31/93"

long getdate();
    Returns a long value representing the date entered.  If the date field
    contains the characters "12/31/93" the value returned will be 931231.



                            TBUTTON

    A Tbutton provides a user interface object which simulates the actions
of a pushbutton.  An additional style of Tbutton, called Tbutton3d, has
been added in this version of the ObjectEase libraries.  It has all of the
same functionality of a standard Tbutton, but it's screen appearance is
different.  Use this documentation for both the Tbutton and Tbutton3d
classes.

Members - PROTECTED

int xpos
    The left x coordinate of the button on the screen.

int ypos
    The top y position of the button on the screen.

int width
    The width of the button on the screen.

int pressed
    This value is 1 if the button is currently pressed, 0 otherwise.

int hilite
    This value represents the index into the string of the highlighted
    character.

char button[81]
    The text string that is actually the button on the screen.

char shadow[81]
    The text string which forms the button's shadow on the screen.

char id[41]
    The actual text that is displayed on the button.

Members - PUBLIC

Tbutton();
    The default constructor.

~Tbutton()
    The default destructor.

void init(int xpos,int ypos,int char *text,int hilite_pos);
    Call this function to initialize the Tbutton object before displaying
    it on the screen.  xpos and ypos represent the left and top
    coordinates of the Tbutton.  The text parameter represents the text to
    be displayed on the button.  hilite_pos represents the index into the
    string of the letter to be highlighted.

    example:    Tbutton mybutton;
                mybutton.init(10,10,"Hello",1);

    This example will create a button with the word "Hello" displayed on
    it with the letter "H" highlighted.

void show(int bgd);
    Displays the Tbutton on the screen.  The bgd value represents color of
    the background onto which the Tbutton will be displayed.  The Tbutton3d
    version of this function does not take any parameters.

int buttonpressed();
    Returns 1 if the Tbutton is currently pressed, 0 otherwise.  For
    compatibility, use the ispressed() function instead of buttonpressed().

int hit();
    Returns 1 if the mouse cursor is currently positioned over the
    Tbutton, 0 otherwise.

void press(int bgd);
    Displays the Tbutton on the screen in its depressed state.  The bgd
    value represents the color of the screen background on which the
    Tbutton will be displayed.  The Tbutton3d version of this function
    does not take any parameters.

int ispressed();
    Returns 1 if the Tbutton is currently depressed, 0 otherwise.




                            TCHECKBOX

    A Tcheckbox can be used in text mode as an indicator for making multple
choice selections.  When used in a group, multiple checkboxes can be
checked, or it can be used more like a radiobutton, where only one
selection from a group can be checked at any one time.

Members - PROTECTED

int xpos
    The left x coordinate of the Tcheckbox

int ypos
    The top y position of the Tcheckbox.

int fgd
    The foreground color of the Tcheckbox.

int bgd
    The background color of the Tcheckbox

int checked
    This value is 1 if the Tcheckbox is currently checked, 0 otherwise.

Members - PUBLIC

Tcheckbox();
    The default constructor.

~Tcheckbox();
    The default destructor.

void init(int xpos,int ypos,int fgd,int bgd)
    Call this functions to initialize the Tcheckbox before displaying it
    on the screen.  The xpos and ypos values represent the left and top
    coordinates of the Tcheckbox.  The fgd and bgd values represent the
    colors in which the Tcheckbox will be displayed.

void show();
    Displays the Tcheckbox on the screen.

void grabcursor();
    Causes the cursor to appear within the Tcheckbox
    object.  If the cursor has been turned off by a call to cursoroff(), it
    will not be visible, but it will still be positioned within the
    Tcheckbox.

int hit();
    This function returns 1 if the mouse cursor is currently positioned
    over the Tcheckbox, 0 otherwise.

void check();
    Causes the Tcheckbox to appear checked.

void uncheck();
    Causes the Tcheckbox to appear unchecked.

int ischecked()
    Returns 1 if the Tcheckbox is currently checked, 0 otherwise.




                            SOUNDQ

    The SoundQ class is useful for having the computer make sounds or play
music in the background, allowing foreground processing to continue
undisturbed.  Most of the functions affecting this class are actully not
part of the class.  This is because they act on data through an interrupt
procedure which is not part of the class itself.

Members - PROTECTED

float speed_factor
    This value represents a speed factor representing the speed of the
    sound playback.  The default play back speed is 1.

Members _ PUBLIC

SoundQ();
    The default constructor.

~SoundQ();
    The default destructor.

void play(int freq, int duration);
    Places a note at the specified frequency and duration into the sound
    queue for playback.  The sound queue will begin playing immediately
    and will continue as long as there are notes available in the queue.
    Use the values defines in TUI.H to more easily specify the freq and
    duration parameters.

    example:    SoundQ sq;
                sq.play(C,HN);
                sq.play(D,HN);
                sq.play(E,HN);
                sq.play(F,HN);
                sq.play(G,HN);
                sq.play(A,HN);
                sq.play(B,HN);
                sq.play(C*2,HN);

    This example plays a C scale in half notes.

void adjust_speed(float);
    Sets the speed factor at which to play back the sound.  The default
    value is 1. To cause the speed of the music to double call
    adjust_speed()with a parameter of 2.

Functions - THESE APPEAR OUTSIDE OF THE CLASS BODY

void empty_sound_queue();
    Empties all notes out of the queue and causes the sound to stop
    immediately.

void init_sound();
    Do NOT call this function.  It is called by the default constuctor.

void restore_sound();
    Do NOT call this function.  It is called by the destructor.

int submit_sound(int freq,int duration);
    Do NOT call this function.  It is called by the play() member function.




                            OPTION

    The option class is used by the menu and listbox classes.  It
represents a single line in the menu or listbox, and has no useful
functionality of its own.  For this reason the option class is not
documented.  There is no loss of functionality to the programmer by the
lack of this documentation.  The functionality of this class can easily be
duplicated by the programmer.



                        PULLDOWN


        The pulldown class is the replacement for the Tmenu class.
Unlike the Tmenu, a pulldown object can be navigated with the
keyboard, the mouse , or both. The programmer also has complete
control over the value returned for a specific menu choice. The
menu can also display separator bars to logically group sections
of a pulldown object.

Members - PROTECTED

friend menubar
    The menubar which is the parent of the pulldown. Can be NULL

int nfg
    The fgd color of an unhighlighted menu option

int nbg
    The bgd color of an unhighlighted menu option

int hfg
    The fgd color of a highlighted menu option

int hbg
    The bgd color of a highlighted menu option

int x
    The left x coordinate of the pulldown menu

int y
    The top y coordinate of the pulldown menu

TWindow frame
    A Twindow object which serves as the frame for the pulldown menu

int shown
    Indicates the visible status of the pulldown object

int width
    The width of the pulldown object

int height
    The height of the pulldown object

int num_options
    The number of options contained in the pulldown menu

int part_of_menubar
    Indicates whether the pulldown object is the child of a menubar
    object

char hotkeys[20]
    Contains the programmer defined accelerator keys for accessing
    the pulldown menu

int kbtrigger_index
    The index into the options of the pulldown of the option that
    is selected using keyboard accelerators


Menbers - PUBLIC

option options[20]
    The array of options within the pulldown. A pulldown menu is
    limited to 20 options.

void init(int norm_fgd,int norm_bgd,int hi_fgd,int hi_bgd,
            int xpos,int ypos)

    Call this function to initialize the pulldown object after
    declaring a variable of this type. The norm_fgd and norm_bgd
    parameters represent the unhighlighted fgd and bgd colors. The
    hi_fgd and hi_bgd parameters represent the fgd and bgd colors of
    a highlighted option. xpos and ypos are the left and top
    coordinates at which the pulldown should be displayed.

    example:    pulldown pd;
                pd.init(BLACK,WHITE,YELLOW,RED,10,10);

void set_option(int index,char *text,int ret_value)
    Adds an option to the menu. Call this function to fill the menu
    after declarinring and initializing it. The index parameter is
    the index into the array of options in the pulldown. The *text
    parameter is the text that you want to be displayed in the menu,
    and the ret_value is the value that will be returned if this
    menu option is chosen. To add a separator bar to the menu make
    the *text parameter a "-" .

    NOTE: The *text parameter can contain the '&' character to
        indicate the letter to be highlighted and represent the
        accelerator for that particular option. For instance, to
        highlight the letter 'x' in the word "Exit" and have it
        serve as an accelerator, enter the text as "E&xit".

    example:    pulldown pd;
                pd.init(BLACK,WHITE,YELLOW,RED,10,10);

                pd.set_option(0,"&Option #1",1);
                pd.set_option(1,"&Second Option",2);

void determine_width_height()
    Do NOT call this function directly. It is used internally to
    determine the width and height to display the pulldown based on
    the strings it will contain.

void display()
    Displays the pulldown menu on the screen.

void position(int xpos,int ypos)
    Positions the pulldown's upper left corner at xpos,ypos.

int trackmenu()
    This is the main engine of the pulldown object. It captures all
    input both from the keyboard and the mouse. The return value is
    127 if the ESCAPE key has been hit. Be careful not to duplicate
    this value with one of your own options. Otherwise, the return
    value is the value that the programmer has defined in the
    set_option call for the option that has been selected.

    example:    pulldown pd;
                pd.init(BLACK,WHITE,YELLOW,RED,10,10);

                pd.set_option(0,"&Option #1",1);
                pd.set_option(1,"&Second Option",2);

                int choice=pd.trackmenu();
                switch(choice) {
                    case 1:...
                    case 2:...
                    }

void hide()
    removes the pulldown menu from the screen.

int is_shown()
    Returns 1 if the menu is currently displayed, 0 otherwise.

void adjust_option_widths()
    Do NOT call this function directly. It is used internally by
    the class.

void adjust_pos_to_menubar(int)
    Do NOT call this function directly. It is used internally by
    the class.

int is_part_of_menubar()
    Returns 1 if the pulldown is the child of a menubar
    object, 0 otherwise.


PULLDOWN NOTE:
    YOU CAN CAUSE CERTAIN PULLDOWN OPTIONS TO APPEAR IN A UNIQUE
    COLOR BY CALLING THE self_color(int fgd,int bgd,int hfgd,int
    hbgd) MEMBER OF THE OPTION CLASS.

    example:    pulldown pd;
                pd.init(1,7,7,1,10,10);

                pd.set_option(0,"&Option 1",1);
                pd.set_option(1,"&Second Option",2);

                pd.options[1].self_color(3,7,7,3);



                            MENUBAR

    A menubar object can serve as a parent to several pulldown
objects. A menubar is typically a bar across the top of the screen
with various options which will invoke the appropriate pulldown
menu.

Members - PROTECTED

option *titles[10]
    An array of pointers to options which represent the options in
    the menubar. A menubar can have a maximum of 10 titles.

pulldown *pd[10]
    An array of pointers to pulldowns. A menubar can have a maximum
    of 10 associated pulldown menus.

int nfg
    The fgd color of an unhighlighted option

int nbg
    The bgd color of an unhighlighted option

int hfg
    The fgd color of a highlighted option

int hbg
    The bgd color of a highlighted option

int num_titles
    The number of titles currently in the menubar.

char hotkeys[10]
    An array of characters which act as accelerators for the
    menubar titles.

int kbtrigger_index
    The index into the array of titles for the option that was
    selected by a keyboard accelerator.

Members - PUBLIC

menubar()
    The default constructor

~menubar()
    The defaule destructor

void init(int nfg,int nbg,int hfg,int hbg)
    Call this function to initialize a menubar object after
    declaring a variable of this type. The 4 parameters represent
    the normal (unhighlighted) fgd and bgd colors, and the
    highlighted fgd and bgd colors.

void set_title(int index,char *text,pulldown *)
    Adds a title and an association with a pulldown menu to the
    menubar.

    NOTE: The *text parameter can contain the '&' character to
    indicate the letter to be highlighted and represent the
    accelerator for that particular option. For instance, to
    highlight the letter 'F' in the word "File" and have it
    serve as an accelerator, enter the text as "&File".

    example:    menubar mb;
                pulldown pd;

                pd.init(BLUE,WHITE,WHITE,BLUE,10,10);
                //The xpos and ypos parameters here are irrevelant
                //because the pulldown will be positioned by the
                //menubar object

                pd.set_option(0,"&Open",1);
                pd.set_option(1,"-",0);
                pd.set_option(2,"E&xit",2);

                mb.init(BLUE,WHITE,WHITE,BLUE);
                mb.set_title(0,"&File",&pd);

void display()
    Displays a menubar object on the screen

int trackbar()
    This is the main engine of the menubar object. It handles all
    mouse and keyboard input to navigate the menubar. The up and
    down arrow keys will move the highlight within a single
    pulldown. The right and left arrow keys will move to the next or
    previous pulldown. The return value is 127 if the ESCAPE key
    was hit, or it is the value of the pulldown option as defined
    by the programmer in the pulldown::set_option call.

    example:    menubar mb;
                pulldown pd;

                pd.init(BLUE,WHITE,WHITE,BLUE,10,10);
                //The xpos and ypos parameters here are irrevelant
                //because the pulldown will be positioned by the
                //menubar object

                pd.set_option(0,"&Open",1);
                pd.set_option(1,"-",0);
                pd.set_option(2,"E&xit",2);

                mb.init(BLUE,WHITE,WHITE,BLUE);
                mb.set_title(0,"&File",&pd);

                int choice=mb.trackbar();
                if(choice==2)
                    Exit the program

int hit()
    Returns 1 if the mouse cursor is currently over the menubar, 0
    otherwise

int mouse_triggered()
    Returns 1 if the menubar has been activated by clicking the
    left mouse button while the cursor is positioned over a menubar
    title, 0 otherwise.

int kb_triggered()
    Returns 1 if the menubar has been activated by a keyboard
    accelerator, 0 otherwise.

    NOTE:   The menu is activated from the keyboard by pressing the
    ALT key along with the highlighted letter from the desired
    menubar title. For example, if the first titles in a menubar is
    "&File", it would be activated by presseing ALT-F.

int triggered()
    Returns mouse_triggered() | kb_triggered()



                               PAD

    The PAD class is solely for use in the scroll bar class and
therefore is not documented here. There is not other useful
functionality for this class.



                             SCROLLBAR

    The scrollbar object is used to visually control the contents
of a particular screen area, allowing the user to manipulate the
screen by changing the position of the scrollbar. It is important
for the programmer to remember that the scrollbar object does not
manipulate the screen in any way on its own, it merely return a
value which must be used by the programmer to make any necessary
changes in display.


Members - PROTECTED

int x
    The left x coordinate of the scrollbar

int y
    The top y coordinate of the scrollbar

pad *thumbpad
pad *increase
pad *decrease
    Pointers to pad objects which represent the thumbpad and the
    buttons at the ends of the scrollbar used for changing the
    scrollbar's value.

int vertical
    Represents the orientation of the scrollbar.

int length
    The total overall length of the scrollbar object

int small_d
    The amount that the scrollbar's value will change if one of the
    end buttons is pressed.

int large_d
    The amount that the scrollbar's value will change if it is
    clicked between the thumbpad and one of the end buttons.

long minimum
    The minimum value of the scrollbar

long maximum
    The maximum value of the scrollbar

long value
    The current value of the scrollbar

int changed
    Indicates the status of the scrollbar

Members _ PUBLIC

void init(int xpos,int ypos,int length,int vert,long min,long max)
    Call this function to initialize a scrollbar object. The xpos
    and ypos parameters are the left and top coordinates of the
    scrollbar. Length represents the number of screen characters
    long to make the scrollbar. Use the global #defines HORIZONTAL
    and VERTICAL for the vert parameter, The min and max parameters
    represent the range of the scrollbar's value.

    example:    scrollbar sb;
                sb.init(10,5,15,VERTICAL,0,10);

void show()
    Displays the scrollbar on the screen.

int thumbpad_hit()
    Returns 1 if the mouse cursor is currently positioned over
    the thumbpad, 0 otherwise.

int decrease_hit()
    Returns 1 if the mouse cursor is currently positioned over the
    top button of a VERTICAL scrollbar or the left button of a
    HORIZONTAL scrollbar, 0 otherwise.

int increase_hit()
    Returns 1 if the mouse cursor is currently positioned over the
    bottom button of a VERTICAL scrollbar or the right button of a
    HORIZONTAL scrollbar, 0 otherwise.

int hit()
    Returns 1 if the mouse cursor is positioned over the scrollbar
    object, 0 otherwise.

void track_scrollbar()
    Captures all mouse input into the scrollbar and adjusts its
    appearance and value accordingly.

    example:    scrollbar sb;
                sb.init(10,5,15,VERTICAL,0,10);

                while(!the_mouse.RBP()) {
                    if(sb.hit())
                        sb.track_scrollbar();
                    }

long get_value()
    Returns the current value of the scrollbar.

int value_changed()
    Returns 1 if the value of the scrollbar has changed since the
    last call to get_value().

void set_small_d(int val)
    Sets the amount to change the value of the scrollbar if the end
    buttons are clicked. This value is 1 by default.

void set_large_d(int val)
    Sets the amount to change the value of the scrollbar if the
    users clicks between the thumbpad and one of the end buttons.
    This value is 10 by default.

void set_maximum(long val)
    Sets the value to be used as the maximum scrollbar value

void set_minimum(long val)
    Sets the value to be used as the minimum scrollbar value

void update_value(long)
    Sets the current value and adjusts the scrollbar's appearance
    accordingly.




                            LISTBOX

    A listbox object can be used similarly to a pulldown menu to
make a single selection from a list of options. Unlike a pulldown,
a listbox has the capability to scroll, so that it may contain
many more options than are currently visible on the screen. The
listbox maintains and navigates a list of optionrec structures
which represent the options in the list.

Members - PROTECTED

int x
int y
    The upper left coordinates of the listbox object

optionrec *listroot
    The root of the list of optionrecs

optionrec *listend
    The end of the list of optionrecs

optionrec *currentsel
    A pointer to the currently selected optionrec

Twindow box
    The Twindow object which serves as the frame for the listbox

scrollbar sbar
    The listbox's scrollbar

int selected_index
    The index into the list of the currently selected option

char *selected_string
    The text of the currently selected option

int option_string_length
    The length of the strings in the list

int changed
    Represents the status of the listbox

int size_forced
    Represents whether the listbox has sized itself, or the
    programmer has determined the size at which to display.

int forced_width
    The width that the programmer has determined for the listbox

int forced_height
    The height that the programmer has determined for the listbox

Members _ PUBLIC

listbox()
    The default constructor

~listbox()
    The default destructor

void init(int xpos,int ypos,int num_displayed,int winfgd,int winbgd,
            int hfgd,int hbgd)
    Call this function to initialize a listbox object. The xpos and
ypos parameter are the upper left screen coordinates. The
num_displayed value is the number of options that can be displayed
in the listbox, NOT the number that it can hold, only the number
that it can display at one time. The winfgd and winbgd parameters
are the fgd and bgd colors of the window and unhighlighted
options. The hfgd and hbgd parameters are the fgd and bgd colors of
a highlighted option.

    example:    listbox lb;
                lb.init(5,5,5,15,1,1,7);

void force_size(int width,int height)
    By default a listbox will determine the width
    and height at which it should be displayed. Use this function to
    override these default value and force it to be displayed at a
    chosen size.

void set_highlight_position(int index)
    Moves the highlight to the position specified in index.

void append_item(char *text)
    Use this function to add strings to the listbox. Strings can
    only be added to the end of the list.

    example:    listbox lb;
                lb.init(5,5,3,15,1,1,7);

                lb.append_item("Item Number 1");
                lb.append_item("Second Item");

void show()
    Displays the listbox on the screen

void show_options(int index)
    Used internally to show a particular segment of the list

void hide()
    Removes the listbox from the screen.

void scroll_list_up()
void scroll_list_down()
    Used internally to position the list within the listbox

int tracklist()
    The main engine of the listbox object. Captures all keyboard
    and mouse input and adjusts the appearance of the listbox
    accordingly. The return value is 1 if successful, 0 otherwise.

    example:    listbox lb;
                lb.init(5,5,3,15,1,1,7);

                lb.append_item("Item Number 1");
                lb.append_item("Second Item");

                int choice=lb.tracklist();

int options_displayed
    The number of options currently displayed

int options_in_list
    The number of options currently in the list

int option_width
    The width if the strings in the list

int shown
    The current visible status

int nfg
    The fgd color of an unhighlighted option

int nbg
    The bgd color of an unhighlighted option

int hfg
    The fgd color of a highlighted option

int hbg
    The bgd color of a highlighted option

int index_at_top
    The index into the list of the option currently displayed at
    the top of the list.

int index at bottom
    The index into the list of the option currently displayed at
    the bottom of the list.

int hit()
    Returns 1 if the mouse cursor is currently positioned over the
    listbox, 0 otherwise.

int is_current_index()
    Returns the index into the list of the currently selected option

char *is_current_string()
    Returns a pointer to the string of the option that is currently
    selected

int is_selected_index()
    Returns the index into the list of the selected option

char *is_selected_string()
    Returns a pointer to the string of the selected option

void deactivate()
    Turns off the highlighting of the selected option

void reactivate()
    Turns on the highlighting for the currently selecting option

int active
    Indicates the current status

int part_of_structure
    This field is 1 if the listbox is part of another structure,
    such as a directory box.

int Getx()
    Returns the left x coordinate of the listbox

int Gety()
    Returns the top y coordinate of the listbox

int list_index
    The current index into the list




                            DIRBOX

    The dirbox object provides a convenient way to access the
directory and file structure of a disk. Because of the large
memory requirements of the dirbox, it should be contained to a very
small scope so as not to interfere with the other parts of the
application.

Members _ PROTECTED

Twindow *box
    The frame of the dirbox

listbox *drive
    listbox containing the available drives

listbox *directory
    listbox containing the available directories

Tbutton *OK
    The OK button

Tbutton *CANCEL
    The CANCEL button

char fullpath[]
    The current path displayed in the dirbox

char returnpath[]
    The path, including the filename and extension that will be
    returned to the caller

Tstring *filename
    The currently selected filename

int shown
    Indicates the current status

int turn
    A counter representing the region of the dirbox that currently
    has the input focus

char dirmask[]
    A mask used to determine which files are listed in the dirbox

int intnumber
    The value of the "Abort, Retry, Fail" interrupt

void interrupt (*)(...)
    A pointer to the "Abort, Retry, Fail" interrupt

Members - PUBLIC

dirbox()
    The default constructor

~dirbox()
    The default destructor

void show()
    Displays the dirbox on the screen

void hide()
    Removes the dirbox from the screen

char *trackdir()
    The main engine of the dirbox object. Captures all mouse and
    keyboard input and updates the internal variables accordingly.
    The return value is a pointer to the currently selected file.

    example:    {
                    dirbox db;
                    char file[MAXPATH];
                    strcpy(file,db.trackdir());
                }

    NOTE: The above section of code is enclosed in its own braces
            to limit the scope of the dirbox object and keep a
            maximum amount of memory available for the application.

void print_current_path()
    Used internally to display the current path

void change_directory(char *)
    Used Internally

void fill_directory_list()
    Used internally to populate the list of available directories

void fill_drive_list()
    Used internally to populate the list of available drives

void set_mask(char *mask)
    Use this function to specify a mask for a particular file type.
    By defaule this mask is "*.*"

static void interrupt _handler(...)
    This handler is responsible for printing an error if the disk
    is not ready in the currently selected drive.





    This completes the documentation of the TUI portion of the
ObjectEase libraries.





























                         GUI library reference

    The GUI.LIB library provides a complete set of graphics mode
user interface objects, as well as some supplemental functions that
you'll find most useful.  The classes are described in the
following section, with the standalone function calls being
described first.


Standalone Function Calls

Gprintxy(

void dlay(int ticks);
    Causes a program delay for the specified number of timer ticks.
    The timer ticks at 18.2 times per second.

    long getticks();
    Returns the timer value representing the current time expressed
    in timer ticks.

int altkey();
    Returns 1 if the ALT key is currently pressed, 0 otherwise.

int shiftkey();
    Returns 1 if the SHIFT key is currently pressed, 0 otherwise

void flushkeys();
    Empties out the keyboard type ahead buffer

unsigned char getvidmode();
    Returns the current video mode. This value can be compared
    against the Borland defined values C40, C80, etc...

void beep();
    Causes the PC speaker to emit a beep

char *strdel(char *text,int pos);
    Deletes the character at position pos from the string text and
    returns a pointer to the new string.

char *strins(char *text,int pos,char ch);
    Inserts the character ch into the string text at position pos,
    and returns a pointer to the new string.

void gprintxy(int xloc,int yloc,char *fmt,...);
    Use like the standard Printf() function to print text on the
    graphics screen.




                            Mcursor


    The following data and functions are all part of the Mcursor
class, which handles mouse functionality in both the text and graphics
modes.  Certain mouse functions are different, however, in the different
video modes.

Global Variables

    _MX An integer value representing the current x value of the mouse.
This varible is updated with every call to get_status().  The LBP() and
RBP() function call call get_status().

    _MY An integer value representing the current y value of the mouse.
This varible is updated with every call to get_status().  The LBP() and
RBP() function call call get_status().

    Using the above variable to get the mouse position can improve program
performance because a function call is not necessary to retrieve
these values.

void far mhandler();
    This is the interrupt handler for the mouse which allows
    capturing such mouse events as double clicks.

MCursor the_mouse
    Since the mouse is used by other classes a global MCursor
    variable is defined in the library.  To use the mouse in your
    programs simply declare "extern Mcursor the_mouse" at the top of
    your source module(s).


Members - PRIVATE

int shown
    Indicates whether the mouse cursor is currently visible or not.

int current
    Indicates the shape of the currently selected cursor

int xpos
    The current x position of the mouse cursor.

int ypos
    The current y position of the mouse cursor.

void mouse_interrupt();
    The current procedure acting as the mouse handler.

int m1
    Used as the AX register variable in mouse calls.

int m2
    Used as the BX register variable in mouse calls.

int m3
    Used as the CX register variable in mouse calls.

int m4
    Used as the DX register variable in mouse calls.

int button
    Represents the button being pressed or tested, left or right.

int count
    Keeps track of the number of times a button has been pressed.

int disabled
    If this variable is 1 the mouse cannot be shown.

int handler_installed
    This value is 1 if the mouse handler has been installed, 0 if not.

int eventmask
    Specifies which events the mouse handler captures.  By
    default only left mouse button presses are captured.

void ClearHandler()
    This function disables the mouse handler.

void InstallHandler()
    This function installs the mouse handler.  The mouse handler is
    installed by default by the arm() function.

Members - PUBLIC

Mcursor()
    The default constructor.

~Mcursor()
    The default destructor.

int init()
    Call to initialize the mouse at the beginning of your program. If the
    return value is 0, there is no mouse present.

    example:    extern Mcursor the_mouse;
                int mouse_present;
                mouse_present=the_mouse.init();

void changeto(int shape)
    Changes the shape of the mouse cursor. Use the global #defines
    in GUI.H for the value of shape.

void get_status()
    This function returns the current state of the mouse buttons.  It is
    not normally called by the programmer.

void show()
    This function makes the mouse cursor visible if it has not been
    disabled by a call to unarm();

void hide()
    This function makes the mouse cursor invisible.

void set_hor_bounds(int min,int max)
    This function sets the bounds of mouse movement on the x axis.  The
    min value represents the left boundary of mouse movement, and the max
    value represents the right boundary.

void set_ver_bounds(int min,int max)
    This function sets the bounds of mouse movement on the y axis.  The
    min value represents the top boundary of mouse movement, and the max
    value represents the bottom boundary.

void conditional_off(int x1,int y1,int x2,int y2)
    This function makes the mouse cursor invisible when it is in the
    rectangle bounded by x1,y1,x2,y2.

void position(int x,int y)
    This function moves the mouse cursor to the screen position defined in
    x,y.

int LBP()
    Returns 1 if the left mouse button is currently pressed, 0 otherwise.

int RBP()
    Returns 1 if the right mouse button is currently pressed, 0 otherwise.

int mousex()
    This function returns the current x coordinate of the mouse cursor.
    Use the global value _MX to avoid this function call.

int mousey()
    This function returns the current y coordinate of the mouse cursor.
    Use the global value _MY to avoid this function call.

int mx()
    Same as mousex().

int my()
    Same as mousey().

void unarm()
    This function turns makes the mouse cursor invisible and does not
    allow it to be re-shown by the show() call.  To re-show the cursor
    you must call arm().

void arm()
    This function shows the mouse cursor and allows future calls to show()
    to do the same.

int LBDCLK()
    This function returns 1 if the left mouse button has been double
    clicked, 0 otherwise.  The left mouse button must be pressed twice
    within 1/2 second (9 timer ticks) for LBDCLK to return 1.

long thistick
    Represents the current timer tick at the time of the mouse event.  Not
    normally used by the programmer.

long prevtick
    Represents the timer tick at the time of the previous mouse event.
    Not normally used by the programmer.

int doubleclicked
    This value is checked by the LBDCLK() function.  It is set by the
    mouse handler.  Not normally used by the programmer.





                                POINT

    The point class serves as the base class for all of the other
graphics mode classes. As such, it contains the data members and
functions which are common to the other classes derived from point.
The point class by itself has no valuable purpose.

Members - PROTECTED

int x
    The x coordinate of the point

int y
    The y coordinate of the point

int color
    The color of the point

void far *background
    A pointer to a memory buffer containg the underlying screen
    image.

long backgroundsize
    The size of the buffer containing the underlying screen image.

char tempfile[MAXPATH]
    The name of a temporary file used to store the underlying
    screen image

int image_is_on_disk
    Indicates the current placement of the buffer comtaining
    the underlying screen image,

Members - PUBLIC

Point()
    The default constructor

~Point()
    The default destructor

void elim()
    Frees the memory associated with the *background data member

int Getx()
    Returns the x coordinate

int Gety()
    Returns the y coordinate

int Getcolor()
    Returns the color associated with the point

int write_background()
    Writes the background buffer to disk. Returns 1 if successful,
    0 otherwise.

int read_background()
    Fills the background buffer by reading the image off of the
    disk. Returns 1 if successful, 0 otherwise.






                                    GSTRING

    The Gstring class provides a convenient way to gather user input while
in the graphics modes.


Members - PROTECTED

int xpos
    The left x coordinate of the input field

int ypos
    The top y coordinate of the input field

int strlength
    The length of the string that has been input in pixels

int height
    The height of the input field

int ucase
    Indicates whether or not the string is to be in all upper case

char laststring[81]
    The string being editted

int shown
int wasshown
    Indicates the current and previous visible states of the input field

int outlined
int was outlined
    Indicates the current previous outlined states of the input field

int escape
    Indicates that the escape key was pressed

int retrn
    Indicates that the ENTER key was pressed

int tab
    Indicates that the tab key was pressed

int uparrow
    Indicates that the up arrow key has been pressed

int dnarrow
    Indicates that the down arrow key has been pressed

int infgd
    The fgd color of the input field

int inbgd
    The bgd color of the input field

int firstchar
    TRUE until a character has been entered

int curpos
    The current index into the string at which editting is taking place

int curson
    Indicates the flashing state of the cursor

void showcurs()
    Makes the flashing cursor visible

void hidecurs()
    Hides the flashing cursor();

long last_tick
    The clock tick of the last mouse click

int clickcount
    The number of times that the input field has been clicked by the mouse
    within the last 1/2 second

Members -PUBLIC

Gstring()
    The default constructor

~Gstring
    The default destructor

void elim()
    Frees the memory that is associated with the buffer containing the
    underlying screen image

void init(int xloc,int yloc,int length,int uppercase,int savebgd=0)
    Call this function to initialize a Gstring object. The xloc and yloc
    parameter represent the upper left coordinates of the input field.  The
    length parameter refers to the number of characters that the input
    field will hold. If uppercase is non-zero, then all input is forced
    into upper case. The savebgd parameter indicates whether or not the
    underlying screen image should be captured to a buffer before drawing
    the input field on the screen. By default, this value is 0.

    example:    Gstring mystring;
                mystring.init(10,10,20,0);

void reinit(int xloc,int yloc,int uppercase,int savebgd=0)
    This function allows a Gstring object to be re-initialized after a
    previous call to init().

void show()
    Displays a Gstring object on the screen

void input()
    The main input function. The other input function repeatedly pass
    through this function checking for certain characters.

void get_input()
    Call this function to get user input. The function will terminate
    on the following keys:
        ENTER
        ESCAPE
        TAB

void get_form_input()
    Call this function to get user input. The function will terminate
    on the following keys:
        ENTER
        ESCAPE
        TAB
        UP ARROW
        DOWN ARROW

void get_form_mouse_input()
    Call this function to get user input. The function will terminate
    on the following keys:
        ENTER
        ESCAPE
        TAB
        UP ARROW
        DOWN ARROW
        A LEFT MOUSE BUTTON PRESS

char *getstring()
    Returns a pointer to the string in the input field

void reset()
    Clears out the input field.

void preset(char *text)
    Pleces the specified text into the input field before the user begins
    editting

int isshown()
    Returns 1 if the input field is currently displayed on the screen, 0
    otherwise.

void check_for_blink();
    Used internally to check if it is time to blink the cursor.

int returnhit()
    Returns non-zero if the ENTER key has been pressed

int escapehit()
    Returns non-zero if the ESCAPE key has been pressed

int dnarrowhit()
    Returns non-zero if the down arrow key has been pressed.

int uparrowhit()
    Returns non-zero if the up arrow key has been pressed.

int tabhit()
    Returns non-zero if the tab key has been pressed.

void setincolors(int fgd,int bgd)
    Sets the colors of the input field to the specified fgd and bgd colors.

int hit()
    Returns 1 if the mouse cursor is currently over the input field, 0
    otherwise.

void outline(int color,int offset=0)
    Draws a dotted outline around the input field in the specified color,
    offset pixels from the outside edge of the input field.

void move(int xloc,int yloc)
    Moves the input field to the specified coordinates

void hide()
    Removes the input field from the screen

int Getx()
    Returns the left x coordinate of the input field

int Gety()
    Returns the top y coordinate of the input field

int is_ucase()
    Returns 1 if all letters are being forced to capitals

int clicked()
    Returns 1 if the left mouse button has been pressed while the mouse
    cursor is positioned over the input field.

int LBDCLK()
    Returns 1 if the left mouse button has been pressed twice within 1/2
    second over the input field

int Getlength()
    Returns the length of the string that has been entered


    Gstring example:    Gstring mystring;
                        mystring.init(10,10,20,0);
                        mystring.get_input();

                        gprintxy(10,50,"%s",mystring.getstring());





                                LINE

    Line is a new class that has been added to version 3.0 of ObjectEase.
It is simply that, a class representing a graphic line on the screen.

Members - PROTECTED

int x2
    The x coordinate of the end of the line

int y2
    The y coordinate of the end of the line

int style
    Represents the thickness of the line

Members - PUBLIC

Line()
    The default constructor

~Line()
    The default destructor

int Getx2()
    Returns the x coordinate of the end of the line

int Gety2()
    Returns the y coordinate of the end of the line

int Getstyle()
    Returns an integer representing the line thickness

void init(int xpos,int ypos,int x2pos,int y2pos,int color, int thickness)
    The xpos and ypos represent the starting point of the line. The x2pos
    and y2pos parameters are the coordinates of the end of the line. color
    is the line color, and thickness is a value of 1 for thin lines, and 3
    for thick lines.

    example:    Line ln;
                ln.init(0,0,getmaxx(),getmaxy(),15,1);

void show()
    Displays the Line object on the screen

void outline()
    Displays the Line object as a dashed line.

int starthit()
    Returns 1 if the mouse cursor is within 4 pixels of the starting x,y
    coordinates

int endhit()
    Returns 1 if the mouse cursor is within 4 pixels of the ending x,y
    coordinates

void end_to_start()
    Sets x and y equal to x2 and y2 respectively

void start_to_end()
    Sets x2 and y2 equal to x and y respectively

void swap_ends()
    Sets x = x2 and vice versa
    Sets y = y2 and vice versa

void new_end(int xloc,int yloc)
    Sets a new end point for the line

void new_start(int xloc,int yloc)
    Sets a new start point for the line





                                GTEXT

    The Gtext class is new to version 3.0 of ObjectEase, and provides a
convenient class wrapper for placing text on a graphics screen.


Members - PROTECTED

struct textsettingstype ts
    A structure containing relevant information about the text font

int length
    The length of the text string in pixels

int height
    The height of the text string in pixels

int strlength
    The length of the text string in characters

int fgd
    The foreground color of the text

int bgd
    The background color of the text

char text[41]
    The actual text string

int shown,wasshown
    These values indicate the visible status of the Gtext object

int outline, wasoutlines
    These values indicate the outlined status of the Gtext object

long last_tick
    The clock tick at the time of the last mouse left button press

int clickcount
    Indicates the number of times that the left mouse button has been
    pressed within the last 1/2 second

Members - PUBLIC

Gtext()
    The default constructor

~Gtext
    The default destructor

int Getlength()
    Returns the length of the text in pixels

int Getstrlength()
    Returns the length of the text in characters

int GetSize()
    Returns an integer representing the size of the font

void init(int xloc,int yloc,char *text,int fgd,int bgd,int size,
            int savebgd=0)
    Call this function to initialize a Gtext object. The xloc and yloc
    parameters are the coordinate of the upper left corner. The *text
    parameter is a pointer to the text string. Colors are specified in the
    fgd and bgd parameters. If the savebgd parameter is non-zero, the
    unserlying screen imgae is saved in a buffer before the text is output
    to the screen. By default this value is 0.

    example:    Gtext textline;
                textline.init(10,10,"TEST",2,14,0);

void show()
    Displays the Gtext object on the screen

void hide()
    Removes the Gtext object from the screen

void outline(int color,int offset=0)
    Draws a dotted line around the Gtext object in the specified color,
    offset pixels from the outside of the Gtext object

void reinit(int xloc,int yloc,char *text,int fgd,int bgd)
    Allows the Gtext object to be re-initialized after a previous call to
    init()

int is_shown()
    Returns 1 if the Gtext object is currently visible on the screen

int hit()
    Returns 1 if the mouse cursor is currently positioned over the Gtext
    object

int clicked()
    Returns 1 if the left mouse button is pressed while over the Gtext
    object

int LBDCLK()
    Returns 1 if the left mouse button is clicked 2 times within 1/2
    second over the Gtext object

void move(int newx,int newy)
    Moves the upper left corner of the Gtext object to the new coordinates

char *Gettext()
    Returns a pointer to the string in the Gtext Object

int Getfgd()
    Returns the current fgd color

int Getbgd()
    Returns the current bgd color





                                COLORBUTTON


    A colorbutton is useful for drawing a color selection palette as in
many paint programs.

Members - PROTECTED

int color
    The color of the colorbutton

int width
    The width of the colorbutton

int height
    The height of the colorbutton

Members - PUBLIC

void init(int xloc,int yloc,int width,int height,int color)
    Call this function to initialize a colorbutton object

    example:    This example will create a color palette bar containing
                colors 0 through 15

                colorbutton colors[16];

                for(int i=0;i<16;i++) {
                    colors[i].init(100+(i*15),10,15,15,i);
                    }

void show()
    Displays the colorbutton on the screen

int clicked()
    Returns 1 if the left mouse button is clicked over the colorbutton

int hit()
    Returns 1 if the mouse cursor is currently positioned over the
    colorbutton

int getcolor()
    Returns the color associated with the colorbutton




                            CLOSEBUTTON

    The Closebutton class is used only within the Gwindow class and
therefore is not documented here.




                            ICON

    The Icon class is useful for creating and
manipulating small graphic icons. These icons can easily be created using
the ICONEDIT utility in the ObjectEase package.

Members - PROTECTED

int state
    The current state of the icon

int w
    The width of the icon

int h
    The height of the icon

void far *picture
    A pointer to the bitmap image to be shown in the icon

int shown,wasshown
    Indicate the visible status of the icon

int outlined,wasoutlined
    Indicate the outlined status of the icon

char fn[9]
    The name of the bitmap to be loaded into the icon

char filename[13]
    The complete filename (including the extension) of the file to be
    loaded into the icon

long last_tick
    The clock tick when the left mouse button was last pressed while over
    the icon

int clickcount
    The number of times that the left mouse button has been pressed within
    the last 1/2 second

Members - PUBLIC

Icon()
    The default constructor

~Icon
    The default destructor

void init(int xloc,int yloc,char *file,int savebgd=0)
    Initializes and Icon object. The xloc and yloc paremeters are the
    upper left coordinate at which the Icon will be displayed. The *file
    parameter is a pointer to the name of the file that contains the bitmap
    for the Icon. This parameter does not include a file extension;.ICN is
    assumed. If the savebgd parameter is non-zero, the underlying screen
    image is saved to a buffer before the Icon is displayed on the screen.
    By default this value is 0.

    example:    Icon myicon;
                myicon.init(10,10,"PAINT");

void reinit(int xloc,int yloc,char *file)
    Allows an Icon object to be reinitialized after a previous call to
    init().

void freepicture()
    Frees the memory associated with the bitmap displayed in an Icon

void show()
    Displays an Icon object on the screen.

void choose()
    Causes the Icon to be displayed in negative form, usually indicating
    that it has been selected.

int hit()
    Returns 1 if the mouse cursor is currently positioned over the Icon

int clicked()
    Returns 1 if the left mouse button is pressed while over the Icon

int ispressed()
    Returns 1 if the Icon is currently selected

int outline(int color,offset=0)
    Draws a dotted outline around the Icon in the specified color, offset
    pixels from the outside edge

void hide()
    Removes an Icon object from the screen

void move(int newx,int newy)
    Repositions an Icon at the specified coordinates

char *Getfilename()
    Returns a pointer to a string represting the file name of the file
    containing the bitmap image in the Icon

int LBDCLK()
    Returns 1 if the left mouse button is pressed 2 times within 1/2
    second over the Icon

int Getw()
    Returns the width of the Icon

int Geth()
    Returns the height of the Icon


    Icon example:   Icon myicon;
                    myicon.init(10,10,"PAINT");
                    myicon.show();

                    while(1) {
                        if(the_mouse.LBP()) {
                            if(myicon.hit()) {
                                myicon.choose();
                                while(the_mouse.LBP() && myicon.hit());
                                myicon.show();
                                }
                            }
                        }





                                ACTICON

    An Acticon provides functions similar to those of an Icon object,
however, Acticons provide for animation of the bitmap image displayed on
them. Acticon sequences can easily be created using the ICONEDIT editor
supplied with the ObjectEase libraries.

Members - PROTECTED

void far *picture[32]
    An array of pointers to memory containg the graphic images to be
    displayed on the Acticon. The maximum number of frames is 32.

int state
    The current state of the Acticon

int numpix
    The number of frames in the animation

Members - PUBLIC

Acticon()
    The default constructor

~Acticon()
    The default destructor

void init(int xloc,int yloc,char *file)
    Call this function to initialize an Acticon object. The xloc and yloc
    parameters refer to the upper left coordinate, and the *text parameter
    is a pointer to a string containing the filename of the file containing
    the image(s). This string should be supplied without an extension, .ICN
    is assumed.

void show(int index)
    Displays the specified sequence frame in the Acticon

void choose()
    Displays frame 0 in negative form, usually indicating that the icon
    has been selected

int ispressed()
    Returns 1 if the Acticon is currently selected, 0 otherwise

void animate(int ticks)
    Plays the animations sequence within the Acticon, pausing the
    specified number of clock ticks between frames. The lower this number,
    the faster the sequence will play. The function must be called within
    some sort of loop to function properly.

    example:    Acticon myicon;
                myicon.int(10,10,"RUNNING");

                while(!kbhit()) {
                    myicon.animate(3);
                    }

void backforth(int ticks)
    This function operates in the same manner as the animate function,
    however once it reaches the last frame it continues to play the
    sequence in reverse until it reaches the first frame, then it repeats.




                                BUTTON

    The button object is a graphic pushbutton that can be made to appear
to be pressed when the mouse is clicked while positioned on the button.
Buttons can contain either text or graphic images. Graphic images for
buttons can be created using the ICONEDIT utility sullpied with the
ObejctEase package.

Members - PROTECTED

int state
    The current status of the button

int sizex
    The width of the button

int sizey
    The height of the button

char btntxt[40]
    The text string to appear on the button

int file_text
    Indicates if the button contains a graphic or text

void far *picture
    A pointer to memory containg the graphic

void getpic(char* file)
    Loads the graphic from the file whose name is specified. Do NOT call
    this function directly

int outlined,wasoutlined
    Indicates the outlined status of the button

int shown,wasshown
    Indicates the visible status of the button

long last_tick
    The clock tick at the time the left mouse button was last pressed

int clickcount
    The number of times that the left mouse button has been pressed within
    the last 1/2 second

int w
    The button width

int h
    The button height

Members - PUBLIC

Button()
    The default constructor

~Button()
    The default destructor

void show()
    Displays the button on the screen

void press()
    Displays the button on the screen in its pressed state

void init(int xloc,int yloc,char *text,int type,int savebgd=0)
    Call this function to initialize a Button object. The xloc and yloc
    parameter indicate the upper left coordinat of the object. The *text
    parameter is either the text to print on the button, or than name of
    the file from which to load the graphic image. If the type parameter is
    TEXT, then the text will be printed on the button. If the type
    parameter is IMAGE, then the image will be loaded from a file by this
    name. If the file name is being specified, do not include the file
    extension as .BTN is assumed. If the savebgd parameter is non-zero then
    the underlying screen image will be saved in a buffer before the button
    is drawn. By default this value is 0.

    example:    Button textbutton,imagebutton;
                textbutton.init(10,10,"TEXT",TEXT);
                imagebutton.init(10,50,"GRAPHIC",IMAGE);

void reinit(int xloc,int yloc,char *text,int type)
    This function allows a Button to be reinitialized after a previous
    call to init()

void freepicture()
    Frees the memory associated with the graphic. Called automatically by
    the destructor.

void resize(int newwidth,int newheight,int savebgd=0)
    Allows a Button to be resized from its default width and height.

int hit()
    Returns 1 if the mouse cursor is currently positioned ober a Button

int pressed()
    Returns 1 if the button is currently in its pressed state

void hide()
    Removes a Button object from the screen

void outline(int color,int offset=0)
    Draws a dotted outline around the button in the specified color,
    offset pixels from the outside edge

void move(int newx,int newy)
    Moves the upper left corner of the button to the new coordinates

int Getformat()
    Returns TEXT if the button contains text, IMAGE if the button contains
    a graphic

char *Getcontents()
    Returns the text that appears on the button

int clicked()
    Returns 1 if the left mouse button is pressed while over the button

int LBDCLK()
    Returns 1 if the left mouse button has been clicked 2 times within the
    last 1/2 second

int Getw()
    Returns the width of the button

int Geth()
    Returns the height of the button



    Button example:     Button mybutton;
                        mybutton.init(10,10,"Test Button",TEXT);
                        mybutton.show();

                        while(!kbhit()) {
                            if(the_mouse.LBP()) {
                                if(mybutton.hit()) {
                                   mybutton.press();
                                   while(mybutton.hit()&&the_mouse.LBP());
                                   mybutton.show();
                                   //branch to the desired function here!
                                   }
                                }
                            }







                                GCHECKBOX

    The Gcheckbox class provides an alternative way for the user to make
selections within your program. Visual checkboxes can be checked and
unchecked using the mouse or the keyboard.

Members - PROTECTED

int checked
    The current state

char desc[40]
    The descriptive text associated with the checkbox

int length
    The length of the Gcheckbox object in pixels

int shown,wasshown
    Indicate the visible staus of the Gcheckbox

int outlined,wasoutlined
    Indicate the outlined status of the Gcheckbox

long last_tick
    The clock tick at the time the left mouse button was last pressed

int clickcount
    The number of times the left mouse button has been pressed within the
    last 1/2 second

int bgd
    The bgd color of the Gcheckbox

Members - PUBLIC

GCheckbox()
    The default constructor

~Gcheckbox()
    The default destructor

void init(int xloc,int yloc,char *text,int savebgd=0)
    Call this function to initialize a Gcheckbox object. The xloc and yloc
    parameters are the upper left coordinate. The *text parameter is a
    pointer to the text string that will be displayed to the right of the
    Gcheckbox. If the sacebgd parameter is non-zero the underlying screen
    image will be saved to a buffer before the Gcheckbox is drawn. By
    default this value is 0.

void reinit(int xloc,int yloc,char *text)
    This function allows a Gcheckbox object to be reinitialized after a
    previous call to init()

void show()
    Displays a Gcheckbox on the screen

void check()
    Places a check mark inside a Gcheckbox

void uncheck()
    Removes the checkmark from a Gcheckbox

int is_checked()
    Returns 1 if the Gcheckbox is currently checked, 0 otherwise

int hit()
    Returns 1 if the mouse cursor is currently positioned over the
    Gcheckbox

void outline(int color,int offset=0)
    Draws a dotted outline around the Gcheckbox in the specified color,
    offset pixels from the outside edge

void hide()
    Removes a Gcheckbox from the screen

void move(int newx,int newy)
    Moves a Gcheckbox to the newly specified x and y coordinates

char *Gettext()
    Returns a pointer to the text associated with the Gcheckbox

int clicked()
    Returns 1 if the left mouse button has been pressed while over the
    Gcheckbox

int LBDCLK()
    Returns 1 if the left mouse button has been clicked 2 times within the
    last 1/2 second

void setbgd(int bgd)
    Sets the bgd coor of the Gcheckbox to the specified color





                                GRADIO

    A Gradio is similar in action to a Gcheckbox object. Only the screen
appearance is different. For this reason, refer to the documentation for
the Gcheckbox for a Gradio as well.






                                BITMAP

    The Bitmap class allows for graphic images to be displayed on the
graphics screen. These graphics must be in Borland's BGI format, and can
be created using the 16IMAGE or 256IMAGE editors supplied with the
ObjectEase package.

Members - PROTECTED

int sizex
    The width of the Bitmap

int sizey
    The height of the bitmap

void far *picture
    A pointer to the memory containg the bitmap image

int shown
    The current visible status

int clickcount
    The number of times the left mouse button has been pressed within the
    last 1/2 second

long last_tick
    The clock tick at the time of the last left mouse button press

Members _ PUBLIC

Bitmap()
    The default constructor

~Bitmap()
    The default destructor

void init(int xloc,int yloc)
    Initializes the bitmap object and places the upper left coordinate at
    xloc,yloc

void load(char *file)
    Loads a graphic from the specified file into memory. The file name
    supplied should be complete, including the extension.

void save(char *)
    Saves the graphic within the Bitmap's coordinates to a file with the
    specified name

void show_XOR()
    Places the bitmap on the screen using the XOR_PUT operator

void show_COPY()
    Places the bitmap on the screen using the XOR_COPY operator

void show_AND()
    Places the bitmap on the screen using the XOR_AND operator

void show_OR()
    Places the bitmap on the screen using the XOR_OR operator

void show_NOT()
    Places the bitmap on the screen using the XOR_NOT operator

int is_shown()
    Returns 1 if the bitmap is currently displayed on the screen

void hide()
    Removes the graphic image from the screen

void moveto(int newx,int newy)
    Moves the Bitmap's upper left corner to the newly specified
    coordinates

int capture(int x,int y,int x1,int y1)
    Captures the screen image bounded by the coordinates x,y,x1,y1 to a
    memory buffer

int hit()
    Returns 1 if the mouse cursor is currently positioned over the Bitmap

int clicked()
    Returns 1 if the left mouse button has been pressed while over the
    Bitmap

int LBDCLK()
    Returns 1 if the left mouse button has been clicked 2 times within the
    last 1/2 second

int xsize()
    Returns the width of the Bitmap

int ysize()
    Returns the height of the bitmap






                                    PANEL


    Panels provide a way of sectioning off a portion of the screen. Panels
function in much the same way that a Twindow does in text mode. Panels
can contain other controls.

Members - PROTECTED

int w
    The width of the Panel

int h
    The height of the Panel

int in_or_out
    The bevel state of the Panel

int thick_or_thin
    The bevel characteristics

int shown,wasshown
    The visible status of the Panel

int outlined,wasoutlined
    The outlined status of the Panel

long last_tick
    The clock tick at the time of the last left mouse button press

int clickcount
    The number of times that the left mouse button has been pressed within
    the last 1/2 second

int panelcolor
    The bgd color of the panel

Members - PUBLIC

Panel()
    The default constructor

~Panel()
    The default destructor

void show()
    Displays the Panel on the screen

void init(int xloc,int yloc,int width, int height,int inorout,
            int thickorthin,int savebgd=0)
    Call this function to initialize a Panel object. The paremeters xloc
    and yloc specify the upper left corner, and widht and height specify
    the size of the Panel. Use the global #defines IN, OUT, THICK, and THIN
    for the Panel characteristics parameters. If the savebgd parameter is
    non-zero, the underlying screen image will be saved to a buffer before
    the Panel is drawn. This value is 0 by default.

    example:    Panel panel;
                panel.init(10,10,300,200,IN,THICK);


void reinit(int xloc,int yloc,int width,int height,int inorout,
            int thickorthin)
    This function allows a Panel object to be reinitialized after a
    previous call to init()

void hide()
    Removes a Panel from the screen.

int isshown()
    Returns 1 if the Panel is currently visible, 0 otherwise

void outline(int color,int offset=0)
    Draws a dotted outline around the Panel in the specified color, offset
    pixels from the outer edge

void move(int newx,int newy)
    Moves the upper left corner of the Panel to the newly specified
    coordinate

int hit()
    Returns 1 if the mouse cursor is currently positioned over the
    Panel

void resize(int width,int height,int savebgd=0)
    Allows the widht and height of the Panel to be changed

int sizerhit()
    Returns 1 if the mouse cursor is within 4 pixels of the lower right
    corner of the Panel

int Getw()
    Returns the width of the Panel

int Geth()
    Returns the height of the Panel

int clicked()
    Returns 1 if the left mouse button has been pressed while over the
    Panel

int LBDCLK()
    Returns 1 if the left mouse button has been clicked 2 times within the
    last 1/2 second

int Getthick()
    Returns 1 if the Panel has a THICK bevel style

int Getin()
    Returns 1 if the Panel has an IN bevel style

void setpanelcolor(int color)
    Changes the bgd color of the Panel to the specified color


    Panel example:  Panel panel;
                    panel.init(10,10,300,200);
                    panel.setpanelcolor(3);
                    panel.show();






                                    BEVEL

    The Bevel object provides similar functionality to the Panel object,
and differs only in screen appearance. For this reason, please refer to
the documentation for the Panel object for the Bevel function
descriptions as well.







                                 BUTTONBOX


    The Buttonbox object provides the functionality of a floating toolbox
of buttons.

Members - PROTECTED

Bevel *box
    The moveable box containing the buttons

Button *buttons[16]
    An array of pointers to the buttons. A maximum of 16 buttons is
    allowed

int outlined,wasoutlined
    Indicates the outlined status of the Buttonbox

int shown,wasshown
    Indicates the visible status

int numbuttons
    The number of buttons in the Buttonbox

int w
    The width of the buttonbox

int h
    The height of the buttonbox

Members - PUBLIC

Buttonbox()
    The default constructor

~Buttonbox()
    The default destructor

void init(int xloc,int yloc,int numofbuttons)
    Initializes a Buttonbox object. The xloc and yloc parameters indicate
    the upper left corner, and the numbuttons parameter indicates the
    number of buttons to be contained in the box.

void setbutton(int index,char *file)
    Use this function to load a particular button image. The index
    parameter is the index into the array of button pointers, and the *file
    parameter indicates the file name of the file containing the graphic to
    be loaded, excluding the file extension. .BTN is assumed.

int hit()
    Returns 1 if the mouse cursor is currently positioned over the
    Buttonbox

int moverhit()
    Returns 1 if the mouse cursor is currently within the top 10 pixels of
    the containing box

void show()
    Displays the Buttonbox on the screen

void outline(int color,int offset=0)
    Draws a dotted outline around the Buttonbox in the specified color,
    offset pixels from the outside edge

void hide()
    Removes the Buttonbox from the screen

void move(int newx,int newy)
    Moves the upper left corner to the newly specified coordinates

int buttoncount()
    Returns the number of buttons in the Buttonbox

int buttonhit(int index)
    Returns 1 if the button at the specified index is under the
    mouse cursor

void buttonpress(int index)
    Draws the button at the specified index in its pressed state

void buttonshow(int index)
    Draws the button at the specified index in its normal state

int isshown()
    Returns 1 if the Buttonbox is currently visible


    Buttonbox example:  Buttonbox tb;
                        tb.init(10,10,4);
                        tb.setbutton(0,"ONE");
                        tb.setbutton(1,"TWO");
                        tb.setbutton(2,"THREE");
                        tb.setbutton(3,"FOUR");

                        while(1) {
                            if(the_mouse.LBP()) {
                                for(int i=0;i<4;i++) {
                                    if(tb.buttonhit(i)) {
                                        tb.buttonpress[i];
                                        while(tb.buttonhit(i));
                                        tb.buttonshow(i);
                                        }
                                    }
                                }
                            }





                                GWINDOW

    The Gwindow class provide the capability to use moveable,
sizeable graphic container windows within your application. At the current
time the windows are limited in size to an area that encompasses 64K in
screen image are. This is due to the limitations imposed by the Borland
BGI functions getimage() and putimage().

Members - PROTECTED

Closebutton *closebox
    A pointer to a Closebutton object used to close the window

int w
    The width of the window

int h
    The height of the window

int tfgd
    The fgd color of the title bar

int tbgd
    The bgd color of the title bar

int active
    Indicates the active status of the window

char title[48]
    Contains the text to be used in the title
    bar

void *beneath
    A pointer to memory containing the underlying screen image

Members - PUBLIC

Gwindow()
    The default constructor

~Gwindow
    The default destructor

void init(int xloc,int yloc,int width,int height,int tfore,
            int tback,char *text)
    Call this function to initialize the Gwindow object. The xloc and yloc
    parameter indicate the upper left corner. Be sure that the specified
    width and height will not create a Gwindow that is larger than 64K in
    screen area. The tfore and tback parameter represent the fgd and bgd
    colors used to draw the title bar, and the *text parameter indicates
    the text to be displayed in the title bar.

    example:    Gwindow gwin;
                gwin.init(10,10,200,100,14,1,"Test Window");

void show()
    Displays the Gwindow on the screen

void redraw()
    Cause the Gwindow object to be redrawn. Do not use this in place of
    show()

void hide()
    Removes the Gwindow from the screen

int closeboxhit()
    Returns 1 if the mouse cursor is currently over the closebox

int sizecornerhit()
    Returns 1 if the mouse cursor is currently within 4 pixels of the
    lower right corner of the Gwindow

int titlebarhit()
    Returns 1 if the mouse cursor is currently positioned over the title
    bar of the Gwindow

void resize()
    Allows the user to interactively resize the Gwindow using the mouse

void move()
    Allows the user to interactively move the Gwindow using the mouse

int write_to_disk()
    Writes the buffer containing the underlying screen image to disk thus
    reducing memory consumption. Returns 1 if successful

int read_from_disk()
    Reads the underlying screen image from disk and places it in a buffer
    to be replaced on the screen. Returns 1 if successful

int totalGwindow()
    Returns the number of Gwindows currently in use


    Gwindow example:    Gwindow gwim;
                        gwin.init(10,10,300,200,14,1,"Test Window");
                        gwin.show();

                        while(!gwin.closeboxhit()) {
                            if(gwin.sizecornerhit())
                                gwin.resize();
                            if(gwin.titlebarhit())
                                gwin.move();
                            }
                        gwin.hide();





                              GMENU & GMENUBUTTON

    The Gmenu and Gmenubutton classes has been superceded by the new
menubar and pulldown classes in version 3.0. The code for Gmenu and
Gmenubutton is still included in the library for compatibility, but it has
not been updated since version 2.0. The documentation from v2.0 is also
included here.

Gmenubutton & Gmenu

        The classes Gmenubutton and Gmenu provide the capabilities for you
to include pulldown menus in you graphics applications. The
Gmenubutton is simply the text that will appear in the menu bar
whereas the Gmenu is the moving bar menu that will pop up when a
Gmenubutton is selected. Since these two objects are so closely
related I will discuss them together.

        The data element gitemarray is a predefined two dimensional
array containing the strings that will appear in the Gmenu.
The maximum number of items in a Gmenu is 10, and the width of
the pop-up menu is fixed at 100 pixels. When initializing the
strings in the gitemarray always start at index 1 rather than
index 0. Like this:

        gitemarray menu1array;
        strcpy(menu1array[1],"ITEM 1");
        strcpy(menu1array[2],"ITEM 2");
        etc...

        A Gmenubutton is initialized with parameters for x and y screen
locations, normal state fgd and bgd colors, selected state fgd
and bgd colors, and the text to be displayed.

        A Gmenu is initialized with parameters for the x and y screen
locations, the number of entries to be in the menu, and the
gitemarray containing the item strings. The Gmenu is popped-up
with a call to "show()" which returns an integer representing the
index of the gitemarray the bar was on when the selection was made.
If no selection was made "show()" returns 11.

        Let's look at an example to hopefully clear this all up.

        gitemarray itemarray;
        Gmenu mymenu;
        Gmenubutton mymenubutton;
        int menuchoice;

        strcpy(itemarray[1],"ITEM 1");
        strcpy(itemarray[2],"ITEM 2");
        strcpy(itemarray[3],"ITEM 3");
        strcpy(itemarray[4],"ITEM 4");

        setfillstyle(SOLID_FILL,15);        MAKE A MENU BAR AT TOP OF
                                                        SCREEN
        bar(0,0,getmaxx(),10);

        mymenubutton.init(0,0,0,15,15,0,"MENU 1");
        mymenubutton.show();

        mymenu.init(0,11,4,itemarray);





        if(the_mouse.LBP()) {
                if(mymenubutton.hit()) {
                        mymenubutton.press();
                        choice=mymenu.show();
                        mymenu.hide();
                        mymenubutton.show();
                        }
                }


        In this example the integer variable choice will contain the
number of the item that was selected. Execution can then branch
to the appropriate functions based on this value using case
statements.






                                 OPTION

    As in the TUI library, the option class is used solely as a piece of
larger classes, and has little or no functionality on its own. For this
reason the option class is not documented.





                            PULLDOWN


    The pulldown class is the replacement for the Gmenu class.  Unlike the
Gmenu, a pulldown object can be navigated with the keyboard, the mouse , or
both. The programmer also has complete control over the value returned for a
specific menu choice. The menu can also display separator bars to logically
group sections of a pulldown object.

Members - PROTECTED

friend menubar
    The menubar which is the parent of the pulldown. Can be NULL

int nfg
    The fgd color of an unhighlighted menu option

int nbg
    The bgd color of an unhighlighted menu option

int hfg
    The fgd color of a highlighted menu option

int hbg
    The bgd color of a highlighted menu option

int shown
    Indicates the visible status of the pulldown object

int width
    The width of the pulldown object

int height
    The height of the pulldown object

int num_options
    The number of options contained in the pulldown menu

int part_of_menubar
    Indicates whether the pulldown object is the child of a menubar
    object

char hotkeys[20]
    Contains the programmer defined accelerator keys for accessing
    the pulldown menu

int kbtrigger_index
    The index into the options of the pulldown of the option that
    is selected using keyboard accelerators


Menbers - PUBLIC

option options[20]
    The array of options within the pulldown. A pulldown menu is
    limited to 20 options.

void init(int norm_fgd,int norm_bgd,int hi_fgd,int hi_bgd,
            int xpos,int ypos)

    Call this function to initialize the pulldown object after
    declaring a variable of this type. The norm_fgd and norm_bgd
    parameters represent the unhighlighted fgd and bgd colors. The
    hi_fgd and hi_bgd parameters represent the fgd and bgd colors of
    a highlighted option. xpos and ypos are the left and top
    coordinates at which the pulldown should be displayed.

    example:    pulldown pd;
                pd.init(BLACK,WHITE,YELLOW,RED,10,10);

void set_option(int index,char *text,int ret_value)
    Adds an option to the menu. Call this function to fill the menu
    after declarinring and initializing it. The index parameter is
    the index into the array of options in the pulldown. The *text
    parameter is the text that you want to be displayed in the menu,
    and the ret_value is the value that will be returned if this
    menu option is chosen. To add a separator bar to the menu make
    the *text parameter a "-" .

    NOTE: The *text parameter can contain the '&' character to
        indicate the letter to be underlined and represent the
        accelerator for that particular option. For instance, to
        underline the letter 'x' in the word "Exit" and have it
        serve as an accelerator, enter the text as "E&xit".

    example:    pulldown pd;
                pd.init(BLACK,WHITE,YELLOW,RED,10,10);

                pd.set_option(0,"&Option #1",1);
                pd.set_option(1,"&Second Option",2);

void determine_width_height()
    Do NOT call this function directly. It is used internally to
    determine the width and height to display the pulldown based on
    the strings it will contain.

void display()
    Displays the pulldown menu on the screen.

void position(int xpos,int ypos)
    Positions the pulldown's upper left corner at xpos,ypos.

int trackmenu()
    This is the main engine of the pulldown object. It captures all
    input both from the keyboard and the mouse. The return value is
    127 if the ESCAPE key has been hit. Be careful not to duplicate
    this value with one of your own options. Otherwise, the return
    value is the value that the programmer has defined in the
    set_option call for the option that has been selected.

    example:    pulldown pd;
                pd.init(BLACK,WHITE,YELLOW,RED,10,10);

                pd.set_option(0,"&Option #1",1);
                pd.set_option(1,"&Second Option",2);

                int choice=pd.trackmenu();
                switch(choice) {
                    case 1:...
                    case 2:...
                    }

void hide()
    removes the pulldown menu from the screen.

int is_shown()
    Returns 1 if the menu is currently displayed, 0 otherwise.

void adjust_option_widths()
    Do NOT call this function directly. It is used internally by
    the class.

void adjust_pos_to_menubar(int)
    Do NOT call this function directly. It is used internally by
    the class.

int is_part_of_menubar()
    Returns 1 if the pulldown is the child of a menubar
    object, 0 otherwise.


PULLDOWN NOTE:
    YOU CAN CAUSE CERTAIN PULLDOWN OPTIONS TO APPEAR IN A UNIQUE
    COLOR BY CALLING THE self_color(int fgd,int bgd,int hfgd,int
    hbgd) MEMBER OF THE OPTION CLASS.

    example:    pulldown pd;
                pd.init(1,7,7,1,10,10);

                pd.set_option(0,"&Option 1",1);
                pd.set_option(1,"&Second Option",2);

                pd.options[1].self_color(3,7,7,3);






                            MENUBAR

    A menubar object can serve as a parent to several pulldown
objects. A menubar is typically a bar across the top of the screen
with various options which will invoke the appropriate pulldown
menu.

Members - PROTECTED

option *titles[10]
    An array of pointers to options which represent the options in
    the menubar. A menubar can have a maximum of 10 titles.

pulldown *pd[10]
    An array of pointers to pulldowns. A menubar can have a maximum
    of 10 associated pulldown menus.

int nfg
    The fgd color of an unhighlighted option

int nbg
    The bgd color of an unhighlighted option

int hfg
    The fgd color of a highlighted option

int hbg
    The bgd color of a highlighted option

int num_titles
    The number of titles currently in the menubar.

char hotkeys[10]
    An array of characters which act as accelerators for the
    menubar titles.

int kbtrigger_index
    The index into the array of titles for the option that was
    selected by a keyboard accelerator.

Members - PUBLIC

menubar()
    The default constructor

~menubar()
    The defaule destructor

void init(int nfg,int nbg,int hfg,int hbg)
    Call this function to initialize a menubar object after
    declaring a variable of this type. The 4 parameters represent
    the normal (unhighlighted) fgd and bgd colors, and the
    highlighted fgd and bgd colors.

void set_title(int index,char *text,pulldown *)
    Adds a title and an association with a pulldown menu to the
    menubar.

    NOTE: The *text parameter can contain the '&' character to
    indicate the letter to be highlighted and represent the
    accelerator for that particular option. For instance, to
    highlight the letter 'F' in the word "File" and have it
    serve as an accelerator, enter the text as "&File".

    example:    menubar mb;
                pulldown pd;

                pd.init(BLUE,WHITE,WHITE,BLUE,10,10);
                //The xpos and ypos parameters here are irrevelant
                //because the pulldown will be positioned by the
                //menubar object

                pd.set_option(0,"&Open",1);
                pd.set_option(1,"-",0);
                pd.set_option(2,"E&xit",2);

                mb.init(BLUE,WHITE,WHITE,BLUE);
                mb.set_title(0,"&File",&pd);

void display()
    Displays a menubar object on the screen

int trackbar()
    This is the main engine of the menubar object. It handles all
    mouse and keyboard input to navigate the menubar. The up and
    down arrow keys will move the highlight within a single
    pulldown. The right and left arrow keys will move to the next or
    previous pulldown. The return value is 127 if the ESCAPE key
    was hit, or it is the value of the pulldown option as defined
    by the programmer in the pulldown::set_option call.

    example:    menubar mb;
                pulldown pd;

                pd.init(BLUE,WHITE,WHITE,BLUE,10,10);
                //The xpos and ypos parameters here are irrevelant
                //because the pulldown will be positioned by the
                //menubar object

                pd.set_option(0,"&Open",1);
                pd.set_option(1,"-",0);
                pd.set_option(2,"E&xit",2);

                mb.init(BLUE,WHITE,WHITE,BLUE);
                mb.set_title(0,"&File",&pd);

                int choice=mb.trackbar();
                if(choice==2)
                    Exit the program

int hit()
    Returns 1 if the mouse cursor is currently over the menubar, 0
    otherwise

int mouse_triggered()
    Returns 1 if the menubar has been activated by clicking the
    left mouse button while the cursor is positioned over a menubar
    title, 0 otherwise.

int kb_triggered()
    Returns 1 if the menubar has been activated by a keyboard
    accelerator, 0 otherwise.

    NOTE:   The menu is activated from the keyboard by pressing the
    ALT key along with the highlighted letter from the desired
    menubar title. For example, if the first titles in a menubar is
    "&File", it would be activated by presseing ALT-F.

int triggered()
    Returns mouse_triggered() | kb_triggered()





                            SOUNDQ

    The SoundQ class is useful for having the computer make sounds or play
music in the background, allowing foreground processing to continue
undisturbed.  Most of the functions affecting this class are actully not
part of the class.  This is because they act on data through an interrupt
procedure which is not part of the class itself.

Members - PROTECTED

float speed_factor
    This value represents a speed factor representing the speed of the
    sound playback.  The default play back speed is 1.

Members _ PUBLIC

SoundQ();
    The default constructor.

~SoundQ();
    The default destructor.

void play(int freq, int duration);
    Places a note at the specified frequency and duration into the sound
    queue for playback.  The sound queue will begin playing immediately
    and will continue as long as there are notes available in the queue.
    Use the values defines in TUI.H to more easily specify the freq and
    duration parameters.

    example:    SoundQ sq;
                sq.play(C,HN);
                sq.play(D,HN);
                sq.play(E,HN);
                sq.play(F,HN);
                sq.play(G,HN);
                sq.play(A,HN);
                sq.play(B,HN);
                sq.play(C*2,HN);

    This example plays a C scale in half notes.

void adjust_speed(float);
    Sets the speed factor at which to play back the sound.  The default
    value is 1. To cause the speed of the music to double call
    adjust_speed()with a parameter of 2.

Functions - THESE APPEAR OUTSIDE OF THE CLASS BODY

void empty_sound_queue();
    Empties all notes out of the queue and causes the sound to stop
    immediately.

void init_sound();
    Do NOT call this function.  It is called by the default constuctor.

void restore_sound();
    Do NOT call this function.  It is called by the destructor.

int submit_sound(int freq,int duration);
    Do NOT call this function.  It is called by the play() member function.





                                SCREEN

    The screen class is provided to simplify placing the display into
various graphics modes. If you wish to use the more traditional
initgraph() function for this purpose that is perfectly acceptable.

Members - PUBLIC

int VGA_480_16()
    Places the display into 640x480 16 color resolution

int VGA_350_16()
    Places the display into 640x350 16 color resolution

int VGA_200_16()
    Places the display into 320x200 16 color resolution

int VGA-200_256()
    Places the display into 320x200 256 color resolution

void fill(int color)
    Fills the screen with the specified color.





                            LISTBOX

    A listbox object can be used similarly to a pulldown menu to
make a single selection from a list of options. Unlike a pulldown,
a listbox has the capability to scroll, so that it may contain
many more options than are currently visible on the screen. The
listbox maintains and navigates a list of optionrec structures
which represent the options in the list.

Members - PROTECTED

option *entry
    A pointer to the current option

int index
    The current index into the list

optionrec *next
    A pointer to the next option in the list

optionrec *previous
    A pointer to the previous item in the list

optionrec *listroot
    The root of the list of optionrecs

optionrec *listend
    The end of the list of optionrecs

optionrec *currentsel
    A pointer to the currently selected optionrec

Bevel box
    The Bevel object which serves as the frame for the listbox

Button *up,*down,*pageup,*pagedown
    Pointers to the buttons which control the navigation of the list

Panel *controlpanel
    The Apnel object which contains the control buttons

int should_show_controls
    Indicates whether or not the navigation buttons need to be shown

int should_save_bgd
    Indicates whether or not the underlying image should be sabved in a
    buffer

int selected_index
    The index into the list of the currently selected option

char *selected_string
    The text of the currently selected option

int option_string_length
    The length of the strings in the list

int changed
    Represents the status of the listbox

int size_forced
    Represents whether the listbox has sized itself, or the
    programmer has determined the size at which to display.

int forced_width
    The width that the programmer has determined for the listbox

int forced_height
    The height that the programmer has determined for the listbox

Members _ PUBLIC

listbox()
    The default constructor

~listbox()
    The default destructor

void init(int xpos,int ypos,int num_displayed,int savebgd=0)
    Call this function to initialize a listbox object. The xpos and
ypos parameter are the upper left screen coordinates. The
num_displayed value is the number of options that can be displayed
in the listbox, NOT the number that it can hold, only the number
that it can display at one time. The winfgd and winbgd parameters
are the fgd and bgd colors of the window and unhighlighted
options. The hfgd and hbgd parameters are the fgd and bgd colors of
a highlighted option.If the savebgd parameter is non-zero the underlying
screen image will be saved before drawing the listbox. This value is 0 by
default.

    example:    listbox lb;
                lb.init(5,5,5);

void force_size(int width,int height)
    By default a listbox will determine the width
    and height at which it should be displayed. Use this function to
    override these default value and force it to be displayed at a
    chosen size.

void set_highlight_position(int index)
    Moves the highlight to the position specified in index.

void append_item(char *text)
    Use this function to add strings to the listbox. Strings can
    only be added to the end of the list.

    example:    listbox lb;
                lb.init(5,5,3,15,1,1,7);

                lb.append_item("Item Number 1");
                lb.append_item("Second Item");

void show()
    Displays the listbox on the screen

void show_options(int index)
    Used internally to show a particular segment of the list

void hide()
    Removes the listbox from the screen.

void scroll_list_up()
void scroll_list_down()
    Used internally to position the list within the listbox

int tracklist()
    The main engine of the listbox object. Captures all keyboard
    and mouse input and adjusts the appearance of the listbox
    accordingly. The return value is 1 if successful, 0 otherwise.

    example:    listbox lb;
                lb.init(5,5,3);

                lb.append_item("Item Number 1");
                lb.append_item("Second Item");

                int choice=lb.tracklist();

int options_displayed
    The number of options currently displayed

int options_in_list
    The number of options currently in the list

int option_width
    The width if the strings in the list

int shown
    The current visible status

int nfg
    The fgd color of an unhighlighted option

int nbg
    The bgd color of an unhighlighted option

int hfg
    The fgd color of a highlighted option

int hbg
    The bgd color of a highlighted option

int index_at_top
    The index into the list of the option currently displayed at
    the top of the list.

int index at bottom
    The index into the list of the option currently displayed at
    the bottom of the list.

int hit()
    Returns 1 if the mouse cursor is currently positioned over the
    listbox, 0 otherwise.

int is_current_index()
    Returns the index into the list of the currently selected option

char *is_current_string()
    Returns a pointer to the string of the option that is currently
    selected

int is_selected_index()
    Returns the index into the list of the selected option

char *is_selected_string()
    Returns a pointer to the string of the selected option

void deactivate()
    Turns off the highlighting of the selected option

void reactivate()
    Turns on the highlighting for the currently selecting option

int active
    Indicates the current status






                            DIRBOX

    The dirbox object provides a convenient way to access the
directory and file structure of a disk. Because of the large
memory requirements of the dirbox, it should be contained to a very
small scope so as not to interfere with the other parts of the
application.

Members _ PROTECTED

Bevel *box
    The frame of the dirbox

listbox *drive
    listbox containing the available drives

listbox *directory
    listbox containing the available directories

Button *OK
    The OK button

Button *CANCEL
    The CANCEL button

char fullpath[]
    The current path displayed in the dirbox

char returnpath[]
    The path, including the filename and extension that will be
    returned to the caller

Gstring *filename
    The currently selected filename

int shown
    Indicates the current status

int turn
    A counter representing the region of the dirbox that currently
    has the input focus

char dirmask[]
    A mask used to determine which files are listed in the dirbox

int intnumber
    The value of the "Abort, Retry, Fail" interrupt

void interrupt (*)(...)
    A pointer to the "Abort, Retry, Fail" interrupt

Members - PUBLIC

dirbox()
    The default constructor

~dirbox()
    The default destructor

void show()
    Displays the dirbox on the screen

void hide()
    Removes the dirbox from the screen

char *trackdir()
    The main engine of the dirbox object. Captures all mouse and
    keyboard input and updates the internal variables accordingly.
    The return value is a pointer to the currently selected file.

    example:    {
                    dirbox db;
                    char file[MAXPATH];
                    strcpy(file,db.trackdir());
                }

    NOTE: The above section of code is enclosed in its own braces
            to limit the scope of the dirbox object and keep a
            maximum amount of memory available for the application.

void print_current_path()
    Used internally to display the current path

void change_directory(char *)
    Used Internally

void fill_directory_list()
    Used internally to populate the list of available directories

void fill_drive_list()
    Used internally to populate the list of available drives

void set_mask(char *mask)
    Use this function to specify a mask for a particular file type.
    By defaule this mask is "*.*"

static void interrupt _handler(...)
    This handler is responsible for printing an error if the disk
    is not ready in the currently selected drive.








                                    MESSAGEBOX

    The messagebox class is used to provide a way of displaying a message
to the user and allowing the user to answer questions in a simple Yes/No
or OK/Cancel manner.


Members - PROTECTED

Button *OK,*CANCEL,*YES,*NO
    Pointers to the various buttons which can appear in the messagebox

char bit
    bitwise indicator of the type of messagebox

int border_color
    The border color

int fill_color
    The interior color

int text_color
    The text color

int OKbutton,
int CANCELbutton,
int YESbutton,
int NObutton,
    Indicators of the chosen button

char *str
    The text to be displayed on the messagebox

Members - PUBLIC

messagebox()
    The default constructor

~messagebox()
    The default destructor

int show(char *text,char bitfield)
    Use this function to display the messagebox and retrieve
    user input. The *text parameter is the text to be displayed. The
    bitfield parameter represents the type of messagebox to create, OK and
    CANCEL, OK, CANCEL, or YES and NO. Use the global #defines in GUI.H to
    specify this value. Returns an int specifying which option was chosen.
Compare this value to the #defines in GUI.H

    example:    messagebox mb;
                if(mb.show("File Error! Continue?",MB_YESNO)==ID_YES)
                    continue;
                else
                    exit(0);


void hide();
    Removes a messagebox from the screen


    NOTE: A helper function exists which allows the programmer to institue
a messagebox  without declaring one first. Simply call

        MessageBox(char *,char)

from within your code with the same parameters you would supply to
messagebox::show.








                             SCROLLBAR

    The scrollbar object is used to visually control the contents
of a particular screen area, allowing the user to manipulate the
screen by changing the position of the scrollbar. It is important
for the programmer to remember that the scrollbar object does not
manipulate the screen in any way on its own, it merely returns a
value which must be used by the programmer to make any necessary
changes in display.


Members - PROTECTED

Button *thumbpad
Button *increase
Button *decrease
    Pointers to Button objects which represent the thumbpad and the
    buttons at the ends of the scrollbar used for changing the
    scrollbar's value.

Panel *rect
    The main body of the scrollbar

int vertical
    Represents the orientation of the scrollbar.

int width
    The width of the scrollbar

int height
    The height of the scrollbar

int length
    The total overall length of the scrollbar object

int small_d
    The amount that the scrollbar's value will change if one of the
    end buttons is pressed.

int large_d
    The amount that the scrollbar's value will change if it is
    clicked between the thumbpad and one of the end buttons.

long minimum
    The minimum value of the scrollbar

long maximum
    The maximum value of the scrollbar

long value
    The current value of the scrollbar

int changed
    Indicates the status of the scrollbar

int _SCROLLWIDTH
    The default width os all scrollbars

Members _ PUBLIC

void init(int xpos,int ypos,int length,int vert,long min,long max,
            int scrollwidth)
    Call this function to initialize a scrollbar object. The xpos
    and ypos parameters are the left and top coordinates of the
    scrollbar. Length represents the number of screen characters
    long to make the scrollbar. Use the global #defines HORIZONTAL
    and VERTICAL for the vert parameter, The min and max parameters
    represent the range of the scrollbar's value. The scrollwidth
    parameter represents the width of the scrollbar.

    example:    scrollbar sb;
                sb.init(10,5,100,VERTICAL,0,100,20);

int get_scrollwidth()
    Returns the width of the scrollbar

int button_widths()
    Returns the widths of the end buttons and the thumbpad combined

void show()
    Displays the scrollbar on the screen.

int thumbpad_hit()
    Returns 1 if the mouse cursor is currently positioned over
    the thumbpad, 0 otherwise.

int decrease_hit()
    Returns 1 if the mouse cursor is currently positioned over the
    top button of a VERTICAL scrollbar or the left button of a
    HORIZONTAL scrollbar, 0 otherwise.

int increase_hit()
    Returns 1 if the mouse cursor is currently positioned over the
    bottom button of a VERTICAL scrollbar or the right button of a
    HORIZONTAL scrollbar, 0 otherwise.

int hit()
    Returns 1 if the mouse cursor is positioned over the scrollbar
    object, 0 otherwise.

void track_scrollbar()
    Captures all mouse input into the scrollbar and adjusts its
    appearance and value accordingly.

    example:    scrollbar sb;
                sb.init(10,5,100,VERTICAL,0,100,20);

                while(!the_mouse.RBP()) {
                    if(sb.hit())
                        sb.track_scrollbar();
                    }

long get_value()
    Returns the current value of the scrollbar.

int value_changed()
    Returns 1 if the value of the scrollbar has changed since the
    last call to get_value().

void set_small_d(int val)
    Sets the amount to change the value of the scrollbar if the end
    buttons are clicked. This value is 1 by default.

void set_large_d(int val)
    Sets the amount to change the value of the scrollbar if the
    users clicks between the thumbpad and one of the end buttons.
    This value is 10 by default.

void set_maximum(long val)
    Sets the value to be used as the maximum scrollbar value

void set_minimum(long val)
    Sets the value to be used as the minimum scrollbar value





                                PCX

    The PCX class provides the capability to load and display both 16 and
256 color .PCX files.   Note that of you display 2 or more .PCX files
on the scrren at one time, they must all have the same palette. Otherwise
the palette of the most recently loaded file will corrupt the palette of
the previously loaded files.

Members - PUBLIC

PCX()
    The default constructor

~PCX()
    The default destructor

void init(char *file,int xloc,int yloc)
    Call this function to load the specified file from disk and
    initialize the upper left corner to xloc,yloc

void show(int xpos=0,int ypos=0)
    Displays the PCX file at the specified coordinates. 0,0 by default

int is_256_color()
    Returns 1 if the loaded .PCX file is a 256 color image


    PCX example:    PCX pcx;
                    pcx.init("TEST.PCX",0,0);
                    pcx.show();







    This completes the documentation of the GUI portion of the ObjectEase
libraries.







                                VIDBIOS

        The remaining functions are all part of the VIDBIOS library.

void set_default_palette();
        Sets all palette values to their initial values.

void blankcolor(int);
        Sets the palette values of the color specified to 0,0,0. In other
        words to BLACK.

void fade1_3();
        Fades any object or text displayed from color 1, BLUE, to color 3,
        CYAN.

void fade3_1();
        Fades any object or text displayed from color 3, CYAN, to color 1,
        BLUE.

void fade1_4();
        Fades any object or text displayed from color 1, BLUE, to color 4,
        RED.

void fade4_1();
        Fades any object or text displayed from color 4, RED, to color 1,
        BLUE.

void fade1_5();
        Fades any object or text displayed from color 1, BLUE, to color 5,
        MAGENTA.

void fade5_1();
        Fades any object or text displayed from color , MAGENTA, to color
        1, BLUE.

void fadein(int color);
        Fades the specified color from 0,0,0, (BLACK) to its normal
        palette value.

void fadeout(int color);
        Fades the specified color from its normal palette value to 0,0,0
        (BLACK).

void rgb(int color,int R,int G,int B);
        Sets the specified color to the specified values of Red, Green,
        and Blue. Valid RGB values are from 0 to 63.

void make_grayscale();
        Resets the normal palette to its grayscale equivalents.

void screenbord(int);
        Makes the screen border the color specified.

void disable_blink();
        Disables the ability to make characters blink, however, this
        allows you to use colors 8 through 15 as background colors in text
        mode.

void enable_blink();
        Restores the ability to make characters blink, however, colors 8
        through 15 will not be available for use as background colors in
        the text mode.

void disable_refresh();
        Disables the video refresh, effectively blanking the screen.

void enable_refresh();
        Enables the video refresh, restoring a screen blanked by a call to
        disable_refresh().