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__(self)

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

Methods to Override

`GeUserArea.CoreMessage(self, id, msg)`	Called when a Cinema 4D core messages is received.
`GeUserArea.DrawMsg(self, x1, y1, x2, y2, msg)`	Called when Cinema 4D wants you to draw your userarea.
`GeUserArea.GetMinSize(self)`	Override this function to specify a minimum size for the user area.
`GeUserArea.Init(self)`	Called once when the user area is initialized by the GUI, before the layout is calculated.
`GeUserArea.InitValues(self)`	Called after the layout is calculated, before the user area is drawn.
`GeUserArea.InputEvent(self, msg)`	Called when an input event is received.
`GeUserArea.Message(self, msg, result)`	Override this function to react to more messages than covered by the other functions. Normally this is not necessary.
`GeUserArea.Sized(self, w, h)`	Called when the user area is resized.
`GeUserArea.Timer(self, msg)`	If you subscribe to timer events using `SetTimer()` (x), this function is called every x th millisecond.

Basic Functions

GeUserArea.LayoutChanged(self)

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

Basic Methods

`GeUserArea.GetHeight(self)`	Returns the height of the user area.
`GeUserArea.GetId(self)`	Returns the ID of the user area.
`GeUserArea.GetWidth(self)`	Returns the width of the user area.
`GeUserArea.HasFocus(self)`	Indicates the focus state.
`GeUserArea.IsEnabled(self)`	Indicates the enabled state.
`GeUserArea.IsR2L(self)`	Checks if the user area has to be drawn in right-to-left layout mode.
`GeUserArea.Redraw(self[, thread])`	Forces the user area to redraw itself.
`GeUserArea.SendParentMessage(self, msg)`	Use this function to send a custom message to the parent dialog.
`GeUserArea.SendParentMessageResult(self, msg)`	Sends a custom message to the parent dialog.
`GeUserArea.SetTimer(self, x)`	Initializes the timer clock, so that `Timer()` is called every timer milliseconds.

Border Methods

GeUserArea.GetBorderSize(self, type)

Retrieves the space required to draw a border.

Coordinates Transformation

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

Drag and Drop Methods

`GeUserArea.CheckDropArea(self, msg, horiz, vert)`	Checks the drag position in a drag event message against the user area’s position in the layout.
`GeUserArea.GetDragObject(self, msg)`	Extracts the object from a drag and drop message.
`GeUserArea.GetDragPosition(self, msg)`	Extracts local drag coordinates from a drag and drop event.
`GeUserArea.HandleMouseDrag(self, msg, type, data, ...)`	Starts a drag and drop operation.
`GeUserArea.MouseDrag(self)`	Polls the mouse during a drag started with `MouseDragStart()`.
`GeUserArea.MouseDragEnd(self)`	Checks why the mouse drag ended. Allows to perform any undo operations needed if the user canceled the drag.
`GeUserArea.MouseDragStart(self, button, mx, my, flag)`	Starts a mouse drag. Only call this when a mouse down message is received.
`GeUserArea.SetDragDestination(self, cursor)`	Sets the correct cursor during drag and drop handling.

Draw Helpers Methods

`GeUserArea.ClearClippingRegion(self)`	Clears any clipping region set with `SetClippingRegion()`.
`GeUserArea.OffScreenOn(self[, x, y, w, h])`	Enables double buffering to avoid blinking and flickering effects.
`GeUserArea.SetClippingRegion(self, x, y, w, h)`	Should be used at the top of the `DrawMsg()` function to specify the clipping region.

Draw Methods

`GeUserArea.DrawBezier(self, sx, sy, p, ...)`	Draws concatenated bezier curves.
`GeUserArea.DrawBezierFill(self, startPoint, ...)`	Draws concatenated Bezier curves.
`GeUserArea.DrawBezierLine(self, startPoint, ...)`	Draws concatenated Bezier curves.
`GeUserArea.DrawBitmap(self, bmp, wx, wy, ww, ...)`	Draws a bitmap into the user area.
`GeUserArea.DrawBorder(self, type, x1, y1, x2, y2)`	Fills a rectangular area with the current pen color between (x1,y1) and (x2,y2).
`GeUserArea.DrawCustomButton(self, x, y, w, h, ids, ...)`	Draws a button.
`GeUserArea.DrawEllipseFill(self, centerPoint, radius)`	Draws an ellipse filled with color.
`GeUserArea.DrawEllipseLine(self, centerPoint, radius)`	Draws an ellipse line.
`GeUserArea.DrawFrame(self, x1, y1, x2, y2[, ...])`	Draws a rectangular frame with the current pen color between (x1,y1) and (x2,y2).
`GeUserArea.DrawGetFontBaseLine(self)`	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.
`GeUserArea.DrawGetTextIndexFromPixel(self, text, pixelPosition)`	Retrieves the index from a position within the text.
`GeUserArea.DrawGetTextWidth(self, text)`	Returns the width in pixels of the string text, if it were drawn in the current font.
`GeUserArea.DrawGetTextWidth_ListNodeName(self, node[, fontid])`	Retrieves the width in pixels of the name of node.
`GeUserArea.DrawImageRef(self, imageRef, wx, wy, ...)`	Draws a image into the user area.
`GeUserArea.DrawLine(self, x1, y1, x2, y2)`	Draws a line with the current pen color between (x1,y1) and (x2,y2).
`GeUserArea.DrawPolyFill(self, p, closed)`	Draws a polygon filled with color.
`GeUserArea.DrawPolyLine(self, p, closed[, ...])`	Draws a polygon line.
`GeUserArea.DrawRectangle(self, x1, y1, x2, y2)`	Fills a rectangular area with the current pen color between (x1,y1) and (x2,y2).
`GeUserArea.DrawSetFont(self, fontid)`	Sets the text font.
`GeUserArea.DrawSetOpacity(self, opacity)`	Sets the opacity value.
`GeUserArea.DrawSetPen(self, color)`	Sets the draw color.
`GeUserArea.DrawSetTextCol(self, fg, bg)`	Sets the draw color.
`GeUserArea.DrawSetTextRotation(self, textrotation)`	Rotates the font for drawing.
`GeUserArea.DrawText(self, text, x, y[, flags])`	Draws the string txt with the upper left corner at the position (x, y).
`GeUserArea.FillBitmapBackground(self, bmp, offsetx, offsety)`	Fills the bitmap bmp with the current pen color.
`GeUserArea.GetColorRGB(self, colorid)`	Gets the RGB values associated with a color ID.

Fading Methods

`GeUserArea.ActivateFading(self, milliseconds)`	Activates the fading.
`GeUserArea.AdjustColor(self, colorid, ...)`	Sets the blend colors for user area fading.

Inputs Methods

`GeUserArea.GetInputEvent(self, askdevice, res)`	Gets the next input event for a certain device from the event queue.
`GeUserArea.GetInputState(self, askdevice, ...)`	Polls a certain channel of a device for the current input state.
`GeUserArea.IsHotkeyDown(self, id)`	Checks the standard navigation hotkeys.
`GeUserArea.KillEvents(self)`	Flushes all events from the window message queue.

Miscellaneous

`GeUserArea.GetPixelRatio(self)`	Always returns 1.0 except for user areas shown on OS X Retina displays, where it returns 2.0.
`GeUserArea.ScrollArea(self, xdiff, ydiff, x, ...)`	Scrolls the area from (x,y) to (x+w,y+h) in the direction specified by xdiff and ydiff.

Parent Dialog

GeUserArea.GetDialog(self)

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

msg (c4d.BaseContainer) – The message container.
result (c4d.BaseContainer) – A container to store results in.

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:

GetMinSize()

Sized()

InitValues()

DrawMsg()

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.

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.

Symbol ID
NORMAL
DOTTED
DASHED
DASHED_INV
DASHED_BIG

Symbol ID
NORMAL
DOTTED
DASHED
DASHED_INV
DASHED_BIG

Symbol ID
NORMAL
DOTTED
DASHED
DASHED_INV
DASHED_BIG

Symbol ID
NORMAL
DOTTED
DASHED
DASHED_INV
DASHED_BIG