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

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.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.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.DrawGetTextWidth(self, text)	Returns the width in pixels of the string text, if it were drawn in the current font.
GeUserArea.DrawLine(self, x1, y1, x2, y2)	Draws a line with the current pen color between (x1,y1) and (x2,y2).
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.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.

Uncategorized

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.
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.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.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.
GeUserArea.LayoutChanged(self)	Tells Cinema 4D that the user area now has new dimensions. That causes c4d to call:

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.

Return type

c4d.gui.GeUserArea

Returns

A new user area.

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 message ID:

  EVMSG_CHANGE	Sent by EventAdd().
  EVMSG_DOCUMENTRECALCULATED	Sent while drawing after the animation, expressions and cache building have been done. It allows that certain managers (e.g. attribute manager) update their values to the changes done by the expressions etc. Any reactions on this message should be pretty fast! No modifying stuff must be done here as the draw thread is running at the same time and accesses the same data!
  EVMSG_TOOLCHANGED	A tool setting has changed (local event).
  EVMSG_GRAPHVIEWCHANGED	Something in XPresso has been changed (local event).
  EVMSG_AUTKEYMODECHANGED	The autokey mode was changed.
  EVMSG_UPDATEHIGHLIGHT	A special message sent by Cinema 4D in the case that only the highlighting changes. This happens for example when the mouse is moved over the viewport. Plugins usually do not need to care about this.
  EVMSG_UPDATEBASEDRAW	Sent in the case that the view should be redrawn.
  EVMSG_CHANGEDSCRIPTMODE	Sent when the script mode changed.
  EVMSG_SETMODE	Private.
  EVMSG_SHOWIN_FC	Show in Function Curve editor.
  EVMSG_SHOWIN_LM	Show in Layer Manager.
  EVMSG_SHOWIN_MT	Show in Motion editor.
  EVMSG_SHOWIN_SB	Show in Scene Browser.
  EVMSG_SHOWIN_TL	Show in Timeline.
  EVMSG_TLOM_MERGE	Private.
  EVMSG_TIMELINESELECTION	A timeline selection has been changed (local event).
  EVMSG_TL_FCURVE_POS	Show and frame fcurve position tracks.
  EVMSG_TL_FCURVE_ROT	Show and frame fcurve rotation tracks.
  EVMSG_TL_FCURVE_SCALE	Show and frame fcurve scale tracks.
  EVMSG_BROWSERCHANGE	Something in the browser has been changed (local event).
  EVMSG_MATERIALSELECTION	A material selection has been changed (local event).
  EVMSG_FCURVECHANGE	Something in the F-Curve manager has been changed (local event).
  EVMSG_RAYTRACER_FINISHED	Private.
  EVMSG_MATERIALPREVIEW	Private.
  EVMSG_ACTIVEVIEWCHANGED	Private.
  EVMSG_ASYNCEDITORMOVE	The user moved something in the editor window. Managers should update things like position fields.
  EVMSG_TIMECHANGED	Private.
  EVMSG_VIEWWINDOW_OUTPUT	Private.
  EVMSG_VIEWWINDOW_3DPAINTUPD	Private.
  EVMSG_UPDATESCHEME	Scheme has been updated.
  EVMSG_TAKECHANGED	New in version R17.032: Sent by the Take System when the current Take ID changed to let all managers react to the new status.

• 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)

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

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.

• 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 (array of float) –

  An array with the bezier curves points.

  Here is an example of initializing the curve points array.

  points = array.array('f', xrange(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.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.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.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.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.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.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.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.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

dict{x: int, y: int}

Returns

The converted coordinates or None.

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

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

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

dict{x: int, y: int}

Returns

The converted coordinates or None.

GeUserArea.LayoutChanged(self)

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

1. GetMinSize()

2. Sized()

3. InitValues()

4. DrawMsg()