OpenGUI::ContainerControl

OpenGUI::ContainerControl Class Reference

#include <OpenGUI_ContainerControl.h>

Inheritance diagram for OpenGUI::ContainerControl:

OpenGUI::Control OpenGUI::WidgetCollectionListener OpenGUI::Widget OpenGUI::Object OpenGUI::Window List of all members.

Detailed Description

base class for all Controls that are also containers

In addition to simply being a Control that contains child Controls, this Widget also supplies an automatic layout system that will reposition and resize child controls according to their exposed layout preferences. Additionally, the results of draw operations from this object, as well as its children, are cached by this object to provide speed increases.

Note:
If a subclass wishes to restrict the client area (the rect within the container in which contained widgets are drawn) to a smaller area, it will need to modify m_ClientAreaOffset_UL and m_ClientAreaOffset_LR as appropriate to reflect the desired client area. The default values for both of these is (0.0fx0.0f), which will result in the full area of the container being used as client area.
Properties
Events Introduced
See also:
ContainerControl Events


Public Member Functions

 ContainerControl ()
 public constructor
virtual ~ContainerControl ()
 public destructor
void setPadding (float padding)
 sets the padding of this container
float getPadding ()
 gets the current padding of this container
void setConsumeInput (bool consume)
 toggles auto consumption of input that occurs inside this container, preventing it from reaching overdrawn widgets. Default is TRUE
bool getConsumeInput ()
 retrieves current ConsumeInput setting
void suspendLayout ()
 suspends automatic layout updates until resumeLayout() is called
void resumeLayout ()
 resumes automatic layout updates and performs an immediate layout update if the current layout is out of date
bool layoutValid ()
 returns true if the current layout schema is still valid
void updateLayout ()
 Performs the layout operation for child widgets, marking the new layout as valid.
void invalidateLayout ()
 Marks the current layout schema as invalid.
virtual ObjectAccessorList * getAccessors ()
 returns this object's ObjectAccessorList head
virtual unsigned int getObjectType () const
 Returns an integer identifying the type of object.
virtual void _translatePointIn (FVector2 &point)
 Translate the given point from local coordinates to inside coordinates.
virtual void _translatePointOut (FVector2 &point)
 Translate the given point from inside coordinates to local coordinates.
virtual void _doflush ()
 Needs to be overridden by container widgets to invalidate self and call _doFlush() for all children.
virtual void _sendToChildren_CursorMove (Cursor_EventArgs &moveEvent)
 Should inject the CursorMove event to all children.
virtual void _sendToChildren_CursorPress (Cursor_EventArgs &pressEvent)
 Should inject the CursorPress event to all children.
virtual void _sendToChildren_CursorRelease (Cursor_EventArgs &releaseEvent)
 Should inject the CursorRelease event to all children.

Public Attributes

WidgetCollection Children
 Collection of child widgets that are contained by this ContainerControl.

Protected Member Functions

const FRect & getClientArea ()
 Returns the client area position and size as an FRect.
virtual void _doUpdateLayout ()
 This performs the actual layout operation.
void dirtyCache ()
 flushes the local draw cache. Causes a call to invalidate() automatically
bool isCacheDirty () const
 returns true if the local cache is dirty
Brush_Caching & _getCacheBrush ()
 retrieves a Brush reference to the underlying cache. Should only be used within _draw() overloads
Event Injectors
void eventDrawBG (Brush &brush)
 Draw this object's background using the given brush.
void eventChildAttached (WidgetCollection *container, Widget *newChild)
 A new child has been attached to this container.
void eventChildDetached (WidgetCollection *container, Widget *prevChild)
 A child has been detached from this container.
void eventInvalidatedChild ()
 A child of this container has been invalidated.
Event Handlers
virtual void onDrawBG (Object *sender, Draw_EventArgs &evtArgs)
 "DrawBG" event
virtual void onChildAttached (Object *sender, Attach_EventArgs &evtArgs)
 "ChildAttached" event
virtual void onChildDetached (Object *sender, Attach_EventArgs &evtArgs)
 "ChildDetached" event
virtual void onInvalidated (Object *sender, EventArgs &evtArgs)
 Flushes the local Brush output cache that contains operations from this and all child Widgets.
virtual void onInvalidatedChild (Object *sender, EventArgs &evtArgs)
 Invalidates this widget, which causes a flush of the local cache of child operations.
virtual void onResized (Object *sender, Resized_EventArgs &evtArgs)
 flushes local Brush cache in addition to normal functionality
virtual void onCursorMove (Object *sender, Cursor_EventArgs &evtArgs)
 "CursorMove" event, only allows Control to consume if ConsumeInput is true
virtual void onCursorPress (Object *sender, Cursor_EventArgs &evtArgs)
 "CursorPress" event, only allows Control to consume if ConsumeInput is true
virtual void onCursorRelease (Object *sender, Cursor_EventArgs &evtArgs)
 "CursorRelease" event, only allows Control to consume if ConsumeInput is true

Protected Attributes

FVector2 m_ClientAreaOffset_UL
 The client area offset from the upper left of the ContainerControl.
FVector2 m_ClientAreaOffset_LR
 The client area offset from the lower right of the ContainerControl.
bool m_ClipChildren
 Signifies if this container should clip the output of its children against the defined client area.

Constructor & Destructor Documentation

OpenGUI::ContainerControl::ContainerControl (   ) 
 

public constructor

OpenGUI::ContainerControl::~ContainerControl (   )  [virtual]
 

public destructor

Member Function Documentation

void OpenGUI::ContainerControl::_doflush (   )  [virtual]
 

Needs to be overridden by container widgets to invalidate self and call _doFlush() for all children.

Reimplemented from OpenGUI::Widget.

void OpenGUI::ContainerControl::_doUpdateLayout (   )  [protected, virtual]
 

This performs the actual layout operation.

This is virtual in the case that a subclass wishes to perform their own layout logic. Toolbars and other specialty containers would likely need this functionality.

Brush_Caching & OpenGUI::ContainerControl::_getCacheBrush (   )  [protected]
 

retrieves a Brush reference to the underlying cache. Should only be used within _draw() overloads

void OpenGUI::ContainerControl::_sendToChildren_CursorMove (  Cursor_EventArgs &  moveEvent  )  [virtual]
 

Should inject the CursorMove event to all children.

Note:
The moveEvent is the copy that was sent to _injectCursorMove(), and will likely need to be translated to an inner coordinate before passing on to the children. Also, be sure to preserve the event's Consumed value in both directions, as it is critical to proper operation.

Reimplemented from OpenGUI::Widget.

void OpenGUI::ContainerControl::_sendToChildren_CursorPress (  Cursor_EventArgs &  pressEvent  )  [virtual]
 

Should inject the CursorPress event to all children.

Note:
The pressEvent is the copy that was sent to _injectCursorPress(), and will likely need to be translated to an inner coordinate before passing on to the children. Also, be sure to preserve the event's Consumed value in both directions, as it is critical to proper operation.

Reimplemented from OpenGUI::Widget.

void OpenGUI::ContainerControl::_sendToChildren_CursorRelease (  Cursor_EventArgs &  releaseEvent  )  [virtual]
 

Should inject the CursorRelease event to all children.

Note:
The releaseEvent is the copy that was sent to _injectCursorRelease(), and will likely need to be translated to an inner coordinate before passing on to the children. Also, be sure to preserve the event's Consumed value in both directions, as it is critical to proper operation.

Reimplemented from OpenGUI::Widget.

void OpenGUI::ContainerControl::_translatePointIn (  FVector2 &  point  )  [virtual]
 

Translate the given point from local coordinates to inside coordinates.

This function is intended for overriding should the existing method not produce accurate results. Overriding should only be necessary if the widget has children and displays them in a non-standard fashion (rotated, for example).

This function takes the given point and translates its value from local coordinates to inner coordinates. As an example, the ContainerControl takes the given point and subtracts its position and upper left client area offset to it to produce a resulting point that is local to its children. (The children's position and size are defined within the resulting coordinate space)

The result of the transform is written back to the given point

Reimplemented from OpenGUI::Widget.

void OpenGUI::ContainerControl::_translatePointOut (  FVector2 &  point  )  [virtual]
 

Translate the given point from inside coordinates to local coordinates.

This function is intended for overriding should the existing method not produce accurate results.

It should produce the inverse result of _translatePointIn()

This function takes the given point and translates its value from inner coordinates to local coordinates. As an example, the ContainerControl takes the given point and adds its position and upper left client area offset to it to produce a resulting point that is local to itself. (Its own position and size are defined within the resulting coordinate space)

The result of the transform is written back to the given point

Reimplemented from OpenGUI::Widget.

void OpenGUI::ContainerControl::dirtyCache (   )  [protected]
 

flushes the local draw cache. Causes a call to invalidate() automatically

void OpenGUI::ContainerControl::eventChildAttached (  WidgetCollection *  container,
Widget *  newChild
)  [protected, virtual]
 

A new child has been attached to this container.

Implements OpenGUI::WidgetCollectionListener.

void OpenGUI::ContainerControl::eventChildDetached (  WidgetCollection *  container,
Widget *  prevChild
)  [protected, virtual]
 

A child has been detached from this container.

Implements OpenGUI::WidgetCollectionListener.

void OpenGUI::ContainerControl::eventDrawBG (  Brush &  brush  )  [protected]
 

Draw this object's background using the given brush.

void OpenGUI::ContainerControl::eventInvalidatedChild (   )  [protected]
 

A child of this container has been invalidated.

ObjectAccessorList * OpenGUI::ContainerControl::getAccessors (   )  [virtual]
 

returns this object's ObjectAccessorList head

Reimplemented from OpenGUI::Control.

Reimplemented in OpenGUI::Window.

const FRect & OpenGUI::ContainerControl::getClientArea (   )  [protected]
 

Returns the client area position and size as an FRect.

This is a convenience function that calculates the client area into a rect from the defined offsets m_ClientAreaOffset_UL and m_ClientAreaOffset_LR.

bool OpenGUI::ContainerControl::getConsumeInput (   ) 
 

retrieves current ConsumeInput setting

unsigned int OpenGUI::ContainerControl::getObjectType (   )  const [virtual]
 

Returns an integer identifying the type of object.

See also:
Object_Type

Reimplemented from OpenGUI::Control.

Reimplemented in OpenGUI::Window.

float OpenGUI::ContainerControl::getPadding (   ) 
 

gets the current padding of this container

See also:
setPadding() for description of Padding

void OpenGUI::ContainerControl::invalidateLayout (   ) 
 

Marks the current layout schema as invalid.

If layout is not suspended, this triggers an immediate update of the layout. This function is protected from re-entry when a layout operation is currently under way.

bool OpenGUI::ContainerControl::isCacheDirty (   )  const [protected]
 

returns true if the local cache is dirty

bool OpenGUI::ContainerControl::layoutValid (   ) 
 

returns true if the current layout schema is still valid

void OpenGUI::ContainerControl::onChildAttached (  Object *  sender,
Attach_EventArgs &  evtArgs
)  [protected, virtual]
 

"ChildAttached" event

void OpenGUI::ContainerControl::onChildDetached (  Object *  sender,
Attach_EventArgs &  evtArgs
)  [protected, virtual]
 

"ChildDetached" event

void OpenGUI::ContainerControl::onCursorMove (  Object *  sender,
Cursor_EventArgs &  evtArgs
)  [protected, virtual]
 

"CursorMove" event, only allows Control to consume if ConsumeInput is true

Reimplemented from OpenGUI::Control.

Reimplemented in OpenGUI::Window.

void OpenGUI::ContainerControl::onCursorPress (  Object *  sender,
Cursor_EventArgs &  evtArgs
)  [protected, virtual]
 

"CursorPress" event, only allows Control to consume if ConsumeInput is true

Reimplemented from OpenGUI::Control.

void OpenGUI::ContainerControl::onCursorRelease (  Object *  sender,
Cursor_EventArgs &  evtArgs
)  [protected, virtual]
 

"CursorRelease" event, only allows Control to consume if ConsumeInput is true

Reimplemented from OpenGUI::Control.

void OpenGUI::ContainerControl::onDrawBG (  Object *  sender,
Draw_EventArgs &  evtArgs
)  [protected, virtual]
 

"DrawBG" event

Default is to do nothing

void OpenGUI::ContainerControl::onInvalidated (  Object *  sender,
EventArgs &  evtArgs
)  [protected, virtual]
 

Flushes the local Brush output cache that contains operations from this and all child Widgets.

Reimplemented from OpenGUI::Widget.

void OpenGUI::ContainerControl::onInvalidatedChild (  Object *  sender,
EventArgs &  evtArgs
)  [protected, virtual]
 

Invalidates this widget, which causes a flush of the local cache of child operations.

void OpenGUI::ContainerControl::onResized (  Object *  sender,
Resized_EventArgs &  evtArgs
)  [protected, virtual]
 

flushes local Brush cache in addition to normal functionality

Reimplemented from OpenGUI::Control.

void OpenGUI::ContainerControl::resumeLayout (   ) 
 

resumes automatic layout updates and performs an immediate layout update if the current layout is out of date

void OpenGUI::ContainerControl::setConsumeInput (  bool  consume  ) 
 

toggles auto consumption of input that occurs inside this container, preventing it from reaching overdrawn widgets. Default is TRUE

Changing this value to false will make the container act as a transparent entity with regards to cursor input, allowing normally obscured widgets to process events. This is primarily useful when you use several fully transparent containers to produce layers that cover the entire Screen for layout purposes. In this case, you would not want the container to always consume the input, as it would prevent the lower layers from ever getting input that they should logically receive.

void OpenGUI::ContainerControl::setPadding (  float  padding  ) 
 

sets the padding of this container

Padding is the distance within the inside of this container to keep children away from the client area edges during auto layout.

The given padding cannot be negative, and is clamped to 0.0f if a negative value is given.

void OpenGUI::ContainerControl::suspendLayout (   ) 
 

suspends automatic layout updates until resumeLayout() is called

void OpenGUI::ContainerControl::updateLayout (   ) 
 

Performs the layout operation for child widgets, marking the new layout as valid.

The update is performed regardless of layout being currently suspended, so only call this if you really want the update to occur. Layout validity, however, is still honored and layouts will not occur unless needed.

Member Data Documentation

WidgetCollection OpenGUI::ContainerControl::Children
 

Collection of child widgets that are contained by this ContainerControl.

FVector2 OpenGUI::ContainerControl::m_ClientAreaOffset_LR [protected]
 

The client area offset from the lower right of the ContainerControl.

FVector2 OpenGUI::ContainerControl::m_ClientAreaOffset_UL [protected]
 

The client area offset from the upper left of the ContainerControl.

bool OpenGUI::ContainerControl::m_ClipChildren [protected]
 

Signifies if this container should clip the output of its children against the defined client area.

It is important to note that children will always be clipped against the rect bounds of the container (either implicitly from a render to texture context, or forcibly by a ClippingRect). This option is merely present to supply an enforced rect clipping of child output in the event that you are not drawing a solid border in the area between the edge of the control and the edge of the client area. The default is false.

The documentation for this class was generated from the following files:
Copyright © 2006 OpenGUI | OpenGUI.SF.net
Generated: Sun Sep 9 02:00:21 2007