15.3.710  src/lib/x-kit/widget/old/leaf/toggleswitches.api

## toggleswitches.api
#
# Common toggles.
#
# Compare to:
#     src/lib/x-kit/widget/old/leaf/pushbuttons.api
#
#           "Toggles are buttons that maintain an on-off state.
#            the user changes the toggle's state by clicking on
#            the button with any mouse button.  As with ordinary
#            buttons, toggle buttons can also be active or inactive.
#            A button's display usually indicates both aspects
#            of the button's state.
#
#           "All constructors take an initial toggle state and
#            a [callback] function that is called whenever the
#            toggle changes from 'on' to 'off' or from 'off' to 'on'.
#            The new value, with 'on' mapped to TRUE, 'off' mapped
#            to FALSE, is passed to the [callback] function.  The
#            [callback] function is not invoked on the initial
#            toggle state.  The various toggle constructors produce
#            widgets differing only in the appearance of the widget.
#            These differences are reflected in the remaining
#            constructor arguments."
#
#             -- p30-31, Gansner+Reppy's 1993 eXene widget manual,
#                http://mythryl.org/pub/exene/1993-widgets.ps
#
# The only differences relative to pushbuttons
# are that toggleswitches provide
#
#     get_button_on_off_flag
#     set_button_on_off_flag
#
# External code can change a toggleswitch's
# state even if it is inactive.
#

# Compiled by:
#     src/lib/x-kit/widget/xkit-widget.sublib

stipulate
    package wg  =  widget;                                              # widget        is from   src/lib/x-kit/widget/old/basic/widget.pkg
    package xc  =  xclient;                                             # xclient       is from   src/lib/x-kit/xclient/xclient.pkg
    package wt  =  widget_types;                                        # widget_types  is from   src/lib/x-kit/widget/old/basic/widget-types.pkg
    package tt  =  toggle_type;                                         # toggle_type   is from   src/lib/x-kit/widget/old/leaf/toggle-type.pkg
herein

    # This api is implemented in:
    #
    #     src/lib/x-kit/widget/old/leaf/toggleswitches.pkg
    #
    api Toggleswitches {
        #
        Toggleswitch = tt::Toggleswitch;

        as_widget:  Toggleswitch -> wg::Widget;

        get_button_on_off_flag:  Toggleswitch -> Bool;
        set_button_on_off_flag: (Toggleswitch, Bool) -> Void;

        get_button_active_flag:  Toggleswitch -> Bool;
        set_button_active_flag: (Toggleswitch, Bool) -> Void;

        radio_button:   (wg::Root_Window, wg::View, List(wg::Arg)) -> (Bool -> Void) -> Toggleswitch;
        check_button:   (wg::Root_Window, wg::View, List(wg::Arg)) -> (Bool -> Void) -> Toggleswitch;
        label_button:   (wg::Root_Window, wg::View, List(wg::Arg)) -> (Bool -> Void) -> Toggleswitch;

        make_checkbox_toggleswitch': (wg::Root_Window, wg::View, List(wg::Arg)) -> (Bool -> Void) -> Toggleswitch;
        make_text_toggleswitch':     (wg::Root_Window, wg::View, List(wg::Arg)) -> (Bool -> Void) -> Toggleswitch;
        make_rocker_toggleswitch':   (wg::Root_Window, wg::View, List(wg::Arg)) -> (Bool -> Void) -> Toggleswitch;
        make_round_toggleswitch':    (wg::Root_Window, wg::View, List(wg::Arg)) -> (Bool -> Void) -> Toggleswitch;

        # Make a checkmark toggle within a square widget,
        # with pixel dimensions given by 'size'.
        #
        make_checkbox_toggleswitch
            :
            wg::Root_Window
            -> { state:          wt::Button_State,
                 click_callback: Bool -> Void,
                 color:          Null_Or( xc::Rgb ),    # Toggle color, defaults to black. Background color is from parent.
                 size:           Int                    # Length in pixels of widget sides. Raises BAD_ARG if < 14.
               }
            -> Toggleswitch;

        make_text_toggleswitch
            :
            wg::Root_Window
            -> { state:           wt::Button_State,
                 rounded:         Bool,
                 click_callback:  Bool -> Void,
                 background:      Null_Or( xc::Rgb ),
                 foreground:      Null_Or( xc::Rgb ),
                 label:           String
               }
            -> Toggleswitch;

        make_rocker_toggleswitch
            :
            wg::Root_Window
            -> { state:           wt::Button_State,
                 click_callback:  Bool -> Void,
                 background:      Null_Or( xc::Rgb ),   # White by default.
                 foreground:      Null_Or( xc::Rgb )    # Black by default.
               }
            -> Toggleswitch;

        make_round_toggleswitch
            :
            wg::Root_Window
            -> { state:           wt::Button_State,
                 click_callback:  Bool -> Void,
                 background:      Null_Or( xc::Rgb ),   # White by default.
                 foreground:      Null_Or( xc::Rgb ),   # Black by default.
                 radius:          Int                   # Radius in pixels of widget. Raises BAD_ARG if < 4.
               }
            -> Toggleswitch;

         make_icon_toggleswitch
             :
             wg::Root_Window
             -> { state:          wt::Button_State,
                  click_callback: Bool -> Void,
                  background:     Null_Or( xc::Rgb ),   # White by default.
                  foreground:     Null_Or( xc::Rgb ),   # Black by default.
                  icon:           xc::Ro_Pixmap
                }
             -> Toggleswitch;

    };

end;