XTkWidgets.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 3:28 pm PDT
DIRECTORY
IO USING [STREAM],
Rope USING [ROPE],
Xl USING [BOOL3, Connection, Event, Font, Geometry, nullWindow, Size, TQ, TimeStamp, Window],
XTk USING [Mapping, Widget, WidgetNotifyProc, WidgetSpec],
XTkCommon USING [ChoiceElement, RepaintMode, StyleSpec],
XTkShellWidgetTypes USING [ICCCMHints];
XTkWidgets: CEDAR DEFINITIONS
~ BEGIN OPEN Xl;
Implements some simple widget classes
ROPE: TYPE = Rope.ROPE;
Geometry: TYPE = Xl.Geometry;
Widget: TYPE = XTk.Widget;
WidgetNotifyProc: TYPE = XTk.WidgetNotifyProc;
WidgetSpec: TYPE = XTk.WidgetSpec;
queryDBFont: READONLY Font; --this "Font" can not be used for drawing
Bare widgets
CreateBareWidget: PROC [widgetSpec: WidgetSpec ¬ []] RETURNS [Widget];
Creates a widget with no other semantics as just an X window
Usefull to have a bare X window for applications wanting to paint directly. Could even be used to pass to an other application...
Shell widgets
Shell widgets are widgets which do not have normal parent widgets.
The typical shell widgets are those which do the window manager conventions.
ShellWidget: TYPE = Widget;
ShellWidget won't be garbage collected between realization and destruction
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=Xl.Connection
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];
Do not call this from inside a configure procedure. Any thread.
Set child
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. Then 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
Critical part is forked!
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.
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
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...
Container widgets
ContainerWidget: TYPE = Widget;
CreateYStack: PROC [widgetSpec: WidgetSpec ¬ [], stack: LIST OF Widget ¬ NIL, force: INT ¬ -1] RETURNS [ContainerWidget];
Container which abuts children in Y direction
force: force children height; -1 to leave individual; 0 to split equal
CreateXStack: PROC [widgetSpec: WidgetSpec ¬ [], stack: LIST OF Widget ¬ NIL, force: INT ¬ -1] RETURNS [ContainerWidget];
Container which abuts children in X direction
force: force children width; -1 to leave individual; 0 to split equal
CreateContainer: PROC [widgetSpec: WidgetSpec ¬ [], children: LIST OF Widget ¬ NIL] RETURNS [ContainerWidget];
Container which draws children at their requested size and position
AppendChild: PROC [container: ContainerWidget, child: Widget, startReconfigure: BOOL ¬ TRUE];
Append child as last child to ContainerWidget
Callable from any thread
AppendChildren: PROC [container: ContainerWidget, children: LIST OF Widget, startReconfigure: BOOL ¬ TRUE];
Append children to ContainerWidget
Callable from any thread
RemoveChild: PROC [container: ContainerWidget, child: Widget, destroyChild: BOOL ¬ TRUE, startReconfigure: BOOL ¬ TRUE];
Removes child from ContainerWidget.
Callable from any thread
SetForce: PROC [container: ContainerWidget, force: INT];
force: forces children height in stacks.
-1 to leave individual; 0 to split equal.
Delayed until next reconfigure.
Text widgets
TextWidget: TYPE = Widget;
StyleSpec: TYPE = XTkCommon.StyleSpec;
ButtonHitProcType: TYPE = XTk.WidgetNotifyProc;
CreateLabel: PROC [widgetSpec: WidgetSpec ¬ [], text: Rope.ROPE ¬ NIL, style: StyleSpec ¬ []] RETURNS [TextWidget];
Creates a label.
A label is a piece of text which can not be directly changed by editing operations.
CreateButton: PROC [widgetSpec: WidgetSpec ¬ [], text: Rope.ROPE ¬ NIL, style: StyleSpec ¬ [], hitProc: XTk.WidgetNotifyProc ¬ NIL, registerData, callData: REF ¬ NIL, tq: TQ ¬ NIL, help: Rope.ROPE ¬ NIL] RETURNS [TextWidget];
Creates a button.
A button is a piece of text which can not be edited, but which calls hitProc [on thread]
when interactively poked at. [A NIL thread causes the hitProc to fork.]
CreateField: PROC [widgetSpec: WidgetSpec ¬ [], text: Rope.ROPE ¬ NIL, style: StyleSpec ¬ []] RETURNS [TextWidget];
Creates a field.
A field is a piece of text which can be edited.
CreateLabeledField: PROC [widgetSpec: WidgetSpec ¬ [], label, init: ROPE ¬ NIL, style: StyleSpec ¬ [], labelWidth, fieldWidth: INT ¬ 0] RETURNS [TextWidget];
Creates a widget which contains a label and a field.
GetText/SetText operates on field but not on label.
GetText: PROC [widget: TextWidget] RETURNS [ROPE];
Returns current text in widget.
RepaintMode: TYPE = XTkCommon.RepaintMode;
SetText: PROC [widget: TextWidget, text: ROPE, repaint: RepaintMode ¬ immediately];
Replaces text displayed with widget; does not change size.
repaint: forces window to repaint.
From any thread.
SetFont: PROC [widget: TextWidget, font: Font, repaint: RepaintMode ¬ immediately];
Replaces font of displayed text.
repaint: forces window to repaint.
From any thread.
SetStyleKey: PROC [widget: TextWidget, style: ATOM, repaint: RepaintMode ¬ immediately];
Replaces style of displayed text.
repaint: forces window to repaint.
Possible styles [see also doc]: NIL, $WhiteOnBlack.
From any thread.
Choice widgets
ChoiceWidget: TYPE = Widget;
ChoiceElement: TYPE = XTkCommon.ChoiceElement;
ChoiceList: TYPE = LIST OF ChoiceElement;
CurrentChoice: PROC [widget: ChoiceWidget] RETURNS [REF ANY];
Returns key field of current choice
Choose: PROC [widget: ChoiceWidget, ce: ChoiceElement];
Selects the feedback choice of a ChoiceWidget;
Like interactive action, except the hitProc is not called.
It is ok if only text or only key in ChoiceElement is defined.
Use this for initializations.
CreateChoices: PROC [widgetSpec: WidgetSpec ¬ [], choices: ChoiceList, horizontal: BOOL ¬ TRUE, hitProc: XTk.WidgetNotifyProc ¬ NIL, registerData: REF ¬ NIL, tq: TQ ¬ NIL, style: StyleSpec ¬ []] RETURNS [ChoiceWidget];
ChoiceWidget displays choices but marks the currently selected one.
choices must not be NIL.
The hitProc procedure is executed on thread [forked if NIL].
style: applied to all elements
choices with NIL key can not be selected; all choices are visible.
CreateToggle: PROC [widgetSpec: WidgetSpec ¬ [], choices: ChoiceList, hitProc: XTk.WidgetNotifyProc ¬ NIL, registerData: REF ¬ NIL, tq: TQ ¬ NIL, style: StyleSpec ¬ []] RETURNS [ChoiceWidget];
ChoiceWidget displays current options but can be toggled through choices.
Ruler and spaces
CreateRuler: PROC [widgetSpec: WidgetSpec ¬ []] RETURNS [Widget];
Creates a recangle. A quite heavy weight method of painting rectangles.
Define the geometry field! a defaulted value means all the way if the parent supports that.
HRule: PROC [height: INT ← 1] RETURNS [XTk.Widget];
VRule: PROC [width: INT ← 1] RETURNS [XTk.Widget];
Short cuts for CreateRuler
CreateSpace: PROC [widgetSpec: XTk.WidgetSpec ¬ []] RETURNS [XTk.Widget];
Creates a widget with no other semantics as just using up space
HSpace: PROC [width: INT ← 1] RETURNS [XTk.Widget];
VSpace: PROC [height: INT ← 1] RETURNS [XTk.Widget];
Short cuts for CreateSpace
Output stream widgets
CreateStreamWidget: PROC [widgetSpec: WidgetSpec ¬ [], widgetStream: IO.STREAM ¬ NIL] RETURNS [Widget];
Creates a stream widget, enabling ascii output.
If widgetStream is not NIL, its output will be directed to the created widget.
CreateStream: PROC [w: Widget ¬ NIL] RETURNS [widgetStream: IO.STREAM];
Creates a new widgetStream stream which can direct its output into arbitrary stream-widgets.
If w is not NIL the new stream will direct its output into w.
Stream might discard characters until widget is attached, created and widget is realized.
BindStream: PROC [w: Widget, widgetStream: IO.STREAM];
Further output into widgetStream is directed into w.
END.