Crazy Eddie's GUI System  0.8.4
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Pages
CEGUI::Element Class Reference

A positioned and sized rectangular node in a tree graph. More...

Inherits CEGUI::PropertySet, CEGUI::EventSet, and CEGUI::AllocatedObject< Element >.

Inherited by CEGUI::NamedElement.

+ Collaboration diagram for CEGUI::Element:

Classes

class  CachedRectf
 A tiny wrapper to hide some of the dirty work of rect caching. More...
 

Public Member Functions

 Element ()
 Constructor.
 
virtual ~Element ()
 Destructor.
 
ElementgetParentElement () const
 Retrieves parent of this element. More...
 
virtual void setArea (const UVector2 &pos, const USize &size)
 Set the Element area. More...
 
void setArea (const UDim &xpos, const UDim &ypos, const UDim &width, const UDim &height)
 
void setArea (const URect &area)
 
const URectgetArea () const
 Return the element's area. More...
 
void setPosition (const UVector2 &pos)
 Set the element's position. More...
 
void setXPosition (const UDim &pos)
 
void setYPosition (const UDim &pos)
 
const UVector2getPosition () const
 Get the element's position. More...
 
const UDimgetXPosition () const
 
const UDimgetYPosition () const
 
virtual void setHorizontalAlignment (const HorizontalAlignment alignment)
 Set the horizontal alignment. More...
 
HorizontalAlignment getHorizontalAlignment () const
 Get the horizontal alignment. More...
 
virtual void setVerticalAlignment (const VerticalAlignment alignment)
 Set the vertical alignment. More...
 
VerticalAlignment getVerticalAlignment () const
 Get the vertical alignment. More...
 
void setSize (const USize &size)
 Set the element's size. More...
 
void setWidth (const UDim &width)
 
void setHeight (const UDim &height)
 
USize getSize () const
 Get the element's size. More...
 
UDim getWidth () const
 
UDim getHeight () const
 
void setMinSize (const USize &size)
 Set the element's minimum size. More...
 
const USizegetMinSize () const
 Get the element's minimum size. More...
 
void setMaxSize (const USize &size)
 Set the element's maximum size. More...
 
const USizegetMaxSize () const
 Get the element's maximum size. More...
 
void setAspectMode (const AspectMode mode)
 Sets current aspect mode and recalculates the area rect. More...
 
AspectMode getAspectMode () const
 Retrieves currently used aspect mode. More...
 
void setAspectRatio (const float ratio)
 Sets target aspect ratio. More...
 
float getAspectRatio () const
 Retrieves target aspect ratio. More...
 
void setPixelAligned (const bool setting)
 Sets whether this Element is pixel aligned (both position and size, basically the 4 "corners"). More...
 
bool isPixelAligned () const
 Checks whether this Element is pixel aligned. More...
 
const Vector2fgetPixelPosition () const
 Return the element's absolute (or screen, depending on the type of the element) position in pixels. More...
 
const SizefgetPixelSize () const
 Return the element's size in pixels. More...
 
Sizef calculatePixelSize (bool skipAllPixelAlignment=false) const
 Calculates this element's pixel size. More...
 
Sizef getParentPixelSize (bool skipAllPixelAlignment=false) const
 Return the pixel size of the parent element. More...
 
void setRotation (const Quaternion &rotation)
 sets rotation of this widget More...
 
const QuaterniongetRotation () const
 retrieves rotation of this widget More...
 
void addChild (Element *element)
 Add the specified Element as a child of this Element. More...
 
void removeChild (Element *element)
 Remove the Element Element's child list. More...
 
ElementgetChildElementAtIdx (size_t idx) const
 return a pointer to the child element that is attached to 'this' at the given index. More...
 
size_t getChildCount () const
 Returns number of child elements attached to this Element.
 
bool isChild (const Element *element) const
 Checks whether given element is attached to this Element.
 
bool isAncestor (const Element *element) const
 Checks whether the specified Element is an ancestor of this Element. More...
 
void setNonClient (const bool setting)
 Set whether the Element is non-client. More...
 
bool isNonClient () const
 Checks whether this element was set to be non client. More...
 
const CachedRectfgetUnclippedOuterRect () const
 Return a Rect that describes the unclipped outer rect area of the Element. More...
 
const CachedRectfgetUnclippedInnerRect () const
 Return a Rect that describes the unclipped inner rect area of the Element. More...
 
const CachedRectfgetUnclippedRect (const bool inner) const
 Return a Rect that describes the unclipped area covered by the Element. More...
 
virtual const CachedRectfgetClientChildContentArea () const
 Return a Rect that is used by client child elements as content area. More...
 
virtual const CachedRectfgetNonClientChildContentArea () const
 Return a Rect that is used by client child elements as content area. More...
 
const CachedRectfgetChildContentArea (const bool non_client=false) const
 Return a Rect that is used to position and size child elements. More...
 
virtual void notifyScreenAreaChanged (bool recursive=true)
 Inform the element and (optionally) all children that screen area has changed. More...
 
virtual const SizefgetRootContainerSize () const
 Return the size of the root container (such as screen size). More...
 
- Public Member Functions inherited from CEGUI::PropertySet
 PropertySet (void)
 Constructs a new PropertySet object.
 
virtual ~PropertySet (void)
 Destructor for PropertySet objects.
 
void addProperty (Property *property)
 Adds a new Property to the PropertySet. More...
 
void removeProperty (const String &name)
 Removes a Property from the PropertySet. More...
 
PropertygetPropertyInstance (const String &name) const
 Retrieves a property instance (that was previously added) More...
 
void clearProperties (void)
 Removes all Property objects from the PropertySet. More...
 
bool isPropertyPresent (const String &name) const
 Checks to see if a Property with the given name is in the PropertySet. More...
 
const StringgetPropertyHelp (const String &name) const
 Return the help text for the specified Property. More...
 
String getProperty (const String &name) const
 Gets the current value of the specified Property. More...
 
template<typename T >
PropertyHelper< T >::return_type getProperty (const String &name) const
 Gets the current value of the specified Property. More...
 
void setProperty (const String &name, const String &value)
 Sets the current value of a Property. More...
 
template<typename T >
void setProperty (const String &name, typename PropertyHelper< T >::pass_type value)
 Sets the current value of a Property. More...
 
bool isPropertyDefault (const String &name) const
 Returns whether a Property is at it's default value. More...
 
String getPropertyDefault (const String &name) const
 Returns the default value of a Property as a String. More...
 
PropertyIterator getPropertyIterator (void) const
 Return a PropertySet::PropertyIterator object to iterate over the available Properties.
 
- Public Member Functions inherited from CEGUI::EventSet
 EventSet ()
 Constructor for EventSet objects.
 
virtual ~EventSet (void)
 Destructor for EventSet objects.
 
void addEvent (const String &name)
 Creates a new Event object with the given name and adds it to the EventSet. More...
 
void addEvent (Event &event)
 Adds the given Event object to the EventSet. Ownership of the object passes to EventSet and it will be deleted when it is removed from the EventSet - whether explicitly via removeEvent or when the EventSet is destroyed. More...
 
void removeEvent (const String &name)
 Removes the Event with the given name. All connections to the event are disconnected, and the underlying Event object is destroyed. More...
 
void removeEvent (Event &event)
 Removes the given event from the EventSet. All connections to the event are disconnected, and the event object is destroyed. More...
 
void removeAllEvents (void)
 Remove all Event objects from the EventSet. Add connections will be disconnected, and all Event objects destroyed.
 
bool isEventPresent (const String &name)
 Checks to see if an Event with the given name is present in this EventSet. More...
 
virtual Event::Connection subscribeEvent (const String &name, Event::Subscriber subscriber)
 Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...
 
virtual Event::Connection subscribeEvent (const String &name, Event::Group group, Event::Subscriber subscriber)
 Subscribes a handler to the specified group of the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...
 
template<typename Arg1 , typename Arg2 >
Event::Connection subscribeEvent (const String &name, Arg1 arg1, Arg2 arg2)
 Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...
 
template<typename Arg1 , typename Arg2 >
Event::Connection subscribeEvent (const String &name, Event::Group group, Arg1 arg1, Arg2 arg2)
 Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...
 
virtual Event::Connection subscribeScriptedEvent (const String &name, const String &subscriber_name)
 Subscribes the named Event to a scripted funtion. More...
 
virtual Event::Connection subscribeScriptedEvent (const String &name, Event::Group group, const String &subscriber_name)
 Subscribes the specified group of the named Event to a scripted funtion. More...
 
virtual void fireEvent (const String &name, EventArgs &args, const String &eventNamespace="")
 Fires the named event passing the given EventArgs object. More...
 
bool isMuted (void) const
 Return whether the EventSet is muted or not. More...
 
void setMutedState (bool setting)
 Set the mute state for this EventSet. More...
 
EventgetEventObject (const String &name, bool autoAdd=false)
 Return a pointer to the Event object with the given name, optionally adding such an Event object to the EventSet if it does not already exist. More...
 
EventIterator getEventIterator (void) const
 Return a EventSet::EventIterator object to iterate over the events currently added to the EventSet.
 

Static Public Attributes

static const String EventNamespace
 Namespace for global events.
 
static const String EventSized
 
static const String EventParentSized
 
static const String EventMoved
 
static const String EventHorizontalAlignmentChanged
 
static const String EventVerticalAlignmentChanged
 
static const String EventRotated
 
static const String EventChildAdded
 
static const String EventChildRemoved
 
static const String EventZOrderChanged
 
static const String EventNonClientChanged
 

Protected Types

typedef std::vector< Element
*CEGUI_VECTOR_ALLOC(Element *)> 
ChildList
 definition of type used for the list of attached child elements.
 
- Protected Types inherited from CEGUI::EventSet
typedef std::map< String,
Event *, StringFastLessCompare
CEGUI_MAP_ALLOC(String, Event *)> 
EventMap
 

Protected Member Functions

void addElementProperties ()
 Add standard CEGUI::Element properties.
 
virtual void setArea_impl (const UVector2 &pos, const USize &size, bool topLeftSizing=false, bool fireEvents=true)
 Implementation method to modify element area while correctly applying min / max size processing, and firing any appropriate events. More...
 
bool isInnerRectSizeChanged () const
 helper to return whether the inner rect size has changed
 
virtual void setParent (Element *parent)
 Set the parent element for this element object. More...
 
virtual void addChild_impl (Element *element)
 Add given element to child list at an appropriate position.
 
virtual void removeChild_impl (Element *element)
 Remove given element from child list.
 
virtual Rectf getUnclippedOuterRect_impl (bool skipAllPixelAlignment) const
 Default implementation of function to return Element's outer rect area.
 
virtual Rectf getUnclippedInnerRect_impl (bool skipAllPixelAlignment) const
 Default implementation of function to return Element's inner rect area.
 
void fireAreaChangeEvents (const bool moved, const bool sized)
 helper to fire events based on changes to area rect
 
void notifyChildrenOfSizeChange (const bool non_client, const bool client)
 
virtual void onSized (ElementEventArgs &e)
 Handler called when the element's size changes. More...
 
virtual void onParentSized (ElementEventArgs &e)
 Handler called when this element's parent element has been resized. If this element is the root / GUI Sheet element, this call will be made when the display size changes. More...
 
virtual void onMoved (ElementEventArgs &e)
 Handler called when the element's position changes. More...
 
virtual void onHorizontalAlignmentChanged (ElementEventArgs &e)
 Handler called when the horizontal alignment setting for the element is changed. More...
 
virtual void onVerticalAlignmentChanged (ElementEventArgs &e)
 Handler called when the vertical alignment setting for the element is changed. More...
 
virtual void onRotated (ElementEventArgs &e)
 Handler called when the element's rotation is changed. More...
 
virtual void onChildAdded (ElementEventArgs &e)
 Handler called when a child element is added to this element. More...
 
virtual void onChildRemoved (ElementEventArgs &e)
 Handler called when a child element is removed from this element. More...
 
virtual void onNonClientChanged (ElementEventArgs &e)
 Handler called when the element's non-client setting, affecting it's position and size relative to it's parent is changed. More...
 
- Protected Member Functions inherited from CEGUI::EventSet
void fireEvent_impl (const String &name, EventArgs &args)
 Implementation event firing member.
 
ScriptModulegetScriptModule () const
 Helper to return the script module pointer or throw.
 
 EventSet (EventSet &)
 
EventSetoperator= (EventSet &)
 

Protected Attributes

ChildList d_children
 The list of child element objects attached to this.
 
Elementd_parent
 Holds pointer to the parent element.
 
bool d_nonClient
 true if element is in non-client (outside InnerRect) area of parent.
 
URect d_area
 This element objects area as defined by a URect.
 
HorizontalAlignment d_horizontalAlignment
 Specifies the base for horizontal alignment.
 
VerticalAlignment d_verticalAlignment
 Specifies the base for vertical alignment.
 
USize d_minSize
 current minimum size for the element.
 
USize d_maxSize
 current maximum size for the element.
 
AspectMode d_aspectMode
 How to satisfy current aspect ratio.
 
float d_aspectRatio
 The target aspect ratio.
 
bool d_pixelAligned
 If true, the position and size are pixel aligned.
 
Sizef d_pixelSize
 Current constrained pixel size of the element.
 
Quaternion d_rotation
 Rotation of this element (relative to the parent)
 
CachedRectf d_unclippedOuterRect
 outer area rect in screen pixels
 
CachedRectf d_unclippedInnerRect
 inner area rect in screen pixels
 
- Protected Attributes inherited from CEGUI::EventSet
EventMap d_events
 
bool d_muted
 true if events for this EventSet have been muted.
 

Additional Inherited Members

- Public Types inherited from CEGUI::PropertySet
typedef ConstMapIterator
< PropertyRegistry > 
PropertyIterator
 
- Public Types inherited from CEGUI::EventSet
typedef ConstMapIterator
< EventMap > 
EventIterator
 

Detailed Description

A positioned and sized rectangular node in a tree graph.

This class implements positioning, alignment, sizing including minimum and maximum size constraining. In its bare essense it's an unnamed rectangular node that may contain other unnamed rectangular nodes.

Unless you are implementing new CEGUI functionality you do NOT want to use this class directly. You most likely want to use CEGUI::Window.

See Also
CEGUI::Window

Member Function Documentation

void CEGUI::Element::addChild ( Element element)

Add the specified Element as a child of this Element.

If the Element element is already attached to a different Element, it is detached before being added to this Element.

Parameters
elementPointer to the Element object to be added.
Exceptions
InvalidRequestExceptionthrown if Element element is NULL.
InvalidRequestExceptionthrown if Element element is "this" element
InvalidRequestExceptionthrown if Element element is an ancestor of this Element, to prevent cyclic Element structures.
Sizef CEGUI::Element::calculatePixelSize ( bool  skipAllPixelAlignment = false) const

Calculates this element's pixel size.

Parameters
skipAllPixelAlignmentShould all pixel-alignment be skipped when calculating the pixel size?

If you want to get the pixel size you most probably want to use the Element::getPixelSize method. This method skips caching and might impact performance!

const URect& CEGUI::Element::getArea ( ) const
inline

Return the element's area.

Sets the area occupied by this Element. The defined area is offset from
one of the corners and edges of this Element's parent element (depending on alignments)
or from the top-left corner of the display if this element has no parent
(i.e. it is the root element).
Returns
URect describing the rectangle of the element area.
See Also
UDim
AspectMode CEGUI::Element::getAspectMode ( ) const
inline

Retrieves currently used aspect mode.

See Also
Element::setAspectMode
float CEGUI::Element::getAspectRatio ( ) const
inline

Retrieves target aspect ratio.

See Also
Element::setAspectRatio
const CachedRectf& CEGUI::Element::getChildContentArea ( const bool  non_client = false) const
inline

Return a Rect that is used to position and size child elements.

It is used as the reference area for positioning and its size is used for the scale components of position and size.

Note
By and large the area returned here will be the same as the unclipped inner rect (for client content) or the unclipped outer rect (for non client content), although certain advanced uses will require alternative Rects to be returned.
The behaviour of this function is modified by overriding the protected Element::getClientChildContentArea and/or Element::getNonClientChildContentArea functions.
Parameters
non_client
  • true to return the non-client child content area.
  • false to return the client child content area (default).
Element* CEGUI::Element::getChildElementAtIdx ( size_t  idx) const
inline

return a pointer to the child element that is attached to 'this' at the given index.

Parameters
idxIndex of the child element who's pointer should be returned. This value is not bounds checked, client code should ensure that this is less than the value returned by getChildCount().
Returns
Pointer to the child element currently attached at index position idx
virtual const CachedRectf& CEGUI::Element::getClientChildContentArea ( ) const
virtual

Return a Rect that is used by client child elements as content area.

Client content area is used for relative sizing, positioning and clipping of child elements that are client (their NonClient property is "false").

See Also
Element::getChildContentArea

Reimplemented in CEGUI::ScrolledContainer, CEGUI::LayoutContainer, and CEGUI::LayoutCell.

UDim CEGUI::Element::getHeight ( ) const
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

HorizontalAlignment CEGUI::Element::getHorizontalAlignment ( ) const
inline

Get the horizontal alignment.

Returns the horizontal alignment for the element. This setting affects
how the element's position is interpreted relative to its parent.
Returns
One of the HorizontalAlignment enumerated values.
const USize& CEGUI::Element::getMaxSize ( ) const
inline

Get the element's maximum size.

Gets the maximum size that this element area may occupy (whether size
changes occur by user interaction, general system operation, or by
direct setting by client code).
Returns
UVector2 describing the maximum size of the element's area.
See Also
Element::setMaxSize
const USize& CEGUI::Element::getMinSize ( ) const
inline

Get the element's minimum size.

Gets the minimum size that this element's area may occupy (whether size
changes occur by user interaction, general system operation, or by
direct setting by client code).
Returns
UVector2 describing the minimum size of the element's area.
See Also
Element::setMinSize
virtual const CachedRectf& CEGUI::Element::getNonClientChildContentArea ( ) const
virtual

Return a Rect that is used by client child elements as content area.

Client content area is used for relative sizing, positioning and clipping of child elements that are non-client (their NonClient property is "true").

See Also
Element::getChildContentArea

Reimplemented in CEGUI::ScrolledContainer.

Element* CEGUI::Element::getParentElement ( ) const
inline

Retrieves parent of this element.

Returns
pointer to parent or 0, 0 means that this Element is a root of the subtree it represents
Sizef CEGUI::Element::getParentPixelSize ( bool  skipAllPixelAlignment = false) const

Return the pixel size of the parent element.

If this element doesn't have any parent, the display size will be returned. This method returns a valid Sizef object in all cases.

Returns
Size object that describes the pixel dimensions of this Element's parent
const Vector2f& CEGUI::Element::getPixelPosition ( ) const
inline

Return the element's absolute (or screen, depending on the type of the element) position in pixels.

Returns
Vector2f object describing this element's absolute position in pixels.
const Sizef& CEGUI::Element::getPixelSize ( ) const
inline

Return the element's size in pixels.

Returns
Size object describing this element's size in pixels.
const UVector2& CEGUI::Element::getPosition ( ) const
inline

Get the element's position.

Sets the position of the area occupied by this element. The position is offset from
one of the corners of this Element's parent element (depending on alignments)
or from the top-left corner of the display if this element has no parent
(i.e. it is the root element).
Returns
UVector2 describing the position of the element area.
See Also
UDim
virtual const Sizef& CEGUI::Element::getRootContainerSize ( ) const
virtual

Return the size of the root container (such as screen size).

This is size of the hypothetical parent of the root element that has no parent element. Display size is usually used.

The value is significant and is used to size and position the root if it is using scale UDim component in position and/or size.

Reimplemented in CEGUI::Window.

const Quaternion& CEGUI::Element::getRotation ( ) const
inline

retrieves rotation of this widget

See Also
Element::setRotation
USize CEGUI::Element::getSize ( void  ) const
inline

Get the element's size.

Gets the size of the area occupied by this element.
Returns
USize describing the size of the element's area.
See Also
UDim
const CachedRectf& CEGUI::Element::getUnclippedInnerRect ( ) const
inline

Return a Rect that describes the unclipped inner rect area of the Element.

The inner rectangle is typically an area that excludes some frame or other decorations that should not be touched by rendering of client clipped child elements.

Note
Unclipped in this context means not limited by any ancestor Element's area.
Returns
Rect object that describes, in unclipped screen pixel co-ordinates, the element object's inner rect area.
const CachedRectf& CEGUI::Element::getUnclippedOuterRect ( ) const
inline

Return a Rect that describes the unclipped outer rect area of the Element.

The unclipped outer rectangle is the entire area of the element, including frames and other outside decorations.

Note
Unclipped in this context means not limited by any ancestor Element's area.
If you take position of the result rectangle it is the same as pixel position of the Element in screenspace.
const CachedRectf& CEGUI::Element::getUnclippedRect ( const bool  inner) const
inline

Return a Rect that describes the unclipped area covered by the Element.

This function can return either the inner or outer area dependant upon the boolean values passed in.

Parameters
inner
  • true if the inner rect area should be returned.
  • false if the outer rect area should be returned.
See Also
Element::getUnclippedOuterRect
Element::getUnclippedInnerRect
VerticalAlignment CEGUI::Element::getVerticalAlignment ( ) const
inline

Get the vertical alignment.

Returns the vertical alignment for the element.  This setting affects how
the element's position is interpreted relative to its parent.
Returns
One of the VerticalAlignment enumerated values.
UDim CEGUI::Element::getWidth ( ) const
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

const UDim& CEGUI::Element::getXPosition ( ) const
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

const UDim& CEGUI::Element::getYPosition ( ) const
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool CEGUI::Element::isAncestor ( const Element element) const

Checks whether the specified Element is an ancestor of this Element.

Parameters
elementPointer to the Element object to look for.

This element itself is not its own ancestor!

Returns
  • true if element was found to be an ancestor (parent, or parent of parent, etc) of this Element.
  • false if element is not an ancestor of this element.
bool CEGUI::Element::isNonClient ( ) const
inline

Checks whether this element was set to be non client.

See Also
Element::setNonClient
bool CEGUI::Element::isPixelAligned ( ) const
inline

Checks whether this Element is pixel aligned.

See Also
Element::setPixelAligned
virtual void CEGUI::Element::notifyScreenAreaChanged ( bool  recursive = true)
virtual

Inform the element and (optionally) all children that screen area has changed.

Note
This will cause recomputation and recaching of various rectangles used. Such an action, especially if applied recursively, will impact performance before everything is cached again.
Parameters
recursive
  • true to recursively call notifyScreenAreaChanged on attached child Element objects.
  • false to just process this Element.

Reimplemented in CEGUI::Window, CEGUI::ScrolledContainer, CEGUI::LayoutContainer, and CEGUI::LayoutCell.

virtual void CEGUI::Element::onChildAdded ( ElementEventArgs e)
protectedvirtual

Handler called when a child element is added to this element.

Parameters
eElementEventArgs object whose 'element' pointer field is set to the element that has been added.

Reimplemented in CEGUI::Window, and CEGUI::ScrolledContainer.

virtual void CEGUI::Element::onChildRemoved ( ElementEventArgs e)
protectedvirtual

Handler called when a child element is removed from this element.

Parameters
eElementEventArgs object whose 'element' pointer field is set the element that has been removed.

Reimplemented in CEGUI::Window, CEGUI::MenuBase, and CEGUI::ScrolledContainer.

virtual void CEGUI::Element::onHorizontalAlignmentChanged ( ElementEventArgs e)
protectedvirtual

Handler called when the horizontal alignment setting for the element is changed.

Parameters
eElementEventArgs object initialised as follows:
  • element field is set to point to the element object who's alignment has changed (typically 'this').
virtual void CEGUI::Element::onMoved ( ElementEventArgs e)
protectedvirtual

Handler called when the element's position changes.

Parameters
eElementEventArgs object whose 'element' pointer field is set to the element that triggered the event.

Reimplemented in CEGUI::Window, and CEGUI::DragContainer.

virtual void CEGUI::Element::onNonClientChanged ( ElementEventArgs e)
protectedvirtual

Handler called when the element's non-client setting, affecting it's position and size relative to it's parent is changed.

Parameters
eElementEventArgs object whose 'element' pointer field is set to the element that triggered the event. For this event the trigger element is always 'this'.
virtual void CEGUI::Element::onParentSized ( ElementEventArgs e)
protectedvirtual

Handler called when this element's parent element has been resized. If this element is the root / GUI Sheet element, this call will be made when the display size changes.

Parameters
eElementEventArgs object whose 'element' pointer field is set the the element that caused the event; this is typically either this element's parent element, or NULL to indicate the screen size has changed.

Reimplemented in CEGUI::Window, CEGUI::ItemListBase, CEGUI::ScrolledContainer, and CEGUI::LayoutContainer.

virtual void CEGUI::Element::onRotated ( ElementEventArgs e)
protectedvirtual

Handler called when the element's rotation is changed.

Parameters
eElementEventArgs object whose 'element' pointer field is set to the element that triggered the event.

Reimplemented in CEGUI::Window.

virtual void CEGUI::Element::onSized ( ElementEventArgs e)
protectedvirtual

Handler called when the element's size changes.

Parameters
eElementEventArgs object whose 'element' pointer field is set to the element that triggered the event.

Reimplemented in CEGUI::Window, CEGUI::MultiColumnList, CEGUI::Combobox, CEGUI::Tree, CEGUI::MultiLineEditbox, CEGUI::Listbox, and CEGUI::ScrollablePane.

virtual void CEGUI::Element::onVerticalAlignmentChanged ( ElementEventArgs e)
protectedvirtual

Handler called when the vertical alignment setting for the element is changed.

Parameters
eElementEventArgs object initialised as follows:
  • element field is set to point to the element object who's alignment has changed (typically 'this').
void CEGUI::Element::removeChild ( Element element)

Remove the Element Element's child list.

Exceptions
InvalidRequestExceptionthrown if Element element is NULL.
See Also
Element::addChild
virtual void CEGUI::Element::setArea ( const UVector2 pos,
const USize size 
)
virtual

Set the Element area.

Sets the area occupied by this Element. The defined area is offset from
one of the corners and edges of this Element's parent element (depending on alignments)
or from the top-left corner of the display if this element has no parent
(i.e. if it is the root element).
Parameters
posUVector2 describing the new position of the element area. Meaning of position depends on currently set alignments. By default it is the offset from the top-left corner of widget's parent.
sizeUVector2 describing the new size of the element area.
See Also
UDim
void CEGUI::Element::setArea ( const UDim xpos,
const UDim ypos,
const UDim width,
const UDim height 
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void CEGUI::Element::setArea ( const URect area)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References CEGUI::Rect< T >::getSize().

virtual void CEGUI::Element::setArea_impl ( const UVector2 pos,
const USize size,
bool  topLeftSizing = false,
bool  fireEvents = true 
)
protectedvirtual

Implementation method to modify element area while correctly applying min / max size processing, and firing any appropriate events.

Note
This is the implementation function for setting size and position. In order to simplify area management, from this point on, all modifications to element size and position (area rect) should come through here.
Parameters
posUVector2 object describing the new area position.
sizeUSize object describing the new area size.
topLeftSizing
  • true to indicate the the operation is a sizing operation on the top and/or left edges of the area, and so element movement should be inhibited if size is at max or min.
  • false to indicate the operation is not a strict sizing operation on the top and/or left edges and that the element position may change as required
fireEvents
  • true if events should be fired as normal.
  • false to inhibit firing of events (required, for example, if you need to call this from the onSize/onMove handlers).

Reimplemented in CEGUI::Window, and CEGUI::ScrolledContainer.

void CEGUI::Element::setAspectMode ( const AspectMode  mode)

Sets current aspect mode and recalculates the area rect.

Parameters
modethe new aspect mode to set
See Also
CEGUI::AspectMode
CEGUI::setAspectRatio
void CEGUI::Element::setAspectRatio ( const float  ratio)

Sets target aspect ratio.

Parameters
ratioThe desired ratio as width / height. For example 4.0f / 3.0f, 16.0f / 9.0.f, ...
Note
This is ignored if AspectMode is AM_IGNORE.
See Also
Element::setAspectMode
void CEGUI::Element::setHeight ( const UDim height)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void CEGUI::Element::setHorizontalAlignment ( const HorizontalAlignment  alignment)
virtual

Set the horizontal alignment.

Modifies the horizontal alignment for the element. This setting affects
how the element's position is interpreted relative to its parent.
Parameters
alignmentOne of the HorizontalAlignment enumerated values.
void CEGUI::Element::setMaxSize ( const USize size)

Set the element's maximum size.

Sets the maximum size that this element area may occupy (whether size
changes occur by user interaction, general system operation, or by
direct setting by client code).
Note
The scale component of UDim takes display size as the base. It is not dependent on parent element's size!
Parameters
sizeUSize describing the new maximum size of the element's area. Note that zero is used to indicate that the Element's maximum area size will be unbounded.
See Also
Element::setSize
void CEGUI::Element::setMinSize ( const USize size)

Set the element's minimum size.

Sets the minimum size that this element's area may occupy (whether size
changes occur by user interaction, general system operation, or by
direct setting by client code).
Note
The scale component of UDim takes display size as the base. It is not dependent on parent element's size!
Parameters
sizeUSize describing the new minimum size of the element's area.
See Also
Element::setSize
void CEGUI::Element::setNonClient ( const bool  setting)

Set whether the Element is non-client.

A non-client element is clipped, positioned and sized according to the parent element's full area as opposed to just the inner rect area used for normal client element.

Parameters
setting
  • true if the element should be clipped, positioned and sized according to the full area rectangle of it's parent.
  • false if the element should be clipped, positioned and sized according to the inner rect area of it's parent.
virtual void CEGUI::Element::setParent ( Element parent)
protectedvirtual

Set the parent element for this element object.

Parameters
parentPointer to a Element object that is to be assigned as the parent to this Element.
Returns
Nothing

Reimplemented in CEGUI::Window.

void CEGUI::Element::setPixelAligned ( const bool  setting)

Sets whether this Element is pixel aligned (both position and size, basically the 4 "corners").

Impact on the element tree
Lets say we have Element A with child Element B, A is pixel aligned and it's position is 99.5, 99.5 px in screenspace. This gives us 100, 100 px pixel aligned position.

B's position is always relative to the pixel-aligned position of its parent. Say B isn't pixel-aligned and it's position is 0.5, 0.5 px. Its final position will be 100.5, 100.5 px in screenspace, not 100, 100 px!

If it were pixel-aligned the final position would be 101, 101 px.

Why you should pixel-align widgets
Pixel aligning is enabled by default and for most widgets it makes a lot of sense and just looks better. Especially with text. However for HUD or decorative elements pixel aligning might make transitions less fluid. Feel free to experiment with the setting.
void CEGUI::Element::setPosition ( const UVector2 pos)
inline

Set the element's position.

Sets the position of the area occupied by this element. The position is offset from
one of the corners and edges of this Element's parent element (depending on alignments)
or from the top-left corner of the display if this element has no parent
(i.e. it is the root element).
Parameters
posUVector2 describing the new position of the element area.
See Also
UDim
Element::setArea(const UVector2& pos, const USize& size)
void CEGUI::Element::setRotation ( const Quaternion rotation)

sets rotation of this widget

Parameters
rotationA Quaternion describing the rotation
Euler angles
CEGUI used Euler angles previously. While these are easy to use and seem intuitive they cause Gimbal locks when animating and are overall the worse solution than using Quaternions. You can still use Euler angles, see the CEGUI::Quaternion class for more info about that.
void CEGUI::Element::setSize ( const USize size)
inline

Set the element's size.

Sets the size of the area occupied by this element.
Parameters
sizeUSize describing the new size of the element's area.
See Also
UDim
virtual void CEGUI::Element::setVerticalAlignment ( const VerticalAlignment  alignment)
virtual

Set the vertical alignment.

Modifies the vertical alignment for the element. This setting affects
how the element's position is interpreted relative to its parent.
Parameters
alignmentOne of the VerticalAlignment enumerated values.
void CEGUI::Element::setWidth ( const UDim width)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void CEGUI::Element::setXPosition ( const UDim pos)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void CEGUI::Element::setYPosition ( const UDim pos)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Member Data Documentation

const String CEGUI::Element::EventChildAdded
static

Event fired when a child Element has been added. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the child element that was added.

const String CEGUI::Element::EventChildRemoved
static

Event fired when a child element has been removed. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the child element that was removed.

const String CEGUI::Element::EventHorizontalAlignmentChanged
static

Event fired when the horizontal alignment for the element is changed. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the Element whose horizontal alignment setting was changed.

const String CEGUI::Element::EventMoved
static

Event fired when the Element position has changed. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the Element whose position was changed.

const String CEGUI::Element::EventNonClientChanged
static

Event fired when the non-client setting for the Element is changed. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the Element whose non-client setting was changed.

const String CEGUI::Element::EventParentSized
static

Event fired when the parent of this Element has been re-sized. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element pointing to the parent element that was resized, not the element whose parent was resized.

const String CEGUI::Element::EventRotated
static

Event fired when the rotation factor(s) for the element are changed. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the Element whose rotation was changed.

const String CEGUI::Element::EventSized
static

Event fired when the Element size has changed. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the Element whose size was changed.

const String CEGUI::Element::EventVerticalAlignmentChanged
static

Event fired when the vertical alignment for the element is changed. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the Element whose vertical alignment setting was changed.

const String CEGUI::Element::EventZOrderChanged
static

Event fired when the z-order of the element has changed. Handlers are passed a const ElementEventArgs reference with ElementEventArgs::element set to the Element whose z order position has changed.