×
Namespaces

Variants
Actions
(Difference between revisions)

How to add an activity or progress indicator to an Alert

From Nokia Developer Wiki
Jump to: navigation, search
skalogir (Talk | contribs)
(Skalogir -)
hamishwillee (Talk | contribs)
(17 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[Category:Draft]]
+
[[Category:Java ME]][[Category:UI]][[Category:Symbian]][[Category:Series 40]][[Category:Code Examples]][[Category:Series 40 2nd Edition]][[Category:Series 40 3rd Edition FP1]][[Category:Series 40 3rd Edition FP2]][[Category:Series 40 3rd Edition (initial release)]][[Category:Series 40 5th Edition (initial release)]][[Category:Series 40 5th Edition FP1]][[Category:Series 40 6th Edition (initial release)]][[Category:Series 40 6th Edition FP1]][[Category:Series 40 Developer Platform 1.0]][[Category:Series 40 Developer Platform 1.1]][[Category:Series 40 Developer Platform 2.0]][[Category:S60 2nd Edition FP2]][[Category:S60 3rd Edition (initial release)]][[Category:S60 3rd Edition FP1]][[Category:S60 3rd Edition FP2]][[Category:S60 5th Edition]][[Category:Symbian^3]][[Category:Symbian Anna]][[Category:Nokia Belle]]
 
{{Abstract|This code example demonstrates how to add an activity indicator to an Alert, that displays the progress for the completion of a process and dismisses itself, when the process is completed.}}
 
{{Abstract|This code example demonstrates how to add an activity indicator to an Alert, that displays the progress for the completion of a process and dismisses itself, when the process is completed.}}
  
Line 32: Line 32:
 
==Overview==
 
==Overview==
  
This code example uses two high-level LCDUI components, an Alert and a Gauge. The alert is manually launched by the end user, while the gauge is used as activity indicator. The activity indicator describes the progress for completing a 10-step task. The range of the indicator is between 0 and 100, in increments of 10.
+
This code example uses two high-level LCDUI components, an [http://www.developer.nokia.com/Resources/Library/Java/_zip/GUID-0D0A1092-5037-4421-B466-B958CB777414/javax/microedition/lcdui/Alert.html Alert] and a [http://www.developer.nokia.com/Resources/Library/Java/_zip/GUID-0D0A1092-5037-4421-B466-B958CB777414/javax/microedition/lcdui/Gauge.html Gauge]. The Alert is manually launched by the end user, while the Gauge is used as activity indicator inside the Alert. The activity indicator describes the progress for completing a 10-step task. The range of the indicator is between 0 and 100, in increments of 10.
  
<gallery widths=200px heights=400px>
+
<gallery widths=250px heights=500px>
 
File:start.png| On full touch Series 40, the Alert Launcher is placed in Action Button 1
 
File:start.png| On full touch Series 40, the Alert Launcher is placed in Action Button 1
 
File:step_2.png| Step 2 in a 10-step progress activity
 
File:step_2.png| Step 2 in a 10-step progress activity
 
File:step9.png| Step 9 in a 10-step progress activity
 
File:step9.png| Step 9 in a 10-step progress activity
 
</gallery>
 
</gallery>
+
 
== The User Interface ==
+
== Main Components==
Both TextFields are empty by default. The TextField at the top of the form becomes of type {{Icode|PHONENUMBER}} and can take up to 20 digits, while the TextField beneath it, becomes of type {{Icode|PLAIN}} and takes up to 160 characters, which is the character limit for an SMS transmission without splitting it up to more than one piece. In the constructor, we instantiate the MessageConnection object and bind it to port 6553. Also a {{Icode|TextMessage}} instance is created of type TEXT_MESSAGE, since this example will be used for sending a message containing characters in the form of a text. If the port cannot be opened, an error message will be appended to the form.
+
 
 +
There are three Commands in this code example. An OK command that launches the Alert and an Exit Command for calling the {{Icode|notifyDestroyed()}} method, are appended to the Form. A Cancel Command is added to the Alert. The running thread moves the progress indicator every one second in increments of 10. There is also an image that is being displayed inside the alert.
 +
 
 +
{{Note|In order for the image to be properly displayed with this code, you need to add an image file to the resource directory of your project and rename it to '''generic_phone.png'''.}}
  
 
<code java>
 
<code java>
 +
Form mainForm;
  
        mainForm = new Form("SMS Example");
+
//OK and Exit are added to the Form
+
Command exitCommand = new Command("Exit", Command.EXIT, 0);
        smsNumber = new TextField("Phone number", null, 20,
+
Command okCommand = new Command("OK", Command.OK, 0);
            TextField.PHONENUMBER);
+
 
        mainForm.append(smsNumber);
+
//Cancel is added to the Alert
+
Command cancelCommand = new Command("Cancel", Command.CANCEL, 0);
        smsText = new TextField("Text", null, 160, TextField.PLAIN);
+
 
        mainForm.append(smsText);
+
//A 1 second per step thread
+
Thread thread;
        sendCommand = new Command("Send", Command.OK, 0);
+
Alert alert;
        mainForm.addCommand(sendCommand);
+
 
+
//A random image for the alert
        exitCommand = new Command("Exit", Command.EXIT, 0);
+
Image img;
        mainForm.addCommand(exitCommand);
+
 
+
//A bar indicator attached to the alert
        mainForm.setCommandListener(this);
+
Gauge indicator;
       
+
        // Open the connection
+
protected void startApp() throws MIDletStateChangeException {
   
+
//The Form's components
        try{
+
mainForm = new Form("Progress Alert");
        connection = (MessageConnection)Connector.open("sms://:6553");
+
mainForm.append("Select OK to launch a 10-step process");
        message = (TextMessage)connection.newMessage(MessageConnection.TEXT_MESSAGE);
+
mainForm.addCommand(okCommand);
        }
+
mainForm.addCommand(exitCommand);
        catch (IOException ex) {
+
mainForm.setCommandListener(this);
        mainForm.append("error:" + ex.getMessage() + "\n");
+
display = Display.getDisplay(this);
        }
+
display.setCurrent(mainForm);
 
</code>
 
</code>
  
== Sending the text message==
+
== Conditions for adding a Gauge as activity indicator within an Alert ==
  
The method {{Icode|handleSendCommand}} is called via the {{Icode|CommandListener}} when the user selects the Send action. The {{Icode|TextMessage}} instance is being given an address in the form sms:// [recipient number] : [port number].
+
Only under certain conditions, can a high-level Gauge be used within an Alert as activity indicator. The Gauge needs to satisfy the following conditions:
The port number is hard coded in this example to 6553. A payload is added to the message by calling the {{Icode|setPayloadText}} method and passing as argument the content of the second TextField.  
+
* it must be non-interactive
 +
* it must not be owned by another container (Alert or Form)
 +
* it must not have any {{Icode|Commands}}
 +
* it must not have an {{Icode|ItemCommandListener}}
 +
* it must not have a label (that is, its label must be null
 +
* its preferred width and height must both be unlocked, and
 +
* its layout value must be {{Icode|LAYOUT_DEFAULT}}.
  
<code java>
+
This practically means that we need to instantiate the Gauge object with {{Icode|null}} for the first argument that denotes the label and {{Icode|false}} for the second argument that denotes the boolean that determines whether the Gauge is interactive or not:
  
      private void handleSendCommand() {
+
<code java>
   
+
indicator = new Gauge(null, false, 100, 0);
    //Set the destination address
+
alert.setTimeout(Alert.FOREVER);      
        String number = "sms://" + smsNumber.getString() + ":6553";
+
alert.setCommandListener(this);
        message.setAddress(number);
+
alert.setIndicator(indicator);
       
+
        // Obtain the specified text and set it as the payload
+
        String text = smsText.getString();
+
        message.setPayloadText(text);
+
       
+
    }
+
 
</code>
 
</code>
  
After a payload and an address is set to the message, the sending operation takes place inside a thread:
+
As seen from the code above, the alert uses a {{Icode|CommandListener}} for canceling the activity. That requires that we set the Timeout to {{Icode|FOREVER}} so that the end user can only dismiss the alert by clicking on the '''Cancel''' button rather than by tapping anywhere on the screen.
 +
 
 +
== The thread that simulates the progress of the activity==
 +
 
 +
The indicator in this example can be used in connection with measuring the progress of a task with definite range. This means that we know in advance how many steps the task consists of. As examples of tasks with definite ranges can be considered downloading a file whose size is known. The example can be adjusted to the measuring quantity. Here, we assume that a task's range is from 0 up to 100 and consists of 10 steps. The thread pauses for 1 second then increments the value of the indicator by 10 until it reaches 100.  At that point, the application exits the while loop and dismisses the Alert as shown below:
  
 
<code java>
 
<code java>
   
+
public void run() {
        // Send the message on its own thread of execution
+
      try {
        Thread smsThread = new Thread() {
+
int current = indicator.getValue();
        public void run() {
+
//A ten step increment from 0 to 100 in steps of 10
        try {
+
while(current < 100){
        connection.send(message);
+
        current = indicator.getValue();
        mainForm.append("Message sent!\n");
+
indicator.setValue(current + 10);
        }
+
//One second pause between the steps
        catch (InterruptedIOException ex) {
+
Thread.sleep(1000);
        mainForm.append("Interrupted Exception!\n");
+
                }
        }
+
        }
        catch (IOException ex) {
+
        catch (InterruptedException e) {
        mainForm.append("IOException!\n");
+
//Dismisses the alert by interrupting the progress thread
        }  
+
e.printStackTrace();
        catch (IllegalArgumentException ex) {
+
}
        mainForm.append("Illegal Argument!\n");
+
//Displays the original screen and resets the progress bar value
        }  
+
display.setCurrent(mainForm);
        catch (SecurityException ex) {
+
indicator.setValue(0);
        mainForm.append("Security");
+
}
        }
+
        }
+
        };
+
        smsThread.start();
+
       
+
 
</code>
 
</code>
  
In order to send the message, as seen from above, we only need to call the {{Icode|send}} method from the connection instance and pass as argument the TextMessage instance that now contains both a recipient address and a payload.
+
The alert can also be dismissed by clicking on the '''Cancel''' button. The code inside this action, simply interrupts the thread:
 +
 
 +
<code java>
 +
public void commandAction(Command c, Displayable arg1) {
 +
if(c == cancelCommand) {
 +
//Interrupts the thread that moves the progress bar
 +
thread.interrupt();
 +
}
 +
}
 +
</code>
  
 
== See also ==
 
== See also ==

Revision as of 05:29, 7 August 2012

This code example demonstrates how to add an activity indicator to an Alert, that displays the progress for the completion of a process and dismisses itself, when the process is completed.

Contents

Overview

This code example uses two high-level LCDUI components, an Alert and a Gauge. The Alert is manually launched by the end user, while the Gauge is used as activity indicator inside the Alert. The activity indicator describes the progress for completing a 10-step task. The range of the indicator is between 0 and 100, in increments of 10.

Main Components

There are three Commands in this code example. An OK command that launches the Alert and an Exit Command for calling the notifyDestroyed() method, are appended to the Form. A Cancel Command is added to the Alert. The running thread moves the progress indicator every one second in increments of 10. There is also an image that is being displayed inside the alert.

Note.pngNote: In order for the image to be properly displayed with this code, you need to add an image file to the resource directory of your project and rename it to generic_phone.png.

 Form mainForm;
 
//OK and Exit are added to the Form
Command exitCommand = new Command("Exit", Command.EXIT, 0);
Command okCommand = new Command("OK", Command.OK, 0);
 
//Cancel is added to the Alert
Command cancelCommand = new Command("Cancel", Command.CANCEL, 0);
 
//A 1 second per step thread
Thread thread;
Alert alert;
 
//A random image for the alert
Image img;
 
//A bar indicator attached to the alert
Gauge indicator;
 
protected void startApp() throws MIDletStateChangeException {
//The Form's components
mainForm = new Form("Progress Alert");
mainForm.append("Select OK to launch a 10-step process");
mainForm.addCommand(okCommand);
mainForm.addCommand(exitCommand);
mainForm.setCommandListener(this);
display = Display.getDisplay(this);
display.setCurrent(mainForm);

Conditions for adding a Gauge as activity indicator within an Alert

Only under certain conditions, can a high-level Gauge be used within an Alert as activity indicator. The Gauge needs to satisfy the following conditions:

  • it must be non-interactive
  • it must not be owned by another container (Alert or Form)
  • it must not have any Commands
  • it must not have an ItemCommandListener
  • it must not have a label (that is, its label must be null
  • its preferred width and height must both be unlocked, and
  • its layout value must be LAYOUT_DEFAULT.

This practically means that we need to instantiate the Gauge object with null for the first argument that denotes the label and false for the second argument that denotes the boolean that determines whether the Gauge is interactive or not:

indicator = new Gauge(null, false, 100, 0);
alert.setTimeout(Alert.FOREVER);
alert.setCommandListener(this);
alert.setIndicator(indicator);

As seen from the code above, the alert uses a CommandListener for canceling the activity. That requires that we set the Timeout to FOREVER so that the end user can only dismiss the alert by clicking on the Cancel button rather than by tapping anywhere on the screen.

The thread that simulates the progress of the activity

The indicator in this example can be used in connection with measuring the progress of a task with definite range. This means that we know in advance how many steps the task consists of. As examples of tasks with definite ranges can be considered downloading a file whose size is known. The example can be adjusted to the measuring quantity. Here, we assume that a task's range is from 0 up to 100 and consists of 10 steps. The thread pauses for 1 second then increments the value of the indicator by 10 until it reaches 100. At that point, the application exits the while loop and dismisses the Alert as shown below:

public void run() {
try {
int current = indicator.getValue();
//A ten step increment from 0 to 100 in steps of 10
while(current < 100){
current = indicator.getValue();
indicator.setValue(current + 10);
//One second pause between the steps
Thread.sleep(1000);
}
}
catch (InterruptedException e) {
//Dismisses the alert by interrupting the progress thread
e.printStackTrace();
}
//Displays the original screen and resets the progress bar value
display.setCurrent(mainForm);
indicator.setValue(0);
}

The alert can also be dismissed by clicking on the Cancel button. The code inside this action, simply interrupts the thread:

public void commandAction(Command c, Displayable arg1) {
if(c == cancelCommand) {
//Interrupts the thread that moves the progress bar
thread.interrupt();
}
}

See also

99 page views in the last 30 days.
×