Xrb::Widget Class Reference

The class which forms the foundation of the GUI system. More...

#include <xrb_widget.hpp>

Inheritance diagram for Xrb::Widget:

[legend]

List of all members.

Public Member Functions
	Widget (ContainerWidget *parent, std::string const &name="Widget")
	Constructs a Widget. The widget will be attached to the given parent widget during construction.
virtual	~Widget ()
	Destructor. Deletes all children.
SignalReceiver1< bool > const *	ReceiverSetIsEnabled ()
	Accessor for the SignalReceiver which calls SetIsEnabled with the received value.
SignalReceiver0 const *	ReceiverEnable ()
	Accessor for the SignalReceiver which enables the widget. Calls Enable.
SignalReceiver0 const *	ReceiverDisable ()
	Accessor for the SignalReceiver which disables the widget. Calls Disable.
SignalReceiver1< bool > const *	ReceiverSetIsHidden ()
	Accessor for the SignalReceiver which calls SetIsHidden with the received value.
SignalReceiver0 const *	ReceiverHide ()
	Accessor for the SignalReceiver which hides the widget. Calls Hide.
SignalReceiver0 const *	ReceiverShow ()
	Accessor for the SignalReceiver which shows the widget. Calls Show.
std::string const &	Name () const
	Returns the name of this widget.
ContainerWidget const *	Parent () const
	Returns a pointer to the parent (const) of this widget.
ContainerWidget *	Parent ()
	Returns a pointer to the parent (non-const) of this widget.
ContainerWidget const *	EffectiveParent () const
	Returns a pointer to the effective parent (const) of this widget -- if this is a modal widget, the top-level parent is returned, otherwise its direct parent.
ContainerWidget *	EffectiveParent ()
	Returns a pointer to the effective parent (non-const) of this widget -- if this is a modal widget, the top-level parent is returned, otherwise its direct parent.
Screen const *	TopLevelParent () const
	Returns a pointer to the top-level parent (const) of this widget hierarchy (a Screen).
Screen *	TopLevelParent ()
	Returns a pointer to the top-level parent (non-const) of this widget hierarchy (a Screen).
bool	IsTopLevelParent () const
	Returns true iff this is a top-level widget (i.e. it has no parent).
bool	IsFocused () const
	Returns true iff this widget is focused. If this is a top-level widget, then it has focus by default.
bool	AcceptsFocus () const
	Returns true iff this widget even accepts focus.
bool	IsMouseover () const
	Returns true iff this widget currently has mouseover focus (i.e. its parent has this widget as its m_mouseover_focus value).
bool	AcceptsMouseover () const
	Returns true iff this widget accepts mouseover focus.
bool	IsMouseGrabbed () const
	Returns true iff this widget has mouse grab focus (meaning that all mouse events will go to/through it even if the mouse is not directly over it).
bool	IsEnabled () const
	Returns true iff this widget is enabled.
bool	IsHidden () const
	Returns true iff this widget is hidden.
bool	IsModal () const
	Returns true iff this widget is currently modal.
StackPriority	GetStackPriority () const
	Returns the widget stack priority of this widget.
WidgetBackground *	Background () const
	Returns the basic background for this widget.
ScreenCoordVector2 const &	FrameMargins () const
	Returns the frame margins for this widget.
ScreenCoordVector2 const &	ContentMargins () const
	Returns the content margins for this widget.
ScreenCoordVector2 const &	LastMousePosition () const
	Returns the last known mouse position (derived from the most recent mouse motion event received by this widget).
ScreenCoordVector2	Position () const
	Returns the current position of the lower-left corner of this widget.
ScreenCoordVector2	Size () const
	Returns the current size of this widget.
ScreenCoord	Width () const
	Returns the widget of this widget.
ScreenCoord	Height () const
	Returns the height of this widget.
virtual Bool2 const &	MinSizeEnabled () const
	Returns the boolean vector containing the is-minimum-size-enabled values for width and height in the x and y components respectively.
virtual ScreenCoordVector2 const &	MinSize () const
	Returns the screen-coordinate vector containing the minimum width and height in the X and Y components respectively.
virtual Bool2 const &	MaxSizeEnabled () const
	Returns the boolean vector containing the is-maximum-size-enabled values for width and height in the X and Y components respectively.
virtual ScreenCoordVector2 const &	MaxSize () const
	Returns the screen-coordinate vector containing the maximum width and height in the X and Y components respectively.
virtual ScreenCoordVector2	AdjustedSize (ScreenCoordVector2 const &size) const
	Returns the adjusted value of the given size vector.
ScreenCoordRect const &	ScreenRect () const
	Returns this widget's screen coordinate rectangle.
ScreenCoordRect	ContentsRect () const
	Returns the rectangle representing the content area.
Color const &	ColorBias () const
	Returns this widget's color bias (the color bias is applied to everything drawn by the widget, AFTER the color mask).
Color const &	ColorMask () const
	Returns this widget's color mask (the color mask is applied to everything drawn by the widget).
Color &	ColorBias ()
	Returns this widget's color bias as a non-const reference (the color bias is applied to everything drawn by the widget, AFTER the color mask).
Color &	ColorMask ()
	Returns this widget's color mask as a non-const reference (the color mask is applied to everything drawn by the widget).
virtual void	SetSizePropertyEnabled (SizeProperties::Property property, Uint32 component, bool value, bool defer_parent_update=false)
	Sets a single component of the min/max-size-enabled property of this widget.
virtual void	SetSizePropertyEnabled (SizeProperties::Property property, Bool2 const &value, bool defer_parent_update=false)
	Sets both components of the min/max-size-enabled property vector of this widget.
virtual void	SetSizeProperty (SizeProperties::Property property, Uint32 component, ScreenCoord value, bool defer_parent_update=false)
	Sets a single component of the min/max-size property of this widget.
virtual void	SetSizeProperty (SizeProperties::Property property, ScreenCoordVector2 const &value, bool defer_parent_update=false)
	Sets both components of the min/max-size property vector of this widget.
void	SetSizePropertyRatio (SizeProperties::Property property, Uint32 component, Float ratio, bool defer_parent_update=false)
	Sets a single component of the min/max-size-to-screen-basis ratio of this widget.
void	SetSizePropertyRatios (SizeProperties::Property property, FloatVector2 const &ratios, bool defer_parent_update=false)
	Sets both components of the min/max-size-to-screen-basis ratio vector of this widget.
void	SetIsModal (bool is_modal)
	Sets the modal state of this widget.
void	SetStackPriority (StackPriority stack_priority)
	Sets the widget's stack priority.
void	SetBackground (WidgetBackground *background)
	Sets the basic background for this widget, NULL for no background (completely transparent).
void	SetFrameMargins (ScreenCoordVector2 const &frame_margins)
	Sets the frame margins for this widget (in direct screen coordinates).
void	SetFrameMarginRatios (FloatVector2 const &frame_margin_ratios)
	Sets the frame margins for this widget via screen-basis ratios.
void	SetContentMargins (ScreenCoordVector2 const &content_margins)
	Sets the content margins for this widget (in direct screen coordinates).
void	SetContentMarginRatios (FloatVector2 const &content_margin_ratios)
	Sets the content margins for this widget via screen-basis ratios.
void	FixSize (ScreenCoordVector2 const &size)
	Sets the min and max sizes to the given size, and then enables min/max size enabled properties for both X and Y components.
void	FixSizeRatios (FloatVector2 const &size_ratios)
	Sets the min and max sizes to the given size, and then enables min/max size enabled properties for both X and Y components -- the size is given in a screen-basis ratio vector.
void	UnfixSize ()
	Disables min and max size enabled properties for both X and Y components.
void	FixWidth (ScreenCoord width)
	Sets the min and max width to the given width, and then enables min/max size enabled properties for the X component only.
void	FixWidthRatio (Float width_ratio)
	Sets the min and max widths to the given size, and then enables min/max size enabled properties for the X component only -- the width is given as a screen-basis ratio.
void	UnfixWidth ()
	Disables min and max size enabled properties for the X component only.
void	FixHeight (ScreenCoord height)
	Sets the min and max height to the given height, and then enables min/max size enabled properties for the Y component only.
void	FixHeightRatio (Float height_ratio)
	Sets the min and max heights to the given size, and then enables min/max size enabled properties for the Y component only -- the height is given as a screen-basis ratio.
void	UnfixHeight ()
	Disables min and max size enabled properties for the Y component only.
virtual void	Draw (RenderContext const &render_context) const
	Draws the widget using the provided RenderContext.
void	MoveTo (ScreenCoordVector2 const &position)
	Move this widget to the given position.
virtual void	MoveBy (ScreenCoordVector2 const &delta)
	Move this widget by a specific delta vector.
virtual ScreenCoordVector2	Resize (ScreenCoordVector2 const &size)
	Attempt to resize this widget to the given size.
ScreenCoordVector2	ResizeByRatios (FloatVector2 const &ratios)
	A screen-basis-ratio based frontend to Resize.
ScreenCoordVector2	MoveToAndResize (ScreenCoordRect const &screen_rect)
	Attempts to move and resize this widget so that its screen rectangle matches the one given.
void	CenterOnWidget (Widget const *widget)
	Centers this widget on the center of the given widget.
bool	Focus ()
	Focuses this widget with respect to its parent widget.
void	Unfocus ()
	Unfocuses this widget with respect to its parent widget.
void	GrabMouse ()
	Grabs the mouse input.
void	UnGrabMouse ()
	Lets go of the mouse input.
void	DetachFromParent ()
	Detaches this widget from its parent.
virtual void	SetIsEnabled (bool is_enabled)
	Sets the enabled state of this widget.
void	Enable ()
	Enables this widget.
void	Disable ()
	Disables this widget.
void	ToggleIsHidden ()
	Toggles the hidden state.
void	SetIsHidden (bool is_hidden)
	Sets the hidden state of this widget.
void	Hide ()
	Hides this widget.
void	Show ()
	Shows this widget.
Protected Member Functions
virtual Uint32	WidgetSkinHandlerChildCount () const
	This implementation was required by WidgetSkinHandler.
virtual WidgetSkinHandler *	WidgetSkinHandlerChild (Uint32 index)
	This implementation was required by WidgetSkinHandler.
virtual WidgetSkinHandler *	WidgetSkinHandlerParent ()
	This implementation was required by WidgetSkinHandler.
WidgetBackground const *	RenderBackground () const
	Returns the a pointer to the background object which is rendered in Widget::Draw.
void	SetRenderBackground (WidgetBackground const *render_background)
	Sets the background to use in Widget::Draw.
void	InitializeFromWidgetSkinProperties ()
	Called only by Widget and Screen after they get a WidgetSkin.
virtual void	HandleFrame ()
	Override of FrameHandler::HandleFrame which does anything that needs to be done once per iteration of the game loop.
virtual bool	HandleEvent (Event const *e)
	Override of EventHandler::HandleEvent which does generic event processing.
virtual bool	ProcessKeyEvent (EventKey const *e)
	Process a key event.
virtual bool	ProcessMouseButtonEvent (EventMouseButton const *e)
	Process a mouse button event.
virtual bool	ProcessMouseWheelEvent (EventMouseWheel const *e)
	Process a mouse wheel event.
virtual bool	ProcessMouseMotionEvent (EventMouseMotion const *e)
	Process a mouse motion event.
virtual bool	ProcessJoyEvent (EventJoy const *e)
	Process a joystick event.
virtual bool	ProcessStateMachineInputEvent (EventStateMachineInput const *e)
	Process a StateMachineInput event.
virtual bool	ProcessCustomEvent (EventCustom const *e)
	Process a custom event.
virtual bool	ProcessDeleteChildWidgetEvent (EventDeleteChildWidget const *e)
	Processes a delete child widget event. This is used mainly to delete modal widgets.
virtual void	HandleFocus ()
	Handler that is called when this widget becomes focused.
virtual void	HandleUnfocus ()
	Handler that is called when this widget becomes unfocused.
virtual void	HandleMouseoverOn ()
	Handler that is called when the mouseover flag is set ON (from off).
virtual void	HandleMouseoverOff ()
	Handler that is called when the mouseover flag is set OFF (from on).
virtual void	HandleMouseGrabOn ()
	Handler that is called when this widget grabs the mouse input.
virtual void	HandleMouseGrabOff ()
	Handler that is called when this widget lets go of the mouse input.
virtual void	HandleChangedBackground ()
	Handler that is called when the basic background object is changed.
virtual void	HandleChangedFrameMargins ()
	Handler that is called when the frame margins have been changed.
virtual void	HandleChangedContentMargins ()
	Handler that is called when the content margins have been changed.
virtual void	UpdateRenderBackground ()
	Assigns the basic widget background to the render background.
void	ParentChildSizePropertiesUpdate (bool defer_parent_update)
	Calls ChildSizePropertiesChanged on this widget's parent, with the "this" pointer as the parameter.
bool	AdjustFromMinSize (ScreenCoordRect *screen_rect) const
	Adjusts *size by the minimum size.
bool	AdjustFromMaxSize (ScreenCoordRect *screen_rect) const
	Adjusts *size by the maximum size.
void	MinSizeUpdated ()
	Performs range checking to ensure the min and max sizes are valid after the minimum size was changed.
void	MaxSizeUpdated ()
	Performs range checking to ensure the min and max sizes are valid after the maximum size was changed.
void	SizeRangeAdjustment (ScreenCoordRect *rect) const
	Ensures the size of the given rectangle is non-negative in both dimensions.
Protected Attributes
SizeProperties	m_size_properties
	Contains the min/max and min/max-enabled size properties of this widget.
bool	m_accepts_focus
	Indicates if this widget accepts focus on its own.
bool	m_accepts_mouseover
	Indicates if this widget accepts the mouseover flag on its own.
Color	m_color_bias
	The color bias of the widget.
Color	m_color_mask
	The color mask of the widget.
Friends
class	ContainerWidget

---

Detailed Description

The class which forms the foundation of the GUI system.

The base class for all GUI widgets and provides 90% of the framework necessary for the GUI's operation.

The GUI system of XuqRijBuh is modeled closely upon the commonly used "widget" paradigm of GUI toolkits such as QT (http://www.trolltech.com). Some examples of specialized widgets are Label, Button, and CheckBox.

A hierarchy of widgets (a widget being essentially a rectangular area on the screen) is created to suit the task at hand. Widgets subordinate to a particular widget in the hierarchy are referred to as its "child widgets" or "children". The hierarchy dictates specific rules as to how widgets are drawn and how they receive events.

The top of the widget hierarchy must be an instance of Screen. it contains specialized functionality for initiating drawing and event-sending.

Widgets are drawn in a top-down manner -- drawing begins at the Screen, which performs some one-time setup work (one-time per frame), and sets up the OpenGL viewport/clip rect and so forth, and then calls the drawing function on all its child widgets in the order in which they appear in the widget stack (see m_child_vector). During the draw function, a widget will draw itself (e.g. backgrounds, text, pictures, nothing, etc) and then call the draw function on its own children in the order specified by m_child_vector. There are a few caveats to this, including hidden widgets, but that will be explained later.

Events (see Event) are processed in a similar fashion as drawing -- starting at the top of the hierarchy, propagating down to children. The difference here is that the event will not be "used" by all the widgets in the hierarchy. An event is created at a particular level in the hierarchy (though usually from outside and passed to the top), and then each child widget is asked if it wishes to use the event. A used event is not destroyed or in any way changed, allowing for parent widgets to perform further processing after a child accepts/denies usage of an event.

See Widget Baseclass for extensive system details.

Note:

All GUI widgets must derive from this class to function properly.

Definition at line 97 of file xrb_widget.hpp.

---

Constructor & Destructor Documentation

Xrb::Widget::Widget	(	ContainerWidget *	parent,
		std::string const &	name = "Widget"
	)

Constructs a Widget. The widget will be attached to the given parent widget during construction.

Parameters:

	parent	The parent ContainerWidget to attach to during construction. This must not be NULL, except in the case of a Screen (the top-level widget).
	name	A textual label applied to the specific widget being constructed. As for now, this is only used in a debug- related capacity.

Definition at line 27 of file xrb_widget.cpp.

References InitializeFromWidgetSkinProperties(), m_accepts_focus, m_accepts_mouseover, m_color_bias, m_color_mask, Xrb::Vector< ScreenCoord, 2 >::ms_zero, Xrb::EventHandler::SetOwnerEventQueue(), and Xrb::SP_NEUTRAL.

Xrb::Widget::~Widget

(

)

[virtual]

Destructor. Deletes all children.

Ensures the widget is set to not modal, ensures mouseover is off, deletes all children, and clears the modal widget stack.

Definition at line 71 of file xrb_widget.cpp.

References DetachFromParent(), and SetIsModal().

---

Member Function Documentation

ContainerWidget const * Xrb::Widget::EffectiveParent

(

)

const

Returns a pointer to the effective parent (const) of this widget -- if this is a modal widget, the top-level parent is returned, otherwise its direct parent.

Modal widgets behave slightly differently than normal widgets. Since they must appear above all other widgets, effectively their parent is the top-level parent (see Screen), which does some special handling of drawing and events for their proper operation.

Definition at line 93 of file xrb_widget.cpp.

References IsModal(), and TopLevelParent().

Referenced by Focus(), GrabMouse(), IsFocused(), IsMouseGrabbed(), IsMouseover(), and UnGrabMouse().

ContainerWidget * Xrb::Widget::EffectiveParent

(

)

Returns a pointer to the effective parent (non-const) of this widget -- if this is a modal widget, the top-level parent is returned, otherwise its direct parent.

Modal widgets behave slightly differently than normal widgets. Since they must appear above all other widgets, effectively their parent is the top-level parent (see Screen), which does some special handling of drawing and events for their proper operation.

Definition at line 100 of file xrb_widget.cpp.

References IsModal(), and TopLevelParent().

bool Xrb::Widget::AcceptsFocus

(

)

const [inline]

Returns true iff this widget even accepts focus.

The member variable m_accepts_focus should be set in Widget derivative classes to indicate if they will accept focus. The default value set by the constructor of Widget is false.

Definition at line 203 of file xrb_widget.hpp.

References m_accepts_focus.

bool Xrb::Widget::AcceptsMouseover

(

)

const [inline]

Returns true iff this widget accepts mouseover focus.

The member variable m_accepts_mouseover should be set in Widget derivative classes to indicate if they will accept mouseover focus. The default value set by the constructor of Widget is true.

Definition at line 214 of file xrb_widget.hpp.

References m_accepts_mouseover.

StackPriority Xrb::Widget::GetStackPriority

(

)

const [inline]

Returns the widget stack priority of this widget.

See also:

StackPriority

Definition at line 232 of file xrb_widget.hpp.

WidgetBackground* Xrb::Widget::Background

(

)

const [inline]

Returns the basic background for this widget.

See also:

WidgetBackground

Definition at line 236 of file xrb_widget.hpp.

Referenced by UpdateRenderBackground().

ScreenCoordVector2 const& Xrb::Widget::ContentMargins

(

)

const [inline]

Returns the content margins for this widget.

The content margins are added to the frame margins to indicate the content area of the label. The content margins can be negative (up to the point that they totally cancel the frame margins).

Definition at line 245 of file xrb_widget.hpp.

Referenced by ContentsRect().

ScreenCoordVector2 Xrb::Widget::AdjustedSize

(

ScreenCoordVector2 const &

size

)

const [virtual]

Returns the adjusted value of the given size vector.

Adjusts the size vector to satisfy the minimum size properties of this widget. Then adjusts the resulting value to satisfy the maximum size properties of this widget. If there is a main widget, then its min/max size properties will be used instead.

Parameters:

size

The size vector to adjust.

Definition at line 141 of file xrb_widget.cpp.

References AdjustFromMaxSize(), AdjustFromMinSize(), and Xrb::Rect< T >::Size().

ScreenCoordRect Xrb::Widget::ContentsRect

(

)

const [inline]

Returns the rectangle representing the content area.

The content area is the area within the sum of the frame margins and the content margins. Note that the content margins can be negative, up to the negative of the frame margins.

Definition at line 297 of file xrb_widget.hpp.

References ContentMargins(), FrameMargins(), Xrb::Rect< T >::Grown(), and ScreenRect().

Color& Xrb::Widget::ColorBias

(

)

[inline]

Returns this widget's color bias as a non-const reference (the color bias is applied to everything drawn by the widget, AFTER the color mask).

Use this method to change the color bias

Definition at line 314 of file xrb_widget.hpp.

References m_color_bias.

Color& Xrb::Widget::ColorMask

(

)

[inline]

Returns this widget's color mask as a non-const reference (the color mask is applied to everything drawn by the widget).

Use this method to change the color mask.

Definition at line 319 of file xrb_widget.hpp.

References m_color_mask.

void Xrb::Widget::SetSizePropertyEnabled	(	SizeProperties::Property	property,
		Uint32	component,
		bool	value,
		bool	defer_parent_update = false
	)			[virtual]

Sets a single component of the min/max-size-enabled property of this widget.

This function is used to set the minimum-size-enabled and maximum-size-enabled for both the X/Y components, separately.

This function should be overridden in a subclass when it is necessary to know when the min/max-size-enabled property of a widget is changed.

See also:

Layout::SetSizePropertyEnabled

Parameters:

	property	Indicates which property is to be set (MIN or MAX).
	component	Can only be either Dim::X or Dim::Y (0 or 1, respectively).
	value	The boolean indicating the new value of the specified property.
	defer_parent_update	This parameter is likely to be moved out of the public API.

Definition at line 153 of file xrb_widget.cpp.

References AdjustFromMaxSize(), AdjustFromMinSize(), Xrb::SizeProperties::m_max_size_enabled, Xrb::SizeProperties::m_min_size_enabled, m_size_properties, MaxSizeUpdated(), MinSizeUpdated(), ParentChildSizePropertiesUpdate(), Resize(), and Xrb::Rect< T >::Size().

Referenced by FixHeight(), FixHeightRatio(), FixSize(), FixSizeRatios(), FixWidth(), FixWidthRatio(), UnfixHeight(), UnfixSize(), and UnfixWidth().

void Xrb::Widget::SetSizePropertyEnabled	(	SizeProperties::Property	property,
		Bool2 const &	value,
		bool	defer_parent_update = false
	)			[virtual]

Sets both components of the min/max-size-enabled property vector of this widget.

This function is used to set either the minimum-size-enabled and maximum-size-enabled for both the X/Y components at once.

This function should be overridden in a subclass when it is necessary to know when the min/max-size-enabled property of a widget is changed.

See also:

Layout::SetSizePropertyEnabled

Parameters:

	property	Indicates which property is to be set (MIN or MAX).
	value	The boolean vector indicating the new components of the specified property.
	defer_parent_update	This parameter is likely to be moved out of the public API.

Definition at line 184 of file xrb_widget.cpp.

References AdjustFromMaxSize(), AdjustFromMinSize(), Xrb::SizeProperties::m_max_size_enabled, Xrb::SizeProperties::m_min_size_enabled, m_size_properties, MaxSizeUpdated(), MinSizeUpdated(), ParentChildSizePropertiesUpdate(), Resize(), and Xrb::Rect< T >::Size().

void Xrb::Widget::SetSizeProperty	(	SizeProperties::Property	property,
		Uint32	component,
		ScreenCoord	value,
		bool	defer_parent_update = false
	)			[virtual]

Sets a single component of the min/max-size property of this widget.

This function is used to set the minimum-size and maximum-size for both the X/Y components, separately.

This function should be overridden in a subclass when it is necessary to know when the min/max-size property of a widget is changed.

See also:

Layout::SetSizeProperty

Parameters:

	property	Indicates which property is to be set (MIN or MAX).
	component	Can only be either Dim::X or Dim::Y (0 or 1, respectively).
	value	The screen coordinate indicating the new value of the specified property.
	defer_parent_update	This parameter is likely to be moved out of the public API.

Definition at line 213 of file xrb_widget.cpp.

References AdjustFromMaxSize(), AdjustFromMinSize(), Xrb::SizeProperties::m_max_size, Xrb::SizeProperties::m_min_size, m_size_properties, MaxSizeUpdated(), MinSizeUpdated(), ParentChildSizePropertiesUpdate(), Resize(), and Xrb::Rect< T >::Size().

Referenced by FixHeight(), FixSize(), FixWidth(), SetSizePropertyRatio(), and SetSizePropertyRatios().

void Xrb::Widget::SetSizeProperty	(	SizeProperties::Property	property,
		ScreenCoordVector2 const &	value,
		bool	defer_parent_update = false
	)			[virtual]

Sets both components of the min/max-size property vector of this widget.

This function is used to set either the minimum-size and maximum-size for both the X/Y components at once.

This function should be overridden in a subclass when it is necessary to know when the min/max-size property of a widget is changed.

See also:

Layout::SetSizeProperty

Parameters:

	property	Indicates which property is to be set (MIN or MAX).
	value	The screen coordinate vector indicating the new components of the specified property.
	defer_parent_update	This parameter is likely to be moved out of the public API.

Definition at line 245 of file xrb_widget.cpp.

References AdjustFromMaxSize(), AdjustFromMinSize(), Xrb::SizeProperties::m_max_size, Xrb::SizeProperties::m_min_size, m_size_properties, MaxSizeUpdated(), MinSizeUpdated(), ParentChildSizePropertiesUpdate(), Resize(), Xrb::Rect< T >::Size(), Xrb::Dim::X, and Xrb::Dim::Y.

void Xrb::Widget::SetSizePropertyRatio	(	SizeProperties::Property	property,
		Uint32	component,
		Float	ratio,
		bool	defer_parent_update = false
	)

Sets a single component of the min/max-size-to-screen-basis ratio of this widget.

This function is used to set the minimum-size-to-screen-basis ratio and maximum-size-to-screen-basis for both the X/Y components, separately.

This function should be overridden in a subclass when it is necessary to know when the min/max-size-to-screen-basis ratio of a widget is changed.

See also:

Layout::SetSizePropertyRatio

Parameters:

	property	Indicates which property is to be set (MIN or MAX).
	component	Can only be either Dim::X or Dim::Y (0 or 1, respectively).
	ratio	The fraction of the screen basis indicating the new value of the specified property.
	defer_parent_update	This parameter is likely to be moved out of the public API.

Definition at line 276 of file xrb_widget.cpp.

References SetSizeProperty(), and TopLevelParent().

Referenced by FixHeightRatio(), and FixWidthRatio().

void Xrb::Widget::SetSizePropertyRatios	(	SizeProperties::Property	property,
		FloatVector2 const &	ratios,
		bool	defer_parent_update = false
	)

Sets both components of the min/max-size-to-screen-basis ratio vector of this widget.

This function is used to set the minimum-size-to-screen-basis ratio and maximum-size-to-screen-basis for both the X/Y components at once.

This function should be overridden in a subclass when it is necessary to know when the min/max-size-to-screen-basis ratio of a widget is changed.

See also:

Layout::SetSizePropertyRatios

Parameters:

	property	Indicates which property is to be set (MIN or MAX).
	component	Can only be either Dim::X or Dim::Y (0 or 1, respectively).
	ratio	The vector of component-wise fractions of the screen basis indicating the new value of the specified ratio vector.
	defer_parent_update	This parameter is likely to be moved out of the public API.

Definition at line 288 of file xrb_widget.cpp.

References SetSizeProperty(), and TopLevelParent().

Referenced by FixSizeRatios().

void Xrb::Widget::SetIsModal

(

bool

is_modal

)

Sets the modal state of this widget.

Makes the call to AddModalWidget or RemoveModalWidget as appropriate). If this causes the widget to become not modal, then SetIsHidden(true) is called.

Definition at line 299 of file xrb_widget.cpp.

References IsEnabled(), IsMouseover(), IsTopLevelParent(), ParentChildSizePropertiesUpdate(), and TopLevelParent().

Referenced by Xrb::ModalWidget::ModalWidget(), Xrb::ModalWidget::Shutdown(), and ~Widget().

void Xrb::Widget::SetStackPriority

(

StackPriority

stack_priority

)

Sets the widget's stack priority.

Will cause a reshuffling of child widgets in this widget's parent's child vector, in order to maintain proper widget stack priority ordering.

Definition at line 332 of file xrb_widget.cpp.

void Xrb::Widget::SetFrameMarginRatios

(

FloatVector2 const &

frame_margin_ratios

)

Sets the frame margins for this widget via screen-basis ratios.

Actually just calls SetFrameMargins with the product of the given ratios and the screen basis.

See also:

Screen::SizeRatioBasis

Definition at line 359 of file xrb_widget.cpp.

References SetFrameMargins(), and TopLevelParent().

void Xrb::Widget::SetContentMarginRatios

(

FloatVector2 const &

content_margin_ratios

)

Sets the content margins for this widget via screen-basis ratios.

Actually just calls SetContentMargins with the product of the given ratios and the screen basis.

See also:

Screen::SizeRatioBasis

Definition at line 380 of file xrb_widget.cpp.

References SetContentMargins(), and TopLevelParent().

void Xrb::Widget::Draw

(

RenderContext const &

render_context

)

const [virtual]

Draws the widget using the provided RenderContext.

This function should be overridden in subclasses to provide the means to draw whatever is necessary. Generally the subclass's Draw function should call the Draw function of its immediate superclass before doing anything else, in order to have the background and other necessary visual elements drawn.

Draw should only be called on top-level widgets -- the Widget baseclass takes care of setting up the RenderContext and calling Draw on its child widgets appropriately.

Note:

You can NOT count on Draw being called every single video frame, since it will not be called if the clip_rect is not valid (0 area).

Reimplemented in Xrb::Label.

Definition at line 468 of file xrb_widget.cpp.

References Xrb::WidgetBackground::Draw(), FrameMargins(), RenderBackground(), and ScreenRect().

void Xrb::Widget::MoveTo

(

ScreenCoordVector2 const &

position

)

Move this widget to the given position.

Parameters:

position

The intended position of the lower-left corner of this widget.

Definition at line 475 of file xrb_widget.cpp.

References MoveBy(), and Position().

Referenced by CenterOnWidget(), and MoveToAndResize().

void Xrb::Widget::MoveBy

(

ScreenCoordVector2 const &

delta

)

[virtual]

Move this widget by a specific delta vector.

Parameters:

delta

The vector to add to this widget's position.

Definition at line 480 of file xrb_widget.cpp.

Referenced by MoveTo().

ScreenCoordVector2 Xrb::Widget::Resize

(

ScreenCoordVector2 const &

size

)

[virtual]

Attempt to resize this widget to the given size.

This function should be overridden when it is necessary to know when a widget has been resized.

The Widget baseclass will resize the widget based on its minimum and maximum sizes, if applicable. If there is a main widget, Resize will be called on the main widget with the min/max adjusted size.

If the size of the widget was actually changed, then its parent will be notified of the change via ParentChildSizePropertiesUpdate.

For examples of overriding these and related functions, see Layout and CellPaddingWidget.

Parameters:

size

The requested size.

Returns:

The actual size of the widget after the resize operation.

Reimplemented in Xrb::Label.

Definition at line 486 of file xrb_widget.cpp.

References Xrb::SizeProperties::AdjustedSize(), m_size_properties, ParentChildSizePropertiesUpdate(), Xrb::Rect< T >::SetSize(), Xrb::Rect< T >::Size(), and SizeRangeAdjustment().

Referenced by MoveToAndResize(), ResizeByRatios(), SetSizeProperty(), and SetSizePropertyEnabled().

ScreenCoordVector2 Xrb::Widget::ResizeByRatios

(

FloatVector2 const &

ratios

)

A screen-basis-ratio based frontend to Resize.

Returns:

The resulting actual size of this widget.

Definition at line 503 of file xrb_widget.cpp.

References Resize(), and TopLevelParent().

ScreenCoordVector2 Xrb::Widget::MoveToAndResize

(

ScreenCoordRect const &

screen_rect

)

Attempts to move and resize this widget so that its screen rectangle matches the one given.

Returns:

The resulting actual size of this widget.

Definition at line 510 of file xrb_widget.cpp.

References Xrb::Rect< T >::BottomLeft(), MoveTo(), Resize(), and Xrb::Rect< T >::Size().

bool Xrb::Widget::Focus

(

)

Focuses this widget with respect to its parent widget.

Widgets that are not direct ancestors of this widget will be defocused before any focusing happens.

Returns:

True iff it (or any of its children) accepted focus.

Definition at line 521 of file xrb_widget.cpp.

References EffectiveParent(), IsFocused(), IsHidden(), and IsTopLevelParent().

Referenced by GrabMouse().

void Xrb::Widget::Unfocus

(

)

Unfocuses this widget with respect to its parent widget.

The parent widget remains focused.

Definition at line 556 of file xrb_widget.cpp.

References IsFocused().

Referenced by SetIsEnabled(), and ToggleIsHidden().

void Xrb::Widget::GrabMouse

(

)

Grabs the mouse input.

All mouse events will be exclusively sent to this widget via its ancestors.

Definition at line 566 of file xrb_widget.cpp.

References EffectiveParent(), Focus(), HandleMouseGrabOn(), and IsMouseGrabbed().

void Xrb::Widget::UnGrabMouse

(

)

Lets go of the mouse input.

Other widgets may now receive mouse events.

Definition at line 597 of file xrb_widget.cpp.

References EffectiveParent(), HandleMouseGrabOff(), and IsMouseGrabbed().

void Xrb::Widget::DetachFromParent

(

)

Detaches this widget from its parent.

This widget must have a parent widget.

Definition at line 620 of file xrb_widget.cpp.

Referenced by ~Widget().

void Xrb::Widget::SetIsEnabled

(

bool

is_enabled

)

[virtual]

Sets the enabled state of this widget.

Disabled widgets will not accept events.

Definition at line 628 of file xrb_widget.cpp.

References Xrb::SignalHandler::IsBlockingSenders(), IsModal(), IsTopLevelParent(), Xrb::SignalHandler::SetIsBlockingSenders(), and Unfocus().

Referenced by Disable(), and Enable().

void Xrb::Widget::Disable

(

)

[inline]

Disables this widget.

Disabled widgets will not accept events.

Definition at line 626 of file xrb_widget.hpp.

References SetIsEnabled().

void Xrb::Widget::ToggleIsHidden

(

)

Toggles the hidden state.

Must not currently be a modal widget.

Definition at line 656 of file xrb_widget.cpp.

References IsModal(), ParentChildSizePropertiesUpdate(), and Unfocus().

Referenced by SetIsHidden().

void Xrb::Widget::SetIsHidden

(

bool

is_hidden

)

Sets the hidden state of this widget.

If this widget is a child in a layout widget, then this will cause the widget to be ignored by the layout (and may cause relative repositioning of the other Layout child widgets).

This widget must not currently be a modal widget.

Parameters:

is_hidden

The new value of the hidden property.

Definition at line 674 of file xrb_widget.cpp.

References ToggleIsHidden().

Referenced by Hide(), and Show().

void Xrb::Widget::Hide

(

)

[inline]

Hides this widget.

Must not currently be a modal widget.

Definition at line 645 of file xrb_widget.hpp.

References SetIsHidden().

void Xrb::Widget::Show

(

)

[inline]

Shows this widget.

Must not currently be a modal widget.

Definition at line 649 of file xrb_widget.hpp.

References SetIsHidden().

virtual Uint32 Xrb::Widget::WidgetSkinHandlerChildCount

(

)

const [inline, protected, virtual]

This implementation was required by WidgetSkinHandler.

See also:

WidgetSkinHandler::WidgetSkinHandlerChildCount

Implements Xrb::WidgetSkinHandler.

Definition at line 656 of file xrb_widget.hpp.

virtual WidgetSkinHandler* Xrb::Widget::WidgetSkinHandlerChild

(

Uint32

index

)

[inline, protected, virtual]

This implementation was required by WidgetSkinHandler.

See also:

WidgetSkinHandler::WidgetSkinHandlerChild

Implements Xrb::WidgetSkinHandler.

Definition at line 660 of file xrb_widget.hpp.

WidgetSkinHandler * Xrb::Widget::WidgetSkinHandlerParent

(

)

[protected, virtual]

This implementation was required by WidgetSkinHandler.

See also:

WidgetSkinHandler::WidgetSkinHandlerParent

Implements Xrb::WidgetSkinHandler.

Definition at line 684 of file xrb_widget.cpp.

virtual void Xrb::Widget::HandleFrame

(

)

[inline, protected, virtual]

Override of FrameHandler::HandleFrame which does anything that needs to be done once per iteration of the game loop.

Calls FrameHandler::ProcessFrame on all child widgets.

This function is guaranteed to be called once per game loop frame, unlike Widget::Draw.

Implements Xrb::FrameHandler.

Definition at line 688 of file xrb_widget.hpp.

bool Xrb::Widget::HandleEvent

(

Event const *

e

)

[protected, virtual]

Override of EventHandler::HandleEvent which does generic event processing.

Subclasses of widget should not override this function -- all of the user interface behavior for Widget is handled/delegated here.

Implements Xrb::EventHandler.

Definition at line 696 of file xrb_widget.cpp.

References Xrb::Event::GetEventType(), IsEnabled(), ProcessCustomEvent(), ProcessDeleteChildWidgetEvent(), and ProcessStateMachineInputEvent().

virtual bool Xrb::Widget::ProcessKeyEvent

(

EventKey const *

e

)

[inline, protected, virtual]

Process a key event.

Subclasses may override this to process key events.

Reimplemented in Xrb::Dialog.

Definition at line 699 of file xrb_widget.hpp.

virtual bool Xrb::Widget::ProcessMouseButtonEvent

(

EventMouseButton const *

e

)

[inline, protected, virtual]

Process a mouse button event.

Subclasses may override this to process mouse button events.

Definition at line 703 of file xrb_widget.hpp.

virtual bool Xrb::Widget::ProcessMouseWheelEvent

(

EventMouseWheel const *

e

)

[inline, protected, virtual]

Process a mouse wheel event.

Subclasses may override this to process mouse wheel events.

Definition at line 707 of file xrb_widget.hpp.

virtual bool Xrb::Widget::ProcessMouseMotionEvent

(

EventMouseMotion const *

e

)

[inline, protected, virtual]

Process a mouse motion event.

Subclasses may override this to process motion events.

Definition at line 711 of file xrb_widget.hpp.

virtual bool Xrb::Widget::ProcessJoyEvent

(

EventJoy const *

e

)

[inline, protected, virtual]

Process a joystick event.

Subclasses may override this to process joystick events.

Definition at line 715 of file xrb_widget.hpp.

virtual bool Xrb::Widget::ProcessStateMachineInputEvent

(

EventStateMachineInput const *

e

)

[inline, protected, virtual]

Process a StateMachineInput event.

Subclasses may override this to process StateMachineInput events.

Definition at line 719 of file xrb_widget.hpp.

Referenced by HandleEvent().

virtual bool Xrb::Widget::ProcessCustomEvent

(

EventCustom const *

e

)

[inline, protected, virtual]

Process a custom event.

Subclasses may override this to process custom events -- events not explicitly handled by the above overridable handlers.

Definition at line 724 of file xrb_widget.hpp.

Referenced by HandleEvent().

virtual void Xrb::Widget::HandleFocus

(

)

[inline, protected, virtual]

Handler that is called when this widget becomes focused.

Subclasses should override this when they need to do something when the widget gains focus.

Definition at line 734 of file xrb_widget.hpp.

virtual void Xrb::Widget::HandleUnfocus

(

)

[inline, protected, virtual]

Handler that is called when this widget becomes unfocused.

Subclasses should override this when they need to do something when the widget loses focus.

Definition at line 739 of file xrb_widget.hpp.

virtual void Xrb::Widget::HandleMouseoverOn

(

)

[inline, protected, virtual]

Handler that is called when the mouseover flag is set ON (from off).

Subclasses should override this when they need to do something when the mouse moves onto the widget.

Definition at line 745 of file xrb_widget.hpp.

virtual void Xrb::Widget::HandleMouseoverOff

(

)

[inline, protected, virtual]

Handler that is called when the mouseover flag is set OFF (from on).

Subclasses should override this when they need to do something when the mouse moves off the widget.

Definition at line 751 of file xrb_widget.hpp.

virtual void Xrb::Widget::HandleMouseGrabOn

(

)

[inline, protected, virtual]

Handler that is called when this widget grabs the mouse input.

Subclasses should override this when they need to do something when the mouse input grab is turned on.

Definition at line 756 of file xrb_widget.hpp.

Referenced by GrabMouse().

virtual void Xrb::Widget::HandleMouseGrabOff

(

)

[inline, protected, virtual]

Handler that is called when this widget lets go of the mouse input.

Subclasses should override this when they need to do something when the mouse input grab is turned off.

Definition at line 762 of file xrb_widget.hpp.

Referenced by UnGrabMouse().

void Xrb::Widget::HandleChangedBackground

(

)

[protected, virtual]

Handler that is called when the basic background object is changed.

Subclasses should override this when they need to do something when the basic render background object has changed.

Note:

If a subclass overrides this function, it should call Widget::HandleChangedBackground -- or the HandleChangedBackground belonging to its superclass, if applicable.

Definition at line 754 of file xrb_widget.cpp.

References UpdateRenderBackground().

Referenced by SetBackground().

virtual void Xrb::Widget::HandleChangedFrameMargins

(

)

[inline, protected, virtual]

Handler that is called when the frame margins have been changed.

Subclasses should override this when they need to do something when the frame margins have been changed.

See also:

Layout

Reimplemented in Xrb::Label.

Definition at line 779 of file xrb_widget.hpp.

Referenced by SetFrameMargins().

virtual void Xrb::Widget::HandleChangedContentMargins

(

)

[inline, protected, virtual]

Handler that is called when the content margins have been changed.

Subclasses should override this when they need to do something when the content margins have been changed.

See also:

Layout

Reimplemented in Xrb::Label.

Definition at line 786 of file xrb_widget.hpp.

Referenced by SetContentMargins().

void Xrb::Widget::UpdateRenderBackground

(

)

[protected, virtual]

Assigns the basic widget background to the render background.

Subclasses may override this function to implement custom background behavior such as mouseover highlighting and button-depressing.

Reimplemented in Xrb::ModalWidget.

Definition at line 759 of file xrb_widget.cpp.

References Background(), and SetRenderBackground().

Referenced by HandleChangedBackground(), and InitializeFromWidgetSkinProperties().

void Xrb::Widget::ParentChildSizePropertiesUpdate

(

bool

defer_parent_update

)

[protected]

Calls ChildSizePropertiesChanged on this widget's parent, with the "this" pointer as the parameter.

Parameters:

defer_parent_update

If this is false, nothing is done. This is used primarily when there is going to be lots of updates in a row, and all but the last update don't matter.

Definition at line 764 of file xrb_widget.cpp.

Referenced by Resize(), SetIsModal(), SetSizeProperty(), SetSizePropertyEnabled(), and ToggleIsHidden().

bool Xrb::Widget::AdjustFromMinSize

(

ScreenCoordRect *

screen_rect

)

const [protected]

Adjusts *size by the minimum size.

Returns:

True iff *size was changed.

Definition at line 770 of file xrb_widget.cpp.

References Xrb::SizeProperties::m_min_size, Xrb::SizeProperties::m_min_size_enabled, m_size_properties, Xrb::Rect< T >::SetSize(), Xrb::Rect< T >::Size(), Xrb::Dim::X, and Xrb::Dim::Y.

Referenced by AdjustedSize(), MinSizeUpdated(), SetSizeProperty(), and SetSizePropertyEnabled().

bool Xrb::Widget::AdjustFromMaxSize

(

ScreenCoordRect *

screen_rect

)

const [protected]

Adjusts *size by the maximum size.

Returns:

True iff *size was changed.

Definition at line 788 of file xrb_widget.cpp.

References Xrb::SizeProperties::m_max_size, Xrb::SizeProperties::m_max_size_enabled, m_size_properties, Xrb::Rect< T >::SetSize(), Xrb::Rect< T >::Size(), Xrb::Dim::X, and Xrb::Dim::Y.

Referenced by AdjustedSize(), MaxSizeUpdated(), SetSizeProperty(), and SetSizePropertyEnabled().

---

Member Data Documentation

bool Xrb::Widget::m_accepts_focus [protected]

Indicates if this widget accepts focus on its own.

A value of false will prevent container widgets from blocking child widgets from gaining focus.

Definition at line 830 of file xrb_widget.hpp.

Referenced by AcceptsFocus(), and Widget().

bool Xrb::Widget::m_accepts_mouseover [protected]

Indicates if this widget accepts the mouseover flag on its own.

A value of false will not prevent container widgets from blocking child widgets from accepting mouseover.

Definition at line 835 of file xrb_widget.hpp.

Referenced by AcceptsMouseover(), and Widget().

Color Xrb::Widget::m_color_bias [protected]

The color bias of the widget.

The color bias represents a blending function which is applied to each drawing operation at or below this widget in the widget hierarchy.

Definition at line 840 of file xrb_widget.hpp.

Referenced by ColorBias(), and Widget().

Color Xrb::Widget::m_color_mask [protected]

The color mask of the widget.

The color mask represents a modulation function (simple multiplication) which is applied to each drawing operation at or below this widget in the widget hierarchy.

Definition at line 846 of file xrb_widget.hpp.

Referenced by ColorMask(), and Widget().

---

The documentation for this class was generated from the following files:

• xrb_widget.hpp
• xrb_widget.cpp