# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.section Widgets
.topic widget.button
.title Button
.toc 0 Button
.index Button
.index wgtButton

.h2 Button

A push button with a text label. Fires onClick when pressed and released. Uses a two-phase press model: the button visually depresses on mouse-down and fires onClick only when the mouse is released while still inside the button bounds -- dragging the mouse off cancels the press. Supports accelerator keys via '&' prefix in the text (e.g. "&OK" underlines 'O' and binds Alt+O).

Disabled buttons use the classic "embossed" rendering (highlight text offset by +1,+1 and shadow text at 0,0) for a chiseled appearance.

Header: widgets/button.h

.h3 Creation

.code
WidgetT *btn = wgtButton(parent, "&OK");
btn->onClick = onOkClicked;
.endcode

.h3 API Functions

.table
  Function                                      Description
  --------                                      -----------
  WidgetT *wgtButton(parent, text)              Create a push button with the given label text. Pass NULL for no text. Text is copied into the widget.
.endtable

.h3 API Struct (wgtRegisterApi "button")

.table
  Slot     Function
  ----     --------
  create   wgtButton
.endtable

.h3 Properties

Uses common WidgetT properties. Label text is managed via wgtSetText() / wgtGetText(). Set accelKey for keyboard shortcut (automatically parsed from '&' prefix in the text). The button is focusable (WCLASS_FOCUSABLE) and draws a focus rectangle when it holds keyboard focus.

No widget-specific properties are registered with the interface system. BASIC code sets the label via the generic "Caption" or "Text" property.

.h3 Methods

No widget-specific methods.

.h3 Events

.table
  Callback     Description
  --------     -----------
  onClick      Fires when the button is clicked (mouse press and release inside, or Space/Enter when focused).
.endtable

.h3 Default Event

"Click" (VB basName: CommandButton, namePrefix: Command).