
@(#)Layouts.readme

Copyright: Yokogawa. All rights reserved.
YOKOGAWA PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

Author:    C. Horevoorts

----------------------------------------------------------------------------
Changes ....
----------------------------------------------------------------------------
Who When    Change  What
----------------------------------------------------------------------------
HVS Mar-05  e9435   First version documented
HVS Jan-09  i10158  Allow printing in inverted mode
HVS Feb-09  e10100  Add debugActivationKey
HVS Nar-09  i10175  Implement shell command
HVS Apr-09  i10192  Allow printing in additional modes
HVS Jun-09  e10100  Web-HMI Phase 2
HVS Jan-11  e10362  Playback
HVS Apr-14  i11026  Correct <tab> usage
HVS Jul-15  e10910  Add sub-menu
HMN Aug-15  e11351  Add toggleSize action
HVS Feb-18  e11928  Add passing parameters values to display activation from menu or toolbar
HVS Mar-18  e11944  Add possibility to place new frame at coordinates of current or specific screen

Layout definition
=================

The layouts.xml file describes the layout of a Web-HMI operator window.
Multiple layouts can be described in this file. A layout is defined as
follows:

<layouts
  layouts options>

  <layout
    layout options>

    <menu>
      menu definition
    </menu>

    <toolbar>
      toolbar definition
    </toolbar>

    <frame-set
      frame set options>
      frame definition
    </frame-set>
  </layout>

  <layout.../>...

  <translations
    translation options>

  <translations.../>...

</layouts>

The menu defines the layout and functions of the menu at the top of the
window defined by the layout. The toolbar defines the layout and functions
of toolbar that appears below the menu. The frame-set defines that frames
that appear in the remainder of the window.

+----------------------------------------------------------------+
| Window heading                                              _OX|
+----------------------------------------------------------------+
| Menu area                                                      |
+----------------------------------------------------------------+
| Toolbar area                                                   |
+----------------------------------------------------------------+
|                                                                |
| Frame area                                                     |
|                                                                |
|                                                                |
|                                                                |
|                                                                |
|                                                                |
|                                                                |
|                                                                |
|                                                                |
|                                                                |
+----------------------------------------------------------------+
| Status line                                                    |
+----------------------------------------------------------------+

The menu and toolbar definitions are optional. The frame set is required.

Layouts options
---------------

debugActivationKey
The name of a key ([<modifier>..] <key_name>) that opens the display
debugger window.
<key_name> can be any letter or HOME, END, PAGE_UP, PAGE_DOWN, UP, DOWN, LEFT,
RIGHT, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, INSERT.
<modifier> can be CONTROL, SHIFT, ALT.
For example: "CONTROL SHIFT F6"


Layout options
---------------

name
The name of the layout. An operator can have a layout assigned. This
layout is activated when the operator logs-in. In addition the
'Activate display' control in a display can specify a layout to activate
the display in.

title
The title that appears in the window heading. This is only true when border
is set to true. If the title is $<frame_name> then
the title of the display active in the frame <frame_name> will be used
as window title.

drawBorder
If true the window border and window heading are drawn.

sizingAllowed
If true then the operator is allowed to resize or maximize the window.

minimizingAllowed
If true then the operator is allowed to minimize the window.

closingAllowed
If true then the operator is allowed to close the window.

alwaysOnTop
If true the window will always be the top window on the desktop.

modal
If true the layout will be modal if other layouts ar active.

lookAndFeel
Sets the look and feel. Must be a Java look and feel class like
com.sun.java.swing.plaf.windows.WindowsLookAndFeel.

initialPosition
Specifies the default position of the window when it appears:
pixels - the window will be positioned at the position specified by
         initialPositionX and initialPositionY of the desktop.
         This is the same as pixelsDesktop.
pixelsDesktop - the window will be positioned at the position specified by
                initialPositionX and initialPositionYof the desktop.
                This is the same as pixels.
pixelsCurrentScreen - the window will be positioned at the position of the current screen specified by
                      initialPositionX and initialPositionY of
pixelsScreen - the window will be positioned at the position of the primary screen specified by
               initialPositionX and initialPositionY of
pixelsScreen1 - the window will be positioned at the position of the first screen specified by
         initialPositionX and initialPositionY.
pixelsScreen2 - the window will be positioned at the position of the second screen specified by
                initialPositionX and initialPositionY.
pixelsScreen<n> - the window will be positioned at the position of the <n>-the screen specified by
                  initialPositionX and initialPositionY.
centreCurrentScreen - the window will be positioned around the centre of the current screen.
centreScreen - the window will be positioned around the centre of the primary screen.
centreScreen1 - the window will be positioned around the centre of the first screen.
centreScreen2 - the window will be positioned around the centre of the seconds screen.
centreScreen<n> - the window will be positioned around the centre of the <n>-the screen.
centreDesktop - the window will be positioned around the centre of the desktop. In case of a
                multiple screen environment the virtual desktop is used.
centreLayout - the window will be positioned around the centre of the parent layout.
centreFrame - the window will be positioned around the centre of the parent frame.
atCursor - the window will be positioned right down at the current cursor position.
awayFromCursor - the window will be positioned as far away as possible from the current cursor position.

initialPositionX
Specifies the X position of the window if initialPosition is pixels, pixelsDesktop, pixelsCurrentScreen or pixelsScreen else
it is ignored.

initialPositionY
Specifies the Y position of the window if initialPosition is pixels, pixelsDesktop, pixelsCurrentScreen or pixelsScreen else
it is ignored.

initialSize
Specifies the default size of the window when it appears:
pixels - the window size is specified by initialSizeWidth and initialSizeHeight.
screenSize - the window size will be the size of the screen.
desktopSize - the window size will be the size of the desktop. In case of a
              multiple screen environment the virtual desktop is used.
fitFrames - the window is wrapped around the size of the defined frames.

initialSizeWidth
Specifies the width of the window if initialSize is pixels else
it is ignored.

initialSizeHeight
Specifies the height of the window if initialSize is pixels else
it is ignored.

maximumOpen
Specifies the maximum number of open instances of the layout. Default is 1.

printOrientation
Specifies the print orientation:
landscape - landscape orientation
portrait - portrait orientation
Default is landscape.

printLeftMargin
Specifies the left printing margin in mm.

printRightMargin
Specifies the right printing margin in mm.

printTopMargin
Specifies the top printing margin in mm.

printBottomMargin
Specifies the bottom printing margin in mm.

Menu definition
===============

Only one menu can be defined. The menu is defined as follows:

<menu>
  <menu-item
    menu item options>
      <menu-item
        menu item options>
      </menu item>
      <menu-item
        type = "sub"
        menu item options>
        <menu-item
          menu item options>
        </menu item>
      ...
      <menu-separator/>
      ...
  </menu item>
  ...
      <menu-separator/>
      ...
  </menu item>
  ...
</menu>

The maximum level of menu nesting is two. A menu item specifies the layout and
associated command of a menu entry. A menu separator specifies a separator
between two menu items and may only appear in the nested menus.

menu item options
-----------------

name
The name of the menu item.

label
The label of the menu.

icon
The name of the icon file. Icons can be found at http://www.trash.net/~ffischer/admin/icons/

type
The menu entry type. Can be one of:
normal - normal menu entry (default)
radio - radio button
check - check button
sub - start of a sub menu

mnemonic
The mnemonic character in the menu.

accelerator
The accelerator key ([<modifier>..] <key_name>) for the menu:
<key_name> can be any letter or HOME, END, PAGE_UP, PAGE_DOWN, UP, DOWN, LEFT,
RIGHT, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, INSERT.
<modifier> can be CONTROL, SHIFT, ALT.
For example: "CONTROL F1"

tooltip
The tooltip text. A $ sign in the tooltip text will be replaced by a text depending
the command (see next).

command
The command to be executed. One of:
exit - close the window.
print <what> [inverted|grayInverted|lightnessInverted] - print to the default system printer.
  <what> can be:
    frameWithSetup - print the selected frame after viewing the setup dialog.
    frame - print the selected frame without viewing the setup dialog.
    preview - shows the preview dialog.
    setup - shows the setup dialog.
    selectFrame - allows to select a frame for printing.
    If inverted is specified then all colors are inverted before printing
    If grayInverted is specified then all gray colors are inverted before printing
    If lightnessInverted is specified then lightness is inverted whilst maintaining the same hue and saturation.
help - activate the help.
navigate <direction> <frame_name> <display_name> <zoom> [<parameters>] - navigate through displays.
  <direction> specifies the navigation direction:
    back - navigates back in the specified frame. A $ sign in the tooltip text will
           be replaced by the back display name.
    backList - navigates backwards showing the history list in the specified frame.
    forward - navigates forward in the specified frame. A $ sign in the tooltip text
              will be replaced by the forward display name.
    forwardList - navigates forward showing the history list in the specified frame.
    up - navigates up in the specified frame.
    home - navigates home in the specified frame. A $ sign in the tooltip text
           will be replaced by the home display name.
    to - activates the specified display in the specified frame.
    history - shows a combobox with all the displays shows before in the specified frame.
  <frame_name> specifies the name of the frame to navigate in.
  <display_name> specifies the name of the display to be activated if the
    direction is "to".
  <zoom> specifies the initial zooming:
    asIs = the display is shown using the size as created (this is the default)
    fitDisplay = the display is fit into the frame remaining the aspect ratio.
    stretchDisplay = the display is fit into the frame without remaining the aspect ratio.
    <number>% = zoom value
  <parameters> specifies the values to be passed to external parameters of the display to activate.
               Will be used when <direction> is "to".
               The parameters are specified as <parameter name>=<value>[;<parameter name>=<value>]...
               Example:
                  Pipeline=MainLine;Station=Houston;Inlet=Valinta;Count=12
shell <where> <os_command> - Executes the specified os command.
  <where> specifies the location to execute the command and is one of:
    client - executes the command on the client.
    server - executes the command on the server.
  <os_command> specifies the command to execute. The command may not contain spaces.
zooom <level> <frame_name> - zoom in the display.
  <level> specifies the zoom level. A number between 0 and 10 specifies an
    absolute zoom level where the value of 1 means original size, 2 means
    a double size, 0.5 means halve size and 0 means fit into frame. 
    Values between 10 and 1000 mean a relative zoom size in % where
    100 means no change and 200 means zoom in twice.
  <frame_name> specified the name of the frame where zooming occurs.
lookfeel <look&feel> - Switch to a look&feel.
  <look&feel> specifies the look and feel and is one of:
    Java look and feel classes like:
      com.sun.java.swing.plaf.windows.WindowsLookAndFeel
    or
      lookfeel javax.swing.plaf.metal.MetalLookAndFeel
toolbar <state> - shows/hides the toolbar.
  <state> can be:
    true - show the toolbar
    false - hide the toolbar
login - secondary login.
logout - secondary logout.
playback <mode> - Access to the playback functionality.
  <mode> is one of:
    record - toggles recording on or off
    view - opens the viewer or moves the viewer to the top if the viewer is already open.
toggleSize <size> - Toggles between initial size and position and provided size and position.
   <size> is one of:
     "fullScreen [screenNr]" - will switch to fullscreen. screenNr is optional.
                                if layout is 'alwaysOnTop', then whole visible area will be used, 
                                else taskbar stays visible.
                                screenNr 0 expands across all screens.
                                screenNr 1+ to select specific screen.
     "<x>,<y>,<width>x<height>" - will switch to provided size and location. 

Toolbar definition
==================

More toolbars can be defined. The toolbar is defined as follows:

<toolbar
  toolbar options>
  <toolbar-item
    toolbar item options/>
  ...
  <toolbar-separator/>
  ...
</toolbar>


A toolbar item specifies the layout and associated command of a toolbar button.
A toolbar separator specifies a separator between two toolbar items.

toolbar options
---------------

name
The name of the toolbar.

label
The label of the toolbar, appears when the toolbar floats.

floatable
If true then the toolbar is floatable. Default is true

position
The position of the toolbar, default position is top:
top - top of the layout.
bottom - bottom of the layout.
left - left side of the layout.
right - right side of the layout.

toolbar item options
--------------------

name
The name of the toolbar item.

label
The label of the button. Optional.

icon
The name of the icon file. Required for the normal type (see type).

type
The toolbar entry type. Can be one of:
normal - normal toolbar button (default)
combo - combo box
editableCombo - editable combo box
dropdownList - a normal toolbar button with a dropdown list

tooltip
The tooltip text

command
The command to be executed (see menu item command).


Status line definition
======================

The status line is defined as follows:

<status-line>
  <status-line-item
    status line item options/>
  ...
  <status-line-separator/>
  ...
</status-line>

A status line item specifies the layout of a status line field.
A status line separator specifies a separator between two status line items.

status line item options
------------------------

name
The name of the status line item

type
The status line entry type. Can be one of:
statusText - In this field the status is displayed.
userName - The user name is displayed.
progresBar - In this field the progress bar is displayed.
graphicsQueueLevel - In this field the level of the graphics queue is displayed.
connectionState - In this field the connection state is displayed.

icon
The name of the icon file for the connection state. The name is appended with:
_v - for the good server connection indication.
_x - for the bad server connection indication.
_s - for a bad server.

tooltip
The tooltip text


Frame definition
================

The frames are defined as follows:

<frame-set
  frame set options>
  <frame
    frame options/>
  ...
  <frame-set
    frame set options>
    <tab
     tab options>
     <frame
      frame options/>
     ...
    </tab>
    <frame
      frame options>
    </frame>
    ...
  </frame-set>
  ...
</frame-set>

Frames can be nested unlimited. The frame mechanism is described in
http://www.w3.org/TR/REC-html40/present/frames.html.
The options supported are described here.

frame-set options
-----------------

cols
The frame is divided into the number of columns specified as
<column_width>[, <column_width>]...
<column_width> can be an absolute width in pixels or a fraction of the width
left over. For example "2*, 100, 3*" defines three columns. The middle has a
width of 100 pixels. When there are 500 pixels left then the first columns
takes 200 pixels and the last column 300 pixels. A value of "fitDisplay" will
make the width to match the width of the display shown in the related frame.

rows
The frame is divided into the number of rows specified as
<row_heigth>[, <row_heigth>]...
<row_heigth> can be an absolute width in pixels or a fraction of the height
left over. A value of "fitDisplay" will
make the height to match the height of the display shown in the related frame.

Note that only one of cols, rows or tabs can be specified.

borderStyle
Specifies the border of the frame or frame-set:
none - no border is drawn
line - a simple line is drawn
raisedEtched -
loweredEtched -
raisedBevel -
loweredBevel -

frame options
-------------

name
The name of the frame.

scrollingAllowed
If true then the display in the frame can be panned.

zoomingAllowed
If true then the display in the frame can be zoomed.

initialDisplay
The name of the display that is initially shown in the fame. This display
becomes the 'home' display.

stackSize
Specifies the number of displays that can be stacked for the Back and Forward navigation
functions

borderStyle
Specifies the border of the frame or frame-set:
none - no border is drawn
line - a simple line is drawn
raisedEtched -
loweredEtched -
raisedBevel -
loweredBevel -

zoom
Specifies the initial zooming of the display:
fitdisplay = the display is fit into the frame remaining the aspect ratio.
stretchdisplay = the display is fit into the frame without remaining the aspect ratio.
<number>% = zoom value

minimumTabLabelWidth
The minimum length of a tab label.

tabButtonGap
The space between the tab label and the close button.

tab Options
-----------

tabPosition
top -
bottom -
left -
right -

maximumTabs
Specifies the maximum number of tabs that can be opened.

The <Tab> element can also provide defaults for the embedded Frames. Default options are:
stacksize 
name 
zoomingAllowed 
scrollingAllowed 
closeTabAllowed 
borderStyle 

Embedded Frames have an extra option 'closeTabAllowed'


Translation definitions
=======================

For localization purposes more translation table can be added to the layouts.

<translations
  translations options/>..

Translation options
-------------------

name
The name of the locale for which this translation contains the translations. For example "nl_NL".

The name option is followed be the list of translations for the locale specified by the name option.
Each translation contains a key/value pair where the key is the name of the menu item, status bar item, etc.
followed by .<option name> where option name is one of the options of the menu item for example.
The value contains the text to be used for the option.
