c4d.gui.GeUserArea

class c4d.gui.GeUserArea

This class helps you to create custom gadgets for dialogs in Cinema 4D.

Note

Just take care about the lifetime of your GeUserArea instance.
If you pass an instance of this class to a dialog, a reference is hold by the dialog and released when the dialog is freed.
That also means that each instance of your GeUserArea class is still alive until the host-dialog is freed, even you dont hold a reference to it.
If you want to use the same instance of your GeUserArea class on the next time you open the dialog, you have to store the instance in the class scope.
See the geuserarea_basic_r13.py example.

The class to create custom user areas.

Methods Signatures

Magic Methods

GeUserArea.__init__()

Creates a user area that is not attached to any dialog.

Methods to Override

GeUserArea.CoreMessage()

Called when a Cinema 4D core messages is received.

GeUserArea.DrawMsg()

Called when Cinema 4D wants you to draw your userarea.

GeUserArea.GetMinSize()

Override this function to specify a minimum size for the user area.

GeUserArea.Init()

Called once when the user area is initialized by the GUI, before the layout is calculated.

GeUserArea.InitValues()

Called after the layout is calculated, before the user area is drawn.

GeUserArea.InputEvent()

Called when an input event is received.

GeUserArea.Message()

Override this function to react to more messages than covered by the other functions. Normally this is not necessary.

GeUserArea.Sized()

Called when the user area is resized.

GeUserArea.Timer()

If you subscribe to timer events using SetTimer() (x), this function is called every x th millisecond.

Basic Functions

GeUserArea.LayoutChanged()

Tells Cinema 4D that the user area now has new dimensions. That causes c4d to call:

Basic Methods

GeUserArea.GetHeight()

Returns the height of the user area.

GeUserArea.GetId()

Returns the ID of the user area.

GeUserArea.GetWidth()

Returns the width of the user area.

GeUserArea.HasFocus()

Indicates the focus state.

GeUserArea.IsEnabled()

Indicates the enabled state.

GeUserArea.IsR2L()

Checks if the user area has to be drawn in right-to-left layout mode.

GeUserArea.Redraw()

Forces the user area to redraw itself.

GeUserArea.SendParentMessage()

Use this function to send a custom message to the parent dialog.

GeUserArea.SendParentMessageResult()

Sends a custom message to the parent dialog.

GeUserArea.SetTimer()

Initializes the timer clock, so that Timer() is called every timer milliseconds.

Border Methods

GeUserArea.GetBorderSize()

Retrieves the space required to draw a border.

Coordinates Transformation

GeUserArea.Global2Local()

Transforms global coordinates (relative to the top left corner of the physical window) to local coordinates (relative to the top left corner of the dialog). Result is a dict with member keys x and y of type int.

GeUserArea.Local2Global()

Transforms local coordinates (relative to the top left corner of the dialog) to global coordinates (relative to the top left corner of the physical window). Result is a dict with member keys x and y of type int.

GeUserArea.Local2Screen()

Transforms local coordinates (relative to the top left corner of the dialog) to screen coordinates (relative to the top left corner of the system screen). Result is a dict with member keys x and y of type int.

GeUserArea.Screen2Local()

Transforms screen coordinates (relative to the top left corner of the system screen) to local coordinates (relative to the top left corner of the dialog). Result is a dict with member keys x and y of type int.

Drag and Drop Methods

GeUserArea.CheckDropArea()

Checks the drag position in a drag event message against the user area’s position in the layout.

GeUserArea.GetDragObject()

Extracts the object from a drag and drop message.

GeUserArea.GetDragPosition()

Extracts local drag coordinates from a drag and drop event.

GeUserArea.HandleMouseDrag()

Starts a drag and drop operation.

GeUserArea.MouseDrag()

Polls the mouse during a drag started with MouseDragStart().

GeUserArea.MouseDragEnd()

Checks why the mouse drag ended. Allows to perform any undo operations needed if the user canceled the drag.

GeUserArea.MouseDragStart()

Starts a mouse drag. Only call this when a mouse down message is received.

GeUserArea.SetDragDestination()

Sets the correct cursor during drag and drop handling.

Draw Helpers Methods

GeUserArea.ClearClippingRegion()

Clears any clipping region set with SetClippingRegion().

GeUserArea.OffScreenOn()

Enables double buffering to avoid blinking and flickering effects.

GeUserArea.SetClippingRegion()

Should be used at the top of the DrawMsg() function to specify the clipping region.

Draw Methods

GeUserArea.DrawBezier()

Draws concatenated bezier curves.

GeUserArea.DrawBezierFill()

Draws concatenated Bezier curves.

GeUserArea.DrawBezierLine()

Draws concatenated Bezier curves.

GeUserArea.DrawBitmap()

Draws a bitmap into the user area.

GeUserArea.DrawBorder()

Fills a rectangular area with the current pen color between (x1,y1) and (x2,y2).

GeUserArea.DrawCustomButton()

Draws a button.

GeUserArea.DrawEllipseFill()

Draws an ellipse filled with color.

GeUserArea.DrawEllipseLine()

Draws an ellipse line.

GeUserArea.DrawFrame()

Draws a rectangular frame with the current pen color between (x1,y1) and (x2,y2).

GeUserArea.DrawGetFontBaseLine()

Returns the base line of the set font.

GeUserArea.DrawGetFontHeight()

Returns the height in pixels of a line of text in the current font.

GeUserArea.DrawGetTextIndexFromPixel()

Retrieves the index from a position within the text.

GeUserArea.DrawGetTextWidth()

Returns the width in pixels of the string text, if it were drawn in the current font.

GeUserArea.DrawGetTextWidth_ListNodeName()

Retrieves the width in pixels of the name of node.

GeUserArea.DrawImageRef()

Draws a image into the user area.

GeUserArea.DrawLine()

Draws a line with the current pen color between (x1,y1) and (x2,y2).

GeUserArea.DrawPolyFill()

Draws a polygon filled with color.

GeUserArea.DrawPolyLine()

Draws a polygon line.

GeUserArea.DrawRectangle()

Fills a rectangular area with the current pen color between (x1,y1) and (x2,y2).

GeUserArea.DrawSetFont()

Sets the text font.

GeUserArea.DrawSetOpacity()

Sets the opacity value.

GeUserArea.DrawSetPen()

Sets the draw color.

GeUserArea.DrawSetTextCol()

Sets the draw color.

GeUserArea.DrawSetTextRotation()

Rotates the font for drawing.

GeUserArea.DrawText()

Draws the string txt with the upper left corner at the position (x, y).

GeUserArea.FillBitmapBackground()

Fills the bitmap bmp with the current pen color.

GeUserArea.GetColorRGB()

Gets the RGB values associated with a color ID.

Fading Methods

GeUserArea.ActivateFading()

Activates the fading.

GeUserArea.AdjustColor()

Sets the blend colors for user area fading.

Inputs Methods

GeUserArea.GetInputEvent()

Gets the next input event for a certain device from the event queue.

GeUserArea.GetInputState()

Polls a certain channel of a device for the current input state.

GeUserArea.IsHotkeyDown()

Checks the standard navigation hotkeys.

GeUserArea.KillEvents()

Flushes all events from the window message queue.

Miscellaneous

GeUserArea.GetPixelRatio()

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

GeUserArea.ScrollArea()

Scrolls the area from (x,y) to (x+w,y+h) in the direction specified by xdiff and ydiff.

Parent Dialog

GeUserArea.GetDialog()

Gets the user area’s parent dialog.

Methods Documentation

GeUserArea.__init__(self)

Creates a user area that is not attached to any dialog.

Note

The user area must be attached to a dialog with GeDialog.AttachUserArea() before it can be used.

GeUserArea.CoreMessage(self, id, msg)
Called when a Cinema 4D core messages is received.
The message type is given by id and the message information is stored in msg.
Parameters
  • id (int) – The received core message<MSG_CORE_EVENT>.

  • msg (c4d.BaseContainer) – The message container.

Return type

bool

Returns

Currently not used - but you have to return a bool value.

GeUserArea.DrawMsg(self, x1, y1, x2, y2, msg)
Called when Cinema 4D wants you to draw your userarea.
Use the drawing functions to update your user area in the region specified by the rectangle from (x1,y1) to (x2,y2).
Parameters
  • x1 (int) – The upper left x coordinate.

  • y1 (int) – The upper left y coordinate.

  • x2 (int) – The lower right x coordinate.

  • y2 (int) – The lower right y coordinate.

  • msg (c4d.BaseContainer) – A mesage container.

GeUserArea.GetMinSize(self)

Override this function to specify a minimum size for the user area.

def GetMinSize(self):
    #do a calculation here
    return self.width, self.height
Return type

Tuple[int, int]

Returns

A tuple with two elements just like this.

GeUserArea.Init(self)
Called once when the user area is initialized by the GUI, before the layout is calculated.
Override this function if you need to initialize anything.

Note

Return True if successful, or False to signalize an error.

Return type

bool

Returns

True if successful, or False to signalize an error.

GeUserArea.InitValues(self)
Called after the layout is calculated, before the user area is drawn.
Override this function if you need to initialize anything.

Note

Return True if successful, or False to signalize an error.

Return type

bool

Returns

True if successful, or False to signalize an error.

GeUserArea.InputEvent(self, msg)
Called when an input event is received.
The information about the input event is stored in the msg container.

See also

Input Events.

Parameters

msg (c4d.BaseContainer) – The event container.

Return type

bool

Returns

True if the event was handled, otherwise False.

GeUserArea.Message(self, msg, result)

Override this function to react to more messages than covered by the other functions. Normally this is not necessary.

Note

If overridden, include a call to the base version of this function, GeUserArea.Message():

def Message(self, msg, result):
    if msg.GetId():
        #Do something
        return True

    return c4d.gui.GeUserArea.Message(self, msg, result)

See also

C4DAtom and Plugin Messages for information on the messages type, data and input/output.

Parameters
Return type

int

Returns

The return value depends on the message.

GeUserArea.Sized(self, w, h)

Called when the user area is resized.

Note

Override if you need to update anything.

Parameters
  • w (int) – The new width in pixels.

  • h (int) – The new height in pixels.

GeUserArea.Timer(self, msg)
If you subscribe to timer events using SetTimer() (x), this function is called every x th millisecond.
The raw timer message is stored in msg.
Parameters

msg (c4d.BaseContainer) – The timer message container.

GeUserArea.LayoutChanged(self)

Tells Cinema 4D that the user area now has new dimensions. That causes c4d to call:

GeUserArea.GetHeight(self)

Returns the height of the user area.

Return type

int

Returns

Height in pixels.

GeUserArea.GetId(self)

Returns the ID of the user area.

Return type

int

Returns

The ID.

GeUserArea.GetWidth(self)

Returns the width of the user area.

Return type

int

Returns

Width in pixels.

GeUserArea.HasFocus(self)

Indicates the focus state.

Return type

bool

Returns

True if the user area has the focus in the dialog, otherwise False.

GeUserArea.IsEnabled(self)

Indicates the enabled state.

Return type

bool

Returns

True if the user area is enabled in the dialog, otherwise False.

GeUserArea.IsR2L(self)

Checks if the user area has to be drawn in right-to-left layout mode.

Return type

bool

Returns

True if the user area is in right-to-left layout mode, otherwise False.

GeUserArea.Redraw(self, thread=False)

Forces the user area to redraw itself.

Parameters

thread (bool) – Must be set to True if the function is called from another thread than the main Cinema 4D thread.

GeUserArea.SendParentMessage(self, msg)

Use this function to send a custom message to the parent dialog.

Parameters

msg (c4d.BaseContainer) – The message container.

GeUserArea.SendParentMessageResult(self, msg)

Sends a custom message to the parent dialog.

New in version 24.

Parameters

msg (c4d.BaseContainer) – The message container.

Returns

Return the result of the message.

Return type

Any

GeUserArea.SetTimer(self, x)

Initializes the timer clock, so that Timer() is called every timer milliseconds.

Note

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

Note

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

x (int) – The timer interval in milliseconds.

GeUserArea.GetBorderSize(self, type)

Retrieves the space required to draw a border.

Parameters

type (int) –

The border type:

BORDER_NONE

No border.

BORDER_THIN_IN

Thin border inward.

BORDER_THIN_OUT

Thin border outward.

BORDER_IN

Normal border inward.

BORDER_OUT

Normal border outward.

BORDER_GROUP_IN

Group border inside.

BORDER_GROUP_OUT

Group border outside.

BORDER_OUT2

Outward border 2.

BORDER_OUT3

Outward border 3

BORDER_BLACK

Thin black line.

BORDER_ACTIVE_1

Active border 1.

BORDER_ACTIVE_2

Active border 2.

BORDER_ACTIVE_3

Active border 3.

BORDER_ACTIVE_4

Active border 4.

BORDER_GROUP_TOP

Border along the top.

BORDER_ROUND

Border with round corners.

BORDER_SCHEME_EDIT

Edit field border like the shortcut gadget for example.

BORDER_SCHEME_EDIT_NUMERIC

Edit field border that is open to the right like the link field for example.

BORDER_OUT3l

Outward border 3, open to the left.

BORDER_OUT3r

Outward border 3, open to the right.

BORDER_THIN_INb

Thin border inward, open to the botton.

BORDER_MASK

Masks out border type.

BORDER_TEXT_DOTTED

New in version R21:
Only used with GeDialog.AddStaticText().
Draws a dotted line at right of text, useful to visually connect the text with its parameter.

BORDER_WITH_TITLE_MONO

Display group title with monospaced font.

BORDER_WITH_TITLE_BOLD

Display group title with bold font.

BORDER_WITH_TITLE

Display group title in the border.

Return type

dict{l: int, t: int, r: int, b: int}

Returns

The space.

GeUserArea.Global2Local(self)

Transforms global coordinates (relative to the top left corner of the physical window) to local coordinates (relative to the top left corner of the dialog). Result is a dict with member keys x and y of type int.

Return type

Optional[Dict[x: int, y: int]]

Returns

The converted coordinates or None.

GeUserArea.Local2Global(self)

Transforms local coordinates (relative to the top left corner of the dialog) to global coordinates (relative to the top left corner of the physical window). Result is a dict with member keys x and y of type int.

Return type

Optional[Dict[x: int, y: int]]

Returns

The converted coordinates or None.

GeUserArea.Local2Screen(self)

Transforms local coordinates (relative to the top left corner of the dialog) to screen coordinates (relative to the top left corner of the system screen). Result is a dict with member keys x and y of type int.

Return type

Optional[Dict[x: int, y: int]]

Returns

The converted coordinates or None.

GeUserArea.Screen2Local(self)

Transforms screen coordinates (relative to the top left corner of the system screen) to local coordinates (relative to the top left corner of the dialog). Result is a dict with member keys x and y of type int.

Return type

Optional[Dict[x: int, y: int]]

Returns

The converted coordinates or None.

GeUserArea.CheckDropArea(self, msg, horiz, vert)

Checks the drag position in a drag event message against the user area’s position in the layout.

Note

The check can be limited to only X or Y coordinates.

Parameters
  • msg (c4d.BaseContainer) – The drag message.

  • horiz (bool) – If True the drag position is checked against the horizontal bounds of the region.

  • vert (bool) – If True the drag position is checked against the vertical bounds of the region.

Return type

bool

Returns

True if the drag message is within the bounds specified, otherwise False.

GeUserArea.GetDragObject(self, msg)

Extracts the object from a drag and drop message.

Parameters

msg (c4d.BaseContainer) – The original message.

Return type

dict{‘type’: int, ‘object’: any}

Returns

The type of drag and the object itself. The types are:

DRAGTYPE_ATOMARRAY

Atom array. The data is a list of c4d.C4DAtom.

DRAGTYPE_CMDPALETTE

Not supported.

DRAGTYPE_COMMAND

Not supported.

DRAGTYPE_DESCID

Description ID. The data is a dict(‘did’: c4d.DescID, ‘arr’: list of c4d.C4DAtom).

DRAGTYPE_ICON

Not supported.

DRAGTYPE_FILES

Files. The data is a string with the filename.

DRAGTYPE_FILENAME_IMAGE

Image. The data is a string with the filename.

DRAGTYPE_FILENAME_OTHER

Other filename. The data is a string with the filename.

DRAGTYPE_FILENAME_SCENE

Scene filename. The data is a string with the filename.

DRAGTYPE_MANAGER

Not supported.

DRAGTYPE_RGB

RGB color. The data is a c4d.Vector.

DRAGTYPE_RGB_ARRAY

RGB color array. The data is a list of c4d.Vector.

DRAGTYPE_RGBA_ARRAY

RGBA color array. The data is a maxon.BaseArray of maxon.ColorA.

DRAGTYPE_BROWSER

Browser drag message. The data is a list of string with the filename.

DRAGTYPE_ASSET

New in version 2023.2.0: Message ID for Asset browser assets, the message data is a maxon.DragAndDropDataAssetArray.

GeUserArea.GetDragPosition(self, msg)

Extracts local drag coordinates from a drag and drop event.

Parameters

msg (c4d.BaseContainer) – The original message.

Return type

dict{‘x’: int, ‘y’: int}

Returns

The local X and Y position.

GeUserArea.HandleMouseDrag(self, msg, type, data, dragflags)

Starts a drag and drop operation.

New in version R19.024.

Parameters
  • msg (c4d.BaseContainer) – The mouse event message that triggered the drag and drop.

  • type (int) –

    The type of data:

    DRAGTYPE_ATOMARRAY

    Atom array. The data is a list of c4d.C4DAtom.

    DRAGTYPE_CMDPALETTE

    Not supported.

    DRAGTYPE_COMMAND

    Not supported.

    DRAGTYPE_DESCID

    Description ID. The data is a dict(‘did’: c4d.DescID, ‘arr’: list of c4d.C4DAtom).

    DRAGTYPE_ICON

    Not supported.

    DRAGTYPE_FILES

    Files. The data is a string with the filename.

    DRAGTYPE_FILENAME_IMAGE

    Image. The data is a string with the filename.

    DRAGTYPE_FILENAME_OTHER

    Other filename. The data is a string with the filename.

    DRAGTYPE_FILENAME_SCENE

    Scene filename. The data is a string with the filename.

    DRAGTYPE_MANAGER

    Not supported.

    DRAGTYPE_RGB

    RGB color. The data is a c4d.Vector.

    DRAGTYPE_RGB_ARRAY

    RGB color array. The data is a list of c4d.Vector.

    DRAGTYPE_RGBA_ARRAY

    RGBA color array. The data is a maxon.BaseArray of maxon.ColorA.

    DRAGTYPE_BROWSER

    Browser drag message. The data is a list of string with the filename.

    DRAGTYPE_ASSET

    New in version 2023.2.0: Message ID for Asset browser assets, the message data is a maxon.DragAndDropDataAssetArray.

  • data (any) – Depends on type.

  • dragflags (int) – The drag flags. Private.

Return type

bool

Returns

True if the user moved the mouse and a drag and drop operation was initiated.
False if the user did not move the mouse, so that the original event is a normal mouse click event.

GeUserArea.MouseDrag(self)

Polls the mouse during a drag started with MouseDragStart().

The best way to use this function is.

while True:
    result, mx, mx, channels = ua.MouseDrag()
    if result != c4d.MOUSEDRAGRESULT_CONTINUE:
        break

To check for qualifiers see the channels container.

if channels[c4d.BFM_INPUT_QUALIFIER] & QSHIFT:
    ...
if channels[c4d.BFM_INPUT_QUALIFIER] & QCTRL:
    ...
Return type

Tuple[int, float, float, c4d.BaseContainer]

Returns

A tuple with the following information:

int: The mouse drag result:

MOUSEDRAGRESULT_ESCAPE

Drag aborted.

MOUSEDRAGRESULT_FINISHED

Drag finished.

MOUSEDRAGRESULT_CONTINUE

Drag still in progress.

float: The X delta-coordinate of the mouse (the amount the mouse has moved).
float: The Y delta-coordinate of the mouse (the amount the mouse has moved).
c4d.BaseContainer: The channels values. Also contains these pen values:

PENPRESSURE

Pressure.

PENTILT

Tilt.

PENROTATION

Rotation.

PENDRAWROTATION

Draw rotation.

PENDRAWRANDOMNESS

Draw randomness.

PENDRAWWHEELROTATION

Draw wheel rotation.

PENDRAWWHEELPRESSURE

Draw wheel pressure.

PENDRAWDISTANCE

Draw distance.

PENFINGERWHEEL

Finger wheel.

GeUserArea.MouseDragEnd(self)

Checks why the mouse drag ended. Allows to perform any undo operations needed if the user canceled the drag.

Return type

int

Returns

The mouse drag result:

MOUSEDRAGRESULT_ESCAPE

Drag aborted.

MOUSEDRAGRESULT_FINISHED

Drag finished.

MOUSEDRAGRESULT_CONTINUE

Drag still in progress.

GeUserArea.MouseDragStart(self, button, mx, my, flag)
Starts a mouse drag. Only call this when a mouse down message is received.
Then repeatedly poll with MouseDrag() during the drag.
Parameters
  • button (int) –

    The mouse button that is 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 message.

    BFM_INPUT_MOUSEMOVE

    Mouse move message.

    BFM_INPUT_MOUSEMOVE

    Mouse move message.

    BFM_INPUT_WHEELSCROLL

    New in version S22:
    True for scroll events on a classic wheel mouse.
    False for everything else (touchpad, magic mouse).

  • mx (float) – The X position of the mouse.

  • my (float) – The Y position of the mouse.

  • flag (int) –

    The mouse drag flags:

    MOUSEDRAGFLAGS_NONE

    None.

    MOUSEDRAGFLAGS_DONTHIDEMOUSE

    Show mouse pointer during drag.

    MOUSEDRAGFLAGS_NOMOVE

    MouseDrag() returns MOUSEDRAGRESULT_CONTINUE even if mouse is not moved. Otherwise MouseDrag() only returns if mouse is moved.

    MOUSEDRAGFLAGS_EVERYPACKET

    Receive every packet of the queue, otherwise only data of the last packet.

    MOUSEDRAGFLAGS_COMPENSATEVIEWPORTORG

    Compensates the viewport origin during drag.

    MOUSEDRAGFLAGS_AIRBRUSH

    Airbrush mode.

GeUserArea.SetDragDestination(self, cursor)

Sets the correct cursor during drag and drop handling.

Parameters

cursor (int) –

A mouse cursor:

MOUSE_HIDE

Hide cursor.

MOUSE_SHOW

Show cursor.

MOUSE_NORMAL

Normal cursor.

MOUSE_BUSY

Busy cursor.

MOUSE_CROSS

Cross cursor.

MOUSE_QUESTION

Question cursor

MOUSE_ZOOM_IN

Zoom in cursor.

MOUSE_ZOOM_OUT

Zoom out cursor.

MOUSE_FORBIDDEN

Forbidden cursor.

MOUSE_DELETE

Delete cursor.

MOUSE_COPY

Copy cursor.

MOUSE_INSERTCOPY

Insert copy cursor.

MOUSE_INSERTCOPYDOWN

Insert copy down cursor.

MOUSE_MOVE

Move cursor.

MOUSE_INSERTMOVE

Insert move cursor.

MOUSE_INSERTMOVEDOWN

Insert move cursor.

MOUSE_ARROW_H

Horizontal cursor.

MOUSE_ARROW_V

Vertical cursor.

MOUSE_ARROW_HV

Horizontal and vertical arrow cursor.

MOUSE_POINT_HAND

Point hand cursor.

MOUSE_MOVE_HAND

Move hand cursor.

MOUSE_IBEAM

I-beam cursor.

MOUSE_SELECT_LIVE

Live selection cursor.

MOUSE_SELECT_FREE

Free selection cursor.

MOUSE_SELECT_RECT

Rectangle selection cursor.

MOUSE_SELECT_POLY

Polygon selection cursor.

MOUSE_SPLINETOOLS

Spline tools cursor.

MOUSE_EXTRUDE

Extrude cursor.

MOUSE_NORMALMOVE

Normal move cursor.

MOUSE_ADDPOINTS

Add points cursor.

MOUSE_ADDPOLYGONS

Add polygons cursor.

MOUSE_BRIDGE

Bridge cursor.

MOUSE_MIRROR

Mirror cursor.

MOUSE_PAINTMOVE

Paint move cursor.

MOUSE_PAINTSELECTRECT

Paint select rectangle cursor.

MOUSE_PAINTSELECTCIRCLE

Paint select circle cursor.

MOUSE_PAINTSELECTPOLY

Paint select polygon cursor.

MOUSE_PAINTSELECTFREE

Paint select free cursor.

MOUSE_PAINTMAGICWAND

Paint magic wand cursor.

MOUSE_PAINTCOLORRANGE

Paint color range cursor.

MOUSE_PAINTFILL

Paint fill cursor.

MOUSE_PAINTPICK

Paint pick cursor.

MOUSE_PAINTBRUSH

Paint brush cursor.

MOUSE_PAINTCLONE

Paint clone cursor.

MOUSE_PAINTTEXT

Paint text cursor.

MOUSE_PAINTCROP

Paint crop cursor.

MOUSE_PAINTLINE

Paint line cursor.

MOUSE_PAINTPOLYSHAPE

Paint polygon shape cursor.

Return type

bool

Returns

True if the cursor could be set, otherwise False.

GeUserArea.ClearClippingRegion(self)

Clears any clipping region set with SetClippingRegion().

GeUserArea.OffScreenOn(self, x=NOTOK, y=0, w=0, h=0)
Enables double buffering to avoid blinking and flickering effects.
Sets the clipping area to the rectangular area determined by x, y, w and h.
If x == c4d.NOTOK the size will be calculated automatically.

Note

The GUI will automatically switch planes.

Note

Just call this function before drawing things.

Parameters
  • x (int) – X-coordinate of the clipping area.

  • y (int) – Y-coordinate of the clipping area.

  • w (int) – Width of the clipping area.

  • h (int) – Height of the clipping area.

Return type

bool

Returns

True if double buffering could be enabled, otherwise False.

GeUserArea.SetClippingRegion(self, x, y, w, h)
Should be used at the top of the DrawMsg() function to specify the clipping region.
Without specifying a dedicated clipping region everything will be painted, even if it is outside the user area!

Note

The method OffScreenOn() automatically sets the clipping region to the whole user area, so normally this function is not necessary.

Parameters
  • x (int) – X coordinate of the upper left corner of the clipping region.

  • y (int) – Y coordinate of the upper left corner of the clipping region.

  • w (int) – Width of the clipping region.

  • h (int) – Height of the clipping region.

GeUserArea.DrawBezier(self, sx, sy, p, closed, filled)

Draws concatenated bezier curves.

New in version R14.014.

Note

Due to improve speed performance, the elements of p will be modified and might be invalid and all values must be set again if DrawBezier() will be called again with the same array.

Parameters
  • sx (float) – X coordinate of the upper left corner of the drawn curve. This is the X coordinate of the starting point.

  • sy (float) – Y coordinate of the upper left corner of the drawn curve. This is the Y coordinate of the starting point.

  • p (List[float]) –

    An array with the bezier curves points.

    Here is an example of initializing the curve points array.

    points = array.array('f', range(6))
    
    points[0] = 35  # The X coordinate of the control point for the starting point.
    points[1] = 200 # The Y coordinate of the control point for the starting point.
    points[2] = 220 # The X coordinate of the control point for the ending point.
    points[3] = 260 # The Y coordinate of the control point for the ending point.
    points[4] = 220 # The X coordinate of the ending point.
    points[5] = 40 # The Y coordinate of the ending point.
    
    self.DrawBezier(120, 160, points, False, False)
    

  • closed (bool) – If True, the last point of the last segment connects back to the starting point ( sx , sy).

  • filled (bool) – If True, fills the drawn bezier curves, only if it is also closed.

GeUserArea.DrawBezierFill(self, startPoint, bezierPoints, closed)

Draws concatenated Bezier curves.

New in version R25.010.

Parameters
  • startPoint (List[float]) – The XY coordinate of the upper left corner of the drawn curve. The list should have 2 elements, the first entry is X the second is Y.

  • bezierPoints (List[float]) –

    An array containing a struct of Bezier curves points.

    Here is an example of initializing the curve points array.

    Note

    To define the line segment, you have to introduce three points, two handle and one end point. Each point is defined by two float, so the length of the bezierPoint should be a multiple of six. Handle’s coordinates must be set within the GeUserArea space coordinate.

    points = array.array('f', range(6))
    
    points[0] = 35  # The X coordinate for the starting point's handle.
    points[1] = 200 # The Y coordinate for the starting point's handle.
    points[2] = 220 # The X coordinate for the ending point's handle.
    points[3] = 260 # The Y coordinate for the ending point's handle.
    points[4] = 220 # The X coordinate of the ending point.
    points[5] = 40 # The Y coordinate of the ending point.
    
    self.DrawBezierLine(120, 160, points, False, False)
    

  • closed (bool) – If True, the last point of the last segment connects back to the starting point ( sx , sy).

GeUserArea.DrawBezierLine(self, startPoint, bezierPoints, closed, lineWidth=1.0, lineStyle=LINESTYLE_NORMAL)

Draws concatenated Bezier curves.

New in version R25.010.

Parameters
  • startPoint (List[float]) – The XY coordinate of the upper left corner of the drawn curve. The list should have 2 elements, the first entry is X the second is Y.

  • bezierPoints (List[float]) –

    An array containing a struct of Bezier curves points.

    Here is an example of initializing the curve points array.

    Note

    To define the line segment, you have to introduce three points, two handle and one end point. Each point is defined by two float, so the length of the bezierPoint should be a multiple of six. Handle’s coordinates must be set within the GeUserArea space coordinate.

    points = array.array('f', range(6))
    
    points[0] = 35  # The X coordinate for the starting point's handle.
    points[1] = 200 # The Y coordinate for the starting point's handle.
    points[2] = 220 # The X coordinate for the ending point's handle.
    points[3] = 260 # The Y coordinate for the ending point's handle.
    points[4] = 220 # The X coordinate of the ending point.
    points[5] = 40 # The Y coordinate of the ending point.
    
    self.DrawBezierLine(120, 160, points, False, False)
    

  • closed (bool) – If True, the last point of the last segment connects back to the starting point ( sx , sy).

  • lineWidth (float) – The width of the Bezier curve.

  • lineStyle (int) –

    The line style of the Bezier curve:

    Symbol ID

    NORMAL

    DOTTED

    DASHED

    DASHED_INV

    DASHED_BIG

GeUserArea.DrawBitmap(self, bmp, wx, wy, ww, wh, x, y, w, h, mode)
Draws a bitmap into the user area.
The region (x,y) to (x+w,y+h) from the bitmap will be scaled and transformed into the region (wx,wy) to (wx+ww,wy+wh) of the destination area.

Note

BMP_ALLOWALPHA can be combined with the other modes.

Parameters
  • bmp (c4d.bitmaps.BaseBitmap) – The bitmap to draw.

  • wx (int) – X coordinate of the upper left corner of the destination area.

  • wy (int) – Y coordinate of the upper left corner of the destination area.

  • ww (int) – Width of the destination area.

  • wh (int) – Height of the destination area.

  • x (int) – X coordinate of the upper left corner of the bitmap area.

  • y (int) – Y coordinate of the upper left corner of the bitmap area.

  • w (int) – Width of the bitmap area.

  • h (int) – Height of the bitmap area.

  • mode (int) –

    Can be a combination of the following flags:

    BMP_NORMAL

    Standard scaling by the operating system. Fast but low quality when using uneven scaling factors.

    BMP_NORMALSCALED

    Scaling with sampling for high quality. Slow.

    BMP_GRAYEDOUT

    New in version R21: | Embosses the bitmap (like the grayed palette icons in Cinema 4D). | Previously called BMP_EMBOSSED.

    BMP_ALLOWALPHA

    Uses the alpha channel to blend with the current draw color set with GeUserArea.DrawSetPen().

    BMP_APPLY_COLORPROFILE

    Applies the color profile.

    BMP_DIMIMAGE

    Darkens the bitmap (like the activated palette icons in Cinema 4D)

    BMP_MIRROR_H

    Mirrors the bitmap horizontally.

    BMP_MIRROR_H_FORBID

    Does not mirror the bitmap horizontally.

    BMP_MIRROR_V

    Mirrors the bitmap vertically.

    BMP_MIRROR_V_FORBID

    Does not mirror the bitmap vertically.

GeUserArea.DrawBorder(self, type, x1, y1, x2, y2)

Fills a rectangular area with the current pen color between (x1,y1) and (x2,y2).

Parameters
  • type (int) –

    The border type. Possible values:

    BORDER_NONE

    No border.

    BORDER_THIN_IN

    Thin border inward.

    BORDER_THIN_OUT

    Thin border outward.

    BORDER_IN

    Normal border inward.

    BORDER_OUT

    Normal border outward.

    BORDER_GROUP_IN

    Group border inside.

    BORDER_GROUP_OUT

    Group border outside.

    BORDER_OUT2

    Outward border 2.

    BORDER_OUT3

    Outward border 3

    BORDER_BLACK

    Thin black line.

    BORDER_ACTIVE_1

    Active border 1.

    BORDER_ACTIVE_2

    Active border 2.

    BORDER_ACTIVE_3

    Active border 3.

    BORDER_ACTIVE_4

    Active border 4.

    BORDER_GROUP_TOP

    Border along the top.

    BORDER_ROUND

    Border with round corners.

    BORDER_SCHEME_EDIT

    Edit field border like the shortcut gadget for example.

    BORDER_SCHEME_EDIT_NUMERIC

    Edit field border that is open to the right like the link field for example.

    BORDER_OUT3l

    Outward border 3, open to the left.

    BORDER_OUT3r

    Outward border 3, open to the right.

    BORDER_THIN_INb

    Thin border inward, open to the botton.

    BORDER_MASK

    Masks out border type.

    BORDER_TEXT_DOTTED

    New in version R21:
    Only used with GeDialog.AddStaticText().
    Draws a dotted line at right of text, useful to visually connect the text with its parameter.

    BORDER_WITH_TITLE_MONO

    Display group title with monospaced font.

    BORDER_WITH_TITLE_BOLD

    Display group title with bold font.

    BORDER_WITH_TITLE

    Display group title in the border.

  • x1 (int) – The X coordinate of the first corner.

  • y1 (int) – The Y coordinate of the first corner.

  • x2 (int) – The X coordinate of the opposite corner.

  • y2 (int) – The Y coordinate of the opposite corner.

GeUserArea.DrawCustomButton(self, x, y, w, h, ids, nofill, focus)

Draws a button.

New in version R25.010.

Parameters
  • x (int) – The X start coordinate.

  • y (int) – The Y start coordinate.

  • w (int) – The button width.

  • h (int) – The button height.

  • ids (List[int]) – A list of ids.

  • nofill (bool) – True if the button should not be filled, otherwise False.

  • focus (True if the button should be drawn as focused, otherwise False.) – bool

GeUserArea.DrawEllipseFill(self, centerPoint, radius)

Draws an ellipse filled with color.

New in version R25.010.

Parameters
  • centerPoint (List[float]) – The XY coordinate of the center of the ellipse. The list should have 2 elements, the first entry is X the second is Y.

  • radius (List[float]) – The radius of the ellipse. The list should have 2 elements, the first entry correspond respectively to the width and the height of the ellispe.

GeUserArea.DrawEllipseLine(self, centerPoint, radius, lineWidth=1.0, lineStyle=LINESTYLE_NORMAL)

Draws an ellipse line.

New in version R25.010.

Parameters
  • centerPoint (List[float]) – The XY coordinate of the center of the ellipse. The list should have 2 elements, the first entry is X the second is Y.

  • radius (List[float]) – The list should have 2 elements, the first entry correspond respectively to the width and the height of the ellispe.

  • lineWidth (float) – The width of the ellipse curve.

  • lineStyle (int) –

    The line style of the ellipse curve:

    Symbol ID

    NORMAL

    DOTTED

    DASHED

    DASHED_INV

    DASHED_BIG

GeUserArea.DrawFrame(self, x1, y1, x2, y2, lineWidth=1.0, lineStyle=LINESTYLE_NORMAL)

Draws a rectangular frame with the current pen color between (x1,y1) and (x2,y2).

Parameters
  • x1 (int) – The X start coordinate.

  • y1 (int) – The Y start coordinate.

  • x2 (int) – The X end coordinate.

  • y2 (int) – The Y end coordinate.

  • lineWidth (float) – Line width to draw the line.

  • lineStyle (int) –

    The line style of the Bezier curve:

    Symbol ID

    NORMAL

    DOTTED

    DASHED

    DASHED_INV

    DASHED_BIG

GeUserArea.DrawGetFontBaseLine(self)

Returns the base line of the set font.

Return type

int

Returns

The base line of the set font.

GeUserArea.DrawGetFontHeight(self)

Returns the height in pixels of a line of text in the current font.

Return type

int

Returns

Height in pixels.

GeUserArea.DrawGetTextIndexFromPixel(self, text, pixelPosition)

Retrieves the index from a position within the text.

New in version 2024.0.0.

Parameters
  • text (str) – Text to process.

  • pixelPosition (float) – Pixel to examine.

Return type

int

Returns

Index of the pixel within the text.

GeUserArea.DrawGetTextWidth(self, text)

Returns the width in pixels of the string text, if it were drawn in the current font.

Parameters

text (str) – The string to measure.

Return type

int

Returns

The width in pixels.

GeUserArea.DrawGetTextWidth_ListNodeName(self, node, fontid=FONT_STANDARD)

Retrieves the width in pixels of the name of node.

Parameters
  • node (c4d.BaseList2D) – The node to check.

  • fontid (int) –

    The font to use:

    FONT_DEFAULT

    Default font.

    FONT_STANDARD

    Standard font.

    FONT_BOLD

    Bold font.

    FONT_MONOSPACED

    Monospaced font.

    FONT_BIG

    Big font.

    FONT_BIG_BOLD

    Big Bold font.

    FONT_ITALIC

    Italic font.

Return type

int

Returns

The text width in pixels.

GeUserArea.DrawImageRef(self, imageRef, wx, wy, ww, wh, opacity, mode)
Draws a image into the user area.
Parameters
  • imageRef (maxon.ImageBaseRef) – maxon.ImageRef to draw.

  • wx (int) – X coordinate of the upper left corner of the destination area.

  • wy (int) – Y coordinate of the upper left corner of the destination area.

  • ww (int) – Width of the destination area.

  • wh (int) – Height of the destination area.

  • opacity (float) – Opacity to draw with (0.0 == completely transparent, 1.0 == fully opaque)

  • mode (int) – maxon.IMAGEINTERPOLATIONMODE

GeUserArea.DrawLine(self, x1, y1, x2, y2)

Draws a line with the current pen color between (x1,y1) and (x2,y2).

Parameters
  • x1 (int) – The X start coordinate.

  • y1 (int) – The Y start coordinate.

  • x2 (int) – The X end coordinate.

  • y2 (int) – The Y end coordinate.

GeUserArea.DrawPolyFill(self, p, closed)

Draws a polygon filled with color.

New in version R25.010.

Parameters
  • p (List[float]) –

    The XY coordinate of each vertices of the final polygon.

    Note

    Each vertex is defined by 2 float, so the length of p should be a multiple of 2 where the first entry is X and the second is Y.

  • closed (bool) – If True, the last point of the last segment connects back to the starting point, otherwise False.

GeUserArea.DrawPolyLine(self, p, closed, lineWidth=1.0, lineStyle=LINESTYLE_NORMAL)

Draws a polygon line.

New in version R25.010.

Parameters
  • p (List[float]) –

    The XY coordinate of each vertices of the final polygon.

    Note

    Each vertex is defined by 2 float, so the length of p should be a multiple of 2 where the first entry is X and the second is Y.

  • closed (bool) – If True, the last point of the last segment connects back to the starting point, otherwise False.

  • lineWidth (float) – The width of the polygon curve.

  • lineStyle (int) –

    The line style of the polygon curve:

    Symbol ID

    NORMAL

    DOTTED

    DASHED

    DASHED_INV

    DASHED_BIG

GeUserArea.DrawRectangle(self, x1, y1, x2, y2)

Fills a rectangular area with the current pen color between (x1,y1) and (x2,y2).

Parameters
  • x1 (int) – The X coordinate of the first corner.

  • y1 (int) – The Y coordinate of the first corner.

  • x2 (int) – The X coordinate of the opposite corner.

  • y2 (int) – The Y coordinate of the opposite corner.

GeUserArea.DrawSetFont(self, fontid)

Sets the text font.

Parameters

fontid (int) –

The font to use:

FONT_DEFAULT

Default font.

FONT_STANDARD

Standard font.

FONT_BOLD

Bold font.

FONT_MONOSPACED

Monospaced font.

FONT_BIG

Big font.

FONT_BIG_BOLD

Big Bold font.

FONT_ITALIC

Italic font.

GeUserArea.DrawSetOpacity(self, opacity)

Sets the opacity value.

Parameters

opacity (float) – The opacity to set from 0.0 to 1.0.

GeUserArea.DrawSetPen(self, color)

Sets the draw color.

Parameters

color (c4d.Vector) – The color to set from 0.0 to 1.0.

GeUserArea.DrawSetTextCol(self, fg, bg)

Sets the draw color.

Parameters
  • fg (c4d.Vector) – A color vector from 0.0 to 1.0.

  • bg (c4d.Vector) – A color vector from 0.0 to 1.0.

GeUserArea.DrawSetTextRotation(self, textrotation)

Rotates the font for drawing.

Note

Rotation is clockwise and must be set to 0 after drawing.

Parameters

textrotation (float) – The text rotation in degree.

GeUserArea.DrawText(self, text, x, y, flags=DRAWTEXT_STD_ALIGN)

Draws the string txt with the upper left corner at the position (x, y).

Note

Use DrawGetTextWidth() and DrawGetFontHeight() to find out where to place the text.

Parameters
  • text (str) – The string to draw.

  • x (int) – X coordinate of the upper left corner of the drawn text.

  • y (int) – Y coordinate of the upper left corner of the drawn text.

  • flags (int) – Flags.

GeUserArea.FillBitmapBackground(self, bmp, offsetx, offsety)
Fills the bitmap bmp with the current pen color.
The offsetx and offsety parameters are used when the background is a pattern and are given in local coordinates of the user area.

Note

This can be used to make semi-transparent bitmap blits.

Parameters
  • bmp (c4d.bitmaps.BaseBitmap) – The bitmap to fill.

  • offsetx (int) – The X offset in pixels.

  • offsety (int) – The X offset in pixels.

GeUserArea.GetColorRGB(self, colorid)

Gets the RGB values associated with a color ID.

Parameters

colorid (int) – The color ID. See COLOR constants.

Return type

dict{r: int, g: int, b: int}

Returns

The color from 0 to 255 in the dict with the keys r, g and b.

GeUserArea.ActivateFading(self, milliseconds)

Activates the fading.

New in version R14.014.

Parameters

milliseconds (int) – Time for the fading.

GeUserArea.AdjustColor(self, colorid, highlightid, percent)

Sets the blend colors for user area fading.

New in version R14.014.

Parameters
  • colorid (int) – A color ID to fade from. See COLOR constants.

  • highlightid (int) – A color ID to fade to. See COLOR constants.

  • percent (float) – Fading percentage.

GeUserArea.GetInputEvent(self, askdevice, res)

Gets the next input event for a certain device from the event queue.

See also

Input Events.

Parameters
  • askdevice (int) – The device to ask. Either BFM_INPUT_MOUSE or BFM_INPUT_KEYBOARD.

  • res (c4d.BaseContainer) – The result container.

Return type

bool

Returns

True if the event could be retrieved in res, otherwise False.

GeUserArea.GetInputState(self, askdevice, askchannel, res)

Polls a certain channel of a device for the current input state.

See also

Input Events.

Parameters
  • askdevice (int) – The device to ask. Either BFM_INPUT_MOUSE or BFM_INPUT_KEYBOARD.

  • askchannel (int) – The channel to ask.

  • res (c4d.BaseContainer) – The result container.

Return type

bool

Returns

True if the state could be retrieved in res, otherwise False.

GeUserArea.IsHotkeyDown(self, id)

Checks the standard navigation hotkeys.

Parameters

id (int) –

The hotkey to check:

HOTKEY_CAMERA_MOVE

Camera move.

HOTKEY_CAMERA_SCALE

Camera scale

HOTKEY_CAMERA_ROTATE

Camera rotate.

HOTKEY_OBJECT_MOVE

Object move.

HOTKEY_OBJECT_SCALE

Object scale

HOTKEY_OBJECT_ROTATE

Object rotate.

HOTKEY_SELECT_FREE

Freehand selection.

HOTKEY_SELECT_LIVE

Live selection.

HOTKEY_SELECT_RECT

Rectangle selection.

HOTKEY_MODEL_SCALE

Model scale.

HOTKEY_ZOOM

Zoom.

HOTKEY_PARENT_MOVE

Parent object move.

HOTKEY_RESIZE_BRUSH

Resize brush.

Return type

int

Returns

A value != 0 if the hotkey is pressed.

HOTKEYFLAGS_NONE

Nothing was used.

HOTKEYFLAGS_MOUSE

Mouse was used.

HOTKEYFLAGS_KEYBOARD

Keyboard was used.

GeUserArea.KillEvents(self)

Flushes all events from the window message queue.

Note

For example if you loop while the mouse is down (polling) you can call this command to flush all keydowns/mouseclicks that are made during the loop.

GeUserArea.GetPixelRatio(self)

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

Returns

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

Return type

float

GeUserArea.ScrollArea(self, xdiff, ydiff, x, y, w, h)

Scrolls the area from (x,y) to (x+w,y+h) in the direction specified by xdiff and ydiff.

Parameters
  • xdiff (int) – X distance to scroll.

  • ydiff (int) – Y distance to scroll.

  • x (int) – X coordinate of the upper left corner of the area to scroll.

  • y (int) – Y coordinate of the upper left corner of the area to scroll.

  • w (int) – Width of the area to scroll.

  • h (int) – Height of the area to scroll.

GeUserArea.GetDialog(self)

Gets the user area’s parent dialog.

Warning

Only works if the parent dialog is a Python dialog.

Return type

c4d.gui.GeDialog

Returns

The user area’s parent dialog.