15.3.728  src/lib/x-kit/widget/old/wrapper/choice-of-widgets.api

## choice-of-widgets.api
#
# Manage a list of widgets
# only one of which is visible
# at any given time.
#
# The shape and size preferences of
# this widget are identical to those
# of its currently visible child.
#
# The internal widget list is addressed via
# integer index values; the first widget is
# number zero.
#
# This list of widgets may be dynamically
# altered via the insert(), append() and
# delete() functions, whose semantics
# match those of in Line_Of_Widgets.                            # Line_Of_Widgets       is from   src/lib/x-kit/widget/old/layout/line-of-widgets.api
#     The length, contents and order of
# the widget list do not change except as
# explicitly requested by the user via
# these functions.
#
# If the choice_of_widgets childlist is
# empty, is behaves as a transparent
# one-pixel-square widget.

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


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




# This api is implemented in:
#
#     src/lib/x-kit/widget/old/wrapper/choice-of-widgets.pkg

stipulate
    package wg = widget;                                        # widget                is from   src/lib/x-kit/widget/old/basic/widget.pkg
herein

    api Choice_Of_Widgets {

        Choice_Of_Widgets;

        exception NO_WIDGETS;
        exception BAD_INDEX;

        choice_of_widgets:  (wg::Root_Window, wg::View, List(wg::Arg)) -> List(wg::Widget) -> Choice_Of_Widgets;

        make_choice_of_widgets:  wg::Root_Window -> List(wg::Widget) -> Choice_Of_Widgets;

        as_widget:  Choice_Of_Widgets -> wg::Widget;

        insert:  Choice_Of_Widgets -> (Int, List(wg::Widget)) -> Void;
            #
            # Insert given List(Layout_Tree) before the nth child
            # in the child widgets list, where the first child
            # is numbered 0.  Impractical values raise BAD_INDEX.
            # The widgets in the List(Layout_Tree) are assumed to be
            # unrealized;  they will be realized at this time.

        append:  Choice_Of_Widgets -> (Int, List(wg::Widget)) -> Void;
            # 
            # append choice_of_widgets (n,list)   is equivalent to
            # insert choice_of_widgets (n+1,list)

        delete:  Choice_Of_Widgets -> List(Int) -> Void;
            #
            # Remove the child widgets with the indices given
            # in List(Int), destroying any associated X-server
            # windows and effectively destroying the widgets.
            # Bad indices raise BAD_INDEX.

        show:        Choice_Of_Widgets -> Int -> Void;  # Select   currently visible child widget. Defaults to child zero.
        showing:     Choice_Of_Widgets -> Int;          # Index of currently visible child widget.
        child_count: Choice_Of_Widgets -> Int;          # Length of internal child-widgets list.
    };

end;