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.

Titlebar creates a collection of Tk widgets on Screen scr, rooted at .Wm_t, using the Tk geometry specification given in where. 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.

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 background. Unhide can be called from another process in the same application to unblock the process executing titlectl, 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.

titlec := wmlib->titlebar(t, "My Program", Appl);
alt{
s := <-titlec =>
wmlib->titlectl(t, s);
}

Geom returns a string with the coordinates for a child window.

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 widget, 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 dialog 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 newline, and then returns the typed string, without the newline.

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 indexed by dflt. Mktabs returns a Tk event channel. Messages 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 channel. 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

Museum