TwBar parameters syntax

Description

This page describes the bar parameters aimed at modifying the behavior of a bar. They can be set through the def string of function TwDefine using the syntax:

TwDefine(” barName barParam1=xx barParam2=xx ... “);

where barParam n is one of the parameter enumerated below.

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

TwSetParam(bar, NULL, “barParam”, TW_PARAM_xx, nb, &inParamValues);
TwGetParam(bar, NULL, “barParam”, TW_PARAM_xx, nb, &outParamValues);

Bar parameters

label

Syntax
label=string

Description

Changes the label of a bar, that is the title displayed on top of a bar. By default, the label is the name used when the bar was created.

Example
TwDefine(" mybar label='Engine properties' ");

help

Syntax
help=string

Description

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

You can also define a global help message. It will be displayed at the beginning of the Help bar. To define it, use the GLOBAL keyword instead of the bar name.

Example
TwDefine(" mybar help='These properties defines the engine behavior' ");
 
TwDefine(" GLOBAL help='I can write here a general description of my program.\n Welcome happy users!' ");

color

Syntax
color=red green blue

Description

Changes the color of a bar.

red, green and blue are integer values between 0 and 255 that define the red, green and blue color channels. See also the alpha and text parameters to change bar visual aspect.

Example
TwDefine(" mybar color='255 255 0' ");             // yellow bar (transparent by default)
TwDefine(" mybar color='0 128 255' alpha=128 ");   // semi-transparent blue bar
TwDefine(" mybar color='192 255 192' text=dark "); // light-green bar with dark text color

alpha

Syntax
alpha=a

Description

Changes the bar opacity.

Bar opacity a can vary from 0 for fully transparent to 255 for fully opaque. See also the color and text parameters to change bar visual aspect.

Example
TwDefine(" mybar alpha=0 ");   // transparent bar
TwDefine(" mybar alpha=128 "); // half-transparent bar
TwDefine(" mybar alpha=255 "); // opaque bar

text

Syntax
text=dark

text=light

Description

Changes text color.

Depending on your application background color and on bar color and alpha, bar text might be more readable if it is dark or light. This parameter allows to switch between the two modes. See also the color and alpha parameters to change bar visual aspect.

Example
TwDefine(" mybar text=dark ");  // use dark text color
TwDefine(" mybar text=light "); // use light text color

position

Syntax
position=x y

Description

Move a bar to a new position.

x and y are positive integer values that represent the new position of the bar in pixels. (x=0, y=0) is upper-left corner of the application window.

Example
TwDefine(" mybar position='200 40' "); // move bar to position (200, 40)

size

Syntax
size=sx sy

Description

Change the bar size.

sx and sy are positive integer values that represent the new size of the bar in pixels.

Example
TwDefine(" mybar size='240 320' "); // resize bar

valueswidth

Syntax
valueswidth=w

valueswidth=fit

Description

Change the width of the bar right column used to display numerical values.

w is a positive integer that represents width in pixels.

If valueswidth is set to fit, column width is adjusted to fit column content.

Example
TwDefine(" mybar valueswidth=120 "); // set values column width
 
TwDefine(" mybar valueswidth=fit "); // column width fits content

refresh

Syntax
refresh=r

Description

Change the refresh rate of the bar.

Values displayed by a bar are automatically updated to reflect changes of their associated variables. r is a real value corresponding to the number of seconds between two updates.

Example
TwDefine(" mybar refresh=1.5 "); // refresh the bar every 1.5 seconds

visible

Syntax
visible=true

visible=false

Description

Show or hide a tweak bar.

Example
TwDefine(" mybar visible=false ");  // mybar is hidden
TwDefine(" mybar visible=true ");   // mybar is displayed again
Note

The help bar can be hidden by calling:

TwDefine(" TW_HELP visible=false ");  // help bar is hidden

iconified

Syntax
iconified=true

iconified=false

Description

Iconify or deiconify a tweak bar.

Example
TwDefine(" mybar iconified=true ");  // mybar is iconified

iconpos

Syntax
iconpos=p

Description

Changes the place where icons of iconified bars are displayed.

p is one of the following values:

  • bottomleft or bl for bottom-left corner of the window (default).
  • bottomright or br for bottom-right corner of the window.
  • topleft or tl for top-left corner of the window.
  • topright or tr for top-right corner of the window.

Note that this parameter is applied to all bar icons. You can use the GLOBAL keyword instead of a bar name to set it.

Example
TwDefine(" GLOBAL iconpos=bottomright "); // icons go to bottom-right corner of the window

iconalign

Syntax
iconalign=vertical

iconalign=horizontal

Description

Changes the alignment of icons of iconified bars. It can be vertical (the default), or horizontal.

Note that this parameter is applied to all bar icons. You can use the GLOBAL keyword instead of a bar name to set it.

Example
TwDefine(" GLOBAL iconalign=horizontal "); // icons will be aligned horizontally

iconmargin

Syntax
iconmargin=’x y

Description

Add a margin between borders of the window and icons of iconified bars. x and y are the number of pixels between window borders and icons in the x and y directions respectively.

Note that this parameter is applied to all bar icons. You can use the GLOBAL keyword instead of a bar name to set it.

Example
TwDefine(" GLOBAL iconmargin='8 16' "); // icons will be displayed at 8 and 16 pixels from the horizontal and vertical window borders respectively

iconifiable

Syntax
iconifiable=true

iconifiable=false

Description

Allow a bar to be iconified or not by the user.

Example
TwDefine(" mybar iconifiable=false "); // mybar cannot be iconified

movable

Syntax
movable=true

movable=false

Description

Allow a bar to be moved or not by the user.

Example
TwDefine(" mybar movable=false "); // mybar cannot be moved

resizable

Syntax
resizable=true

resizable=false

Description

Allow a bar to be resized or not by the user.

Example
TwDefine(" mybar resizable=false "); // mybar cannot be resized

fontsize

Syntax
fontsize=s

Description

Change the size of the font used by the bars.

s is 1 for small font, 2 for medium font, or 3 for large font. Note that all bars share the same font, so this change is applied to all bars.

fontsize is a global parameter. You can use the GLOBAL keyword instead of a bar name to set it.

Example
TwDefine(" GLOBAL fontsize=3 "); // use large font

fontstyle

Syntax
fontstyle=default

fontstyle=fixed

Description

Change the style of the font used by the bars.

Either specify default for the default proportional font or fixed for the non-proportional (fixed-width) font. Note that all bars share the same font and the fixed font has only one size (non-resizable).

fontstyle is a global parameter. You can use the GLOBAL keyword instead of a bar name to set it.

Example
TwDefine(" GLOBAL fontstyle=fixed "); // use fixed-width font

fontresizable

Syntax
fontresizable=true

fontresizable=false

Description

Allow bar fonts to be resized or not by the user.

Note that this parameter is applied to all bars. You can use the GLOBAL keyword instead of a bar name to set it.

Example
TwDefine(" GLOBAL fontresizable=false "); // font cannot be resized

fontscaling

Syntax
fontscaling=s

Description

Apply a global scaling factor to all fonts. This may be useful to double the size of characters on high-density display for instance. The result may be pixelized. s is any positive real value.

fontscaling is a global parameter (use the GLOBAL keyword instead of a bar name to set it) and must be set before calling TwInit. This is an exception.

Example
TwDefine(" GLOBAL fontscaling=2 "); // double the size of all fonts
TwInit(....);

alwaystop

Syntax
alwaystop=true

alwaystop=false

Description

Set a bar to be always on top of the others.

Example
TwDefine(" mybar alwaystop=true "); // mybar is always on top

alwaysbottom

Syntax
alwaysbottom=true

alwaysbottom=false

Description

Set a bar to be always behind the others.

Example
TwDefine(" mybar alwaysbottom=true "); // mybar is always on bottom

contained

Syntax
contained=true

contained=false

Description

Prevent a bar from moving outside of the window. To prevent all bars from moving outside of the window, use GLOBAL in place of bar name.

Example
TwDefine(" GLOBAL contained=true "); // bars cannot move outside of the window

overlap

Syntax
overlap=true

overlap=false

Description

If true, the content of overlapped bars is always completely drawn. If false, the content of overlapped regions is clipped and not drawn which improves readability of overlapped transparent bars (this is the default).

Note that this parameter is applied to all bars. You can use the GLOBAL keyword instead of a bar name to set it.

Example
TwDefine(" GLOBAL overlap=true ");

buttonalign

Syntax
buttonalign=left

buttonalign=center

buttonalign=right

Description

Change display alignment of buttons added by TwAddButton to a bar.

This parameter could be applied to all bars by using the GLOBAL keyword instead of a bar name.

Example
TwDefine(" GLOBAL buttonalign=left "); // buttons are left-aligned

Notes

Note on string parameters

If a parameter requires a string, the string can be a simple name without any special characters; but if it contains special characters like spaces, punctuations or quotation marks, you should surround it with simple quotes (), back-quotes (`), or double-quotes (). In between these two quotes, the other kind of quotes would be considered as normal characters; so use a kind of quotes that does not appear in your string. If you need the three kinds of quotes in your string, you can split it and surround each part by a different quotation mark; the successive string parts would then be concatenated and you’d get the expected result (see the following examples).

Examples:

param=Simple                // ->  Simple

param='Two words'           // ->  Two words

param=`That's All Folks`    // ->  That's All Folks

param='He says "Hello!"'    // ->  He says "Hello!" 
                            // note that in a c-string " are replaced by \" ie.:  " param='He says \"Hello!\"' "

param="'aa'-"`"bb"-`'`cc`'  // ->  'aa'-"bb"-`cc`
                            // note that in a c-string " are replaced by \" ie.: " param=\"'aa'-\"`\"bb\"-`'`cc`' "

Note on case sensitivity

  • Parameter names are case insensitive: color=’...’ is the same as Color=’...’ and is the same as COLOR=’...’ .
  • Bar and var names are case sensitive: mybar is different from MyBar and is different from myBar.

See also