Oregano2 GUI Design

Document Information
Security	Public
Projects	Oregano2
Author(s)	John Ballance (based on Oregan documentation)
Version	$Revision: 1.2 $
Copyright	This document is Copyright (C) 2001 Castle Technology Ltd and Oregan Networks Ltd
Status	First Release

Introduction

This document describes how a designer can create a Graphical User Interface (GUI) for Oregano2. This is a straightforward activity that can be accomplished by anybody, although careful though and attention to detail is required to produce an effective and usable GUI.

Interactor GUIs are created using HTML (with some special extensions) and a simple programming language, which is all explained in this document. The special extensions are tags that use the 'GUI' namespace to separate them from other tags, so that they are easily recognisable - i.e. <GUI:Button> as opposed to <Button>.

Designing a GUI for Oregano2 comprises two activities:

Designing the structure, layout, look and feel of the GUI using HTML. This can be done with any HTML editor, or even a text editor.
Adding the interactive elements and enabling the functional parts of the GUI.

These activities are covered in the following sections.

Structure of a GUI

The structure of the GUI will determine how the user will interact with it. Which components are visible/enabled at any one time will dictate what the user can interactive with. This needs careful thought and consideration for the target audience as a badly designed GUI will frustrate users.

To define what elements (windows, toolbars, popups, etc.) are available in a GUI, a manifest file is created to describe the elements. It defines all the panes, popups, hot-keys, fixed pictures and focus style for the GUI.

The main device for user interaction is a GUI Window. These can be pane or popup windows which contain buttons, forms, graphics, links, etc. All the normal HTML items can be used in a GUI Window, with some considerations. They can also contain GUI Objects such as Buttons, Messages, TextEntrys, Throbbers and WinTitles.

Manifest File

The manifest file is an HTML file that references all the other parts of the GUI, specifies graphics files, sets global CSS Style sheets, describes key bindings, etc. It is the most important component of the GUI as without it, there is no GUI.

The manifest file can be in any location - local or remote - and can have any name, although we suggest 'Manifest.html' for simplicity.

Here is an example of a manifest file:

<HTML>
<GUI:Pane Name="Toolbar" Align="Center" VAlign="Bottom" Src="toolbar.html">
<GUI:Popup Name="Error" Align="Center" VAlign="Middle" Src="error.html">
<GUI:HotKey Key="Escape" Action="Hangup()">
<BODY>
  This is a GUI manifest file.
</BODY>
</HTML>

The Oregano2-specific tags are highlighted in bold type. They can appear anywhere in the manifest file. There are several tags available for use in the manifest file:

<GUI:Pane ... >
References an HTML document to be used as a pane window - a sliding/appearing window which is usually available to the user. An example of this is the toolbar which allows you to navigate the web. It would contain 'Back', 'Forward', 'Stop', 'Reload' buttons, etc., and a place to enter a URL.
<GUI:Popup ... >
References an HTML document to be used as a popup window. This is a window that is only opened when specified by Oregano2 or when triggered by some other GUI element.
<GUI:Focus ... >
Defines the behaviour of the focussing mechanisms - the highlight box used for keyboard navigation and mouse tracking, plus the flashing cursor (or 'caret').
<GUI:Globals ... >
Declares some features which affect all parts of the GUI, such as a style sheet, etc.
<GUI:HotKey .. >
Defines a special action to be performed when a key is pressed.
<GUI: FixPic ... >
References a graphic file which is used by Oregano2 for user-interface elements such as form buttons.

If any of these tags appear anywhere else, they are ignored by Oregano2 - they must be specified in the Manifest file.

GUI Windows

The GUI Windows come in two forms - GUI:Panes and GUI:Popups.

GUI:Panes

GUI:Panes are used for devices like tool bars and status bars; they are always available to the user, although they may be 'dynamic' in that they appear when the user moves the cursor near to them.

Dynamic Panes

A GUI:Pane that is declared with a type of 'dynamic' will activate when the user moves the pointer towards them. The activation is caused by a 'hot area' on the edge of the screen which responds to the pointer entering it and opens any dynamic panes that are attached to that edge. If more than one dynamic pane is attached to a particular edge of the screen, then all of the panes open at once. This can be use to construct interesting user-interfaces.

GUI:Popups

GUI:Popups are used for dialogue with the user - they can appear anywhere on the screen, but they are not dynamic - they require invocation by either Oregano2 or another part of the GUI.

The primary difference between GUI:Pane's and GUI:Popup's is that GUI:Pane's are controlled by the user, whereas Popups are controlled by Oregano2 or some action defined on another GUI element.

Special Windows

There are some GUI Windows that Oregano2 uses in certain circumstances to request information or decisions from the user. These windows are dialogues.

There are also Options Windows which are used for modifying the configuration options.

Finally, there some Transient Windows which come and go depending on certain conditions or events.

Dialogues

There are occasions when Oregano2 will need to open a dialogue to let the user decide the course of action, or to request some urgent information from the user.

For example, if the user visits a secure site that requires HTTP Authorisation, then Oregano2 will look for, and open, a window with the name 'HTTPAuth'. This would be a window which requests the user name and password, and has 'Enter Site' and 'Cancel' buttons to control access to the site. These special windows have special names and contain GUI Objects also with special names. They are detailed below.

JSAlert

The window that is used to display JavaScript alert() messages. It must contain a <GUI:Message> with the name 'Message'.

JSConfirm

The window that is used to display JavaScript confirm() requests. It must contain a <GUI:Message> with the name 'Message'.

JSPrompt

The window that is used to display JavaScript prompt() requests.It must contain a <GUI:Message> with the name 'Message' and a text box (<INPUT Type=Text> or <GUI:TextEntry>) with the name 'Input'.

FetchError

The window that is used to display any error message from Oregano2 that is related to retrieving a web page. For example, if a web site cannot be located, Oregano2 will use this window to alert the user of that fact. It must contain a <GUI:Message> with the name 'Message'.

HTTPAuth

The window that is used to request a user name and password for HTTP Authorisation protected web sites. It must contain two <GUI:Message>s called 'host' and 'realm' for the HTTP Host and Realm of the protected site. It must also contain two text boxes (<INPUT TYPE=text> or <GUI:TextEntry ... >) that are called 'user' and 'password' which will be for the user to enter the relevant user name and password.

Options Windows

An Options Window is a window that is used to modify the users' configuration options for Oregano2. There can be any number of Options Windows in the GUI, but it is normally sensible to only have one.

An Options Window usually has a <FORM> with a 'NOSUBMIT' attribute, and many form elements that allow the user to change their options. When the Options Window is Confirm()'d, the changes in the options are recorded by Oregano2 and written back to storage.

The current values of the configuration options are entered into the window by using the 'OpenOptions()' function. The form elements and/or GUI Objects in the specified window are searched through and where a named element uses a recognised Option name, the value is set the current option value.

Valid configuration options are listed in a separate document to be publihed at a later date. Example GUI's can be used as an indication at present.

Transient Windows

At the moment, there is only one transient window - the FloatingThrobber window.

FloatingThrobber

The FloatingThrobber window is a window which will be opened when a page is being requested from the Internet. It can be used in conjunction with, or as an alternative to, the Throbber object. When Oregano2 begins to fetch a page from the internet, it will open any window called 'FloatingThrobber' (if one exists) and when all the information requested from the internet has been fetched, it will close this window again. It is not recommended to put animated images on this window as they will continue to animate (and consume resources) even when the window is not visible. This window is ideal for a simple 'Please Wait while we fetch your page' page.

Window Examples

Here is an example of a GUI that uses Panes on either side of the screen, which slide into view when the user moves the pointer near to them.

Pointer moved to the left:

Pointer moved to the right:

These panes are declared in the manifest file thus:

<GUI:Pane Name="Toolbar"  SRC="toolbar.html"  Align="Left"  VAlign="0"   Width="130" Height="100%" Type="Dynamic Duration=100">
<GUI:Pane Name="Urlbar"   SRC="urlbar.html"   Align="Left"  VAlign="80%" Width="380" Height="103"  Type="Dynamic Duration=100">
<GUI:Pane Name="Services" SRC="services.html" Align="Right" VAlign="0"   Width="130" Height="100%" Type="Dynamic Duration=100">

Notice that the 'Toolbar' and 'Urlbar' panes appear in a similar location - attached to the left hand side of the screen. At this time, Oregano2 does not support non-rectangular windows and so we use two panes that activate at the same time. This effect works because any GUI:Pane which has an ALIGN or VALIGN tag that specifies the pane is on the same edge of the screen and a type of 'dynamic' will activate at the same time. Therefore, the Toolbar and URLBar panes both open at the same time when the user moves the pointer to the left hand edge.

GUI Objects

The interactive elements of a GUI are defined by GUI Objects. There are several different types of GUI Object:

<GUI:Button ... >
A pressable/clickable button that can have multiple states - enabled/disabled, visible/invisible, checked/unchecked - and can perform complex actions when it is clicked/pressed by the user.
<GUI:Message ... >
A textual message which provides feedback to the user. The content of the message is dynamic and often provided by Oregano2.
<GUI:TextEntry ... >
A text-entry box that allows the user to enter some text and then perform an action when they press 'Enter' or 'Return'. The text in the box can be referenced by other GUI Objects.
<GUI:Indicator ... >
A non-interactive element that displays an icon or image depending on some condition. Useful for flags indicating state such as 'online' or 'secure site'.
<GUI:WinTitle ... >
A non-interactive element that can be used to change the title of a window. This is a valid operation only in desktop builds (that operate in a windowed environment, rather than full-screen).
<GUI:Throbber ... >
A non-interactive element that is activated when Oregano2 is busy fetching data over the network. There can be as many Throbbers as desired, but it is a waste of processing power to have more than necessary. See FloatingThrobber Window for an alternative mechanism.
<GUI:Union ... >
A non-interactive element that is used to combine two or more other GUI Objects in the same object. This is used to position multiple GUI Objects in the same location, when only one is visible at a time.

Many GUI Objects use an ACTION attribute to perform some actions when the object is clicked/used. They also can use a VISIBLE attribute to specify an expression which determines whether the object is visible or invisible. These actions and expressions are specified using GUIScript.

Here are some examples of uses of GUI Objects:

<GUI:Button Name="Settings" SRC="Settings.png" ACTION="OpenWindow(Settings)">

This declares a GUI:Button object which uses the 'Settings.png' image for user-interface and that opens the 'Settings' window when it is pressed.

<GUI:Button Name="Home" SRC="Home.png" ACTION="Goto(Home())"    VISIBLE="IsOnline()">

This declares a GUI:Button object which uses the Home.png image for user-interface and that navigates to the user's preferred home page when it is pressed. The button is only visible when Oregano2 is dialled-up/online.

<GUI:indicator visible="(IsSecure() | IsSemiSecure())" SRC="i/icon_padlock_tiny.png" 
               Title="You are currently viewing a secure web site">

This declares an indicator that shows a padlock image when the user is visiting secure or semi-secure sites. When the user is visiting a non-secure (normal) site, the indicator does not show.

Reference

GUI Tags

GUI Tags fall into two categories - those that are used in the Manifest file to define the structure of the GUI, and those that are used to define interactive elements in the GUI Windows.

Structural

GUI:Pane
GUI:Popup
GUI:FixPic
GUI:HotKey
GUI:Focus
GUI:Globals

Attribute	Description	Example
Name	Names the pane window for reference by Oregano2 and other GUI elements.	Toolbar
Src	The HTML document containing the contents of the pane window.	toolbar.html
Align	The horizontal alignment of the pane window on screen.	Left
VAlign	The vertical alignment of the pane window on the screen.	Middle
Width	The width of the pane window.	"100%"
Height	The height of the pane window.	"80"
Type	The type of the window, plus specifics of that type. The values currently supported here are "Static" for a static pane, and "Dynamic" for a moving pane. A dynamic pane can have further details to fully specify its behaviour which are "OpenDelay", "CloseDelay" and "Duration". These specify the time to wait before opening the window, time to wait before closing the window, and the length of time it takes to slide the window into view. They are specified like this: :"Dynamic Duration=X" where X is the time that the pane takes to slide into view, specified in 100ths of a second.	"Dynamic, Duration=100, CloseDelay=200"

Attribute	Description	Example
Name	Names the popup window for reference by Oregano2 and other GUI elements.	Question
Src	The HTML document containing the contents of the popup window.	question.html
Align	The horizontal alignment of the popup window on screen, text or percentage.	Center
VAlign	The vertical alignment of the popup window on the screen, text or percentage.	Middle
Width	The width of the popup window, in pixels or percentage.	"300"
Height	The height of the popup window, in pixels or percentage..	"300"

Attribute	Description	Example
Name	Names the popup window for reference by Oregano2. See table below	CheckBoxOn
Src	The file containing the contents of the popup window.	checkboxon.png
Width	The width of the fixed picture.	"300"
Height	The height of the fixed picture.	"300"

Name	Purpose
CheckBoxOn	A check box item that is selected.
CheckBoxOff	A check box item that is not selected.
RadioOn	A radio button that is selected.
RadioOff	A radio button that is not selected.
Menu	An indicator that clicking will produce a drop-down menu.
Bullet0	A bullet-point mark at the top level.
Bullet1	A bullet-point mark at the first level of indentation.
Bullet2	A bullet-point mark at the second level of indentation.
Bullet3	A bullet-point mark at the third level of indentation.
Downloading	A graphic to represent that the user must wait patiently because some data is busy being downloaded, whether this is a picture or an embedded object.
Broken	A graphic to represent some content that contained errors and hence could not be displayed.
UpArrow	The "up arrow" at the top of a vertical scrollbar.
DownArrow	The "down arrow" at the bottom of a vertical scrollbar.
VertThumbTop	The top of the draggable scroll bar.
VertThumb	The middle of the draggable scroll bar.
VertThumbBottom	The bottom of the draggable scroll bar.
VertScrollBar	The background of the vertical scroll bar.

Attribute	Description	Example
Key	The name of the key pressed.	Home
Action	The action to perform when this key is pressed.	Goto(Home())

Attribute	Description	Example
NormalColour	The normal colour of the focus box.	"yellow"
ClickColour	The colour to indicate that the user has clicked the item.	"orange"

Interactive

GUI:Button
GUI:Message
GUI:TextEntry
GUI:Indicator
GUI:WinTitle
GUI:Throbber
GUI:Union

Attribute	Description	Example
Name	The name of the button, for reference by other elements.	"Refresh"
Src	The URI for the image to use for the 'normal' state of the button.	"icons/ok.png"
Src_Pressed	The URI for the image to use for the 'pressed' state of the button.	"icons/ok_pressed.png"
Src_Focus	The URI for the image to use for the 'focus' state of the button.	"icons/ok_focus.png"
Src_Disabled	The URI for the image to use for the 'disabled' state of the button.	"icons/ok_disabled.png"
Visible	A GUIScript expression that indicates whether the button is visible or not.	"IsOnline()"
Disabled	A GUIScript expression that indicates whether the button is disabled or not.	"TVModeIsOff()"
Action	A list of GUIScript actions to perform when the button is pressed.	"Confirm(JSAlert); Dismiss(JSAlert)"
NoFocus	If this attribute is present, then the Focus Box cannot highlight this GUI Button.
Type	The type of button - a 'Switch' (on or off), a 'radio' button (a group) or 'key' (normal).	"Switch"
ActionRelease	A list of GUIScript actions to perform when the button is released.	"OpenWindow(Settings)"

Attribute	Description	Example
Name	The name of the GUI Message item	"question"
Value	A GUIScript expression which returns a text string which is used for the message	"DialStatus()"
MaxLength	A number which limits the length of the GUI Message	60
NoWrap	If this attribute is present, the GUI Message will not wrap across multiple lines

Attribute	Description	Example
Name	The name for the TextEntry object	"username"
Type	The type of the TextEntry :- "password" for a password field (shows *'s) or "normal"	"normal"
Width	The width of the TextEntry box. Same as <TEXTAREA> Width attribute	"100%"
Action	A list of GUIScript actions to perform when the user pressed 'Enter' or 'Return' in this TextEntry.	"Goto(url)"

Attribute	Description	Example
Src	The URI for the image to use for the indicator.	"secure.png"
Visible	A GUIScript expression that controls when the indicator can be seen.	"IsSecure()"

Attribute	Description	Example
Value	A text or GUIScript expression which will be used to set the window title.	"'Browsing: ' + DocumentTitle() "

Attribute	Description	Example
Type	The type of throbber - "progress" for a progress bar, or "image" for an animated image.	"image"
Colour	The colour to use for a 'progress bar' throbber.	"white"
Src	The URI of the image to use for the active state of the throbber.	"throb.gif"
Src_Stop	The URI of the image to use for the inactive state of the throbber	"throb_stopped.gif"

GUI Script

Actions

These functions cause actions to happen. Some of them take a parameter which is most often a text string.

Goto(uri)
GoBack()
GoForward()
Refresh()
Stop()
OpenWindow(name)
CloseWindow(name)
ToggleWindow(name)
FocusWindow(name)
OpenOptions(name)
Confirm(name)
Dismiss(name)
Select(item)
Focus(item)
FocusWithPointer(item)
Clear(item)

Information

These functions return information from Oregano2. The information can be used to pass into functions that cause actions.

Home()
Location()
DocumentTitle()
Value(item)

Conditions

CanGoBack()
CanGoForward()
Selected(item)
IsSecure()
IsSemiSecure()

--END--

PageUp	PageDown	Home	End	BackSpace	TopOfPage	EndOfPage
Break	PrintScreen	Print	Help	Zoom	FontSizeIncrease	FontSizeDecrease
Back	Forward	Stop	Reload	Refresh	Search	WebHome	Favourites
History	Goto	Mail	Email	Online	SummonMenuLeft	SummonMenuRight	News
FinanceNews	Weather	Sports	Shopping	ToggleMute	VolumeUp	VolumeDown	Record	Play
Previous	Next	ChooseDevice	Media	Documents	Calculator	SuspendToDisk	SuspendToRAM
Sleep	Setup	Battery	ToggleDisplay	BrightnessUp	BrightnessDown	ContrastUp
ContrastDown	TelevisionMode	ChannelUp	ChannelDown	Teletext	TextReveal	TextExpand	TextMix
TextHide	TextCancel	TextInfo	TextRed	TextGreen	TextBlue	TextYellow	F1 - F25	Menu

Contents