## root-window.api
#
# This widget represents the root window on an X screen
# -- the one on which the wallpaper is drawn.
#
# This widget also serves as the top-level representative
# of a running X server session. For example, run_in_x_window_old in
#
# src/lib/x-kit/widget/old/lib/run-in-x-window-old.pkg#
# creates a Root_Window and passes it to the user-provided
# application function as the sole representative of the
# running X session.
#
# Other widgets use Root_Window instances to access display
# resources such as fonts; the Root_Window to use is usually
# supplied to them at creation time.
#
# Also, by X convention, various things get published by
# posting them as properties on the root window.
# Compiled by:
# src/lib/x-kit/widget/xkit-widget.sublib# 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 xc = xclient; # xclient is from src/lib/x-kit/xclient/xclient.pkg package xt = xtypes; # xtypes is from src/lib/x-kit/xclient/src/wire/xtypes.pkg package g2d = geometry2d; # geometry2d is from src/lib/std/2d/geometry2d.pkg package wb = widget_base; # widget_base is from src/lib/x-kit/widget/old/basic/widget-base.pkg package rop = ro_pixmap; # ro_pixmap is from src/lib/x-kit/xclient/src/window/ro-pixmap.pkg package shp = shade; # shade is from src/lib/x-kit/widget/lib/shade.pkg package xrs = cursors; # cursors is from src/lib/x-kit/xclient/src/window/cursors.pkg package wy = widget_style; # widget_style is from src/lib/x-kit/widget/lib/widget-style.pkg package xj = xsession_junk; # xsession_junk is from src/lib/x-kit/xclient/src/window/xsession-junk.pkgherein
# This api is implemented in:
#
# src/lib/x-kit/widget/lib/root-window.pkg #
# Oddly enough, it is not referenced in the above file.
# It is however 'include'-ed in
#
# src/lib/x-kit/widget/old/basic/widget.api api Root_Window {
#
Root_Window
=
{ screen: xj::Screen,
id: Int, # This is for internal client-side use only -- never gets passed to X.
#
make_shade: rgb::Rgb -> shp::Shades,
make_tile: String -> rop::Ro_Pixmap,
#
style: wy::Widget_Style,
next_widget_id: Void -> Int
};
make_root_window
:
{ display_name: String, # X server spec, typically taken from DISPLAY environment variable, e.g. ":0.0" or "foo.com:0.0" or such.
xauthentication: Null_Or( xt::Xauthentication ), # See Xauthentication comments in src/lib/x-kit/xclient/xclient.api run_gun': Run_Gun,
end_gun: End_Gun
}
->
Root_Window;
delete_root_window: Root_Window -> Void;
#
# Close the display connection. This
# deletes all windows associated with it
# and releases all associated X server
# resources such as fonts.
same_root: (Root_Window, Root_Window) -> Bool;
xsession_of: Root_Window -> xsession_junk::Xsession;
screen_of: Root_Window -> xsession_junk::Screen;
shades: Root_Window -> xc::Rgb -> wb::Shades;
ro_pixmap: Root_Window -> String -> xc::Ro_Pixmap;
color_of: Root_Window -> xc::Color_Spec -> xc::Rgb;
open_font: Root_Window -> String -> font_base::Font;
get_standard_xcursor: Root_Window -> xrs::Standard_Xcursor -> xrs::Xcursor;
ring_bell: Root_Window -> Int -> Void; # Generate beep. Int volume argument must be in range [-100,100].
size_of_screen: Root_Window -> g2d::Size;
mm_size_of_screen: Root_Window -> g2d::Size;
depth_of_screen: Root_Window -> Int;
is_monochrome: Root_Window -> Bool;
style_of: Root_Window -> wy::Widget_Style;
style_from_strings: (Root_Window, List( String )) -> wy::Widget_Style;
/* was/is included for testing purposes: disabled because can be unreliable.
my stringsFromStyle: Style -> List( String )
*/
# merge_Styles (style1, style2): merge style1 with style2,
# giving precedence first to tight namings, then to resources
# of style1.
#
merge_styles: (wy::Widget_Style, wy::Widget_Style) -> wy::Widget_Style;
# styleFromXRDB: return a style created from the properties
# loaded by xrdb into the X-server
#
style_from_xrdb: Root_Window -> wy::Widget_Style;
# Commandline option specification and parsing -- see
#
# src/lib/x-kit/style/widget-style-g.pkg #
Opt_Name;
Arg_Name;
Opt_Kind;
Opt_Spec;
Opt_Db;
Value;
# parse_command: given a root and
# an option spec, create an option db
# from command line arguments.
#
parse_command: Opt_Spec -> List( String ) -> (Opt_Db, List( String ));
# find_named_opt: given an option db and a named option (an option to
# be used for purposes other than resource specification), return a
# list of attribute::attribute_values. This list is ordered such that the last
# value to appear on the command line appears first in this list, so
# that the application may choose to use the first value only, or it
# may choose to use all values given.
# Named options should be typically useful in obtaining input for
# processing by an application, as opposed to X resource specification
# values. For example, "-filename foo" will probably be used by an
# application in some process, while "-background bar" is an X resource
# to be used in some graphical display.
# For further details see src/lib/x-kit/style/styles-fn.pkg.
#
find_named_opt: Opt_Db -> Opt_Name -> Root_Window -> List( Value );
#
find_named_opt_strings: Opt_Db -> Opt_Name -> List( String );
# style_from_opt_db: create a style from resource specifications in optDb.
#
style_from_opt_db: (Root_Window, Opt_Db) -> wy::Widget_Style;
# A utility function that returns a string
# outlining the valid command line arguments
# in opt_spec.
#
help_string_from_opt_spec: Opt_Spec -> String;
};
end;