# CEGUI::System Class Reference

The System class is the CEGUI class that provides access to all other elements in this system. More...

Inheritance diagram for CEGUI::System:

[legend]
Collaboration diagram for CEGUI::System:

[legend]
List of all members.

## Public Member Functions

| System (Renderer *renderer, const utf8 *logFile=(const utf8 *)"CEGUI.log")
| Constructs a System object.
| System (Renderer *renderer, ResourceProvider *resourceProvider, const utf8 *logFile=(const utf8 *)"CEGUI.log")
| Construct a new System object.
| System (Renderer *renderer, ScriptModule *scriptModule, const utf8 *configFile=(const utf8 *)"cegui.config")
| Construct a new System object.
| System (Renderer *renderer, ScriptModule *scriptModule, ResourceProvider *resourceProvider, const utf8 *configFile=(const utf8 *)"cegui.config")
| Construct a new System object.
| System (Renderer *renderer, XMLParser *xmlParser, const utf8 *logFile=(const utf8 *)"CEGUI.log")
| Constructs a System object.
| System (Renderer *renderer, ResourceProvider *resourceProvider, XMLParser *xmlParser, const utf8 *logFile=(const utf8 *)"CEGUI.log")
| Constructs a System object.
| System (Renderer *renderer, XMLParser *xmlParser, ScriptModule *scriptModule, const utf8 *configFile=(const utf8 *)"cegui.config")
| Construct a new System object.
| System (Renderer *renderer, ResourceProvider *resourceProvider, XMLParser *xmlParser, ScriptModule *scriptModule, const utf8 *configFile=(const utf8 *)"cegui.config")
| Construct a new System object.
| ~System (void)
| Destructor for System objects.
Renderer * | getRenderer (void) const
| Return a pointer to the Renderer object being used by the system.
void | setDefaultFont (const String &name)
| Set the default font to be used by the system.
void | setDefaultFont (Font *font)
| Set the default font to be used by the system.
Font * | getDefaultFont (void) const
| Return a pointer to the default Font for the GUI system.
void | signalRedraw ()
| Causes a full re-draw next time renderGUI() is called.
bool | isRedrawRequested () const
| Return a boolean value to indicate whether a full re-draw is requested next time renderGUI() is called.
void | renderGUI (void)
| Render the GUI.
Window * | setGUISheet (Window *sheet)
| Set the active GUI sheet (root) window.
Window * | getGUISheet (void) const
| Return a pointer to the active GUI sheet (root) window.
double | getSingleClickTimeout (void) const
| Return the current timeout for generation of single-click events.
double | getMultiClickTimeout (void) const
| Return the current timeout for generation of multi-click events.
const Size & | getMultiClickToleranceAreaSize (void) const
| Return the size of the allowable mouse movement tolerance used when generating multi-click events.
void | setSingleClickTimeout (double timeout)
| Set the timeout used for generation of single-click events.
void | setMultiClickTimeout (double timeout)
| Set the timeout to be used for the generation of multi-click events.
void | setMultiClickToleranceAreaSize (const Size &sz)
| Set the size of the allowable mouse movement tolerance used when generating multi-click events.
const Image * | getDefaultMouseCursor (void) const
| Return the currently set default mouse cursor image.
void | setDefaultMouseCursor (const Image *image)
| Set the image to be used as the default mouse cursor.
void | setDefaultMouseCursor (MouseCursorImage image)
| Set the image to be used as the default mouse cursor.
void | setDefaultMouseCursor (const String &imageset, const String &image_name)
| Set the image to be used as the default mouse cursor.
Window * | getWindowContainingMouse (void) const
| Return the Window object that the mouse is presently within.
ScriptModule * | getScriptingModule (void) const
| Return a pointer to the ScriptModule being used for scripting within the GUI system.
ResourceProvider * | getResourceProvider (void) const
| Return a pointer to the ResourceProvider being used within the GUI system.
void | executeScriptFile (const String &filename, const String &resourceGroup="") const
| Execute a script file if possible.
int | executeScriptGlobal (const String &function_name) const
| Execute a scripted global function if possible. The function should not take any parameters and should return an integer.
void | executeScriptString (const String &str) const
| If possible, execute script code contained in the given CEGUI::String object.
float | getMouseMoveScaling (void) const
| return the current mouse movement scaling factor.
void | setMouseMoveScaling (float scaling)
| Set the current mouse movement scaling factor.
void | notifyWindowDestroyed (const Window *window)
| Internal method used to inform the System object whenever a window is destroyed, so that System can perform any required housekeeping.
uint | getSystemKeys (void) const
| Return the current system keys value.
XMLParser * | getXMLParser (void) const
| Return the XMLParser object.
void | setTooltip (Tooltip *tooltip)
| Set the system default Tooltip object. This value may be NULL to indicate that no default Tooltip will be available.
void | setTooltip (const String &tooltipType)
| Set the system default Tooltip to be used by specifying a Window type.
Tooltip * | getDefaultTooltip (void) const
| return a poiter to the system default tooltip. May return 0.
void | setModalTarget (Window *target)
| Internal method to directly set the current modal target.
Window * | getModalTarget (void) const
| Return a pointer to the Window that is currently the modal target.
bool | injectMouseMove (float delta_x, float delta_y)
| Method that injects a mouse movement event into the system.
bool | injectMouseLeaves (void)
| Method that injects that the mouse has left the application window.
bool | injectMouseButtonDown (MouseButton button)
| Method that injects a mouse button down event into the system.
bool | injectMouseButtonUp (MouseButton button)
| Method that injects a mouse button up event into the system.
bool | injectKeyDown (uint key_code)
| Method that injects a key down event into the system.
bool | injectKeyUp (uint key_code)
| Method that injects a key up event into the system.
bool | injectChar (utf32 code_point)
| Method that injects a typed character event into the system.
bool | injectMouseWheelChange (float delta)
| Method that injects a mouse-wheel / scroll-wheel event into the system.
bool | injectMousePosition (float x_pos, float y_pos)
| Method that injects a new position for the mouse cursor.
bool | injectTimePulse (float timeElapsed)
| Method to inject time pulses into the system.

## Static Public Member Functions

static System & | getSingleton (void)
| Return singleton System object.
static System * | getSingletonPtr (void)
| Return pointer to singleton System object.

## Static Public Attributes

static const String | EventNamespace
| Namespace for global events.
static const double | DefaultSingleClickTimeout = 0.2
| Default timeout for generation of single click events.
static const double | DefaultMultiClickTimeout = 0.33
| Default timeout for generation of multi-click events.
static const Size | DefaultMultiClickAreaSize
| Default allowable mouse movement for multi-click event generation.
static const String | EventGUISheetChanged
| Name of event fired whenever the GUI sheet is changed.
static const String | EventSingleClickTimeoutChanged
| Name of event fired when the single-click timeout is changed.
static const String | EventMultiClickTimeoutChanged
| Name of event fired when the multi-click timeout is changed.
static const String | EventMultiClickAreaSizeChanged
| Name of event fired when the size of the multi-click tolerance area is changed.
static const String | EventDefaultFontChanged
| Name of event fired when the default font changes.
static const String | EventDefaultMouseCursorChanged
| Name of event fired when the default mouse cursor changes.
static const String | EventMouseMoveScalingChanged
| Name of event fired when the mouse move scaling factor changes.

## Detailed Description

The System class is the CEGUI class that provides access to all other elements in this system.

This object must be created by the client application. The System object requires that you pass it an initialised Renderer object which it can use to interface to whatever rendering system will be used to display the GUI imagery.

## Constructor & Destructor Documentation

CEGUI::System::System | ( | Renderer * | renderer,
|  | const utf8 * | logFile = `(const utf8 *)"CEGUI.log"`
| ) |

Constructs a System object.

Parameters:

  | renderer | Pointer to the valid Renderer object that will be used to render GUI imagery
  | logFile | pointer to a utf8 encoded buffer containing the name to use for the log file.

CEGUI::System::System | ( | Renderer * | renderer,
|  | ResourceProvider * | resourceProvider,
|  | const utf8 * | logFile = `(const utf8 *)"CEGUI.log"`
| ) |

Construct a new System object.

Parameters:

  | renderer | Pointer to the valid Renderer object that will be used to render GUI imagery
  | resourceProvider | Pointer to a ResourceProvider object.
  | logFile | pointer to a utf8 encoded buffer containing the name to use for the log file.

CEGUI::System::System | ( | Renderer * | renderer,
|  | ScriptModule * | scriptModule,
|  | const utf8 * | configFile = `(const utf8 *)"cegui.config"`
| ) |

Construct a new System object.

Parameters:

  | renderer | Pointer to the valid Renderer object that will be used to render GUI imagery
  | scriptModule | Pointer to a ScriptModule object. may be NULL.
  | configFile | pointer to a utf8 encoded buffer containing the name to use for the configuration file.

CEGUI::System::System | ( | Renderer * | renderer,
|  | ScriptModule * | scriptModule,
|  | ResourceProvider * | resourceProvider,
|  | const utf8 * | configFile = `(const utf8 *)"cegui.config"`
| ) |

Construct a new System object.

Parameters:

  | renderer | Pointer to the valid Renderer object that will be used to render GUI imagery
  | scriptModule | Pointer to a ScriptModule object. may be NULL.
  | resourceProvider | Pointer to a ResourceProvider object.
  | configFile | pointer to a utf8 encoded buffer containing the name to use for the configuration file.

CEGUI::System::System | ( | Renderer * | renderer,
|  | XMLParser * | xmlParser,
|  | const utf8 * | logFile = `(const utf8 *)"CEGUI.log"`
| ) |

Constructs a System object.

Parameters:

  | renderer | Pointer to the valid Renderer object that will be used to render GUI imagery
  | xmlParser | Pointer to a valid XMLParser object to be used when parsing XML files, or NULL to use a default parser.
  | logFile | pointer to a utf8 encoded buffer containing the name to use for the log file.

CEGUI::System::System | ( | Renderer * | renderer,
|  | ResourceProvider * | resourceProvider,
|  | XMLParser * | xmlParser,
|  | const utf8 * | logFile = `(const utf8 *)"CEGUI.log"`
| ) |

Constructs a System object.

Parameters:

  | renderer | Pointer to the valid Renderer object that will be used to render GUI imagery
  | resourceProvider | Pointer to a ResourceProvider object.
  | xmlParser | Pointer to a valid XMLParser object to be used when parsing XML files, or NULL to use a default parser.
  | logFile | pointer to a utf8 encoded buffer containing the name to use for the log file.

CEGUI::System::System | ( | Renderer * | renderer,
|  | XMLParser * | xmlParser,
|  | ScriptModule * | scriptModule,
|  | const utf8 * | configFile = `(const utf8 *)"cegui.config"`
| ) |

Construct a new System object.

Parameters:

  | renderer | Pointer to the valid Renderer object that will be used to render GUI imagery
  | xmlParser | Pointer to a valid XMLParser object to be used when parsing XML files, or NULL to use a default parser.
  | scriptModule | Pointer to a ScriptModule object. may be NULL.
  | configFile | pointer to a utf8 encoded buffer containing the name to use for the configuration file.

CEGUI::System::System | ( | Renderer * | renderer,
|  | ResourceProvider * | resourceProvider,
|  | XMLParser * | xmlParser,
|  | ScriptModule * | scriptModule,
|  | const utf8 * | configFile = `(const utf8 *)"cegui.config"`
| ) |

Construct a new System object.

Parameters:

  | renderer | Pointer to the valid Renderer object that will be used to render GUI imagery
  | resourceProvider | Pointer to a ResourceProvider object.
  | xmlParser | Pointer to a valid XMLParser object to be used when parsing XML files, or NULL to use a default parser.
  | scriptModule | Pointer to a ScriptModule object. may be NULL.
  | configFile | pointer to a utf8 encoded buffer containing the name to use for the configuration file.

## Member Function Documentation

void CEGUI::System::executeScriptFile | ( | const String & | filename,
|  | const String & | resourceGroup = `""`
| ) | const

Execute a script file if possible.

Parameters:

  | filename | String object holding the filename of the script file that is to be executed
  | resourceGroup | Resource group identifier to be passed to the ResourceProvider when loading the script file.

int CEGUI::System::executeScriptGlobal | ( | const String & | function_name | ) | const

Execute a scripted global function if possible. The function should not take any parameters and should return an integer.

Parameters:

  | function_name | String object holding the name of the function, in the global script environment, that is to be executed.

Returns:
  The integer value returned from the script function.

void CEGUI::System::executeScriptString | ( | const String & | str | ) | const

If possible, execute script code contained in the given CEGUI::String object.

Parameters:

  | str | String object holding the valid script code that should be executed.

Returns:
  Nothing.

Font* CEGUI::System::getDefaultFont | ( | void |  | ) | const`[inline]`

Return a pointer to the default Font for the GUI system.

Returns:
  Pointer to a Font object that is the default font in the system.

const Image* CEGUI::System::getDefaultMouseCursor | ( | void |  | ) | const`[inline]`

Return the currently set default mouse cursor image.

Returns:
  Pointer to the current default image used for the mouse cursor. May return NULL if default cursor has not been set, or has intentionally been set to NULL - which results in a blank default cursor.

Tooltip* CEGUI::System::getDefaultTooltip | ( | void |  | ) | const`[inline]`

return a poiter to the system default tooltip. May return 0.

Returns:
  Pointer to the current system default tooltip. May return 0 if no system default tooltip is available.

Window* CEGUI::System::getGUISheet | ( | void |  | ) | const`[inline]`

Return a pointer to the active GUI sheet (root) window.

Returns:
  Pointer to the window object that has been set as the GUI root element.

Window* CEGUI::System::getModalTarget | ( | void |  | ) | const`[inline]`

Return a pointer to the Window that is currently the modal target.

Returns:
  Pointer to the current modal target. NULL if there is no modal target.

float CEGUI::System::getMouseMoveScaling | ( | void |  | ) | const

return the current mouse movement scaling factor.

Returns:
  float value that is equal to the currently set mouse movement scaling factor. Defaults to 1.0f.

double CEGUI::System::getMultiClickTimeout | ( | void |  | ) | const`[inline]`

Return the current timeout for generation of multi-click events.

A multi-click event is a double-click, or a triple-click. The value returned here is the maximum allowable time between mouse button down events for which a multi-click event will be generated.

Returns:
  double value equal to the current multi-click timeout value.

const Size& CEGUI::System::getMultiClickToleranceAreaSize | ( | void |  | ) | const`[inline]`

Return the size of the allowable mouse movement tolerance used when generating multi-click events.

This size defines an area with the mouse at the centre. The mouse must stay within the tolerance defined for a multi-click (double click, or triple click) event to be generated.

Returns:
  Size object describing the current multi-click tolerance area size.

Renderer* CEGUI::System::getRenderer | ( | void |  | ) | const`[inline]`

Return a pointer to the Renderer object being used by the system.

Returns:
  Pointer to the Renderer object used by the system.

ResourceProvider * CEGUI::System::getResourceProvider | ( | void |  | ) | const

Return a pointer to the ResourceProvider being used within the GUI system.

Returns:
  Pointer to a ResourceProvider based object.

ScriptModule * CEGUI::System::getScriptingModule | ( | void |  | ) | const

Return a pointer to the ScriptModule being used for scripting within the GUI system.

Returns:
  Pointer to a ScriptModule based object.

double CEGUI::System::getSingleClickTimeout | ( | void |  | ) | const`[inline]`

Return the current timeout for generation of single-click events.

A single-click is defined here as a button being pressed and then released.

Returns:
  double value equal to the current single-click timeout value.

System & CEGUI::System::getSingleton | ( | void |  | ) | `[static]`

Return singleton System object.

Returns:
  Singleton System object

System * CEGUI::System::getSingletonPtr | ( | void |  | ) | `[static]`

Return pointer to singleton System object.

Returns:
  Pointer to singleton System object

uint CEGUI::System::getSystemKeys | ( | void |  | ) | const`[inline]`

Return the current system keys value.

Returns:
  uint value representing a combination of the SystemKey bits.

Window* CEGUI::System::getWindowContainingMouse | ( | void |  | ) | const`[inline]`

Return the Window object that the mouse is presently within.

Returns:
  Pointer to the Window object that currently contains the mouse cursor, or NULL if none.

bool CEGUI::System::injectChar | ( | utf32 | code_point | ) |

Method that injects a typed character event into the system.

Parameters:

  | code_point | Unicode code point of the character that was typed.

Returns:
  - true if the input was processed by the gui system.
  - false if the input was not processed by the gui system.

bool CEGUI::System::injectKeyDown | ( | uint | key_code | ) |

Method that injects a key down event into the system.

Parameters:

  | key_code | uint value indicating which key was pressed.

Returns:
  - true if the input was processed by the gui system.
  - false if the input was not processed by the gui system.

bool CEGUI::System::injectKeyUp | ( | uint | key_code | ) |

Method that injects a key up event into the system.

Parameters:

  | key_code | uint value indicating which key was released.

Returns:
  - true if the input was processed by the gui system.
  - false if the input was not processed by the gui system.

bool CEGUI::System::injectMouseButtonDown | ( | MouseButton | button | ) |

Method that injects a mouse button down event into the system.

Parameters:

  | button | One of the MouseButton values indicating which button was pressed.

Returns:
  - true if the input was processed by the gui system.
  - false if the input was not processed by the gui system.

bool CEGUI::System::injectMouseButtonUp | ( | MouseButton | button | ) |

Method that injects a mouse button up event into the system.

Parameters:

  | button | One of the MouseButton values indicating which button was released.

Returns:
  - true if the input was processed by the gui system.
  - false if the input was not processed by the gui system.

bool CEGUI::System::injectMouseLeaves | ( | void |  | ) |

Method that injects that the mouse has left the application window.

Returns:
  - true if the generated mouse move event was handled.
  - false if the generated mouse move event was not handled.

bool CEGUI::System::injectMouseMove | ( | float | delta_x,
|  | float | delta_y
| ) |

Method that injects a mouse movement event into the system.

Parameters:

  | delta_x | amount the mouse moved on the x axis.
  | delta_y | amount the mouse moved on the y axis.

Returns:
  - true if the input was processed by the gui system.
  - false if the input was not processed by the gui system.

bool CEGUI::System::injectMousePosition | ( | float | x_pos,
|  | float | y_pos
| ) |

Method that injects a new position for the mouse cursor.

Parameters:

  | x_pos | New absolute pixel position of the mouse cursor on the x axis.
  | y_pos | New absolute pixel position of the mouse cursoe in the y axis.

Returns:
  - true if the generated mouse move event was handled.
  - false if the generated mouse move event was not handled.

bool CEGUI::System::injectMouseWheelChange | ( | float | delta | ) |

Method that injects a mouse-wheel / scroll-wheel event into the system.

Parameters:

  | delta | float value representing the amount the wheel moved.

Returns:
  - true if the input was processed by the gui system.
  - false if the input was not processed by the gui system.

bool CEGUI::System::injectTimePulse | ( | float | timeElapsed | ) |

Method to inject time pulses into the system.

Parameters:

  | timeElapsed | float value indicating the amount of time passed, in seconds, since the last time this method was called.

Returns:
  Currently, this method always returns true.

bool CEGUI::System::isRedrawRequested | ( |  | ) | const`[inline]`

Return a boolean value to indicate whether a full re-draw is requested next time renderGUI() is called.

Returns:
  true if a re-draw has been requested

void CEGUI::System::notifyWindowDestroyed | ( | const Window * | window | ) |

Internal method used to inform the System object whenever a window is destroyed, so that System can perform any required housekeeping.

Note:
  This method is not intended for client code usage. If you use this method anything can, and probably will, go wrong!

void CEGUI::System::renderGUI | ( | void |  | ) |

Render the GUI.

Depending upon the internal state, this may either re-use rendering from last time, or trigger a full re-draw from all elements.

Returns:
  Nothing

void CEGUI::System::setDefaultFont | ( | Font * | font | ) |

Set the default font to be used by the system.

Parameters:

  | font | Pointer to the font to be used as the system default.

Returns:
  Nothing.

void CEGUI::System::setDefaultFont | ( | const String & | name | ) |

Set the default font to be used by the system.

Parameters:

  | name | String object containing the name of the font to be used as the system default.

Returns:
  Nothing.

void CEGUI::System::setDefaultMouseCursor | ( | const String & | imageset,
|  | const String & | image_name
| ) |

Set the image to be used as the default mouse cursor.

Parameters:

  | imageset | String object that contains the name of the Imageset that contains the image to be used.
  | image_name | String object that contains the name of the Image on imageset that is to be used.

Returns:
  Nothing.

Exceptions:

  | UnknownObjectException | thrown if imageset is not known, or if imageset contains no Image named image_name.

void CEGUI::System::setDefaultMouseCursor | ( | MouseCursorImage | image | ) | `[inline]`

Set the image to be used as the default mouse cursor.

Parameters:

  | image | One of the MouseCursorImage enumerated values.

Returns:
  Nothing.

void CEGUI::System::setDefaultMouseCursor | ( | const Image * | image | ) |

Set the image to be used as the default mouse cursor.

Parameters:

  | image | Pointer to an image object that is to be used as the default mouse cursor. To have no cursor rendered by default, you can specify NULL here.

Returns:
  Nothing.

Window * CEGUI::System::setGUISheet | ( | Window * | sheet | ) |

Set the active GUI sheet (root) window.

Parameters:

  | sheet | Pointer to a Window object that will become the new GUI 'root'

Returns:
  Pointer to the window that was previously set as the GUI root.

void CEGUI::System::setModalTarget | ( | Window * | target | ) | `[inline]`

Internal method to directly set the current modal target.

Note:
  This method is called internally by Window, and must be used by client code. Doing so will most likely not have the expected results.

void CEGUI::System::setMouseMoveScaling | ( | float | scaling | ) |

Set the current mouse movement scaling factor.

Parameters:

  | scaling | float value specifying the scaling to be applied to mouse movement inputs.

Returns:
  nothing.

void CEGUI::System::setMultiClickTimeout | ( | double | timeout | ) |

Set the timeout to be used for the generation of multi-click events.

A multi-click event is a double-click, or a triple-click. The value returned here is the maximum allowable time between mouse button down events for which a multi-click event will be generated.

Parameters:

  | timeout | double value equal to the multi-click timeout value to be used from now onwards.

Returns:
  Nothing.

void CEGUI::System::setMultiClickToleranceAreaSize | ( | const Size & | sz | ) |

Set the size of the allowable mouse movement tolerance used when generating multi-click events.

This size defines an area with the mouse at the centre. The mouse must stay within the tolerance defined for a multi-click (double click, or triple click) event to be generated.

Parameters:

  | sz | Size object describing the multi-click tolerance area size to be used.

Returns:
  Nothing.

void CEGUI::System::setSingleClickTimeout | ( | double | timeout | ) |

Set the timeout used for generation of single-click events.

A single-click is defined here as a button being pressed and then released.

Parameters:

  | timeout | double value equal to the single-click timeout value to be used from now onwards.

Returns:
  Nothing.

void CEGUI::System::setTooltip | ( | const String & | tooltipType | ) |

Set the system default Tooltip to be used by specifying a Window type.

System will internally attempt to create an instance of the specified window type (which must be derived from the base Tooltip class). If the Tooltip creation fails, the error is logged and no system default Tooltip will be available.

Parameters:

  | tooltipType | String object holding the name of the Tooltip based Window type which should be used as the Tooltip for the system default.

Returns:
  Nothing.

void CEGUI::System::setTooltip | ( | Tooltip * | tooltip | ) |

Set the system default Tooltip object. This value may be NULL to indicate that no default Tooltip will be available.

Parameters:

  | tooltip | Pointer to a valid Tooltip based object which should be used as the default tooltip for the system, or NULL to indicate that no system default tooltip is required. Note that when passing a pointer to a Tooltip object, ownership of the Tooltip does not pass to System.

Returns:
  Nothing.

void CEGUI::System::signalRedraw | ( |  | ) | `[inline]`

Causes a full re-draw next time renderGUI() is called.

Returns:
  Nothing