.TH OMERO 2 .SH NAME createpanel, createsubpanel, panelpath, openpanel, openpanelctl, closepanel, closepanelctl, seekpanel, readpanel, dirstatpanel, readallpanel, writepanel, readpanelctl, writepanelctl, omeroterm, omeroeventchan, clearoev, removepanel, panelctl, plumbexec, plumblook, evhistory, createport, createportproc \- Omero graphical user interface library .SH SYNOPSIS .B #include .br .B #include .br .B #include .br .B #include .PP .nf .ft L .PP .ta 11n +11n +11n +11n struct Repl{ Repl* next; // in replica list char* path; // e.g., "/n/.../row:2/slider:volume" int fd[2]; // data and ctl fds }; struct Panel{ QLock; // name is WORM, so mostly for repl. char* name; // e.g., "slider:volume" Repl* repl; // known replicas int nrepl; Channel*evc; // events here or through oeventchan(nil) ... }; .PP .B Panel* createpanel(char* name, char* type, char* omero); Panel* createsubpanel(Panel* g, char* name); char* panelpath(Panel*); int openpanel(Panel* g, int omode); int openpanelctl(Panel* g); void closepanel(Panel* g); void closepanelctl(Panel* g); vlong seekpanel(Panel*g, vlong pos, int type); long readpanel(Panel* g, void* buf, long len); Dir* dirstatpanel(Panel* g); void* readallpanel(Panel* g, long* l); long writepanel(Panel* g, void* buf, long len); long readpanelctl(Panel* g, void* buf, long len); long writepanelctl(Panel* g, void* buf, long len); void omeroterm(void); Channel* omeroeventchan(Panel* g); void clearoev(Oev* e); void removepanel(Panel* g); int panelctl(Panel* g, char* fmt, ...); .PP int plumbexec(char* dir, char* arg); int plumblook(char* dir, char* arg); void evhistory(char* prg, char* ev, char* arg); Channel* createportproc(char* port); int createport(char* name); .PP extern char*appluiaddress; extern int omerodebug; .fi .SH DESCRIPTION These functions provide a convenient application interface for using .IR omero (4) to build user interfaces for Plan B applications. The application must be programmed using .IR thread (2) if this library is used. .PP Each omero panel is represented by a .I Panel data structure, where .I Name is the file name (not the full path) for the panel in the omero file system. .I Repl is the list of of copies known for the panel. Each once is called a replica. For each replica, .I path is the absolute path for its file in omero, when it is mounted at the standard mount point .BR /devs/$sysnameui . .PP The library creates processes to service events from omero and handles replication of omero panels by itself. Different copies of the same panel are kept synchronized by the library. When the application updates a panel, the library updates all known replicas. When a panel reports a data change through event delivery, the library pulls the data, updates other replicas, and delivers the event to the application. The library handles in the same way the creation, deletion, and control operations for graphs within replicated interfaces. .PP If the omero file tree for a given replica is not mounted, the library attempts to mount it at its standard mount point when it is first seen. Regarding failure, an error at a replica causes it to be removed from the replica list and a failed operation at all the known replicas is considered to be failed. A panel is considered to be gone if all its replicas are gone. .PP The library assumes that the file name (not the path) for a given panel is unique. Events sent by omero carry the path for the panel and are used to determine which panels are affected. The name determines the graph, and the full path determines the replica. When omero reports that a panel moved, was created, or was deleted, the library updates the set of replicas. .PP .I Createpanel initializes the library, if not yet initialized, mounts .I omero if necessary, and starts an event listener. The function creates a top-level .I panel for the application with the .I name specified as an argument. The name is randomized by the function. The parameter .B type argument is usually the string .B col and determines the type of panel created. The panel is kept in hold mode and its control file is open and programed with the application address before returning to the user. See .IR omero (4) for an exhaustive list of panel types and more details about their behaviour. .PP .I Createsubpanel behaves in a similar way, but creates the named panel within the one passed as a parameter. Unlike .I createpanel this function does not set the panel in hold mode and does not open its control file. .PP .I Panelpath returns the path for the directory representing the first replica found for the panel. .PP .I Openpanel opends the data file(s) for the panel (there is one file per replica). .I Openpanelctl does the same for the control file(s). .I Closepanel and .I closepanelctl are the respective close operations. .PP While open, .IR seekpanel , .IR readpanel , and .IR writepanel can be used to seek, read, and write the panel data file. .IR Readpanelctl , and .IR writepanelctl do the same for the control file. Also, .I panelctl permits formatted output to the control file. .PP .I Dirstatpanel returns a .IR stat (2) structure (unpacked) for the data file of the first replica of the panel. .PP As a convenience, .I readallpanel returns all the contents of the data file for the panel. .PP .I Removepanel deletes a panel (i.e. all its replicas). .PP .I Omeroterm terminates any user interface created by the library and kills any process started by the library (to receive and process events). .PP .I Omeroeventchan returns a channel where events from .I omero are sent. When its parameter is nil, a global channel is returned. When the parameter is a panel, the routine initializes the panel's .I evc field with a channel where events for that panel are sent. .PP Events are represented by .I Oev structures that contain the event name, .IR ev , and event arguments, .IR arg . The .I panel and .I path to the replica generating the event are initialized before delivering the event to the user. .EX struct Oev { Panel* panel; char* path; // to repl char* ev; char* arg; }; .EE Once used, event resources are to be deallocated by calling .IR clearoev . This is important because it may lead to (already removed) panels to be destroyed. .PP When the last replica for the application's interface is known to be gone, the user routine .I omerogone is called. This routine must be provided by all applications using this library. It usually terminates the application. If the application wants to stay running and stay listening to further omero connections, it should return zero. .PP .I Plumbexec and .I plumblook are helper routines to make the user interface respond to execution and looking up requests in a similar way to .I ox (1) and other omero applications. They send .I arg to .IR portfs (4) as either .B exec or .B look requests. .PP .I Portfs ports can be created using .I createport and supplying the .I name for the port file (basename only). Instead of creating the port and servicing it by hand, .I createportproc returns a channel where .I Plumbmsg* elements are forwarded as they are obtained by a process that creates and serves the port. This is more convenient, but requires using the thread library and does not permit a fine control over the ports. .PP .I Evhistory updates the omero event history for the user. It receives the program name, the event name and its argument. .SH EXAMPLES See .IR oclock (1) for a simple example that does not require user interaction, and .IR ox (1) for a more elaborate example that includes user input. .SH SOURCE .B /sys/src/libomero .SH SEE ALSO .IR omero (4) and .IR ox (1), .SH DIAGNOSTICS These functions set .IR errstr . .SH BUGS This service is still evolving. Expect changes.