GeBaseDialog

Description

A base dialog class.

Definition

class GeBaseDialog
{
public:
  GeBaseDialog();

  // Overload for special message handling
  [int] Message([BaseContainer] msg);

  // Basic functions
  [bool] Open([bool] async, [int] xpos, [int] ypos);
  [bool] Close();
  [bool] SendMessage([int] id, [BaseContainer] msg);
  [bool] SetTimer([int] timer);
  [bool] SetTitle([string] title);

  // Convenience functions for setting values to gadgets
  [bool] Enable([int] id, [bool] enabled);

  [bool] SetString([int] id, [string] text);

  [bool] SetCheckbox([int] id, [bool] value);
  [bool] SetItem([int] id, [int] subid);

  [bool] SetInt([int] id, [int] val, [int] min, [int] max, [int] step);
  [bool] SetFloat([int] id, [float] val, [float] min, [float] max, [float] step);
  [bool] SetMeter([int] id, [float] val, [float] min, [float] max, [float] step);
  [bool] SetDegree([int] id, [float] val, [float] min, [float] max, [float] step);
  [bool] SetRadians([int] id, [float] val, [float] min, [float] max, [float] step);
  [bool] SetPercent([int] id, [float] val, [float] min, [float] max, [float] step);

  [bool] SetFloatWithUnits([int] id, [float] val, [float] min, [float] max, 
                           [float] step, [int] format);

  [bool] SetColorField([int] id, [vector] color);
  [bool] SetColorChooser([int] id, [vector] color, [float] brightness, 
                         [float] maxbrightness, [int] flags);
						
  // Activation
  [bool] Activate([int] id);

  // Convenience functions for returning values from gadgets
  [string] GetString([int] id);

  [bool] GetCheckbox([int] id);
  [int] GetItem([int] id);

  [int] GetInt([int] id);
  [float] GetFloat([int] id);
  [float] GetMeter([int] id);
  [float] GetDegree([int] id);
  [float] GetRadians([int] id);
  [float] GetPercent([int] id);

  [vector] GetColor([int] id);
  [float] GetBrightness([int] id);

  // Layout stuff
  [bool] LoadDialogResource([int] id, [GeResource] res, [int] flags);

  [bool] AddItem([int] id, [int] subid, [string] name);
  [bool] FreeItems([int] id);

  [bool] SetVisibleArea([int] id, [int] x1, [int] y1, [int] x2, [int] y2);
  
  [int] GetItemPosX([int] id);
  [int] GetItemPosY([int] id);
  [int] GetItemWidth([int] id);
  [int] GetItemHeight([int] id);
  
  // Dynamic layout functions
  [bool] LayoutFlushGroup([int] id);
  [bool] LayoutChanged([int] id);
  
  // Drag and drop convenience functions
  [int] GetDragPosition([BaseContainer] msg, [int] coordinate);
  [any type] GetDragObject([BaseContainer] msg);
  [bool] CheckDropArea([int] id, [BaseContainer] msg, 
                       [bool] check_x = TRUE, [bool] check_y = TRUE);
}

Explanation

This is the base class for dialogs in C.O.F.F.E.E. It has functions for defining the layout of the dialog as well as functions for initializing the gadgets and reading them out. All messages can be caught by overlading the Message() function.

For your convenience there are some derived classes as well, called GeDialog and GeModalDialog, which handle the complex messages automatically and give you additional convenience functions for overloading. So whenever possible you should use GeDialog instead of GeBaseDialog because it's much simpler. If you absolutely want to program your own behaviour you can of course use or derive GeBaseDialog directly.

Basically there are two different methods for the plugin programmer to define the layout of a dialog. The best one is to use separate resource files since they can be easily changed without the need to recompile the plugin. Also you automatically get multi language support. Just add another string resource file and you can sell your plugin not only in Germany but also in Japan. Normally, translating the handful of strings is done within minutes.

If you don't want to fiddle around with extra resource files and never ever want to translate your plugin to other languages you can also define the layout from within the plugin by using the Add*() functions of the GeUserDialog class. Especially when you only need two checkboxes for your plugin this is a bit faster.

However, as soon as you have more then just two buttons, MAXON highly recommends that you use resource files. They are much more flexible and elegant to use!

Members

Message( msg )

[int] Message([BaseContainer] msg);

Overload this function if you want to react to messages. This is normally not needed if using GeDialog or GeModalDialog. If you do overload it, be sure to include this statement at the end of the function to pass the original message on upwards to the parent class:

return super::Message(msg);

Open( async, xpos, ypos )

[bool] Open([bool] async, [int] xpos, [int] ypos);

Opens the dialog at the specified position. If async is TRUE, one can open the dialog as a nonmodal (asynchronous) window. If xpos=-1 and ypos=-1 the dialog will be opened at the current mouse position. Returns TRUE if successful.

Close()

[bool] Close();

Closes the dialog. Not necessary when using modal dialogs.

SendMessage( id, msg )

[bool] SendMessage([int] id, [BaseContainer] msg);

Sends an internal message to the dialog.

SetTimer( timer )

[bool] SetTimer([int] timer);

Subscribes to the timer event message. This makes CINEMA 4D send a time event, or call Timer() of derived classes, 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...

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

SetTitle( title )

[bool] SetTitle([string] title);

Sets the title of the dialog window to title. Returns TRUE if successful.

Enable( id, enabled )

[bool] Enable([int] id, [bool] enabled);

Enables or disables the dialog item with the specified id, depending on the value of enabled. Returns TRUE if successful.

SetString( id, text )

[bool] SetString([int] id, [string] text);

Sets the text field with the specified id to text. Returns TRUE if successful.

SetCheckbox( id, value )

[bool] SetCheckbox([int] id, [bool] value);

Sets the state of the checkbox with the specified id to value. Returns TRUE if successful.

SetItem( id, subid )

[bool] SetItem([int] id, [int] subid);

Sets the sub item of the element with the specified id to subid. This is used to set the active item in a RadioGroup, ComboBox or PopupButton. Returns TRUE if successful.

SetInt( id, val, min, max, step )

[bool] SetInt([int] id, [int] val, [int] min, [int] max, [int] step);

Sets the number field with the speicified id to the integer val. The settings for slider fields and arrow buttons are given by min, max and step.

SetFloat( id, val, min, max, step )

[bool] SetFloat([int] id, [float] val, [float] min, [float] max, [float] step);

Sets the number field with the speicified id to the float val. The settings for slider fields and arrow buttons are given by min, max and step.

SetMeter( id, val, min, max, step )

[bool] SetMeter([int] id, [float] val, [float] min, [float] max, [float] step);

Sets the number field with the speicified id to the float val, enabling a display of the current unit in the field. The settings for slider fields and arrow buttons are given by min, max and step.

SetDegree( id, val, min, max, step )

[bool] SetDegree([int] id, [float] val, [float] min, [float] max, [float] step);

Sets the number field with the speicified id to the float val, enabling the display of a ° sign in the field. The angle should be given in degrees. The settings for slider fields and arrow buttons are given by min, max and step.

SetRadians( id, val, min, max, step )

[bool] SetRadians([int] id, [float] val, [float] min, [float] max, [float] step);

Sets the number field with the speicified id to the float val, enabling the display of a ° sign in the field. The angle should be given in radians. The settings for slider fields and arrow buttons are given by min, max and step.

SetPercent( id, val, min, max, step )

[bool] SetPercent([int] id, [float] val, [float] min, [float] max, [float] step);

Sets the number field with the speicified id to the float val, enabling a display of a % sign in the field. A value of 50.0 gives 50%. The settings for slider fields and arrow buttons are given by min, max and step.

SetFloatWithUnits( id, val, min, max, step, format )

[bool] SetFloatWithUnits([int] id, [float] val, [float] min, [float] max, 
                         [float] step, [int] format);

Sets the number field with the speicified id to the value val using the unit given by format. The settings for slider fields and arrow buttons are given by min, max and step. Valid units are:

Unit Explanation

FORMAT_METER meters (m)

FORMAT_DEGREE degrees (°)

FORMAT_PERCENT percent (%)

SetColorField( id, color )

[bool] SetColorField([int] id, [vector] color);

Sets the color of the color field with the specified id to color.

SetColorChooser( id, color, brightness, maxbrightness, flags )

[bool] SetColorChooser([int] id, [vector] color, [float] brightness, 
                       [float] maxbrightness, [int] flags);

Sets the color and brightness of the color chooser with the specified id to color and brightness. Additionally one can specify the maximum allowed brightness using maxbrightness. The following are the valid options for the flags parameter:

Option Explanation

NO_COLOR Disables the color sliders.

NO_BRIGHTNESS Disables the brightness slider.

Activate( id )

[bool] Activate([int] id);

Activates the gadget with the specified id. Returns TRUE if successful.

GetString( id )

[string] GetString([int] id);

Returns the value of the text field with the specified id.

GetCheckbox( id )

[bool] GetCheckbox([int] id);

Returns the state of the checkbox with the specified id.

GetItem( id )

[int] GetItem([int] id);

Returns the subid of the active sub item of the RadioGroup, ComboBox or PopupButton with the specified id.

GetInt( id )

[int] GetInt([int] id);

Returns the value of the integer field with the specified id.

GetFloat( id )

[float] GetFloat([int] id);

Returns the value of the float field with the specified id.

GetMeter( id )

[float] GetMeter([int] id);

Returns the value of the meter field with the specified id.

GetDegree( id )

[float] GetDegree([int] id);

Returns the value of the degree field with the specified id. The angle is measured in degrees.

GetRadians( id )

[float] GetRadians([int] id);

Returns the value of the integer field with the specified id. The angle is measured in radians.

GetPercent( id )

[float] GetPercent([int] id);

Returns the value of the percent field with the specified id. A value of 50.0 equals 50%.

GetColor( id )

[vector] GetColor([int] id);

Returns the color vector of the color element with the specified id.

GetBrightness( id )

[float] GetBrightness([int] id);

Returns the brightness of the color element with the specified id.

LoadDialogResource( id, res, flags )

[bool] LoadDialogResource([int] id, [GeResource] res, [int] flags);

Loads an external resource file. This is the prefered method for the layout because then one has maximum flexibility and multi language support. One first has to allocate a GeResource class for the res parameter. For the flags one can use the same options as with groups (e.g. BFV_CENTER) since the complete dialog resource is grouped by an additional outer group. Returns TRUE if successful.

AddItem( id, subid, name )

[bool] AddItem([int] id, [int] subid, [string] name);

Adds an item to the RadioGroup, ComboBox or PopupButton with the specified id. Returns TRUE if successful.

FreeItems( id )

[bool] FreeItems([int] id);

Removes all items from the RadioGroup, ComboBox or PopupButton with the specified id. Returns TRUE if successful.

SetVisibleArea( id, x1, y1, x2, y2 )

[bool] SetVisibleArea([int] id, [int] x1, [int] y1, [int] x2, [int] y2);

Scroll the scroll group with the specified id so that the specified region from (x1,y1) to (x2,y2) is visible

GetItemPosX( id )

[int] GetItemPosX([int] id);

Returns the x position of the element with the specified id.

GetItemPosY( id )

[int] GetItemPosY([int] id);

Returns the y position of the element with the specified id.

GetItemWidth( id )

[int] GetItemWidth([int] id);

Returns the width of the element with the specified id.

GetItemHeight( id )

[int] GetItemHeight([int] id);

Returns the height of the element with the specified id.

LayoutFlushGroup( id )

[bool] LayoutFlushGroup([int] id);

Clears the layout for the group with the specified id and sets the insert pointer to this group. Thus, it is possible to insert new elements into the group with Add*() or LoadDialogResource(). Returns TRUE if successful. Be sure to call LayoutChanged() after everything has been added.

LayoutChanged( id )

[bool] LayoutChanged([int] id);

Should be called after LayoutFlushGroup() when all elements have been added. Returns TRUE if successful.

GetDragPosition( msg, coordinate )

[int] GetDragPosition([BaseContainer] msg, [int] coordinate);

Extracts the drag position from a drag event message and returns one of the coordinates, depending on the coordinate parameter (0 = x and 1 = y).

GetDragObject( msg )

[any type] GetDragObject([BaseContainer] msg);

Extracts the dragged object from a drag event message and returns it.

CheckDropArea( id, msg, check_x, check_y )

[bool] CheckDropArea([int] id, [BaseContainer] msg, 
                     [bool] check_x = TRUE, [bool] check_y = TRUE);

Checks the drag position in a drag event message against the position of a gadget in the layout. With check_x and check_y one can limit the check to only x or y coordinates. This is the source of the function:

CheckDropArea(id, msg, check_x, check_y)
{
  var x, y, w, h, dx, dy;
  dx = GetDragPosition(msg, 0);
  dy = GetDragPosition(msg, 1);
  x  = GetItemPosX(id);
  y  = GetItemPosY(id);
  w  = GetItemWidth(id);
  h  = GetItemHeight(id);

  if ( (!check_x || (dx>x && dx<x+w)) && 
       (!check_y || (dy>y && dy<y+h)) )
  {
    return TRUE;
  }
  return FALSE;
}

Unit	Explanation
`FORMAT_METER`	meters (m)
`FORMAT_DEGREE`	degrees (°)
`FORMAT_PERCENT`	percent (%)

Option	Explanation
`NO_COLOR`	Disables the color sliders.
`NO_BRIGHTNESS`	Disables the brightness slider.