Getting Started7:Containers and Layout Hierarchy

[kino]

When programming applets written in the Curl language, you typically create a user interface by building a graphic hierarchy of graphical objects; that is, by putting graphical objects inside of other graphical objects that serve as containers, such as scroll boxes or tables, which may in turn be displayed inside of another graphical object, such as a window on your computer screen.


Graphical containers are used to create graphical interface objects that can contain other graphical objects. Containers may contain text, images, menus, controls, and other containers.


VBox, HBox, and Frame
Curl has many kinds of "boxes" that serve as graphical containers. Each type of box has specified functionality as to how it displays its content. It can also control the selectable attributes, or options, of the graphic.


Three of the most commonly used graphical "boxes" are VBox, HBox, and Frame.


Container Name: Description

VBox: A container for arranging a collection of Graphic objects in a vertical column. It adds each child by placing it below its most recently added sibling.

HBox: A container for arranging a collection of Graphic objects in a horizontal row. It adds each child by placing it to the right of its most recently added sibling.

Frame: A container that can hold zero or one Graphic objects


Using these three classes, we can create containers that arrange their contents in various horizontal and vertical arrangements.

Code:

{curl 6.0, 7.0 applet}
{applet {compiler-directives careful? = true}}

{HBox
spacing = 10pt,
{HBox
{Frame
width = 1cm,
height = 1cm,
background = "orange"
},
{Frame
width = 1cm,
height = 1cm,
background = "teal"
}
},
{VBox
{Frame
width = 1cm,
height = 1cm,
background = "pink"
},
{Frame
width = 1cm,
height = 1cm,
background = "maroon"
}
}

}

As you add a new HBox, VBox, or Frame to a layout, you are creating your hierarchy of graphical containers. This hierarchy creates parent/child relationships that can be used to pass information up and down the layout.


The following diagram depicts the graphical hierarchy of the above example.



Recall that a Frame can hold zero or one graphical object. In this case, each child Frame is empty (containing zero objects). The height and width are used to display the background color of the object.




For more information regarding graphical boxes, please refer to the following section in the Curl Documentation:Curl Developer's Guide > Graphical User Interface > Graphical Containers > Sequence Boxes



Passing Property Values down the Hierarchy
It is common to build your user interface hierarchy using multiple types of containers in parent/child relationships.


Certain option values can be 'carried through' such an object to affect the appearance of another object further down the descendant hierarchy. This is the case for options that are "nonlocal", where the values are passed down the hierarchy to child objects. There are also options that affect that only the object on which they are set. These options are said to be "local".


You may want to use nonlocal options to your advantage by setting an option on a particular graphical object and having its graphical children and descendants take on the same option value without having to set each one of them separately. In the following example, the font-family option is specified on the parent object. This value will be passed down the hierarchy and each child object will inherently obtain the same value.


In the following example, both local and nonlocal options are set on the top HBox. Local options, such as margin, only apply to the HBox but not to its graphical children. The nonlocal options, such as font-family and border-color apply to the top HBox object and to its graphical children.

Code:

{curl 6.0, 7.0 applet}
{applet {compiler-directives careful? = true}}

{HBox
background = "silver", || local
margin = 5pt, || local
font-family = "Courier", || non local
border-color = "blue", || non local
border-style = "raised", || local
border-width = 3pt, ||local
{Frame
background = "gray",
width = 1cm,
height = 1cm,
{text A}
},
{Frame
width = 1cm,
height = 1cm,
{text B}
},
{VBox
{Frame
width = 1cm,
height = 1cm,
{text C}
},
{Frame
border-style = "raised",
border-width = 3pt,
width = 1cm,
height = 1cm,
{text D}
}
}
}

There are three other things to note in this example:



1.A child object can override a parent's nonlocal option value by explicitly setting the option.

2.In the child Frame that specifies border-style and border-width, border-color does not need to be specified since it is a nonlocal option (unless another value is wanted).

3.Notice that the background option is local and yet the children still obtain the silver color. This is due to the fact that the default value for the background is transparent.


You can find out if a particular option is local or nonlocal by referring to the Curl API Reference Manual, where local and nonlocal options are specified in the option definition.


Tip: The type of Box also controls the positioning of its children, i.e., relative positioning vs. discrete positioning. For example, VBox and HBox position children relative to one another in either a vertical or horizontal structure whereas a Canvas positions children using x,y positioning.


Other Graphical Containers
Of course, there are more graphical containers than what we have discussed in this Curl Cue. The most commonly used containers are as follows:


Containers in the GUI Toolkit
Container Name: Description

VBox: A container for arranging a collection of Graphic objects in a vertical column

HBox: A container for arranging a collection of Graphic objects in a horizontal row

TextFlowBox: A box for laying out a flow of rich text that can have embedded Graphic objects

Canvas: A container for arranging a collection of Graphic objects using x,y coordinates

Table: A container for arranging a collection of Graphic objects in rows and columns

Frame: A container that can hold zero or one Graphic objects

ScrollBox: A container that encloses a Graphic object using vertical and/or horizontal scroll bars

View: A window containing Curl graphical content