Index

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

TwDefine(" barName/varName  varCommand1 varCommand2 ... ");
 
TwAddVarRW(bar, "varName", TW_TYPE_xx, &myVar, "varCommand1 varCommand2 ... ");

where varCommandn is one of the following commands.

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 hide ");  // variable 'extra' is hidden
 
TwDefine(" mybar/extra show ");  // variable 'extra' is displayed again

Makes a variable ReadWrite or ReadOnly . The user would be able to modify it or not.

TwDefine(" mybar/speed      readwrite ");  // variable 'speed' is made ReadWrite
 
TwDefine(" mybar/framerate  readonly ");   // variable 'framerate' is made ReadOnly

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 ");  // 'code' will be displayed as hexadecimal.
 
TwDefine(" mybar/code  decimal ");  // '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 commands, 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 close ");  // fold the group 'Properties'
 
TwDefine(" mybar/Properties open ");  // unfold it

For enum variables only.

This command defines the labels (strings) associated to the values of a variable of type enum created by TwDefineEnum. It is an alternative to define them when calling the TwDefineEnum function (but TwDefineEnum allows you to use defines macro 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 use one of these block marks instead: < > , ( ) or [ ] . In this case, other block marks found inbetween will be ingnored and treates as standard characters.

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

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

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

// an example with different quotation marks and separators
TwDefine(" bar/messages  val=' 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 alpha command can be used to make it editable. It can be ignored again by using the noalpha command.

TwDefine(" mybar/BoxColor alpha ");    // alpha channel of the variable 'BoxColor' is made editable
 
TwDefine(" mybar/BoxColor noalpha ");  // 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 command 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) edition 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 hls ");  // 'BoxColor' will be edited in HLS mode
 
TwDefine(" mybar/BoxColor rgb ");  // 'BoxColor' will be edited in RGB mode (the default)

See note on string parameters and note on case sensitivity.

TwDefine, bar commands syntax, TwDefineEnum, TwDefineStruct