A Graphical User Interface (GUI) represents a set of graphical components that enables the user to browse, access and interact with the application functionalities.

There are two basic approaches to user interaction with SL4A namely −

• Dialog boxes such as Alerts.

• Using HTML and JavaScript to build the UI and then Python behind the scenes to handle any additional processing.

This chapter explains both the approaches.

Python Dialog Box – Based GUIs

SL4A includes a UI façade to access the basic UI elements provided by the android API. These functions return a result object as a named tuple when called. Each result is assigned a unique id for tracking purpose. The second element is the result. It represents the user’s input. The tuple also includes the third element error to provide feedback to the caller about any error condition that might have been encountered. If no errors were encountered this element is set to None.

The following table lists the commonly used UiFacade functions.

S.No.	UiFacade Function & Description
1	dialogGetInput Queries the user for a text input. title (String) title of the input box (default = Value) message (String) message to display above the input box (default = Please enter value:) defaultText (String) text to insert into the input box (optional) The result is the user”s input, or None (null) if cancel was hit.
2	dialogShow Show dialog
3	dialogCreateAlert Create alert dialog. title (String)(optional) message (String) (optional)
4	dialogDismiss Dismiss dialog.
5	dialogCreateDatePicker Create date picker dialog. year (Integer) (default = 1970) month (Integer) (default = 1) day (Integer) (default = 1)
6	dialogCreateTimePicker Create time picker dialog. hour (Integer) (default = 0) minute (Integer) (default = 0) is24hour (Boolean) Use 24 hour clock (default = false)
7	dialogGetPassword Queries the user for a password. title (String) title of the password box (default = Password) message (String) message to display above the input box (default = Please enter password:)
8	dialogGetResponse Returns dialog response.
9	dialogSetPositiveButtonText Set alert dialog positive button text. text (String)
10	dialogSetNegativeButtonText Set alert dialog button text. text (String)
11	dialogSetNeutralButtonText Set alert dialog button text. text (String)
12	dialogSetSingleChoiceItems This creates a list of radio buttons.
13	dialogSetMultiChoiceItems This creates a checkbox
14	dialogCreateHorizontalProgress Create a horizontal progress dialog. title (String) (optional) message (String) (optional) maximum progress (Integer) (default = 100)
15	dialogCreateSpinnerProgress Create a spinner progress dialog. title (String) (optional) message (String) (optional) maximum progress (Integer) (default = 100)
16	addContexMenuItem Adds a new item to context menu. label (String) label for this menu item event (String) event that will be generated on menu item click eventData (Object) (optional)
17	addOptionsMenuItem Adds a new item to options menu. label (String) label for this menu item event (String) event that will be generated on menu item click eventData (Object) (optional) iconName (String)
18	webViewShow Display a WebView with the given URL. url (String) wait (Boolean) block until the user exits the WebView (optional)
19	clearContextMenu Removes all items previously added to context menu.
20	clearOptionsMenu Removes all items previously added to options menu
21	makeToast Create a notification

Examples

A simple Toast Example

import android 
droid = android.Android() 
uname = droid.getInput("Enter your name") 
print uname  
droid.makeToast("Hello %s" %uname.result)

A Horizontal Progress Bar

import android 
   droid = android.Android() 
   title = "Progress" 
   str = "Loading..." 
   droid.dialogCreateHorizontalProgress(title,str,100) 
   droid.showDialog() 
	
   for x in range(0,99) 
      time.sleep(0.1) 
      droid.dialogSetCurrentProgress(x) 
		
   droid.dialogDismiss()

Modal Vs Non-Modal Dialog Boxes

A modal dialog box or window is a child to another process or window. With a modal dialog box, processing will wait or block until the user interacts with the new dialog box.

A typical example of this case is an alert dialog box. The alert will not close until the user performs an action.

The following image is an example of a modal dialog box.

To sum up, use a modal dialog box when you need input from the user before you continue execution.

Python GUIs with HTML

SL4A enables building Graphical User Interfaces (GUIs) based on CSS, HTML, JavaScript and Python. The approach uses HTML and JavaScript to build the UI, CSS to enhance the appearance and consistency of HTML elements and fonts and Python to handle any additional processing.

The following example illustrates a basic HTML GUI example −

1. Speech.html

<html> 
   <head> 
      <title>Text To Speech</title> 
		
      <script> 
         var droid = new Android(); 
         var speak = function(){ 
            droid.postEvent("say",document.getElementById("say").value); 
         } 
      </script> 
		
   </head>
	
   <body> 
      <form onsubmit = "speak()";return false;”> 
         <label for = "say">What is your message?</label> 
         <input type = "text" id = "say"/> 
         <input type = "submit" value = "Speak"/> 
      </form> 
   </body> 
	
</html>

2. txtToSpeech.py

import android 
droid = android.Android() 
droid.webViewShow(‘file:///sdcard/sl4a/scripts/Speech.html’) 

while True: 
   result = droid.waitForEvent(‘say’).result 
   droid.ttsSpeak(result[‘data’])

Both the files − Speech.html and txtToSpeech.py, must reside in the /sdcard/sl4a/scripts directory on the device. Run the python script to launch the HTML file.

This file is launched by the webViewShow API call. The event is generated when the Speak button is clicked.