1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
.TH TKCLIENT 2
.SH NAME
tkclient: makedrawcontext, toplevel, onscreen, startinput,
wmctl, settitle, handler, snarfput, snarfget \-
window manager interface for Tk applications.
.SH SYNOPSIS
.EX
include "tkclient.m";
tkclient := load Tkclient Tkclient->PATH;
Resize,
Hide,
Help,
OK,
Plain: con 1 << iota;
Appl: con Resize | Hide;
init: fn();
makedrawcontext: fn(): ref Draw->Context;
toplevel: fn(ctxt: ref Draw->Context, topconfig: string,
title: string, buts: int): (ref Tk->Toplevel, chan of string);
onscreen: fn(top: ref Tk->Toplevel, how: string);
startinput: fn(top: ref Tk->Toplevel, devs: list of string);
wmctl: fn(top: ref Tk->Toplevel, request: string): string;
settitle: fn(top: ref Tk->Toplevel, name: string): string;
handler: fn(top: ref Tk->Toplevel, stop: chan of int);
snarfput: fn(buf: string);
snarfget: fn(): string;
.EE
.SH DESCRIPTION
The
.B Tkclient
module provides routines for making windows controlled by
.IR wm (1)
containing
.IR tk (2)
widgets.
.PP
.B Init
should be called once to initialise the internal state of
.BR tkclient .
.PP
.B Makedrawcontext
establishes an initial connection with the window manager,
creating a new
.B Draw
context suitable for creating new windows. It is only
necessary to call this if the application has not already
been provided with a context.
.PP
.B Toplevel
creates a new window through
.IR ctxt .
.I Topconfig
gives a list of
.IR frame (9)
options that are applied to the
new tk window, as described in
.IR tk (2).
.I Title
gives a label that will be displayed in the title bar
of the window;
.I buts
determines which buttons are created in the titlebar,
a bitwise combination of the constants
.BR Resize ,
.BR Help ,
.BR OK,
and
.BR Hide .
If
.B Plain
is given, the window is given no decoration at all.
.B Toplevel
returns a tuple, say
.RI ( top ,\ ctl ),
where
.I top
is the newly created top level tk window,
and
.I ctl
is a channel down which requests from the
title bar are sent.
Messages received on
.I ctl
should be processed
by the application or passed to the
.B wmctl
function. Requests are formatted
as with
.B quoted
in
.IR string (2).
The messages include:
.TP
.B exit
The window should be closed.
.B Wmctl
will kill all processes in the current
process group.
.TP
.B !move \fIx\fP \fIy\fP
The user has started to try to drag the window.
.I X
and
.I y
give the location of the initial pointer click.
.TP
.B !size
The user wishes to resize the window.
.TP
.B help
The help button has been clicked.
.TP
.B ok
The OK button has been clicked.
.TP
.B hide
The Hide button has been clicked.
The window will be deleted, and an entry
shown on the toolbar.
.PP
In order to function correctly, an application
should process not only events from the
title bar channel, but also events from
the Tk toplevel
.I wreq
channel, those received from the window
manager itself (via
.IB top .ctxt.ctl\fR),\fP
and pointer and keyboard events received from
the window manager (via
.IB top .ctxt.ptr
and
.IB top .ctxt.kbd
respectively).
Control events can be passed to
.BR wmctl ;
pointer and keyboard events should be
passed to their respective functions
in
.IR tk (2).
.PP
When created, the window is not visible
and will not receive pointer or keyboard events.
.B Onscreen
makes it visible, and possibly chooses a
position and a size for it.
.I How
specifies what sort of placement is required
for the window; it can be one of
.TP
.B place
tries to choose a suitable place on the screen
with respect to other windows; it may size the
window as it feels appropriate. This the default
(if
.I how
is nil).
.TP
.B onscreen
tries to keep the position and size the same
as specified on the window, adjusting them only
to bring the window fully on screen, and making sure
that the window is no bigger than the entire display.
.TP
.B exact
does not change the specified size or position
of the window unless absolutely necessary.
.PP
.B Startinput
informs the window manager that the window is
ready to the event types specified in
.IR devs .
Currently understood are
.B kbd
for keyboard events, and
.B ptr
for pointer events.
.PP
The simplest well-behaved
.IR wm (1)
client will therefore contain:
.PP
.EX
(top, ctl) := tkclient->toplevel(ctxt, nil, "My Program", Tkclient->Appl);
# ... populate the window with tk widgets
tkclient->startinput(top, "ptr" :: "kbd" :: nil);
tkclient->onscreen(top, nil);
for(;;){
alt{
s := <-ctl or
s = <-top.ctxt.ctl or
s = <-top.wreq =>
tkclient->wmctl(top, s);
p := <-top.ctxt.ptr =>
tk->pointer(top, *p);
c := <-top.ctxt.kbd =>
tk->keyboard(top, c);
}
}
.EE
.PP
.B Settitle
changes the name displayed in the title bar
and the window's name when it is in the task bar.
.PP
.B Snarfget
and
.B snarfput
retrieve and replace the contents of the window
manager's snarf buffer.
.SH FILES
.TF /chan/snarf
.TP
.B /chan/snarf
snarf buffer maintained by
.IR wm (1)
.TP
.B /chan/wm
channel for interaction with
.IR wm (1)
.SH SOURCE
.B /appl/lib/tkclient.b
.SH SEE ALSO
.IR wm (1),
.IR tk (2)
|
