Nebula Switch Buttons

Switch Buttons

These widgets are a Switch Button and a TriState Switch Button to pick one value which are a different graphical representation of a checkbox button.

Switch Button

Usage

The API is similar to the Button widget. You can get or set the selection, add selection listeners, enable or disable the button, etc.

final SwitchButton button = new SwitchButton(shell, SWT.NONE);
button.setText("Switch button...");
button.setTextForSelect("Selected...");
button.setTextForUnselect("Unselected...");
button.addListener(SWT.Selection, e -> {
    System.out.println("Before clicking, the selection was... " + button.getSelection());
});

Customisation

By default, the button is grey, without border, with a blue background and two labels "On" and "Off". You can customise almost all elements of a switch button by setting the following properties:

• textForSelect — text associated to the selected state of the button
• textForUnselect — text associated to the unselected state of the button
• text — text displayed beside the button
• round — if true, the switch button's corners are round; if false, they are square
• borderColor — if set, a border is displayed around the widget
• focusColor — color of the button when it has focus
• selectedForegroundColor and selectedBackgroundColor — text and background colors of the selected state
• unselectedForegroundColor and unselectedBackgroundColor — text and background colors of the unselected state
• buttonBorderColor, buttonBackgroundColor1 and buttonBackgroundColor2 — colors of the toggle button (border and gradient)
• gap — gap between the button and the associated text
• foreground, background — foreground and background colors of the whole widget
• font — font of the widget

Examples

An example called SwitchButtonSnippet.java is located in the plugin org.eclipse.nebula.widgets.opal.switchbutton.snippets.

This example is also available here: SwitchButtonSnippet.java

Tri-State Switch Button

Tri-State Switch Button

The TriStateSwitchButton is an SWT widget in the Eclipse Nebula Opal library that extends the concept of the standard SwitchButton to support three distinct states. It is a graphical alternative to a tri-state checkbox, rendered as a horizontal switch with three named sections.

Package: org.eclipse.nebula.widgets.opal.switchbutton Requires: JavaSE-21, SWT, org.eclipse.nebula.widgets.opal.switchbutton

The TriState Enum

The state of the button is represented by the TriState enum:

Constant	Position	Description
FIRST	Left	The first active state
OFF	Center	The neutral / off state
SECOND	Right	The second active state

---

Click Behaviour

Current state	User clicks…	Result
FIRST or SECOND	Anywhere on button	→ OFF
OFF	Left section	→ FIRST
OFF	Center section	No change
OFF	Right section	→ SECOND

---

Basic Usage

import org.eclipse.nebula.widgets.opal.switchbutton.TriState;
import org.eclipse.nebula.widgets.opal.switchbutton.TriStateSwitchButton;
import org.eclipse.swt.SWT;

// Create — defaults to OFF state
TriStateSwitchButton button = new TriStateSwitchButton(shell, SWT.NONE);
button.setText("My switch");

// Read the current state
TriState state = button.getState(); // TriState.OFF, FIRST, or SECOND

// Set the state programmatically
button.setState(TriState.FIRST);

---

API Reference

State

Method	Description
getState() → TriState	Returns the current state of the button.
setState(TriState state)	Sets the state programmatically.

Section Labels

Method	Description
setTextForFirst(String text)	Label shown inside the left (FIRST) section.
setTextForOff(String text)	Label shown inside the center (OFF) section.
setTextForSecond(String text)	Label shown inside the right (SECOND) section.
setText(String text)	Label displayed beside (outside) the button itself.

Colors

Method	Description
setFirstBackgroundColor(Color color)	Background color of the FIRST section.
setFirstForegroundColor(Color color)	Text color of the FIRST section.
setOffBackgroundColor(Color color)	Background color of the OFF section.
setOffForegroundColor(Color color)	Text color of the OFF section.
setSecondBackgroundColor(Color color)	Background color of the SECOND section.
setSecondForegroundColor(Color color)	Text color of the SECOND section.
setButtonBorderColor(Color color)	Color of the border drawn around the toggle button.
setBorderColor(Color color)	Color of the outer border around the whole widget.
setFocusColor(Color color)	Glow/highlight color when the widget has focus. Pass null to disable.
setBackground(Color color)	Background color of the entire widget (label area).
setForeground(Color color)	Foreground (text) color of the entire widget.

Shape & Layout

Method	Description
setRound(boolean round)	true (default) for rounded corners; false for square corners.
setArc(int arc)	Manually set the corner arc radius in pixels.
setInsideMargin(int h, int v)	Set horizontal and vertical padding inside each section.

Font

Method	Description
setFont(Font font)	Sets the font used for all labels.

Standard SWT Controls

Method	Description
setEnabled(boolean enabled)	Enables or disables the button.

---

Event Handling

The button fires SWT.Selection events when its state changes. You can listen with either a typed SelectionListener or a low-level SWT Listener.

SelectionListener

button.addSelectionListener(new SelectionListener() {
    @Override
    public void widgetSelected(SelectionEvent e) {
        System.out.println("New state: " + button.getState());
    }

    @Override
    public void widgetDefaultSelected(SelectionEvent e) {}
});

Vetoing a State Change

Set e.doit = false inside widgetSelected to cancel the state transition:

button.addSelectionListener(new SelectionListener() {
    @Override
    public void widgetSelected(SelectionEvent e) {
        e.doit = false; // state will NOT change
    }

    @Override
    public void widgetDefaultSelected(SelectionEvent e) {}
});

Low-Level SWT Listener

button.addListener(SWT.Selection, event -> {
    event.display.beep(); // called on every accepted state change
});

---

Customisation Examples

Custom Section Labels

TriStateSwitchButton button = new TriStateSwitchButton(shell, SWT.NONE);
button.setTextForFirst("Left");
button.setTextForOff("Neutral");
button.setTextForSecond("Right");
button.setText("Custom labels");

Initial State

// Start in FIRST
button.setState(TriState.FIRST);

// Start in SECOND
button.setState(TriState.SECOND);

Custom Section Colors

button.setFirstBackgroundColor(display.getSystemColor(SWT.COLOR_DARK_BLUE));
button.setFirstForegroundColor(display.getSystemColor(SWT.COLOR_WHITE));
button.setOffBackgroundColor(display.getSystemColor(SWT.COLOR_DARK_GRAY));
button.setOffForegroundColor(display.getSystemColor(SWT.COLOR_WHITE));
button.setSecondBackgroundColor(display.getSystemColor(SWT.COLOR_DARK_RED));
button.setSecondForegroundColor(display.getSystemColor(SWT.COLOR_WHITE));
button.setButtonBorderColor(display.getSystemColor(SWT.COLOR_BLACK));

Border

button.setBorderColor(display.getSystemColor(SWT.COLOR_DARK_RED));

Square Style

button.setRound(false);

No Focus / Hover Glow

button.setFocusColor(null);

Custom Font

Font font = new Font(display, "Courier New", 16, SWT.BOLD | SWT.ITALIC);
shell.addDisposeListener(e -> font.dispose()); // always dispose fonts
button.setFont(font);

Custom Margins and Arc

button.setInsideMargin(10, 3); // 10px horizontal, 3px vertical padding
button.setArc(4);              // small corner radius

Widget-Level Background / Foreground

button.setBackground(display.getSystemColor(SWT.COLOR_YELLOW));
button.setForeground(display.getSystemColor(SWT.COLOR_DARK_RED));

---

Example Snippet

A full runnable example is included in the plugin org.eclipse.nebula.widgets.opal.switchbutton.snippets as TriStateSwitchButtonSnippet.java.

---

Notes

• The widget is based on the existing SwitchButton widget and follows the same general API conventions.
• Licensed under the Eclipse Public License 2.0 (EPL-2.0).