Skip to content

WToggleButton

Jump to bottom
Mark Reeves edited this page Jan 4, 2018 · 10 revisions

WToggleButton is a component used to make a single on/off switch control. It can be used as a trigger for a WSubordinateControl or WAjaxControl.

Why use WToggleButton

The most usual use-case for WToggleButton is to invoke a WAjaxControl or WSubordinateControl. A WToggleButton may also stand in for a WCheckBox and be labelled in the same way either directly or by using WField. Unlike WCheckBox though, if the WToggleButton is manually associated with a WLabel then the WLabel must be placed in the UI immediately before the WToggleButton.

Creating a WToggleButton

WToggleButton is a simple input control and is created by calling one of its constructors. The WToggleButton should contain a text description for accessibility purposes.

// A simple toggle button to show more information
WToggleButton toggle = new WToggleButton("More information");

// A toggle button which is initially selected
WToggleButton toggleSelected = new WToggleButton("More information", true);

Accessibility

Labeling a WToggleButton

All WToggleButtons in a UI must be associated with a text description or label or otherwise have their usage and intent exposed to all users. This may be done using (in order of preference):

  • a text description on the WToggleButton;
  • WLabel or by using the WToggleButton in a WField (preferred) this is required if the label must be visible in the UI; or
  • the toolTip property if the label does not have to be visible in the UI; or
  • the accessibleText property of WToggleButton.

When designing a UI containing a WToggleButton the WLabel must be placed immediately before the toggle button:

Setting a toolTip

See toolTip. A WToggleButton may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.

// given WToggleButton `field`
// to set the toolTip
field.setToolTip("context for this selection");

Additional labelling text

WToggleButton may have accessible text applied as information additional to the visible label text. This should be used with care and restraint as it may result in less accessible applications.

// with WToggleButton field
field.setAccessibleText("Some further context to this selection");

Access Keys

A WLabel for a WToggleButton may be given an access key to provide rapid keyboard access.

Default focus

A WToggleButton in an enabled, interactive state may be set as the default focus point for a page. If this is specified it must comply with accessibility principles regarding focus and not put users into a position where they may skip content required for full understanding of the current view. See Setting focus for more information.

This property is ignored if the WToggleButton is in a read-only state.

Variations from WCheckBox

The following are the properties of WToggleButton which are available for manipulation within an application and which have a UI consequence. The following descriptions are, therefore, mostly for the consumption of those who need to specify a UI design. The properties of WCheckBox apply to WToggleButton with the following exceptions:

  • the defaultSubmitButton property is inapplicable as the input is not a submitting control;
  • the mandatory state is inapplicable as a toggle switch which is mandatory is pointless - if the switch may not be turned off then it is not a switch;
  • submitOnChange is not supported as a toggle button is not a submitting control, it is a toggle switch.

Note for Developers

The default state of most of these properties may be set explicitly using the usual accessor syntax. It would, of course, be more usual to set the state based on underlying data, for example a Bean value rather than setting it explicitly. To take the selected state as an example:

// Creating a WToggleButton selected by default:
WToggleButton toggle = new WToggleButton(true);

// Setting the selected state of an existing WToggleButton 'toggle':
toggle.setSelected(true);
// Unsetting the selected state of existing WToggleButton 'toggle':
toggle.setSelected(false);

To test if a WToggleButton is in a selected state use its accessor:

// given WToggleButton 'toggle'
if (toggle.isSelected()) {
  // do stuff
}

Text content

A WToggleButton should contain a text label even though this is not visible in the UI. This may be set in the constructor as shown above or by using the text accessors. This text is implemented as a Serializable and may be internationalised. The text should succinctly describe the purpose of the WToggleButton.

// given WToggleButton toggle and

// to set text
toggle.setText("Show more information");

// to get the current text
String toggleText = toggle.getText();

Default selection

WToggleButton may be selected on load. This property is most usually set based on the state of the control in the underlying data system and should only be specified if the initial state of a WToggleButton is to be selected when presented to a new user for the first time. This must, therefore, be explicitly specified.

HTML output

A WToggleButton will output a button element in the checkbox state.

When a WToggleButton is in a read-only state the output is a span element decorated to indicate the selected state of the control.

Disabling

A WToggleButton may be disabled on page load. When disabled the WToggleButton will not respond to user interaction. This property may be used in conjunction with WSubordinateControl to enable or disable content without making another server call. In this case the state is managed by the WSubordinateControl and does not have to be set explicitly. The disabled state is ignored if the WToggleButton is also in a readOnly state.

UI designer note

A disabled toggle button has no rational checked state: a checked, disabled toggle button is the same as an unchecked disabled toggle button and both will be considered unchecked.

Hiding

A WToggleButton may be hidden on page load. When hidden the WToggleButton is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. When a WToggleButton is hidden a WLabel associated with it is also hidden.

Read-only

The read-only state changes the output rendering of the WToggleButton so that it appears as a graphical representation of the control in the state set when last updated. The control is not able to be interacted with by the user and does not return any value back to the application.

A WToggleButton in a readOnly state may be the target of a WSubordinateControl or WAjaxControl. If it is the target of an AJAX action its state may be changed to remove the readOnly setting.

Appearance

WToggleButton is rendered as a switch and the details of the rendering are determined by the theme. There are no properties in the Java API to adjust this appearance.

Customising based on HTML class

WTextField may have one or more values to be added to the component's wrapper element. This can be used for fine-grain styling of specific components but should be used with care.

For more information see WComponents HTML class property.

WToggleButton toggle = new WToggleButton("Show more");
// to set class attribute values on the HTML output
toggle.setHtmlClass("myMagicClass anotherMagicClass");

Related components

Further information

Some start pages

Clone this wiki locally