Home

Welcome to the guisan wiki!

Guisan is an updated version of Guichan for SDL2.

Installation

Once you have cloned the repository, build the library and its examples by typing

scons

Note: this will not build the demo.
To install, type

sudo scons install

which will install the library, its header files and the pkg-config file at the appropriate places. The authors of Guichan have made an amazing work in documenting their code, but to generate a more user-friendly documentation in HTML, type

doxygen Doxyfile

Adding guisan to your project

As is the case with most libraries, make sure you link your program with the -lguisan option. Because guisan requires SDL2, SDL2_image and SDL2_ttf, guisan needs to appear before them in the compilation command. It may also be necessary to indicate the correct directory where the headers are installed.

If your project uses autotools, you can check for the presence of guisan on the system with pkg-config using the PKG_CHECK_MODULES macro in your configure.ac file.
If instead you prefer CMake, thanks to the use of pkg-config, you can use the PKG_SEARCH_MODULE macro to look for guisan.

Using guisan

Note: this part builds upon the knowledge gained from reading the examples provided.

The first step is to add the necessary headers in your source file:

#include <guisan.hpp> /* mandatory */
#include <guisan/sdl.hpp> /* needed for SDL-specific implementations */

Pay attention to the fact that in the case of errors, guisan uses C++ exceptions instead of the integer return codes and SDL_{Set/Get}Error combo used by other SDL libraries. Make sure you catch them!
All the widgets and classes provided by guisan are located in the namespace gcn.

Library initialization

Several objects need to be created to be able to use guisan in your project. According to the examples provided, the required parts are:

• a Graphics object, like an SDLGraphics to handle widget drawing
• an Input object to manage events
• an ImageLoader, which is used internally to... load images, for example to create Icons or ImageButtons
• a GUI object
• a Font object to draw texts such as Labels or captions. Guisan provides ImageFont out of the box, but if you prefer to use TrueType fonts, SDLTrueTypeFont is also available (imported from Guichan, justifies the SDL2_ttf dependency).
• a Container object. Indeed, the GUI object can only contain one widget, so if you plan to use more than one at the same time, the Container is the only way to go.

Please note: guisan is not compatible (yet) with the new SDL2 Render API! See SDL2Graphics for an attempt to fix this.
In the meantime, the workaround I found consists of:

• creating a dedicated SDL_Surface with the dimensions of your window. Fill it with an opaque color (I recommend magenta), then set this color as the colorkey for this surface. Set its blend mode to SDL_BLENDMODE_NONE.
• from this SDL_Surface, create a SDL_Texture using SDL_CreateTextureFromSurface. Set the blend mode of this texture to SDL_BLENDMODE_BLEND.
• Set the target surface for the Graphics object to your dedicated surface.

Event loop

The next step is to include guisan in your game event loop.

• At the end of your event processing code, add a call to the pushInput(SDL_Event event) method of the gcn::SDLInput object to make guisan aware of this event.
• Then, we would like the GUI to process this event. To do so, call the logic() method of the Gui object. No parameter is needed.
• If you use SDLGraphics with the workaround explained above: now is the time to clear your dedicated surface using SDL_FillRect() and a transparent color (alpha value of 0).
• Next, it is time to draw the updates to the target surface, using the draw() method of the Gui object. Again, no parameter is needed.
• If you use SDLGraphics with the workaround explained above: update your dedicated texture with the contents of the dedicated GUI surface using SDL_UpdateTexture, then do SDL_RenderCopy to copy the texture contents to the renderer.
• Finally, we tell SDL to display the changes on the screen with a call to SDL_UpdateWindowSurface() if you use the window surface, or SDL_RenderPresent() if you use a renderer.

Please see the examples sdlwidgets.cpp and sdl2widgets.cpp for the 2 possible solutions (SDLGraphics + GetWindowSurface or SDL2Graphics + renderer).