CSS216 MOBILE PROGRAMMING

Android, Chapter 10

Book: “Professional Android™ 2 Application Development” by Reto Meier, 2010

by: Andrey Bogdanchikov ( andrey.bogdanchikov@sdu.edu.kz )

Outline(Invading the Phone-Top)

• Creating home screen Widgets• Implementing Live Folders• Adding search to your applications• Surfacing search results to the Quick Search Box• Creating Live Wallpaper (self-study)

Introduction• Widgets, Live Folders, Live Wallpaper, and the Quick Search

Box let you own a piece of the user’s home screen, providing either a window to your application or a stand-alone source of information directly on the home screen.

• They’re an exciting innovation for users and developers, providing the following:• ➤ Users get instant access to interesting information without needing

to open an application.• ➤ Developers get an entry point to their applications directly from the

home screen.

• A useful widget, Live Folder, or dynamic wallpaper decreases the chance that an application will be uninstalled, and increases the likelihood of its being used.

Introducing home-screen widgets

Introducing Home-screen widgets• Widgets, more properly AppWidgets, are visual application components that can be added to other applications.

• The most notable example is the default Android home screen, where users can add widgets to their phone-top, though any application you create can become an AppHost and support third-party widgets if you desire.

• Widgets enable your application to own a piece of interactive screen real estate, and an entry point, directly on the user’s home screen. A good App Widget provides useful, concise, and timely information with a minimal resource cost.

Creating app widgets• App Widgets are implemented as IntentReceivers. They use

RemoteViews to update a view hierarchy hosted within another application process; in most cases that host process is the home screen.

• To create a widget for your application you need to create three components:• 1. A layout resource that defines the UI for the widget• 2. An XML definition file that describes the metadata

associated with the widget• 3. An Intent Receiver that defines and controls the

widget

Creating the Widget Layout• The first step in creating your widget is to design and implement its user interface.

• Construct your widget’s UI as you would other visual components in Android, as described in Chapter 4.

• Best practice is to define your widget layout using XML as an external layout resource, but it’s also possible to lay out your UI programmatically within the Intent Receiver’s onCreate method.

Supported Widget Views and Layouts

• In general, the following Views are unavailable for App Widget layouts and will result in a null pointer error (NPE) if used:• All custom Views• Descendants of the allowed Views• EditText

Layouts and Views• Currently, the layouts available are limited to:

• FrameLayout• LinearLayout• RelativeLayout

• The Views they contain are restricted to:• AnalogClock• Button• Chronometer• ImageButton• ImageView• ProgressBar• TextView

Defining Your Widget Settings• Widget definition resources are stored as XML in the res/xml folder of

your project. The appwidget-provider tag lets you describe the widget metadata that defines the size, layout, and update rate for your widget using the following attributes:• ➤ initialLayout The layout resource to use in constructing the

widget’s user interface.• ➤ minWidth / minHeight Respectively, the minimum width and

minimum height of the widget, as described in the previous section.• ➤ label The title used by your widget in the widget-picker.• ➤ updatePeriodMillis The minimum period between widget updates

in milliseconds. Android will wake the device to update your widget at this rate, so you should specify at least an hour. Ideally your widget shouldn’t use this update technique more than once or twice daily.

• ➤ configure You can optionally specify a fully qualified Activity to be launched when your widget is added to the home screen. This Activity can be used to specify widget settings and user preferences.

Example

<?xml version="1.0" encoding="utf-8"?><appwidget-providerxmlns:android="http://schemas.android.com/apk/res/android"

android:initialLayout="@layout/my_widget_layout"android:minWidth="146dp"android:minHeight="146dp"android:label="My App Widget"android:updatePeriodMillis="3600000"/>

Creating Your Widget Intent Receiver and Adding It to the Application Manifest• Widgets are implemented as Intent Receivers with Intent

Filters that catch broadcast Intents, which request widget updates using the AppWidget.ACTION_APPWIDGET_UPDATE, DELETED, ENABLED, and DISABLED actions.

• You can create your widget by extending the IntentReceiver class directly and interpreting those broadcast Intents by overriding the onReceive method.

• The AppWidgetProvider class provides a simplified alternative by encapsulating the Intent processing and presenting you with event handlers for the update, delete, enable, and disable events.

App Widget implementationimport android.appwidget.AppWidgetManager;

import android.appwidget.AppWidgetProvider;

import android.content.Context;

public class MyAppWidget extends AppWidgetProvider {@Overridepublic void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {// TODO Update the Widget UI.

}

}

App Widget manifest node<receiver android:name=".MyAppWidget" android:label="My App Widget"><intent-filter>

<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />

</intent-filter><meta-dataandroid:name="android.appwidget.provider"android:resource="@xml/my_app_widget_info"/>

</receiver>

Introducing Remote Views and the App Widget Manager

• The RemoteViews class is used to describe and manipulate a View hierarchy that’s hosted within another application process. This lets you change a property, or run a method, on a View running as part of another application.

• For example, the Views within App Widgets are hosted within a separate process (generally the home screen), so Remote Views can be used to modify the widget UI from the Intent Receiver running within your application.

• The AppWidgetManager is used to update App Widgets and provide details related to them.

Using Remote ViewsRemoteViews views = new

RemoteViews(context.getPackageName(), R.layout.my_remote_layout);

• To use Remote Views on widgets, call the static getInstance method to return an instance of the App Widget Manager and use it to find identifiers for each instance of a particular widget class,

AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

// Retrieve the identifiers for each instance of your chosen widget.

ComponentName thisWidget = new ComponentName(context, MyAppWidget.class);

int[] appWidgetIds = appWidgetManager.getAppWidgetIds(thisWidget);

//apply modifications to widgets

appWidgetManager.updateAppWidget(appWidgetIds, views);

Making Your Widgets Interactive• You can also add interactivity to your widgets using Remote

Views, but reactions to user input are tightly restricted.• Because they run within the home-screen process, the

widgets themselves inherit its permissions. As a result of these security implications widget interactivity is carefully controlled.

• Widget interaction is generally limited to two possibilities:• Adding a click listener to one or more views within the layout• Changing the UI based on selection changes

• It’s notable that there is no supported technique for entering text directly into an App Widget.

• If you need text input from your widget, best practice is to add a click listener that displays an Activity to accept the user data when a portion of the widget is clicked.

Adding a Click Listener to an App Widget

Intent intent = new Intent("com.paad.ACTION_WIDGET_CLICK");

PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, 0);

views.setOnClickPendingIntent(R.id.my_text_view, pendingIntent);

• Using this technique you can add click handlers to one or more of the Views used within your widget, which means you can add support for multiple actions.

• For example, the standard media player widget assigns different broadcast Intents to several buttons, providing playback control through the play, pause, and next buttons.

Refreshing Your Widgets• Widgets are most commonly displayed on the home screen, so it’s important that they’re always kept relevant and up to date. It’s just as important to balance that relevance with your widget’s impact on system resources — particularly battery life.

• The following sections describe several techniques for managing your widget refresh intervals.

Using the Minimum Update Rate• The simplest, but potentially most resource-intensive,

technique is to set the minimum update rate for a widget in the XML definition file.

• Setting this value will cause the device to broadcast an Intent requesting an update of your widget at the rate specified.

• The host device will wake up to complete these updates, meaning they are completed even when the device is on standby. This has the potential to be a significant resource drain, so it’s very important to consider the implications of your update rate.

Listening for Intents• As widgets are implemented as Intent Receivers you can trigger updates and UI refreshes by registering Intent Filters for additional actions.

• This is a dynamic approach to refreshing your widget that uses a more efficient event model rather than the potentially battery-draining method of specifying a short minimum refresh rate.

Using Alarms• Alarms provide a middle-ground alternative to the polling and

Intent-based techniques described so far.• Alarms, covered in detail in Chapter 9, provide a flexible way

to schedule regular events within your application. Using alarms you can poll at regular intervals, using an Intent to trigger your updates.

• Using Alarms to refresh your widgets is similar to using the Intent-driven model described earlier.

• Add a new Intent Filter to the manifest entry for your widget and override its onReceive method to identify the Intent that triggered it. Within your application, use the Alarm Manager to create an Alarm that fires an Intent with the registered action.

Creating and Using a Widget Configuration Activity

• In some cases an App Widget will be significantly more useful if the user is given the opportunity to customize the data it displays and how the data is displayed. This is particularly important given that multiple instances of the same widget can be added to the home screen.

• An App Widget configuration Activity is an Activity that is launched immediately when a widget is added to the home screen. It can be any Activity within your application, provided it has an Intent Filter for the APPWIDGET_CONFIGURE action, as shown here:

<activity android:name=".MyWidgetConfigurationActivity">

<intent-filter>

<action android:name="android.apwidget.action.APPWIDGET_CONFIGURE"/>

</intent-filter>

</activity>

Return result• It must also return a result Intent that includes an extra that

describes the App Widget ID of the widget it is configuring using the EXTRA_APPWIDGET_ID constant. This extra is included in the Intent that launches the Activity.

Intent result = new Intent();result.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);

setResult(RESULT_OK, result);finish();

Add configuration Activity to xml• To assign a completed configuration Activity to a widget you must

add it to the widget settings file using the configure tag. The activity must be specified by its fully qualified package name, as shown here:

<?xml version="1.0" encoding="utf-8"?><appwidget-providerxmlns:android="http://schemas.android.com/apk/res/android"android:initialLayout="@layout/my_widget_layout"android:minWidth="146dp"android:minHeight="146dp"android:label="My App Widget"android:updatePeriodMillis="3600000"android:configure="com.paad.chapter9.MyWidgetConfigurationActivity"

/>

Introducing live folders

• Live Folders are a unique and powerful means by which your applications can expose data from their Content Providers directly on the home screen. They provide dynamic shortcuts to information stored in your application.

• When added, a Live Folder is represented on the home screen as a shortcut icon. Selecting the icon will open the Live Folder

Creating Live Folders• Live Folders are a combination of two things: a Content

Provider that returns the data required to populate a Live Folder in a standard format, and an Activity that returns an Intent used to generate the Live Folder.

• To create a new Live Folder you need to define:• An Activity responsible for creating and configuring the Live Folder by

generating and returning a specially formatted Intent• A Content Provider that provides the items to be displayed using the

correct column names

• Each Live Folder item can display up to three pieces of information: an icon, a title, and a description.

Example

Live Folder Content Providers• Any Content Provider can provide the data displayed within a

Live Folder. Live Folders use a standard set of column names:• LiveFolders._ID A unique identifier used to indicate which

item was selected if a user clicks the Live Folder list.• LiveFolders.NAME The primary text, displayed in a large

font. This is the only required column.• LiveFolders.DESCRIPTION A longer descriptive field in a

smaller font, displayed beneath the name column.• LiveFolders.IMAGE An image displayed at the left of each

item.

Live Folder Activity• The Live Folder itself is created with an Intent returned as a result from an Activity.

• The Intent’s data property indicates the URI of the Content Provider supplying the data (with the appropriate projection applied), while a series of extras are used to configure settings such as the display mode, icon, and folder name.

• The Live Folder definition Intent is constructed and set as the Activity result, before the Activity is closed with a call to finish.

Adding the Live Folder Intent Filter• When adding your Live Folder Activity to the application

manifest you need to include an Intent Filter for the CREATE_LIVE_FOLDER action

<activity android:name=".MyLiveFolder "

android:label="My Live Folder"><intent-filter><action

android:name="android.intent.action.CREATE_LIVE_FOLDER"/>

</intent-filter>

</activity>

ADDING SEARCH TO YOUR APPLICATIONS AND THE QUICK SEARCH BOX

• With applications featuring large back-end databases and storing large volumes of data, the ability to search for information within an application is an increasingly important feature.

• Android includes a framework to simplify searching within your Content Providers and surfacing the results using a consistent framework.

• This section explains how to add search functionality to your application using this search framework.

Adding Search to Your Application• Most Android devices feature a hardware search key. Using this framework you can expose your application-specific search functionality whenever a user presses the search button.

• The search box will dynamically display search results as the user types a query.

Creating a Search Activity• To enable application search, you must create an Activity that will

be used to initiate and display the search.• The first step is to create a new searchable metadata XML

resource in the res/xml folder. This file specifies the authority of the Content Provider you will be performing the search on, and the action to fire if a suggested search result is clicked.

<searchable xmlns:android="http://schemas.android.com/apk/res/android"

android:label="@string/app_name"

android:searchSuggestAuthority="myauthority"

android:searchSuggestIntentAction="android.intent.action.VIEW">

</searchable>

Registering a search results Activity

<activity android:name=".EarthquakeSearch" android:label="Earthquake Search"><intent-filter>

<action android:name="android.intent.action.SEARCH" /><category

android:name="android.intent.category.DEFAULT" />

</intent-filter><meta-dataandroid:name="android.app.searchable"android:resource="@xml/searchable"/>

</activity>

Get search query• The search query that caused this search result Activity to be

displayed will be returned within the calling Intent using the SearchMananger.USER_QUERY extra as shown in the following:

String searchTerm = getIntent().getStringExtra(SearchManager.USER_QUERY);

• It’s good practice to use the same search results form for your entire application.

• So by use of this techniques your can magnificently improve user access to your content.

• Technical implementation is for your self-study.

THE ENDThank you