NAME
|
panels – o/mero panel library |
SYNOPSIS
|
#include <u.h> #include <libc.h> #include <thread.h> #include <panel.h> typedef struct Panel Panel; typedef struct Pev Pev; struct Panel {
enum {
struct Pev {
void pclose(Panel* p); int cols(char* scr, char** v, int nv); long pdata(Panel* p, void* data, long cnt); Panel* pnew(Panel* p, char* name, int id); Panel* pnewnamed(Panel* p, char* name, int id); int pctl(Panel* p, char* fmt, ...); Channel* pevc(Panel* p); void pevfree(Pev* ev); char* pevname(int evid); Panel* pinit(char* type, char* name); int screens(char**v, int nv); char* userscreen(void); int oxctl(char* c); extern char* omero; |
DESCRIPTION
|
Panel is a convenience module to implement user interfaces for
the o/mero window system. This window system is implemented for
the Octopus but can be used from Plan 9 as well. These pages from
the Octopus User's manual are relevant: olive(1) for an introduction
to the window system, omero(4) for a description
of the file system interface, and ports(4) for a description of
the file system used to receive events for the panels created
by the application. A Panel represents an o/mero panel. It corresponds to a directory in the o/mero file tree. The name of the panel, and its absolute path in the current name space are kept in Panel.name and Panel.path respectively. Applications may give identifiers (numbers) to omero panels. The identifier for a panel is kept in its Panel.id. Before using the library pinit but be called at least once, to initialize it and to create an initial panel. After this call, the global omero keeps the path to the omero file tree, as reported by the $omero environment variable. Pinit creates a directory in the /appl directory of omero to represent a top–level panel for the application. The name argument is used to name the panel (usually the program name) by appending the PID of the caller. The type argument must be a valid panel type, e.g., row, draw, etc. Pinit sets the panel application process id to that of the caller process and the panel id to zero. Also, it ensures that when the panel is closed the hierarchy it contains be removed. It is allowed to create multiple top–level panels if necessary. A new panel may be created within panel p by calling pnew with an appropriate name and id. The name given is randomized by the library, to make it unique and avoid conflicts in the file system. Pnewnamed is like pnew but it does not randomize the name. Note that unlike in pinit the name supplied must be a legal o/mero panel name. This means that it must include the prefix specifying the panel type. See omero(4) for a reference. Pclose removes a panel and releases the memory holding the Panel structure. If events have been requested for the panel, the file representing the events port is also removed. Note that closing a panel would remove all the file tree rooted at the panel. Sometimes it is useful to create a Panel structure for an panel that already exists in o/mero. To permit this, both pinit and pnew consider that when their name arguments are absolute paths to the panel, the panel already exists. In this case a Panel structure is built for the panel and returned, after checking out that the panel indeed exists. Control and data files for a panel may be open and used by the application, by opening the files named ctl and data in the directory named by the path field of the panel. Pctl issues a control request to the panel. It admits formatted output similar to print(2). Pdata updates the contents of the panel with those in data and returns the number of bytes written or –1 upon errors. Pevc returns a channel that can be used to receive events for a panel p and all its inner panels. Most of the times this function is called once for the top–level panel returned by pinit. The panel identifier contained in the omero event (or the panel path, also contained) can be used to demultiplex the event stream and locate the panel for an event. Each receive from the event channel returns a pointer to a Pev structure kept in malloc memory. The receiver is responsible for releasing this memory by calling pevfree with the pointer received. A panel event contains a path with the absolute path for the panel, an id with the id for the panel (or 0 if the identifier was not set in the panel by the application), an integer ev identifying the event type, and perhaps a single argument kept at arg. The event types are described by the constants shown in the synopsis. See omero(4) for a full description. The function pevname may be used to obtain a string for each event type. To make panels appear on a screen, replicas must be created at the desired location. To aid in locating an appropriate place, screens returns a list of o/mero screen names, and cols returns a list of paths for columns at the given screen name. Userscreen returns the name of the last screen used, as reported by /dev/sel. The string is allocated using malloc(2) and must be free by the caller.
Oxctl executes the given argument as a control request in one
of the Ox panels. This is useful to post Look or Exec events to
make Ox open files or execute commands. |
EXAMPLE
|
The source for oclock(1) is a simple example. It can be found
at /sys/src/cmd/o/clock.c |
SOURCE
|
/sys/src/libpanel |
SEE ALSO
|
olive(1), omero(4), and ports(4) in the Octopus User's Manual. |