A Brief Tour

In a library as diverse in functionality as GG, it can be difficult even to figure out what the library has to offer.

This "tour" is designed to provide a brief overview of the various features of GG not covered elsewhere, and to point users to the more detailed information elsewhere in the documentation. The topics are covered in no particular order.

First off, it should be noted that there is a lot of general overview-type documentation in the GG::Wnd and GG::GUI detailed documentation. Many of the things mentioned below are covered there in more detail.

Event Filters

Event filtering allows one to use a Wnd to intrusively handle the events sent to another Wnd. This can be useful, for example, in a control (the parent) that is composed of multiple controls (the children), but which needs to handle certain events uniformly. Perhaps left-clicks should always bring up a context menu, for instance. Without event filtering, each child control would have to explicitly forward its left-clicks instead of processing them normally, which would in turn require subclassing. Event filters remove the need for such subclassing.

See also:

The GG::Wnd description, GG::Wnd::EventFilter(), GG::Wnd::InstallEventFilter(), and GG::Wnd::RemoveEventFilter().

Layouts

GG::Layout encapsulates the relative arrangement of child Wnds in the client area of a Wnd, so that positioning such children requires less hand-coding.

See also:

The GG::Wnd description.

The Browse-Info System

Like "tooltips", but more general. You can have any non-interactive GUI elements you like inside of a GG::BrowseInfoWnd, and the contents of the GG::BrowseInfoWnd can vary, for example to provide increasing amounts of info over time.

See also:

The GG::Wnd description.

The Style Factory

Many of the control classes reuse other controls to do part of their work. For instance, GG::Scroll uses a pair of GG::Button objects for its up and down (or left and right) buttons. If a user wishes to use a custom subclass of GG::Button throughout an application, how is she to get GG::Scroll to create GG::Button's of the right type? The answer is that all controls created by GG are requested from a GG::StyleFactory.

See also:

The GG::Wnd description and the GG::GUI description.

Plugins

Plugins (dynamically loaded shared libraries/DLLs not linked into the application when it is built) can be created and used with GG. Plugins provide a GG::StyleFactory, a default font name and size, and functions to serialize and deserialize GG::Wnd's.

See also:

GG::PluginInterface.

Standard Dialogs

Three standard dialogs are provided:

• A color selection dialog, GG::ColorDlg;
• A file(s)/directory selection dialog, GG::FileDlg; and
• A general-purpose message dialog containing at most three buttons, GG::ThreeButtonDlg.

Cursor Rendering

GG can optionally render a cursor. By default, GG assumes that the underlying system is rendering the cursor, and so does not attempt to do so.

See also:

GG::GUI::RenderCursor(), GG::GUI::GetCursor(), GG::GUI::SetCursor(), and GG::Cursor.

Flags

GG uses format flags, window creation flags, and several other types of bit-flag sets in various places. These bit-flag sets are not interoperable. This is designed as a workaround to problems inherent to C++ enums, such as implicit conversion to integral types, which in turn leads to comparability of arbitrary enumeration values from different enumerations. For instance, it is impossible (due to a compile-time error) to accidentally pass the (nonsensical) flag FORMAT_NONE to the flags parameter of GG::Wnd::Wnd(). With built-in C++ enums, this would not be caught by the compiler. GG provides two classes, GG::Flags and GG::FlagSpec, that allow the user to extend the sets of flags used in GG, if user-created subclasses should require more flags than the ones GG provides.

Text Formatting Tags

Text rendered by GG can make use of text formatting tags, similar to those used in HTML documents (e.g. <i>italicized text here</i>). GG defines numerous tags that control text justification, text color, bolding, underlining, italicizing, etc. Users can also add their own tags. Though GG does not associate any semantics with user-defined tags, it will treat them as tags, meaning they will be automatically be removed from the text as it appears when rendered.

See also:

The GG::Font description.

Keyboard Accelerators

Keyboard accelerators may be established that emit signals on (and possibly filter out) keystrokes. Accelerators can include a modifier specification, so for instance Ctrl-K, Alt-K, and K may be created as different accelerators. Each accelerator has an associated signal to which arbitrarily many slots can be connected.

See also:

The GG::GUI description.

User Input Drivers

Two input drivers are currently available for use with GG -- one for SDL and one for Ogre. Note that Ogre does not have built-in support for user input. As of this writing, it uses another library called OIS. An Ogre plugin that provides OIS support is also provided in src/Ogre/Plugins.

See also:

GG::SDLGUI, GG::OgreGUI, GG::OgreGUIInputPlugin, and OISInput.

Timers

Timers are available, to which slots can be connected. A timer fires its signal after at least T time has elapsed, where T is a user-provided time interval. Note the use of "at least". Timers are only evaluated during GG's normal processing loop, so if the application is cycling slowly (due to heavy processing, etc.), timers can fire arbitrarily less frequently than desired.

Event Pumps

GG abstracts out the inner loop that processes events and renders frames, into a class called GG::EventPump. Most users will never need to use event pumps, but those users writing a new input driver will.

---