OMERO(4)                                                 OMERO(4)

     NAME
          omero - Plan B portable window system

     SYNOPSIS
          omero [ -A ] [ -dDCFLBMTS ] [ -n addr ] [ -p ] [ -V volspec
          ] [ initprog ]

     DESCRIPTION
          Omero is the Plan B window system and the Graphical User
          Interface resource volume, as described in omero(1). It ser-
          vices 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 and
          a data file.  Panels can be created and deleted by making
          and removing such directories.  Besides the two files men-
          tioned 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 corre-
          sponds 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. The applica-
          tions affected are usually unaware of this if they are using
          omero(2).

          The name of a directory determines the type of panel it rep-
          resents. 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

     OMERO(4)                                                 OMERO(4)

          /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.

        Panels
          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 con-
          trol 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 simi-
          lar. If the application is using omero(2), it would properly
          handle all the copies of its interface.

          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 pan-
          els 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:

     OMERO(4)                                                 OMERO(4)

          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.

          undo to undo the last editing.

          redo to redo the last undone operation.

          cut  to cut the selection.

          paste
               to paste the contents of /dev/snarf replacing the cur-
               rent 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 per-
               formed on all the replicas by means of panelctl(2).

          del arg
               to delete text. The argument is a string with the dele-
               tion offset and the number of runes to delete.

          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 graph-
          ical representation of a gauge.

          Slider is a gauge than can be adjusted by the user using the
          left button.

     OMERO(4)                                                 OMERO(4)

          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.

          hide hides the panel,

          show undoes 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 tele-
               type 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.

          hold requests 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 use-
               ful 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.

     OMERO(4)                                                 OMERO(4)

          nomin
               undoes the effect of the previous request.

        Events
          Panels can be programmed (via their ctl files) with the net-
          work address of their application.  Omero sends relevant
          interface events to the address of the application associ-
          ated 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 argu-
               ment 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.

     OMERO(4)                                                 OMERO(4)

          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.

          exit The panel is terminated (perhaps by using the Del com-
               mand 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.