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/>
Parameter kind	Default value	Type
Other unkeyed arguments	opt with ekind of code	ui

Water Contract
<class ui.pane _other_unkeyed=opt=ui="_other_unkeyed" _other_unkeyed=opt=ui="_other_unkeyed" />

See also: ui, item, window

A pane is a container of other components (panes and items). Each of these parts is displayed within the borders of the pane. Panes differ from one another in how their parts are laid out with respect to each other. Ultimately the function of panes is to display items. Panes without items is like coming home from the supermarket with a trunk full of empty bags. Every visible component is a window or contained in one. Each window has an optional menubar and a center. The menubar can contain items but usually contains just menus. Each menu can contain submenus, menuitems or other items. Similarly the center of a window can contain a pane, say a row, which itself contains other panes or items such as buttons. Windows themselves are stored as parts of the ui class. The ui class is invisible but you should think of it as the top level container, since, for purposes of referencing windows, it behaves just like another pane.

Part initialization, insert, remove, rename, set

A pane can be initialized with parts by having the code for each part in the content of the call to create the pane much like nested tags in HTML. After a pane has been created you can insert, remove, rename and set parts within the pane just like using insert, remove, rename and set on fields of any Water object.

ui.<window name="mywin">
 null
 ui.<row name="myrow"> ui.<button name="mybA"/> </row>
</window>
ui.mywin.myrow.<insert ui.<button name="mybB"/>/>
ui.mywin.myrow.mybB
ui.mywin.myrow.<remove "mybB"/>
ui.mywin.myrow.<length/>  <!-- now back to 1 -->
ui.mywin.myrow.<rename mybA_new="mybA"/>
ui.mywin.myrow.mybA_new  <!-- gets the renamed button -->
ui.mywin.myrow.<set mybA_new=ui.<checkbox "mycheck"/>/>
ui.mywin.myrow.mycheck

Note that by using set, you are replacing one part of a container with another part. So after we've executed the above example,

ui.mywin.myrow.mybA_new

error

will error since there is no longer a part at that key.

Referencing Parts

There are two or three ways to refer to a part from its containing pane. You can refer to a part by its name.

ui.<window name="mywin"> null ui.<row name="myrow"/> </window>
ui.mywin.myrow

You can also refer to a part by its 'index' within its container. These index references are created and maintained by the ui system itself. The programmer need not be aware of them, though sometimes they're very handy.

ui.<window name="mywin"> 
 null
 ui.<row name="myrow"> 
    ui.<button name="mybuttonA"/> ui.<button name="mybuttonB"/> 
 </row>
</window>
ui.mywin.myrow.0

ui.mywin.myrow.mybuttonA

Since the 'length' method operates on the nonnegative integer keyed fields of any object, it can be used to find out how many parts a pane has.

ui.<window name="mywin">
 null 
 ui.<row name="myrow"> 
  ui.<button name="mybuttonA"/> 
  ui.<button name="mybuttonB"/> 
 </row>
</window>
ui.mywin.myrow.<length/>

You can loop through the parts of a pane using for_each, just like for any Water object. This example returns a vector of the two buttons in the row.

ui.mywin.myrow.<for_each include=vector_key combiner=insert>
 value
</for_each>

Of course, since the two buttons have indexes of 0 and 1, myrow itself acts as a supervector, i.e. a vector with some additional fields. Some containers have "logically" named parts that can be used to refer to parts. When you use the content of a pane to initialize parts, those parts will get assigned to the logical keys within their container, if any, according to the ordering of the parts within the content of the call to create the pane. The actual names of the logical parts differ depending on the class of the pane. For example, window has a 'menubar' and a 'center'.

ui.<window name="mywin">
 null              <!-- this is the menubar part which we are not initializing -->
 ui.<button name="bA"/> <!-- this is the center part -->
</window>
ui.mywin.bA     <!--reference the button by name -->
ui.mywin.1      <!--reference the button by index -->
ui.mywin.center <!--reference the button by logical name -->