Index

This page describes the parameters aimed at modifying the behavior of variables. They can be used in the def string of functions TwDefine, TwAddVar* and TwAddButton.

TwDefine(” barName/varName varParam1=xx varParam2=xx ... “);
TwAddVarRW(bar, “varName”, TW_TYPE_xx, &myVar, “varParam1=xx varParam2=xx ... “);

where varParam n is one of the parameter enumerated below.

They can also be set or get using the TwSetParam and TwGetParam functions, eg.:

TwSetParam(bar, “varName”, “varParam”, TW_PARAM_xx, nb, &inParamValues);
TwGetParam(bar, “varName”, “varParam”, TW_PARAM_xx, nb, &outParamValues);

Changes the label of a variable, that is the name displayed before its value. By default, the label is the name used when the variable was added to a bar.

TwAddVarRW(bar, "WindVel", TW_TYPE_FLOAT, &windVel, " label='Wind velocity' ");
 
TwDefine(" mybar/WindVel  label='Wind velocity' ");

Defines the help message associated to a variable. This message will be displayed inside the Help bar automatically created to help the user.

TwDefine(" mybar/WindVel  help='Velocity of the virtual wind used in the simulation' ");

Move a variable into a group. This allows you to regroup variables. If groupname does not exist, it is created and added to the bar. You can also put groups into groups, and so obtain a hierarchical organization.

TwAddVarRO(bar, "Hit", TW_TYPE_BOOL32, &hit, " group=Properties ");  // Hit is put into group Properties (Properties is created)
 
TwAddVarRW(bar, "Red", TW_TYPE_UINT8, &red, " group=Color ");        // Red is put into group Color (Color is created)
 
TwDefine(" mybar/Blue   group=Color     \n"    // Blue is moved into group Color
         " mybar/Color  group=Properties  ");  // group Color is moved into group Properties

Show or hide a variable.

TwDefine(" mybar/extra visible=false ");  // variable 'extra' is hidden
 
TwDefine(" mybar/extra visible=true ");  // variable 'extra' is displayed again

Makes a variable Read-Only or Read-Write. The user would be able to modify it or not.

TwDefine(" mybar/speed      readonly=false ");  // variable 'speed' is made Read-Write
 
TwDefine(" mybar/framerate  readonly=true ");   // variable 'framerate' is made Read-Only

For numerical variables only.

Set a minimum and maximum value of a variable. Thus, user cannot exceed these bounding values when (s)he edit the variable.

TwDefine(" mybar/speed  min=0 max=250 ");  // variable 'speed' is bounded to [0,250]

For numerical variables only.

Set a step value for a variable. When user interactively edit the variable, it is incremented or decremented by this value.

TwDefine(" mybar/speed  step=0.5 ");  // variable 'speed' can be interactively incremented or decremented by 0.5

For float and double variables only.

Defines the number of significant digits printed after the period for floating point variables. This number must be between 0 and 12, or -1 to disable precision and use the default formating.

If precision is not defined and step is defined, the step number of significant digits is used for defining the precision.

TwDefine(" mybar/ratio  precision=2 ");  // the 'ratio' float value will be displayed with 2 digits after the period.

For integer variables only.

Print an integer variable as hexadecimal or decimal number.

TwDefine(" mybar/code  hexa=true ");  // 'code' will be displayed as hexadecimal.
 
TwDefine(" mybar/code  hexa=false "); // 'code' will be displayed as decimal (the default).

Associates a key shortcut to a variable. If the variable can be incremented or decremented, by pressing the keyincr or keydecr shortcut, the user will increment or decrement the value by step. In the other cases (variable of type button or boolean for instance), the user will activate or change the value by pressing the key shortcut.

keyshortcut can be a keyboard symbol (eg., A, b, #, 5, =, &, F10, BACKSPACE,...) or a combination of one or more modifiers and a symbol (eg., ALT+A, CTRL+SPACE, SHIFT+F5, ALT+SHIFT+F12,...).

In addition to the ASCII symbols (ie., standard characters, like letters and numbers), the following special key symbols can be used:

• SPACE (or ‘ ‘)
  
• BACKSPACE (or BS)
  
• TAB
  
• CLEAR (or CLR)
  
• RETURN (or RET)
  
• PAUSE
  
• ESCAPE (or ESC)
  
• DELETE (or DEL), INSERT (or INS)
  
• UP, DOWN, RIGHT, LEFT
  
• HOME, END
  
• PGUP, PGDOWN
  
• F1, F2,..., F15

Key modifiers can be:

• SHIFT
  
• ALT
  
• CTRL

Note on modifiers: SHIFT and CTRL should be used preferably with special keys. With standard characters, SHIFT and CTRL modify the key itself : SHIFT+a → A, CTRL+a..z → ASCII codes 1 through 26 which are often system key shortcuts.

For your convenience, the key symbol relative to a received key pressed event is displayed at the bottom of the Help bar. See the 'events howto' section.

TwDefine(" mybar/speed  keyincr=a keydecr=A ");                   // key [a] will increment 'speed', key [A] will decrement it
 
TwAddButton(bar, "Run", RunCB, NULL, " key=SPACE ");              // key [SPACE] will activate the 'Run' button
 
TwDefine(" mybar/amount  keyincr=ALT+F1 keydecr=SHIFT+ALT+F1 ");  // key [ALT+F1] will increment 'amount', key [SHIFT+ALT+F1] will decrement it

For boolean variables only.

By default, if a boolean variable (of type TW_TYPE_BOOL*) is true, it is displayed as “ON“, and if it is false, as “OFF“. You can change this message with the true and false parameters, the new string will replace the previous message.

bool driverOK; 
...
TwAddVarRO(bar, "DriverState", TW_TYPE_BOOLCPP, &driverOK, " true='Ready' false='Busy' ");  // display Ready if driverOK boolean variable is true, and Busy if it is false.

For groups only.

Fold or unfold a group displayed in a tweak bar (as when the +/- button displayed in front of the group is clicked).

TwDefine(" mybar/Properties opened=false "); // fold the group 'Properties'
 
TwDefine(" mybar/Properties opened=true ");  // unfold it

For enum variables only.

This parameter defines the labels associated to the values of a variable of type enum created by TwDefineEnum or TwDefineEnumFromString. It is an alternative to define them by calling the TwDefineEnum function (but TwDefineEnum allows you to use enum macros instead of numerical values to refer to the enum constants).

In the syntax declaration, constn are numerical values corresponding to the values declared by the enum, and labeln are strings which will be displayed instead of the enum values. They are separated by commas (,). labels are bounded by braces { } . If your labels contain braces, you can use one of these block marks instead: < > , ( ) or [ ] . In this case, other block marks found in-between will be ignored and treated as standard characters.

If you use quotes (‘) in your labels, you should consider that the whole parameter (surrounded by quotes) is a string and refer to this note to deal with quotation accurately (the easiest way is to bound the parameter value by back-quotes or double-quotes instead of simple-quotes).

int digit;
TwType digitType;
 
digitType = TwDefineEnum("DigitType", NULL, 0);
TwAddVarRW(bar, "Digit", digitType, &digit, " enum='1 {One}, 2 {Two}, 3 {Three}' ");

// this example is detailed in the TwDefineEnum documentation
TwDefine(" bar/season  enum=' 0 {Summer},  "
                      "       1 {Fall},    "
                      "       2 {Winter},  "
                      "       3 {Spring} ' ");

// an example with different quotation marks and separators
TwDefine(" bar/messages  enum=' 0 {Nothing}, 1 {He says \"Hello\"}, 2 <I need {braces} here>, '` 3 {I need 'quotes' here}` ");

For TW_TYPE_COLOR32 only.

By default, the alpha channel of 32 bits colors variables (TW_TYPE_COLOR32) is ignored and is not editable. The coloralpha parameter can be used to make it editable.

TwDefine(" mybar/BoxColor coloralpha=true ");   // alpha channel of the variable 'BoxColor' is made editable
 
TwDefine(" mybar/BoxColor coloralpha=false ");  // alpha channel is now ignored

For TW_TYPE_COLOR32 only.

For 32 bits coded colors, OpenGL, Direct3D9 and Direct3D10 use a different order for storing the Red, Blue, Green and Alpha channels. By default, AntTweakBar uses the representation corresponding to the graphic API declared in TwInit (rgba for OpenGL and Direct3D10, and argb for Direct3D9). This parameter allows you to switch between the two representations.

// OpenGL example
unsigned char color[4] = { 200, 100, 50, 255 };                     // color is Red=200, Green=100, Blue=50, Apha=255 (OpenGL RGBA order)
TwAddVar(bar, "Color", TW_TYPE_COLOR32, &color, "colororder=rgba"); // color is stored using OpenGL color channels order. 
                                                                    // Note that "colororder=rgba" can be skipped because it is the default while AntTweakBar has been initialized in OpenGL graphic mode.
 
glColor4ubv(color);  // use color: (for instance) change the current OpenGL color

// Direct3D9 example
unsigned int color = D3DCOLOR_ARGB(255, 200, 100, 50);              // color is Alpha=255, Red=200, Green=100, Blue=50 (Direct3D9 ARGB order)
TwAddVar(bar, "Color", TW_TYPE_COLOR32, &color, "colororder=argb"); // color is stored using  Direct3D9 color channels order. 
                                                                    // Note that "colororder=argb" can be skipped because it is the default while AntTweakBar has been initialized in Direct3D9 graphic mode.
 
device->SetRenderState(D3DRS_FOGCOLOR, &color);  // use color: (for instance) change the Direct3D9 fog color

For color variables only.

Switch between RGB (Red Green Blue) and HLS (Hue Lightness Saturation) editing modes for color variables. Internally, colors are always stored in RGB format, but they can be edited in HLS mode (which is often more user friendly).

TwDefine(" mybar/BoxColor colormode=hls ");  // 'BoxColor' will be edited in HLS mode
 
TwDefine(" mybar/BoxColor colormode=rgb ");  // 'BoxColor' will be edited in RGB mode (the default)

For quaternion variables only.

Draw an 3D arrow (as for direction type) instead of a sphere to depict rotation. x y z defines the direction corresponding to a null rotation.

arrow=0 restore drawing of the sphere.

TwDefine(" mybar/Quat arrow='0 1 0' ");  // 'Quat' is depicted as an arrow initially pointing to +y axis.

For direction and quaternion variables only.

Change the color of the arrow displayed to represent a direction or a rotation. r g b are the color red, green and blue channel values between 0 and 255.

TwDefine(" mybar/Dir arrowcolor='0 0 255' ");  // 'Dir' arrow color is blue.

For direction and quaternion variables only.

Change the default coordinate system used to represent quaternion and direction. By default the coordinate system is right-handed with axis x pointing to the right, axis y pointing to the top and axis z pointing to the front (ie., the viewer). If you are using a different coordinate system in your application, use these parameters to permute the axes. n represents the new axis; it is one of the following values: x, -x, y, -y, z or -z.

TwDefine(" mybar/Rotation axisx=x axisy=y axisz=-z ");  // Permute z axis to get a left-handed coordinate system

For direction and quaternion variables only.

Show or hide the numerical value of a quaternion or a direction. By default, quaternion value is hidden, and can be shown using this parameter. Direction value is shown by default.

TwDefine(" mybar/Quat showval=true ");  // Unhide quaternion value.

See note on string parameters and note on case sensitivity.

TwDefine, bar parameters syntax, TwDefineEnum, TwDefineStruct, TwSetParam, TwGetParam