Customizing the Spinner Widget

Occasionally while developing, you get the urge to add a little personal flavor in your application. Let’s spice up one of the more under-appreciated widgets on the platform: the spinner.

Since we should be providing the user some visual feedback while waiting on a response from a service/device, many apps make use of the spinner widget. While most developers will choose to leave the spinner as-is, you may want to customize it a bit. Before making the mistake of Googling for animated gif spinners, let’s learn how we can modify the spinner widget to get unique results. Mojo’s built-in spinner widget contains properties that allows us to modify the look and behavior of the spinner. Utilizing this gives us the following benefits:

- Control over when the animation starts/stops
- Frames per second
- Lead-in/lead-out animations
- Any image format can be used

If we take a look at the webOS email application (video preview), we’ll see that it uses a custom skin and a lead-in/out animation for its spinner widget. This is an example of a custom spinner used correctly. Here’s how you can get similar results:

First, we need an image sequence. For this example, let’s use the same style spinner as the email application (download here). What we need to know is that our image sequence needs to be laid out vertically, in a single image. Mojo’s spinner widget will cycle through the image at a defined amount of y-pixels. Since the desired viewable area of our custom spinner will be 26px by 26px, spanning 17 frames total, we will need to create an image that is 26px (width) by 442px (height). Save this image as custom_spinner.png and place it into your application’s “/images” folder.

Now that the hard part is over, let’s add the markup needed to our scene view.

Scene View:

<div x-mojo-element="Spinner" id="image_sequence"></div>

Next, open up your scene assistant and modify the widget attributes that are required when instantiating the spinner.

Scene Assistant:

/*
* Widget attribute properties used
*
* superClass		-> 	CSS class desired
* fps				->	Animation speed (frames-per-second)
* frameHeight		->	Visible area height of the image
* startFrameCount	->	Amount of frames in the lead-in animation
* mainFrameCount	->	Amount of frames in the main animation loop
*/

// Widget attributes
this.sequence_attributes = {
fps: 14,
frameHeight: 26,
startFrameCount: 7,
mainFrameCount: 10,
superClass: "custom_animation"
};

// Widget model
this.sequence_model = { spinning: true };

// Instantiate the spinner
this.controller.setupWidget("image_sequence", this.sequence_attributes, this.sequence_model);

In our widget attributes, we defined a frameHeight property. This tells the spinner how many vertical pixels to move for each “frame” of our animation. The startFrameCount property tells the spinner to start the spinner animation by playing the first 7 frames, then ignore those frames once the main animation loop begins. The mainFrameCount property is the number of frames in our main loop animation. We also defined a superClass property, which is simply the CSS class we want to use in order to style our spinner.

CSS:

.custom_animation {
width: 26px;
height: 26px;
background: url(../images/custom_spinner.png) no-repeat;
}

Now we have a custom spinner with a nifty lead-in animation (video preview).