GUI and Interaction Messages Manual

Table of Contents

• About
• Message Redirection
  • GeDialog
  • GeUserArea
• Return Values
• User Interaction
  • Cursor
  • Focus
  • Close Dialog
  • GeDialog Gadget Interaction
  • Mouse and Keyboard Interaction
  • Drag and Drop
  • Description Notifications
• Layout Messages
  • Layout Change
  • Weights
  • Fading
  • Draw
  • Visibility
• Specific GUI Elements
  • Text Edit Fields
  • Status Bar
  • Pop Up
  • Scroll Group
  • Custom GUI Elements
• Core Messages
• Further Reading

About

Communication between different parts of the Cinema 4D GUI happens through multiple messages. These messages are sent to GeDialog and GeUserArea elements:

• Messages are sent from Cinema 4D's GUI and event system to dialogs (GeDialog::Message())
• Messages are sent from dialogs to their gadgets (GeDialog::SendMessage())
• Messages are sent from dialogs to a parent dialog or the GUI and event system (GeDialog::SendParentMessage())
• Messages are sent from the GUI or dialogs to gadgets (GeUserArea::Message())
• Messages are sent from gadgets to the parent dialog. (GeUserArea::SendParentMessage() to GeDialog::Command())

Messages are represented by BaseContainer objects that store the parameters of the message. The ID of the message is typically the ID of the BaseContainer (BaseContainer::GetId()). See BaseContainer Manual.

For details on GeDialog and GeUserArea see GeDialog Manual and GeUserArea Manual.

  // This example catches a message to set the cursor when the mouse is over the user area.
 
  Int32 Message(const BaseContainer& msg, BaseContainer& result)
  {
    // messages are identified by the BaseContainer ID
    switch (msg.GetId())
    {
      case BFM_GETCURSORINFO:
      {
        result.SetId(BFM_GETCURSORINFO);
        result.SetInt32(RESULT_CURSOR, MOUSE_POINT_HAND);
        result.SetString(RESULT_BUBBLEHELP, "This is an example GeUserArea"_s);
 
        return true;
      }
    }
 
    return GeUserArea::Message(msg, result);
  }

Message Redirection

All message are first sent to the object's "Message" function (GeDialog::Message(), GeUserArea::Message()). If the messages are not handled in the implementation of the "Message" function they will be also handled in the base-class. Certain messages are re-directed to dedicated functions.

GeDialog

Several messages sent to a GeDialog will invoke these member functions:

Message	Function
BFM_INIT	GeDialog::CreateLayout()
BFM_DESTROY	GeDialog::DestroyWindow()
BFM_INITVALUES	GeDialog::InitValues()
BFM_SYNC_MESSAGE	GeDialog::CoreMessage()
BFM_CORE_MESSAGE	GeDialog::CoreMessage()
BFM_ACTION	GeDialog::Command()
BFM_CHECKCLOSE	GeDialog::AskClose()
BFM_TIMER_MESSAGE	GeDialog::Timer()

GeUserArea

Several messages sent to a GeUserArea will invoke these member functions:

Message	Function
BFM_INIT	GeUserArea::Init()
BFM_INITVALUES	GeUserArea::InitValues()
BFM_CALCSIZE	GeUserArea::GetMinSize()
BFM_SIZED	GeUserArea::Sized()
BFM_DRAW	GeUserArea::DrawMsg()
BFM_INPUT	GeUserArea::InputEvent()
BFM_TIMER_MESSAGE	GeUserArea::Timer()
BFM_SYNC_MESSAGE	GeUserArea::CoreMessage()
BFM_CORE_MESSAGE	GeUserArea::CoreMessage()

Return Values

Messages can be sent to receive information from the target element. In some cases the message must explicitly state that it requests a result.

• BFM_REQUIRESRESULT: This option has to be set to make sure a return value is delivered.

    // This example in a GeDialog requests the cursor position from a text edit field.
 
    // prepare message
    BaseContainer message = BaseContainer(BFM_EDITFIELD_GETCURSORPOS);
    message.SetBool(BFM_REQUIRESRESULT, true);
 
    // send message
    const GeData res = this->SendMessage(3000, message);
 
    // get position
    const Int32 pos = res.GetInt32();
    ApplicationOutput("Cursor Pos.: " + String::IntToString(pos));

User Interaction

Cursor

When the mouse cursor is moved over a GeDialog or GeUserArea a message is sent to these elements. The reaction to this message allows to define the cursor and some help text.

• BFM_GETCURSORINFO: Message is sent to a GUI element when the cursor is moved over it.

The parameters of the message are:

• RESULT_CURSOR: The cursor ID, see MOUSE.
• RESULT_BUBBLEHELP: The bubble help text.
• RESULT_BUBBLEHELP_TITLE: The bubble help title.
• RESULT_SUPPRESSBUBBLE: Set to true if the bubble help should be suppressed.

Note

The message BFM_GETCURSORINFO also contains BFM_DRAG_SCREENX and BFM_DRAG_SCREENY.

      // This example sets the cursor when the mouse is over the current GUI element.
 
      case BFM_GETCURSORINFO:
      {
        result.SetId(BFM_GETCURSORINFO);
        result.SetInt32(RESULT_CURSOR, MOUSE_POINT_HAND);
        result.SetString(RESULT_BUBBLEHELP_TITLE, "Bubblehelp Title"_s);
        result.SetString(RESULT_BUBBLEHELP, "This is the bubble help text."_s);
 
        return true;
      }

Compare also ToolData::GetCursorInfo(), SceneHookData::GetCursorInfo(), etc.

The message BFM_CURSORINFO_REMOVE can be sent by a custom callback function to inform a user area that the cursor has left the area:

// This example user area registers a callback function with RemoveLastCursorInfo().
// This function is called when the cursor leaves the user area. It is used to send the
// message BFM_CURSORINFO_REMOVE back to the user area to inform it about the event.
 
// declarations
static void RemoveCursorInfo();
class RemoveCursorUserArea;
 
static RemoveCursorUserArea* g_userArea = nullptr;  // static variable storing pointer to a user area
 
// user area will display a different color depending if the cursor is over the area or not
class RemoveCursorUserArea : public GeUserArea
{
public:
  RemoveCursorUserArea()
  {
    if (g_userArea == this)
      g_userArea = nullptr;
  };
 
  ~RemoveCursorUserArea() { };
 
  Int32 Message(const BaseContainer& msg, BaseContainer& result)
  {
    // messages are identified by the BaseContainer ID
    switch (msg.GetId())
    {
      case BFM_GETCURSORINFO:
      {
        // register RemoveCursorInfo() callback
        g_userArea = this;
        RemoveLastCursorInfo(RemoveCursorInfo);
 
        _cursorInside = true;
        Redraw();
        return true;
      }
      case BFM_CURSORINFO_REMOVE:
      {
        // message "BFM_CURSORINFO_REMOVE" sent by RemoveCursorInfo()
        _cursorInside = false;
        Redraw();
        break;
      }
    }
    return GeUserArea::Message(msg, result);
  }
 
  void DrawMsg(Int32 x1, Int32 y1, Int32 x2, Int32 y2, const BaseContainer& msg)
  {
    OffScreenOn();
    SetClippingRegion(x1, y1, x2, y2);
 
    // gadget color is controlled by the cursor position
 
    if (_cursorInside)
      DrawSetPen(Vector(1.0, 0.0, 0.0));
    else
      DrawSetPen(Vector(0.0, 1.0, 0.0));
 
    DrawRectangle(x1, y1, x2, y2);
  }
 
private:
  Bool _cursorInside = false; // set to true if the cursor is over the user area
};
 
// function will be called by the user area when the cursor left its area
static void RemoveCursorInfo()
{
  if (g_userArea == nullptr)
    return;
 
  // send message to the user area
  BaseContainer bc;
  g_userArea->Message(BaseContainer(BFM_CURSORINFO_REMOVE), bc);
}

Focus

A GeDialog or GeUserArea is informed when it receives or looses the focus:

• BFM_GOTFOCUS: Element got the focus.
• BFM_LOSTFOCUS: Element lost the focus.

      // This example catches focus related messages in GeDialog::Message().
      // Depending on the focus, a gadget is enabled or disabled.
 
      case BFM_GOTFOCUS:
      {
        Enable(1000, true);
        break;
      }
      case BFM_LOSTFOCUS:
      {
        Enable(1000, false);
        break;
      }

Close Dialog

A GeDialog is informed when it is about to be closed. One has to return false if it is safe to close the dialog.

• BFM_CHECKCLOSE: Calls GeDialog::AskClose().
• BFM_CHECKCLOSE_LAYOUTSWITCH: Is stored in the BaseContainer of BFM_CHECKCLOSE. Check if a dialog is able to close when layouts are switched.
• BFM_ASKCLOSE: Calls GeDialog::AskClose().
• BFM_DESTROY: Calls GeDialog::DestroyWindow().

GeDialog Gadget Interaction

A GeDialog is informed when any kind of interaction with some hosted gadget starts or ends:

• BFM_INTERACTSTART: Sent when user interaction starts.
• BFM_INTERACTEND: Sent when user interaction ends.

Note

These messages are useful to stop threads that work on the scene or to create undo steps. See Undo System Manual.

      // This example catches two messages in GeDialog::Message()
      // to check if any interaction with a gadget started or ended.
 
      case BFM_INTERACTSTART:
      {
        ApplicationOutput("Interaction start"_s);
        break;
      }
      case BFM_INTERACTEND:
      {
        ApplicationOutput("Interaction end"_s);
        break;
      }

When a gadget or custom GUI element is changed by the user it sends the message BFM_ACTION to the parent dialog.

• BFM_ACTION: Calls GeDialog::Command().

The parameters of the message are:

• BFM_ACTION_ID: The ID of the dialog element that triggered the action.
• BFM_ACTION_VALUE: The action value.
• BFM_ACTION_INDRAG: Slider in dragging mode (not finished).
• BFM_ACTION_STRCHG: String in text field changed.
• BFM_ACTION_VALCHG: Edit/slider changed.
• BFM_ACTION_ESC: Action escaped.
• BFM_ACTION_RESET: Right-click to reset input fields.
• BFM_ACTION_UPDATE: Update without verify.

        // This example sends the BFM_ACTION message from a GeUserArea to the parent GUI element.
        // This message can be caught in GeDialog::Message() or GeDialog::Command().
 
        BaseContainer action(BFM_ACTION);
        action.SetInt32(BFM_ACTION_ID, GetId());
        SendParentMessage(action);

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

    // This example catches an interaction with an edit number field in GeDialog::Command().
    // If the user clicked with the right mouse button on the number field's arrows,
    // the value BFM_ACTION_RESET is set.
 
    if (id == ID_EDIT_NUMBER)
    {
      if (msg.GetBool(BFM_ACTION_RESET))
      {
        // right click on the number field's arrows
        // set the value to a pre-defined default value
        const Float defaultValue = 0.5;
        SetPercent(ID_EDIT_NUMBER, defaultValue, 0.0, 100.0, 1.0);
      }
      else
      {
        // just pass through the given value
        const Float value = msg.GetFloat(BFM_ACTION_VALUE);
        SetPercent(ID_EDIT_NUMBER, value, 0.0, 100.0, 1.0);
      }
    }

Mouse and Keyboard Interaction

Both GeDialog and GeUserArea are informed on keyboard and mouse user interaction events.

• BFM_INPUT: Is sent to GeDialog::Message(). In a GeUserArea it will call GeUserArea::InputEvent().

The parameters of the message are:

• BFM_INPUT_DEVICE: The device:
  • BFM_INPUT_MOUSE: Mouse.
  • BFM_INPUT_KEYBOARD: Keyboard.
• BFM_INPUT_CHANNEL: The mouse button or key that was pressed:
  • BFM_INPUT_MOUSELEFT: Left mouse button.
  • BFM_INPUT_MOUSERIGHT: Right mouse button.
  • BFM_INPUT_MOUSEMIDDLE: Middle mouse button.
  • BFM_INPUT_MOUSEX1: Fourth mouse button.
  • BFM_INPUT_MOUSEX2: Five mouse button.
  • BFM_INPUT_MOUSEWHEEL: Mouse wheel. For wheel direction see BFM_INPUT_VALUE.
  • BFM_INPUT_MOUSEMOVE: Mouse move.
• BFM_INPUT_QUALIFIER: A bit mask with the qualifiers at the time when the event occurred.
  • QSHIFT: Shift.
  • QCTRL: Control.
  • QALT: Alt.
  • QALT2: Alt Gr.

      // This example checks in GeUserArea::InputEvent() if the right mouse button was pressed.
 
      const Int32 device  = msg.GetInt32(BFM_INPUT_DEVICE);
      const Int32 channel = msg.GetInt32(BFM_INPUT_CHANNEL);
 
      // check if this is a mouse event triggered by the right mouse button
      const Bool deviceIsMouse  = device == BFM_INPUT_MOUSE;
      const Bool channelIsRight = channel == BFM_INPUT_MOUSERIGHT;
 
      if (deviceIsMouse && channelIsRight)
      {
        ApplicationOutput("Right mouse button pressed.");
 
        const Int32 qualifier = msg.GetInt32(BFM_INPUT_QUALIFIER);
 
        if (qualifier & QCTRL)
          ApplicationOutput("Right mouse button with CTRL pressed.");
 
        return true;
      }

The input from keyboard interactions is either a character or some special key:

• BFM_INPUT_ASC: Contains the Unicode input from the keyboard.
• For keys see KEY

      // This example catches keyboard events in GeUserArea::InputEvent().
 
      const Int32 device = msg.GetInt32(BFM_INPUT_DEVICE);
 
      if (device == BFM_INPUT_KEYBOARD)
      {
        const Int32 channel = msg.GetInt32(BFM_INPUT_CHANNEL);
        if (channel == KEY_ENTER)
          ApplicationOutput("Enter!");
 
        const String key = msg.GetString(BFM_INPUT_ASC);
 
        // check if the String contains any content
        if (key.IsPopulated())
          ApplicationOutput("Key: " + key);
 
        return true;
      }

Further details on the event are stored in these parameters:

• BFM_INPUT_X: X value.
• BFM_INPUT_Y: Y value.
• BFM_INPUT_Z: Z value.
• BFM_INPUT_TILT: Pen tilt.
• BFM_INPUT_ORIENTATION: Pen rotation.
• BFM_INPUT_FINGERWHEEL: Finger wheel.
• BFM_INPUT_P_ROTATION : Pen rotation around its own axis.
• BFM_INPUT_DOUBLECLICK: Double click.
• INPUT_DBLCLK: Mouse qualifier flag for double click.
• BFM_INPUT_VALUE: Value of the input channel (true/false or an Int32 value, e.g. for scroll wheel data).
• BFM_INPUT_VALUE_REAL: Channel value (e.g. pressure or mouse wheel)

      // This example handles some mouse interaction in GeUserArea::InputEvent().
 
      // get device and channel
      const Int32 device  = msg.GetInt32(BFM_INPUT_DEVICE);
      const Int32 channel = msg.GetInt32(BFM_INPUT_CHANNEL);
 
      // check if this is a mouse event triggered by the left mouse button
      const Bool deviceIsMouse = device == BFM_INPUT_MOUSE;
      const Bool channelIsLeft = channel == BFM_INPUT_MOUSELEFT;
 
      if (deviceIsMouse && channelIsLeft)
      {
        // check if double click
        if (msg.GetBool(BFM_INPUT_DOUBLECLICK))
        {
          // get the cursor position
          Int32 mx = msg.GetInt32(BFM_INPUT_X);
          Int32 my = msg.GetInt32(BFM_INPUT_Y);
 
          Global2Local(&mx, &my);
 
          ApplicationOutput("Double click at " + String::IntToString(mx) + " - " + String::IntToString(my));
          return true;
        }
      }

Drag and Drop

Both GeDialog and GeUserArea are informed on drag and drop operations onto their area:

• BFM_DRAGRECEIVE: Message sent on drag and drop events.

The parameters of the message are:

• BFM_DRAG_SCREENX: Screen position X.
• BFM_DRAG_SCREENY: Screen position Y.
• BFM_DRAG_FINISHED: Drag finished.
• BFM_DRAG_LOST: Drag lost.
• BFM_DRAG_ESC: Drag escaped.
• BFM_DRAG_DATA_NEW: Internal drag data.

Different types of elements can be dragged:

• DRAGTYPE_FILES: Files. The data is a string with the file name.
• DRAGTYPE_ICON: Icon.
• DRAGTYPE_MANAGER: Destination drag for C.O.F.F.E.E. manager.
• DRAGTYPE_COMMAND: Destination drag for command.
• DRAGTYPE_CMDPALETTE: Command palette.
• DRAGTYPE_DESCID: Description ID. The data is of type DescPropertyDragData.
• DRAGTYPE_ATOMARRAY: An AtomArray referencing dragged objects, tags, materials etc. See AtomArray Manual.
• DRAGTYPE_FILENAME_IMAGE: Texture file name.
• DRAGTYPE_RGB: RGB color.
• DRAGTYPE_FILENAME_SCENE: Scene file name.
• DRAGTYPE_FILENAME_OTHER: Other file name.
• DRAGTYPE_RGB_ARRAY: Color array. Data received is maxon::BaseArray<Vector>*.

See also Drag and Drop and Drag and Drop.

      // This example receives a drag & drop message in GeUserArea::Message().
      // If the dragged element is a command (from the "Customize Commands" dialog),
      // the command is executed.
 
      case BFM_DRAGRECEIVE:
      {
        // check drag area
        if (!CheckDropArea(msg, true, true))
          break;
 
        Int32 type;
        void* data = nullptr;
 
        // get the drag data
        if (!GetDragObject(msg, &type, &data))
          return false;
 
        if (type == DRAGTYPE_COMMAND)
        {
          // check if the drag has finished
          if (msg.GetInt32(BFM_DRAG_FINISHED))
          {
            // end of drag
            // get command ID and execute the command
            const Int32 ID = msg.GetInt32(BFM_DRAG_DATA_NEW);
            StopAllThreads();
            CallCommand(ID);
 
            return true;
          }
          else
          {
            // while in drag show cursor with question mark
            return SetDragDestination(MOUSE_QUESTION);
          }
        }
        return false;
      }

Description Notifications

A custom GUI element can be used to display a parameter of a NodeData based plugin the in the Attribute Manager. It is possible to send a message from the custom GUI to that NodeData based plugin. This can be used to inform the plugin on what internal data specificity was changed.

• MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION: The message id for description notifications.
• MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION_CONTENT: Stores the message data.
• MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION_ID: Stores the ID of the source custom GUI type.

See also Attribute Manager Interaction.

        // This example shows some part of a custom GUI that has a color picker that defines
        // the color of some of it's elements. When this color is changed a message is sent
        // to the host NodeData based plugin (assuming that the custom GUI is used by the
        // Attribute Manager to display a parameter).
 
        // Update GUI
        this->InitValues();
 
        // get the current color
        Vector color;
        Float  brightness;
 
        GetColorField(COLOR_ID, color, brightness);
 
        // store message data
        BaseContainer messageContent;
        messageContent.SetVector(MSG_DESCRIPTION_COLORSTRING_COLOR, color);
 
        // prepare message
        BaseContainer message(MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION);
        message.SetInt32(BFM_ACTION_ID, GetId());
        message.SetInt32(BFM_ACTION_VALUE, MSG_DESCRIPTION_COLORSTRING_COLORCHANGE);
        message.SetContainer(MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION_CONTENT, messageContent);
        message.SetInt32(MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION_ID, ID_CUSTOMGUI_COLORSTRING);
 
        // send message
        SendParentMessage(message);

Layout Messages

Layout Change

A GeUserArea can inform the parent dialog when it changed its size:

• BFM_LAYOUT_CHANGED: Sent to parent about layout changes. Used internally by GeUserArea::LayoutChanged().

A GeDialog can be part of a layout and is created when that layout is loaded. To restore a given state of that GeDialog, internal data of that dialog must be stored with the layout. This internal data is received and reset using these messages:

• BFM_LAYOUT_GETDATA: Sent when saving the layout.
• BFM_LAYOUT_SETDATA: Receive the container saved with BFM_LAYOUT_GETDATA when loading a layout.

Note

Typically the group weights are stored here. See Weights.

      // This example catches two layout messages in GeDialog::Message().
      // The messages are sent when the layout is saved to a file or when it is loaded from a file.
 
      case BFM_LAYOUT_GETDATA:
      {
        // store custom data
        result = BaseContainer(0);
        result.SetInt32(1000, 123);
 
        return true;
      }
      case BFM_LAYOUT_SETDATA:
      {
        const BaseContainer* bc = msg.GetContainerInstance(BFM_LAYOUT_SETDATA);
        if (bc)
        {
          const Int32 custom = bc->GetInt32(1000);
          ApplicationOutput("Got custom data: " + String::IntToString(custom));
 
          return true;
        }
        break;
      }

Weights

A GeDialog defines its layout using groups with multiple columns/rows. The weights of a group define the relative scale of these columns/rows. When the user changes the scale a message is sent to the GeDialog:

• BFM_WEIGHTS_CHANGED: Sent when group weights changed. The group ID is stored with this message ID.

See also GeDialog Groups.

      // This example catches in GeDialog::Message() the event when the weights
      // of a group are changed. The current weights are stored in a BaseContainer.
      // When the layout is saved the weights are stored as custom layout data.
 
      // save the weights
      case BFM_WEIGHTS_CHANGED:
      {
        GroupWeightsSave(WEIGHT_GROUP, _weights);
        break;
      }
      // store the weights
      case BFM_LAYOUT_GETDATA:
      {
        result = BaseContainer(0);
        result.SetContainer(10000, _weights);
        return true;
      }
      // restore the weights
      case BFM_LAYOUT_SETDATA:
      {
        const BaseContainer* bc = msg.GetContainerInstance(BFM_LAYOUT_SETDATA);
        if (bc)
        {
          // access the sub-container with the ID 10000
          const BaseContainer* const weightsContainer = bc->GetContainerInstance(10000);
 
          if (weightsContainer)
            _weights = *weightsContainer;
 
          GroupWeightsLoad(WEIGHT_GROUP, _weights);
 
          return true;
        }
        break;
      }

Fading

A GeUserArea can support a dynamic fading effect. After GeUserArea::ActivateFading() was called, Cinema 4D sends the BFM_FADE message to the user area for the duration of the fading operation.

• BFM_FADE: Sent to a GeUserArea to blend a GUI color with GeUserArea::AdjustColor().

See Drawing Operations.

// This example shows a GeUserArea that is "fading".
// When the cursor is over the user area the fading is activated.
// Cinema 4D will then send the message BFM_FADE to the user area so
// it can interpolate a color and use this color to redraw itself.
 
class FadingUserArea : public GeUserArea
{
public:
  FadingUserArea() { };
  ~FadingUserArea() { };
 
  Int32 Message(const BaseContainer& msg, BaseContainer& result)
  {
    // messages are identified by the BaseContainer ID
    switch (msg.GetId())
    {
      case BFM_GETCURSORINFO:
      {
        // cursor is over the user area
        // start fading
        ActivateFading(100);
        return true;
      }
      case BFM_FADE:
      {
        // receive fade message and update the COLOR_BG used in DrawMsg()
        const Float percentage = msg.GetFloat(BFM_FADE);
        AdjustColor(COLOR_BG, COLOR_BG_HIGHLIGHT, percentage);
 
        // redraw using the updated COLOR_BG
        Redraw();
        return true;
      }
    }
    return GeUserArea::Message(msg, result);
  }
 
  void DrawMsg(Int32 x1, Int32 y1, Int32 x2, Int32 y2, const BaseContainer& msg)
  {
    OffScreenOn();
    SetClippingRegion(x1, y1, x2, y2);
    // draw background with COLOR_BG
    DrawSetPen(COLOR_BG);
    DrawRectangle(x1, y1, x2, y2);
    // draw text
    DrawSetTextCol(COLOR_CONSOLE_TEXT, COLOR_TRANS);
    DrawSetFont(FONT_MONOSPACED);
    DrawText("User Area"_s, 0, 0, DRAWTEXT_HALIGN_LEFT);
  }
};

Draw

The message BFM_DRAW is sent to a GeUserArea to draw into the Cinema 4D GUI. The message will call GeUserArea::DrawMsg().

The clipping dimensions are stored in these parameters:

• BFM_DRAW_LEFT: Left clipping.
• BFM_DRAW_TOP: Top clipping.
• BFM_DRAW_RIGHT: Right clipping.
• BFM_DRAW_BOTTOM: Bottom clipping.

The draw reason is also stored:

• BFM_DRAW_REASON: Message which started the redraw.
  • BFM_GOTFOCUS: User area got the focus.
  • BFM_LOSTFOCUS: User area lost the focus.

    // This example in GeUserArea::DrawMsg() skips the redraw if only the focus has changed.
 
    const Int32 reason = msg.GetInt32(BFM_DRAW_REASON);
 
    // check if DrawMsg() was called because the focus changed
    const Bool reasonGotFocus = reason == BFM_GOTFOCUS;
    const Bool reasonLostFocurs = reason == BFM_LOSTFOCUS;
 
    if (reasonGotFocus || reasonLostFocurs)
      return;

Visibility

Dialogs and user areas are informed when they become visible:

• BFM_VISIBLE_ON: Sent when the element comes to front after tabbing invisible.
• BFM_VISIBLE_OFF: Sent when the element went back (another tab becomes visible).

Specific GUI Elements

Some messages can only be sent to specific elements or are only sent by specific elements.

Text Edit Fields

Text edit field messages:

• BFM_EDITFIELD_GETCURSORPOS: Return the cursor position in an edit field.
• BFM_EDITFIELD_GETBLOCKSTART: Returns the block start position in an edit field.
• BFM_EDITFIELD_SETCURSORPOS: Sets the cursor position in an edit field.
• BFM_SETCURSORINFO: Same as BFM_EDITFIELD_SETCURSORPOS.

      // This example sets the string of a text edit gadget that is part of a GeDialog.
      // Then a message is sent to the gadget to set the cursor position.
 
      // set the text of the edit field.
      const String text { "Hello World" };
      SetString(ID_TEXTEDIT, text);
 
      // sets the cursor to the end of the new text
      BaseContainer bc { BFM_EDITFIELD_SETCURSORPOS };
      bc.SetInt32(1, (Int32)text.GetLength());
      SendMessage(ID_TEXTEDIT, bc);
 
      // set focus
      Activate(ID_TEXTEDIT);

Multi-line edit fields messages:

• BFM_SPECIALMODE: Setting the scripting language mode. Used internally by GeDialog::SetMultiLineMode().

Messages to access the internally stored undo stack of a multi-line edit field:

• BFM_EDITFIELD_STOREUNDO: Stores the undo container for a multi-line edit text.
• BFM_EDITFIELD_RESTOREUNDO: Restore the undo container for a multi-line edit text.
• BFM_EDITFIELD_FLUSHUNDO: Flushes the undo stack for a multi-line edit text.
• BFM_EDITFIELD_UNDOSTAT_COUNT: Returns the undo stack size.
• BFM_EDITFIELD_UNDOSTAT_UNDOLEVEL: Returns the current undo level.

It is also possible to send messages from the IDM list to the multi-line edit field.

  // This example GeDialog includes a multi-line edit field and two buttons.
  // The two buttons can be used to send "Undo" and "Redo" commands to the
  // multi-line field. The buttons are enabled or disabled depending on the
  // undo stack of the field.
 
  Bool CreateLayout()
  {
    SetTitle("Simple Script Manager"_s);
 
    const Int32 style = DR_MULTILINE_STATUSBAR | DR_MULTILINE_HIGHLIGHTLINE | DR_MULTILINE_WORDWRAP |
                        DR_MULTILINE_MONOSPACED | DR_MULTILINE_PYTHON | DR_MULTILINE_SYNTAXCOLOR;
 
    // add a multi line text field
    AddMultiLineEditText(ID_MULTILINE_EDIT, BFH_SCALEFIT, 0, 200, style);
 
    // set some python code
    SetString(ID_MULTILINE_EDIT, "import c4d\n\nprint(\"hello world\")\n"_s);
 
    // add two buttons for "Undo" and "Redo"
    AddButton(ID_UNDO_BUTTON, BFH_SCALEFIT, 0, 10, "Undo"_s);
    AddButton(ID_REDO_BUTTON, BFH_SCALEFIT, 0, 10, "Redo"_s);
 
    // use a timer to check the undo stack of the text field
    this->SetTimer(250);
 
    return true;
  }
 
  Bool Command(Int32 id, const BaseContainer& msg)
  {
    if (id == ID_UNDO_BUTTON)
    {
      // when "Undo" button was pressed, send IDM_UNDO
      // to the multi line text field
      SendMessage(ID_MULTILINE_EDIT, BaseContainer(IDM_UNDO));
      CheckUndoState();
    }
    if (id == ID_REDO_BUTTON)
    {
      // when "Redo" button was pressed, send IDM_REDO
      // to the multi line text field
      SendMessage(ID_MULTILINE_EDIT, BaseContainer(IDM_REDO));
      CheckUndoState();
    }
    return GeDialog::Command(id, msg);
  }
 
  void Timer(const BaseContainer& msg)
  {
    CheckUndoState();
  }
 
  // ----------------------------------------------------------------------------------------
  // Checks the current undo stack of the multi-line edit text.
  // Depending on the stack the "Undo" and "Redo" buttons are enabled.
  // ----------------------------------------------------------------------------------------
  void CheckUndoState()
  {
    // send message to get data
    BaseContainer getUndoLevelMsg = BaseContainer(BFM_EDITFIELD_UNDOSTAT_UNDOLEVEL);
    getUndoLevelMsg.SetBool(BFM_REQUIRESRESULT, true);
 
    const GeData res = SendMessage(ID_MULTILINE_EDIT, getUndoLevelMsg);
 
    // check if the message result is a BaseContainer
    if (res.GetType() == DA_CONTAINER)
    {
      BaseContainer* stat = res.GetContainer();
      if (stat)
      {
        // get undo stack size and current level
        const Int32 undoStackCount = stat->GetInt32(BFM_EDITFIELD_UNDOSTAT_COUNT);
        const Int32 currentLevel = stat->GetInt32(BFM_EDITFIELD_UNDOSTAT_UNDOLEVEL);
 
        // enable and disable buttons accordingly
        if (currentLevel > 0)
          Enable(ID_UNDO_BUTTON, true);
        else
          Enable(ID_UNDO_BUTTON, false);
 
        // check if the current level is not the latest undo-level
        if (currentLevel < (undoStackCount - 1))
          Enable(ID_REDO_BUTTON, true);
        else
          Enable(ID_REDO_BUTTON, false);
      }
    }
  }

Status Bar

The message BFM_SETSTATUSBAR can be sent to edit the status bar of a scroll group or a progress bar custom GUI element:

• BFM_SETSTATUSBAR: Status bar message.

The parameters of this message are:

• BFM_STATUSBAR_PROGRESSON: Status bar active.
• BFM_STATUSBAR_PROGRESS: Progress between 0.0 and 1.0.
• BFM_STATUSBAR_PROGRESSSPIN: Spinning bar.
• BFM_STATUSBAR_TXT: First text.
• BFM_STATUSBAR_HELP: Second text. (Help.)
• BFM_STATUSBAR_PROGRESSFULLSIZE: Use full-sized progress bar.
• BFM_STATUSBAR_TINT_COLOR: Color ID for the status bar, or as RGB value (Vector).

    // This example sends a message to a CUSTOMGUI_PROGRESSBAR gadget to update the status bar.
 
    BaseContainer m(BFM_SETSTATUSBAR);
    m.SetBool(BFM_STATUSBAR_PROGRESSON, true);
    m.SetFloat(BFM_STATUSBAR_PROGRESS, _progress);
    m.SetData(BFM_STATUSBAR_TINT_COLOR, Vector(1.0 - _progress, _progress, 0.0));
 
    SendMessage(ID_STATUSBAR, m);

    // This example sends a message to a scroll group to set the text of its status bar.
 
    BaseContainer bc(BFM_SETSTATUSBAR);
    bc.SetData(BFM_STATUSBAR_PROGRESSON, false);
    bc.SetData(BFM_STATUSBAR_TXT, "Some Text");
    bc.SetData(BFM_STATUSBAR_HELP, "More Text");
 
    SendMessage(ID_SCROLLGROUP, bc);

Pop Up

A message is sent from a popup button:

• BFM_POPUPNOTIFY: Notification of popup before the menu opens.

    // This example adds a pop up button to the layout in GeDialog::CreateLayout().
 
    AddPopupButton(ID_POPUP, BFH_LEFT, 10, 10);
    AddChild(ID_POPUP, 1, "Child 0"_s);
    AddChild(ID_POPUP, 2, "Child 1"_s);

      // This example catches a message in GeDialog::Message() after the pop up button was pressed
      // (but before the pop up menu is created).
 
      case BFM_POPUPNOTIFY:
      {
        const Int32 ID = msg.GetInt32(BFM_ACTION_ID);
        if (ID == ID_POPUP)
        {
          ApplicationOutput("The pop up button was pressed"_s);
        }
        break;
      }

    // This example catches the result in GeDialog::Command() after
    // something was selected in the pop up button's pop up menu.
 
    if (id == ID_POPUP)
    {
      const Int32 selectedItem = msg.GetInt32(BFM_ACTION_VALUE);
      ApplicationOutput("The item " + String::IntToString(selectedItem) + " was selected");
    }

Scroll Group

A scroll group informs the parent dialog when it was scrolled:

• BFM_SCROLLGROUP_SCROLLED: Sent to the parent dialog when a scroll group was scrolled.

Custom GUI Elements

The base class for custom GUI elements (used to display NodeData parameters in the Attribute Manager) is iCustomGui which is based on GeDialog. Such custom GUI elements receive these messages when the used "User Interface" is changed in the Attribute Manager. The custom GUI can then store the ID of the currently active gadget:

• BFM_GETFOCUSBEFOREUPDATE: Sent before the layout is changed.
• BFM_SETFOCUSAFTERUPDATE Sent after the layout is changed.

      // This example stores the ID of the gadget currently in focus.
 
      case BFM_GETFOCUSBEFOREUPDATE:
      {
        result.SetInt32(0, _activeID);  // store ID of active gadget
        return true;
      }
      case BFM_SETFOCUSAFTERUPDATE:
      {
        const Int32 ID = msg.GetInt32(0);
        Activate(ID); // active stored ID
        return true;
      }

Core Messages

Both GeDialog and GeUserArea receive core messages. These messages call GeDialog::CoreMessage() or GeUserArea::CoreMessage().

• BFM_SYNC_MESSAGE: Sync message.
• BFM_CORE_MESSAGE: Core message.

See the Core Messages Manual.

      // This example catches EVMSG_ASYNCEDITORMOVE in a GeDialog.
 
      case EVMSG_ASYNCEDITORMOVE:
      {
        // check if this core message is new
        if (CheckCoreMessage(bc))
        {
          const Int movement = (Int)bc.GetVoid(BFM_CORE_PAR1);
 
          switch (movement)
          {
            case MOVE_START: { ApplicationOutput("Start Movement"); break; }
            case MOVE_CONTINUE: { ApplicationOutput("Continue Movement"); break; }
            case MOVE_END: { ApplicationOutput("End Movement"); break; }
          }
        }
        break;
      }

Further Reading

• GeDialog Manual
• GeUserArea Manual
• Core Messages Manual
• BaseContainer Manual
• Undo System Manual
• AtomArray Manual