XTkShellWidgets.mesa
Copyright Ó 1988, 1989, 1990, 1991, 1992 by Xerox Corporation. All rights reserved.
Created by Christian Jacobi, October 18, 1988 10:46:22 am PDT
Christian Jacobi, April 8, 1992 2:47 pm PDT
DIRECTORY
Rope USING [ROPE],
Xl USING [BOOL3, Connection, Event, Geometry, nullWindow, Size, TQ, TimeStamp, Window],
XTkShellWidgetTypes USING [ICCCMHints],
XTk USING [Mapping, Widget, WidgetNotifyProc, WidgetSpec];
XTkShellWidgets: CEDAR DEFINITIONS
~ BEGIN
Shell widgets are widgets which do not have normal parent widgets.
The typical shell widgets are those which do the window manager conventions.
ROPE: TYPE = Rope.ROPE;
Geometry: TYPE = Xl.Geometry;
Widget: TYPE = XTk.Widget;
WidgetNotifyProc: TYPE = XTk.WidgetNotifyProc;
WidgetSpec: TYPE = XTk.WidgetSpec;
Shell widgets
ShellWidget: TYPE = Widget;
ShellWidget won't be garbage collected between realization and destruction
IsShell: PROC [w: XTk.Widget] RETURNS [BOOL];
Returns true if w is shell or subclass of shell
CreateShell: PROC [widgetSpec: WidgetSpec ¬ [], child: Widget ¬ NIL, windowHeader: ROPE ¬ NIL, iconName: ROPE ¬ NIL, className: ATOM ¬ NIL, packageName: ROPE ¬ NIL, shortName: ROPE ¬ NIL, rootTQ: Xl.TQ ¬ NIL, dontQueryGeometry: BOOL ¬ FALSE, deletionProtocol: BOOL ¬ TRUE, focusProtocol: BOOL ¬ TRUE, standardMigration: BOOL ¬ TRUE] RETURNS [ShellWidget];
Creates a shell widget, subject to window management.
rootTQ: if not defaulted must watch locking order!
shortName: used for look ups
packageName: e.g. used for finding files
deletionProtocol: interactive enable of DestroyShell [using WM DELETE WINDOW protocol].
focusProtocol: enables FocusTarget [using WM TAKE FOCUS protocol].
BindScreenShell: PROC [shell: ShellWidget, connection: REF ¬ NIL, parentWindow: Xl.Window ¬ Xl.nullWindow];
Creates connection and binds screen.
connection: If not a Xl.Connection, one is made up.
atom, NIL: Check external for a server name and create connection.
rope: Create connection to this server.
May raise Xl.connectionNotCreated.
ForgetScreenShell: PROC [shell: ShellWidget];
Unrealizes shell and forgets screen.
RegisterCallWMDeleteWindow: PROC [shell: ShellWidget, proc: WidgetNotifyProc, registerData: REF ¬ NIL];
Registers proc to be called in case of a window manager request to delete the window. Default behaviour is to destroy the widget; but note that this is invoked only when deletionProtocol is TRUE. Procedure may deny the deletion. Unregisters previous proc. Not monitored. callData=$wmDeleteWindow
RegisterCallConnectionDied: PROC [shell: ShellWidget, proc: WidgetNotifyProc, registerData: REF ¬ NIL];
Registers proc to be called on rootTQ in case of unexpected dying connection (after stopping interactions). Default behaviour is to destroy the widget. Procedure must forget the screen. Unregisters previous proc. Not monitored. callData=$connectionDied
RegisterCallWindowDied: PROC [shell: ShellWidget, proc: WidgetNotifyProc, registerData: REF ¬ NIL];
Registers proc to be called on rootTQ in case of unexpected destroyWindow event (after stopping interactions). Default behaviour is to destroy the widget. Procedure must forget the screen. Unregisters previous proc. Not monitored. callData=$destroyNotify
SetShellChild: PROC [shell: ShellWidget, child: Widget];
Changes child of shell; destroys previous one.
RealizeShell: PROC [shell: ShellWidget, geometry: Xl.Geometry ¬ [], mapping: XTk.Mapping ¬ mapped, reConsiderChildren: BOOL ¬ TRUE];
Acquires lock and builds the widget tree (starts configuration).
If no screen has been bound, one is made up. May raise Xl.connectionNotCreated.
ForkRealizeShell: PROC [shell: ShellWidget, geometry: Xl.Geometry ¬ [], mapping: XTk.Mapping ¬ mapped, reConsiderChildren: BOOL ¬ TRUE];
Forks and calls RealizeShell (start configuration).
DestroyShell: PROC [shell: ShellWidget];
Destroys the widget tree
ApplicationClassName: PROC [shell: ShellWidget] RETURNS [className: ATOM];
Destroys the widget tree
Input Focus according to ICCCM
SetFocusMethod: PROC [shell: ShellWidget, focusProtocol, inputHint: Xl.BOOL3 ¬ illegal];
Sets the input method hints according to ICCCM
focusProtocol: Usage of WM←TAKE𡤏OCUS protocol
inputHint: WM←HINTS InputHint flag
No input:
No keyboard input expected
(focusProtocol: false, inputHint: false)
Passive:
Expects input but does not set input focus
(focusProtocol: false, inputHint: true)
Locally active:
Client sets input focus when it is in one of his windows
(focusProtocol: true, inputHint: true)
Globally active:
Client sets input focus even when it belonged to another clients window
(focusProtocol: true, inputHint: false)
Some window managers read flags only on transition from withdrawn state.
SetFocus: PROC [shell: ShellWidget, time: Xl.TimeStamp, child: REF ¬ NIL];
Actively sets the input focus to child if time is valid and advances time.
child a Widget, REF Window or NIL
(child=NIL: use current focus target of shell)
(child#NIL: set focus target of shell and input focus)
SetFocusTarget: PROC [shell: ShellWidget, child: REF ¬ NIL, time: Xl.TimeStamp ¬ [0]];
Delayed: If shell gets WM←TAKE𡤏OCUS message (or a SetFocus with NIL child) shell will then set (forward) focus to child.
child a Widget, REF Window or NIL
time: If used then restricts operation to valid times. Time is not advanced.
Useful only if ICCCM WM←TAKE𡤏OCUS protocol is enabled.
FocusTime: PROC [shell: ShellWidget] RETURNS [Xl.TimeStamp];
Returns TimeStamp of last WM←TAKE𡤏OCUS message or SetFocus to shell.
Window state according to ICCCM
Top level windows are in either normal state (open) Iconic state or withdrawn state.
These routines do not cache the state and therefore might generate request to the server even if not absolutely necessary. Don't rely on result: Interactive actions of user through window manager could change state at any time.
These procedures do not cause realization but might be delayed if a shell hasn't been realized.
OpenIcon: PROC [shell: ShellWidget];
Opens iconic or withdrawn widget. Fancy map request.
Iconify: PROC [shell: ShellWidget];
Iconifies open or withdrawn widget.
WithDraw: PROC [shell: ShellWidget];
Puts open or iconic window into withdrawn state. Fancy unmap request.
Withdrawn state is particularly interesting since on transition from it the window manager really must read the windows properties.
Other ICCCM stuff
SetHeader: PROC [shell: ShellWidget, header: ROPE];
Conveniance procedure assigning WM NAME property.
Some window managers might consider change only on transition from withdrawn state.
SetIconName: PROC [shell: ShellWidget, header: ROPE];
Conveniance procedure assigning WM ICON←NAME property.
Some window managers might consider change only on transition from withdrawn state.
TrackColorMap: PROC [shell: ShellWidget, w: Widget];
Makes the necessary ICCCM compliant mumbojumbo so window managers will know to install w's color map.
GetHints: PROC [shell: ShellWidget] RETURNS [REF ICCCMHints];
Returns associated fields for ICCCM hints.
Cache for properties! Will be put onto property before first mapping. Cedar convention: whenever data covered by ICCCMHints is modified, change it also in hints (So next client will set all the fields correctly).
UpdateHints: PROC [shell: ShellWidget];
Eventually makes sure ICCCMHints are forwarded to server
ICCCMHints: TYPE = XTkShellWidgetTypes.ICCCMHints;
Interoperability widgets
CreateInteroperabilityShell: PROC [widgetSpec: WidgetSpec ¬ [], child: Widget ¬ NIL, className: ATOM ¬ NIL, rootTQ: Xl.TQ ¬ NIL ] RETURNS [ShellWidget];
Creates an interoperability shell widget.
BindInteroperabilityShell: PROC [shell: ShellWidget, connection: Xl.Connection, foreignParent: Xl.Window];
Grafting interoperability shell as child of an X window of an unknown connection.
Warning: there is no control whether foreignParent just disappears with or without its connection...
END.