.TH PANELS 2
.SH NAME
panels \- octopus user interface panel library
.SH SYNOPSIS
.EX
include "panels.m";
panels := load Panels Panels->PATH;

Panel: adt {
	id:		int;
	name:	string;
	path:		string;
	cfd:		ref Sys->FD;
	dfd:		ref Sys->FD;
	rpid:		int;
	init:		fn(name: string): ref Panel;
	eventc:	fn(p: self ref Panel): chan of list of string;
	new:		fn(p: self ref Panel, name: string, id: int): ref Panel;
	ctl:		fn(p: self ref Panel, ctl: string): int;
	close:	fn(p: self ref Panel);
};

init:		fn();
screens:	fn(): list of string;
cols:		fn(scr: string): list of string;
copy:		fn(dfd, sfs: ref Sys->FD): int;
omero:		string;

.EE
.SH DESCRIPTION
.B Panels
is a convenience module to use
.IR omero (4)
to provide a user interface for the application. Refer to that manual
page for a description of such user interface, and to
.IR olive (1)
to see how to use omero as a user inferface.
.PP
.B Init
must be called before calling any other utility in the library, to initialize
it by loading required modules and to initialize the global
.B omero
with the path to the omero file tree, as reported by the
.B $omero
environment variable.
.PP
A
.B Panel
represents an omero panel. It corresponds to a directory in the omero
file tree. The name of the panel, and its absolute path in the current name
space are kept in the
.B name
and
.B path
fields. Applications may supply identifiers (numbers) to omero panels. The
identifier for a panel is kept in its
.B id
field. Two additional fields,
.B cfd
and
.B dfd
are available to contain descriptors to the control and data files for the panel.
They are not (in general) used by the library, such fields are a convenience for the
client program.
.PP
Before creating any panel, the application must create a directory in the
.B /appl
directory of omero. That is, an initial container panel. This panel is created by
.B Panel.init
(which should be called right after initializing the library to create an application
container with the name given in
.IR name ).
The function returns a reference to the panel. Also, it sets the application process id
to that of the caller program and the panel id to zero,
via appropriate control operations on the panel. The control file for this panel
is open (for writing)
as
.I "remove on close",
and its descriptor kept in the
.B cfd
field.
This means that when the reference to this
.B Panel
is lost, the entire application
panel hierarchy is removed by omero.
.PP
A new panel may be created by calling
.B Panel.new
on the container panel, supplying the desired panel
.I name
and
.I id
(identifier). This name is randomized by the library, to make it unique.
To remove a panel, call
.B Panel.close
on it.
.PP
In general, control and data files for the panel may be open and used by the application,
by appending
.B /ctl
or
.B /data
to
.B Panel.path
and opening the resulting file name. As a convenience,
.B Panel.ctl
writes a control operation for the panel, using
.B cfd
if non-null.
.PP
The function
.B Panel.eventc
returns a channel that can be used to receive events for a panel (and all its
inner panels). Usually, it is called once for the top-level panel. The panel identifier
contained in the omero event (or the panel path, also contained) can be used
to demultiplex the event stream. Each receive from the channel returns a list
of strings with the event arguments (already parsed): panel path, panel id,
event type, and optional argument string.
.PP
What has been said is not enough to make panels appear on a screen. Replicas
must be created on the desired location. To aid in locating an appropriate place,
.B screens
returns a list of omero screen names, and
.B cols
returns a list of column names for the given screen name.
.PP
The utility
.B copy
copies bytes from
.I sfd
to
.B dfd
until EOF. This is frequently used to update text or image panels with
other file contents, or viceversa.
.SH EXAMPLE
.PP
Initialize, and create a text panel containing
.B /NOTICE :
.EX
	panels->init();
	ui := Panel.init("xample");
	text := ui.new("text:xample", 1);
	sfd := open("/NOTICE", OREAD);
	dfd := open(text.path+"/data", OWRITE|OTRUNC);
	panels->copy(dfd, sfd);
.EE
.PP
Show the panel in the first column of the first screen:
.EX
	scr := hd panels->screens();
	col := hd panels->cols(scr);
	text.ctl(sprint("copyto %s\n", col);
.EE
.PP
Start receiving and printing events:
.EX
	c := ui.eventc();
	for(;;){
		ev := <-evc;
		if (ev == nil)
			break;
		print("path %s id %s ev %s\n", hd ev, hd tl ev, hd tl tl ev);
	}
.EE
.PP
The source of
.IR ox (1)
and
.IR oclock (1)
can be used as a more elaborate example.
.SH SOURCE
.B /usr/octopus/port/lib/panel.b
.SH SEE ALSO
.IR omero (4)
and
.IR olive (1).
.SH BUGS
Too young to be reliable.