TurtleBrains  0.2.1
High quality, portable, C++ API for native application and game development.
Public Member Functions | Static Public Member Functions | List of all members
TurtleBrains::Application::ApplicationDialog Class Reference

Create a customized dialog prompt with simple controls. More...

#include <tb_application_dialog.h>

Inheritance diagram for TurtleBrains::Application::ApplicationDialog:
TurtleBrains::Core::Noncopyable

Public Member Functions

 ApplicationDialog (const DialogIdentifier &dialogIdentifier)
 
 ~ApplicationDialog (void)
 
const DialogIdentifier & GetIdentifier (void) const
 
void ResizeDialog (const DialogBucketType &bucketType, const int visibleSlots, const bool allowVerticalScrolling=false)
 
void AddLabelControl (const DialogControlIdentifier &controlIdentifier, const tbCore::tbString &controlName, const DialogControlGuide &guide=0)
 
void AddButtonControl (const DialogControlIdentifier &controlIdentifier, const tbCore::tbString &controlName, const DialogControlGuide &guide=0)
 
void AddCheckboxControl (const DialogControlIdentifier &controlIdentifier, const tbCore::tbString &controlName, const bool isChecked, const DialogControlGuide &guide=0)
 
void AddTextControl (const DialogControlIdentifier &controlIdentifier, const tbCore::tbString &controlValue, const DialogControlGuide &guide=0)
 
void AddDropdownControl (const DialogControlIdentifier &controlIdentifier, const std::vector< tbCore::tbString > &controlValues, const DialogControlGuide &guide=0)
 
tbCore::tbString GetValueAsString (const DialogControlIdentifier &controlIdentifier) const
 
float GetValueAsFloat (const DialogControlIdentifier &controlIdentifier) const
 
int GetValueAsInteger (const DialogControlIdentifier &controlIdentifier) const
 
void SetEnabled (const DialogControlIdentifier &controlIdentifier, const bool isEnabled)
 
void RepositionControl (const DialogControlIdentifier &controlIdentifier, const DialogControlGuide &guide, const int leftEdge=0, const int width=100, const DialogControlSlot &slot=kDefaultSlot)
 

Static Public Member Functions

static void SetControlSafeForDuplication (const DialogControlIdentifier &controlIdentifier)
 

Detailed Description

The ApplicationDialog represents a reusuable dialog object that common controls can quickly be added to and remain easy to customize without worrying about the look on each targeted system. When the user interacts with a control, the ApplicationHandlerInterface::OnDialogAction() will be invoked.

TODO: TIM: Documentation: Create an example of creating / using an ApplicaitonDialog. TODO: TIM: DocLink: Link to an example of control placement and sizing.

Constructor & Destructor Documentation

TurtleBrains::Application::ApplicationDialog::ApplicationDialog ( const DialogIdentifier &  dialogIdentifier)
explicit

When you create an ApplicationDialog object with a DialogIdentifier, you can later create another ApplicationDialog object with that same DialogIdentifier value and BOTH of those dialog objects will refer to and edit the same dialog settings.

TurtleBrains::Application::ApplicationDialog::~ApplicationDialog ( void  )

This will destruct the ApplicationDialog object, but will not destroy resources or remove the dialog settings from memory or remove the dialog if it were visible. Creating another ApplicationDialog object with the same DialogIdentifier value will give access to these settings once again. To close the dialog you should use RealtimeApplication::CloseDialog()

Note
this does not cause the dialog to be destroyed, or even cause any settings to be removed from memory, as creating another ApplicationDialog object with the same DialogIdentifier will provide access again.

Member Function Documentation

void TurtleBrains::Application::ApplicationDialog::AddButtonControl ( const DialogControlIdentifier &  controlIdentifier,
const tbCore::tbString &  controlName,
const DialogControlGuide &  guide = 0 
)

Add a button control to the dialog prompt for the user to interact with. When the button is pressed by the user, the ApplicationHandlerInterface::OnDialogAction() will be invoked with the controlIdentifier specified here, and the dialogIdentifier of the prompt it was clicked from.

Parameters
controlIdentifierThe identifier of the control which can be used to access the control, modify the control or handle interaction with the dialog control. An error will be triggered if this value is an identifier that has been set safe to duplicate.
controlNameThe text that should be displayed on the button to get the user to click.
guideThe guide which the control will be placed.aligned with. See TODO: TIM: DocLink: Link to an example of control placement and sizing.
Note
Any controls added after calling OpenDialog from the RealtimeApplication, will not change the dialog. The control will not be added until the dialog is closed and opened again.
void TurtleBrains::Application::ApplicationDialog::AddCheckboxControl ( const DialogControlIdentifier &  controlIdentifier,
const tbCore::tbString &  controlName,
const bool  isChecked,
const DialogControlGuide &  guide = 0 
)

Add a checkbox control to the dialog prompt for the user to interact with. When the checkbox is toggled by the user, the ApplicationHandlerInterface::OnDialogAction() will be invoked with the controlIdentifier specified here, and the dialogIdentifier of the prompt it was clicked from.

Parameters
controlIdentifierThe identifier of the control which can be used to access the control, modify the control or handle interaction with the dialog control. An error will be triggered if this value is an identifier that has been set safe to duplicate.
controlNameThe text that should be displayed next to the checkbox control.
isCheckedThe starting state of the checkbox, true if it should be checked and false for the checkbox to start unchecked, user interaction will toggle this state.
guideThe guide which the control will be placed.aligned with. See TODO: TIM: DocLink: Link to an example of control placement and sizing.
Note
Any controls added after calling OpenDialog from the RealtimeApplication, will not change the dialog. The control will not be added until the dialog is closed and opened again.
void TurtleBrains::Application::ApplicationDialog::AddDropdownControl ( const DialogControlIdentifier &  controlIdentifier,
const std::vector< tbCore::tbString > &  controlValues,
const DialogControlGuide &  guide = 0 
)

Add a dropdown control to the dialog prompt for the user to interact with. When the selection is changed or the dropdown closes, the ApplicationHandlerInterface::OnDialogAction() method will be invoked with the controlIdentifier specified here, and the dialogIdentifier of the prompt it was clicked from. GetValueAsInteger() is used to retieve the zero-based index of the selection, and likewise SetValueAsInteger is used to modifiy the selection, again zero-based index. GetValueAsString will return the selected option as a string.

Parameters
controlIdentifierThe identifier of the control which can be used to access the control, modify the control or handle interaction with the dialog control. An error will be triggered if this value is an identifier that has been set safe to duplicate.
controlValuesA container of strings of each option the dropdown control should contain.
guideThe guide which the control will be placed.aligned with. See TODO: TIM: DocLink: Link to an example of control placement and sizing.
Note
Any controls added after calling OpenDialog from the RealtimeApplication, will not change the dialog. The control will not be added until the dialog is closed and opened again.
void TurtleBrains::Application::ApplicationDialog::AddLabelControl ( const DialogControlIdentifier &  controlIdentifier,
const tbCore::tbString &  controlName,
const DialogControlGuide &  guide = 0 
)

Add a label control to the dialog prompt for the user to read. The user cannot interact with a label control, however it can give them valuable information about the other controls on the dialog prompt.

Parameters
controlIdentifierThe identifier of the control which can be used to access the control, modify the control or handle interaction with the dialog control.
controlNameThe text that should be displayed by the label to help or inform the user.
guideThe guide which the control will be placed.aligned with. See TODO: TIM: DocLink: Link to an example of control placement and sizing.
Note
Any controls added after calling OpenDialog from the RealtimeApplication, will not change the dialog. The control will not be added until the dialog is closed and opened again.
void TurtleBrains::Application::ApplicationDialog::AddTextControl ( const DialogControlIdentifier &  controlIdentifier,
const tbCore::tbString &  controlValue,
const DialogControlGuide &  guide = 0 
)

Add a text edit control to the dialog prompt for the user to interact with. When the text control loses focus, the user clicks away from the control, the ApplicationHandlerInterface::OnDialogAction() will be invoked with the controlIdentifier specified here, and the dialogIdentifier of the prompt it was clicked from.

Parameters
controlIdentifierThe identifier of the control which can be used to access the control, modify the control or handle interaction with the dialog control. An error will be triggered if this value is an identifier that has been set safe to duplicate.
controlValueThe text that should be used as the default input value for the text control.
guideThe guide which the control will be placed.aligned with. See TODO: TIM: DocLink: Link to an example of control placement and sizing.
Note
Any controls added after calling OpenDialog from the RealtimeApplication, will not change the dialog. The control will not be added until the dialog is closed and opened again.
const DialogIdentifier& TurtleBrains::Application::ApplicationDialog::GetIdentifier ( void  ) const

Retrieves the DialogIdentifier as specified when the object was created. Once created, the identifier cannot change for an ApplicationDialog object.

float TurtleBrains::Application::ApplicationDialog::GetValueAsFloat ( const DialogControlIdentifier &  controlIdentifier) const

For most dialog controls this will simply return a zero, 0.0f, without attempting to convert from a string. For Text Controls the return will be the string value of the control, converted into a float using TurtleBrains::Core::FromString.

Parameters
controlIdentifierThe identifier of the control that to retrieve the value as a string from, this is the same value as the control had when added to the custom dialog prompt.
int TurtleBrains::Application::ApplicationDialog::GetValueAsInteger ( const DialogControlIdentifier &  controlIdentifier) const

The value retrieved depends greatly on the type of control the identitifier represents. Label and Button controls will return zero, 0, without attempting to convert from a string. For Text Controls the return will be the string value of the control, converted into an int using TurtleBrains::Core::FromString. Checkbox Controls will return the status of the checkbox, 0 for unchecked, 1 for checked. The Dropdown Controls will return the zero-based index of the currently selected item.

Parameters
controlIdentifierThe identifier of the control that to retrieve the value as a string from, this is the same value as the control had when added to the custom dialog prompt. An error will be triggered if this controlIdentifier is set safe for duplication.
tbCore::tbString TurtleBrains::Application::ApplicationDialog::GetValueAsString ( const DialogControlIdentifier &  controlIdentifier) const

For most dialog controls this will retrieve the displayed name of the control but for Text Controls the value the user can modify is returned, and for Dropdown Controls the currently selected string value is retrieved.

Parameters
controlIdentifierThe identifier of the control that to retrieve the value as a string from, this is the same value as the control had when added to the custom dialog prompt.
void TurtleBrains::Application::ApplicationDialog::RepositionControl ( const DialogControlIdentifier &  controlIdentifier,
const DialogControlGuide &  guide,
const int  leftEdge = 0,
const int  width = 100,
const DialogControlSlot &  slot = kDefaultSlot 
)

For dialog prompts that need any more than the very basic level of placement, controls can be moved and resized for customized prompts. This is a multipurpose function that both repositions and resizes the control. For more sizing and positioning information see TODO: TIM: DocLink: Link to an example of control placement and sizing.

Parameters
controlIdentifierThe identifier of the control that to retrieve the value as a string from, this is the same value as the control had when added to the custom dialog prompt. An error will be triggered if this controlIdentifier is set safe for duplication.
guideThe guide which the control will be placed.aligned with once repositioned.
leftEdgeAn offset value for the positioning of the left edge of the control relative to the choosen guide. The value is based on a percentage of the width of the standard control, so a value of 30 would move the left edge of the control, 30% of the standard control width to the right of the guide.
widthThe new desired with of control represented as a percentage based on the width of the standard control. The default value of 100 keeps the control width unchanged from when first added to the dialog prompt. A value of 50 would be half as wide as the standard control width.
slotThe slot to place the control into. A value of kDefaultSlot, which is the default value, will keep the slot unchanged keeping the control at the same vertical position.
Note
Any controls modified after calling OpenDialog from the RealtimeApplication, will not change the dialog prompt. The control will not be modified until the dialog is closed and opened again.
void TurtleBrains::Application::ApplicationDialog::ResizeDialog ( const DialogBucketType &  bucketType,
const int  visibleSlots,
const bool  allowVerticalScrolling = false 
)

By default a custom ApplicationDialog will contain a single column of five (5) slots for controls to be added. Resizing the dialog by changing the bucket type and number of visible slots will create a dialog that fits your project and needs better.

Parameters
bucketTypeThe bucketType of the dialog prompt effects the width of the prompt and how many controls can fit side by side. This also effect the number, and values, of the guides used to position the dialog controls horizontally.
visibleSlotsChoose how many controls can be visible vertically before (if any) scrolling is required for lower controls to be seen. This effects the height of the prompt.
allowVerticalScrollingAllow controls to be added in slots greater than the number of visible slots. If this value is false, an error will be triggered when a control is added, or repositioned, to a slot that is not visible without scroll bars.
See also
DialogBucketType, DialogControlSlot
Note
Vertical scrolling is currently only implemented on Windows and not working on other platforms, for maximum portability do not allow scrolling, and do not reposition controls to slots greater than the number of visible slots requested here.

TODO: TIM: DocLink: Link to an example of control placement and sizing.

static void TurtleBrains::Application::ApplicationDialog::SetControlSafeForDuplication ( const DialogControlIdentifier &  controlIdentifier)
static

Sometimes you don't care to modify or retrieve information from a dialog control, mainly labels. Since each control must have an identifier value attached to it, this allows you to create an identifier that is safe for duplicating. Once an identifier is made safe for duplication it can not be made unsafe and access to any controls with the identifier will be lost. Calling GetValue / SetEnabled / Reposition or any accessor/modifier functions for an identifier safe for duplication will trigger errors.

Parameters
controlIdentifierThe identifier value that is safe for duplication, no controls created with this identifier can be modified or accessed beyond creation.
Note
Once an identifier is set safe for duplication, the value can not be used to access or modifiy any controls with that identifier, and the value cannot be later removed from safe for duplication.
void TurtleBrains::Application::ApplicationDialog::SetEnabled ( const DialogControlIdentifier &  controlIdentifier,
const bool  isEnabled 
)

Modifies the control specified by controlIdentifier so that the user can interact with the enabled control, disable the control so the user can see the control but not interact with it. Typically the control will be displayed greyed out to indicated it is disabled.

Parameters
controlIdentifierThe identifier of the control that to retrieve the value as a string from, this is the same value as the control had when added to the custom dialog prompt. An error will be triggered if this controlIdentifier is set safe for duplication.
isEnabledTrue to enable the control and allow the user to interact, or false to disable interaction and display the control greyed out to indicated a disabled control.
Note
Any controls modified after calling OpenDialog from the RealtimeApplication, will not change the dialog prompt. The control will not be modified until the dialog is closed and opened again.