Helper Macros in Guiliani

Overview

The following is an overview of useful helper macros which allow for easy and convenient access to many of Guiliani's core components.

There are two kinds of macros provided. The first set of macros are available to get access to certain components of the framework. The second set helps to define data contents guiliani needs. For example Ids for controls or Ids and parameters for fonts and images.

Getter Macros

When writing an application with Guiliani you will make heavy use of features that are implemented in dedicated Guiliani classes. For instance if you wish to implement an animated object that loads an image, draws it to screen and displays an internationalized text next to it, you will already be accessing CGUITimer (for the animation callback), CGUIResourceManager (for loading the image), CGfxWrap (for drawing it to the screen) and CGUILocalisationHandler (for the multilingual text).

To make the developer's life easier and the resulting code more readable, a set of helper macros has been introduced, which grant access to the respective Guiliani components in a compact and memorable form. This list offers all these macros at a glance:

Helper macro	Required include	Description
GETGFX	include "GfxWrap.h"	Access to the graphics wrapper (CGfxWrap), for performing graphic operations such as blitting an image, drawing a rectangle etc.
GETFNT	include "FntWrap.h"	Access to the font wrapper (CFntWrap). Usually not relevant for user-code.
GETSND	include "SndWrap.h"	Access to the Sound wrapper (CSndWrap). Used for audio playback.
GETRESMANAGER	include "GUIResourceManager.h"	Access to the Resource Manager (CGUIResourceManager). Used for registering, requesting and freeing all types of resources, such as images, fonts or sounds.
GETRESHANDLER	include "GUIResourceFileHandler.h"	Access to the Resource File Handler (CGUIResourceFileHandler). Allows accessing files independent of the availability of an actual filesystem. Files can also reside in a resource-file or at a given location in flash memory.
GETLOCALEHDL	include "GUILocalisationHandler.h"	Access to the Localisation Handler (CGUILocalisationHandler). Used for dealing with internationalized texts.
GET_LAYOUT_HELPER	include "GUILayoutHelper.h"	Access to the Layout Helper (CGUILayoutHelper). Offers convenience methods for layouting objects within the GUI.
GETPROPHDL	include "GUIProperties.h"	Access to the Property handler (CGUIProperties). Allows storing values of various types and later accessing them via an abstract property ID.
GETEVENTHDL	include "GUIEventHandler.h"	Access to the Event Handler (CGUIEventHandler). The event handler forwards incoming evens (e.g. user input) to the respective objects within the GUI, while taking their current status into account. You may also use the EventHandler for retrieving the currently focused or highlighted objects within the GUI.
GETGUI	include "GUI.h"	Access to main GUI object (CGUI). This grants access to the GUI's root object, i.e. the GUICompositeObject which contains all other objects within the application.
GETCMDHDL	include "GUICommandHandler.h"	Access to CommandHandler (CGUICommandHandler). The CommandHandler offers a generic and thread-safe interface, which is ideally suited for communication between the GUI and an underlying application logic.
GETINPUTSTREAM	include "GUIStreamReader.h"	Access to the active StreamReader (CGUIStreamReader). Use this interface when reading data from a streaming file (independent of format, e.g. XML or binary)
GETOUTPUTSTREAM	include "GUIStreamWriter.h"	Access to the active StreamWriter (CGUIStreamWriter). Use this interface when writing data to a streaming file (independent of format, e.g. XML or binary)
GETTIMER	include "GUITimer.h"	Access to the Timer component (CGUITimer). The timer offers the possibility to register callbacks which will be periodically called. You may use this for instance when implementing animation effects.
GETFILESYS	include "GUIFileSysWrap.h"	Access to the FileSystem-Wrapper (CGUIFileSysWrap). This offers basic filesystem operations (such as searching for files or creating directories) independent of the underlying operating system.
GETFACTORY	include "GUIFactoryManager.h"	Access to the Factory Manager (CGUIFactoryManager). Allows the registration of customized user factories, for loading additional customized controls, commands or behaviours from a streaming file.

Data Macros

We start with a short example used to define image ids and associated image information (you will find the original code in GUIImageResource.h). The define IMAGE_TABLE is used to contain the complete list of images and the associated data. Therefore, it is important to know that the whole list is a single define and it is necessary to always use a "\" as continuation character as it is used for that purpose by C and C++. Every single image is encapsulated within this list inside an ENTRY macro. For images the macro has 3 parameters (image id, image file name and the permanent flag). <br> During compilation these parameters will be extracted where needed. The first parameter for example is used to create an enumeration of all image ids as you can see below. To have a better understanding on how the preprocessor is used please have a look at http://en.wikipedia.org/wiki/X_Macro.<br> <br> Your own images have to be added within UserImageResource.h following the same concept. The only slight difference is, that you add the entries to USER_IMAGE_TABLE, while Guiliani internal images are added into IMAGE_TABLE.<br> <br> The same approach is used in nearly all places were ids have to be defined. For example: <br> object ids: @ref ObjectHandle_t.<br> image ids: @ref ImageResource_t.<br> font ids: @ref FontResource_t.<br> and many more ...<br> <br> @code //Add Guiliani-ImageResources here: #define IMAGE_TABLE \ ENTRY(IMG_STDCTRL_GAUGE_NEEDLE, "GaugeNeedle.png", true) \ ENTRY(IMG_STDCTRL_GAUGE, "Gauge.png", true) \ . . . ENTRY(DUMMY_IMAGE, "DUMMY_IMAGE", true) #ifndef GUILIANI_GUILIANILIB #include "UserImageResource.h" #endif enum ImageResource_t { IMG_START_TAG=-84, #define ENTRY_ENUM(a) a, #define ENTRY(a, b, c) a, IMAGE_TABLE #ifndef GUILIANI_GUILIANILIB USER_IMAGE_TABLE #endif #undef ENTRY #undef ENTRY_ENUM NOF_IMAGERESOURCES, GUILIANI_INTERNAL_IMG = INT_MAX // Do not touch this. Required for ensuring consistent enum type size across libraries. }; @endcode <br> <H1>Conversion from old style ids to new macro style ids:</H1> <br> Below you can see the same code piece from above using the old style of id definitions as they are used inside Guiliani in the past. That means the enum id has to be wrapped inside an ENTRY() macro. This macro can have varying number of parameters, but minimal one. The first parameter will always be the enum id equivalent to the use in the past. The other parameters are described within the corresponding GUI*Resource.h header files. For images for example the second parameter is the filename of the image and the last parameter defines if the image should stay permanently in memory. <br> <br> @code enum ImageResource_t { IMG_START_TAG=-84, //Add Guiliani-ImageResources here: IMG_STDCTRL_GAUGE_NEEDLE, IMG_STDCTRL_GAUGE, . . . DUMMY_IMAGE, #ifndef GUILIANI_GUILIANILIB #include "UserImageResource.h" #endif NOF_IMAGERESOURCES, GUILIANI_INTERNAL_IMG = INT_MAX // Do not touch this. Required for ensuring consistent enum type size across libraries. };
The last two parameters can be used to automatically register the images with guiliani with the following statements:

// Register images.
#define ENTRY(img, img_name, img_permanent)  GETRESMANAGER.RegisterImageResource(img_name, img, img_permanent);
    USER_IMAGE_TABLE
#undef ENTRY

The RegisterImageResource call will be generated by the preprocessor automatically for every ENTRY you have defined within your UserImageResource.h file.