Mobile Programming using PyS60: Advanced UI Controls

In an earlier article I wrote, the topic of discussion covered the basic UI controls that PyS60 provides. These controls are useful when the solution to be developed is simple in terms of interaction. However, if a scenario presents itself where interaction becomes complex, then the basic controls would not suffice. Keep reading to learn about the advanced controls you’ll need to deal with these kinds of issues.

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.

{mospagebreak title=Text}

Text provides text editor with almost all of the text formatting functionalities. The control is provided by Text type. Unlike selection or multi-selection lists, text is a type. The functionalities provided by the text type are categorized as either attributes or methods. More precisely, since the text is a type, the functionalities are exposed either as a attribute or a method. 

The most commonly used attributes of Text include the following:  

  • color: Defines the color of the text. The valid values are all the colors supported by graphic models in graphics module. 
  • font: Determines the font family of the text. It can be set using the supported Unicode name.
  • style: Affects the style of the text. The valid values for this attribute are defined as flags. The valid flags are provided by appuifw module. Some of the commonly used flags are:
    • STYLE_BOLD – Makes the text bold.
    • STYLE_UNDERLINE – Underlines a displayed text.
    • STYLE_ITALIC – Makes the text italic.


For example, to use a Text type with LatinPlain12 as the font value with bold text, the statements would be:


t = appuifw.Text()

t.font = u"LatinPlain12" # sets font to Latin Plain 12

t.style = appuifw.STYLE_BOLD


As mentioned above, the Text type provides various methods to perform common operations on the text held by the editor. The most common methods are:

  • add() : Accepts a Unicode string as an argument. This method appends a text to the existing text. It can also be used to insert the passed argument at current cursor position. 
  • set() : Just like the add() method, it accepts a Unicode string as an argument. Specifically, it sets the passed Unicode string as an argument. It replaces any text that may be present in the editor. 
  • delete() : Accepts two arguments, position and length, and deletes characters in the editor for the given length, editor starting from the position passed as argument.

 

For example, to set a string having the value “This is a text” as the text in the editor, the statement is


t.set(u”This is a text”)


This brings us to the end of this section. In the next section, the guessing game application that was developed in the previous article (linked to at the beginning of this one) will be enhanced using a single selection list.

{mospagebreak title=PyS60 in Real World}

In the last discussion, a guessing game was developed. The code was as follows


from appuifw import *


continue_guess=true


while continue_guess:

guess_no=random()

user_guess=query(u”Enter your guess”, ‘number’)

if user_guess is Null:

note(u”You have opted out”)

continue_guess=false

elif user_guess<guess_no:

note(u”Your guess is lesser than the goal”)

elif user_guess>guess_no:

note(u”Your guess is higher than the goal”)

else:

note(u”Congrats for excellent guess”)


user_choice=query(u”Enter Y to continue or N to quit”)

 

if user_choice is Null or user_choice==’N’:

continue_guess=false

else:

continue_guess=true


Now, let us change the display part for displaying the choices. Instead of taking user’s input using a query dialog, let us show a selection list from which the user can select a value. The following code


user_guess=query(u”Enter your guess”, ‘number’)


needs to be changed to


list = [guess-100, guess, guess*200, u”Quit”]

user_guess = selection_list(list)


First, a list is created using the guess number and its combination. Then the list is given as an argument to the selection_list() method. The returned index, which is the value selected by the user, is then stored in the user_guess variable.

{mospagebreak title=Reprocessing the Result}

Next, let us change how the result is processed. To do so, change the code below 


if user_guess is Null:

note(u”You have opted out”)

continue_guess=false

elif user_guess<guess_no:

note(u”Your guess is lesser than the goal”)

elif user_guess>guess_no:

note(u”Your guess is higher than the goal”)

else:

note(u”Congrats for excellent guess”)


to the following


if guess_no < list [user_guess]:

note(u”Your guess is lesser than the goal”)

elif guess_no < list [user_guess]:

note(u”Your guess is higher than the goal”)

elif guess_no == list [user_guess]:

note(u”Congrats for excellent guess”)

else:

note(“Bye”)

continue_guess = false


The index returned by the selection_list() is used by the if condition to get the value selected by the user, from the list. If the index corresponds to the value lesser or greater than the goal value, then a note is displayed telling the user that he/she is either short of the goal or has overshot the goal. Otherwise, the user is congratulated. If the user selected the option to quit, the continue_guess is set to false, thus ending the game. The complete code is as follows:


from appuifw import *


continue_guess=true


while continue_guess:

guess_no=random()

list = [guess-100, guess, guess*200, u”Quit”]

user_guess = selection_list(list)


if guess_no < list [user_guess]:

note(u”Your guess is lesser than the goal”)

elif guess_no < list [user_guess]:

note(u”Your guess is higher than the goal”)

elif guess_no == list [user_guess]:

note(u”Congrats for excellent guess”)

else:

note(“Bye”)

continue_guess = false


That completes our application. This discussion focused on the UI controls. When I next pick up this discussion, I will bring up third party libraries in PyS60. However, I will focus primarily on the graphics module. Till then…  

Google+ Comments

Google+ Comments