User Interface Basics5:Swapping UI Content

[kino]

Classically, each time the user makes a selection, an entire HTML page is rendered and sent from the server machine. This means that the server must know the exact layout of each page, including each user's personalization preferences, if any, which may enable or disable display elements.


With the added client-side processing ability, Curl's runtime interactions are very different from a classic Web application. The biggest difference is that Curl applets can store and locally manipulate content, allowing the display to be locally created on the client machine. In Curl, there is no need to render each page every time the user makes a selection. Instead, one or more objects can be swapped, replaced, or reorganized in the user interface.

In Curl, there are two main implementations for changing the user interface display:


1.The content of one object is replaced with another object. In this case, the parent object can contain no more than one child object, such as a Frame.

2.One or more the objects can be deleted or replaced with other objects. In this case, the parent object can contain on or more child objects, such as a VBox.


We'll cover both of these cases in this Curl Cue. In either case, the strategy is the same: It is easy to dynamically change content in your user interface.


1.Create a graphical hierarchy.

2.Define a dynamic event handler on an event target.

3.Create a conditional that changes the graphical container based on a user selection, or other type of interaction.


Replacing Content
The Frame class implements a container that holds no more than one graphical object. The object it contains, however, may itself contain multiple objects. A Frame is used to:


1.Specify an additional layer of border or background decorations around an object

2.Swap content programmatically


Let's concentrate on the second case. A Frame is useful as a holder that can contain a succession of different objects as its graphical child while continuing to occupy the same position in a graphic hierarchy. To swap a Frame's content programmatically, we use the add method. Frame.add has a keyword parameter replace?.


•If replace? = true, then the Frame's previous child, if any, is replaced by a specified object.

•If replace? = false, which is the default, an error will be thrown if this method is invoked on a Frame that already has a child.


In the following example a Frame holds the selected value from the ComboBox. Once the user selects an item from the ComboBox then the Frame content is replaced with the value.

Code:

{curl 6.0, 7.0 applet}
{curl-file-attributes character-encoding = "utf8"}

{value
let favorite:Frame =
{Frame}
let combo:ComboBox =
{ComboBox
width=3cm,
"Red",
"White",
"Blue",
value = "Red",
{on ValueFinished at combo:ComboBox do
{favorite.add replace? = true,
combo.value}
}}
{spaced-vbox
{HBox "Your favorite color is: ", favorite},
combo
}
}

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

Adding and Detaching Objects
In the following example, we have a VBox that can have zero, one or more children. Each time a user selects a button, an object is either added to or detached from the parent object using the add method of VBox or the detach method of the object to be detached, respectively.


Here we have more than one child object that can be placed in the hierarchy. The first thing is to define each object with a given name. Once we can get a handle on an object using its name, we can use the methods to detach and add the object as needed.

Code:

{curl 6.0, 7.0 applet}
{curl-file-attributes character-encoding = "utf8"}

{value
let rectangle:RectangleGraphic=
{RectangleGraphic
fill-color = "red",
width = 1in,
height = 0.5in}
let ellipse:EllipseGraphic=
{EllipseGraphic
width = 2cm,
height = 2cm,
fill-color = "blue"
}
let rectangle_added?:bool = true
let ellipse_added?:bool = true
let container:VBox =
{VBox
halign = "center",
spacing = .1in,
{HBox
{CommandButton
label = "Remove Rectangle",
width = 1.2in,
{on Action at cb:CommandButton do
{if rectangle_added? then
{rectangle.detach}
set cb.label = "Add Rectangle"
set rectangle_added? = false
else
{container.add rectangle}
set cb.label = "Remove Rectangle"
set rectangle_added? = true
}
}
},
{CommandButton
label = "Remove Circle",
width = 1.2in,
{on Action at cb:CommandButton do
{if ellipse_added? then
{ellipse.detach}
set cb.label = "Add Ellipse"
set ellipse_added? = false
else
{container.add ellipse}
set cb.label = "Remove Ellipse"
set ellipse_added? = true
}
}
}
},
rectangle,
ellipse
}
container
}

Notice that the objects are added sequentially. You can also specify the location of the child object by specifying the index. If index = 0, then the object is added as the first child in the list.


Tip: Objects can only be displayed once in the hierarchy. Create another instance of the object to display it multiple times. For example, if another rectangle needs to be displayed, modify the code with the following:

Code:

let rectangle2:RectangleGraphic=|
{RectangleGraphic
fill-color = red,
width = 1in,
height = 0.5in
}

In most cases, it is much easier to encapsulate swappable objects in a Frame rather than add and detach objects in a sequence box, e.g. VBox.




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