MAXScript Tools and Interaction with 3ds Max > Creating MAXScript Tools > Scripted Utilities and Rollouts > Rollout User-Interface Controls > Rollout User-Interface Controls Types >

# 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 ).

NoteThe <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.

#### See Also

- Rollout User-Interface Items Common Properties

- Rollout User-Interface Items Common Layout Parameters

- Rollout User-Interface Control Types

- Similar Controls

- Checkbox

- Button

- Pickbutton

- Materialbutton

- Mapbutton