wxButton(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💖 wxButton(3) — Erlang Module Definition 💖

✨ NAME ✨

wxButton — okay so bestie, it's a button. A button is a control that contains a text string, and is literally one of the most common elements of a GUI. Iconic behavior. 👑

✨ DESCRIPTION ✨

You can place it on a wxDialog, or on a wxPanel panel, or honestly on almost any other window. It's giving flexible. 💅

By default — like, if none of the alignment styles are specified — the label is centered both horizontally and vertically. If the button has both a label and a bitmap, the alignment styles above specify the location of the rectangle combining both the label and the bitmap and the bitmap position set with wxButton::SetBitmapPosition() (not implemented in wx) defines the relative position of the bitmap with respect to the label (however currently non-default alignment combinations are not implemented on all platforms). Lowkey a lot, but we move. 🫶

Since version 2.9.1, wxButton supports showing both text and an image (currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), see SetBitmap() (not implemented in wx) and setBitmapLabel/2, setBitmapDisabled/2 &c methods. In the previous wxWidgets versions this functionality was only available in (the now trivial) wxBitmapButton class which was only capable of showing an image without text. So yeah, glow-up era. ✨

A button may have either a single image for all states or different images for the following states (different images are not currently supported under macOS where the normal image is used for all states):

  • normal: the default state
  • disabled: bitmap shown when the button is disabled.
  • pressed: bitmap shown when the button is pushed (e.g. while the user keeps the mouse button pressed on it)
  • focus: bitmap shown when the button has keyboard focus (but is not pressed as in this case the button is in the pressed state)
  • current: bitmap shown when the mouse is over the button (but it is not pressed although it may have focus). Notice that if current bitmap is not specified but the current platform UI uses hover images for the buttons (such as Windows or GTK+), then the focus bitmap is used for hover state as well. This makes it possible to set focus bitmap only to get reasonably good behaviour on all platforms.

All of the bitmaps must be of the same size and the normal bitmap must be set first (to a valid bitmap), before setting any other ones. Also, if the size of the bitmaps is changed later, you need to change the size of the normal bitmap before setting any other bitmaps with the new size (and you do need to reset all of them as their original values can be lost when the normal bitmap size changes). No skipping steps, bestie. 🚫

The position of the image inside the button be configured using SetBitmapPosition() (not implemented in wx). By default the image is on the left of the text. 🖼️

Please also notice that GTK+ uses a global setting called gtk-button-images to determine if the images should be shown in the buttons at all. If it is off (which is the case in e.g. Gnome 2.28 by default), no images will be shown, consistently with the native behaviour. So if your button images ghost you, that's why. 👻

🎀 Styles 🎀

This class supports the following styles:

  • wxBU_LEFT — Left-justifies the label. Windows and GTK+ only.
  • wxBU_TOP — Aligns the label to the top of the button. Windows and GTK+ only.
  • wxBU_RIGHT — Right-justifies the bitmap label. Windows and GTK+ only.
  • wxBU_BOTTOM — Aligns the label to the bottom of the button. Windows and GTK+ only.
  • wxBU_EXACTFIT — By default, all buttons are made of at least the standard button size, even if their contents is small enough to fit into a smaller size. This is done for consistency as most platforms use buttons of the same size in the native dialogs, but can be overridden by specifying this flag. If it is given, the button will be made just big enough for its contents. Notice that under MSW the button will still have at least the standard height, even with this style, if it has a non-empty label.
  • wxBU_NOTEXT — Disables the display of the text label in the button even if it has one or its id is one of the standard stock ids with an associated label: without using this style a button which is only supposed to show a bitmap but uses a standard id would display a label too.
  • wxBORDER_NONE — Creates a button without border. This is currently implemented in MSW, GTK2 and OSX/Cocoa.

See: wxBitmapButton

This class is derived, and can use functions, from:

  • wxControl
  • wxWindow
  • wxEvtHandler

wxWidgets docs: wxButton

🔥 Events 🔥

Event types emitted from this class:

  • command_button_clicked

💜 DATA TYPES 💜

wxButton() :: wx:wx_object().

create(This, Parent, Id, [Option]) -> boolean()

create(This, Parent, Id, [Option]) -> boolean()
                when
                    This :: wxButton(),
                    Parent :: wxWindow:wxWindow(),
                    Id :: integer(),
                    Option ::
                        {label, unicode:chardata()} |
                        {pos, {X :: integer(), Y :: integer()}} |
                        {size, {W :: integer(), H :: integer()}} |
                        {style, integer()} |
                        {validator, wx:wx_object()}.

okay so this is the two-step creation girlie 💅 you make the button in two moves instead of one.

want the whole lore? go read new/3. see also energy ✨

destroy(This :: wxButton()) -> ok.

destroy(This :: wxButton()) -> ok.

destroys the object 💀 bye bestie, you had a good run.

getBitmapDisabled(This) -> wxBitmap:wxBitmap()

getBitmapDisabled(This) -> wxBitmap:wxBitmap()
                              when This :: wxButton().

hands you the bitmap that shows when the button is disabled — and ngl, it might be invalid. that's allowed, no cap 🫶

See: setBitmapDisabled/2

Since: 2.9.1 (available in wxBitmapButton only in previous versions)

getBitmapFocus(This) -> wxBitmap:wxBitmap()

getBitmapFocus(This) -> wxBitmap:wxBitmap()
                           when This :: wxButton().

returns the bitmap for the focused state — and yeah, this one may be invalid too, it's giving mysterious ✨

See: setBitmapFocus/2

Since: 2.9.1 (available in wxBitmapButton only in previous versions)

getBitmapLabel(This) -> wxBitmap:wxBitmap()

getBitmapLabel(This) -> wxBitmap:wxBitmap()
                           when This :: wxButton().

returns the bitmap for the normal state. the everyday look. the main character fit 👑

this is exactly the same as GetBitmap() (not implemented in wx) but it uses a name that's backwards-compatible with wxBitmapButton. so like, same girl, different name tag 🎀

See: setBitmapLabel/2

Since: 2.9.1 (available in wxBitmapButton only in previous versions)

getDefaultSize() -> {W :: integer(), H :: integer()}

getDefaultSize() -> {W :: integer(), H :: integer()}.

returns the default size for buttons. periodt.

the advice here is real though: make all your dialog buttons the same size, and this function lets you retrieve the size that's best suited for that — it depends on the platform and the current font, so don't hardcode it bestie 😭

lowkey important: the optional win argument is new since wxWidgets 3.1.3 and lets you get a per-monitor DPI specific size 🦋

getDefaultSize(Win) -> {W :: integer(), H :: integer()}

getDefaultSize(Win) -> {W :: integer(), H :: integer()}
                           when Win :: wxWindow:wxWindow().

same thing as above but you hand it a window and it gives you that DPI-specific size. iconic 💅

new() -> wxButton()

new() -> wxButton().

default ctor. that's it, that's the whole vibe 🌸

new(Parent, Id, [Option]) -> wxButton()

new(Parent, Id, [Option]) -> wxButton()
                when
                    Parent :: wxWindow:wxWindow(),
                    Id :: integer(),
                    Option ::
                        {label, unicode:chardata()} |
                        {pos, {X :: integer(), Y :: integer()}} |
                        {size, {W :: integer(), H :: integer()}} |
                        {style, integer()} |
                        {validator, wx:wx_object()}.

constructor — it creates and shows a button. two jobs, one queen 👑

the preferred way to make standard buttons is to just use the default value of label. like, don't even bother. if no label is supplied and id is one of the standard IDs from this list, a standard label gets used automatically. in other words: if you're using a predefined wxID_XXX constant, just omit the label completely instead of specifying it. iykyk ✨

and specifically — help buttons (the ones with id of wxID_HELP) under macOS can't display any label at all. wxButton will detect if the standard "Help" label is used and ignore it, but if you use any other label it will prevent the button from correctly appearing as a help button, so pls pls pls avoid that 🙈

on top of all that? the button gets decorated with stock icons under GTK+ 2. cute 💖

See: create/4

setBitmapDisabled(This, Bitmap) -> ok

setBitmapDisabled(This, Bitmap) -> ok
                              when
                                  This :: wxButton(),
                                  Bitmap :: wxBitmap:wxBitmap().

sets the bitmap for the disabled button appearance.

if the bitmap is invalid, the disabled bitmap becomes the automatically generated greyed-out version of the normal bitmap — i.e. the same bitmap used by default if you never call this method at all. and if you actually want to remove the bitmap completely (for all states), use SetBitmap() (not implemented in wx) with an invalid bitmap 🫶

See:

  • getBitmapDisabled/1
  • setBitmapLabel/2
  • setBitmapFocus/2

Since: 2.9.1 (available in wxBitmapButton only in previous versions)

setBitmapFocus(This, Bitmap) -> ok

setBitmapFocus(This, Bitmap) -> ok
                           when
                               This :: wxButton(),
                               Bitmap :: wxBitmap:wxBitmap().

sets the bitmap that shows up when the button has the keyboard focus. main character moment fr fr ✨

if the bitmap is invalid, the normal bitmap is used in the focused state instead. no drama 💅

See:

  • getBitmapFocus/1
  • setBitmapLabel/2
  • setBitmapDisabled/2

Since: 2.9.1 (available in wxBitmapButton only in previous versions)

setBitmapLabel(This, Bitmap) -> ok

setBitmapLabel(This, Bitmap) -> ok
                           when
                               This :: wxButton(),
                               Bitmap :: wxBitmap:wxBitmap().

sets the bitmap label for the button.

Remark: this is the bitmap used for the unselected state, and for all other states if no other bitmaps are provided. so it's basically the default fit when nothing else is styled 👑

See: getBitmapLabel/1

Since: 2.9.1 (available in wxBitmapButton only in previous versions)

setDefault(This) -> wxWindow:wxWindow()

setDefault(This) -> wxWindow:wxWindow() when This :: wxButton().

this sets the button to be the default item in its top-level window (e.g. the panel or the dialog box containing it).

as normal, pressing return causes the default button to be depressed when the return key is pressed. that's the whole point bestie 💖

See also wxWindow:setFocus/1, which sets the keyboard focus for windows and text panel items, and wxTopLevelWindow::SetDefaultItem() (not implemented in wx).

Remark: under Windows, only dialog box buttons respond to this function. so like… keep that in mind 😭

Return: the old default item (possibly NULL) 👑

setLabel(This, Label) -> ok

setLabel(This, Label) -> ok
                         when This :: wxButton(), Label :: unicode:chardata().

sets the string label for the button. that's the text on the button. the whole lewk 🎀✨

and that's the page, bestie 💜 this was the wxButton(3) manual from Ericsson AB, version wx 2.6 — go forth and make extremely well-labelled buttons, no cap 🦋💅

📦 where this page comes from