## xsession-junk.api
#
# Compiled by:
# src/lib/x-kit/xclient/xclient-internals.sublib# TODO:
#
# I think we should recast the X session type as a
# trivial-OOP record of closures. This will let us write
#
# session.foo (bar, zot);
#
# in place of
#
# sn::foo (session, bar, zot);
#
# With the following benefits:
#
# o It takes better advantage of existing
# mainstream-hacker OOP (or just C) intuition.
#
# o Eventually we should be able to tweak the typechecker
# so that "foo" is resolved in the context of "session"'s
# type (rather than in the full local context, as currently).
# At this point we will be dispensing with the irritating
# "sn::" package qualifier without loss of namespace cleanliness.
# This does make the relevant code definition less obvious;
# maybe by then we'll have an IDE where hovering the mouse over
# an identifier pops up a tooltip-style window with its type.
#
# o It generalizes to a pervasive concurrent-programming
# paradigm in which "trampoline" style record-of-closure
# objects serve as ``capabilities'' granting access to
# some some im/proper subset of the functionality of an
# object.
# If we are to go this route, our OOP support will need
# to move from the conventional notion of object as
# state-record with embedded method-table pointer to one
# which somehow provides support for the trampoline/warthog
# paradigm of trampoline "capability" objects indirectly
# referencing the primary warthog object. Maybe something
# using one nested subpackage per capability/trampoline:
#
# class package foo {
# capability package bar {
# method fun zot ...
# }:
# fun make_bar_capability foo_instance
# =
# bar::make foo_instance;
# ...
#
# where the bar::make function is autogenerated by the compiler
# and contains an entry for every method fun declared in 'bar'.
stipulate
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 cs = color_spec; # color_spec is from src/lib/x-kit/xclient/src/window/color-spec.pkg package xt = xtypes; # xtypes is from src/lib/x-kit/xclient/src/wire/xtypes.pkg# package dy = display_old; # display_old is from src/lib/x-kit/xclient/src/wire/display-old.pkg package dy = display; # display is from src/lib/x-kit/xclient/src/wire/display.pkg# package fb = font_base_old; # font_base_old is from src/lib/x-kit/xclient/src/window/font-base-old.pkg package fb = font_base; # font_base is from src/lib/x-kit/xclient/src/window/font-base.pkg# package fti = font_imp_old; # "fi" is taken! :-) # font_imp_old is from src/lib/x-kit/xclient/src/window/font-imp-old.pkg package fti = font_index; # font_index is from src/lib/x-kit/xclient/src/window/font-index.pkg# package p2g = pen_to_gcontext_imp_old; # pen_to_gcontext_imp_old is from src/lib/x-kit/xclient/src/window/pen-to-gcontext-imp-old.pkg package p2g = pen_cache; # pen_cache is from src/lib/x-kit/xclient/src/window/pen-cache.pkg# package s2t = xsocket_to_hostwindow_router_old; # xsocket_to_hostwindow_router_old is from src/lib/x-kit/xclient/src/window/xsocket-to-hostwindow-router-old.pkg package s2t = xevent_router_ximp; # xevent_router_ximp is from src/lib/x-kit/xclient/src/window/xevent-router-ximp.pkg package a2r = windowsystem_to_xevent_router; # windowsystem_to_xevent_router is from src/lib/x-kit/xclient/src/window/windowsystem-to-xevent-router.pkg# package ai = atom_imp_old; # atom_imp_old is from src/lib/x-kit/xclient/src/iccc/atom-imp-old.pkg package ai = atom_ximp; # atom_ximp is from src/lib/x-kit/xclient/src/iccc/atom-ximp.pkg package ap = client_to_atom; # client_to_atom is from src/lib/x-kit/xclient/src/iccc/client-to-atom.pkg# package di = draw_imp_old; # draw_imp_old is from src/lib/x-kit/xclient/src/window/draw-imp-old.pkg package di = xserver_ximp; # xserver_ximp is from src/lib/x-kit/xclient/src/window/xserver-ximp.pkg# package ki = keymap_imp_old; # keymap_imp_old is from src/lib/x-kit/xclient/src/window/keymap-imp-old.pkg package ki = keymap_ximp; # keymap_ximp is from src/lib/x-kit/xclient/src/window/keymap-ximp.pkg package r2k = xevent_router_to_keymap; # xevent_router_to_keymap is from src/lib/x-kit/xclient/src/window/xevent-router-to-keymap.pkg# package si = selection_imp_old; # selection_imp_old is from src/lib/x-kit/xclient/src/window/selection-imp-old.pkg package si = selection_ximp; # selection_ximp is from src/lib/x-kit/xclient/src/window/selection-ximp.pkg package sep = client_to_selection; # client_to_selection is from src/lib/x-kit/xclient/src/window/client-to-selection.pkg package w2x = windowsystem_to_xserver; # windowsystem_to_xserver is from src/lib/x-kit/xclient/src/window/windowsystem-to-xserver.pkg package x2s = xclient_to_sequencer; # xclient_to_sequencer is from src/lib/x-kit/xclient/src/wire/xclient-to-sequencer.pkg package mop = mailop; # mailop is from src/lib/src/lib/thread-kit/src/core-thread-kit/mailop.pkg package wme = window_map_event_sink; # window_map_event_sink is from src/lib/x-kit/xclient/src/window/window-map-event-sink.pkg# package wpi = window_property_imp_old; # window_property_imp_old is from src/lib/x-kit/xclient/src/window/window-property-imp-old.pkg package wpi = window_watcher_ximp; # window_watcher_ximp is from src/lib/x-kit/xclient/src/window/window-watcher-ximp.pkg package wpp = client_to_window_watcher; # client_to_window_watcher is from src/lib/x-kit/xclient/src/window/client-to-window-watcher.pkgherein
# This api is implemented in:
#
# src/lib/x-kit/xclient/src/window/xsession-junk.pkg api Xsession_Junk {
#
Per_Depth_Imps = { # The pen-cache and draw_ximp for a given depth, visual and screen.
depth: Int,
# pen_cache: p2g::Pen_Cache, # The pen-to-cache for this depth on this screen.
windowsystem_to_xserver: w2x::Windowsystem_To_Xserver, # The xpacket encoder for this depth on this screen.
window_map_event_sink: wme::Window_Map_Event_Sink
}; #
# For each combination of visual and depth
# we allot a pair of imps, one to draw,
# one to manage graphics contexts.
# This is forced because X requires that
# each GraphicsContext and pixmap be associated
# with a particular screen, visual and depth.
Screen_Info = { xscreen: dy::Xscreen, # Xscreen def in src/lib/x-kit/xclient/src/wire/display-old.pkg per_depth_imps: List( Per_Depth_Imps ), # The pen-cache and draw imps for the supported depths on this screen.
rootwindow_per_depth_imps: Per_Depth_Imps # The pen-cache and draw imps for the root window on this screen.
};
Xsession = { xdisplay: dy::Xdisplay, #
screens: List( Screen_Info ),
default_screen_info: Screen_Info,
windowsystem_to_xevent_router: a2r::Windowsystem_To_Xevent_Router, # Feeds X events to appropriate toplevel window.
font_index: fti::Font_Index,
client_to_atom: ap::Client_To_Atom,
client_to_window_watcher: wpp::Client_To_Window_Watcher,
client_to_selection: sep::Client_To_Selection,
windowsystem_to_xserver: w2x::Windowsystem_To_Xserver,
xevent_router_to_keymap: r2k::Xevent_Router_To_Keymap
};
Screen = { # A screen handle for users.
xsession: Xsession,
screen_info: Screen_Info
};
Rw_Pixmap = { # An off-screen rectangular array of pixels on the X server.
pixmap_id: xt::Pixmap_Id,
screen: Screen,
size: g2d::Size,
per_depth_imps: Per_Depth_Imps
};
Ro_Pixmap = RO_PIXMAP Rw_Pixmap; # Immutable pixmaps
#
Window = { # An on-screen rectangular array of pixels on the X server.
window_id: xt::Window_Id,
#
screen: Screen,
per_depth_imps: Per_Depth_Imps,
#
windowsystem_to_xserver: w2x::Windowsystem_To_Xserver,
#
subwindow_or_view: Null_Or( Rw_Pixmap ) # 'subwindow_or_view' was probably accidentally renamed and needs to be renamed back to something sensible like 'pixmap'. XXX SUCKO FIXME.
};
# Identity tests:
#
same_xsession: (Xsession, Xsession) -> Bool;
same_screen: (Screen, Screen ) -> Bool;
same_window: (Window, Window ) -> Bool;
# Currently called only internally within xesssion-junk.pkg:
#
# make_per_screen_xsession_imps: # Called mainly from make_root_window in src/lib/x-kit/widget/old/basic/root-window-old.pkg# {
# run_gun': mop::Run_Gun,
# end_gun': mop::End_Gun,
# windowsystem_to_xevent_router: a2r::Windowsystem_To_Xevent_Router, # Directs X mouseclicks etc to right hostwindow.
# xclient_to_sequencer: x2s::Xclient_To_Sequencer, # All drawing commands go to X server via sequencer then outbuf.
# client_to_atom: ap::Client_To_Atom,
# xevent_router_to_keymap: r2k::Xevent_Router_To_Keymap,
# client_to_selection: sep::Client_To_Selection,
# client_to_window_watcher: wpp::Client_To_Window_Watcher,
# xdisplay: dy::Xdisplay,
# drawable: xt::Drawable_Id
# }
# ->
# Xsession;
open_xsession:
{
display_name: String,
xauthentication: Null_Or( xt::Xauthentication ),
run_gun': mop::Run_Gun,
end_gun': mop::End_Gun
}
-> Xsession;
#
# Start an X session with some X server.
#
# Parameters:
#
# display_name: "128.84.254.97:0.0" or such.
#
# General display_name format is:
#
# <host>:<display_number><screen_number>.
#
# display_number:
# screen_number:
# In practice these are almost always zero,
# since most home computers have a single
# display subsystem with a single logical
# screen, even if using two physical monitors.
# (My xserver box has six monitors and three
# graphics cards, but still gets addressed
# as the single screen 0.0)
#
# host:
# This can be "unix" to open a unix domain
# socket instead of the usual internet domain socket.
#
# Supported display_name abbreviations include:
# "" == "unix:0.0"
# ":3" == "unix:3.0"
# ":3.4" == "unix:3.4"
# "128.84.254.97:0 == "128.84.254.97:0.0
#
# Any failure to connect to the given display
# results in raising of the exception
#
# display::BAD_ADDRESS "somestring";
#
# xauthentication:
# See Xauthentication comments in
# src/lib/x-kit/xclient/xclient.api.
# X-server I/O.
#
# These just forward to the
# Xsocket embedded in the Xsession:
#
# send_xrequest: Xsession -> vector_of_one_byte_unts::Vector -> Void;
# send_xrequest_and_return_completion_mailop: Xsession -> vector_of_one_byte_unts::Vector -> Mailop( Void );
#
# send_xrequest_and_read_reply: Xsession -> vector_of_one_byte_unts::Vector -> Mailop( vector_of_one_byte_unts::Vector );
# sent_xrequest_and_read_replies: Xsession -> (vector_of_one_byte_unts::Vector, (vector_of_one_byte_unts::Vector -> Int)) -> Mailop( vector_of_one_byte_unts::Vector );
#
# flush_out: Xsession -> Void;
close_xsession: Xsession -> Void;
# The standard X queries:
#
# It is possible these should be a separate
# package, but for now it seems simplest to
# just fold them into xsession:
# query_font
# :
# Xsession
# ->
# { font: xt::Xid }
# ->
# {
# all_chars_exist: Bool,
# default_char: Int,
# #
# char_infos: List(xt::Char_Info),
# draw_dir: xt::Font_Drawing_Direction,
# #
# font_ascent: Int,
# font_descent: Int,
# #
# min_bounds: xt::Char_Info,
# max_bounds: xt::Char_Info,
# #
# max_byte1: Int,
# min_byte1: Int,
# #
# min_char: Int,
# max_char: Int,
# #
# properties: List(xt::Font_Prop)
# }
# ;
#
# # Get/set location of mouse pointer
# # relative to root window:
# #
# get_mouse_location: Xsession -> g2d::Point;
# set_mouse_location: Xsession -> g2d::Point -> Void;
#
# query_colors
# :
# Xsession
# ->
# { cmap: xt::Xid,
# pixels: List(rgb8::Rgb8)
# }
# ->
# List(rgb::Rgb)
# ;
#
# query_best_size
# :
# Xsession
# ->
# { drawable: xt::Xid,
# ilk: xt::Best_Size_Ilk,
# size: g2d::Size
# }
# ->
# { high: Int,
# wide: Int
# }
# ;
#
# query_text_extents
# :
# Xsession
# ->
# { font: xt::Xid,
# string: String
# }
# ->
# { draw_direction: xt::Font_Drawing_Direction,
# #
# font_ascent: one_word_unt::Unt,
# font_descent: one_word_unt::Unt,
# #
# overall_ascent: one_word_unt::Unt,
# overall_descent: one_word_unt::Unt,
# #
# overall_left: one_word_unt::Unt,
# overall_right: one_word_unt::Unt,
# #
# overall_width: one_word_unt::Unt
# }
# ;
#
# # See p23 http://mythryl.org/pub/exene/X-protocol-R6.pdf
# #
# query_tree
# :
# Xsession
# ->
# { window_id: xt::Xid }
# ->
# { children: List(xt::Xid),
# parent: Null_Or(xt::Xid),
# root: xt::Xid
# }
# ;
#
# NB: Rather than using the following xevent-send calls,
# you will often find it more convenient to use the
# corresponding call in
#
# src/lib/x-kit/xclient/src/window/window.api # Make 'window' receive a (faked) keyboard keypress at 'point'.
# 'window' should be the sub/window actually holding the widget to be activate.
# 'point' should be the click point in that window's coordinate system.
#
# NOTE! We send the event via the X server to provide full end-to-end testing;
# the resulting network round trip will be quite slow, making this call
# generally inappropriate for anything other than unit test code.
#
send_fake_key_press_xevent
:
Xsession
->
{ window: Window, # Window handling the keypress event.
keycode: xt::Keycode, # Keyboard key just pressed down.
point: g2d::Point
}
->
Void
;
# Make 'window' receive a (faked) keyboard key release at 'point'.
# 'window' should be the sub/window actually holding the widget to be activate.
# 'point' should be the click point in that window's coordinate system.
#
# NOTE! We send the event via the X server to provide full end-to-end testing;
# the resulting network round trip will be quite slow, making this call
# generally inappropriate for anything other than unit test code.
#
send_fake_key_release_xevent
:
Xsession
->
{ window: Window, # Window handling the keypress event.
keycode: xt::Keycode, # Keyboard key just pressed down.
point: g2d::Point
}
->
Void
;
# Make 'window' receive a (faked) mousebutton click at 'point'.
# 'window' should be the sub/window actually holding the widget to be activate.
# 'point' should be the click point in that window's coordinate system.
#
# NOTE! We send the event via the X server to provide full end-to-end testing;
# the resulting network round trip will be quite slow, making this call
# generally inappropriate for anything other than unit test code.
#
send_fake_mousebutton_press_xevent
:
Xsession
->
{ window: Window, # Window handling the mouse-button click event.
button: xt::Mousebutton, # Mouse button just clicked down.
point: g2d::Point
}
->
Void
;
# Counterpart of previous: make 'window' receive a (faked) mousebutton release at 'point'.
# 'window' should be the sub/window actually holding the widget to be activate.
# 'point' should be the button-release point in that window's coordinate system.
#
# NOTE! We send the event via the X server to provide full end-to-end testing;
# the resulting network round trip will be quite slow, making this call
# generally inappropriate for anything other than unit test code.
#
send_fake_mousebutton_release_xevent
:
Xsession
->
{ window: Window, # Window handling the mouse-button release event.
button: xt::Mousebutton, # Mouse button just released.
point: g2d::Point
}
->
Void
;
# This call may be used to simulate mouse "drag" operations in unit-test code.
# 'window' should be the sub/window actually holding the widget to be activate.
# 'point' should be the supposed mouse-pointer location in that window's coordinate system.
#
# NOTE! We send the event via the X server to provide full end-to-end testing;
# the resulting network round trip will be quite slow, making this call
# generally inappropriate for anything other than unit test code.
#
send_fake_mouse_motion_xevent
:
Xsession
->
{ window: Window, # Window handling the mouse-button release event.
buttons: List(xt::Mousebutton), # Mouse button(s) being dragged.
point: g2d::Point
}
->
Void
;
# The xkit buttons react not just to mouse-up and mouse-down events but also
# to mouse-enter and mouse-leave events, so to auto-test them propertly we
# must synthesize those also:
#
send_fake_''mouse_enter''_xevent
:
Xsession
->
{ window: Window, # Window handling the event.
point: g2d::Point # End-of-event coordinate, thus should be just inside window.
}
->
Void
;
#
send_fake_''mouse_leave''_xevent
:
Xsession
->
{ window: Window, # Window handling the event.
point: g2d::Point # End-of-event coordinate, thus should be just outside window.
}
->
Void
;
# Return the maximum request size
# supported by the display. This
# information comes ultimately from
# the connect-request reply supplied
# by the X server:
#
# max_request_length: Xsession -> Int;
# Atom operations:
#
# These just forward to the
# Atom_Imp embedded in the Xsession:
#
# make_atom: Xsession -> String -> xt::Atom;
# find_atom: Xsession -> String -> Null_Or( xt::Atom );
# atom_to_string: Xsession -> xt::Atom -> String;
# Font operations:
#
# These just forward to the
# Font_Imp embedded in the Xsession:
#
find_font: Xsession -> String -> fb::Font;
default_screen_of: Xsession -> Screen;
# screens_of: Xsession -> List(Screen);
# get_''gui_startup_complete''_oneshot_of_xsession # Export to the wider world from src/lib/x-kit/xclient/src/window/xsocket-to-hostwindow-router-old.api# :
# Xsession -> Oneshot_Maildrop(Void);
ring_bell: Xsession -> Int -> Void;
# Screen functions:
#
# color_of_screen: cs::Color_Spec -> rgb::Rgb;
xsession_of_screen: Screen -> Xsession;
root_window_of_screen: Screen -> xt::Window_Id;
size_of_screen: Screen -> g2d::Size;
mm_size_of_screen: Screen -> g2d::Size;
depth_of_screen: Screen -> Int;
display_class_of_screen: Screen -> xt::Display_Class;
per_depth_imps_for_depth: (Screen, Int) -> Per_Depth_Imps; # Arg is (screen, depth). Find and return per-depth imps for that screen and depth. Fatal if not present.
# Map a point in the window's coordinate system
# to the screen's coordinate system
#
window_point_to_screen_point: Window -> g2d::Point -> g2d::Point;
# keysym_to_keycode: (Xsession, xt::Keysym) -> Null_Or(xt::Keycode);
}; # api Xsession
end; # stipulate.