Cross-platform HUD progress indicator

The Heads Up Display (HUD) interaction pattern, named after the UIKit UIProgressHUD component, is an effective way to provide progress information to your users. This is especially true for Enterprise mobile apps, as they typically are deeply integrated with backend systems. So the app does not appear sluggish or unresponsive while making these calls. It is recommended to use the Waiting or Progress indicators to provide feedback to the users. This recipe demonstrates how to use an HUD module to present a Waiting indicator to inform your user about the progress of long-running actions in your app.

Getting ready

This chainable CommonJS HUD module, hud.js, provides a native iOS and Android progress indicator experience. This is a simple recipe demonstrating how to use the HUD module. You can use this example to easily incorporate the module into your Titanium project.

Getting ready

Adding the HUD module to your project

Adding the HUD module to your project is easy. Simply copy the hud.js file into the Resources folder of your project, as shown in the following screenshot:

Adding the HUD module to your project

Once you've added the hud.js file to your project, you need to use require to import the module into your code:

//Create our application namespace
var my = {
    hud : require('hud'),
    isAndroid : Ti.Platform.osname === 'android'
};

Creating a sample window

To demonstrate the HUD module, we create a basic window with a single button. To do this, first we create a Ti.UI.Window and attach a button:

var win = Ti.UI.createWindow({
  backgroundColor:'yellow'
});

var hudButton = Ti.UI.createButton({
  title:'Show HUD', height:50, right:5, left:5, bottom: 40
});
win.add(hudButton);

Adding HUD listeners

Next in our example, we add a series of listeners. The following code block demonstrates how to add a listener, to be fired when the HUD window is closed:

my.hud.addEventListener('close',function(e){
  Ti.API.info('HUD Window Closed'),
});
  1. You can also listen to an open event, which will fire when the HUD window is opened:
    my.hud.addEventListener('open',function(e){
  Ti.API.info('HUD Window Open'),
});
  2. The dblclick event is fired when the user double taps on the HUD window:
    my.hud.addEventListener(dblclick,function(e){
  Ti.API.info('HUD Window double clicked'),
});
  3. The hudTextChanged event is fired whenever updateMessage is called to update the HUD window message:
    my.hud.addEventListener('hudTextChanged',function(e){
  Ti.API.info('Text Changed from ' + e.oldValue + ' to ' + e.newValue);
});
  4. If you are using the Close Timer functionality, it is helpful to know if your window is being closed by the timer or by some other method. To help determine this, you can subscribe to the timerClose event, as shown in the following snippet:
    my.hud.addEventListener('timerClose',function(e){
  Ti.API.info('HUD Window Closed by Timer'),
});

Creating a HUD indicator

We can now use the button created earlier, to demonstrate how to show the HUD window. To the click handler of the button we've added logic to load the HUD module with the message text, Please Wait.... Then we call the show method, which displays the HUD window to the user.

hudButton.addEventListener('click',function(e){
  win.navBarHidden=true;
  my.hud.load('Please Wait...').show();
});

Tip

On Android, you might wish to hide the navigation bar so that the HUD window can take up the entire screen. If you don't hide the navigation bar, the HUD module will set the window title to the same text as provided for the HUD display message.

Updating the HUD message

By calling the updateMessage function, you can update the HUD window text at any time. The following line demonstrates how to update the text from Please Wait... to Still waiting....

my.hud.updateMessage('Still waiting...'),

Closing the HUD window

There are two ways to close the HUD module window. The first and most common way is to call the hide function, as shown here:

my.hud.hide();

The second way to close the HUD window is to use the addCloseTimer function on the HUD module before the show function is called, as highlighted in the following snippet. In this example, the HUD window will close after 5,000 milliseconds.

my.hud.load('Please Wait...').addCloseTimer(5000).show();

Tip

The addCloseTimer function is helpful in dealing with timeout situations. For example, when making network calls you might wish to abandon the process after five seconds so as not to keep the user waiting too long.

How it works…

The HUD module provides a series of functions to create, update, and maintain the HUD progress window. The following list provides a description of each method along with their associated functionalities:

  • The load function: This is called to build the Ti.UI.Window, Ti.UI.ActivityIndicator, and Ti.UI.Label, that will later be used to display your progress indicator. Please note you will need to first call the load function, followed by the show function, to display the HUD window.
  • The show function: This displays the HUD window. Please note you first need to call the load method before calling show. If this is done out of sequence, the HUD window will not appear.
  • The updateMessage function: To update the HUD label, you call this function, providing a string with the updated text to be displayed.
  • The hide function: Calling this will close the HUD window and remove all of the HUD objects created.
  • The addCloseTimer function: You use this function to set a timer that will close the HUD window after the provided duration (in milliseconds).
  • The removeCloseTimer function: You use this function to close the timer that you set using addCloseTimer.
  • The addEventListener function: The HUD module supports several events as detailed in the next section. You can subscribe to these events using this function.
  • The removeEventListener function: Any events you have subscribed to, can be removed by calling this function. To remove an event, you need to provide the same name and callback arguments as you used while calling addEventListener.

    Tip

    All functions in the HUD module are chainable, similar to jQuery functions.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.191.212.246