CYIDevWidget Class Reference

Detailed Description

The base class for all dev widgets.

Dev widgets represent a developer utility. They can be as simple as a function call, or as complex as custom views and interactions. Each dev widget, when added to a dev panel, has a dev panel item. This item tells the user what the widget does, what state it is in, and may provide configuration options.

Dev widgets can be in one of four states:

• On
• Of
• Stateless
• Disabled

The widget state has to be set by the widget itself, and must be updated as needed. The CYIDevWidget::State::On and CYIDevWidget::State::Off state imply that the widget makes use of an on/off indicator in the dev panel. This is handled automatically by the dev panel. Widgets that do not wish to make use of the on/off indicator should set their state to CYIDevWidget::StateLESS. When the widget state is set to CYIDevWidget::State::Disabled, it cannot be selected in the dev panel.

Hooks into the app are available through the OnDraw(), OnUpdate(), OnHandleKeyInputs() and OnHandleActionInputs() functions.

On touch devices, arrow and enter keys can be simulated by the dev widget. This can be enabled using the SetUseSimulatedKeys() function.

Configuration options can be provided for dev widgets. If the SetUsesConfigurationItems() function is called with true, the dev panel will automatically display and manage a list of configuraiton items for the widget. These configuration items are configured through the GetConfigurationButtonTitles() function, and the widgets are notified when these configuration items are activated through the OnConfigurationItemClicked() function. Dev widgets may also provide their own configuration views by overriding the OnConfigureButtonClicked() button.

Note

This header is part of the debug-tools optional module.

#include <debug/YiDevWidget.h>

Inheritance diagram for CYIDevWidget:

Public Types
enum	State {   State::Off = 0,   State::On,   State::Stateless,   State::Disabled }

Public Member Functions
	CYIDevWidget (const CYIString &title, const CYIString &subtitle="")
virtual	~CYIDevWidget ()
bool	IsUsingIndicator () const
bool	IsUsingSimulatedKeys () const
bool	IsCapturingAllEvents () const
bool	IsUsingConfigurationItems () const
State	GetState () const
virtual const CYIString &	GetTitle () const
virtual const CYIString &	GetSubtitle () const
void	SetParentPanel (CYIDevPanel *pPanel, size_t indexInPanel)
size_t	GetIndexInPanel () const
void	UpdateWidgetState ()
virtual void	OnPanelItemClicked ()=0
virtual void	RefreshState ()
virtual void	OnConfigureButtonClicked ()
virtual void	OnConfigurationItemClicked (size_t buttonID)
virtual void	OnConfigurationSubpanelClosed ()
virtual void	OnDraw ()
virtual bool	OnUpdate (bool *pSkipUpdate=nullptr)
virtual bool	OnHandleKeyInputs (const CYIKeyEvent &keyEvent)
virtual bool	OnHandleActionInputs (const CYIActionEvent &actionEvent)
virtual bool	OnPreFilterEvent (const std::shared_ptr< CYIEventDispatcher > &pDispatcher, CYIEvent *pEvent, CYIEventHandler *pDestination)
void	SimulatePanelItemClicked ()
bool	SimulateKeyPress (const CYIKeyEvent &keyEvent)
void	SimulatedKeyPressesEnded ()
Public Member Functions inherited from CYISignalHandler
	CYISignalHandler ()
	CYISignalHandler (const CYISignalHandler &signalHandler)
virtual	~CYISignalHandler ()
CYISignalHandler &	operator= (const CYISignalHandler &signalHandler)
void	MoveToThread (CYIThread *pThread)
	This function allows the user to override the default thread affinity to any CYIThread that may or may not be running. More...
CYIThreadHandle	GetThreadAffinity () const
void	SetThreadAffinity (const CYIThreadHandle &threadAffinity)
virtual bool	IsConnected () const
virtual bool	IsConnected (const CYISignalBase &signal) const
void	Disconnect (CYISignalBase &signal)
void	DisconnectFromAllSignals ()
Public Member Functions inherited from CYIThread::Listener
	Listener ()
virtual	~Listener ()
virtual void	OnThreadStarted (CYIThread *)
virtual void	OnThreadTerminated (CYIThread *)
virtual void	OnThreadFinished (CYIThread *)

Protected Member Functions
void	SetUseSimulatedKeys (bool useSimulatedKeys)
void	SetCaptureAllEvents (bool captureAllEvents)
void	SetUsesConfigurationItems (bool usesConfigurationItems)
virtual std::vector< std::pair< CYIString, CYIString > >	GetConfigurationButtonTitles ()
CYISceneNode *	GetLogicalRoot () const

Protected Attributes
CYIDevPanel *	m_pParentPanel
size_t	m_indexInPanel
State	m_state
CYIString	m_title
CYIString	m_subtitle

Member Enumeration Documentation

State

enum CYIDevWidget::State

strong

The various states that dev widgets can be in.

Enumerator
Off	Indicates that the widget is inactive/off.
On	Indicates that the widget is active/on.
Stateless	Indicates that this widget does not make use of states.
Disabled	Indicates that this widget cannot (currently) be activated.

Constructor & Destructor Documentation

CYIDevWidget()

CYIDevWidget::CYIDevWidget	(	const CYIString &	title,
		const CYIString &	subtitle = ""
	)

~CYIDevWidget()

virtual CYIDevWidget::~CYIDevWidget ( )

virtual

Member Function Documentation

GetConfigurationButtonTitles()

virtual std::vector<std::pair<CYIString, CYIString> > CYIDevWidget::GetConfigurationButtonTitles ( )

protectedvirtual

Returns a vector of configuration items. These items will be used to populate the configuration subpanel when that subpanel is open. The pairs in the vector must contain the title and subtitle of the configuration items respectively.

Note

This is used as an 'easy' way to provide configuration options. Alternatively, the OnConfigureButtonClicked() function can be overridden to display a custom configuration view.

See also

SetUsesConfigurationItems

GetIndexInPanel()

size_t CYIDevWidget::GetIndexInPanel

(

)

const

Returns the index of the widget within the dev panel.

GetLogicalRoot()

CYISceneNode* CYIDevWidget::GetLogicalRoot ( ) const

protected

Finds and returns the logical root of the scene tree.

GetState()

State CYIDevWidget::GetState

(

)

const

Returns the current state of the widget.

GetSubtitle()

virtual const CYIString& CYIDevWidget::GetSubtitle ( ) const

virtual

Returns the subtitle for this widget. The subtitle is displayed in the dev panel's entry for the widget. The subtitle is displayed under the title, but in a smaller font. By default this returns the value of the m_subtitle variable, but sub-classes can override this function to return something different.

GetTitle()

virtual const CYIString& CYIDevWidget::GetTitle ( ) const

virtual

Returns the title for this widget. The title is displayed in the dev panel's entry for the widget. By default this returns the value of the m_title variable, but sub-classes can override this function to return something different.

IsCapturingAllEvents()

bool CYIDevWidget::IsCapturingAllEvents

(

)

const

Returns true if this widget is capturing all events when active.

See also

SetCaptureAllEvents

IsUsingConfigurationItems()

bool CYIDevWidget::IsUsingConfigurationItems

(

)

const

Returns true if this widget has configuration items.

See also

SetUsesConfigurationItems

IsUsingIndicator()

bool CYIDevWidget::IsUsingIndicator

(

)

const

Returns true if this widget uses an on/off indicator in the dev panel.

IsUsingSimulatedKeys()

bool CYIDevWidget::IsUsingSimulatedKeys

(

)

const

Returns true if this widget makes use of simulated keys (for touch devices).

See also

SetUseSimulatedKeys

OnConfigurationItemClicked()

virtual void CYIDevWidget::OnConfigurationItemClicked ( size_t  buttonID )

virtual

Called when the user selects a configuration item. The buttonID parameter denotes the index of the configuration item that was selected, starting at 0.

OnConfigurationSubpanelClosed()

virtual void CYIDevWidget::OnConfigurationSubpanelClosed ( )

virtual

Called when the configuration subpanel is closing.

OnConfigureButtonClicked()

virtual void CYIDevWidget::OnConfigureButtonClicked ( )

virtual

Called when the user clicks the 'configure' button for this widget. Normally this does not need to be overridden, and the GetConfigurationButtonTitles() function is overridden instead to provide configuration options. However, some widgets may want to override this function to display a custom configuration view.

OnDraw()

virtual void CYIDevWidget::OnDraw ( )

inlinevirtual

Called during the app's Draw cycle. This is called after the scene tree has been rendered (and after the dev panel itself has been rendered). Widgets that make use of CYIGeometryBatch will typically want to implement this function.

Reimplemented in CYIDevWidgetWithText.

OnHandleActionInputs()

virtual bool CYIDevWidget::OnHandleActionInputs ( const CYIActionEvent &  actionEvent )

virtual

Called when an action input occurs. If true is returned, the input will not be propagated to the app.

Reimplemented in CYIDevWidgetWithText.

OnHandleKeyInputs()

virtual bool CYIDevWidget::OnHandleKeyInputs ( const CYIKeyEvent &  keyEvent )

virtual

Called when a key event occurs. If true is returned, the event will not be propagated to the app.

Reimplemented in CYIDevWidgetWithText.

OnPanelItemClicked()

virtual void CYIDevWidget::OnPanelItemClicked ( )

pure virtual

Called when the widget's item in the dev panel is clicked. This is where a widgets should implement its behaviour. Widgets often update their state when this function is called.

Note

At a minimum, dev widgets must implement this function.

Implemented in CYIDevWidgetWithText, CYISignalWidget, and CYIDevWidgetWithView.

OnPreFilterEvent()

virtual bool CYIDevWidget::OnPreFilterEvent ( const std::shared_ptr< CYIEventDispatcher > &  pDispatcher, CYIEvent *  pEvent, CYIEventHandler *  pDestination  )

virtual

Called before an event is processed by the default event dispatcher. If true is returned, the event is not propagated to the rest of the app.

OnUpdate()

virtual bool CYIDevWidget::OnUpdate ( bool *  pSkipUpdate = nullptr )

virtual

Called during the app's Update cycle. This is called prior to the scene tree's update. The pSkipUpdate boolean can be set to true to skip updating the scene tree. This function should return true if a draw is required.

Reimplemented in CYIDevWidgetWithText.

RefreshState()

virtual void CYIDevWidget::RefreshState ( )

inlinevirtual

Used to refresh the state of the widget. This is called when the dev panel is opened.

Reimplemented in CYISignalWidget, and CYIDevWidgetWithView.

SetCaptureAllEvents()

void CYIDevWidget::SetCaptureAllEvents ( bool  captureAllEvents )

protected

Sets whether this widget should capture all events when active. If called with true, this widget will report all key and action events (including trackpad events) as having been 'handled', even if the widget did not report those events as handled. This is useful for full-screen widgets which should block all input to the rest of the app.

SetParentPanel()

void CYIDevWidget::SetParentPanel	(	CYIDevPanel *	pPanel,
		size_t	indexInPanel
	)

Sets owner of this widget to pPanel, and the index in the owner's list to indexInPanel. This is called by the dev panel when a widget is added to said panel, and the set values are used by the widget to access panel functions.

SetUsesConfigurationItems()

void CYIDevWidget::SetUsesConfigurationItems ( bool  usesConfigurationItems )

protected

Sets the 'uses configuration items' flag of this widget. If called with usesConfigurationItems set to true, the dev panel will display a configuration arrow for this widget's dev panel item.

The configuration arrow is a button displayed in the dev panel to indicate that a specific entry has configuration options, as well as to provide to the user a way to display the configuration items.

SetUseSimulatedKeys()

void CYIDevWidget::SetUseSimulatedKeys ( bool  useSimulatedKeys )

protected

Sets the 'use simulated key' flag of this widget. When called with useSimulatedKeys set to true, the widget will be using 'simulated' arrow and 'enter' keys. This is useful on touch devices for simulating key presses.

SimulatedKeyPressesEnded()

void CYIDevWidget::SimulatedKeyPressesEnded

(

)

Called by the dev panel when simulated key presses have ended. This is used to stop repeated key events.

SimulateKeyPress()

bool CYIDevWidget::SimulateKeyPress

(

const CYIKeyEvent &

keyEvent

)

Called by the dev panel to simulate a keypress.

SimulatePanelItemClicked()

void CYIDevWidget::SimulatePanelItemClicked

(

)

Simulates clicking the widget's item in the dev panel. This is useful for enabling the widget when the user selects a configuration option.

UpdateWidgetState()

void CYIDevWidget::UpdateWidgetState

(

)

Update the title, the subtitle and the on/off indicator of widget on the dev panel.

Member Data Documentation

m_indexInPanel

size_t CYIDevWidget::m_indexInPanel

protected

m_pParentPanel

CYIDevPanel* CYIDevWidget::m_pParentPanel

protected

m_state

State CYIDevWidget::m_state

protected

m_subtitle

CYIString CYIDevWidget::m_subtitle

protected

m_title

CYIString CYIDevWidget::m_title

protected

---

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

• debug/YiDevWidget.h