wmlib - window manager toolkit

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, name: 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;
geom:		fn(t: ref Tk->Toplevel): string;
snarfput:	fn(buf: string);
snarfget:	fn(): string;
tkquote:	fn(s: string): string;
tkcmds:		fn(top: ref Tk->Toplevel, a: array of string);
dialog:		fn(parent: ref Tk->Toplevel, ico, title, msg: 
string,
			dflt: int, labs : list of string): int;
getstring:	fn(parent: ref Tk->Toplevel, msg: string): 
string;
filename:	fn(scr: ref Draw->Screen, top: ref Tk->Toplevel,
			title: string,
			pat: list of string,
			dir: string): string;
mktabs:		fn(t: ref Tk->Toplevel, dot: string,
			tabs: array of (string, string),
			dflt: int): chan of string;
tabsctl:	fn(t: ref Tk->Toplevel,
			dot: string,
			tabs: array of (string, string),
			id: int,
			s: string): int;

Description

The Wmlib module provides routines for making and updating windows controlled by wm.

Note: The Wmlib module includes functions that were previously part of the Tklib module. Not all functions from Tklib were transferred unchanged to Wmlib. In particular, the notice() and is_err() functions no longer exist in Wmlib, and the dialog() function has a different interface.

init

init: fn();

The init function must be called once to initialize the internal state of wmlib.

titlebar

titlebar:	fn(scr: ref Draw->Screen, where, name: string,

	buts: int): (ref Tk->Toplevel, chan of string);

The titlebar function creates a collection of widgets, rooted at .Wm_t, which can be packed in the Toplevel t to create a managed title bar. The title bar consists of a label, .Wm_t.title, and the buttons specified by the bit mask buts. The .Wm_t.title label 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.

An application is informed of Tk events by a channel that is returned by titlebar. (See Tk - graphics toolkit module in Chapter 13). Messages received on it should be processed by the application. The messages that may arrive on the returned channel are:

exit The exit button was activated. The window should be closed.

ok The ok button was activated. The window should be closed.

help The help button was activated.

task The hide button was activated. The window can be hidden by sending a task request via the titlectl function.

size The resize button was pressed.

exit	The exit button was activated. The window should be closed.
ok	The ok button was activated. The window should be closed.
help	The help button was activated.
task	The hide button was activated. The window can be hidden by sending a task request via the titlectl function.
size	The resize button was pressed.

In some cases the appropriate response is to make the received message the request argument to the titlectl function.

titlectl

titlectl: fn(t: ref Tk->Toplevel, request: string);

The titlectl function performs a variety of operations according to the string passed in argument request. The supported requests are:


move and size	The titlectl function communicates with wm to obtain new position (size) parameters and relays the new configuration to Tk.
exit	The titlectl function terminates the current process and all members of its process group.
task	The titlectl function unmaps the Toplevel, makes an entry in the task bar, and suspends the current process. Later, selecting the task bar entry will remap the Toplevel and allow the process to resume.

taskbar

taskbar: fn(t: ref Tk->Toplevel, name: string): string;

The taskbar function changes the name displayed in the title bar and the window's name when it is in the task bar.

geom

geom: fn(t: ref Tk->Toplevel): string;

The geom function returns a string with the coordinates for a child window.

snarfget and snarfput

snarfput: fn(buf: string);
snarfget: fn(): string;

The snarfget and snarfput functions retrieve and replace the contents of the window manager's snarf buffer.

tkquote

tkquote: fn(s: string): string;

The tkquote function returns a string that is the same as its argument, but enclosed in curly braces and with internal curly braces escaped. The tkquote function can be used to make an arbitrary string, s, into a word suitable as an argument to a Tk function.

tkcmds

tkcmds: fn(top: ref Tk->Toplevel, cmds: array of string);

The tkcmds function executes tkcmd on all strings in the argument array, cmds, using top for the first argument of Tkcmd. It does not check for error returns.

dialog

dialog: fn(p: ref Tk->Toplevel, ico, title, msg: string, 
dflt: int,labs: list of string): int;

The dialog function pops up a dialog box near the corner of the parent top level widget, p. It displays ico, which should be a string that names an icon file in the /icons directory (or a subdirectory). The title string is displayed in the title bar of the dialog box. The message msg is displayed next to the icon. The list of string labs, is displayed as a series of buttons, labeled 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

getstring: fn(p: ref Tk->Toplevel, s: string): string;

The getstring function 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.

filename

filename:	fn(scr: ref Draw->Screen, top: ref Tk->Toplevel,
			title: string,
			pat: list of string,
			dir: string): string;

The filename function makes a dialog box for selecting a file. It is displayed on screen near parent. The dir argument gives the directory where the file search should begin. Only files that match pattern pat are displayed. The rules for defining match patterns are described in filepat - file pattern matching.

The returned string is the name of the selected file, or the empty string if no file was selected.

mktabs

mktabs:		fn(t: ref Tk->Toplevel, dot: string,
				tabs: array of (string, string),
				dflt: int): chan of string;

The mktabs function creates a pseudo tabbed notebook widget, dot, for insertion into widget t. Once created, dot can be packed like any other Tk widget. The notebook will initially display the page indexed by dflt.

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 dot and displayed.

The mktabs function returns a Tk event channel. Messages received on this channel should be passed as the s argument (a string containing the index of the new page to be displayed) to tabsctl.

tabsctl

tabsctl:	fn(t: ref Tk->Toplevel,
				dot: string,
				tabs: array of (string, string),
				id: int,
				s: string): int;

The tabsctl function controls a tabbed notebook. The id parameter is the index of the page currently selected in the notebook. The s parameter is a string containing the index of the new page to be displayed. This is usually the information received by the channel returned from mktabs. The index of the newly selected page is returned.

Files

/chan/wm Interface with wm for the titlectl function's handling of move and size requests.

/chan/snarf Interface with wm for the snarfget and snarfput functions.

/chan/wm	Interface with wm for the titlectl function's handling of move and size requests.
/chan/snarf	Interface with wm for the snarfget and snarfput functions.