GeDialog Manual
GeDialog is the base class for interface elements of Cinema 4D . An asynchronous (non-modal) dialog acts as a panel that can be added to the application layout or as a free floating window. In contrast a synchronous (modal) dialog blocks the application's main thread until it is closed. A custom dialog is added by creating a subclass of GeDialog . GeDialog is also the base class of iCustomGui which is used to create custom GUI elements for NodeData 参数。
A GeDialog based window is typically owned by a CommandData plugin. This CommandData stores and opens the dialog instance.
// This CommandData example opens and restores a GeDialog based window. // g_geDialogID is the plugin ID of the CommandData plugin.// "RestoreLayout" is called to restore the dialog after a layout change Bool RestoreLayout ( void * secret) { return _dialog.RestoreLayout(g_geDialogID, 0, secret); }; static OpenExampleDialog* Alloc() { return NewObjClear(OpenExampleDialog); } };
The GeDialog is opened with GeDialog::Open() . The different types of dialogs are:
The GeDialog window can be closed with GeDialog::Close() . This will call GeDialog::AskClose() (see below).
A custom window is created by implementing a subclass of GeDialog . This subclass can implement different virtual functions to define the layout and behaviour of the dialog.
Dialog setup:
// sets the timer to 1000 milliseconds this->SetTimer(1000); return true ; }
// Initialize internal data and set the values Bool InitValues() { SetFloat(1000, 123.456); return true ; }
Messages and Interaction:
// This "Message" function checks if any interaction in the GeDialog starts or ends. Int32 Message( const BaseContainer & msg, BaseContainer & result) { // messages are identified // by the BaseContainer ID switch (msg. GetId ()) { case BFM_INTERACTSTART : { ApplicationOutput ( "Interaction start" ); break ; } case BFM_INTERACTEND : { ApplicationOutput ( "Interaction end" ); break ; } } return SUPER::Message(msg, result); }
Timed Actions:
It is possible to check these GeDialog properties:
It is also possible to read the pixel ratio of the current screen:
// get pixel ratio const Float pixelRatio = GetPixelRatio();
// check if Retina or not if (pixelRatio == 1.0) filename = "lowRes.png" ; else filename = "highRes.png" ;
// load bitmap (GetFullFilename() is just a custom utility function) const String fullFileName = GetFullFilename(filename); if (bitmap-> Init (fullFileName) == IMAGERESULT::OK ) { // store ratio bitmap-> SetData ( BASEBITMAP_DATA_GUIPIXELRATIO , pixelRatio);
// apply to BitmapButton bitmapButtonGUI-> SetImage (bitmap, true , false ); } } }
The layout of a GeDialog - the arrangement of groups and gadgets - is defined in the implementation of GeDialog::CreateLayout() . This layout can be defined by creating the groups and gadgets individually or by loading a dialog resource file.
General functions to handle GeDialog gadgets are:
// load dialog from resource file if (!LoadDialogResource(DLG_CUSTOM_DIALOG, nullptr , 0)) return false ;
// set a different title this->SetTitle( "New Title" _s);
// disable a GUI element this->Enable(IDC_CUSTOM_CHECKBOX, false ); return true ; }
GeDialog based windows contain a menu bar. This menu bar can contain various sub-menus and also any kind of gadget in a special sub-group.
Menus are created with:
Sub-menus are added with these functions:
Menu items are added with these functions:
// submenu "Cinema Commands" MenuSubBegin( "Cinema 4D Commands" _s);
// add Cinema 4D commands const Int32 saveAsCommandID = 12218; // "Save as" Command const Int32 saveCommandID = 12098; // "Save" Command MenuAddCommand(saveAsCommandID); MenuAddCommand(saveCommandID); MenuSubEnd();
// submenu "Dialog Commands" MenuSubBegin( "Dialog Commands" _s);
// add dialog commands MenuAddString(ID_COMMAND_A, "Action A" _s); MenuAddSeparator(); MenuAddString(ID_COMMAND_B, "Action B" _s); MenuSubEnd(); MenuFinished();
// set state MenuInitString(ID_COMMAND_B, true , true ); // set as checked
It is possible to add arbitrary gadgets to a special sub-group of the menu bar:
The arrangement of elements of the dialog layout is defined with groups. Such groups can define rows and columns and can contain further sub-groups.
Groups are created with these functions:
// parent group with the whole width of the GeDialog GroupBegin(100, BFH_SCALEFIT , 2, 0, "" _s, 0, 0, 300);
// left subgroup GroupBegin(200, BFH_SCALEFIT | BFV_SCALEFIT , 1, 0, "" _s, 0, 0, 0);
// tab parent group within the left subgroup TabGroupBegin(210, BFH_SCALEFIT | BFV_SCALEFIT );
// first tab group GroupBegin(220, BFH_SCALEFIT | BFV_SCALEFIT , 1, 0, "Tab 1" _s, 0, 400, 300); AddStaticText(221, BFH_SCALEFIT | BFH_LEFT , 0, 10, "Tab 1" _s, BORDER_NONE ); GroupEnd();
// second tab group GroupBegin(230, BFH_SCALEFIT | BFV_SCALEFIT , 1, 0, "Tab 2" _s, 0, 400, 300); AddStaticText(231, BFH_SCALEFIT | BFH_LEFT , 0, 10, "Tab 2" _s, BORDER_NONE ); GroupEnd(); GroupEnd(); GroupEnd();
// right subgroup GroupBegin(300, BFH_SCALEFIT | BFV_SCALEFIT , 1, 0, "" _s, 0, 0, 0); AddStaticText(301, BFH_SCALEFIT | BFH_LEFT , 0, 10, "Right subgroup" _s, BORDER_NONE ); GroupEnd(); GroupEnd();
The border style and spacing of groups can be defined with these functions:
If the group flag BFV_GRIDGROUP_ALLOW_WEIGHTS is set the user can change the width/height of group's columns/rows. The size of columns/rows is stored as "weights" which can be stored.
另请参阅 BFM_WEIGHTS_CHANGED in GUI and Interaction Messages Manual .
// This example creates a group with two columns. // The width of these columns can be changed by the user. GroupBegin(WEIGHT_GROUP, BFH_SCALEFIT | BFV_SCALEFIT , 3, 1, "" _s, BFV_GRIDGROUP_ALLOW_WEIGHTS ); GroupBegin(GROUP_LEFT, BFH_SCALEFIT | BFV_SCALEFIT , 1, 1, "" _s, 0); AddStaticText(100, 0, 0, 10, "Left Column" _s, 0); GroupEnd(); AddSeparatorV(1); GroupBegin(GROUP_RIGHT, BFH_SCALEFIT | BFV_SCALEFIT , 1, 1, "" _s, 0); AddStaticText(200, 0, 0, 10, "Right Column" _s, 0); GroupEnd(); GroupEnd(); GroupWeightsLoad(WEIGHT_GROUP, _weights);The content of a group can be flushed and replaced with new gadgets:
// flush group LayoutFlushGroup(100);
// add new gadget AddStaticText(101, BFH_SCALEFIT | BFH_LEFT , 0, 10, "New Element" _s, BORDER_NONE );
// update group LayoutChanged(100);
// This example flushes the group with the ID 1000 and adds new elements to it.
// begin layout change and store data UpdateDialogHelper updateDialog = BeginLayoutChange(1000, true );
// add new elements to flushed group AddStaticText(1100, BFH_SCALEFIT , 0, 10, "Add" _s, BORDER_NONE ); AddStaticText(1101, BFH_SCALEFIT , 0, 10, "new" _s, BORDER_NONE ); AddStaticText(1102, BFH_SCALEFIT , 0, 10, "elements" _s, BORDER_NONE );
// update group updateDialog. CommitChanges ();
A scroll group allows to scroll the content of a group using the mouse-wheel:
另请参阅 BFM_SETSTATUSBAR in Specific GUI Elements .
// This example creates a scroll group and fills it with multiple gadgets. ScrollGroupBegin(500, BFH_SCALEFIT , SCROLLGROUP_VERT | SCROLLGROUP_BORDERIN , 0, 100);// layout group within the scroll group GroupBegin(501, BFV_TOP | BFH_SCALEFIT , 1, 0, "" _s, 0);
// add gadgets for ( Int32 i = 0; i < 100; ++i) AddCheckbox(502 + i, BFH_SCALEFIT | BFH_LEFT , 0, 10, "element" _s); GroupEnd(); GroupEnd();
// This example gets the visible area of a scroll group and changes it. Int32 x1 = NOTOK ; Int32 y1 = NOTOK ; Int32 x2 = NOTOK ; Int32 y2 = NOTOK ;
// access the visible area of the scroll group if (GetVisibleArea(scrollGroupID, &x1, &y1, &x2, &y2)) { const Int32 height = y2 - y1; SetVisibleArea(scrollGroupID, x1, 0, x2, height); }
A gadget that is part of a GeDialog layout can be identified in two ways:
// add text edit field and store the C4DGadget pointer C4DGadget * const textA = AddEditText(ID_TEXT_A, BFH_SCALEFIT , 0, 10, 0); if (textA) SetString(textA, "This is some text." _s);
// add text edit field AddEditText(ID_TEXT_B, BFH_SCALEFIT , 0, 10, 0); SetString(ID_TEXT_B, "This is some other text." _s);
Default GUI gadgets can be added to a GeDialog with these member functions:
Number related gadgets:
Text related gadgets:
Color related gadgets:
Buttons:
Seperators:
Further gadgets are:
// This example adds a list view to the GeDialog layout. private : SimpleListView _listview; public : Bool CreateLayout() { SetTitle( "Listview Dialog" _s);
// add list view element to layout AddListView(1000, BFH_SCALEFIT | BFV_SCALEFIT , 0, 0); _listview. AttachListView ( this , 1000); return true ; } Bool InitValues() { // configure listview columns BaseContainer layout; layout. SetInt32 (CHECKBOX, LV_COLUMN_CHECKBOX ); layout. SetInt32 ( NAME , LV_COLUMN_TEXT ); _listview. SetLayout (2, layout);
// don't allow multi selection _listview. SetProperty ( SLV_MULTIPLESELECTION , false );
// fill with content Int32 line = 0; BaseContainer data; data. SetBool (CHECKBOX, true ); data. SetString ( NAME , "Element A" _s); _listview. SetItem (line, data); ++line; // increment ID data. SetBool (CHECKBOX, false ); data. SetString ( NAME , "Element B" _s); _listview. SetItem (line, data);
// update _listview. DataChanged (); return true ; }
A multi-line text edit field can be created and configured with these functions:
另请参阅 Specific GUI Elements .
// This example creates a multi line edit field with Python syntax highlighting. const Int32 style = DR_MULTILINE_STATUSBAR | DR_MULTILINE_HIGHLIGHTLINE | DR_MULTILINE_WORDWRAP | DR_MULTILINE_MONOSPACED | DR_MULTILINE_PYTHON | DR_MULTILINE_SYNTAXCOLOR ; AddMultiLineEditText(4000, BFH_SCALEFIT , 0, 200, style);// set some python code SetString(4000, "import c4d\n\nprint(\"hello world\")\n" _s);
// set the cursor position at the beginning of the last line SetMultiLinePos(4000, 4, 0);
Several gadgets can contain multiple child-elements, typically for selection purposes:
// This example creates a combo box and defines the used icons.
// loading the icon data IconData data1, data2; GetIcon ( Ocube , &data1); GetIcon ( Osphere , &data2);
// creating the combo box // the address of the icon data is written into the String AddComboBox(5001, BFH_LEFT , 100, 10, false ); const String iconData1Address = String::HexToString (( UInt ) & data1); AddChild(5001, 0, "Cube &" + iconData1Address + "&" ); const String iconData2Address = String::HexToString (( UInt ) & data2); AddChild(5001, 1, "Sphere &" + iconData2Address + "&" );
Further interaction with gadgets is typically done by sending messages to the gadget:
另请参阅 GUI and Interaction Messages Manual .
// This example creates a "Progress Bar" custom GUI element. const Int32 flags = BFH_LEFT | BFV_FIT ; const BaseContainer settings; AddCustomGui(10000, CUSTOMGUI_PROGRESSBAR , String (), flags, SizePix (100), SizePix (12), settings);// This example sends a message to the progress bar custom GUI element. BaseContainer m( BFM_SETSTATUSBAR ); m.SetBool( BFM_STATUSBAR_PROGRESSON , true ); m.SetFloat( BFM_STATUSBAR_PROGRESS , _someValue); m.SetData( BFM_STATUSBAR_TINT_COLOR , 向量 (0.0, 0.0, 1.0)); SendMessage(10000, m);
There is no default gadget to display an image ( BaseBitmap ) in a GeDialog . Two possible solutions are:
Further gadgets are implemented as custom GUI elements. Such custom GUI elements have to be created using their type ID.
// This example accesses a custom GUI element that is part of the GeDialog. // The value presented in the GUI element is first set using the specific GUI element class. // Alternatively one can also set the value using the BaseCustomGui base class.
// search for custom gui gadget void * const customGUI = FindCustomGui(ID_GRADIENT, CUSTOMGUI_GRADIENT );
// cast into specific class GradientCustomGui * const gradientGUI = static_cast< GradientCustomGui * > (customGUI); if (gradientGUI) { // set data AutoAlloc<Gradient> gradientData; if (gradientData) { // set gradient data using the GradientCustomGui class function
// add a knot GradientKnot firstKnot; firstKnot. pos = 0.25; firstKnot. col = 向量 (1.0, 0, 0); // red gradientData-> InsertKnot (firstKnot); gradientGUI-> SetGradient (gradientData);
// set gradient data using the BaseCustomGui class function
// add a knot GradientKnot secondKnot; secondKnot. pos = 0.75; secondKnot. col = 向量 (0, 0, 1.0); // blue gradientData-> InsertKnot (secondKnot);
// store as GeData GeData geData; geData. SetCustomDataType ( CUSTOMDATATYPE_GRADIENT , gradientData);
// store as TriState TriState<GeData> triStateData; triStateData. 添加 (geData);
// set data of the GUI element gradientGUI-> SetData (triStateData); } }
GeUserArea is the base class for all dialog gadgets. A subclass of GeUserArea defines a new custom gadget. Such a custom gadget can be added to the GeDialog .
另请参阅 GeUserArea Manual .
// This example adds a user area (that is owned by the GeDialog) to the layout. C4DGadget * userarea = this->AddUserArea(12000, BFH_LEFT , 300, 100); if (userarea) this->AttachUserArea(_userArea, userarea);It is possible to add a sub-dialog to a given GeDialog based window. Such a sub-dialog is based on SubDialog which in return is also based on GeDialog .
For convenience it is possible to add a default group of gadgets to the dialog. This group can contain the standard buttons "OK" or"Cancel". See DLG .
// The "Command" function is called when a button is pressed. Bool Command( Int32 id , const BaseContainer & msg) { switch ( id ) { // the "OK" button of a AddDlgGroup() group, IDC_CANCEL is the other case IDC_OK : { ApplicationOutput ( "OK was pressed" ); break ; } } return true ; }
For most gadgets it is possible to define the size of the gadget. To define this size one must use these functions to bake the pixel size:
The position and behaviour of groups and gadgets is defined with these flags:
Horizontal alignment:
Vertical alignment:
// the parent group with three columns GroupBegin(20000, BFH_SCALEFIT , 3, 1, String (), BFV_GRIDGROUP_ALLOW_WEIGHTS );
// left group GroupBegin(21000, BFH_LEFT | BFV_SCALEFIT , 1, 1, String (), 0, 100); AddButton(21100, BFH_SCALEFIT | BFH_SCALEFIT , 0, 0, "" _s); GroupEnd();
// center group GroupBegin(22000, BFH_SCALEFIT | BFV_SCALEFIT , 1, 1, String (), 0); AddButton(22100, BFH_SCALEFIT | BFH_SCALEFIT , 0, 0, "" _s); GroupEnd();
// right group GroupBegin(23000, BFH_RIGHT | BFV_SCALEFIT , 1, 1, String (), 0, 100); AddButton(23100, BFH_SCALEFIT | BFH_SCALEFIT , 0, 0, "" _s); GroupEnd(); GroupEnd();
GUI elements are used to display values and to allow user interaction to change these values. For default GUI elements there are three kinds of functions to edit these values:
Editing Boolean values:
Editing integer values:
Editing float values:
Editing Vector values:
Editing Time values:
编辑 String values:
编辑 Filename values: These functions just wrap around GeDialog::GetString() and GeDialog::SetString() .
Editing Color values:
// add a text field and define the text AddEditText(1000, BFH_SCALEFIT , 0, 10, 0); SetString(1000, "Hello World" _s);
// add a number field and set the value using a TriState object AddEditNumber(2000, BFH_SCALEFIT , 0, 10); TriState<Int32> numberData; numberData. 添加 (100); numberData. 添加 (200); SetInt32(2000, numberData);
A GeDialog receives messages from both its gadget and from the Cinema 4D GUI. They are sent to GeDialog::Message() .
见 GUI and Interaction Messages Manual .
// This example catches the event when the "F1" key is pressed in GeDialog::Message(). case BFM_INPUT : { // check if this event was triggered by some keyboard interaction if (msg. GetInt32 ( BFM_INPUT_DEVICE ) == BFM_INPUT_KEYBOARD ) { // check if the "F1" triggered the event if (msg. GetInt32 ( BFM_INPUT_CHANNEL ) == KEY_F1 ) { ApplicationOutput ( "Pressed \"F1\" key." _s); return true ; } } break ; }When a gadget is changed it sends a message to the parent GeDialog . This message can be caught in GeDialog::Command() .
见 GUI and Interaction Messages Manual .
// This example adds a button to the layout. AddButton(ID_BUTTON_ACTION, BFH_SCALEFIT , 0, 20, "Button" _s);// The "Command" function is called when the button is pressed. Bool Command( Int32 id , const BaseContainer & msg) { if ( id == ID_BUTTON_ACTION) { ApplicationOutput ( "Button pressed" ); }
When a gadget is changed one might need to know the state of the mouse or keyboard when this happened.
// get String value if (GetString(1000, value)) { // get state of the "Enter" key. BaseContainer state; GetInputState ( BFM_INPUT_KEYBOARD , KEY_ENTER , state);
// check if "Enter" key is pressed if (state. GetInt32 ( BFM_INPUT_VALUE )) { ApplicationOutput ( "Value: " + value); } } }
// This example catches an interaction message in GeDialog::Message(). If the // left mouse button is pressed more mouse events are processed via GeDialog::GetInputState(). // After the left mouse button is released all queued events are freed. Int32 Message( const BaseContainer & msg, BaseContainer & result) { // messages are identified by the BaseContainer ID switch (msg. GetId ()) { // interaction event case BFM_INPUT : { // check if mouse event if (msg. GetInt32 ( BFM_INPUT_DEVICE ) == BFM_INPUT_MOUSE ) { // check if left mouse button if (msg. GetInt32 ( BFM_INPUT_CHANNEL ) == BFM_INPUT_MOUSELEFT ) { // save initial start position Int32 xPos = msg. GetInt32 ( BFM_INPUT_X ); Int32 yPos = msg. GetInt32 ( BFM_INPUT_Y ); BaseContainer res;
// loop and process queued events while ( GetInputState ( BFM_INPUT_MOUSE , BFM_INPUT_MOUSELEFT , res)) { // check if left mouse button is still pressed if (!res. GetInt32 ( BFM_INPUT_VALUE )) break ;
// get coordinates const Int32 currentX = res. GetInt32 ( BFM_INPUT_X ); const Int32 currentY = res. GetInt32 ( BFM_INPUT_Y );
// compare coordinates const Bool xPosChanged = currentX != xPos; const Bool yPosChanged = currentY != yPos; if (xPosChanged || yPosChanged) { ApplicationOutput ( "Mouse dragged and moved" ); xPos = currentX; yPos = currentY; } }
// delete all other events that might have occurred in the meantime KillEvents(); return true ; } } break ; } } return SUPER::Message(msg, result); }
The user can drag and drop various elements onto a GeDialog 。 GeDialog is informed about this event through messages sent to GeDialog::Message() . These functions are used to react to these messages:
另请参阅 Drag and Drop .
// This example catches a Drag&Drop message. // If the dragged element is a C4DAtom the name of the element is displayed in a text field. Int32 Message( const BaseContainer & msg, BaseContainer & result) { // messages are identified by the BaseContainer ID switch (msg. GetId ()) { case BFM_DRAGRECEIVE : { // Check if the drag is over a certain gadget if (CheckDropArea(ID_TEXT_NAME, msg, true , true )) { void * object = nullptr ; Int32 type;// get the dragged element if (!GetDragObject(msg, &type, & object )) return false ;
// if the drag is finished set the text gadget const Bool typeIsAtom = type == DRAGTYPE_ATOMARRAY ; const Int32 isFinished = msg. GetInt32 ( BFM_DRAG_FINISHED ); if (typeIsAtom && isFinished) { const AtomArray * const atomArray = static_cast< AtomArray * > (object);
// check if the AtomArray can be accessed and if it contains any objects if (atomArray && atomArray-> GetCount () > 0) { C4DAtom * const atom = atomArray-> GetIndex (0);
// check if the given C4DAtom is a BaseList2D element if (atom && atom-> IsInstanceOf ( Tbaselist2d )) { BaseList2D * const baselist = static_cast< BaseList2D * > (atom); SetString(ID_TEXT_NAME, baselist-> GetName ()); } } return true ; } else { return SetDragDestination( MOUSE_POINT_HAND ); } } return SetDragDestination( MOUSE_FORBIDDEN ); } } return SUPER::Message(msg, result); }
A GeDialog can also receive core messages. These messages are sent to inform the dialog about global events e.g. when something in the active document changed. The messages are sent to GeDialog::CoreMessage() .
另请参阅 GUI and Interaction Messages Manual and Core Messages Manual .
// This example catches the core message EVMSG_CHANGE and re-initializes the dialog's values. // This is typically done to update GUI elements that correspond to certain scene elements. Bool CoreMessage( Int32 id , const BaseContainer & msg) { switch ( id ) { case EVMSG_CHANGE : { // check if this core message is new if (!CheckCoreMessage(msg)) break ; this->InitValues(); break ; } } return GeDialog::CoreMessage ( id , msg); } Bool InitValues() { // set default value SetString(1000, "---" _s);// access active document and object BaseDocument * const doc = GetActiveDocument (); if (doc == nullptr ) return true ; BaseObject * const object = doc-> GetActiveObject (); if ( object == nullptr ) return true ;
// set string value SetString(1000, object-> GetName ()); return true ; }
A GeDialog can be the base of a sub-dialog or a custom GUI element. In this case it must send messages to a parent dialog. The typical use case is a custom GUI element (based on CustomGuiData , iCustomGui ) that has to inform the parent dialog that a stored value has changed.
// construct the message BaseContainer message( BFM_ACTION ); message.SetInt32( BFM_ACTION_ID , GetId()); message.SetData( BFM_ACTION_VALUE , _value);
// send the message SendParentMessage(message);
These utility functions allow to access the dimensions of a gadget or to transfer given coordinates into various spaces:
// construct position of the pop up menu x += w; Local2Screen(&x, &y);
// define pop up menu BaseContainer bc; bc. InsData (5159, "CMD" ); // cube bc. InsData (0, String ()); bc. InsData (5160, "CMD" ); // sphere
// show pop up menu ShowPopupMenu ( Get (), x, y, bc); }
Color related functions are:
c4d_colors.h
.