c4d.gui.GeUserArea - a customizable dialog gadget

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

The class to create custom user areas.

class c4d.gui.GeUserArea

//Constructor

• GeUserArea.__init__()

//Methods to override

• GeUserArea.Init()
• GeUserArea.DrawMsg()
• GeUserArea.GetMinSize()
• GeUserArea.InputEvent()

• GeUserArea.Redraw()
• GeUserArea.SendParentMessage()
• GeUserArea.GetId()
• GeUserArea.GetWidth()
• GeUserArea.GetHeight()
• GeUserArea.IsEnabled()
• GeUserArea.HasFocus()
• GeUserArea.SetTimer()

• GeUserArea.GetInputState()
• GeUserArea.GetInputEvent()
• GeUserArea.KillEvents()
• GeUserArea.IsHotkeyDown()

• GeUserArea.GetColorRGB()
• GeUserArea.DrawSetPen()
• GeUserArea.DrawSetTextCol()
• GeUserArea.DrawLine()
• GeUserArea.DrawRectangle()
• GeUserArea.DrawBitmap()
• GeUserArea.DrawText()
• GeUserArea.FillBitmapBackground()
• GeUserArea.DrawSetFont()
• GeUserArea.DrawGetTextWidth()
• GeUserArea.DrawGetFontHeight()

• GeUserArea.SetClippingRegion()
• GeUserArea.ClearClippingRegion()
• GeUserArea.OffScreenOn()

• GeUserArea.LayoutChanged()

• GeUserArea.GetBorderSize()
• GeUserArea.DrawBorder()

Methods

static GeUserArea.__init__()

Return type:GeUserArea or None Returns:A new user area.

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. Return True if successful, or False to signalize an error.

Return type:bool Returns:Return 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. Return TRUE if successful, or FALSE to signalize an error.

Return type:bool Returns:Return True if successful, or False to signalize an error.

GeUserArea.GetMinSize(self)

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

Return type:

tuple of ints

Returns:

Return a tuple with two elements just like this:

def GetMinSize(self):

#do a calculation here return self.width, self.height

GeUserArea.DrawMsg(self, x1, y1, x2, y2, msg)

Called when C4D wants you to draw your userarea. Use the drawing functions to update your user area in the region speicified 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.

GeUserArea.InputEvent(self, msg)

Called when an input event is received. All information about the input event is stored in the msg container.

Parameter:msg (BaseContainer) – The event container. Return type:bool Returns:Return True if the event was handled, otherwise False.

GeUserArea.CoreMessage(self, id, msg)

Called when a C4D core messages is received. The message type is given by id and the message information is stored in msg.

Parameters:

• id (int) – The message type.
• msg (BaseContainer) – The event container.

Return type:

bool

Returns:

Return True if the event was handled, otherwise False.

GeUserArea.Timer(color)

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

Parameter:color (BaseContainer) – The timer message container.

GeUserArea.Message(msg, result)

Override this function if you want to react to more messages than covered by the other functions. Normally this is not necessary. Be sure to include a call the parent version of this function, GeUserArea.Message(self, msg, result).

Parameters:

• msg (BaseContainer) – The timer message container.
• result (BaseContainer) – The timer message container.

Return type:

int

Returns:

The return value depends on the message.

GeUserArea.Redraw(thread=False)

Forces the user area to redraw itself.

Parameter:thread (bool) – Must be set to True if the function is called from another thread than the main C4D thread.

GeUserArea.SendParentMessage(msg)

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

Parameter:msg (BaseContainer) – The message container.

GeUserArea.GetId()

Returns the ID of the user area.

Return type:int Returns:The ID.

GeUserArea.GetWidth()

Returns the width of the user area.

Return type:int Returns:Width in pixels.

GeUserArea.GetHeight()

Returns the height of the user area.

Return type:int Returns:Height in pixels.

GeUserArea.IsEnabled()

Indicates the enabled state.

Return type:bool Returns:TRUE if the user area is enabled in the dialog, otherwise FALSE.

GeUserArea.HasFocus()

Indicates the focus state.

Return type:bool Returns:TRUE if the user area has the focus in the dialog, otherwise FALSE.

GeUserArea.SetTimer(x)

Initializes the timer clock, so that GeUserArea.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.

Parameter:x (int) – The timer interval in milliseconds.

GeUserArea.GetInputState(askdevice, askchannel)

Polls a certain channel of a device for the current input state. If the return value is not None, the result container is just like an input event message, otherwise no state was available.

Parameters:

• askdevice (int) – The device to ask.
• askchannel (int) – The channel of the device.
• color (BaseContainer) – The result.

GeUserArea.GetInputEvent(askdevice)

Gets the next input event for a certain device from the event queue. If the return value is not None, the result container is just like an input event message, otherwise no state was available.

Parameters:

• askdevice (int) – The device to ask.
• color (BaseContainer) – The result or None.

GeUserArea.KillEvents()

Flushes all events from the window message queue. 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.IsHotkeyDown(id)

Checks the standard navigation hotkeys.

Parameter:id (int) –

The hotkey:

**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_MODEL_SCALE	Model scale.
HOTKEY_ZOOM	Zoom.
HOTKEY_SELECT_FREE	Freehand selection.
HOTKEY_SELECT_LIVE	Live selection.
HOTKEY_SELECT_RECT	Rectangle selection.

Return type:bool Returns:TRUE if the hotkey is down.

GeUserArea.GetColorRGB(colorid)

Gets the RGB values associated with a color code.

Parameter:type (int) –

A color constant:

COLOR_3DTEXT
COLOR_XOR
COLOR_TRANS
COLOR_BG
COLOR_BGEDIT
COLOR_BGFOCUS
COLOR_TEXT
COLOR_TEXTFOCUS
COLOR_EDGELT
COLOR_EDGEWH
COLOR_EDGEDK
COLOR_EDGEBL
COLOR_DBARFG1
COLOR_DBARBG1
COLOR_DBARFG2
COLOR_DBARBG2
COLOR_BGGADGET
COLOR_BGSELECTEDTEXT
COLOR_FGSELECTEDTEXT
COLOR_TIMELINE
COLOR_BGTRISTATE
COLOR_BG_DARK1
COLOR_BG_DARK2
COLOR_EMBOSS_WH
COLOR_EMBOSS_DK
COLOR_TIMELINE_BG
COLOR_TIMELINE_BG_DARK
COLOR_TIMELINE_TEXT
COLOR_TIMELINE_TEXT_SELECTED
COLOR_TIMELINE_TEXT_SELECTED2
COLOR_TIMELINE_LINES
COLOR_TIMELINE_LINES_SEL
COLOR_TIMELINE_LINES_SEPARATOR1
COLOR_TIMELINE_LINES_SEPARATOR2
COLOR_TIMELINE_TREE
COLOR_TIMELINE_LOOP
COLOR_TIMELINE_SELECTION
COLOR_TIMELINE_TICKS1
COLOR_TIMELINE_TICKS2
COLOR_TIMELINESCROLLER_MINMAX
COLOR_TIMELINESCROLLER_CURRENT
COLOR_BROWSER_LINES_SELECTED
COLOR_FCURVE_BG
COLOR_FCURVE_TEXT
COLOR_FCURVE_LINES
COLOR_FCURVE_MAINGRID
COLOR_FCURVE_SUBGRID
COLOR_FCURVE_LLTGRAY
COLOR_FCURVE_GRAY1
COLOR_FCURVE_GRAY2
COLOR_FCURVE_GRAY3
COLOR_FCURVE_POINTSELECTED
COLOR_MATERIALMANAGER_BG
COLOR_MATERIALMANAGER_TEXT
COLOR_MATERIALMANAGER_TEXT_SELECTED
COLOR_MATERIALMANAGER_SELECTED
COLOR_OBJECTMANAGER_BG
COLOR_OBJECTMANAGER_ACTIVECAMERA
COLOR_OBJECTMANAGER_INACTIVECAMERA
COLOR_OBJECTMANAGER_TEXT
COLOR_OBJECTMANAGER_TEXT_ACTIVE
COLOR_OBJECTMANAGER_TEXT_ACTIVE2
COLOR_OBJECTMANAGER_SELECTEDTAG
COLOR_OBJECTMANAGER_TREE
COLOR_SPREADSHEET_BG
COLOR_SPREADSHEET_TEXT
COLOR_SPREADSHEET_EDITBG
COLOR_SPREADSHEET_EDITTEXT
COLOR_SPREADSHEET_SELECTED
COLOR_CONSOLE_BG
COLOR_CONSOLE_TEXT
COLOR_PAINTER_SELECTED
COLOR_PAINTER_TREE
COLOR_SYNTAX_COFFEE
COLOR_SYNTAX_INCLUDE
COLOR_SYNTAX_COMMENT
COLOR_SYNTAX_COMMENTWRONG
COLOR_SYNTAX_STRING
COLOR_TEXT_SELECTED
COLOR_TEXT_SELECTED_DARK
COLOR_TEXT_DISABLED
COLOR_TEXT_EDIT
COLOR_TEXT_EDIT_DISABLED
COLOR_TEXT_MENU
COLOR_TEXT_MENU_DISABLED
COLOR_TEXT_TAB
COLOR_TEXT_TAB_DISABLED
COLOR_TEXT_BUTTON
COLOR_TEXT_BUTTON_DISABLED
COLOR_TEXT_COMBO
COLOR_TEXT_COMBO_DISABLED
COLOR_MENU_BG
COLOR_MENU_BG_SELECTED
COLOR_MENU_TEXT
COLOR_MENU_TEXT_DISABLED
COLOR_MENU_TEXT_SELECTED
COLOR_MENU_BORDER_WH
COLOR_MENU_BORDER_DK
COLOR_TIMELINE_LAYER0
COLOR_TIMELINE_LAYER1
COLOR_TIMELINE_LAYER2
COLOR_TIMELINE_LAYER3
COLOR_TIMELINE_LAYER4
COLOR_TIMELINE_LAYER5
COLOR_TIMELINE_LAYER6
COLOR_TIMELINE_LAYER7
COLOR_BG_MM_E_ACTIVE_TEXTURE
COLOR_FG_MM_E_ACTIVE_TEXTURE
COLOR_BG_MM_E_INACTIVE_TEXTURE
COLOR_FG_MM_E_INACTIVE_TEXTURE
COLOR_BG_MM_E_SELECTED_LAYER
COLOR_FG_MM_E_SELECTED_LAYER
COLOR_BG_MM_E_ACTIVE_LAYER
COLOR_FG_MM_E_ACTIVE_LAYER
COLOR_BG_MM_E_INACTIVE_LAYER
COLOR_FG_MM_E_INACTIVE_LAYER
COLOR_BG_TEXTUREVIEW
COLOR_OBJECTMANAGER_TEXT_ACTIVE3
COLOR_SYNTAX_CONSTANT
COLOR_SYNTAX_FUNCTION
COLOR_SYNTAX_CLASS
COLOR_SYNTAX_MEMBER
COLOR_CTIMELINE_GRID
COLOR_CTIMELINE_POSITION
COLOR_CTIMELINE_ROTATION
COLOR_CTIMELINE_SCALE
COLOR_CTIMELINE_PLA
COLOR_CTIMELINE_COLOR
COLOR_CTIMELINE_GENERAL
COLOR_CTIMELINE_MASTER
COLOR_CTIMELINE_MASTERIDENTICAL
COLOR_CTIMELINE_CURRENTFRAME
COLOR_CTIMELINE_PREVIEW
COLOR_CTIMELINE_BREAKDOWN
COLOR_CTIMELINE_HLECURVE
COLOR_DBARBG3
COLOR_CONTENTBROWSER_TEXT
COLOR_CONTENTBROWSER_BG_TEXT_ACT
COLOR_CONTENTBROWSER_BG_TEXT_INACT
COLOR_CONTENTBROWSER_FG_TEXT_ACT
COLOR_CONTENTBROWSER_FG_TEXT_INACT
COLOR_CONTENTBROWSER_NOTAVAILABLE
COLOR_BG_GROUP1
COLOR_BG_GROUP2
COLOR_POWERSOUND
COLOR_BG_GROUPBAR1
COLOR_BG_GROUPBAR2
COLOR_CTIMELINE_CLIPTEXT
COLOR_CTIMELINE_CLIP
COLOR_CTIMELINE_CLIPMASTER
COLOR_BUBBLE_BG
COLOR_BUBBLE_FG
COLOR_BUBBLE_BORDER
COLOR_CTIMELINE_CLIPTEXTHL
COLOR_TRACK_X
COLOR_TRACK_Y
COLOR_TRACK_Z
COLOR_TRACK_S
COLOR_AM_ANIMDOT
COLOR_AM_ANIMDOT_CHANGED
COLOR_AM_BPDOT
COLOR_PV_BUCKET
COLOR_PV_TEXT
COLOR_PV_CACHE
COLOR_PV_NOTALL
COLOR_PV_COMPARE
COLOR_PV_FPS

Return type:dict of int Returns:The color or None.

GeUserArea.DrawSetPen(color)

Sets the draw color.

Param:A color vector.

GeUserArea.DrawSetTextCol(fg, bg)

Sets the draw color.

Parameters:

• fg (Vector) – A color vector.
• bg (Vector) – A color vector.

GeUserArea.DrawLine(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(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.DrawBitmap(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 (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_DARKEN	Darkens the bitmap (like the activated palette icons in C4D)
  BMP_EMBOSSED	Embosses the bitmap (like the grayed palette icons in C4D).
  BMP_ALLOWALPHA	Use the alpha channel to blend with background.

GeUserArea.SetFont(type)

Sets the text font.

Parameter:type (int) –

Sets the text font.

FONT_DEFAULT	Default font.
FONT_STANDARD	Standard font.
FONT_BOLD	Bold font.
FONT_MONOSPACED	Monospaced font.

GeUserArea.set_text_pen(fg, bg)

Call this in draw_msg() to set the color for the following text elements.

Parameters:

• fg (Vector) – The foreground color
• bg (Vector) – The background color

GeUserArea.draw_border(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.DrawText(text, x, y[, flags=DRAWTEXT_STD_ALIGN])

Draws the string txt with the upper left corner at the position (x,y). Use get_font_height and get_font_width 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(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. This can be used to make semi-transparent bitmap blits.

Parameters:

• bmp (BaseBitmap) – The bitmap to fill.
• offsetx (int) – The X offset in pixels.
• offsety (int) – The X offset in pixels.

GeUserArea.DrawSetFont(fontid)

Sets the text font.

Parameter:fontid (int) –

The font to use:

FONT_DEFAULT	Default font.
FONT_STANDARD	Standard font.
FONT_BOLD	Bold font.
FONT_MONOSPACED	Monospaced font.

GeUserArea.DrawGetTextWidth(text)

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

Parameter:text (str) – The string to measure. Return type:int Returns:The width in pixels.

GeUserArea.DrawGetFontHeight()

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

Return type:int Returns:Height in pixels.

GeUserArea.SetClippingRegion(x, y, w, h)

Should be used at the top of the GeUserArea.DrawMsg>() function to specify the clipping region. Without specifying a dedicated clipping region everything will be painted, even if it’s outside the user area!

Note

GeUserArea.OffScreenOn() automatically sets the clipping region to the whole user area, so normally this function isn’t 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.ClearClippingRegion()

Clears any clipping region set with GeUserArea.SetClippingRegion().

GeUserArea.OffScreenOn([x, y, w, h])

Enables double buffering to avoid blinking and flickering effects. The GUI will automatically switch planes. Just call this function before drawing things. Sets the clipping area to the rectangular area determined by x, y, w and h.

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

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

1. GetMinSize
2. DrawMsg

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

Draws a border within the rectangle from (x1,y1) to (x2,y2).

Parameters:

• type (int) –

  The border:

  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_MASK	Masks out border type.
  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.GetBorderSize(type)

Retrieves the space required to draw a border.

Parameter: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_MASK	Masks out border type.
BORDER_WITH_TITLE	Display group title in the border.

Return type:dict of int Returns:The space.