# CEGUI::WindowManager Class Reference

The WindowManager class describes an object that manages creation and lifetime of Window objects. More...

Collaboration diagram for CEGUI::WindowManager:

[legend]
List of all members.

## Public Types

typedef bool | PropertyCallback (Window *window, String &propname, String &propvalue, void *userdata)
| Function type that is used as a callback when loading layouts from XML; the function is called for each Property element encountered.
typedef ConstBaseIterator< WindowRegistry > | WindowIterator

## Public Member Functions

| WindowManager (void)
| Constructs a new WindowManager object.
| ~WindowManager (void)
| Destructor for WindowManager objects.
Window * | createWindow (const String &type, const String &name="")
| Creates a new Window object of the specified type, and gives it the specified unique name.
void | destroyWindow (Window *window)
| Destroy the specified Window object.
void | destroyWindow (const String &window)
| Destroy the specified Window object.
Window * | getWindow (const String &name) const
| Return a pointer to the specified Window object.
bool | isWindowPresent (const String &name) const
| Examines the list of Window objects to see if one exists with the given name.
void | destroyAllWindows (void)
| Destroys all Window objects within the system.
Window * | loadWindowLayout (const String &filename, const String &name_prefix="", const String &resourceGroup="", PropertyCallback *callback=NULL, void *userdata=NULL)
| Creates a set of windows (a Gui layout) from the information in the specified XML file.
bool | isDeadPoolEmpty (void) const
| Return whether the window dead pool is empty.
void | cleanDeadPool (void)
| Permanently destroys any windows placed in the dead pool.
void | writeWindowLayoutToStream (const Window &window, OutStream &out_stream, bool writeParent=false) const
| Writes a full XML window layout, starting at the given Window to the given OutStream.
void | writeWindowLayoutToStream (const String &window, OutStream &out_stream, bool writeParent=false) const
| Writes a full XML window layout, starting at the given Window to the given OutStream.
void | renameWindow (const String &window, const String &new_name)
| Rename a window.
void | renameWindow (Window *window, const String &new_name)
| Rename a window.
WindowIterator | getIterator (void) const
| Return a WindowManager::WindowIterator object to iterate over the currently defined Windows.

## Static Public Member Functions

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

## Static Public Attributes

static const String | GeneratedWindowNameBase
| Base name to use for generated window names.

## Detailed Description

The WindowManager class describes an object that manages creation and lifetime of Window objects.

The WindowManager is the means by which Window objects are created and destroyed. For each sub-class of Window that is to be created, there must exist a WindowFactory object which is registered with the WindowFactoryManager. Additionally, the WindowManager tracks every Window object created, and can be used to access those Window objects by name.

## Member Typedef Documentation

typedef bool CEGUI::WindowManager::PropertyCallback(Window *window, String &propname, String &propvalue, void *userdata)

Function type that is used as a callback when loading layouts from XML; the function is called for each Property element encountered.

Parameters:

  | window | Window object that the property is to be applied to.
  | propname | String holding the name of the property that is being set.
  | propvalue | String holding the new value that will be applied to the property specified by /a propname.
  | userdata | Some client code supplied data.

Returns:
  - true if the property should be set.
  - false if the property should not be set,

## Constructor & Destructor Documentation

CEGUI::WindowManager::WindowManager | ( | void |  | ) |

| Constructs a new WindowManager object. NB: Client code should not create WindowManager objects - they are of limited use to you! The intended pattern of access is to get a pointer to the GUI system's WindowManager via the System object, and use that.

CEGUI::WindowManager::~WindowManager | ( | void |  | ) |

| Destructor for WindowManager objects. This will properly destry all remaining Window objects. Note that WindowFactory objects will not be destroyed (since they are owned by whoever created them).

## Member Function Documentation

void CEGUI::WindowManager::cleanDeadPool | ( | void |  | ) |

Permanently destroys any windows placed in the dead pool.

Note:
  It is probably not a good idea to call this from a Window based event handler if the specific window has been or is being destroyed.

Returns:
  Nothing.

Window * CEGUI::WindowManager::createWindow | ( | const String & | type,
|  | const String & | name = `""`
| ) |

Creates a new Window object of the specified type, and gives it the specified unique name.

Parameters:

  | type | String that describes the type of Window to be created. A valid WindowFactory for the specified type must be registered.
  | name | String that holds a unique name that is to be given to the new window. If this string is empty (""), a name will be generated for the window.

Returns:
  Pointer to the newly created Window object.

Exceptions:

  | AlreadyExistsException | A Window object with the name name already exists.
  | UnknownObjectException | No WindowFactory is registered for type Window objects.
  | GenericException | Some other error occurred (Exception message has details).

void CEGUI::WindowManager::destroyAllWindows | ( | void |  | ) |

Destroys all Window objects within the system.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | Thrown if the WindowFactory for any Window object type has been removed.

void CEGUI::WindowManager::destroyWindow | ( | const String & | window | ) |

Destroy the specified Window object.

Parameters:

  | window | String containing the name of the Window object to be destroyed. If window is not recognised, nothing happens.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | Can be thrown if the WindowFactory for window's object type was removed.

void CEGUI::WindowManager::destroyWindow | ( | Window * | window | ) |

Destroy the specified Window object.

Parameters:

  | window | Pointer to the Window object to be destroyed. If the window is null, or is not recognised, nothing happens.

Returns:
  Nothing

Exceptions:

  | InvalidRequestException | Can be thrown if the WindowFactory for window's object type was removed.

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

Return singleton WindowManager object.

Returns:
  Singleton WindowManager object

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

Return pointer to singleton WindowManager object.

Returns:
  Pointer to singleton WindowManager object

Window * CEGUI::WindowManager::getWindow | ( | const String & | name | ) | const

Return a pointer to the specified Window object.

Parameters:

  | name | String holding the name of the Window object to be returned.

Returns:
  Pointer to the Window object with the name name.

Exceptions:

  | UnknownObjectException | No Window object with a name matching name was found.

bool CEGUI::WindowManager::isDeadPoolEmpty | ( | void |  | ) | const

Return whether the window dead pool is empty.

Returns:
  - true if there are no windows in the dead pool.
  - false if the dead pool contains >=1 window awaiting destruction.

bool CEGUI::WindowManager::isWindowPresent | ( | const String & | name | ) | const

Examines the list of Window objects to see if one exists with the given name.

Parameters:

  | name | String holding the name of the Window object to look for.

Returns:
  true if a Window object was found with a name matching name. false if no matching Window object was found.

Window * CEGUI::WindowManager::loadWindowLayout | ( | const String & | filename,
|  | const String & | name_prefix = `""`,
|  | const String & | resourceGroup = `""`,
|  | PropertyCallback * | callback = `NULL`,
|  | void * | userdata = `NULL`
| ) |

Creates a set of windows (a Gui layout) from the information in the specified XML file.

Parameters:

  | filename | String object holding the filename of the XML file to be processed.

  name_prefix

  String object holding the prefix that is to be used when creating the windows in the layout file, this function allows a layout to be loaded multiple times without having name clashes. Note that if you use this facility, then all windows defined within the layout must have names assigned; you currently can not use this feature in combination with automatically generated window names.

  | resourceGroup | Resource group identifier to be passed to the resource provider when loading the layout file.
  | callback | PropertyCallback function to be called for each Property element loaded from the layout. This is called prior to the property value being applied to the window enabling client code manipulation of properties.
  | userdata | Client code data pointer passed to the PropertyCallback function.

Returns:
  Pointer to the root Window object defined in the layout.

Exceptions:

  | FileIOException | thrown if something goes wrong while processing the file filename.
  | InvalidRequestException | thrown if filename appears to be invalid.

void CEGUI::WindowManager::renameWindow | ( | Window * | window,
|  | const String & | new_name
| ) |

Rename a window.

Parameters:

  | window | Pointer to the window to be renamed.
  | new_name | String holding the new name for the window

Exceptions:

  | AlreadyExistsException | thrown if a Window named new_name already exists.

void CEGUI::WindowManager::renameWindow | ( | const String & | window,
|  | const String & | new_name
| ) |

Rename a window.

Parameters:

  | window | String holding the current name of the window to be renamed.
  | new_name | String holding the new name for the window

Exceptions:

  | UnknownObjectException | thrown if window is not known in the system.
  | AlreadyExistsException | thrown if a Window named new_name already exists.

void CEGUI::WindowManager::writeWindowLayoutToStream | ( | const String & | window,
|  | OutStream & | out_stream,
|  | bool | writeParent = `false`
| ) | const

Writes a full XML window layout, starting at the given Window to the given OutStream.

Parameters:

  | window | String holding the name of the Window object to become the root of the layout.
  | out_stream | OutStream (std::ostream based) object where data is to be sent.
  | writeParent | If the starting window has a parent window, specifies whether to write the parent name into the Parent attribute of the GUILayout XML element.

Returns:
  Nothing.

void CEGUI::WindowManager::writeWindowLayoutToStream | ( | const Window & | window,
|  | OutStream & | out_stream,
|  | bool | writeParent = `false`
| ) | const

Writes a full XML window layout, starting at the given Window to the given OutStream.

Parameters:

  | window | Window object to become the root of the layout.
  | out_stream | OutStream (std::ostream based) object where data is to be sent.
  | writeParent | If the starting window has a parent window, specifies whether to write the parent name into the Parent attribute of the GUILayout XML element.

Returns:
  Nothing.