Checkbutton UI Control

User Interface Controls > Common Properties > Layout > Types > Checkbutton

Creating User Interfaces - Quick Navigation

A checkbutton control is used to place a press button on the rollout that has two states, on and off, just like a check box. The user can click to successively switch between states.

The syntax is:

checkbutton <name> [<caption>] [ highlightColor:<color> ] \ 
[ toolTip:<string> ] [ checked:<boolean> ] [ images:<image_spec_array> ] \ 
[ border:<boolean> ]

The default alignment of checkbutton items is #center .

EXAMPLE:

checkbutton setup "Setup" checked:true tooltip:"Opens setup panels"
on setup changed state do
if state == on then
  openRollout setup_pan
else
  closeRollout setup_pan

Parameters:

checked:

Initial state of the check button, defaults to off .

highlightColor:

The background color of the check button in its pressed (or on) state, defaults to a light-gray wash in keeping with 3ds Max user-interface conventions.

toolTip:

Provides text for a tooltip for the check button; no tooltip if unsupplied.

images:

An image-specification array for providing bitmap images for the check button. If this is specified, the <label> is ignored and the contents of the check button are replaced with the bitmaps.

The form is:

images:#(<image>, <maskImage>, <count_integer>, <enabled_out_image_index>, <enabled_in_image_index>, <disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four check button states.

FOR EXAMPLE:

bm1 = render camera:$cam01 outputSize:[80,60]
...
checkbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the check button image, and

checkbutton decay images:#("dcybtns.bmp","dcymask.bmp", 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the check button, respectively.

See also Image Buttons.

border:

When set to true or not specified, the checkbutton will be drawn with a border. This was the default behavior prior to 3ds Max 2009.

When set to false, the checkbutton will be drawn without a border, making it one with the UI background. If the checkbutton is enabled, the border will appear when the checkbutton is pressed, checked, if its .checked property is set to true and upon mouseover.

Available in 3ds Max 2009 and higher.

Properties:

<checkbutton>.checkedBoolean

The state of the check button, on ( true ) or off ( false ).

<checkbutton>.state Boolean

Synonym for .checked

<checkbutton>.images Array

Sets the image-specification array for the check button.This property is write-only.

Setting the value to undefined will set the control back to displaying its caption rather than images in 3ds Max 8 and higher.

FOR EXAMPLE:

 -- re-render, update button
bm1 = render()
foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

<checkbutton>. tooltip String

Get/set the tooltip string of the checkbutton.

Available in 3ds Max 9 and higher.

FOR EXAMPLE:

 --Evaluate this script, then roll over the checkbutton to read the tooltip. --Check the checkbutton, roll over again to see the new tooltip. --Uncheck the checkbutton and roll over once again to see the new tooltip.
(
rollout test "Test"
(
checkbutton chk_test "Check Me!" tooltip:"This is a tooltip"
on chk_test changed state do
chk_test.tooltip = if state then "I am checked!" else "I am unchecked!"
)
createDialog test
)

Events:

on <checkbutton> changed <arg> do <expr>

Called when the user clicks the check button to change its state. The <arg> argument will contain the new state of the check button, on ( true ) or off ( false ).

NOTE:The <arg> is a local variable in the context of the event handler - you can use it inside the handler to act according to the new state of the checkbutton.

FOR EXAMPLE:

utility testCheckButton "Test The CheckButton"
(
checkbutton myCheckButton "Check Me!"
-- theState is a user variable name that will contain the state -- of the checkbox whenever the change handler is executed
on myCheckButton changed theState do
(
if theState == true then
myCheckButton.text = "Uncheck Me!"
else
myCheckButton.text = "Check Me!"
)
)--end utility

on <checkbutton> rightclick do <expr>

Called when the right mouse button is released over the button. Available in 3ds Max 8 and higher.

Checkbutton UI Control

See Also