wxButton(3erl)

wxButton(3erl) — Erlang Module Definition 💅

okay bestie, so this is the manual page for wxButton, and honestly? It's giving "fundamental GUI building block" and we're obsessed. Let me walk you through it fr fr. ✨

---

💖 NAME 💖

wxButton — Functions for the wxButton class. That's it, that's the whole name. Simple, iconic, periodt. 👑

---

🌸 DESCRIPTION 🌸

So picture this: a button is a control that contains a text string, and it's literally one of the most common elements of a GUI. Like, no cap, every interface you've ever touched has one. 🎀

It may be placed on a wxDialog or on a wxPanel panel, or indeed on almost any other window. Versatile queen. 👑

By default, i.e. 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). So yeah, alignment is a whole vibe but watch out for platform shenanigans. 😤

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 like, glow-up era for buttons, we love to see it. 🦋

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). macOS said "one look for every mood" and honestly? Respect. 🙈

⚠️ Important bestie note: 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). So don't be chaotic about it, okay? Rules are rules. 💅

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. Left is the default, main character energy. ⭐

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. GTK+ said "images? in THIS economy?" and honestly relatable. 💀

💅 Styles 💅

This class supports the following styles:

(yes, that's the whole list in the original — styles section is giving mysterious and lowkey empty but we're not gonna pretend otherwise, no cap) 🙃

See: wxBitmapButton — the older sibling who's still iconic in their own way. 🎀

This class is derived (and can use functions) from: wxControl wxWindow wxEvtHandler. Family tree is giving royalty, honestly. 👑

wxWidgets docs: wxButton

---

🌈 EVENTS 🌈

Event types emitted from this class: command_button_clicked. That's the one, that's the money event, the whole reason you clicked (literally). 💖

---

🎀 DATA TYPES 🎀

• wxButton() = wx:wx_object() — that's the type, it's an object, it's iconic, moving on. ✨

---

🔥 EXPORTS 🔥

🆕 THE CONSTRUCTORS (new/1, new/2, new/3) 🆕

• new() -> wxButton() — Default ctor. Short, sweet, does what it says on the tin. 🫶
• new(Parent, Id) -> wxButton() — Types:
  • Parent = wxWindow:wxWindow()
  • Id = integer()
• new(Parent, Id, Options :: [Option]) -> wxButton() — Types:
  • Parent = wxWindow:wxWindow()
  • Id = integer()
  • Option = one of:
    • {label, unicode:chardata()}
    • {pos, {X :: integer(), Y :: integer()}}
    • {size, {W :: integer(), H :: integer()}}
    • {style, integer()}
    • {validator, wx:wx_object()}

💡 Constructor, creating and showing a button. The full glow-up in one call, bestie.

The preferred way to create standard buttons is to use default value of label. If no label is supplied and id is one of standard IDs from this list, a standard label will be used. In other words, if you use a predefined wxID_XXX constant, just omit the label completely rather than specifying it. In particular, help buttons (the ones with id of wxID_HELP) under macOS can't display any label at all and while wxButton will detect if the standard "Help" label is used and ignore it, using any other label will prevent the button from correctly appearing as a help button and so should be avoided. Like, don't fight the system on this one, macOS said no. 😭

In addition to that, the button will be decorated with stock icons under GTK+ 2. Cute little bonus, we stan. ✨

See: create/4, wxValidator (not implemented in wx)

🛠️ THE CREATION FUNCTION (create/3, create/4) 🛠️

• create(This, Parent, Id) -> boolean() — Types:
  • This = wxButton()
  • Parent = wxWindow:wxWindow()
  • Id = integer()
• create(This, Parent, Id, Options :: [Option]) -> boolean() — Types:
  • This = wxButton()
  • Parent = wxWindow:wxWindow()
  • Id = integer()
  • Option = one of:
    • {label, unicode:chardata()}
    • {pos, {X :: integer(), Y :: integer()}}
    • {size, {W :: integer(), H :: integer()}}
    • {style, integer()}
    • {validator, wx:wx_object()}

💡 Button creation function for two-step creation. For more details, see new/3. Two-step creation is that "build first, show later" energy, very mysterious, very demure. 🎀

📏 SIZE STUFF (getDefaultSize/0, getDefaultSize/1) 📏

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

💡 Returns the default size for the buttons. It is advised to make all the dialog buttons of the same size and this function allows retrieving the (platform, and current font dependent) size which should be the best suited for this. The optional win argument is new since wxWidgets 3.1.3 and allows to get a per-monitor DPI specific size. Matching sizes = coordinated outfit, we love cohesion. 💅

• getDefaultSize(Win) -> {W :: integer(), H :: integer()} — Types:
  • Win = wxWindow:wxWindow()

👑 SETTING THE DEFAULT (setDefault/1) 👑

• setDefault(This) -> wxWindow:wxWindow() — Types:
  • 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. Main character button, gets the spotlight when you hit enter. 👑

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. Windows said "not all buttons get the spotlight" and honestly, rude but okay. 💀

Return: the old default item (possibly NULL)

🏷️ LABELS (setLabel/2) 🏷️

• setLabel(This, Label) -> ok — Types:
  • This = wxButton()
  • Label = unicode:chardata()

💡 Sets the string label for the button. Name change, new era, slay. ✨

🖼️ BITMAP GETTERS (the whole collection) 🖼️

• getBitmapDisabled(This) -> wxBitmap:wxBitmap() — Types:
  • This = wxButton()

💡 Returns the bitmap for the disabled state, which may be invalid. The "button is off duty" look. 😴

See: setBitmapDisabled/2 Since: 2.9.1 (available in wxBitmapButton only in previous versions)

• getBitmapFocus(This) -> wxBitmap:wxBitmap() — Types:
  • This = wxButton()

💡 Returns the bitmap for the focused state, which may be invalid. The "button is the center of attention" look. 🔥

See: setBitmapFocus/2 Since: 2.9.1 (available in wxBitmapButton only in previous versions)

• getBitmapLabel(This) -> wxBitmap:wxBitmap() — Types:
  • This = wxButton()

💡 Returns the bitmap for the normal state. This is exactly the same as GetBitmap() (not implemented in wx) but uses a name backwards-compatible with wxBitmapButton. Legacy name, same icon, we not mad at it. 🫶

See: SetBitmap() (not implemented in wx), setBitmapLabel/2 Since: 2.9.1 (available in wxBitmapButton only in previous versions)

🎨 BITMAP SETTERS (the glow-up squad) 🎨

• setBitmapDisabled(This, Bitmap) -> ok — Types:
  • This = wxButton()
  • Bitmap = wxBitmap:wxBitmap()

💡 Sets the bitmap for the disabled button appearance. If bitmap is invalid, the disabled bitmap is set to the automatically generated greyed out version of the normal bitmap, i.e. the same bitmap as is used by default if this method is not called at all. Use SetBitmap() (not implemented in wx) with an invalid bitmap to remove the bitmap completely (for all states). "Invalid bitmap" = auto grey-out, the system's got your back. 💅

See: getBitmapDisabled/1, setBitmapLabel/2, SetBitmapPressed() (not implemented in wx), setBitmapFocus/2 Since: 2.9.1 (available in wxBitmapButton only in previous versions)

• setBitmapFocus(This, Bitmap) -> ok — Types:
  • This = wxButton()
  • Bitmap = wxBitmap:wxBitmap()

💡 Sets the bitmap for the button appearance when it has the keyboard focus. If bitmap is invalid, the normal bitmap will be used in the focused state. Invalid input? Fallback to the classic. Very forgiving. 🦋

See: getBitmapFocus/1, setBitmapLabel/2, SetBitmapPressed() (not implemented in wx), setBitmapDisabled/2 Since: 2.9.1 (available in wxBitmapButton only in previous versions)

• setBitmapLabel(This, Bitmap) -> ok — Types:
  • 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 the default outfit and the backup outfit. Versatility icon. 👑

See: SetBitmap() (not implemented in wx), getBitmapLabel/1 Since: 2.9.1 (available in wxBitmapButton only in previous versions)

💀 THE DESTROYER (destroy/1) 💀

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

💡 Destroys the object. It's over, it's done, the button has left the chat. 👋

---

✨ and that's the whole page bestie ✨

This manual page was brought to you by the wxWidgets team 💖, for version wx 2.2.2.1, dated wxButton(3erl). Go forth and make buttons, you're gonna slay. 🫶🎀💅