GG
|
An abstract base for an GUI framework class to drive the GG GUI. More...
#include <GUI.h>
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 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 |
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) |
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 | 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) |
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.
typedef boost::signal<bool (), OrCombiner> GG::GUI::AcceleratorSignalType |
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().
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().
typedef void(* GG::GUI::SaveWndFn)(const Wnd *wnd, const std::string &name, boost::archive::xml_oarchive &ar) |
typedef void(* GG::GUI::LoadWndFn)(Wnd *&wnd, const std::string &name, boost::archive::xml_iarchive &ar) |
enum GG::GUI::EventType |
These are the only events absolutely necessary for GG to function properly
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) |
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.
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.
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.
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.
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().
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
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.
GG::GUI::BadFunctionPointer | Throws 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.
GG::GUI::BadFunctionPointer | Throws GG::GUI::BadFunctionPointer if no Wnd-serializing function has ben defined by the user using SetLoadWndFunction(). |
Referenced by LoadWnd().
void GG::GUI::LoadWnd | ( | T *& | wnd, |
const std::string & | name, | ||
boost::archive::xml_iarchive & | ar | ||
) |
void GG::GUI::SetSaveLoadFunctions | ( | const PluginInterface & | 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.