CEGUI::WindowManager Class Reference

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

Inheritance diagram for CEGUI::WindowManager:

Inheritance graph
[legend]
Collaboration diagram for CEGUI::WindowManager:

Collaboration graph
[legend]

List of all members.

Public Types

typedef ConstBaseIterator
< WindowRegistry > 
WindowIterator

Public Member Functions

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.
 WindowManager (void)
 Constructs a new WindowManager object.
 ~WindowManager (void)
 Destructor for WindowManager objects.
WindowcreateWindow (const String &type, const String &name="", const String &prefix="")
 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.
WindowgetWindow (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.
WindowloadWindowLayout (const String &filename, const String &name_prefix="", const String &resourceGroup="", PropertyCallback *callback=0, void *userdata=0)
 Creates a set of windows (a Gui layout) from the information in the specified XML file.
WindowloadWindowLayout (const String &filename, bool generateRandomPrefix)
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.
void lock ()
 Put WindowManager into the locked state.
void unlock ()
 Put WindowManager into the unlocked state.
bool isLocked () const
 Returns whether WindowManager is currently in the locked state.
WindowIterator getIterator (void) const
 Return a WindowManager::WindowIterator object to iterate over the currently defined Windows.
void DEBUG_dumpWindowNames (String zone)
 Outputs the names of ALL existing windows to log (DEBUG function).

Static Public Member Functions

static const StringgetDefaultResourceGroup ()
 Returns the default resource group currently set for layouts.
static void setDefaultResourceGroup (const String &resourceGroup)
 Sets the default resource group to be used when loading layouts.

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.


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

References cleanDeadPool(), and destroyAllWindows().


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.

Referenced by ~WindowManager().

Window * CEGUI::WindowManager::createWindow ( const String type,
const String name = "",
const String prefix = "" 
)

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:
InvalidRequestException WindowManager is locked and no Windows may be created.
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).

References CEGUI::WindowFactory::createWindow(), CEGUI::Window::d_falagardType, CEGUI::WindowFactoryManager::FalagardWindowMapping::d_lookName, CEGUI::WindowFactoryManager::FalagardWindowMapping::d_rendererType, CEGUI::String::empty(), CEGUI::WindowFactoryManager::getFactory(), CEGUI::WindowFactoryManager::getFalagardMappingForType(), CEGUI::Informative, CEGUI::WindowFactoryManager::isFalagardMappedType(), isLocked(), isWindowPresent(), CEGUI::Window::setLookNFeel(), CEGUI::Window::setPrefix(), and CEGUI::Window::setWindowRenderer().

void CEGUI::WindowManager::DEBUG_dumpWindowNames ( String  zone  ) 

Outputs the names of ALL existing windows to log (DEBUG function).

Parameters:
zone Helper string that can specify where the name dump was made (e.g. "BEFORE FRAME DELETION").
Returns:
Nothing.

References CEGUI::ConstBaseIterator< T >::getCurrentValue(), getIterator(), and CEGUI::ConstBaseIterator< T >::isAtEnd().

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.

References destroyWindow().

Referenced by ~WindowManager().

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.

References CEGUI::Window::destroy(), CEGUI::System::getSingleton(), CEGUI::Informative, and CEGUI::System::notifyWindowDestroyed().

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.

References CEGUI::Window::getName().

Referenced by CEGUI::Window::destroy(), and destroyAllWindows().

static const String& CEGUI::WindowManager::getDefaultResourceGroup ( void   )  [inline, static]

Returns the default resource group currently set for layouts.

Returns:
String describing the default resource group identifier that will be used when loading layouts.

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.

Referenced by CEGUI::GroupBox::getContentPane(), renameWindow(), and writeWindowLayoutToStream().

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::isLocked (  )  const

Returns whether WindowManager is currently in the locked state.

While WindowManager is in the locked state all attempts to create a Window of any type will fail with an InvalidRequestException being thrown. Calls to lock/unlock are recursive; if multiple calls to lock are made, WindowManager is only unlocked after a matching number of calls to unlock.

Returns:
  • true to indicate WindowManager is locked and that any attempt to create Window objects will fail.
  • false to indicate WindowManager is unlocked and that Window objects may be created as normal.

Referenced by createWindow().

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.

Referenced by createWindow(), CEGUI::Window::destroy(), CEGUI::GroupBox::getContentPane(), and CEGUI::Window::rename().

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

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

Warning:
When using a C string literal as the value for the second argument name_prefix, currently (0.6.x releases) it is likely that the incorrect overload of loadWindowLayout will be invoked (possibly without immediate error or warning). To avoid the possibility of invoking the incorrect overload by mistake, it is recommended that you explicity use the CEGUI::String type when passing name_prefix.
For example, instead of this:
 winMgr.loadWindowLayout("MyLayout.layout", "aPrefix/"); 
Do this:
 winMgr.loadWindowLayout("MyLayout.layout", CEGUI::String("aPrefix/"));
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.

References CEGUI::String::empty(), CEGUI::Errors, CEGUI::GUILayout_xmlHandler::getLayoutRootWindow(), CEGUI::System::getSingleton(), CEGUI::System::getXMLParser(), CEGUI::Informative, CEGUI::XMLParser::parseXMLFile(), and CEGUI::Standard.

void CEGUI::WindowManager::lock (  ) 

Put WindowManager into the locked state.

While WindowManager is in the locked state all attempts to create a Window of any type will fail with an InvalidRequestException being thrown. Calls to lock/unlock are recursive; if multiple calls to lock are made, WindowManager is only unlocked after a matching number of calls to unlock.

Note:
This is primarily intended for internal use within the system.

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,

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.

References CEGUI::Window::getName(), and CEGUI::Window::rename().

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.

References getWindow().

Referenced by CEGUI::Window::rename(), and CEGUI::WidgetLookFeel::renameChildren().

static void CEGUI::WindowManager::setDefaultResourceGroup ( const String resourceGroup  )  [inline, static]

Sets the default resource group to be used when loading layouts.

Parameters:
resourceGroup String describing the default resource group identifier to be used.
Returns:
Nothing.

void CEGUI::WindowManager::unlock (  ) 

Put WindowManager into the unlocked state.

While WindowManager is in the locked state all attempts to create a Window of any type will fail with an InvalidRequestException being thrown. Calls to lock/unlock are recursive; if multiple calls to lock are made, WindowManager is only unlocked after a matching number of calls to unlock.

Note:
This is primarily intended for internal use within the system.

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.

References getWindow(), and writeWindowLayoutToStream().

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.

References CEGUI::XMLSerializer::attribute(), CEGUI::XMLSerializer::closeTag(), CEGUI::Window::getName(), CEGUI::Window::getParent(), CEGUI::XMLSerializer::openTag(), and CEGUI::Window::writeXMLToStream().

Referenced by writeWindowLayoutToStream().


Generated on Thu Nov 27 20:34:33 2008 for Crazy Eddies GUI System by  doxygen 1.5.7.1