## pushbuttons.api
#
# Buttons are supplied in two flavors, callback and standard:
#
# o Callback buttons just call the supplied callback
# function when pressed. (A button is pressed by
# moving the mouse over the button and pressing
# any mouse button.) The callback is invoked on
# BUTTON_UP; a user can cancel a downclick by
# moving off the button before releasing it. XXX BUGGO FIXME. Should fire on downclick to minimize latency.
#
# Do not call block_until_mailop_fires on the button_transition'
# of a callback button; a dedicated thread is
# spawned to wait on this mailop and invoke the
# callback, and you will interfere with this thread.
#
#
# o Standard buttons generate event mails on each
# button transition identifying both the transition
# and the state of all mouse buttons.
#
# When a mouse button is pressed the button widget
# generates a BUTTON_DOWN eventmail, and continues
# to generate them regularly until the button is
# released (at which point it generates a BUTTON_UP
# eventmail) or until it leaves the widget window,
# at which point it generates a BUTTON_EXIT eventmail.
#
# [ 'BUTTON_EXIT' does not exist; it must
# have become BUTTON_IS_UNDER_MOUSE or BUTTON_IS_NOT_UNDER_MOUSE.
# ]
#
# A text button carries a text label in 8x13 font;
# it sizes itself just large enough to display the
# text. If 'rounded' is TRUE it draws a cartouche
# around itself, otherwise it is unframed.
#
# Buttons are factored into separate view and
# control halves; any view half may be combined with
# any control half to produce a complete button.
#
# The button thread guarantees to generate a
# BUTTON_DOWN for each downclick followed
# eventually by either a BUTTON_UP or BUTTON_EXIT;
# between these it will generate a continual
# stream of BUTTON_DOWN events. XXX BUGGO FIXME this sounds like a time-wasting busy-wait loop.
#
# WARNING: The client code programmer MUST
# monitor (e.g., call 'block_until_mailop_fires' or
# 'do_one_mailop' on) the button_transition' mailop
# provided by standard buttons; otherwise the
# button thread will block.
#
# Compare to:
# src/lib/x-kit/widget/leaf/toggleswitches.api# Compiled by:
# src/lib/x-kit/widget/xkit-widget.sublib# Compiled by:
# src/lib/x-kit/widget/xkit-widget.sublib# Common buttons.
# This api is implemented in:
#
# src/lib/x-kit/widget/leaf/pushbuttons.pkgstipulate
include threadkit; # threadkit is from src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit.pkg #
package wg = widget; # widget is from src/lib/x-kit/widget/basic/widget.pkg #
package xc = xclient; # xclient is from src/lib/x-kit/xclient/xclient.pkg #
Button = button_type::Button;
herein
api Pushbuttons {
Button_Transition
= BUTTON_DOWN xc::Mousebutton
| BUTTON_UP xc::Mousebutton
| BUTTON_IS_UNDER_MOUSE
| BUTTON_IS_NOT_UNDER_MOUSE
;
Arrow_Direction
= ARROW_UP
| ARROW_DOWN
| ARROW_LEFT
| ARROW_RIGHT
;
button_transition'_of: Button -> Mailop( Button_Transition );
as_widget: Button -> wg::Widget;
set_button_active_flag: (Button, Bool) -> Void;
get_button_active_flag: Button -> Bool;
make_arrow_pushbutton': (wg::Root_Window, wg::View, List(wg::Arg)) -> Button;
make_label_pushbutton': (wg::Root_Window, wg::View, List(wg::Arg)) -> Button;
make_text_pushbutton': (wg::Root_Window, wg::View, List(wg::Arg)) -> Button;
make_arrow_pushbutton_with_click_callback': (wg::Root_Window, wg::View, List(wg::Arg)) -> (Void -> Void) -> Button;
make_label_pushbutton_with_click_callback': (wg::Root_Window, wg::View, List(wg::Arg)) -> (Void -> Void) -> Button;
make_text_pushbutton_with_click_callback': (wg::Root_Window, wg::View, List(wg::Arg)) -> (Void -> Void) -> Button;
make_arrow_pushbutton
:
wg::Root_Window
->
{ background: Null_Or( xc::Rgb ), # Background color for button; defaults to black.
direction: Arrow_Direction,
foreground: Null_Or( xc::Rgb ), # Foreground color for button; defaults to white.
size: Int # Ideal size. BAD_ARG is raised if size < 4.
}
->
Button;
make_arrow_pushbutton_with_click_callback
:
wg::Root_Window
->
{ click_callback: Void -> Void,
background: Null_Or( xc::Rgb ), # Background color for button; defaults to black.
direction: Arrow_Direction,
foreground: Null_Or( xc::Rgb ), # Foreground color for button; defaults to white.
size: Int # Ideal size. BAD_ARG is raised if size < 4.
}
->
Button;
make_text_pushbutton
:
wg::Root_Window
->
{ rounded: Bool,
background: Null_Or( xc::Rgb ), # Background color for button; defaults to black.
foreground: Null_Or( xc::Rgb ), # Foreground color for button; defaults to white.
label: String
}
->
Button;
make_text_pushbutton_with_click_callback
:
wg::Root_Window
->
{ rounded: Bool,
click_callback: Void -> Void,
background: Null_Or( xc::Rgb ), # Background color for button; defaults to black.
foreground: Null_Or( xc::Rgb ), # Foreground color for button; defaults to white.
label: String
}
->
Button;
}; # api Pushbutton
end;