GG: GG::GUI Class Reference

GG

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Static Public Member Functions | Protected Member Functions | Friends | List of all members
GG::GUI Class Referenceabstract

`#include <GUI.h>`

Inheritance diagram for GG::GUI:

## Public Types
enum | EventType { IDLE, KEYPRESS, KEYRELEASE, LPRESS, MPRESS, RPRESS, LRELEASE, MRELEASE, RRELEASE, MOUSEMOVE, MOUSEWHEEL }
typedef std::set< std::pair < Key, Flags< ModKey > > >::iterator | accel_iterator
typedef std::set< std::pair < Key, Flags< ModKey > > >::const_iterator | const_accel_iterator

## Static Public Member Functions
static GUI * | GetGUI ()
static void | RenderWindow (Wnd *wnd)

## Protected Member Functions
virtual void | Run ()=0

## Friends
class | EventPumpBase

## Signal Types
typedef boost::signal< bool(), OrCombiner > | AcceleratorSignalType

## Structors
virtual | ~GUI ()
| GUI (const std::string &app_name)

## Accessors
const std::string & | AppName () const
Wnd * | FocusWnd () const
Wnd * | GetWindowUnder (const Pt &pt) const
unsigned int | DeltaT () const
virtual unsigned int | Ticks () const =0
bool | RenderingDragDropWnds () const
bool | FPSEnabled () const
double | FPS () const
std::string | FPSString () const
double | MaxFPS () const
virtual X | AppWidth () const =0
virtual Y | AppHeight () const =0
unsigned int | ButtonDownRepeatDelay () const
unsigned int | ButtonDownRepeatInterval () const
unsigned int | DoubleClickInterval () const
unsigned int | MinDragTime () const
unsigned int | MinDragDistance () const
bool | DragDropWnd (const Wnd *wnd) const
bool | AcceptedDragDropWnd (const Wnd *wnd) const
bool | MouseButtonDown (unsigned int bn) const
Pt | MousePosition () const
Pt | MouseMovement () const
Flags< ModKey > | ModKeys () const
bool | MouseLRSwapped () const
const std::map< Key, Key > & | KeyMap () const
virtual std::set< std::pair < CPSize, CPSize > > | FindWords (const std::string &str) const
const boost::shared_ptr < StyleFactory > & | GetStyleFactory () const
bool | RenderCursor () const
const boost::shared_ptr< Cursor > & | GetCursor () const
const_accel_iterator | accel_begin () const
const_accel_iterator | accel_end () const
AcceleratorSignalType & | AcceleratorSignal (Key key, Flags< ModKey > mod_keys=MOD_KEY_NONE) const
void | SaveWndAsPNG (const Wnd *wnd, const std::string &filename) const

## Mutators
void | operator() ()
virtual void | Exit (int code)=0
virtual void | HandleSystemEvents ()=0
void | HandleGGEvent (EventType event, Key key, boost::uint32_t key_code_point, Flags< ModKey > mod_keys, const Pt &pos, const Pt &rel)
void | SetFocusWnd (Wnd *wnd)
virtual void | Wait (unsigned int ms)
void | Register (Wnd *wnd)
void | RegisterModal (Wnd *wnd)
void | Remove (Wnd *wnd)
void | WndDying (Wnd *wnd)
void | MoveUp (Wnd *wnd)
void | MoveDown (Wnd *wnd)
virtual boost::shared_ptr < ModalEventPump > | CreateModalEventPump (bool &done)
void | RegisterDragDropWnd (Wnd *wnd, const Pt &offset, Wnd *originating_wnd)
void | CancelDragDrop ()
void | RegisterTimer (Timer &timer)
void | RemoveTimer (Timer &timer)
virtual void | Enter2DMode ()=0
virtual void | Exit2DMode ()=0
void | EnableFPS (bool b=true)
void | SetMaxFPS (double max)
void | EnableMouseButtonDownRepeat (unsigned int delay, unsigned int interval)
void | SetDoubleClickInterval (unsigned int interval)
void | SetMinDragTime (unsigned int time)
void | SetMinDragDistance (unsigned int distance)
accel_iterator | accel_begin ()
accel_iterator | accel_end ()
void | SetAccelerator (Key key, Flags< ModKey > mod_keys=MOD_KEY_NONE)
void | RemoveAccelerator (Key key, Flags< ModKey > mod_keys=MOD_KEY_NONE)
void | RemoveAccelerator (accel_iterator it)
void | SetMouseLRSwapped (bool swapped=true)
void | SetKeyMap (const std::map< Key, Key > &key_map)
boost::shared_ptr< Font > | GetFont (const std::string &font_filename, unsigned int pts)
boost::shared_ptr< Font > | GetFont (const std::string &font_filename, unsigned int pts, const std::vector< unsigned char > &file_contents)
template<class CharSetIter >
boost::shared_ptr< Font > | GetFont (const std::string &font_filename, unsigned int pts, CharSetIter first, CharSetIter last)
template<class CharSetIter >
boost::shared_ptr< Font > | GetFont (const std::string &font_filename, unsigned int pts, const std::vector< unsigned char > &file_contents, CharSetIter first, CharSetIter last)
boost::shared_ptr< Font > | GetFont (const boost::shared_ptr< Font > &font, unsigned int pts)
void | FreeFont (const std::string &font_filename, unsigned int pts)
boost::shared_ptr< Texture > | StoreTexture (Texture *texture, const std::string &texture_name)
boost::shared_ptr< Texture > | StoreTexture (const boost::shared_ptr< Texture > &texture, const std::string &texture_name)
boost::shared_ptr< Texture > | GetTexture (const std::string &name, bool mipmap=false)
void | FreeTexture (const std::string &name)
void | SetStyleFactory (const boost::shared_ptr< StyleFactory > &factory)
void | RenderCursor (bool render)
void | SetCursor (const boost::shared_ptr< Cursor > &cursor)
void | ProcessBrowseInfo ()
virtual void | RenderBegin ()=0
virtual void | Render ()
virtual void | RenderEnd ()=0
void | SetFPS (double FPS)
void | SetDeltaT (unsigned int delta_t)

## Exceptions
| GG_ABSTRACT_EXCEPTION (Exception)
| GG_CONCRETE_EXCEPTION (BadFunctionPointer, GG::GUI, Exception)

## Detailed Description

An abstract base for an GUI framework class to drive the GG GUI.

This class has all the essential services that GG requires:

- GUI initialization and emergency exit
- GG event handling
- rendering of GUI windows
- entry into and cleanup after a "2D" mode, in case the app also uses non-orthographic 3D projections
- registration into, removal from, and movement within a z-ordering of windows, including handling of "always-on-top" windows
- handling of modal windows
- drag-and-drop support
- inter-frame time updates and FPS calculations
- limits on FPS speed
- access to the dimensions of the application window or screen
- mouse state information
- keyboard accelerators
- management of fonts and textures

The user is required to provide several functions. The most vital functions the user is required to provide are: Enter2DMode(), Exit2DMode(), DeltaT(), PollAndRender() [virtual private], and Run() [virtual private]. Without these, GUI is pretty useless. In addition, HandleEvent() must be driven from PollAndRender(). The code driving HandleEvent() must interact with the hardware and/or operating system, and supply the appropriate EventType's, key presses, and mouse position info to HandleEvent(). It is the author's recommendation that the user use one of the provided SDL and Ogre drivers to do this.

Keyboard accelerators may be defined, as mentioned above. Each defined accelerator has its own signal which is emitted each time the accelerator is detected. Client code should listen to the appropriate signal to act on an accelerator invocation. Each slot that is signalled with a keyboard accelerator should return true if it processed the accelerator, or false otherwise. This lets GUI know whether or not it should create a keystroke event and process it normally, sending it to the Wnd that currently has focus. Note that since signals can be connected to multiple slots, if even one slot returns true, no kestroke event is created. It is perfectly legal to return false even if an accelerator is processed, as long as you also then want the focus Wnd to receive a keystroke event. Also, note that all accelerators are processed before, and possbily instead of, any key events. So setting a plain "h" as a keyboard accelerator can (if it is processed normally by a slot) prevent any Wnd anywhere in your application from receiving "h" keystrokes. To avoid this:

- Define accelerators with modifier keys like CTRL and ALT, or
- Have slots that process these accelerators return false, or
- Do not connect anything to such an accelerator, in which case it will return false.

A GUI-wide StyleFactory can be set; this controls the actual types of controls and dialogs that are created when a control or dialog creates one (e.g. when FileDlg encounters an error and creates a ThreeButtonDlg). This is overridden by any StyleFactory that may be installed in an individual Wnd.

A note about "button-down-repeat". When you click on the down-button on a scroll-bar, you probably expect the the button's action (scrolling down one increment) to repeat when you hold down the button, much like the way kestrokes are repeated when you hold down a keyboard key. This is in fact what happens, and it is accomplished by having the scroll and its buttons respond to extra LButtonDown events generated by the GUI. These extra messages, occur ButtonDownRepeatDelay() milliseconds after the button is first depressed, repeating every ButtonDownRepeatInterval() milliseconds thereafter. Only Wnds created with the REPEAT_BUTTON_DOWN flag receive such extra messages.

Definition at line 116 of file GUI.h.

## Member Typedef Documentation

typedef boost::signal<bool (), OrCombiner> GG::GUI::AcceleratorSignalType

Emitted when a keyboard accelerator is invoked. A return value of true indicates that the accelerator was processed by some slot; otherwise, a keystroke event is processed instead.

Definition at line 130 of file GUI.h.

typedef std::set<std::pair<Key, Flags<ModKey> > >::iterator GG::GUI::accel_iterator

The type of iterator returned by non-const accel_begin() and accel_end().

Definition at line 151 of file GUI.h.

typedef std::set<std::pair<Key, Flags<ModKey> > >::const_iterator GG::GUI::const_accel_iterator

The type of iterator returned by const accel_begin() and accel_end().

Definition at line 155 of file GUI.h.

## Member Enumeration Documentation

enum GG::GUI::EventType

These are the only events absolutely necessary for GG to function properly

Enumerator
IDLE | nothing has changed since the last message, but the GUI might want to update some things anyway
KEYPRESS | a down key press or key repeat, with or without modifiers like Alt, Ctrl, Meta, etc.
KEYRELEASE | a key release, with or without modifiers like Alt, Ctrl, Meta, etc.
LPRESS | a left mouse button press
MPRESS | a middle mouse button press
RPRESS | a right mouse button press
LRELEASE | a left mouse button release
MRELEASE | a middle mouse button release
RRELEASE | a right mouse button release
MOUSEMOVE | movement of the mouse; may include relative motion in addition to absolute position
MOUSEWHEEL | rolling of the mouse wheel; this event is accompanied by the amount of roll in the y-component of the mouse's relative position (+ is up, - is down)

Definition at line 135 of file GUI.h.

## Member Function Documentation

virtual std::set<std::pair<CPSize, CPSize> > GG::GUI::FindWords | ( | const std::string & | str | ) | const
| virtual

Returns the (begin, end) indices of the code points of all the word-tokens in the given string. This is perhaps an odd place for this function to exist, but the notion of what a "word" is is so application-specific that it was placed here so that users can customize this behavior.

const_accel_iterator GG::GUI::accel_begin | ( |  | ) | const

Returns an iterator to one past the first defined keyboard accelerator.

const_accel_iterator GG::GUI::accel_end | ( |  | ) | const

Returns an iterator to one past the last defined keyboard accelerator.

AcceleratorSignalType& GG::GUI::AcceleratorSignal | ( | Key | key,
|  | Flags< ModKey > | mod_keys = `MOD_KEY_NONE`
| ) |  | const

Returns the signal that is emitted when the requested keyboard accelerator is invoked.

void GG::GUI::SaveWndAsPNG | ( | const Wnd * | wnd,
|  | const std::string & | filename
| ) |  | const

Saves wnd to file filename during the next render cycle. If wnd is not rendered during the render cycle, or PNG support is not enabled, this is a no-op.

virtual void GG::GUI::HandleSystemEvents | ( |  | ) |
| pure virtual

Handles all waiting system events (from SDL, DirectInput, etc.). This function should only be called from custom EventPump event handlers.

Implemented in GG::OgreGUI, and GG::SDLGUI.

void GG::GUI::RegisterDragDropWnd | ( | Wnd * | wnd,
|  | const Pt & | offset,
|  | Wnd * | originating_wnd
| ) |  |

Adds wnd to the set of current drag-and-drop Wnds, to be rendered offset pixels from the cursor position. originating_wnd indicates the original owner of wnd before the drag-and-drop.

Exceptions

  std::runtime_error | May throw std::runtime_error if there are already other Wnds registered that belong to a window other than originating_wnd.

accel_iterator GG::GUI::accel_begin | ( |  | ) |

Returns an iterator to the first defined keyboard accelerator.

accel_iterator GG::GUI::accel_end | ( |  | ) |

Returns an iterator to one past the last defined keyboard accelerator.

void GG::GUI::SetAccelerator | ( | Key | key,
|  | Flags< ModKey > | mod_keys = `MOD_KEY_NONE`
| ) |  |

Establishes a keyboard accelerator. Any key modifiers may be specified, or none at all.

void GG::GUI::RemoveAccelerator | ( | Key | key,
|  | Flags< ModKey > | mod_keys = `MOD_KEY_NONE`
| ) |  |

Removes a keyboard accelerator. Any key modifiers may be specified, or none at all.

void GG::GUI::RemoveAccelerator | ( | accel_iterator | it | ) |

Removes a keyboard accelerator.

void GG::GUI::SetMouseLRSwapped | ( | bool | swapped = `true` | ) |

Sets whether to swap left and right mouse button events.

void GG::GUI::SetKeyMap | ( | const std::map< Key, Key > & | key_map | ) |

Sets which Key presses are substitued for actual key presses before event handling.

boost::shared_ptr<Font> GG::GUI::GetFont | ( | const std::string & | font_filename,
|  | unsigned int | pts
| ) |  |

Returns a shared_ptr to the desired font, supporting all printable ASCII characters.

boost::shared_ptr<Font> GG::GUI::GetFont | ( | const std::string & | font_filename,
|  | unsigned int | pts,
|  | const std::vector< unsigned char > & | file_contents
| ) |  |

Returns a shared_ptr to the desired font, supporting all printable ASCII characters, from the in-memory contents file_contents.

template<class CharSetIter >

boost::shared_ptr< Font > GG::GUI::GetFont | ( | const std::string & | font_filename,
|  | unsigned int | pts,
|  | CharSetIter | first,
|  | CharSetIter | last
| ) |  |

Returns a shared_ptr to the desired font, supporting all the characters in the UnicodeCharsets in the range [first, last).

Definition at line 390 of file GUI.h.

References GG::FontManager::GetFont(), and GG::GetFontManager().

template<class CharSetIter >

boost::shared_ptr< Font > GG::GUI::GetFont | ( | const std::string & | font_filename,
|  | unsigned int | pts,
|  | const std::vector< unsigned char > & | file_contents,
|  | CharSetIter | first,
|  | CharSetIter | last
| ) |  |

Returns a shared_ptr to the desired font, supporting all the characters in the UnicodeCharsets in the range [first, last), from the in-memory contents file_contents.

Definition at line 395 of file GUI.h.

References GG::FontManager::GetFont(), and GG::GetFontManager().

boost::shared_ptr<Font> GG::GUI::GetFont | ( | const boost::shared_ptr< Font > & | font,
|  | unsigned int | pts
| ) |  |

Returns a shared_ptr to existing font font in a new size, pts.

void GG::GUI::FreeFont | ( | const std::string & | font_filename,
|  | unsigned int | pts
| ) |  |

Removes the desired font from the managed pool; since shared_ptr's are used, the font may be deleted much later

boost::shared_ptr<Texture> GG::GUI::StoreTexture | ( | Texture * | texture,
|  | const std::string & | texture_name
| ) |  |

Adds an already-constructed texture to the managed pool

Warning
  calling code must not delete texture; the texture pool will do that.

GG::GUI::GG_ABSTRACT_EXCEPTION | ( | Exception |  | ) |

The base class for GUI exceptions.

GG::GUI::GG_CONCRETE_EXCEPTION | ( | BadFunctionPointer | ,
|  | GG::GUI | ,
|  | Exception |
| ) |  |

Thrown when an attempt is made to invoke either of the save- or load-window functions before they have been set.

The documentation for this class was generated from the following file:

- GUI.h