WMLIB(2) WMLIB(2)
NAME
wmlib: titlebar, titlectl, taskbar, unhide, geom, snarfput,
snarfget, tkquote, tkcmds, dialog, getstring, filename,
mktabs, tabsctl - window manager toolkit
SYNOPSIS
include "wmlib.m";
wmlib := load Wmlib Wmlib->PATH;
Resize,
Hide,
Help,
OK: con 1 << iota;
Appl: con Resize | Hide;
init: fn();
titlebar: fn(scr: ref Draw->Screen, where,
title: string, buts: int):
(ref Tk->Toplevel, chan of string);
titlectl: fn(t: ref Tk->Toplevel, request: string);
taskbar: fn(t: ref Tk->Toplevel, name: string): string;
unhide: fn();
geom: fn(t: ref Tk->Toplevel): string;
snarfput: fn(buf: string);
snarfget: fn(): string;
tkquote: fn(s: string): string;
tkcmds: fn(t: ref Tk->Toplevel, cmds: array of string);
dialog: fn(p: ref Tk->Toplevel, icon, title, msg: string,
dflt: int, labs: list of string): int;
getstring: fn(p: ref Tk->Toplevel, s: string): string;
filename: fn(scr: ref Draw->Screen, t: ref Tk->Toplevel,
title: string,
pat: list of string,
dir: string): string;
mktabs: fn(p: ref Tk->Toplevel, book: string,
tabs: array of (string, string), dflt: int):
chan of string;
tabsctl: fn(p: ref Tk->Toplevel, book: string,
tabs: array of (string, string), curid: int,
newid: string): int;
DESCRIPTION
The Wmlib module provides routines for making and updating
windows controlled by wm(1).
Init should be called once to initialize the internal state
of wmlib.
Page 1 Plan 9 (printed 12/21/24)
WMLIB(2) WMLIB(2)
Titlebar creates a collection of Tk widgets on Screen scr,
rooted at .Wm_t, using the Tk geometry specification given
in where. Additionally where may also contain other required
characteristics (such as a font specification) by simply
adding them to any geometry specification. The widgets have
been packed in the Toplevel returned by titlebar to create a
managed titlebar. The title bar consists of a label,
.Wm_t.title, and the buttons specified by the bit mask buts.
.Wm_t.title is initialized with the string title, and can be
reconfigured to change the title of the window. An exit
button is always created in the title bar; the buttons
defined by the constants Resize, Hide, Help, and OK are
optional. Most applications should use the buttons defined
by the constant Appl, which is Resize|Hide.
A tk(2) event channel is returned by titlebar. Messages
received on it should be processed by the application or
passed to the titlectl function. The messages include
exit The window should be closed. Titlectl will terminate
the current process and all members of its process
group.
ok The OK button was activated. The window should be
closed.
help The Help button was activated.
task The Hide button was activated. Titlectl will unmap the
Toplevel, make an entry in the task bar, and suspend
the current process. Selecting the task bar entry will
remap the Toplevel and allow the process to resume.
The simplest well-behaved wm (1) client will therefore con-
tain:
(t, titlec) := wmlib->titlebar(ctxt.screen, "", "My Program", Wmlib->Appl);
# ...
for(;;){
alt{
s := <-titlec =>
wmlib->titlectl(t, s);
# handle any other channels
}
}
An application can assign a separate process to handle
titlectl, so that only that process will block on Hide,
allowing the rest of the application to proceed in the back-
ground. Unhide can be called from another process in the
same application to unblock the process executing titlectl,
Page 2 Plan 9 (printed 12/21/24)
WMLIB(2) WMLIB(2)
and remap the Toplevel as if by selecting the taskbar entry.
Taskbar changes the name displayed in the title bar and the
window's name when it is in the task bar.
Geom returns a string with the coordinates for a child win-
dow.
Snarfget and snarfput retrieve and replace the contents of
the window manager's snarf buffer.
The remaining functions build on the Tk module to provide
some common user interface functions.
Filename makes a dialog panel for selecting a file. It is
displayed on screen near parent. Dir gives the directory
where the file search should begin. Only files that match
pat are displayed. The returned string is the name of the
selected file, or the empty string if no file was selected.
Tkquote returns a string that is the same as its arguments,
but enclosed in curly braces and with internal curly braces
escaped. This can be used to make an arbitrary string into
a word suitable as an argument to a Tk function.
Tkcmds executes tkcmd on all strings in the argument array,
using top for the first argument of Tkcmd. It does not
check for error returns.
Dialog pops up a dialog box, with the given title and an
optional icon, near the corner of the parent top level wid-
get, p. It displays the given msg and a number of buttons,
labelled with the strings in labs. The dialog box waits for
the user to push a button, and then returns the index of the
button pushed (the first element of labs is index 0). If
the user types a newline, the dflt value is returned. The
button with the dflt index is specially outlined in the dia-
log box.
Getstring pops up a dialog box near the corner of the parent
top level widget, p. The box contains the msg and an entry
widget. It waits for the user to type a string and a new-
line, and then returns the typed string, without the new-
line.
Mktabs creates a tabbed notebook pseudo widget, book, for
insertion into widget p. Once created, book can be packed
like any other Tk widget. Information for specific tab
pages is contained in the tabs array. For each page, tabs
contains the name displayed in the tab and a Tk widget name.
Whenever a page is selected, its widget is packed in book
and displayed. The notebook will initially display the page
Page 3 Plan 9 (printed 12/21/24)
WMLIB(2) WMLIB(2)
indexed by dflt. Mktabs returns a Tk event channel. Mes-
sages received on this channel should be passed as the newid
argument to tabsctl.
Tabsctl controls a tabbed notebook. Curid is the index of
the page currently selected in the notebook. Newid is a
string containing the index of the new page to be displayed;
this is usually the information received on the tabs chan-
nel. The index of the newly selected page is returned.
FILES
/chan/snarf snarf buffer maintained by wm(1)
/chan/wm channel for interaction with wm(1)
SOURCE
/appl/lib/wmlib.b
SEE ALSO
draw-context(2), tk(2)
Page 4 Plan 9 (printed 12/21/24)