# button — `u_pbt_button` #

← Component reference · Guide contents

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

> ▶ 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
`of_set_redraw (boolean)` | Groups a burst of changes into a single render
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exports the rendering as an image

## 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.

← Component reference · Guide contents