Using CGUI

When you want to compile and link your own program that uses CGUI you need to know the following 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: 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

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.
int InitCguiLoadMode(void)

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.
int InitCguiFullscreenMode(void)

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.
int InitCguiWindowedMode(void)

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.
int InitCguiKeepCurrent(void)

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.
void DeInitCgui(void);

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


void SetCguiColors(int exact);

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): 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