WidgetContainer Class Reference

This class is the base class for all widget containers. More...

Inheritance diagram for WidgetContainer:

Public Types
enum	FocusStrategy {   Inherit, AllowAll, Selective, Strict,   Deny }
	Defines focus strategy for the container. Default is Inherit. More...

Public Member Functions
	WidgetContainer ()=default
	WidgetContainer (WidgetContainer &&)=default
virtual	~WidgetContainer ()
	Virtual destructor. More...
bool	Add (Widget &widget)
	Adds the given widget to this container. More...
void	AttachOrganizer (Organizers::Base &organizer)
	Attaches an organizer to this container. More...
auto	begin ()
	Returns the begin iterator for the contained widgets. More...
auto	begin () const
	Returns the begin iterator for the contained widgets. More...
void	ChangeFocusOrder (Widget &widget, int order)
	Changes the focus order of the given widget. More...
void	ChangeZorder (Widget &widget, int order)
	Changes the z-order of the widget. More...
virtual bool	CharacterEvent (Char c)
	This function should be called whenever a character is received from operating system. More...
template<class O_ , class ... Args_>
O_ &	CreateOrganizer (Args_ &&... args)
	Creates a new organizer that lives with this container. More...
FocusStrategy	CurrentFocusStrategy () const
	Returns the active focus strategy. This function will not return Inherit. More...
void	Disable ()
	Disables the container, disallowing interactions of all widgets in it. More...
void	DisableTabSwitch ()
	Disable tab switching. More...
void	Displaced ()
	Call this function if the container or widgets in it is moved without move function is called. More...
void	Enable ()
	Enables the container, allowing interaction with the widgets in it. More...
void	EnableTabSwitch ()
	Enable tab switching. More...
auto	end ()
	Returns the end iterator for the contained widgets. More...
auto	end () const
	Returns the end iterator for the contained widgets. More...
virtual bool	EnsureVisible (const Widget &widget)=0
	Ensures the widget is visible. More...
bool	FocusFirst ()
	Focuses the first widget that accepts focus. More...
bool	FocusLast ()
	Focuses the last widget in the container. More...
bool	FocusNext ()
	Focuses the next widget that accepts focus. More...
bool	FocusNext (const Widget &widget)
	Focuses the next widget that accepts focus starting from the given focus index. More...
bool	FocusNext (int after)
	Focuses the next widget that accepts focus starting from the given focus index. More...
bool	FocusPrevious ()
	Focuses the previous widget that accepts focus. More...
bool	FocusPrevious (const Widget &widget)
	Focuses the previous widget that accepts focus. More...
bool	FocusPrevious (int before)
	Focuses the previous widget that accepts focus. More...
void	ForceRemove (Widget &widget)
	Forcefully removes the given widget from this container. More...
void	ForceRemoveFocus ()
	Forcefully removes the focus from the focused widget. More...
virtual Widget &	GetCancel () const
	Returns the cancel element of the container which is called when the use presses escape key. More...
int	GetCount () const
	Returns the number of widgets in this container. More...
virtual Widget &	GetDefault () const
	Returns the default element of the container. More...
Widget &	GetFocus () const
	Returns the focused widget. More...
int	GetFocusOrder (const Widget &widget) const
FocusStrategy	GetFocusStrategy () const
	Returns the focus strategy set to this container. More...
virtual Geometry::Size	GetInteriorSize () const =0
	Should return the interior (usable) size of the container. More...
Organizers::Base &	GetOrganizer () const
	Returns the organizer controlling this container. More...
virtual bool	HasCancel () const
	Returns if this container has a cancel widget. More...
virtual bool	HasDefault () const
	Returns if this container has a default object. More...
bool	HasFocusedWidget () const
	Returns if this container has a focused widget. More...
bool	HasOrganizer () const
	Returns if this container has an organizer. More...
bool	Insert (Widget &widget, int index)
	Add the given widget to this container. More...
virtual bool	IsEnabled () const
	Returns whether container is enabled. More...
virtual bool	IsTabSwitchEnabled () const
	Check if tab switch is enabled. More...
virtual bool	IsVisible () const =0
	Should return whether the container is visible. More...
virtual bool	KeyEvent (Input::Key key, float state)
	This function should be called whenever a key is pressed or released. More...
WidgetContainer &	operator= (WidgetContainer &&)=default
Widget &	operator[] (int ind)
	Returns the widget at the given index. More...
const Widget &	operator[] (int ind) const
	Returns the widget at the given index. More...
bool	Remove (Widget &widget)
	Removes the given widget from this container. More...
virtual void	RemoveCancel ()
	Removes the cancel widget of this container. More...
virtual void	RemoveDefault ()
	Removes the default widget of this container. More...
bool	RemoveFocus ()
	Removes the focus from the focused widget. More...
void	RemoveOrganizer ()
	Removes the organizer from this container. More...
virtual ExtenderRequestResponse	RequestExtender (const Gorgon::Layer &self)=0
	This function will return a container that will act as an extender. More...
virtual bool	ResizeInterior (Geometry::Size size)=0
	Should resize the interior (usable) size of the container. More...
virtual void	SetCancel (Widget &widget)
	Sets the cancel widget of the container. More...
virtual void	SetDefault (Widget &widget)
	Sets the default object of the container. More...
virtual void	SetEnabled (bool value)
	Sets the enabled state of this container. More...
void	SetFocusStrategy (FocusStrategy value)
	Sets the focus strategy, see FocusStrategy. More...
bool	SetFocusTo (Widget &widget)
	Sets the focus to the given widget. More...
virtual void	SetTabSwitchEnabledState (bool state)
	Sets the state of tab switching. More...
void	ToggleEnabled ()
	Toggles the enabled state of this container. More...
void	ToggleTabSwitchEnabledState ()
	Toggles the state of tab switching. More...

Protected Member Functions
virtual bool	addingwidget (Widget &)
	This function can return false to prevent the given widget from getting added to the container. More...
virtual void	childboundschanged (Widget *source)
	The boundary of any of the children is changed. Source could be nullptr. More...
bool	distributecharevent (Char c)
	Distributes a pressed character to the focused widget. More...
bool	distributekeyevent (Input::Key key, float state, bool handlestandard)
	Distributes the pressed key to the focused widget. More...
void	distributeparentenabled (bool state)
	Distributes a enabled state to children. More...
virtual void	focuschanged ()
	This function is called when the focus is changed. More...
virtual Layer &	getlayer ()=0
	Returns the layer that will be used to place the contained widgets. More...
virtual FocusStrategy	getparentfocusstrategy () const
	If this widget is not top level, return the current strategy used by the parent. More...
bool	handlestandardkey (Input::Key key)
	Performs the standard operations (tab/enter/escape) More...
virtual bool	removingwidget (Widget &)
	This function is called before removing a widget. More...
virtual void	widgetadded (Widget &)
	This function is called after a widget is added. More...
virtual void	widgetremoved (Widget &)
	This function is called after a widget is removed. More...

Protected Attributes
Containers::Collection< Widget >	widgets
	This container is sorted by the focus order. More...

Detailed Description

This class is the base class for all widget containers.

All widgets require a layer to be placed on, to allow widget containers that are also widgets, this class is left abstract. You may derive from this class and WidgetBase at the same time.

Member Enumeration Documentation

FocusStrategy

enum FocusStrategy

Defines focus strategy for the container. Default is Inherit.

Enumerator
Inherit	Inherit from the parent. If this container is top level then it will be AllowAll
AllowAll	All widgets that can be focused are allowed to receive focus, including buttons but not labels.
Selective	Widgets that require input to work or benefit from input greatly are allowed to receive focus. Button, listbox, and select will loose the ability to receive focus. However, sliders and input boxes will receive the focus
Strict	Only the widget that will not work without input will receive focus. This includes input boxes. This will also disable tab switching.
Deny	No widget is allowed focus and this container will not handle any keys.

Constructor & Destructor Documentation

WidgetContainer() [1/2]

WidgetContainer ( )

default

WidgetContainer() [2/2]

WidgetContainer ( WidgetContainer &&  )

default

~WidgetContainer()

~WidgetContainer ( )

virtual

Virtual destructor.

Member Function Documentation

Add()

bool Add

(

Widget &

widget

)

Adds the given widget to this container.

Widget will be placed to the top of the z-order, to the end of the focus order. If the given widget cannot be added, this function will return false.

References Widget::addedto(), Widget::addingto(), WidgetContainer::addingwidget(), Widget::addto(), WidgetContainer::getlayer(), Widget::GetParent(), Widget::HasParent(), WidgetContainer::Remove(), WidgetContainer::widgetadded(), and WidgetContainer::widgets.

addingwidget()

virtual bool addingwidget ( Widget &  )

protectedvirtual

This function can return false to prevent the given widget from getting added to the container.

AttachOrganizer()

void AttachOrganizer

(

Organizers::Base &

organizer

)

Attaches an organizer to this container.

Ownership is not transferred

References Base::AttachTo(), and Base::Reorganize().

begin() [1/2]

auto begin

(

)

Returns the begin iterator for the contained widgets.

References WidgetContainer::widgets.

begin() [2/2]

auto begin

(

)

const

Returns the begin iterator for the contained widgets.

References WidgetContainer::widgets.

ChangeFocusOrder()

void ChangeFocusOrder	(	Widget &	widget,
		int	order
	)

Changes the focus order of the given widget.

If the order is out of bounds, the widget will be moved to the end. You may use the functions in the widget to manage focus order.

References WidgetContainer::widgets.

ChangeZorder()

void ChangeZorder	(	Widget &	widget,
		int	order
	)

Changes the z-order of the widget.

If the order is out of bounds, the widget will be drawn on top. You may use the functions in the widget to manage z-order.

References WidgetContainer::getlayer(), Widget::setlayerorder(), and WidgetContainer::widgets.

CharacterEvent()

virtual bool CharacterEvent ( Char  c )

virtual

This function should be called whenever a character is received from operating system.

Reimplemented in Panel, and Composer.

References WidgetContainer::distributecharevent().

childboundschanged()

void childboundschanged ( Widget *  source )

protectedvirtual

The boundary of any of the children is changed. Source could be nullptr.

References Base::Reorganize().

CreateOrganizer()

O_& CreateOrganizer

(

Args_ &&...

args

)

Creates a new organizer that lives with this container.

References WidgetContainer::AttachOrganizer().

CurrentFocusStrategy()

FocusStrategy CurrentFocusStrategy

(

)

const

Returns the active focus strategy. This function will not return Inherit.

References WidgetContainer::getparentfocusstrategy(), and WidgetContainer::Inherit.

Disable()

void Disable

(

)

Disables the container, disallowing interactions of all widgets in it.

References WidgetContainer::SetEnabled().

DisableTabSwitch()

void DisableTabSwitch

(

)

Disable tab switching.

Tab switch allows user to change focus to the next widget using tab key

References WidgetContainer::SetTabSwitchEnabledState().

Displaced()

void Displaced

(

)

Call this function if the container or widgets in it is moved without move function is called.

References WidgetContainer::widgets.

distributecharevent()

bool distributecharevent ( Char  c )

protected

Distributes a pressed character to the focused widget.

References Widget::CharacterEvent(), WidgetContainer::CurrentFocusStrategy(), and WidgetContainer::Deny.

distributekeyevent()

bool distributekeyevent ( Input::Key  key, float  state, bool  handlestandard  )

protected

Distributes the pressed key to the focused widget.

If action not handled and and handlestandard is true, this function will also perform standard action.

References WidgetContainer::CurrentFocusStrategy(), WidgetContainer::Deny, WidgetContainer::handlestandardkey(), Widget::KeyEvent(), and WidgetContainer::Strict.

distributeparentenabled()

void distributeparentenabled ( bool  state )

protected

Distributes a enabled state to children.

References WidgetContainer::widgets.

Enable()

void Enable

(

)

Enables the container, allowing interaction with the widgets in it.

References WidgetContainer::SetEnabled().

EnableTabSwitch()

void EnableTabSwitch

(

)

Enable tab switching.

Tab switch allows user to change focus to the next widget using tab key

References WidgetContainer::SetTabSwitchEnabledState().

end() [1/2]

auto end

(

)

Returns the end iterator for the contained widgets.

References WidgetContainer::widgets.

end() [2/2]

auto end

(

)

const

Returns the end iterator for the contained widgets.

References WidgetContainer::widgets.

EnsureVisible()

virtual bool EnsureVisible ( const Widget &  widget )

pure virtual

Ensures the widget is visible.

Returns true if the container can be scroll to make sure the given widget is visible. This function cannot be expected to take outside factors into account, such as occlusion. This function does not change the visibility of the widget and will return false if the widget is not visible.

Implemented in Panel, Composer, RadioButtons< T_, W_ >, Window, and LayerAdapter.

focuschanged()

virtual void focuschanged ( )

protectedvirtual

This function is called when the focus is changed.

Reimplemented in Panel, and Composer.

FocusFirst()

bool FocusFirst

(

)

Focuses the first widget that accepts focus.

If none of the widgets accept focus or if the currently focused widget blocks focus transfer then this function will return false.

References WidgetContainer::FocusNext().

FocusLast()

bool FocusLast

(

)

Focuses the last widget in the container.

If none of the widgets accept focus or if the currently focused widget blocks focus transfer then this function will return false.

References WidgetContainer::FocusPrevious(), and WidgetContainer::widgets.

FocusNext() [1/3]

bool FocusNext

(

)

Focuses the next widget that accepts focus.

If no widget other than the currently focused widget accept focus then this function will return false. Additionally, if the currently focused widget blocks focus transfer, this function will return false.

FocusNext() [2/3]

bool FocusNext

(

const Widget &

widget

)

Focuses the next widget that accepts focus starting from the given focus index.

If no widget other than the currently focused widget accept focus then this function will return false. Additionally, if the currently focused widget blocks focus transfer, this function will return false.

References WidgetContainer::FocusNext(), and WidgetContainer::GetFocusOrder().

FocusNext() [3/3]

bool FocusNext

(

int

after

)

Focuses the next widget that accepts focus starting from the given focus index.

If no widget other than the currently focused widget accept focus then this function will return false. Additionally, if the currently focused widget blocks focus transfer, this function will return false.

References Widget::canloosefocus(), WidgetContainer::CurrentFocusStrategy(), WidgetContainer::Deny, WidgetContainer::EnsureVisible(), WidgetContainer::focuschanged(), WidgetContainer::IsEnabled(), WidgetContainer::IsVisible(), and WidgetContainer::widgets.

FocusPrevious() [1/3]

bool FocusPrevious

(

)

Focuses the previous widget that accepts focus.

If no widget other than the currently focused widget accept focus then this function will return false. Additionally, if the currently focused widget blocks focus transfer, this function will return false.

References WidgetContainer::FocusPrevious().

FocusPrevious() [2/3]

bool FocusPrevious

(

const Widget &

widget

)

Focuses the previous widget that accepts focus.

If no widget other than the currently focused widget accept focus then this function will return false. Additionally, if the currently focused widget blocks focus transfer, this function will return false.

References WidgetContainer::FocusNext(), and WidgetContainer::GetFocusOrder().

FocusPrevious() [3/3]

bool FocusPrevious

(

int

before

)

Focuses the previous widget that accepts focus.

If no widget other than the currently focused widget accept focus then this function will return false. Additionally, if the currently focused widget blocks focus transfer, this function will return false.

References Widget::canloosefocus(), WidgetContainer::CurrentFocusStrategy(), WidgetContainer::Deny, WidgetContainer::EnsureVisible(), WidgetContainer::focuschanged(), WidgetContainer::FocusLast(), WidgetContainer::IsEnabled(), WidgetContainer::IsVisible(), and WidgetContainer::widgets.

ForceRemove()

void ForceRemove

(

Widget &

widget

)

Forcefully removes the given widget from this container.

References WidgetContainer::widgets.

ForceRemoveFocus()

void ForceRemoveFocus

(

)

Forcefully removes the focus from the focused widget.

References WidgetContainer::focuschanged().

GetCancel()

virtual Widget& GetCancel ( ) const

virtual

Returns the cancel element of the container which is called when the use presses escape key.

It also might be activated programmatically. Cancel elements are generally buttons, however, any widget can be cancel widget. If there is no cancel object set, this function will throw. Use HasCancel to check if this container has a cancel widget.

GetCount()

int GetCount

(

)

const

Returns the number of widgets in this container.

References WidgetContainer::widgets.

GetDefault()

virtual Widget& GetDefault ( ) const

virtual

Returns the default element of the container.

Default widget is activated when the user presses enter and the focused widget does not consume the key or if the user presses ctrl+enter. Default elements are generally buttons, however, any widget can be designated as default widget. If there is no default object, this function will throw. Use HasDefault to check if this container has a default widget.

GetFocus()

Gorgon::UI::Widget & GetFocus

(

)

const

Returns the focused widget.

If no widget is focused, this function will throw.

GetFocusOrder()

int GetFocusOrder

(

const Widget &

widget

)

const

References WidgetContainer::widgets.

GetFocusStrategy()

FocusStrategy GetFocusStrategy

(

)

const

Returns the focus strategy set to this container.

Do not use this to determine current strategy, use CurrentFocusStrategy instead.

GetInteriorSize()

virtual Geometry::Size GetInteriorSize ( ) const

pure virtual

Should return the interior (usable) size of the container.

Implemented in RadioButtons< T_, W_ >, Panel, Composer, Window, and LayerAdapter.

getlayer()

virtual Layer& getlayer ( )

protectedpure virtual

Returns the layer that will be used to place the contained widgets.

Implemented in RadioButtons< T_, W_ >, Panel, Composer, Window, and LayerAdapter.

GetOrganizer()

Organizers::Base& GetOrganizer

(

)

const

Returns the organizer controlling this container.

If this container does not have an organizer this function will throw

getparentfocusstrategy()

virtual FocusStrategy getparentfocusstrategy ( ) const

protectedvirtual

If this widget is not top level, return the current strategy used by the parent.

Never return Inherit from this function.

Reimplemented in Panel.

References WidgetContainer::AllowAll.

handlestandardkey()

bool handlestandardkey ( Input::Key  key )

protected

Performs the standard operations (tab/enter/escape)

References Widget::Activate(), Modifier::Ctrl, Gorgon::Input::Keyboard::CurrentModifier, Gorgon::Input::Keyboard::Keycodes::Enter, Gorgon::Input::Keyboard::Keycodes::Escape, WidgetContainer::FocusNext(), WidgetContainer::FocusPrevious(), Modifier::None, Gorgon::Input::Keyboard::Keycodes::Numpad_Enter, Modifier::Shift, and Gorgon::Input::Keyboard::Keycodes::Tab.

HasCancel()

virtual bool HasCancel ( ) const

virtual

Returns if this container has a cancel widget.

HasDefault()

virtual bool HasDefault ( ) const

virtual

Returns if this container has a default object.

HasFocusedWidget()

bool HasFocusedWidget

(

)

const

Returns if this container has a focused widget.

HasOrganizer()

bool HasOrganizer

(

)

const

Returns if this container has an organizer.

Insert()

bool Insert	(	Widget &	widget,
		int	index
	)

Add the given widget to this container.

Widget will be placed to the top of the z-order, and to the specified focus order. If the given widget cannot be added, this function will return false. If the index is out of bounds the widget will be added at the end.

References Widget::addedto(), Widget::addingto(), WidgetContainer::addingwidget(), Widget::addto(), WidgetContainer::ChangeFocusOrder(), WidgetContainer::ChangeZorder(), WidgetContainer::getlayer(), Widget::setlayerorder(), WidgetContainer::widgetadded(), and WidgetContainer::widgets.

IsEnabled()

virtual bool IsEnabled ( ) const

virtual

Returns whether container is enabled.

Reimplemented in RadioButtons< T_, W_ >, Panel, and Composer.

IsTabSwitchEnabled()

virtual bool IsTabSwitchEnabled ( ) const

virtual

Check if tab switch is enabled.

Tab switch allows user to change focus to the next widget using tab key. Default is enabled.

IsVisible()

virtual bool IsVisible ( ) const

pure virtual

Should return whether the container is visible.

Due to different container designs and capabilities, setting visibility depends on the particular container

Implemented in RadioButtons< T_, W_ >, Panel, Composer, Window, and LayerAdapter.

KeyEvent()

virtual bool KeyEvent ( Input::Key  key, float  state  )

virtual

This function should be called whenever a key is pressed or released.

Reimplemented in Panel, RadioButtons< T_, W_ >, and Composer.

References WidgetContainer::distributekeyevent().

operator=()

WidgetContainer& operator= ( WidgetContainer &&  )

default

operator[]() [1/2]

Widget& operator[]

(

int

ind

)

Returns the widget at the given index.

References WidgetContainer::widgets.

operator[]() [2/2]

const Widget& operator[]

(

int

ind

)

const

Returns the widget at the given index.

References WidgetContainer::widgets.

Remove()

bool Remove

(

Widget &

widget

)

Removes the given widget from this container.

If the widget does not exits, this function will return true without taking any additional action. If the widget cannot be removed from the container, this function will return false.

References WidgetContainer::ForceRemove(), Widget::removingfrom(), WidgetContainer::removingwidget(), and WidgetContainer::widgets.

RemoveCancel()

virtual void RemoveCancel ( )

virtual

Removes the cancel widget of this container.

RemoveDefault()

virtual void RemoveDefault ( )

virtual

Removes the default widget of this container.

RemoveFocus()

bool RemoveFocus

(

)

Removes the focus from the focused widget.

References Widget::canloosefocus(), and WidgetContainer::ForceRemoveFocus().

RemoveOrganizer()

void RemoveOrganizer

(

)

Removes the organizer from this container.

References Base::RemoveFrom().

removingwidget()

virtual bool removingwidget ( Widget &  )

protectedvirtual

This function is called before removing a widget.

Return false to prevent that widget from getting removed. This widget is guaranteed to be in this container

RequestExtender()

virtual ExtenderRequestResponse RequestExtender ( const Gorgon::Layer &  self )

pure virtual

This function will return a container that will act as an extender.

Implemented in RadioButtons< T_, W_ >, Panel, Composer, Window, and LayerAdapter.

ResizeInterior()

virtual bool ResizeInterior ( Geometry::Size  size )

pure virtual

Should resize the interior (usable) size of the container.

If resize operation cannot set the size exactly to the requested size, this function returns false.

Implemented in RadioButtons< T_, W_ >, Panel, Composer, Window, and LayerAdapter.

SetCancel()

virtual void SetCancel ( Widget &  widget )

virtual

Sets the cancel widget of the container.

Ideally this should be a button or a similar widget.

SetDefault()

virtual void SetDefault ( Widget &  widget )

virtual

Sets the default object of the container.

Ideally this should be a button or a similar widget.

SetEnabled()

virtual void SetEnabled ( bool  value )

virtual

Sets the enabled state of this container.

This function will return true if the container is enabled at the end of the call.

Reimplemented in RadioButtons< T_, W_ >, Panel, and Composer.

References WidgetContainer::distributeparentenabled().

SetFocusStrategy()

void SetFocusStrategy

(

FocusStrategy

value

)

Sets the focus strategy, see FocusStrategy.

SetFocusTo()

bool SetFocusTo

(

Widget &

widget

)

Sets the focus to the given widget.

References Widget::allowfocus(), Widget::canloosefocus(), WidgetContainer::CurrentFocusStrategy(), WidgetContainer::Deny, WidgetContainer::EnsureVisible(), WidgetContainer::focuschanged(), Widget::focused(), Widget::focuslost(), Widget::IsEnabled(), Widget::IsVisible(), and WidgetContainer::widgets.

SetTabSwitchEnabledState()

virtual void SetTabSwitchEnabledState ( bool  state )

virtual

Sets the state of tab switching.

Tab switch allows user to change focus to the next widget using tab key

ToggleEnabled()

void ToggleEnabled

(

)

Toggles the enabled state of this container.

If the state is toggled after the call, this function will return true.

References WidgetContainer::IsEnabled(), and WidgetContainer::SetEnabled().

ToggleTabSwitchEnabledState()

void ToggleTabSwitchEnabledState

(

)

Toggles the state of tab switching.

Tab switch allows user to change focus to the next widget using tab key

widgetadded()

virtual void widgetadded ( Widget &  )

protectedvirtual

This function is called after a widget is added.

widgetremoved()

virtual void widgetremoved ( Widget &  )

protectedvirtual

This function is called after a widget is removed.

Member Data Documentation

widgets

Containers::Collection<Widget> widgets

protected

This container is sorted by the focus order.

---

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

• Gorgon/UI/WidgetContainer.h
• Gorgon/UI/WidgetContainer.cpp