15.3.709  src/lib/x-kit/xclient/src/window/xsocket-to-topwindow-router.api

## xsocket-to-topwindow-router.api
#
# API for functionality which reads X server events from
#
#     src/lib/x-kit/xclient/src/wire/xsocket.pkg
# 
# (specifically, xbuf_imp) and routes them
# to the appropriate top-level window.
# From there they get routed down the widget tree:
#
#     src/lib/x-kit/xclient/src/window/topwindow-to-widget-router.api

# Compiled by:
#     src/lib/x-kit/xclient/xclient-internals.sublib



# This api is implemented in:
#
#     src/lib/x-kit/xclient/src/window/xsocket-to-topwindow-router.pkg

stipulate
    include threadkit;                                                  # threadkit             is from   src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit.pkg
    #
    package xt =  xtypes;                                               # xtypes                is from   src/lib/x-kit/xclient/src/wire/xtypes.pkg
    package xg =  xgeometry;                                            # xgeometry             is from   src/lib/std/2d/xgeometry.pkg
herein

    api Xsocket_To_Topwindow_Router {

        Xsocket_To_Topwindow_Router;

        Envelope_Route
          = ENVELOPE_ROUTE_END  xt::Window_Id
          | ENVELOPE_ROUTE     (xt::Window_Id, Envelope_Route)
          ;
                        # XXX BUGGO FIXME Envelope_Route should be defined elswhere, with Envelope.
                        # Current Envelope is defined in src/lib/x-kit/xclient/src/window/widget-cable.pkg

        make_xsocket_to_topwindow_router
            :
            { xdisplay:       display::Xdisplay,
              keymap_imp:     keymap_imp::Keymap_Imp,
              #
              to_window_property_imp_slot:  Mailslot( event_types::x::Event ),
              to_selection_imp_slot:        Mailslot( event_types::x::Event )
            }
            ->
            Xsocket_To_Topwindow_Router;

        # Note new toplevel window and return the event slot
        # through which we will feed X events to that window:
        #
        note_new_topwindow
            :
            ( Xsocket_To_Topwindow_Router,
              xt::Window_Id,
              xg::Window_Site   
            )
            ->
            Mailop( (Envelope_Route, event_types::x::Event) );

        # Lock a window and all of its descendants.
        # Return the unlocking function:
        #
        lock_window_tree
            :
            (Xsocket_To_Topwindow_Router, xt::Window_Id)
            ->
            (Void -> Void);

        # Test to see if a window is locked:
        # 
        window_is_locked
            :
            ( Xsocket_To_Topwindow_Router,
              xt::Window_Id
            )
            ->
            Bool;

        # Get size of window plus position
        # relative to parent:
        #
        get_window_site
            :
            ( Xsocket_To_Topwindow_Router,
              xt::Window_Id
            )
            ->
            xg::Box;


        # Infrastructure -- see comments in src/lib/x-kit/xclient/src/window/xsocket-to-topwindow-router.pkg
        #
        note_window's_''seen_first_expose''_oneshot
            :
            ( Xsocket_To_Topwindow_Router,
              xt::Window_Id,
              Oneshot_Maildrop(Void)
            )
            ->
            Void;

        # This function makes the above oneshot
        # available to clients with access to
        # the Window but not the Widget.  Clients
        # with access to the Widget should use the
        #
        #     widget::seen_first_redraw_oneshot_of
        #
        # call because it is guaranteed to return
        # the required oneshot;  the below call may
        # return NULL, in which case the client thread
        # will have to sleep a bit and then retry:
        #
        get_''seen_first_expose''_oneshot_of
            :
            ( Xsocket_To_Topwindow_Router,
              xt::Window_Id
            )
            ->
            Null_Or(Oneshot_Maildrop(Void));

        
        # Application threads can wait on the oneshot
        # returned by this call; when it fires they
        # can be confident that the GUI windows exist
        # and the widget threads have been created and
        # in general the widgettree is go.
        #
        # Currently this oneshot it set when the first
        # EXPOSE xevent is received from the X server,
        # but that is internal implementation, not
        # supported external semantics:
        #
        get_''gui_startup_complete''_oneshot_of
            :
            Xsocket_To_Topwindow_Router
            ->
            Oneshot_Maildrop(Void);

    };
end;                                            # stipulate



## COPYRIGHT (c) 1990, 1991 by John H. Reppy.  See SMLNJ-COPYRIGHT file for details.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2013,
## released per terms of SMLNJ-COPYRIGHT.