For complex interactions, advanced controls need to be used that can abstract out the complexities of the interaction to the user and provide a simple and consistent interface for the developer to work with. PyS60 has many such controls that a developer can use.

In this discussion, the focus will be on three of the most commonly used controls: selection list, multi-selection list and text. The first section will focus on the whys and wherefores of these controls. In the last section, the application developed in the previous part will be enhanced using the controls being discussed in this section. That is the agenda for this discussion.

If you wish, you can also read my earlier article on PyS60 UI controls.  

Lists and Text Controls: Whys and Wherefores

There are times when providing a list of choices is a better option than asking the user to enter data in an entry box. To provide lists, PyS60 has two UI controls: Selection List and Multi-selection List. The former is a good choice when only one item needs to be chosen, whereas when several items need to be chosen, the later is the control of choice. 

As its name suggests, Selection List displays a list to the user from which he or she can choose. The selection list provided by PyS60 also contains a search field that helps the user to narrow down the choices. It is displayed to the user using a function called selection_list(). It comes under the category of dialogs wrapped in functions.

The selection_list() function takes two arguments, choices and search_field. The latter is an optional argument. Choices is a list of Unicode strings containing the options to be displayed to the user. The other argument, search_field, accepts a "0" or "1" as the value. The value decides whether the search field will be shown. If the value is "1," the search field is shown. The default value is "0," i.e. the search field is off by default. If enabled, the search field is shown after the first key press occurs.

The value returned by the selection_list() function is the index of the selected item. For example, to show a list with "egg," "spam" and "butter" to choose from without any search field, the statements would be:

list = [u”egg”, u”spam”, u”butter”]

selection_list(list)

There are cases where a single selection is not a solution. This is where a multi-selection list comes handy. Like a selection list, a multi-selection list is also a function that wraps a dialog and displays the dialog when it is executed. The function that brings up a multi-selection list is multi_selection_list() . It accepts the following three arguments:

• choices
  
• style
  
• search_field

The first and third are similar to the selection_list() arguments. The second argument is unique to a multi_selection_list(). Choices is simple to explain; just as with a selection_list, the value accepted by this argument is a list of Unicode strings.

The style argument is a little more detailed. It is optional. The value of this parameter decides how the list will be displayed. There are two valid values for the style parameter, checkbox and checkmark. Checkbox is the default value; if it is given as the value of the style, the list presented to the user will be a list containing a checkbox against each list item. Empty checkboxes indicate selectable items. If checkmark is used, on the other hand, the list presented to the user doesn’t provide a visual clue as to which item is to be selected. However, once selected, a checkmark will appear against that item.

Finally, the search_field argument does the same thing that search_field does for the selection_list() function. If a value of 1 is passed, the search field is displayed and if a value of 0 is given, the search field is not displayed.

The value returned by the function is a tuple containing selected values. If no values are selected, then an empty tuple is returned. For example, the following statements display a list from which multiple items can be selected; it has the checkmark style and a search field, and the returned values are displayed.

list = [u”egg”, u”spam”, u”butter”]

result = multi_selection_list(list, ‘checkmark’, 1)

print result

Next, let us move on to the control that provides the text editor functions.