User Interface Basics4:Populating Control List Data

[kino]

Allowing a user to select one or more items from a list is a common Web design pattern. A ListBox permits the programmer to display a number of items, allow the user to make a selection, and then proceed accordingly. ListBoxes are ideal controls for presenting a list of choices to the user---whether a few items or a large number.


In Curl, a ListBox is used to select multiple items. Each selection can be displayed as either text or graphics. The choices are displayed in single vertical column. Zero, one, or more of the choices can be selected by the user.

Code:

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


{value
   let my-list-box:ListBox =
       {ListBox
           style = "checkbutton",
           height = 1in,
           "Pizza",
           "Cheeseburger",
           "Spaghetti",
           "Lobster",
           "Barbeque ribs",
           "Beef stew",
           "Fried chicken"
       }

   {spaced-vbox
       {italic{bold Select one or more of your favorite foods:}},
       my-list-box
   }
}

Notice that scrollbars will automatically appear if the ListBox height is greater than the specified height. If the height is not specified, the ListBox will display all selections. Also, the style of the displayed items has been set to checkbutton which provides a small box to show what is selected. When an item is selected, a "check" graphic will appear in the box. The style can also be set to standard, in which it looks and behaves like a traditional list control.



If the requirement is that a maximum of one item can be selected from the list, you can set ListBox.selection-policy to "single" instead of the default policy of "multiple". You may also want to consider using ComboBox, DropdownList or RadioButton classes.



Creating List Items from Accessed Data
It is common that the selectable items are dynamically retrieved at runtime from an external source such as a database. We can query the data and temporarily store it using an array, hashtable, recordset, or other method of storage. The append or insert methods are used to add new items to the ListBox.


Items appended to a ListBox appear in the order in which they were added. For our example, we will store our list data in an array and then append each item in the array to the ListBox.

Code:

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


{value
   let my-list-box:ListBox =
       {ListBox
           style = "checkbutton",
           height = 1in
       }


   let food-array:{Array-of String} =
       {{Array-of String}
           "Pizza",
           "Cheeseburger",
           "Spaghetti",
           "Lobster",
           "Barbeque ribs",
           "Beef stew",
           "Fried chicken"
       }


   {for food:String in food-array do
       {my-list-box.append food}
   }

   {spaced-vbox
       {italic{bold Select one or more of your favorite foods:}},
       my-list-box
   }
}

Another method of gathering items from an array is to use splice. The splice macro returns the elements of the array as a list of arguments as shown below.

Code:

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

{value
   let food-array:{Array-of String} =
       {{Array-of String}
           "Pizza",
           "Cheeseburger",
           "Spaghetti",
           "Lobster",
           "Barbeque ribs",
           "Beef stew",
           "Fried chicken"
       }
   let my-list-box:ListBox =
       {ListBox
           style = "checkbutton",
           height = 1in,
           {splice food-array}
       }
  
   {spaced-vbox
       {italic{bold Select one or more of your favorite foods:}},
       my-list-box
   }
}

Tip: Sometimes list items need to be added after the actual control has been created. ListModelControl provides methods for manipulating items such as append, remove, clear, delete and find.


Getting Selected Values
Once the user has made their selections, you will need to gather the information for display or further processing. The user selected items in a ListBox are stored as an array in the value property. We can loop through the items of the array to obtain the selected values.


In our example below, the selected values are gathered and displayed in a VBox.

Code:

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


{value

   let my-list-box:ListBox =
       {ListBox
           style = "checkbutton",
           height = 1in
       }

   let food-array:{Array-of String} =
       {{Array-of String}
           "Pizza",
           "Cheeseburger",
           "Spaghetti",
           "Lobster",
           "Barbeque ribs",
           "Beef stew",
           "Fried chicken"
       }


   {for food:String in food-array do
       {my-list-box.append food}
   }

   let selection-button:CommandButton =  
       {CommandButton label = "Press for selections",
           {on Action at box:CommandButton do
               let selections:VBox = {VBox spacing=2pt}
               {for val in my-list-box.value do
                   {selections.add val}
               }

               {popup-message
                   {HBox
                       {text You have selected:   },
                       {value selections}
                   }
               }
           }
       }

   {spaced-vbox
       {italic{bold Select one or more of your favorite foods:}},
       my-list-box,
       selection-button
   }
}

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



The next example takes input from a TextField and appends those values to a ListBox. The ListBox displays the current entries.

Code:

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


{value
   let name-list:DefaultListModel = {DefaultListModel}
   let name-listbox:ListBox =
       {ListBox
           data-model = name-list
       }
  
   {VBox
       {bold Type items to add and press enter},
       {TextField
           {on ValueFinished at text:TextField do
               {name-list.append text.value}
           }
       },
       {bold Here are the current items in the {italic List}},
       name-listbox
   }
}

Notice that unset-value is used to clear the input value in the TextField when the user presses enter.




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