This is the text version of the documentation, which is autogenerated from
the HTML version.


,-------------------------------------------------------------------------.
| The Allegro GUI Un-uglification Project                                 |
`-------------------------------------------------------------------------'


Version 0.99.5
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Let's be honest. When you see an Allegro dialog, don't you just want to
stick your fingers down your throat, and make choking noises? Haven't you
started your own GUI system before, simply because the GUI objects Allegro
provides are *damned ugly*? Don't you wish Shawn had grown up with an Apple
Macintosh, instead of an Atari ST?

The Allegro GUI Un-uglification Project is here to help. Its purpose is to
make Allegro DIALOGs look *good*, so you don't have to choke yourself,
reinvent lots of wheels, or wish a fate worse than death upon deity Shawn
(lest you be struck down by the non-portability bug).


What it provides, so far
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some sets of GUI objects which act almost exactly like Allegro's d_*_procs.
*Almost*, because there are some very minor differences, which are
described further below.

Here is the list of procs.

* d_agup_box_proc
* d_agup_shadow_box_proc
* d_agup_button_proc
* d_agup_push_proc (1)
* d_agup_check_proc
* d_agup_radio_proc
* d_agup_icon_proc
* d_agup_edit_proc
* d_agup_list_proc
* d_agup_text_list_proc
* d_agup_textbox_proc
* d_agup_slider_proc
* d_agup_menu_proc
* d_agup_window_proc (2)
* d_agup_text_proc
* d_agup_ctext_proc
* d_agup_rtext_proc
* d_agup_clear_proc

(1) d_agup_push_proc implements a "push" button, which I think is more
useful than Allegro's "toggle" buttons. The dp3 field should point to a
callback function, which will be called whenever the button is clicked
(with the DIALOG entry as an argument), or NULL. The callback should have a
function prototype of the form:

int foobar(DIALOG *d);

It will be passed the dialog entry that was pressed, and should return a
value that will be passed back to the GUI control loop, e.g. D_O_K or
D_CLOSE.

(2) d_agup_window_proc implements a window frame, which can be used in
place of d_box_proc or d_shadow_box_proc. It expects the title of the
window in the dp field, or NULL.

Additionally, each theme sets the following two Allegro menu callbacks to
functions which render a themed menu:

* gui_menu_draw_menu
* gui_menu_draw_menu_item to


The API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AGUP can select from different widget sets ("themes") on the fly. You
select the theme at initialisation, e.g.

  agup_init(agtk_theme);

Then to switch themes, shutdown the old one, and initialise the new:

  agup_shutdown ();
  agup_init(awin95_theme);

Remember to shutdown again before the end of your program.

If you don't want to deal with global theme pointers, you can also get a
theme by its name.

 AGUP_THEME *theme = agup_theme_by_name("Photon");

This will select the theme by its string name. The names for the non-bitmap
themes are: "GTK", "Win95", "Photon", "BeOS", "NeXTStep", "ASE", "Allegro".

Bitmap themes will register with their theme-specific names as well. The
two example bitmap themes use "Blue" and "Fleur de Lis".

There's one more function for bitmap themes. In order to not require bitmap
themes to be compiled into the program, you need to load them before using.
E.g.

  blue_theme = agup_load_bitmap_theme ("blue.cfg", NULL);

will load a new bitmap theme which is read from the file "blue.cfg". See
the section about bitmap themes for information about how the actual
bitmaps are found and loaded.

Also, if you only have need for one specific widget set, there's no need to
use AGUPs theme functions: Just use the widget set you want directly (see
the header files).

Furthermore, nothing stops you from using the stock Allegro dialogs at the
same time as agup. In fact, things like e.g. d_text_proc can be quite
useful to have colored text.


About "the project"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

So far, there are seven widget sets, so it's starting to become more of a
project. Please consider contributing emulations of other widget sets. It
does not have to look *exactly* the same as the original, just close enough
to be recognised.

Here are some that I would like to see:

MacOS (Platinum?), Motif, SGI, or maybe your own (if it's not damned ugly
;)

Also send in bitmap themes which you would like to share with others, they
will be hosted on the AGUP site, with your name displayed.

Thanks to Robert Ohannessian for stepping up and creating the first "3rd-
party" widget set (awin95). As promised, there is now a wrapper layer.

Thanks to David A. Capello for creating the second 3rd-party widget set
(aase).

[ Warning: The aase theme isn't 100% complete, and probably won't ever be
completed. It will likely be removed in later versions of AGUP. ]

Thanks to Eric Botcazou for creating the fourth widget set (aphoton). Wow,
that's really sweet!

Thanks to Elias Pschernig for creating the BeOS widget set. Very cool, and
very yellow.

Thanks to Joao Neves for creating the NeXTStep widget set. My list of OS
themes to emulate is diminishing :-)

Well, and thanks to Peter Wang for creating the first theme, and
maintaining AGUP for so long. Hm, and who thanks me now again for creating
the bitmap theme? Maybe the next maintainer should there ever be one.


For C++ people
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AGUP is basically a C library, but it can be compiled as C++ source too.
You have two options:

(1) Compile AGUP as C, then include like so:

   extern "C" {
     #include "agup.h"
   }

(2) Compile AGUP as C++.


Contacting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See http://agup.sf.net.

,-------------------------------------------------------------------------.
| The AGUP Bitmap Theme Engine                                            |
`-------------------------------------------------------------------------'

Everyone who tried creating his/her own Allegro GUI knows how hard it is to
get it looking good. And the same applies for creating a new GUI theme
inside AGUP - it requires to write a replacement for every single one of
Allegros dialogs, and the menus. This is why the bitmap engine might be
useful. It only requires you to draw bitmaps, and specify which bitmap or
part of a bitmap to use for Allegro's dialog elements. The amount of
bitmaps is your choice, you can use a single bitmap for every element and
every state of it, or at the other extreme, draw the complete theme into
one bitmap - or anything between.

Of course, the drawback of a bitmapped theme is that it is possibly slower
than the other themes (but not necessariy, especially if the provided
bitmaps aren't too small, so there don't need to be multiple blits per
widget).


Overview about the supported widgets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This contains a list of all the dialog elements, and a short description
how the bitmap engine displays them - in order to aid in creating a new
theme. The bitmap engine is accurate down to the pixel - so your themes
will look perfect (of course, all the restriction of the Allegro GUI
apply).

Stock Allegro widgets

keyboard, yield

These two are not provided by AGUP, since they are invisible.

bitmap

This one is not provided by AGUP, since it is independent of the theme.

box, shadow_box, button, check, radio, icon

They all can be customized with the bitmap engine..

clear

This one is special, since it ignores its dimensions - so AGUP does the
same. It can only be used as first element, and you should fill in the
right dimensions anyway.

text, ctext, rtext

Draw text. The stock text widgets don't clear the dialog array, so neither
does the AGUP bitmap theme. The specified bitmap is put just behind the
text (not the entire DIALOG area), and may be transparent.

edit

Input text. In Allegro, this doesn't have any border, just like the text
items. In AGUP, this is changed, and a 2 pixel border is added on all
sides. This means, it should always be 4 pixels wider and higher than when
using the stock Allegro GUI. Otherwise, there will be a 4 pixel overdraw to
the right and the bottom, and the mouse input will be 2 pixels off. But
this was the best compromise we could find.

list, text_list, textbox

Draw a list/text list/text box with a vertical scrollbar. The scrollbar of
the stock Allegro GUI always is 12 pixels wide and right aligned - AGUP
follows this of course.

slider

Draws a horizontal or vertical slider.

menu

Draws a menu bar. This is named "menubar" in the AGUP bitmap engine, and
"menu" means an actual popup-menu.

Additional AGUP widgets

push

Like button, but with a callback instead of 2 states.

window

Like box/shadow_box.

Allegro Menus

menu

This is the area of the complete menu. It has a border of one pixel at the
top, and a border of 2 pixels at the bottom.

menu_item

A single menu item.

menubar

It has a border of 1 pixel to the left, and a border of 2 pixels to the
right.

menubar_item

A single menubar item.


Which files do I need to provide for a bitmap theme?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All that is needed is a configuration file, and a set of bitmaps. There are
various ways to pass them to AGUP, so for simplicity, lets consider some
examples:

 agup_load_bitmap_theme (NULL, my_dat);

This will load a theme using the provided datafile "my_dat" to find all its
data. The configuration file must be a binary object named "agup.cfg"
inside the datafile. The bitmap names inside that agup.cfg will be found by
passing them directly to find_datafile_object. For example, if the agup.cfg
contains:

 box = box.bmp

Then my_dat should have a BITMAP element named "box.bmp" in it.

 agup_load_bitmap_theme ("my.dat", NULL);

Normally, themes are loaded externally, so just NULL is passed as datafile,
and the file extension is used to determine what to do. In the above
example, the loadeded theme will load "my.dat" when it is initialized
later, and the datafile then is used in the same was as if it was passed
directly (needs "agup.cfg" and bitmap objects inside it).

 agup_load_bitmap_theme ("my.cfg", NULL);

This will load the file "my.cfg" as configuration file, and pass bitmap
names to load_bitmap. This means, you can use any bitmap names and formats
that are understood by load_bitmap. This includes the special # separator,
and handling of user registered formats like PNG or JPG with appropriate
Allegro addons.

 agup_load_bitmap_theme ("my", NULL);

This will first try to find "my.dat", and if it is not found, try "my.cfg".

 agup_load_bitmap_theme (NULL, NULL);

If you pass NULL to both the path and the datafile, the current Allegro
configuration is used to find the AGUP configuration. This requires a
config section named "[agup.cfg]" to be present. If it is found, then its
contents are used as agup.cfg. Bitmap names are directly passed to
load_bitmap again. Note that you can use Allegro functions like
set_config_file or override_config_file to specify where the configuration
should be read from.

 agup_load_bitmap_theme ("my.dat", my_dat);

Rarely useful, but in this case, if "my.dat" fails to load, my_dat is used
instead.


So, what goes into the agup.cfg file?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

At the top of the file, there must be this line:

 [agup.cfg]

Then there follow various options (read with Allegro's config file
routines).

 name = <string>
 prefix = <string>
 suffix = <string>

That way, you can specify a name for theme, and a prefix/suffix to be
prepended/appened to all the bitmap names. The name is currently unused.

For example:

 prefix = my/
 suffix = .png

will be useable to look for ".png" files in the directoy "my", i.e. instead
of

 box = my/mybox.png

you can just use:

 box = mybox

Most important is of course the entries for all the different bitmaps.
There's an entry for every bitmap, with 3 states each. (If not all entries
are present, some bitmaps will inherit from others.) The "box" entry must
be present, else the theme won't load.

Bitmaps marked with *M can contain transparency (color #ff00ff, or index 0
if a palette is used, like you know from Allegro).

* box
* shadowbox
* button
* check *M
* radio *M
* icon
* scroller *M
* sliderh *M
* sliderv *M
* buttonsel
* iconsel
* scroll
* slidev
* slideh
* cursor *M
* menusep *M
* checked *M
* radiosel *M
* menucheck *M
* menusub *M
* edit
* list
* textbox
* menu
* menuitem
* menubar
* menubaritem
* window
* clear
* checkback
* checkbacksel
* radioback
* radiobacksel
* text
* listitem


Short descriptions what the bitmaps do
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

clear, text

Background used for d_agup_clear_proc and d_agup_text_proc.

box, shadowbox, window

Boxes, used by d_agup_box_proc, d_agup_shadow_box_proc, and
d_agup_window_proc.

button icon buttonsel iconsel

Buttons for d_agup_button_proc and d_agup_push_proc and d_agup_icon_proc.
Plus each time a version for when D_SELECTED is set.

checkback radioback checkbacksel radiobacksel

Background bitmaps for d_agup_check_proc and d_agup_radio_proc, with
versions when D_SELECTED is set.

check radio checked radiosel

Buttons for d_agup_check_proc and d_agup_radio_proc, plus versions when
D_SELECTED is set. They can contain transparency, since they are drawn over
the previous *back bitmaps.

textbox listbox edit

Box for d_agup_textbox_proc, d_agup_list_proc/d_agup_text_list_proc and
d_edit_proc.

cursor listsel

Cursor for d_agup_edit_proc, and highlighted list line for the list procs.
They can contain transparency, since they are drawn over their parent
boxes.

scroll slideh slidev

Frame for the scroller of textbox and list procs, and frames for horizontal
and vertical sliders.

scroller sliderh sliderv

Handles for the scroller and sliders. They can contain transparency, since
they are drawn over the scroll/slideh/slidev bitmaps.

menu menubar

Menu and menbar frames.

menuitem menubaritem

Single menu items/menubar items. They can't be transparent because of the
way Allegro menus work.

menusep menucheck menusub

Menu separator, menu check mark, and submenu indicator. They can all be
transparent and are drawn over the menuitem bitmap.

The 3 states for each element are normal, highlighted, and disabled. They
are specified with <name> <name_hl> and <name_dis>. The _hl version is used
when D_GOTFOCUS is set for an element, the _dis version with D_DISABLED.
The hl and dis variants are inherited from the normal state if not
specified. Again, it's best to leave them all in the config file, to avoid
any confusion.


How are bitmaps used?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A bitmap is used in the AGUP bitmap engine to fill a rectangular dialog
area. You can provide many separate bitmaps, or use the "cut" option below
to use areas inside bitmaps. In both cases, a bitmap will never get loaded
twice - AGUP is clever enough and keeps track of what bitmaps it has
already loaded since the last call to agup_init.

Each bitmap entry has the following format:

 <bitmap> = <name> [options]

Options are:

 [tile_h|sretch_h|center_h|align_h]
 [tile_v|sretch_v|center_v|align_v]
 [border <l> <r> <t> <b>]
 [cut <x> <y> <w> <h>]
 [color 0xrrggbb] (See next section)

<bitmap> may be any of the valid elements, <name> is the file/object name.
A bitmap is either centered, stretched, or tiled across a dimension of the
box it is used for. The tiling aligns in the center when no align option is
set, else the top left corner is aligned with the top left screen corner.

The cut option can be used to use a sub-bitmap. That is, only the given
pixel region out of the loaded bitmap is considered. So you can use this to
create a skin bitmap, which contains everything on a certain position, and
then just specify the positions with cut, always specifying the skin
bitmap. The bitmap will be loaded only once, and subbitmaps used to draw
the single widgets.

If a border is given, it is cut out off the given (sub-)bitmap. The 4
required numbers after 'border' are the pixels used as border to the left,
right, top and bottom, respectively. A border results in splitting the
source bitmap into 9 bitmaps like this:

 ______________
/    |    |    \
| lt | t  | rt |
|____|____|____|
|    |    |    |
| l  | c  | r  |
|____|____|____|
|    |    |    |
| lb | b  | rb |
\____|____|____/

Only the center bitmap <c> is then used for filling the destination
rectangle, the other 8 are used as a border.

The default is to tile the source bitmap across the destination rectangle,
aligning at the center, and using no borders.

Examples:

 bitmap = test.bmp

Tiles <test.bmp> across the box, aligning its center with the box center.

 bitmap = test.bmp tileh stretchv border 8 8 4 4

Cuts a 8-8-4-4 border off <test.bmp>. It means, <lt>,<rt>,<lb> and <rb> are
all sized 8 times 4 pixels, <t> and <b> are 4 pixels high and bitmap width
minus 16 pixels wide, <l> and <r> are 8 pixels wide and bitmap height minus
8 pixels high. <c> is the rest. It then fills in the 4 edges <lt> <rt> <lb>
<rb>. Tiles two 4 pixel high stripes at the top and bottom (<t> and <b>).
Then scales <l> and <r> vertically and fills out the left and right border.
Finally, scales <c> vertically, and tiles it horizontally, filling the
remaing area in the middle.

 bitmap = test.bmp center

Centers <test.bmp> inside the box.

If the bitmap is too big to fit inside the target box, and no stretching is
done, the following applies: If no border is used, it is centered in the
box, and clipped at the sides. If a border is used, the <c> bitmap is
reduced until it is completely gone. After that, the right and bottom
borders overlap the left and top ones.

The above descriptions may sound complicated, but it should get clear when
seeing it used. Just look at the example bitmap themes.


How can I set text colors?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some AGUP GUI elements require text to be displayed. In this case, the text
is printed transparently on top of whatever bitmap the AGUP bitmap engine
provides. But, just having a single color is often not enough, since the
text is most important part of some widgets and therefore its color is very
important.

The color being used for text can be specified with 'color'. It expects an
RGB hex-triplet in the form '0xRRGGBB', for example '0xFF0000' is red.
Colors are always inherited from their parent (and never from another
state, unlike bitmaps). Therefore, if you want all your text to be in the
same colors, it is sufficient to set the colors for the 'box' element.


What else can I modify?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Currently, there are the following other settings: fg, bg, mg, px, py. They
are the foreground, disabled and background colors, and the amount a
clicked button is shifted.


What other advices are there?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Don't make the bitmaps too small. There is no size optimizations applied,
so if you tile a 1x1 sized bitmap across the screen, it will result into a
blit for every pixel on the screen - which is much slower than say a few
32x32 blits.


