When you want to compile and link your own program that uses CGUI you need
to know the following
-
To satisfy the compiler you need to #include <cgui.h> in the top of
each file that uses a function from the CGUI library.
-
Before calling any CGUI function you must have initialised CGUI once.
-
To satisfy the linker you need to tell the linker that you want to use
the Allegro library and the CGUI library. You also need to tell if you
want to link dynamic or static, and the choice you do need of course the
corresponding libraries to be installed.
How to tell the linker this, may differ depending on which compiler and
development environment you use. You are supposed to be familiar with
the platform you use. Here are mentioned only some possibilities:
- If you use gcc (or djgpp or mingw32) and link on the command line,
link with '-lcgui -lalleg'. It is in this case important that you
specify the libraries in that order. If you instead want to use
the debug version of the libraray, then link with '-lcguid'
instead of '-lcgui'.
- If you use RHIDE, go to the menu Options/Libraries and fill
in 'cgui'. It is important that 'cgui' is before 'alleg'. Don't
forget to check the box to the left of the library. You have to
replace 'cgui' with 'cguid' to include debugging information.
- If you use MSVC version 6.0 the integrated environment and have
a "Win32 Application" project, the setting may possibly be done
the following way. "Project" menu -> "Settings" opens a
dialogue. Select the "Link" tab. Chose "Category" to "General".
Add the text "alleg.lib cgui.lib" at end of "Object/Library
modules" separated with a space.
-
The dialogues in CGUI may want to save and restore som user settings in
the default allegro.cfg file. If that file is not present the dialoues
will work anyway, only that the changes will never be stored. You don't
need to type any initial data into the config file.
There is a minor allegro.cfg in the examples directory of CGUI. You will
find another one in your installation of Allegro. It is supposed to be
located in the directory of your program executable.
-
To make the keyboard work as you are used with (country specific
keyboard), then you need to have the allegro.cfg present, and you need
to type in it the prefered keyboard. See comments in the file.
-
If you need to use some of the dialogs in CGUI you will find that it uses
the english language. Actually there is a possibilty to chose any other
language. This is also done in the allegro.cfg file. Currently there
are only two choices, swedish and english. If you want to translate to
your favourite language, just contact me for instructions about how to do.
-
The default font used int CGUI may not satisfy the requirements of your
language. If so, just make your own font using Allegro, load it using
Allegro, and tell CGUI to use it (see section Fonts).
-
The steps needed to build a simple dialogue is the following:
- Create a dialogue window (by a call to `MkDialogue'). This is still
not visible.
- Put some objects into that window (e.g. `AddButton', `AddEditBox' etc).
- Make it all visible by calling `DisplayWin'.
- Call `ProcessEvents', which will start scanning keyboard and mouse
for events. If you e.g. have a Close button and the user klicks that
button, you funcation (the one passed to `AddButton') will be called
back. Typically it should call `CloseWin' to close the window, and
`StopProcessEvents' to force `ProcessEvents' to stop (and the
execution will continue at the code line after the call to
`ProcessEvents').
Fundamental in CGUI is the event driven approach. This means that your
program doesn't need to check for certain operator actions like mouse
clicks and key presses. Instead you must write functions that will be
called by CGUI when those events occure. Therefore you must inform CGUI
which function to call. You do that by passing a pointer to your
function when creating any object that needs such a callback.
Your callback function may do whatever it likes, e.g. start a new
dialogue (i.e. put another window above the current) or close the
current window or exit (by calling exit) or call `StopProcessEvents', etc.
A few word to those that are not used with function pointers:
Maybe you find the declaration of functions in CGUI a bit messy because
of the callback parameter, but don't worry - when writing your code for
the actual call you will find it quite ok.
The C-code in the callback may look like the code of any of the functions
you have written before, there are no special requirements except that
the declaration (the function head) must match that of the function
pointer - so there will be a void* pointer involved in most cases.
Example:
...
my_type *my_data;
...
AddButton(DOWNLEFT, "OK", my_okfun, my_data);
...
void my_okfun(void *data)
{
my_type *my_data = data;
/* Do whatever you need */
}
The declaration of the function passed to AddButton must be like above
(i.e. taking a single parameter of type void*). To use the data you need
to copy the pointer to one of a type that is not void* like above. That
type must of course be the one of the last parameter passed to AddButton.
When passing your function pointer and data pointer lika this, e.g.
AddButton(DOWNLEFT, "Label", fptr, dataptr);
You should think like this:
When the button is pressed by the user, the call fptr(dataptr);
will be done, and you must write the code of fptr to match that.
Lots of important functions in CGUI needs function pointer and void*
pointers, and they should all be handled similarly.
There are also several examples in the directory "cgui/examples" which
can be useful to look at.
int InitCgui(int w, int h, int color_depth);
This function initializes CGUI. This includes setting a graphic mode
as specified by the parameters. CGUI will also take over the keyboard
and mouse, and this is done by the initialization function. A desktop
will be created automatically.
There are some alternative initialization functions: InitCguiLoadMode,
InitCguiFullscreenMode, InitCguiWindowedMode and InitCguiKeepCurrent
that differs only in how the graphics is initialized. Se the sections
for these if you want to know details.
Parameters:
- w,h: The size of the desktop. In case of full screen mode this is also
the screen resolution, else the (inner) size of the window.
- color_depth: The colour depth to be used, expressed in bits, see
Allegro's `set_color_depth' for info about color dephts.
Simple initialisation: just call the initialization function at
program start (i.e. without initializing any part of Allegro, CGUI will
do that for you).
Whenever CGUI fails to set a graphics mode (this applies also to the
alternative initialization functions) it will do the following:
The first attempt is to try another colour depth. If the requested colour
depth was
- 8 no more try
- 15 it will try 16
- 16 it will try 15
- 24 it will try in order 32, 16, 15
- 32 it will try in order 24, 16, 15
If the above fails, it will try with a lower pixel resolution and the
same sequence as above including the requested colour depth. This will be
repeared until an accepted screen mode was found or there are only modes
using 8 bits colour depth left (in which case it will try all resolutions
from 640x480 and less in 8 bpp, and if still no one is accepted it will
terminate the program by a call to exit).
You can do subsequent calls to `InitCgui' to change the the screen
mode (resolution and/or colour depth). Some CGUI-objects needs to be
notified about the change, so to handle a screen mode change properly
you should use this method instead of setting it directly with Allegro's
set_gfx_mode() (if you still prefere the latter way you should call
InitCgui afterwards).
Returns always non-0 (does never fail).
See also:
InitCguiLoadMode,
InitCguiFullscreenMode,
InitCguiWindowedMode,
InitCguiKeepCurrent,
DeInitCgui.
Will look for a full screen mode setting in the current config file.
[cgui:screen-res]
Width = 1024
Height = 768
Colour_depth = 15
The above numbers are a examples, you can preset these values to whateever
you like. If you make CGUI's screen mode selector available for the user
of your program that dialogue will uppdate the values.
If no settings were found, then 1024x768x32 will be used.
See also:
InitCgui,
DeInitCgui.
Will try to pick the current screen mode from the system and then
use these when trying to set a full screen mode.
See also:
InitCgui,
DeInitCgui.
Will try to keep the current screen mode of a windowed environment and
try to set the CGUI screen to windowed mode, with the same colour depth,
and a window size equal to the next smaller possible resolution.
See also:
InitCgui,
DeInitCgui.
Will no set the grapics mode at all. This requires the graphic to be
initialized before calling InitCguiKeepCurrent (i.e. call set_gfx_mode
first).
Note! If you have set a paletted mode: CGUI will make no changes to the
palette. It is just assuming that the colors values cgui_* are set to
make a nice GUI. See `SetCguiColors' if you will make a better setting.
See also:
InitCgui,
DeInitCgui,
SetCguiColors.
Closes all windows, removes the event queue and frees all data
allocated by CGUI.
DeInitCgui will be automatically called at exit, so normally you don't
need to call it yourself.
NOTE! It is important that you call DeInitCgui NOT from within any
callback from CGUI, i.e. the call must be after the event processing
has terminated (immediately after the call to ProcessEvents()).
If graphics were initialized before the first call to InitCgui() then the
screen content will be restored to what is was by that time, but the
screen mode will not.
See also:
InitCgui.
int cgui_ver, cgui_rev, cgui_minor_rev, cgui_release_date;
Version 1.6.9
Searches in the current palette to find the entries that matches CGUI's
colour needings as close as possible. If `exact' is non-zero the found
entries of the palette will be adjusted to be exact those needed for
CGUI. If `exact' is 0 the pallette will be left unchanged and your images
possibly using it will be correct, but the apperance of CGUI may be
different. The CGUI colour variables and their initial values in case of
pallette are (in case of true colour the values will be those indicated
by their names):
- cgui_white 255
- cgui_lgray 254
- cgui_gray 253
- cgui_dgray 252
- cgui_black 251
- cgui_lblue 250
- cgui_blue 249
- cgui_dblue 248
- cgui_red 247
When you first initilize CGUI and request for a palletted colour depth
these entries of the current pallette will
If you later makes changes in the pallete and avoid to change these
indecies (above 246) then the CGUI look will be the same as before.
See also:
InitCgui.
int HookExit(int id, void (*ExitFun)(void *data), void *data);
This function installs the callback function `ExitFun'. This is a pointer
to a function written by you. It will be called by CGUI when the object
`id' is destroyed, and it will be passed the pointer `data'.
If `id' refers to an object that has an "action-callback", like e.g.
a button that has a call-back that will be called when the button is
clicked, and such a function destroys the object `id' then `ExitFun'
will be called when the "action-callback" is finished. To be more precise,
`ExitFun' will be pushed on to the event queue.
Installing an `ExitFun' may be useful if you want to free some memory
allocated for e.g. a dialog, and wants a somple way to catch all
possibilities of its closing.
Returns 1 if id referes to an existing object, otherwise 0.
See also:
InitCgui,
DeInitCgui,
CloseWin,
Remove,
Destroy.
Back to contents