AlgAudio::UIWidget Class Reference

#include <UIWidget.hpp>

Inheritance diagram for AlgAudio::UIWidget:

Classes
class	ID

Public Member Functions
virtual void	CustomDraw (DrawContext &c)=0
virtual std::shared_ptr< UIWidget >	CustomFindChild (ID) const
virtual void	CustomResize (Size2D)
void	Draw (DrawContext &c)
std::shared_ptr< UIWidget >	FindChild (ID search_id)
Size2D	GetCurrentSize () const
Point2D	GetPosInParent (std::shared_ptr< UIWidget > ancestor)
Size2D	GetRequestedSize () const
std::shared_ptr< Window >	GetWindow ()
bool	HasParent ()
bool	HasZeroArea () const
virtual void	OnFocusChanged (bool)
virtual void	OnKeyboard (KeyData)
virtual void	RequestFocus () override
void	Resize (Size2D s)
void	SetBackColor (const Color &c)
void	SetCustomSize (Size2D size)
void	SetFrontColor (const Color &c)
void	TriggerFakeResize ()
virtual	~UIWidget ()
Public Member Functions inherited from AlgAudio::UIMouseEventsBase
virtual void	CustomMouseEnter (Point2D)
virtual void	CustomMouseLeave (Point2D)
virtual void	CustomMouseMotion (Point2D, Point2D)
virtual bool	CustomMousePress (bool, MouseButton, Point2D)
void	OnMouseEnter (Point2D)
void	OnMouseLeave (Point2D)
void	OnMouseMotion (Point2D, Point2D)
bool	OnMousePress (bool, MouseButton, Point2D)
void	SetFocusable (bool f)
Public Member Functions inherited from AlgAudio::UIVisibilityBase
bool	IsDrawn () const
bool	IsInvisible () const
void	SetDisplayMode (DisplayMode m)

Public Attributes
bool	debug_this_widget = false
std::weak_ptr< UIWidget >	parent
ID	widget_id
Public Attributes inherited from AlgAudio::UIMouseEventsBase
Point2D	last_mouse_pos
Signal	on_clicked
Signal< Point2D >	on_motion
Signal< bool >	on_pointed
Signal< bool >	on_pressed
Public Attributes inherited from AlgAudio::UIVisibilityBase
Signal	on_display_mode_changed
Public Attributes inherited from AlgAudio::SubscriptionsManager
SubscriptionList	subscriptions

Protected Member Functions
bool	IsFocused () const
bool	IsRoot () const
virtual void	OnChildFocusRequested (std::shared_ptr< UIWidget >)
virtual bool	OnChildFocusTested (std::shared_ptr< const UIWidget >)
virtual void	OnChildRequestedSizeChanged ()
virtual void	OnChildVisibilityChanged ()
void	SetMinimalSize (Size2D)
void	SetNeedsRedrawing ()
	UIWidget (std::weak_ptr< Window > parent_window)
Protected Member Functions inherited from AlgAudio::UIMouseEventsBase
	UIMouseEventsBase ()
Protected Member Functions inherited from AlgAudio::UIVisibilityBase
	UIVisibilityBase ()

Protected Attributes
Size2D	current_size = Size2D(0,0)
std::weak_ptr< Window >	window
Protected Attributes inherited from AlgAudio::UIMouseEventsBase
bool	focusable = true
bool	pointed = false
bool	pressed = false
Protected Attributes inherited from AlgAudio::UIVisibilityBase
DisplayMode	display_mode = DisplayMode::Visible

Additional Inherited Members
Public Types inherited from AlgAudio::UIVisibilityBase
enum	DisplayMode { DisplayMode::Visible, DisplayMode::EmptySpace, DisplayMode::Invisible }

Detailed Description

Widgets are drawable, interactive parts of the user interface. This is the base class for many many interface elements, such as buttons, labels, sliders, etc.

It is recommended for widgets to implement Create static method, which returns a new shared_ptr of that object type, which simplifies the syntax for interface building. It shall be remembered, however, that a separate init() function may be destignated to be run once the constructor finishes, so that shared_from_this can work correctly (in case the this pointer is needed during initialisation, e.g. if a widget wishes to build a subinterface and parent pointers have to be filled).

When implementing custom widgets you are expected to override CustomDraw with a specialized version. Do not implement your own Draw. If your widget has children and you wish to draw them too, use their Draw. Draw is basically a wrapper for CustomDraw, which performs visibility check, size clipping, resizing and texture caching. Use Draw, but write CustomDraw.

When a widget gets drawn, the draw area size is guaranteed to be of exactly the same dimentions, as were set by the last call to CustomResize. Therefore you can use CustomResize to calculate your children size, but remeber to pass the resize event down to them, by using Resize.

At the moment when CustomResize is called, the previous widget size is still stored in current_size, the new size is passed as an argument to CustomResize (but you don't need to correct current_size on your own).

Constructor & Destructor Documentation

AlgAudio::UIWidget::UIWidget ( std::weak_ptr< Window >  parent_window )

protected

virtual AlgAudio::UIWidget::~UIWidget ( )

inlinevirtual

Member Function Documentation

virtual void AlgAudio::UIWidget::CustomDraw ( DrawContext &  c )

pure virtual

Implemented in AlgAudio::CanvasView, AlgAudio::UICheckbox, AlgAudio::StandardModuleGUI, AlgAudio::UITextArea, AlgAudio::UIBox, AlgAudio::UILabel, AlgAudio::UISlider, AlgAudio::UIButton, AlgAudio::UIAnimDrawer, AlgAudio::UILayered, AlgAudio::UIPosition, AlgAudio::UIProgressBar, AlgAudio::UITextEntry, AlgAudio::UICentered, AlgAudio::UIMarginBox, and AlgAudio::UISeparator.

virtual std::shared_ptr<UIWidget> AlgAudio::UIWidget::CustomFindChild ( ID  ) const

inlinevirtual

Reimplemented in AlgAudio::StandardModuleGUI, AlgAudio::UIBox, and AlgAudio::UIContainerSingle.

virtual void AlgAudio::UIWidget::CustomResize ( Size2D  )

inlinevirtual

Reimplemented in AlgAudio::UISlider, AlgAudio::UICheckbox, AlgAudio::StandardModuleGUI, AlgAudio::UIBox, AlgAudio::UIAnimDrawer, AlgAudio::UILayered, AlgAudio::UICentered, and AlgAudio::UIMarginBox.

void AlgAudio::UIWidget::Draw

(

DrawContext &

c

)

std::shared_ptr<UIWidget> AlgAudio::UIWidget::FindChild ( ID  search_id )

inline

This method lets you search the widget hierarchy tree for a transitive child with given id.

Size2D AlgAudio::UIWidget::GetCurrentSize ( ) const

inline

The current size is the actual size this widget takes on screen. This is exactly the dimensions of the DrawContext from the last time this widget was drawn. Note that before a widget is drawn for the first time, this value is unspecified.

Point2D AlgAudio::UIWidget::GetPosInParent

(

std::shared_ptr< UIWidget >

ancestor

)

This function returns an offset at which this widget is drawn inside ancestor. The argument can be either a diretct parent, or a transitive one.

Size2D AlgAudio::UIWidget::GetRequestedSize ( ) const

inline

The requested size depends on both minimal size and custom size. The minimal size is set by the particular widget implementation. For example, a Box container will set it's minimal size just large enough so that all it's children can be correctly drawn. The custom size is set by the widget's user. It is used if you want a widget to always take take the given area. The requested size is a dimention-wise maximum of minimal and custom sizes. Except for serval cases, a widget shall never be drawn smaller than its requested size.

std::shared_ptr<Window> AlgAudio::UIWidget::GetWindow ( )

inline

bool AlgAudio::UIWidget::HasParent ( )

inline

bool AlgAudio::UIWidget::HasZeroArea ( ) const

inline

Returns true if this widget has zero area, and this it will not take any space.

bool AlgAudio::UIWidget::IsFocused ( ) const

protected

This method checks whether this widget currently has focus. If it does, this method returns true. If it lies on the focus path (e.g. is a box whose child has grabbed focus), it also returns true. This should be always true for a top-level widget. In any other case, false is returned.

bool AlgAudio::UIWidget::IsRoot ( ) const

protected

If a children has no parent, this can mean two things: either it was not yet placed in the hierarchy tree, or it's meant to be the root widget, whose parent is the window. This method returns true iff this is a root widget attached to a window.

virtual void AlgAudio::UIWidget::OnChildFocusRequested ( std::shared_ptr< UIWidget >  )

inlineprotectedvirtual

This method gets called when a child widget tries to catch focus. Multiple container widgets should react on it by remembering which widget is the focused one, and passing keyboard events to it. Single container widgets can ignore this signal, as they have no choice as to whom they shall pass such events to.

Argument: the child that is requesting focus.

Reimplemented in AlgAudio::UIContainerMultiple, and AlgAudio::UIContainerSingle.

virtual bool AlgAudio::UIWidget::OnChildFocusTested ( std::shared_ptr< const UIWidget >  )

inlineprotectedvirtual

This method is called by a child when it has to ask the parent whether it is the focused child. This is necessary for performing IsFocused() test. Containers should override this method.

Reimplemented in AlgAudio::UIContainerMultiple, and AlgAudio::UIContainerSingle.

virtual void AlgAudio::UIWidget::OnChildRequestedSizeChanged ( )

inlineprotectedvirtual

This method will be called by a child when it changes the desired size.

Reimplemented in AlgAudio::StandardModuleGUI, AlgAudio::UICheckbox, AlgAudio::UIBox, AlgAudio::UIAnimDrawer, AlgAudio::UILayered, AlgAudio::UIPosition, AlgAudio::UICentered, and AlgAudio::UIMarginBox.

virtual void AlgAudio::UIWidget::OnChildVisibilityChanged ( )

inlineprotectedvirtual

This method will be called by a child when it changes its visibility.

Reimplemented in AlgAudio::StandardModuleGUI, AlgAudio::UIBox, AlgAudio::UIAnimDrawer, AlgAudio::UILayered, AlgAudio::UIPosition, AlgAudio::UICentered, and AlgAudio::UIMarginBox.

virtual void AlgAudio::UIWidget::OnFocusChanged ( bool  )

inlinevirtual

This method is called when the widget focus state has changed. The only param states whether this widget has now the focus

Reimplemented in AlgAudio::UIContainerMultiple, AlgAudio::UIContainerSingle, AlgAudio::UITextEntry, and AlgAudio::UISlider.

virtual void AlgAudio::UIWidget::OnKeyboard ( KeyData  )

inlinevirtual

Reimplemented in AlgAudio::UIContainerMultiple, AlgAudio::UITextEntry, AlgAudio::CanvasView, and AlgAudio::UIContainerSingle.

virtual void AlgAudio::UIWidget::RequestFocus ( )

overridevirtual

This method is called by the widget when it wishes to grab focus, for example a text entry field should call this method when it's clicked.

Implements AlgAudio::UIMouseEventsBase.

Reimplemented in AlgAudio::UIContainerMultiple, and AlgAudio::UIContainerSingle.

void AlgAudio::UIWidget::Resize

(

Size2D

s

)

void AlgAudio::UIWidget::SetBackColor ( const Color &  c )

inline

void AlgAudio::UIWidget::SetCustomSize

(

Size2D

size

)

If you want to unset a custom-size, simply set the desired dimension(s) to 0, so that minimal-size will always take precedence.

void AlgAudio::UIWidget::SetFrontColor ( const Color &  c )

inline

void AlgAudio::UIWidget::SetMinimalSize ( Size2D  )

protected

If you are implementng a custom widget, you will want to use SetMinimalSize a lot, to notify parent widgets what is the minimal area size that will be large enough for your widget to draw completely. However, by no means should you use SetMinimalSize while inside CustomResize. This could lead to huge problems, including stack loops and undefined widget state. On the other hand, you are very welcome to Resize while reacting on child's requested size change in OnChildRequestedSizeChanged.

void AlgAudio::UIWidget::SetNeedsRedrawing ( )

protected

Calling this method marks the widget's (as well as its ancestor's) render cache as invalid, causing it to be redrawn with the next frame using CustomDraw. It is NOT inefficient to call this method multiple times in a single frame. When implementng a custom widget, you should call this method whenever its internal state changes in a way that modifies widget's appearance.

void AlgAudio::UIWidget::TriggerFakeResize ( )

inline

Starts the downward resize-chain without actually changing size. Useful for propagating size to a newly inserted child.

Member Data Documentation

Size2D AlgAudio::UIWidget::current_size = Size2D(0,0)

protected

bool AlgAudio::UIWidget::debug_this_widget = false

Some widgets output verbose information to stdout when this flag is set. This is useful for debugging new widgets, this way one can select an only instance to be verbose, witout noise from other instances.

std::weak_ptr<UIWidget> AlgAudio::UIWidget::parent

ID AlgAudio::UIWidget::widget_id

std::weak_ptr<Window> AlgAudio::UIWidget::window

protected

Only the topmost widget should be bound to a window.

---

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

• E:/rc/algaudio/libalgaudio/include/UI/UIWidget.hpp