You.i Engine
CYIDevWidget Class Referenceabstract

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.

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,

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 CYIStringGetTitle () const
virtual const CYIStringGetSubtitle () 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 ()
CYISignalHandleroperator= (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 ()
CYISceneNodeGetLogicalRoot () const

Protected Attributes

size_t m_indexInPanel
State m_state
CYIString m_title
CYIString m_subtitle

Member Enumeration Documentation

◆ State

enum CYIDevWidget::State

The various states that dev widgets can be in.


Indicates that the widget is inactive/off.


Indicates that the widget is active/on.


Indicates that this widget does not make use of states.


Indicates that this widget cannot (currently) be activated.

Constructor & Destructor Documentation

◆ CYIDevWidget()

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

◆ ~CYIDevWidget()

virtual CYIDevWidget::~CYIDevWidget ( )

Member Function Documentation

◆ GetConfigurationButtonTitles()

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

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.

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

◆ GetIndexInPanel()

size_t CYIDevWidget::GetIndexInPanel ( ) const

Returns the index of the widget within the dev panel.

◆ GetLogicalRoot()

CYISceneNode* CYIDevWidget::GetLogicalRoot ( ) const

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

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

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

◆ IsUsingConfigurationItems()

bool CYIDevWidget::IsUsingConfigurationItems ( ) const

Returns true if this widget has configuration items.

See also

◆ 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

◆ OnConfigurationItemClicked()

virtual void CYIDevWidget::OnConfigurationItemClicked ( size_t  buttonID)

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 ( )

Called when the configuration subpanel is closing.

◆ OnConfigureButtonClicked()

virtual void CYIDevWidget::OnConfigureButtonClicked ( )

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 ( )

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)

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)

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.

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 

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)

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 ( )

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)

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)

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)

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

◆ m_pParentPanel

CYIDevPanel* CYIDevWidget::m_pParentPanel

◆ m_state

State CYIDevWidget::m_state

◆ m_subtitle

CYIString CYIDevWidget::m_subtitle

◆ m_title

CYIString CYIDevWidget::m_title

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