NAME

	omero, Ocp – Plan B portable window system

SYNOPSIS

	omero [ –A ] [ –dDCFLBMTS ] [ –n addr ] [ –p ] [ –V volspec ] [ –t mouseaddr [ initprog ] Ocp from to

DESCRIPTION

Omero is the Plan B window system and the Graphical User Interface resource volume, as described in omero(1). It services a tree of files (i.e., a volume) to implement a Plan B GUI service. Upon starting, it runs ox(1) to permit the user to edit, execute commands and browse the system. Besides, the script initprog is executed if given as a parameter. Most users use /bin/owins as the omero startup script. By default, omero listens for clients (authenticating them) at tcp!*!11007. Options –A, –n, and –V can change this behaviour and are like those of other Plan B volume servers. See planb(4) for a description. Uppercase options are used for debugging and may lead to very verbose executions. Omero provides GUI components known as panels, like rows, columns, buttons, sliders, and others described below. Each panel is represented by a directory that contains a ctl, a data, and a lck file. Panels can be created and deleted by making and removing such directories. Besides the three files mentioned above, rows and columns have one extra subdirectory for each one of the panels they contain. The order of the files contained in a directory is representative and corresponds to the order used to show their panels in the screen, which is usually the order of their creation. The order in the screen is left to right for rows and top to down for columns. The file system can be used to move, copy (i.e replicate), and delete graphical items serviced by omero. Ocp is a script that copies omero panels from a directory to another in response to user mouse commands. The applications affected are usually unaware of this if they are using omero(2). The name of a directory determines the type of panel it represents. A name is of the form type:name (eg. text:ox.3442) where type is any of row, col, image, text, label, button, tag, gauge, slider, page, and draw. Usually, name is a string randomized by the application to permit any two names to cohexist within the same directory (i.e., within the same container panel). Omero uses the file /dev/snarf as the clipboard, to put there the bytes when a cut operation snarfs them. The file /dev/sel is updated by omero with the file system path for the last text panel where some text was selected. This is a helper for executing commands that operate on selected text. Panel Files Panel directories contain a data and a ctl file. The data file contains a portable representation of the graphical panel, text for text elements and Plan 9 images for images. The ctl file contains a textual representation of the panel attributes. Some attributes are common to all panels and are described later. The textual representation for an attribute may be issued as a control request by writing it to the control file. Both files are complete descriptions (i.e. they are not streams), which means that tools like tar(1) can be used to copy a hierarchy of panels from one place to another (maybe at different machines), and the resulting GUI would be similar. If the application is using omero(2), it would properly handle all the copies of its interface. Panel directories also contain a lck file used to synchronize multiple processes that operate on the same set of panels. An open of this file is refused if the panel (or any of its containers up to the root) is on hold. Opening the file puts the file on hold until the file is closed. Programs that want to gain a coarse lock on a panel must keep this file open during the locked operation. This is done by Ocp while a panel is being copied, and by most omero programs while creating and removing panels. Omero uses this mechanism also to synchronize a move operation performed using the mouse. Deletions using the mouse are always obeyed. If the open of lck fails, the expected behaviour is to retry several times for a few seconds at most. Therefore, the lock should not be kept for a long time. Panels What follows documents the list of panels along with the format of their data files and their specific control requests. Attributes and control requests common to all panels are described later. Image panels hold Plan 9 images as data. The size of the panel is that of the image. Its ctl file contains size nx ny besides other attributes, to report the size of the image measured in pixels. Page is like image but grows depending on available space and allows mouse interaction to see images bigger than the space available. Text is a text panel that permits edition. The contents of the data file is the text being edited. See omero(1), and ox(1) for a description of the user interface. Its ctl file contains size nx ny sel s0 s1 mark n besides other attributes. Size is like before, but measured (approximately) in characters. The sel attribute shows the current selection start and end position. The mark attribute keps a relative position that is maintained by omero despite text edition. This is used primarily by ox(1), to keep track of the output insertion point for the panel. Besides the requests that can be made for these attributes text panels understand other control requests: search text to search for the given text. If it has more than one line, this request must be the only one being sent to the control file. If the request is made using panelctl as described in graph(2), the search is performed on all replicas of the panel, which is not wise. Updating the control file of just one replica is usually the right thing to do. The same happens to the following requests. look arg to look for arg like when the user uses the mouse to look for it on the panel. exec arg is similar, but mimics a user request to execute the given string instead. undoto undo the last editing. redoto redo the last undone operation. cut   to cut the selection. paste to paste the contents of /dev/snarf replacing the current selection. ins arg to insert text. The argument is a string with the insertion offset, the number of runes, and the runes to insert. This operation and the next are usually performed on all the replicas by means of panelctl(2). del arg to delete text. The argument is a string with the deletion offset and the number of runes to delete. scroll to put the panel in scroll mode. The last position copied to the panel is always shown. Tag is an editable single–line text panel. Label is a read–only fixed–size tag. By default, the text of the label matches its name (without the type prefix). The data file can be used to change this. Button is a label that sends execution events for both look and execute requests (mouse buttons 2 and 3). Gauge shows a numeric value between 0 and 100 using a graphical representation of a gauge. Slider is a gauge than can be adjusted by the user using the left button. Draw is a graphical panel for vector graphics. It draws the commands contained in its data file. Currently, draw knows the following commands: ellipse cx cy rx ry [col] rect x0 y0 x1 y1 col line x0 y0 x1 y1 n col They are similar to those in draw(2). The control file reports the size as in images. Attributes and control requests The following attributes are common among panels and can be found in their ctl files, or changed by a write to them: tag   activates a tag for the panel. notag deactivates it. hidehides the panel, showundoes this. dirty flags the panel as dirty (unsaved changes). clean does the opposite. font F changes the font to F. The argument can be T for teletype font, R for variable width (e.g. roman), B for bold–face, S for small, and L for large. There is no way to select a particular font; this is not a bug, but a feature. holdrequests omero to ignore changes within the panel with respect to screen layout. The panel (and inner ones) are held until the control file is closed. This is useful to ask for several requests while trying to avoid unnecessary resizes in the middle. addr netaddr tells omero that the application in charge of a panel can be reached at netaddr and asks for any further event to be sent to such address. Events are textual and consist of the path for the affected panel, the event name, an optional argument and the ASCII 001 character. The omero(2) library is usually in charge of handling events in the application side. min   Minimizes the panel (only for rows and columns). This sets the number of non–hidden inner panels to one. nomin undoes the effect of the previous request. Events Panels can be programmed (via their ctl files) with the network address of their application. Omero sends relevant interface events to the address of the application associated to each panel. Events are separated by the ASCII 001, to permit multi–line events. Each event has the path (in the file system) of the panel generating it, the name of the event (a string), and a optional string argument. Omero can send any of the following events: look arg the user is looking for arg. For example, the user did click the right mouse button in the panel. The argument has a number printed with %11d with the length of the look string, and the string itself. click arg There was a mouse event. The argument is the mouse event in the format of mouse(3). keys arg The keys corresponding to the runes in arg were pressed. interrupt The interrupt key (Delete) was pressed. exec arg The user is requesting to run arg. The argument has the same format used for look. args arg The user is requesting to run arg using the contents of the current selection as an argument. To locate the current selection, omero places in /dev/sel the path of the last panel where text was selected. Its ctl and data files can be used to retrieve the selected string. The event argument has the same format used for look. data arg The data associated with the panel (eg., the value of a slider) was changed. For gauges and sliders, the value follows. ins arg Text (as shown in the argument) has been inserted in a text panel. The argument contains the position, number of runes, and the text itself. del arg Text has been deleted from the text panel. The argument is like before. addr arg The panel has been created within the given volume. The argument names the volume. The application uses this event to track down which interfaces it has and where are them. Usually, by means of omero(2). path arg The panel has been moved to a new path. The argument is the new path name. dirty The user edited the panel using the mouse/keyboard interface. exitThe panel is terminated (perhaps by using the Del command through the user interface). When using omero(2), the application is notified when the last replica of the panel exits.

SOURCE

	/sys/src/cmd/omero

SEE ALSO

	omero(1), ox(1), and omero(2).

BUGS

	There is no way to replicate a panel within the a single container, there may be only one file with a given name. Besides, this service is young, there may be some other bugs. All the comunication is plain text and thus can be eavesdropped. Some support for encryption should be added.

Copyright © 2008 Lucent Technologies. All rights reserved.