button — `u_pbt_button` #

Themed button: text and icon, styles, counter badge, keyboard shortcut, default and cancel buttons.

⚠️ Several buttons? Prefer buttonbar: a row of buttons in one component, where N separate button cost N times the memory (each component is an engine view). button stays supported for existing code. What each property becomes in the bar — and what only button does — is in "From button to buttonbar", below.

▶ See it live — Demo application, Button tile: the preview, the code behind it and this page, side by side.

At a glance #

Userobject	`u_pbt_button`
Item class	— (component without items)
Used for	Replacing a `commandbutton` with a modern, themed button that supports an icon and a badge
Opt-in options	`ib_track_mouse`

Quick start #

// window open event
uo_button.is_text  = "&Save"          // & = underlined letter : Alt+S fires it
uo_button.is_style = uo_button.STYLE_PRIMARY // primary action button
uo_button.is_image = "mono:img\save.svg"     // icon recolored by the theme
uo_button.is_shortcut = "Ctrl+S"             // shortcut displayed and active
uo_button.is_tooltip = "Saves the current file"

// ue_clicked event of uo_button
of_save()

Constants #

Constant	Value	For
`STYLE_STANDARD` · `STYLE_PRIMARY` · `STYLE_FLAT`	`"standard"` `"primary"` `"flat"`	`is_style`

Properties #

Property	Type	Default	Purpose
`is_text`	string	`""`	Caption. Accepts rich text markup and the `&` mnemonic (`&Save` underlines the S, and Alt+S fires it wherever the focus is in the window, after the explicit shortcuts and never while grayed out; a PB menu bar using the same letter loses it); `&&` displays a literal ampersand. An image-only caption (`[picture=…]`) is allowed. Any letter or digit can be the mnemonic, accented letters included (`&Édition`: Alt+É); only the first `&` counts, a second one is shown without an underline. With no text rendered at all, the tooltip gives the button its name for screen readers
`is_image`	string	`""`	Icon displayed before the caption (accepted forms: path, `mono:`, `tint:`, DLL resource). Without a caption, the icon is centered
`ii_image_size`	integer	`0`	Icon size in pixels (`0` = the theme size, 18 pixels)
`is_style`	string	`"standard"`	Appearance: `STYLE_STANDARD`, `STYLE_PRIMARY` (accent background, primary action), `STYLE_FLAT` (borderless)
`ib_enabled`	boolean	`true`	Button enabled or grayed out. Grayed out, it ignores the mouse and the keyboard, leaves the Tab order and gives Enter, Esc, its shortcut and its mnemonic back to the window — to its window: a grayed default or cancel button closest to the focus keeps the key away from the default button of another sheet. Grayed out, it never takes the keyboard focus
`ib_default`	boolean	`false`	Default button: Enter triggers it wherever the focus is in the window, as long as it is enabled; an accent outline marks it. With two default buttons, the one closest to the focus wins, and on a tie none does. Ctrl, Alt or Shift + Enter is a chord: it never presses the default button
`ib_cancel`	boolean	`false`	Cancel button: Esc triggers it wherever the focus is in the window, as long as it is enabled; Ctrl, Alt or Shift + Esc is a chord, never the cancel button
`is_shortcut`	string	`""`	Keyboard shortcut (`"Ctrl+S"`, `"F5"`, `"Ctrl+Shift+N"`), active wherever the focus is in the window and added to the tooltip ("Save (Ctrl+S)"). Key names are written in English (`Enter`, `Esc`, `Del`, `PageUp`…); a shortcut the window cannot fire (unknown modifier or key) is refused and reads back `""`. With Ctrl or Alt, `+`, `-`, `,`, `.`, the arrows, `Space`, `Tab` and `Backspace` are accepted too. It reads back in its canonical form, in lower case: `"Ctrl+Del"` reads back `"ctrl+delete"` — compare the read-back with that form, not with what you wrote
`ii_badge`	integer	`0`	Counter badge in the top end corner (right, left in right-to-left); above 99 it shows `99+` (`0` = none)
`il_badge_color`	long	`-1`	Badge background, as a PowerBuilder RGB value (`-1` = not set: the color that comes from the theme; `0` is black, like any other color). The text color is picked automatically so that the counter stays legible
`ii_badge_size`	integer	`0`	Badge height in pixels (`0` = the size that comes from the theme). The font size follows on its own: the counter stays centered whatever the size. A negative size reads back `0`
`ib_track_mouse`	boolean	`false`	Opt-in: enables `ue_mouse_enter` / `ue_mouse_leave`. A grayed button raises no `ue_mouse_enter`; an entry that was raised always gets its `ue_mouse_leave`, even if the button was grayed out in between
`is_theme_style`	string	`""`	Visual style of the component (`THEME_STYLE_*` constants); empty = the application's, followed at every change
`is_theme_mode`	string	`""`	Light or dark variant (`THEME_MODE_*` constants); empty = the application's, followed at every change
`il_theme_accent`	long	`-1`	Accent colour of this component (`-1` = the application accent, or the theme's)
`is_tooltip`	string	`""`	Simple tooltip shown when hovering the component. On a button without text (an icon alone), it is also the name a screen reader says
`is_super_tooltip_title`	string	`""`	Title of the rich tooltip (takes precedence over `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Text of the rich tooltip (rich markup accepted)
`is_super_tooltip_image`	string	`""`	Image of the rich tooltip

Methods #

Method	Purpose
`of_reset ( )`	Resets every property to its default. Returns `0` once applied, `-2` when the component is not created
`of_set_redraw (boolean)`	Groups a burst of changes into a single render. Returns `0` once applied, `-2` when the component is not created
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exports the rendering as an image. Returns `0` once the image is written, `-4` when writing fails, `-2` when the component is not created

Events #

Event	Raised when
`ue_clicked ( )`	The button is clicked; or triggered by Enter or Space (alone) when it has the focus, by Enter / Esc according to its role, by its shortcut or by Alt + its letter, wherever the focus is in the window. Ctrl, Alt or Shift + Enter or Space on the focused button are chords of the window: they do not click it
`ue_rclicked ( )`	Right-click on the button
`ue_mouse_enter ( )`	The mouse enters — requires `ib_track_mouse = true`
`ue_mouse_leave ( )`	The mouse leaves — requires `ib_track_mouse = true`
`ue_ready ( )`	The component has finished loading; everything sent beforehand has been replayed
`ue_runtime_missing ( )`	The WebView2 runtime is missing: the component stays empty
`ue_bg_color (long al_color)`	The component has computed its theme background color; the userobject has already adopted it (`backcolor`)

Examples #

The three styles #

// The main button : it answers the Enter key
uo_ok.is_text     = "OK"
uo_ok.is_style    = uo_ok.STYLE_PRIMARY
uo_ok.ib_default  = true          // Enter key

// The cancel button : it answers the Esc key
uo_cancel.is_text   = "Cancel"
uo_cancel.is_style  = uo_cancel.STYLE_STANDARD
uo_cancel.ib_cancel = true       // Esc key

// A discreet help button
uo_help.is_text  = "Help"
uo_help.is_style = uo_help.STYLE_FLAT   // discreet, borderless

Icon and notification badge #

// A bigger icon and a counter badge
uo_messages.is_text  = "Messages"
uo_messages.is_image = "mono:img\mail.svg"
uo_messages.ii_image_size = 20
uo_messages.ii_badge = 12             // "12" badge

// Local variables
long ll_unread

// Update the counter : the badge disappears at 0
ll_unread = 12
uo_messages.ii_badge = ll_unread

// A red badge for an alert, rather than the theme color.
// The text color is picked on its own so it stays legible.
uo_messages.il_badge_color = RGB(/*red*/ 200, /*green*/ 30, /*blue*/ 30)

// Go back to the color that comes from the theme
uo_messages.il_badge_color = -1

Rich caption #

// Rich text : bold and a smaller size, or a picture inside the text
uo_button.is_text = "[b]Export[/b] [size-=20]· CSV[/size-=20]"
uo_button.is_text = "Status [picture=mono:img\ok.svg,14,14]"

Primary action button with a shortcut and help #

// Freeze the drawing while you set it up
uo_submit.of_set_redraw(/*on*/ false)

// Text, style, shortcut, default button and rich tooltip
uo_submit.is_text     = "&Submit order"
uo_submit.is_style    = uo_submit.STYLE_PRIMARY
uo_submit.is_shortcut = "Ctrl+Enter"
uo_submit.ib_default  = true
uo_submit.is_super_tooltip_title = "Submit"
uo_submit.is_super_tooltip_text  = "Sends the order to the supplier." &
                                    + "[br][br][size-=15]This action cannot be undone.[/size-=15]"

// One single redraw, with everything
uo_submit.of_set_redraw(/*on*/ true)

Reacting to hover #

// Raise ue_mouse_enter and ue_mouse_leave when the pointer comes and goes
uo_button.ib_track_mouse = true

// ue_mouse_enter event of uo_button
uo_status.of_panel(/*key*/ "main").is_text = "Saves the current file"

From button to buttonbar #

A row of buttons lives better in one buttonbar. Here is what each member of button becomes in the bar — and what only button does:

`button`	`buttonbar`
`uo_button.is_text = "&Save"`	`uo_bar.of_add_button("save", "&Save")`, `uo_bar.of_button("save").is_text`
`uo_button.is_image`	`uo_bar.of_button("save").is_image`
`uo_button.ii_image_size`	`uo_bar.ii_image_size` (one size for all the buttons of the bar)
`uo_button.is_style`	`uo_bar.of_button("save").is_style`
`uo_button.ib_enabled`	`uo_bar.of_button("save").ib_enabled`; the whole bar: `uo_bar.ib_enabled`
`uo_button.ib_default` · `uo_button.ib_cancel`	`uo_bar.is_default = "save"` · `uo_bar.is_cancel = "close"`: the key of the button
`uo_button.is_shortcut`	`uo_bar.of_button("save").is_shortcut`
`uo_button.ii_badge`	`uo_bar.of_button("save").is_badge` (a text)
`uo_button.il_badge_color`	`uo_bar.of_button("save").il_badge_color`
`uo_button.ii_badge_size`	`uo_bar.ii_badge_size` (one size for all the buttons of the bar)
`uo_button.ue_clicked` · `uo_button.ue_rclicked`	`uo_bar.ue_clicked` · `uo_bar.ue_button_rclicked`, which carry the key of the button
`uo_button.ib_track_mouse` · `uo_button.ue_mouse_enter` · `uo_button.ue_mouse_leave`	— the bar has no mouse enter and leave events: keep `button` for that

Best practices #

Only one primary button per screen: it is the action the user is expected to take.
ib_default and ib_cancel replace the manual handling of Enter / Esc in your window.
Use mono: for monochrome icons: they will follow both the light and the dark theme.
Call of_reset() before reusing a button for a different action.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Members	Role	Detailed in
`of_reset`	Put the component back to zero	3.6 Resetting a component: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	The component's keyboard chords	3.5 Keyboard shortcuts
`of_is_created` · `of_is_ready` · `of_get_last_error`	Whether it was born, whether it is ready, what failed	3.7 Diagnostics
`of_save_as_png` · `of_save_as_jpg`	Export the rendering as an image	3.8 Exporting the rendering as an image
`of_set_redraw`	Group changes into a single repaint	3.10 Best practices
`of_preload_icons`	Icons shown with no delay	Instant display: `of_icon`
`of_set_translation`	Translate one of the component's labels	5.2 Adapting a label: `of_set_translation`
`of_focus_webview`	Give the component the focus	6.4 Keyboard and focus
`of_print` · `of_print_to_pdf`	Print, or write a PDF	6.9 Printing
`of_set_property` · `of_get_property` · `of_component_name`	Driving a property by its name	3.1 The property engine
`is_accessible_name` · `is_accessible_description`	The name and description a screen reader says	3.4 Optional properties and events

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents

button — u_pbt_button #