GeUserArea Class Reference

#include <c4d_gui.h>

Detailed Description

A class that can be used to create custom GUI components.
There are already dozens of predefined buttons in the GUI easy available. But if one wants to make his own button, one needs to use the GeUserArea class.
Every user area has a specified drawing area and several commands for drawing lines or text. So it is possible to developer whatever needed, either a 3D trackball or a tree like object manager.

The message sequence when the user area is created:

1. Init() (only once)
   
2. GetMinSize()
   
3. Sized()
   
4. InitValues()
   
5. DrawMsg()
   The message sequence if the user area is scaled:

1. Sized()
   
2. DrawMsg()
   Does not require special allocation, but must be attached to a dialog with GeDialog::AttachUserArea().

Protected Attributes
GeDialog *	dlg

Private Member Functions
	MAXON_DISALLOW_COPY_AND_ASSIGN (GeUserArea)

Private Attributes
Bool	owncu
CUserArea *	cu

Friends
class	GeDialog

Constructor/Destructor
	GeUserArea ()
virtual	~GeUserArea ()

Internal Representation
CUserArea *	Get ()
void	Set (CUserArea *t_cu)

Parent Dialog
GeDialog *	GetDialog ()

Override
virtual Bool	Init ()
virtual Bool	InitValues ()
virtual Bool	GetMinSize (Int32 &w, Int32 &h)
virtual void	Sized (Int32 w, Int32 h)
virtual OBSOLETE	Draw (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
virtual void	DrawMsg (Int32 x1, Int32 y1, Int32 x2, Int32 y2, const BaseContainer &msg)
virtual Bool	InputEvent (const BaseContainer &msg)
virtual Bool	CoreMessage (Int32 id, const BaseContainer &msg)
virtual void	Timer (const BaseContainer &msg)
virtual Int32	Message (const BaseContainer &msg, BaseContainer &result)

Basic Functions
void	Redraw (Bool threaded=false)
Bool	SendParentMessage (const BaseContainer &msg)
GeData	SendParentMessageResult (const BaseContainer &msg)
Int32	GetId () const
Int32	GetWidth () const
Int32	GetHeight () const
Bool	IsEnabled () const
Bool	IsR2L () const
Bool	HasFocus () const
void	LayoutChanged ()
void	SetTimer (Int32 timer)

Input
Bool	GetInputState (Int32 askdevice, Int32 askchannel, BaseContainer &res) const
Bool	GetInputEvent (Int32 askdevice, BaseContainer &res) const
void	KillEvents ()
HOTKEYFLAGS	IsHotkeyDown (Int32 id) const

Draw
void	DrawSetPen (const Vector &color)
void	DrawSetPen (Int32 id)
void	DrawSetPen (const GeData &d)
void	DrawSetOpacity (Float opacity)
void	DrawSetTextCol (Int32 fg, Int32 bg)
void	DrawSetTextCol (const Vector &fg, Int32 bg)
void	DrawSetTextCol (Int32 fg, const Vector &bg)
void	DrawSetTextCol (const Vector &fg, const Vector &bg)
void	DrawSetTextCol (const GeData &fg, const GeData &bg)
Bool	GetColorRGB (Int32 colorid, Int32 &r, Int32 &g, Int32 &b) const
void	ActivateFading (Int32 milliseconds)
void	AdjustColor (Int32 colorid, Int32 highlightid, Float percent)
void	DrawLine (Int32 x1, Int32 y1, Int32 x2, Int32 y2, Float lineWidth=1.0, LINESTYLE lineStyle=LINESTYLE::NORMAL)
void	DrawFrame (Int32 x1, Int32 y1, Int32 x2, Int32 y2, Float lineWidth=1.0, LINESTYLE lineStyle=LINESTYLE::NORMAL)
void	DrawRectangle (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
void	DrawBitmap (BaseBitmap *bmp, Int32 wx, Int32 wy, Int32 ww, Int32 wh, Int32 x, Int32 y, Int32 w, Int32 h, Int32 mode)
void	DrawImageRef (maxon::ImageBaseRef &imageRef, Float wx, Float wy, Float ww, Float wh, Float opacity, maxon::IMAGEINTERPOLATIONMODE mode)
void	DrawText (const maxon::String &txt, Int32 x, Int32 y, Int32 flags=(0|(0<< 4)))
void	DrawBezierLine (const Vector2d &startPoint, const maxon::Block< const BezierPoint > &bezierPoints, Bool closed, Float lineWidth=1.0, LINESTYLE lineStyle=LINESTYLE::NORMAL)
void	DrawBezierFill (const Vector2d &startPoint, const maxon::Block< const BezierPoint > &bezierPoints, Bool closed)
void	DrawPolyLine (const maxon::Block< const Vector2d > &p, Bool closed, Float lineWidth=1.0, LINESTYLE lineStyle=LINESTYLE::NORMAL)
void	DrawPolyFill (const maxon::Block< const Vector2d > &p, Bool closed)
void	DrawEllipseLine (const Vector2d &centerPoint, const Vector2d &radius, Float lineWidth=1.0, LINESTYLE lineStyle=LINESTYLE::NORMAL)
void	DrawEllipseFill (const Vector2d &centerPoint, const Vector2d &radius)
void	DrawCustomButton (Int32 x, Int32 y, Int32 w, Int32 h, const Int32 *ids, Bool nofill, Bool focus)
void	FillBitmapBackground (BaseBitmap *bmp, Int32 offsetx, Int32 offsety)
void	DrawSetFont (Int32 fontid)
Int32	DrawGetTextWidth (const maxon::String &text) const
Int32	DrawGetTextWidth_ListNodeName (BaseList2D *node, Int32 fontid=FONT_STANDARD) const
Int32	DrawGetFontHeight () const
Int32	DrawGetFontBaseLine () const
void	DrawSetTextRotation (Float textrotation)

Clipping
void	SetClippingRegion (Int32 x, Int32 y, Int32 w, Int32 h)
void	ClearClippingRegion ()
Bool	OffScreenOn ()
Bool	OffScreenOn (Int32 x, Int32 y, Int32 w, Int32 h)

Miscellaneous
void	ScrollArea (Int32 xdiff, Int32 ydiff, Int32 x, Int32 y, Int32 w, Int32 h)
Float	GetPixelRatio () const

Coordinates Transformation
Bool	Local2Global (Int32 *x, Int32 *y) const
Bool	Local2Global (Float &x, Float &y) const
Bool	Global2Local (Int32 *x, Int32 *y) const
Bool	Global2Local (Float &x, Float &y) const
Bool	Local2Screen (Int32 *x, Int32 *y) const
Bool	Local2Screen (Float &x, Float &y) const
Bool	Screen2Local (Int32 *x, Int32 *y) const
Bool	Screen2Local (Float &x, Float &y) const

Drag and Drop
Bool	GetDragPosition (const BaseContainer &msg, Int32 *x, Int32 *y) const
Bool	GetDragObject (const BaseContainer &msg, Int32 *type, void **object) const
Bool	HandleMouseDrag (const BaseContainer &msg, Int32 type, void *data, Int32 dragflags)
Bool	SetDragDestination (Int32 cursor)

Border
void	GetBorderSize (Int32 type, Int32 *l, Int32 *t, Int32 *r, Int32 *b) const
void	DrawBorder (Int32 type, Int32 x1, Int32 y1, Int32 x2, Int32 y2)
Bool	CheckDropArea (const BaseContainer &msg, Bool horiz, Bool vert) const

Mouse Drag
void	MouseDragStart (Int32 button, Float mx, Float my, MOUSEDRAGFLAGS flag)
MOUSEDRAGRESULT	MouseDrag (Float *mx, Float *my, BaseContainer *channels)
MOUSEDRAGRESULT	MouseDragEnd ()

Constructor & Destructor Documentation

GeUserArea()

GeUserArea

(

)

Constructs 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()

virtual ~GeUserArea ( )

virtual

Destroys the user area.

Member Function Documentation

MAXON_DISALLOW_COPY_AND_ASSIGN()

MAXON_DISALLOW_COPY_AND_ASSIGN ( GeUserArea  )

private

Get()

CUserArea* Get

(

)

Gets the internal representation of the user area.
Needed by some areas in the API for historical reasons.

Returns

The internal user area representation. nullptr if the user area is not attached to a dialog.

Set()

void Set

(

CUserArea *

t_cu

)

Sets the internal representation of the user area.
Needed by some areas in the API for historical reasons.

Parameters

[in]

t_cu

An internal user area representation.

GetDialog()

GeDialog* GetDialog

(

)

Gets the user area's parent dialog.

Returns

The pointer to the user area's parent dialog.

Init()

virtual Bool Init ( )

virtual

Called once when the user area is initialized by the GUI, before the layout is calculated.
Override this function to initialize anything.

Returns

true if successful, or false to signalize an error.

InitValues()

virtual Bool InitValues ( )

virtual

Called after the layout is calculated, before the user area is drawn.
Override this function to initialize anything.

Returns

true if successful, or false to signalize an error.

GetMinSize()

virtual Bool GetMinSize ( Int32 &  w, Int32 &  h  )

virtual

Called to specify a minimum size for the user area.
Override this function to set the minimum size of the user area to w and h.

Parameters

[in]	w	Assign the minimum width in pixels.
[in]	h	Assign the minimum height in pixels.

Returns

true if successful, or false to signalize an error.

Sized()

virtual void Sized ( Int32  w, Int32  h  )

virtual

Called when the user area is resized.
Override this function to update anything.

Parameters

[in]	w	The new width in pixels.
[in]	h	The new height in pixels.

Draw()

virtual OBSOLETE Draw ( Int32  x1, Int32  y1, Int32  x2, Int32  y2  )

virtual

Deprecated.

DrawMsg()

virtual void DrawMsg ( Int32  x1, Int32  y1, Int32  x2, Int32  y2, const BaseContainer &  msg  )

virtual

Called to draw the user area.
Use the drawing functions to update the user area in the region specified by the rectangle from (x1, y1) to (x2, y2).
Remember to use OffScreenOn() to avoid flickering.

Parameters

[in]	x1	The upper left X coordinate.
[in]	y1	The upper left Y coordinate.
[in]	x2	The lower right X coordinate.
[in]	y2	The lower right Y coordinate.
[in]	msg	The draw container.

InputEvent()

virtual Bool InputEvent ( const BaseContainer &  msg )

virtual

Called when an input event is received.
The information about the input event is stored in the msg container. See Input Events for more information.

See also

MOUSEMOVE_DELTA.

Parameters

[in]

msg

The event container.

Returns

true if the event was handled, otherwise false.

CoreMessage()

virtual Bool CoreMessage ( Int32  id, const BaseContainer &  msg  )

virtual

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

See also

The article Core Messages for more information.

Parameters

[in]	id	The message type: EVMSG
[in]	msg	The core message container.

Returns

Currently not used.

Timer()

virtual void Timer ( const BaseContainer &  msg )

virtual

Called when a timer event is received.
To subscribe to timer events use SetTimer().

Parameters

[in]

msg

The timer message container.

Message()

virtual Int32 Message ( const BaseContainer &  msg, BaseContainer &  result  )

virtual

Called when a message is received.
Override this function to react to more messages than covered by the other virtual functions. Normally this is not necessary.

Note

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

See also

The article GUI Messages for more information.

Parameters

[in]	msg	The message container.
[in]	result	A container to place results in.

Returns

Depends on the message.

Redraw()

void Redraw

(

Bool

threaded = false

)

Forces the user area to redraw itself.

Parameters

[in]

threaded

Must be set to true if the function is called from another thread than the main Cinema 4D thread.

SendParentMessage()

Bool SendParentMessage

(

const BaseContainer &

msg

)

Sends a custom message to the parent dialog.

See also

The article GUI Messages for more information.

Parameters

[in]

msg

The message container.

Returns

true if successful, otherwise false.

SendParentMessageResult()

GeData SendParentMessageResult

(

const BaseContainer &

msg

)

Sends a custom message to the parent dialog.

See also

The article GUI Messages for more information.

Parameters

[in]

msg

The message container.

Returns

returns the result of the message

GetId()

Int32 GetId

(

)

const

Gets the ID of the user area.

Returns

The user area ID.

GetWidth()

Int32 GetWidth

(

)

const

Gets the width in pixels of the user area.

Returns

The user area's width.

GetHeight()

Int32 GetHeight

(

)

const

Gets the height in pixels of the user area.

Returns

The user area's height.

IsEnabled()

Bool IsEnabled

(

)

const

Checks the enabled state of the user area.

Returns

true if the user area is enabled in the dialog, otherwise false.

IsR2L()

Bool IsR2L

(

)

const

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

Returns

true if the user area is in right-to-left layout mode, otherwise false.

HasFocus()

Bool HasFocus

(

)

const

Checks if the user area has the focus.

Returns

true if the user area has the focus in the dialog, otherwise false.

LayoutChanged()

void LayoutChanged

(

)

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

1. GetMinSize()
   
2. Sized()
   
3. InitValues()
   
4. Draw()
   The dialog's layout is recalculated in this process.

SetTimer()

void SetTimer

(

Int32

timer

)

Initializes the timer clock, so that Timer() is called every timer milliseconds. Use SetTimer(0) to stop the timer.

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 guarantee that event messages will occur on a regular basis.
Using a value of 500 ms should be no problem but 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 etc.

Warning

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

Parameters

[in]

timer

The timer interval in milliseconds. Pass 0 to stop the timer.

GetInputState()

Bool GetInputState	(	Int32	askdevice,
		Int32	askchannel,
		BaseContainer &	res
	)		const

Polls a certain channel of a device for the current input state.
If the return value is true, the container stored in res is like an input event message, otherwise no state was available.
For a list of valid devices and channels, see Input Events.

Parameters

[in]	askdevice	The device to ask.
[in]	askchannel	The channel of the device.
[in]	res	The result container.

Returns

true if an input state could be retrieved, otherwise false.

GetInputEvent()

Bool GetInputEvent	(	Int32	askdevice,
		BaseContainer &	res
	)		const

Gets the next input event for a certain device from the event queue.
If the return value is true, the container stored in res is like an input event message, otherwise no state was available.
For a list of valid devices and channels, see Input Events.

Parameters

[in]	askdevice	The device to poll.
[in]	res	The result container.

Returns

true if an input event could be retrieved, otherwise false.

KillEvents()

void KillEvents

(

)

Flushes all events from the window message queue.
For example if looping while the mouse is down (polling), call this function to flush all key downs/mouse clicks that are made during the loop.

IsHotkeyDown()

HOTKEYFLAGS IsHotkeyDown

(

Int32

id

)

const

Checks the standard navigation hotkeys.

Parameters

[in]

id

The hotkey to check: HOTKEY

Returns

A value != 0 if the hotkey is pressed.

DrawSetPen() [1/3]

void DrawSetPen

(

const Vector &

color

)

Sets the draw color.

Parameters

[in]

color

A color vector.

DrawSetPen() [2/3]

void DrawSetPen

(

Int32

id

)

Sets the draw color.

Parameters

[in]

id

A color constant: COLOR

DrawSetPen() [3/3]

void DrawSetPen

(

const GeData &

d

)

Set the draw color.

Parameters

[in]

d

A color data. Can be either a color vector or a color constant in the GeData.

DrawSetOpacity()

void DrawSetOpacity

(

Float

opacity

)

Sets the opacity value.

Parameters

[in]

opacity

The opacity.

DrawSetTextCol() [1/5]

void DrawSetTextCol	(	Int32	fg,
		Int32	bg
	)

Sets the text foreground and background color.

Parameters

[in]	fg	A color constant for the foreground: COLOR
[in]	bg	A color constant for the background: COLOR

DrawSetTextCol() [2/5]

void DrawSetTextCol	(	const Vector &	fg,
		Int32	bg
	)

Sets the text foreground and background color.

Parameters

[in]	fg	A color vector for the foreground.
[in]	bg	A color constant for the background: COLOR

DrawSetTextCol() [3/5]

void DrawSetTextCol	(	Int32	fg,
		const Vector &	bg
	)

Sets the text foreground and background color.

Parameters

[in]	fg	A color constant for the foreground: COLOR
[in]	bg	A color vector for the background.

DrawSetTextCol() [4/5]

void DrawSetTextCol	(	const Vector &	fg,
		const Vector &	bg
	)

Sets the text foreground and background color.

Parameters

[in]	fg	A color vector for the foreground.
[in]	bg	A color vector for the background.

DrawSetTextCol() [5/5]

void DrawSetTextCol	(	const GeData &	fg,
		const GeData &	bg
	)

Sets the text foreground and background color.

Parameters

[in]	fg	A color data for the foreground. Can be either a color vector or a color ID.
[in]	bg	A color data for the background. Can be either a color vector or a color ID.

GetColorRGB()

Bool GetColorRGB	(	Int32	colorid,
		Int32 &	r,
		Int32 &	g,
		Int32 &	b
	)		const

Gets the RGB values associated with a color constant.

Parameters

[in]	colorid	A color constant: COLOR
[out]	r	Assigned the red component of the color.
[out]	g	Assigned the green component of the color.
[out]	b	Assigned the blue component of the color.

Returns

true if successful, otherwise false.

ActivateFading()

void ActivateFading

(

Int32

milliseconds

)

Activates the fading.

Parameters

[in]

milliseconds

The time for the fading in milliseconds.

AdjustColor()

void AdjustColor	(	Int32	colorid,
		Int32	highlightid,
		Float	percent
	)

Sets the blend colors for user area fading.

Parameters

[in]	colorid	A color constant to fade from: COLOR
[in]	highlightid	A color constant to fade to: COLOR
[in]	percent	A fading percentage.

DrawLine()

void DrawLine	(	Int32	x1,
		Int32	y1,
		Int32	x2,
		Int32	y2,
		Float	lineWidth = 1.0,
		LINESTYLE	lineStyle = LINESTYLE::NORMAL
	)

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

Parameters

[in]	x1	The X start coordinate.
[in]	y1	The Y start coordinate.
[in]	x2	The X end coordinate.
[in]	y2	The Y end coordinate.

DrawFrame()

void DrawFrame	(	Int32	x1,
		Int32	y1,
		Int32	x2,
		Int32	y2,
		Float	lineWidth = 1.0,
		LINESTYLE	lineStyle = LINESTYLE::NORMAL
	)

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

Parameters

[in]	x1	The X coordinate of the first corner.
[in]	y1	The Y coordinate of the first corner.
[in]	x2	The X coordinate of the opposite corner.
[in]	y2	The Y coordinate of the opposite corner.
[in]	lineWidth	Line width to draw the line.

DrawRectangle()

void DrawRectangle	(	Int32	x1,
		Int32	y1,
		Int32	x2,
		Int32	y2
	)

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

Parameters

[in]	x1	The X coordinate of the first corner.
[in]	y1	The Y coordinate of the first corner.
[in]	x2	The X coordinate of the opposite corner.
[in]	y2	The Y coordinate of the opposite corner.

DrawBitmap()

void DrawBitmap	(	BaseBitmap *	bmp,
		Int32	wx,
		Int32	wy,
		Int32	ww,
		Int32	wh,
		Int32	x,
		Int32	y,
		Int32	w,
		Int32	h,
		Int32	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 BMP modes for parameter mode.

Parameters

[in]	bmp	The bitmap to draw. The caller owns the pointed bitmap.
[in]	wx	The X coordinate of the upper left corner of the destination area.
[in]	wy	The Y coordinate of the upper left corner of the destination area.
[in]	ww	The width of the destination area.
[in]	wh	The height of the destination area.
[in]	x	The X coordinate of the upper left corner of the bitmap area.
[in]	y	The Y coordinate of the upper left corner of the bitmap area.
[in]	w	The width of the bitmap area.
[in]	h	The height of the bitmap area.
[in]	mode	Can be a combination of the following flags: BMP

DrawImageRef()

void DrawImageRef	(	maxon::ImageBaseRef &	imageRef,
		Float	wx,
		Float	wy,
		Float	ww,
		Float	wh,
		Float	opacity,
		maxon::IMAGEINTERPOLATIONMODE	mode
	)

Draws a image into the user area.

Parameters

[in]	imageRef	ImageRef to draw.
[in]	wx	The X coordinate of the upper left corner of the destination area.
[in]	wy	The Y coordinate of the upper left corner of the destination area.
[in]	ww	The width of the destination area.
[in]	wh	The height of the destination area.
[in]	opacity	Opacity to draw with (0.0 == completely transparent, 1.0 == fully opaque).

DrawText()

void DrawText	(	const maxon::String &	txt,
		Int32	x,
		Int32	y,
		Int32	flags = (0|(0<< 4))
	)

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

[in]	txt	The text to draw.
[in]	x	The X coordinate of the upper left corner for the text to draw.
[in]	y	The Y coordinate of the upper left corner for the text to draw.
[in]	flags	The draw text flags: DRAWTEXT

DrawBezierLine()

void DrawBezierLine	(	const Vector2d &	startPoint,
		const maxon::Block< const BezierPoint > &	bezierPoints,
		Bool	closed,
		Float	lineWidth = 1.0,
		LINESTYLE	lineStyle = LINESTYLE::NORMAL
	)

Draws concatenated Bezier curves.

Parameters

[in]	startPoint	The XY coordinate of the upper left corner of the drawn curve.
[in]	bezierPoints	An array containing a struct of Bezier curves points.
[in]	closed	If true, the last point of the last segment connects back to the starting point (startPoint).
[in]	lineWidth	The width of the Bezier curve. Default 1.0.
[in]	lineStyle	The line style of the Bezier curve.

DrawBezierFill()

void DrawBezierFill	(	const Vector2d &	startPoint,
		const maxon::Block< const BezierPoint > &	bezierPoints,
		Bool	closed
	)

DrawPolyLine()

void DrawPolyLine	(	const maxon::Block< const Vector2d > &	p,
		Bool	closed,
		Float	lineWidth = 1.0,
		LINESTYLE	lineStyle = LINESTYLE::NORMAL
	)

DrawPolyFill()

void DrawPolyFill	(	const maxon::Block< const Vector2d > &	p,
		Bool	closed
	)

DrawEllipseLine()

void DrawEllipseLine	(	const Vector2d &	centerPoint,
		const Vector2d &	radius,
		Float	lineWidth = 1.0,
		LINESTYLE	lineStyle = LINESTYLE::NORMAL
	)

DrawEllipseFill()

void DrawEllipseFill	(	const Vector2d &	centerPoint,
		const Vector2d &	radius
	)

DrawCustomButton()

void DrawCustomButton	(	Int32	x,
		Int32	y,
		Int32	w,
		Int32	h,
		const Int32 *	ids,
		Bool	nofill,
		Bool	focus
	)

Private.

FillBitmapBackground()

void FillBitmapBackground	(	BaseBitmap *	bmp,
		Int32	offsetx,
		Int32	offsety
	)

Fills a bitmap with the current pen color.

Note

The offsetx and offsety parameters are used when the background is a pattern and are given in local coordinates of the user area. These can be used to make semi-transparent bitmap blits.

Parameters

[in]	bmp	The bitmap to fill. The caller owns the pointed bitmap.
[in]	offsetx	The X offset in pixels.
[in]	offsety	The Y offset in pixels.

DrawSetFont()

void DrawSetFont

(

Int32

fontid

)

Sets the text font.

Parameters

[in]

fontid

The font to use: FONT

DrawGetTextWidth()

Int32 DrawGetTextWidth

(

const maxon::String &

text

)

const

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

Parameters

[in]

text

The string to measure.

Returns

The text width in pixels.

DrawGetTextWidth_ListNodeName()

Int32 DrawGetTextWidth_ListNodeName	(	BaseList2D *	node,
		Int32	fontid = FONT_STANDARD
	)		const

Retrieves the width in pixels of the name of node.

Parameters

[in]	node	The node to check.
[in]	fontid	The font: FONT

Returns

The text width in pixels.

DrawGetFontHeight()

Int32 DrawGetFontHeight

(

)

const

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

Returns

The height in pixels.

DrawGetFontBaseLine()

Int32 DrawGetFontBaseLine

(

)

const

Retrieves the base line of the current font.

Returns

The base line of the current font.

DrawSetTextRotation()

void DrawSetTextRotation

(

Float

textrotation

)

Rotates the font for drawing.

Note

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

Parameters

[in]

textrotation

The text rotation in degree.

SetClippingRegion()

void SetClippingRegion	(	Int32	x,
		Int32	y,
		Int32	w,
		Int32	h
	)

Specifies the clipping region for the Draw() functions.

Note

The clipping region can be set to the whole user area with OffScreenOn automatically, so normally this function is not necessary.

Warning

Without specifying a dedicated clipping region everything will be painted, even outside the user area.

Parameters

[in]	x	The X coordinate of the upper left corner of the clipping region.
[in]	y	The Y coordinate of the upper left corner of the clipping region.
[in]	w	The width of the clipping region.
[in]	h	The height of the clipping region.

ClearClippingRegion()

void ClearClippingRegion

(

)

Clears any clipping region set with SetClippingRegion.

OffScreenOn() [1/2]

Bool OffScreenOn

(

)

Enables double buffering to avoid blinking and flickering effects. Automatically sets the clipping area to the whole user area.
The GUI will automatically switch planes. Just call this function before drawing things.

Returns

true if double buffering could be enabled, otherwise false.

OffScreenOn() [2/2]

Bool OffScreenOn	(	Int32	x,
		Int32	y,
		Int32	w,
		Int32	h
	)

Enables double buffering to avoid blinking and flickering effects. Sets the clipping area to the rectangular area determined by x, y, w and h.

Parameters

[in]	x	The X coordinate of the upper left corner of the clipping area.
[in]	y	The Y coordinate of the upper left corner of the clipping area.
[in]	w	The width of the clipping area.
[in]	h	The height of the clipping area.

Returns

true if double buffering could be enabled, otherwise false.

ScrollArea()

void ScrollArea	(	Int32	xdiff,
		Int32	ydiff,
		Int32	x,
		Int32	y,
		Int32	w,
		Int32	h
	)

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

Parameters

[in]	xdiff	The X distance to scroll.
[in]	ydiff	The Y distance to scroll.
[in]	x	The X coordinate of the upper left corner of the area to scroll.
[in]	y	The Y coordinate of the upper left corner of the area to scroll.
[in]	w	The width of the area to scroll.
[in]	h	The height of the area to scroll.

GetPixelRatio()

Float GetPixelRatio

(

)

const

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

Local2Global() [1/2]

Bool Local2Global	(	Int32 *	x,
		Int32 *	y
	)		const

Transforms local coordinates (relative to the top left corner of the user area) to global window coordinates (relative to the top left corner of the application window). Stores the result in *x and *y.

Parameters

[in,out]	x	The local X coordinate. Assigned the global window coordinate.
[in,out]	y	The local Y coordinate. Assigned the global window coordinate.

Returns

true if the coordinates were converted, otherwise false.

Local2Global() [2/2]

Bool Local2Global	(	Float &	x,
		Float &	y
	)		const

Global2Local() [1/2]

Bool Global2Local	(	Int32 *	x,
		Int32 *	y
	)		const

Transforms global window coordinates (relative to the top left corner of the application window) to local coordinates (relative to the top left corner of the user area). Stores the result in *x and *y.

Parameters

[in,out]	x	The global window X coordinate. Assigned the local coordinate.
[in,out]	y	The global window Y coordinate. Assigned the local coordinate.

Returns

true if the coordinates were converted, otherwise false.

Global2Local() [2/2]

Bool Global2Local	(	Float &	x,
		Float &	y
	)		const

Local2Screen() [1/2]

Bool Local2Screen	(	Int32 *	x,
		Int32 *	y
	)		const

Transforms local coordinates (relative to the top left corner of the user area) to screen coordinates (relative to the top left corner of the system screen). Stores the result in *x and *y.

Parameters

[in,out]	x	The local X coordinate. Assigned the screen coordinate.
[in,out]	y	The local Y coordinate. Assigned the screen coordinate.

Returns

true if the coordinates were converted, otherwise false.

Local2Screen() [2/2]

Bool Local2Screen	(	Float &	x,
		Float &	y
	)		const

Screen2Local() [1/2]

Bool Screen2Local	(	Int32 *	x,
		Int32 *	y
	)		const

Transforms screen coordinates (relative to the top left corner of the system screen) to local coordinates (relative to the top left corner of the user area). Stores the result in *x and *y.

Parameters

[in,out]	x	The screen X coordinate. Assigned the converted local coordinate.
[in,out]	y	The screen Y coordinate. Assigned the converted local coordinate.

Returns

true if the coordinates were converted, otherwise false.

Screen2Local() [2/2]

Bool Screen2Local	(	Float &	x,
		Float &	y
	)		const

GetDragPosition()

Bool GetDragPosition	(	const BaseContainer &	msg,
		Int32 *	x,
		Int32 *	y
	)		const

Extracts local drag coordinates from a drag and drop event. Stores the result in *x and *y.

See also

The article Drag and Drop for more information.

Parameters

[in]	msg	The original message.
[out]	x	Assigned the local X position.
[out]	y	Assigned the local Y position.

Returns

true if the drag position was extracted, otherwise false.

GetDragObject()

Bool GetDragObject	(	const BaseContainer &	msg,
		Int32 *	type,
		void **	object
	)		const

Extracts the object from a drag and drop message. Stores the result in *type and *object.

See also

The article Drag and Drop for more information.

Parameters

[in]	msg	The original message.
[out]	type	Assigned the type of the object.
[out]	object	Assigned a pointer to the object. Cinema 4D owns the pointed object.

Returns

true if the drag object was extracted, otherwise false.

HandleMouseDrag()

Bool HandleMouseDrag	(	const BaseContainer &	msg,
		Int32	type,
		void *	data,
		Int32	dragflags
	)

Starts a drag and drop operation.

See also

The article Drag and Drop for more information.

Parameters

[in]	msg	The mouse event message that triggered the drag and drop.
[in]	type	The type of data passed: DRAGTYPE
[in]	data	A pointer to the data passed.
[in]	dragflags	The drag flags. Private.

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.

SetDragDestination()

Bool SetDragDestination

(

Int32

cursor

)

Sets the correct cursor during drag and drop handling.

See also

The article Drag and Drop for more information.

Parameters

[in]

cursor

A mouse cursor: MOUSE

Returns

true if the cursor could be set, otherwise false.

GetBorderSize()

void GetBorderSize	(	Int32	type,
		Int32 *	l,
		Int32 *	t,
		Int32 *	r,
		Int32 *	b
	)		const

Retrieves the space required to draw a border.

Parameters

[in]	type	The border type: BORDER
[out]	l	Assigned the space to the left.
[out]	t	Assigned the space on the top.
[out]	r	Assigned the space to the right.
[out]	b	Assigned the space on the bottom.

DrawBorder()

void DrawBorder	(	Int32	type,
		Int32	x1,
		Int32	y1,
		Int32	x2,
		Int32	y2
	)

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

Parameters

[in]	type	The border type: BORDER
[in]	x1	The X coordinate of the first corner.
[in]	y1	The Y coordinate of the first corner.
[in]	x2	The X coordinate of the opposite corner.
[in]	y2	The Y coordinate of the opposite corner.

CheckDropArea()

Bool CheckDropArea	(	const BaseContainer &	msg,
		Bool	horiz,
		Bool	vert
	)		const

Checks the drag position in a drag event message against the user area's position in the layout. The check can be limited to only X or Y coordinates.

Parameters

[in]	msg	The drag message.
[in]	horiz	If true the drag position is checked against the horizontal bounds of the region.
[in]	vert	If true the drag position is checked against the vertical bounds of the region.

Returns

true if the drag message is within the bounds specified, otherwise false.

MouseDragStart()

void MouseDragStart	(	Int32	button,
		Float	mx,
		Float	my,
		MOUSEDRAGFLAGS	flag
	)

Starts a mouse drag. Only call this when a mouse down message is received. Then repeatedly poll with MouseDrag during the drag.

Parameters

[in]	button	The mouse button that is pressed: BFM_INPUT_CHANNEL
[in]	mx	The X position of the mouse.
[in]	my	The Y position of the mouse.
[in]	flag	The mouse drag flags: MOUSEDRAGFLAGS

MouseDrag()

MOUSEDRAGRESULT MouseDrag	(	Float *	mx,
		Float *	my,
		BaseContainer *	channels
	)

Polls the mouse during a drag started with MouseDragStart::
To check for qualifiers see the channels container:

while (MouseDrag(&dx, &dy, &channels)==MOUSEDRAGRESULT::CONTINUE)
{
  if (channels.GetInt32(BFM_INPUT_QUALIFIER) & QSHIFT) shift = true;
  if (channels.GetInt32(BFM_INPUT_QUALIFIER) & QCTRL) ctrl = true;
  ...
  }

Parameters

[out]	mx	Assigned the X delta-coordinate of the mouse (the amount the mouse has moved).
[out]	my	Assigned the Y delta-coordinate of the mouse (the amount the mouse has moved).
[out]	channels	Assigned the channels values. See Input Events. Also contains these PEN values: PEN

Returns

The mouse drag result: MOUSEDRAGRESULT

MouseDragEnd()

MOUSEDRAGRESULT MouseDragEnd

(

)

Ends a mouse drag started with MouseDragStart.

Returns

The mouse drag result: MOUSEDRAGRESULT

Friends And Related Function Documentation

GeDialog

friend class GeDialog

friend

Member Data Documentation

owncu

Bool owncu

private

cu

CUserArea* cu

private

dlg

GeDialog* dlg

protected

If the user area is attached to a dialog this points to the dialog, otherwise nullptr. Can be used by derived classes.