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_bouton.is_text  = "&Save"          // & = underlined letter (mnemonic)
uo_bouton.is_style = uo_bouton.STYLE_PRIMARY // primary action button
uo_bouton.is_image = "mono:img\save.svg"     // icon recolored by the theme
uo_bouton.is_shortcut = "Ctrl+S"             // shortcut displayed and active
uo_bouton.is_tooltip = "Saves the current file"

// ue_clicked event of uo_bouton
of_enregistrer()

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); `&&` displays a literal ampersand
`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` = natural size for the component)
`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
`ib_default`	boolean	`false`	Default button: the Enter key triggers it; an accent outline marks it
`ib_cancel`	boolean	`false`	Cancel button: the Esc key triggers it
`is_shortcut`	string	`""`	Keyboard shortcut (`"Ctrl+S"`, `"F5"`, `"Ctrl+Shift+N"`), shown in the tooltip and active when the button has focus
`ii_badge`	integer	`0`	Counter badge in the top-right corner (`0` = none)
`il_badge_color`	long	`0`	Badge background, as a PowerBuilder RGB value (`0` = the color that comes from the theme). 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	`fluent`	Visual style of the component (`THEME_STYLE_*` constants)
`is_theme_mode`	string	`light`	Light or dark variant (`THEME_MODE_*` constants)
`il_theme_accent`	long	`-1`	Accent color of this component (`-1` = the theme accent)
`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 #

uo_ok.is_text     = "OK"
uo_ok.is_style    = uo_ok.STYLE_PRIMARY
uo_ok.ib_default  = true          // Enter key

uo_annuler.is_text   = "Cancel"
uo_annuler.is_style  = uo_annuler.STYLE_STANDARD
uo_annuler.ib_cancel = true       // Esc key

uo_aide.is_text  = "Help"
uo_aide.is_style = uo_aide.STYLE_FLAT   // discreet, borderless

Icon and notification 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_non_lus

// 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(200, 30, 30)

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

Rich caption #

uo_bouton.is_text = "[b]Export[/b] [size-=20]· CSV[/size-=20]"
uo_bouton.is_text = "Status [picture=mono:img\ok.svg,14,14]"

Primary action button with a shortcut and help #

uo_valider.of_set_redraw(false)

uo_valider.is_text     = "&Submit order"
uo_valider.is_style    = uo_valider.STYLE_PRIMARY
uo_valider.is_shortcut = "Ctrl+Enter"
uo_valider.ib_default  = true
uo_valider.is_super_tooltip_title = "Submit"
uo_valider.is_super_tooltip_text  = "Sends the order to the supplier." &
                                    + "[br][br][size-=15]This action cannot be undone.[/size-=15]"

uo_valider.of_set_redraw(true)

Reacting to hover #

uo_bouton.ib_track_mouse = true

// ue_mouse_enter event of uo_bouton
uo_statut.of_item("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 #