Contract
Parameter key	Default value	Type
name	opt
label	label	string
x	active_value	nonnegative
y	active_value	nonnegative
width	active_value	nonnegative
height	active_value	nonnegative
foreground_color	black	color
background_color	white	color
visibility	active_value	boolean
tool_tip	null	type.<one_of string/>

Water Contract

<class ui
  name          =opt
  label         =ui.item.label=string
  x             =<active_value></active_value>=number.integer.nonnegative
  y             =<active_value></active_value>=number.integer.nonnegative
  width         =<active_value></active_value>=number.integer.nonnegative
  height        =<active_value></active_value>=number.integer.nonnegative
  foreground_color=<color red=0 green=0 blue=0 name="black" _name="black"/>=color
  background_color=<color red=255 green=255 blue=255 name="white" _name="white"/>=color
  visibility    =<active_value></active_value>=boolean
  tool_tip      =null=<type.one_of null string/>
/>

1. HTML

The primary mechanism is to use HTML. HTML is a subset of the Water language and as such Water is ideal for making dynamic web pages.

2. ide.add_item

add_item is used for developing modifications to the Steam IDE, the ide.add_item method makes it extremely easy to customize the menus and toolbar in the ide. If you are making a tool for users that can benefit from the overall Steam IDE yet need some additional widgets to help with your specific application, ide.add_item is the way to go.

3. ui

The Water 'ui' objects are use for developing normal-looking stand-alone applications. If you were using Java, you'd use the Swing objects for this. In fact Water ui uses Swing as the underlying mechanism so your applications will look very Swing-like. To a first approximation, you can think of the ui package as "HTML-like with Swing tags". The syntax is Water so your ui code can have the basic architecture of a web page if you like. You can also code it more "java style" wherein you create widgets by themselves, add them to various containers explicitly, and continue to change their characteristics and read user input programmatically. Intermixing both styles is easy for the creation of the interface as well as dynamically modifying it. Assigning actions to buttons and menu items is as simple as giving the widget a "click" property who's value is a water method. Unlike Java Swing, you do not need to know about interfaces, listeners, inner classes, events, layout managers, etc. Furthermore, Water ui widgets are much more consistent with themselves than the Swing widgets so that per functionality, there's a lot less to learn. Here's a simple example to give you the flavor of using Water ui. This example makes a window with one button in it. Clicking the button changes the label of the button to the current time.

ui.<window name="mywin" width=150 height=100>
   null
   ui.<button name="Press for time" 
      background_color=color.of.yellow
      click=<method null> 
               .<set label=<h1><do time.<current/>/></h1>/>
            </method>
    />
  </window>

To programmatically move the window, just set its x and/or y field

ui.mywin.<set x=275 y=100/>

To programmatically "click" the button, just call the click method:

ui.mywin."Press for time".<click/>

Water ui does not attempt to implement ALL of the functionality of Swing, just the most useful widgets and the most useful properties on each are implemented. You can access the underlying Swing component within each Water ui widget to perform uncommon operations if you need to. You can also call Swing methods from Water just like any Java methods should you need to. Water ui components are divided into two sets: panes and items. Panes are containers of other sub-panes or items such as windows and menus. The difference between the various pane objects is primarily how they lay out their parts. Items are the end-user widgets like buttons and checkboxes. Each application is composed of instances of several different classes of panes and items. ui panes and ui items share a lot of features and syntax in common: First, both the pane and the item class have a parent class of 'ui'. ui.pane.row ui.item.button Each of the panes and items have a synonym in the ui class for concise entry. The below are synonyms for the above:

ui.row
ui.button

Each component has each of the below keys:

name

The value of the name attribute is the name by which the object is known in its container. The container will have a key of the name of each of its contained components. The value of that key will be the component part itself. Thus the name is used to reference the object from its container. The name is almost always a string. It defaults to the name of the class plus a small integer to make it unique such as "button_1". The name must be unique as a key in the container of the component.

ui.<window name="mywin">
 null
 ui.<button name="mybutton"/>
</window>
ui.mywin.mybutton

label

The label is a string that appears on the object when the object is displayed, though not all components display their label. The label is optional. It defaults to the value of "name". If the string starts with <html then it is considered to be html and will be rendered into the component.

ui.<button name="mybutton" label="<html><h1>hey</h1></html>"/>

Most panes and many items don't show the label, so for them its value is unimportant.

x

x represents the x position of the component within its container in pixels. Many containers ignore the x field but it is important for windows (who's container is just the screen) and for components in an xy pane. x must be a non-negative integer. It defaults to 0.

ui.<window x=333/>.x

333

ui.<window/>.<set x=99/>

y

y represents the y position of the component within its container in pixels. Many containers ignore the y field but it is important for windows and for components in an xy pane. y must be a non-negative integer. It defaults to 0. The higher the y value, the lower the component will appear on the screen.

ui.<window y=333/>.y

333

ui.<window/>.<set y=99/>

width

width is the width of the component in pixels. It must be a non-negative integer. The default value depends on the component type.

ui.<window name="mywin" width=188/> 
ui.mywin.width

ui.mywin.<set width=133/>

height

height is the height of the component in pixels. It must be a non-negative integer. The default value depends on the component type.

ui.<window name="mywin" height=188/> 
ui.mywin.height

ui.mywin.<set height=133/>

foreground_color

foreground_color is the color of the component's foreground, which is usually the text of the label. It must be a color. Black is the default.

ui.<window name="mywin"> 
 null 
 ui.<button name="mybutton" foreground_color=color.of.red/>
</window> 
ui.mywin.mybutton.foreground_color

color.of.red

ui.mywin.mybutton.<set foreground_color=color.of.blue/>

ui.mywin.mybutton.<set foreground_color=<color red=100 green=255 blue=0/>/>

background_color

background_color is the color of the component's background. It must be a color. The default value is white or gray depending on the component.

ui.<window name="mywin">
 null 
 ui.<label name="mylab" background_color=color.of.yellow/>
</window> 
ui.mywin.mylab.background_color

color.of.yellow

ui.mywin.mylab.<set background_color=color.of.green/>

ui.mywin.mylab.<set background_color=<color red=200 green=100 blue=200/> />

Note that on WindowsXP using Java 1.4.2 or so, setting the background of certain items like button and textfield may not work, or may only draw a thin colored line around the item. This is apparently a bug in the interaction between the operating system and Java.

visibility

visibility determines if a component is visible or not. It is a boolean with default true.

ui.<window name="mywin">
 null 
 ui.<row> ui.<button name="mybutton1"/> ui.<button name="mybutton2" visibility=false/> </row>
</window> 
ui.mywin.center.mybutton2.<set visibility=true/>
ui.mywin.center.mybutton1.<set visibility=false/>
ui.mywin.center.mybutton1.visibility

false

tool_tip

A tool_tip is a short description of a component that pops up when the user leaves their mouse cursor on the component without moving it for a few seconds. It must be null or a string. The default is null which means there will be no pop up description.

ui.<window name="mywin">
 null
 ui.<button name="mybutton" tool_tip="the button's tool_tip"/>
</window>
ui.mywin.mybutton.<set tool_tip="short tt"/>
ui.mywin.mybutton.tool_tip

"short tt"

native_object

Each component has an underlying Java Swing instance that implements it in the field "native_object". This object is created automatically, but may be accessed for operations not supported by the Water ui code. If you find yourself using this a lot, let us know and we'll add support for the functionality you need in Water.

ui.mywin.mybutton.native_object