GG
Public Types | Static Public Member Functions | Protected Member Functions | Friends

GG::GUI Class Reference

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

#include <GUI.h>

Inheritance diagram for GG::GUI:
GG::OgreGUI GG::SDLGUI

List of all members.

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
typedef void(* SaveWndFn )(const Wnd *wnd, const std::string &name, boost::archive::xml_oarchive &ar)
typedef void(* LoadWndFn )(Wnd *&wnd, const std::string &name, boost::archive::xml_iarchive &ar)

Static Public Member Functions

static GUIGetGUI ()
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
WndFocusWnd () const
WndGetWindowUnder (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
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
AcceleratorSignalTypeAcceleratorSignal (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)
boost::shared_ptr< FontGetFont (const std::string &font_filename, unsigned int pts)
boost::shared_ptr< FontGetFont (const std::string &font_filename, unsigned int pts, const std::vector< unsigned char > &file_contents)
template<class CharSetIter >
boost::shared_ptr< FontGetFont (const std::string &font_filename, unsigned int pts, CharSetIter first, CharSetIter last)
template<class CharSetIter >
boost::shared_ptr< FontGetFont (const std::string &font_filename, unsigned int pts, const std::vector< unsigned char > &file_contents, CharSetIter first, CharSetIter last)
boost::shared_ptr< FontGetFont (const boost::shared_ptr< Font > &font, unsigned int pts)
void FreeFont (const std::string &font_filename, unsigned int pts)
boost::shared_ptr< TextureStoreTexture (Texture *texture, const std::string &texture_name)
boost::shared_ptr< TextureStoreTexture (const boost::shared_ptr< Texture > &texture, const std::string &texture_name)
boost::shared_ptr< TextureGetTexture (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 SaveWnd (const Wnd *wnd, const std::string &name, boost::archive::xml_oarchive &ar)
void LoadWnd (Wnd *&wnd, const std::string &name, boost::archive::xml_iarchive &ar)
template<class T >
void LoadWnd (T *&wnd, const std::string &name, boost::archive::xml_iarchive &ar)
void SetSaveWndFunction (SaveWndFn fn)
void SetLoadWndFunction (LoadWndFn fn)
void SetSaveLoadFunctions (const PluginInterface &interface)
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:

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:

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.

typedef void(* GG::GUI::SaveWndFn)(const Wnd *wnd, const std::string &name, boost::archive::xml_oarchive &ar)

The type of function used to serialize Wnds.

Definition at line 158 of file GUI.h.

typedef void(* GG::GUI::LoadWndFn)(Wnd *&wnd, const std::string &name, boost::archive::xml_iarchive &ar)

The type of function used to deserialize Wnds.

Definition at line 161 of file GUI.h.


Member Enumeration Documentation

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_errorMay 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.

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 412 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 417 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.
void GG::GUI::SaveWnd ( const Wnd wnd,
const std::string &  name,
boost::archive::xml_oarchive &  ar 
)

Saves wnd to the archive ar, with the xml tag name.

Exceptions:
GG::GUI::BadFunctionPointerThrows GG::GUI::BadFunctionPointer if no Wnd-serializing function has ben defined by the user using SetSaveWndFunction().
void GG::GUI::LoadWnd ( Wnd *&  wnd,
const std::string &  name,
boost::archive::xml_iarchive &  ar 
)

Loads wnd, with the xml tag name, from the archive ar.

Exceptions:
GG::GUI::BadFunctionPointerThrows GG::GUI::BadFunctionPointer if no Wnd-serializing function has ben defined by the user using SetLoadWndFunction().

Referenced by LoadWnd().

template<class T >
void GG::GUI::LoadWnd ( T *&  wnd,
const std::string &  name,
boost::archive::xml_iarchive &  ar 
)

Since LoadWnd() will only accept a referemce to a GG::Wnd*, this method is provided to more conveniently accept pointers to Wnd subclasses.

Definition at line 423 of file GUI.h.

References LoadWnd().

void GG::GUI::SetSaveLoadFunctions ( const PluginInterface interface)

Sets all the SaveWnd() and LoadWnd() function pointers to be the functions provided by interface.

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: