File: bgui.txt (C) 1998 Dan Huizenga (Skis)
Web: http://www.concentric.net/~skis
E/M: skis@concentric.net


    T  h  e       B  G  u  i       R  e  a  d  m  e
    -----------------------------------------------
           Proudly Created with MSDos Edit.

=================
=  Intro Stuff  =
=================

  Please forgive the spelling and grammar in this file.
  If you want to fix it, go ahead ;-)  This file gets
  updated when I have time, which isn't often.. I'll
  do my best to keep it up to date, but if something is
  missing or seems innacurate, please E-Mail me about
  it.

  BGui    -- A win-95 like drop in replacement for the  
             Allegro GUI. All errors in this file are (C) 1998     
             Dan Huizenga.

  License -- If you use BGui, in your program, I don't
             require you to send me any money. All that
             I ask for in return is an E-Mail telling me
             about you program, and a copy of your program,
             if I decide I want it.

  You Break it.. -- If this breaks your computer, printer, body,
                    brain, or anything else it's not my fault and I
                    cannot be held responsible.

  Updates -- New versions will be available at
             http://www.concentric.net/~skis. Also be sure to
             check out the Allegro Wish List.

  New in this release --
             see changes.txt

==========================
=  Contributors to BGui  =
==========================
This was a hard section to write.
There are just so MANY!
BGui is based on the Allegro GUI,
therefore, anybody who contributed
to that contributed to BGui.

People who have contributed specifically to
BGui include:

 Shawn Hargreaves -- Shawn wrote many of the
  (in an indirect    origional GUI routines.
   sort of way :-)   Much of BGui's code came
                     from them.  Please see
                     the Allegro credits for
                     information on the contributors
                     to the origional Allegro
                     GUI.

 Johan J”nsson -- Wrote the vertical 3D line.
                  (Will be used in a future
                   release for "subdividing"
                   frames )
 Jason Eccles  -- Made tdbox slightly faster
                  by cutting the number of
                  calls to get_bill_color
                  in half.
 Julien Audran -- Contributed Drop Down List,
                  Group Box, fixed BillCheck
                  to respond to D_DISABLED.
                  Also contributed BitmapButton
                  and ToolBar, but I still have
                  to add those in (at least, I
                  did when I wrote this :-)

 Myself        -- Wrote everything not listed
                  above that didn't come out
                  of Allegro.

==================
=  Notes on Use  =
==================

1. Compatibility notes:
    A. There are several small differences from BGui and Allegro. Although
       I have tried to maintain as much compatibility as possible, there are
       a few minor differences, please see the "differences from Allegro"
       section before using BGui.

2. Quick Start:
    To give your program the Windows 95 look, just put "bill_" in front
    of all of the procedures in your dialog array. Also remember to
    make everything 2-6 pixels taller and/or wider, to accommodate the
    "3D" look. You will also have to do a search and replace of "do_menu"
    to "do_billmenu".  Finally, be sure to remember to initialize BGui's
    which is covered under "Initializing BGui" under "Notes on use".

    *Note: You will also have to follow the compiling/installation
           instructions.  BGui no longer comes with a precompiled
           library.

3. Compiling with BGui.
    You will have to compile with "gcc myprog.c -lalleg -lbgui".
    That is the absolute minimum you can have on your command line.
    Be sure to copy BGui to you djgpp\lib directory, and tdgui.h
    to you djgpp\include directory.

4. Initializing BGui.

    Step 1: Palette initialization
    ------------------------------
     This must always be done before the other steps.

     BGui requires that certain colors be available to it in order to
     create the 3D look. You can initialize this palette in 3 ways. Please
     note that in modes greater than 8-bit you do not have to do this.

     1. bill_init_pal();
      This creates a gray palette with blue for title bars. This uses the
      entire palette.

     2. bill_init_smallpal(index of where you want the small palette to start);
      This uses only a part of the palette, taking one palette index for each
      BGui color constant.  The integer passed to it is where the palette will
      begin.  This is the recommended method of setting up the palette.

     3. bill_init_very_smallpal(palette starting position);
      This is not recommended unless you _really_ need the few palette entries
      this will save you. (When I typed this, it saved 3 or 4. That may change
      in the future).

    Step 2: BGui Initialization
    ---------------------------
     Simply call Bill_init.  This must be done after you've initialized
     the palette (if you are in 8-bit mode), and before you use any
     BGui functions

    Step 3: Re-initializing upon graphics mode/palette change
    ---------------------------------------------------------
     Call bill_init_radio_buttons().
     BGui does this automatically when you call bill_init, but you
     must do this again every time you change and/or move BGui's
     palette in 8 bit mode, and also every time you change
     graphics modes.  I havn't changed the name of the function
     to maintain compatibility with existing code, but it is
     innacurate as BGui will crash weather or not you use radio
     buttons if you fail to call it.

==========================================
= Compiling BGui and things made with it =
==========================================
 1. Making and installing the library
   Type bmake.
   Copy libbgui.a to your djgpp\lib directory
   Put tdgui.h in your djgpp\include directory         

 2. Compiling with BGui 
   #include "tdgui.h" into your program
   To use: gcc myprog.c -o myprog.exe [other options] -lalleg -lbgui   

=================
=  Known Bugs   =
=================
  1. Text can be drawn outside of controls.
  2. There are no arrows on the scroll bar on the list box

===============================
=  Things that aren't in BGui =
===============================
  1. Anything you want? Let me know.

============================
= Differences from Allegro =
============================
Notes on Everything:
  - The FG and BG properties are now ignored. You will have to
    change the color constants (you can do this at run-time) in
    order to change the colors.  If you do change the color
    constants, be sure to call bill_init_smallpal if you are in
    8-bit mode. _DO NOT_ use bill_init_pal, or bill_init_verysmallpal.
    Also, I reccomend calling bill_init_radio_buttons after changing
    color constants.

  - All of your controls will have to be made a little taller and
    wider.

Notes on "alert":
  In BGui, the first message string passed to alert and alert3
  is used as the window title. This can cause some programs to
  look very bad.  Maybe I will change this in later versions,
  and make this behavior user selectable, with the other choice
  being to have a global string for message box titles that you
  could change.

Notes on menus:
  Due to the way "do_menu" and "_do_menu" were written in
  the original Allegro, I had to change them.  If your
  program uses these, please call "do_billmenu" and
  "_do_billmenu" instead.

Notes on d_billclear_proc:
  Unlike it's Allegro counterpart, d_billclear_proc DOES obey
  it's x, y, w, h. So be sure to take those 0's out of w/h and
  make them values as larg as or larger than your resolution
  is.

Notes on radio buttons:
  Radio buttons can be round or square. They are square if
  the button's d2 is 1.  Square radio buttons look like a
  standard BillButton.  Also, the size of the round
  "button" part will always be the same, since it is a bitmap,
  and is not drawn with an algorithm.
  You MUST call bill_init_radio_buttons every time you switch
  graphics modes, unless you have already called bill_init in
  the current graphics mode.

======================
= BGui F A Q         =
======================
1. Q - Why do moveable BillWindows crash my program when you
       move them?

   A - This was a bug.  It should be fixed in this release, but
       since I never had this problem, I cannot be sure.
       Please let me know if your program still has this problem.

2. Q - Why are BGui's colors all funny in the 8 bit graphics mode
       program that I just made?

   A - You forgot to initialize the palette.  Information on doing
       this can be found under "initializing BGui", which is in
       "Notes on use"

3. Q - Can I have multiple BillWindows open at once?

   A - BWinSys, an addon available at my site
       (http://www.concentric.net/~skis) will allow you to
       do this with minimal modification to your program,
       and no modification to BGui or Allegro.

4. Q - Can I use BGui with my C++ program?

   A - Currently, no.  I've been told that there are a number
       of missing type casts that are required for C++.  If you
       know C++, and are willing to fix BGui to work with C++,
       please contact me.

5. Q - My program that uses BGui crashes, what can I do to fix it?

   A - Solving Mysterious Crashes
   ------------------------------
       i.   - Have you properly initialized BGui?  Information on this
              is in "Notes on uses" under "initializing BGui".

       ii.  - Have you read this entire file?  Usefull information is
              scattered througout it in a very abstract mannor.

       iii. - Have you compared your program with BTest.c to see what
              you are doing different?

       iv.  - E-Mail me at Skis@Concentric.net for help, including
              the following information:

                1.  What is your program doing when the crash occurs?
                2.  What is the output at crash time, including the
                    output of Symify.exe (run "symify myprog.exe" while
                    the debug information is on screen"), and the kind
                    of exception that was generated.  Any other information
                    that you feel is relevant can also be included.
                3.  You correct E-Mail address, preferably in the
                    reply-to feild, so that I don't have to enter it
                    manually.  If I click the "reply" button, type a
                    reply, and hit "send", and it gets sent back to me
                    because of a bad E-Mail address, you are on your
                    own.  I do NOT like "anti spam" e-mail addresses
                    that require me to modify the address manually.
                     Thanks.

6. Q - Can I use BGui in my commercial program/CD?

   A - Sure!  The only requirments are that you send me an E-Mail
       telling me what you used it for, and giving me a copy of
       your program or CD that uses BGui.  Please notify me before
       sending me a copy via E-Mail, because I may decide that I
       don't want it or perfer a CD/Disk if the file is very large
       (My mail ISP connection can be shaky, so a large file repetedly
       failing to D/L can temporarilly cut my access to E-Mail off, I
       know this from experience).  Thanks.




======================
= The Future of BGui =
======================
   Stuff I want to do:
      * Create a GUI from scratch :)

      * Add more controls to BGui


=======================================================
= The Mysteries of The Things In The TDGui.h File ... =
=======================================================

There are also explanations of stuff in .H file.
Info on most of the #defines can be found in BGui.c
before the tdbox() proc.

-=>#define WM_XXXXXX
  Messages for the BGui Window Manager which will allow you to have
  multiple standard dialogs open in different windows at one time.
  ** Unused.  The BGui Window Manager has been implemented in the
     form of BWinSys.  These are left in case I decide to write
     a true Window Manager some day, which would replace Allegro's
     Dialog Manager.

-=>#define W_XXXXXX
  Responses for w_xxxxxxx_proc's
  ** See above note

-=>typedef struct WS
  WinSystem structure. Like dialog, only for a window w/ a pointer
  to the dialog it will contain.
  ** See above note

-=>typedef struct MOVABLE_INFO
  Currently unused

-=>#define STL_XXXXXXX
  Used by tdbox()

-=>#define SCL_XXXXXXX
  Used by scrollbar

-=>#define BILL_SMALLPAL_SIZE 9 
  This is just the number of colors required
  for the bill_init_smallpal  

-=>#define BILL_VERY_SMALLPAL_SIZE 7
  This is just the number of colors required
  for the bill_init_very_smallpal  

-=>extern float bg_ver;
-=>extern char bg_ver_str;
  Version information.

-=>extern RGB bill_XXXXXXXX
  Color constants that control how BGui looks.
  Want to change the colors within BGui? Change
  these, and then call bill_init_smallpal()

-=>void set_gui_mode(int mode);
  Right now this only makes the buttons look
  more like Win95. Later I hope to add arrows
  to the scrollbars on the listbox.  Leaving
  this off will (after BGui is done) make the
  controls fit the same dimensions as their
  Allegro counterparts better.

-=>int get_bill_color(RGB billcolor);
  Just returns the closest index of an RGB.

-=>void bill_init_pal();
  sets up a gray palette w/ blue for the title bar.

-=>void bill_init_smallpal(int start);      
 use 9 colors of the palette for BGui, instead of all 255.

-=>void bill_init_very_smallpal(int start); 
  Same as smallpal, except it skips
  repeat colors, and takes the required
  color count down to 7. DONT USE THIS
  IF YOU ARE GOING TO CHANGE THE COLOR
  CONSTANTS

-=>void bill_init();                  
  As of now, this does absolutely nothing, but you should
  call it anyway in case I change that later.

-=>void tdbox(BITMAP *b, int x, int y, int w, int h, int stl);
  This routine is used to draw some part of almost EVERY object
  you see in BGui. If you can make this go faster, you can make
  BGui go faster.  By the way, does anybody want to write a 
  tdcircle for me? ;-)

-=>void tdhline(BITMAP *b, int x, int y, int x2);
  Horizontal 3D line

-=>void tdvline(BITMAP *b, int x, int y, int x2);
  Vertical 3D line

-=>static void bill_dotted_rect(int x1, int y1, int x2, int y2, int fg);
  Same as Allegro's dotted rect, except
  it leaves spaces inbetween the dots alone.

-=>void _draw_scrollable_billframe(DIALOG *d, int listsize, int offset,
                                   int height, int fg_color, int bg);
  Same as the counterpart function in
  Allegro, except it looks like windows
  95. (except there are no arrows on the
  scroll bar).

-=>void bill_fade_bmp(BITMAP *bmp, int clr);
  You know how Windows fades the screen
  when you hit shutdown? That's what this
  does.  Please note that it's kinda slow.

-=>int billgfx_mode_select(int *card, int *w, int *h);
  Same as in allegro, except 3D  

-=>int billalert3(char *s1, char *s2, char *s3, char *b1, char *b2,
                   char *b3, int c1, int c2, int c3);
  Same as in allegro, except 3D. NOTE: The char *s1 is put in the
  window's title bar, NOT in the window itself.

-=>int billalert(char *s1, char *s2, char *s3, char *b1, char *b2,
                   int c1, int c2);
  Same as above.



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Dialog procedures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

=============Origional BGui procedures which have no Allegro counterpart====================
-=>d_billprogress_proc(int msg, DIALOG *d, int c);
   Progress bar, or "percent finished" thing.
   d2 is current value, d1 is the maximum value
   that it will reach.  The percent is calculated
   with d2/d1.

-=>d_billgroupbox_proc(int msg, DIALOG *d, int c);
   A group box.  See the btest.c for an example.
   Optionally, dp1 can point to a string for the
   lable of the group.  This must appear in the
   dialog array befor the objects that it will contain.

-=>d_billddlist_proc(int msg,DIALOG *d,int c);
   Drop Down list.  Identicle to the standard list except
   that it "folds up", so that only the selected choice
   is visible.  See Btest.c for an example.

-=>d_billscrollablebitmap_proc(int msg, DIALOG *d, int c);
   This is almost exactly like Allegro's bitmap proc,
   except that it can contain x and y coordinants of
   where to blit from on the "from" bitmap.  These
   are stored in the d1 and d2 variables. Be sure to
   send it MSG_DRAW after changing them.

-=>int d_hbillscrollbar_proc(int msg, DIALOG *d, int c);
   Fully functional horizontal scroll bar. D1 value is
   the maximum, and the D2 value is the current value of the
   scroll bar. These do not respond to D_HIDDEN, instead just
   set the d1 value to 0, and they will hide themselves.
   The dp field can point to a proc in the format

   void scrollbar_change(int i).

   This will be called whenever the scrollbar's value changes,
   and the I will be equal to it's d2.


-=>int d_vbillscrollbar_proc(int msg, DIALOG *d, int c);
   Fully functional vertical scroll bar.  See above.

-=>int d_billwin_proc(int msg, DIALOG *d, int c);
  BillWindows now have the ability to move, but you
  have to show their dialog with movable_do_dialog, and
  everything in the dialog has to be contained by them.
  For using these in an update_dialog loop, use the
  functions shown in the "Added Bonus" section.

-=>int d_ex_billbutton_proc(int msg, DIALOG *d, int c);
  This is a button with a callback. It will not close the dialog,
  and it will not toggle, it just pops in and out when clicked, and
  calls the callback.
  The callback should look like this:
  int my_proc(void *dp3, int d2);

  The dp3 will be equal to the buttons's dp3, the d2 equal to the
  buttons's d2.


-=>int d_samplex_billbutton_proc(int msg, DIALOG *d, int c); //Button w/ callback
  Same as above, only with a slightly different format for
  the callback.
  The callback should be in the format
  int my_proc();
  The dp2 feild should point to a sample.

-=>int d_callback_billbutton_proc(int msg, DIALOG *d, int c);
  Same as above, doesn't play a sample

-=>int d_billhline_proc(int msg, DIALOG *d, int c);
  Draw a horizontal 3D line at d->x, d->y with width d->w.

-=>int d_billvline_proc(int msg, DIALOG *d, int c);
  Same as above, verticle.


=============Here's some stuff that I threw in as an added bonus :-)========================
-=>void replace_col(BITMAP *b, int oc, int nc);
  Replaces all occurences of OC in a B with NC (kind of like set_color in 8-bit).

-=>void make_solid_pal(PALETTE pal, int start, int stop, int r, int g, int b);
  Sets all RGB's in a palette from index start to index stop to r, g, b.

-=>int moveable_do_dialog(DIALOG *dialog, int focus_obj);
  You need to use this in order to have movable BillWindows.

-=>int init_moveable(DIALOG *dialog);
  Call this before init_dialog in an update_dialog loop.

-=>int shutdown_moveable(DIALOG *dialog);
  Call this before shutdown_dialog in an update_dialog loop.

============== Allegro routines w/ the Win 95 look =========================================
-=>int do_billmenu(MENU *menu, int x, int y);
   You MUST use this in place of the old "do_menu"
   in your programs.

int d_billmenu_proc(int msg, DIALOG *d, int c);

-=>int d_billradio_proc(int msg, DIALOG *d, int c);
  Same as allegro with the following exceptions.
   1. They can only be round.
   2. You MUST call bill_init_radio_buttons()
      before you use them in a new graphics mode,
      unless you have called bill_init in the current
      graphics mode.

int d_billtextbox_proc(int msg, DIALOG *d, int c);
   Same as Allegro.

int d_billedit_proc(int msg, DIALOG *d, int c);
   Same as Allegro.

int d_billslider_proc(int msg, DIALOG *d, int c);
   Same as Allegro.

int d_billlist_proc(int msg, DIALOG *d, int c);
   Same as Allegro.

int d_billbutton_proc(int msg, DIALOG *d, int c);
   Same as Allegro.

-=>int d_billtext_proc(int msg, DIALOG *d, int c);
-=>int d_billctext_proc(int msg, DIALOG *d, int c);
  Changed: Now you can use "BILL_CLEAR" and "BILL_TITLE"
           for the background color, to make it
           transparent, or the color of the title bar.

           Using "BILL_TITLE" for the foreground make
           the text the same color as the text on title
           bars.

int d_billcheck_proc(int msg, DIALOG *d, int c);
   Same as Allegro.

int d_billclear_proc(int msg, DIALOG *d, int c);
   Same as Allegro, except it obeys the x, y, h, and w
   settings.

int billfile_select(char *message, char *path, char *ext);
   Same as Allegro.
 
static char *gfx_mode_getter(int index, int *list_size);
static char *gfx_card_getter(int index, int *list_size);


-/-[-<-(-{-}-)->-]-\--/-[-<-(-{-}-)->-]-\--/-[-<-(-{-}-)->-]-\--/-[-<-(-{-}-)->-]-\-
If you don't understand what something is doing, here's the list of what
you can do to figure it out:
1. Look at the Allegro counterpart.
2. E-Mail me. (Skis@Concentric.net) Be sure to include a good title on your
   message, I receive a LOT of spam.  (SpammerSlammer quite working on my
   computer).
3. If something doesn't look right, it's probably not.  Go ahead and fix it,
   but be sure to tell me what you did, so that I can put it on my page.


OK, I couldn't make myself take *ALL* of the ASCII art out.  If you've
been reading this file straight through, I think it's about time you
take a break..

|||;;;:::==='''```'''===:::;;;|||;;;:::==='''```'''===:::;;;|||;;;:::==='''```'''===:::;;;

   /-\     /--    /----  _____  _____  |
  /   \    \      |        |      |    |
 /-----\    --\   |        |      |    
/       \   __/   \____  __|__  __|__  * 

|||;;;:::==='''```'''===:::;;;|||;;;:::==='''```'''===:::;;;|||;;;:::==='''```'''===:::;;;
___________________________________________________________________________

File currently not maintained below this line.  See TDGui.H for
information concerning TDBox options.

---------------------------------------------------------------------------
Here's some comments that I copied out of the .c and .h file.  I don't have
the time to write much more, I have to go study :-(.

Color constants used to draw billgui routines. Want to change the colors?
use these, NOT the fg/bg properties of the dialogs

   ALL of the BillGui routines are based on the tdbox routine.
   Styles include:
   STL_IN     (1)        "in" state border (used w/ buttuns and frames)
   STL_OUT    (2)        "out" state border (used w/ buttons)
   STL_FRAME  (8)        used in conjunction w/ STL_IN, it switches the order
                         of the "shadow" lines at the top of a frame, so that
                         the light one is towards the outside
   STL_BUTTONDOWN (64)   used for buttons in appearexact mode 

   STL_FACE   (4)        fills the bg w/ bill_face. otherwise bg isn't drawn.
   STL_FLAT   (4)        same as above
   STL_FILLED (4)        same as above

   STL_FRAMEFILLED (32)  used for filled frames (white bg).  This DOES NOT include
                         objects drawn w/ draw_scrollable_billframe.  They have
                         to draw their own background.
   STL_DITHERED    (16)  draws a dither of bill_light and bill_hlight as the bg,
                         for scroll bars

Please forgive the spelling and grammar in the comments in this file, I can't
run it through a spell-check.
If you want to fix it, go ahead ;-)

Several styles are re-defined under different names.  This is simply
because they are used for different purposes.  They do exactly the same thing,
it is just to make the code easier to read / understand

You shouldnt have to used these #define's in your programs, they are used
for the tdbox() routine.

By the way, I should mention that quite a few Allegro variables/functions
are included in this source, with the same names. It wouldn't compile otherwise.
If you know why this is, PLEASE tell me! (Are they not in Allegro.h?)

Please note the 80% of the code in here was taken straight out of Allegro,
I only made a few small changes to the drawing routines.


