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.

▶ 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
`is_image`	string	`""`	Icon displayed before the caption (accepted forms: path, `mono:`, `tint:`, DLL resource)
`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
`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
`ib_cancel`	boolean	`false`	Cancel button: Esc triggers it wherever the focus is in the window, as long as it is enabled
`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 `""`
`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
`ib_track_mouse`	boolean	`false`	Opt-in: enables `ue_mouse_enter` / `ue_mouse_leave`
`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
`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 / Esc / its shortcut
`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

// Update the counter : the badge disappears at 0
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"

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

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 #