GeDialog Manual

Table of Contents

• About
• Allocation
• GeDialog Based Classes
• Read-Only Properties
• Layout
  • Create Layout
  • Menus
  • Groups
  • Gadget IDs
  • Default Gadgets
  • Images
  • Custom GUI Elements
  • GeUserAreas
  • Sub-Dialogs
  • Pixel Size
  • Layout Flags
• Gadget Values
• Interaction
  • Messages
  • Interaction with Gadgets
  • Drag and Drop
  • Core Messages
  • GeDialog Parent
• Utility
  • Coordinates
  • Colors
• Further Reading

About

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 parameters.

Allocation

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.
 
class OpenExampleDialog : public CommandData
{
  INSTANCEOF(OpenExampleDialog, CommandData)
 
private:
  ExampleDialog _dialog;
 
public:
  // "Execute" function opens the dialog window
  Bool Execute(BaseDocument* doc, GeDialog* parentManager)
  {
    // open the dialog window if it is not already open
    if (_dialog.IsOpen() == false)
      _dialog.Open(DLG_TYPE::ASYNC, g_geDialogID, -1, -1, 400, 400);
    else
      _dialog.Close();
 
    return true;
  };
 
  // "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:

• DLG_TYPE::MODAL : A modal dialog. On OSX this does not include a standard "Close" icon.
• DLG_TYPE::MODAL_RESIZEABLE : A resizeable modal dialog.
• DLG_TYPE::ASYNC : A resizeable, asynchronous dialog. Typical Cinema 4D manager windows are such asynchronous dialogs.
• DLG_TYPE::ASYNC_POPUP_RESIZEABLE : Resizeable asynchronous dialog without title bar.
• DLG_TYPE::ASYNC_POPUPEDIT : Fixed asynchronous dialog without title bar.
• DLG_TYPE::ASYNC_FULLSCREEN_WORK : Fullscreen asynchronous window over desktop area.
• DLG_TYPE::ASYNC_FULLSCREEN_MONITOR : Fullscreen asynchronous window over monitor area.

The GeDialog window can be closed with GeDialog::Close(). This will call GeDialog::AskClose() (see below).

GeDialog Based Classes

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:

• GeDialog::CreateLayout(): Creates the dialog layout, see Create Layout.
• GeDialog::InitValues(): Initializes the values stored and displayed in the GeDialog.
• GeDialog::DestroyWindow(): Called when the dialog is temporarily closed; GeDialog::CreateLayout() will be called when the dialog is restored.

  // create the layout
  Bool CreateLayout()
  {
    SetTitle("Example Dialog"_s);
 
    AddEditNumber(1000, BFH_SCALEFIT, 0, 10);
 
    // 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:

• GeDialog::CoreMessage(): Receives core messages, see Core Messages Manual.
• GeDialog::Command(): Receives commands from the dialog's GUI elements.
• GeDialog::Message(): Receives various GUI and interaction messages, see GUI and Interaction Messages Manual.
• GeDialog::AskClose(): Called when the dialog should be closed.

  // This "Command" function checks if the gadget with the ID 1000 was changed.
 
  Bool Command(Int32 id, const BaseContainer& msg)
  {
    if (id == 1000)
    {
      ApplicationOutput("Gadget 1000 was changed.");
    }
 
    return GeDialog::Command(id, msg);
  }
 
  // 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:

• GeDialog::Timer(): Called in intervals set with GeDialog::SetTimer().

  // This "Timer" function is called depending on the value set with SetTimer()
  void Timer(const BaseContainer& msg)
  {
    ApplicationOutput("Tick..");
  }

Read-Only Properties

It is possible to check these GeDialog properties:

• GeDialog::IsOpen(): Returns true if the dialog is currently open.
• GeDialog::IsVisible(): Returns true if the dialog is visible.
• GeDialog::CheckClose(): Returns true if the dialog can be closed.

It is also possible to read the pixel ratio of the current screen:

• GeDialog::GetPixelRatio(): Returns the screen pixel ratio to indicate Retina displays.

    // This example adds a BitmapButton to the layout of the GeDialog.
    // Depending on the pixel ratio a low-res or high-res bitmap file is loaded
    // and applied to the BitmapButton.
 
    void* const customGUI = AddCustomGui(1000, CUSTOMGUI_BITMAPBUTTON, ""_s, BFH_SCALEFIT, 300, 300, settings);
    BitmapButtonCustomGui* const bitmapButtonGUI = static_cast<BitmapButtonCustomGui*>(customGUI);
 
    if (bitmapButtonGUI)
    {
      // allocate bitmap
      AutoAlloc<BaseBitmap> bitmap;
      if (bitmap)
      {
        String filename = "";
 
        // 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);
        }
      }
    }

Layout

Create Layout

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.

• GeDialog::LoadDialogResource(): Loads and applies a dialog resource file. See Resource Files Manual.
• GeDialog::SetTitle(): Sets the title of the dialog window.

General functions to handle GeDialog gadgets are:

• GeDialog::Activate(): Sets the focus to the given gadget.
• GeDialog::IsActive(): Returns true if the given gadget has the focus.
• GeDialog::RemoveElement(): Removes the given gadget from the layout.
• GeDialog::HideElement(): Hides the given gadget.
• GeDialog::Enable(): Enables or disables the given gadget.
• GeDialog::IsEnabled(): Returns true if the given gadget is enabled.

  // This example loads a dialog layout from a resource file and edits it.
 
  Bool CreateLayout()
  {
    // call default CreateLayout()
    if (!GeDialog::CreateLayout())
      return false;
 
    // 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;
  }

Menus

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:

• GeDialog::MenuFlushAll(): Flushes the content of the menu bar.
• GeDialog::MenuFinished(): Has to be called when all menus and all items have been added.
• GeDialog::MenuSetResource(): Loads the menu from a given menu ID.

Sub-menus are added with these functions:

• GeDialog::MenuSubBegin(): Adds a new sub-menu.
• GeDialog::MenuSubEnd(): Closes the current sub-menu.

Menu items are added with these functions:

• GeDialog::MenuAddCommand(): Adds a command item referencing a Cinema 4D command. See also Command Utility Manual.
• GeDialog::MenuAddString(): Adds a string item. GeLoadString() is used to load strings from *.str files.
• GeDialog::MenuAddSeparator(): Adds a separator.
• GeDialog::MenuInitString(): Sets the checked and enabled state of menu items.

    // This example creates two sub-menus.
 
    MenuFlushAll();
 
    // 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:

• GeDialog::GroupBeginInMenuLine(): Begins a sub-group on the right side of the menu bar.

    // This example adds a group to the menu bar.
    // This menu group contains a button.
 
    GroupBeginInMenuLine();
 
    GroupBegin(1000, BFH_RIGHT, 2, 1, ""_s, 0);
    AddButton(ID_MENU_BUTTON, BFH_SCALEFIT, 0, 10, "Button"_s);
    GroupEnd();
 
    GroupEnd();

Groups

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:

• GeDialog::GroupBegin(): Begins a new group. See flags BFV_GROUP.
• GeDialog::GroupEnd(): Closes the current group.
• GeDialog::TabGroupBegin(): Begins a new tab group.

    // This example creates a group with two columns.
    // The subgroup within the left column contains a tab group with two tabs.
 
    // 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:

• GeDialog::GroupSpace(): Defines the space between elements inside the group.
• GeDialog::GroupBorderSpace(): Defines the space around the group.
• GeDialog::GroupBorder(): Defines the border type of the current group. See also BORDER.
• GeDialog::GroupBorderNoTitle(): Defines the border type of the current group without displaying the title. See also BORDER.

    // This example creates a group with space settings and a border.
 
    GroupBegin(600, BFH_SCALEFIT, 2, 1, "Group"_s, BFV_BORDERGROUP_CHECKBOX, 0, 100);
 
    GroupSpace(100, 0);               // space between group elements
    GroupBorder(BORDER_GROUP_IN);     // group border
    GroupBorderSpace(10, 10, 10, 10); // space around the group
 
    AddButton(601, BFH_SCALEFIT | BFV_SCALEFIT, 0, 0, "Button A"_s);
    AddButton(602, BFH_SCALEFIT | BFV_SCALEFIT, 0, 0, "Button B"_s);
 
    GroupEnd();

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.

• GeDialog::GroupWeightsSave(): Retrieves the weights of the given group.
• GeDialog::GroupWeightsLoad(): Sets the weights of the given group.

See also 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:

• GeDialog::LayoutFlushGroup(): Removes all gadgets from the given group and re-starts this group.
• GeDialog::LayoutChanged(): Notifies the dialog that the layout has changed.
• GeDialog::LayoutChangedNoRedraw(): Notifies the dialog that the layout has changed without redrawing the dialog.
• GeDialog::BeginLayoutChange(): Returns a UpdateDialogHelper object to flush and re-layout the given gadget.
• GeDialog::LayoutFlushDisableRedraw(): Used to flush a group.

    // This example flushes a layout group and fills it 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:

• GeDialog::ScrollGroupBegin(): Begins a scrollable group.
• GeDialog::GetVisibleArea(): Gets the visible area of the given scroll group.
• GeDialog::SetVisibleArea(): Sets the visible area of the given scroll group.

Note

A scroll group must always contain another sub-group that stores the actual gadgets.

See also 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);
    }

Note that GeDialog::GetItemDim will take scrollbars of a scroll group into account, while GeDialog::SetVisibleArea will not. When computing the scroll area of a scroll group, e.g., for centering a gadget inside the scroll group, this must be taken into account, as otherwise GeDialog::SetVisibleArea will on scroll frames that are larger than the visible area.

  maxon::Result<void> CenterScrollGroup(const Int32 idScrollGroup, const Int32 idGadget)
  {
    iferr_scope;
    // Get the gadget dimensions of the scroll group and the gadget. 
    Int32 sgx, sgy, scrollWidth, scrollHeight;
    Int32 gx, gy, gadgetWidth, gadegtHeight;
    if (!GetItemDim(idScrollGroup, &sgx, &sgy, &scrollWidth, &scrollHeight) ||
      !GetItemDim(idGadget, &gx, &gy, &gadgetWidth, &gadegtHeight))
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not get item dimensions."_s);
 
    // GetItemDim() takes the scrollbars of a gadget into account, but SetVisibleArea() does not, 
    // since the scrollbars are not part of the visible area. So, when it's about to center something,
    // or mix these two methods in any other way, these scrollbars need to be taken into account.
 
    // Compute the scroll bars as the delta between the visible are of the the scroll group and its
    // total size.
    Int32 svax1, svay1, svax2, svay2;
    if (!GetVisibleArea(idScrollGroup, &svax1, &svay1, &svax2, &svay2))
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION,
      "Could not get visible area of scroll group."_s);
    Int32 dx = (scrollWidth - (svax2 - svax1));
    Int32 dy = (scrollHeight - (svay2 - svay1));
 
    // Subtract the deltas from the width and height of the scroll group, compute the x and y offsets
    // for a centered gadget.
    Int32 realScrollWidth = scrollWidth - dx;
    Int32 realScrollHeight = scrollHeight - dy;
    Int32 x = static_cast<Int32>(((gadgetWidth - realScrollWidth) * .5));
    Int32 y = static_cast<Int32>(((gadegtHeight - realScrollHeight) * .5));
 
    // With that information, center the scroll group on the gadget.
    if (!SetVisibleArea(idScrollGroup, x, y, x + realScrollWidth, y + realScrollHeight))
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION,
      "Could not set visible area of scroll group."_s);
    return maxon::OK;
  }

Gadget IDs

A gadget that is part of a GeDialog layout can be identified in two ways:

• With a GadgetPtr. This GadgetPtr is returned by functions creating the gadget in question.
• With the gadget ID. This gadget ID is used with the function that creates the gadget in question.

    // This example creates two text edit fields.
    // One edit field is edited using the C4DGadget pointer,
    // the other using just the ID.
 
    // 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 Gadgets

Default GUI gadgets can be added to a GeDialog with these member functions:

Number related gadgets:

• GeDialog::AddEditNumber(): Adds a number field.
• GeDialog::AddEditNumberArrows(): Adds a number field with arrows.
• GeDialog::AddEditSlider(): Adds a number field with a slider.
• GeDialog::AddSlider(): Adds a slider.

Text related gadgets:

• GeDialog::AddStaticText(): Adds a static text field.
• GeDialog::AddEditText(): Adds an editable text field

Color related gadgets:

• GeDialog::AddColorField(): Adds a color field.
• GeDialog::AddColorChooser(): Adds a color chooser.

Buttons:

• GeDialog::AddButton(): Adds a button.
• GeDialog::AddArrowButton(): Adds a small arrow button.

Seperators:

• GeDialog::AddSeparatorH(): Adds a horizontal separator.
• GeDialog::AddSeparatorV(): Adds a vertical separator.

Further gadgets are:

• GeDialog::AddCheckbox(): Adds a checkbox.
• GeDialog::AddEditShortcut(): Adds a shortcut edit field.
• GeDialog::AddListView(): Adds a list view (SimpleListView).

    // This example just adds some generic gadgets to the layout.
 
    AddCheckbox(1000, BFH_SCALEFIT, 0, 10, "Checkbox"_s);
    AddButton(2000, BFH_SCALEFIT, 0, 10, "Button"_s);
 
    AddSeparatorH(0, BFH_SCALEFIT);
 
    AddEditText(3000, BFH_SCALEFIT, 0, 10, 0);

  // 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:

• GeDialog::AddMultiLineEditText(): Adds a multi line edit field.
• GeDialog::SetMultiLineMode(): Sets the script mode of the given field, see SCRIPTMODE.
• GeDialog::SetMultiLineLock(): Locks the given field.
• GeDialog::SetMultiLinePos(): Sets the position of the cursor in the given field.

See also 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:

• GeDialog::AddRadioGroup(): Adds a radio group.
  • GeDialog::AddRadioButton(): Adds a radio button.
  • GeDialog::AddRadioText(): Adds a radio text field.
• GeDialog::AddComboBox(): Adds a combo box.
• GeDialog::AddComboButton(): Adds a combo button.
• GeDialog::AddPopupButton(): Adds a popup button.
• GeDialog::AddChild(): Adds a child element to the given gadget.
• GeDialog::AddChildren(): Adds multiple children stored in a BaseContainer to the given gadget.
• GeDialog::FreeChildren(): Deletes the child elements of the given gadget.

    // This example creates a combo box and a combo button.
 
    AddComboBox(5000, BFH_LEFT, 100, 10, false);
    AddChild(5000, 0, "Child 0"_s);
    AddChild(5000, 1, "Child 1"_s);
    AddChild(5000, 2, "Child 2"_s);
 
    AddComboButton(6000, BFH_LEFT, 100, 10, 0);
 
    BaseContainer children;
    children.SetString(0, "Child 0"_s);
    children.SetString(1, "Child 1"_s);
    AddChildren(6000, children);

    // 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:

• GeDialog::SendMessage(): Sends a message to a dialog gadget.

See also 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, Vector(0.0, 0.0, 1.0));
 
    SendMessage(10000, m);

Images

There is no default gadget to display an image (BaseBitmap) in a GeDialog. Two possible solutions are:

• To use a custom gadget based on GeUserArea to draw the BaseBitmap, see GeUserArea Manual.
• Or to use a BitmapButtonCustomGui custom GUI element.

        // This example creates a BitmapButtonCustomGui to present an image.
 
        const Int32 flags  = BFH_CENTER;
        const Int32 width  = SizePix(300);
        const Int32 height = SizePix(50);
 
        BaseContainer settings;
        settings.SetBool(BITMAPBUTTON_BUTTON, false);
 
        void* const customGUI = AddCustomGui(5050, CUSTOMGUI_BITMAPBUTTON, ""_s, flags, width, height, settings);
        BitmapButtonCustomGui* const bitmapButtonGUI = static_cast<BitmapButtonCustomGui*>(customGUI);
 
        if (bitmapButtonGUI)
        {
          bitmapButtonGUI->SetImage(buttonBitmap, true, false);
        }

Custom GUI Elements

Further gadgets are implemented as custom GUI elements. Such custom GUI elements have to be created using their type ID.

• GeDialog::AddCustomGui(): Adds a custom GUI element of the given type.
• GeDialog::FindCustomGui(): Finds a custom GUI element with the given ID and the given type.

See Custom GUI Elements.

Note

A custom GUI is typically configured using a BaseContainer given to GeDialog::AddCustomGui(). Only the parameters accessible with the custom GUI class itself can be changed afterwards.

Custom GUI element instances are based on BaseCustomGui. Using this base class it is possible to further edit the instance.

Some "custom GUIs" are no real custom GUI elements but are hardcoded in the DescriptionCustomGui and cannot be used in a GeDialog (e.g. CUSTOMGUI_VECTOR).

    // This example creates and configures a "Hyperlink" custom GUI element.
 
    BaseContainer hlSettings;
    hlSettings.SetBool(HYPERLINK_IS_LINK, true);
 
    const Int32 customGuiID = CUSTOMGUI_HYPER_LINK_STATIC;
 
    void* const customGui = AddCustomGui(11000, customGuiID, String(), BFH_SCALEFIT, 100, 50, hlSettings);
    HyperLinkCustomGui* const linkGustomGui = static_cast<HyperLinkCustomGui*>(customGui);
 
    if (linkGustomGui != nullptr)
    {
      const String linkTitle { "MAXON" };
      const String url { "https://www.maxon.net" };
 
      linkGustomGui->SetLinkString(&url, &linkTitle);
    }

    // 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
        maxon::GradientKnot firstKnot;
        firstKnot.pos = 0.25;
        firstKnot.col = maxon::Color(1.0, 0, 0);  // red
        gradientData->InsertKnot(firstKnot);
 
        gradientGUI->SetGradient(gradientData);
 
        // set gradient data using the BaseCustomGui class function
 
        // add a knot
        maxon::GradientKnot secondKnot;
        secondKnot.pos = 0.75;
        secondKnot.col = maxon::Color(0, 0, 1.0); // blue
        gradientData->InsertKnot(secondKnot);
 
        // store as GeData
        GeData geData;
        geData.SetCustomDataType<Gradient>(gradientData);
 
        // store as TriState
        TriState<GeData> triStateData;
        triStateData.Add(geData);
 
        // set data of the GUI element
        gradientGUI->SetData(triStateData);
      }
    }

GeUserAreas

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.

• GeDialog::AddUserArea(): Adds a user area to the dialog layout.
• GeDialog::AttachUserArea(): Connects the user area gadget with the actual user area instance.

See also 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);

Sub-Dialogs

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.

• GeDialog::AddSubDialog(): Adds a sub-dialog to the dialog layout.
• GeDialog::AttachSubDialog(): Connects the sub-dialog gadget with the actual sub-dialog instance.

    // This example adds a SubDialog based sub-dialog to the layout.
 
    AddSubDialog(14000, BFH_SCALEFIT | BFV_SCALEFIT);
    AttachSubDialog(&_subDialog, 14000);

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.

• GeDialog::AddDlgGroup(): Adds a group with standard buttons to the dialog.

    // This example adds the generic "OK" and "Cancel" buttons to the layout.
 
    AddDlgGroup(DLG_OK | DLG_CANCEL);

  // 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;
  }

Pixel Size

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:

• SizePix(): Bakes the given pixel size.
• SizeChr(): Bakes the given character count into a size.
• SizePixChr(): Bakes the given pixel size and character count.

    // This example creates a button with a height of 50 pixels.
 
    AddButton(15000, BFH_SCALEFIT, 0, SizePix(50), ""_s);

Layout Flags

The position and behaviour of groups and gadgets is defined with these flags:

Horizontal alignment:

• BFH_CENTER: Centered horizontally.
• BFH_LEFT: Aligned to the left.
• BFH_RIGHT: Aligned to the right.
• BFH_FIT: Fit. (BFH_LEFT|BFH_RIGHT)
• BFH_SCALE: Scale if there is more space.
• BFH_SCALEFIT: Scale fit. (BFH_SCALE|BFH_FIT)
• BFH_MASK: Masks out flags.

Vertical alignment:

• BFV_CENTER: Centered vertically.
• BFV_TOP: Aligned to the top.
• BFV_BOTTOM: Aligned to the bottom.
• BFV_FIT: Fit. (BFV_BOTTOM|BFV_TOP)
• BFV_SCALE: Scale if there is more space.
• BFV_SCALEFIT: Scale fit. (BFV_SCALE|BFV_FIT)
• BFV_MASK: Masks out flags.

    // This example creates a group with three subgroups.
    // The left and right subgroup have a fixed width.
    // The center subgroup is scaled horizontally.
 
    // 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();

Gadget Values

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:

• Plain getter/setter: Simple functions that allow to edit the value displayed in the given gadget.
• Container getter/setter: Functions that access the value from a given BaseContainer.
• TriState setter: Functions that set the value using the given TriState object (see TriState Manual)

Editing Boolean values:

• GeDialog::GetBool(): Gets the Boolean value displayed by the given gadget.
• GeDialog::SetBool(): Sets the Boolean value displayed by the given gadget.

Editing integer values:

• GeDialog::GetInt32(): Gets the integer value displayed by the given gadget.
• GeDialog::SetInt32(): Sets the integer value displayed by the given gadget.

Editing float values:

• GeDialog::GetFloat(): Gets the float value displayed by the given gadget.
• GeDialog::SetFloat(): Sets the float value displayed by the given gadget. See FORMAT_NUMBERS.
• GeDialog::SetMeter(): Sets the float value in meters displayed by the given gadget.
• GeDialog::SetDegree(): Sets the float value in degree displayed by the given gadget.
• GeDialog::SetPercent(): Sets the float value in percent displayed by the given gadget.

Editing Vector values:

• GeDialog::GetVector(): Gets the Vector value displayed by the given gadgets. This function is just a wrapper around GeDialog::GetFloat().

Editing Time values:

• GeDialog::GetTime(): Gets the time value displayed by the given gadget.
• GeDialog::SetTime(): Sets the time value displayed by the given gadget.

Editing String values:

• GeDialog::GetString(): Gets the String value displayed by the given gadget.
• GeDialog::SetString(): Sets the String value displayed by the given gadget.

Editing Filename values: These functions just wrap around GeDialog::GetString() and GeDialog::SetString().

• GeDialog::GetFilename(): Gets the Filename value displayed by the given gadget.
• GeDialog::SetFilename(): Sets the Filename value displayed by the given gadget.

Editing Color values:

• GeDialog::GetColorField(): Gets the color value displayed by the given gadget.
• GeDialog::SetColorField(): Sets the color value displayed by the given gadget.

    // This example adds different GUI elements to the layout and sets their 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.Add(100);
    numberData.Add(200);
 
    SetInt32(2000, numberData);

Interaction

Messages

A GeDialog receives messages from both its gadget and from the Cinema 4D GUI. They are sent to GeDialog::Message().

See 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;
      }

Interaction with Gadgets

When a gadget is changed it sends a message to the parent GeDialog. This message can be caught in GeDialog::Command().

See 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.

• GeDialog::GetInputState(): Get the current state of the given input device.
• GeDialog::GetInputEvent(): Gets the next input event for the given device from the event queue.
• GeDialog::KillEvents(): Flushes all events from the window message queue.

    // This example is executed in a GeDialog::Command() function.
    // When the text gadget with the ID 1000 is changed its value is read.
    // If the "Enter" key was pressed, the value is printed to the console.
 
    if (id == 1000)
    {
      String value;
 
      // 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);
  }

Drag and Drop

The user can drag and drop various elements onto a GeDialog. The GeDialog is informed about this event through messages sent to GeDialog::Message(). These functions are used to react to these messages:

• GeDialog::CheckDropArea(): Returns true if the drag event is over the given gadget.
• GeDialog::GetDragPosition(): Gets the coordinates of the drag event.
• GeDialog::GetDragObject(): Gets the object that is dragged.
• GeDialog::SetDragDestination(): Sets the cursor that should be displayed. See MOUSE.

See also 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);
  }

Core Messages

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

• GeDialog::CheckCoreMessage(): Speedup function that checks if the given core message is new or has been already processed.

See also 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;
  }

GeDialog Parent

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.

• GeDialog::SendParentMessage(): Sends a message to the parent dialog.
• GeDialog::GetId(): Returns the ID of the dialog. Typically needed in a custom GUI element to send the message BFM_ACTION_ID.

        // This example sends a message from a GeDialog (iCustomGui)
        // to the parent GeDialog to inform about change of stored value.
 
        // construct the message
        BaseContainer message(BFM_ACTION);
        message.SetInt32(BFM_ACTION_ID, GetId());
        message.SetData(BFM_ACTION_VALUE, _value);
 
        // send the message
        SendParentMessage(message);

Utility

Coordinates

These utility functions allow to access the dimensions of a gadget or to transfer given coordinates into various spaces:

• GeDialog::GetItemDim(): Gets the dimensions of the given gadget.
• GeDialog::Local2Global(): Transforms the given local coordinates into global space.
• GeDialog::Global2Local(): Transforms the given global coordinates into local space.
• GeDialog::Screen2Local(): Transforms the given screen coordinates into local space.
• GeDialog::Local2Screen(): Transforms the given local coordinates into screen space.

    // This example catches the event when the button with the ID 4000 is pressed.
    // The dimensions of the button are accessed and transferred into screen space
    // so a pop up menu can be displayed beside it.
 
    if (id == 4000)
    {
      // get button dimensions
      Int32 x, y, w, h = 0;
      GetItemDim(id, &x, &y, &w, &h);
 
      // 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);
    }

Colors

Color related functions are:

• GeDialog::GetColorRGB(): Gets the color value for the given color ID. See c4d_colors.h.
• GeDialog::SetDefaultColor(): Sets the value of a color ID for the given gadget.

    // This example edits the color of the text gadget with the ID 1000.
    // The text color is set to red.
 
    SetDefaultColor(1000, COLOR_TEXT_EDIT, Vector(1.0, 0.0, 0.0));

Further Reading

• Resource Files Manual
• GeUserArea Manual
• GUI and Interaction Messages Manual
• TriState Manual
• Core Messages Manual