## hostwindow.api -- Pre-packaged management for the top-level window of an application.
#
# For lower-level top-level window functionality see:
# src/lib/x-kit/xclient/src/window/window-old.api#
#
# Background
# ==========
#
# x-kit supports five kinds of windows:
#
# o Top-level windows (hostwindows).
# o Sub-windows.
# o Transient windows.
# o Pop-up windows.
# o Input-only windows.
#
# In more detail:
#
# o A Top-level window is the root of a widget hierarchy.
# It is managed (and thus decorated) by the window manager.
# This is what the end-user thinks of as a "window".
#
# o All descendents of a top-level window are called
# subwindows. Typically there is one per widget.
#
# o Transient windows are top-level windows with
# short lifetimes such as dialogue boxes. These
# are managed (and thus decorated) by the window
# manager.
#
# o Popup windows are short-lifetime top-level windows
# such as menus which are not managed by the window
# manager, and which thus lack the usual window
# manager decorations such as borders and close buttons.
#
# o An input-only window provides a new xevent-stream
# handling context for an existing window.
#
#
# Overview
# ========
#
# Here we focus on top-level window widgets.
# These serve as the root widgets of widget trees,
# interfacing between the X library/window manager
# and the generic widgets making up the rest of
# the widget tree.
#
# Hostwindow widgets abstract the properties and
# responsibilities of top-level windows:
#
# o They cannot be inserted into other windows.
#
# o They mediate between the X and X-kit paradigms
# for handling mouse and keyboard input.
#
# o They provide an application gateway to X window
# manager services.
#
# Graphically, a Hostwindow widget is entirely overlaid
# by its child widget; it has no graphical presence
# of its own.
#
# The preferred size of the hostwindow is
# the preferred size of its child widget.
# Compiled by:
# src/lib/x-kit/widget/xkit-widget.sublib# See also:
# src/lib/x-kit/xclient/src/window/window-old.api# Compiled by:
# src/lib/x-kit/widget/xkit-widget.sublibstipulate
include package threadkit; # threadkit is from src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit.pkg #
package g2d= geometry2d; # geometry2d is from src/lib/std/2d/geometry2d.pkg package xc = xclient; # xclient is from src/lib/x-kit/xclient/xclient.pkg #
package wg = widget; # Widget is from src/lib/x-kit/widget/old/basic/widget.apiherein
# This api is implemented in:
#
# src/lib/x-kit/widget/old/basic/hostwindow.pkg #
api Hostwindow {
#
Hostwindow;
Window_And_Icon_Names # To pass to the X window manager.
=
{ window_name: Null_Or( String ),
icon_name: Null_Or( String )
};
Window_Manager_Hints;
make_window_manager_hints
:
{ size_hints: List( xc::Window_Manager_Size_Hint ),
nonsize_hints: List( xc::Window_Manager_Nonsize_Hint )
}
->
Window_Manager_Hints;
hostwindow
:
(wg::Root_Window, wg::View, List( wg::Arg ))
->
wg::Widget
->
Hostwindow;
# Create a hostwindow. We supply:
#
# o A child widget, the root widget of
# the widget-tree for the hostwindow.
#
# o An optional color giving the
# hostwindow's background color.
# (Defaults to white.)
#
# o Optional names for the window and
# icon, to be passed to the window
# manager.
#
make_hostwindow
:
( wg::Widget, # Root of widget-tree for window.
Null_Or( xc::Rgb ), # Background color; defaults to white.
Window_And_Icon_Names # Label strings for window manager.
)
->
Hostwindow;
make_hostwindow_at
:
g2d::Box
->
( wg::Widget, # Root of widget-tree for window.
Null_Or( xc::Rgb ), # Background color; defaults to white.
Window_And_Icon_Names # Label strings for window manager.
)
->
Hostwindow;
# Create a 'transient' Hostwindow,
# used for dialogue boxes and such.
#
# Transient windows are shorter-lived
# than plain toplevel windows but are
# still registered with the window manager,
# although not usually given a title bar or
# the other decorations of a full-scale
# application hostwindow.
#
# Transient windows are longer-lived than
# the simple pop-up windows used for menus
# and such, which are not registered with
# the window manager and created via
# make_simple_popup_window ()
# from
# src/lib/x-kit/xclient/src/window/window-old.pkg #
# A transient window is associated with the
# main hostwindow for the application; typically
# the window manager will de/iconify them together.
#
#
make_transient_hostwindow
:
xc::Window # Main application hostwindow; window manager will de/iconify us along with it.
->
( wg::Widget, # Root of widget-tree for window.
Null_Or( xc::Rgb ), # Background color; defaults to white.
Window_And_Icon_Names # Label strings for window manager.
)
->
Hostwindow;
make_transient_hostwindow_at
:
g2d::Box
->
xc::Window # Main application hostwindow; window manager will de/iconify us along with it.
->
( wg::Widget, # Root of widget-tree for window.
Null_Or( xc::Rgb ), # Background color; defaults to white.
Window_And_Icon_Names # Label strings for window manager.
)
->
Hostwindow;
set_window_manager_hints: Hostwindow -> Window_Manager_Hints -> Void;
#
# Override default window manager properties for window.
# If this is called before 'start_widgettree_running_in_hostwindow'
# (i.e., before the window manager is made aware of the window),
# the hostwindow caches the values for use in the start call.
start_widgettree_running_in_hostwindow: Hostwindow -> Void;
#
# Instantiate the widget tree associated with
# the hostwindow (via the child widget supplied
# to the 'make' call), creating and mapping all
# required X-server windows and thus making
# the widget hierarchy visible.
window_of: Hostwindow -> xc::Window; # Get the actual underlying Window.
unmap: Hostwindow -> Void; # Hide the hostwindow (and thus all of its widgettree).
map: Hostwindow -> Void; # (Re-)show a hostwindow hidden by previous call.
destroy: Hostwindow -> Void;
#
# Recursively destroys all X-server windows
# associated with the hostwindow's widget hierarchy.
#
# We invoke this if we get a REQ_DESTRUCTION
# from the root widget of our widget-tree.
get_''close_window''_mailop: Hostwindow -> Mailop(Void);
#
# This returns a mailop which will be set when
# the user clicks on our windowframe close button.
#
# The idea is that the application can detect and
# handle this condition via code somethine like:
#
# close_window' = get_''close_window''_mailop hostwindow;
#
# ...
#
# for (;;) { # Main application loop
#
# ...
#
# do_one_mailop [ # Main application select reading mouse events etc.
#
# ...
#
# close_window'
# ==>
# {. hostwindow::destroy hostwindow;
# shut_down_thread_scheduler winix__premicrothread::process::success;
# };
# ];
# };
#
# Note that it is entirely up to the application to close
# the window; if this mailop is ignored, nothing whatever
# will happen. (Except user frustration.)
#
# It is fine to pop up a confirmation dialogue, and to do
# nothing if the user does not confirm.
#
#
# For the supporting infrastructure see
#
# src/lib/x-kit/xclient/src/window/hostwindow-to-widget-router-old.pkg };
end; # stipulate