Button

About 5 min read

TwButton · Category: Buttons

Touch panels

The Button's settings for touch panels are described on the Touch Panels page:

• Lock Reason: text shown when a locked button is tapped.
• Two-Step Apply and Second Press Window (s): the value is written only on the second press; see Two-step apply.
• Badge and Badge Class: a number in the top-right corner, for example the active alarm count; see Button badge.
• With Needs Confirmation on, the confirmation dialog carries the button caption; see Confirmation.
• onMouseDown and onMouseUp code also runs on touch screens; see Event code on touch.

Settings

These settings are in the properties panel on the right while the widget is selected. The default value is the value the widget has when it is first added to a page.

Value / Write

Setting	Type	Default	Description
Process Value processValue	Value (typed)	true	Base read/write value. When State Mode is Process Value, the visual state is computed from this value.
Action Mode actionMode	Selection	write	Write: only writes the Process Value, Link: only runs the link action, Write and Link: writes first, then runs the link. Options: write Write, link Link, writeAndLink Write and Link

Behavior

Setting	Type	Default	Description
Read Only readOnly	Checkbox	On	When on, the user cannot change the value at runtime.
Two-Step Apply twoStepApply	Checkbox	Off	For a write action the first press arms the button (pulsing outline and "Press again to apply" as caption); the write, the click code and the link run only on a second press within the window. The armed state ends without writing when the window runs out, on a press elsewhere, when the window loses focus, or when the page is hidden or changes. With Needs Confirmation also on, the confirmation dialog still opens after the second press. Not used for link-only buttons or buttons without a bound value Tag. The button's press/release event code (onMouseDown/onMouseUp) is not gated by this option and also runs on the first press.
Lock Reason lockReason	Text	—	Optional. While the control is locked at runtime (Read Only bound to a tag that is true, or a user without write permission), a tap shows this text briefly instead of the permission message, and it appears as the tooltip. Example: "Interlock: door open". A locale key is translated. Empty keeps the default behaviour.
Needs Confirmation needsConfirmation	Checkbox	Off	Asks for confirmation before the value is written to the Tag.
Second Press Window (s) twoStepSeconds	Number (1–10)	3	Time in seconds for the second press while Two-Step Apply is on (1 to 10, default 3).

Labels / Icons

Setting	Type	Default	Description
Icon icon	Icon	—	Auto: uses the image (IconSrc) first, otherwise the CSS class icon. CSS Class: class icon only. Image: IconSrc only (falls back to the class icon if empty).
Icon Position iconPos	Selection	left	The icon is always shown before the text. Options: left Left, right Right, top Top, bottom Bottom
Hint hint	Text	—	Tooltip text shown at runtime when the pointer rests on the widget.
Badge badge	Text	—	Small count at the top-right corner, usually bound to a tag, e.g. the system tag __activeAlarmCount. Hidden when empty or 0; counts above 99 show 99+; text shows up to 4 characters.

Appearance

Setting	Type	Default	Description
Styling Mode stylingMode	Selection	outlined	Contained fills the button with color, Outlined shows only a border (default), Text shows no border or background. Options: contained Contained, outlined Outlined, text Text
Type type	Selection	normal	Button color from the theme: Normal is neutral, Default uses the accent color, Success is green and Danger is red. Options: normal Normal, success Success, default Default, danger Danger
Button Class buttonClass	CSS classes	—	CSS classes added to the button element.
Badge Class badgeClass	CSS classes	—	Extra CSS classes for the badge, e.g. bg-orange-500 for another colour.

Other settings

Setting	Type	Default	Description
Enable Flashing enableFlashing	Checkbox	Off	Makes the widget blink (an opacity pulse every second). Usually bound to an alarm condition.
Log Button logButton	Checkbox	Off	At runtime shows a chart icon when hovering the widget; clicking it adds the Tags bound to the widget to the log Tag list.

Bindings

In the Bindings (Rules) section of the properties panel, a Tag can be bound to the following properties of this widget with a Direct binding. The binding types (Direct, IntRange, FloatRange, Boolean, Bit) are the same for all widgets; they are described on the Widget Reference page.

title, visible, authorization, x, y, width, height, rotation, class, foregroundColor, backgroundColor, borderColor, borderStyle, borderWidth, borderRadius, borderTopLeftRadius, borderTopRightRadius, enableFlashing, logButton, onClick, onMouseDown, onMouseUp, to.type, lockReason, readOnly, needsConfirmation, twoStepApply, twoStepSeconds, processValue, buttonClass, badge, badgeClass, hint, icon, iconPos, stylingMode, actionMode

Common sections

While this widget is selected, the properties panel also shows these common sections: General, Layout, Appearance, Navigation (To), Events, Bindings (Rules). These sections are described on the Page Editor page.