GeDialog Class Reference

#include <c4d_gui.h>

Inheritance diagram for GeDialog:

Detailed Description

Used to display GUI dialogs. Derive this class, overriding the necessary functions, and then call Open() to display it.

Public Member Functions
Bool	SetColorField (const GadgetPtr &id, const TriState< Vector > &tri, Float brightness, Float maxbrightness, Int32 flags)
Bool	GetFolding (void)
void	SetFolding (Bool allowClose)
Int32	IsDockedOrTabbed ()

Protected Attributes
Bool	createlayout

Private Member Functions
	MAXON_DISALLOW_COPY_AND_ASSIGN (GeDialog)

Private Attributes
CDialog *	cd
Int32	t_lastcoremsg
Bool	_folding

Friends
class	GeUserArea
class	_GeListView

Constructor/Destructor
	GeDialog (void)
virtual	~GeDialog (void)

Internal Representation
CDialog *	Get ()

Override
virtual Bool	CreateLayout (void)
virtual Bool	InitValues (void)
virtual Bool	CoreMessage (Int32 id, const BaseContainer &msg)
virtual Bool	Command (Int32 id, const BaseContainer &msg)
virtual Bool	AskClose (void)
virtual void	Timer (const BaseContainer &msg)
virtual void	DestroyWindow (void)
virtual Int32	Message (const BaseContainer &msg, BaseContainer &result)

Open/Close
Bool	Open (DLG_TYPE dlgtype, Int32 pluginid, Int32 xpos=-1, Int32 ypos=-1, Int32 defaultw=0, Int32 defaulth=0, Int32 subid=0, OPENDIALOGFLAGS flags=OPENDIALOGFLAGS::NONE)
Bool	Close (void)
Bool	Close (Bool dummy)

Basic Functions
GeData	SendMessage (const GadgetPtr &id, const BaseContainer &msg)
Bool	SendParentMessage (const BaseContainer &msg, Bool receiveSelf=false)
Int32	GetId (void)
Bool	IsOpen ()
Bool	IsVisible ()
Bool	IsMinimized () const
void	SetTimer (Int32 timer)
void	SetTitle (const maxon::String &title)
maxon::String	GetTitle ()
Bool	Enable (const GadgetPtr &id, Bool enabled)
Bool	IsEnabled (const GadgetPtr &id)

Input
Bool	GetInputState (Int32 askdevice, Int32 askchannel, BaseContainer &res)
Bool	GetInputEvent (Int32 askdevice, BaseContainer &res)
void	KillEvents (void)

Plain Set
Bool	SetBool (const GadgetPtr &id, Int32 value, Int32 tristate=0)
Bool	SetInt32 (const GadgetPtr &id, Int32 value, Int32 min=LIMIT< Int32 >::MIN, Int32 max=LIMIT< Int32 >::MAX, Int32 step=1, Int32 tristate=0, Int32 min2=LIMIT< Int32 >::MIN, Int32 max2=LIMIT< Int32 >::MAX)
Bool	SetFloat (const GadgetPtr &id, Float value, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0, Int32 format=FORMAT_FLOAT, Float min2=0.0, Float max2=0.0, Bool quadscale=false, Int32 tristate=0)
Bool	SetMeter (const GadgetPtr &id, Float value, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0, Int32 tristate=0)
Bool	SetDegree (const GadgetPtr &id, Float radians_value, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0, Int32 tristate=0)
Bool	SetPercent (const GadgetPtr &id, Float value, Float min=0.0, Float max=100.0, Float step=1.0, Int32 tristate=0)
Bool	SetTime (const GadgetPtr &id, const BaseDocument *doc, const BaseTime &value, const BaseTime &min=BaseTime(- 108000, 1), const BaseTime &max=BaseTime(108000, 1), Int32 stepframes=1, Int32 tristate=0)
Bool	SetString (const GadgetPtr &id, const maxon::String &text, Int32 tristate=0, Int32 flags=0)
Bool	SetColorField (const GadgetPtr &id, const Vector &color, Float brightness, Float maxbrightness, Int32 flags)
Bool	SetFilename (const GadgetPtr &id, const Filename &fn, Int32 tristate=0)

Plain Get
Bool	GetBool (const GadgetPtr &id, Bool &value) const
Bool	GetInt32 (const GadgetPtr &id, Int32 &value) const
Bool	GetFloat (const GadgetPtr &id, Float &value) const
Bool	GetVector (const GadgetPtr &id_x, const GadgetPtr &id_y, const GadgetPtr &id_z, Vector &value) const
Bool	GetString (const GadgetPtr &id, maxon::String &text) const
Bool	GetColorField (const GadgetPtr &id, Vector &color, Float &brightness) const
Bool	GetTime (const GadgetPtr &id, const BaseDocument *doc, BaseTime &time) const
Bool	GetFilename (const GadgetPtr &id, Filename &fn) const
Bool	CheckTristateChange (const GadgetPtr &id)

Container Set
Bool	SetBool (const GadgetPtr &id, const BaseContainer *bc, Int32 bcid)
Bool	SetInt32 (const GadgetPtr &id, const BaseContainer *bc, Int32 bcid, Int32 min=LIMIT< Int32 >::MIN, Int32 max=LIMIT< Int32 >::MAX, Int32 step=1, Int32 min2=LIMIT< Int32 >::MIN, Int32 max2=LIMIT< Int32 >::MAX)
Bool	SetFloat (const GadgetPtr &id, const BaseContainer *bc, Int32 bcid, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0, Int32 format=FORMAT_FLOAT, Float min2=0.0, Float max2=0.0, Bool quadscale=false)
Bool	SetMeter (const GadgetPtr &id, const BaseContainer *bc, Int32 bcid, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0)
Bool	SetDegree (const GadgetPtr &id, const BaseContainer *bc, Int32 bcid, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0)
Bool	SetPercent (const GadgetPtr &id, const BaseContainer *bc, Int32 bcid, Float min=0.0, Float max=100.0, Float step=1.0)
Bool	SetTime (const GadgetPtr &id, const BaseDocument *doc, const BaseContainer *bc, Int32 bcid, const BaseTime &min=BaseTime(- 108000, 1), const BaseTime &max=BaseTime(108000, 1), Int32 stepframes=1)
Bool	SetString (const GadgetPtr &id, const BaseContainer *bc, Int32 bcid, Int32 flags=0)
Bool	SetFilename (const GadgetPtr &id, const BaseContainer *bc, Int32 bcid)
Bool	SetColorField (const GadgetPtr &id, const BaseContainer *bc, Int32 bc_colid, Int32 bc_brightnessid, Float maxbrightness, Int32 flags)

Container Get
Bool	GetBool (const GadgetPtr &id, BaseContainer *bc, Int32 bcid) const
Bool	GetInt32 (const GadgetPtr &id, BaseContainer *bc, Int32 bcid) const
Bool	GetFloat (const GadgetPtr &id, BaseContainer *bc, Int32 bcid) const
Bool	GetTime (const GadgetPtr &id, const BaseDocument *doc, BaseContainer *bc, Int32 bcid) const
Bool	GetVector (const GadgetPtr &id_x, const GadgetPtr &id_y, const GadgetPtr &id_z, BaseContainer *bc, Int32 bcid) const
Bool	GetString (const GadgetPtr &id, BaseContainer *bc, Int32 bcid) const
Bool	GetFilename (const GadgetPtr &id, BaseContainer *bc, Int32 bcid) const
Bool	GetColorField (const GadgetPtr &id, BaseContainer *bc, Int32 bc_colid, Int32 bc_brightnessid) const

TriState Set
Bool	SetBool (const GadgetPtr &id, const TriState< Bool > &tri)
Bool	SetInt32 (const GadgetPtr &id, const TriState< Int32 > &tri, Int32 min=LIMIT< Int32 >::MIN, Int32 max=LIMIT< Int32 >::MAX, Int32 step=1, Int32 min2=LIMIT< Int32 >::MIN, Int32 max2=LIMIT< Int32 >::MAX)
Bool	SetFloat (const GadgetPtr &id, const TriState< Float > &tri, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0, Int32 format=FORMAT_FLOAT, Float min2=0.0, Float max2=0.0, Bool quadscale=false)
Bool	SetMeter (const GadgetPtr &id, const TriState< Float > &tri, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0)
Bool	SetDegree (const GadgetPtr &id, const TriState< Float > &tri, Float min=(-1.0e18), Float max=(1.0e18), Float step=1.0)
Bool	SetPercent (const GadgetPtr &id, const TriState< Float > &tri, Float min=0.0, Float max=100.0, Float step=1.0)
Bool	SetTime (const GadgetPtr &id, const BaseDocument *doc, const TriState< BaseTime > &tri, const BaseTime &min=BaseTime(- 108000, 1), const BaseTime &max=BaseTime(108000, 1), Int32 stepframes=1)
Bool	SetString (const GadgetPtr &id, const TriState< String > &tri, Int32 flags=0)

Coordinates Transformation
Bool	Local2Global (Int32 *x, Int32 *y)
Bool	Global2Local (Int32 *x, Int32 *y)
Bool	Screen2Local (Int32 *x, Int32 *y)
Bool	Local2Screen (Int32 *x, Int32 *y)

Color
Bool	GetColorRGB (Int32 colorid, Int32 &r, Int32 &g, Int32 &b)
void	SetDefaultColor (const GadgetPtr &id, Int32 colorid, Int32 mapid)
void	SetDefaultColor (const GadgetPtr &id, Int32 colorid, const Vector &color)

Layout
Bool	LoadDialogResource (Int32 id, GeResource *lr, Int32 flags)
C4DGadget *	AddCheckbox (Int32 id, Int32 flags, Int32 initw, Int32 inith, const maxon::String &name)
C4DGadget *	AddButton (Int32 id, Int32 flags, Int32 initw, Int32 inith, const maxon::String &name)
C4DGadget *	AddStaticText (Int32 id, Int32 flags, Int32 initw, Int32 inith, const maxon::String &name, Int32 borderstyle)
C4DGadget *	AddArrowButton (Int32 id, Int32 flags, Int32 initw, Int32 inith, Int32 arrowtype)
C4DGadget *	AddEditText (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0, Int32 editflags=0)
C4DGadget *	AddMultiLineEditText (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0, Int32 style=0)
C4DGadget *	AddEditNumber (Int32 id, Int32 flags, Int32 initw=80, Int32 inith=0)
C4DGadget *	AddEditNumberArrows (Int32 id, Int32 flags, Int32 initw=70, Int32 inith=0)
C4DGadget *	AddEditSlider (Int32 id, Int32 flags, Int32 initw=80, Int32 inith=0)
C4DGadget *	AddSlider (Int32 id, Int32 flags, Int32 initw=90, Int32 inith=0)
C4DGadget *	AddColorField (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0, Int32 colorflags=0)
C4DGadget *	AddColorChooser (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0, Int32 layoutflags=0, const BaseContainer &settings=BaseContainer())
C4DGadget *	AddRadioButton (Int32 id, Int32 flags, Int32 initw, Int32 inith, const maxon::String &name)
C4DGadget *	AddRadioText (Int32 id, Int32 flags, Int32 initw, Int32 inith, const maxon::String &name)
C4DGadget *	AddEditShortcut (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0, Int32 shortcutflags=0)
C4DGadget *	AddSeparatorH (Int32 initw, Int32 flags=BFH_FIT)
C4DGadget *	AddSeparatorV (Int32 inith, Int32 flags=BFV_FIT)
Bool	AddRadioGroup (Int32 id, Int32 flags, Int32 columns=1, Int32 rows=0)
C4DGadget *	AddComboBox (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0, Bool specialalign=false, Bool allowFiltering=false)
C4DGadget *	AddComboButton (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0, Bool specialalign=false, Bool allowFiltering=false)
C4DGadget *	AddPopupButton (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0, Bool allowFiltering=false)
Bool	AddListView (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0)
Bool	LayoutChanged (const GadgetPtr &id)
Bool	LayoutChangedNoRedraw (const GadgetPtr &id)
Bool	Activate (const GadgetPtr &id)
Bool	IsActive (const GadgetPtr &id)
UpdateDialogHelper	BeginLayoutChange (const GadgetPtr &gadget, Bool disableRedraws, Bool doNotFlush=false)
Bool	LayoutFlushGroup (const GadgetPtr &id)
Bool	LayoutFlushDisableRedraw (const GadgetPtr &id, Bool disable)
Bool	RemoveElement (const GadgetPtr &id)
Bool	HideElement (const GadgetPtr &id, Bool hide)
Bool	RestoreLayout (Int32 pluginid, Int32 subid, void *secret)

Layout Helpers
Bool	AddChild (const GadgetPtr &id, Int32 subid, const maxon::String &child)
Bool	FreeChildren (const GadgetPtr &id)
Bool	SetPopup (const GadgetPtr &id, const BaseContainer &bc)
Bool	AddChildren (const GadgetPtr &id, const BaseContainer &bc)
C4DGadget *	AddUserArea (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0)
Bool	AttachUserArea (GeUserArea &ua, const GadgetPtr &id, USERAREAFLAGS userareaflags=USERAREAFLAGS::COREMESSAGE)
Bool	AddSubDialog (Int32 id, Int32 flags, Int32 initw=0, Int32 inith=0)
Bool	AttachSubDialog (SubDialog *userdlg, Int32 id)
Bool	AddDlgGroup (Int32 type)

Group
Bool	GroupBeginInMenuLine ()
Bool	TabGroupBegin (Int32 id, Int32 flags, Int32 tabtype=TAB_TABS)
Bool	GroupBegin (Int32 id, Int32 flags, Int32 cols, Int32 rows, const maxon::String &title, Int32 groupflags, Int32 initw=0, Int32 inith=0)
Bool	GroupEnd (void)
Bool	GroupSpace (Int32 spacex, Int32 spacey)
Bool	GroupBorder (UInt32 borderstyle)
Bool	GroupBorderNoTitle (UInt32 borderstyle)
Bool	GroupBorderSpace (Int32 left, Int32 top, Int32 right, Int32 bottom)
Bool	GroupWeightsSave (const GadgetPtr &id, BaseContainer &weights)
Bool	GroupWeightsLoad (const GadgetPtr &id, const BaseContainer &weights)

Drag and Drop
Bool	GetItemDim (const GadgetPtr &id, Int32 *x, Int32 *y, Int32 *w, Int32 *h) const
Bool	GetDragPosition (const BaseContainer &msg, Int32 *x, Int32 *y)
Bool	GetDragObject (const BaseContainer &msg, Int32 *type, void **object)
Bool	SetDragDestination (Int32 cursor, Int32 gadgetid=0)
Bool	CheckDropArea (const GadgetPtr &id, const BaseContainer &msg, Bool horiz, Bool vert)

Scroll Group
Bool	GetVisibleArea (Int32 scrollgroupid, Int32 *x1, Int32 *y1, Int32 *x2, Int32 *y2)
Bool	SetVisibleArea (Int32 scrollgroupid, Int32 x1, Int32 y1, Int32 x2, Int32 y2)
Bool	ScrollGroupBegin (Int32 id, Int32 flags, Int32 scrollflags, Int32 initw=0, Int32 inith=0)

Menu
Bool	MenuFlushAll (void)
Bool	MenuSubBegin (const maxon::String &string)
Bool	MenuSubEnd (void)
Bool	MenuAddCommand (Int32 cmdid)
Bool	MenuAddString (Int32 id, const maxon::String &string)
Bool	MenuAddSeparator (const maxon::String &title=maxon::String())
Bool	MenuFinished (void)
Bool	MenuInitString (Int32 id, Bool enabled, Bool checked)
Bool	MenuSetResource (Int32 id)

Custom GUI
void *	FindCustomGui (Int32 id, Int32 pluginid)
template<typename T >
T *	FindCustomGui (Int32 id)
void *	AddCustomGui (Int32 id, Int32 pluginid, const maxon::String &name, Int32 flags, Int32 minw, Int32 minh, const BaseContainer &customdata)
template<typename T >
T *	AddCustomGui (Int32 id, const maxon::String &name, Int32 flags, Int32 minw, Int32 minh, const BaseContainer &customdata)

Multi-line Edit
Bool	SetMultiLineMode (const GadgetPtr &id, SCRIPTMODE mode)
Bool	SetMultiLineLock (const GadgetPtr &id, Bool lock)
Bool	SetMultiLinePos (const GadgetPtr &id, Int32 line, Int32 pos)

Miscellaneous
Bool	CheckClose (void)
Bool	CheckValueRanges (void)
Float	GetPixelRatio () const
Bool	ReleaseLink ()
Bool	CheckCoreMessage (const BaseContainer &msg, Int32 *ownlastcoremsg=nullptr)
void *	GetWindowHandle ()
void *	GetWindowInterface ()
static void	HandleHelpString (const BaseContainer &msg, BaseContainer &result, const maxon::String &sym)
static void *	GetGuiInterface ()

Constructor & Destructor Documentation

GeDialog()

GeDialog

(

void

)

Creates the dialog, but does not open it.

~GeDialog()

virtual ~GeDialog ( void  )

virtual

Destroys the dialog. If the dialog is still open, it is closed.

Member Function Documentation

MAXON_DISALLOW_COPY_AND_ASSIGN()

MAXON_DISALLOW_COPY_AND_ASSIGN ( GeDialog  )

private

Get()

CDialog* Get

(

void

)

Retrieves a pointer to the internal dialog pointer.

Returns

The internal dialog.

CreateLayout()

virtual Bool CreateLayout ( void  )

virtual

Called when the dialog is about to be displayed. Override this method to define the layout of the dialog.
Either use the recommended LoadDialogResource function or the manual functions (for example AddButton()). See Dialog Layout for more information.

Returns

true if successful, otherwise false.

Reimplemented in ProgressDialog.

InitValues()

virtual Bool InitValues ( void  )

virtual

Called when the dialog is initialized by the GUI. Override this method to initialize local variables and the gadgets used.

See also

The article GUI Messages for more information.

Returns

true if successful, otherwise false.

Reimplemented in ProgressDialog.

CoreMessage()

virtual Bool CoreMessage ( Int32  id, const BaseContainer &  msg  )

virtual

Override this method to react to Cinema 4D core messages.

See also

The article Core Messages for more information.

Parameters

[in]	id	The message ID: EVMSG
[in]	msg	The message container.

Returns

Currently not used.

Command()

virtual Bool Command ( Int32  id, const BaseContainer &  msg  )

virtual

Whenever the user clicks on a gadget and/or changes its value this function will be called. It is also called when a string menu item is selected. Override this methods to handle such events.

Note

Remember StopAllThreads() must be called before making modifications to the scene.

Parameters

[in]	id	The ID of the gadget that triggered the event.
[in]	msg	The message container. Contains the following values: BFM_ACTION_ID and BFM_ACTION_VALUE.

Returns

true if successful, otherwise false.

Reimplemented in ProgressDialog.

AskClose()

virtual Bool AskClose ( void  )

virtual

If the user wants to close the dialog with the OK button this function will be called. Override it to avoid closing the dialog if an error situation has occurred.
If false is returned everything will be as usual, but if true is returned the dialog will not close. This function is especially useful in combination with the GeModalDialog class for handling wrong user input before leaving the dialog.

Warning

A buggy function, always returning true, will lead to a frustrating user experience.

Returns

true if the dialog should not be closed, false if it should.

Reimplemented in ProgressDialog.

Timer()

virtual void Timer ( const BaseContainer &  msg )

virtual

Called when a timer event is received.
To subscribe to timer events use SetTimer().

Parameters

[in]

msg

The timer message container.

Reimplemented in ProgressDialog.

DestroyWindow()

virtual void DestroyWindow ( void  )

virtual

Called when the dialog is about to be closed temporarily, for example for layout switching.
All pointers to C4DGadget, GeUserArea and SubDialog objects as well as custom GUI objects are invalidated. So set all such stored pointers to nullptr.
CreateLayout will be called when the dialog is restored.

Message()

virtual Int32 Message ( const BaseContainer &  msg, BaseContainer &  result  )

virtual

Called when a message is received.
Override this function to react to more messages than covered by the other virtual functions. Normally this is not necessary.

Note

If overriden, be sure to include a call to the base version of this function, GeDialog::Message().

See also

The article GUI Messages for more information.

Parameters

[in]	msg	The message container.
[in]	result	A container to place results in.

Returns

Depends on the message.

Reimplemented in ProgressDialog, iCustomGui, SubDialog, and GeModalDialog.

Open()

Bool Open	(	DLG_TYPE	dlgtype,
		Int32	pluginid,
		Int32	xpos = -1,
		Int32	ypos = -1,
		Int32	defaultw = 0,
		Int32	defaulth = 0,
		Int32	subid = 0,
		OPENDIALOGFLAGS	flags = OPENDIALOGFLAGS::NONE
	)

Opens the dialog at the specified position.

Note

If xpos=-1 and ypos=-1 the dialog will be opened at the current mouse position.
If xpos=-2 and ypos=-2 the dialog will be opened at the center of the screen.

Make sure to pass the ID for asynchronous plugins so that Cinema 4D can correctly restore dialogs added by the user to the user interface.

Parameters

[in]	dlgtype	The dialog type: DLG_TYPE
[in]	pluginid	The plugin ID of the CommandData with the dialog's CommandData::RestoreLayout().
[in]	xpos	The X position of the dialog. See note above.
[in]	ypos	The Y position of the dialog. See note above.
[in]	defaultw	The default width of the dialog in pixels.
[in]	defaulth	The default height of the dialog in pixels.
[in]	subid	The dialog sub-ID. This can be used to open several dialogs with a single command plugin for CommandData::ExecuteSubID().
[in]	flags	See OPENDIALOGFLAGS

Returns

true if successful, otherwise false.

Close() [1/2]

Bool Close

(

void

)

Closes the dialog. Not necessary when using modal dialogs.

Returns

true if the dialog was closed, otherwise false.

Close() [2/2]

Bool Close

(

Bool

dummy

)

Always calls Close(void).

Parameters

[in]

dummy

A dummy boolean state.

SendMessage()

GeData SendMessage	(	const GadgetPtr &	id,
		const BaseContainer &	msg
	)

Sends a message to a dialog element by ID.

See also

The article GUI Messages for more information.

Parameters

[in]	id	The dialog element ID.
[in]	msg	The message container.

Returns

Depends on the message sent.

SendParentMessage()

Bool SendParentMessage	(	const BaseContainer &	msg,
		Bool	receiveSelf = false
	)

Sends a message to the parent dialog.

See also

The article GUI Messages for more information.

Parameters

[in]	msg	The message container.
[in]	receiveSelf	True if the own parent message should process this message. Default is false.

Returns

true if the message was sent, otherwise false.

GetId()

Int32 GetId

(

void

)

Gets the dialog ID.

Returns

The dialog ID.

IsOpen()

Bool IsOpen

(

)

Checks if the dialog is open.

Returns

true if the dialog is open, otherwise false.

IsVisible()

Bool IsVisible

(

)

Checks if the dialog is visible.

Returns

true if the dialog is visible, otherwise false.

IsMinimized()

Bool IsMinimized

(

)

const

Checks if the dialog is minimized (in the dock or task bar).

Returns

true if the dialog is minimized, otherwise false.

SetTimer()

void SetTimer

(

Int32

timer

)

Initializes the timer clock, so that Timer() is called every timer milliseconds. Use SetTimer(0) to stop the timer.

Note

Depending on the speed of the computer, the operating system, the complexity of the dialog and the threads running in the background, there is no guarantee that event messages will occur on a regular basis.
Using a value of 500 ms should be no problem but using a value of 1 ms one might get events with the following time spaces: 3 ms, 76 ms, 15 ms, 19 ms, 67 ms etc.

Warning

Keep in mind that using small timer values results in heavy message traffic in the application which may slow down Cinema 4D (and all other applications running on the computer) to a point where nothing is working any longer besides the dialog.

Parameters

[in]

timer

The timer interval in milliseconds. Pass 0 to stop the timer.

SetTitle()

void SetTitle

(

const maxon::String &

title

)

Sets the title of the dialog window.

Parameters

[in]

title

The title.

GetTitle()

maxon::String GetTitle

(

)

Gets the title of the dialog window.

Returns

The title

Enable()

Bool Enable	(	const GadgetPtr &	id,
		Bool	enabled
	)

Enables or disables the dialog item with the specified id.

Parameters

[in]	id	The control ID.
[in]	enabled	true to enable and false to disable.

Returns

true if successful, otherwise false.

IsEnabled()

Bool IsEnabled

(

const GadgetPtr &

id

)

Checks if a dialog item is enabled.

Parameters

[in]

id

The control ID.

Returns

true if the dialog item is enabled, otherwise false.

GetInputState()

Bool GetInputState	(	Int32	askdevice,
		Int32	askchannel,
		BaseContainer &	res
	)

Polls a certain channel of a device for the current input state.
If the return value is true, the container stored in res is like an input event message, otherwise no state was available.
For a list of valid devices and channels, see Input Events.

Parameters

[in]	askdevice	The device to ask.
[in]	askchannel	The channel of the device.
[out]	res	The result container.

Returns

true if an input state could be retrieved, otherwise false.

GetInputEvent()

Bool GetInputEvent	(	Int32	askdevice,
		BaseContainer &	res
	)

Gets the next input event for a certain device from the event queue.
If the return value is true, the container stored in res is like an input event message, otherwise no state was available.
For a list of valid devices and channels, see Input Events.

Parameters

[in]	askdevice	The device to poll.
[out]	res	The result container.

Returns

true if an input event could be retrieved, otherwise false.

KillEvents()

void KillEvents

(

void

)

Flushes all events from the window message queue.
For example if looping while the mouse is down (polling), call this function to flush all key downs/mouse clicks that are made during the loop.

SetBool() [1/3]

Bool SetBool	(	const GadgetPtr &	id,
		Int32	value,
		Int32	tristate = 0
	)

Sets the value of checkbox controls.

Parameters

[in]	id	The control ID.
[in]	value	The new value. Checked is true and unchecked is false. If tristate is true then value must be 2.
[in]	tristate	If true, and value is 2, the control is tinted to indicate tristate mode.

Returns

true if the value was set, otherwise false.

SetInt32() [1/3]

Bool SetInt32	(	const GadgetPtr &	id,
		Int32	value,
		Int32	min = LIMIT< Int32 >::MIN,
		Int32	max = LIMIT< Int32 >::MAX,
		Int32	step = 1,
		Int32	tristate = 0,
		Int32	min2 = LIMIT< Int32 >::MIN,
		Int32	max2 = LIMIT< Int32 >::MAX
	)

Sets the value and limits of integer fields. Also used for tab groups, radio buttons and combo boxes.

Parameters

[in]	id	The control ID.
[in]	value	The new value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.
[in]	tristate	If true the control is tinted to indicate tristate mode.
[in]	min2	The minimum value allowed outside the visual range used for sliders. Overrides min for the acceptance check.
[in]	max2	The maximum value allowed outside the visual range used for sliders. Overrides max for the acceptance check.

Returns

true if the value was set, otherwise false.

SetFloat() [1/3]

Bool SetFloat	(	const GadgetPtr &	id,
		Float	value,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0,
		Int32	format = FORMAT_FLOAT,
		Float	min2 = 0.0,
		Float	max2 = 0.0,
		Bool	quadscale = false,
		Int32	tristate = 0
	)

Sets the value, unit and limits of float fields.

Parameters

[in]	id	The control ID.
[in]	value	The new value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.
[in]	format	The unit and format of the field: FORMAT_NUMBERS
[in]	min2	The minimum value allowed outside the visual range used for sliders. Overrides min for the acceptance check.
[in]	max2	The maximum value allowed outside the visual range used for sliders. Overrides max for the acceptance check.
[in]	quadscale	If true a quadratic scale is used for the slider, so that more precision is available for lower values.
[in]	tristate	If true the control is tinted to indicate tristate mode.

Returns

true if the value was set, otherwise false.

SetMeter() [1/3]

Bool SetMeter	(	const GadgetPtr &	id,
		Float	value,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0,
		Int32	tristate = 0
	)

Sets the value and limits of a meter field. Same as SetFloat with FORMAT_METER.

Parameters

[in]	id	The control ID.
[in]	value	The new value.
[in]	min	The minimum value accepted.
[in]	max	The maximum value accepted.
[in]	step	The step used for arrow buttons.
[in]	tristate	If true the control is tinted to indicate tristate mode.

Returns

true if the value was set, otherwise false.

SetDegree() [1/3]

Bool SetDegree	(	const GadgetPtr &	id,
		Float	radians_value,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0,
		Int32	tristate = 0
	)

Sets the value and limits of an angle field. Same as SetFloat with FORMAT_DEGREE.

Parameters

[in]	id	The control ID.
[in]	radians_value	The new angle in radians.
[in]	min	The minimum angle accepted in degrees.
[in]	max	The maximum angle accepted in degrees.
[in]	step	The step used for arrow buttons in degrees.
[in]	tristate	If true the control is tinted to indicate tristate mode.

Returns

true if the value was set, otherwise false.

SetPercent() [1/3]

Bool SetPercent	(	const GadgetPtr &	id,
		Float	value,
		Float	min = 0.0,
		Float	max = 100.0,
		Float	step = 1.0,
		Int32	tristate = 0
	)

Sets the value and limits of a percent field. Same as SetFloat with FORMAT_PERCENT.

Parameters

[in]	id	The control ID.
[in]	value	The new value (real fraction).
[in]	min	The minimum value accepted (percentage units).
[in]	max	The maximum value accepted (percentage units).
[in]	step	The step used for arrow buttons (percentage units).
[in]	tristate	If true the control is tinted to indicate tristate mode.

Returns

true if the value was set, otherwise false.

SetTime() [1/3]

Bool SetTime	(	const GadgetPtr &	id,
		const BaseDocument *	doc,
		const BaseTime &	value,
		const BaseTime &	min = BaseTime(- 108000, 1),
		const BaseTime &	max = BaseTime(108000, 1),
		Int32	stepframes = 1,
		Int32	tristate = 0
	)

Sets the value and limits of a time field. Same as SetFloat with FORMAT_FRAMES.

Parameters

[in]	id	The control ID.
[in]	doc	The document to be used for framerate calculations.
[in]	value	The new time value.
[in]	min	The minimum time accepted.
[in]	max	The maximum time accepted.
[in]	stepframes	The frame step used for arrow buttons.
[in]	tristate	If true the control is tinted to indicate tristate mode.

Returns

true if the value was set, otherwise false.

SetString() [1/3]

Bool SetString	(	const GadgetPtr &	id,
		const maxon::String &	text,
		Int32	tristate = 0,
		Int32	flags = 0
	)

Sets the text of string controls. Used for all controls that have a text, for example static text fields, edit fields, buttons and check boxes.

Parameters

[in]	id	The control ID.
[in]	text	The new text.
[in]	tristate	If true the control is tinted to indicate tristate mode.
[in]	flags	Flags: EDITTEXT FLAG_CENTER_ALIGN

Returns

true if the text was set, otherwise false.

SetColorField() [1/2]

Bool SetColorField	(	const GadgetPtr &	id,
		const Vector &	color,
		Float	brightness,
		Float	maxbrightness,
		Int32	flags
	)

Sets the color, brightness and limits of color fields and color choosers.

Warning

flags does not apply to color fields, only to color choosers.

Parameters

[in]	id	The control ID.
[in]	color	The new color value.
[in]	brightness	The new brightness value.
[in]	maxbrightness	The maximum brightness allowed.
[in]	flags	Controls what parts of a color chooser are available: DR_COLORFIELD

Returns

true if the color field values were set, otherwise false.

SetFilename() [1/2]

Bool SetFilename	(	const GadgetPtr &	id,
		const Filename &	fn,
		Int32	tristate = 0
	)

Sets the text of string controls, taking the new value from a filename.

Parameters

[in]	id	The control ID.
[in]	fn	The new filename.
[in]	tristate	If true the control is tinted to indicate tristate mode.

Returns

true if the filename was set, otherwise false.

GetBool() [1/2]

Bool GetBool	(	const GadgetPtr &	id,
		Bool &	value
	)		const

Retrieves the state of checkbox controls.

Parameters

[in]	id	The control ID.
[out]	value	Assigned the current state.

Returns

true if the state was retrieved, otherwise false.

GetInt32() [1/2]

Bool GetInt32	(	const GadgetPtr &	id,
		Int32 &	value
	)		const

Retrieves the value of integer fields. Also used for tab groups, radio buttons and combo boxes.

Parameters

[in]	id	The control ID.
[out]	value	Assigned the current value.

Returns

true if the value was retrieved, otherwise false.

GetFloat() [1/2]

Bool GetFloat	(	const GadgetPtr &	id,
		Float &	value
	)		const

Retrieves the value of float fields.

Parameters

[in]	id	The control ID.
[out]	value	Assigned the current value.

Returns

true if the value was retrieved, otherwise false.

GetVector() [1/2]

Bool GetVector	(	const GadgetPtr &	id_x,
		const GadgetPtr &	id_y,
		const GadgetPtr &	id_z,
		Vector &	value
	)		const

Retrieves the value of three float fields at the same time as a vector.

Parameters

[in]	id_x	The control ID of the X field.
[in]	id_y	The control ID of the Y field.
[in]	id_z	The control ID of the Z field.
[out]	value	Assigned the current value.

Returns

true if the value was retrieved, otherwise false.

GetString() [1/2]

Bool GetString	(	const GadgetPtr &	id,
		maxon::String &	text
	)		const

Retrieves the text from string controls. Used for all controls that have a text, for example static text fields, edit fields, buttons and check boxes.

Parameters

[in]	id	The control ID.
[out]	text	Assigned the current text.

Returns

true if the text was retrieved, otherwise false.

GetColorField() [1/2]

Bool GetColorField	(	const GadgetPtr &	id,
		Vector &	color,
		Float &	brightness
	)		const

Retrieves the color and brightness of color controls.

Parameters

[in]	id	The control ID.
[out]	color	Assigned the current color.
[out]	brightness	Assigned the current brightness.

Returns

true if the color field values were retrieved, otherwise false.

GetTime() [1/2]

Bool GetTime	(	const GadgetPtr &	id,
		const BaseDocument *	doc,
		BaseTime &	time
	)		const

Retrieves the time of time fields.

Parameters

[in]	id	The control ID.
[in]	doc	The document to use for framerate calculations.
[out]	time	Assigned the current time.

Returns

true if the time was retrieved, otherwise false.

GetFilename() [1/2]

Bool GetFilename	(	const GadgetPtr &	id,
		Filename &	fn
	)		const

Retrieves the text from string controls as a filename.

Parameters

[in]	id	The control ID.
[out]	fn	Assigned the current filename.

Returns

true if the value was retrieved, otherwise false.

CheckTristateChange()

Bool CheckTristateChange

(

const GadgetPtr &

id

)

Checks if a control content has been changed since the last Set.

Parameters

[in]

id

The control ID.

Returns

true if the control has been changed, otherwise false.

SetBool() [2/3]

Bool SetBool	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bcid
	)

Sets the value of checkbox controls, taking the new value from a base container.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new value. The caller owns the pointed base container.
[in]	bcid	The container ID of the new value.

Returns

true if the value was set, otherwise false.

SetInt32() [2/3]

Bool SetInt32	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bcid,
		Int32	min = LIMIT< Int32 >::MIN,
		Int32	max = LIMIT< Int32 >::MAX,
		Int32	step = 1,
		Int32	min2 = LIMIT< Int32 >::MIN,
		Int32	max2 = LIMIT< Int32 >::MAX
	)

Sets the value and limits of integer fields, taking the new value from a base container. Also used for tab groups, radio buttons and combo boxes.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new value. The caller owns the pointed base container.
[in]	bcid	The container ID of the new value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.
[in]	min2	The minimum value allowed outside the visual range used for sliders. Overrides min for the acceptance check.
[in]	max2	The maximum value allowed outside the visual range used for sliders. Overrides max for the acceptance check.

Returns

true if the value was set, otherwise false.

SetFloat() [2/3]

Bool SetFloat	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bcid,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0,
		Int32	format = FORMAT_FLOAT,
		Float	min2 = 0.0,
		Float	max2 = 0.0,
		Bool	quadscale = false
	)

Sets the value, unit and limits of float fields, taking the new value from a base container.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new value. The caller owns the pointed base container.
[in]	bcid	The container ID of the new value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.
[in]	format	The unit and format of the field: FORMAT_NUMBERS
[in]	min2	The minimum value allowed outside the visual range used for sliders. Overrides min for the acceptance check.
[in]	max2	The maximum value allowed outside the visual range used for sliders. Overrides max for the acceptance check.
[in]	quadscale	If true a quadratic scale is used for the slider, so that more precision is available for lower values.

Returns

true if the value was set, otherwise false.

SetMeter() [2/3]

Bool SetMeter	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bcid,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0
	)

Sets the value, unit and limits of meter fields, taking the new value from a base container. Same as SetFloat with FORMAT_METER.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new value. The caller owns the pointed base container.
[in]	bcid	The container ID of the new value.
[in]	min	The minimum value accepted.
[in]	max	The maximum value accepted.
[in]	step	The step used for arrow buttons.

Returns

true if the value was set, otherwise false.

SetDegree() [2/3]

Bool SetDegree	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bcid,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0
	)

Sets the value, unit and limits of angle fields, taking the new value from a base container. Same as SetFloat with FORMAT_DEGREE.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new value. The caller owns the pointed base container.
[in]	bcid	The container ID of the new value.
[in]	min	The minimum value accepted.
[in]	max	The maximum value accepted.
[in]	step	The step used for arrow buttons.

Returns

true if the value was set, otherwise false.

SetPercent() [2/3]

Bool SetPercent	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bcid,
		Float	min = 0.0,
		Float	max = 100.0,
		Float	step = 1.0
	)

Sets the value, unit and limits of percent fields, taking the new value from a base container. Same as SetFloat with FORMAT_PERCENT.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new value (real fraction). The caller owns the pointed base container.
[in]	bcid	The container ID of the new value.
[in]	min	The minimum value accepted.
[in]	max	The maximum value accepted.
[in]	step	The step used for arrow buttons.

Returns

true if the value was set, otherwise false.

SetTime() [2/3]

Bool SetTime	(	const GadgetPtr &	id,
		const BaseDocument *	doc,
		const BaseContainer *	bc,
		Int32	bcid,
		const BaseTime &	min = BaseTime(- 108000, 1),
		const BaseTime &	max = BaseTime(108000, 1),
		Int32	stepframes = 1
	)

Sets the value and limits of a time field, taking the new value from a base container. Same as SetFloat with FORMAT_FRAMES.

Parameters

[in]	id	The control ID.
[in]	doc	The document to get the framerate from. The caller owns the pointed document.
[in]	bc	The base container with the new time. The caller owns the pointed base container.
[in]	bcid	The container ID of the new time.
[in]	min	The minimum value accepted.
[in]	max	The maximum value accepted.
[in]	stepframes	The frame step used for arrow buttons.

Returns

true if the time was set, otherwise false.

SetString() [2/3]

Bool SetString	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bcid,
		Int32	flags = 0
	)

Sets the text of string controls, taking the new value from a base container. Used for all controls that have a text, for example static text fields, edit fields, buttons and check boxes.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new value. The caller owns the pointed base container.
[in]	bcid	The container ID of the new value.
[in]	flags	Flags: EDITTEXT FLAG_CENTER_ALIGN

Returns

true if the value was set, otherwise false.

SetFilename() [2/2]

Bool SetFilename	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bcid
	)

Sets the text of string controls, taking the new value from a filename in a base container.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new value. The caller owns the pointed base container.
[in]	bcid	The container ID of the new value.

Returns

true if the value was set, otherwise false.

SetColorField() [2/2]

Bool SetColorField	(	const GadgetPtr &	id,
		const BaseContainer *	bc,
		Int32	bc_colid,
		Int32	bc_brightnessid,
		Float	maxbrightness,
		Int32	flags
	)

Sets the color, brightness and limits of color fields and color choosers, taking the new values from a base container.

Parameters

[in]	id	The control ID.
[in]	bc	The base container with the new color field values. The caller owns the pointed base container.
[in]	bc_colid	The container ID of the new color value.
[in]	bc_brightnessid	The container ID of the new brightness value.
[in]	maxbrightness	The maximum brightness allowed.
[in]	flags	Controls what parts of a color chooser are available: DR_COLORFIELD

Returns

true if the color field values were set, otherwise false.

GetBool() [2/2]

Bool GetBool	(	const GadgetPtr &	id,
		BaseContainer *	bc,
		Int32	bcid
	)		const

Retrieves the state of checkbox controls, and stores it in a base container.

Parameters

[in]	id	The control ID.
[out]	bc	The base container to receive the state. The caller owns the pointed base container.
[in]	bcid	The container ID of the state.

Returns

true if the value was retrieved, otherwise false.

GetInt32() [2/2]

Bool GetInt32	(	const GadgetPtr &	id,
		BaseContainer *	bc,
		Int32	bcid
	)		const

Retrieves the value of integer fields, and stores it in a base container. Also used for tab groups, radio buttons and combo boxes.

Parameters

[in]	id	The control ID.
[out]	bc	The base container to receive the value. The caller owns the pointed base container.
[in]	bcid	The container ID of the value.

Returns

true if the value was retrieved, otherwise false.

GetFloat() [2/2]

Bool GetFloat	(	const GadgetPtr &	id,
		BaseContainer *	bc,
		Int32	bcid
	)		const

Retrieves the value of float fields, and stores it in a base container.

Parameters

[in]	id	The control ID.
[out]	bc	The base container to receive the value. The caller owns the pointed base container.
[in]	bcid	The container ID of the value.

Returns

true if the value was retrieved, otherwise false.

GetTime() [2/2]

Bool GetTime	(	const GadgetPtr &	id,
		const BaseDocument *	doc,
		BaseContainer *	bc,
		Int32	bcid
	)		const

Retrieves the value of a time field, and stores it in a base container.

Parameters

[in]	id	The control ID.
[in]	doc	The document to get the framerate from. The caller owns the pointed document.
[out]	bc	The base container to receive the value. The caller owns the pointed base container.
[in]	bcid	The container ID of the value.

Returns

true if the value was retrieved, otherwise false.

GetVector() [2/2]

Bool GetVector	(	const GadgetPtr &	id_x,
		const GadgetPtr &	id_y,
		const GadgetPtr &	id_z,
		BaseContainer *	bc,
		Int32	bcid
	)		const

Retrieves the value of three float fields at the same time as a vector, and stores it in a base container.

Parameters

[in]	id_x	The control ID of the X field.
[in]	id_y	The control ID of the Y field.
[in]	id_z	The control ID of the Z field.
[out]	bc	The base container to receive the value. The caller owns the pointed base container.
[in]	bcid	The container ID of the value.

Returns

true if the value was retrieved, otherwise false.

GetString() [2/2]

Bool GetString	(	const GadgetPtr &	id,
		BaseContainer *	bc,
		Int32	bcid
	)		const

Retrieves the value from string controls, and stores it in a base container. Used for all controls that have a text, for example static text fields, edit fields, buttons and check boxes.

Parameters

[in]	id	The control ID.
[out]	bc	The base container to receive the value. The caller owns the pointed base container.
[in]	bcid	The container ID of the value.

Returns

true if the value was retrieved, otherwise false.

GetFilename() [2/2]

Bool GetFilename	(	const GadgetPtr &	id,
		BaseContainer *	bc,
		Int32	bcid
	)		const

Retrieves the value from string controls, and stores it as a filename in a base container.

Parameters

[in]	id	The control ID.
[out]	bc	The base container to receive the value. The caller owns the pointed base container.
[in]	bcid	The container ID of the value.

Returns

true if the value was retrieved, otherwise false.

GetColorField() [2/2]

Bool GetColorField	(	const GadgetPtr &	id,
		BaseContainer *	bc,
		Int32	bc_colid,
		Int32	bc_brightnessid
	)		const

Retrieves the values of color and brightness for color controls, and stores them in a base container.

Parameters

[in]	id	The control ID.
[out]	bc	The base container to receive the values. The caller owns the pointed base container.
[in]	bc_colid	The container ID of the color value.
[in]	bc_brightnessid	The container ID of the brightness value.

Returns

true if the values were retrieved, otherwise false.

SetBool() [3/3]

Bool SetBool	(	const GadgetPtr &	id,
		const TriState< Bool > &	tri
	)

Sets the value of checkbox controls using a TriState object.

Parameters

[in]	id	The control ID.
[in]	tri	A tristate object for the value.

Returns

true if the value was set, otherwise false.

SetInt32() [3/3]

Bool SetInt32	(	const GadgetPtr &	id,
		const TriState< Int32 > &	tri,
		Int32	min = LIMIT< Int32 >::MIN,
		Int32	max = LIMIT< Int32 >::MAX,
		Int32	step = 1,
		Int32	min2 = LIMIT< Int32 >::MIN,
		Int32	max2 = LIMIT< Int32 >::MAX
	)

Sets the value and limits of integer fields using a TriState object.

Parameters

[in]	id	The control ID.
[in]	tri	A tristate object for the value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.
[in]	min2	The minimum value allowed outside the visual range used for sliders. Overrides min for the acceptance check.
[in]	max2	The maximum value allowed outside the visual range used for sliders. Overrides max for the acceptance check.

Returns

true if the value was set, otherwise false.

SetFloat() [3/3]

Bool SetFloat	(	const GadgetPtr &	id,
		const TriState< Float > &	tri,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0,
		Int32	format = FORMAT_FLOAT,
		Float	min2 = 0.0,
		Float	max2 = 0.0,
		Bool	quadscale = false
	)

Sets the value, unit and limits of float fields using a TriState object.

Parameters

[in]	id	The control ID.
[in]	tri	A tristate object for the value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.
[in]	format	The unit and format of the field: FORMAT_NUMBERS
[in]	min2	The minimum value allowed outside the visual range used for sliders. Overrides min for the acceptance check.
[in]	max2	The maximum value allowed outside the visual range used for sliders. Overrides max for the acceptance check.
[in]	quadscale	If true a quadratic scale is used for the slider, so that more precision is available for lower values.

Returns

true if the value was set, otherwise false.

SetMeter() [3/3]

Bool SetMeter	(	const GadgetPtr &	id,
		const TriState< Float > &	tri,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0
	)

Sets the value and limits of a meter field using a TriState object. Same as SetFloat with FORMAT_METER.

Parameters

[in]	id	The control ID.
[in]	tri	A tristate object for the value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.

Returns

true if the value was set, otherwise false.

SetDegree() [3/3]

Bool SetDegree	(	const GadgetPtr &	id,
		const TriState< Float > &	tri,
		Float	min = (-1.0e18),
		Float	max = (1.0e18),
		Float	step = 1.0
	)

Sets the value and limits of an angle field using a TriState object. Same as SetFloat with FORMAT_DEGREE.

Parameters

[in]	id	The control ID.
[in]	tri	A tristate object for the value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.

Returns

true if the value was set, otherwise false.

SetPercent() [3/3]

Bool SetPercent	(	const GadgetPtr &	id,
		const TriState< Float > &	tri,
		Float	min = 0.0,
		Float	max = 100.0,
		Float	step = 1.0
	)

Sets the value and limits of a percent field using a TriState object. Same as SetFloat with FORMAT_PERCENT.

Parameters

[in]	id	The control ID.
[in]	tri	A tristate object for the value.
[in]	min	The minimum visual value accepted.
[in]	max	The maximum visual value accepted.
[in]	step	The step used for arrow buttons.

Returns

true if the value was set, otherwise false.

SetTime() [3/3]

Bool SetTime	(	const GadgetPtr &	id,
		const BaseDocument *	doc,
		const TriState< BaseTime > &	tri,
		const BaseTime &	min = BaseTime(- 108000, 1),
		const BaseTime &	max = BaseTime(108000, 1),
		Int32	stepframes = 1
	)

Sets the value and limits of a time field using a TriState object. Same as SetFloat with FORMAT_FRAMES.

Parameters

[in]	id	The control ID.
[in]	doc	The document to be used for framerate calculations.
[in]	tri	A tristate object for the value.
[in]	min	The minimum time accepted.
[in]	max	The maximum time accepted.
[in]	stepframes	The frame step used for arrow buttons.

Returns

true if the value was set, otherwise false.

SetString() [3/3]

Bool SetString	(	const GadgetPtr &	id,
		const TriState< String > &	tri,
		Int32	flags = 0
	)

Sets the text of string controls using a TriState object.

Parameters

[in]	id	The control ID.
[in]	tri	A tristate object for the value.
[in]	flags	Flags: EDITTEXT FLAG_CENTER_ALIGN

Returns

true if the value was set, otherwise false.

Local2Global()

Bool Local2Global	(	Int32 *	x,
		Int32 *	y
	)

Transforms local coordinates (relative to the top left corner of the user area) to global window coordinates (relative to the top left corner of the application window). Stores the result in *x and *y.

Parameters

[in,out]	x	The local X coordinate. Assigned the global window coordinate.
[in,out]	y	The local Y coordinate. Assigned the global window coordinate.

Returns

true if the coordinates were converted, otherwise false.

Global2Local()

Bool Global2Local	(	Int32 *	x,
		Int32 *	y
	)

Transforms global window coordinates (relative to the top left corner of the application window) to local coordinates (relative to the top left corner of the user area). Stores the result in *x and *y.

Parameters

[in,out]	x	The global window X coordinate. Assigned the local coordinate.
[in,out]	y	The global window Y coordinate. Assigned the local coordinate.

Returns

true if the coordinates were converted, otherwise false.

Screen2Local()

Bool Screen2Local	(	Int32 *	x,
		Int32 *	y
	)

Transforms screen coordinates (relative to the top left corner of the system screen) to local coordinates (relative to the top left corner of the user area). Stores the result in *x and *y.

Parameters

[in,out]	x	The screen X coordinate. Assigned the local coordinate.
[in,out]	y	The screen Y coordinate. Assigned the local coordinate.

Returns

true if the coordinates were converted, otherwise false.

Local2Screen()

Bool Local2Screen	(	Int32 *	x,
		Int32 *	y
	)

Transforms local coordinates (relative to the top left corner of the user area) to screen coordinates (relative to the top left corner of the system screen). Stores the result in *x and *y.

Parameters

[in,out]	x	The local X coordinate. Assigned the screen coordinate.
[in,out]	y	The local Y coordinate. Assigned the screen coordinate.

Returns

true if the coordinates were converted, otherwise false.

GetColorRGB()

Bool GetColorRGB	(	Int32	colorid,
		Int32 &	r,
		Int32 &	g,
		Int32 &	b
	)

Gets the RGB values associated with a color constant.

Parameters

[in]	colorid	A color constant: COLOR
[out]	r	Assigned the red component of the color.
[out]	g	Assigned the green component of the color.
[out]	b	Assigned the blue component of the color.

Returns

true if successful, otherwise false.

SetDefaultColor() [1/2]

void SetDefaultColor	(	const GadgetPtr &	id,
		Int32	colorid,
		Int32	mapid
	)

Sets the default color for GUI elements.

Parameters

[in]	id	The control ID to set the color for.
[in]	colorid	A color constant: COLOR
[in]	mapid	The color map ID.

SetDefaultColor() [2/2]

void SetDefaultColor	(	const GadgetPtr &	id,
		Int32	colorid,
		const Vector &	color
	)

Sets the default color for GUI elements.

Parameters

[in]	id	The control ID to set the color for.
[in]	colorid	A color constant: COLOR
[in]	color	The color to set.

LoadDialogResource()

Bool LoadDialogResource	(	Int32	id,
		GeResource *	lr,
		Int32	flags
	)

Loads an external resource file.
This is the preferred method for dialog layout since it gives maximum flexibility and easy multi language support.

Note

The dialog loaded is automatically surrounded by an additional outer group, so flags means the same as with dialog groups (e.g. BFV_CENTER). See Dialog Resource for more information.

Parameters

[in]	id	The dialog ID.
[in]	lr	The loaded resource or nullptr. If this is nullptr then the global ::resource singleton is used. The caller owns the pointed resource.
[in]	flags	The layout flags: BFH BFV

Returns

true if the dialog was loaded successfully, otherwise false.

AddCheckbox()

C4DGadget* AddCheckbox	(	Int32	id,
		Int32	flags,
		Int32	initw,
		Int32	inith,
		const maxon::String &	name
	)

Adds a checkbox to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	name	The name of the checkbox.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddButton()

C4DGadget* AddButton	(	Int32	id,
		Int32	flags,
		Int32	initw,
		Int32	inith,
		const maxon::String &	name
	)

Adds a button to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	name	The name of the button.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddStaticText()

C4DGadget* AddStaticText	(	Int32	id,
		Int32	flags,
		Int32	initw,
		Int32	inith,
		const maxon::String &	name,
		Int32	borderstyle
	)

Adds a static text to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	name	The name of the static text.
[in]	borderstyle	The border style: BORDER

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddArrowButton()

C4DGadget* AddArrowButton	(	Int32	id,
		Int32	flags,
		Int32	initw,
		Int32	inith,
		Int32	arrowtype
	)

Adds an arrow button to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	arrowtype	The arrow type: ARROW

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddEditText()

C4DGadget* AddEditText	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0,
		Int32	editflags = 0
	)

Adds an editable text field to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	editflags	The edit flags: EDITTEXT

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddMultiLineEditText()

C4DGadget* AddMultiLineEditText	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0,
		Int32	style = 0
	)

Adds an editable text field with multiple lines to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	style	The style flags: DR_MULTILINE

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddEditNumber()

C4DGadget* AddEditNumber	(	Int32	id,
		Int32	flags,
		Int32	initw = 80,
		Int32	inith = 0
	)

Adds an editable number field to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddEditNumberArrows()

C4DGadget* AddEditNumberArrows	(	Int32	id,
		Int32	flags,
		Int32	initw = 70,
		Int32	inith = 0
	)

Adds an editable number field with up/down arrows to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddEditSlider()

C4DGadget* AddEditSlider	(	Int32	id,
		Int32	flags,
		Int32	initw = 80,
		Int32	inith = 0
	)

Adds a slider with an editable number field to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddSlider()

C4DGadget* AddSlider	(	Int32	id,
		Int32	flags,
		Int32	initw = 90,
		Int32	inith = 0
	)

Adds a slider to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddColorField()

C4DGadget* AddColorField	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0,
		Int32	colorflags = 0
	)

Adds a simple color field without sliders to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	colorflags	The color flags: DR_COLORFIELD

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddColorChooser()

C4DGadget* AddColorChooser	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0,
		Int32	layoutflags = 0,
		const BaseContainer &	settings = BaseContainer()
	)

Adds a color chooser gadget to the layout.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	layoutflags	The color flags: DR_COLORFIELD
[in]	settings	@markPrivate{The color chooser settings.} Since R17

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddRadioButton()

C4DGadget* AddRadioButton	(	Int32	id,
		Int32	flags,
		Int32	initw,
		Int32	inith,
		const maxon::String &	name
	)

Adds a radio button to the layout. Used with radio groups created with AddRadioGroup().

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	name	The name of the radio button.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddRadioText()

C4DGadget* AddRadioText	(	Int32	id,
		Int32	flags,
		Int32	initw,
		Int32	inith,
		const maxon::String &	name
	)

Adds a text radio button to the layout (like the ones to the left in the Material Editor). Used with radio groups created with AddRadioGroup().

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	name	The name of the text radio button.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddEditShortcut()

C4DGadget* AddEditShortcut	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0,
		Int32	shortcutflags = 0
	)

Adds a field for editing shortcuts.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	shortcutflags	The shortcut flags.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddSeparatorH()

C4DGadget* AddSeparatorH	(	Int32	initw,
		Int32	flags = BFH_FIT
	)

Adds a horizontal separator to the layout.

Parameters

[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	flags	The layout flags: BFH BFV

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddSeparatorV()

C4DGadget* AddSeparatorV	(	Int32	inith,
		Int32	flags = BFV_FIT
	)

Adds a vertical separator to the layout.

Parameters

[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	flags	The layout flags: BFH BFV

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddRadioGroup()

Bool AddRadioGroup	(	Int32	id,
		Int32	flags,
		Int32	columns = 1,
		Int32	rows = 0
	)

Adds a radio group to the layout. To add items to the radio button group use the AddChild() function.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	columns	The number of columns, or 0 if rows is used.
[in]	rows	The number of rows, or 0 if columns is used.

Returns

true if the radio group was added, otherwise false.

AddComboBox()

C4DGadget* AddComboBox	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0,
		Bool	specialalign = false,
		Bool	allowFiltering = false
	)

Adds a combo box to the layout. To add items to the combo box menu use the AddChild() function.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	specialalign	Used to quantize the width of the combo box. If this is true then the width of the combo box will be a multiple of initw. For example if initw is 60px and specialalign is true the width will be 60, 120, 180px and so on.
[in]	allowFiltering	True to allow keyboard filtering of the combobox list.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddComboButton()

C4DGadget* AddComboButton	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0,
		Bool	specialalign = false,
		Bool	allowFiltering = false
	)

Adds a combo button to the layout. To add items to the combo box menu use the AddChild() function.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	specialalign	Used to quantize the width of the item. If this is true then the width of the item will be a multiple of initw. For example if initw is 60px and specialalign is true the width will be 60, 120, 180px and so on.
[in]	allowFiltering	True to allow keyboard filtering of the popup list.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddPopupButton()

C4DGadget* AddPopupButton	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0,
		Bool	allowFiltering = false
	)

Adds a popup button to the layout. To add items to the popup menu use the AddChild() function or SetPopup().

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.
[in]	allowFiltering	True to allow keyboard filtering of the popup list.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AddListView()

Bool AddListView	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0
	)

Adds a list view to the layout.

Note

Use the SimpleListView class to wrap the created list view control.

Parameters

[in]	id	The control ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.

Returns

true if the list view was added, otherwise false.

AddChild()

Bool AddChild	(	const GadgetPtr &	id,
		Int32	subid,
		const maxon::String &	child
	)

Adds items to combo boxes or popup buttons. The dialog resource equivalent is CHILDS.

Parameters

[in]	id	The control ID.
[in]	subid	The ID of the item to add.
[in]	child	The name of the item to add.

Returns

true if the child was added, otherwise false.

FreeChildren()

Bool FreeChildren

(

const GadgetPtr &

id

)

Clears the item list of combo boxes and popup buttons.

Note

Please note the spelling!

Parameters

[in]

id

The control ID.

Returns

true if the children were removed, otherwise false.

SetPopup()

Bool SetPopup	(	const GadgetPtr &	id,
		const BaseContainer &	bc
	)

Sets the item list of a popup button using a popup menu base container.
This allow things like sub-menus and separators. See ShowPopupMenu() for more information.

Parameters

[in]	id	The popup button ID.
[in]	bc	A base container with menu items.

Returns

true if the popup menu was set, otherwise false.

AddChildren()

Bool AddChildren	(	const GadgetPtr &	id,
		const BaseContainer &	bc
	)

Adds children to a dialog element using a base container.

Parameters

[in]	id	The element to add children to.
[in]	bc	A base container with items.

Returns

true if the children were added, otherwise false.

AddUserArea()

C4DGadget* AddUserArea	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0
	)

Adds a user area to the layout. Use AttachUserArea() to assign a GeUserArea object to the user area control.

Parameters

[in]	id	The user area ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.

Returns

The added gadget, or nullptr if an error occurred. The dialog owns the pointed gadget.

AttachUserArea()

Bool AttachUserArea	(	GeUserArea &	ua,
		const GadgetPtr &	id,
		USERAREAFLAGS	userareaflags = USERAREAFLAGS::COREMESSAGE
	)

Attaches a GeUserArea object to a user area control, added with AddUserArea().
The object will handle all messages to the user area and is responsible for painting the user area.

Note

A good practice is to place the GeUserArea derived object as a member of the GeDialog derived class.

Parameters

[in]	ua	A user area object to attach.
[in]	id	The user area ID.
[in]	userareaflags	The user area flags: USERAREAFLAGS

Returns

true if the user area was attached, otherwise false.

AddSubDialog()

Bool AddSubDialog	(	Int32	id,
		Int32	flags,
		Int32	initw = 0,
		Int32	inith = 0
	)

Adds a sub-dialog to the layout. Use AttachSubDialog() to assign a SubDialog object to the sub-dialog control.

See also

SubDialog

Parameters

[in]	id	The sub-dialog ID.
[in]	flags	The layout flags: BFH BFV
[in]	initw	The initial width. Use SizePixChr() to set this value.
[in]	inith	The initial height. Use SizePixChr() to set this value.

Returns

true if the sub dialog was added, otherwise false.

AttachSubDialog()

Bool AttachSubDialog	(	SubDialog *	userdlg,
		Int32	id
	)

Attaches a SubDialog derived object to a SubDialog control, added with AddSubDialog().
To replace the sub-dialog with another one, just call this function again.

Parameters

[in]	userdlg	The sub-dialog object. The caller owns the pointed sub-dialog.
[in]	id	The sub-dialog ID.

Returns

true if the sub-dialog was attached, otherwise false.

AddDlgGroup()

Bool AddDlgGroup

(

Int32

type

)

Adds a dialog group with standard buttons to the layout.

Parameters

[in]

type

The standard buttons to add: DLG

Returns

true if the dialog group was added, otherwise false.

GroupBeginInMenuLine()

Bool GroupBeginInMenuLine

(

)

Begins a group in the menu bar of the dialog. End the group with GroupEnd().

Returns

true if a group in the menu bar could be begun, otherwise false.

TabGroupBegin()

Bool TabGroupBegin	(	Int32	id,
		Int32	flags,
		Int32	tabtype = TAB_TABS
	)

Begins a tab group. Add tabs to the tab group with GroupBegin(). End the tab group with GroupEnd().

Parameters

[in]	id	The ID of the tab group.
[in]	flags	The layout flags: BFH BFV
[in]	tabtype	The tab type: TAB

Returns

true if a tab group could be begun, otherwise false.

GroupBegin()

Bool GroupBegin	(	Int32	id,
		Int32	flags,
		Int32	cols,
		Int32	rows,
		const maxon::String &	title,
		Int32	groupflags,
		Int32	initw = 0,
		Int32	inith = 0
	)

Begins a group. End the group with GroupEnd().

Note

GroupSpace(), GroupBorder(), GroupBorderNoTitle() and GroupBorderSpace() to further specify the look of the group.

Parameters

[in]	id	The ID of the group.
[in]	flags	The layout flags: BFH BFV
[in]	cols	The number of columns, or 0 if rows are used.
[in]	rows	The number of rows, or 0 if cols are used.
[in]	title	The title of the the group. Used for tab groups and groups with border.
[in]	groupflags	The group flags: BFV_GROUP
[in]	initw	The initial width.
[in]	inith	The initial height.

Returns

true if a group could be begun, otherwise false.

GroupEnd()

Bool GroupEnd

(

void

)

Ends groups begun with GroupBegin(), TabGroupBegin() and ScrollGroupBegin().

Returns

true if a group was ended, otherwise false.

GroupSpace()

Bool GroupSpace	(	Int32	spacex,
		Int32	spacey
	)

Sets the space in pixels between two elements in the current group. Equivalent to SPACE in dialog resources.

Parameters

[in]	spacex	The X distance.
[in]	spacey	The Y distance.

Returns

true if the spacing could be set, otherwise false.

GroupBorder()

Bool GroupBorder

(

UInt32

borderstyle

)

Sets the border type of the current group, and displays the title in the border if possible.
Equivalent to BORDERSTYLE in dialog resources, if a NAME field is provided with the GROUP declaration.

Note

Use GroupBorderNoTitle() to not have a title. Otherwise there will be a small gap in the border where the title would be.

Parameters

[in]

borderstyle

The border style: BORDER

Returns

true if the border was set, otherwise false.

GroupBorderNoTitle()

Bool GroupBorderNoTitle

(

UInt32

borderstyle

)

Sets the border type of the current group. Does not display the title in the border.
Equivalent to BORDERSTYLE in dialog resources, if a NAME field is not provided with the GROUP declaration.

Parameters

[in]

borderstyle

The border style: BORDER

Returns

true if the border was set, otherwise false.

GroupBorderSpace()

Bool GroupBorderSpace	(	Int32	left,
		Int32	top,
		Int32	right,
		Int32	bottom
	)

Sets the border size around the current group in pixels. Equivalent to BORDERSIZE in dialog resources.

Parameters

[in]	left	The distance to the left of the group.
[in]	top	The distance above the group.
[in]	right	The distance to the right of the group.
[in]	bottom	The distance below the group.

Returns

true if the border space could be set, otherwise false.

GroupWeightsSave()

Bool GroupWeightsSave	(	const GadgetPtr &	id,
		BaseContainer &	weights
	)

Retrieves group weights for group id.

Parameters

[in]	id	The ID of the group.
[out]	weights	Filled with the weights: GROUPWEIGHTS_PERCENT

Returns

true if the group weights could be retrieved, otherwise false.

GroupWeightsLoad()

Bool GroupWeightsLoad	(	const GadgetPtr &	id,
		const BaseContainer &	weights
	)

Sets group weights for group id.
The group weights are usually absolute values. If an element has a bigger minimum size the given weight will be ignored. The sum of the weights do not need to be 100.

Note

A weight value can be negative. In this case the group keeps its size absolute and it is not resized proportionally.

Parameters

[in]	id	The ID of the group.
[in]	weights	The weights to set: GROUPWEIGHTS_PERCENT

Returns

true if the group weights could be set, otherwise false.

GetItemDim()

Bool GetItemDim	(	const GadgetPtr &	id,
		Int32 *	x,
		Int32 *	y,
		Int32 *	w,
		Int32 *	h
	)		const

Queries a dialog control for its current size and position in pixels.

Parameters

[in]	id	The control ID. Use C4DGUIWINDOWID to get the pos/size of the window.
[out]	x	Assigned the X coordinate of the upper left corner of the control.
[out]	y	Assigned the Y coordinate of the upper left corner of the control.
[out]	w	Assigned the width of the control.
[out]	h	Assigned the height of the control.

Returns

true if the item size and position were stored, otherwise false.

GetDragPosition()

Bool GetDragPosition	(	const BaseContainer &	msg,
		Int32 *	x,
		Int32 *	y
	)

Extracts local drag coordinates from a drag and drop event. Stores the result in *x and *y.

See also

The article Drag and Drop for more information.

Parameters

[in]	msg	The original message.
[out]	x	Assigned the local X position.
[out]	y	Assigned the local Y position.

Returns

true if the drag position was extracted, otherwise false.

GetDragObject()

Bool GetDragObject	(	const BaseContainer &	msg,
		Int32 *	type,
		void **	object
	)

Extracts the object from a drag and drop message. Stores the result in *type and *object.

See also

The article Drag and Drop for more information.

Parameters

[in]	msg	The original message.
[out]	type	Assigned the type of the object.
[out]	object	Assigned a pointer to the object. Cinema 4D owns the pointed object.

Returns

true if the drag object was extracted, otherwise false.

SetDragDestination()

Bool SetDragDestination	(	Int32	cursor,
		Int32	gadgetid = 0
	)

Sets the correct cursor during drag and drop handling.

See also

The article Drag and Drop for more information.

Parameters

[in]	cursor	A mouse cursor: MOUSE
[in]	gadgetid	The dialog element that this cursor is for, or 0.

Returns

true if the cursor could be set, otherwise false.

CheckDropArea()

Bool CheckDropArea	(	const GadgetPtr &	id,
		const BaseContainer &	msg,
		Bool	horiz,
		Bool	vert
	)

Checks the drag position in a drag event message against a certain dialog element's position in the layout. The check can be limited to only X or Y coordinates.

See also

The article Drag and Drop for more information.

Parameters

[in]	id	The dialog element ID.
[in]	msg	The drag message.
[in]	horiz	If true the drag position is checked against the horizontal bounds of the region.
[in]	vert	If true the drag position is checked against the vertical bounds of the region.

Returns

true if the drag message is within the bounds specified, otherwise false.

GetVisibleArea()

Bool GetVisibleArea	(	Int32	scrollgroupid,
		Int32 *	x1,
		Int32 *	y1,
		Int32 *	x2,
		Int32 *	y2
	)

Queries a scroll group for its currently visible region, a rectangle between (x1,y1) and (x2,y2).

Parameters

[in]	scrollgroupid	The scroll group ID.
[out]	x1	Assigned the X coordinate of the top left visible corner.
[out]	y1	Assigned the Y coordinate of the top left visible corner.
[out]	x2	Assigned the X coordinate of the bottom right visible corner.
[out]	y2	Assigned the Y coordinate of the bottom right visible corner.

Returns

true if the visible area could be retrieved, otherwise false.

SetVisibleArea()

Bool SetVisibleArea	(	Int32	scrollgroupid,
		Int32	x1,
		Int32	y1,
		Int32	x2,
		Int32	y2
	)

Scrolls a scroll group so that the rectangle between (x1,y1) and (x2,y2) is visible.

• If the area is smaller than the scroll group then it is moved only as much as necessary.
• If the area is bigger than the scroll group then the top left corners are aligned.

  Parameters

  [in]	scrollgroupid	The scroll group ID.
  [in]	x1	The X coordinate of the top left corner of the rectangle.
  [in]	y1	The Y coordinate of the top left corner of the rectangle.
  [in]	x2	The X coordinate of the bottom right corner of the rectangle.
  [in]	y2	The Y coordinate of the bottom right corner of the rectangle.

  Returns

  true if the group was scrolled or already had the right view, otherwise false.

ScrollGroupBegin()

Bool ScrollGroupBegin	(	Int32	id,
		Int32	flags,
		Int32	scrollflags,
		Int32	initw = 0,
		Int32	inith = 0
	)

Begins a scrollable group. End the scroll group with GroupEnd().
Use SetVisibleArea() and GetVisibleArea() to control the currently visible area.

Parameters

[in]	id	The scroll group ID.
[in]	flags	The layout flags: BFH BFV
[in]	scrollflags	Additional flags for the scroll group: SCROLLGROUP
[in]	initw	The initial width of the scroll area.
[in]	inith	The initial height of the scroll area.

Returns

true if a scroll group could be begun, otherwise false.

LayoutChanged()

Bool LayoutChanged

(

const GadgetPtr &

id

)

Notifies Cinema 4D that the layout of a dynamic group in the dialog has changed.
This is usually done by first calling LayoutFlushGroup() and then adding new controls.

Parameters

[in]

id

The ID of the changed group.

Returns

true if the layout was updated, otherwise false.

LayoutChangedNoRedraw()

Bool LayoutChangedNoRedraw

(

const GadgetPtr &

id

)

Notifies Cinema 4D that the layout of a dynamic group in the dialog has changed.
This is usually done by first calling LayoutFlushGroup() and then adding new controls.

Warning

Does not redraw the dialog.

Parameters

[in]

id

The ID of the changed group.

Returns

true if the layout was updated, otherwise false.

Activate()

Bool Activate

(

const GadgetPtr &

id

)

Sets the focus to a specific control within the dialog.

Parameters

[in]

id

The control ID.

Returns

true if the control was activated, otherwise false.

IsActive()

Bool IsActive

(

const GadgetPtr &

id

)

Checks if the given gadget has the focus.

Since

R18

Parameters

[in]

id

The control ID.

Returns

true if the control is active, otherwise false.

BeginLayoutChange()

UpdateDialogHelper BeginLayoutChange	(	const GadgetPtr &	gadget,
		Bool	disableRedraws,
		Bool	doNotFlush = false
	)

BeginLayoutChange simplifies the call of the combinations of LayoutFlushGroup()/LayoutChanged().

Parameters

[in]	gadget	Gadget to flush and re-layout.
[in]	disableRedraws	True if all redraws should be disabled while the result object lives and result.CommitChanges() wasn't called.
[in]	doNotFlush	If true, existing elements persist and new elements are added at the end.

Returns

UpdateDialogRef on success. The returned object needs to be stored. Calling CommitChanges() will update the dialog group again and if redraw were disabled it will re-enable the redraw.

LayoutFlushGroup()

Bool LayoutFlushGroup

(

const GadgetPtr &

id

)

Removes all controls from a group and places the control insertion point within the group. This makes it possible to have dynamic groups.
After all components are added call LayoutChanged() with the group ID.

Parameters

[in]

id

The ID of the group.

Returns

true if the group was flushed, otherwise false.

LayoutFlushDisableRedraw()

Bool LayoutFlushDisableRedraw	(	const GadgetPtr &	id,
		Bool	disable
	)

LayoutFlushDisableRedraw description. Warning. For each calls of LayoutFlushDisableRedraw(true) you must call LayoutFlushDisableRedraw(false)!

Parameters

[in]	id	The ID of the group.
[in]	disable	True to disable redraw. Don't forget to enable it. Best use a finally{} to enable it again.

Returns

true if the group was disabled/enabled for redraw, otherwise false.

RemoveElement()

Bool RemoveElement

(

const GadgetPtr &

id

)

Removes an element from the dialog.

Parameters

[in]

id

The control ID.

Returns

true if the element was removed, otherwise false.

HideElement()

Bool HideElement	(	const GadgetPtr &	id,
		Bool	hide
	)

Hides/unhides an element within a dialog.

Parameters

[in]	id	The control ID.
[in]	hide	true to hide and false to unhide.

Returns

true if the element was hidden/unhidden, otherwise false.

RestoreLayout()

Bool RestoreLayout	(	Int32	pluginid,
		Int32	subid,
		void *	secret
	)

Used to restore an asynchronous dialog that has been placed in the users layout.

Note

Called from CommandData::RestoreLayout() where the secret pointer is provided.

Parameters

[in]	pluginid	The plugin ID of the command plugin.
[in]	subid	The sub-ID of the dialog.
[in]	secret	An internal pointer.

Returns

true if the dialog was restored, otherwise false.

MenuFlushAll()

Bool MenuFlushAll

(

void

)

Flushes the menu bar of the dialog, removing all menus.
Add menus with MenuSubBegin(). Call MenuFinished() when all menus and items have been added.

Returns

true if the menu bar was flushed, otherwise false.

MenuSubBegin()

Bool MenuSubBegin

(

const maxon::String &

string

)

Creates a new menu group. At the top level this means a menu, at lower levels a sub-menu. Add items with MenuAddCommand(), MenuAddString() or MenuAddSeparator(). Call MenuSubEnd() when the menu is finished.

Parameters

[in]

string

The name of the sub menu.

Returns

true if a menu group could be begun, otherwise false.

MenuSubEnd()

Bool MenuSubEnd

(

void

)

Closes the current menu group, opened with MenuSubBegin().

Returns

true if a menu group was ended, otherwise false.

MenuAddCommand()

Bool MenuAddCommand

(

Int32

cmdid

)

Adds a command item to the current menu.
This can either be a Cinema 4D command or a plugin command. Particularly useful is IDM_CM_CLOSEWINDOW to add a close item for dialogs.

Parameters

[in]

cmdid

A Cinema 4D command id or a plugin ID.

Returns

true if the command was added, otherwise false.

MenuAddString()

Bool MenuAddString	(	Int32	id,
		const maxon::String &	string
	)

Adds a string item to the current menu. Command() will be called when the menu item is selected.

Parameters

[in]	id	The item ID.
[in]	string	The item text. Use a  d  suffix for disabled and a  c  suffix for checked items.

Returns

true if a string item was added, otherwise false.

MenuAddSeparator()

Bool MenuAddSeparator

(

const maxon::String &

title = maxon::String()

)

Adds a separator to the current menu.

Parameters

[in]

title

Optional separator title.

Returns

true if a separator was added, otherwise false.

MenuFinished()

Bool MenuFinished

(

void

)

Call this function when all menus and all items have been added.

Returns

true if the menu bar was updated, otherwise false.

MenuInitString()

Bool MenuInitString	(	Int32	id,
		Bool	enabled,
		Bool	checked
	)

Used to change the enabled/disabled and checked/unchecked state of menu items.

Note

Can be called after MenuFinished() to update the menu item dynamically.

Parameters

[in]	id	The menu item ID.
[in]	enabled	true if the menu item is enabled or false if the menu item is disabled (grayed out).
[in]	checked	true if the menu item should be checked, otherwise false.

Returns

true if a string item was updated, otherwise false.

MenuSetResource()

Bool MenuSetResource

(

Int32

id

)

Sets the menu from a MENU resource ID.

Parameters

[in]

id

The menu resource ID.

Returns

true if the menu was set from resource, otherwise false.

FindCustomGui() [1/2]

void* FindCustomGui	(	Int32	id,
		Int32	pluginid
	)

Gets the custom GUI for a certain element ID. The GUI object must have been previously added with AddCustomGui().

Parameters

[in]	id	The custom GUI element ID.
[in]	pluginid	The plugin ID of the custom GUI.

Returns

The custom GUI. The dialog owns the pointed custom GUI.

FindCustomGui() [2/2]

T* FindCustomGui

(

Int32

id

)

Gets the custom GUI for a certain element ID. The GUI object must have been previously added with AddCustomGui().

Parameters

[in]

id

The custom GUI element ID.

Returns

The custom GUI. The dialog owns the pointed custom GUI.

AddCustomGui() [1/2]

void* AddCustomGui	(	Int32	id,
		Int32	pluginid,
		const maxon::String &	name,
		Int32	flags,
		Int32	minw,
		Int32	minh,
		const BaseContainer &	customdata
	)

Adds a custom GUI element to the dialog.

Parameters

[in]	id	The dialog element ID of the new custom GUI.
[in]	pluginid	The plugin ID of the custom GUI.
[in]	name	The name of the added custom GUI. (Not necessarily used.)
[in]	flags	The layout flags: BFH BFV
[in]	minw	The minimum width.
[in]	minh	The minimum height.
[in]	customdata	The settings for the new custom GUI.

Returns

The custom GUI element that was added, or nullptr if an error occurred. The dialog owns the pointed custom GUI.

AddCustomGui() [2/2]

T* AddCustomGui	(	Int32	id,
		const maxon::String &	name,
		Int32	flags,
		Int32	minw,
		Int32	minh,
		const BaseContainer &	customdata
	)

Adds a custom GUI element to the dialog.

Parameters

[in]	id	The dialog element ID of the new custom GUI.
[in]	name	The name of the added custom GUI. (Not necessarily used.)
[in]	flags	The layout flags: BFH BFV
[in]	minw	The minimum width.
[in]	minh	The minimum height.
[in]	customdata	The settings for the new custom GUI.

Returns

The custom GUI element that was added, or nullptr if an error occurred. The dialog owns the pointed custom GUI.

SetMultiLineMode()

Bool SetMultiLineMode	(	const GadgetPtr &	id,
		SCRIPTMODE	mode
	)

Sets the edit mode for multi-line edit fields.

Parameters

[in]	id	The control ID.
[in]	mode	The multi-line edit mode: SCRIPTMODE

Returns

true if the multi-line mode was set, otherwise false.

SetMultiLineLock()

Bool SetMultiLineLock	(	const GadgetPtr &	id,
		Bool	lock
	)

Locks/unlocks multi-line edit fields.

Parameters

[in]	id	The control ID.
[in]	lock	true to lock the field, formatConstant{false} to unlock it.

Returns

true if the multi-line edit field was locked/unlocked, otherwise false.

SetMultiLinePos()

Bool SetMultiLinePos	(	const GadgetPtr &	id,
		Int32	line,
		Int32	pos
	)

Sets the cursor position within a multi-line edit text control.

Parameters

[in]	id	The control ID.
[in]	line	The line number.
[in]	pos	The position within the line.

Returns

true if successful, otherwise false.

CheckClose()

Bool CheckClose

(

void

)

Checks if the dialog can be closed. Normally checks the value ranges and calls AskClose().

Returns

true if the dialog should not be closed, otherwise false.

CheckValueRanges()

Bool CheckValueRanges

(

void

)

Checks whether all input fields' values are within the allowed range.

Returns

true if everything is alright, or false if any field is wrong.

GetPixelRatio()

Float GetPixelRatio

(

)

const

Private. Always returns 1.0 except for user areas shown on OS X Retina displays, where it returns 2.0.

Returns

Always 1.0 except for user areas shown on OS X Retina displays.

ReleaseLink()

Bool ReleaseLink

(

)

Internal.

CheckCoreMessage()

Bool CheckCoreMessage	(	const BaseContainer &	msg,
		Int32 *	ownlastcoremsg = nullptr
	)

Speedup function that checks if a core message is new or has been already processed.

See also

The article Core Messages for more information.

Parameters

[in]	msg	The core message.
[in]	ownlastcoremsg	An optional pointer to a last core message.

Returns

true if the message is new, false if it is a message of the same age.

HandleHelpString()

static void HandleHelpString ( const BaseContainer &  msg, BaseContainer &  result, const maxon::String &  sym  )

static

Private.

GetWindowHandle()

void* GetWindowHandle

(

)

Gets the handle of the dialog window (HWND). Private.

Returns

The window handle.

GetWindowInterface()

void* GetWindowInterface

(

)

Private.

GetGuiInterface()

static void* GetGuiInterface ( )

static

Private.

GetFolding()

Bool GetFolding

(

void

)

Retrieve if the dialog is open but currently folded away in the layout.

Returns

True if folded.

SetFolding()

void SetFolding

(

Bool

allowClose

)

Fold the dialog away in the layout.

Parameters

[in]

allowClose

True if the dialog should fold away.

IsDockedOrTabbed()

Int32 IsDockedOrTabbed

(

)

Returns the docking state of the dialog.

Returns

Bit mask of DIALOG_ISDOCKED and DIALOG_ISTABBED. 0 if the dialog is a individual window.

Friends And Related Function Documentation

GeUserArea

friend class GeUserArea

friend

_GeListView

friend class _GeListView

friend

Member Data Documentation

cd

CDialog* cd

private

t_lastcoremsg

Int32 t_lastcoremsg

private

_folding

Bool _folding

private

createlayout

Bool createlayout

protected

true if the layout has been created, otherwise false. Normally not needed.