OMERO(4)                                                 OMERO(4)

     NAME
          omero - octopus window system

     SYNOPSIS
          o/mero [ -abcdi ] [ -m mnt ]

     DESCRIPTION
          O/mero is the Octopus window system, as introduced in
          olive(1). Here we describe the file system interface.

          By default, o/mero mounts itself at /mnt/ui.  Flags -abc are
          similar to the bind(2) flags of the same name. Option -m can
          be used to select mnt as the mount point instead of the
          default /mnt/ui.  Under flag -i the standard input is used
          as a connection to the client.

          O/mero provides GUI components known as panels, like rows,
          columns, buttons, sliders, and others described below. Per-
          haps surprisingly, o/mero does not draw and does not inter-
          act with the mouse or keyboard.  O/live is a viewer for
          o/mero that does it, as said in olive(1).

          The root directory contains a directory named appl where
          applications create their panel hierarchies, one extra
          directory per screen or session, and a file named olive used
          by the viewer to receive updates from the window system and
          to send requests to it.

          Each panel is represented by a directory that contains some
          files, the most important are files named ctl, and a data.
          Panels can be created and deleted by making and removing
          such directories.  Rows and columns have one extra subdirec-
          tory for each one of the panels they contain, and do not
          contain a data file.  The file system can be used to move,
          copy (i.e. replicate), and delete panels.  The applications
          affected are usually unaware of this fact.

          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).  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).
          Type is any of the following:

          row    A container panel arranging children in a row.
          col    A container panel arranging children in a table.
          image  An image in Plan 9 format.
          text   An editable text panel.
          tbl    An editable text panel that insists on tabulating the
                 words contained.

     OMERO(4)                                                 OMERO(4)

          label  A single line (small) read-only text panel.
          button A single line (small) read-only text panel customized
                 to behave as a button.
          tag    A single line editable text panel. Usually to inform
                 the user of sibling panels and to provide a place to
                 type some text.
          gauge  A meter to show a value between 0 and 100.
          slider An editable meter to show a value between 0 and 100
                 and let the user adjust it.
          page   An image in  Plan 9 format supporting paning. To view
                 large images.
          draw   A vector graphics device. Used to draw geometrical
                 figures.

          O/mero (or rather, o/live) uses the file /dev/snarf as the
          clipboard, to put there the bytes when a cut operation
          snarfs them.  The file /mnt/snarf/sel is updated with the
          file system path for the last text panel where some text was
          selected. This does not consider tag lines and is a conve-
          nience 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 most panels 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 together later. The textual representation for an
          attribute may be issued as a control request by writing it
          to the control file of a panel. Each control request is ter-
          minated by a newline character.

          Both files are complete descriptions (i.e. they are not
          streams), which means that tools like tar(1) can be used to
          take a snapshot of a hierarchy of panels.

          Applications are expected to read, write, create, and remove
          panel files using the /mnt/ui/appl file tree. Panels found
          there are not shown by default at any screen. Instead, a
          panel can be replicated at other places under /mnt/ui by
          issuing control requests. A panel replicated at a directory
          /mnt/ui/dir has a mirror of its file tree at that directory.
          Operations made to the files at /mnt/ui/appl affect all the
          replicas (the panel itself). Operations made to the files at
          /mnt/ui/dir (ususally done by viewers) are made to that
          replica. Most of the operations also update the panel (and
          any other replicas), but some (eg., hidding the panel) do
          not.

        Attributes and control requests
          These are both attributes and control requests common to all
          panels.  Depending on the panel type, additional attributes

     OMERO(4)                                                 OMERO(4)

          and/or control requests may exist as described later.

          tag          Activates a tag for the panel.  This permits
                       using the mouse and keyboard commands described
                       in olive(1) for tags.
          notag        Ceactivates it.
          hide         Hides the panel,
          show         Makes a hidden panel visible.
          appl id pid  Sets the panel as an application panel, identi-
                       fied by id (reported back along with events for
                       the panel), handled by the process with the
                       given pid. If a pid is set to -1 the panel is
                       not associated to any process. Otherwise, an
                       interrupt request causes o/mero to try to
                       interrupt that process.
          layout       The counterpart of appl.  It flags the panel as
                       one used just for layout purposes.
          copyto dir[pos]
                       Informs of a replica of the panel (or estab-
                       lishes a new one when issued as a control
                       request). The destination dir should be an
                       absolute path starting from the o/mero root
                       directory (eg.  /mnt/ui) and showing where to
                       ``copy'' the panel.  The optional pos argument
                       is a number indicating the position for the
                       panel in the target container ( `1' for the
                       first, `2' for the second, etc.)

          The following control requests may be issued but do not cor-
          respond to panel attributes:

          moveto dir[pos]
               Is similar to copyto but it is meant only as a control
               request at a replica. It relocates the replica to a
               different path. It is equivalent of a copyto request
               followed by a close request for the original replica.

          top  Makes the panel full-screen (by zooming to it).

          pos n
               Sets the position of the panel to n in its container.

          hold Prevents o/mero from sending events notifying of
               changes to the panel (and its children) until the
               moment when the control file is closed or the next
               request is issued.

          release
               Makes o/mero release the hold on the panel (and inner
               ones).

          look what

     OMERO(4)                                                 OMERO(4)

               Causes the panel to post an event to the application to
               look for what. The argument  is terminated by a newline
               character. It may be more than a single line of text,
               and the convention is to replace ew lines within the
               argument with the SOH character (ASCII `1').

          exec cmd
               Causes the panel to post an event to the application to
               execute cmd. The argument is handled as in look regard-
               ing newline characters.

          By default, container panels have the attributes tag, show,
          and appl 0 -1; and all other panels have the attributes
          notag, show, and appl 0 -1.

        Panels
          What follows documents the list of panels along with the
          format of their data files and their specific control
          requests.

          Row and col are the two container panels. They contain the
          order
           attribute (also a control request). Its arguments are the
          names for the panels contained in the container. The order
          of the arguments corresponds to the order of the panels on
          the viewer. New panels created inside the container are
          added to the end of this attribute.

          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 content of
          the data file is the text being edited. See olive(1), for a
          description of the user interaction for this panel.  The
          following attributes and control requests are specific of
          text panels:

          dirty   Flags the panel to indicate edits not sent to the
                  application  (i.e., unsaved changes).
          clean   The opposite of dirty.
          sel n m Indicates (or sets) the selection to include runes
                  from the n-th to the m-th. When both values are the
                  same the selection is null and corresponds to the
                  insertion point for the panel.
          font F  Sets the font for the panel to F.  Where F may be

     OMERO(4)                                                 OMERO(4)

                  any of B, I, L, R S and T (bold, italics, large,
                  roman, small, and fixed-width).
          tab wid Sets the tab width to wid.
          usel    permits the panel to update /mnt/snarf/sel to record
                  the path of the panel with the last selection. This
                  is the default (but note that none of tags, tables,
                  buttons or labes update that file).
          nousel  prevents the panel from updating the last selection
                  file.
          scroll  puts the panel in scroll mode (the frame shows the
                  last text added and it keeps at most 16Kbytes of
                  text).
          noscroll
                  puts the panel in no-scroll mode (the default, keep-
                  ing all the text placed in the panel and preserving
                  the position shown by the frame despite appends of
                  new text).
          temp    prevents the panel from becoming dirty. The panel is
                  considered as scratch space.

          The following requests are understood for text panels but
          are not attributes:

          ins tag vers pos text
                  Inserts text at position pos in the panel, but only
                  the the Qid.vers for the data file matches vers. Tag
                  is a user chosen identifier sent along with any
                  insert event resulting from the control request (so
                  that the sender may identify the operation as its
                  own one).
          del tag vers pos n
                  Deletes n runes starting at position pos in the
                  text.  Tag and vers are similar to those of the ins
                  request.
          Tbl, label, tag, and button panels are similar to text.
          Gauge and slider contain in their data files a numeric value
          between 0 and 100 corresponding to a graphical representa-
          tion of a gauge.
          Draw is a graphical panel for vector graphics. The data file
          contains a textual representation of drawing commands (one
          per line).  The following commands are understood:
          ellipse cx cy rx ry[w col]
               Draws a ellipse with center (cx,cy) and rx and ry as
               radiuses. The width of the line is w and the color is
               col (which is a string naming a color; most of the typ-
               ical ones are available. See the implementation for a
               full list.)
          ellipse cx cy rx ry[col]
               is similar but draws a filled ellipse.
          line ax ay bx by[ea eb r col]
               draws a line from (ax,ay) to (bx,by).  Arguments ea and
               eb are small integers that select a line ending at the

     OMERO(4)                                                 OMERO(4)

               former and the latter point.  The width of the line is
               given by r and col selects the color for the line.
          rect ax ay bx by[col]
               Draws a rectangle with opposite corners at (ax,ay) and
               (bx,by).  Col selects the color for the lines.
          poly x0 y0 x1 y1...xn yn e0 en w col
               draws a polygon. Arguments indicate the points, E0 and
               en indicate endings, w the line width and col the
               color.
          bezspline x0 y0 x1 y1...xn yn e0 en w col
               is similar but draws a spline curve.
          fillpoly x0 y0 x1 y1...xn yn w col
               is like poly but fills the polygon.
          fillbezspline x0 y0 x1 y1...xn yn w col
               is like bezspline but fills the region delimited by the
               spline.

        Events
          Events are sent using ports(4). All events are terminated on
          a newline character (not considered part of the event data).
          By convention, newlines part of the event data are escaped
          by replacing them with ASCII `01'.  All events start with
          the string `omero:', followed by the panel id (as set using
          the appl control request) and the panel path (eg.
          /appl/draw:clock).

          The following events are sent from o/mero to the applica-
          tion, in response to user interaction or to operations on
          the file system.

               o/mero: id path look arg
               o/mero: id path exec arg
               o/mero: id path close
               o/mero: id path click buttons x y time
               o/mero: id path keys str
               o/mero: id path interrupt
               o/mero: id path clean
               o/mero: id path dirty

          Look and exec notify that the user is looking for arg or
          tries to execute arg. Close notifies that a panel is no
          longer being viewed. This event is posted when the last
          replica is closed (also when the panel files at /appl are
          removed).

          Click and keys report mouse and keyboard activity. This is
          only done for vector graphics panels. Keyboard is also
          reported for non-editable text panels.

          Interrupt notifies the application that the user wants to
          inerrupt it.

     OMERO(4)                                                 OMERO(4)

          Clean and dirty report that panel does not have  (or does)
          unsaved changes.

     SOURCE
          /usr/octopus/port/live
          /usr/octopus/port/mero

     SEE ALSO
          panels(2), olive(1), and ox(1).