1738 RICH TEXT However, do bear in mind that these are undocumented and therefore are subject to change. Also note that fromHtml() is perhaps slower than you might think, particularly for longer strings. You might also wind up using some other support code to get your HTML. For example, some data sources might publish text formatted as Markdown — Stack Overflow, GitHub, etc. use this extensively. Markdown can be converted to HTML, through any number of available Java libraries or via CWAC-AndDown, which wraps the native hoedown Markdown-to-HTML converter for maximum speed. CWACAndDown will be explored in a bit more detail in the chapter on the NDK. From EditText The reason why so much sample code calls getText() followed by toString() on an EditText widget is because EditText is going to return an Editable object from getText(), not a simple string. That’s because, in theory, EditText could be returning something with formatting applied. The call to toString() simply strips out any potential formatting as part of giving you back a String. However, you could elect to use the Editable object (presumably a SpannableStringBuilder) if you wanted, such as for pouring the entered text into a TextView, complete with any formatting that might have wound up on the entered text. Actually getting formatting applied to the contents of an EditText is covered later in this chapter. Manually You are welcome to create a SpannableString via its constructor, supplying the text that you wish to display, then calling various methods on SpannableString to format it. We will see an example of this later in this chapter. Or, you are welcome to create a SpannableStringBuilder via its constructor. In some respects, SpannableStringBuilder works like the classic StringBuilder — you call append() to add more text. However, SpannableStringBuilder also offers delete(), insert(), and replace() methods to modify portions of the existing content. It also supports the same methods that SpannableString does, via the Spannable interface, for applying formatting rules to portions of text. 1739 RICH TEXT Editing Rich Text If the Spannable you wound up with is a SpannedString, it is what it is — you cannot change it. If, however, you have a SpannableString, that can be modified by you, or by the user. Of course, allowing the user to modify a Spannable gets a wee bit tricky, and is why the RichEditText project was born. RichEditText If you load a Spannable into an EditText, the formatting will not only be displayed, but it will be part of the editing experience. For example, if the phrase “the fox jumped” is in bold, and the user adds in more words to make it “the quick brown fox jumped”, the additional words will also be in boldface. That is because the user is modifying text in the middle of a defined span, and so therefore the adjusted text is rendered according to that span. The biggest problem is that EditText alone has no mechanism to allow users to change formatting. Perhaps someday it will have options for that. In the meantime, though, RichEditText is designed to fill that gap. RichEditText is a CWAC project that offers a reasonably convenient API for applying, toggling, or removing effects applied to the current selected text. You have your choice of creating your own UI for this (e.g., implementing a toolbar) or enabling an extension to the EditText action modes to allow the users to format the text. More information on using RichEditText can be found on the project site. Manually Spannable offers two methods for modifying its formatting: setSpan() to apply formatting, and removeSpan() to get rid of an existing span. And, since Spannable extends Spanned, a Spannable also has getSpans(), to return existing spans of a current type within a certain range of characters in the text. These methods, along with others on Spanned, allow you to get and set whatever formatting you wish to apply on a Spannable object, such as a SpannableString. For example, let’s take a look at the RichText/Search sample project. Here, we are going to load some text into a TextView, then allow the user to enter a search string 1740 RICH TEXT in an EditText, and we will use the Spannable methods to highlight the search string occurrences inside the text in the TextView. Our layout is simply an EditText atop a TextView (wrapped in a ScrollView): > > > /> (from RichText/Search/app/src/main/res/layout/main.xml) We pre-fill the TextView with a string resource (@string/address), which in this project is the text of Lincoln’s Gettysburg Address, with a bit of inline markup (e.g., “Four score and seven years ago” italicized). So, when we fire up the project at the outset, we see the formatted prose from the string resource: 1741 RICH TEXT Figure 564: The RichTextSearch sample, as initially launched In onCreate() of our activity, we find the EditText widget and designate the activity itself as being an OnEditorActionListener for the EditText: @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.main); search=(EditText)findViewById(R.id.search); search.setOnEditorActionListener(this this); } (from RichText/Search/app/src/main/java/com/commonsware/android/rich/search/RichTextSearchActivity.java) That means when the user presses , we will get control in an onEditorAction() method. There, we pass the search text to a private searchFor() method, plus ensure that the input method editor is hidden (if one was used to fill in the search text): @Override public boolean onEditorAction(TextView v, int actionId, KeyEvent event) { if (event == null || event.getAction() == KeyEvent.ACTION_UP) { 1742 RICH TEXT searchFor(search.getText().toString()); InputMethodManager imm= (InputMethodManager)getSystemService(INPUT_METHOD_SERVICE); imm.hideSoftInputFromWindow(v.getWindowToken(), 0); } return return(true true); } (from RichText/Search/app/src/main/java/com/commonsware/android/rich/search/RichTextSearchActivity.java) The searchFor() method is where the formatting is applied to our search text: private void searchFor(String text) { TextView prose=(TextView)findViewById(R.id.prose); Spannable raw=new new SpannableString(prose.getText()); BackgroundColorSpan[] spans=raw.getSpans(0, raw.length(), BackgroundColorSpan.class); for (BackgroundColorSpan span : spans) { raw.removeSpan(span); } int index=TextUtils.indexOf(raw, text); while (index >= 0) { raw.setSpan(new new BackgroundColorSpan(0xFF8B008B), index, index + text.length(), Spanned.SPAN_EXCLUSIVE_EXCLUSIVE); index=TextUtils.indexOf(raw, text, index + text.length()); } prose.setText(raw); } (from RichText/Search/app/src/main/java/com/commonsware/android/rich/search/RichTextSearchActivity.java) First, we get a Spannable object out of the TextView. While an EditText returns an Editable from getText(), getText() on a TextView returns a CharSequence. In particular, the first time we execute searchFor(), getText() will return a SpannedString, as that is what a string resource turns into. However, that is not modifiable, so we convert it into a SpannableString so we can apply formatting to it. An optimization would be to see if getText() returns something implementing Spannable and then just using it directly. 1743 RICH TEXT We want to highlight the search terms using a BackgroundColorSpan. However, that means we first need to get rid of any existing BackgroundColorSpan objects applied to the prose from a previous search — otherwise, we would keep highlighting more and more of the prose. So, we use getSpans() to find all BackgroundColorSpan objects anywhere in the prose (from index 0 through the length of the text). For each that we find, we call removeSpan() to get rid of it from our Spannable. Then, we use indexOf() on TextUtils to find the first occurrence of whatever the user typed into the EditText. If we find it, we create a new BackgroundColorSpan and apply it to the matching portion of the prose using setSpan(). The last parameter to setSpan() is a flag, indicating what should happen if text is inserted at either the starting or ending point. In our case, the text itself is remaining constant, so the flag does not matter much – here, we use SPAN_EXCLUSIVE_EXCLUSIVE, which would mean that the span would not cover any text inserted at the starting or ending point of the span. We then continue using indexOf() to find any remaining occurrences of the search text. Once we are done modifying our Spannable, we put it into the TextView via setText(). The result is that all matching substrings are highlighted in a purple/magenta shade: 1744 RICH TEXT Figure 565: The RichTextSearch sample, after searching on “can” Saving Rich Text SpannableString and SpannedString are not Serializable. There is no built-in way to persist them directly. However, Html.toHtml() will convert a Spanned object into corresponding HTML, for all CharacterStyle and ParagraphStyle objects that can be readily converted into HTML. You can then persist the resulting HTML any place you would persist a String (e.g., database column). In principle, you could create other similar conversion code, such as something to take a Spanned and return the corresponding Markdown source. Manipulating Rich Text The TextUtils class has many utility methods that manipulate a CharSequence, to allow you to do things that you might ordinarily have done just with methods on String. These utility methods will work with any CharSequence, including SpannedString and SpannableString. 1745 RICH TEXT Some are specifically aimed at Spanned objects, such as copySpansFrom() (to apply formatting from one CharSequence onto another). Some are clones of String equivalents, such as split(), join(), and substring(). Yet others are designed for developers using the Canvas 2D drawing API, such as ellipsize() and commaEllipsize() for intelligently truncating messages. 1746 Animators Users like things that move. Or fade, spin, or otherwise offer a dynamic experience. Much of the time, such animations are handled for us by the framework. We do not have to worry about sliding rows in a ListView when the user scrolls, or as the user pans around a ViewPager, and so forth. However, sometimes, we will need to add our own animations, where we want effects that either are not provided by the framework innately or are simply different (e.g., want something to slide off the bottom of the screen, rather than off the left edge). Android had an animation framework back in the beginning, one that is still available for you today. However, Android 3.0 introduced a new animator framework that is going to be Android’s primary focus for animated effects going forward. Many, but not all, of the animator framework capabilities are available to us as developers via a backport. Prerequisites Understanding this chapter requires that you have read the core chapters of this book. Also, you should read the chapter on custom views, to be able to make sense of one of the samples. ViewPropertyAnimator Let’s say that you want to fade out a widget, instead of simply setting its visibility to INVISIBLE or GONE. 1747 ANIMATORS For a widget whose name is v, on API Level 11 or higher, that is as simple as: v.animate().alpha(0); Here, “alpha” refers to the “alpha channel”. An alpha of 1 is normal opacity, while an alpha of 0 is completely transparent, with values in between representing various levels of translucence. That may seem rather simple. The good news is, it really is that easy. Of course, there is a lot more you can do here, and you might have to worry about supporting older Android versions, and we need to think about things other than fading widgets in and out, and so forth. First, though, let’s consider what is really going on when we call animate() on a widget on API Level 11+. Native Implementation The call to animate() returns an instance of ViewPropertyAnimator. This object allows us to build up a description of an animation to be performed, such as calling alpha() to change the alpha channel value. ViewPropertyAnimator uses a so-called fluent interface, much like the various builder classes (e.g., Notification.Builder) — calling a method on a ViewPropertyAnimator() usually returns the ViewPropertyAnimator itself. This allows you to build up an animation via a chained series of method calls, starting with that call to animate() on the widget. You will note that we do not end the chain of method calls with something like a start() method. ViewPropertyAnimator will automatically arrange to start the animation once we return control of the main application thread back to the framework. Hence, we do not have to explicitly start the animation. You will also notice that we did not indicate any particulars about how the animation should be accomplished, beyond stating the ending alpha channel value of 0. ViewPropertyAnimator will use some standard defaults for the animation, such as a default duration, to determine how quickly Android changes the alpha value from its starting point to 0. Most of those particulars can be overridden from their defaults via additional methods called on our ViewPropertyAnimator, such as setDuration() to provide a duration in milliseconds. There are four standard animations that ViewPropertyAnimator can perform: 1748 ANIMATORS 1. Changes in alpha channel values, for fading widgets in and out 2. Changes in widget position, by altering the X and Y values of the upper-left corner of the widget, from wherever on the screen it used to be to some new value 3. Changes in the widget’s rotation, around any of the three axes 4. Changes in the widget’s size, where Android can scale the widget by some percentage to expand or shrink it We will see an example of changing a widget’s position, using the translationXBy() method, later in this chapter. You are welcome to use more than one animation effect simultaneously, such as using both alpha() and translationXBy() to slide a widget horizontally and have it fade in or out. There are other aspects of the animation that you can control. By default, the animation happens linearly — if we are sliding 500 pixels in 500ms, the widget will move evenly at 1 pixel/ms. However, you can specify a different “interpolator” to override that default linear behavior (e.g., start slow and accelerate as the animation proceeds). You can attach a listener object to find out about when the animation starts and ends. And, you can specify withLayer() to indicate that Android should try to more aggressively use hardware acceleration for an animation, a concept that we will get into in greater detail later in this chapter. To see this in action, take a look at the Animation/AnimatorFade sample app. The app consists of a single activity (MainActivity). It uses a layout that is dominated by a single TextView widget, whose ID is fadee: > /> 1749 ANIMATORS (from Animation/AnimatorFade/app/src/main/res/layout/activity_main.xml) In onCreate(), we load up the layout and get our hands on the fadee widget: @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); fadee=(TextView)findViewById(R.id.fadee); } (from Animation/AnimatorFade/app/src/main/java/com/commonsware/android/animator/fade/MainActivity.java) MainActivity itself implements Runnable, and our run() method will perform some animated effects: @Override public void run() { if (fadingOut) { fadee.animate().alpha(0).setDuration(PERIOD); fadee.setText(R.string.fading_out); } else { fadee.animate().alpha(1).setDuration(PERIOD); fadee.setText(R.string.coming_back); } fadingOut=!fadingOut; fadee.postDelayed(this this, PERIOD); } (from Animation/AnimatorFade/app/src/main/java/com/commonsware/android/animator/fade/MainActivity.java) Specifically, we use ViewPropertyAnimator to fade out the TextView over a certain period (fadee.animate().alpha(0).setDuration(PERIOD);) and set its caption to a value indicating that we are fading out. If we are to be fading back in, we perform the opposite animation and set the caption to a different value. We then flip the fadingOut boolean for the next pass and use postDelayed() to reschedule ourselves to run after the period has elapsed. 1750 ANIMATORS To complete the process, we run() our code initially in onStop() and cancel the postDelayed() loop in onStart(): @Override public void onStart() { super super.onStart(); run(); } @Override public void onStop() { fadee.removeCallbacks(this this); super super.onStop(); } (from Animation/AnimatorFade/app/src/main/java/com/commonsware/android/animator/fade/MainActivity.java) The result is that the TextView smoothly fades out and in, alternating captions as it goes. However, it would be really unpleasant if all this animator goodness worked only on API Level 11+. Fortunately for us, somebody wrote a backport. Backport Via NineOldAndroids Jake Wharton wrote NineOldAndroids. This is, in effect, a backport of ViewPropertyAnimator and its underpinnings. There are some slight changes in how you use it, because NineOldAndroids is simply a library. It cannot add methods to existing classes (like adding animate() to View), nor can it add capabilities that the underlying firmware simply lacks. But, it may cover many of your animator needs, even if the name is somewhat inexplicable, and it works going all the way back to API Level 1, ensuring that it will cover any Android release that you care about. NineOldAndroids is an Android library project. Android Studio users can add a implementation statement to their dependencies closure in build.gradle to pull in com.nineoldandroids:library:... (for some version indicated by ...). Since NineOldAndroids cannot add animate() to View, the recommended approach is to use a somewhat obscure feature of Java: imported static methods. An import static statement, referencing a particular static method of a class, makes that method available as if it were a static method on the class that you are writing, or as 1751 ANIMATORS some sort of global function. NineOldAndroids has an animate() method that you can import this way, so instead of v.animate(), you use animate(v) to accomplish the same end. Everything else is the same, except perhaps some imports, to reference NineOldAndroids instead of the native classes. You can see this in the Animation/AnimatorFadeBC sample app. In addition to having the NineOldAndroids JAR in libs/, the only difference between this edition and the previous sample is in how the animation is set up. Instead of lines like: fadee.animate().alpha(0).setDuration(PERIOD); we have: animate(fadee).alpha(0).setDuration(PERIOD); This takes advantage of our static import: import static com.nineoldandroids.view.ViewPropertyAnimator.animate; If the static import makes you queasy, you are welcome to simply import the com.nineoldandroids.view.ViewPropertyAnimator class, rather than the static method, and call the animate() method on ViewPropertyAnimator: ViewPropertyAnimator.animate(fadee).alpha(0).setDuration(PERIOD); The Foundation: Value and Object Animators ViewPropertyAnimator itself is a layer atop of a more primitive set of animators, known as value and object animators. A ValueAnimator handles the core logic of transitioning some value, from an old to a new value, over a period of time. ValueAnimator offers replaceable “interpolators”, which will determine how the values change from start to finish over the animation period (e.g., start slowly, accelerate, then end slowly). ValueAnimator also handles the concept of a “repeat mode”, to indicate if the animation should simply happen once, a fixed number of times, or should infinitely repeat (and, in the latter cases, whether it does so always transitioning from start to finish or if it reverses direction on alternate passes, going from finish back to start). 1752 ANIMATORS What ValueAnimator does not do is actually change anything. It is merely computing the different values based on time. You can call getAnimatedValue() to find out the value at any point in time, or you can call addUpdateListener() to register a listener object that will be notified of each change in the value, so that change can be applied somewhere. Hence, what tends to be a bit more popular is ObjectAnimator, a subclass of ValueAnimator that automatically applies the new values. ObjectAnimator does this by calling a setter method on some object, where you supply the object and the “property name” used to derive the getter and setter method names. For example, if you request a property name of foo, ObjectAnimator will try to call getFoo() and setFoo() methods on your supplied object. As with ViewPropertyAnimator, ValueAnimator and ObjectAnimator are implemented natively in API Level 11 and are available via the NineOldAndroids backport as well. To see what ObjectAnimator looks like in practice, let us examine the Animation/ ObjectAnimator sample app. Once again, our activity’s layout is pretty much just a centered TextView, here named word: > /> (from Animation/ObjectAnimator/app/src/main/res/layout/activity_main.xml) The objective of our activity is to iterate through 25 words, showing one at a time in the TextView: 1753 ANIMATORS package com.commonsware.android.animator.obj; import import import import import android.app.Activity android.app.Activity; android.os.Bundle android.os.Bundle; android.widget.TextView android.widget.TextView; com.nineoldandroids.animation.ObjectAnimator com.nineoldandroids.animation.ObjectAnimator; com.nineoldandroids.animation.ValueAnimator com.nineoldandroids.animation.ValueAnimator; public class MainActivity extends Activity { private static final String[] items= { "lorem", "ipsum", "dolor", "sit", "amet", "consectetuer", "adipiscing", "elit", "morbi", "vel", "ligula", "vitae", "arcu", "aliquet", "mollis", "etiam", "vel", "erat", "placerat", "ante", "porttitor", "sodales", "pellentesque", "augue", "purus" }; private TextView word=null null; int position=0; @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); word=(TextView)findViewById(R.id.word); ValueAnimator positionAnim = ObjectAnimator.ofInt(this this, "wordPosition", 0, 24); positionAnim.setDuration(12500); positionAnim.setRepeatCount(ValueAnimator.INFINITE); positionAnim.setRepeatMode(ValueAnimator.RESTART); positionAnim.start(); } public void setWordPosition(int position) { this this.position=position; word.setText(items[position]); } public int getWordPosition() { return return(position); } } (from Animation/ObjectAnimator/app/src/main/java/com/commonsware/android/animator/obj/MainActivity.java) To accomplish this, we use NineOldAndroids version of ObjectAnimator, saying that we wish to “animate” the wordPosition property of the activity itself, from 0 to 24. We configure the animation to run for 12.5 seconds (i.e., 500ms per word) and to repeat indefinitely by restarting the animation from the beginning on each pass. We then call start() to kick off the animation. For this to work, though, we need getWordPosition() and setWordPosition() accessor methods for the theoretical wordPosition property. In our case, the “word position” is simply an integer data member of the activity, which we return in getWordPosition() and update in setWordPosition(). However, we also update the TextView in setWordPosition(), to display the word at that position. 1754 ANIMATORS The net effect is that words appear in our TextView, changing on average every 500ms. Animating Custom Types In the previous section, we animated an int property of an Activity. That works, because Android knows how to compute int values between the start and end position, through simple math. But, what if we wanted to animate something that is not a simple number? For example, what if we want to animate a Color, or a LatLng from Maps V2, or a TastyTreat class of our own design? So long as we can perform the calculations, we can animate a type of anything we want, using TypeEvaluator and ofObject() on ObjectAnimator. A TypeEvaluator is a simple interface, containing a single method that we need to override: evaluate(). However, TypeEvaluator uses generics, and so our implementation will actually be of some concrete class (e.g., a TypeEvaluator of TastyTreat). Our job in evaluate() is to return a value of our designated type (e.g., TastyTreat) given three inputs: 1. The initial value for our animation range, in the form of our designated type 2. The end value for our animation range, in the form of our designated type 3. The fraction along that range that represents how much we have moved from the initial value to the end value Note that the fraction is not limited to being between 0 and 1, as certain interpolators (e.g., an overshoot interpolator) might result in a fraction being negative (e.g., we overshot past the initial value) or greater than one (e.g., we overshot past the end value). For example, to have a TypeEvaluator of Color, we might have evaluate() generate a new Color instance based upon applying the fraction to the initial and end red, green, blue, and alpha channels. To use a TypeEvaluator, instead of ofInt(), ofFloat(), or similar simple factory methods on ObjectAnimator, we use ofObject(). ofObject() takes the object to be animated, the property to be animated, the TypeEvaluator to assist in the actual 1755 ANIMATORS animation, and the final value of the animation (or, optionally, a series of waypoints to be animated along). A flavor of ofObject() that takes the property name — akin to the wordPosition ofInt() used in the previous section — has been around since API Level 11. API Level 14 added an ofObject() method that takes a Property value instead of the name of the property. This version has the added benefit of type-safety, as it can ensure that your object to be animated, TypeEvaluator, and final position are all of the same type. You can see an example of using TypeEvaluator this way in the chapter on Maps V2, as we animate the movement of a map marker from a starting point to an ending point. Hardware Acceleration Animated effects operate much more smoothly with hardware acceleration. There are two facets to employing hardware acceleration for animations: enabling it overall and directing its use for the animations themselves. Hardware acceleration is enabled overall on Android devices running Android 4.0 or higher (API Level 14). On Android 3.x, hardware acceleration is available but is disabled by default — use android:hardwareAccelerated="true" in your or element in the manifest to enable it on those versions. Hardware acceleration for 2D graphics operations like widget animations is not available on older versions of Android. While this will provide some benefit across the board, you may also wish to consider rendering animated widgets or containers in an off-screen buffer, or “hardware layer”, that then gets applied to the screen via the GPU. In particular, the GPU can apply certain animated transformations to a hardware layer without forcing software to redraw the widgets or containers (e.g., what happens when you invalidate() them). As it turns out, these GPU-enhanced transformations match the ones supported by ViewPropertyAnimator: 1. Changes in alpha channel values, for fading widgets in and out 2. Changes in widget position, by altering the X and Y values of the upper-left corner of the widget, from wherever on the screen it used to be to some new value 3. Changes in the widget’s rotation, around any of the three axes 1756 ANIMATORS 4. Changes in the widget’s size, where Android can scale the widget by some percentage to expand or shrink it By having the widget be rendered in a hardware layer, these ViewPropertyAnimator operations are significantly more efficient than before. However, since hardware layers take up video memory, generally you do not want to keep a widget or container in a hardware layer indefinitely. Instead, the recommended approach is to have the widget or container be rendered in a hardware layer only while the animation is ongoing, by calling setLayerType() for LAYER_TYPE_HARDWARE before the animation begins, then calling setLayerType() for LAYER_TYPE_NONE (i.e., return to default behavior) when the animation completes. Or, for ViewPropertyAnimator on API Level 16 and higher, use withLayer() in the fluent interface to have it apply the hardware layer automatically just for the animation duration. We will see examples of using hardware acceleration this way in the next section. The Three-Fragment Problem The original tablet implementation of Gmail organized its landscape main activity into two panes, one on the left taking up ~30% of the screen, and one on the right taking up the remainder: Figure 566: Gmail Fragments (image courtesy of Google and AOSP) Gmail had a very specific navigation mode in its main activity when viewed in landscape on a tablet, where upon some UI event (e.g., tapping on something in the right-hand area): • The original left-hand fragment (Fragment A) slid off the screen to the left 1757 ANIMATORS • The original right-hand fragment (Fragment B) slid to the left edge of the screen and shrunk to take up the spot vacated by Fragment A • Another fragment (Fragment C) slid in from the right side of the screen and expanded to take up the spot vacated by Fragment B And a BACK button press reversed this operation. This is a bit tricky to set up, leading to the author of this book posting a question on Stack Overflow to get input. Here, we will examine one of the results of that discussion, based in large part on the implementation of the AOSP Email app, which has a similar navigation flow. The other answers on that question may have merit in other scenarios as well. You can see one approach for implementing the three-pane solution in the Animation/ThreePane sample app. The ThreePaneLayout The logic to handle the animated effects is encapsulated in a ThreePaneLayout class. It is designed to be used in a layout XML resource where you supply the contents of the three panes, sizing the first two as you want, with the third “pane” having zero width at the outset: > /> /> /> (from Animation/ThreePane/app/src/main/res/layout/activity_main.xml) 1758 ANIMATORS ThreePaneLayout itself is a subclass of LinearLayout, set up to always be horizontal, regardless of what might be set in the layout XML resource. public ThreePaneLayout(Context context, AttributeSet attrs) { super super(context, attrs); initSelf(); } void initSelf() { setOrientation(HORIZONTAL); } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/ThreePaneLayout.java) When the layout finishes inflating, we grab the three panes (defined as the first three children of the container) and stash them in data members named left, middle, and right, with matching getter methods: @Override public void onFinishInflate() { super super.onFinishInflate(); left=getChildAt(0); middle=getChildAt(1); right=getChildAt(2); } public View getLeftView() { return return(left); } public View getMiddleView() { return return(middle); } public View getRightView() { return return(right); } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/ThreePaneLayout.java) The major operational API, from the standpoint of an activity using ThreePaneLayout, is hideLeft() and showLeft(). hideLeft() will switch from showing the left and middle widgets in their original size and position to showing the middle and right widgets wherever left and middle had been originally. showLeft() reverses the operation. 1759 ANIMATORS The problem is that, initially, we do not know where the widgets are or how big they are, as that should be able to be set from the layout XML resource and are not known until the ThreePaneLayout is actually applied to the screen. Hence, we lazyretrieve those values in hideLeft(), plus remove any weights that had been originally defined, setting the actual pixel widths on the widgets instead: public void hideLeft() { if (leftWidth == -1) { leftWidth=left.getWidth(); middleWidthNormal=middle.getWidth(); resetWidget(left, leftWidth); resetWidget(middle, middleWidthNormal); resetWidget(right, middleWidthNormal); requestLayout(); } translateWidgets(-1 * leftWidth, left, middle, right); ObjectAnimator.ofInt(this this, "middleWidth", middleWidthNormal, leftWidth).setDuration(ANIM_DURATION).start(); } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/ThreePaneLayout.java) The work to change the weights into widths is handled in resetWidget(): private void resetWidget(View v, int width) { LinearLayout.LayoutParams p= (LinearLayout.LayoutParams)v.getLayoutParams(); p.width=width; p.weight=0; } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/ThreePaneLayout.java) After the lazy-initialization and widget cleanup, we perform the two animations. translateWidgets() will slide each of our three widgets to the left by the width of the left widget, using a ViewPropertyAnimator and a hardware layer: private void translateWidgets(int deltaX, View... views) { for (final final View v : views) { v.setLayerType(View.LAYER_TYPE_HARDWARE, null null); v.animate().translationXBy(deltaX).setDuration(ANIM_DURATION) .setListener(new new AnimatorListenerAdapter() { 1760 ANIMATORS @Override public void onAnimationEnd(Animator animation) { v.setLayerType(View.LAYER_TYPE_NONE, null null); } }); } } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/ThreePaneLayout.java) The resize animation — to set the middle size to be what left had been – is handled via an ObjectAnimator, for a theoretical property of middleWidth on ThreePaneLayout. That is backed by a setMiddleWidth() method that adjusts the width property of the middle widget’s LayoutParams and triggers a redraw: @SuppressWarnings("unused") private void setMiddleWidth(int value) { middle.getLayoutParams().width=value; requestLayout(); } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/ThreePaneLayout.java) The showLeft() method simply performs those two animations in reverse: public void showLeft() { translateWidgets(leftWidth, left, middle, right); ObjectAnimator.ofInt(this this, "middleWidth", leftWidth, middleWidthNormal).setDuration(ANIM_DURATION) .start(); } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/ThreePaneLayout.java) Using the ThreePaneLayout The sample app uses one activity (MainActivity) and one fragment (SimpleListFragment) to set up and use the ThreePaneLayout. The objective is a UI that roughly mirrors that of the AOSP Email app: a list on the left, a list in the middle (whose contents are based on the item chosen in the left list), and something else on the right (whose contents are based on the item chosen in the middle list). 1761 ANIMATORS SimpleListFragment is used for both lists. Its newInstance() factory method is handed the list of strings to display. SimpleListFragment just loads those into its ListView, also setting up CHOICE_MODE_SINGLE for use with the activated style, and routing all clicks on the list to the MainActivity that hosts the fragment: package com.commonsware.android.anim.threepane; import import import import import import import android.app.ListFragment android.app.ListFragment; android.os.Bundle android.os.Bundle; android.view.View android.view.View; android.widget.ArrayAdapter android.widget.ArrayAdapter; android.widget.ListView android.widget.ListView; java.util.ArrayList java.util.ArrayList; java.util.Arrays java.util.Arrays; public class SimpleListFragment extends ListFragment { private static final String KEY_CONTENTS="contents"; public static SimpleListFragment newInstance(String[] contents) { return return(newInstance(new new ArrayList(Arrays.asList(contents)))); } public static SimpleListFragment newInstance(ArrayList contents) { SimpleListFragment result=new new SimpleListFragment(); Bundle args=new new Bundle(); args.putStringArrayList(KEY_CONTENTS, contents); result.setArguments(args); return return(result); } @Override public void onActivityCreated(Bundle savedInstanceState) { super super.onActivityCreated(savedInstanceState); getListView().setChoiceMode(ListView.CHOICE_MODE_SINGLE); setContents(getArguments().getStringArrayList(KEY_CONTENTS)); } @Override public void onListItemClick(ListView l, View v, int position, long id) { ((MainActivity)getActivity()).onListItemClick(this this, position); } void setContents(ArrayList contents) { setListAdapter(new new ArrayAdapter( 1762 ANIMATORS getActivity(), R.layout.simple_list_item_1, contents)); } } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/SimpleListFragment.java) MainActivity populates the left FrameLayout with a SimpleListFragment in onCreate(), if the fragment does not already exist (e.g., from a configuration change). When an item in the left list is clicked, MainActivity populates the middle FrameLayout. When an item in the middle list is clicked, it sets the caption of the right Button and uses hideLeft() to animate that Button onto the screen, hiding the left list. If the user presses BACK, and our left list is not showing, MainActivity calls showLeft() to reverse the animation: package com.commonsware.android.anim.threepane; import import import import android.app.Activity android.app.Activity; android.os.Bundle android.os.Bundle; android.widget.Button android.widget.Button; java.util.ArrayList java.util.ArrayList; public class MainActivity extends Activity { private static final String KEY_MIDDLE_CONTENTS="middleContents"; private static final String[] items= { "lorem", "ipsum", "dolor", "sit", "amet", "consectetuer", "adipiscing", "elit", "morbi", "vel", "ligula", "vitae", "arcu", "aliquet", "mollis", "etiam", "vel", "erat", "placerat", "ante", "porttitor", "sodales", "pellentesque", "augue", "purus" }; private boolean isLeftShowing=true true; private SimpleListFragment middleFragment=null null; private ArrayList middleContents=null null; private ThreePaneLayout root=null null; @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); root=(ThreePaneLayout)findViewById(R.id.root); if (getFragmentManager().findFragmentById(R.id.left) == null null) { getFragmentManager().beginTransaction() .add(R.id.left, SimpleListFragment.newInstance(items)) .commit(); 1763 ANIMATORS } middleFragment= (SimpleListFragment)getFragmentManager().findFragmentById(R.id.middle); } @Override public void onBackPressed() { if (!isLeftShowing) { root.showLeft(); isLeftShowing=true true; } else { super super.onBackPressed(); } } @Override protected void onSaveInstanceState(Bundle outState) { super super.onSaveInstanceState(outState); outState.putStringArrayList(KEY_MIDDLE_CONTENTS, middleContents); } @Override protected void onRestoreInstanceState(Bundle inState) { middleContents=inState.getStringArrayList(KEY_MIDDLE_CONTENTS); } void onListItemClick(SimpleListFragment fragment, int position) { if (fragment == middleFragment) { ((Button)root.getRightView()).setText(middleContents.get(position)); if (isLeftShowing) { root.hideLeft(); isLeftShowing=false false; } } else { middleContents=new new ArrayList(); for (int i=0; i < 20; i++) { middleContents.add(items[position] + " #" + i); } if (getFragmentManager().findFragmentById(R.id.middle) == null null) { middleFragment=SimpleListFragment.newInstance(middleContents); getFragmentManager().beginTransaction() 1764 ANIMATORS .add(R.id.middle, middleFragment).commit(); } else { middleFragment.setContents(middleContents); } } } } (from Animation/ThreePane/app/src/main/java/com/commonsware/android/anim/threepane/MainActivity.java) The Results If you run this app on a landscape tablet running API Level 11 or higher, you start off with a single list of words on the left: Figure 567: ThreePane, As Initially Launched Clicking on a word brings up a second list, taking up the rest of the screen, with numbered entries based upon the clicked-upon word: 1765 ANIMATORS Figure 568: ThreePane, After Clicking a Word Clicking on an entry in the second list starts the animation, sliding the first list off to the left, sliding the second list into the space vacated by the first list, and sliding in a “detail view” into the right portion of the screen: 1766 ANIMATORS Figure 569: ThreePane, After Clicking a Numbered Word Pressing BACK once will reverse the animation, restoring you to the two-list perspective. The Backport The ThreePane sample described above uses the native API Level 11 version of the animator framework and the native implementation of fragments. However, the same approach can work using the Android Support package’s version of fragments and NineOldAndroids. You can see this in the Animation/ThreePaneBC sample app. Besides changing the import statements and adding the NineOldAndroids JAR file, the only other changes of substance were: • Using ViewPropertyAnimator.animate(v) instead of v.animate() in translateWidgets() • Conditionally setting the hardware acceleration layers via setLayerType() in translateWidgets() based upon API level, as that method was only added in API Level 11 1767 ANIMATORS The smoothness of animations, though, will vary by hardware capabilities. For example, on a first-generation Kindle Fire, running Android 2.3, the backport works but is not especially smooth, while the animations are very smooth on more modern hardware where hardware acceleration can be applied. The Problems As we will see in the chapter on “jank”, there is some stutter in the rendering of this app. Fixing it requires removing the animated change in the width of the middle pane, which in turn makes the animation itself look worse. More details on the analysis can be found in the “jank” chapter. 1768 Legacy Animations Before ViewPropertyAnimator and the rest of the animator framework were added in API Level 11, we had the original Animation base class and specialized animations based upon it, like TranslateAnimation for movement and AlphaAnimation for fades. On the whole, you will want to try to use the animator framework where possible, as the new system is more powerful and efficient than the legacy Animation approach. However, particularly for apps where the NineOldAndroids backport is insufficient, you may wish to use the legacy framework. After an overview of the role of the animation framework, we go in-depth to animate the movement of a widget across the screen. We then look at alpha animations, for fading widgets in and out. We then see how you can get control during the lifecycle of an animation, how to control the acceleration of animations, and how to group animations together for parallel execution. Finally, we see how the same framework can now be used to control the animation for the switching of activities. Prerequisites Understanding this chapter requires that you have read the core chapters, particularly the ones on basic resources and basic widgets. Also, you should read the chapter on custom views. It’s Not Just For Toons Anymore Android has a package of classes (android.view.animation) dedicated to animating the movement and behavior of widgets. 1769 LEGACY ANIMATIONS They center around an Animation base class that describes what is to be done. Builtin animations exist to move a widget (TranslateAnimation), change the transparency of a widget (AlphaAnimation), revolve a widget (RotateAnimation), and resize a widget (ScaleAnimation). There is even a way to aggregate animations together into a composite Animation called an AnimationSet. Later sections in this chapter will examine the use of several of these animations. Given that you have an animation, to apply it, you have two main options: 1. You may be using a container that supports animating its contents, such as a ViewFlipper or TextSwitcher. These are typically subclasses of ViewAnimator and let you define the “in” and “out” animations to apply. For example, with a ViewFlipper, you can specify how it flips between Views in terms of what animation is used to animate “out” the currently-visible View and what animation is used to animate “in” the replacement View. 2. You can simply tell any View to startAnimation(), given the Animation to apply to itself. This is the technique we will be seeing used in the examples in this chapter. A Quirky Translation Animation takes some getting used to. Frequently, it takes a fair bit of experimentation to get it all working as you wish. This is particularly true of TranslateAnimation, as not everything about it is intuitive, even to authors of Android books. Mechanics of Translation The simple constructor for TranslateAnimation takes four parameters describing how the widget should move: the before and after X offsets from the current position, and the before and after Y offsets from the current position. The Android documentation refers to these as fromXDelta, toXDelta, fromYDelta, and toYDelta. In Android’s pixel-space, an (X,Y) coordinate of (0,0) represents the upper-left corner of the screen. Hence, if toXDelta is greater than fromXDelta, the widget will move to the right, if toYDelta is greater than fromYDelta, the widget will move down, and so on. 1770 LEGACY ANIMATIONS Imagining a Sliding Panel Some Android applications employ a sliding panel, one that is off-screen most of the time but can be called up by the user (e.g., via a menu) when desired. When anchored at the bottom of the screen, you get a container that slides up from the bottom and slides down and out when being removed. One way to implement such a panel is to have a container (e.g., a LinearLayout) whose contents are absent (INVISIBLE) when the panel is closed and is present (VISIBLE) when the drawer is open. If we simply toggled setVisibility() using the aforementioned values, though, the panel would wink open and closed immediately, without any sort of animation. So, instead, we want to: 1. Make the panel visible and animate it up from the bottom of the screen when we open the panel 2. Animate it down to the bottom of the screen and make the panel invisible when we close the panel The Aftermath This brings up a key point with respect to TranslateAnimation: the animation temporarily moves the widget, but if you want the widget to stay where it is when the animation is over, you have to handle that yourself. Otherwise, the widget will snap back to its original position when the animation completes. In the case of the panel opening, we handle that via the transition from INVISIBLE to VISIBLE. Technically speaking, the panel is always “open”, in that we are not, in the end, changing its position. But when the body of the panel is INVISIBLE, it takes up no space on the screen; when we make it VISIBLE, it takes up whatever space it is supposed to. Later in this chapter, we will cover how to use animation listeners to accomplish this end for closing the panel. Introducing SlidingPanel With all that said, turn your attention to the Animation/SlidingPanel sample project and, in particular, the SlidingPanel class. 1771 LEGACY ANIMATIONS This class implements a layout that works as a panel, anchored to the bottom of the screen. A toggle() method can be called by the activity to hide or show the panel. The panel itself is a LinearLayout, so you can put whatever contents you want in there. We use two flavors of TranslateAnimation, one for opening the panel and one for closing it. Here is the opening animation: anim=new new TranslateAnimation(0.0f, 0.0f, getHeight(), 0.0f); (from Animation/SlidingPanel/app/src/main/java/com/commonsware/android/anim/SlidingPanel.java) Our fromXDelta and toXDelta are both 0, since we are not shifting the panel’s position along the horizontal axis. Our fromYDelta is the panel’s height according to its layout parameters (representing how big we want the panel to be), because we want the panel to start the animation at the bottom of the screen; our toYDelta is 0 because we want the panel to be at its “natural” open position at the end of the animation. Conversely, here is the closing animation: anim=new new TranslateAnimation(0.0f, 0.0f, 0.0f, getHeight()); (from Animation/SlidingPanel/app/src/main/java/com/commonsware/android/anim/SlidingPanel.java) It has the same basic structure, except the Y values are reversed, since we want the panel to start open and animate to a closed position. The result is a container that can be closed: 1772 LEGACY ANIMATIONS Figure 570: The SlidingPanel sample application, with the panel closed … or open, in this case toggled via a menu choice in the SlidingPanelDemo activity: 1773 LEGACY ANIMATIONS Figure 571: The SlidingPanel sample application, with the panel open Using the Animation When setting up an animation, you also need to indicate how long the animation should take. This is done by calling setDuration() on the animation, providing the desired length of time in milliseconds. When we are ready with the animation, we simply call startAnimation() on the SlidingPanel itself, causing it to move as specified by the TranslateAnimation instance. Fading To Black. Or Some Other Color. AlphaAnimation allows you to fade a widget in or out by making it less or more transparent. The greater the transparency, the more the widget appears to be “fading”. 1774 LEGACY ANIMATIONS Alpha Numbers You may be used to alpha channels, when used in #AARRGGBB color notation, or perhaps when working with alpha-capable image formats like PNG. Similarly, AlphaAnimation allows you to change the alpha channel for an entire widget, from fully-solid to fully-transparent. In Android, a float value of 1.0 indicates a fully-solid widget, while a value of 0.0 indicates a fully-transparent widget. Values in between, of course, represent various amounts of transparency. Hence, it is common for an AlphaAnimation to either start at 1.0 and smoothly change the alpha to 0.0 (a fade) or vice versa. Animations in XML With TranslateAnimation, we showed how to construct the animation in Java source code. One can also create animation resources, which define the animations using XML. This is similar to the process for defining layouts, albeit much simpler. For example, there is a second animation project, Animation/SlidingPanelEx, which demonstrates a panel that fades out as it is closed. In there, you will find a res/anim/ directory, which is where animation resources should reside. In there, you will find fade.xml: (from Animation/SlidingPanelEx/app/src/main/res/anim/fade.xml) The name of the root element indicates the type of animation (in this case, alpha for an AlphaAnimation). The attributes specify the characteristics of the animation, in this case a fade from 1.0 to 0.0 on the alpha channel. This XML is the same as calling new AlphaAnimation(1.0f,0.0f) in Java. 1775 LEGACY ANIMATIONS Using XML Animations To make use of XML-defined animations, you need to inflate them, much as you might inflate a View or Menu resource. This is accomplished by using the loadAnimation() static method on the AnimationUtils class, seen here in our SlidingPanel constructor: public SlidingPanel(final final Context ctxt, AttributeSet attrs) { super super(ctxt, attrs); TypedArray a=ctxt.obtainStyledAttributes(attrs, R.styleable.SlidingPanel, 0, 0); speed=a.getInt(R.styleable.SlidingPanel_speed, 300); a.recycle(); fadeOut=AnimationUtils.loadAnimation(ctxt, R.anim.fade); } (from Animation/SlidingPanelEx/app/src/main/java/com/commonsware/android/anim2/SlidingPanel.java) Here, we are loading our fade animation, given a Context. This is being put into an Animation variable, so we neither know nor care that this particular XML that we are loading defines an AlphaAnimation instead of, say, a RotateAnimation. When It’s All Said And Done Sometimes, you need to take action when an animation completes. For example, when we close the panel, we want to use a TranslationAnimation to slide it down from the open position to closed… then keep it closed. With the system used in SlidingPanel, keeping the panel closed is a matter of calling setVisibility() on the contents with INVISIBLE. However, you cannot do that when the animation begins; otherwise, the panel is gone by the time you try to animate its motion. Instead, you need to arrange to have it become invisible when the animation ends. To do that, you use an animation listener. 1776 LEGACY ANIMATIONS An animation listener is simply an instance of the AnimationListener interface, provided to an animation via setAnimationListener(). The listener will be invoked when the animation starts, ends, or repeats (the latter courtesy of CycleInterpolator, discussed later in this chapter). You can put logic in the onAnimationEnd() callback in the listener to take action when the animation finishes. For example, here is the AnimationListener for SlidingPanel: Animation.AnimationListener collapseListener=new new Animation.AnimationListener() { public void onAnimationEnd(Animation animation) { setVisibility(View.INVISIBLE); } public void onAnimationRepeat(Animation animation) { // not needed } public void onAnimationStart(Animation animation) { // not needed } }; (from Animation/SlidingPanel/app/src/main/java/com/commonsware/android/anim/SlidingPanel.java) All we do is set our content’s visibility to be INVISIBLE, thereby closing the panel. Loose Fill You will see attributes, available on Animation, named android:fillEnabled and android:fillAfter. Reading those, you may think that you can dispense with the AnimationListener and just use those to arrange to have your widget wind up being “permanently” in the state represented by the end of the animation. All you would have to do is set each of those to true in your animation XML (or the equivalent in Java), and you would be set. At least for TranslateAnimation, you would be mistaken. It actually will look like it works — the animated widgets will be drawn in their new location. However, if those widgets are clickable, they will not be clicked in their new location, but rather in their old one. This, of course, is not terribly useful. Hence, even though it is annoying, you will want to use the AnimationListener techniques described in this chapter. 1777 LEGACY ANIMATIONS Hit The Accelerator In addition to the Animation classes themselves, Android also provides a set of Interpolator classes. These provide instructions for how an animation is supposed to behave during its operating period. For example, the AccelerateInterpolator indicates that, during the duration of an animation, the rate of change of the animation should begin slowly and accelerate until the end. When applied to a TranslateAnimation, for example, the sliding movement will start out slowly and pick up speed until the movement is complete. There are several implementations of the Interpolator interface besides AccelerateInterpolator, including: 1. AccelerateDecelerateInterpolator, which starts slowly, picks up speed in the middle, and slows down again at the end 2. DecelerateInterpolator, which starts quickly and slows down towards the end 3. LinearInterpolator, the default, which indicates the animation should proceed smoothly from start to finish 4. CycleInterpolator, which repeats an animation for a number of cycles, following the AccelerateDecelerateInterpolator pattern (slow, then fast, then slow) To apply an interpolator to an animation, simply call setInterpolator() on the animation with the Interpolator instance, such as the following line from SlidingPanel: anim.setInterpolator(new new AccelerateInterpolator(1.0f)); (from Animation/SlidingPanel/app/src/main/java/com/commonsware/android/anim/SlidingPanel.java) You can also specify one of the stock interpolators via the android:interpolator attribute in your animation XML file. Animate. Set. Match. For the Animation/SlidingPanelEx project, though, we want the panel to slide open, but also fade when it slides closed. This implies two animations working at the same time (a fade and a slide). Android supports this via the AnimationSet class. 1778 LEGACY ANIMATIONS An AnimationSet is itself an Animation implementation. Following the composite design pattern, it simply cascades the major Animation events to each of the animations in the set. To create a set, just create an AnimationSet instance, add the animations, and configure the set. For example, here is the logic from the SlidingPanel implementation in Animation/SlidingPanelEx: public void toggle() { TranslateAnimation anim=null null; AnimationSet set=new new AnimationSet(true true); isOpen=!isOpen; if (isOpen) { setVisibility(View.VISIBLE); anim=new new TranslateAnimation(0.0f, 0.0f, getHeight(), 0.0f); } else { anim=new new TranslateAnimation(0.0f, 0.0f, 0.0f, getHeight()); anim.setAnimationListener(collapseListener); set.addAnimation(fadeOut); } set.addAnimation(anim); set.setDuration(speed); set.setInterpolator(new new AccelerateInterpolator(1.0f)); startAnimation(set); } (from Animation/SlidingPanelEx/app/src/main/java/com/commonsware/android/anim2/SlidingPanel.java) If the panel is to be opened, we make the contents visible (so we can animate the motion upwards), and create a TranslateAnimation for the upward movement. If the panel is to be closed, we create a TranslateAnimation for the downward movement, but also add a pre-defined AlphaAnimation (fadeOut) to an AnimationSet. In either case, we add the TranslateAnimation to the set, give the set a duration and interpolator, and run the animation. 1779 LEGACY ANIMATIONS Active Animations Starting with Android 1.5, users could indicate if they wanted to have inter-activity animations: a slide-in/slide-out effect as they switched from activity to activity. However, at that time, they could merely toggle this setting on or off, and applications had no control over these animations whatsoever. Starting in Android 2.0, though, developers have a bit more control. Specifically: 1. Developers can call overridePendingTransition() on an Activity, typically after calling startActivity() to launch another activity or finish() to close up the current activity. The overridePendingTransition() indicates an in/ out animation pair that should be applied as control passes from this activity to the next one, whether that one is being started (startActivity()) or is the one previous on the stack (finish()). 2. Developers can start an activity via an Intent containing the FLAG_ACTIVITY_NO_ANIMATION flag. As the name suggests, this flag requests that animations on the transitions involving this activity be suppressed. These are prioritized as follows: • Any call to overridePendingTransition() is always taken into account • Lacking that, FLAG_ACTIVITY_NO_ANIMATION will be taken into account • In the normal case, where neither of the two are used, whatever the user’s preference, via the Settings application, is applied 1780 Custom Drawables Many times, our artwork can simply be some PNG or JPEG files, perhaps with different variations in different resource directories by density. Sometimes, though, we need something more. In addition to supporting standard PNG and JPEG files, Android has a number of custom drawable resource formats — mostly written in XML — that handle specific scenarios. For example, you may wish to customize “the background” of a Button, but a Button really has several different background images for different circumstances (normal, pressed, focused, disabled, etc.). Android has a certain type of drawable resource that aggregates other drawable resources, indicating which of those other resources should be used in different circumstances (e.g., for a normal button use X, for a disabled button use Y). In this chapter, we will explore these non-traditional types of “drawables” and how you can use them within your apps. Prerequisites Understanding this chapter requires that you have read the core chapters, particularly the ones on basic resources, basic widgets, and vector drawables. Having read the chapters on animators and legacy animations would be useful. 1781 CUSTOM DRAWABLES Where Do These Things Go? All of the drawables described in this chapter, unless otherwise noted, are densityindependent. Hence, they do not normally go in a density-dependent directories like res/drawable-hdpi/. However, that still leaves three possible candidates: res/ drawable-nodpi/, res/drawable-anydpi/, and the unadorned res/drawable/. nodpi: Fallback A drawable in res/drawable-nodpi/ is valid for any screen density. However, if there is another drawable with the same base name in a density-specific directory, and the device running your app happens to have that screen density, the density-specific resource will be used. As a result, -nodpi becomes a fallback, to be used in cases where you do not have something specific for a density. For example, suppose that we have res/drawable-nodpi/foo.xml and res/ drawable-xxhdpi/foo.png. An -xxhdpi device would use the PNG; all other devices would use the XML. anydpi: Takeover A drawable in res/drawable-anydpi/ also is valid for any screen density. However, in this case, the -anydpi variant trumps any density-specific variant. For example, suppose that we have res/drawable-anydpi/foo.xml and res/ drawable-xxhdpi/foo.png. All devices would use the XML, even -xxhdpi devices. For this reason, often you will see -anydpi used in conjunction with other qualifiers. A popular one will be -v21, to restrict the resources to be used on API Level 21+ devices. No Qualifier: Just Say “WTF?” res/drawable/ is a synonym for res/drawable-mdpi/, for backwards compatibility with really old Android apps, written before we had density-specific resources. Hence, res/drawable/ is not really an appropriate choice for density-independent drawables. Alas, Android Studio may put some drawables here, for uncertain reasons. 1782 CUSTOM DRAWABLES So long as there are no other resources with the same basename, the choice made by Android Studio’s developers is unlikely to cause any harm. ColorDrawable The simplest XML drawable format, by far, is for ColorDrawable. Not surprisingly, this defines a Drawable that is a solid color. So, you can have a res/drawable/thing.xml file, containing something like this: /> From there, you can use @drawable/thing or R.drawable.thing in the same places that you would use any other drawable resource. Note that a ColorDrawable is different than a color resource. A color resource (e.g., res/values/colors.xml) specifies a color. A ColorDrawable resource defines a Drawable of a color. A ColorDrawable resource is welcome to reference a color defined by a color resource, though: /> AnimationDrawable The original way of doing animation on the Web was via the animated GIF. An individual GIF file could contain many frames, and the browser would switch between those frames to display a basic animated effect. This was used by Web designers for things both good (animated progress “spinners”) and bad (“hit the monkey” ad banners). Android, on the whole, does not support animated GIF files, certainly not as regular images for use with widgets like ImageView. However, there are times where having this sort of frame-by-frame animation would be useful. For example, in another chapter, we will look at ProgressBar, which is Android’s primary way of demonstrating progress of background work. You may wish to customize the “spinning wheel” image that Android uses by default, to match your app’s color scheme, or to spin your company logo, or whatever. On the 1783 CUSTOM DRAWABLES Web, particularly on older browsers, you might use an animated GIF for that. On Android, you still could, though it would require a third-party library or some fairly heavyweight solutions (e.g., WebView, Movie). Another possibility is to use an AnimationDrawable. AnimationDrawable has the net effect of an animated GIF: • You define a series of images that serve as the frames of the animation • You define how long each of those images should be on the screen • You define whether the animation should loop back to the beginning after it reaches the end or not However, rather than encoding all of this in an animated GIF, you instead encode this information in an XML file, stored as a drawable resource. XML-encoded drawable resources are typically stored in a drawable directory that does not contain density information, such as res/drawable/. That is because the XML-encoded drawable resources are density-invariant: they behave the same regardless of density. Those, like the AnimationDrawable, that refer to other images might well refer to other images that are stored in density-dependent resource directories, but the XML-encoded drawable itself is independent of density. An AnimationDrawable is defined as in XML with a root element, containing a series of elements for each frame: > The root element can have an android:oneshot attribute, indicating whether the animation should repeat after displaying the last frame (false) or stop (true). The elements have android:drawable attributes pointing to the individual images for the individual frames. Usually these frames are PNG or JPEG files, but you refer to them as drawable resources, using @drawable syntax, so Android can find the right image based upon the density (or other characteristics) of the current device. The elements also need an android:duration attribute, specifying 1784 CUSTOM DRAWABLES the time in milliseconds that this frame should be on the screen. While the above example has all durations the same, that is not required. For example, the Android OS uses AnimationDrawable resources in a few places. One is for the download icon used in a Notification for use with DownloadManager and similar situations. That drawable resource – stat_sys_download.xml — looks like this: > Here, we have a repeating animation (android:oneshot="false"), consisting of six frames, each on the screen for 200 milliseconds. 1785 CUSTOM DRAWABLES By specifying an AnimationDrawable in your Notification for its icon, you too can have this sort of animated effect. Of course, the animation is “fire and forget”: other than by removing or replacing the Notification, you cannot affect the animation in any other way. Animated GIF Conversion It may be that you have an animated GIF that you would like to use as the basis for your AnimationDrawable. If you have passing familiarity with Ruby, the author of this book has published a Ruby script, named gif2animdraw, that automates the conversion. To use gif2animdraw, in addition to the script itself and a Ruby interpreter, you will need the RMagick, slop, and builder gems. Note that RMagick, in turn, will require ImageMagick libraries and therefore is a bit more complicated to install than is your ordinary gem. On Linux environments, you can also chmod the script to run it directly; otherwise, you would run it via the ruby command. The script takes four command-line switches: • -i should point to the GIF file to be converted • -o should point to the root output directory, which typically would be a project’s res/ directory • -d should have, as a value, one of the Android density bucket names (e.g., hdpi); this will be used as the density for the frames of the GIF • Optionally, include --oneshot to indicate that this should be a one-shot animation, not a repeating one The results will be: • A drawable/ directory underneath your supplied root, containing a file with the same name as the GIF file, but with a .xml extension, representing the AnimationDrawable itself • A drawable-XXXX/ directory, where XXXX is your stated density, containing each frame of the animated GIF, as a PNG file, with a sequentially numbered filename based on the GIF’s filename 1786 CUSTOM DRAWABLES StateListDrawable Another XML-defined drawable resource, the StateListDrawable, is key if you want to have different images when widgets are in different states. As outlined in the introduction to this chapter, what makes a Button visually be a Button is its background. To handle different looks for the Button background for different states (normal, pressed, disabled, etc.), the standard Button background is a StateListDrawable, one that looks something like this: > The XML has a root element, indicating this is a StateListDrawable. The elements inside the root describe what Drawable resource should be 1787 CUSTOM DRAWABLES used if the StateListDrawable is being used in some state. For example, if the “window” (think activity or dialog) does not have the focus (android:state_window_focused="false") and the Button is enabled (android:state_enabled="true"), then we use the @drawable/btn_default_normal Drawable resource. That resource, as it turns out, is a nine-patch PNG file, described later in this chapter. Android applies each rule in turn, top-down, to find the Drawable to use for a given state of the StateListDrawable. The last rule has no android:state_* attributes, meaning it is the overall default image to use if none of the other rules match. So, if you want to change the background of a Button, you need to: • Copy the above resource, found in your Android SDK as res/drawable/ btn_default.xml inside any of the platforms/ directories, into your project • Copy each of the Button state nine-patch images into your project • Modify whichever of those nine-patch images you want, to affect the visual change you seek • If need be, tweak the states and images defined in the StateListDrawable XML you copied • Reference the local StateListDrawable as the background for your Button The backgrounds of most widgets that have backgrounds by default will use a StateListDrawable. Searching a platform version’s res/drawable/ directory for XML files containing elements comes up with a rather long list. ColorStateList A ColorStateList is analogous to a StateListDrawable, in that it defines states and identifies what should be used for a given state. Whereas StateListDrawable ties states to drawables, ColorStateList ties states to colors. This allows you to, say, change the color of some text based upon whether that text is drawn in a widget that is being pressed, or has the focus, or is disabled. If you tailor the background of a text-based widget using a StateListDrawable, you may well wind up tailoring the foreground text using a ColorStateList. While this chapter mentions ColorStateList, technically a ColorStateList is not a Drawable. You do not use it in methods that take drawables or in widget XML attributes that take drawables. Rather, there are other methods and other attributes that take a ColorStateList, such as android:textColor. 1788 CUSTOM DRAWABLES Similarly, while you can define a ColorStateList in XML, you do not do so in a res/ drawable/ resource directory, but rather a res/color/ resource directory. Beyond that, though, a ColorStateList XML resource looks a lot like a StateListDrawable XML resource, such as this definition of @android:color/primary_text_dark from Android 4.4: > /> /> /> /> /> /> Based upon the state, the ColorStateList pulls in a separate resource to define the actual color. Those colors, in turn, are defined via elements in res/values/ colors.xml as color resources, or are pulled in from system-defined colors (@android:color/... syntax): >#ff000000 name="background_light"> >#ffffffff name="bright_foreground_dark"> >@android:color/background_light name="bright_foreground_light"> >@android:color/background_dark 1789 CUSTOM DRAWABLES >#80ffffff >#80000000 >@android:color/ bright_foreground_light >@android:color/ bright_foreground_dark LayerDrawable A LayerDrawable basically stacks a bunch of other drawables on top of each other. Later drawables are drawn on top of earlier drawables, much as later children of a RelativeLayout are drawn on top of earlier children. Typically, you will create a LayerDrawable via a XML drawable resource. For example, a ToggleButton widget has a LayerDrawable as its background: ?xml version="1.0" encoding="utf-8"?> > This LayerDrawable draws two images on top of each other. One is a standard small button background (@android:drawable/btn_default_small). The other is the 1790 CUSTOM DRAWABLES actual face of the toggle itself — a StateListDrawable that uses different images for checked and unchecked states. In the , you can have several elements. Each element usually will need an android:drawable attribute, pointing to the drawable that should be drawn. Optionally, you can assign ID values to the items via android:id attributes, much like you would do for widgets in a layout XML resource. Later on, you can call findDrawableByLayerId() on the LayerDrawable to retrieve an individual Drawable representing the layer, given its android:id value. There are also android:left, android:right, android:top, and android:bottom attributes, which you can use to provide dimension values to offset an image within the layered set. For example, you could use android:left to inset one of the layers by a certain number of pixels (or dp or whatever). By default, the layers in the LayerDrawable are scaled to fit the size of whatever View is holding them (e.g., the size of the ToggleButton using the LayerDrawable as a background). To prevent this, you can skip the android:drawable attribute, and instead nest a element inside the , where you can provide an android:gravity attribute to control how the image should be handled relative to its containing View. We will get more into nested elements later in this chapter. TransitionDrawable A TransitionDrawable is a LayerDrawable with one added feature: for a two-layer drawable, it can smoothly transition from showing one layer to another on top. For example, you may have noticed that when you tap-and-hold on a row in a ListView that the selector highlight has an animated effect, slowly shifting colors from the color used for a simple click to one signifying that you have long-clicked the row. Android accomplishes this via a TransitionDrawable, set up as a XML drawable resource: > The TransitionDrawable object has a startTransition() method that you can use, that will have Android smoothly switch from the first drawable to the second. You specify the duration of the transition as a number of milliseconds passed to startTransition(). There are also options to reverse the transition, set up more of a cross-fade effect, and the like. LevelListDrawable A LevelListDrawable is similar in some respects to a StateListDrawable, insofar as one specific item from the “list drawable” will be displayed based upon certain conditions. In the case of StateListDrawable, the conditions are based upon the state of the widget using the drawable (e.g., checked, pressed, disabled). In the case of LevelListDrawable, it is merely an integer level. For example, the status or system bar of your average Android device has an icon indicating the battery charge level. That is actually implemented as a LevelListDrawable, via an XML resource containing a root element: > This LevelListDrawable has eight items, whose android:drawable attributes point to specific other drawable resources (in this case, standard PNG files with different implementations for different densities). Each has an android:maxLevel value. When someone calls setLevel() on the Drawable or setImageLevel() on the ImageView, Android will choose the item with the lowest maxLevel that meets or exceeds the requested level, and show that. In the case of the battery icon, when the battery level changes, the status bar picks up that change and calls setImageLevel() with the battery charge percentage (expressed as an integer from 0-100) — that, in turn, triggers the right PNG file to be displayed. Another use of LevelListDrawable is with a RemoteViews, such as for an app widget. The setImageLevel() method is “remotable”, despite not being directly part of the RemoteViews API. Hence, given that you use a LevelListDrawable in your app widget’s layout, you should be able to use setInt() with a method name of "setImageLevel" to have the app widget update to display the proper image. 1793 CUSTOM DRAWABLES ScaleDrawable and ClipDrawable A ScaleDrawable does pretty much what its name suggests: it scales another drawable. A ClipDrawable does pretty much what its name suggests: it clips another drawable. How they do this, and how you control it, requires a bit more explanation. Like LevelListDrawable, ScaleDrawable and ClipDrawable leverage the setLevel() method on Drawable (or the setImageLevel() method on ImageView). Whereas LevelListDrawable uses this to choose an individual image out of a set of possible images, ScaleDrawable and ClipDrawable use the level to control how much an image should be scaled or clipped. For this, they support a range of levels from 0 to 10000. Scaling For a level of 0, ScaleDrawable will not draw anything. For a level from 1 to 10000, ScaleDrawable will scale an image from a configurable minimum size to the bounds of the View to which the drawable is applied. The amount of scaling is determined by android:scaleHeight and android:scaleWidth attributes: /> (from Drawable/ScaleClip/app/src/main/res/drawable/scale.xml) The above ScaleDrawable (denoted by the root element) says that we should scale both height and width of the underlying drawable to 50% of the available space for the drawable, when the level is at its maximum (10000). Note that you do not have to scale along both dimensions. If, for example, you kept android:scaleWidth but deleted android:scaleHeight, setImageLevel() would control the scaled width of the underlying image (provided via android:drawable) but not the height. 1794 CUSTOM DRAWABLES The android:scaleGravity attribute indicates where the scaled image should reside within the available space (the 10000 level, determined by the bounds of the View to which the drawable is applied). The value shown above, center, keeps the image centered within the available space, and shrinks or expands it around the center. A value of left|top would keep the image in the upper-left corner of the space, having the visual effect of moving the lower-right corner based upon the supplied level. Clipping Scaling proportionally reduces the height and/or width of an image. Clipping, on the other hand, chops off part of the height or width of the image. /> (from Drawable/ScaleClip/app/src/main/res/drawable/clip.xml) In this sample ClipDrawable (indicated by the root element), we are going to allow the level to chop off part of the image indicated by the android:drawable attribute. Our android:clipOrientation, set to horizontal, means we are going to chop off part of the width (vertical would have us chop off part of the height). The amount that is going to be chopped off is the level you supply (e.g., setImageLevel()) divided by 10000. Hence, a level of 5000 will chop off 0.5 (a.k.a., 50%) of the image. Where in the image the clipping occurs is determined by the android:gravity attribute. An android:clipOrientation of horizontal and an android:gravity of left, as in the sample drawable above, means that the left side of the image is retained, and the image will be clipped on the right. Specifying right instead of left would reverse that, clipping the image from the right, while center would clip equally from both sides. There are other gravity values as well, such as top and bottom values to be used with a vertical orientation. Seeing It In Action To see these effects, take a look at the Drawable/ScaleClip sample project. This is derived from an earlier example showing how to use ViewPager with PagerTabStrip. In that example, we had 10 tabs, each being a large EditText widget. In this example, we have 2 tabs, “Scale” and “Clip”, both using the same layout: 1795 CUSTOM DRAWABLES > /> /> (from Drawable/ScaleClip/app/src/main/res/layout/scaleclip.xml) This is simply a 150dp square ImageView towards the top of the screen and a SeekBar towards the bottom of the screen. The SeekBar will be used to control the level applied to a ScaleDrawable and ClipDrawable, which is why we have android:max set to 10000. We also have our “progress” (original SeekBar value) set to 10000, so the bar’s thumb will be fully slid over to the right at the outset. The fragments that we will use for the tabs both inherit from a common abstract FragmentBase class: package com.commonsware.android.scaleclip; import import import import import import import android.app.Fragment android.app.Fragment; android.os.Bundle android.os.Bundle; android.view.LayoutInflater android.view.LayoutInflater; android.view.View android.view.View; android.view.ViewGroup android.view.ViewGroup; android.widget.ImageView android.widget.ImageView; android.widget.SeekBar android.widget.SeekBar; abstract public class FragmentBase extends Fragment implements 1796 CUSTOM DRAWABLES SeekBar.OnSeekBarChangeListener { abstract void setImageBackground(ImageView image); private ImageView image=null null; @Override public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) { setRetainInstance(true true); View result=inflater.inflate(R.layout.scaleclip, container, false false); SeekBar bar=((SeekBar)result.findViewById(R.id.level)); bar.setOnSeekBarChangeListener(this this); image=(ImageView)result.findViewById(R.id.image); setImageBackground(image); image.setImageLevel(bar.getProgress()); return return(result); } @Override public void onProgressChanged(SeekBar seekBar, int progress, boolean fromUser) { image.setImageLevel(progress); } @Override public void onStartTrackingTouch(SeekBar seekBar) { // no-op } @Override public void onStopTrackingTouch(SeekBar seekBar) { // no-op } } (from Drawable/ScaleClip/app/src/main/java/com/commonsware/android/scaleclip/FragmentBase.java) In onCreateView(), we inflate the above layout file, hook up the fragment itself to be the listener for SeekBar change events, call the subclass’ setImageBackground() method to populate the ImageView with an image, and set the ImageView’s level to be the initial value of the SeekBar. When the SeekBar value changes, our onProgressChanged() method will adjust the level. 1797 CUSTOM DRAWABLES The concrete subclasses — ScaleFragment and ClipFragment — simply populate the ImageView with the ScaleDrawable and ClipDrawable resources shown earlier in this section: package com.commonsware.android.scaleclip; import android.widget.ImageView android.widget.ImageView; public class ScaleFragment extends FragmentBase { @Override void setImageBackground(ImageView image) { image.setImageResource(R.drawable.scale); } } (from Drawable/ScaleClip/app/src/main/java/com/commonsware/android/scaleclip/ScaleFragment.java) package com.commonsware.android.scaleclip; import android.widget.ImageView android.widget.ImageView; public class ClipFragment extends FragmentBase { @Override void setImageBackground(ImageView image) { image.setImageResource(R.drawable.clip); } } (from Drawable/ScaleClip/app/src/main/java/com/commonsware/android/scaleclip/ClipFragment.java) Those two drawables based their scaling and clipping on res/drawable-xdpi/ btn_default_normal.9.png. This is a slightly-modified copy of the default button background, and is a nine-patch PNG file. We will discuss nine-patch PNG files later in this chapter — suffice it to say for now that it is a PNG file with rules about how it should be stretched. Our scale tab starts off showing the full image: 1798 CUSTOM DRAWABLES Figure 572: ScaleDrawable, Level of 10000 As we start sliding the SeekBar thumb to the left, the image shrinks progressively: 1799 CUSTOM DRAWABLES Figure 573: ScaleDrawable, Level of Approximately 5000 It eventually tends towards the 50% level specified in our android:scaleHeight and android:scaleWidth values: 1800 CUSTOM DRAWABLES Figure 574: ScaleDrawable, Level of Approximately 100 Sliding it all the way to the left, though, causes the image to vanish. The ClipDrawable starts off looking much like the ScaleDrawable: 1801 CUSTOM DRAWABLES Figure 575: ClipDrawable, Level of 10000 As we slide the SeekBar to the left, the right side of the image gets clipped: 1802 CUSTOM DRAWABLES Figure 576: ClipDrawable, Level of Approximately 5000 InsetDrawable An InsetDrawable allows you to apply insets on any side (or all sides) of some other drawable resource. The use case cited in the documentation is “This is used when a View needs a background that is smaller than the View’s actual bounds”. However, at the present time, nothing in the Android open source code uses this particular type of resource, or even the Java class. In principle, though, you could have an XML drawable resource that looked like this: When used as the background for some View, for example, Android would pull in the something_or_another resource and effectively add 20dp of left margin and 10dp of top margin on the background when calculating its size and drawing it on the screen. 1803 CUSTOM DRAWABLES ShapeDrawable ShapeDrawable is the original approach to implementing limited vector art on Android. It gives you what amounts to a very tiny subset of SVG, for creating simple vector art shapes. The root element of a ShapeDrawable resource is , which may have child elements, along with attributes, to configure what gets rendered on the screen when the drawable is applied. This section will review the elements and attributes available to you, with sample drawables (and screenshots) culled from the Drawable/Shape sample project. This is a “sampler” project, designed to depict a number of ShapeDrawables. To accomplish this, we will use action bar tabs. Our activity (MainActivity) has a pair of static int arrays, one pointing at string resources to use for tab captions, the other pointing at corresponding drawable resources: package com.commonsware.android.shape; import import import import import import import android.app.ActionBar android.app.ActionBar; android.app.ActionBar.Tab android.app.ActionBar.Tab; android.app.ActionBar.TabListener android.app.ActionBar.TabListener; android.app.Activity android.app.Activity; android.app.FragmentTransaction android.app.FragmentTransaction; android.os.Bundle android.os.Bundle; android.widget.ImageView android.widget.ImageView; public class MainActivity extends Activity implements TabListener { private static final int TABS[]= { R.string.solid, R.string.gradient, R.string.border, R.string.rounded, R.string.ring, R.string.layered }; private static final int DRAWABLES[]= { R.drawable.rectangle, R.drawable.gradient, R.drawable.border, R.drawable.rounded, R.drawable.ring, R.drawable.layered }; private ImageView image=null null; @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); image=(ImageView)findViewById(R.id.image); 1804 CUSTOM DRAWABLES ActionBar bar=getActionBar(); bar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS); for (int i=0; i < TABS.length; i++) { bar.addTab(bar.newTab().setText(getString(TABS[i])) .setTabListener(this this)); } } @Override public void onTabSelected(Tab tab, FragmentTransaction ft) { image.setImageResource(DRAWABLES[tab.getPosition()]); } @Override public void onTabUnselected(Tab tab, FragmentTransaction ft) { // no-op } @Override public void onTabReselected(Tab tab, FragmentTransaction ft) { // no-op } } (from Drawable/Shape/app/src/main/java/com/commonsware/android/shape/MainActivity.java) In onCreate(), we toggle the ActionBar into tab-navigation mode, then iterate over the arrays and add one tab per element. Our layout is an ImageView, named image, centered on the screen, taking up 80% of the horizontal space, plus has 20dp of top and bottom margin: > /> (from Drawable/Shape/app/src/main/res/layout/activity_main.xml) In our activity’s onTabSelected() — implemented because the activity is the TabListener for our tabs — we get the position of our tab and fill in the appropriate drawable into the ImageView. Given that, let’s take a look at how to construct a ShapeDrawable, along with some sample drawables. Your root element, not surprisingly, is . The primary thing that you will define on the element is the redundantlynamed android:shape attribute, to define what sort of shape you want: • • • • line (a shape with no interior) oval (also for ellipses) rectangle (including rounded rectangles) ring (for partially-filled circles) There are some other attributes available on for a ring, which we will examine later in this chapter. Your shape will usually require some sort of fill, to say what color goes in the shape. There are two types of fills: solid and gradient. For a solid fill, add a child element to the , with an android:color attribute indicating what color to use. As with most places in Android, this can either be a literal color or a reference to a color resource. So, for example, we can specify a solid red rectangle as: 1806 CUSTOM DRAWABLES > /> (from Drawable/Shape/app/src/main/res/drawable/rectangle.xml) This gives us the following visual result: Figure 577: ShapeDrawable, Solid Red Rectangle Your alternative fill is a gradient. The nice thing about gradients with ShapeDrawable is that they are generated at runtime from the specifications in the ShapeDrawable, and therefore will be smooth. Gradients that appear in PNG files and the like, if stretched, will tend to have a banding effect. Gradient fills are defined via a child element of the element. The simplest way to set up a gradient is to use three attributes: 1807 CUSTOM DRAWABLES • android:startColor and android:endColor, to specify the starting and ending colors of the gradient, respectively, and • android:angle, to specify what direction the gradient “flows” in The angle must be a multiple of 45 degrees. 0 degrees is left-to-right, 90 degrees is bottom-to-top, 180 degrees is right-to-left, and 270 degrees is top-to-bottom. So, for example, we could change our rectangle to have a gradient fill, from red to blue, with red at the top, via: > /> (from Drawable/Shape/app/src/main/res/drawable/gradient.xml) That gives us: 1808 CUSTOM DRAWABLES Figure 578: ShapeDrawable, Gradient Fill Rectangle We will examine some other gradient options in the section on rings, later in this chapter. If you want a separate color for a border around your shape, you can use the element, as a child of the element, to configure one. There are four attributes that you can declare. The two that you will probably always use are android:color (to indicate the color of the border) and android:width (to indicate the thickness of the border). By default, using just those two will give you a solid line around the edge of your shape. If you would prefer a dashed border, you can add in android:dashWidth (to indicate how long each dash segment should be) and android:dashGap (to indicate how long the gaps between dash segments should be). So, for example, we can add a dashed border to our gradient rectangle via a suitable element: 1809 CUSTOM DRAWABLES > /> /> (from Drawable/Shape/app/src/main/res/drawable/border.xml) This gives us: Figure 579: ShapeDrawable, Gradient Fill Rectangle with Dashed Border 1810 CUSTOM DRAWABLES If we are implementing a rectangle shape, but we really want it to be a rounded rectangle, we can add a element as a child of the element. You can specify the radius to apply to the corners, either for all corners (e.g., android:radius), or for individual corners (e.g., android:topLeftRadius). Here, “radius” basically means the size of the circle that should implement the corner, where a radius of 0dp would indicate the default square corner. So, if we wanted to add rounded corners to our gradient-filled, dash-outlined rectangle, we could use this: > /> /> /> (from Drawable/Shape/app/src/main/res/drawable/rounded.xml) This gives us the following: 1811 CUSTOM DRAWABLES Figure 580: ShapeDrawable, Gradient Fill Rounded Rectangle with Dashed Border and There are also and elements that you can add, that specify padding to put on the various sizes and the overall size of the drawable. More often than not, you would actually handle this on the ImageView or other widget that is using your drawable, but if you would prefer to define those things in the drawable itself, you are welcome to do so. Put a Ring On It Rings are a bit more complicated, in large part because they are not completely filled. With a ring, the “fill” is filling what goes in the ring itself, not the “hole” in the center of the ring. This means that we need to teach Android more about how that “hole” is supposed to be set up. To do that, we need to provide two pieces of information: 1. How big the inner radius should be, where by “inner radius” Android means “the radius of the hole” 2. How thick the ring should be 1812 CUSTOM DRAWABLES The ring will then be drawn based upon that inner radius and thickness. You might wonder, “well, where does the size of the actual drawable come into play?” After all, if we specify an inner radius of 20dp and a thickness of 10dp, that would give us an outer radius of 30dp, for a total width of 60dp… regardless of how big the actual drawable is. And that is completely correct. However, for both the inner radius and the thickness, you have two choices of how to specify their values: 1. As actual sizes (dimensions or references to dimension resources) 2. As ratios to the overall drawable width (defined by or the widget that is using the drawable) This gives us four total attributes to choose from, to be placed on the element for ring drawables: 1. 2. 3. 4. android:innerRadius android:innerRadiusRatio android:thickness android:thicknessRatio Therefore, if you want the ring’s size to be based on the size of the drawable, you would use innerRadiusRatio, thicknessRatio, or both. The other thing about rings is that they are round. Hence, a default linear gradient fill — going from one side of the drawable to another – may not be what you really want. You can control the type of gradient fill to use via the android:type attribute on the element. There are three possible values: 1. linear (the default behavior) 2. radial, where the gradient starts from the center (or another point that you define) and changes color from that center to the edges 3. sweep, where the gradient revolves clockwise in a circle, starting from whatever android:angle you specify (or 0, meaning “east”, as the default) So, for example, take a look at the following ShapeDrawable: > /> (from Drawable/Shape/app/src/main/res/drawable/ring.xml) Here, we: • Declare that our shape is a ring • Indicate that the distance between the inner radius and the outer radius of the ring should be 15dp • Indicate that there is a 3:1 ratio between the width of the image and the radius of the “hole” in the ring • Indicate that the fill should be a gradient that sweeps clockwise from the default angle of 0 • Indicate that the first half of the gradient (start to center) should remain a constant color • Indicate that the second half of the gradient (center to end) should change color from gray to purple We also have android:useLevel="false" in the element. For unknown reasons, this is required for rings but not for other types of shapes. This gives us: 1814 CUSTOM DRAWABLES Figure 581: ShapeDrawable, Ring with Gradient Fill BitmapDrawable Having an XML drawable format named BitmapDrawable may seem like a contradiction in terms. However, BitmapDrawable is not an XML representation of a bitmap, but rather an XML representation of operations to perform on an actual bitmap. The big thing that BitmapDrawable offers is android:tileMode, which turns a single bitmap into a repeating bitmap. The bitmap is tiled, horizontally and vertically, using a tiling mode that you specify. This is demonstrated in the Drawable/TileMode sample project. Our activity’s layout is just a LinearLayout, set to fill the screen: > (from Drawable/TileMode/app/src/main/res/layout/activity_main.xml) Our activity populates action bar tabs, where it applies a particular background image to the LinearLayout (known as R.id.widget) based on the selected tab: package com.commonsware.android.tilemode; import import import import import import import android.app.ActionBar android.app.ActionBar; android.app.ActionBar.Tab android.app.ActionBar.Tab; android.app.ActionBar.TabListener android.app.ActionBar.TabListener; android.app.Activity android.app.Activity; android.app.FragmentTransaction android.app.FragmentTransaction; android.os.Bundle android.os.Bundle; android.view.View android.view.View; public class MainActivity extends Activity implements TabListener { private static final int TABS[]= { R.string._default, R.string.clamp, R.string.repeat, R.string.mirror }; private static final int DRAWABLES[]= { R.drawable._default, R.drawable.clamp, R.drawable.repeat, R.drawable.mirror }; private View widget=null null; @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); widget=findViewById(R.id.widget); ActionBar bar=getActionBar(); bar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS); for (int i=0; i < TABS.length; i++) { bar.addTab(bar.newTab().setText(getString(TABS[i])) .setTabListener(this this)); } } @Override public void onTabSelected(Tab tab, FragmentTransaction ft) { widget.setBackgroundResource(DRAWABLES[tab.getPosition()]); } @Override 1816 CUSTOM DRAWABLES public void onTabUnselected(Tab tab, FragmentTransaction ft) { // no-op } @Override public void onTabReselected(Tab tab, FragmentTransaction ft) { // no-op } } (from Drawable/TileMode/app/src/main/java/com/commonsware/android/tilemode/MainActivity.java) The res/drawable/_default.xml resource, used on the first tab, is an unadorned BitmapDrawable resource, where our element simply has an android:src attribute pointing to a bitmap to be used for this BitmapDrawable: /> (from Drawable/TileMode/app/src/main/res/drawable/_default.xml) Since we have not specified a tile mode, the image is stretched to fill the size of our LinearLayout when serving as its background: Figure 582: BitmapDrawable, Without android:tileMode 1817 CUSTOM DRAWABLES The res/drawable/clamp.xml resource, used on the second tab, adds android:tileMode="clamp": /> (from Drawable/TileMode/app/src/main/res/drawable/clamp.xml) This causes the right-most column of pixels and the bottom-most row of pixels to be repeated to fill the available space: Figure 583: BitmapDrawable, Clamped Zooming in on the upper-left portion of our LinearLayout demonstrates this: 1818 CUSTOM DRAWABLES Figure 584: Portion of BitmapDrawable, Clamped The res/drawable/repeat.xml resource, used on the third tab, employs android:tileMode="repeat": /> (from Drawable/TileMode/app/src/main/res/drawable/repeat.xml) Here, the image is simply repeated in toto to fill the available space, rather than only its lower-right edges: 1819 CUSTOM DRAWABLES Figure 585: BitmapDrawable, Repeated Zooming in on an arbitrary chunk of the LinearLayout shows this effect: Figure 586: Portion of BitmapDrawable, Repeated 1820 CUSTOM DRAWABLES The res/drawable/mirror.xml resource, used on the fourth tab, uses android:tileMode="mirror": /> (from Drawable/TileMode/app/src/main/res/drawable/mirror.xml) Here, the image is repeated, but alternately mirrored along the repeating axis. So, it is flipped horizontally for each repeat along the horizontal axis, and it is flipped vertically for each repeat along the vertical axis: Figure 587: BitmapDrawable, Mirrored Zooming in on an arbitrary chunk of the LinearLayout shows this effect: 1821 CUSTOM DRAWABLES Figure 588: Portion of BitmapDrawable, Mirrored Composite Drawables Let’s say that we wanted to have a pair of ShapeDrawable images, one superimposed on another. Since a single ShapeDrawable defines only one shape, we would need something else to assist with stacking the images. One possibility would be to use a LayerDrawable, creating three total resources: 1. The first ShapeDrawable, in its own resource file 2. The second ShapeDrawable, in its own resource file 3. The LayerDrawable, holding references to the two ShapeDrawable resources And this will certainly work. But you have an alternative: put all of it into a single drawable resource. An android:drawable attribute in an element can be replaced by child elements representing another drawable structure. Hence, rather than having a LayerDrawable with two elements pointing to other drawable resources, we could have those same elements contain the other drawable XML structures, and thereby cut our number of files from 3 to 1. For example, we could have something like this: > > /> /> /> > /> (from Drawable/Shape/app/src/main/res/drawable/layered.xml) This is a LayerDrawable, layering two ShapeDrawable structures. The first ShapeDrawable is our dash-bordered, gradient-filled, rounded rectangle from before. The second ShapeDrawable is a ring with a simple gradient sweep fill, from black to white. This gives us: 1823 CUSTOM DRAWABLES Figure 589: Composite Drawable Hence, any of the drawable XML structures other than ShapeDrawable can, in their elements, hold any drawable XML structure, instead of pointing to another separate resource. Android uses this trick as well. For example, the stock ProgressBar image is based off of a LayerDrawable wrapped around three ShapeDrawable structures: 1824 CUSTOM DRAWABLES > > > > 1825 CUSTOM DRAWABLES We will get into how this works with a ProgressBar in a separate chapter. A Stitch In Time Saves Nine Most of the types of non-traditional drawable resources you can create in Android are described in XML… but not all. As you read through the Android documentation, you no doubt ran into references to “nine-patch” or “9-patch” and wondered what Android had to do with quilting. Rest assured, you will not need to take up needlework to be an effective Android developer. If, however, you are looking to create backgrounds for resizable widgets, like a Button, you may wish to work with nine-patch images. As the Android documentation states, a nine-patch is “a PNG image in which you define stretchable sections that Android will resize to fit the object at display time to accommodate variable sized sections, such as text strings”. By using a speciallycreated PNG file, Android can avoid trying to use vector-based formats (e.g., ShapeDrawable) and their associated overhead when trying to create a background at runtime. Yet, at the same time, Android can still resize the background to handle whatever you want to put inside of it, such as the text of a Button. In this section, we will cover some of the basics of nine-patch graphics, including how to customize and apply them to your own Android layouts. Note that nine-patch PNG files, while they provide stretching rules, are still somewhat dependent upon density. You may wish to have different versions of your nine-patch PNG files for different densities, and therefore these images should be put in density-specific resource directories (e.g., res/drawable-hdpi/). The Name and the Border Nine-patch graphics are PNG files whose names end in .9.png. This means they can be edited using normal graphics tools, but Android knows to apply nine-patch rules to their use. What makes a nine-patch graphic different than an ordinary PNG is a one-pixelwide border surrounding the image. When drawn, Android will remove that border, showing only the stretched rendition of what lies inside the border. The border is 1826 CUSTOM DRAWABLES used as a control channel, providing instructions to Android for how to deal with stretching the image to fit its contents. Padding and the Box Along the right and bottom sides, you can draw one-pixel-wide black lines to indicate the “padding box”. Android will stretch the image such that the contents of the widget will fit inside that padding box. For example, suppose we are using a nine-patch as the background of a Button. When you set the text to appear in the button (e.g., “Hello, world!”), Android will compute the size of that text, in terms of width and height in pixels. Then, it will stretch the nine-patch image such that the text will reside inside the padding box. What lies outside the padding box forms the border of the button, typically a rounded rectangle of some form. Figure 590: The padding box, as shown by a set of control lines to the right and bottom of the stretchable image 1827 CUSTOM DRAWABLES Stretch Zones To tell Android where on the image to actually do the stretching, draw one-pixelwide black lines on the top and left sides of the image. Android will scale the graphic only in those areas — areas outside the stretch zones are not stretched. Perhaps the most common pattern is the center-stretch, where the middle portions of the image on both axes are considered stretchable, but the edges are not: Figure 591: The stretch zones, as shown by a set of control lines to the left and top of the stretchable image Here, the stretch zones will be stretched just enough for the contents to fit in the padding box. The edges of the graphic are left unstretched. Some additional rules to bear in mind: 1. If you have multiple discrete stretch zones along an axis (e.g., two zones separated by whitespace), Android will stretch both of them but keep them in their current proportions. So, if the first zone is twice as wide as the second zone in the original graphic, the first zone will be twice as wide as the second zone in the stretched graphic. 1828 CUSTOM DRAWABLES 2. If you leave out the control lines for the padding box, it is assumed that the padding box and the stretch zones are one and the same. Tooling Android Studio has a nine-patch PNG editor, based on the now-discontinued draw9patch utility used previously by Android app developers. To work with this tool: • If you have a regular PNG that you want to convert into a nine-patch PNG, right-click over it and choose “Create 9-patch file” from the context menu • If you already have a nine-patch PNG (with the .9.png extension), or you created one using “Create 9-patch file”, just double-click on the image to bring it up in a nine-patch editor Figure 592: Android Studio, Editing a Nine-Patch PNG While a regular graphics editor would allow you to draw any color on any pixel, the nine-patch editor limits you to drawing or erasing pixels in the control area: • Set a pixel (making it black) by clicking on it • Clear a pixel by shift-clicking on it 1829 CUSTOM DRAWABLES If you attempt to draw inside the main image area itself, you will be blocked. On the right, you will see samples of the image in various stretched sizes, so you can see the impact as you change the stretchable zones and padding box. While this is convenient for working with the nine-patch nature of the image, you will still need some other graphics editor to create or modify the body of the image itself. For example, the image shown above, from the Drawable/NinePatch project, is a modified version of a nine-patch graphic from the SDK’s ApiDemos, where the GIMP was used to add the neon green stripe across the bottom portion of the image. Using Nine-Patch Images Nine-patch images are most commonly used as backgrounds, as illustrated by the following layout from the Drawable/NinePatch sample project: (from Drawable/NinePatch/app/src/main/res/layout/main.xml) Here, we have two SeekBar widgets, labeled for the horizontal and vertical axes, plus a Button set up with our nine-patch graphic as its background (android:background = "@drawable/button"). The NinePatchDemo activity then uses the two SeekBar widgets to let the user control how large the button should be drawn on-screen, starting from an initial size of 64px square: package com.commonsware.android.ninepatch; import import import import import import android.app.Activity android.app.Activity; android.os.Bundle android.os.Bundle; android.view.View android.view.View; android.view.ViewGroup android.view.ViewGroup; android.widget.LinearLayout android.widget.LinearLayout; android.widget.SeekBar android.widget.SeekBar; public class NinePatchDemo extends Activity { SeekBar horizontal=null null; 1831 CUSTOM DRAWABLES SeekBar vertical=null null; View thingToResize=null null; @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.main); thingToResize=findViewById(R.id.resize); horizontal=(SeekBar)findViewById(R.id.horizontal); vertical=(SeekBar)findViewById(R.id.vertical); horizontal.setMax(144); // 240 less 96 starting size vertical.setMax(144); // keep it square @ max horizontal.setOnSeekBarChangeListener(h); vertical.setOnSeekBarChangeListener(v); } SeekBar.OnSeekBarChangeListener h=new new SeekBar.OnSeekBarChangeListener() { public void onProgressChanged(SeekBar seekBar, int progress, boolean fromTouch) { ViewGroup.LayoutParams old=thingToResize.getLayoutParams(); ViewGroup.LayoutParams current=new new LinearLayout.LayoutParams(64+progress, old.height); thingToResize.setLayoutParams(current); } public void onStartTrackingTouch(SeekBar seekBar) { // unused } public void onStopTrackingTouch(SeekBar seekBar) { // unused } }; SeekBar.OnSeekBarChangeListener v=new new SeekBar.OnSeekBarChangeListener() { public void onProgressChanged(SeekBar seekBar, int progress, boolean fromTouch) { ViewGroup.LayoutParams old=thingToResize.getLayoutParams(); ViewGroup.LayoutParams current=new new LinearLayout.LayoutParams(old.width, 64+progress); thingToResize.setLayoutParams(current); } public void onStartTrackingTouch(SeekBar seekBar) { // unused } public void onStopTrackingTouch(SeekBar seekBar) { // unused } }; } 1832 CUSTOM DRAWABLES (from Drawable/NinePatch/app/src/main/java/com/commonsware/android/ninepatch/NinePatchDemo.java) The result is an application that can be used much like the right pane of draw9patch, to see how the nine-patch graphic looks on an actual device or emulator in various sizes: Figure 593: The NinePatch sample project, in its initial state 1833 CUSTOM DRAWABLES Figure 594: The NinePatch sample project, after making it bigger horizontally 1834 CUSTOM DRAWABLES Figure 595: The NinePatch sample application, after making it bigger in both dimensions 1835 Mapping with Maps V2 One of Google’s most popular services — after search, of course – is Google Maps, where you can find everything from the nearest pizza parlor to directions from New York City to San Francisco (only 2,905 miles!) to street views and satellite imagery. Android has had mapping capability from the beginning, with an API available to us as developers to bake maps into our apps. However, as we will see shortly, that original API was getting a bit stale. In December 2012, Google released a long-awaited update to the mapping capabilities available to Android app developers. The original mapping solution, now known as the Maps V1, worked but had serious limitations. The new mapping solution, known as Maps V2, offers greater power and greater ease of handling common situations, though it too has its rough edges. Prerequisites Understanding this chapter requires that you have read the core chapters, along with the chapter on drawables. Also, one of the samples involves location tracking, and another of the samples involves the use of the animator framework. One section involves the use of Picasso, covered in the chapter on Internet access. This chapter also makes the occasional reference back to Maps V1 for comparisons, mostly for the benefit of developers already familiar with Maps V1 and looking to migrate to Maps V2. However, prior experience with Maps V1 is not necessary to understand this chapter. 1837 MAPPING WITH MAPS V2 A Brief History of Mapping on Android Back in the dawn of Android, we were given the Maps SDK add-on. This would allow us to load a firmware-hosted mapping library into our applications, then embed maps into our activities, by means of a MapView widget. And it worked. More importantly, from the standpoint of users, the results from our apps were visually indistinguishable from the built-in Maps application available on devices that had the Maps SDK add-on. This was the case through most of 2009. Eventually, though, the Google Maps team wanted to update the Maps application… but, for whatever reason, the decision was made to not update the Maps SDK add-on as well. At this point, the Google Maps team effectively forked the Maps SDK add-on, causing the Maps application to diverge from what other Android app developers could deliver. Over time, this feature gap became quite pronounced. The release of Android 3.0 in early 2011 compounded the problems. Now, we needed to consider using fragments to help manage our code and deliver solutions to all screen sizes. Alas, while we could add maps to our fragments, we could only do so on API Level 11 or higher — the fragments backport from the Android Support package did not work with the Maps SDK add-on. The release of Maps V2 helped all of this significantly. Now we have proper map support for native and backported versions of the fragment framework. We also have a look and feel that is closer to what the Maps application itself supports. While we still cannot reach feature parity with the Maps application, our SDK apps can at least look like they belong on the same device as the Maps application. More importantly, as of the time of this writing, Maps V1 is no longer an option for new developers. Those who already have Maps V1 API keys can use Maps V1, but no new Maps V1 API keys are being offered. That leaves you with either using Maps V2 or some alternative mapping solution. Where You Can Use Maps V2 Many devices will be able to use Maps V2… but not all. Notably: 1838 MAPPING WITH MAPS V2 • Devices need to support OpenGL ES 2.0+, to handle the new vector-based tiles that Maps V2 uses. Over 99% of Android devices in use today that support the Play Store (or its “Android Market” predecessor) also support OpenGL ES 2.0+. • Devices will need an update to the Play Services Framework that accompanies the Play Store. Devices that do not have the Play Store — either because they are forever stuck on the old Android Market or, like the Kindle Fire, never had Play Store support in the first place — will be unable to use Maps V2. Later in this chapter, we will look at other mapping libraries that you could use instead of either of Google’s mapping solutions. Licensing Terms for Maps V2 As with the original Maps SDK add-on, to use Maps V2, you must agree to a terms of service agreement to be authorized to embed Google Maps within your application. If you intend to use Maps V2, you should review these terms closely, as they place many restrictions on developers. The most notorious of these is that you cannot use Maps V2 to create an application that offers “real time navigation or route guidance, including but not limited to turn-by-turn route guidance that is synchronized to the position of a user’s sensor-enabled device.” If you find these terms to be an issue for your application, you may need to consider alternative mapping solutions. What You Need to Start If you wish to use Maps V2 in one or more of your Android applications, this section will outline what you need to get started. Your Signing Key Fingerprint(s) As with the legacy Maps SDK add-on, you will need fingerprints of your app signing keys, to tie your apps to your Google account and the API keys you will be generating. However, unlike the legacy Maps SDK add-on, the fingerprints you will be using will be created using the SHA-1 hash algorithm, rather than MD5. 1839 MAPPING WITH MAPS V2 First, you will need to know where the keystore is for your signing key. For a production keystore that you created yourself for your production apps, you should know where it is located already. For the debug keystore, used by default during development, the location is dependent upon operating system: • macOS and Linux: ~/.android/debug.keystore • Windows XP: C:\Documents and Settings\$USER\.android\ debug.keystore • Windows Vista and Windows 7: C:\Users\$USER\.android\debug.keystore (where $USER is your Windows user name) You will then need to run the keytool command, to dump information related to this keystore. The keytool command is in your Java SDK, not the Android SDK. You will need to run this from a command line (e.g., Command Prompt in Windows). The specific command to run is: keytool -list -v -keystore ... -alias androiddebugkey -storepass android -keypass android where the ... is replaced by the path to your debug keystore, enclosed in quotation marks if the path contains spaces. For your production keystore, you would supply your own alias and passwords. This should emit output akin to: Alias name: androiddebugkey Creation date: Aug 7, 2011 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=Android Debug, O=Android, C=US Issuer: CN=Android Debug, O=Android, C=US Serial number: 4e3f2684 Valid from: Sun Aug 07 19:57:56 EDT 2011 until: Tue Jul 30 19:57:56 EDT 2041 Certificate fingerprints: MD5: 98:84:0E:36:F0:B3:48:9C:CD:13:EB:C6:D8:7F:F3:B1 SHA1: E6:C5:81:EB:8A:F4:35:B0:04:84:3E:6E:C3:88:BD:B2:66:52:E7:09 Signature algorithm name: SHA1withRSA Version: 3 You will need to make note of the SHA1 entry (see third line from the bottom of the above sample). 1840 MAPPING WITH MAPS V2 Your Google Account To sign up for an API key, you need a Google account. Ideally, this account would be the same one you intend to use for submitting apps to the Play Store (if, indeed, you intend to do so). Your API Key Given that you are logged into the aforementioned Google account, you can visit the Google Cloud Console to request access to the Maps V2 API. They have a tendency to keep changing this set of pages, but these instructions were good as of late February 2014: • Create a project via the “Create project” option, if you have not done so already for something else (e.g., GCM) • Open your project, then select “APIs & auth” from the left navigation bar, and in there select “APIs” • Sift through the various APIs until you find “Google Maps Android API v2”, then toggle that on • Agree to the Terms of Service that appears when you try to toggle on Maps V2 access • Click “Credentials” in the left navigation bar • Click the “CREATE NEW KEY” button • In the popup dialog, choose “Android key” • In the fields that appear once you chose “Android key”, fill in your app’s package name and your SHA1 fingerprint, then click the “Create” button This will give you an “API key” that you will need for your application. If you wish to have more than one app use Maps V2, you can click “Edit allowed Android applications” for a key, to return to the dialog where you can paste in another SHA1 fingerprint and package name, separated by a semicolon. Or, if you prefer, you can create new keys for each application. For apps that are in (or going to) production, you will need to supply both the debug and production SHA1 fingerprints with your package name. By doing this on the same key, you will use the same API key string for both debug and production builds, which simplifies things a fair bit over the separate API keys you would have used with the legacy Maps SDK add-on. 1841 MAPPING WITH MAPS V2 Also note that a single API key seems to only support a few fingerprint/package pairs. If you try adding a new pair, and the form ignores you, you will need to set up a separate API key for additional pairs. The Play Services Library You also need to set up the Google Play Services library for use with your app. While this used to be published via a separate “Google Repository” that you had to download to your development machine, nowadays, it is part of Google’s overall public Maven repository, the one that google() points to in your build.gradle files. Most likely, your project is already set up to use this repository. If so, all you need to do is add a dependency on com.google.android.gms:play-services-maps for some likely version (e.g., com.google.android.gms:play-services-maps:11.6.2) to your dependencies closure. Note, though, that starting with version 10.x, the minSdkVersion imposed by the Play Services libraries is 14. If your desired minSdkVersion is lower than that, you will need to remain on older versions of the Play Services libraries. The Book Samples… And You! If you wish to try to run the book samples outlined in this chapter, you will need to replace the Maps V2 API key in the manifest with your own. Setting Up a Basic Map With that preparation work completed, now you can start working on projects that use the Maps V2 API. In this section, we will review the MapsV2/Basic sample project, which simply brings up a Maps V2 map of the world. The Dependency Android Studio users need an entry in their top-level dependencies closure to pull in the Play Services SDK artifact: 1842 MAPPING WITH MAPS V2 dependencies { implementation 'com.google.android.gms:play-services-maps:11.6.2' } (from MapsV2/Basic/app/build.gradle) The Project Setup and the Manifest This project uses Maps V2, and so it has a reference to that library project. Our manifest file is fairly traditional, though there are a number of elements in it that are required by Maps V2: > > > (from MapsV2/Basic/app/src/main/AndroidManifest.xml) Specifically: • We need the WRITE_EXTERNAL_STORAGE permissions, but only on Android 5.1 and below, so we can use android:maxSdkVersion="22" to only request that permission on older devices • We need a element, with a name of com.google.android.maps.v2.API_KEY, whose value is the API key we got from the Google APIs Console for use with this particular package name. • We can have a second element, with a name of com.google.android.gms.version, with a value of the @integer/ google_play_services_version (an integer resource supplied by the Play Services SDK library project). Starting with version 8.1.0 of the Maps V2 library, this element is not essential, as it will be added automatically to our manifest via the manifest merger process. However, code written for older versions of Maps V2 than 8.1.0 will need the element, and there is no particular harm in having it. We also should include a element for OpenGL ES 2.0. If your app absolutely must be able to run Maps V2, have android:required="true" (or drop the android:required attribute entirely, as true is the default), which will force devices to have OpenGL ES 2.0 to run your app. If your app will gracefully degrade for devices incapable of running Maps V2, use android:required="false", as is shown in the sample. Beyond those items, everything else in this project is based on what the app needs, more so than what Maps V2 needs. Note, though, that the Play Services SDK library project will add additional items to our manifest, notably requests for a few other permissions, like INTERNET. Also note that we used to need to define and use a custom permission, based upon our app’s package name and ending in MAPS_RECEIVE. This is not required as of Play Services 3.1.59 and the “rev 8” release of the Play Services SDK. 1844 MAPPING WITH MAPS V2 The Play Services Detection In the fullness of time, all devices that are capable of using Maps V2 will already have the on-device portion of this logic, known as the “Google Play services” app. However, it is entirely possible, in the short term, that you will encounter devices that are capable of using Maps V2 (e.g., they have OpenGL ES 2.0 or higher), but do not have the “Google Play services” app from the Play Store, and therefore you cannot actually use Maps V2 in your app. This is a departure from the Maps V1 approach, where either the device shipped with maps capability, or it did not, and nothing (legally) could be done to change that state. To determine whether or not the Maps V2 API is available to you, the best option is to call the isGooglePlayServicesAvailable() static method on the GooglePlayServicesUtil utility class supplied by the Play Services library. This will return an int, with a value of ConnectionResult.SUCCESS if Maps V2 can be used right away. Actually assisting the user to get Maps V2 set up all the way is conceivable but is also bug-riddled and annoying. The MapsV2/Basic sample app has an AbstractMapActivity base class that is designed to hide most of this annoyance from you. If you wish to know the details of how this works, we will cover it later in this chapter. The Fragment and Activity Our main activity — MainActivity — extends from the aforementioned AbstractMapActivity and simply overrides onCreate(), as most activities do: package com.commonsware.android.mapsv2.basic; import android.os.Bundle android.os.Bundle; public class MainActivity extends AbstractMapActivity { @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); if (readyToGo()) { setContentView(R.layout.activity_main); 1845 MAPPING WITH MAPS V2 } } } (from MapsV2/Basic/app/src/main/java/com/commonsware/android/mapsv2/basic/MainActivity.java) We call setContentView() to load up the activity_main layout resource: /> (from MapsV2/Basic/app/src/main/res/layout/activity_main.xml) That resource, in turn, has a element pointing to a com.google.android.gms.maps.MapFragment class supplied by the Play Services library. This is a fragment that knows how to display a Maps V2 map. There is a corresponding com.google.android.gms.maps.SupportMapFragment class for use with the fragments backport from the Android Support library. You will notice, though, that we only call setContentView() if a readyToGo() method returns true. The readyToGo() method is supplied by the AbstractMapActivity class and returns true if we are safe to go ahead and use Maps V2, false otherwise. In the false case, AbstractMapActivity will be taking care of trying to get Maps V2 going, and we need do nothing further. The Result When you run the app, assuming that Maps V2 is ready for use, you will get a basic map showing a good-sized chunk of the planet: 1846 MAPPING WITH MAPS V2 Figure 596: Maps V2 Map, as Initially Viewed If your Maps V2 API key is incorrect, or you do not have this app’s package name set up for that key in the Google APIs Console, you will get an “Authorization failure” error message in Logcat, and you will get a blank map, akin to the behavior seen in Maps V1 when you had an invalid android:apiKey attribute on the MapView. Playing with the Map Showing a map of a good-sized chunk of the planet is nice, and it is entirely possible that is precisely what you wanted to show the user. If, on the other hand, you wanted to show the user something else — another location, a closer look, etc. — you will need to further configure your map, via a GoogleMap object. To see how this is done, take a look at the MapsV2/NooYawk sample application. This is a clone of MapsV2/Basic that adds in logic to center and zoom the map over a portion of New York City. The onCreate() method of the revised MapActivity is now a bit more involved: @Override protected void onCreate(Bundle savedInstanceState) { 1847 MAPPING WITH MAPS V2 super super.onCreate(savedInstanceState); if (readyToGo()) { setContentView(R.layout.activity_main); MapFragment mapFrag= (MapFragment)getFragmentManager().findFragmentById(R.id.map); if (savedInstanceState == null null) { mapFrag.getMapAsync(this this); } } } (from MapsV2/NooYawk/app/src/main/java/com/commonsware/android/mapsv2/nooyawk/MainActivity.java) After calling setContentView(), we can retrieve our MapFragment via findFragmentById(), no different than any other static fragment. Then, if savedInstanceState is null — meaning that the activity is not being recreated, but instead is being created from scratch — we call getMapAsync() on the MapFragment. This triggers some asynchronous work to set up a GoogleMap object. getMapAsync() takes an implementation of OnMapReadyCallback as a parameter. In this case, OnMapReadyCallback is implemented on the activity itself. That GoogleMap object will then be delivered to us in onMapReady(). Most of our work in configuring the map will be accomplished by calling methods on this GoogleMap object: @Override public void onMapReady(GoogleMap map) { CameraUpdate center= CameraUpdateFactory.newLatLng(new new LatLng(40.76793169992044, -73.98180484771729)); CameraUpdate zoom=CameraUpdateFactory.zoomTo(15); map.moveCamera(center); map.animateCamera(zoom); } (from MapsV2/NooYawk/app/src/main/java/com/commonsware/android/mapsv2/nooyawk/MainActivity.java) To change where the map is centered, we can create a CameraUpdate object from the CameraUpdateFactory (“camera” in this case referring to the position of the user’s virtual eyes with respect to the surface of the Earth). The newLatLng() factory 1848 MAPPING WITH MAPS V2 method on CameraUpdateFactory will give us a CameraUpdate object that can recenter the map over a supplied latitude and longitude. Those coordinates are encapsulated in a LatLng object and are maintained as decimal degrees as Java float or double values (as opposed to the Maps V1 GeoPoint, which used integer microdegrees). To change the zoom level of the map, we need another CameraUpdate object, this time from the zoomTo() factory method on CameraUpdateFactory. As with Maps V1, the zoom levels start at 1 and zoom in by powers of two. As you will see, a value of 15 gives you a nice block-level view of a city like New York City. To actually apply these changes to the map, we have two methods on GoogleMap: 1. moveCamera() will perform a “smash cut” and immediately change the map based upon the supplied CameraUpdate 2. animateCamera() will smoothly animate the map from its original state to the new state supplied by the CameraUpdate In our case, we immediately shift to the proper position, but then zoom in from the default zoom level to 15, giving us a map centered over Columbus Circle, in the southwest corner of Central Park in Manhattan: 1849 MAPPING WITH MAPS V2 Figure 597: Maps V2 Centered Over Columbus Circle, New York City Note that you might want to do both actions simultaneously, rather than have one be animated and one not as in this sample. In that case, you can manually create a CameraPosition object that describes the desired center, zoom, etc., then use the newCameraPosition() method on CameraUpdateFactory to get a CameraUpdate instance that will apply all of those changes. Map Tiles The map, by default, shows the normal tile set. setMapType() on the GoogleMap allows you to switch to satellite, hybrid (satellite view plus place labels), or terrain tile sets. Placing Simple Markers For markers — push-pins and the like — you simply hand markers to the GoogleMap for display, as is illustrated in the MapsV2/Markers sample application. This is a clone of MapsV2/NooYawk, with four markers for four landmarks within Manhattan. 1850 MAPPING WITH MAPS V2 Our onCreate() method on MainActivity now always invokes getMapAsync(), not just when the activity is first created. However, we still check savedInstanceState and set a new needsInit boolean data member to true if savedInstanceState is null: @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); if (readyToGo()) { setContentView(R.layout.activity_main); MapFragment mapFrag= (MapFragment)getFragmentManager().findFragmentById(R.id.map); if (savedInstanceState == null null) { needsInit=true true; } mapFrag.getMapAsync(this this); } } (from MapsV2/Markers/app/src/main/java/com/commonsware/android/mapsv2/markers/MainActivity.java) Our onMapReady() method performs the camera adjustments if needsInit is true. It also has four additional statements – calls to a private addMarker() method to define the four landmarks: @Override public void onMapReady(GoogleMap map) { if (needsInit) { CameraUpdate center= CameraUpdateFactory.newLatLng(new new LatLng(40.76793169992044, -73.98180484771729)); CameraUpdate zoom=CameraUpdateFactory.zoomTo(15); map.moveCamera(center); map.animateCamera(zoom); } addMarker(map, 40.748963847316034, -73.96807193756104, R.string.un, R.string.united_nations); addMarker(map, 40.76866299974387, -73.98268461227417, R.string.lincoln_center, R.string.lincoln_center_snippet); addMarker(map, 40.765136435316755, -73.97989511489868, 1851 MAPPING WITH MAPS V2 R.string.carnegie_hall, R.string.practice_x3); addMarker(map, 40.70686417491799, -74.01572942733765, R.string.downtown_club, R.string.heisman_trophy); } (from MapsV2/Markers/app/src/main/java/com/commonsware/android/mapsv2/markers/MainActivity.java) The addMarker() method on our MainActivity adds markers by creating a MarkerOptions object and passing it to the addMarker() on GoogleMap. MarkerOptions offers a so-called “fluent” interface, with a series of methods to affect one aspect of the MarkerOptions, each of which returns the MarkerOptions object itself. That way, configuring a MarkerOptions is a chained series of method calls: private void addMarker(GoogleMap map, double lat, double lon, int title, int snippet) { map.addMarker(new new MarkerOptions().position(new new LatLng(lat, lon)) .title(getString(title)) .snippet(getString(snippet))); } (from MapsV2/Markers/app/src/main/java/com/commonsware/android/mapsv2/markers/MainActivity.java) Here, we: • Set the position() of the marker, in the form of another LatLng object • Set the title() and snippet() of the marker to be a pair of strings loaded from string resources We will see other methods available on MarkerOptions in upcoming sections of this chapter. addMarker() on GoogleMap returns an actual Marker object, which we could hold onto to change certain aspects of it later on (e.g., its title). In the case of this sample, we ignore this. Now, you may be wondering why we set up the markers on every onMapReady() invocation, not just in the needsInit block. That is because while a MapFragment retains its camera information (center, zoom, etc.) on a configuration change, it does not retain its markers. Hence, we need to re-establish the markers in all calls to onCreate(), not just the very first one. With no other changes, we get a version of the map that shows markers at our designated locations: 1852 MAPPING WITH MAPS V2 Figure 598: Maps V2 with Two Markers Initially, we only see two markers, as the other two are outside the current center position and zoom level of the map. If the user changes the center or zoom, markers will come and go as needed: 1853 MAPPING WITH MAPS V2 Figure 599: Maps V2 with All Four Markers We do not need to worry about managing the markers ourselves, so long as the GoogleMap performance is adequate. It is likely that dumping 10,000 markers into a GoogleMap will still result in sluggish responses, though, so you may need to add and remove markers yourself based upon what portion of the world the user happens to be examining in the map at the moment. Seeing All the Markers When you add markers to a map, there is no guarantee that the markers will be visible given the map’s current center position and zoom level. In fact, it is entirely possible that you add a bunch of markers and none are visible, so the user may not realize that the markers were added. There is a way that you can center and zoom the map to show some set of markers, based on their positions. You get to choose the markers: all of them, the four nearest markers, etc. 1854 MAPPING WITH MAPS V2 We can see how this works in the MapsV2/Bounds sample application. This is a clone of MapsV2/Markers from the previous section, with reworked code to show all four markers when the map is first displayed. The key to making this work is a LatLngBounds object. This represents a bounding box that contains all LatLng locations handed to the LatLngBounds. To build up a LatLngBounds, you can use the LatLngBounds.Builder class. So, our revised MainActivity has a LatLngBounds.Builder private data member: private LatLngBounds.Builder builder=new new LatLngBounds.Builder(); (from MapsV2/Bounds/app/src/main/java/com/commonsware/android/mapsv2/markers/MainActivity.java) Our revised addMarker() method adds the LatLng values from our markers as they are added to the map: private void addMarker(GoogleMap map, double lat, double lon, int title, int snippet) { Marker marker= map.addMarker(new new MarkerOptions().position(new new LatLng(lat, lon)) .title(getString(title)) .snippet(getString(snippet))); builder.include(marker.getPosition()); } (from MapsV2/Bounds/app/src/main/java/com/commonsware/android/mapsv2/markers/MainActivity.java) Finally, the revised onMapReady() moves the CameraUpdateFactory work until after all four of the addMarker() calls and changes it a bit: @Override public void onMapReady(final final GoogleMap map) { addMarker(map, 40.748963847316034, -73.96807193756104, R.string.un, R.string.united_nations); addMarker(map, 40.76866299974387, -73.98268461227417, R.string.lincoln_center, R.string.lincoln_center_snippet); addMarker(map, 40.765136435316755, -73.97989511489868, R.string.carnegie_hall, R.string.practice_x3); addMarker(map, 40.70686417491799, -74.01572942733765, R.string.downtown_club, R.string.heisman_trophy); if (needsInit) { findViewById(android.R.id.content).post(new new Runnable() { @Override 1855 MAPPING WITH MAPS V2 public void run() { CameraUpdate allTheThings= CameraUpdateFactory.newLatLngBounds(builder.build(), 32); map.moveCamera(allTheThings); } }); } } (from MapsV2/Bounds/app/src/main/java/com/commonsware/android/mapsv2/markers/MainActivity.java) Specifically, we: • Ask the LatLngBounds.Builder to build() the LatLngBounds • Pass that to the newLatLngBounds() method on CameraUpdateFactory, along with an inset value in pixels (all LatLng locations will be that many pixels in from the edges, or more) • Use moveCamera() to center and zoom the map based upon the resulting CameraUpdate All of this is done in a Runnable which we post() to a View (here, the FrameLayout of our activity supplied by Android as android.R.id.content). GoogleMap cannot ensure that all of our markers are visible until it knows how big the map is, and that is not known until the map is rendered to the screen. post() will add our work to the end of the main application thread’s work queue. The Runnable will not be run until after the map is on the screen, at which time the CameraUpdate can work. Flattening and Rotating Markers Markers, by default, appear to be “push pins” pressed into the surface of the map. This is not necessarily obvious with the default top-down perspective of the map camera. But, if you use a two-finger vertical swiping gesture, you can change the camera tilt, and that will illustrate the “push pin” effect a bit better: 1856 MAPPING WITH MAPS V2 Figure 600: Maps V2 with Markers, Viewed on a Tilt However, you have options for flat markers and rotated markers. A flat marker is one that is flat on the map. In other words, rather than theoretically rising out of the Z axis of the map, the marker is kept on the X-Y plane: 1857 MAPPING WITH MAPS V2 Figure 601: Maps V2 with Markers, One Normal, One Flat It is also possible to rotate a marker. The flat marker in the previous screenshot is rotated 90 degrees from its normal “bulb on the north side” orientation. The following screenshot shows another flat marker, rotated 270 degrees from normal: 1858 MAPPING WITH MAPS V2 Figure 602: Maps V2 with Markers, Flat and Rotated These features can be handy for providing pointers in a particular direction, such as indicating not only the location to make a turn, but what direction to turn at that location. These capabilities are courtesy of flat() and rotation() methods on MarkerOptions, plus corresponding getters and setters on Marker itself. To see how this works, let’s examine the MapsV2/FlatMarkers sample application. This is a clone of MapsV2/Markers, with markers applied using different values for flat() and rotation(). Specifically, our own addMarker() helper method now takes and applies a boolean parameter for flat (true means it is flat, false means normal behavior), as well as a float parameter for rotation (a value between 0 and 360 for the rotation off the default in degrees): private void addMarker(GoogleMap map, double lat, double lon, int title, int snippet, boolean flat, float rotation) { map.addMarker(new new MarkerOptions().position(new new LatLng(lat, lon)) .title(getString(title)) .snippet(getString(snippet)) 1859 MAPPING WITH MAPS V2 .flat(flat).rotation(rotation)); } (from MapsV2/FlatMarkers/app/src/main/java/com/commonsware/android/mapsv2/flatmarkers/MainActivity.java) When we call addMarker(), we supply corresponding values: addMarker(map, 40.748963847316034, -73.96807193756104, R.string.un, R.string.united_nations, false false, 180); addMarker(map, 40.76866299974387, -73.98268461227417, R.string.lincoln_center, R.string.lincoln_center_snippet, false false, 0); addMarker(map, 40.765136435316755, -73.97989511489868, R.string.carnegie_hall, R.string.practice_x3, true true, 90); addMarker(map, 40.70686417491799, -74.01572942733765, R.string.downtown_club, R.string.heisman_trophy, true true, 270); (from MapsV2/FlatMarkers/app/src/main/java/com/commonsware/android/mapsv2/flatmarkers/MainActivity.java) Sprucing Up Your “Info Windows” If the user taps on one of the markers from the preceding sample, Android will automatically display a popup, known as an “info window”: 1860 MAPPING WITH MAPS V2 Figure 603: Maps V2 with Default Info Window You can tailor that “info window” if desired, either replacing just the interior portion (leaving the bounding border with its caret intact) or replacing the entire window. However, in the interests of memory conservation, you do not hand new View widgets to the MarkerOptions object. Instead, you can provide an adapter that will be called when info windows (or their contents) are required. To see how this works, we can examine the MapsV2/Popups sample application. This is a clone of MapsV2/Markers, where we are using our own layout file for the contents of the info windows, from the popup.xml layout resource: > /> > /> /> (from MapsV2/Popups/app/src/main/res/layout/popup.xml) Here, we will show the title and snippet in our own chosen font size and weight, plus show the launcher icon on the left. To use this layout, we must create an InfoWindowAdapter implementation — in the case of this sample project, that is found in the PopupAdapter class: package com.commonsware.android.mapsv2.popups; import import import import import import android.annotation.SuppressLint android.annotation.SuppressLint; android.view.LayoutInflater android.view.LayoutInflater; android.view.View android.view.View; android.widget.TextView android.widget.TextView; com.google.android.gms.maps.GoogleMap.InfoWindowAdapter com.google.android.gms.maps.GoogleMap.InfoWindowAdapter; com.google.android.gms.maps.model.Marker com.google.android.gms.maps.model.Marker; class PopupAdapter implements InfoWindowAdapter { private View popup=null null; private LayoutInflater inflater=null null; PopupAdapter(LayoutInflater inflater) { this this.inflater=inflater; 1862 MAPPING WITH MAPS V2 } @Override public View getInfoWindow(Marker marker) { return return(null null); } @SuppressLint("InflateParams") @Override public View getInfoContents(Marker marker) { if (popup == null null) { popup=inflater.inflate(R.layout.popup, null null); } TextView tv=(TextView)popup.findViewById(R.id.title); tv.setText(marker.getTitle()); tv=(TextView)popup.findViewById(R.id.snippet); tv.setText(marker.getSnippet()); return return(popup); } } (from MapsV2/Popups/app/src/main/java/com/commonsware/android/mapsv2/popups/PopupAdapter.java) When an info window is to be displayed, Android will first call getInfoWindow() on our InfoWindowAdapter, passing in the Marker whose info window is needed. If we return a View here, that will be used for the entire info window. If, instead, we return null, Android will call getInfoContents(), passing in the same Marker object. If we return a View here, Android will use that as the “body” of the info window, with Android supplying the border. If we return null, the default info window is displayed. This way, we can conditionally do any of the three possibilities (replace the window, replace the contents, or accept the default). In our case, getInfoContents() will inflate the popup.xml layout and populate the two TextView widgets with the title and snippet from the Marker. However, we cache the inflated layout and reuse it on the second and subsequent calls to getInfoContents(). Despite the “adapter” name conjuring up visions of ListAdapter and having multiple outstanding views, InfoWindowAdapter will only ever use one View at a time. Hence, rather than inflate our layout each time we need to show the info window, we can safely reuse the previously-used View. 1863 MAPPING WITH MAPS V2 Then, we just need to tell the GoogleMap to use our InfoWindowAdapter, via a call to setInfoWindowAdapter(), such as this statement from onMapReady() of our new edition of MainActivity: map.setInfoWindowAdapter(new new PopupAdapter(getLayoutInflater())); (from MapsV2/Popups/app/src/main/java/com/commonsware/android/mapsv2/popups/MainActivity.java) Now, when the user taps on a marker, they will get our customized info window: Figure 604: Maps V2 with Customized Info Window We can also call setOnInfoWindowClickListener() on our GoogleMap, passing in an implementation of the OnInfoWindowClickListener interface, to find out when the user taps on the info window. In the case of MainActivity, we set up the activity itself to implement that interface and be the listener: map.setOnInfoWindowClickListener(this this); (from MapsV2/Popups/app/src/main/java/com/commonsware/android/mapsv2/popups/MainActivity.java) This requires us to implement an onInfoWindowClick() method, where we are passed the Marker representing the tapped-upon info window: @Override public void onInfoWindowClick(Marker marker) { Toast.makeText(this this, marker.getTitle(), Toast.LENGTH_LONG).show(); } 1864 MAPPING WITH MAPS V2 (from MapsV2/Popups/app/src/main/java/com/commonsware/android/mapsv2/popups/MainActivity.java) Here, we just display a Toast with the title of the Marker when the user taps an info window: Figure 605: Maps V2 with Toast Triggered by Tap on Info Window Note that, according to the documentation, you can only find out about taps on the entire info window. Indeed, if you try setting up click listeners on the widgets in your custom layout, you will find that they are not called. This is because the View you return for the info window is converted into a Bitmap, which is then displayed. Presumably, this is to steer developers in the direction of making larger tap targets, rather than expecting users to tap tiny elements within an info window. On the other hand, if your design calls for a large info window containing several navigation options, you will need to either re-think your design or avoid the info window system. We will see how to find out about taps on markers more directly later in this chapter. Images and Your Info Window The Bitmap approach that Maps V2 uses for the info window introduces an additional challenge: updating the info window itself. Normally, we would just 1865 MAPPING WITH MAPS V2 update the individual widgets in the info window, the way we might update widgets in an already-visible row in a ListView. However, that is not an option here, as our widgets are discarded almost immediately. One particular occurrence of this problem comes when you want to show an image in the info window. If the image is a resource, or is already in memory, showing it is not a big problem, as you can just populate your ImageView in your info window with it. However, if the image is a file (or, worse, needs to be downloaded), you want to load the image asynchronously. However, if you kick off some background thread, like an AsyncTask, to retrieve the image, you will return from your InfoWindowAdapter method long before the task is complete. Your info window will show whatever placeholder image you used; the image you loaded will never be seen, even if you update your original ImageView. There are two solutions to this problem. The best solution, by far, is to have the images before you need them, wherever possible. For example, if you are showing a map with 25 markers, for which you need 25 thumbnail images, start downloading those images while you are showing the map. With luck, at the point in time when the user taps on a marker to show the info window, you will have your image already. However, this approach will not work well if: • You need a ridiculous number of images, or • You need images, but they need to be downloaded full-sized and turned into thumbnails locally, as that might consume quite a bit of bandwidth, or • Your last name is Murphy, and therefore the user taps on an info window before you have had a chance to prepare its image The workaround is to make note of the Marker the user tapped upon to open its info window, then call showInfoWindow() on that Marker to cause the info window to be redisplayed once you have your image, triggering calls to your InfoWindowAdapter. There, you can see that your image cache includes the image that you need, and you can apply it to the info window. The problem here is that it is possible that the user tapped on another marker, after the first one, while you were busily fetching and loading the image. Hence, rather than blindly calling showInfoWindow() on the Marker, you should call isInfoWindowShown() first, and only call showInfoWindow() to force the refresh if isInfoWindowShown() returns true. Otherwise, some other marker’s info window is 1866 MAPPING WITH MAPS V2 shown. The user is not expecting this earlier info window to somehow magically reappear. All of this is a pain. It can be made a bit less of a pain by use of an image fetchingand-caching library like Picasso. We can see how this can be applied by looking at the MapsV2/ImagePopups sample application. This is a clone of MapsV2/Popups, with some additions to handle lazy-populating an info window based upon a downloaded image. First, since we are going to be generating some thumbnails based on downloaded imagery, it helps to establish a fixed-size ImageView for our icon. So, this project has a pair of dimension resources, for the image height and width: >96dp >64dp (from MapsV2/ImagePopups/app/src/main/res/values/dimens.xml) Those are then used in a revised version of the popup layout resource: > /> > /> /> (from MapsV2/ImagePopups/app/src/main/res/layout/popup.xml) We need some way of keeping track of what images should be used for each marker. This is somewhat annoying to implement, as we cannot subclass Marker, since it is marked as final and cannot be extended. However, we can use getId() on a Marker to obtain a unique ID, and we can use that as the key to additional model data. We will examine variations on this technique later in this chapter. For now, this sample gets away with a simple HashMap, mapping the string ID of a Marker to a Uri representing an image to be shown for that Marker’s info window: private HashMap images=new new HashMap(); (from MapsV2/ImagePopups/app/src/main/java/com/commonsware/android/mapsv2/imagepopups/MainActivity.java) Our private addMarker() method now takes a String name of an image, and it adds a Uri pointing to that image to the HashMap, keyed by the ID of the generated Marker: private void addMarker(GoogleMap map, double lat, double lon, int title, int snippet, String image) { Marker marker= map.addMarker(new new MarkerOptions().position(new new LatLng(lat, lon)) .title(getString(title)) .snippet(getString(snippet))); if (image != null null) { images.put(marker.getId(), Uri.parse("http://misc.commonsware.com/mapsv2/" + image)); } } (from MapsV2/ImagePopups/app/src/main/java/com/commonsware/android/mapsv2/imagepopups/MainActivity.java) 1868 MAPPING WITH MAPS V2 For three of our markers, we pass in actual filenames; for a fourth, null is used, indicating that there is no suitable image for use: addMarker(map, 40.748963847316034, -73.96807193756104, R.string.un, R.string.united_nations, "UN_HQ.jpg"); addMarker(map, 40.76866299974387, -73.98268461227417, R.string.lincoln_center, R.string.lincoln_center_snippet, "Avery_Fisher_Hall.jpg"); addMarker(map, 40.765136435316755, -73.97989511489868, R.string.carnegie_hall, R.string.practice_x3, "Carnegie_Hall.jpg"); addMarker(map, 40.70686417491799, -74.01572942733765, R.string.downtown_club, R.string.heisman_trophy, null null); (from MapsV2/ImagePopups/app/src/main/java/com/commonsware/android/mapsv2/imagepopups/MainActivity.java) Note that the three images being used in this chapter come from Wikipedia. One is public domain, the others are licensed under the Creative Commons Attribution 1.0 license. Those two are a picture of Avery Fisher Hall, part of the Lincoln Center for the Performing Arts (courtesy of Geographer) and the other is a picture of the United Nations building (courtesy of WorldIslandInfo). The PopupAdapter needs access to these images. It will also need access to a Context, for use with Picasso. So, PopupAdapter now has data members for these, which are passed into a revised version of its constructor by MainActivity. That constructor not only holds onto the new objects, but it retrieves the values of the dimension resources for our images, converted by Android into pixels for the screen density of the device that we are running on: PopupAdapter(Context ctxt, LayoutInflater inflater, HashMap images) { this this.ctxt=ctxt; this this.inflater=inflater; this this.images=images; iconWidth= ctxt.getResources().getDimensionPixelSize(R.dimen.icon_width); iconHeight= ctxt.getResources().getDimensionPixelSize(R.dimen.icon_height); } (from MapsV2/ImagePopups/app/src/main/java/com/commonsware/android/mapsv2/imagepopups/PopupAdapter.java) 1869 MAPPING WITH MAPS V2 The revised getInfoContents() method is significantly more complicated than was its predecessor: @SuppressLint("InflateParams") @Override public View getInfoContents(Marker marker) { if (popup == null null) { popup=inflater.inflate(R.layout.popup, null null); } if (lastMarker == null || !lastMarker.getId().equals(marker.getId())) { lastMarker=marker; TextView tv=(TextView)popup.findViewById(R.id.title); tv.setText(marker.getTitle()); tv=(TextView)popup.findViewById(R.id.snippet); tv.setText(marker.getSnippet()); Uri image=images.get(marker.getId()); ImageView icon=(ImageView)popup.findViewById(R.id.icon); if (image == null null) { icon.setVisibility(View.GONE); } else { Picasso.with(ctxt).load(image).resize(iconWidth, iconHeight) .centerCrop().noFade() .placeholder(R.drawable.placeholder) .into(icon, new MarkerCallback(marker)); } } return return(popup); } (from MapsV2/ImagePopups/app/src/main/java/com/commonsware/android/mapsv2/imagepopups/PopupAdapter.java) We track the last Marker that we have processed in a lastMarker data member. Initially, of course, that will be null. If it is, or if the Marker passed into getInfoContents() is a different one (based on the getId() value), then we populate the popup View. This includes fetching the Uri from the HashMap of Uri values (given the Marker ID). If there is no Uri, getInfoContents() marks the ImageView as GONE, so it will not take up space in the popup. If, however, there is an image Uri, getInfoContents() asks Picasso to “do its thing”: 1870 MAPPING WITH MAPS V2 • Load the image from the Uri • Resize the image to be the desired dimensions for the ImageView, centercropping to keep the right aspect ratio • Skip the fade-in animation that is normally applied when Picasso populates an ImageView (as the Maps V2 Bitmap is generated before the animation completes, resulting in a washed-out image) • Use a particular placeholder drawable resource while the image is loading • Populate the ImageView with the results, specifying a MarkerCallback to be notified of the results MarkerCallback, as an implementation of Picasso’s Callback interface, needs onError() and onSuccess() methods. onError() just dumps a message to Logcat, while onSuccess() refreshes the info window, via a call to showInfoWindow() on the Marker, if that info window is still showing: static class MarkerCallback implements Callback { Marker marker=null null; MarkerCallback(Marker marker) { this this.marker=marker; } @Override public void onError() { Log.e(getClass().getSimpleName(), "Error loading thumbnail!"); } @Override public void onSuccess() { if (marker != null && marker.isInfoWindowShown()) { marker.showInfoWindow(); } } } (from MapsV2/ImagePopups/app/src/main/java/com/commonsware/android/mapsv2/imagepopups/PopupAdapter.java) If you run this sample app, you will see the popup with a placeholder image at first, quickly being replaced by the thumbnail supplied by Picasso: 1871 MAPPING WITH MAPS V2 Figure 606: Maps V2 with Popup and Thumbnail Setting the Marker Icon Maps V2 includes a stock marker icon that looks a lot like the standard Google Maps marker. You have three major choices for what to use for your own markers: 1. Stick with the stock icon, which is the default behavior 2. Change the stock icon to a different hue 3. Replace the stock icon with your own from an asset, resource, file, or inmemory Bitmap To indicate that you want a different icon than the stock one, use the icon() method on the MarkerOptions fluent interface. This takes a BitmapDescriptor, which you get from one of a series of static methods on the BitmapDescriptorFactory class. For example, you might have a revised version of the addMarker() method of MainActivity that took a hue — a value from 0 to 360 representing different colors along a color wheel. 0 represents red, 120 represents green, and 240 represents blue, with different shades in between. There is a series of HUE_ constants defined on 1872 MAPPING WITH MAPS V2 BitmapDescriptorFactory, plus a defaultMarker() method that takes a hue as a parameter and returns a BitmapDescriptor that will use the stock icon, colored to the specified hue: private void addMarker(GoogleMap map, double lat, double lon, int title, int snippet, int hue) { map.addMarker(new new MarkerOptions().position(new new LatLng(lat, lon)) .title(getString(title)) .snippet(getString(snippet)) .icon(BitmapDescriptorFactory.defaultMarker(hue))); } (from MapsV2/Taps/app/src/main/java/com/commonsware/android/mapsv2/taps/MainActivity.java) This could then be used to give you different colors per marker, or by category of marker, etc.: Figure 607: Maps V2 with Alternate Marker Hues Note that you can modify the icon at runtime via the setIcon() method on the Marker returned by addMarker() method on GoogleMap. However, you cannot draw the marker directly yourself, the way you might have with Maps V1. What you can do is draw to a Bitmap-backed Canvas object, then use the 1873 MAPPING WITH MAPS V2 resulting Bitmap with BitmapFactoryDescriptor and its fromBitmap() factory method. Responding to Taps Perhaps we would like to find out when a user taps on one of our markers, instead of displaying an info window. Maybe we want to have some other UI response to that tap in our app. To do that, simply create an implementation of the OnMarkerClickListener interface and attach it to the GoogleMap via setOnMarkerClickListener(). You will then be called with onMarkerClick() when the user taps on a marker, and you are passed the Marker object in question. If you return true, you are indicating that you are handling the event; returning false means that default handling (the info window) should be done. You can see this, plus the multi-colored markers, in the MapsV2/Taps sample application. This takes MapsV2/Popups and adds a Toast when the user taps a marker, in addition to displaying the info window: @Override public boolean onMarkerClick(Marker marker) { Toast.makeText(this this, marker.getTitle(), Toast.LENGTH_LONG).show(); return return(false false); } (from MapsV2/Taps/app/src/main/java/com/commonsware/android/mapsv2/taps/MainActivity.java) 1874 MAPPING WITH MAPS V2 Figure 608: Maps V2 with Toast and Info Window Our call to setOnMarkerClickListener() is up in the onMapReady() method of MainActivity: map.setOnMarkerClickListener(this this); (from MapsV2/Taps/app/src/main/java/com/commonsware/android/mapsv2/taps/MainActivity.java) Dragging Markers By default, markers are not draggable. But, if you call draggable(true) on your MarkerOptions when creating the marker — or call setDraggable(true) on the Marker later on — Android will automatically support drag-and-drop. The user can tap-and-hold on the marker to enable drag mode, then slide the marker around the map. Note that at the present time, this functionality is a little odd. When you tap-andhold the marker, with drag mode enabled, the marker initially jumps away from its original position. The user can reposition the marker to any desired location, and the marker will seem to “drop” where the user requests. Why the marker makes the sudden shift at the outset, using the default marker settings, is unclear. 1875 MAPPING WITH MAPS V2 Of course, your code may need to know about drag-and-drop events, such as to update your own data model to reflect the newly-chosen location. You can register an OnMarkerDragListener that will be notified of the start of the drag, where the marker slides during the drag, and where the marker is dropped at the end of the drag. You can see all of this in the MapsV2/Drag sample application, which is a clone of MapsV2/Popup with drag-and-drop enabled. To enable drag-and-drop, we just chain draggable(true) onto the series of calls on our MarkerOptions when creating the markers: private void addMarker(GoogleMap map, double lat, double lon, int title, int snippet) { map.addMarker(new new MarkerOptions().position(new new LatLng(lat, lon)) .title(getString(title)) .snippet(getString(snippet)) .draggable(true true)); } (from MapsV2/Drag/app/src/main/java/com/commonsware/android/mapsv2/drag/MainActivity.java) We also register MainActivity as being the drag listener, up in onMapReady(): map.setOnMarkerDragListener(this this); (from MapsV2/Drag/app/src/main/java/com/commonsware/android/mapsv2/drag/MainActivity.java) That requires MainActivity to implement OnMarkerDragListener, which in turn requires three methods to be defined: onMarkerDragStart(), onMarkerDrag(), and onMarkerDragEnd(): @Override public void onMarkerDragStart(Marker marker) { LatLng position=marker.getPosition(); Log.d(getClass().getSimpleName(), String.format("Drag from %f:%f", position.latitude, position.longitude)); } @Override public void onMarkerDrag(Marker marker) { LatLng position=marker.getPosition(); 1876 MAPPING WITH MAPS V2 Log.d(getClass().getSimpleName(), String.format("Dragging to %f:%f", position.latitude, position.longitude)); } @Override public void onMarkerDragEnd(Marker marker) { LatLng position=marker.getPosition(); Log.d(getClass().getSimpleName(), String.format("Dragged to %f:%f", position.latitude, position.longitude)); } (from MapsV2/Drag/app/src/main/java/com/commonsware/android/mapsv2/drag/MainActivity.java) Here, we just dump the information about the new marker position in Logcat. So, if you run this app and drag-and-drop a marker, you will see output in Logcat akin to: 12-19 12-19 12-19 12-19 . . . 12-19 12-19 13:10:36.442: 13:10:36.892: 13:10:36.912: 13:10:36.932: D/MainActivity(22510): D/MainActivity(22510): D/MainActivity(22510): D/MainActivity(22510): Drag from 40.770876:-73.982499 Dragging to 40.770876:-73.981593 Dragging to 40.770795:-73.981352 Dragging to 40.770754:-73.981141 13:10:38.292: D/MainActivity(22510): Dragging to 40.769596:-73.983615 13:10:38.372: D/MainActivity(22510): Dragged to 40.769596:-73.983615 The actual list of events was much longer, as onMarkerDrag() is called a lot, so the ... in the Logcat entries above reflect another 50 or so lines for a drag-and-drop that took a couple of seconds. Also, up in onCreate(), we retain our MapFragment across configuration changes via setRetainInstance(true): mapFrag.setRetainInstance(true true); (from MapsV2/Drag/app/src/main/java/com/commonsware/android/mapsv2/drag/MainActivity.java) Retaining the fragment instance causes the fragment to keep our markers in their moved positions, rather than resetting them to their original positions. 1877 MAPPING WITH MAPS V2 The “Final” Limitations In Maps V2, not only do you not create Marker objects directly yourself, but Marker is marked as final and cannot be extended. Hence, you cannot use a Marker directly to hold model data. However, Marker does have getId(), an immutable identifier for the Marker. We can use that as a key for a HashMap that allows us to get at additional model data associated with the Marker. You can see this approach in the MapsV2/Models sample application, which is a clone of MapsV2/Popup where we use the ID in just this fashion. Our simplified model is merely the data we poured into our Marker objects in the original MapsV2/Popup project: package com.commonsware.android.mapsv2.model; import android.content.Context android.content.Context; public class Model { String title; String snippet; double lat; double lon; Model(Context ctxt, double lat, double lon, int title, int snippet) { this this.title=ctxt.getString(title); this this.snippet=ctxt.getString(snippet); this this.lat=lat; this this.lon=lon; } String getTitle() { return return(title); } String getSnippet() { return return(snippet); } double getLatitude() { return return(lat); } 1878 MAPPING WITH MAPS V2 double getLongitude() { return return(lon); } } (from MapsV2/Models/app/src/main/java/com/commonsware/android/mapsv2/model/Model.java) Our activity holds onto a HashMap of these Model objects, with the map keyed by the Marker ID (a String): private HashMap models=new new HashMap(); (from MapsV2/Models/app/src/main/java/com/commonsware/android/mapsv2/model/MainActivity.java) Of course, a real application would have a much more elaborate setup than this. We then arrange to populate our map with Marker objects created from our Model objects, moving the add-the-markers-to-the-map logic to an addMarkers() method: private void addMarkers(GoogleMap map) { Model model= new Model(this this, 40.748963847316034, -73.96807193756104, R.string.un, R.string.united_nations); models.put(addMarkerForModel(map, model).getId(), model); model= new Model(this this, 40.76866299974387, -73.98268461227417, R.string.lincoln_center, R.string.lincoln_center_snippet); models.put(addMarkerForModel(map, model).getId(), model); model= new Model(this this, 40.765136435316755, -73.97989511489868, R.string.carnegie_hall, R.string.practice_x3); models.put(addMarkerForModel(map, model).getId(), model); model= new Model(this this, 40.70686417491799, -74.01572942733765, R.string.downtown_club, R.string.heisman_trophy); models.put(addMarkerForModel(map, model).getId(), model); } private Marker addMarkerForModel(GoogleMap map, Model model) { LatLng position= new LatLng(model.getLatitude(), model.getLongitude()); 1879 MAPPING WITH MAPS V2 return return(map.addMarker(new new MarkerOptions().position(position) .title(model.getTitle()) .snippet(model.getSnippet()))); } (from MapsV2/Models/app/src/main/java/com/commonsware/android/mapsv2/model/MainActivity.java) Notice that addMarkerForModel() returns the Marker, and we use getId() on that Marker as the key when adding a Model to the HashMap. Our PopupAdapter gets the data for the info window from the Model (though, in truth, in this case, it could have gotten the data from the Marker itself, since we did not add more information to the info window): package com.commonsware.android.mapsv2.model; import import import import import import android.view.LayoutInflater android.view.LayoutInflater; android.view.View android.view.View; android.widget.TextView android.widget.TextView; java.util.HashMap java.util.HashMap; com.google.android.gms.maps.GoogleMap.InfoWindowAdapter com.google.android.gms.maps.GoogleMap.InfoWindowAdapter; com.google.android.gms.maps.model.Marker com.google.android.gms.maps.model.Marker; class PopupAdapter implements InfoWindowAdapter { LayoutInflater inflater=null null; HashMap models=null null; PopupAdapter(LayoutInflater inflater, HashMap models) { this this.inflater=inflater; this this.models=models; } @Override public View getInfoWindow(Marker marker) { return return(null null); } @Override public View getInfoContents(Marker marker) { View popup=inflater.inflate(R.layout.popup, null null); TextView tv=(TextView)popup.findViewById(R.id.title); tv.setText(models.get(marker.getId()).getTitle()); tv=(TextView)popup.findViewById(R.id.snippet); 1880 MAPPING WITH MAPS V2 tv.setText(models.get(marker.getId()).getSnippet()); return return(popup); } } (from MapsV2/Models/app/src/main/java/com/commonsware/android/mapsv2/model/PopupAdapter.java) Visually, this is indistinguishable from the original MapsV2/Popups project. Of course, a real app would have more complex models, perhaps containing more discrete information for a more complex info window. A Bit More About IPC IPC is not only a problem in terms of disappearing Marker objects. If you run a Maps V2 app under Traceview, to see what methods get called and how much time everything takes, you will see that many, many operations with GoogleMap do little in your process, but instead make synchronous calls to a Play Services process to do the real work. You need to avoid manipulating your GoogleMap in time-sensitive portions of your code. Finding the User Many times, the user is looking at a map to figure out where they are. Perhaps they are lost. Perhaps their spouse or significant other thinks that they are lost. Perhaps they think that they were teleported somewhere (e.g., a North African desert) after turning a “frozen wheel” in an icy cavern beneath an island, and therefore are really lost. Stranger things have happened. (well, OK, perhaps not) Regardless, it is often useful to help point out to the user their current location. That is a matter of adding a suitable location permission (e.g., ACCESS_FINE_LOCATION) and calling setMyLocationEnabled(true) on your GoogleMap. This activates a layer that will highlight their location, with the user having an option of having the “camera” (i.e., their perspective on the map) reposition itself to their location and move as they move. This latter capability is activated by a small icon in the upper right of the map. 1881 MAPPING WITH MAPS V2 You can see this in operation in the MapsV2/MyLocation sample application, which is a clone of MapsV2/Popup with standard location tracking enabled. All we do is call two additional methods on our GoogleMap in onCreate(): • setMyLocationEnabled(), indicating that we want the “my location” layer added and automatic tracking to be enabled, and • setOnMyLocationChangeListener(), indicating that we also want to be notified about changes in the user position map.setMyLocationEnabled(true true); map.setOnMyLocationChangeListener(this this); (from MapsV2/MyLocation/app/src/main/java/com/commonsware/android/mapsv2/mylocation/MainActivity.java) That latter method also requires our activity to implement the OnMyLocationChangeListener interface, which in turn requires us to implement the onMyLocationChange() method, which will be called when Maps V2 gets a new location fix: @Override public void onMyLocationChange(Location lastKnownLocation) { Log.d(getClass().getSimpleName(), String.format("%f:%f", lastKnownLocation.getLatitude(), lastKnownLocation.getLongitude())); } (from MapsV2/MyLocation/app/src/main/java/com/commonsware/android/mapsv2/mylocation/MainActivity.java) Here, we simply log the location to Logcat. This is nice and easy, giving us our my-location overlay and arrow indicating the user’s location and orientation: 1882 MAPPING WITH MAPS V2 Figure 609: Maps V2, Showing the User’s Location However, there are three problems here. First, setOnMyLocationChangeListener() is now deprecated, as Google would prefer that you directly request the locations through the LocationClient available from Play Services. Second, there does not appear to be a way to force camera tracking of the user’s position — you are reliant upon the user tapping that icon. You also have no control over the nature of the location provider that is used. However, there is a workaround for this, proposed in a Stack Overflow answer – provide your own location data and update the camera yourself, by means of setLocationSource(). setLocationSource() lets you push locations to the GoogleMap, making other adjustments (e.g., camera position) along the way. To see how this works, take a peek at the MapsV2/Location sample application, which is a clone of MapsV2/Popup with custom location tracking enabled. Along with adding ACCESS_FINE_LOCATION to the manifest, this sample project adds some lines to the onMapReady() implementation of MainActivity to configure the GoogleMap: 1883 MAPPING WITH MAPS V2 locMgr=(LocationManager)getSystemService(LOCATION_SERVICE); crit.setAccuracy(Criteria.ACCURACY_FINE); locMgr.requestLocationUpdates(0L, 0.0f, crit, this this, null null); map.setLocationSource(this this); map.setMyLocationEnabled(true true); map.getUiSettings().setMyLocationButtonEnabled(false false); (from MapsV2/Location/app/src/main/java/com/commonsware/android/mapsv2/location/MainActivity.java) The first three lines get access to a LocationManager, indicate that a Criteria object (initialized as a data member) should require fine accuracy, and request location updates. These come from the location tracking subsystem in Android. The next two lines register our activity as being the source of location data and turns on location tracking in the GoogleMap, so the user’s position will be marked on the map. The last line disables the user’s control over whether the camera position tracks their movement, since we want that to always be on in this case. In onResume() and onPause() of MainActivity, we enable and disable getting location updates, as is typical of an activity needing location data. However, we also tell the GoogleMap that we are going to supply it with location data, rather than it having to obtain location data itself: @Override public void onResume() { super super.onResume(); if (locMgr!=null null) { locMgr.requestLocationUpdates(0L, 0.0f, crit, this this, null null); } if (map!=null null) { map.setLocationSource(this this); } } @Override public void onPause() { map.setLocationSource(null null); locMgr.removeUpdates(this this); 1884 MAPPING WITH MAPS V2 super super.onPause(); } (from MapsV2/Location/app/src/main/java/com/commonsware/android/mapsv2/location/MainActivity.java) Note that we are blindly assuming that we will get location data. A production-grade app would put in better smarts to confirm that we will actually learn our location via this Criteria (e.g., the user does not have all location providers disabled). Also note that because the map initialization is now happening on a background thread, onResume() might be called before onMapReady(), and so onResume() has to check to see if we already have a LocationManager and GoogleMap before proceeding. The call to setLocationSource() — both in onMapReady() and onResume() – tells GoogleMap that our MainActivity itself is to be the source of location data. This requires MainActivity to implement the LocationSource interface, requiring us to implement activate() and deactivate() methods: @Override public void activate(OnLocationChangedListener listener) { this this.mapLocationListener=listener; } @Override public void deactivate() { this this.mapLocationListener=null null; } (from MapsV2/Location/app/src/main/java/com/commonsware/android/mapsv2/location/MainActivity.java) activate() provides us with an OnLocationChangedListener, from GoogleMap, to which we need to pass location data as we get it. deactivate() indicates that we should no longer attempt to contact that listener. In addition to holding onto that listener (or removing our reference to it when deactivated), we also take this opportunity to request and remove location updates. The onLocationChanged() method — where we get our location fixes from LocationManager via the LocationListener interface — must pass the location along to the GoogleMap-supplied OnLocationChangedListener, if we have such a listener available: @Override public void onLocationChanged(Location location) { if (mapLocationListener != null null) { 1885 MAPPING WITH MAPS V2 mapLocationListener.onLocationChanged(location); LatLng latlng= new LatLng(location.getLatitude(), location.getLongitude()); CameraUpdate cu=CameraUpdateFactory.newLatLng(latlng); map.animateCamera(cu); } } (from MapsV2/Location/app/src/main/java/com/commonsware/android/mapsv2/location/MainActivity.java) Here, we also create a CameraUpdate representing the new location and animate that update, to have the map slide over to the new location, centering the camera on the user’s updated position. The net effect of all of this is that the map continuously re-centers itself to show the user’s position, which GoogleMap is highlighting on the map for us. Dealing with Runtime Permissions The previous section claimed three problems with the MyLocation sample, yet only explained two of them. That is because the third problem is shared by the Location sample as well: the apps are oblivious to Android 6.0’s runtime permissions system. Both samples have a targetSdkVersion of 22. They will install just fine on an Android 6.0 device, triggering the classic “accept all permissions at install time” dialog if installed by any means other than development tools. However, this also means that the apps will not know if the user goes into Settings and revokes the app’s access to location data. Besides, eventually something will force your hand to have a targetSdkVersion of 23 or higher, and that will require you to adopt the new runtime permission system, whether you like it or not. The MapsV2/MyLocationMNC sample application is nearly identical to the MyLocation sample, except that it has a targetSdkVersion of 23 and it makes limited use of the runtime permission system. onCreate() of MainActivity now looks radically different: @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); 1886 MAPPING WITH MAPS V2 if (savedInstanceState==null null) { needsInit=true true; } else { isInPermission= savedInstanceState.getBoolean(STATE_IN_PERMISSION, false false); } onCreateForRealz(canGetLocation()); } (from MapsV2/MyLocationMNC/app/src/main/java/com/commonsware/android/mapsv2/mylocation/MainActivity.java) Most of the original business logic from onCreate() has been moved into onCreateForRealz(). That method takes a boolean parameter, indicating whether or not we have permission to access the user’s location. Here, we get that from a canGetLocation() method that, in turn, uses ContextCompat.checkSelfPermission() to see if we hold ACCESS_FINE_LOCATION: private boolean canGetLocation() { return return(ContextCompat.checkSelfPermission(this this, Manifest.permission.ACCESS_FINE_LOCATION)== PackageManager.PERMISSION_GRANTED); } (from MapsV2/MyLocationMNC/app/src/main/java/com/commonsware/android/mapsv2/mylocation/MainActivity.java) If we can work with locations, onCreateForRealz() will do what onCreate() used to do: call readyToGo() and, if we are ready to go, bring up the map: private void onCreateForRealz(boolean canGetLocation) { if (canGetLocation) { if (readyToGo()) { setContentView(R.layout.activity_main); MapFragment mapFrag= (MapFragment)getFragmentManager().findFragmentById( R.id.map); mapFrag.getMapAsync(this this); } } else if (!isInPermission) { isInPermission=true true; ActivityCompat.requestPermissions(this this, new String[] {Manifest.permission.ACCESS_FINE_LOCATION}, 1887 MAPPING WITH MAPS V2 REQUEST_PERMS); } } (from MapsV2/MyLocationMNC/app/src/main/java/com/commonsware/android/mapsv2/mylocation/MainActivity.java) If we do not have access to the user’s location, this particular sample app is not that interesting, so we will ask the user for permission, via a call to ActivityCompat.requestPermissions(). This will eventually trigger a call to onRequestPermissionsResult(): @Override public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) { isInPermission=false false; if (requestCode==REQUEST_PERMS) { if (canGetLocation()) { onCreateForRealz(true true); } else { finish(); // denied permission, so we're done } } } (from MapsV2/MyLocationMNC/app/src/main/java/com/commonsware/android/mapsv2/mylocation/MainActivity.java) Here, if we can now get the location, we go ahead and run through onCreateForRealz() again, to initialize the map. If, however, the user denied us the right to access the location, we finish() and exit the activity outright. One could argue that a better approach would be to show the map and simply not call setMyLocationEnabled(true) or setOnMyLocationChangeListener(). That would be another approach to dealing with the missing permission, and it is probably the better option if your primary goal was to just show a map. Throughout this code, you have seen references to an isInPermission field. This tracks whether or not we are in the middle of requesting a permission: • • • • It is initialized to false in the activity It is set to true just before calling requestPermissions() It is set back to false in onRequestPermissionsResult() It is saved across configuration changes via onSaveInstanceState() and is retrieved from that state in onCreate(): 1888 MAPPING WITH MAPS V2 @Override protected void onSaveInstanceState(Bundle outState) { super super.onSaveInstanceState(outState); outState.putBoolean(STATE_IN_PERMISSION, isInPermission); } (from MapsV2/MyLocationMNC/app/src/main/java/com/commonsware/android/mapsv2/mylocation/MainActivity.java) (where STATE_IN_PERMISSION is a static final String to use as a key for the Bundle value) This allows us to check whether or not we are in the middle of requesting permissions already in onCreateForRealz() and avoid popping up the permissionrequest dialog twice if the user rotates the screen while the first dialog is up, then denies the permission. Also note that we are not taking any steps here to leverage ActivityCompat.showShowRequestPermissionRationale(), in case the user denied the permission on some previous run of our app, but then ran the app again. You could do something for that here, such as pop up a dialog and call requestPermissions() afterwards. Drawing Lines and Areas If you wanted to draw on a map in the Maps V1 framework, you created an Overlay and drew upon it. This forced you to handle low-level drawing work yourself, as you were handed a Canvas object and had to handle all the lines, fills, and so forth yourself. Maps V2 offers a different approach. Free-form drawing is still conceivable, though it appears to have to be handled in the form of tile overlays instead of map overlays. However, for the simpler cases of drawing lines and areas, Maps V2 has built-in polyline, polygon, and circle support. You tell the GoogleMap what needs to be drawn, and it handles drawing it, both initially and as the map is zoomed or panned. A polyline is a line connecting a series of points; a polygon is a region defined by a series of corners. A circle, from the standpoint of Maps V2, is defined by a center coordinate and a radius. We can see polylines and polygons on a GoogleMap in the MapsV2/Poly sample application, which is a clone of MapsV2/Popup with two additions: 1889 MAPPING WITH MAPS V2 • A polyline connecting the locations of our four markers • A polygon enclosing the area of Manhattan known as the Garment District (bounded by 34th Street, 42nd Street, Fifth Avenue, and Ninth Avenue) To draw those, we simply add a few lines to onMapReady() of MainActivity: PolylineOptions line= new PolylineOptions().add(new new LatLng(40.70686417491799, -74.01572942733765), new LatLng(40.76866299974387, -73.98268461227417), new LatLng(40.765136435316755, -73.97989511489868), new LatLng(40.748963847316034, -73.96807193756104)) .width(5).color(Color.RED); map.addPolyline(line); PolygonOptions area= new PolygonOptions().add(new new LatLng(40.748429, new LatLng(40.753393, new LatLng(40.758393, new LatLng(40.753484, .strokeColor(Color.BLUE); -73.984573), -73.996311), -73.992705), -73.980882)) map.addPolygon(area); (from MapsV2/Poly/app/src/main/java/com/commonsware/android/mapsv2/poly/MainActivity.java) The API for adding polylines and polygons is reminiscent of the API for adding markers: define an ...Options object with the characteristics of the item to be drawn, then call an add...() method on GoogleMap to add the item. So, to add a polyline, we create a PolylineOptions object. Using its fluent interface, we add() a series of LatLng objects, representing the points to be connected by the line. We also specify the line width in pixels via width() and the color of the line via color(). If we had several lines that might overlap, we could specify the zIndex(), where higher indexes indicate lines to be drawn over the top of lines with lower indexes. We add the polyline to the map by passing our PolylineOptions to addPolyline() on GoogleMap. This gives us a line connecting the four markers, with GoogleMap handling the details of where the line should be drawn on the screen given the current map center and zoom levels: 1890 MAPPING WITH MAPS V2 Figure 610: Maps V2 with Polyline Note that the polyline is drawn using a flat Mercator projection by default. For most maps, that is perfectly fine. If your map will be showing countries and continents, rather than city blocks, you might want to call geodesic(true) on the PolylineOptions, to have the line drawn on a geodesic curve, reflecting the spherical nature of the Earth (dissenting opinions on that notwithstanding). Similarly, we create a PolygonOptions object, configure it, and pass it to addPolygon for our Garment District box. The add() method on PolygonOptions will take the corners of our polygon, automatically enclosing that region. We also specify the strokeColor(). We could have specified a fillColor() (default is transparent), strokeWidth() (default is 10 pixels), zIndex(), and geodesic(). If we run the app and pan the map down to the south a bit, we see our polygon: 1891 MAPPING WITH MAPS V2 Figure 611: Maps V2 with Polyline and Polygon As with the polyline, Android automatically handles drawing what is needed based on map center and zoom levels. Note that, as with markers, we need to re-add the polylines and polygons after a configuration change, as the GoogleMap does not retain that information. Gestures and Controls By default, standard gestures and controls are enabled on your map: • The user can change zoom level either by + and - buttons or via “pinch-tozoom” gestures • The user can change the center of the map via simple swipe gestures • The user can change the camera tilt via two-finger vertical swipes, so instead of a traditional top-down perspective, the user can see things on an angle • The user can change the orientation of the map via a two-finger rotating swipe, to change the typical “north is to the top of the map” to some other orientation 1892 MAPPING WITH MAPS V2 You can obtain a UiSettings object from your GoogleMap via getUiSettings() to disable these features, if desired: • • • • • setRotateGesturesEnabled() setScrollGesturesEnabled() (for panning the map) setTiltGesturesEnabled() setZoomControlsEnabled() (for the + and - buttons) setZoomGesturesEnabled() (for pinch-to-zoom) There is also setAllGesturesEnabled() to toggle on or off all gesture-based map control. This is roughly analogous to the android:clickable attribute on the Maps V1 edition of MapView. There is also setCompassEnabled(), to indicate if a compass should be shown if the user changes the map orientation via a rotate gesture. Tracking Camera Changes If you have gestures enabled, the user can change the perspective of the map, referred to as changing the camera position. You may need to know about these changes, to perform various operations in your app based upon what is presently visible on the screen. Originally, to find out when the camera position changes, you could call setOnCameraChangeListener() on the GoogleMap, supplying an implementation of OnCameraChangeListener, which would be called with onCameraChange() as the user pans, zooms, or tilts the map. This approach was deprecated and replaced with a series of listeners: • OnCameraMoveStartedListener, invoked when the user starts moving the map • OnCameraMoveListener, invoked when the user continues moving the map after having originally started moving it, all in one gesture • OnCameraIdleListener, invoked when the user stops moving the map (e.g., lifts up their finger or stylus) • OnCameraMoveCanceledListener, invoked if you do something programmatically to interrupt the camera movement 1893 MAPPING WITH MAPS V2 To see how this works, we can take a quick peek at the MapsV2/Camera sample application, which is a clone of MapsV2/Popup with camera position tracking enabled. Late in onMapReady() of MainActivity, we call a series of setter methods on the GoogleMap to associate MainActivity itself as the listener for these events: map.setOnCameraMoveStartedListener(this this); map.setOnCameraMoveListener(this this); map.setOnCameraMoveCanceledListener(this this); map.setOnCameraIdleListener(this this); (from MapsV2/Camera/app/src/main/java/com/commonsware/android/mapsv2/camera/MainActivity.java) This requires MainActivity to implement all four of those listener interfaces: public class MainActivity extends AbstractMapActivity implements OnMapReadyCallback, OnInfoWindowClickListener, OnCameraMoveStartedListener, OnCameraMoveListener, OnCameraMoveCanceledListener, OnCameraIdleListener { (from MapsV2/Camera/app/src/main/java/com/commonsware/android/mapsv2/camera/MainActivity.java) And, this requires MainActivity to implement the callback method for each of those listeners: Listener Interface Event Method OnCameraMoveStartedListener onCameraMoveStarted(int i) OnCameraMoveListener onCameraMove() OnCameraIdleListener onCameraIdle() OnCameraMoveCanceledListener onCameraMoveCanceled() @Override public void onCameraIdle() { CameraPosition position=map.getCameraPosition(); Log.d("onCameraIdle", String.format("lat: %f, lon: %f, zoom: %f, tilt: %f", position.target.latitude, position.target.longitude, position.zoom, position.tilt)); } 1894 MAPPING WITH MAPS V2 @Override public void onCameraMoveCanceled() { CameraPosition position=map.getCameraPosition(); Log.d("onCameraMoveCanceled", String.format("lat: %f, lon: %f, zoom: %f, tilt: %f", position.target.latitude, position.target.longitude, position.zoom, position.tilt)); } @Override public void onCameraMove() { CameraPosition position=map.getCameraPosition(); Log.d("onCameraMove", String.format("lat: %f, lon: %f, zoom: %f, tilt: %f", position.target.latitude, position.target.longitude, position.zoom, position.tilt)); } @Override public void onCameraMoveStarted(int i) { CameraPosition position=map.getCameraPosition(); Log.d("onCameraMoveStarted", String.format("lat: %f, lon: %f, zoom: %f, tilt: %f", position.target.latitude, position.target.longitude, position.zoom, position.tilt)); } (from MapsV2/Camera/app/src/main/java/com/commonsware/android/mapsv2/camera/MainActivity.java) Here, we just log a message to Logcat on each camera position change, logging: • the latitude and longitude of the map center, obtained from the target LatLng data member of the CameraPosition object supplied to onCameraChange(), • the zoom level of the map, from the zoom data member of CameraPosition, and • the tilt of the map, in degrees, from the tilt data member of CameraPosition 1895 MAPPING WITH MAPS V2 As a result, if you run this app and play around with the various gestures, you get a series of Logcat messages with the results: 10-08 12:13:54.449 28718-28718/com.commonsware.android.mapsv2.camera D/ onCameraMoveStarted: lat: 40.771664, lon: -73.986067, zoom: 15.000000, tilt: 0.000000 10-08 12:13:54.453 28718-28718/com.commonsware.android.mapsv2.camera D/onCameraMove: lat: 40.771773, lon: -73.985717, zoom: 15.000000, tilt: 0.000000 10-08 12:13:54.483 28718-28718/com.commonsware.android.mapsv2.camera D/onCameraMove: lat: 40.771805, lon: -73.985701, zoom: 15.000000, tilt: 0.000000 10-08 12:13:54.500 28718-28718/com.commonsware.android.mapsv2.camera D/onCameraMove: lat: 40.771843, lon: -73.985669, zoom: 15.000000, tilt: 0.000000 . . . 10-08 12:13:57.001 28718-28718/com.commonsware.android.mapsv2.camera D/onCameraIdle: lat: 40.774540, lon: -73.985632, zoom: 15.000000, tilt: 0.000000 Note that onCameraMoveStarted() will be invoked for three reasons: 1. The user started panning, tilting, or rotating the map, or used a pinch-tozoom gesture 2. The user did something else that triggered a camera change, such as tapping the “my location” button to move the camera to their current location 3. You did something programmatically to change the camera position The parameter passed into onCameraMoveStarted() will contain a reason code (e.g., REASON_GESTURE) to help you distinguish these cases, if that level of detail is needed by your app. Maps in Fragments and Pagers One key limitation of Maps V1 was that you could only have one MapView instance per process. Presumably, the proprietary code at the heart of the Maps SDK add-on used static data members for some state management, ones that would get messed up if there were two or more MapView widgets in active use. Fortunately, Maps V2 gets rid of this restriction. You are welcome to have multiple MapFragment objects if that makes sense. Maps are relatively memory-intensive, so you should not be planning on having dozens or hundreds of them in use at a time, but you can have more than one. 1896 MAPPING WITH MAPS V2 To showcase this, the MapsV2/Pager sample application hosts 10 MapFragment instances as pages in a ViewPager. The bulk of the application is a clone of one of the ViewPager samples from the chapter on ViewPager. Having maps in a ViewPager presents a bit of a problem, in terms of interpreting horizontal swipe events. Normally, ViewPager handles those itself. However, that would mean that the user cannot pan the map horizontally, which makes using the map somewhat challenging. In this sample, we will augment the ViewPager with logic to allow horizontal swiping on the maps and on the tab strip. Our activity inflates a layout that contains our ViewPager along with a PagerTabStrip: > /> (from MapsV2/Pager/app/src/main/res/layout/activity_main.xml) However, you will note that this is not ViewPager, but rather MapAwarePager, a custom subclass of ViewPager that we will examine shortly. MainActivity then MapPageAdapter: populates the MapAwarePager with an instance of a package com.commonsware.android.mapsv2.pager; import android.os.Bundle android.os.Bundle; import android.support.v4.view.PagerAdapter android.support.v4.view.PagerAdapter; import android.support.v4.view.ViewPager android.support.v4.view.ViewPager; public class MainActivity extends AbstractMapActivity { @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); if (readyToGo()) { setContentView(R.layout.activity_main); 1897 MAPPING WITH MAPS V2 ViewPager pager=(ViewPager)findViewById(R.id.pager); pager.setAdapter(buildAdapter()); } } private PagerAdapter buildAdapter() { return return(new new MapPageAdapter(this this, getFragmentManager())); } } (from MapsV2/Pager/app/src/main/java/com/commonsware/android/mapsv2/pager/MainActivity.java) MapPageAdapter is a FragmentStatePagerAdapter, not a FragmentPagerAdapter. This means that as the user swipes through our ViewPager, the adapter has the right to discard old fragments when it creates new ones. This helps reduce the overall memory footprint of our activity. package com.commonsware.android.mapsv2.pager; import import import import android.content.Context android.content.Context; android.app.Fragment android.app.Fragment; android.app.FragmentManager android.app.FragmentManager; android.support.v13.app.FragmentStatePagerAdapter android.support.v13.app.FragmentStatePagerAdapter; public class MapPageAdapter extends FragmentStatePagerAdapter { Context ctxt=null null; public MapPageAdapter(Context ctxt, FragmentManager mgr) { super super(mgr); this this.ctxt=ctxt; } @Override public int getCount() { return return(10); } @Override public Fragment getItem(int position) { return return(new new PageMapFragment()); } @Override public String getPageTitle(int position) { return return(ctxt.getString(R.string.map_page_title) + String.valueOf(position + 1)); } } (from MapsV2/Pager/app/src/main/java/com/commonsware/android/mapsv2/pager/MapPageAdapter.java) 1898 MAPPING WITH MAPS V2 MapPageAdapter declares that there should be ten pages (in getCount()) and returns an instance of PageMapFragment for each page. PageMapFragment is a subclass of MapFragment, and so is responsible for displaying our map: package com.commonsware.android.mapsv2.pager; import import import import import import import import android.os.Bundle android.os.Bundle; com.google.android.gms.maps.CameraUpdate com.google.android.gms.maps.CameraUpdate; com.google.android.gms.maps.CameraUpdateFactory com.google.android.gms.maps.CameraUpdateFactory; com.google.android.gms.maps.GoogleMap com.google.android.gms.maps.GoogleMap; com.google.android.gms.maps.MapFragment com.google.android.gms.maps.MapFragment; com.google.android.gms.maps.OnMapReadyCallback com.google.android.gms.maps.OnMapReadyCallback; com.google.android.gms.maps.model.LatLng com.google.android.gms.maps.model.LatLng; com.google.android.gms.maps.model.MarkerOptions com.google.android.gms.maps.model.MarkerOptions; public class PageMapFragment extends MapFragment implements OnMapReadyCallback { private boolean needsInit=false false; @Override public void onActivityCreated(Bundle savedInstanceState) { super super.onActivityCreated(savedInstanceState); if (savedInstanceState == null null) { needsInit=true true; } getMapAsync(this this); } @Override public void onMapReady(final final GoogleMap map) { if (needsInit) { CameraUpdate center= CameraUpdateFactory.newLatLng(new new LatLng(40.76793169992044, -73.98180484771729)); CameraUpdate zoom=CameraUpdateFactory.zoomTo(15); map.moveCamera(center); map.animateCamera(zoom); } addMarker(map, 40.748963847316034, -73.96807193756104, R.string.un, R.string.united_nations); addMarker(map, 40.76866299974387, -73.98268461227417, R.string.lincoln_center, R.string.lincoln_center_snippet); addMarker(map, 40.765136435316755, -73.97989511489868, 1899 MAPPING WITH MAPS V2 R.string.carnegie_hall, R.string.practice_x3); addMarker(map, 40.70686417491799, -74.01572942733765, R.string.downtown_club, R.string.heisman_trophy); } private void addMarker(GoogleMap map, double lat, double lon, int title, int snippet) { map.addMarker(new new MarkerOptions().position(new new LatLng(lat, lon)) .title(getString(title)) .snippet(getString(snippet))); } } (from MapsV2/Pager/app/src/main/java/com/commonsware/android/mapsv2/pager/PageMapFragment.java) If we simply wanted to display an unconfigured map, we could just have MapPageAdapter create and return instances of MapFragment directly. If we want to configure our map, though, we need to get control when the GoogleMap object is ready for use. One way to do that is to extend MapFragment and override onActivityCreated() and call getMapAsync() there to begin the whole getthe-GoogleMap-loaded process. In onMapReady(), we can then go ahead and configure the map much as we have done in previous examples, just from within the fragment itself rather than from the hosting activity. MapAwarePager overrides one key method of ViewPager: canScroll(): package com.commonsware.android.mapsv2.pager; import import import import import import android.content.Context android.content.Context; android.support.v4.view.PagerTabStrip android.support.v4.view.PagerTabStrip; android.support.v4.view.ViewPager android.support.v4.view.ViewPager; android.util.AttributeSet android.util.AttributeSet; android.view.SurfaceView android.view.SurfaceView; android.view.View android.view.View; public class MapAwarePager extends ViewPager { public MapAwarePager(Context context, AttributeSet attrs) { super super(context, attrs); } @Override protected boolean canScroll(View v, boolean checkV, int dx, int x, int y) { if (v instanceof SurfaceView || v instanceof PagerTabStrip) { return return(true true); } 1900 MAPPING WITH MAPS V2 return return(super super.canScroll(v, checkV, dx, x, y)); } } (from MapsV2/Pager/app/src/main/java/com/commonsware/android/mapsv2/pager/MapAwarePager.java) canScroll() should return true if the View (and specifically the supplied X and Y coordinates within that View) can be scrolled horizontally, false otherwise. In our case, we want to say that the map and the tab strip are each scrollable horizontally. As it turns out, the passed-in View for our MapFragment will be the map if it is a subclass of SurfaceView (determined by trial and error on the author’s part, with hopes for a more authoritative solution in a future edition of the Maps V2 API). So, if the passed-in View is either a SurfaceView or a PagerTabStrip, we return true, otherwise we default to normal logic. The result is a series of independent maps, one per page: Figure 612: Multiple Maps V2 Maps in a ViewPager Each map is independent: if the user pans or zooms one map, that has no impact on any of the other pages. Panning the maps horizontally works; to move between pages, use the tab strip. 1901 MAPPING WITH MAPS V2 Animating Marker Movement Markers, by default, are static, unless you make them be draggable, and then only the user can drag them. However, you are welcome to update the position of a Marker at any point, by calling setPosition() and supplying a new LatLng. The Marker then will jump to that position. But what if you want to animate the movement of a Marker from its current position to a new one? Maps V2 does not offer anything “out of the box” for implementing this, but Google demonstrated approaches for this in a “DevBytes” video and related bit of code in a GitHub Gist. This section will cover the technique appropriate for API Level 14+, including a full working sample (the Gist shows code but not its usage). Problem #1: Animating a LatLng The position of a Marker is a LatLng, as we have seen previously. LatLng is not a simple number, and so the animator framework needs our assistance to animate them. Specifically, we need a TypeEvaluator for LatLng, with our evaluate() method taking the initial and end positions and computing another LatLng representing the fraction position between those other positions. This concept was introduced back in the chapter on the animator framework. A simple approach to computing the fractional LatLng would be to apply the fraction to the latitude and the longitude as Java double values: LatLng interpolate(float fraction, LatLng initial, LatLng end) { double lat = (end.latitude - initial.latitude) * fraction + initial.latitude; double lng = (end.longitude - initial.longitude) * fraction + initial.longitude; return return(new new LatLng(lat, lng)); } That would work reasonably well for fairly close points, such as animating a marker within a city. However, animating markers across longer distances means that we have to take into account some geographic realities that a simple calculation will miss. 1902 MAPPING WITH MAPS V2 Problem #2: The Earth Is Not Flat (Really!) One bit of reality is that the Earth is round. The above calculation assumes that the Earth is flat. Calculating “great circle” positions requires a fair bit of spherical trigonometry, known to cause loss of hair in software developers. Hence, ideally, we will use somebody’s existing debugged algorithm for that. Problem #3: 180 Equals –180, At Least For Longitude The other problem is that longitudes wrap around, as 180 degrees longitude is equivalent to –180 degrees longitude, and longitudinal values are considered to be between 180 and –180. In cases where we would not cross 180 degrees longitude, this is not an issue. However, a simple calculation might miss this and wind up having our animation “take the long way” (e.g., animating from –175 degrees longitude to 175 degrees longitude by going 350 degrees around the Earth, rather than just 10 degrees and crossing the International Date Line). Introducing Some Googly Assistance Google themselves have released a utility library for Maps V2. It offers polyline and polygon decoding, primarily for interoperability with other location-related Google services like the Google Directions API. The SphericalUtil class handles all of the nasty math for computing distances along the surface of the Earth and related calculations. It also offers BubbleIconFactory, which makes it easy to create marker icons that look a bit like info windows (complete with border and caret) wrapping around a bit of text or an icon. In our case, we can use SphericalUtil to handle Problem #2 and Problem #3, interpolating the location between two LatLng values, taking the curvature of the Earth and longitude idiosyncrasies into account. Seeing This in Action The MapsV2/Animator sample project is a modified version of the MapsV2/Markers project, adding in the notion of animating a marker from its original position (Lincoln Center) to a new position (Penn Station) within Manhattan. Since we want to use the Google map utility library, we need to add it as a dependency. Android Studio users can simply add implementation 1903 MAPPING WITH MAPS V2 'com.google.maps.android:android-maps-utils:0.3.4' the dependencies closure. (or a higher version) to We need to know where our starting and ending position for the animation will be, in terms of LatLng objects. Since those have no dependencies upon a Context or anything, we can simply declare them as static final values: private static final LatLng PENN_STATION=new new LatLng(40.749972, -73.992319); private static final LatLng LINCOLN_CENTER= new LatLng(40.76866299974387, -73.98268461227417); (from MapsV2/Animator/app/src/main/java/com/commonsware/android/mapsv2/animator/MainActivity.java) We will also need the actual Marker object created when we add our starting position (LINCOLN_CENTER) to the map. So far, we have ignored the Marker returned by addMarker() on GoogleMap, but now we need that. So, our own addMarker() method now returns this value: private Marker addMarker(GoogleMap map, double lat, double lon, int title, int snippet) { return return(map.addMarker(new new MarkerOptions().position(new new LatLng(lat, lon)) .title(getString(title)) .snippet(getString(snippet)))); } (from MapsV2/Animator/app/src/main/java/com/commonsware/android/mapsv2/animator/MainActivity.java) We also now have a markerToAnimate data member of the activity, for our Marker, which we populate from our modified addMarker() method: addMarker(map, 40.748963847316034, -73.96807193756104, R.string.un, R.string.united_nations); markerToAnimate= addMarker(map, LINCOLN_CENTER.latitude, LINCOLN_CENTER.longitude, R.string.lincoln_center, R.string.lincoln_center_snippet); addMarker(map, 40.765136435316755, -73.97989511489868, R.string.carnegie_hall, R.string.practice_x3); addMarker(map, 40.70686417491799, -74.01572942733765, R.string.downtown_club, R.string.heisman_trophy); (from MapsV2/Animator/app/src/main/java/com/commonsware/android/mapsv2/animator/MainActivity.java) 1904 MAPPING WITH MAPS V2 To make the sample work repeatedly, it would be nice to support bi-directional animation, starting with animating from Lincoln Center to Penn Station, then reversing the animation to go back to Lincoln Center. That means that we need to know, for any particular animation, where the end position should be. So, we track a LatLng for the next end position, surprisingly named nextAnimationEnd, initializing it to be PENN_STATION (since we are starting at the outset at LINCOLN_CENTER): private LatLng nextAnimationEnd=PENN_STATION; (from MapsV2/Animator/app/src/main/java/com/commonsware/android/mapsv2/animator/MainActivity.java) Next, we need to give the user a means of actually requesting the animation to run. To do that, we define a new menu XML resource for an animate menu item (using the directions icon for lack of a better handy icon): > /> (from MapsV2/Animator/app/src/main/res/menu/animate.xml) We then load that menu resource in an overridden onCreateOptionsMenu() and direct the click event to an animateMarker() method in onOptionsItemSelected(): @Override public boolean onCreateOptionsMenu(Menu menu) { getMenuInflater().inflate(R.menu.animate, menu); return return(super super.onCreateOptionsMenu(menu)); } @Override public boolean onOptionsItemSelected(MenuItem item) { if (item.getItemId() == R.id.animate) { animateMarker(); return return(true true); } 1905 MAPPING WITH MAPS V2 return return(super super.onOptionsItemSelected(item)); } (from MapsV2/Animator/app/src/main/java/com/commonsware/android/mapsv2/animator/MainActivity.java) In animateMarker(), we need to do two things: 1. Actually run the animation 2. Ensure that the camera position is such that the animation will actually be visible, as it is pointless to animate a marker between two points if the currently-viewed portion of the map does not show those points To handle the camera position, we need to use moveCamera() with a CameraUpdate from CameraUpdateFactory, as we used to set the initial camera position and zoom level. To handle the case where we want one or more points to be visible, we can use the newLatLngBounds() method on CameraUpdateFactory. This takes a LatLngBounds describing the area that needs to be visible, plus a padding amount in pixels for where that area should be inset within the map. Of course, this implies that we have a LatLngBounds. Since LatLngBounds also does not depend upon a Context or much of anything, we can define one of those as a static final data member, using a LatLngBounds.Builder instance: private static final LatLngBounds bounds= new LatLngBounds.Builder().include(LINCOLN_CENTER) .include(PENN_STATION).build(); (from MapsV2/Animator/app/src/main/java/com/commonsware/android/mapsv2/animator/MainActivity.java) A LatLngBounds.Builder takes one or more LatLng objects — passed in via include() – then constructs a LatLngBounds that encompasses all of those points via build(). Our animateMarker() method then starts off by using moveCamera() to reset the camera to show that defined region: private void animateMarker() { map.moveCamera(CameraUpdateFactory.newLatLngBounds(bounds, 48)); Property property= Property.of(Marker.class, LatLng.class, "position"); ObjectAnimator animator= 1906 MAPPING WITH MAPS V2 ObjectAnimator.ofObject(markerToAnimate, property, new LatLngEvaluator(), nextAnimationEnd); animator.setDuration(2000); animator.start(); if (nextAnimationEnd == LINCOLN_CENTER) { nextAnimationEnd=PENN_STATION; } else { nextAnimationEnd=LINCOLN_CENTER; } } (from MapsV2/Animator/app/src/main/java/com/commonsware/android/mapsv2/animator/MainActivity.java) Then, we need to set up the animation. To do this, we will use the object animator framework, specifically an ObjectAnimator. We know the Marker that we want to animate (markerToAnimate) and we know where we want to animate it to (nextAnimationEnd). What we need is to indicate the property to animate on this object, plus provide help to actually animate a LatLng. To specify the property, we could just pass in the name of the property ("position"). However, in animateMarker(), we set up a Property object via the static of() factory method. This makes our use of ofObject() more type-safe, as Property will help enforce that we are animating a Marker using LatLng values. To animate LatLng values, we need a TypeEvaluator for LatLng, here defined as a static inner class named LatLngEvaluator: private static class LatLngEvaluator implements TypeEvaluator { @Override public LatLng evaluate(float fraction, LatLng startValue, LatLng endValue) { return return(SphericalUtil.interpolate(startValue, endValue, fraction)); } } (from MapsV2/Animator/app/src/main/java/com/commonsware/android/mapsv2/animator/MainActivity.java) Our evaluate() method turns around and calls the static interpolate() method on SphericalUtil, supplied by Google’s map utility library. interpolate() handles all the nasty spherical trigonometry and stuff, so we do not have to. We then set the duration of the animation to be two seconds, and start the animation. 1907 MAPPING WITH MAPS V2 Finally, to reverse the animation for the next request, animateMarker() resets the value of nextAnimationEnd to be PENN_STATION or LINCOLN_CENTER, wherever we will animate to next. Honoring Traffic Rules, Like “Drive Only On Streets” You will notice that our animation ignores other aspects of reality, such as buildings that might be in the way. Sometimes, that is appropriate, such as animating the movement of: • a bird • a plane • a costumed superhero with independent flight capability Sometimes, though, we need to take into account those obstacles, such as animating the movement of: • a pedestrian • a car • a costumed superhero “flying” by means of swinging between buildings using dynamically-generated cables of either natural or synthetic origin However, to do this implies that we know where the obstacles are. Or, more accurately, we would need to animate the marker along known good waypoints, such as streets. The animation would not be especially difficult, as ofObject() can take a series of waypoints. However, we would need to find those waypoints, and there is nothing in Maps V2 itself that supplies this data. Maps, of the Indoor Variety The good news is that Maps V2 supports Google’s indoor maps, for those venues for which Google has indoor map data. The bad news is that for some reason, only one map at a time supports indoor maps. The default will be that the first map you create will support indoor maps, and others will not. 1908 MAPPING WITH MAPS V2 To see if a given map offers indoor map capability, you can call isIndoorEnabled() on GoogleMap. To toggle this capability, call setIndoorEnabled(). Taking a Snapshot of a Map Once a map is drawn, you can take a snapshot of it, converting the viewed map into a Bitmap object. This is designed to take an image of the map and use it in places where a MapFragment, or even a MapView, cannot go, such as: • Things tied to a RemoteViews, such as a custom Notification • Thumbnails of maps, for an app that allows users to manipulate several maps at once The GoogleMap object has two flavors of a snapshot() method. Both take a SnapshotReadyCallback object. You will need to supply an instance of something implementing the SnapshotReadyCallback interface, overriding onSnapshotReady(), where you will receive your Bitmap. One flavor of snapshot() takes just the SnapshotReadyCallback; the other also takes a Bitmap of the proper dimensions, such as a previous snapshot Bitmap that you want to recycle. Using the latter snapshot() is recommended where possible, so you do not need to allocate new Bitmap objects on each snapshot() call. Note that snapshot() will only work once the map is actually rendered. So, for example, calling snapshot() from onCreate() of your activity will fail, because the map has not been rendered yet. snapshot() is designed to be called based upon user input, either to manually capture a snapshot or based on navigation (e.g., tapping on a ListView item triggers saving a snapshot of the current map as a thumbnail before changing the map contents). Also, the documentation for snapshot() contains the following: Note: Images of the map must not be transmitted to your servers, or otherwise used outside of the application. If you need to send a map to another application or user, send data that allows them to reconstruct the map for the new user instead of a snapshot. As this statement may be tied to the terms and conditions of your use of Maps V2, you should talk with qualified legal counsel before: 1909 MAPPING WITH MAPS V2 • Saving a snapshot to external storage • Sharing a snapshot via ACTION_SEND • Sending a snapshot to your server or similar operations. MapFragment vs. MapView So far, all the examples shown in this chapter use MapFragment. In most cases, this is the right thing to use. However, there may be places where you really want to use a View, rather than a Fragment, for your maps. The good news is that Maps V2 does have a MapView. MapFragment usually handles creating and managing the MapView for you, but you can, if you wish, avoid MapFragment and manage the MapView yourself. The biggest limitation is that you need to forward the lifecycle methods from your activity or fragment on to the MapView, calling onCreate(), onResume(), onPause(), onDestroy(), and onSaveInstanceState() on the MapView. Normally, MapFragment would do that for you, saving you the trouble. Also note that while MapView is a ViewGroup, you are not allowed to add child widgets to it. About That AbstractMapActivity Class… Early on, we hand-waved our way past the AbstractMapActivity that all of our MainActivity classes inherit from, and we skirted past the readyToGo() method that we were calling. Also, you may have noticed that our app has an action bar overflow item, that we do not seem to be creating in MainActivity. Now, it is time to dive into what is going on in our AbstractMapActivity implementations. The readyToGo() method in AbstractMapActivity is designed to help us determine if Maps V2 is “ready to go” and, if not, to help the user perhaps fix their device such that Maps V2 will work in the future: 1910 MAPPING WITH MAPS V2 protected boolean readyToGo() { GoogleApiAvailability checker= GoogleApiAvailability.getInstance(); int status=checker.isGooglePlayServicesAvailable(this this); if (status == ConnectionResult.SUCCESS) { if (getVersionFromPackageManager(this this)>=2) { return return(true true); } else { Toast.makeText(this this, R.string.no_maps, Toast.LENGTH_LONG).show(); finish(); } } else if (checker.isUserResolvableError(status)) { ErrorDialogFragment.newInstance(status) .show(getFragmentManager(), TAG_ERROR_DIALOG_FRAGMENT); } else { Toast.makeText(this this, R.string.no_maps, Toast.LENGTH_LONG).show(); finish(); } return return(false false); } (from MapsV2/Basic/app/src/main/java/com/commonsware/android/mapsv2/basic/AbstractMapActivity.java) Determining the availability of Maps V2 — or anything in the Play Services SDK — is handled through an instance of GoogleApiAvailability. You get a singleton instance of this class via its static getInstance() method. First, we call isGooglePlayServicesAvailable() method on the GoogleApiAvailability singleton. This will return an integer indicating whether Maps V2 is available for our use or not. If the return value is ConnectionResult.SUCCESS — meaning Maps V2 is indeed available to us – we check to see if OpenGL ES is version 2.0 or higher, as we did not require that in the manifest. There are a few ways in Android to check the OpenGL ES version. This sample uses some code from the Compatibility Test Suite (CTS), examining PackageManager to determine the major level: // following from // https://android.googlesource.com/platform/cts/+/master/tests/tests/graphics/src/android/opengl/cts/ 1911 MAPPING WITH MAPS V2 OpenGlEsVersionTest.java /* * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the * "License"); you may not use this file except in * compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in * writing, software distributed under the License is * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR * CONDITIONS OF ANY KIND, either express or implied. See * the License for the specific language governing * permissions and limitations under the License. */ private static int getVersionFromPackageManager(Context context) { PackageManager packageManager=context.getPackageManager(); FeatureInfo[] featureInfos= packageManager.getSystemAvailableFeatures(); if (featureInfos != null && featureInfos.length > 0) { for (FeatureInfo featureInfo : featureInfos) { // Null feature name means this feature is the open // gl es version feature. if (featureInfo.name == null null) { if (featureInfo.reqGlEsVersion != FeatureInfo.GL_ES_VERSION_UNDEFINED) { return getMajorVersion(featureInfo.reqGlEsVersion); } else { return 1; // Lack of property means OpenGL ES // version 1 } } } } return 1; } /** @see FeatureInfo#getGlEsVersion() */ private static int getMajorVersion(int glEsVersion) { return return((glEsVersion & 0xffff0000) >> 16); } (from MapsV2/Basic/app/src/main/java/com/commonsware/android/mapsv2/basic/AbstractMapActivity.java) If the major version is 2 or higher, we return true from readyToGo(), so MainActivity knows to continue on setting up the map. If the major version is 1, we display a Toast — a production-grade app would do something else to let the user know of the problem, most likely. But, what if isGooglePlayServicesAvailable() returns something else? 1912 MAPPING WITH MAPS V2 There are two major possibilities here: 1. The error is something that the user might be able to rectify, such as by downloading the Google Play Services app from the Play Store 2. The error is something that the user cannot recover from We can distinguish these two cases by calling isUserResolvableError() on the GoogleApiAvailability singleton, passing in the value we received from isGooglePlayServicesAvailable(). This will return true if the user might be able to fix the problem, false otherwise. In the false case, the user is just out of luck, so we display a Toast to alert them of this fact, then finish() the activity and return false, so MainActivity skips over the rest of its work. In the true case, we can display something to the user to prompt them to fix the problem. One way to do that is to use a dialog obtained from Google code, by calling the static getErrorDialog() method on a GoogleApiAvailability singleton. In our case, we wrap that in a DialogFragment named ErrorDialogFragment, implemented as a static inner class of AbstractMapActivity: public static class ErrorDialogFragment extends DialogFragment { static final String ARG_ERROR_CODE="errorCode"; static ErrorDialogFragment newInstance(int errorCode) { Bundle args=new new Bundle(); ErrorDialogFragment result=new new ErrorDialogFragment(); args.putInt(ARG_ERROR_CODE, errorCode); result.setArguments(args); return return(result); } @Override public Dialog onCreateDialog(Bundle savedInstanceState) { Bundle args=getArguments(); GoogleApiAvailability checker= GoogleApiAvailability.getInstance(); return return(checker.getErrorDialog(getActivity(), args.getInt(ARG_ERROR_CODE), 0)); } 1913 MAPPING WITH MAPS V2 @Override public void onDismiss(DialogInterface dlg) { if (getActivity()!=null null) { getActivity().finish(); } } } (from MapsV2/Basic/app/src/main/java/com/commonsware/android/mapsv2/basic/AbstractMapActivity.java) While the code and comments around getErrorDialog() suggest that there is some way for us to find out if the user performed actions that fix the problem, this code does not seem to work well in practice. After all, downloading Google Play Services is asynchronous, so even if the user returns to our app, it is entirely likely that Maps V2 is still unavailable. As a result, when the user is done with the dialog, we finish() the activity, forcing the user to start it again if and when they are done downloading Google Play Services. Testing this code requires an older device, one in which the “Google Play services” app can be uninstalled… if it can be installed at all. As it turns out, not all Android devices support the Play Store, or the Google Play Services by extension. Notably, if the device lacks the Play Store, isUserRecoverableError() returns true, even though the user cannot recover from this situation (except perhaps via a firmware update). (An earlier problem where getErrorDialog() could return null even for cases where the error is supposedly user-recoverable has been fixed) Helper Libraries for Maps V2 Many developers have been busy writing libraries that help in the development of Maps V2 applications, beyond Google’s own utility library mentioned in the section on animating markers. Perhaps the most expansive of these is the Android Maps Extensions library. The big thing that this library offers is marker clustering, where as the user zooms out, individual markers are replaced by a marker representing a cluster, so you avoid flooding a small area with too many individual markers: 1914 MAPPING WITH MAPS V2 Figure 613: Map with Many Markers ( from Android Maps Extensions demo app) 1915 MAPPING WITH MAPS V2 Figure 614: Same Map with Cluster Markers ( from Android Maps Extensions demo app) 1916 MAPPING WITH MAPS V2 Figure 615: Same Map with Zoomed In Cluster Markers ( from Android Maps Extensions demo app) This library wraps the Maps V2 classes, allowing the library to offer extensions to the standard Maps V2 API, including: • Associating your own data with Marker, Polygon, Polyline, and other classes, to tie them back to your models • Getters to retrieve previously-defined markers, etc. • Etc. Another library offering marker clustering is clusterkraf, from Two Toasters. The clusterkraf library can optionally integrate with Cyril Mottier’s Polaris2 library. His original Polaris library aimed to provide more features to Maps V1; Polaris2 fills a similar role for Maps V2. At this time, Polaris2 is a smaller library, simply because Maps V2 handles much of what Polaris provided. Polaris2, like Android Maps Extensions, wraps the Maps V2 API with its own classes, in lieu of subclassing (since most Maps V2 classes are marked final). Of note, Polaris2 offers reset() methods on many of the ...Options classes (e.g., MarkerOptions), and offers constants for the minimum and maximum valid latitude and longitude. 1917 MAPPING WITH MAPS V2 Problems with Maps V2 at Runtime Portions of the logic that powers your Maps V2 MapFragment are supplied by the Google Play Services app. As a result, many operations with Maps V2, such as manipulating markers, require IPC calls between your app and Google Play Services. If those IPC calls are synchronous, they will add a bit of overhead to your app — enough that you will want to avoid them in time-critical pieces of code, tight loops, and the like. Problems with Maps V2 Deployment Of course, the key question is: should you be using Maps V2 at all? Google thinks so, as they have turned off access to new API keys for Maps V1. That makes ongoing development of Maps V1 solutions a bit risky, as you cannot create new API keys for new signing keys, such as if you need to replace your debug keystore. However, Maps V2 has some deployment limitations at this time. While 99.8+% of Android devices that have the Play Store have the requisite OpenGL ES 2.0+, some devices that have a suitable OpenGL ES version may not have the Play Store or otherwise be unable to get Google Play Services, required for using Maps V2. The isGooglePlayServicesAvailable() approach advocated by Google can help determine this at runtime, though this approach used to have some bugs, and it still cannot always help you recover from this problem. And, as the next section illustrates, not every Android device supports Maps V2, because not every device supports Google Play Services. What Non-Compliant Devices Show If your app tries to bring up Maps V2 on a device that cannot possibly have the Play Services Framework — such as a Kindle Fire — the user will see an error dialog: 1918 MAPPING WITH MAPS V2 Figure 616: Maps V2 Error on Kindle Fire For those devices, you will need to consider some alternative source of maps. Mapping Alternatives Beyond using Maps V2 or Maps V1, you may need to consider other mapping alternatives. The Google mapping APIs are only available on Android devices that have the Maps SDK add-on (Maps V1) or Google Play Services (Maps V2). Not all devices have those. And, the limitations of Maps V2 deployment and the deprecation of Maps V1 may convince you that relying upon Google for maps is not safe at the present time. The most common native replacement for Google’s mapping is OpenStreetMap, which to some extent is “the Wikipedia of maps”. OSMDroid is a library that provides a Maps V1-ish API for embedding OpenStreetMap-based maps into your application. Another solution is to integrate Web-based Google maps into your app, the same way that you might embed them into your Web site. An activity hosting a WebView can display a Web-based Google Map, for example. Certain devices may have access to other native mapping solutions. For example, Amazon has published their own maps API for use with the Kindle Fire. 1919 Crafting Your Own Views One of the classic forms of code reuse is the GUI widget. Since the advent of Microsoft Windows — and, to some extent, even earlier – developers have been creating their own widgets to extend an existing widget set. These range from 16-bit Windows “custom controls” to 32-bit Windows OCX components to the innumerable widgets available for Java Swing and SWT, and beyond. Android lets you craft your own widgets as well, such as extending an existing widget with a new UI or new behaviors. Prerequisites Understanding this chapter requires that you have read the core chapters of this book. Pick Your Poison You have five major options for creating a custom View class. First, your “custom View class” might really only be custom Drawable resources. Many widgets can adopt a radically different look and feel just with replacement graphics. For example, you might think that these toggle buttons from the Android 2.1 Google Maps application are some fancy custom widget: Figure 617: Google Maps navigation toggle buttons 1921 CRAFTING YOUR OWN VIEWS In reality, those are just radio buttons with replacement images. Second, your custom View class might be a simple subclass of an existing widget, where you override some behaviors or otherwise inject your own logic. Unfortunately, most of the built-in Android widgets are not really designed for this sort of simple subclassing, so you may be disappointed in how well this particular technique works. Third, your custom View class might be a composite widget — akin to an activity’s contents, complete with layout and such, but encapsulated in its own class. This allows you to create something more elaborate than you will just by tweaking resources. We will see this later in the chapter with ColorMixer. Fourth, you might want to implement your own layout manager, if your GUI rules do not fit well with RelativeLayout, TableLayout, or other built-in containers. For example, you might want to create a layout manager that more closely mirrors the “box model” approach taken by XUL and Flex, or you might want to create one that mirrors Swing’s FlowLayout (laying widgets out horizontally until there is no more room on the current row, then start a new row). Finally, you might want to do something totally different, where you need to draw the widget yourself. For example, the ColorMixer widget uses SeekBar widgets to control the mix of red, blue, and green. But, you might create a ColorWheel widget that draws a spectrum gradient, detects touch events, and lets the user pick a color that way. Some of these techniques are fairly simple; others are fairly complex. All share some common traits, such as widget-defined attributes, that we will see throughout the remainder of this chapter. Colors, Mixed How You Like Them The classic way for a user to pick a color in a GUI is to use a color wheel like this one: 1922 CRAFTING YOUR OWN VIEWS Figure 618: A color wheel from the API samples There is even code to make one in the API samples. However, a color wheel like that is difficult to manipulate on a touch screen, particularly a capacitive touchscreen designed for finger input. Fingers are great for gross touch events and lousy for selecting a particular color pixel. Another approach is to use a mixer, with sliders to control the red, green, and blue values: 1923 CRAFTING YOUR OWN VIEWS Figure 619: The ColorMixer widget, inside an activity That is the custom widget you will see in this section, based on the code in the Views/ColorMixer sample project. The Layout ColorMixer is a composite widget, meaning that its contents are created from other widgets and containers. Hence, we can use a layout file to describe what the widget should look like. The layout to be used for the widget is not that much: three SeekBar widgets (to control the colors), three TextView widgets (to label the colors), and one plain View (the “swatch” on the left that shows what the currently selected color is). Here is the file, found in res/layout/mixer.xml in the Views/ColorMixer project: > (from Views/ColorMixer/app/src/main/res/layout/mixer.xml) One thing that is a bit interesting about this layout, though, is the root element: . A layout is a bag of widgets that can be poured into some other container. The layout rules on the children of are then used in conjunction with whatever container they are added to. As we will see shortly, ColorMixer itself inherits from RelativeLayout, and the children of the element will become children of ColorMixer in Java. Basically, the element is only there because XML files need a single root — otherwise, the element itself is ignored in the layout. The Attributes Widgets usually have attributes that you can set in the XML file, such as the android:src attribute you can specify on an ImageButton widget. You can create your own custom attributes that can be used in your custom widget, by creating a res/values/attrs.xml file containing declare-styleable resources to specify them. For example, here is the attributes file for ColorMixer: > (from Views/ColorMixer/app/src/main/res/values/attrs.xml) The declare-styleable element describes what attributes are available on the widget class specified in the name attribute — in our case, ColorMixer. Inside declare-styleable you can have one or more attr elements, each indicating the name of an attribute (e.g., initialColor) and what data format the attribute has (e.g., color). The data type will help with compile-time validation and in getting any supplied values for this attribute parsed into the appropriate type at runtime. 1926 CRAFTING YOUR OWN VIEWS Here, we indicate there is only one attribute: initialColor, which will hold the initial color we want the mixer set to when it first appears. There are many possible values for the format attribute in an attr element, including: 1. 2. 3. 4. 5. 6. 7. 8. boolean color dimension float fraction integer reference Drawable) string (which means a reference to another resource, such as a You can even support multiple formats for an attribute, by separating the values with a pipe (e.g., reference|color). The Class Our ColorMixer class, a subclass of RelativeLayout, will take those attributes and provide the actual custom widget implementation, for use in activities. Constructor Flavors A View has three possible constructors: 1. One takes just a Context, which usually will be an Activity 2. One takes a Context and an AttributeSet, the latter of which represents the attributes supplied via layout XML 3. One takes a Context, an AttributeSet, and the default style to apply to the attributes If you are expecting to use your custom widget in layout XML files, you will need to implement the second constructor and chain to the superclass. If you want to use styles with your custom widget when declared in layout XML files, you will need to implement the third constructor and chain to the superclass. If you want developers to create instances of your View class in Java code directly, you probably should implement the first constructor and, again, chain to the superclass. 1927 CRAFTING YOUR OWN VIEWS In the case of ColorMixer, all three constructors are implemented, eventually routing to the three-parameter edition, which initializes our widget. Below, you will see the first two of those constructors, with the third coming up in the next section: public ColorMixer(Context context) { this this(context, null null); } public ColorMixer(Context context, AttributeSet attrs) { this this(context, attrs, 0); } (from Views/ColorMixer/app/src/main/java/com/commonsware/android/colormixer/ColorMixer.java) Using the Attributes The ColorMixer has a starting color — after all, the SeekBar widgets and swatch View have to show something. Developers can, if they wish, set that color via a setColor() method: public void setColor(int color) { red.setProgress(Color.red(color)); green.setProgress(Color.green(color)); blue.setProgress(Color.blue(color)); swatch.setBackgroundColor(color); } (from Views/ColorMixer/app/src/main/java/com/commonsware/android/colormixer/ColorMixer.java) If, however, we want developers to be able to use layout XML, we need to get the value of initialColor out of the supplied AttributeSet. In ColorMixer, this is handled in the three-parameter constructor: public ColorMixer(Context context, AttributeSet attrs, int defStyle) { super super(context, attrs, defStyle); ((Activity)getContext()) .getLayoutInflater() .inflate(R.layout.mixer, this this, true true); swatch=findViewById(R.id.swatch); red=(SeekBar)findViewById(R.id.red); red.setMax(0xFF); red.setOnSeekBarChangeListener(onMix); 1928 CRAFTING YOUR OWN VIEWS green=(SeekBar)findViewById(R.id.green); green.setMax(0xFF); green.setOnSeekBarChangeListener(onMix); blue=(SeekBar)findViewById(R.id.blue); blue.setMax(0xFF); blue.setOnSeekBarChangeListener(onMix); if (attrs!=null null) { TypedArray a=getContext() .obtainStyledAttributes(attrs, R.styleable.ColorMixer, 0, 0); setColor(a.getInt(R.styleable.ColorMixer_initialColor, 0xFFA4C639)); a.recycle(); } } (from Views/ColorMixer/app/src/main/java/com/commonsware/android/colormixer/ColorMixer.java) There are three steps for getting attribute values: • Get a TypedArray conversion of the AttributeSet by calling obtainStyledAttributes() on our Context, supplying it the AttributeSet and the ID of our styleable resource (in this case, R.styleable.ColorMixer, since we set the name of the declare-styleable element to be ColorMixer) • Use the TypedArray to access specific attributes of interest, by calling an appropriate getter (e.g., getInt()) with the ID of the specific attribute to fetch (R.styleable.ColorMixer_initialColor) • Recycle the TypedArray when done, via a call to recycle(), to make the object available to Android for use with other widgets via an object pool (versus creating new instances every time) Note that the name of any given attribute, from the standpoint of TypedArray, is the name of the styleable resource (R.styleable.ColorMixer) concatenated with an underscore and the name of the attribute itself (_initialColor). In ColorMixer, we get the attribute and pass it to setColor(). Since getInt() on AttributeSet takes a default value, we supply some stock color that will be used if the developer declined to supply an initialColor attribute. 1929 CRAFTING YOUR OWN VIEWS Also note that our ColorMixer constructor inflates the widget’s layout. In particular, it supplies true as the third parameter to inflate(), meaning that the contents of the layout should be added as children to the ColorMixer itself. When the layout is inflated, the element is ignored, and the element’s children are added as children to the ColorMixer. Saving the State Similar to activities, a custom View overrides onSaveInstanceState() and onRestoreInstanceState() to persist data as needed, such as to handle a screen orientation change. The biggest difference is that rather than receive a Bundle as a parameter, onSaveInstanceState() must return a Parcelable with its state… including whatever state comes from the parent View. The simplest way to do that is to return a Bundle, in which we have filled in our state (the chosen color) and the parent class’ state (whatever that may be). So, for example, here are implementations of onSaveInstanceState() and onRestoreInstanceState() from ColorMixer: @Override public Parcelable onSaveInstanceState() { Bundle state=new new Bundle(); state.putParcelable(SUPERSTATE, super super.onSaveInstanceState()); state.putInt(COLOR, getColor()); return return(state); } @Override public void onRestoreInstanceState(Parcelable ss) { Bundle state=(Bundle)ss; super super.onRestoreInstanceState(state.getParcelable(SUPERSTATE)); setColor(state.getInt(COLOR)); } (from Views/ColorMixer/app/src/main/java/com/commonsware/android/colormixer/ColorMixer.java) The Rest of the Functionality ColorMixer defines a callback interface, named OnColorChangedListener: 1930 CRAFTING YOUR OWN VIEWS public interface OnColorChangedListener { public void onColorChange(int argb); } (from Views/ColorMixer/app/src/main/java/com/commonsware/android/colormixer/ColorMixer.java) ColorMixer also provides getters and setters for an OnColorChangedListener object: public OnColorChangedListener getOnColorChangedListener() { return return(listener); } public void setOnColorChangedListener(OnColorChangedListener listener) { this this.listener=listener; } (from Views/ColorMixer/app/src/main/java/com/commonsware/android/colormixer/ColorMixer.java) The rest of the logic is mostly tied up in the SeekBar handler, which will adjust the swatch based on the new color and invoke the OnColorChangedListener object, if there is one: private SeekBar.OnSeekBarChangeListener onMix=new new SeekBar.OnSeekBarChangeListener() { public void onProgressChanged(SeekBar seekBar, int progress, boolean fromUser) { int color=getColor(); swatch.setBackgroundColor(color); if (listener!=null null) { listener.onColorChange(color); } } public void onStartTrackingTouch(SeekBar seekBar) { // unused } public void onStopTrackingTouch(SeekBar seekBar) { // unused } }; (from Views/ColorMixer/app/src/main/java/com/commonsware/android/colormixer/ColorMixer.java) Seeing It In Use The project contains a sample activity, ColorMixerDemo, that shows the use of the ColorMixer widget. 1931 CRAFTING YOUR OWN VIEWS The layout for that activity, shown below, can be found in res/layout/main.xml of the Views/ColorMixer project: (from Views/ColorMixer/app/src/main/res/layout/main.xml) Notice that the root LinearLayout element defines two namespaces, the standard android namespace, and a separate one named mixer. The mixer namespace is given a URL of http://schemas.android.com/apk/res-auto, which indicates to the Android build system to match up mixer attributes with their respective widgets that are supplied via Android library projects. Our ColorMixer widget is in the layout, with a fully-qualified class name (com.commonsware.android.colormixer.ColorMixer), since ColorMixer is not in the android.widget package. Notice that we can treat our custom widget like any other, giving it a width and height and so on. The one attribute of our ColorMixer widget that is unusual is mixer:initialColor. initialColor, you may recall, was the name of the attribute we declared in res/ values/attrs.xml and retrieve in Java code, to represent the color to start with. The mixer namespace is needed to identify where Android should be pulling the rules for what sort of values an initialColor attribute can hold. Since our element indicated that the format of initialColor was color, Android will expect to see a color value here, rather than a string or dimension. The ColorMixerDemo activity is not very elaborate: 1932 CRAFTING YOUR OWN VIEWS package com.commonsware.android.colormixer; import android.app.Activity android.app.Activity; import android.os.Bundle android.os.Bundle; import android.widget.TextView android.widget.TextView; public class ColorMixerDemo extends Activity { private TextView color=null null; @Override public void onCreate(Bundle state) { super super.onCreate(state); setContentView(R.layout.main); color=(TextView)findViewById(R.id.color); ColorMixer mixer=(ColorMixer)findViewById(R.id.mixer); mixer.setOnColorChangedListener(onColorChange); } private ColorMixer.OnColorChangedListener onColorChange= new ColorMixer.OnColorChangedListener() { public void onColorChange(int argb) { color.setText(Integer.toHexString(argb)); } }; } (from Views/ColorMixer/app/src/main/java/com/commonsware/android/colormixer/ColorMixerDemo.java) It gets access to both the ColorMixer and the TextView in the main layout, then registers an OnColorChangedListener with the ColorMixer. That listener, in turn, puts the value of the color in the TextView, so the user can see the hex value of the color along with the shade itself in the swatch. ReverseChronometer: Simply a Custom Subclass Sometimes, what you want to achieve only requires a basic subclass of an existing widget (or container), into which you can pour your business logic. For example, Android has a Chronometer widget, which is used for denoting elapsed time of some operation. It works well, but it only counts up from zero. It cannot be used to display a countdown instead. 1933 CRAFTING YOUR OWN VIEWS But, we can roll a ReverseChronometer that does, simply by subclassing TextView, as seen in the Views/ReverseChronometer sample project: package com.commonsware.android.revchron; import import import import import android.content.Context android.content.Context; android.graphics.Color android.graphics.Color; android.os.SystemClock android.os.SystemClock; android.util.AttributeSet android.util.AttributeSet; android.widget.TextView android.widget.TextView; public long long long class ReverseChronometer extends TextView implements Runnable { startTime=0L; overallDuration=0L; warningDuration=0L; public ReverseChronometer(Context context, AttributeSet attrs) { super super(context, attrs); reset(); } @Override public void run() { long elapsedSeconds= (SystemClock.elapsedRealtime() - startTime) / 1000; if (elapsedSeconds < overallDuration) { long remainingSeconds=overallDuration - elapsedSeconds; long minutes=remainingSeconds / 60; long seconds=remainingSeconds - (60 * minutes); setText(String.format("%d:%02d", minutes, seconds)); if (warningDuration > 0 && remainingSeconds < warningDuration) { setTextColor(0xFFFF6600); // orange } else { setTextColor(Color.BLACK); } postDelayed(this this, 1000); } else { setText("0:00"); setTextColor(Color.RED); } 1934 CRAFTING YOUR OWN VIEWS } public void reset() { startTime=SystemClock.elapsedRealtime(); setText("--:--"); setTextColor(Color.BLACK); } public void stop() { removeCallbacks(this this); } public void setOverallDuration(long overallDuration) { this this.overallDuration=overallDuration; } public void setWarningDuration(long warningDuration) { this this.warningDuration=warningDuration; } } (from Views/ReverseChronometer/app/src/main/java/com/commonsware/android/revchron/ReverseChronometer.java) ReverseChronometer is designed to show minutes and seconds remaining from some initial time. In the constructor, by means to a call to a reset() method, we set the text of the TextView to show a generic starting point (“-:–”), set its color to black, and note the current time (SystemClock.elapsedRealtime()) in a startTime data member. ReverseChronometer also tracks two durations in seconds, with corresponding setter methods: • overallDuration is how long the countdown should run from beginning to end • warningDuration is how far from the end we should change the color of the TextView from black to orange, to hint to the viewer that time is running out ReverseChronometer implements Runnable, and when its run() method is called, it determines how many seconds have elapsed since that startTime value. Depending on the amount of seconds remaining, we either: • Just update the text to show the minutes and seconds remaining • Update the text and set the color to black or orange • Set the text to “0:00” (time has run out) and set the text color to red 1935 CRAFTING YOUR OWN VIEWS In either of the first two cases, we also call postDelayed() to schedule ourselves to run again in a second, where we can update the TextView contents once more. That continues until somebody calls stop(). As with any custom View, we can reference this in a layout XML resource, fullyqualifying the class name used as the name of our XML element for the widget. And, since we inherit from TextView, we can set any of the attributes that we want on that TextView, in terms of styling the text, positioning it within a parent container, etc.: > /> (from Views/ReverseChronometer/app/src/main/res/layout/activity_main.xml) All our activity needs to do is set the durations, then call run() and stop() at appropriate times, such as when the activity is resumed and paused: package com.commonsware.android.revchron; import android.app.Activity android.app.Activity; import android.os.Bundle android.os.Bundle; public class MainActivity extends Activity { private ReverseChronometer chrono=null null; @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); chrono=(ReverseChronometer)findViewById(R.id.chrono); chrono.setOverallDuration(90); chrono.setWarningDuration(10); 1936 CRAFTING YOUR OWN VIEWS } @Override public void onResume() { super super.onResume(); chrono.run(); } @Override public void onPause() { chrono.stop(); super super.onPause(); } } (from Views/ReverseChronometer/app/src/main/java/com/commonsware/android/revchron/MainActivity.java) The result is much as you would expect: a countdown of the time remaining: Figure 620: ReverseChronometer, Early in Countdown …changing to orange when we are within the warning duration: 1937 CRAFTING YOUR OWN VIEWS Figure 621: ReverseChronometer, Late in Countdown …and changing to red when time has run out: 1938 CRAFTING YOUR OWN VIEWS Figure 622: ReverseChronometer, With Complete Time Elapsed Of course, much more could be done with this widget, if you chose: • Support other constructors, beyond the two-argument constructor needed for layout inflation • Support setting durations and colors via custom XML attributes • Adding listeners for warning and expired events, so other things can be done at those points in time (e.g., play a sound, vibrate the device) AspectLockedFrameLayout: A Custom Container You can also craft your own custom container classes, whether inheriting straight from ViewGroup to implement your own set of layout rules, or by extending an existing ViewGroup to merely augment its functionality. For example, there may be cases where you want to control the aspect ratio of some set of widgets. This is important when working with preview frames off of the Camera to prevent distortion, for example. 1939 CRAFTING YOUR OWN VIEWS AspectLockedFrameLayout, therefore, is a custom extension of FrameLayout that ensures that its contents are kept within a particular aspect ratio, reducing the height or width of the contents to keep that aspect ratio. AspectLockedFrameLayout is published as part of the CWAC-Layouts project, with its own GitHub repo. As with many of the CWAC projects, the reusable code is distributed as a JAR and as an Android library project, with a demo/ sub-project illustrating the use of some of the library’s contents. AspectLockedFrameLayout holds onto two data members: • A double (aspectRatio) that represents a specific aspect ratio to maintain, initialized to 0.0 • A View (aspectRatioSource) that represents some other widget whose aspect ratio should be matched, initialized to null AspectLockedFrameLayout has corresponding setters for each: lockedHeight=(int)(lockedWidth / localRatio + .5); } // Add the padding of the border. lockedWidth+=hPadding; lockedHeight+=vPadding; // Ask children to follow the new preview dimension. super super.onMeasure(MeasureSpec.makeMeasureSpec(lockedWidth, MeasureSpec.EXACTLY), MeasureSpec.makeMeasureSpec(lockedHeight, MeasureSpec.EXACTLY)); } } /** * Supplies a View as a source. The AspectLockedFrameLayout will aim to * match the aspect ratio of this View. This is a one-time check; if the * View changes its aspect ratio later, the AspectLockedFrameLayout will * not attempt to match it. * * @param v some View The “business logic” of maintaining the aspect ratio comes in onMeasure(). onMeasure() is called on a ViewGroup when it is time for it to determine its actual size, based upon things like the requested height and width and the sizes of its 1940 CRAFTING YOUR OWN VIEWS children. In our case onMeasure() needs to be tweaked to maintain the aspect ratio, assuming that we have an aspect ratio to work with: } /** * {@inheritDoc} */ public AspectLockedFrameLayout(Context context, AttributeSet attrs) { super super(context, attrs); } // from com.android.camera.PreviewFrameLayout, with slight // modifications /** * {@inheritDoc} */ @Override protected void onMeasure(int widthSpec, int heightSpec) { double localRatio=aspectRatio; if (localRatio == 0.0 && aspectRatioSource != null && aspectRatioSource.getHeight() > 0) { localRatio= (double)aspectRatioSource.getWidth() / (double)aspectRatioSource.getHeight(); } if (localRatio == 0.0) { super super.onMeasure(widthSpec, heightSpec); } else { int lockedWidth=MeasureSpec.getSize(widthSpec); int lockedHeight=MeasureSpec.getSize(heightSpec); if (lockedWidth == 0 && lockedHeight == 0) { throw new IllegalArgumentException( "Both width and height cannot be zero -- watch out for scrollable containers"); } // Get the padding of the border background. int hPadding=getPaddingLeft() + getPaddingRight(); int vPadding=getPaddingTop() + getPaddingBottom(); // Resize the preview frame with correct aspect ratio. lockedWidth-=hPadding; lockedHeight-=vPadding; if (lockedHeight > 0 && (lockedWidth > lockedHeight * localRatio)) { lockedWidth=(int)(lockedHeight * localRatio + .5); } We start by determining what actually is the desired aspect ratio, held onto in a localRatio local variable. That will be aspectRatio if we do not have an aspectRatioSource that already knows its size, otherwise we will calculate the 1941 CRAFTING YOUR OWN VIEWS aspect ratio from the source. And, if localRatio turns out to be 0.0, indicating that we do not have an aspect ratio to maintain, we just chain to the superclass, so AspectLockedFrameLayout will behave just like a normal FrameLayout. If we do have an aspect ratio to maintain, we start by determining our requested height and width. onMeasure() is passed a pair of “specs” that provides details about our requested size, and we can get the height and width from those by means of the MeasureSpec helper class. We remove any horizontal padding — padding is considered to be “outside” the locked area and therefore is ignored in aspect ratio calculations. We then adjust the height or the width, as needed, to maintain the aspect ratio. We add back in the padding, then chain to the superclass with revised height and width “specs” via MeasureSpec. Note that much of this logic was derived from com.android.camera.PreviewFrameLayout from the AOSP Camera application, which is used to maintain the aspect ratio of the SurfaceView used to display preview frames. To use an AspectLockedFrameLayout, just add it to your layout XML file, with an appropriate child widget/container representing the material that needs to maintain a particular aspect ratio. Since the AspectLockedFrameLayout is overriding its natural size, you can use android:layout_gravity to control its positioning within some parent widget, such as centering it: > > Mirror and MirroringFrameLayout: Draw It Yourself Another scenario where aspect ratios matter is when you are presenting information on an external display via Presentation, as is covered elsewhere in this book. 1942 CRAFTING YOUR OWN VIEWS Ideally, you fill the external display. And normally this will happen for you automatically, as your Presentation content view should fill the available screen space… assuming that the content has the right aspect ratio, or can be suitably stretched. One scenario where this might be a problem is if you want the same material shown on both the main display and on the external display. For example, suppose that you are using Presentation to deliver… well… a presentation. The external display is probably some form of video projector, and you will want your slides or other materials shown there. However, it is useful for you to be able to see those same slides and such on the tablet, as typically the projector screen is behind, or to the side of, the presenter. If the presenter has to keep turning around to confirm what is shown on “the big screen”, it can detract from the presentation. Moreover, you might not only want to show the same material, but have it stem from the same source, on the tablet, for interactivity reasons. Suppose that you want to display a Web page. You might just pop up a WebView in the Presentation. But… how do you scroll? The Presentation offers no touch interface — projector screens do not magically respond to pinch-to-zoom just because we happen to be projecting something onto them from an Android tablet. In this case, ideally we would like to mirror something. Have the actual widgets shown on the tablet, which can then respond to touch events and the like. At the same time, capture what is shown on the tablet and reproduce it, verbatim, on the Presentation for the audience to see. Now everybody can see the same material, and the presenter can manipulate that material. But now aspect ratios come into play. We want to fill the Presentation display space, without black bars or stretching or whatever. That only works if our source material — the widgets and containers to be mirrored — have the same aspect ratio as the Presentation’s Display itself. With that in mind, the CWAC Layouts project also contains two classes to solve this problem: • MirroringFrameLayout is an AspectLockedFrameLayout that also can mirror its content to… • Mirror, a View that takes a Bitmap representing the MirroringFrameLayout contents and displays it 1943 CRAFTING YOUR OWN VIEWS Technically, MirroringFrameLayout works with a MirrorSink, an interface that can receive updates to the content to be mirrored when that content changes. Mirror implements MirrorSink, and you could have other classes implement MirrorSink as well if that made sense for your app. The sections that follow focus on MirroringFrameLayout working with a Mirror, as that is the most likely scenario. MirroringFrameLayout MirroringFrameLayout extends AspectLockedFrameLayout, so that we can lock the aspect ratio of the to-be-mirrored contents to match the aspect ratio of the Mirror. The Mirror is designed to be projected by the Presentation, and so if the Mirror fills the Presentation’s Display, we want our MirroringFrameLayout to match the aspect ratio so the entire Display can indeed be filled. Of course, a ViewGroup like FrameLayout normally just has its children draw to the screen. In our case, we need to capture what is drawn ourselves, to supply to the Mirror as needed. This is a bit tricky. package com.commonsware.cwac.layouts; import import import import import import import android.content.Context android.content.Context; android.graphics.Bitmap android.graphics.Bitmap; android.graphics.Canvas android.graphics.Canvas; android.graphics.Rect android.graphics.Rect; android.util.AttributeSet android.util.AttributeSet; android.view.ViewTreeObserver.OnPreDrawListener android.view.ViewTreeObserver.OnPreDrawListener; android.view.ViewTreeObserver.OnScrollChangedListener android.view.ViewTreeObserver.OnScrollChangedListener; /** * A FrameLayout that locks its aspect ratio (courtesy of AspectLockedFrameLayout) * and supplies "screenshots" of its contents to an associated MirrorSink, * such as a Mirror. * * Principally, MirroringFrameLayout and Mirror are designed for use with * Android's Presentation system. The MirroringFrameLayout would be part of the * UI of the activity on the mobile device, allowing for user interaction. The * Mirror would be used in the Presentation to show an audience (e.g., via a * projector) what is shown inside the MirroringFrameLayout on the mobile * device. */ public class MirroringFrameLayout extends AspectLockedFrameLayout implements OnPreDrawListener, OnScrollChangedListener { private MirrorSink mirror=null null; private Bitmap bmp=null null; private Canvas bmpBackedCanvas=null null; private Rect rect=new new Rect(); /** * {@inheritDoc} */ public MirroringFrameLayout(Context context) { 1944 CRAFTING YOUR OWN VIEWS this this(context, null null); } /** * {@inheritDoc} */ public MirroringFrameLayout(Context context, AttributeSet attrs) { super super(context, attrs); setWillNotDraw(false false); } /** * Associate a MirrorSink; this sink will be given bitmaps representing * updated contents of the MirroringFrameLayout as those contents change. * * @param mirror a Mirror or other MirrorSink implementation */ public void setMirror(MirrorSink mirror) { this this.mirror=mirror; if (mirror != null null) { setAspectRatioSource(mirror); } } /** * {@inheritDoc} */ @Override public void onAttachedToWindow() { super super.onAttachedToWindow(); getViewTreeObserver().addOnPreDrawListener(this this); getViewTreeObserver().addOnScrollChangedListener(this this); } /** * {@inheritDoc} */ @Override public void onDetachedFromWindow() { getViewTreeObserver().removeOnPreDrawListener(this this); getViewTreeObserver().removeOnScrollChangedListener(this this); super super.onDetachedFromWindow(); } /** * {@inheritDoc} */ @Override public void draw(Canvas canvas) { if (mirror != null null) { bmp.eraseColor(0); super super.draw(bmpBackedCanvas); getDrawingRect(rect); canvas.drawBitmap(bmp, null null, rect, null null); mirror.update(bmp); 1945 CRAFTING YOUR OWN VIEWS } else { super super.draw(canvas); } } /** * {@inheritDoc} */ @Override protected void onSizeChanged(int w, int h, int oldw, int oldh) { initBitmap(w, h); super super.onSizeChanged(w, h, oldw, oldh); } /** * {@inheritDoc} */ @Override public boolean onPreDraw() { if (mirror != null null) { if (bmp == null null) { requestLayout(); } else { invalidate(); } } return return(true true); } /** * {@inheritDoc} */ @Override public void onScrollChanged() { onPreDraw(); } private void initBitmap(int w, int h) { if (mirror != null null) { if (bmp == null || bmp.getWidth() != w || bmp.getHeight() != h) { if (bmp != null null) { bmp.recycle(); } bmp=Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888); bmpBackedCanvas=new new Canvas(bmp); } } } } Our one-argument constructor uses this() to chain to the two-argument constructor. The two-argument constructor calls setWillNotDraw(false) indicating to Android that we want this ViewGroup to participate in the drawing process like a 1946 CRAFTING YOUR OWN VIEWS regular View — normally, certain steps in the drawing process are skipped as being irrelevant to View classes that do not draw anything themselves. We have a setMirror() method, where the activity or fragment can supply the MirrorSink that is connected to this MirroringFrameLayout. In addition to holding onto the MirrorSink in a mirror data member, we call setAspectRatioSource(), inherited from AspectLockedFrameLayout, so our contents will match the aspect ratio from that source. MirroringFrameLayout overrides onAttachedToWindow() and onDetatchedFromWindow(). As one might guess, these callbacks are called when views are attached and detached from some window. Usually, that window represents an activity, though it could represent a Dialog or a Presentation. In those callbacks, we connect with the ViewTreeObserver of the MirroringFrameLayout. A ViewTreeObserver is a way to find out about events of a view tree, rooted at some ViewGroup. In our case, we want to find out when children are going to be drawn (addOnPreDrawListener()) and when they are scrolled (addOnScrollChangedListener()). We override onSizeChanged(). This is called on any View when its size may have changed, either because it is being sized initially when the UI is being set up, or because something else nearby changed size (e.g., its parent) and therefore the size of the View itself may now be different. In our case, we use onSizeChanged() to set up a Bitmap object, sized to match our size, and a Canvas object that wraps around that Bitmap object. As you will see, we will use this Canvas to capture what is being drawn on the screen, for later use by the Mirror. We also override draw(). This is, in effect, the “entry point” into the logic that causes a View to render itself on the screen, by drawing to a supplied Canvas object. Most View classes do not override draw(), as the real rendering is done in an onDraw() method, as we will see with Mirror later in this chapter. However, in our case, we have to override draw() for one simple reason: we do not want to draw to the Canvas supplied by Android to the draw() method. We want to draw to our own Canvas, backed by that Bitmap. To that end, if we have a MirrorSink, we: • Make sure the Bitmap starts off blank by calling eraseColor() • Chain to the superclass, replacing the Canvas given to us in draw() by our own Bitmap-backed Canvas 1947 CRAFTING YOUR OWN VIEWS • Calculate a Rect object with our size and position, using getDrawingRect() • Use that Rect and the Bitmap to render the Bitmap to the “real” Canvas supplied to us in draw() • Call update() on the MirrorSink, to give it the new Bitmap By rendering our contents to the Bitmap-backed Canvas, instead of the normal one, we capture a copy of the output, in the form of the Bitmap. Since the Bitmap has the same size as the “real” Canvas (courtesy of our onSizeChanged() work), when we draw the Bitmap onto the Canvas, we effectively “color in” the same pixels in the same spots as if we had skipped all of this and left the normal draw() logic alone. But, since we still hold onto our Bitmap, we can use those same pixels elsewhere… such as in our Mirror. The problem with relying on draw() is that it is not always called when there are changes to widgets within the MirroringFrameLayout. In particular, WebView often does not trigger draw() on the MirroringFrameLayout. That’s where the pre-draw and scroll-changed events from the ViewTreeObserver come into play: they give us more indication that we need to update our Bitmap. The onPreDraw() method is called when a child of this MirroringFrameLayout is about to be drawn. If we have our MirrorSink, we then either call requestLayout() (if we have no bitmap yet) or invalidate() (if we do), to trigger Android to go through the draw process for the MirroringFrameLayout too, allowing us to update our Bitmap. The onScrollChanged() method is called when a child of this MirroringFrameLayout has been scrolled. This delegates to onPreDraw(), to run through the same logic to force an update to the Bitmap. Mirror Mirror extends the base View class, and so it is the most “raw” of all the custom widgets and containers shown so far in this chapter. It has an update() method, used to connect the MirroringFrameLayout from which the Mirror can obtain what it is supposed to display: package com.commonsware.cwac.layouts; import import import import android.content.Context android.content.Context; android.graphics.Bitmap android.graphics.Bitmap; android.graphics.Canvas android.graphics.Canvas; android.graphics.Rect android.graphics.Rect; 1948 CRAFTING YOUR OWN VIEWS import android.util.AttributeSet android.util.AttributeSet; import android.view.View android.view.View; /** * A View that implements MirrorSink and renders the supplied bitmaps to its * own contents. When connected to a MirroringFrameLayout, Mirror will aim to * show the same contents as is in the MirroringFrameLayout, at the same aspect * ratio, though possibly at a different size. * * Principally, MirroringFrameLayout and Mirror are designed for use with * Android's Presentation system. The MirroringFrameLayout would be part of the * UI of the activity on the mobile device, allowing for user interaction. The * Mirror would be used in the Presentation to show an audience (e.g., via a * projector) what is shown inside the MirroringFrameLayout on the mobile * device. */ public class Mirror extends View implements MirrorSink { private Rect rect=new new Rect(); private Bitmap bmp=null null; /** * {@inheritDoc} */ public Mirror(Context context) { super super(context); } /** * {@inheritDoc} */ public Mirror(Context context, AttributeSet attrs) { super super(context, attrs); } /** * {@inheritDoc} */ public Mirror(Context context, AttributeSet attrs, int defStyle) { super super(context, attrs, defStyle); } /** * {@inheritDoc} */ @Override public void update(Bitmap bmp) { this this.bmp=bmp; invalidate(); 1949 CRAFTING YOUR OWN VIEWS } /** * {@inheritDoc} */ @Override protected void onDraw(Canvas canvas) { super super.onDraw(canvas); if (bmp != null null) { getDrawingRect(rect); calcCenter(rect.width(), rect.height(), bmp.getWidth(), bmp.getHeight(), rect); canvas.drawBitmap(bmp, null null, rect, null null); } } // based upon http://stackoverflow.com/a/14679729/115145 static void calcCenter(int vw, int vh, int iw, int ih, Rect out) { double scale= Math.min((double)vw / (double)iw, (double)vh / (double)ih); int int int int h=(int)(scale * ih); w=(int)(scale * iw); x=((vw - w) >> 1); y=((vh - h) >> 1); out.set(x, y, x + w, y + h); } } The bulk of the “business logic” lies in onDraw(), plus a helper calcCenter() static method. onDraw() is called on a View when it is time for that widget to actually draw its visual representation onto the supplied Canvas. Different widgets will use different drawing primitive methods offered by Canvas, to draw lines and text and whatnot. In our case, we: • Calculate a Rect object with our size and position, using getDrawingRect() • Get the Bitmap object from the MirroringFrameLayout, via a call to getLastBitmap() (which simply returns the Bitmap that the MirroringFrameLayout is using) 1950 CRAFTING YOUR OWN VIEWS • Call calcCenter to adjust our Rect to take into account the fact that our size may be different than the size of the actual Bitmap • Call drawBitmap() on our Canvas, to render the Bitmap into the location specified by the Rect, where drawBitmap() will automatically down-sample or up-sample the image as needed to fill the necessary space Usage and Results Normally, you would use the Mirror in a layout for a Presentation and the MirroringFrameLayout in an activity that controls the Presentation. However, it is possible to use both in the same layout file, for light testing. However, please do not put the Mirror inside of the MirroringFrameLayout, as this is likely to cause a rupture in the space-time continuum, and you really do not want to be responsible for that. So, in the SimpleMirrorActivity from the demo/ sub-project, we use a layout that has both Mirror and MirroringFrameLayout, with the latter set to mirror a WebView: > > > /> 1951 CRAFTING YOUR OWN VIEWS /> /> In this case, we set the background of the FrameLayout holding our MirroringFrameLayout to green, to show how the MirroringFrameLayout size is changed to maintain our aspect ratio. (or, perhaps we just like green) Besides configuring the to-be-mirrored widgets, all you need to do is call setMirror() on the MirroringFrameLayout to enable the mirroring logic: package com.commonsware.cwac.layouts.demo; import import import import android.app.Activity android.app.Activity; android.os.Bundle android.os.Bundle; com.commonsware.cwac.layouts.Mirror com.commonsware.cwac.layouts.Mirror; com.commonsware.cwac.layouts.MirroringFrameLayout com.commonsware.cwac.layouts.MirroringFrameLayout; public class SimpleMirrorActivity extends Activity { MirroringFrameLayout source=null null; @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.simple_mirror); source=(MirroringFrameLayout)findViewById(R.id.source); Mirror target=(Mirror)findViewById(R.id.target); source.setMirror(target); } } 1952 CRAFTING YOUR OWN VIEWS Figure 623: MirroringFrameLayout Above Its Mirror While the bottom portion is just the Mirror and therefore is non-interactive, the top is the real WebView, which can be scrolled, with the resulting changes reflected in the Mirror in real-time: 1953 CRAFTING YOUR OWN VIEWS Figure 624: MirroringFrameLayout and Mirror, Showing Scrolled Contents Limitations MirroringFrameLayout only works for materials drawn in the Java layer, that therefore can be drawn to the Bitmap-backed Canvas. Content not drawn in the Java layer will not work with MirroringFrameLayout, notably anything involving a SurfaceView. This not only includes your own SurfaceView widgets, but anything else that depends upon SurfaceView, such as VideoView or the Maps V2 MapView and MapFragment. Also, the re-sampling done by Mirror is not especially sophisticated and will cause jagged effects, particularly when up-sampling. Ideally, the MirroredFrameLayout will be the same size or larger than the Mirror. This may not always be possible, particularly with a Mirror shown on a 1080p external display, but the closer you can get will improve the output. 1954 Advanced Preferences We saw SharedPreferences and PreferenceFragment earlier in the book. However, we can have more elaborate preference collection options if we wish, such as a full master-detail implementation like the Settings app sports. There are also many other common attributes on the preference XML elements that we might consider taking advantage of, such as allowing us to automatically enable and disable preferences based upon whether some other preference is checked or unchecked. In this chapter, we will explore some of these additional capabilities in the world of Android preferences. Prerequisites Understanding this chapter requires that you have read the core chapters, particularly the one on SharedPreferences. Introducing PreferenceActivity If you have a fairly simple set of preferences to collect from the user, using a single PreferenceFragment should be sufficient. On the far other end of the spectrum, Android’s Settings app collects a massive amount of preference values from the user. These are spread across a series of groups of preferences, known as preference headers. While your app may not need to collect as many preferences as does the Settings app, you may need more than what could be collected easily in a single PreferenceFragment. In that case, you can consider adopting the same structure of 1955 ADVANCED PREFERENCES headers-and-fragments that the Settings app uses, by means of a PreferenceActivity. To see this in action, take a look at the Prefs/FragmentsBC sample project. It is very similar to the original SharedPreferences demo app from before. However, this one arranges to collect a fifth preference value, in a separate PreferenceFragment, and uses PreferenceActivity to allow access to both PreferenceFragment UI structures. Defining Your Preference Headers In the master-detail approach offered by PreferenceActivity, the “master” list is a collection of preference headers. Typically, you would define these in another XML resource. In the sample project, that is found in res/xml/preference_headers.xml: >

>

>

(from Prefs/FragmentsBC/app/src/main/res/xml/preference_headers.xml) Here, your root element is , containing a series of

elements. Each

contains at least three attributes: 1. android:fragment, which identifies the Java class implementing the PreferenceFragment to use for this header, as is described in the next section 2. android:title, which is a few words identifying this header to the user Once again, you may wish to also include android:summary, which is a short sentence explaining what the user will find inside of this header. 1956 ADVANCED PREFERENCES You can, if you wish, include one or more child elements inside the

element. These values will be put into the “arguments” Bundle that the associated PreferenceFragment can retrieve via getArguments(). Creating Your PreferenceActivity EditPreferences — which in the original sample app was a regular Activity now a PreferenceActivity. It contains little more than the two fragments referenced in the above preference header XML: package com.commonsware.android.preffragsbc; import import import import android.os.Bundle android.os.Bundle; android.preference.PreferenceActivity android.preference.PreferenceActivity; android.preference.PreferenceFragment android.preference.PreferenceFragment; java.util.List java.util.List; public class EditPreferences extends PreferenceActivity { @Override public void onBuildHeaders(List

target) { loadHeadersFromResource(R.xml.preference_headers, target); } @Override protected boolean isValidFragment(String fragmentName) { if (First.class.getName().equals(fragmentName) || Second.class.getName().equals(fragmentName)) { return return(true true); } return return(false false); } public static class First extends PreferenceFragment { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); addPreferencesFromResource(R.xml.preferences); } } public static class Second extends PreferenceFragment { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); 1957 — is ADVANCED PREFERENCES addPreferencesFromResource(R.xml.preferences2); } } } (from Prefs/FragmentsBC/app/src/main/java/com/commonsware/android/preffragsbc/EditPreferences.java) onBuildHeaders() is where we loadHeadersFromResource(). supply the preference headers, via a call to We also need to have an isValidFragment() method, that will return true if the supplied fragment name is one we should be showing in this PreferenceActivity, false otherwise. This will only be called on Android 4.4+. However, we need to set up the project build target (e.g., compileSdkVersion in Android Studio) to API Level 19 or higher. Failing to have this method will cause your app to crash on Android 4.4+ devices, when the user tries to bring up one of your PreferenceFragments. Each PreferenceFragment is then responsible for calling addPreferencesFromResource() to populate its contents. In this case, we now have two such resources: res/xml/preferences.xml (the original, used by First) and res/xml/preferences2.xml (used by Second). The Results On a wide enough screen — like that of a Nexus 9 in landscape — we get a masterdetail presentation: 1958 ADVANCED PREFERENCES Figure 625: PreferenceActivity UI, on a Landscape Nexus 9 Here, we see the first preference fragment already pre-selected, showing its settings. Tapping on the second header will show the other preferences. On a smaller screen, the master-detail approach means that we see a list of headers first: 1959 ADVANCED PREFERENCES Figure 626: PreferenceActivity UI, on a Portrait Nexus 5 Tapping the headers give us access to the individual fragments. Intents for Headers or Preferences If you have the need to collect some preferences that are beyond what the standard preferences can handle, you have some choices. One is to create a custom Preference. Extending DialogPreference to create your own Preference implementation is not especially hard. However, it does constrain you to something that can fit in a dialog. Another option is to specify an element as a child of a

element. When the user taps on this header, your specified Intent is used with startActivity(), giving you a gateway to your own activity for collecting things that are beyond what the preference UI can handle. For example, you could have the following

:

>

Then, so long as you have an activity with an specifying your desired action (com.commonsware.android.MY_CUSTOM_ACTION), that activity will get control when the user taps on the associated header. Conditional Headers The two-tier, headers-and-preferences approach is fine and helps to organize large rosters of preferences. However, it does tend to steer developers in the direction of displaying headers all of the time. For many apps, that is rather pointless, because there are too few preferences to collect to warrant having more than one header. One alternative approach is to use the headers on larger devices, but skip them on smaller devices. That way, the user does not have to tap past a single-item ListFragment just to get to the actual preferences to adjust. This is a wee bit tricky to implement. However, you have two options for how to accomplish it. (The author would like to thank Richard Le Mesurier, whose question on this topic spurred the development of this section and its samples) Option #1: Do Not Define the Headers The basic plan in the first approach is to have smarts in onBuildHeaders() to handle this. onBuildHeaders() is the callback that Android invokes on our PreferenceActivity to let us define the headers to use in the master-detail pattern. If we want to have headers, we would supply them here; if we want to skip the headers, we would instead fall back to the classic (and, admittedly, deprecated) addPreferencesFromResource() method to load up some preference XML. There is an isMultiPane() method on PreferenceActivity, starting with API Level 11, that will tell you if the activity will render with two fragments (master+detail) or not. In principle, this would be ideal to use. Unfortunately, it does not seem to be designed to be called from onBuildHeaders(). Similarly, addPreferencesFromResource() does not seem to be callable from onBuildHeaders(). Both are due to timing: onBuildHeaders() is called in the middle of the PreferenceActivity onCreate() processing. 1961 ADVANCED PREFERENCES So, we have to do some fancy footwork. By examining the source code to PreferenceActivity, you will see that the logic that drives the single-pane vs. dual-pane UI decision boils down to: onIsHidingHeaders() || !onIsMultiPane() If that expression returns true, we are in single-pane mode; otherwise, we are in dual-pane mode. onIsHidingHeaders() will normally return false, while onIsMultiPane() will return either true or false based upon screen size. So, we can leverage this information in a PreferenceActivity to conditionally load our headers, as seen in the EditPreferences class in the Prefs/SingleHeader sample project: package com.commonsware.android.pref1header; import android.os.Bundle android.os.Bundle; import android.preference.PreferenceActivity android.preference.PreferenceActivity; import java.util.List java.util.List; public class EditPreferences extends PreferenceActivity { private boolean needResource=false false; @SuppressWarnings("deprecation") @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); if (needResource) { addPreferencesFromResource(R.xml.preferences); } } @Override public void onBuildHeaders(List

target) { if (onIsHidingHeaders() || !onIsMultiPane()) { needResource=true true; } else { loadHeadersFromResource(R.xml.preference_headers, target); } } @Override protected boolean isValidFragment(String fragmentName) { 1962 ADVANCED PREFERENCES return return(StockPreferenceFragment.class.getName().equals(fragmentName)); } } (from Prefs/SingleHeader/app/src/main/java/com/commonsware/android/pref1header/EditPreferences.java) Here, if we are in dual-pane mode, onBuildHeaders() populates the headers as normal. If, though, we are in single-pane mode, we skip that step and make note that we need to do some more work in onCreate(). Then, in onCreate(), if we did not load our headers we use the classic addPreferencesFromResource() method. The net result is that on Android 3.0+ tablets, we get the dual-pane, master-detail look with our one header, but on smaller devices (regardless of version), we roll straight to the preferences themselves. Note that this sample application uses a single PreferenceFragment implementation, named StockPreferenceFragment: package com.commonsware.android.pref1header; import android.os.Bundle android.os.Bundle; import android.preference.PreferenceFragment android.preference.PreferenceFragment; public class StockPreferenceFragment extends PreferenceFragment { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); int res= getActivity().getResources() .getIdentifier(getArguments().getString("resource"), "xml", getActivity().getPackageName()); addPreferencesFromResource(res); } } (from Prefs/SingleHeader/app/src/main/java/com/commonsware/android/pref1header/StockPreferenceFragment.java) StockPreferenceFragment does what it is supposed to: call addPreferencesFromResource() in onCreate() with the resource 1963 ID of the ADVANCED PREFERENCES preferences to load. However, rather than hard-coding a resource ID, as we normally would, we look it up at runtime. The elements in our preference header XML supply the name of the preference XML to be loaded: >

> />

(from Prefs/SingleHeader/app/src/main/res/xml/preference_headers.xml) We get that name via the arguments Bundle (getArguments().getString("resource")). To look up a resource ID at runtime, we can use the Resources object, available from our activity via a call to getResources(). Resources has a method, getIdentifier(), that will return a resource ID given three pieces of information: 1. The base name of the resource (in our case, the value retrieved from the element) 2. The type of the resource (e.g., "xml") 3. The package holding the resource (in our case, our own package, retrieved from our activity via getPackageName()) Note that getIdentifier() uses reflection to find this value, and so there is some overhead in the process. Do not use getIdentifier() in a long loop – cache the value instead. The net is that StockPreferenceFragment loads the preference XML described in the element, so we do not need to create separate PreferenceFragment implementations per preference header. 1964 ADVANCED PREFERENCES Option #2: Go Directly to the Fragment The advantage of the above approach is that it works with Android’s own logic of whether to display the master-detail fragments or just one at a time. However, that logic — the fact that onIsHidingHeaders() || !onIsMultiPane() determines the look of the activity — is not documented, and therefore may change in future Android releases. Another option is to launch your PreferenceActivity in such a way that tells Android to skip showing the headers. This approach is better documented and therefore perhaps more stable. This can also be used in cases where you do want headers sometimes, but at other times you want to route the user to a specific PreferenceFragment. The downside is that this technique only works on API Level 11+. To see how this works, take a look at the Prefs/SingleHeader2 sample project. Our EditPreferences class is the same implementation as in the original sample for this chapter, except that we only load up the single XML resource’s worth of preferences: package com.commonsware.android.pref1header; import android.preference.PreferenceActivity android.preference.PreferenceActivity; import java.util.List java.util.List; public class EditPreferences extends PreferenceActivity { @Override public void onBuildHeaders(List

target) { loadHeadersFromResource(R.xml.preference_headers, target); } @Override protected boolean isValidFragment(String fragmentName) { return return(StockPreferenceFragment.class.getName().equals(fragmentName)); } } (from Prefs/SingleHeader2/app/src/main/java/com/commonsware/android/pref1header/EditPreferences.java) However, there is a change in our main activity (FragmentsDemo). Before, when the user chose the “Settings” action bar overflow item, we would just call startActivity() to bring up EditPreferences. Now, we delegate that work to an 1965 ADVANCED PREFERENCES editPrefs() method on FragmentsDemo, which will have the smarts to control how we bring up the EditPreferences activity: private void editPrefs() { Intent i=new new Intent(this this, EditPreferences.class); i.putExtra(PreferenceActivity.EXTRA_SHOW_FRAGMENT, StockPreferenceFragment.class.getName()); Bundle b=new new Bundle(); b.putString("resource", "preferences"); i.putExtra(PreferenceActivity.EXTRA_SHOW_FRAGMENT_ARGUMENTS, b); startActivity(i); } (from Prefs/SingleHeader2/app/src/main/java/com/commonsware/android/pref1header/FragmentsDemo.java) Here, we will add two extras to our Intent: • EXTRA_SHOW_FRAGMENT, set to the fully-qualified class name of the PreferenceFragment to be displayed, here obtained by calling getName() on the Class object for StockPreferenceFragment • EXTRA_SHOW_FRAGMENT_ARGUMENTS, set to a Bundle containing the same values that would ordinarily be loaded from the elements in the preference header XML resource (in our case, the name of the preference XML resource to load) Those extras will be automatically handled by PreferenceActivity (on API Level 11+) and will have the effect of directly taking the user to our one-and-only fragment, bypassing the headers. Dependent Preferences In the Settings app, or in other apps that appear to be using PreferenceFragmentbased UIs, you may have noticed that there are times when preferences are disabled. They become enabled when you check a CheckBoxPreference or toggle on a SwitchPreference. That is handled via the android:dependency attribute on the to-be-disabled preferences. The value of android:dependency is the key of a TwoStatePreference 1966 ADVANCED PREFERENCES subclass, such as a CheckBoxPreference or a SwitchPreference. The enabled/ disabled state of the preference with the android:dependency attribute depends on the checked state of the named dependency. For example, the Prefs/Dependency sample project is a clone of the original SharedPreferences demo app with one slight change: all the preferences other than checkbox are now dependent upon checkbox: > /> /> /> /> (from Prefs/Dependency/app/src/main/res/xml/preferences.xml) When you run the project, the dependent preferences are disabled while the checkbox is unchecked: 1967 ADVANCED PREFERENCES Figure 627: Dependent Preferences, Disabled …but become enabled once the user checks the checkbox: 1968 ADVANCED PREFERENCES Figure 628: Dependent Preferences, Enabled Nested Screens Perhaps you have more preferences than you want to collect on a single screen, but you do not feel that a master-detail presentation is the right structure. Or, perhaps you have lots of preferences to collect, and even collecting preferences into groups by header is insufficient. Another possibility is to nest preference screens. One screen holds another. On the outer preference screen, the user has a “preference” entry that simply displays the nested screen, as opposed to directly collecting any preferences. A element in your preference XML can hold another element. That inner can come in one of two forms: 1. Inside the inner you have more preference XML elements. This means there is only one PreferenceFragment for the whole structure (outer , including the inner 1969 ADVANCED PREFERENCES ). However, visually, the user will “drill down” from the outer screen into the inner one by tapping on an entry. 2. The inner has an android:fragment attribute, just like a preference header might. This points to a Fragment — typically a PreferenceFragment — that will be responsible for the “inner” content. This is a bit more complex to set up, as it requires a couple of fragments. However, it gives you greater flexibility. Plus, it is fairly easy to then switch from using preference headers and the master-detail approach to using nested preference screens, or back again, as you are simply reusing the same PreferenceFragment implementations in either case. The Prefs/NestedScreens sample project takes the master-detail approach shown earlier in this chapter and switches it to having a top-level screen and a nested screen. This is accomplished by adding a element to res/xml/ preferences.xml, pointing to our Second PreferenceFragment: /> (from Prefs/NestedScreens/app/src/main/res/xml/preferences.xml) Here, the android:title (and optional android:summary) will be shown on the outer screen, as an entry that the user can tap on to get to this inner screen. While in this sample, we are not using android:key, in principle you could use this to get at the PreferenceScreen itself to manipulate it at runtime (e.g., disable it). For this style of to work, the preference XML must be used by a PreferenceFragment in a PreferenceActivity — you cannot use it with a regular Activity. However, just because you use PreferenceActivity does not mean that you have to opt into the master-detail structure. We can use the same onCreate(), show-the-PreferenceFragment approach that we use with a regular Activity. However, there is one big catch: when the user taps on the entry that will launch the inner screen, the Android framework will start another instance of our PreferenceActivity. It will give us the same EXTRA_SHOW_FRAGMENT value as we saw earlier in this chapter. However, PreferenceActivity will automatically show that fragment; we do not need to show it ourselves. But, this means that our onCreate() needs to distinguish between the “show the outer screen ourselves” case and the “show the inner screen automatically” case, which we can do by seeing if EXTRA_SHOW_FRAGMENT exists: 1970 ADVANCED PREFERENCES @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); if (getIntent().getStringExtra(PreferenceActivity.EXTRA_SHOW_FRAGMENT)==null null) { if (getFragmentManager().findFragmentById(android.R.id.content)==null null) { getFragmentManager().beginTransaction() .add(android.R.id.content, new First()).commit(); } } } (from Prefs/NestedScreens/app/src/main/java/com/commonsware/android/preffragsbc/EditPreferences.java) The result is that we see the outer screen first, containing our entry for the inner screen: Figure 629: Nested Preferences, Outer Screen Tapping on that entry brings up the inner, nested, screen: 1971 ADVANCED PREFERENCES Figure 630: Nested Preferences, Inner Screen Listening to Preference Changes Sometimes, you may need to take steps when the user interacts with a preference in your PreferenceFragment-based UI. A common scenario for this comes with the summary. In some cases, is it handy to have the summary reflect the current value of the preference. While some preferences naturally show their value inline (e.g., a CheckBoxPreference), those that extend from DialogPreference only show their value when the user taps on the preference to display the dialog. Putting something in the summary that reflects the value can save the user a click. However, by default, the summary is static, populated by the android:summary attribute in your preference XML. If you want it to reflect the current preference value, you not only need to be able to set the summary in Java, but to be able to respond when the user changes the value, so you can update the summary again. The Prefs/CustomSubtitle sample project demonstrates how this works. This is yet another clone of the original SharedPreferences demo app. This time, the 1972 ADVANCED PREFERENCES preference XML is unchanged from the original. However, we have a slightly more elaborate PreferenceFragment implementation: public static class Prefs extends PreferenceFragment implements Preference.OnPreferenceChangeListener { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); addPreferencesFromResource(R.xml.preferences); Preference pref=findPreference("text"); updateSummary(pref, pref.getSharedPreferences().getString(pref.getKey(), null null)); pref.setOnPreferenceChangeListener(this this); } @Override public boolean onPreferenceChange(Preference pref, Object newValue) { updateSummary(pref, newValue.toString()); return return(true true); } private void updateSummary(Preference pref, String value) { if (value==null null || value.length()==0) { pref.setSummary(R.string.msg_missing_text); } else { pref.setSummary(value); } } } (from Prefs/CustomSubtitle/app/src/main/java/com/commonsware/android/preffrag/EditPreferences.java) In onCreate(), after addPreferencesFromResource(), we call findPreference() to retrieve the Preference object that manages the snippet of UI for a particular preference. The flow here mimics that of setContentView() and findViewById(): first you inflate the resource, then you find the Java object corresponding to some XML element out of that resource. findPreference() takes the key of the preference that you are looking for; in this case, we are looking for the EditTextPreference, whose key is text. 1973 ADVANCED PREFERENCES We then call a private updateSummary() method, which takes the Preference and the current value of that preference and updates the summary. To get the current value, onCreate() can ask the Preference for its backing SharedPreferences (via getSharedPreferences()), then retrieve the value using standard getters (e.g., getString()). updateSummary() then shows the string representation of the current value, or a canned message if there does not appear to be a current value. We also register the fragment itself as being the OnPreferenceChangeListener, and register the fragment with the preference via setOnPreferenceChangeListener(). This means that when the user manipulates this preference, we will be called with onPreferenceChange(). This is done before the SharedPreferences are updated. Our options are either to return true and have the normal persistence process continue, or return false and manage persistence ourselves (e.g., perform some conversion on the raw value before storing it). In our case, we are just using this to call updateSummary() again. If you install the app and run it, you will not have an existing value for the preference, and so the summary shows a stock message: Figure 631: Custom Subtitle Demo, Before Editing Text 1974 ADVANCED PREFERENCES After you tap on the EditTextPreference and fill in some value in the dialog, the summary updates to show what you typed in: Figure 632: Custom Subtitle Demo, After Editing Text Defaults, and Defaults When you use SharedPreferences to retrieve a value, you can usually provide a default value along with the key for the value that you want. If there is no preference value for that key, you get the default that you supplied. A preference in preference XML also has an android:defaultValue attribute. This is, roughly speaking, the preference UI counterpart to that second parameter to the SharedPreferences getters. If the user interacts with the preference, the android:defaultValue value will be presented to the user if there was no preference value stored for that key in the underlying SharedPreferences. To synchronize these, you can call setDefaultValues() on the PreferenceManager class. Given the resource ID of some preference XML, PreferenceManager will find all android:defaultValue attributes and then persist those default values to the SharedPreferences under their respective keys. 1975 ADVANCED PREFERENCES Listening to Preference Value Changes Sometimes, you will have components that need to know when preference values are changed elsewhere in your app. For example, you may have a Service that is using information from SharedPreferences, and the Service may need to know when those values change. One approach, used in all the sample apps, is simply to re-read the preference values as needed, rather than caching them in data members or something. After the first time SharedPreferences are accessed, the SharedPreferences themselves are held in heap space, and so accessing them can be fairly cheap. So, the sample apps’ launcher activities just re-read the preference values in onResume() and update the UI that way. If, however, that is inappropriate, inconvenient, or otherwise not what you want to do, you can call registerOnSharedPreferenceChangeListener() on a SharedPreferences object, supplying an instance of an implementation of the OnSharedPreferenceChangeListener interface. That object will be called with onSharedPreferenceChanged() every time a preference value changes. You are given the key to the changed value, so you can implement a filter to only pay attention to keys that matter to you. When one of those keys is reported to have changed, you can ask the SharedPreferences for the new value. Dynamic ListPreference Contents Many times, the items that the user can choose from in your ListPreference or MultiSelectListPreference are fixed, allowing you to populate them from resources. However, sometimes, the items (display names and corresponding values) are dynamic, based upon information held elsewhere: database, server, or something at a system level. For those, we need to be able to define the preference in XML, but configure its contents in Java code. For example, the Introspection/SAWMonitor sample project is a monitor for new and upgraded apps that ask for the SYSTEM_ALERT_WINDOW permission. Such apps have the right to draw over top of other apps, for anything from Facebook “chatheads” to tapjacking attacks. However, some apps may request this permission that you are perfectly fine with having it. By default, SAWMonitor will point out this permission on each subsequent update, which can get tiresome after a while. Hence, SAWMonitor 1976 ADVANCED PREFERENCES allows you to add apps to a “whitelist”; those apps will be ignored, even if they request SYSTEM_ALERT_WINDOW. To that end, we have a settings.xml resource describing some preferences to collect from the user: > /> (from Introspection/SAWMonitor/app/src/main/res/xml/settings.xml) Here we have two preferences: a SwitchPreference for whether we should be monitoring for SYSTEM_ALERT_WINDOW at all, and a MultiSelectListPreference to allow the user to control the whitelist. In onCreate() of our SettingsFragment, we load up those preferences into the UI via addPreferencesFromResource(), use findPreference() to retrieve both of the Preference objects, and use setOnPreferenceChangeListener() to be notified about changes to the enabled preference: @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); addPreferencesFromResource(R.xml.settings); pm=getActivity().getPackageManager(); SwitchPreference enabled=(SwitchPreference)findPreference("enabled"); enabled.setOnPreferenceChangeListener(this this); populateWhitelist((MultiSelectListPreference)findPreference("whitelist")); } (from Introspection/SAWMonitor/app/src/main/java/com/commonsware/android/sawmonitor/SettingsFragment.java) The populateWhitelist() call is where we fill in the details for the MultiSelectListPreference. In our case, the possible values are the apps presently 1977 ADVANCED PREFERENCES installed that have requested the SYSTEM_ALERT_WINDOW permission. So, we use PackageManager to find those, then use that information to populate the whitelist preference: void populateWhitelist(MultiSelectListPreference whitelist) { List apps=pm.getInstalledApplications(0); Collections.sort(apps, new ApplicationInfo.DisplayNameComparator(pm)); ArrayList displayNames= new ArrayList(); ArrayList packageNames=new new ArrayList(); for (ApplicationInfo app : apps) { try { PackageInfo pkgInfo= pm.getPackageInfo(app.packageName, PackageManager.GET_PERMISSIONS); if (pkgInfo.requestedPermissions!=null null) { for (String perm : pkgInfo.requestedPermissions) { if (SYSTEM_ALERT_WINDOW.equals(perm)) { displayNames.add(app.loadLabel(pm)); packageNames.add(app.packageName); break break; } } } } catch (PackageManager.NameNotFoundException e) { // should not happen, quietly ignore } } whitelist .setEntries(displayNames .toArray(new new CharSequence[displayNames.size()])); whitelist .setEntryValues(packageNames .toArray(new new String[packageNames.size()])); } (from Introspection/SAWMonitor/app/src/main/java/com/commonsware/android/sawmonitor/SettingsFragment.java) 1978 ADVANCED PREFERENCES Most of the code is determining which applications have that permission. However, MultiSelectListPreference complicates matters, by having two separate setter methods for its contents: • setEntries() sets the display names, what the user will see in the multiselect dialog • setEntryValues() sets the corresponding values, what will be stored in the SharedPreferences based upon the user’s input These each take arrays of CharSequence implementations, like String. Hence, we need two parallel arrays of values, rather than a single ArrayList of Pair objects or something. With that in mind, populateWhitelist(): • Gets the list of installed applications from the PackageManager (pm is a field initialized in onCreate()) • Sorts those by display name, so our results will wind up in alphabetical order • Creates an ArrayList for the display names and a separate one for the package names, which will serve as our entry values • Iterates over the applications, gets the permissions requested by each app, and if any of those is SYSTEM_ALERT_WINDOW, add the display name (loadLabel()) and the package name to their respective lists • Converts each of those ArrayList objects into a corresponding Java array, and passes them to their appropriate setters The resulting SettingsFragment has the two preferences: 1979 ADVANCED PREFERENCES Figure 633: SAWMonitor SettingsFragment Tapping on the “Whitelist” entry brings up the MultiSelectListPreference: Figure 634: SAWMonitor Whitelist MultiSelectListPreference 1980 ADVANCED PREFERENCES If you run the app on your device or emulator, you will wind up with different possible entries in the MultiSelectListPreference, as the mix of apps requesting SYSTEM_ALERT_WINDOW will be different for different devices and users. Note that, in addition to this section and the next one, you can learn more about SAWMonitor elsewhere in the book. Dealing with External Changes to Preferences What happens if you have a PreferenceFragment in the foreground, and the preference changes “behind the scenes” by some other component of your app? For preferences with dialogs — ListPreference, EditTextPreference, etc. — the pattern seems to be “transaction by dialog”. Whatever the preference value is at the time the dialog appears is what the user sees, and that does not change (and cannot readily be changed) if the preference changes while that dialog is on the screen. However, for inline preferences — CheckBoxPreference, SwitchPreference, etc. — while the UI will not automatically update based on the external change, you can handle that yourself. For example, there is another version of SAWMonitor known as Introspection/ SAWMonitorTile. This sample project is a clone of SAWMonitor with one added feature: an optional notification shade tile using a TileService on Android 7.0. The tile allows the user to enable and disable the monitoring, just as the user can from the SwitchPreference. So… what happens if the SettingsFragment is on the screen, the user slides open the notification shade, and taps the tile? By default, the SettingsFragment would be oblivious to this, with the result of the SwitchPreference being out of sync. But, we can fix this. In the SAWMonitorTile rendition of SettingsFragment, in onStart(), we register for preference changes, plus call a syncEnabledStates() method. We unregister from preference changes in onStop(): @Override public void onStart() { super super.onStart(); prefs=PreferenceManager.getDefaultSharedPreferences(getActivity()); 1981 ADVANCED PREFERENCES prefs.registerOnSharedPreferenceChangeListener(this this); syncEnabledStates(); } @Override public void onStop() { super super.onStop(); prefs.unregisterOnSharedPreferenceChangeListener(this this); } (from Introspection/SAWMonitorTile/app/src/main/java/com/commonsware/android/sawmonitor/SettingsFragment.java) The onSharedPreferenceChanged() method on our SettingsFragment will be called when any of our preferences changes. If the enabled preference changes, we call syncEnabledStates(): @Override public void onSharedPreferenceChanged(SharedPreferences prefs, String s) { if (PREF_ENABLED.equals(s)) { syncEnabledStates(); } } (from Introspection/SAWMonitorTile/app/src/main/java/com/commonsware/android/sawmonitor/SettingsFragment.java) syncEnabledStates() simply updates the checked now-current value in SharedPreferences: state of enabled based upon the void syncEnabledStates() { enabled.setChecked(prefs.getBoolean(PREF_ENABLED, false false)); } (from Introspection/SAWMonitorTile/app/src/main/java/com/commonsware/android/sawmonitor/SettingsFragment.java) This therefore also handles the case where our SettingsFragment was displayed, the user navigated elsewhere, one of our preferences changes, and then the user returns to our running SettingsFragment. Normally, the SettingsFragment might miss that preference change, but with this implementation, the SettingsFragment will be kept in sync with the actual preference value. 1982 ADVANCED PREFERENCES Preferences in Device Settings App On Android 7.0+, you can have the Settings app show a “gear” icon on your activity that collects preferences. When the user taps that gear, the Settings app will launch your designated activity: Figure 635: Settings Activity Gear Icon To offer this, you need to add an for your desired activity, with an of android.intent.action.APPLICATION_PREFERENCES: > However, by default, there is a cost to this: any app can start your settings activity, whenever another app wants to. Your settings activity is exported once you add the 1983 ADVANCED PREFERENCES , and it needs to be exported for the Settings app to be able to start the activity. However, it is fairly likely that this activity was not exported before you added this . And while you may not mind it if the Settings app starts this activity, or if your own application code starts this activity, you may not want arbitrary other apps to start this activity. A general rule of thumb in modern development is to keep your “attack surface” low. Having an activity be exported for little value is an unnecessary increase in your app’s attack surface. There is no officially-documented solution for this, though perhaps they will add one someday. There are two candidate approaches. An unexpected one works: you can mark the activity as being not exported, via android:exported="false". For some reason, the Settings app can still start up that activity, perhaps due to some system-level privilege. However, other apps will be unable to start the activity. This would result in an element like this: > Another approach that should work is to use android:permission to limit what other apps can start your activity, choosing a permission that the Settings app is sure to have but that most other apps will lack. WRITE_SECURE_SETTINGS is one candidate: > 1984 ADVANCED PREFERENCES Now, the only other apps that can start your activity must hold the WRITE_SECURE_SETTINGS permission, which ordinary Android SDK apps cannot hold. Custom Preference Storage SharedPreferences are stored in an app’s portion of internal storage as an XML file. This is fine in many cases. However, it is a problem for apps that need to ensure that persisted data is encrypted. While you can create a wrapper around SharedPreferences that encrypts the keys and values, that will not work well with things like the preference screen UI system. Basically, anything that does not know about the wrapper would try working with the actual SharedPreference data and be broken by the encryption. This has always been disappointing, considering that SharedPreferences is an interface, and so setting up some sort of decorator approach should have been fairly easy to add. In Android 8.0+, Google does not do that. However, they do add in another mechanism: PreferenceDataStore. You can create a PreferenceDataStore and associate it with a PreferenceManager via setPreferenceDataStore(). Then, all SharedPreferences loaded from that PreferenceManager will not use the normal XML-based persistence. Instead, the PreferenceDataStore will be used instead. That interface has getter and setter methods for all of the types supported by SharedPreferences, and it is the responsibility of some instance of PreferenceDataStore to handle the persistence as you see fit. This solution is goofy, but it works, after a fashion, as is illustrated in the Prefs/ DataStore sample project. In that project, we have a SillyDataStore implementation of the PreferenceDataStore interface. It just stuffs all the data into a HashMap: package com.commonsware.android.preffrag; import import import import android.preference.PreferenceDataStore android.preference.PreferenceDataStore; java.util.HashMap java.util.HashMap; java.util.Map java.util.Map; java.util.Set java.util.Set; 1985 ADVANCED PREFERENCES class SillyDataStore implements PreferenceDataStore { static private final SillyDataStore INSTANCE=new new SillyDataStore(); private Map cache=new new HashMap<>(); static SillyDataStore get() { return return(INSTANCE); } private SillyDataStore() { // just here to prevent accidental creation from outside } @Override public void putString(String key, String value) { cache.put(key, value); } @Override public void putStringSet(String key, Set values) { cache.put(key, values); } @Override public void putInt(String key, int value) { cache.put(key, value); } @Override public void putLong(String key, long value) { cache.put(key, value); } @Override public void putFloat(String key, float value) { cache.put(key, value); } @Override public void putBoolean(String key, boolean value) { cache.put(key, value); } @SuppressWarnings("Since15") @Override public String getString(String key, String defValue) { return return((String)cache.getOrDefault(key, defValue)); } 1986 ADVANCED PREFERENCES @SuppressWarnings("Since15") @Override public Set getStringSet(String key, Set defValues) { return return((Set)cache.getOrDefault(key, defValues)); } @SuppressWarnings("Since15") @Override public int getInt(String key, int defValue) { return return((Integer)cache.getOrDefault(key, defValue)); } @SuppressWarnings("Since15") @Override public long getLong(String key, long defValue) { return return((Long)cache.getOrDefault(key, defValue)); } @SuppressWarnings("Since15") @Override public float getFloat(String key, float defValue) { return return((Float)cache.getOrDefault(key, defValue)); } @SuppressWarnings("Since15") @Override public boolean getBoolean(String key, boolean defValue) { return return((Boolean)cache.getOrDefault(key, defValue)); } } (from Prefs/DataStore/app/src/main/java/com/commonsware/android/preffrag/SillyDataStore.java) This implementation is truly silly, as it does no type checking and no persistence. It should be considered the bare minimum implementation of a PreferenceDataStore, though one that might be useful, instead of rolling a mock, in unit testing. (note: the @SuppressWarnings("Since15") annotations are because this code uses the getOrDefault() method on HashMap, which was added in Java 8 and is new to Android 8.0) There is a singleton instance of SillyDataStore. That way we can ensure that the same instance is used wherever we want it. 1987 ADVANCED PREFERENCES We apply that singleton in the PreferenceFragment subclass: public static class Prefs extends PreferenceFragment { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); if (getPreferenceManager().getPreferenceDataStore()==null null) { getPreferenceManager().setPreferenceDataStore(SillyDataStore.get()); } addPreferencesFromResource(R.xml.preferences); } } (from Prefs/DataStore/app/src/main/java/com/commonsware/android/preffrag/EditPreferences.java) Here, we check to see if there is a PreferenceDataStore associated with the PreferenceManager and, if not, we attach the SillyDataStore singleton. This causes the SharedPreferences used by this PreferenceFragment to use the SillyDataStore for storage, instead of the default XML-based persistence. This works… somewhat. There are some problems. First, a PreferenceManager is not a system service. Of note, each instance of our PreferenceFragment gets its own fresh PreferenceManager. This is why we need to check for, and set, the PreferenceDataStore on the PreferenceManager for the PreferenceFragment each time. Second, we have no way of associating a PreferenceDataStore with the default SharedPreferences obtained from PreferenceManager.getDefaultSharedPreferences(). That will always use the standard XML backing store. The initial activity contents are in the form of a PreferenceContentsFragment that reads from the default SharedPreferences in onResume(). Normally, that would cause changes that we make via our PreferenceFragment to show up when the PreferenceContentsFragment is resumed. In this specific sample, that does not happen, as the PreferenceContentsFragment is using the default XML data store, and our data is really in the SillyDataStore. This illustrates the fatal flaw of this system: you can never really use the SharedPreferences. You cannot create PreferenceManager instances yourself, as it has no public constructors. All of the code that gives you SharedPreferences 1988 ADVANCED PREFERENCES objects back other than through a PreferenceManager has no way of associating a PreferenceDataStore with the SharedPreferences. Instead of using SharedPreferences… you have to read and write from your PreferenceDataStore itself. This, in turn, loses everything that you normally associate with SharedPreferences, such as atomicity of updates and preferencechange listeners. Worse, since PreferenceDataStore has no API telling you when to persist changes, you would have to do that yourself… somehow. These can be overcome, with a sufficiently-robust PreferenceDataStore implementation and lots of documentation. However, for casual use, other than perhaps for test mocks, PreferenceDataStore is not a well-engineered solution and probably should be avoided. 1989 Custom Dialogs and Preferences Android ships with a number of dialog classes for specific circumstances, like DatePickerDialog and ProgressDialog. Similarly, Android comes with a smattering of Preference classes for your PreferenceActivity, to accept text or selections from lists and so on. However, there is plenty of room for improvement in both areas. As such, you may find the need to create your own custom dialog or preference class. This chapter will show you how that is done. We start off by looking at creating a custom AlertDialog, not by using AlertDialog.Builder, but via a custom subclass. Then, we show how to create your own dialog-style Preference, where tapping on the preference pops up a dialog to allow the user to customize the preference value. Prerequisites Understanding this chapter requires that you have read the chapter on dialogs, along with the chapter on the preference system. Also, the samples here use the custom ColorMixer View described in another chapter. Your Dialog, Chocolate-Covered For your own application, the simplest way to create a custom AlertDialog is to use AlertDialog.Builder, as described in a previous chapter. You do not need to create any special subclass — just call methods on the Builder, then show() the resulting dialog. 1991 CUSTOM DIALOGS AND PREFERENCES However, if you want to create a reusable AlertDialog, this may become problematic. For example, where would this code to create the custom AlertDialog reside? So, in some cases, you may wish to extend AlertDialog and supply the dialog’s contents that way, which is how TimePickerDialog and others are implemented. Unfortunately, this technique is not well documented. This section will illustrate how to create such an AlertDialog subclass, as determined by looking at how the core Android team did it for their own dialogs. The sample code is ColorMixerDialog, a dialog wrapping around the ColorMixer widget shown in a previous chapter. The implementation of ColorMixerDialog can be found in the CWAC-ColorMixer GitHub repository, as it is part of the CommonsWare Android Components. Using this dialog works much like using DatePickerDialog or TimePickerDialog. You create an instance of ColorMixerDialog, supplying the initial color to show and a listener object to be notified of color changes. Then, call show() on the dialog. If the user makes a change and accepts the dialog, your listener will be informed. Figure 636: The ColorMixerDialog 1992 CUSTOM DIALOGS AND PREFERENCES Basic AlertDialog Setup The ColorMixerDialog class is not especially long, since all of the actual color mixing is handled by the ColorMixer widget: package com.commonsware.cwac.colormixer; import import import import android.app.AlertDialog android.app.AlertDialog; android.content.Context android.content.Context; android.content.DialogInterface android.content.DialogInterface; android.os.Bundle android.os.Bundle; public class ColorMixerDialog extends AlertDialog implements DialogInterface.OnClickListener { static private final String COLOR="c"; private ColorMixer mixer=null null; private int initialColor; private ColorMixer.OnColorChangedListener onSet=null null; public ColorMixerDialog(Context ctxt, int initialColor, ColorMixer.OnColorChangedListener onSet) { super super(ctxt); this this.initialColor=initialColor; this this.onSet=onSet; mixer=new new ColorMixer(ctxt); mixer.setColor(initialColor); setView(mixer); setButton(ctxt.getText(R.string.cwac_colormixer_set), this this); setButton2(ctxt.getText(R.string.cwac_colormixer_cancel), (DialogInterface.OnClickListener)null null); } @Override public void onClick(DialogInterface dialog, int which) { if (initialColor!=mixer.getColor()) { onSet.onColorChange(mixer.getColor()); } } @Override public Bundle onSaveInstanceState() { Bundle state=super super.onSaveInstanceState(); 1993 CUSTOM DIALOGS AND PREFERENCES state.putInt(COLOR, mixer.getColor()); return return(state); } @Override public void onRestoreInstanceState(Bundle state) { super super.onRestoreInstanceState(state); mixer.setColor(state.getInt(COLOR)); } } We extend the AlertDialog class and implement a constructor of our own design. In this case, we take in three parameters: 1. A Context (typically an Activity), needed for the superclass 2. The initial color to use for the dialog, such as if the user is editing a color they chose before 3. A ColorMixer.OnColorChangedListener object, just like ColorMixer uses, to notify the dialog creator when the color is changed We then create a ColorMixer and call setView() to make that be the main content of the dialog. We also call setButton() and setButton2() to specify a “Set” and “Cancel” button for the dialog. The latter just dismisses the dialog, so we need no event handler. The former we route back to the ColorMixerDialog itself, which implements the DialogInterface.OnClickListener interface. Handling Color Changes When the user clicks the “Set” button, we want to notify the application about the color change…if the color actually changed. This is akin to DatePickerDialog and TimePickerDialog only notifying you of date or times if the user clicks Set and actually changed the values. The ColorMixerDialog tracks the initial color via the initialColor data member. In the onClick() method — required by DialogInterface.OnClickListener — we see if the mixer has a different color than the initialColor, and if so, we call the supplied ColorMixer.OnColorChangedListener callback object: @Override public void onClick(DialogInterface dialog, int which) { 1994 CUSTOM DIALOGS AND PREFERENCES if (initialColor!=mixer.getColor()) { onSet.onColorChange(mixer.getColor()); } } State Management Dialogs use onSaveInstanceState() and onRestoreInstanceState(), just like activities do. That way, if the screen is rotated, or if the hosting activity is being evicted from RAM when it is not in the foreground, the dialog can save its state, then get it back later as needed. The biggest difference with onSaveInstanceState() for a dialog is that the Bundle of state data is not passed into the method. Rather, you get the Bundle by chaining to the superclass, then adding your data to the Bundle it returned, before returning it yourself: @Override public Bundle onSaveInstanceState() { Bundle state=super super.onSaveInstanceState(); state.putInt(COLOR, mixer.getColor()); return return(state); } The onRestoreInstanceState() pattern is much closer to the implementation you would find in an Activity, where the Bundle with the state data to restore is passed in as a parameter: @Override public void onRestoreInstanceState(Bundle state) { super super.onRestoreInstanceState(state); mixer.setColor(state.getInt(COLOR)); } Preferring Your Own Preferences, Preferably The Android Settings application, built using the Preference system, has lots of custom Preference classes. You too can create your own Preference classes, to collect things like dates, numbers, or colors. Once again, though, the process of creating such classes is not well documented. This section reviews one recipe for 1995 CUSTOM DIALOGS AND PREFERENCES making a Preference — specifically, a subclass of DialogPreference – based on the implementation of other Preference classes in Android. The result is ColorPreference, a Preference that uses the ColorMixer widget. As with the ColorMixerDialog from the previous section, the ColorPreference is from the CommonsWare Android Components, and its source code can be found in the CWAC-ColorMixer GitHub repository. One might think that ColorPreference, as a subclass of DialogPreference, might use ColorMixerDialog. However, that is not the way it works, as you will see. The Constructor A Preference is much like a custom View, in that there are a variety of constructors, some taking an AttributeSet (for the preference properties), and some taking a default style. In the case of ColorPreference, we need to get the string resources to use for the names of the buttons in the dialog box, providing them to DialogPreference via setPositiveButtonText() and setNegativeButtonText(). Here, we just implement the standard two-parameter constructor, since that is the one that is used when this preference is inflated from a preference XML file: public ColorPreference(Context ctxt, AttributeSet attrs) { super super(ctxt, attrs); setPositiveButtonText(ctxt.getText(R.string.cwac_colormixer_set)); setNegativeButtonText(ctxt.getText(R.string.cwac_colormixer_cancel)); } Creating the View The DialogPreference class handles the pop-up dialog that appears when the preference is clicked upon by the user. Subclasses get to provide the View that goes inside the dialog. This is handled a bit reminiscent of a CursorAdapter, in that there are two separate methods to be overridden: • onCreateDialogView() works like newView() of CursorAdapter, returning a View that should go in the dialog • onBindDialogView() works like bindView() of CursorAdapter, where the custom Preference is supposed to configure the View for the current preference value 1996 CUSTOM DIALOGS AND PREFERENCES In the case of ColorPreference, we use a ColorMixer for the View: @Override protected View onCreateDialogView() { mixer=new new ColorMixer(getContext()); return return(mixer); } Then, in onBindDialogView(), we set the mixer’s color to be lastColor, a private data member: @Override protected void onBindDialogView(View v) { super super.onBindDialogView(v); mixer.setColor(lastColor); } We will see later in this section where lastColor comes from – for the moment, take it on faith that it holds the user’s chosen color, or a default value. Dealing with Preference Values Of course, the whole point behind a Preference is to allow the user to set some value that the application will then use later on. Dealing with values is a bit tricky with DialogPreference, but not too bad. Getting the Default Value The preference XML format has an android:defaultValue attribute, which holds the default value to be used by the preference. Of course, the actual data type of the value will differ widely — an EditTextPreference might expect a String, while ColorPreference needs a color value. Hence, you need to implement onGetDefaultValue(). This is passed a TypedArray — similar to how a custom View uses a TypedArray for getting at its custom attributes in an XML layout file. It is also passed an index number into the array representing android:defaultValue. The custom Preference needs to return an Object representing its interpretation of the default value. 1997 CUSTOM DIALOGS AND PREFERENCES In the case of ColorPreference, we simply get an integer out of the TypedArray, representing the color value, with an overall default value of 0xFFA4C639 (a.k.a., Android green): @Override protected Object onGetDefaultValue(TypedArray a, int index) { return return(a.getInt(index, 0xFFA4C639)); } Setting the Initial Value When the user clicks on the preference, the DialogPreference supplies the lastknown preference value to its subclass, or the default value if this preference has not been set by the user to date. The way this works is that the custom Preference needs to override onSetInitialValue(). This is passed in a boolean flag (restoreValue) indicating whether or not the user set the value of the preference before. It is also passed the Object returned by onGetDefaultValue(). Typically, a custom Preference will look at the flag and choose to either use the default value or load the already-set preference value. To get the existing value, Preference defines a set of type-specific getter methods — getPersistedInt(), getPersistedString(), etc. So, ColorPreference uses getPersistedInt() to get the saved color value: @Override protected void onSetInitialValue(boolean restoreValue, Object defaultValue) { lastColor=(restoreValue ? getPersistedInt(lastColor) : (Integer)defaultValue); } Here, onSetInitialValue() stores that value in lastColor — which then winds up being used by onBindDialogView() to tell the ColorMixer what color to show. Closing the Dialog When the user closes the dialog, it is time to persist the chosen color from the ColorMixer. This is handled by the onDialogClosed() callback method on your custom Preference: @Override protected void onDialogClosed(boolean positiveResult) { super super.onDialogClosed(positiveResult); 1998 CUSTOM DIALOGS AND PREFERENCES if (positiveResult) { if (callChangeListener(mixer.getColor())) { lastColor=mixer.getColor(); persistInt(lastColor); } } } The passed-in boolean indicates if the user accepted or dismissed the dialog, so you can elect to skip saving anything if the user dismissed the dialog. The other DialogPreference implementations also call callChangeListener(), which is somewhat ill-documented. Assuming both the flag and callChangeListener() are true, the Preference should save its value to the persistent store via persistInt(), persistString(), or kin. Using the Preference Given all of that, using the custom Preference class in an application is almost anticlimactic. You simply add it to your preference XML, with a fully-qualified class name: > At this point, it behaves no differently than does any other Preference type. Since ColorPreference stores the value as an integer, your code would use getInt() on the SharedPreferences to retrieve the value when needed. The user sees an ordinary preference entry in the PreferenceActivity: 1999 CUSTOM DIALOGS AND PREFERENCES Figure 637: A PreferenceActivity, showing the ColorPreference When tapped, it brings up the mixer: 2000 CUSTOM DIALOGS AND PREFERENCES Figure 638: The ColorMixer in a custom DialogPreference Choosing a color and clicking “Set” persists the color value as a preference. 2001 Progress Indicators Sometimes, we make the user wait. And wait. And wait some more. Often, in these cases, it is useful to let the user know that something they requested is something that we are diligently working on. To do this, we can use some form of progress indicator. We saw basic use of a ProgressBar in the tutorials earlier in this book — now is the time to take a much closer look at ProgressBar and other means of displaying progress. Prerequisites Understanding this chapter requires that you have read the core chapters of this book. Having read the chapters on dialogs, custom drawables, and animators is also a good idea. Progress Bars The classic way to tell the user that we are doing something for them is to use a ProgressBar widget, much as we briefly displayed one in the EmPubLite sample app in the tutorials. However, a ProgressBar is much more than a simple spinning image. We can use it to display either indeterminate progress (“we will be done… sometime”) or specific progress (“we are 34% complete”). We can use it either as a circle or as a classic horizontal bar, the latter typically used for specific progress. And, for specific progress, we can actually show two tiers of progress, known as “primary” and “secondary” (e.g., primary for the progress in copying a directory’s worth of files, secondary for the progress on a specific file). 2003 PROGRESS INDICATORS In this section, we will take a look at these different ways of using ProgressBar. Circular vs. Horizontal As the name suggests, a ProgressBar denotes progress. As the name does not suggest, a ProgressBar is not a bar, by default — it is a circle. Hence, the following element from an XML layout resource: /> (from Progress/BarSampler/app/src/main/res/layout/activity_main.xml) gives us: Figure 639: Android 5.1 ProgressBar, Default Style 2004 PROGRESS INDICATORS Figure 640: Android 4.0 ProgressBar, Default Style However, referencing style="?android:attr/progressBarStyleHorizontal" in the element: /> (from Progress/BarSampler/app/src/main/res/layout/activity_main.xml) gives us a horizontal bar: Figure 641: Android 5.1 ProgressBar, Horizontal Style Figure 642: Android 4.0 ProgressBar, Horizontal Style Note that the look-and-feel of these widgets have changed over the years. On Android 1.x and 2.x, they will look like this: 2005 PROGRESS INDICATORS Figure 643: Android 2.3.3 ProgressBar, Both Styles Specific vs. Indeterminate Typically, you use the circular ProgressBar style for indeterminate progress, where the circle simply spins in place to let the user know that work is proceeding and the device (or activity) has not frozen. The horizontal ProgressBar style is used to illustrate specific amounts of progress, from 0 to a value you choose. However, while those patterns are typical, the choice of whether to use indeterminate or some specific amount of progress is independent of the style of the widget. The android:indeterminate attribute controls whether the ProgressBar will render an indeterminate look or a specific look. For the latter, calls to setMax() (or the android:max attribute) will set the upper end of the progress range (the default is 100), and setProgress() or incrementProgressBy() will set how much progress along that range is illustrated. Figure 644: Android 5.1 ProgressBar, Horizontal Style, Indeterminate and Specific Figure 645: Android 4.0 ProgressBar, Horizontal Style, Indeterminate and Specific Figure 646: Android 2.3.3 ProgressBar, Horizontal Style, Indeterminate and Specific 2006 PROGRESS INDICATORS Primary vs. Secondary For specific progress, you actually have two independent amounts of progress. setProgress(), incrementProgressBy(), and android:progress control the primary progress, while setSecondaryProgress(), incrementSecondaryProgressBy(), and android:secondaryProgress control the secondary progress. Here, “primary progress” refers to the progress along an entire piece of work (e.g., copying a folder’s worth of files), while “secondary progress” refers the progress along a discrete chunk of the overall work (e.g., copying an individual file). A ProgressBar will render these with different colors, though primary trumps secondary, and so the secondary progress will only be visible when its value exceeds that of the primary progress: Figure 647: Android 4.0 ProgressBar, Horizontal Style, Primary-Only and PrimaryPlus-Secondary Figure 648: Android 2.3.3 ProgressBar, Horizontal Style, Primary-Only and PrimaryPlus-Secondary ProgressBar and Threads Normally, you cannot update the UI of a widget from a background thread. ProgressBar is an exception. You can safely call setProgress() and incrementProgressBy() from a background thread to update the primary progress, and you can safely call setSecondaryProgress() and incrementSecondaryProgressBy() from a background thread to update the secondary progress. To see this in action, take a look at the Progress/BarSampler sample project. This project has a single activity (MainActivity), whose layout (activity_main.xml) contains four ProgressBar widgets, two indeterminate and two for specific progress: 2007 PROGRESS INDICATORS > /> /> /> /> (from Progress/BarSampler/app/src/main/res/layout/activity_main.xml) The activity gets access to the latter two ProgressBar widgets and sets up a ScheduledThreadPoolExecutor to get control every second in a background thread, which calls our run() method. The run() method will increment both ProgressBar widgets primary progress by 2 each time, and the secondary progress by 10 (dropping back to the starting point when the secondary progress reaches the 2008 PROGRESS INDICATORS maximum of 100). When the primary progress gets to 100, we cancel our scheduled work in the ScheduledThreadPoolExecutor: package com.commonsware.android.progress; import import import import import android.app.Activity android.app.Activity; android.os.Bundle android.os.Bundle; android.widget.ProgressBar android.widget.ProgressBar; java.util.concurrent.ScheduledThreadPoolExecutor java.util.concurrent.ScheduledThreadPoolExecutor; java.util.concurrent.TimeUnit java.util.concurrent.TimeUnit; public class MainActivity extends Activity implements Runnable { private static final int PERIOD_SECONDS=1; private ScheduledThreadPoolExecutor executor= new ScheduledThreadPoolExecutor(1); private ProgressBar primary=null null; private ProgressBar secondary=null null; @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); primary=(ProgressBar)findViewById(R.id.progressHS); secondary=(ProgressBar)findViewById(R.id.progressHS2); executor.setExecuteExistingDelayedTasksAfterShutdownPolicy(false false); executor.scheduleAtFixedRate(this this, 0, PERIOD_SECONDS, TimeUnit.SECONDS); } @Override public void onDestroy() { executor.shutdown(); super super.onDestroy(); } @Override public void run() { if (primary.getProgress() < 100) { primary.incrementProgressBy(2); secondary.incrementProgressBy(2); if (secondary.getSecondaryProgress() == 100) { secondary.setSecondaryProgress(10); } 2009 PROGRESS INDICATORS else { secondary.incrementSecondaryProgressBy(10); } } else { executor.remove(this this); } } } (from Progress/BarSampler/app/src/main/java/com/commonsware/android/progress/MainActivity.java) The net effect is that you see the progress march across the screen, with the secondary progress going through five passes for the primary progress’ single pass through the 0-100 range. Tailoring Progress Bars The stock ProgressBar look and feel is decent, if perhaps not spectacular. Often times, the stock look is sufficient for your needs. If you wish to have greater control over the look of your ProgressBar, the following sections will demonstrate some possibilities. Changing the Progress Colors The ProgressBar uses different colors for primary and secondary specific progress. By default, those colors are defined by the theme you are using, and the stock themes have firmware-defined colors (e.g., yellows for Android 1.x and 2.x, blues for Android 3.x and higher). However, you can change the colors by using a LayerListDrawable and associating it with a ProgressBar by means of the android:progressDrawable attribute. The ProgressBar background image needs to be a LayerListDrawable with three specific layers: • android:id="@android:id/background" for the background color of the bar • android:id="@android:id/progress" for the primary progress • android:id="@android:id/secondaryProgress" for the secondary progress 2010 PROGRESS INDICATORS Whether those layers are defined as ShapeDrawable structures, or as nine-patch PNG files is up to you, but they will need the ability to stretch to fit however big your bar winds up being. To see what this means, let’s take a look at the Progress/Styled sample project. This is a near-clone of the Progress/BarSampler project from earlier, using custom backgrounds for the bars. Here, we will look at the horizontal ProgressBar widgets — in the next section, we will look at how to change the background of a circular indefinite ProgressBar. For the first horizontal ProgressBar (progressHS), for Android 4.x, we will use a custom style created by the Android Holo Colors Generator, a Web site set up to help us create custom versions of the holographic widget theme. When you visit this site in Google Chrome (note: other browsers are not supported at this time), you can fill in a name for your theme (e.g., “AppTheme”), the color scheme to use for the theme, and the foundation theme to use (light or dark): Figure 649: Android Holo Colors Generator, Basic Info You can then toggle on and off which widgets you intend to use, so the generator will create custom styles for them: 2011 PROGRESS INDICATORS Figure 650: Android Holo Colors Generator, Widget Selection Then, the generator will create a ZIP file that you can download that contains the generated resources for your custom styles. The Progress/Styled project contains the files generated by the generator, replacing the original style resources. Note that the generator does not create a .DarkActionBar version of the style resource, so the values-v14 resource directory in the project has one hand-crafted based upon a regular generated style resource. On Android 5.0+, we will use a theme with the same name, but where we are using tints in the theme to affect the colors of the progress indicators. Our manifest points to our AppTheme as being how we wish to style widgets in this application: > /> > > /> /> (from Progress/Styled/app/src/main/AndroidManifest.xml) That theme, defined in apptheme_themes.xml, points to style resources for horizontal ProgressBar widgets: > (from Progress/Styled/app/src/main/res/values-v14/apptheme_themes.xml) The ProgressBarAppTheme style resource is defined in a separate apptheme_styles.xml resource: > 2013 PROGRESS INDICATORS (from Progress/Styled/app/src/main/res/values-v11/apptheme_styles.xml) Here, we say that we want the android:progressDrawable property to be a progress_horizontal_holo_light drawable resource. We also set the android:indeterminateDrawable property — used for indeterminate bars — to a progress_indeterminate_horizontal_holo_light drawable resource. Those are defined as XML-based drawables, in the res/drawable/ directory in the project. The progress_horizontal_holo_light resource is defined as: > > > (from Progress/Styled/app/src/main/res/drawable/progress_horizontal_holo_light.xml) 2014 PROGRESS INDICATORS The generator creates our LayerListDrawable resource with our three layers, each pointing to a nine-patch PNG file (with different versions for different densities) that contains our desired custom color. The progress and secondaryProgress layers use ScaleDrawable definitions to ensure that the images are measured against the complete width of the background layer, which in turn will be sized according to the size of the ProgressBar itself. We will take a look at the progress_indeterminate_horizontal_holo_light drawable resource in the next section. Note that you could skip the custom theme and style if you wished, and simply add the android:progressDrawable attribute to the ProgressBar widget definition in its layout XML resource. Regardless, the result is that our progress bars have the desired purple color scheme: Figure 651: Custom ProgressBar Style, Primary and Secondary Also, you can have your LayerListDrawable use ShapeDrawable layers, to avoid creating nine-patch PNG files, if you prefer, using a resource like this: > > > > On Android 5.0+, we have it much easier, as ProgressBar automatically adopts the accent tint. So we go with a much simpler theme definition: (from Progress/Styled/app/src/main/res/values-v21/styles.xml) This references colors from a separate colors.xml resource: >#3f51b5 >#1a237e >#ffee58 2016 PROGRESS INDICATORS (from Progress/Styled/app/src/main/res/values-v21/colors.xml) The result are yellow-tinted progress bars: Figure 652: Material ProgressBar Style, Primary and Secondary Changing the Indeterminate Animation Similarly, for indefinite progress “bars”, changing the progress drawable will let you change the way they look. However, in this case, the drawable also needs to implement the animation itself. You can accomplish this either by using an AnimationDrawable or by using some other type of drawable wrapped in an animation, such as a ShapeDrawable wrapped in a animation. For example, the Android 4.x custom theme created by the Android Holo Colors Generator assigns the following drawable resource to android:indeterminateDrawable in the theme: > /> /> /> PROGRESS INDICATORS android:duration="50" android:duration="50" android:duration="50" android:duration="50" /> /> /> /> (from Progress/Styled/app/src/main/res/drawable/progress_indeterminate_horizontal_holo_light.xml) Hence, every horizontal indeterminate ProgressBar will use that AnimationDrawable. The individual images in the animation are PNG files, with different versions for different densities. Circular ProgressBar widgets also need a custom progress drawable, though obviously the image will need to be circular, not a bar. You can certainly use an AnimationDrawable for this, or you can use a ShapeDrawable, such as the res/ drawable/progress_circular.xml resource shown below: > > /> (from Progress/Styled/app/src/main/res/drawable/progress_circular.xml) Here, we have a ring ShapeDrawable, with a certain thickness and radius, filled with a gradient. Half of the fill is actually a solid color (#4c737373), as the start and center colors are the same. The other half is a sweep gradient from the starting color to the same purple shade that is used by the other bar styles. This ring is then wrapped in a 2018 PROGRESS INDICATORS rotate animation. This yields a simple gradient-filled ring, that rotates smoothly to indicate progress: Figure 653: Custom ProgressBar Styles, Including Circular Indefinite Note that the Android Holo Colors Generator does not generate circular indefinite ProgressBar resources as of the time of this writing. Once again, Android 5.0+ can leverage Theme.Material and get rid of all the extra clutter. Just having an accent color defined will have your indefinite progress bars adopt that same color: 2019 PROGRESS INDICATORS Figure 654: Material ProgressBar Styles, Including Circular Indefinite Progress Dialogs One use of a ProgressBar is to have it wrapped in a ProgressDialog. Like all dialogs, ProgressDialog is modal, preventing the user from interacting with an underlying activity while the dialog is displayed. From a UI design standpoint, a ProgressDialog is an easy way to temporarily show progress without having to find a spot for a ProgressBar widget somewhere in the UI. Also, since usually there are things in the activity that are dependent upon the work being done in the background, having the dialog in place prevents anyone from trying to use things that are not yet ready. However, modal dialogs are not a great design approach, as they aggressively limit the user’s options. ProgressDialog is perhaps the worst in this regard, as the user can do nothing except wait. While part of your app may not yet be ready, other parts surely are, such as reading the documentation, or adjusting settings, or clicking on your ad banners. Hence, using anything else other than ProgressDialog, while perhaps a bit more work, will be an improvement in the usability of your app. 2020 PROGRESS INDICATORS That being said, let us see how to set up a ProgressDialog. The Progress/Dialog sample project is a near-clone of the Dialogs/DialogFragment sample project from the chapter on dialogs. The only difference is the onCreateDialog() method of our DialogFragment, where we directly create a ProgressDialog instead of using an AlertDialog.Builder to create an AlertDialog as before: @Override public Dialog onCreateDialog(Bundle savedInstanceState) { ProgressDialog dlg=new new ProgressDialog(getActivity()); dlg.setMessage(getActivity().getString(R.string.dlg_title)); dlg.setIndeterminate(true true); dlg.setProgressStyle(ProgressDialog.STYLE_SPINNER); return return(dlg); } (from Progress/Dialog/app/src/main/java/com/commonsware/android/progdlg/SampleDialogFragment.java) We create the ProgressDialog via its constructor, set the message explaining what we are waiting for via setMessage(), indicate that the ProgressBar should be an indeterminate one via setIndeterminate(), and indicate that we want a circular “spinner” ProgressBar rather than a horizontal one by calling setProgressStyle(ProgressDialog.STYLE_SPINNER). There are a variety of other things you could configure on the ProgressDialog if desired, and ProgressDialog inherits from AlertDialog, so some things you could configure on an AlertDialog will also be available on the ProgressDialog. The result is a dialog that you may have seen from other apps in Android: 2021 PROGRESS INDICATORS Figure 655: ProgressDialog Title Bar and Action Bar Progress Indicators Another place to let users know that you are doing something on their behalf is to put a progress indicator in the title bar or action bar of your activity. This avoids your having to put an indeterminate ProgressBar somewhere in your activity’s UI. It is also very simple to set up, as we can see in the Progress/TitleBar sample project. package com.commonsware.android.titleprog; import android.app.Activity android.app.Activity; import android.os.Bundle android.os.Bundle; import android.view.Window android.view.Window; public class MainActivity extends Activity { @Override public void onCreate(Bundle savedInstanceState) { getWindow().requestFeature(Window.FEATURE_INDETERMINATE_PROGRESS); super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); setProgressBarIndeterminateVisibility(true true); 2022 PROGRESS INDICATORS } } (from Progress/TitleBar/app/src/main/java/com/commonsware/android/titleprog/MainActivity.java) Up front, as the first thing that you do in your onCreate() call, you need to call: getWindow().requestFeature(Window.FEATURE_INDETERMINATE_PROGRESS); This tells Android to reserve space in your title bar or action bar for an indeterminate progress indicator, though the indicator does not appear at this point. Later on, when you want the indicator to actually appear, call setProgressBarIndeterminateVisibility(true) on your activity, and later call setProgressBarIndeterminateVisibility(false) to make the indicator go away. This particular application has android:targetSdkVersion set to 11 or higher, but it is not using an action bar backport. Hence, when you run it on an older Android environment, you get a classic title bar with the progress indicator on the right: Figure 656: Progress Indicator in Title Bar 2023 PROGRESS INDICATORS When you have an action bar, you get the same basic effect, albeit with a larger indicator to match the larger bar: Figure 657: Progress Indicator in Action Bar Note that this approach is not supported by Theme.Material or the appcompat-v7 action bar backport, which makes it far less commonly used today. Direct Progress Indication Sometimes, the best way to let the user know about updates is to simply update the data in place. Rather than have some separate indicator, let the core UI itself convey the work being done. We saw this in the chapter on threads, where we populated a ListView in “real time” as we loaded in data into its adapter. Other variations on this theme include: • Updating a page count TextView to show the number of downloaded pages, while the user is reading earlier pages, perhaps with some sort of style (e.g., italics) or color coding (e.g., red) to indicate data that is being loaded. 2024 PROGRESS INDICATORS • Simply disabling the buttons, action bar items, and other ways that the user could navigate to a point in your app where you need the data that is being loaded in the background. The key here is to make sure that users understand why those items are disabled, and sometimes that is not obvious. Hence, while this step may be necessary, it is often tied in with progress indicators in the title bar or action bar or other means of indicating to the user the reason they cannot perform certain operations. 2025 More Fun with Pagers In earlier chapters, we saw basic uses of ViewPager, along with ways to show multiple pages at a time on larger screens. However, there are other ways to apply ViewPager and integrate it into the rest of your application, some of which we will examine in this chapter. Prerequisites This chapter assumes that you have read the core chapters, particularly the one showing how to use ViewPager. Hosting ViewPager in a Fragment Classically, the primary restriction on ViewPager was that you could not both have ViewPager be in a fragment and have ViewPager host fragments as its pages. You could do one or the other, but not both simultaneously. As noted in a previous chapter, Android 4.2 supports nested fragments natively, and the latest Android Support package backport also supports nested fragments. With those, you can have ViewPager be in a fragment and host fragments as its pages. However, it requires a minor modification to the way we set up a PagerAdapter, as is illustrated in the ViewPager/Nested sample project. This is the same project as ViewPager/Indicator, with the twist that the pages are fragments and the ViewPager is inside a fragment. Our activity now implements the standard add-the-fragment-if-it-does-not-exist pattern that we have seen previously: 2027 MORE FUN WITH PAGERS package com.commonsware.android.pagernested; import android.os.Bundle android.os.Bundle; import android.support.v4.app.FragmentActivity android.support.v4.app.FragmentActivity; public class ViewPagerIndicatorActivity extends FragmentActivity { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); if (getSupportFragmentManager().findFragmentById(android.R.id.content) == null null) { getSupportFragmentManager().beginTransaction() .add(android.R.id.content, new PagerFragment()).commit(); } } } (from ViewPager/Nested/app/src/main/java/com/commonsware/android/pagernested/ViewPagerIndicatorActivity.java) This loads a PagerFragment, which contains most of the logic from our original activity: package com.commonsware.android.pagernested; import import import import import import import android.os.Bundle android.os.Bundle; android.support.v4.app.Fragment android.support.v4.app.Fragment; android.support.v4.view.PagerAdapter android.support.v4.view.PagerAdapter; android.support.v4.view.ViewPager android.support.v4.view.ViewPager; android.view.LayoutInflater android.view.LayoutInflater; android.view.View android.view.View; android.view.ViewGroup android.view.ViewGroup; public class PagerFragment extends Fragment { @Override public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) { View result=inflater.inflate(R.layout.pager, container, false false); ViewPager pager=(ViewPager)result.findViewById(R.id.pager); pager.setAdapter(buildAdapter()); return return(result); } private PagerAdapter buildAdapter() { return return(new new SampleAdapter(getActivity(), getChildFragmentManager())); } } 2028 MORE FUN WITH PAGERS (from ViewPager/Nested/app/src/main/java/com/commonsware/android/pagernested/PagerFragment.java) The biggest difference is that our call to the constructor of SampleAdapter no longer uses getSupportFragmentManager(). Instead, it uses getChildFragmentManager(). This allows SampleAdapter to use fragments hosted by PagerFragment, rather than ones hosted by the activity as a whole. No other code changes are required, and from the user’s standpoint, there is no visible difference. Pages and the Action Bar Fragments that are pages inside a ViewPager can participate in the action bar, supplying items to appear as toolbar buttons, in the overflow menu, etc. This is not significantly different than how any fragment participates in the action bar: • Call setHasOptionsMenu() early in the fragment lifecycle (e.g., onCreateView()) to state that the fragment wishes to contribute to the action bar contents • Override onCreateOptionsMenu() and onOptionsItemSelected(), much as you would with an activity ViewPager and FragmentManager will manage the contents of the action bar, based upon the currently-visible page. That page’s contributions will appear in the action bar, then will be removed when the user switches to some other page. To see this in action, take a look at the ViewPager/ActionBar sample project. This is the same as the ViewPager/Indicator project from before, except: • In onCreateView(), for even-numbered page positions (0, 2, etc.), we call setHasOptionsMenu(true): @Override public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) { View result=inflater.inflate(R.layout.editor, container, false false); EditText editor=(EditText)result.findViewById(R.id.editor); position=getArguments().getInt(KEY_POSITION, -1); editor.setHint(getTitle(getActivity(), position)); 2029 MORE FUN WITH PAGERS if ((position % 2)==0) { setHasOptionsMenu(true true); } return return(result); } (from ViewPager/ActionBar/app/src/main/java/com/commonsware/android/pagerbar/EditorFragment.java) • In onCreateOptionsMenu(), we inflate a res/menu/actions.xml menu resource: @Override public void onCreateOptionsMenu(Menu menu, MenuInflater inflater) { inflater.inflate(R.menu.actions, menu); super super.onCreateOptionsMenu(menu, inflater); } (from ViewPager/ActionBar/app/src/main/java/com/commonsware/android/pagerbar/EditorFragment.java) Normally, we would also implement onOptionsItemSelected(), to find out when the action bar item was tapped, though this is skipped in this sample. The result is that when we have an even-numbered page position — equating to an odd-numbered title and hint — we have items in the action bar: 2030 MORE FUN WITH PAGERS Figure 658: A ViewPager, PagerTabStrip, and Action Bar Item on Android 4.1 …but as soon as we swipe to an odd-numbered page position — equating to an evennumbered title and hint — our action bar item is removed, as that fragment did not call setHasOptionsMenu(true): Figure 659: A ViewPager and PagerTabStrip, Sans Action Bar Item on Android 4.1 2031 MORE FUN WITH PAGERS ViewPagers and Scrollable Contents There are other things in Android that can be scrolled horizontally, besides a ViewPager: • • • • • HorizontalScrollView WebView, for content that is wider the deprecated Gallery widget than the width of the screen maps from many mapping engines, such as Google Maps various third-party widgets The challenge then comes in terms of dealing with horizontal swipe events. The ideal situation is for you to be able to swipe horizontally on the material inside the page, until you hit some edge (e.g., end of the HorizontalScrollView), then have swipe events move you to the adjacent page. You can assist ViewPager in handling this scenario by subclassing it and overriding the canScroll() method. This will be called on a horizontal swipe, and it is up to you to indicate if the contents can be scrolled (returning true) or not (returning false). If the built-in logic is insufficient, tailoring canScroll() to your particular needs can help. We will see an example of this later in the book, when we put some maps into a ViewPager. Columns for Large, Pages for Small In some cases, you can take better advantage of larger screens by using ViewPager more judiciously. In a previous chapter, we explored having ViewPager itself display more than one page at a time. A variation on that same theme is to only use a ViewPager on screen sizes where you lack sufficient room for everything, and to put those same pages on the screen at the same time when you have room for all of them. For example, a Twitter client for Android could use the columns-or-pages support for displaying various streams of tweets: your timeline, your @ mentions, hashtags you follow, etc. Each stream is represented by a typical ListView, with one row per tweet. On a phone, since screen space is at a premium, those ListView widgets are set up in a ViewPager, with one list per page. Users can swipe between the lists, or use tabs to navigate the available lists. However, tablets offer more room, so the app 2032 MORE FUN WITH PAGERS could show three ListView widgets side-by-side in landscape mode, so you can take in three sets of content without further interaction with the screen. The ViewPager/Columns1 sample project will demonstrate how you can accomplish the same basic approach in your own app… with some limitations. The Layouts Our main activity layout — cunningly named main — has a ViewPager-based definition in res/layout/main.xml: > /> (from ViewPager/Columns1/app/src/main/res/layout/main.xml) However, in res/layout-large/, for 5-inch devices on up, we have a horizontal LinearLayout with three FrameLayout containers, each representing an equal-sized slot for one of our “pages”: > /> /> /> (from ViewPager/Columns1/app/src/main/res/layout-large/main.xml) Android will automatically inflate the proper layout when we call setContentView(R.layout.main). The Activity However, while Android handles the inflation for us, we obviously need to populate the contents a bit differently. In this sample, though, we are relying upon the fact that screen size will not change on the fly. Hence, an instance of our application will either show a ViewPager or show the horizontal LinearLayout, and not have to switch between those at runtime. Our SampleAdapter, therefore, can remain unchanged, except for reducing the page count to 3: package com.commonsware.android.pagercolumns; import import import import android.app.Fragment android.app.Fragment; android.app.FragmentManager android.app.FragmentManager; android.content.Context android.content.Context; android.support.v13.app.FragmentPagerAdapter android.support.v13.app.FragmentPagerAdapter; public class SampleAdapter extends FragmentPagerAdapter { Context ctxt=null null; public SampleAdapter(Context ctxt, FragmentManager mgr) { super super(mgr); this this.ctxt=ctxt; } @Override public int getCount() { return return(3); 2034 MORE FUN WITH PAGERS } @Override public Fragment getItem(int position) { return return(EditorFragment.newInstance(position)); } @Override public String getPageTitle(int position) { return return(EditorFragment.getTitle(ctxt, position)); } } (from ViewPager/Columns1/app/src/main/java/com/commonsware/android/pagercolumns/SampleAdapter.java) Our MainActivity will still use the SampleAdapter, and if we have a ViewPager, it will use it the same way as before. However, if we do not have a ViewPager, we must be showing three panes of content side by side, in which case we just execute a FragmentTransaction to populate the three FrameLayout containers with the three items created by the SampleAdapter: package com.commonsware.android.pagercolumns; import import import import android.app.Activity android.app.Activity; android.os.Bundle android.os.Bundle; android.support.v13.app.FragmentPagerAdapter android.support.v13.app.FragmentPagerAdapter; android.support.v4.view.ViewPager android.support.v4.view.ViewPager; public class MainActivity extends Activity { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.main); ViewPager pager=(ViewPager)findViewById(R.id.pager); if (pager==null null) { if (getFragmentManager().findFragmentById(R.id.editor1)==null null) { FragmentPagerAdapter adapter=buildAdapter(); getFragmentManager().beginTransaction() .add(R.id.editor1, adapter.getItem(0)) .add(R.id.editor2, adapter.getItem(1)) .add(R.id.editor3, adapter.getItem(2)).commit(); 2035 MORE FUN WITH PAGERS } } else { pager.setAdapter(buildAdapter()); } } private FragmentPagerAdapter buildAdapter() { return return(new new SampleAdapter(this this, getFragmentManager())); } } (from ViewPager/Columns1/app/src/main/java/com/commonsware/android/pagercolumns/MainActivity.java) Of course, we skip the FragmentTransaction if the fragments already exist, such as due to a screen rotation configuration change. The Results On a phone, the ViewPager-based layout looks pretty much as it did before: Figure 660: A ViewPager. Again. However, on a tablet, we get our three editors side-by-side: 2036 MORE FUN WITH PAGERS Figure 661: Same App, Large-Screen Layout with Side-By-Side Editors The Limitations The simplified large-screen layout does not contain any indicators above the three editors. This could be added by simple changes to the res/layout-large/main.xml layout resource, if desired. The bigger limitation is that this only works if you want the same look in all configurations except screen size, and if the screen size never changes. However, it is eminently possible that you will want to have a different mix than that, such as using the three-column approach only on large-screen landscape layouts, using ViewPager everywhere else. In that case, our approach breaks down, as we will have different fragments inside the pager and outside the pager, meaning that we will lose our data on a configuration change. Addressing this issue is covered in the next two sections. 2037 MORE FUN WITH PAGERS Introducing ArrayPagerAdapter The flexibility of ViewPager is governed, to a large extent, by the implementation of its PagerAdapter. Inflexible PagerAdapter implementations lead to inflexible uses of ViewPager. Notably, the two concrete PagerAdapter implementations shipped in the Android Support package — FragmentPagerAdapter and FragmentStatePagerAdapter — have their limitations when it comes to things like: • Using fragments created by those adapters in other fashions, such as in the columns-or-pager scenario from the previous section • Handling dynamically-changing contents, such as adding pages, removing pages, or reordering pages The ArrayPagerAdapter is an attempt to provide a more flexible PagerAdapter implementation that still feels a lot like FragmentPagerAdapter in terms of its use of fragments. It also bears some resemblance to the ArrayAdapter used for AdapterView implementations like ListView, giving rise to its name. ArrayPagerAdapter is part of the CWAC-Pager project and is available for use in any Android project compatible with the Apache License 2.0. We will review the implementation of ArrayPagerAdapter later in this chapter. This section reviews how you can use ArrayPagerAdapter in your projects. Adding the Dependency Android Studio users can use the repositories and dependencies closures outlined on the CWAC-Pager project home page: repositories { maven { url "https://s3.amazonaws.com/repo.commonsware.com" } } dependencies { implementation 'com.commonsware.cwac:pager:0.2.+' } 2038 MORE FUN WITH PAGERS Choosing the Package There are two implementations of ArrayPagerAdapter. One, in the com.commonsware.cwac.pager package, is designed for use with native API Level 11 fragments. The other, in the com.commonsware.cwac.pager.v4 package, is designed for use with the Android Support package’s backport of fragments. You will need to choose the right ArrayPagerAdapter for the type of fragments that you are using. However, other than choosing suitable versions of classes for Fragment, etc., there is no real public API difference between the two. Hence, the documentation that follows is suitable for either implementation of ArrayPagerAdapter, so long as you use the one that matches the source of your fragment implementation. Note that only ArrayPagerAdapter lives in the com.commonsware.cwac.pager.v4 package. The classes and interfaces that support ArrayPagerAdapter, like PageDescriptor, are implemented in com.commonsware.cwac.pager and used by both implementations of ArrayPagerAdapter. Creating PageDescriptors You might think that ArrayPagerAdapter would take an array of pages, much like ArrayAdapter takes an array of models. That’s not how it works. Instead, ArrayPagerAdapter wants an ArrayList of PageDescriptor objects. PageDescriptor is an interface, requiring you to supply implementations of two methods: • getTitle(), which will be the title used for this page, for things like PagerTabStrip and the ViewPagerIndicator family of indicators • getFragmentTag(), which is a unique tag for this page’s fragment Also, PageDescriptor extends the Parcelable interface, and so any implementation of PageDescriptor must also implement the methods and CREATOR required by Parcelable. You are welcome to create your own PageDescriptor if you wish. However, there is a built-in implementation, SimplePageDescriptor, which probably meets your needs. You just pass the tag and title into the SimplePageDescriptor constructor, and it handles everything else, including the Parcelable implementation. 2039 MORE FUN WITH PAGERS Creating and Populating the Adapter To work with ArrayPagerAdapter, you start by creating an ArrayList of PageDescriptor objects, one for each page that is to be in your pager. Then, create a subclass of ArrayPagerAdapter. ArrayPagerAdapter uses Java generics, requiring you to declare the type of fragment the adapter is serving up to the ViewPager. So, for example, if you have a ViewPager that will have each page be an EditorFragment, you would declare your custom ArrayPagerAdapter to be: static class SamplePagerAdapter extends ArrayPagerAdapter If you will have pages come from a variety of fragments, just use the Fragment base class appropriate for your fragment source (e.g., android.app.Fragment). Your custom ArrayPagerAdapter subclass will need to override (at minimum) one method: createFragment(). This method is responsible for instantiating fragments, as requested. You are passed the PageDescriptor for the fragment to be created — you simply create and return that fragment. Hence, a custom ArrayPagerAdapter can be as simple as: static class SamplePagerAdapter extends ArrayPagerAdapter { public SamplePagerAdapter(FragmentManager fragmentManager, ArrayList descriptors) { super super(fragmentManager, descriptors); } @Override protected EditorFragment createFragment(PageDescriptor desc) { return return(EditorFragment.newInstance(desc.getTitle())); } Then, you can create an instance of your custom ArrayPagerAdapter subclass as needed, supplying the constructor with a suitable FragmentManager and your ArrayList of PageDescriptor objects. Once attached to a ViewPager, ArrayPagerAdapter behaves much like a FragmentPagerAdapter by default. There is another flavor of the ArrayPagerAdapter constructor, one that takes a RetentionStrategy as a parameter, as is described later in this chapter. 2040 MORE FUN WITH PAGERS Modifying the Contents ArrayPagerAdapter the ViewPager: offers several methods to allow you to change the contents of • add() takes a PageDescriptor and adds a new page at the end of the current roster of pages • insert() takes a PageDescriptor and an insertion point and inserts a new page before the current page at that insertion point • remove() takes a position and removes the page at that position • move() takes an old and new position and moves the page from the old position to the new position (effectively combining a remove() from the old position and an insert() of the same page into the new position Other Useful Methods getExistingFragment(), given a position, returns the existing fragment for that position in the ViewPager, if that fragment exists. Otherwise, it returns null. getCurrentFragment() is like getExistingFragment(), but returns the fragment for the currently-viewed page in the ViewPager. Columns for Large Landscape, Pages for the Rest Earlier in this chapter, we saw how you could conditionally use a ViewPager in some circumstances, but not others, such as using a ViewPager on smaller screens and a set of columns for the “pages” on larger screens. The limitation noted at that time was that you were stuck with one pattern for the lifetime of the activity, meaning that in any configuration change, you had to stick with the ViewPager or the columns that you started with. However, while the columnar approach for larger screens works well in landscape, you may find the columns to be too tall and too skinny in portrait. Hence, a better solution would be to use columns only on larger screens in landscape, and to use the ViewPager everywhere else. This is annoyingly tricky to do, assuming that you want to use the same fragments in each case, so you can arrange to hold onto the contents of their widgets. 2041 MORE FUN WITH PAGERS Jake Wharton — author of ViewPagerIndicator and a seemingly infinite number of other Android open source libraries — raised this issue in a Google+ post. He also posted a sample solution, but one that was limited to only two fragments. Quoting Mr. Wharton: Due the shenanigans performed by FragmentPagerAdapter we’re forced to write a custom PagerAdapter which handles the instances our selves. However, while two pages is reasonable, having some flexibility for a few more pages would be useful. So, let’s see how we can accomplish the same aims, using ArrayPagerAdapter, in the ViewPager/FlexColumns sample project. Fragments Inside and Outside the ViewPager A fragment cannot be in two containers at once. The ViewPager, where we have one, is a different container than one of our columns, when we have one. Hence, if the container is not changing during the operation of our activity — such as using a ViewPager in both portrait and landscape on smaller screens — we have no problem. But, if the container is changing — such as switching between columns and a ViewPager on larger screens — we need to take steps. One option for those “steps”, of course, is to simply run a separate set of fragments. One set serves as pages of the ViewPager; the other serves as the columns. However, then we have to do work to synchronize those on configuration changes, as from the user’s perspective, the fact that we happen to render things in pages or columns should not cause the user to lose data they entered in one form when switching to the other. If we want to use the same fragment instances, then we can use normal configuration-change logic, like onSaveInstanceState(), to ensure that we hold onto user-entered data during the change. However, we have to arrange to move the fragment from one container to another. This will involve running a FragmentTransaction to remove() the fragment from the old container and add() it to its new container. Making this more complicated is that the PagerAdapter should be handling the add() part, when the fragment is being put into a page, as that is how fragmentbased PagerAdapter implementations like FragmentPagerAdapter work. 2042 MORE FUN WITH PAGERS Adding to the fun is a matter of timing. By default, a FragmentTransaction is committed asynchronously. Attempting to remove() a fragment and add() the same fragment in the same transaction will fail, because the add() will complain that the fragment is already in another container, because the remove() will not have happened. Even doing the remove() and add() in separate normal transactions will not help. Instead, we need to ensure that the remove() has completed processing first, before we try to add(). To help with this, FragmentManager has a executePendingTransactions() method we can call, to have it complete its own processing on committed FragmentTransactions synchronously. Committing the remove() transaction and calling executePendingTransactions() before committing the add() transaction works. The Revised PagerAdapter With all that in mind, let’s look at how this revised sample behaves. The core functionality is the same as with the earlier pager-or-columns sample, but now we will only use the columns on -large screen devices in -land orientation, by simply renaming res/layout-large/ to res/layout-large-land/. Our PagerAdapter is still called SamplePagerAdapter, but this time it is a ArrayPagerAdapter for our EditorFragment pages: static class SamplePagerAdapter extends ArrayPagerAdapter { public SamplePagerAdapter(FragmentManager fragmentManager, ArrayList descriptors) { super super(fragmentManager, descriptors); } @Override protected EditorFragment createFragment(PageDescriptor desc) { return return(createFragment(desc.getTitle())); } EditorFragment createFragment(String title) { return return(EditorFragment.newInstance(title)); } } (from ViewPager/FlexColumns/app/src/main/java/com/commonsware/android/pagercolumns/MainActivity.java) 2043 MORE FUN WITH PAGERS The Revised Activity The onCreate() method of the earlier example would see if we had a ViewPager, then either populate the columns or populate the ViewPager from our PagerAdapter. The onCreate() method of the new example does the same basic thing, except that it delegates most of the work for actually filling in the columns to a private populateColumn() method: @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.main); ViewPager pager=(ViewPager)findViewById(R.id.pager); if (pager == null null) { if (getFragmentManager().findFragmentById(R.id.editor1) == null null) { SamplePagerAdapter adapter=buildAdapter(); FragmentTransaction ft= getFragmentManager().beginTransaction(); populateColumn(getFragmentManager(), ft, adapter, 0, R.id.editor1); populateColumn(getFragmentManager(), ft, adapter, 1, R.id.editor2); populateColumn(getFragmentManager(), ft, adapter, 2, R.id.editor3); ft.commit(); } } else { SamplePagerAdapter adapter=buildAdapter(); pager.setAdapter(adapter); } } (from ViewPager/FlexColumns/app/src/main/java/com/commonsware/android/pagercolumns/MainActivity.java) The buildAdapter() method changes a bit, to create our ArrayPagerAdapter subclass using an array of SimplePageDescriptor objects: private SamplePagerAdapter buildAdapter() { ArrayList pages=new new ArrayList(); for (int i=0; i < 3; i++) { 2044 MORE FUN WITH PAGERS pages.add(new new SimplePageDescriptor(buildTag(i), buildTitle(i))); } return return(new new SamplePagerAdapter(getFragmentManager(), pages)); } (from ViewPager/FlexColumns/app/src/main/java/com/commonsware/android/pagercolumns/MainActivity.java) buildAdapter(), in turn, uses buildTag() and buildTitle() methods to retrieve the tag and title to use given a position: private String buildTag(int position) { return return("editor" + String.valueOf(position)); } private String buildTitle(int position) { return return(String.format(getString(R.string.hint), position + 1)); } (from ViewPager/FlexColumns/app/src/main/java/com/commonsware/android/pagercolumns/MainActivity.java) Finally, our populateColumn() method handles the work to fill in one of our columns, if we are in column mode: private void populateColumn(FragmentManager fm, FragmentTransaction ft, SamplePagerAdapter adapter, int position, int slot) { EditorFragment f=adapter.getExistingFragment(position); if (f == null null) { f=adapter.createFragment(buildTitle(position)); } else { fm.beginTransaction().remove(f).commit(); fm.executePendingTransactions(); } ft.add(slot, f, buildTag(position)); } (from ViewPager/FlexColumns/app/src/main/java/com/commonsware/android/pagercolumns/MainActivity.java) First, we ask our ArrayPagerAdapter to retrieve for us the existing fragment, if any, for this given column/page, based on its position. This may return null, if this is the first time we have run our app, in which case we ask our ArrayPagerAdapter to 2045 MORE FUN WITH PAGERS create the fragment for us (using the same logic that it would when functioning inside of a ViewPager, via createFragment()). Otherwise, getExistingFragment() should return an existing EditorFragment instance, one probably formerly managed by a ViewPager. So, we create, commit, and execute a FragmentTransaction to remove() this fragment from its existing container. The net is that, in either case, we have an EditorFragment, set up for use in this column, that does not have a current container. To add it to our column, we simply call add() on the supplied FragmentTransaction, which is committed by our activity’s onCreate() method. However, we use the three-parameter form of add(), which allows us not only to put the fragment into a container, but to assign it a tag as well. The tag is how ArrayPagerAdapter identifies the various fragments — by using the same tag, this fragment can be picked up by future instances of ArrayPagerAdapter in case of a configuration change. You will notice that while we remove() the EditorFragment from the ViewPager and add() it to the column, we are not handling the reverse case, where we would remove() the fragment from the column and/or add() it to the ViewPager. That little bit of logic is supplied to us by ArrayPagerAdapter, as we will see when we examine the implementation of ArrayPagerAdapter later in this chapter. The resulting activity works exactly the same as the previous one, except that we use the ViewPager in portrait mode on larger-screen devices. Rotating a large-screen device will show our fragments moving between pages and columns, with their contents (whatever you type into the EditorFragment instances) being maintained via the built-in onSaveInstanceState() support for EditText widgets. Adding, Removing, and Moving Pages ArrayPagerAdapter also supports modifying the roster of pages at runtime: adding, inserting, removing, and moving pages. For example, a Twitter client might: • Allow users to add pages for new monitored hashtags or search results • Allow users to reorder the pages, putting more frequently-used ones towards the “front”, for easier access when the app starts from scratch • Allow users to remove pages they do not use, such as ones they added earlier 2046 MORE FUN WITH PAGERS To see how this works in practice, we can examine the demo project for the CWACPager library. There are two versions of this demo, one for the “v4” fragments from the Android Support package, and one for native API Level 11 fragments. Here, we will take a look at the latter project. Reviewing the Core Functionality This project is yet another rendition of our bunch-of-EditorFragment-pages sample that we have been examining for various ways of using ViewPager. This one sets up 10 pages at the start. However, it also inflates a menu resource to add four actions to the action bar: add, split, remove, and swap: Figure 662: ArrayPagerAdapter Demo App, Showing First 3 Pages and Action Bar onOptionsItemSelected() in our activity routes those four methods: add() (for add and split), remove(), and swap(). action items to three Add and Split Tapping the “add” action bar item will add a new page before the current one, with a title and hint based upon the number of existing pages (e.g., tapping “add” with 10 pages will add “Editor #11”): 2047 MORE FUN WITH PAGERS Figure 663: ArrayPagerAdapter Demo App, Showing Result of “Add” From Second Page Tapping the “split” action bar item will add a new page after the currently-selected one. Since both of these involve adding pages, this sample consolidates their work into a single add() method, taking a boolean parameter to indicate if we are inserting a page before the current one or after: private void add(boolean before) { int current=pager.getCurrentItem(); SimplePageDescriptor desc= new SimplePageDescriptor(buildTag(adapter.getCount()), buildTitle(adapter.getCount())); if (before) { adapter.insert(desc, current); } else { if (current < adapter.getCount() - 1) { adapter.insert(desc, current + 1); } else { 2048 MORE FUN WITH PAGERS adapter.add(desc); } } } We call getCurrentItem() on the ViewPager to determine what the position index is of the currently-selected page. From there, we set up our SimplePageDescriptor for the page that we will be adding, giving it a title based upon our hint string resource and a tag based upon the number of pages. We then call add() (if we are on the last page and the user clicked on “split”) or insert() (for all other scenarios) to inject the new page. The ArrayPagerAdapter will be responsible for creating this page, just as it did for all previous pages. Remove Tapping “remove” will remove the currently-selected page, so long as we will still have at least one page remaining (just to keep the example simpler, so we do not have to worry about not having a “current page”). This is handled by the remove() method on our activity, which turns around and calls remove() on the ArrayPagerAdapter: private void remove() { if (adapter.getCount() > 1) { adapter.remove(pager.getCurrentItem()); } } Swap Tapping “swap” will swap the positions of the current page and the one immediately after it. The exception is if you are on the last page, in which case we will swap the current page with the one immediately before it: private void swap() { int current=pager.getCurrentItem(); if (current < adapter.getCount() - 1) { adapter.move(current, current + 1); } else { adapter.move(current, current - 1); 2049 MORE FUN WITH PAGERS } } This is handled by the swap() method on our activity, which calls move() on the ArrayPagerAdapter. move() takes the position of the page to be moved and the position it should wind up in after the move, so we call move(current, current + 1) to swap the current page with the one after it or move(current, current - 1) to swap the current page with the one before it. Inside ArrayPagerAdapter ArrayPagerAdapter is a relatively large implementation of the PagerAdapter interface, and it helps to demonstrate some of the challenges faced when trying to create alternative fragment-based PagerAdapter implementations. Hence, this section will dive into portions of the innards of ArrayPagerAdapter, to explain how (and, sometimes, why) it does what it does. Note that ArrayPagerAdapter will continue to expand over time, and so the copy in the master branch of the GitHub repo may be newer than the one profiled in this chapter. This chapter covers v0.2.2. Also note that some of the code in ArrayPagerAdapter comes from FragmentPagerAdapter — as little of this code was altered as was practical, to help make it easier to integrate changes made to FragmentPagerAdapter over time. Also, to simplify the discussion, this section will demonstrate the ArrayPagerAdapter set up for native API Level 11 fragments, in the com.commonsware.cwac.pager package. PageDescriptor and PageEntry ArrayPagerAdapter PageEntry. works with two representations of pages: PageDescriptor and PageDescriptor is a simple interface, supplying the unique tag (getFragmentTag()) and indicator title (getTitle()) to use for a page: package com.commonsware.cwac.pager; import android.os.Parcelable android.os.Parcelable; 2050 MORE FUN WITH PAGERS public interface PageDescriptor extends Parcelable { String getFragmentTag(); String getTitle(); } Developers can use SimplePageDescriptor as an implementation of PageDescriptor in most cases. SimplePageDescriptor just holds onto those two strings, plus handles the implementation of the Parcelable interface: package com.commonsware.cwac.pager; import android.os.Parcel android.os.Parcel; import android.os.Parcelable android.os.Parcelable; public class SimplePageDescriptor implements PageDescriptor { private String tag=null null; private String title=null null; public static final Parcelable.Creator CREATOR= new Parcelable.Creator() { public SimplePageDescriptor createFromParcel(Parcel in) { return new SimplePageDescriptor(in); } public SimplePageDescriptor[] newArray(int size) { return new SimplePageDescriptor[size]; } }; public SimplePageDescriptor(String tag, String title) { this this.tag=tag; this this.title=title; } private SimplePageDescriptor(Parcel in) { tag=in.readString(); title=in.readString(); } @Override public int describeContents() { return return(0); } @Override public void writeToParcel(Parcel out, int flags) { 2051 MORE FUN WITH PAGERS out.writeString(tag); out.writeString(title); } public String getTitle() { return return(title); } public void setTitle(String title) { this this.title=title; } public String getFragmentTag() { return return(tag); } } However, the actual data model held by ArrayPagerAdapter is not the PageDescriptor, but rather a PageEntry, that holds onto its corresponding PageDescriptor plus a Fragment.SavedState object: } }; // // // // // // // // // // // // public static final RetentionStrategy REMOVE=new RetentionStrategy() { public void attach(Fragment fragment, FragmentTransaction currTransaction) { currTransaction.attach(fragment); } public void detach(Fragment fragment, FragmentTransaction currTransaction) { currTransaction.detach(fragment); } }; private static class PageEntry implements Parcelable { private PageDescriptor descriptor=null null; private Fragment.SavedState state=null null; public static final Parcelable.Creator CREATOR= new Parcelable.Creator() { public PageEntry createFromParcel(Parcel in) { return new PageEntry(in); } 2052 MORE FUN WITH PAGERS public PageEntry[] newArray(int size) { return new PageEntry[size]; } }; PageEntry(PageDescriptor descriptor) { this this.descriptor=descriptor; } PageEntry(Parcel in) { this this.descriptor=in.readParcelable(getClass().getClassLoader()); this this.state=in.readParcelable(getClass().getClassLoader()); } Fragment.SavedState is a Parceble object we can request from a Fragment at any point, representing the saved state of that fragment, as obtained via onSaveInstanceState() and related code. At present, that Fragment.SavedState is unused, as will be explained in the next section. RetentionStrategy ArrayPagerAdapter also uses a RetentionStrategy, designed to abstract the logic for manipulating the fragments themselves as pages come and go within the ViewPager. RetentionStrategy is an interface, with methods to attach() a fragment to be in the pager and to detach() the fragment from the pager: public interface RetentionStrategy { void attach(Fragment fragment, FragmentTransaction currTransaction); void detach(Fragment fragment, FragmentTransaction currTransaction); There is only one stock implementation of this strategy at this time, in the form of a static data member named KEEP. This strategy is designed to replicate the behavior of FragmentPagerAdapter, keeping all fragments around once created, and merely attach()-ing and detach()-ing them from the FragmentManager as dictated: public T getCurrentFragment() { return return(currPrimaryItem); } private String getFragmentTag(int position) { return return(getPageDescriptor(position).getFragmentTag()); } private void validatePageDescriptor(PageDescriptor desc) { 2053 MORE FUN WITH PAGERS for (PageEntry entry : entries) { if (desc.getFragmentTag().equals(entry.getDescriptor() .getFragmentTag())) { throw new IllegalArgumentException( A future implementation of ArrayPagerAdapter should include another strategy that behaves more like FragmentStatePagerAdapter, removing the fragments entirely and allowing them to be garbage collected, while using PageEntry to hold onto their Fragment.SavedState structures to repopulate them later on if the user swipes back to that page. Class Declaration and Generics ArrayPagerAdapter uses Java generics to allow developers to state what Fragment subclass the pages are. This is for use with convenience methods — getExistingFragment() and getCurrentFragment() — to help reduce the developer’s need to downcast those Fragment instances to some subclass. If the pages in the ViewPager will all come from a single Fragment subclass, the developer would use that class as the T in the declaration; otherwise, the developer would just use Fragment: abstract public class ArrayPagerAdapter ArrayPagerAdapter extends Constructors ArrayPagerAdapter offers two constructors. The simpler two-parameter constructor, taking the FragmentManager and the desired pages as an ArrayList of PageDescriptor objects, just chains to the three-parameter constructor. That third parameter is an instance of a RetentionStrategy, allowing reusers of ArrayPagerAdapter to try their own hand at implementing such a strategy. null — the default strategy from the standpoint of the constructors — is replaced with the default KEEP strategy, and the PageDescriptor objects are wrapped in PageEntry objects as the actual data model (an entries ArrayList): public ArrayPagerAdapter(FragmentManager fragmentManager, List descriptors, RetentionStrategy retentionStrategy) { this this.fm=fragmentManager; this this.entries=new new ArrayList(); for (PageDescriptor desc : descriptors) { validatePageDescriptor(desc); 2054 MORE FUN WITH PAGERS entries.add(new new PageEntry(desc)); } this this.retentionStrategy=retentionStrategy; if (this this.retentionStrategy == null null) { this this.retentionStrategy=KEEP; } Core PagerAdapter Methods All PagerAdapter implementations have some core methods that they must handle. When you create a subclass of FragmentPagerAdapter and FragmentStatePagerAdapter, you only need to worry about getCount() and getPage(). However, if you are creating your own replacement for those fragmentbased adapters, there are a few more standard PagerAdapter methods that you will need to override. getCount() getCount() is easy: all we need to do is return our desired number of pages. That is based on the number of PageDescriptor objects supplied to our adapter, which we wrapped into PageEntry objects and hold onto in entries: @Override public int getCount() { return return(entries.size()); } getPageTitle() Similarly, getPageTitle() just needs to find the appropriate PageDescriptor and call getTitle() on it, to supply the title for a given page for use by an indicator like PagerTabStrip: @Override public String getPageTitle(int position) { return return(getPageDescriptor(position).getTitle()); } 2055 MORE FUN WITH PAGERS instantiateItem() and destroyItem() The instantiateItem() method on PagerAdapter is responsible for setting up the user interface for a given page (indicated by position) and adding those widgets to a ViewGroup supplied as a parameter. It returns an Object that represents a “handle” to the page that ViewPager will return to the PagerAdapter in future calls, such as to destroyItem(). A Fragment-based PagerAdapter can use the fragment itself as the “handle”, and the fragment’s onCreateView() as the means of obtaining the UI to pour into the ViewGroup. Hence, the ArrayPagerAdapter implementation of instantiateItem() does the following: • First, starts a FragmentTransaction, if there is not one already in progress • Then, tries to find an existing Fragment for this position, using a getExistingFragment() helper method (described later in this chapter) • If an existing fragment exists, instantiateItem() uses the RetentionStrategy to re-attach the UI • If an existing fragment does not exist, instantiateItem() calls the abstract createFragment() method, to allow the subclass to return the actual Fragment object given the PageDescriptor, then add() that fragment to the UI • If the fragment is not already the current page, make sure that its action bar contributions are hidden via setMenuVisibility() and setUserVisibleHint() • Return the fragment itself as the “handle” @TargetApi(Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) @Override public Object instantiateItem(ViewGroup container, int position) { if (currTransaction == null null) { currTransaction=fm.beginTransaction(); } Fragment fragment=getExistingFragment(position); if (fragment != null null) { retentionStrategy.attach(fragment, currTransaction); } else { fragment=createFragment(entries.get(position).getDescriptor()); currTransaction.add(container.getId(), fragment, getFragmentTag(position)); } 2056 MORE FUN WITH PAGERS if (fragment != currPrimaryItem) { fragment.setMenuVisibility(false false); if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) { fragment.setUserVisibleHint(false false); } } return return(fragment); } Conversely, destroyItem() is responsible for cleaning up anything from a page that the PagerAdapter thinks is no longer needed. The destroyItem() method on ArrayPagerAdapter starts a transaction if there is none, then delegates the actual work to the RetentionStrategy: @TargetApi(Build.VERSION_CODES.HONEYCOMB) @Override public void destroyItem(ViewGroup container, int position, Object object) { if (currTransaction == null null) { currTransaction=fm.beginTransaction(); } retentionStrategy.detach((Fragment)object, currTransaction); } startUpdate() and finishUpdate() The startUpdate() method will be called before any calls to instantiateItem() or destroyItem(), and so, if desired, we can do some initialization work there. In the case of ArrayPagerAdapter, all initialization is done lazily, and so startUpdate() is not needed. However, since FragmentPagerAdapter overrides startUpdate() with an empty implementation, we keep that for maximum fidelity with the stock implementation: @Override public void startUpdate(ViewGroup container) { } The finishUpdate() method will be called after any calls to instantiateItem() or destroyItem(), where we can do some cleanup work. ArrayPagerAdapter creates a FragmentTransaction as part of its work in instantiateItem() and destroyItem(), and so we need to commit that transaction in finishUpdate(). Once again, we reproduce the implementation from FragmentPagerAdapter, which uses 2057 MORE FUN WITH PAGERS commitAllowingStateLoss() (so we are not concerned with the timing of any statesaving being done at the activity level) and executePendingTransactions() (so all of the fragment work is done directly, rather than being posted to the end of the main application thread’s work queue): @TargetApi(Build.VERSION_CODES.HONEYCOMB) @Override public void finishUpdate(ViewGroup container) { if (currTransaction != null null) { currTransaction.commitAllowingStateLoss(); currTransaction=null null; fm.executePendingTransactions(); } } setPrimaryItem() ViewPager will call setPrimaryItem() on the PagerAdapter when a new page is being brought into view, based on gestures or other calls on ViewPager itself (e.g., setCurrentItem()). Some PagerAdapter implementations will have nothing much to do here. Fragment-based PagerAdapter implementations, though, need to ensure that the right fragment’s action bar items are shown. Hence, ArrayPagerAdapter removes the action bar items from the previously-current page and adds the action bar items of the newly-current page: @TargetApi(Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) @SuppressWarnings("unchecked") @Override public void setPrimaryItem(ViewGroup container, int position, Object object) { T fragment=(T)object; if (fragment != currPrimaryItem) { if (currPrimaryItem != null null) { currPrimaryItem.setMenuVisibility(false false); if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) { currPrimaryItem.setUserVisibleHint(false false); } } if (fragment != null null) { fragment.setMenuVisibility(true true); if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) { fragment.setUserVisibleHint(true true); } } currPrimaryItem=fragment; 2058 MORE FUN WITH PAGERS } } isViewFromObject() isViewFromObject() helps ViewPager keep track of the UI for pages and how it maps back to a page’s “handle”. In our case, since the “handle” is a Fragment, we need to see if the supplied View is the View from the supplied Fragment: @TargetApi(Build.VERSION_CODES.HONEYCOMB) @Override public boolean isViewFromObject(View view, Object object) { return ((Fragment)object).getView() == view; } State Management Our PagerAdapter is called with saveState() and restoreState() methods, to have us save the state of our data model and restore it, for configuration changes. saveState() returns a Parcelable which will form part of the state saved by the ViewPager, while restoreState() is handed back that Parcelable (or a copy). The state of the fragments is handled by FragmentManager, no different than with any other fragments we might use in an activity. The mere fact that we happen to coordinate those fragments with a PagerAdapter does not change this. Hence, the “state” that we are dealing with in saveState() and restoreState() is solely the state of the PagerAdapter data model — in our case, the roster of pages. To future-proof the implementation a bit, the state is represented as a Bundle, into which we can store other Parcelable objects. Since Bundle knows how to save an ArrayList of Parcelable objects, we can just call putParcelableArrayList() to save our ArrayList of PageEntry objects, restoring them in restoreState() via getParcelableArrayList(): @Override public Parcelable saveState() { Bundle state=new new Bundle(); state.putParcelableArrayList(KEY_DESCRIPTORS, entries); return return(state); } 2059 MORE FUN WITH PAGERS Content Manipulation and Position Management Perhaps the trickiest method on PagerAdapter that we have to worry about is innocuously named getItemPostion(). We are given the Object “handle” for a page, and we need to return the position of that page. However, that’s not really what is going on here. getItemPosition() is used when we call notifyDataSetChanged() to indicate a structural change in our data model, such as an added or removed page. ViewPager is looking for getItemPosition() to tell us the new position of pages for this notifyDataSetChanged() call. So, as we manipulate our pages, we need to track what is going on with page positions, so getItemPosition() can return the correct data. The actual value returned by getItemPosition() is either: • The actual numerical position of the page, from 0 to getCount()-1, if the page moved to another position (where we return the new position) • PagerAdapter.POSITION_UNCHANGED, if the page has not moved • PagerAdapter.POSITION_NONE, if the page no longer exists (e.g., was removed) ArrayPagerAdapter simply holds a HashMap (positionDelta), mapping our Fragment “handle” to the page to an Integer representing any change to the position of that page made by methods like add(). When getItemPosition() is called, we return the value for that page out of the HashMap, or POSITION_UNCHANGED if the page does not appear in the HashMap, indicating that the page has not been affected: @Override public int getItemPosition(Object o) { Integer result=positionDelta.get(o); if (result == null null) { return return(PagerAdapter.POSITION_UNCHANGED); } return return(result); } The add() method needs to add a new page to the data model, given the PageDescriptor. We clear() our positionDelta HashMap (as any previous changes 2060 MORE FUN WITH PAGERS should already have been picked up), add() a new PageEntry to our data model based on the supplied PageDescriptor, then call notifyDataSetChanged(): public PageDescriptor getPageDescriptor(int position) { return return(entries.get(position).getDescriptor()); } public int getPositionForTag(String tag) { for (int i=0;i, to stipulate that this widget should be the one to get the focus Note that this is a child element, not an attribute, as you might ordinarily expect. For example, let’s look at the Focus/Sampler sample project, which we will use to illustrate various focus-related topics. Our main activity, creatively named MainActivity, loads a layout named request_focus.xml, and demonstrates the element: >

/> /> > 2068 FOCUS MANAGEMENT AND ACCESSIBILITY (from Focus/Sampler/app/src/main/res/layout/request_focus.xml) Here, we have three widgets in a horizontal LinearLayout: a Button, and two EditText widgets. The second EditText widget has the child element, and so it gets the focus when we display our launcher activity: Figure 664: Focus Sampler, Showing Requested Focus If we had skipped the element, the focus would have wound up on the first EditText… assuming that we are working in touch mode. If the activity had been launched via the pointing device or keyboard, then the Button would have the focus, because the Button is focusable in non-touch mode by default. Calling requestFocus() from Java code gets a bit trickier. There are a few flavors of the requestFocus() method on View, of which two will be the most popular: • An ordinary zero-argument requestFocus() • A one-argument requestFocus(), with the argument being the direction in which the focus should theoretically be coming from 2069 FOCUS MANAGEMENT AND ACCESSIBILITY You might look at the description of the second flavor and decide that the zeroargument requestFocus() looks a lot easier. And, sometimes it will work. However, sometimes it will not, as is the case with our second activity, RequestFocusActivity. In this activity, our layout (focusable_button) is a bit different: > /> > /> (from Focus/Sampler/app/src/main/res/layout/focusable_button.xml) Here, we put the Button last instead of first. We have no element anywhere, which would put the default focus on the first EditText widget. And, our Button has android:focusableInTouchMode="true", so it will be focusable regardless of whether we are in touch mode or not. 2070 FOCUS MANAGEMENT AND ACCESSIBILITY In onCreate() of our activity, we use the one-parameter version of requestFocus() to give the Button the focus: @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.focusable_button); initActionBar(); button=findViewById(R.id.button1); button.requestFocus(View.FOCUS_RIGHT); button.setOnClickListener(this this); } (from Focus/Sampler/app/src/main/java/com/commonsware/android/focus/RequestFocusActivity.java) If there were only the one EditText before the Button, the zero-argument requestFocus() works. However, with a widget between the default focus and our Button, the zero-argument requestFocus() does not work, but using requestFocus(View.FOCUS_RIGHT) does. This tells Android that we want the focus, and it should be as if the user is moving to the right from where the focus currently lies. All of our activities inherit from a BaseActivity that manages our action bar, with an overflow menu to get to the samples and the app icon to get to the original activity. So, if you run the app and choose “Request Focus” from the overflow menu, you will see: 2071 FOCUS MANAGEMENT AND ACCESSIBILITY Figure 665: Focus Sampler, Showing Manually-Requested Focus We also wire up the Button to the activity for click events, and in onClick(), we call clearFocus() to abandon the focus: @Override public void onClick(View v) { button.clearFocus(); } (from Focus/Sampler/app/src/main/java/com/commonsware/android/focus/RequestFocusActivity.java) What clearFocus() will do is return to the original default focus for this activity, in our case the first EditText: 2072 FOCUS MANAGEMENT AND ACCESSIBILITY Figure 666: Focus Sampler, After Clearing the Focus Focus Ordering Beyond manually placing the focus on a widget (or manually clearing that focus), you can also override the focus order that Android determines automatically. While Android’s decisions usually are OK, they may not be optimal. A widget can use android:nextFocus... attributes in the layout file to indicate the widget that should get control on a focus change in the direction indicated by the ... part. So, android:nextFocusDown, applied to Widget A, indicates which widget should receive the focus if, when the focus is on Widget A, the user “moves down” (e.g., presses a DOWN key, presses the down direction on a D-pad). The same logic holds true for the other three directions (android:nextFocusLeft, android:nextFocusRight, and android:nextFocusUp). For example, the res/layout/table.xml resource in the FocusSampler project is based on the TableLayout sample from early in this book, with a bit more focus control: > /> /> /> /> (from Focus/Sampler/app/src/main/res/layout/table.xml) In the original TableLayout sample, by default, pressing either RIGHT or DOWN while the EditText has the focus will move the focus to the “Cancel” button. This certainly works. However, it does mean that there is no single-key means of moving from the EditText to the “OK” button, and it would be nice to offer that, so those using the pointing device or keyboard can quickly move to either button. This is a matter of overriding the default focus-change behavior of the EditText widget. In our case, we use android:nextFocusRight="@+id/ok" to indicate that the “OK” button should get the focus if the user presses RIGHT from the EditText. This gives RIGHT and DOWN different behavior, to reach both buttons. 2074 FOCUS MANAGEMENT AND ACCESSIBILITY Scrolling and Focusing Do Not Mix Let’s suppose that you have a UI design with a fixed bar of widgets at the top (e.g., action bar), a ListView dominating the activity, and a panel of widgets at the bottom (e.g., a Toolbar). This is a common UI pattern on iOS, though it is relatively uncommon on Android nowadays. You used to see it with the so-called “split action bar”, which is now officially deprecated as a pattern: Figure 667: Split Action Bar However, this UI pattern does not work well for those using pointing devices or keyboards for navigation. In order to get to the bottom panel of widgets, they will have to scroll through the entire list first, because scrolling trumps focus changes. So while this is easy to navigate via a touchscreen, it is a major problem to navigate for those not using a touchscreen. Similarly, if the user has scrolled down the list, and now wishes to get to the action bar at the top, the user would have to scroll all the way to the top of the list first. Workarounds include: 2075 FOCUS MANAGEMENT AND ACCESSIBILITY • Overriding focus control such that left and right navigation from the list moves you to the action bar or bottom Toolbar (e.g., left moves you to the action bar, right moves you to the Toolbar) • In a television setup, having the “action bar” be vertical down the left, and the tools be vertical down the right, so you automatically get the left/right navigation to move between these “zones” • Eliminating the Toolbar entirely, moving those items instead to the action bar, or perhaps an action mode (a.k.a., contextual action bar) if the items are only relevant if the user checks one or more items in the list • Offer a hotkey, separate from navigation, that repositions the focus (e.g., Ctrl-A to jump to the action bar), if you believe that users will read your documentation to discover this key combination Accessibility and Focus People suffering from impaired vision, including the blind, have had to rely heavily on proper keyboard navigation for their use of Android apps, at least prior to Android 4.0 and “Explore by Touch”. These users need focus to be sensible, so that they can find their way through your app, with TalkBack supplying prompts for what has the focus. Having widgets that are unreachable in practice will eliminate features from your app for this audience, simply because they cannot get to them. “Explore by Touch” provides accessibility assistance without reliance upon proper focus. However: • “Explore by Touch” is new to Android 4.0, and a few visually-impaired users will be using older devices • “Explore by Touch” is less reliable than keyboard-based navigation, insofar as users have to remember specific screen locations (and get to them without seeing those locations), rather than simply memorizing certain key combinations • “Explore by Touch”, by requiring additional taps (e.g., double-tap to tap a Button), may cause some challenges when the UI itself requires additional taps (e.g., a double-tap on a widget to perform an action — is this now a triple-tap in “Explore by Touch” mode?) • “Explore by Touch” is mostly for the visually impaired, and does not help others that might benefit from key-based navigation (e.g., people with limited motor control) 2076 FOCUS MANAGEMENT AND ACCESSIBILITY So, even though “Explore by Touch” will help people use apps that cannot be navigated purely through key events, the better you can support keyboards, the better off your users will be. Accessibility Beyond Focus While getting focus management correct goes a long way towards making your application easier to use, it is not the only thing to consider for making your application truly accessible by all possible users. This section covers a number of other things that you should consider as part of your accessibility initiatives. Content Descriptions For TalkBack to work, it needs to have something useful to read aloud to the user. By default, for most widgets, all it can say is the type of widget that has the focus (e.g., “a checkbox”). That does not help the TalkBack-reliant user very much. Please consider adding android:contentDescription attributes to most of your widgets, pointing to a string resource that briefly describes the widget (e.g., “the Enabled checkbox”). This will be used in place of the basic type of widget by TalkBack. Classes that inherit from TextView will use the text caption of the widget by default, so your Button widgets may not need android:contentDescription if their captions will make sense to TalkBack users. However, with an EditText, since the text will be what the user types in, the text is not indicative of the widget itself. Android will first use your android:hint value, if available, falling back to android:contentDescription if android:hint is not supplied. Also, bear in mind that if the widget changes purpose, you need to change your android:contentDescription to match. For example, suppose you have a media player app with an ImageButton that you toggle between “play” and “pause” modes by changing its image. When you change the image, you also need to change the android:contentDescription as well, lest sighted users think the button will now “pause” while blind users think that the button will now “play”. 2077 FOCUS MANAGEMENT AND ACCESSIBILITY Labels Sometimes, we have TextView widgets that serve as on-screen labels for some adjacent other widget, such as an EditText. In those cases, you can associate the two by using android:labelFor on the TextView, supplying the ID of the widget for which the TextView is a label. This will help accessibility tools properly announce the widgets, as otherwise those tools do not know that these widgets are related. Custom Widgets and Accessibility Events The engine behind TalkBack is an accessibility service. Android ships with some, like TalkBack, and third parties can create other such services. Stock Android widgets generate relevant accessibility events to feed data into these accessibility services. That is how android:contentDescription gets used, for example — on a focus change, stock Android widgets will announce the widget that just received the focus. If you are creating custom widgets, you may need to raise your own accessibility events. This is particularly true for custom widgets that draw to the Canvas and process raw touch events (rather than custom widgets that merely aggregate existing widgets). The Android developer documentation provides instructions for when and how to supply these sorts of events. Announcing Events Sometimes, your app will change something about its visual state in ways that do not get picked up very well by any traditional accessibility events. For example, you might use GestureDetector to handle some defined library of gestures and change state in your app. Those state changes may have visual impacts, but GestureDetector will not know what those are and therefore cannot supply any sort of accessibility event about them. To help with this, API Level 16 added announceForAccessibility() as a method on View. Just pass it a string and that will be sent out as an “announcement” style of AccessibilityEvent. Your code leveraging GestureDetector, for example, could use this to explain the results of having applied the gesture. 2078 FOCUS MANAGEMENT AND ACCESSIBILITY Font Selection and Size For users with limited vision, being able to change the font size is a big benefit. Android 4.0 finally allows this, via the Settings app, so users can choose between small, normal, large, and huge font sizes. Any place where text is rendered and is measured in sp will adapt. The key, of course, is the sp part. sp is perhaps the most confusing of the available dimension units in Android. px is obvious, and dp (or dip) is understandable once you recognize the impacts of screen density. Similarly, in, mm, and pt are fairly simple, at least once you remember that pt is 1/72nd of an inch. If the user has the font scale set to “normal”, sp equates to dp, so a dimension of 30sp and 30dp will be the same size. However, values in dp do not change based on font scale; values in sp will increase or decrease in physical size based upon the user’s changes to the font scale. We can see how this works in the Accessibility/FontScale sample project. In our layout (res/layout/activity_main.xml), we have six pieces of text: two each (regular and bold) measured at 30px, 30dp, and 30sp: > /> /> /> /> /> /> (from Accessibility/FontScale/app/src/main/res/layout/activity_main.xml) You will be able to see the differences between 30px and 30dp on any Android OS release, simply by running the app on devices with different densities. To see the changes between 30dp and 30sp, you will need to run the app on an Android 4.0+ device or emulator and change the font scale from the Settings app (typically in the Display section). Here is what the text looks like with a normal font scale: 2080 FOCUS MANAGEMENT AND ACCESSIBILITY Figure 668: Fonts at Normal Scale As you can see, 30dp and 30sp are equivalent. If we raise the font scale to “large”, the 30sp text grows to match: 2081 FOCUS MANAGEMENT AND ACCESSIBILITY Figure 669: Fonts at Large Scale Moving to “huge” scale increases the 30sp text size further: 2082 FOCUS MANAGEMENT AND ACCESSIBILITY Figure 670: Fonts at Huge Scale In the other direction, some users may elect to drop their font size to “small”, with a corresponding impact on the 30sp text: 2083 FOCUS MANAGEMENT AND ACCESSIBILITY Figure 671: Fonts at Small Scale As a developer, your initial reaction may be to run away from sp, because you do not control it. However, just as Web developers should deal with changing font scale in Web browsers, Android developers should deal with changing font scale in Android apps. Remember: the user is changing the font scale because the user feels that the revised scale is easier for them to use. Blocking such changes in your app, by avoiding sp, will not be met with love and adoration from your user base. Also, bear in mind that changes to the font scale represent a configuration change. If your app is in memory at the time the user goes into Settings and changes the scale, if the user returns to your app, each activity that comes to the foreground will undergo the configuration change, just as if the user had rotated the screen or put the device into a car dock or something. Widget Size Users with ordinary sight already have trouble with tiny widgets, as they are difficult to tap upon. Users trying to use the Explore by Touch facility added in Android 4.1 have it worse, as they cannot even see (or see well) the tiny target you are expecting them to tap 2084 FOCUS MANAGEMENT AND ACCESSIBILITY upon. They need to be able to reliably find your widget based on its relative position on the screen, and their ability to do so will be tied, in part, on widget size. The Android design guidelines recommend 7-10mm per side minimum sizes for tappable widgets. In particular, they recommend 48dp per side, which results in a size of about 9mm per side. You also need to consider how closely packed your widgets are. The closer the tap targets lie, the more likely it is that all users — whether using Explore by Touch or not — will accidentally tap on the wrong thing. Google recommends 8dp or more of margin between widgets. Also note that the key is margins, as while increasing padding might visually separate the widgets, the padding is included as part of the widget from the standpoint of touch events. While padding may help users with ordinary sight, margins provide similar help while also being of better benefit to those using Explore by Touch. Gestures and Taps If you employ gestures, be careful when employing the same gesture in different spots for different roles, particularly within the same activity. For example, you might use a horizontal swipe to the right to switch pages in a ViewPager in some places and remove items from a ListView in others. While there may be visual cues to help explain this to users with ordinary sight, it may be far less obvious what is going on for TalkBack users. This is even more true if you are somehow combining these things (e.g., the ListView in question is in a page of the ViewPager). Also, be a bit careful as you “go outside the box” for tap events. You might decide that a double-tap, or a two-finger tap, has special meaning on some widgets. Make sure that this still works when users use Explore by Touch, considering that the first tap will be “consumed” by Explore by Touch to announce the widget being tapped upon. Enhanced Keyboard Support All else being equal, users seeking accessibility assistance will tend to use keyboards when available. For users with limited (or no) sight, tactile keyboards are simply easier to use than touchscreens. For users with limited motor control, external devices that interface as keyboards may allow them to use devices that otherwise they could not. 2085 FOCUS MANAGEMENT AND ACCESSIBILITY Of course, plenty of users will use keyboards outside of accessibility as well. For example, devices like the ASUS Transformer series form perfectly good “netbook”style devices when paired with their keyboards. Hence, consider adding hotkey support, to assist in the navigation of your app. Some hotkeys may be automatically handled (e.g., Ctrl-C for copy in an EditText). However, in other cases you may wish to add those yourself (e.g., Ctrl-C for “copy” with respect to a checklist and its selected rows, in addition to a “copy” action mode item). API Level 11 adds KeyEvent support for methods like isCtrlPressed() to detect meta keys used in combination with regular keys. Audio and Haptics Of course, another way to make your app more accessible is to provide alternative modes of input and output, beyond the visual. Audio is popular in this regard: • Using tones or clicks to reinforce input choices • Integrating your own text-to-speech to augment TalkBack • Integrating speech recognition for simple commands However, bear in mind that deaf users will be unable to hear your audio. You are better served using both auditory and visual output, not just one or the other. In some cases, haptics can be helpful for input feedback, by using the Vibrator system service to power the vibration motor. While most users will be able to feel vibrations, the limitation here is whether the device is capable of vibrating: • Some tablets lack a vibration motor • Television-based Android environment may or may not have some sort of vibration output (e.g., remote controls probably will not, but game controllers might) • Devices not held in one’s hand, such as those in a dock, will make haptics less noticeable So, audio and vibration can help augment visual input and output, though they should not be considered complete replacements except in rare occurrences. 2086 FOCUS MANAGEMENT AND ACCESSIBILITY Color and Color Blindness Approximately 8% of men (and 0.5% of women) in the world are colorblind, meaning that they cannot distinguish certain close colors: …It’s not that colorblind people (in most cases) are incapable or perceiving “green,” instead they merely distinguish fewer shades of green than you do. So where you see three similar shades of green, a colorblind user might only see one shade of green. (from “Tips for Designing for Colorblind Users”) Hence, relying solely on colors to distinguish different items, particularly when required for user input, is not a wise move. Make sure that there is something more to distinguish two pieces of your UI than purely a shift in color, such as: • Labels or icons • Textures (e.g., solid vs. striped) • Borders (e.g., drop shadow) Accessibility Beyond Impairment Accessibility is often tied to impaired users: ones with limited (or no) sight, ones with limited (or no) hearing, ones with limited motor control, etc. In reality, accessibility is for situations where users may have limitations. For example, a user who might not normally think of himself as “impaired” has limited sight, hearing, and motor control when those facilities are already in use, such as while driving. Hence, offering features that help with accessibility can benefit all your users, not just ones you think of as “impaired”. For example: • Offer a UI mode with an eye towards use in low-visibility situations that can either be manually invoked (e.g., via a preference) or automatically invoked (e.g., via a car dock) • Offer voice input (commands) and output (text-to-speech) — iOS’s Siri is not just for the blind, after all 2087 FOCUS MANAGEMENT AND ACCESSIBILITY • Offer hotkeys, not only to help those requiring a keyboard as their primary mode of input (e.g., blind users minimizing touchscreen use), but to help those who opt into using it for input (e.g., using a keyboard with an Android tablet in lieu of a traditional notebook or netbook) 2088 Miscellaneous UI Tricks While well-written GUI frameworks are better organized than XKCD’s take on home organization, there are always a handful of tidbits that do, indeed, get categorized as “miscellaneous”. Prerequisites Understanding this chapter requires that you have read the core chapters of this book. Having an appreciation for XKCD is welcome, but optional. Full-Screen and Lights-Out Modes Full-screen mode, in Android parlance, means removing any system-supplied “bars” from the screen: title bar, action bar, status bar, system bar, navigation bar, etc. You might use this for games, video players, digital book readers, or other places where the time spent in an activity is great enough to warrant removing some of the normal accouterments to free up space for whatever the activity itself is doing. Lights-out mode, in Android parlance, is where you take the system bar or navigation bar and dim the widgets inside of them, such that the bar is still usable, but is less visually distracting. This is a new concept added in Android 3.0 and has no direct analogue in Android 1.x or 2.x. Android 1.x/2.x To have an activity be in full-screen mode, you have two choices: 2089 MISCELLANEOUS UI TRICKS 1. Having the activity use a theme of Theme.NoTitleBar.Fullscreen (or some custom theme that inherits from Theme.NoTitleBar.Fullscreen) 2. Execute the following statements in onCreate() of your activity before calling setContentView(): requestWindowFeature(Window.FEATURE_NO_TITLE); getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN, WindowManager.LayoutParams.FLAG_FULLSCREEN); The first statement removes the title bar or action bar. The second statement indicates that you want the activity to run in full-screen mode, hiding the status bar. Android 4.0+ Things got significantly more messy once we started adding in the system bar (and, later, the navigation bar as the replacement for the system bar). Since these bars provide the user access to HOME, BACK, etc., it is usually important for them to be available. Android’s behavior, therefore, varies in how you ask for something to happen and what then happens, based upon whether the device is a phone or a tablet. The Activities/FullScreen sample project tries to enumerate some of the possibilities. On an Android 4.0 device, we have three RadioButtons: > > /> /> /> /> (from Activities/FullScreen/app/src/main/res/layout/main.xml) Figure 672: Sample UI, As Initially Launched on Android 4.0 …while on Android 4.1 or higher, we have another two possibilities: 2091 MISCELLANEOUS UI TRICKS > > /> /> /> /> /> /> 2092 MISCELLANEOUS UI TRICKS (from Activities/FullScreen/app/src/main/res/layout-v16/main.xml) Figure 673: Sample UI, As Initially Launched on a Nexus 4/Android 4.2 Controlling the full-screen and lights-out modes is managed via a call to setSystemUiVisibility(), a method on View. You pass in a value made up of an OR’d (|) set of flags indicating what you want the visibility to be, with the default being normal operation. Hence, in the screenshot above, you see a Nexus 4 in normal mode. Here is the same UI on a Nexus 10 in normal mode: 2093 MISCELLANEOUS UI TRICKS Figure 674: Sample UI, As Initially Launched on a Nexus 10/Android 4.2 Lights-out, or low-profile mode, is achieved by calling setSystemUiVisibility() with the View.SYSTEM_UI_FLAG_LOW_PROFILE flag. This will dim the navigation or system bar, so the bar is there and the buttons are still active, but that they are less visually intrusive: 2094 MISCELLANEOUS UI TRICKS Figure 675: Sample UI, Lights-Out Mode, Nexus 4/Android 4.2 Figure 676: Sample UI, Lights-Out Mode, Nexus 10/Android 4.2 2095 MISCELLANEOUS UI TRICKS You can temporarily hide the navigation bar (or system bar) by passing View.SYSTEM_UI_FLAG_HIDE_NAVIGATION to setSystemUiVisibility(). The bar will disappear, until the user touches the UI, in which case the bar reappears: Figure 677: Sample UI, Hidden-Navigation Mode, Nexus 4/Android 4.2 2096 MISCELLANEOUS UI TRICKS Figure 678: Sample UI, Hidden-Navigation Mode, Nexus 10/Android 4.2 Similarly, you can hide the status bar by passing View.SYSTEM_UI_FLAG_FULLSCREEN to setSystemUiVisibility(). However, despite this flag’s name, it does not affect the navigation or system bar: 2097 MISCELLANEOUS UI TRICKS Figure 679: Sample UI, “Full-Screen” Mode, Nexus 4/Android 4.2 Figure 680: Sample UI, “Full-Screen” Mode, Nexus 10/Android 4.2 2098 MISCELLANEOUS UI TRICKS Hence, to hide both the status bar and the navigation or system bar, you need to pass both flags (View.SYSTEM_UI_FLAG_FULLSCREEN | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION): Figure 681: Sample UI, True Full-Screen Mode, Nexus 4/Android 4.2 2099 MISCELLANEOUS UI TRICKS Figure 682: Sample UI, True Full-Screen Mode, Nexus 10/Android 4.2 Note that showing and hiding the ActionBar is also possible, via calls to show() and hide(), respectively. Offering a Delayed Timeout Android makes it easy for activities to keep the screen on while the activity is in the foreground, by means of android:keepScreenOn and setKeepScreenOn(). However, these are very blunt instruments, and too many developers simply ask to keep the screen on constantly, even when that is not needed and can cause excessive battery drain. That is because it is very easy to always keeps the screen on. Say, for example, you are playing a game. Keeping the screen on while the game is being played is probably a good thing, particularly if the game does not require constant interaction with the screen. However, if you press the in-game pause button, the game might keep the screen on while the game is paused. This might lead you to press pause, put down your tablet (expecting it to fall asleep in a normal period of time), and then have the tablet keep going and going and going… until the battery runs dead. 2100 MISCELLANEOUS UI TRICKS Whether you use setKeepScreenOn() or directly use a WakeLock, it is useful to think of three tiers of user interaction. The first tier is when your app is doing its “one big thing”: playing the game, playing the video, displaying the digital book, etc. If you expect that there will be periods of time when the user is actively engaged with your app, but is not interacting with the screen, keep the screen on. The second tier is when your app is delivering something to the user that probably would get used without interaction in the short term, but not indefinitely. For example, a game might reasonably expect that 15 seconds could be too short to have the screen time out, but if the user has not done anything in 5-10 minutes, most likely they are not in front of the game. Similarly, a digital book reader should not try to keep the screen on for an hour without user interaction. The third tier is when your app is doing anything other than the main content, where normal device behavior should resume. A video player might keep the screen on while the video is playing, but if the video ends, normal behavior should resume. After all, if the person who had been watching the video fell asleep, they will not be in position to press a power button. The first and third tiers are fairly easy from a programming standpoint. Just acquire() and release() the WakeLock, or toggle setKeepScreenOn() between true and false. The second tier — where you are willing to have a screen timeout, just not too quickly — requires you to add a bit more smarts to your app. A simple, low-overhead way of addressing this is to have a postDelayed() loop, to get a Runnable control every 5-10 seconds. Each time the user interacts with your app, update a lastInteraction timestamp. The Runnable compares lastInteraction with the current time, and if it exceeds some threshold, release the WakeLock or call setKeepScreenOn(false). When the user interacts again, though, you will need to re-acquire the WakeLock or call setKeepScreenOn(true). Basically, you have your own inactivity timing mechanism to control when you are inhibiting normal inactivity behavior or not. To see the second tier in action, take a look at the MiscUI/DelayedTimeout sample project. The UI is a simple button. We want to keep the screen awake while the user is using the button, but let it fall asleep after a period of inactivity that we control. To 2101 MISCELLANEOUS UI TRICKS accomplish this, we will use a postDelayed() loop, to get control every 15 seconds to see if there has been user activity: package com.commonsware.android.timeout; import import import import android.app.Activity android.app.Activity; android.os.Bundle android.os.Bundle; android.os.SystemClock android.os.SystemClock; android.view.View android.view.View; public class MainActivity extends Activity implements Runnable { private static int TIMEOUT_POLL_PERIOD=15000; // 15 seconds private static int TIMEOUT_PERIOD=300000; // 5 minutes private View content=null null; private long lastActivity=SystemClock.uptimeMillis(); @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); content=findViewById(android.R.id.content); content.setKeepScreenOn(true true); run(); } @Override public void onDestroy() { content.removeCallbacks(this this); super super.onDestroy(); } @Override public void run() { if ((SystemClock.uptimeMillis() - lastActivity) > TIMEOUT_PERIOD) { content.setKeepScreenOn(false false); } content.postDelayed(this this, TIMEOUT_POLL_PERIOD); } public void onClick(View v) { lastActivity=SystemClock.uptimeMillis(); } } (from MiscUI/DelayedTimeout/app/src/main/java/com/commonsware/android/timeout/MainActivity.java) 2102 MISCELLANEOUS UI TRICKS In onCreate(), we call setKeepScreenOn(true) to keep the screen on, regardless of what the user’s default timeout is. Then, we call the run() method from our Runnable interface (implemented on the activity itself ). run() sees if 5 minutes has elapsed since the last bit of user activity (initially set to be the time the activity launches). If 5 minutes has elapsed, we revert to normal screen-timeout behavior with setKeepScreenOn(false). We also schedule ourselves, as a Runnable, to get control again in 15 seconds, to see if 5 minutes has elapsed since the last-seen activity. Our button’s onClick() method simply updates the last-seen timestamp, and onDestroy() cleans up our postDelayed() loop by calling removeCallbacks() to stop invoking our Runnable. The net is that the device’s screen will remain on for 5 minutes since the last time the user taps the button, even if the user’s default screen timeout is set to shorter than 5 minutes. Yet, at the same time, we do not keep the screen on forever, causing unnecessary battery drain. Note that to test this, you will probably need to unplug your USB cable after installing the app on the device (since many developers have it set up to keep the screen on while plugged in). Also, you will need to set your device’s screen timeout to be under 5 minutes, if it is not set that way already. This is a primitive implementation, missing lots of stuff that you would want in production code (e.g., it never calls setKeepScreenOn(true) if we flipped it to false but then tap the button). And the complexity of determining if the user interacted with the screen will be tied to the complexity of your UI. That being said, by having a more intelligent use of WakeLock and setKeepScreenOn(), you can deliver value to the user while not accidentally causing excessive battery drain. Users do not always remember to press the power button, so you need to make sure that just because the user made a mistake, that you do not make it worse. 2103 Event Bus Alternatives Earlier in the book, we covered the concept of an event bus as a way of communicating between portions of our app, focusing on one event bus implementation: greenrobot’s EventBus. Later, in the chapter on broadcast Intent objects, we briefly covered LocalBroadcastManager. However, those are not the only event buses available for Android, and others may fit your needs better. In this chapter, we will explore these and other event bus implementations, to compare and contrast. Prerequisites Understanding this chapter requires that you have read the core chapters of this book, particularly the chapters on basic event bus usage, broadcast Intents, AlarmManager and the scheduled service pattern, and Notifications. A Brief Note About the Sample Apps The sample apps in this chapter are generally designed to run forever. It is unlikely that you really want them to run forever, though. Hence, please uninstall each sample after experimenting with it, particularly if you are testing on hardware, such as your personal phone. Your battery will appreciate it. Standard Intents as Event Bus You can think of the standard Intent and system as a threechannel event bus: 2105 EVENT BUS ALTERNATIVES • One channel is used for starting activities • One channel is used for starting or binding to services • One channel is used for more ad-hoc “broadcast” events The component starting an activity does not need to communicate directly with code for that activity — in fact, often times this is impossible, as they are separate apps running in separate processes. Instead, the component starting an activity sends an event indicating the particular operation to be performed (e.g., view this URL), and Android and the user determine which of candidate consumers is the one to process that event. However, broadcast Intent objects are a closer analogue to a real “event bus”, in that an event produced by somebody can be consumed by zero, one, or several subscribed consumers, based upon the filtering provided by elements in the manifest or IntentFilter objects for use with registerReceiver(). In theory, you could use broadcast Intent objects as the backbone for a fairly flexible event bus within your app. In practice, this is not usually a good idea: • Each broadcast involves inter-process communication (IPC), even if the event producer and consumer(s) are in the same process. This adds overhead. • Because broadcasts are intrinsically IPC, you have to take security into account, to ensure only authorized producers can publish events that the consumers pick up. However, if you specifically need a cross-process event bus, such as between a suite of related apps, using a broadcast Intent is a very likely choice. LocalBroadcastManager as Event Bus As was briefly noted earlier in the book, the Android Support package offers a LocalBroadcastManager. This is designed to offer an event bus with a feel very similar to classic broadcast Intent objects, but local to your process. Not only does this avoid IPC overhead, but it improves security, as other apps have no means of spying on your internal communications. LocalBroadcastManager is supplied by both the support-v4 and support-v13 libraries. Generally speaking, if your minSdkVersion is less than 13, you probably should choose support-v4. 2106 EVENT BUS ALTERNATIVES A Simple LocalBroadcastManager Sample Let’s see LocalBroadcastManager in action via the Intents/Local sample project. Here, our LocalActivity sends a command to a NoticeService from onCreate(): @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.main); notice=(TextView)findViewById(R.id.notice); startService(new new Intent(this this, NoticeService.class)); } (from Intents/Local/app/src/main/java/com/commonsware/android/localcast/LocalActivity.java) The NoticeService simply delays five seconds, then sends a local broadcast using LocalBroadcastManager: package com.commonsware.android.localcast; import import import import android.app.IntentService android.app.IntentService; android.content.Intent android.content.Intent; android.os.SystemClock android.os.SystemClock; android.support.v4.content.LocalBroadcastManager android.support.v4.content.LocalBroadcastManager; public class NoticeService extends IntentService { public static final String BROADCAST= "com.commonsware.android.localcast.NoticeService.BROADCAST"; private static Intent broadcast=new new Intent(BROADCAST); public NoticeService() { super super("NoticeService"); } @Override protected void onHandleIntent(Intent intent) { SystemClock.sleep(5000); LocalBroadcastManager.getInstance(this this).sendBroadcast(broadcast); } } (from Intents/Local/app/src/main/java/com/commonsware/android/localcast/NoticeService.java) 2107 EVENT BUS ALTERNATIVES Specifically, you get at your process’ singleton instance of LocalBroadcastManager by calling getInstance() on the LocalBroadcastManager class. Our LocalActivity registers for this local broadcast in onStart(), once again using getInstance() on LocalBroadcastManager: @Override public void onStart() { super super.onStart(); IntentFilter filter=new new IntentFilter(NoticeService.BROADCAST); LocalBroadcastManager.getInstance(this this).registerReceiver(onNotice, filter); } (from Intents/Local/app/src/main/java/com/commonsware/android/localcast/LocalActivity.java) LocalActivity unregisters for this broadcast in onStop(): @Override public void onStop() { super super.onStop(); LocalBroadcastManager.getInstance(this this).unregisterReceiver(onNotice); } (from Intents/Local/app/src/main/java/com/commonsware/android/localcast/LocalActivity.java) The BroadcastReceiver simply updates a TextView with the current date and time: private BroadcastReceiver onNotice=new new BroadcastReceiver() { public void onReceive(Context ctxt, Intent i) { notice.setText(new new Date().toString()); } }; (from Intents/Local/app/src/main/java/com/commonsware/android/localcast/LocalActivity.java) If you start up this activity, you will see a “(waiting...)” bit of placeholder text for about five seconds, before having that be replaced by the current date and time. The BroadcastReceiver, the IntentFilter, and the Intent being broadcast are the same as we would use with full broadcasts. It is merely how we are using them — via LocalBroadcastManager – that dictates they are local to our process versus the standard device-wide broadcasts. 2108 EVENT BUS ALTERNATIVES A More Elaborate Sample That sample is not terribly realistic, but it is simple. A somewhat more realistic sample is the one using WakefulIntentService from earlier in the book. However, that app was also fairly unrealistic, at least in terms of its output, as Logcat is not very useful to users. A more typical approach for a background service like this is to notify a foreground Activity, if there is one, about work that was accomplished, and otherwise display a Notification. We described that pattern in the chapter on Notifications. In the EventBus/LocalBroadcastManager sample project, we blend: • Having a service wake up every so often to do some work • Arranging to let the user know of background accomplishments via an Activity or a Notification • Using LocalBroadcastManager to keep the communications in-process The Activity The EventDemoActivity that is our app’s entry point is a bit similar to the one used in the WakefulIntentService demo, in that it calls scheduleAlarms() on PollReceiver to set up the AlarmManager schedule: package com.commonsware.android.eventbus.lbm; import android.app.Activity android.app.Activity; import android.os.Bundle android.os.Bundle; public class EventDemoActivity extends Activity { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); if (getFragmentManager().findFragmentById(android.R.id.content) == null null) { getFragmentManager().beginTransaction() .add(android.R.id.content, new EventLogFragment()).commit(); PollReceiver.scheduleAlarms(this this); } } } 2109 EVENT BUS ALTERNATIVES (from EventBus/LocalBroadcastManager/app/src/main/java/com/commonsware/android/eventbus/lbm/EventDemoActivity.java) However, we also put an EventLogFragment on the screen, if it is not already there, via a FragmentTransaction. This is where we will display events coming from the service, while our activity is in the foreground. We will examine EventLogFragment and how it participates in the event bus shortly. The PollReceiver PollReceiver is unchanged from its WakefulIntentService demo original edition. This BroadcastReceiver will be used both for getting control at boot time (to reschedule the alarms, wiped on the reboot) and for sending the work to the ScheduledService for processing: package com.commonsware.android.eventbus.lbm; import import import import import import import android.app.AlarmManager android.app.AlarmManager; android.app.PendingIntent android.app.PendingIntent; android.content.BroadcastReceiver android.content.BroadcastReceiver; android.content.Context android.content.Context; android.content.Intent android.content.Intent; android.os.SystemClock android.os.SystemClock; com.commonsware.cwac.wakeful.WakefulIntentService com.commonsware.cwac.wakeful.WakefulIntentService; public class PollReceiver extends BroadcastReceiver { private static final int PERIOD=15000; // 15 seconds private static final int INITIAL_DELAY=1000; // 1 second @Override public void onReceive(Context ctxt, Intent i) { if (i.getAction() == null null) { WakefulIntentService.sendWakefulWork(ctxt, ScheduledService.class); } else { scheduleAlarms(ctxt); } } static void scheduleAlarms(Context ctxt) { AlarmManager mgr= (AlarmManager)ctxt.getSystemService(Context.ALARM_SERVICE); Intent i=new new Intent(ctxt, PollReceiver.class); PendingIntent pi=PendingIntent.getBroadcast(ctxt, 0, i, 0); mgr.setRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP, SystemClock.elapsedRealtime() + INITIAL_DELAY, 2110 EVENT BUS ALTERNATIVES PERIOD, pi); } } (from EventBus/LocalBroadcastManager/app/src/main/java/com/commonsware/android/eventbus/lbm/PollReceiver.java) Note that on Android 5.1 and higher, despite the fact that we are asking for a 15-second polling period, the actual polling period will be one minute, as AlarmManager no longer supports sub-minute polling periods. ScheduledService and Sending Events Before, our ScheduledService just dumped a message to Logcat. This was crude but effective for what that demo required. Now, we want our service to let the UI layer know about some work that was accomplished, or to raise a Notification. In this case, the “work” is generating a random number. package com.commonsware.android.eventbus.lbm; import import import import import import import import import android.app.Notification android.app.Notification; android.app.NotificationManager android.app.NotificationManager; android.app.PendingIntent android.app.PendingIntent; android.content.Intent android.content.Intent; android.support.v4.app.NotificationCompat android.support.v4.app.NotificationCompat; android.support.v4.content.LocalBroadcastManager android.support.v4.content.LocalBroadcastManager; java.util.Calendar java.util.Calendar; java.util.Random java.util.Random; com.commonsware.cwac.wakeful.WakefulIntentService com.commonsware.cwac.wakeful.WakefulIntentService; public class ScheduledService extends WakefulIntentService { private static int NOTIFY_ID=1337; private Random rng=new new Random(); public ScheduledService() { super super("ScheduledService"); } @Override protected void doWakefulWork(Intent intent) { Intent event=new new Intent(EventLogFragment.ACTION_EVENT); long now=Calendar.getInstance().getTimeInMillis(); int random=rng.nextInt(); event.putExtra(EventLogFragment.EXTRA_RANDOM, random); 2111 EVENT BUS ALTERNATIVES event.putExtra(EventLogFragment.EXTRA_TIME, now); if (!LocalBroadcastManager.getInstance(this this).sendBroadcast(event)) { NotificationCompat.Builder b=new new NotificationCompat.Builder(this this); Intent ui=new new Intent(this this, EventDemoActivity.class); b.setAutoCancel(true true).setDefaults(Notification.DEFAULT_SOUND) .setContentTitle(getString(R.string.notif_title)) .setContentText(Integer.toHexString(random)) .setSmallIcon(android.R.drawable.stat_notify_more) .setTicker(getString(R.string.notif_title)) .setContentIntent(PendingIntent.getActivity(this this, 0, ui, 0)); NotificationManager mgr= (NotificationManager)getSystemService(NOTIFICATION_SERVICE); mgr.notify(NOTIFY_ID, b.build()); } } } (from EventBus/LocalBroadcastManager/app/src/main/java/com/commonsware/android/eventbus/lbm/ScheduledService.java) LocalBroadcastManager, as we have seen, uses the same Intent and IntentFilter and BroadcastReceiver structures as are used with regular broadcasts, just via a singleton message bus (LocalBroadcastManager.getInstance()) instead of the framework’s IPC engine. Hence, we need an Intent that represents the message, so we create one, using an action string published by the EventLogFragment. We also attach two extras to this Intent, using keys published by EventLogFragment: the random number, plus the time of this event. We then call sendBroadcast() on the singleton LocalBroadcastManager. This returns a boolean value, true indicating that one or more locally-registered receivers were delivered the Intent, false otherwise. Hence, if sendBroadcast() returns true, we can assume that somebody in the UI layer picked up our message and is now responsible for displaying these results to the user. Conversely, if sendBroadcast() returns false, we must assume that the UI layer did not receive the message, and so the service should inform the user directly, in this case via a Notification, showing the random number as the text in the notification drawer. 2112 EVENT BUS ALTERNATIVES EventLogFragment and Receiving Events EventLogFragment, therefore, is responsible for: • Registering (and unregistering) to receive the broadcasts to be sent locally by the service • Doing something with those events to inform the user about the allimportant random numbers In this case, we use a retained ListFragment with a ListView set into transcript mode, meaning that entries are added at the bottom, and older entries scroll off the top, like a chat transcript: package com.commonsware.android.eventbus.lbm; import import import import import import import import import import import import import import import import import import android.annotation.SuppressLint android.annotation.SuppressLint; android.app.ListFragment android.app.ListFragment; android.content.BroadcastReceiver android.content.BroadcastReceiver; android.content.Context android.content.Context; android.content.Intent android.content.Intent; android.content.IntentFilter android.content.IntentFilter; android.os.Bundle android.os.Bundle; android.support.v4.content.LocalBroadcastManager android.support.v4.content.LocalBroadcastManager; android.view.View android.view.View; android.view.ViewGroup android.view.ViewGroup; android.widget.ArrayAdapter android.widget.ArrayAdapter; android.widget.ListView android.widget.ListView; android.widget.TextView android.widget.TextView; java.text.DateFormat java.text.DateFormat; java.text.SimpleDateFormat java.text.SimpleDateFormat; java.util.ArrayList java.util.ArrayList; java.util.Date java.util.Date; java.util.Locale java.util.Locale; public class EventLogFragment extends ListFragment { static final String EXTRA_RANDOM="r"; static final String EXTRA_TIME="t"; static final String ACTION_EVENT="e"; private EventLogAdapter adapter=null null; @Override public void onActivityCreated(Bundle state) { super super.onActivityCreated(state); setRetainInstance(true true); getListView().setTranscriptMode(ListView.TRANSCRIPT_MODE_NORMAL); 2113 EVENT BUS ALTERNATIVES if (adapter == null null) { adapter=new new EventLogAdapter(); } setListAdapter(adapter); } @Override public void onStart() { super super.onStart(); IntentFilter filter=new new IntentFilter(ACTION_EVENT); LocalBroadcastManager.getInstance(getActivity()) .registerReceiver(onEvent, filter); } @Override public void onStop() { LocalBroadcastManager.getInstance(getActivity()) .unregisterReceiver(onEvent); super super.onStop(); } class EventLogAdapter extends ArrayAdapter { DateFormat fmt=new new SimpleDateFormat("HH:mm:ss", Locale.US); public EventLogAdapter() { super super(getActivity(), android.R.layout.simple_list_item_1, new ArrayList()); } @SuppressLint("DefaultLocale") @Override public View getView(int position, View convertView, ViewGroup parent) { TextView row= (TextView)super super.getView(position, convertView, parent); Intent event=getItem(position); Date date=new new Date(event.getLongExtra(EXTRA_TIME, 0)); row.setText(String.format("%s = %x", fmt.format(date), event.getIntExtra(EXTRA_RANDOM, -1))); return return(row); } } 2114 EVENT BUS ALTERNATIVES private BroadcastReceiver onEvent=new new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { adapter.add(intent); } }; } (from EventBus/LocalBroadcastManager/app/src/main/java/com/commonsware/android/eventbus/lbm/EventLogFragment.java) The ListAdapter for the ListView is an EventLogAdapter, an ArrayAdapter for Intent objects, where in getView() we populate the list rows with the time and random value. In onStart() and onStop(), we register for (and unregister from) the desired broadcast, pointing to an onEvent BroadcastReceiver that adds the incoming Intent to the EventLogAdapter. That, in turn, updates the ListView. The result is that while the activity is in the foreground, the events will be displayed to the user directly: Figure 683: LocalBroadcastManager as Event Bus, Demo Activity 2115 EVENT BUS ALTERNATIVES Whereas if events are processed while the activity is not in the foreground, a Notification will be shown with the last results: Figure 684: LocalBroadcastManager as Event Bus, Demo Notification Reference, Not Value When you send a “real” broadcast Intent, your Intent is converted into a byte array (courtesy of the Parcelable interface) and transmitted to other processes. This occurs even if the recipient of the Intent is within your own process — that is what makes LocalBroadcastManager faster, as it avoids the inter-process communication. However, since LocalBroadcastManager does not need to send your Intent between processes, that means it does not turn your Intent into a byte array. Instead, it just passes the Intent along to any registered BroadcastReceiver with a matching IntentFilter. In effect, while “real” broadcasts are pass-by-value, local broadcasts are pass-by-reference. This can have subtle side effects. For example, there are a few ways that you can put a collection into an Intent extra, such as putStringArrayListExtra(). This takes an ArrayList as a parameter. With 2116 EVENT BUS ALTERNATIVES a real broadcast, once you send the broadcast, it does not matter what happens to the original ArrayList — the rest of the system is working off of a copy. With a local broadcast, though, the Intent holds onto the ArrayList you supplied via the setter. If you change that ArrayList elsewhere (e.g., clear it for reuse), the recipient of the Intent will see those changes. Similarly, if you put a Parcelable object in an extra, the Intent holds onto the actual object while it is being broadcast locally, whereas a real broadcast would have resulted in a copy. If you change the object while the broadcast is in progress, the recipient of the broadcast will see those changes. This can be a feature, not a bug, when used properly. But, regardless, it is a nontrivial difference, one that you will need to keep in mind. Limitations of Local While LocalBroadcastManager is certainly useful, it has some serious limitations. The biggest is that it is purely local. While traditional broadcasts can either be internal (via setPackage()) or device-wide, LocalBroadcastManager only handles the local case. Hence, anything that might involve other processes, such as a PendingIntent, will not use LocalBroadcastManager. For example, you cannot register a receiver through LocalBroadcastManager, then use a getBroadcast() PendingIntent to try to reach that BroadcastReceiver. The PendingIntent will use the regular broadcast Intent mechanism, which the local-only receiver will not respond to. Similarly, since a manifest-registered BroadcastReceiver is spawned via the operating system upon receipt of a matching true broadcast, you cannot use such receivers with LocalBroadcastManager. Only a BroadcastReceiver registered via registerReceiver() on the LocalBroadcastManager will use the LocalBroadcastManager. For example, you cannot implement the Activityor-Notification pattern that we will see later in this book via LocalBroadcastManager. Also, LocalBroadcastManager does not offer ordered or sticky broadcasts. greenrobot’s EventBus 3.x LocalBroadcastManager has two major advantages: 2117 EVENT BUS ALTERNATIVES 1. It is part of the Android Support package, and therefore it is part of the officially-supported corner of the Android ecosystem 2. It works like traditional broadcasts, which will make it easier for some developers to “wrap their heads around” it However, that same dependency on the Intent and IntentFilter structure adds bulk and limits flexibility. Hence, it is not surprising that there are alternative event buses to LocalBroadcastManager. Java, outside of Android, has had a few event bus implementations. One of the more popular ones in recent years has been the event bus that is part of Google’s Guava family of libraries. However, while a Java event bus perhaps can be used on Android, it may not be optimal for Android. Hence, a few projects have started with Guava’s event bus implementation and have extended it to be a bit more Android-aware, or perhaps even Android-centric. greenrobot’s EventBus is one such event bus. NOTE: For the purposes of this chapter, “greenrobot’s EventBus” refers to the library, and “EventBus”" refers to the EventBus Java class in that library. Basic Usage and Sample App With LocalBroadcastManager, you work with a singleton instance, calling methods like registerReceiver() and sendBroadcast() upon it to subscribe to and raise events, respectively. With greenrobot’s EventBus, you work with an EventBus instance, calling methods like register() and post() upon it to subscribe to and raise events, respectively. Usually, we use the singleton instance of EventBus that we get by calling getDefault() on the EventBus class, but you are welcome to have different EventBus objects, representing distinct communications channels, if you wish. Hence, at the core, greenrobot’s EventBus behaves much like LocalBroadcastManager. What differs is in the nature of the events and the subscribers. With LocalBroadcastManager, events are Intent objects. With greenrobot’s EventBus, an event can be whatever data type you like. Hence, you can create your own ...Event classes, holding whatever bits of data, in whatever data types suit you — you are not restricted to things that can go in an Intent extra. However, as has 2118 EVENT BUS ALTERNATIVES been noted on occasion, “with great power comes great responsibility”, and so you will need to ensure that you use this carefully and do not wind up creating some sort of memory leak as a result. For example, do not pass something from an Activity to a Service via a custom event, where the Service will hold onto that information for a long time, if that “something” holds a reference back to the Activity. With LocalBroadcastManager, subscribers are BroadcastReceivers, who use an IntentFilter to identify which events they are interested in. With greenrobot’s EventBus, subscribers are any class you want. A special @Subscribe annotation is used to both indicate what sorts of events the subscriber is interested in (based on the parameter to the annotated method) and what method should be invoked when a matching event is raised (the annotated method itself ). Hence, not only do you use custom event classes to allow you to carry along custom data, but you use them as a filtering mechanism, much like you would use custom action strings with LocalBroadcastManager. To see how this works, take a look at the EventBus/GreenRobot3 sample project, which is a clone of the EventBus/LocalBroadcastManager demo, but one where we substitute in greenrobot’s EventBus as a replacement for LocalBroadcastManager. Our activity and PollReceiver are unchanged: they did not directly interact with LocalBroadcastManager and do not need to interact with greenrobot’s EventBus. The changes are isolated in our ScheduledService and EventLogFragment. NOTE: This sample app uses a 3.x version of greenrobot’s EventBus. This came with a significant API change from the previous 2.x generation. We will examine the 2.x version later in this chapter. ScheduledService and Sending Events We will need an EventBus instance, one that serves the same basic role as does the singleton LocalBroadcastManager retrieved by getInstance(). As noted above, you can call getDefault() on EventBus to get a singleton EventBus instance, and this suffices in most cases. When it comes time for us to send a message, we can call post() on the EventBus, supplying whatever sort of event object that we want: @Override protected void doWakefulWork(Intent intent) { EventBus.getDefault().post(new new RandomEvent(rng.nextInt())); } 2119 EVENT BUS ALTERNATIVES (from EventBus/GreenRobot3/app/src/main/java/com/commonsware/android/eventbus/greenrobot/ScheduledService.java) Here, we are posting an instance of a RandomEvent: package com.commonsware.android.eventbus.greenrobot; import java.util.Calendar java.util.Calendar; import java.util.Date java.util.Date; public class RandomEvent { Date when=Calendar.getInstance().getTime(); int value; RandomEvent(int value) { this this.value=value; } } (from EventBus/GreenRobot3/app/src/main/java/com/commonsware/android/eventbus/greenrobot/RandomEvent.java) EventLogFragment and Receiving Events Over in our EventLogFragment, rather than register and unregister a BroadcastReceiver in onStart() and onStop(), we register and unregister the fragment itself with the EventBus: @Override public void onStart() { super super.onStart(); EventBus.getDefault().register(this this); } @Override public void onStop() { EventBus.getDefault().unregister(this this); super super.onStop(); } (from EventBus/GreenRobot3/app/src/main/java/com/commonsware/android/eventbus/greenrobot/EventLogFragment.java) Now, we can use the @Subscribe annotation to arrange to receive any event we want that is delivered via this EventBus, based on event class. Since we want to receive RandomEvent messages, we merely need to have a public void method, taking a 2120 EVENT BUS ALTERNATIVES RandomEvent parameter, onRandomEvent(): marked with the @Subscribe annotation, such as @Subscribe(threadMode = ThreadMode.MAIN) public void onRandomEvent(final final RandomEvent event) { adapter.add(event); } (from EventBus/GreenRobot3/app/src/main/java/com/commonsware/android/eventbus/greenrobot/EventLogFragment.java) Note that the method name can be anything we want, as it is the annotation, not the method name, that identifies this as being an event handling method. Since Java annotations can take key-value pairs for configuration, EventBus 3.x uses that to configure the behavior of @Subscribe. Here, we use @Subscribe(threadMode = ThreadMode.MAIN), to indicate that we want this event to be delivered to this method on the main application thread. In this method, we can do what we need to with our RandomEvent. In our case, EventLogAdapter has been modified to be an ArrayAdapter of RandomEvent, as opposed to being an ArrayAdapter of Intent as in the earlier sample. What we want to do is append the new RandomEvent to the end of the adapter. Handling the “Nobody’s Home” Scenario What is missing, though, is the logic we used in LocalBroadcastManager to determine if somebody received our message, where we raised a Notification if that is not the case. The solution for this with greenrobot’s EventBus is to have ScheduledService listen for NoSubscriberEvent events. A NoSubscriberEvent is delivered on the bus when an attempt to deliver some other event failed with no subscribers. The NoSubscriberEvent has an originalEvent field that contains the original event that failed to be delivered. If we can get the NoSubscriberEvent, we know the RandomEvent was not handled at the UI layer, and we can raise the Notification. To do this, not only do we need to register EventLogFragment with the Bus, but we also need to register ScheduledService itself, so it can listen for a NoSubscriberEvent: @Override public void onCreate() { 2121 EVENT BUS ALTERNATIVES super super.onCreate(); EventBus.getDefault().register(this this); } (from EventBus/GreenRobot3/app/src/main/java/com/commonsware/android/eventbus/greenrobot/ScheduledService.java) @Override public void onDestroy() { EventBus.getDefault().unregister(this this); super super.onDestroy(); } (from EventBus/GreenRobot3/app/src/main/java/com/commonsware/android/eventbus/greenrobot/ScheduledService.java) Then, our Notification logic can be moved into some method that has the @Subscribe annotation and a NoSubscriberEvent parameter: @Subscribe public void onNoSubscriber(NoSubscriberEvent event) { RandomEvent randomEvent=(RandomEvent)event.originalEvent; NotificationCompat.Builder b=new new NotificationCompat.Builder(this this); Intent ui=new new Intent(this this, EventDemoActivity.class); b.setAutoCancel(true true).setDefaults(Notification.DEFAULT_SOUND) .setContentTitle(getString(R.string.notif_title)) .setContentText(Integer.toHexString(randomEvent.value)) .setSmallIcon(android.R.drawable.stat_notify_more) .setTicker(getString(R.string.notif_title)) .setContentIntent(PendingIntent.getActivity(this this, 0, ui, 0)); NotificationManager mgr= (NotificationManager)getSystemService(NOTIFICATION_SERVICE); mgr.notify(NOTIFY_ID, b.build()); } (from EventBus/GreenRobot3/app/src/main/java/com/commonsware/android/eventbus/greenrobot/ScheduledService.java) Other Notable Capabilities In addition to the threading features, greenrobot’s EventBus has a few other noteworthy bells and whistles: • Other thread modes are available, including ThreadMode.POSTING (events are delivered on the same thread they are posted from) and 2122 EVENT BUS ALTERNATIVES ThreadMode.BACKGROUND (events are delivered on a background thread, EventBus using its own thread if the event was posted from the main with application thread). • postSticky() and registerSticky() allow you to have sticky events, much like sticky broadcasts with the classic broadcast Intent system. • Ordered event processing as an option, akin to ordered broadcasts. You accomplish this by assigning a priority to the event handling method (e.g., @Subscribe(priority = 1)). If a higher-priority handler wants to consume the event, it can call cancelEventDelivery() on the EventBus, passing in the event object. greenrobot’s EventBus 2.x greenrobot’s EventBus came of age with the 2.x version series. However, they made a few changes of note with the new 3.x API. If you are looking at projects using the older library, you will see these changes. Package Changes The org.greenrobot:eventbus artifact is for the 3.x generation of the library. de.greenrobot:eventbus was used previously. So, if you see a project referring to de.greenrobot:eventbus, you know that it is using the older library: dependencies { implementation 'de.greenrobot:eventbus:2.4.0' implementation 'com.android.support:support-v13:21.0.3' implementation 'com.commonsware.cwac:wakeful:1.0.+' } This also affects the Java package used for the classes: 2.x classes were in de.greenrobot, while 3.x classes are in org.greenrobot. Magic Method Names Version 3.x of the greenrobot EventBus API uses the @Subscribe annotation. Version 2.x did not. Instead, your event handling method had to be named onEvent(), or some variation of it to indicate the thread mode (e.g., onEventMainThread()). greenrobot’s EventBus would look up the methods matching this naming scheme and use those as event handlers, rather than look up methods using the @Subscribe annotation. 2123 EVENT BUS ALTERNATIVES Hey, What About Otto? For a few years, a third major event bus implementation was popular: Square’s Otto. Like greenrobot’s EventBus, Otto was based off of Guava’s EventBus class and was tuned towards Android app development. It shared some characteristics with greenrobot’s EventBus, owing to the shared heritage. On the whole, greenrobot’s EventBus was a bit more complex to use but offered greater flexibility. Square has since discontinued work on Otto, so unless you have existing legacy code that uses Otto, you should use some other event bus implementation. 2124 Tasks One of the most confusing aspects of Android to deal with is the concept of tasks. Fortunately, the automatic management of tasks is almost enough to get by, without you having to do much customization. However, many apps will have needs to tailor how their app interacts with the task system, and understanding what is possible and how to do it is not easy. It is made even more complicated by changes to Android, from both engineering and design perspectives, over the years. This chapter will attempt to untie the knot of knowledge surrounding Android’s task system, explaining why things are the way they are. However, there will be a few places where the knot turns a bit Gordian, and we will have to settle for more about “how” and less about “why” the task system works as it does. Prerequisites Understanding this chapter requires that you have read the core chapters of this book. One sample app makes heavy use of the PackageManager system service and refers in a few places to the Launchalot sample app profiled in that chapter. First, Some Terminology It will be useful to establish some common definitions of terms that you will encounter, both in this chapter and in other materials that describe the task system. 2125 TASKS Task So, what exactly is a “task”? The Android developer documentation describes it as: A task is a collection of activities that users interact with when performing a certain job. The activities are arranged in a stack (the back stack), in the order in which each activity is opened. In that sense, a task is reminiscent of a tab in a tabbed browser. As the user navigates, clicking links and submitting forms, the user advances into other Web pages. Those pages could be on the same site as they started or could be on different sites. The browser BACK button is supposed to reverse the navigation, allowing the user to return from whence they came. Back Stack The user perceives tasks mostly in the form of pressing the BACK button, using this to return to previous “screens” that they had been on previously. Sometimes, BACK button processing is handled within a single activity, such as when you put a dynamic fragment onto the “back stack” via addToBackStack() on a FragmentTransaction. Or, the activity could override onBackPressed() and do special stuff in certain scenarios. Those are part of the user experience of pressing BACK. From the standpoint of the task system, though, internal consumption of the BACK button presses do not affect the task. At the task level, the “back stack” refers to a chain of activities. This matches the behavior of Web sites, where while pressing the browser BACK button might trigger in-page behavior, usually it returns you to the previous page. Similarly, while pressing BACK on an Android device might trigger in-activity behavior, usually it triggers a call to finish() on the foreground activity and returns control to whatever had preceded it on the back stack. Recent Tasks In a tabbed Web browser, if we have several tabs open, we think of all of them as being “running”. Frequently, we do not really even think about the concept, any more than we might think about the state of tabs in an IDE other than the one that 2126 TASKS we are working in right now. However, if you have ever had some browser tab all of a sudden start playing audio, such as from a reloaded page pulling in an audioenabled ad banner, you are well aware that tabs are “running”, while you are also “running” to try to figure out what tab is playing the audio so you can get rid of it. However, that is the behavior on a desktop Web browser. A desktop Web browser is not subject to heap size limitations the way Android apps are. And, historically, mobile devices had less system RAM than did their desktop and notebook counterparts, though that is rapidly changing. In Android, therefore, developers are used to the notion that their processes may be terminated, while in the background, to free up memory for other processes. This is being done to allow for more apps to deliver more value in less system RAM. However, from a multitasking standpoint, having apps just up and vanish is awkward. Hence, Android has the notion of “recent tasks”. These are tasks, with their corresponding back stacks, that the user has been in “recently”. How far back “recently” goes depends a bit on the version of Android – there could be as few as eight items. These “recent tasks” may or may not have a currently-running process associated with them. However, if the user chooses to return to one of those recent tasks, and there is no process for it, Android will seamlessly fork a fresh process, to be able to not only start up those apps, but return the user to where they were, in terms of UI contents (e.g., saved instance state Bundle) and in terms of back stack contents (e.g., where the user goes if the user now presses BACK). Overview Screen In a tabbed Web browser, you can navigate between different tabs in some browserspecific way. Some tabs may have the actual “tab” visible around the address bar. Some tabs might only be reachable via some sort of scrolling operation, or via a drop-down list, for people who have lots and lots of tabs open. Regardless, there is some UI means to pick the tab that you want to be viewing in the main browser area. In Android, the “overview screen” is where the user can view the recent tasks and choose to return to one of them. Many people, including this author, refer to this as the “recent tasks list”, but apparently the official term is “overview screen”. The way the overview screen has looked and worked has changed over the years. 2127 TASKS Android 1.x/2.x In the early days of Android, long-pressing the HOME button would bring up the overview screen, with up to eight recent tasks: Figure 685: Overview Screen, from Android 2.3.3 And… that was pretty much it. Android 3.x/4.x The overall move to the holographic theme for Android brought with us a new icon, for a dedicated way to get to the overview screen: Figure 686: Overview Screen/Recent Tasks Navigation Bar Icon, from Android 4.3 Devices that offered a navigation bar at the bottom would have this button. Devices that chose to have off-screen affordances for BACK and HOME might have a similar button for the overview screen. For those that neither had a navigation bar nor a dedicated off-screen button for the overview screen, long-pressing HOME would bring up the overview screen. The overview screen could have more apps (15 or so) before old tasks would be dropped: 2128 TASKS Figure 687: Overview Screen, from Android 4.3 The overview screen also added more improvements: • Thumbnails of the top activity in each task’s back stack, except for those activities that used FLAG_SECURE to block this, and except on some emulator images • Swiping an entry off the list would remove that recent task Android 5.x Functionally, the Android 5.x overview screen functions much like its 4.x counterpart, with the ability to see previews of tasks and remove tasks from the screen. However, there are some differences, starting with the navigation bar icon used to bring up the overview screen: 2129 TASKS Figure 688: Overview Screen/Recent Tasks Navigation Bar Icon, from Android 5.0 Also, the previews are larger and stacked like cards, more so than being a classically vertically-scrolling list: Figure 689: Overview Screen, from Android 5.0 More importantly: • The roster of recent tasks will be restored after a reboot, and 2130 TASKS • If there is a limit on how many entries can appear in the list, the author has not run into it yet Running Tasks A running task is a task that has running process(es) associated with it. Recent tasks may or may not be running. And Now, a Bit About Task Killers In October 2008, the first Android device was publicly released (the T-Mobile G1, a.k.a., HTC Dream). Around December of 2008, the first task killers appeared on the Android Market (now the Play Store). While the techniques used in 2008 to kill tasks were removed in later releases, some amount of task management behavior still exists in Android. Having a task killer is useful for understanding how tasks (and their killers) behave on Android. In particular, it is useful to have a way to emulate an app’s process being terminated due to low memory conditions… which is exactly what modern task killers do. So, in this section, we will explore the concept of task killers, including how to implement one, before using this tool to help us explore the overall Android task system. What Do Task Killers Do? Despite the name, task killers do not kill tasks. Rather, task killers terminate background processes. This does not impact the task, insofar as it will still be in the recent tasks roster and will still show up on the overview screen. However, the process for the app associated with the task will shut down. Task killers can only request to terminate background processes. If your app is in the foreground (i.e., has the foreground activity), you cannot be terminated by a task killer. 2131 TASKS To terminate background processes, task killers need to hold the KILL_BACKGROUND_PROCESSES permission, via a element in their manifests. That enables them to be able to call the killBackgroundProcesses() method on ActivityManager. Supplied an application ID, killBackgroundProcesses() will terminate any background process(es) associated with that application. Normally, there will only be one such process, but if the app in question is using the android:process attribute in the manifest to have multiple processes, then all the app’s processes will be terminated. This termination is done using the same internal mechanism that is used by the “out-of-memory killer”, which is responsible for freeing up system RAM due to low memory conditions. Killing vs. Force-Stopping For ordinary users, there are a few options for terminating background processes. Using a task killer, or swiping the task off the overview screen on Android 4.0+, will terminate background processes. Both use killBackgroundProcesses() (or internal equivalents). However, users can also go into the Settings app, find the app in the list of installed apps, and click a “Force Stop” button associated with that app. On the surface, this has a similar effect to the above techniques, as the background process is terminated. However, force-stopping the app also unschedules any AlarmManager or JobScheduler events for that app, plus moves the app back into the “stopped state”, blocking manifest-registered broadcast receivers. Hence, force-stopping an app has a much larger impact than does merely using a task killer. A few devices have manufacturer-supplied task managers (a.k.a., task killers), where stopping an app from those apps actually does a force stop behind the scenes, rather than killBackgroundProcesses(). This is not a good idea, as force-stopping an app has the aforementioned side effects. Fortunately, third-party task killers cannot force-stop apps, barring any security flaws in Android that might make this possible. Why Use One? Nowadays, normally, users do not need task killers. Occasionally one can be useful, to stop a background process for a poorly-written app (e.g., one that powers on GPS but fails to let go of GPS when the app moves to the background). On most modern Android devices, swiping the app off the overview screen usually suffices, and so 2132 TASKS task killers are not nearly as crucial as they were in Android 1.x/2.x, where there was no such built-in background process management solution. For developers, the problem with swiping an app off the overview screen is that it not only terminates background processes, but it also removes the task entirely. This makes it difficult to see what the behavior is when apps’ processes terminate for more conventional reasons (e.g., out-of-memory killer) and how tasks tie into that. While developers have the ability to stop processes through development tools (e.g., the process list in DDMS), that just terminates the process, and it may do so slightly differently than does the out-of-memory killer. Hence, having a task killer around can be useful for experimentation purposes. And, since getting a task killer on an emulator can be challenging (since emulators do not have access to the Play Store), having the source code for a simple task killer is useful for developers. So, let’s look at how to implement a task killer. A Killer Sample The Tasks/Nukesalot sample application implements the Nukesalot app. This is a reworked version of the Launchalot sample from elsewhere in the book. Launchalot lists the launchable activities and lets the user launch those activities by clicking on them in a ListView. Nukesalot lists the running applications and allows the user to kill those applications’ background processes by clicking on them in a ListView. Finding Killable Apps First, we need to find apps that are eligible to be killed. In onCreate() of the MainActivity, we get our hands on an ActivityManager system service. ActivityManager is not strictly tied to the UI construct known as activities, but rather to general “activity” of the user with respect to the device. @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.main); am=(ActivityManager)getSystemService(ACTIVITY_SERVICE); } (from Tasks/Nukesalot/app/src/main/java/com/commonsware/android/nukesalot/Nukesalot.java) 2133 TASKS In onResume(), we then call a private buildAdapter() method to create an instance of an AppAdapter for us: @Override public void onResume() { super super.onResume(); adapter=buildAdapter(); setListAdapter(adapter); } (from Tasks/Nukesalot/app/src/main/java/com/commonsware/android/nukesalot/Nukesalot.java) We do this in onResume() so that when our activity returns to the foreground, it shows a fresh list of running apps. This activity lacks the ability to detect new running processes on the fly, something that could be addressed by a manual refresh option (e.g., action bar item). The implementation of this is left as an exercise for the reader. buildAdapter() needs to find out the application ID (a.k.a., package name) of the running applications. It would be easier to list all applications, but there is little point in listing apps that cannot be killed simply because they are not running. The roster of application IDs of the running apps is a HashSet named runningPackages, initially empty: private AppAdapter buildAdapter() { HashSet runningPackages=new new HashSet(); for (ActivityManager.RunningAppProcessInfo proc : am.getRunningAppProcesses()) { for (String pkg : proc.pkgList) { runningPackages.add(pkg); } } PackageManager pm=getPackageManager(); List apps=new new ArrayList(); for (ApplicationInfo app : pm.getInstalledApplications(0)) { if (runningPackages.contains(app.packageName)) { apps.add(app); } } Collections.sort(apps, new ApplicationInfo.DisplayNameComparator(pm)); 2134 TASKS return return(new new AppAdapter(pm, apps)); } (from Tasks/Nukesalot/app/src/main/java/com/commonsware/android/nukesalot/Nukesalot.java) We then iterate over the running application processes, obtained via a call to getRunningAppProcesses() on the ActivityManager. In theory (though it is unclear how this works in practice), a running app process could hold code from multiple packages. We find out those packages via the pkgList in each RunningAppProcessInfo object that we get back from getRunningAppProcesses(). We then iterate over the strings in pkgList and add each to runningPackages. Next, in order to display icons and names for these apps, we really need ApplicationInfo objects for each app. Plus, it would be nice if these were in some logical order. So, we get a PackageManager, create an ArrayList of ApplicationInfo objects named apps, and iterate over all installed applications (via getInstalledApplications() on PackageManager). For each app, if its package name (via the packageName attribute on the ApplicationInfo) is in our runningPackages, we add the ApplicationInfo to the ArrayList. We then sort the ArrayList using an ApplicationInfo.DisplayNameComparator convenience class provided by the Android SDK, which will sort ApplicationInfo arrays based on the display name. We then wrap the ApplicationInfo list in an AppAdapter and return it. Displaying Killable Apps AppAdapter itself is an ArrayAdapter for ApplicationInfo objects, designed to render them in rows containing the app’s icon and display name: 2135 TASKS (from Tasks/Nukesalot/app/src/main/res/layout/row.xml) AppAdapter steals a page from CursorAdapter and has getView() delegate to newView() and bindView() methods. newView() is called when there is no row to recycle, and it just inflates the row layout. bindView() uses PackageManager to populate the icon and display name widgets using loadIcon() and loadLabel() calls: class AppAdapter extends ArrayAdapter { private PackageManager pm=null null; AppAdapter(PackageManager pm, List apps) { super super(Nukesalot.this, R.layout.row, apps); this this.pm=pm; } @Override public View getView(int position, View convertView, ViewGroup parent) { if (convertView==null null) { convertView=newView(parent); } bindView(position, convertView); return return(convertView); } private View newView(ViewGroup parent) { return return(getLayoutInflater().inflate(R.layout.row, parent, false false)); } private void bindView(int position, View row) { TextView label=(TextView)row.findViewById(R.id.label); label.setText(getItem(position).loadLabel(pm)); 2136 TASKS ImageView icon=(ImageView)row.findViewById(R.id.icon); icon.setImageDrawable(getItem(position).loadIcon(pm)); } } (from Tasks/Nukesalot/app/src/main/java/com/commonsware/android/nukesalot/Nukesalot.java) loadIcon() and loadLabel() are methods on ApplicationInfo that, given a PackageManager, can find the proper resources for those items and retrieve them from the foreign app’s package. The result is a ListView filled with running apps… including Nukesalot itself: Figure 690: Nukesalot, on Android 5.0 That App Needed Killin’ The idea is that when the user taps on a row in the list, Nukesalot will go and terminate that app’s process. So, in onListItemClick(), we determine the ApplicationInfo of the clicked-upon app, and call killBackgroundProcesses() on that app’s package name. Then, we refresh the adapter, to show the updated roster of running apps: 2137 TASKS @Override protected void onListItemClick(ListView l, View v, int position, long id) { ApplicationInfo app=adapter.getItem(position); am.killBackgroundProcesses(app.packageName); adapter=buildAdapter(); setListAdapter(adapter); } (from Tasks/Nukesalot/app/src/main/java/com/commonsware/android/nukesalot/Nukesalot.java) killBackgroundProcesses() requires the KILL_BACKGROUND_PROCESSES permission, which we have in the manifest: /> If you tap on a row for some ordinary Android app, other than Nukesalot itself, that process will be terminated. However: • Nukesalot cannot kill itself, as it is not a background process, but rather is the foreground process. In principle, we could detect this case, finish() the activity, and fork a background thread to call killBackgroundProcesses() after a short delay to ensure that our process is categorized as a background process. In practice, that seems like an awful lot of work for a book example. • Some system processes (e.g., “Android System”) simply cannot be killed using killBackgroundProcesses(). More importantly, from the standpoint of this chapter, is that killing a background process using Nukesalot does not disturb the recent-tasks list. Our task still shows up there, even though we terminated the process for it, and that will be useful as we examine the behavior of Android’s task system. A Canary for the Task’s Coal Mine In order to see some of the effects of fussing with our tasks, we need an app where we can see when our saved instance state comes and goes. To that end, we have the Tasks/TaskCanary sample application. It consists of a single activity, with a UI that is merely a full-screen EditText. In addition to the automatic saving of the EditText contents in the saved instance state Bundle, we also keep track of the time we first worked with that Bundle, in a data member named creationTime, backed by a STATE_CREATION_TIME entry in the Bundle itself: 2138 TASKS package com.commonsware.android.task.canary; import import import import import import import android.app.Activity android.app.Activity; android.content.Intent android.content.Intent; android.os.Bundle android.os.Bundle; android.provider.Settings android.provider.Settings; android.util.Log android.util.Log; android.view.Menu android.view.Menu; android.view.MenuItem android.view.MenuItem; public class MainActivity extends Activity { private static final String STATE_CREATION_TIME="creationTime"; private long creationTime=-1L; @Override public void onCreate(Bundle state) { super super.onCreate(state); setContentView(R.layout.activity_main); } @Override protected void onRestoreInstanceState(Bundle savedInstanceState) { super super.onRestoreInstanceState(savedInstanceState); dumpBundleToLog("restore", savedInstanceState); creationTime=savedInstanceState.getLong(STATE_CREATION_TIME, -1L); } @Override protected void onSaveInstanceState(Bundle outState) { super super.onSaveInstanceState(outState); outState.putLong(STATE_CREATION_TIME, getCreationTime()); dumpBundleToLog("save", outState); } @Override public boolean onCreateOptionsMenu(Menu menu) { getMenuInflater().inflate(R.menu.actions, menu); return return(super super.onCreateOptionsMenu(menu)); } @Override public boolean onOptionsItemSelected(MenuItem item) { if (item.getItemId()==R.id.settings) { startActivity(new new Intent(Settings.ACTION_DATE_SETTINGS)); } 2139 TASKS else if (item.getItemId()==R.id.other) { startActivity(new new Intent(this this, OtherActivity.class)); } return return(super super.onOptionsItemSelected(item)); } private long getCreationTime() { if (creationTime==-1L) { creationTime=System.currentTimeMillis(); } return return(creationTime); } // inspired by http://stackoverflow.com/a/14948713/115145 private void dumpBundleToLog(String msg, Bundle b) { Log.d(getClass().getSimpleName(), String.format("Task ID #%d", getTaskId())); for (String key: b.keySet()) { Log.d(getClass().getSimpleName(), String.format("(%s) %s: %s", msg, key, b.get(key))); } } } (from Tasks/TaskCanary/app/src/main/java/com/commonsware/android/task/canary/MainActivity.java) Each time we save and restore the instance state, we dump the Bundle to Logcat, so we can see what is in that Bundle. We wind up with lines like: D/MainActivity: D/MainActivity: D/MainActivity: D/MainActivity: (save) android:viewHierarchyState: Bundle[...] (save) creationTime: 1427032894794 (restore) android:viewHierarchyState: Bundle[...] (restore) creationTime: 1427032894794 (where the ... is a bit long to reproduce in the book and is not essential for the sample) This way, both in the UI and in the logs, we can confirm that our state is being saved and restored as expected… or perhaps not as expected, in some cases. You will notice that we have a pair of action bar items. One will bring up a screen from the Settings app, which we will use to see how this affects our task. The other 2140 TASKS one will bring up another activity from our app, which we will use to explore how to start a clean task. The Default User Experience With all that behind us, let’s start talking about tasks, focusing first on what behavior the developer gets “out of the box”, with no task-specific logic in the app. In other words, what is the default user experience for an ordinary Android app? NOTE: if you wish to reproduce the results described here, you will want to have Nukesalot and the Task Canary installed on your device or emulator. Starting from the Home Screen Assume that we are “starting from scratch”. For example, the user has installed your app (or bought a device with your app pre-installed) but has never run your app before. Or, perhaps the overview screen is cleared of all tasks. If the user taps your home screen launcher icon, not only is a process forked to run your app, but a new task is created, and your app’s task will appear in the overview screen. (see! that wasn’t so hard!) To reproduce this behavior: • Clear the overview screen of all tasks, by swiping them off the screen. Note that this may take some time on an Android 5.x device that is really being used (versus just being some test device), as there may be a lot of tasks to clear. • Run your app, from the home screen or IDE. Resuming from the Overview Screen Eventually, the user wanders away from your app. Then, later on, the user returns to your app, by finding the task associated with your app in the overview screen and tapping upon it. In the end, you wind up in the same state as before: you have a process for your app, and your task is still in the overview screen. How we get there depends a bit on what 2141 TASKS happened with your process, in between when you had been in the foreground and when the user taps on your task in the overview screen. If your app’s process was still running, nothing much happens of note, other than you return to the foreground. From a state standpoint, your app would be called with onSaveInstanceState() when the user left your app, but you will not be called with onRestoreInstanceState(), because your activity was not destroyed yet. Note that this assumes that you did not undergo a configuration change (e.g., user originally was in your app in portrait, then returned to you from the overview screen while the device was in landscape). In the case of a configuration change, your activity would be destroyed and recreated by default, and you would be called with onRestoreInstanceState(), but that would be due to the configuration change more so than the use of the task and the overview screen. To reproduce the above behavior, given that your device was in the state after the “Starting from the Home Screen” section above: • Press HOME to move your app to the background, and notice the “(saved)” entries being reported to Logcat. • Quickly press RECENTS (or, if you have no such option, long-press HOME) to bring up the overview, and tap on your task there. However, it is entirely possible that while your task is around that your process is terminated to free up memory for other processes. If the user returns to your app via the overview screen, a fresh process will be forked for your app. This would trigger a call to onRestoreInstanceState(), because your old activity no longer exists, because its process no longer exists. To reproduce the above behavior, given that your device was in the state after the “Starting from the Home Screen” section above: • Press HOME to move your app to the background, and notice the “(saved)” entries being reported to Logcat. • Run Nukesalot, find the Task Canary in the list of running apps, and tap upon that entry to terminate its process. You should see its process go away in the list of debuggable processes in DDMS. You could also experiment with just terminating the process directly from DDMS, but Nukesalot may be a bit closer to “natural” device behavior, in terms of how the process is terminated. • Press RECENTS (or, if you have no such option, long-press HOME) to bring up the overview, and tap on your task there. Note your “(restored)” Logcat 2142 TASKS entries, which should include the same creationTime as you saved, even though it is now in the future. Note that if you leave a task for an extended period of time — say, 30 minutes or so — the task may be “cleared” when you return to it. This means that you are taken back to whatever the “root” activity of the task is, where by “root” we mean the original activity put into the task. Starting Another App Some apps only start up other activities within the same app. However, many apps start up activities from other apps, either directly via startActivity() or indirectly (e.g., clicking in links in a WebView). For example, the Task Canary app has an item in the action bar overflow that, when clicked, brings up the Settings screen for adjusting date and time settings. You might think that when the user taps on this overflow item, and Task Canary calls startActivity(), that a new task is created. After all, the Settings app is a completely separate app from the Task Canary app. However, try this: • Clear the overview screen • Launch Task Canary • Choose the Settings action bar overflow item to bring up the date-and-time Settings screen • Press HOME to bring up the home screen • Press RECENTS or otherwise bring up the overview screen You will see one entry in the overview screen, for Task Canary, rather than two. Furthermore, particularly on Android 5.x devices, you will see the Settings screen as the top-most activity within the Task Canary task: 2143 TASKS Figure 691: The Task Canary Task, on Android 5.1 However, suppose that instead of using ACTION_DATE_SETTINGS for the Intent, we used ACTION_APN_SETTINGS instead, to allow the user to view mobile access point names and such. You might think, given the above flow, that we would wind up with just one task, as we did with ACTION_DATE_SETTINGS. In reality, you will see two tasks, instead of just one: Figure 692: Two Tasks on Android 5.1 This is where things start to get a bit confusing. 2144 TASKS Explaining the Default Behavior With the user experience as background, let’s now dive into what is really going on with these operations. When Tasks are Created A task is not created just because an activity is started. Otherwise, even individual apps would have lots of tasks, one per activity. A task is not created just because a task from a different app is started. Otherwise, the two Settings scenarios above would have both resulted in a new task. Instead, tasks are created when somebody asks for a task to be created. That “somebody” could be the author of the app calling startActivity() or the author of the activity being started. There are three major approaches for indicating that a new task should be started: flags on the Intent used with startActivity(), task affinity values, and launch modes. We will get into launch modes later in this chapter, as the normally-used launch modes have no impact on tasks. Instead, we will focus on the other two approaches here. Task-Management Intent Flags If you want to start an activity, and ensure that the activity starts in a new task, add Intent.FLAG_ACTIVITY_NEW_TASK to the flags on the Intent being used with startActivity(): startActivity(new new Intent(SOME_ACTION_STRING) .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)) What will happen, when you call startActivity() with FLAG_ACTIVITY_NEW_TASK, is that Android will see if there is a task that already has this activity in it. If there is, that task will be brought to the foreground, and the user will see whatever is on the top of that task’s stack. Otherwise, if there is no task with this activity in it, Android will create a new task and associate a new instance of the activity with this task. 2145 TASKS This is what home screen launchers do. When you tap on a home screen launcher icon, if there is a task that has a copy of your home screen activity in it, that task is brought back to the foreground. Otherwise, a new task is started. If you also add Intent.FLAG_ACTIVITY_MULTIPLE_TASK, then Android skips the search for existing tasks and unconditionally launches the activity into a new task. This is generally not a good idea, as the user can wind up with many copies of this activity, not know which one is which, and perhaps have difficulty getting back to the right one. Task Affinities By default, if Android needs to create a new task as a result of FLAG_ACTIVITY_NEW_TASK, it just creates a task. And, if there is no such flag on the Intent, Android will put the activity into the task of whoever called startActivity(). If, however, the activity has an android:taskAffinity attribute in its element in the manifest, then Android will specifically start this activity in a certain task, identified by the string value of the attribute. Other activities with the same task affinity will also go into this task. The reason why the two Settings screens behave differently is that the ACTION_APN_SETTINGS activity has a certain task affinity value, while ACTION_DATE_SETTINGS does not. The task affinity of the ACTION_APN_SETTINGS activity is shared by many, though not all, activities within the Settings app. Those activities, when started, will always go into the task identified by the affinity. Hence, when we start ACTION_DATE_SETTINGS, it goes in our task (because that activity has no affinity and we did not include FLAG_ACTIVITY_NEW_TASK), but when we start the ACTION_APN_SETTINGS activity, it goes into a Settings-specific task. Note that you can also have the android:taskAffinity value defined on the element, to provide a default task affinity for all activities. The overall default is "", or no affinity. When Tasks are Removed On Android 3.0 and higher, the user can get rid of a task by swiping the task off of the overview screen. 2146 TASKS Otherwise, prior to Android 5.0, a task would automatically go away after some amount of user activity, as there were only so many “slots” available for tasks. On Android 5.0+, though, it is unclear if there is an upper bound to how many tasks can exist. Beyond that, tasks survive a reboot, as information about those tasks is persisted. We will get more into the ramifications of this, and how you can take advantage of it, later in this chapter. When Tasks (and Processes) are Resumed A task will be resumed and brought back to the foreground in several situations, including: • the user manually requests it via the overview screen, by clicking on one of the recent tasks • if FLAG_ACTIVITY_NEW_TASK is added (without FLAG_ACTIVITY_MULTIPLE_TASK) to the Intent used to start an activity, and there is a task containing the activity in question • if the taskAffinity for the activity being started ties it to another task • if the launch mode for the activity being started ties it to another task However, just because the task exists does not mean that the process(es) exist for the activities in the task. As needed, Android will fork fresh processes, to be able to load in the app’s code and start the necessary activities. Android will deliver to the newly-created activities the same Intent that was used to create the original incarnation of the activity (via getIntent()) and the saved instance state Bundle. What Happens to Services In theory, services are immune to task behavior. Tasks can come and go, and services are usually oblivious to this. A service should be called with onTaskStopped() if a task associated with one or more of the app’s activities is removed. The service might use that as a signal that it too should shut itself down. There appears to be a quasi-documented android:stopWithTask attribute on the element in the manifest. The default is false, but if you override it to be true on your , then onTaskStopped() will not be called, and Android will simply destroy your service when the task is removed. 2147 TASKS However, as of Android 4.4, there are many reports that services may be destroyed when a task is removed, even without android:stopWithTask="true", though on a slight delay. Developers concerned about this should keep an eye on this issue and this issue, both for various hacky workarounds and for any signs that this is being permanently addressed. What’s Up with onDestroy()? If the user swipes away the task using the overview screen, onDestroy() will be called on all outstanding activities. If, however, you use Nukesalot to kill the background process, Android does not call onDestroy() on any outstanding activities. Since other task killers will use the same techniques as does Nukealot, this means that your onDestroy() methods will not be called when your process is terminated by those apps as well. So, removing a task is a graceful exit, and Android calls onDestroy(), but an explicit termination of your process by another is a not-so-graceful exit, and Android skips onDestroy(). As a result, as previously advised in this book and elsewhere, you cannot count on your onDestroy() methods being called, and you need to take this into account in terms of what sorts of code you put in them. Basic Scenarios for Changing the Behavior In many cases, the default behavior of tasks is just fine. However, there are many scenarios in which we may want to override the default behavior, routing activities to specific tasks, to have a better flow for the user. Reusing an Activity By default, each time you call startActivity(), a new instance of the activity is created. Depending upon the user flow, that may not be a bad approach. For example, it may be that the only logical path out of the started activity will be to press BACK and destroy it. However, there will be plenty of cases where we will not want to keep creating new activity instances. For example, if you elect to have several activities reachable via a nav drawer, you do not want to create fresh instances of activities that the user has 2148 TASKS already visited via that drawer. Otherwise, they will keep piling up, continuing to consume heap space. Instead, it would be better to try to reuse an existing activity instance, if one is available, creating a fresh one only if needed. The most flexible approach for accomplishing this involves using a flag on the Intent used to start the activity: Intent.FLAG_ACTIVITY_REORDER_TO_FRONT. This tells Android to bring an existing activity matching our Intent to the foreground, if one already exists in our task. If there is no such activity, then go ahead and create a new instance. The Tasks/RoundRobin sample application demonstrates this. It consists of two activities (FirstActivity and SecondActivity), each of whose UI consists of one really big button. Clicking the button should start the other activity, so clicking the button in FirstActivity should start an instance of SecondActivity. But, we want to reuse activity instances where available, and confirm that indeed we are reusing those instances. FirstActivity accomplishes that by adding FLAG_ACTIVITY_REORDER_TO_FRONT the Intent used to start SecondActivity when the button is clicked: package com.commonsware.android.tasks.roundrobin; import import import import import android.app.Activity android.app.Activity; android.content.Intent android.content.Intent; android.os.Bundle android.os.Bundle; android.util.Log android.util.Log; android.view.View android.view.View; public class FirstActivity extends Activity implements View.OnClickListener { @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.first); findViewById(R.id.button).setOnClickListener(this this); Log.d(getClass().getSimpleName(), String.format("onCreate for %x", hashCode())); } @Override protected void onResume() { super super.onResume(); Log.d(getClass().getSimpleName(), 2149 to TASKS String.format("onResume for %x", hashCode())); } @Override protected void onDestroy() { Log.d(getClass().getSimpleName(), String.format("onDestroy for %x", hashCode())); super super.onDestroy(); } @Override public void onClick(View view) { startActivity(new new Intent(this this, SecondActivity.class) .addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT)); } } (from Tasks/RoundRobin/app/src/main/java/com/commonsware/android/tasks/roundrobin/FirstActivity.java) SecondActivity FirstActivity. has a nearly identical implementation, just routing back to If you run the app, the user’s perspective is that clicking the button “ping-pongs” the user between the two activities. Looking at Logcat, you will see new instances created the first time the user visits an activity, courtesy of the Log.d() call in onCreate(). But, if the user returns to an existing instance via the button click, you will see that onCreate() is not called, and that the hashCode() reported in onResume() matches the hashCode() of the previously-created instance of this activity: D/FirstActivity: onCreate for b31b9430 D/FirstActivity: onResume for b31b9430 D/SecondActivity: onCreate for b31eb8a8 D/SecondActivity: onResume for b31eb8a8 D/FirstActivity: onResume for b31b9430 D/SecondActivity: onResume for b31eb8a8 If you use Nukesalot to terminate the process for RoundRobin, then return to RoundRobin (e.g., via the overview screen), you will see that Android has to create a new instance of whatever activity had been in the foreground, as the old instance went away when the old process did. An instance of the other activity will not be created until the user returns to it, such as via a click of the really big button. In other words, Android lazy-instantiates the activities in the task’s back stack, only creating instances when it is absolutely required based upon user navigation. 2150 TASKS Note that launch modes offer another way to control this behavior, having the activity being started indicate that its instance should always be reused. However, this is a specialty case, one that most apps will not require. Forcing a Clean Task Let’s suppose that you have an app that requires in-app authentication, via some form of login screen. For example, your app’s data is held in SQLCipher for Android, and so you need the user to supply a passphrase for the database. In the beginning, when your app is launched from the home screen, your LAUNCHER activity appears. If that is your login screen, all is good. You collect the passphrase, create your singleton instance of the SQLCipher-enabled SQLiteOpenHelper, and you can access the database. Eventually, the user presses HOME, and time passes. Android terminates your process to free up system RAM. The user then tries returning to your existing task, such as via the overview screen. Android creates a fresh process for you and takes you to the activity on the top of that task’s back stack. But at this point, your singleton SQLiteOpenHelper is gone, and you need to collect a passphrase again. You might think that this is purely a UI issue. Rather than collecting the passphrase in an activity, you collect it in a fragment, one that your LAUNCHER activity uses directly, and one that other activities can use via a DialogFragment. This way, you can arrange for every activity to be able to complete the re-initialization of your process and give you access to the encrypted database again. Another approach would be to say that you want to wipe out this task and start over, routing the user back to the LAUNCHER activity for authentication. There are two main approaches for implementing this: setting Intent flags or using android:clearTaskOnLaunch in the manifest. Starting a Cleared Task Yourself One way to do that is to have each activity check to see if a new task is needed (e.g., “is the SQLiteOpenHelper singleton null?”). When that situation is detected, you call startActivity() for your LAUNCHER activity, with two flags: FLAG_ACTIVITY_NEW_TASK and FLAG_ACTIVITY_CLEAR_TASK. 2151 TASKS For example, the Tasks/Tasksalot sample application is a straight-up clone of Launchalot with only one change of substance: using FLAG_ACTIVITY_CLEAR_TASK instead of FLAG_ACTIVITY_RESET_TASK_IF_NEEDED: @Override protected void onListItemClick(ListView l, View v, int position, long id) { ResolveInfo launchable=adapter.getItem(position); ActivityInfo activity=launchable.activityInfo; ComponentName name=new new ComponentName(activity.applicationInfo.packageName, activity.name); Intent i=new new Intent(Intent.ACTION_MAIN); i.addCategory(Intent.CATEGORY_LAUNCHER); i.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK); i.setComponent(name); startActivity(i); } (from Tasks/Tasksalot/app/src/main/java/com/commonsware/android/tasksalot/MainActivity.java) To see this in action: • Run the TaskCanary sample app and use the overflow to bring up OtherActivity • Press HOME • Run Tasksalot • Click on the “Task Canary” entry in Tasksalot At this point, you will see the TaskCanary sample app return to the screen. From the logs in Logcat, you will see it is the same task ID as before. Yet, you are seeing the FirstActivity. OtherActivity was removed from the task as part of FLAG_ACTIVITY_CLEAR_TASK processing. This differs from what you see in a home screen, with FLAG_ACTIVITY_RESET_TASK_IF_NEEDED. If you run the same test, but rather than use Tasksalot, you tap on the “Task Canary” icon in the home screen launcher, the task will return to the foreground, but you will be taken to OtherActivity. FLAG_ACTIVITY_CLEAR_TASK always clears the task and makes the activity that you are starting up be the root of the newly-cleared task. 2152 TASKS Always Starting a Cleared Task Perhaps you always want to start with a cleared task, whenever the user returns to the task after having left it previously. In other words, you always want to start back at whatever your task’s root activity is, which is typically your launcher activity. To do this, simply have android:clearTaskOnLaunch="true" on that launcher activity. Then, for any task where that activity is the root, when the user returns to the task, any other activities in the task are reparented (if applicable) or dropped. Note, though, that this does not mean that you get a new process. Hence, any singletons you had before may or may not still be there. So, in the authentication scenario described above, using android:clearTaskOnLaunch="true" would take the user back to your initial activity, where you can perform the authentication. However, if you detect that the SQLiteOpenHelper still exists, and therefore you do not need the user to log in again, you could switch over to showing your initial content (e.g., run a FragmentTransaction). This is far simpler than having the detect-the-null-singleton-on-each-activity approach. However, the downside is that the user loses context. If they were six activities deep into your app, and they get interrupted by a phone call, when they come back to your app, they are back at the beginning. Launching an App Into a New Task A home screen launcher app, when it invokes the user’s selected activity, will use code something like this from the Launchalot sample: @Override protected void onListItemClick(ListView l, View v, int position, long id) { ResolveInfo launchable=adapter.getItem(position); ActivityInfo activity=launchable.activityInfo; ComponentName name=new new ComponentName(activity.applicationInfo.packageName, activity.name); Intent i=new new Intent(Intent.ACTION_MAIN); i.addCategory(Intent.CATEGORY_LAUNCHER); i.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED); i.setComponent(name); 2153 TASKS startActivity(i); } (from Introspection/Launchalot/app/src/main/java/com/commonsware/android/launchalot/Launchalot.java) Here, we: • Create a ComponentName identifying the specific activity in the specific app to be started (in this case, based on the ResolveInfo that the user chose) • Create an Intent for the MAIN action and the LAUNCHER category • Set the FLAG_ACTIVITY_NEW_TASK and the FLAG_ACTIVITY_RESET_TASK_IF_NEEDED flags in the Intent • Attach the ComponentName to the Intent, to convert it from an implicit Intent into an explicit Intent • Start the activity using the Intent FLAG_ACTIVITY_NEW_TASK indicates that we want the activity being started to be the root of a new task. If there is no outstanding task for this app, a new task will be created, a new activity instance will be created, and that activity will be the root of the task. Here, “root” means that if the user presses BACK and destroys the activity, the task itself is removed and the user returns to the home screen. However, despite its name, FLAG_ACTIVITY_NEW_TASK does not necessarily create a new task. If there is an existing task for this app containing this activity, that task is brought back to the foreground and is left intact. The activity we request is not created, let alone brought to the foreground. That is where FLAG_ACTIVITY_RESET_TASK_IF_NEEDED comes in. It ensures that the task that is brought to the foreground is showing the requested activity. This may involve reparenting activities as well. Another possibility, instead of FLAG_ACTIVITY_RESET_TASK_IF_NEEDED, is FLAG_ACTIVITY_MULTIPLE_TASK. This always starts a fresh task, with a fresh instance of the requested activity in the root of that task. However, this now may mean that the user has multiple tasks for the same app, which may be confusing in some circumstances. However, this also lies at the core of Android 5.0’s documents-astasks support and therefore may become more familiar to users over time. 2154 TASKS The Invisible Activity Several sample apps in this book use an “invisible activity”, one with the theme set to Theme.Translucent.NoTitleBar. These are useful in cases where something outside your app needs an activity, but you do not really have a UI that you want to display. In the case of the book samples, having a LAUNCHER activity makes it much easier for readers like you to simply run the samples from the IDE. However, those sample apps usually do not have any other activities. The invisible activity is just there to kick-start something else, such as AlarmManager events. However, if you have a mix of invisible and regular activities in an app, your invisible activities still wind up potentially having a visible impact. For example, suppose that we have an ordinary Android app, with regular activities. However, we want a home screen shortcut icon to allow the user to start something in the background, such as playing music. While an app widget would allow us to control what happens when the user taps on an icon in that app widget, a home screen shortcut icon always launches an activity. So, we make the start-the-music activity invisible via Theme.Translucent.NoTitleBar. If the user taps on that shortcut, and none of our other activities are part of a task, things proceed as expected: the music starts and the user sees nothing (other than perhaps a Toast that we show to let the user know that we are responding to their request). But, if one or more of our activities are in some task, launching the invisible activity brings the task back to the foreground. While our invisible activity is still invisible, the user now sees whatever other activity of ours they had last been in. It is possible that this is a feature, and not a bug, for some apps. But, in other cases, we might want the invisible activity to not have this effect. The solution: task affinity. Your ordinary activities can use the default task affinity, or have other task affinities as needs dictate. Your invisible activity, though, would have an android:taskAffinity value that is distinct from all others, to force it into its own task. That way, when the user taps on the shortcut, the invisible activity routes to its own task. That task will not yet exist, so the invisible activity causes the task to be created. When the invisible activity calls finish() to destroy itself after kicking off the background work, the task is now empty and is removed. Since this was a new 2155 TASKS task, no existing UI would be brought back to the foreground, and since the task is removed in the end, we are “reset” for the next time the user taps on the shortcut. Reparenting Tasks One of the more unusual features of Android’s task system is the ability for activities to be “reparented”, or moved from one task to another. On the surface, this feels a bit odd, as if a Web page on one browser tab might magically show up in a separate browser tab, just via navigation. And, in truth, it is a specialized use case, but one that could conceivably apply to your app. Suppose that you were writing an SMS client. You have an activity that is your message composer, where the user can type in a text message to send to somebody. You export that activity, with Intent actions like ACTION_SEND and ACTION_SENDTO. A third-party app, using one of those Intent actions, starts up your message composer activity. In the absence of a taskAffinity to stipulate otherwise, by default, your message composer activity will be in the task of the third-party app. Now, suppose that the user fails to actually send a message, such as by pressing HOME from the third-party app’s task. Some time later, the user taps on your app’s home screen launcher icon. At this point, there are two possibilities as to what happens: 1. You may decide that you want to have the already-running message composer activity appear, to remind the user that they were in the middle of composing a text message and failed to either send it or explicitly BACK out of the activity. 2. You may decide that you do not care, and you are willing to ignore that outstanding message composer activity instance. The default is option #2. If, instead, you want to offer option #1, that is where task reparenting comes into play. On your (or on to set an app-wide default), you can have android:allowTaskReparenting="true". This indicates to Android that the message composing activity, that is on some other app’s task, can move to your app’s task when that task is created. The trigger for this “reparenting” is the task affinity. If you do not specify a task affinity for an activity, the default affinity is for a task rooted in one of your app’s activities, typically the launcher activity. In some circumstances, when a task for 2156 TASKS your app is created, Android will search through other tasks to see if there is any activity, in another task, that has an affinity for your task and allows reparenting. If there is a match, that activity is brought into your task. The “some circumstances” mentioned in the preceding paragraph is something using two Intent flags when calling startActivity(): • FLAG_ACTIVITY_NEW_TASK, to create a new task if one is needed, and • FLAG_ACTIVITY_RESET_TASK_IF_NEEDED, to clear out the task if it already has contents and reparent any activities in other tasks to this one if appropriate As it turns out, home screen launchers are supposed to use this pair of flags when they respond to the user tapping on a home screen launcher icon. The Tasks/ReparentDemo sample Android Studio project contains a pair of applications as modules that demonstrate this effect, based on David Wasser’s epic Stack Overflow answer. One module, app/, contains an application with two activities, where the second activity (ReparentableActivity) has android:allowTaskReparenting="true": > > > /> /> > /> /> 2157 TASKS (from Tasks/ReparentDemo/app/src/main/AndroidManifest.xml) The two activities just display static messages, indicating which of those two activities you are seeing in the foreground. They also log process and task IDs to Logcat. MainActivity does that in onCreate(): package com.commonsware.android.tasks.reparent; import android.app.Activity android.app.Activity; import android.os.Bundle android.os.Bundle; import android.util.Log android.util.Log; public class MainActivity extends Activity { @Override public void onCreate(Bundle state) { super super.onCreate(state); setContentView(R.layout.main); Log.d(getApplicationInfo().loadLabel(getPackageManager()).toString(), String.format("Process ID %d, Task ID %d", android.os.Process.myPid(), getTaskId())); } } (from Tasks/ReparentDemo/app/src/main/java/com/commonsware/android/tasks/reparent/MainActivity.java) ReparentableActivity logs the same information in onResume(): package com.commonsware.android.tasks.reparent; import android.app.Activity android.app.Activity; import android.os.Bundle android.os.Bundle; import android.util.Log android.util.Log; public class ReparentableActivity extends Activity { @Override public void onCreate(Bundle state) { super super.onCreate(state); setContentView(R.layout.reparent); } @Override public void onResume() { super super.onResume(); Log.d(getClass().getSimpleName(), String.format("Process ID %d, Task ID %d", 2158 TASKS android.os.Process.myPid(), getTaskId())); } } (from Tasks/ReparentDemo/app/src/main/java/com/commonsware/android/tasks/reparent/ReparentableActivity.java) The other module, app2/, contains an application with one activity, whose UI consists of one really big button. Clicking that button triggers a launch() method that calls startActivity() on an Intent identifying the ReparentableActivity from the first app: package com.commonsware.android.tasks.reparent.app2; import import import import import android.app.Activity android.app.Activity; android.content.Intent android.content.Intent; android.os.Bundle android.os.Bundle; android.util.Log android.util.Log; android.view.View android.view.View; public class MainActivity extends Activity { @Override public void onCreate(Bundle state) { super super.onCreate(state); setContentView(R.layout.main); Log.d(getApplicationInfo().loadLabel(getPackageManager()).toString(), String.format("Process ID %d, Task ID %d", android.os.Process.myPid(), getTaskId())); } public void launch(View v) { startActivity(new new Intent("com.commonsware.android.tasks.reparent.WHEEEEE")); } } (from Tasks/ReparentDemo/app2/src/main/java/com/commonsware/android/tasks/reparent/app2/MainActivity.java) To see this behavior in action, install both apps. If you run them straight from your IDE, you will want to clear out all relevant tasks, either by swiping them off the recent-tasks list (or by rebooting the device or emulator, if it runs Android 4.4 or lower). Then, start up the “Reparent Demo Aux” app (from the app2/ module). Click the button, and you will see the ReparentableActivity appear. If you press HOME, bring up the recent-tasks list, and go back to this task, you will see the same ReparentableActivity. The task, however, is for “Reparent Demo Aux”. Now, press HOME, then start up the “Reparent Demo” app (from the app/ module). Rather than seeing the MainActivity from that app, you see the ReparentableActivity instance from before. The logs will illustrate that your 2159 TASKS process ID has not changed, but that the task ID for this activity has changed, from the task ID used by the app2/ app to the task ID created for app/. The activity has been reparented. The use of FLAG_ACTIVITY_RESET_TASK_IF_NEEDED may sound a lot like FLAG_ACTIVITY_CLEAR_TASK. The “if needed” part comes into play in two cases: • If a new task is being created, the “reset” work is really the reparenting described above • If an existing task is being brought back to the foreground, then get rid of resettable activities Here, by “resettable activities”, we mean: • Activities launched with the FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET flag • Any activities that are higher on the back stack than other explicitly resettable activities So, if our back stack consists of activities A-B-C-D, and C was started with FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET, and we start up one of these activities (say, A) with FLAG_ACTIVITY_RESET_TASK_IF_NEEDED, and this existing task is coming back to the foreground, C and D will be cleared from the task. The user ordinarily would be taken to activity D, but instead will be taken to activity B, because C is explicitly resettable and D is higher on the back stack. The Self-Destructing Activity Sometimes, you only want an activity around while it is in the foreground and the user can see it. Once the user leaves the app, you no longer want that activity to exist. For example, a bank app showing bank account details might want this behavior, so that highly-sensitive information like this does not hang around. Or, you might want this for certain activities that are memory-intensive, so they release their heap space and reduce the odds of an OutOfMemoryError. You could attempt to manage this yourself, via timely calls to finish(), but catching all the cases when finish() is needed could get troublesome. Instead, Android has a pair of options to have no-history activities: activities that automatically finish when the user leaves them: 2160 TASKS • An activity can decide for itself that it should be removed upon a task switch via the android:noHistory attribute on the in the manifest • You can decide ad-hoc to have activities exhibit this behavior by adding Intent.FLAG_ACTIVITY_NO_HISTORY on the Intent used to start those activities You can see these in action in the Tasks/NoHistory sample application. This is a near-clone of a simple two-activity app that we saw back when we first learned about how to have multiple activities. There are only two real differences in this version of the sample app. First, the launcher activity (MainActivity) has android:noHistory="true" on its element: > /> /> (from Tasks/NoHistory/app/src/main/AndroidManifest.xml) Second, when that activity goes to start OtherActivity, it adds FLAG_ACTIVITY_NO_HISTORY to the Intent used with startActivity(): public void showOther(View v) { Intent other=new new Intent(this this, OtherActivity.class); other.putExtra(OtherActivity.EXTRA_MESSAGE, getString(R.string.other)); other.addFlags(Intent.FLAG_ACTIVITY_NO_HISTORY); startActivity(other); } (from Tasks/NoHistory/app/src/main/java/com/commonsware/android/tasks/nohistory/MainActivity.java) Both of these inherit from the original sample’s LifecycleLoggingActivity, which just logs messages to Logcat on the major lifecycle methods. If you run the app, click 2161 TASKS the big button to go from MainActivity to OtherActivity, then switch to some other app (via the overview screen, via the home screen launcher, etc.), you will see that both activities are destroyed, even though we do not press BACK, call finish(), or do anything else ourselves to destroy them. This has a key side-effect: you cannot combine no-history with startActivityForResult() especially well. If the activity that calls startActivityForResult() has no-history enabled (via the manifest attribute or the Intent flag), it will simply not be called with onActivityResult(). A related attribute is android:finishOnTaskLaunch. If set to true, and if the user leaves the task and returns to it, the activity is destroyed. Whereas android:noHistory removes the activity when the user leaves the activity, android:finishOnTaskLaunch only removes the activity when the user leaves the task and returns to it. The Hidden Task Perhaps you have a use case where you want your entire task to be hidden from the overview screen. To do that, you can indicate that the activity that is the root of the task (e.g., your launcher activity) is to be “excluded from recents”. To do that, you can: • Add android:excludeFromRecents="true" to the appropriate element in your manifest, or • Add Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS to the Intent used to start up the activity and its task Note that this only matters if the activity in question is the task root (i.e., the one that started the task). Having this setting on other activities higher in the back stack will have no effect on the visibility of the task. Also, please note that this does not eliminate the task itself. It merely hides it from the overview screen. So, for example, suppose you were to: • Add android:excludeFromRecents="true" to MainActivity in the TaskCanary sample • Run the sample app • Press HOME and note the task ID that shows up in Logcat • Press RECENTS and note that the task does not show up there 2162 TASKS • Return to the home screen, find TaskCanary in the launcher, and tap on the launcher icon • Press HOME again and note the task ID that shows up in Logcat You will see that those task IDs are the same. So, the task is there, and we can return to that task, but the task is merely suppressed from the listing shown in the overview screen. Dealing with the Persistent Tasks As noted previously in this chapter, on Android 5.0+, tasks live forever, insofar as they survive a reboot. That, coupled with a seemingly-infinite roster of recent tasks — compared with rather finite lists in earlier versions of Android — means that your app usually will be brought back from an existing task on Android 5.0+. However, there are a few key differences. The State of Your State For normal process termination, in between device reboots, the Bundle that we get in onSaveInstanceState() is held onto in RAM by some core OS process. Of course, on a reboot, that process is terminated along with everything else. And a Bundle can hold onto objects that, while perhaps Parcelable, are not designed to be persisted. The default behavior is that when your task is brought back to the foreground after a reboot, only the task’s root activity is created, and that is the only activity in the task. This effectively mimics the behavior of pre-Android 5.0 versions of Android. However, if you want to, you can control a bit more how your task behaves on a reboot. Your element in the manifest can have a largely-undocumented android:persistableMode attribute. If you set this to persistAcrossReboots on the activity that serves as the root of your task (e.g., your launcher activity), then you will be able to override three additional methods on your Activity: • onCreate() • onSaveInstanceState() • onRestoreInstanceState() 2163 TASKS Right now, you may think that the author of this book is drunk, as we covered those methods already, far earlier in the book. However, what API Level 21 adds, for persistAcrossReboots activities, are flavors of those methods that take two parameters: a Bundle (as normal) and a PersistableBundle. Values that you store in the latter parameter will be delivered to you when your activity is re-created as part of your task coming back to the foreground, even after a reboot. Note that all of the above requires that you set your compileSdkVersion to 21 or higher. PersistableBundle allows you to save int, long, double, and String values, along with arrays of each. On Android 5.1+, you can also save boolean and arrays of boolean values. Notably, you cannot put a Parcelable (or, strangely, a Serializable) in a PersistableBundle. If your activity has persistAcrossReboots set — as does MainActivity in the Tasks/PersistentCanary sample application — you will be called both with the single-parameter and dual-parameter versions of those methods, in that order. Unless your app has a minSdkVersion of 21 or higher, you will probably wind up overriding both versions of each method, where you put stuff in the Bundle in the single-parameter method and you put stuff in the PersistableBundle in the dualparameter method. Since versions of Android prior to 5.0 do not know about PersistableBundle or methods that take one, only the single-parameter versions of those methods will be called on those devices. If your minSdkVersion is 21 or higher, though, you could just override the dual-parameter versions of the methods and work with both Bundle and PersistableBundle as needed. Where You Return To Normally, if your task is in the overview screen, and the user returns to it, the user will be taken to whatever activity was at the top of the back stack. However, if the device reboots, and the user returns to your task, what happens depends on that semi-documented persistableMode value: • If the value for the root activity of the task is persistNever, the task is not persisted across reboots 2164 TASKS • If the value for the root activity of the task is persistRootOnly, the task will be persisted, but only for that root activity; other activities higher on the back stack are discarded • If the value for the root activity of the task is persistAcrossReboots, then not only is the task persisted for the root activity, but other activities on the back stack are also persisted if they too have persistAcrossReboots (and were not launched with the FLAG_CLEAR_TASK_WHEN_RESET flag) So, in the case of PersistentCanary, even if you use the overflow to bring up the date-and-time Settings screen, since that activity has the default persistRootOnly value for persistableMode, only the MainActivity will be in the task after a reboot. Documents As Tasks Tasks used to be relatively app-centric. By and large, each app had its own task, and just one task. Android 5.0 extended the task system to support the notion of “documents” as tasks. Now, an app may be in several tasks, with different tasks focused on different “documents” or other specific contexts. The vision is that this would be used by: • Web browsers, where different browser tabs would be represented as separate tasks • Editors, where different editing sessions on different content could be represented as separate tasks • And so on The benefit to the user is a standard way to switch between these different contexts, by means of the overview screen. The risk is that the overview screen becomes unwieldy, choked with too many entries to sift through. When You Should Do This An app should open a new “document” based on some specific explicit “open” operation by the user. So, for example: • If the user asks to open a new “tab” in a browser, that could start a new document 2165 TASKS • If the user asks to open a new file into an editor, that might start a new document, if you feel that the user understands that there are N other documents out there already opened in this editor • If the user launches one of your activities from outside of the home screen, such as by clicking on a link in a Web browser, that might start a new document, to keep that work separate from any past work that might be part of other active tasks Conversely, an app should not open a new document based on pure navigation operations: • Swiping to a new page in a ViewPager should not open a new document • Choosing an item in a nav drawer should not open a new document • Tapping on an action bar item on its own should not open a new document, though it might lead the user down a path to open a new document Adding a Document You have a few options for launching an activity as a new document, indicating that it should have a separate entry on the Android 5.0+ overview screen. android:documentLaunchMode If you always want this activity to form the basis of a new document, add android:documentLaunchMode="always" to the element of your manifest, and you are done. Every time you start up an instance, you will get a new document. This can be seen in the Tasks/Docs sample application, which has an EditorActivity with the aforementioned attribute: /> (from Tasks/Docs/app/src/main/AndroidManifest.xml) (we will cover those other new attributes shortly) There are four possible values for android:documentLaunchMode: 2166 TASKS • always, as noted, always starts a new document • intoExisting, which looks for an existing document, where the root activity is the same class and the Intent is for the same Uri, and brings it back to the foreground, or starts a new document if a match cannot be found • never prevents this activity from ever being launched as a new document • none, which is the default, indicates that the activity will only be launched as a new document if Intent flags indicate that it should, as will be explained shortly Since intoExisting depends upon Uri matches, you only want to use intoExisting if you are passing Uri values into the activity when starting it. Otherwise, use always. FLAG_ACTIVITY_NEW_DOCUMENT To conditionally launch an activity as a new document, have its android:documentLaunchMode set to none (or missing, since that is the default), and add Intent.FLAG_ACTIVITY_NEW_DOCUMENT to the Intent that is used to start up the activity that would represent a new document. This will have the behavior akin to intoExisting for android:documentLaunchMode, meaning that Android will search for a matching document and bring it back to the foreground if the match is available. To replicate always functionality, add both Intent.FLAG_ACTIVITY_NEW_DOCUMENT and Intent.FLAG_ACTIVITY_MULTIPLE_TASK to the Intent. Capping the Number of Documents By default, you can launch as many documents as you want. However, unless you get rid of the document (as will be described below), or the user gets rid of the document (by swiping it off the overview screen), your roster of documents can keep piling up. Users may get frustrated if their overview screen is flooded by entries for your app. You can employ an automatic least-recently-used (LRU) algorithm here by adding android:maxRecents to the that is the root of the task for the document. This indicates the maximum number of entries there should be in the overview screen for that activity, where Android will remove older tasks to make way for new ones if needed. 2167 TASKS So, in the Docs sample, android:maxRecents="3" limits the number of EditorActivity tasks to 3; if the user tries opening more than this, older ones are quietly removed. Note that the default value for android:maxRecents is 16. Also, there is a cap, ranging from 25 to 50, depending on device RAM — you will be unable to set it higher than this. Removing and Retaining Documents Android’s default behavior is that the document will exist forever, or until the user swipes it off the overview screen. It is rather unlikely that this is really the behavior that you or your users will want. Hence, you are going to want to take some steps to ensure that your documents will go away from the overview screen when they are no longer needed. The simplest solution is to add android:autoRemoveFromRecents="true". This indicates that once the root activity is finished (e.g., the user presses BACK), the document is removed. By default, pressing BACK does not remove the document, so you need to opt into this behavior. However, that approach assumes that it is fairly easy for the user to get back to the task’s root activity and press BACK. If you have a complex navigation of activities within the “document”, it may not be easy for the user to trigger document removal this way. You can also forcibly get rid of the document by calling finishAndRemoveTask() yourself on an activity in the task. For example, in a tabbed Web browser, if you have a “close tab” UI element (e.g., action bar item), that could call finishAndRemoveTask() to get rid of the “document”. Other Task-Related Activity Properties There are other attributes that you can place on your element in the manifest that have impacts on how that activity participates with the task system. 2168 TASKS launchMode Occasionally, particular techniques become much too popular in Android development, courtesy of some blog posts or other resources touting them as “quick hacks” to address certain issues. The android:launchMode attribute is one of those. Most Android apps should have no need to change launchMode off of its default value of standard, or occasionally singleTop. Yet, because the Android task system is rather confusing, some developers latch onto other launch modes and use them in places where there are better, more fine-grained solutions. That being said, let’s explore the launch modes, with the help from the fine people at Novoda. The Novoda developers released an app on the Play Store, and an accompanying GitHub repo that helps to illustrate the launch modes. That app has four activities, one for each of the four launch modes: • • • • standard singleTop singleTask singleInstance The launcher activity is the standard activity. Each activity has four buttons, to start up that activity via startActivity(), by default with no particular Intent flags (though there’s a legacy options menu that allows you to play with those as well). The color-coded UI for each activity also shows a unique identifier of the activity, the task ID of the task that the activity is in, the lifecycle methods that were invoked on that instance, and a set of stacked bars designed to illustrate what should be on the back stack for that task (using some techniques of dubious reliability, but the sort of thing that should be OK for a demo app like this). So, when we launch the app, we get a green UI for a standard activity: 2169 TASKS Figure 693: Novoda Demo App, As Initially Launched singleTop Using singleTop for the launchMode has one effect: controlling whether a new instance of the activity is created. Normally, calling startActivity() will create a new instance of the activity, unless Intent flags dictate otherwise. With singleTop, if the activity being started is already at the top of its stack, that existing instance is simply called with onNewIntent(). Otherwise, singleTop behaves as does standard. So, if we tap the button to launch a singleTop method in the Novoda demo app, from our earlier state, we get a blue singleTop activity: 2170 TASKS Figure 694: Novoda Demo App, After Starting singleTop Activity That worked just like standard. But, if we tap the same button again, we do not get a new instance of the activity. However, the transcript of lifecycle methods shows that onNewIntent() was called: 2171 TASKS Figure 695: Novoda Demo App, After Starting singleTop Activity Again Note that you can get a similar result by including Intent.FLAG_ACTIVITY_SINGLE_TOP on a startActivity() call. Using launchMode says you always want single-top behavior; using FLAG_ACTIVITY_SINGLE_TOP says that this time you want single-top behavior. Pressing BACK returns you to the original green standard activity, with the blue singleTop activity having been destroyed. singleTask A launchMode of singleTask says that this activity must always be the root activity of a task. If the task does not have that activity, a new task is created. So, if we tap the button to launch the singleTask activity in the Novoda demo app, we get a new task (ID 978, compared to the previous 977), with an instance of the yellow singleTask activity as its root: 2172 TASKS Figure 696: Novoda Demo App, After Starting singleTask Activity However, if the activity in question is already there as the root of the task, all other activities on the back stack are cleared, and we are taken to the singleTask activity again. So, in the Novoda demo app, if after we start the singleTask activity, we tap the button to launch a standard activity or two: 2173 TASKS Figure 697: Novoda Demo App, Two standard Activities After singleTask Activity …then tap the button to launch the singleTask activity, we get largely the same screen as before, just with a few more lifecycle methods logged: 2174 TASKS Figure 698: Novoda Demo App, After Starting singleTask Activity Again It is the same task and the same instance, but with the other activities removed. singleInstance singleInstance works much like singleTask, except that the task will only ever hold this one activity. No other activities will be placed into the task. So, tapping the button to start a singleInstance activity in the Novoda demo app brings up the red singleInstance UI: 2175 TASKS Figure 699: Novoda Demo App, After Starting singleInstance Activity Tapping the same button again just triggers onNewIntent() and other lifecycle methods on the same activity in the same task. If, however, you try tapping on the button for the standard activity, your activity will go to another task. Depending on when and how you try the Novoda demo app, this could be a prior task associated with our app (e.g., one you used for earlier standard tests), or it could be a new task (if you do not have any other ones). This is based on the taskAffinity of the activity being started. In general, singleTask and singleInstance are for unusual use cases, and ordinary Android apps should have little reason to use them. Google specifically urges you not to use them: …standard is the default mode and is appropriate for most types of activities. SingleTop is also a common and useful launch mode for many types of activities. The other modes — singleTask and singleInstance — are not appropriate for most applications, since they result in an interaction model that is likely to be unfamiliar to users and is very different from most other applications. 2176 TASKS alwaysRetainTaskState As noted earlier in the chapter, tasks may be cleared by Android if the user has not been in the task for some time (e.g., 30+ minutes). In these cases, the user is taken back to the root activity. If, however, the root activity has android:alwaysRetainTaskState="true" in its manifest entry, then Android will not apply this timeout rule. So long as the task exists, its entire state will be retained and used when the user returns to the task. This is useful for tasks where there is a lot of state that the user might regret losing. Other Task-Related Activity Methods There are a handful of other task-related methods and such floating around the Activity class: finishAffinity() This calls finish() not only on the current activity, but on all activities immediately behind it on the back stack for this task that have the same taskAffinity as does the current activity. Much of the time, the activities on the stack will all share an affinity, and therefore this will frequently finish all activities in the task. If the task has a mixed set of affinities (e.g., a mix of explicitly-named affinities and other activities using the default affinity), this method would only wipe out those behind the current with a specific match. This method is not commonly used. finishAndRemoveTask() This calls finish() on all activities in the task and removes the task outright. For example, a “logout” operation might call finishAndRemoveTask() to flush the current task, then call startActivity() to launch the login activity. That login activity will wind up in a fresh task (since the current one will be removed), and the old activity instances will go away, so the user cannot somehow stumble into them when they are not yet logged in. 2177 TASKS getTaskId() Returns a unique integer that identifies the task the activity resides in. This method is not commonly used. isTaskRoot() isTaskRoot() is a method on Activity. It will return true if this activity instance is at the root of a task, meaning that pressing BACK should remove the task and return the user to the home screen. moveTaskToBack() This method moves the current task to the background. What comes to the foreground is undocumented but generally seems to be the task for the home screen. Some apps use this to offer a “minimize” or “go to background” option within the app, though this is superfluous, as the task will move to the background naturally as the user navigates their device. setTaskDescription() For Android 5.0+, setTaskDescription() allows you to associate an ActivityManager.TaskDescription instance with your task. Here you can provide values that help drive what the task looks like on the overview screen. Specifically, you can provide the icon, title, and background color to use for the title bar over your thumbnail on the overview screen. 2178 The Assist API (“Now On Tap”) Android 6.0 introduced the concept of the device “assistant”. The assistant can be triggered by a long-press of the HOME button or via a spoken phrase (if the user has always-on keyphrase detection) enabled. An assistant is a special app that has access to the content of the foreground activity and other visible windows, much like an accessibility service does. For the vast majority of users of Google Play ecosystem devices running Android 6.0 or higher, the “assistant” is known as Now On Tap. On some devices, such as the Google Pixel series, this assistant is known simply as the “Google Assistant”. This is marketed as an extension of the Google Now UI, where Now On Tap/Google Assistant will take the data from the foreground activity and use that to find other relevant things for the user to do based upon that data. (for the purposes of this chapter, this Google-supplied assistant will be referred to as “Now On Tap”, to distinguish Google’s assistant from assistants that others might write using these APIs) For example, suppose the user receives a text message, suggesting dinner at a particular restaurant. The restaurant is merely named — no URL — and so the text messaging client would just display the name of the restaurant as part of the message. If the user invokes Now On Tap, Google will take the contents of this message (and anything else on the screen), and presumably send it to Google’s servers, sending back things like details about the restaurant (e.g., URL to Web site, Google’s scanned reviews of the restaurant, link to Google Maps for driving directions). Google’s search engine technology would scan the data from the app, recognize that the restaurant name appears to be something significant, and give Now On Tap details of what to offer the user. 2179 THE ASSIST API (“NOW ON TAP”) As with many things from Google, Now On Tap is very compelling and very much a privacy problem. Now On Tap is automatically installed and enabled on Android 6.0 devices — users have to go through some work to disable it. Users and app developers have limited ability to control Now On Tap, in terms of what data it collects and what it does with that data. On the other hand, certain apps (for which there are no privacy considerations) might wish to provide more data to Now On Tap, beyond what is visible in widgets, to help provide more context for Now On Tap to help users. In this chapter, we will explore the Assist API, in terms of: • • • • what data gets collected how apps can add to that data how apps can block sensitive information from the assistant how to write your own assistant, as a Now On Tap replacement Prerequisites Understanding this chapter requires that you have read the core chapters of this book. What Data Gets Disclosed Quite a bit of data is made available to Now On Tap or other assistants through the Assist API alone, as will be explored in this section. Assistants are welcome to use other APIs as well, subject to standard Android permissions and such. So, for example, an app might not show the device’s location, and therefore an assistant could not get the location from the Assist API, but the assistant could use LocationManager or the Play Services location API to find out the device’s location. There is also a risk of pre-installed assistants using undocumented means of getting at data beyond what the normal Android SDK would allow. All that being said, assistants will get a lot of information about the currently-visible UI, just from what the Assist API provides. 2180 THE ASSIST API (“NOW ON TAP”) Screenshot Assistants can get a screenshot of the current screen contents — minus the status bar — when the user activated the assistant (e.g., long-pressed HOME). Developers can block this for select activities or other windows. Hence, an assistant cannot assume that it will get a screenshot, though frequently it will. Presumably, the “vision” here is to use computer vision and other image recognition techniques on the screenshot to find things of interest. For example, the user might bring up Now On Tap for some activity that is showing a photo of a monument. The activity might not be showing any other details about the monument, such as its name. However, Google’s servers might well recognize what monument it is and therefore give the user links to Wikipedia pages about the monument, a map of where the monument is located, etc. View Structure By far the largest dump of data that the assistant gets comes in the form of the view structure. This is represented by a tree of AssistStructure.ViewNode objects, one per widget or container within a window. These provide similar information as to what one gets from the accessibility APIs. For most assistants, the key data is the text or content description in the widget. In the case of text, this is available as a CharSequence and so may contain additional information (e.g., hyperlinks represented in URLSpan objects) beyond the words visible to the user. Developers can restrict what widgets and containers are disclosed, but that is something developers have to do explicitly. In other words, making data available to assistants is something a developer has to opt out of, not opt into. Other Data In addition to the view structure and a largely-undocumented Bundle, the other piece of data supplied to the assistant is the AssistContent. Here is where an app can provide some additional context about the foreground activity. Specifically, the app can provide: • an Intent that represents the activity, replacing the Intent that was used to start the activity, if there is a better one for long-term use (e.g., the activity 2181 THE ASSIST API (“NOW ON TAP”) • • • • was started via a Notification action and you want to route the user through a different Intent for other scenarios) a Uri that points to some Web page of relevance for this activity a string of “structured data”, designed to be populated by a snippet of JSON using the schema.org specification, to provide details of the book, song, video, or whatever happens to be in the activity at the moment another undocumented Bundle an undocumented ClipData Assistants can use this directly (e.g., offer a link to the Uri supplied in this content) or indirectly (e.g., using the schema.org JSON to find places where the user can purchase related content). Adding to the Data You may wish to provide some additional information to Now On Tap or other assistants, such as the Intent or JSON described above. Or, you may just generally want to ensure that your app provides the maximum amount of information to these assistants, without necessarily trying to invent new data to provide. There are a few options for accomplishing this. Accessibility The big one is to ensure that your app provides text or content descriptions for everything visible. This will not only help these assistants, but this will make your app far more accessible to those using TalkBack or other accessibility services. Mostly, this is a matter of ensuring that your ImageView widgets and other nontextual widgets have a content description, whether set via android:contentDescription attributes or by setContentDescription() in Java. TextView and its subclasses automatically use their text as the content description; EditText will use the hint if there is no text in the field at the moment. More advice regarding accessibility can be found in the chapter on accessibility and focus management. 2182 THE ASSIST API (“NOW ON TAP”) Assist-Specific Data Beyond that, you can contribute to the AssistContent (where the Intent, Uri, and JSON live) and other assist-related information for a given invocation of the assistant by the user. You have a few options of where to place this logic: in one spot globally, on a peractivity basis, and, for custom views, on a per-view basis. Globally You can call registerOnProvideAssistDataListener() on the global Application object (retrieved by calling getApplicationContext() on some other Context, like your Activity). This takes an OnProvideAssistDataListener implementation, which in turn provides an onProvideAssistData() implementation, that will be called when the assistant is requested. You are passed the Activity of yours that is in the foreground, along with a Bundle that you can fill in. However, the documentation only says that the Bundle will go into the EXTRA_ASSIST_CONTEXT extra on the Intent that invokes the assistant. What that Bundle is supposed to contain is undocumented. Per-Activity Your primary hooks for customizing the assist data come in the form of two callbacks on your Activity subclasses: onProvideAssistData() and onProvideAssistContent(). onProvideAssistData() is given the same Bundle that is given to the OnProvideAssistDataListener on a global basis. However, it is unclear what that Bundle, and the contents of that Bundle do not appear to make it to the goes in assistant, at least through the documented Assist API. onProvideAssistContent(), though, is more relevant. The Assist/MoAssist sample project is a clone of a sample app demonstrating the use of tabs in Android. The clone has its compileSdkVersion bumped to 23, and it overrides onProvideAssistData() and onProvideAssistContent(): @Override public void onProvideAssistData(Bundle data) { 2183 THE ASSIST API (“NOW ON TAP”) super super.onProvideAssistData(data); data.putInt("random-value", new SecureRandom().nextInt()); } @TargetApi(23) @Override public void onProvideAssistContent(AssistContent outContent) { super super.onProvideAssistContent(outContent); outContent.setWebUri(Uri.parse("https://commonsware.com")); try { JSONObject json=new new JSONObject() .put("@type", "Book") .put("author", "https://commonsware.com/mmurphy") .put("publisher", "CommonsWare, LLC") .put("name", "The Busy Coder's Guide to Android Development"); outContent.setStructuredData(json.toString()); } catch (JSONException e) { Log.e(getClass().getSimpleName(), "Um, what happened here?", e); } } (from Assist/MoAssist/app/src/main/java/com/commonsware/android/assist/mo/MainActivity.java) The onProvideAssistData() simply puts a random number into the Bundle. That random number does not appear anywhere in the data collected by an assistant. onProvideAssistContent() fills in two items in the AssistContent: • a Web URL of relevance to the activity, in this case the home page of the book’s publisher • a bit of JSON, following the published schema.org Book structure, with metadata about this book This information is supplied to assistants and can be used by them to do something useful, such as offer links for the user to click on to visit the sites. 2184 THE ASSIST API (“NOW ON TAP”) Per-View If you are implementing your own custom views, particularly those that render their own text using low-level Canvas APIs, you may wish to override onProvideStructure() and/or onProvideVirtualStructure(). These will be called on your widgets to provide the AssistStructure.ViewNode details to be passed to the assistant. However, in all likelihood, you would want to instead work with the accessibility APIs to publish data to be used by accessibility services, such as the text that you are rendering. If you do that, the default implementations of onProvideStructure() and onProvideVirtualStructure() should suffice. Removing from the Data While some developers may embrace Now On Tap, others may specifically want to prevent Now On Tap or other assistants from “spying” on application data. You have a few options for controlling what is provided to assistants; however, all require work and some have side effects. For example, there is nothing in the manifest that you can specify to make your activities opt out of providing assist data. FLAG_SECURE The standard approach for making private activities really private is to use FLAG_SECURE: public class FlagSecureTestActivity extends Activity { @Override public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); getWindow().setFlags(LayoutParams.FLAG_SECURE, LayoutParams.FLAG_SECURE); setContentView(R.layout.main); } } Call setFlags() before setContentView(), in this case setting FLAG_SECURE. 2185 THE ASSIST API (“NOW ON TAP”) The classic effect of FLAG_SECURE is to block screenshots, both user-initiated ones and system-initiated ones (e.g., the screenshots used in the overview/recent-tasks screen on Android 4.0+). If the user triggers an assistant for a secure activity, the assistant will not get the full view structure (i.e., no widgets and no text) and will not get a screenshot. Password Fields An EditText that is set up as a password field will have its text blocked from the view structure. The widget will be listed, but its text will be null. Presumably, this relies on the EditText using a PasswordTransformationMethod, as that is Android’s typical approach for determining whether or not an EditText is deemed to be secure. If you have implemented your own TransformationMethod (e.g., with a different approach for shrouding the user input), either have it extend PasswordTransformationMethod or use other approaches to prevent this field’s contents from being published to assistants. NoAssistFrameLayout The apparently-official way to block a widget or container from participating in the assist API is to create a subclass of it and override dispatchProvideStructure(). The stock implementation of this triggers the calls to onProvideStructure() and onProvideVirtualStructure(). Plus, for a ViewGroup, it will iterate over the children and call dispatchProvideStructure() on each of them. If you are creating your own custom view, and you want it eliminated from the view structure, just override dispatchProvideStructure() and have it do nothing. Or, you can create a container that is there solely to block the assist data collection. The Assist/NoAssist sample project does this, in the form of a NoAssistFrameLayout: package com.commonsware.android.assist.no; import import import import import import android.annotation.TargetApi android.annotation.TargetApi; android.content.Context android.content.Context; android.os.Build android.os.Build; android.util.AttributeSet android.util.AttributeSet; android.view.ViewStructure android.view.ViewStructure; android.widget.FrameLayout android.widget.FrameLayout; 2186 THE ASSIST API (“NOW ON TAP”) public class NoAssistFrameLayout extends FrameLayout { public NoAssistFrameLayout(Context context) { super super(context); } public NoAssistFrameLayout(Context context, AttributeSet attrs) { super super(context, attrs); } public NoAssistFrameLayout(Context context, AttributeSet attrs, int defStyleAttr) { super super(context, attrs, defStyleAttr); } @TargetApi(Build.VERSION_CODES.LOLLIPOP) public NoAssistFrameLayout(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes) { super super(context, attrs, defStyleAttr, defStyleRes); } @Override public void dispatchProvideStructure(ViewStructure structure) { // no, thanks } } (from Assist/NoAssist/app/src/main/java/com/commonsware/android/assist/no/NoAssistFrameLayout.java) EditorFragment — responsible for showing a large multi-line EditText for the user to type into — will conditionally use a NoAssistFrameLayout, specifically on the third tab (a ViewPager position of 2): @Override public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) { int position=getArguments().getInt(KEY_POSITION, -1); View result; if (position==2) { ViewGroup doctorNo=new new NoAssistFrameLayout(getActivity()); inflater.inflate(R.layout.editor, doctorNo); 2187 THE ASSIST API (“NOW ON TAP”) result=doctorNo; } else { result=inflater.inflate(R.layout.editor, container, false false); } EditText editor=(EditText)result.findViewById(R.id.editor); editor.setHint(getTitle(getActivity(), position)); if (position==1) { editor. setTransformationMethod(PasswordTransformationMethod. getInstance()); } return return(result); } (from Assist/NoAssist/app/src/main/java/com/commonsware/android/assist/no/EditorFragment.java) If we are on the third tab, we create a NoAssistFrameLayout and inflate our EditText into it. Otherwise, we inflate the layout normally. Note that this sample also applies a PasswordTransformationMethod for the second page of the ViewPager (a position of 1), to illustrate the null text that will be recorded as a result. Blocking Assist as a User It is possible that your reaction to all of this is that you want to opt out of Now On Tap as a user. Or, perhaps you want to provide some instructions to your users on how to opt out of Now On Tap. Go to Settings > Apps. There should be an option for advanced app configuration actions (on Nexus-series devices, this is a gear icon in the action bar). Tap that, then choose “Default Apps” to bring up categories of default apps for various actions: 2188 THE ASSIST API (“NOW ON TAP”) Figure 700: Android 6.0 Default Apps Screen in Settings In there, tap on “Assist & voice input”. By default, you should see “Google App” as the chosen option, which means that Now On Tap is active: 2189 THE ASSIST API (“NOW ON TAP”) Figure 701: Android 6.0 Assist & Voice Input Screen in Settings Tapping on that entry will bring up a list of available options, including “None”: Figure 702: Android 6.0 Assist & Voice Input Options in Settings 2190 THE ASSIST API (“NOW ON TAP”) Implementing Your Own Assistant While Now On Tap is pre-installed and pre-activated, and while users can disable Now On Tap, another option for users is to activate some other assistant. Any app that implements the proper pieces of the Assist API will appear in the roster of available assistants for the user to choose from, as described in the previous section. The Assist/AssistLogger sample project represents one such app. Primarily, this app is for diagnostic purposes, showing you exactly what your activity is “leaking” to assistants. It was essential in figuring out how the APIs shown in earlier examples in this chapter worked, for instance. However, it also serves as a demonstration of the minimum requirements to implement an assistant in general. Creating an assistant is technically part of a larger bit of work on handling voice interactions in Android. However, if all you want is an assistant, you can ignore the voice-related bits. A Stub VoiceInteractionService Some of what is needed to set up an assistant is some boilerplate. For example, the entry point for assistants and voice interactions is a custom subclass of VoiceInteractionService. If you only are concerned with implementing an assistant, your VoiceInteractionService can be empty: package com.commonsware.android.assist.logger; import android.service.voice.VoiceInteractionService android.service.voice.VoiceInteractionService; public class AssistLoggerService extends VoiceInteractionService { } (from Assist/AssistLogger/app/src/main/java/com/commonsware/android/assist/logger/AssistLoggerService.java) However, it needs to exist, and in particular it needs to have its entry in your manifest: > /> 2191 THE ASSIST API (“NOW ON TAP”) /> (from Assist/AssistLogger/app/src/main/AndroidManifest.xml) The keys to the manifest entry are: • It needs to have the android:permission attribute, limiting it clients that hold the BIND_VOICE_INTERACTION permission, which should limit clients to those that are part of the device firmware • It needs to have the advertising that it supports the android.service.voice.VoiceInteractionService action string • It needs an android.voice_interaction element, pointing to an XML resource that further configures the voice interaction/assistant implementation The sample project has that metadata in res/xml/assist_service.xml: /> (from Assist/AssistLogger/app/src/main/res/xml/assist_service.xml) There are three attributes required on the root element to enable an assistant: • android:recognitionService points back to your VoiceInteractionService subclass • android:sessionService points to a subclass of VoiceInteractionSessionService (we will examine the project’s implementation shortly) • android:supportsAssist should be true If you want, you can also have an android:settingsActivity attribute, shown in this XML as a commented-out snippet at the end of the file. This can point to an activity in your app. If you have this, a gear icon will appear on the “Assist & voice 2192 THE ASSIST API (“NOW ON TAP”) input” Settings screen that, when tapped, will bring up this activity, to configure the behavior of your assistant. The sample app skips this. A Trivial VoiceInteractionSessionService The service pointed to by android:sessionService in the metadata needs to be a subclass of VoiceInteractionSessionService. The only method that you need to override is onNewSession(), where you can return an instance of a VoiceInteractionSession: package com.commonsware.android.assist.logger; import android.os.Bundle android.os.Bundle; import android.service.voice.VoiceInteractionSession android.service.voice.VoiceInteractionSession; import android.service.voice.VoiceInteractionSessionService android.service.voice.VoiceInteractionSessionService; public class AssistLoggerSessionService extends VoiceInteractionSessionService { @Override public VoiceInteractionSession onNewSession(Bundle args) { return return(new new AssistLoggerSession(this this)); } } (from Assist/AssistLogger/app/src/main/java/com/commonsware/android/assist/logger/AssistLoggerSessionService.java) Here, we return an instance of AssistLoggerSession, which is where all of our real business logic resides for our assistant. Note that this service also should use android:permission to limit clients to those that hold the android.permission.BIND_VOICE_INTERACTION permission: /> (from Assist/AssistLogger/app/src/main/AndroidManifest.xml) The VoiceInteractionSession VoiceInteractionSession has a lot of methods that you can override, both for voice interactions and for assistant invocations. The sample app overrides the minimum required for an assistant, as its mission simply is to log all of the data received by our assistant to files on external storage, for diagnostic purposes. 2193 THE ASSIST API (“NOW ON TAP”) NOTE: Running this sample app on hardware that is actually used with private data is stupid beyond words. Any app can then read the files on external storage and see what information is published by whatever apps are in the foreground at the times when you invoke the assistant. Please use this only on test environments. Basic Setup Akin to components, a VoiceInteractionSession has an onCreate() method, called as part of setting up the session. In there, AssistLoggerSession sets up an output directory for logging the results, assuming that external storage is available: @Override public void onCreate() { super super.onCreate(); if (Environment.MEDIA_MOUNTED .equals(Environment.getExternalStorageState())) { String logDirName= "assistlogger_"+ new SimpleDateFormat("yyyyMMdd'-'HHmmss").format(new new Date()); logDir= new File(getContext().getExternalCacheDir(), logDirName); logDir.mkdirs(); } } (from Assist/AssistLogger/app/src/main/java/com/commonsware/android/assist/logger/AssistLoggerSession.java) onHandleScreenshot() If the user invokes your assistant, you will be called with onHandleScreenshot(). Usually, you will be passed a Bitmap that contains the screenshot. However, if the foreground activity is using FLAG_SECURE, the Bitmap that is passed to you will be null, so make sure you check it before doing anything with it. The AssistLoggerSession forks a ScreenshotThread to save this screenshot in the background: @Override public void onHandleScreenshot(Bitmap screenshot) { super super.onHandleScreenshot(screenshot); 2194 THE ASSIST API (“NOW ON TAP”) if (screenshot!=null null) { new ScreenshotThread(getContext(), logDir, screenshot).start(); } } (from Assist/AssistLogger/app/src/main/java/com/commonsware/android/assist/logger/AssistLoggerSession.java) ScreenshotThread, in turn, just uses compress() on Bitmap to write the image out as a PNG to the directory that we are using for logging: private static class ScreenshotThread extends Thread { private final File logDir; private final Bitmap screenshot; private final Context ctxt; ScreenshotThread(Context ctxt, File logDir, Bitmap screenshot) { this this.ctxt=ctxt.getApplicationContext(); this this.logDir=logDir; this this.screenshot=screenshot; } @Override public void run() { if (logDir!=null null) { try { File f=new new File(logDir, "screenshot.png"); FileOutputStream fos=new new FileOutputStream(f); screenshot.compress(Bitmap.CompressFormat.PNG, 100, fos); fos.flush(); fos.getFD().sync(); fos.close(); MediaScannerConnection .scanFile(ctxt, new String[] {f.getAbsolutePath()}, new String[] {"image/png"}, null null); Log.d(getClass().getSimpleName(), "screenshot written to: "+f.getAbsolutePath()); } catch (IOException e) { Log.e(getClass().getSimpleName(), "Exception writing out screenshot", e); } } else { Log.d(getClass().getSimpleName(), 2195 THE ASSIST API (“NOW ON TAP”) String.format("onHandleScreenshot: %dx%d", screenshot.getWidth(), screenshot.getHeight())); } } } (from Assist/AssistLogger/app/src/main/java/com/commonsware/android/assist/logger/AssistLoggerSession.java) onHandleAssist() onHandleAssist() is your other main assistant callback. Here is where you get: • a Bundle of undocumented stuff • the AssistStructure outlining the contents of the windows, including the view hierarchy • the AssistContent with the Intent, Web Uri, JSON, and so on AssistLoggerSession kicks off an AssistDumpThread to record this data in the background: @Override public void onHandleAssist(Bundle data, AssistStructure structure, AssistContent content) { super super.onHandleAssist(data, structure, content); new AssistDumpThread(getContext(), logDir, data, structure, content).start(); } (from Assist/AssistLogger/app/src/main/java/com/commonsware/android/assist/logger/AssistLoggerSession.java) AssistDumpThread itself is a long class that generates a JSON file containing the information found in the parameters to onHandleAssist(): package com.commonsware.android.assist.logger; import import import import import import import import import android.app.assist.AssistContent android.app.assist.AssistContent; android.app.assist.AssistStructure android.app.assist.AssistStructure; android.content.Context android.content.Context; android.content.Intent android.content.Intent; android.media.MediaScannerConnection android.media.MediaScannerConnection; android.os.Bundle android.os.Bundle; android.util.Log android.util.Log; org.json.JSONArray org.json.JSONArray; org.json.JSONException org.json.JSONException; 2196 THE ASSIST API (“NOW ON TAP”) import import import import import import org.json.JSONObject org.json.JSONObject; java.io.File java.io.File; java.io.FileOutputStream java.io.FileOutputStream; java.io.OutputStreamWriter java.io.OutputStreamWriter; java.io.PrintWriter java.io.PrintWriter; java.util.Set java.util.Set; class AssistDumpThread extends Thread { private final File logDir; private final Bundle data; private final AssistStructure structure; private final AssistContent content; private final Context ctxt; AssistDumpThread(Context ctxt, File logDir, Bundle data, AssistStructure structure, AssistContent content) { this this.ctxt=ctxt.getApplicationContext(); this this.logDir=logDir; this this.data=data; this this.structure=structure; this this.content=content; } @Override public void run() { if (logDir!=null null) { JSONObject json=new new JSONObject(); try { json.put("data", dumpBundle(data, new JSONObject())); } catch (JSONException e) { Log.e(getClass().getSimpleName(), "Exception saving data", e); } try { json.put("content", dumpContent(new new JSONObject())); } catch (JSONException e) { Log.e(getClass().getSimpleName(), "Exception saving content", e); } try { json.put("structure", dumpStructure(new new JSONObject())); } 2197 THE ASSIST API (“NOW ON TAP”) catch (JSONException e) { Log.e(getClass().getSimpleName(), "Exception saving structure", e); } File f=new new File(logDir, "assist.json"); try { FileOutputStream fos=new new FileOutputStream(f); OutputStreamWriter osw=new new OutputStreamWriter(fos); PrintWriter pw=new new PrintWriter(osw); pw.print(json.toString(2)); pw.flush(); fos.getFD().sync(); fos.close(); MediaScannerConnection .scanFile(ctxt, new String[] {f.getAbsolutePath()}, new String[] {"application/json"}, null null); Log.d(getClass().getSimpleName(), "assist data written to: "+f.getAbsolutePath()); } catch (Exception e) { Log.e(getClass().getSimpleName(), "Exception writing out assist data", e); } } else { Log.d(getClass().getSimpleName(), "onHandleAssist"); } } JSONObject dumpBundle(Bundle b, JSONObject json) throws JSONException { Set keys=b.keySet(); for (String key : keys) { json.put(key, wrap(b.get(key))); } return (json); } private JSONObject dumpContent(JSONObject json) throws JSONException { 2198 THE ASSIST API (“NOW ON TAP”) JSONObject extras=new new JSONObject(); if (content.getExtras()!=null null) { json.put("extras", extras); dumpBundle(content.getExtras(), extras); } if (content.getIntent()!=null null) { json.put("intent", content.getIntent().toUri(Intent.URI_INTENT_SCHEME)); } json.put("structuredData", wrap(content.getStructuredData())); json.put("webUri", wrap(content.getWebUri())); return (json); } private JSONObject dumpStructure(JSONObject json) throws JSONException { return (json.put("windows", dumpStructureWindows(new new JSONArray()))); } private JSONArray dumpStructureWindows(JSONArray windows) throws JSONException { for (int i=0; i (from DataBinding/Focus/app/src/main/res/layout/request_focus.xml) Here, if the device has an available physical keyboard, we put the focus on the first EditText widget, so that the user can start typing right away. But, if the device lacks an available physical keyboard, we put the focus on the Button, to avoid the IME appearing right away. Offering Mouse Context Menus One thing that users of mice and trackpads are used to having are context menus, typically displayed as the result of a right-mouse click. More specifically, they are used to a popup menu appearing adjacent to the mouse pointer when they click the right-mouse button. Android has had its own context menu system since API Level 1. However, it does not look a lot like what desktop users are used to. We can create such a menu ourselves, but it takes a little work, due to bugs and limitations in Android. Ideally, we would use PopupMenu. This does pretty much what the class name implies: displays a popup window containing a menu, driven by a menu resource. However, that popup window will appear to drop down from some anchor View that we specify, and there is no way in the public API to adjust its position to be closer to the mouse pointer. Hence, for larger widgets — such as rows in a ListView or RecyclerView — PopupMenu will result in a menu that can appear fairly far away from the mouse pointer, which will be aggravating. PopupWindow and ListPopupWindow both allow for fine-grained positioning, which make them better candidates for our purposes. Of the two, ListPopupWindow handles the notion of a scrolling list, which may be useful for longer menus. And, we can populate its contents from a simple ListAdapter, like an ArrayAdapter. The KBMouse/Context sample project is a clone of the KBMouse/Hotkeys sample app that adds in a ListPopupWindow for a mouse-driven context menu… but it takes a bit of work. First, we need to define what goes in the list of the ListPopupWindow. A simple solution for that is to use a string-array resource: 2361 KEYBOARD AND MOUSE INPUT > @string/menu_video @string/menu_thumbnail (from KBMouse/Context/app/src/main/res/values/arrays.xml) Here, the two items are references to string resources, for internationalization purposes (in theory, at least). All of our business logic for adding the context menu lies in the RowController — just as it handles clicks (to play the video in a standalone player) and long-clicks (to initiate a drag-and-drop), it can now handle context menus. First, in the RowController constructor, we register the RowController as handling touch events for the row, via setOnTouchListener(): RowController(View row, ChoiceCapableAdapter adapter) { super super(row); this this.adapter=adapter; title=(TextView)row.findViewById(android.R.id.text1); thumbnail=(ImageView)row.findViewById(R.id.thumbnail); row.setOnClickListener(this this); row.setOnLongClickListener(this this); row.setOnTouchListener(this this); } (from KBMouse/Context/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/RowController.java) That requires RowController to implement the View.OnTouchListener interface, and therefore requires RowController to override onTouch(): @Override public boolean onTouch(View v, MotionEvent event) { if ((event.getButtonState() & MotionEvent.BUTTON_SECONDARY)!=0 && event.getAction()==MotionEvent.ACTION_DOWN) { adapter.onChecked(position, true true, true true); String[] items= itemView .getContext() 2362 KEYBOARD AND MOUSE INPUT .getResources() .getStringArray(R.array.popup); ArrayAdapter adapter= new ArrayAdapter<>(itemView.getContext(), android.R.layout.simple_list_item_1, items); final ListPopupWindow popup= new ListPopupWindow(itemView.getContext()); popup.setAnchorView(itemView); popup.setHorizontalOffset((int)event.getX()); popup.setVerticalOffset((int)event.getY()-itemView.getHeight()); popup.setAdapter(adapter); popup.setWidth(measureContentWidth(itemView.getContext(), adapter)); popup.setOnItemClickListener( new AdapterView.OnItemClickListener() { @Override public void onItemClick(AdapterView parent, View view, int position, long id) { if (position==0) { ((MainActivity)itemView.getContext()) .playVideo(videoUri); } else { ((MainActivity)itemView.getContext()) .showLargeThumbnail(videoUri); } popup.dismiss(); } }); popup.show(); return return(true true); } return return(false false); } (from KBMouse/Context/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/RowController.java) To determine if a given MotionEvent is a trigger for the context menu, we check two things: 1. Is the BUTTON_SECONDARY pressed? 2363 KEYBOARD AND MOUSE INPUT 2. Is this a “down” event (ACTION_DOWN)? If yes, we tell our ChoiceCapableAdapter to check this row, so it is clear to the user what they have right-clicked over. Then, we load in the string array from the resources and wrap that in a standard ArrayAdapter. At that point, we can begin configuring the ListPopupWindow. The constructor for the ListPopupWindow takes a Context. We grab the Context from the itemView field of this ViewHolder, which represents our row. We then call five configuration methods to set up the look-and-feel of the ListPopupWindow. The first four are fairly straightforward: • setAnchorView() specifies the View that this popup is anchored to. In this case, we use the row itself (itemView). • setHorizontalOffset() and setVerticalOffset() indicate, from the upperleft corner of the anchor view, where to place the upper-left corner of the ListPopupView. We want the ListPopupView to be adjacent to the mouse pointer, and the getX() and getY() values of the MotionEvent tell us where inside the itemView the user clicked. However, the default position of the ListPopupWindow is to be anchored to the lower left corner of the anchor view, not the upper left corner. To adjust the horizontal position, we can simply use getX(), since both getX() and the default horizontal position of the ListPopupWindow are on the left. However, the offset for the vertical position needs to be a negative value, as we want to raise the ListPopupWindow to where the mouse pointer is. That value is the difference between the Y coordinate of the mouse pointer (getY()) and the height of the row (itemView.getHeight()). • setAdapter() provides the ArrayAdapter to populate the list in the ListPopupWindow. The fifth method — setWidth() — is more complex than it should be, due to a bug. Ideally, we would call setWidth(ListPopupWindow.WRAP_CONTENT). According to the documentation, this will set the width of the ListPopupWindow to be the width of the content of the adapter. Unfortunately, this does not work. And, since that bug has been outstanding since 2013, it is unlikely that it will ever work. The workaround — as documented in Stack Overflow – is to calculate the maximum width of our adapter rows ourselves, then call setWidth() with that pixel value. This is isolated in a measureContentWidth() method: 2364 KEYBOARD AND MOUSE INPUT // based on http://stackoverflow.com/a/26814964/115145 private int measureContentWidth(Context ctxt, ListAdapter listAdapter) { ViewGroup mMeasureParent = null null; int maxWidth = 0; View itemView = null null; int itemType = 0; final ListAdapter adapter = listAdapter; final int widthMeasureSpec = View.MeasureSpec.makeMeasureSpec(0, View.MeasureSpec.UNSPECIFIED); final int heightMeasureSpec = View.MeasureSpec.makeMeasureSpec(0, View.MeasureSpec.UNSPECIFIED); final int count = adapter.getCount(); for (int i = 0; i < count; i++) { final int positionType = adapter.getItemViewType(i); if (positionType != itemType) { itemType = positionType; itemView = null null; } if (mMeasureParent == null null) { mMeasureParent = new FrameLayout(ctxt); } itemView = adapter.getView(i, itemView, mMeasureParent); itemView.measure(widthMeasureSpec, heightMeasureSpec); final int itemWidth = itemView.getMeasuredWidth(); if (itemWidth > maxWidth) { maxWidth = itemWidth; } } return maxWidth; } (from KBMouse/Context/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/RowController.java) This implementation iterates over the items in the adapter, has the adapter create row views for each row (using a bit of light caching to try to recycle row views in simple adapters), then determines the measured width of those rows. The longest measured width is then used as the result. This works for simple rows and short lists, which is all we really need here anyway. 2365 KEYBOARD AND MOUSE INPUT Then, we call setOnItemClickListener() to register a listener to find out when rows in the list in the ListPopupWindow are clicked. This works the same as with a ListView. In our case, we look at the passed-in position, and route to the activity’s playVideo() or showLargeThumbnail() methods according to which list item the user clicked upon. We then dismiss() the ListPopupWindow, so it goes away after the user clicked on one of the list items. Finally, we can show() the ListPopupWindow, so it displays its list to the user. From the user’s perspective, right-clicking over one of the videos in the list offers the context menu: Figure 729: Right-Mouse Context Menu What is missing is the ability for the user to dismiss the context menu. If the user clicks outside the ListPopupWindow, it goes away as expected. However, the underlying click event is still processed. So, if the user clicks over the VideoView or large thumbnail ImageView, everything looks fine. If the user clicks over one of the RecyclerView rows… the clicked-upon video starts playing back in a standalone video player, rather than just dismissing the ListPopupWindow. This will be addressed in a future edition of this sample app. Also note that API Level 23 offers setOnContextClickListener() on View. This works like setOnClickListener() and setOnLongClickListener(), letting you know via an OnContextClickListener that the view was “context-clicked”. However, you do not get details of the touch event, and so you have no good means of positioning the popup to be near where it should go. 2366 KEYBOARD AND MOUSE INPUT Offering Tooltips Users of desktop operating systems, and even Web apps, are used to having tooltips available on key UI elements (e.g., buttons). In a mouse-driven environment, these usually appear after the mouse has hovered over the UI element for a short while. Touchscreens can also offer similar contextual help. For example, if the user longpresses on an action bar item’s icon, a Toast will appear with the item’s title. So, there are two pieces to the puzzle of offering tooltips: 1. How do you decide when to show a tooltip? 2. What is the UI for the tooltip itself? As with many things in Android, there are two options, depending on what version of Android you are running on. Android 7.1 and Older This section will focus on the first piece — how you decide when to show a toolip — using a simple Toast for the tooltip UI. There are many Android libraries for tooltip UIs, which you may wish to investigate. Hover Events API Level 14 added setOnHoverListener() to View. This, and the corresponding OnHoverListener interface, allow developers to find out when the user is “hovering” over a widget. This can be triggered by a mouse or by some styluses. The onHover() method of your OnHoverListener will be called when a change in the state of hovering occurs. You are given the affected View, along with the MotionEvent that triggered the state change. The MotionEvent should have one of three actions: • ACTION_HOVER_ENTER, meaning that the user has begun hovering over the view • ACTION_HOVER_MOVE, meaning that the user was already hovering over the view, but has moved the mouse pointer, so the hover position within the view bounds has changed • ACTION_HOVER_EXIT, meaning that the user is no longer hovering over the view 2367 KEYBOARD AND MOUSE INPUT The KBMouse/Tooltip sample project is a clone of the KBMouse/Hotkeys sample app that adds in tooltip support for long-clicks and hovers. MainActivity now implements the OnLongClickListener and OnHoverListener interfaces, so we can register those listeners on our VideoView and large thumbnail ImageView: @Override public void onCreate(Bundle state) { super super.onCreate(state); setContentView(R.layout.main); player=(VideoView)findViewById(R.id.player); if (player!=null null) { player.setOnDragListener(this this); player.setOnHoverListener(this this); player.setOnLongClickListener(this this); } thumbnailLarge=(ImageView)findViewById(R.id.thumbnail_large); if (thumbnailLarge!=null null) { thumbnailLarge.setOnDragListener(this this); thumbnailLarge.setOnHoverListener(this this); thumbnailLarge.setOnLongClickListener(this this); } setLayoutManager(new new LinearLayoutManager(this this)); adapter=new new VideoAdapter(getRecyclerView()); setAdapter(adapter); getRecyclerView().requestFocus(); if (state!=null null) { isInPermission= state.getBoolean(STATE_IN_PERMISSION, false false); } if (hasFilesPermission()) { loadVideos(); } else if (!isInPermission) { isInPermission=true true; ActivityCompat.requestPermissions(this this, new String[] {Manifest.permission.READ_EXTERNAL_STORAGE}, REQUEST_PERMS); } } 2368 KEYBOARD AND MOUSE INPUT (from KBMouse/Tooltip/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/MainActivity.java) We will see why we are not registering for events on the RecyclerView a bit later in this chapter. The onLongClick() method for the OnLongClickListener forwards the event to a showTooltip() method, providing a string resource with the particular message to show: @Override public boolean onLongClick(View v) { if (v==thumbnailLarge) { showTooltip(R.string.tooltip_thumbnail); } else if (v==player) { showTooltip(R.string.tooltip_player); } else { return return(false false); } return return(true true); } (from KBMouse/Tooltip/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/MainActivity.java) showTooltip() shows a Toast… with a slight wrinkle: private void showTooltip(@StringRes int message) { if (tooltip!=null null) { tooltip.cancel(); } tooltip=Toast.makeText(this this, message, Toast.LENGTH_LONG); tooltip.show(); } (from KBMouse/Tooltip/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/MainActivity.java) If, while a tooltip Toast is showing, the user long-clicks on a different widget, we want to show that tooltip immediately. By default, we would have to wait until the first Toast completed its duration. Toast has a cancel() method that does one of three things: 1. If the Toast has not yet been shown, it removes the Toast from the roster of pending Toasts 2369 KEYBOARD AND MOUSE INPUT 2. If the Toast is presently showing, it gets rid of the Toast 3. If the Toast was shown previously, it does nothing, as nothing is needed So, we hold onto the most-recent tooltip Toast in a field named tooltip, and we cancel() it before showing the next tooltip. The onHover() method for the OnHoverListener forwards the event to a private onHover(), where we supply the string resource of the tooltip message: @Override public boolean onHover(View v, MotionEvent event) { if (v==player) { onHover(event, R.string.tooltip_player, player); } else if (v==thumbnailLarge) { onHover(event, R.string.tooltip_thumbnail, thumbnailLarge); } else { return return(false false); } return return(true true); } (from KBMouse/Tooltip/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/MainActivity.java) And that is where things start to get complicated. Detecting a Long-Enough Hover The problem is that while we can find out when the user starts and stops hovering over a view, we need additional code to determine when some time has elapsed between those two events. So, for example, if you want to show a tooltip one second after the user begins hovering over a view, you need to: • Arrange to find out when one second has elapsed after the user starts hovering over the view • Cancel that work if the user stops hovering over that view, either preventing the tooltip from appearing (if it has not done so yet) or perhaps causing the tooltip to vanish immediately (if it is presently being displayed) postDelayed() provides a nice cheap way of handling this. We can schedule Runnable to be invoked after our one-second delay, and we can use 2370 a KEYBOARD AND MOUSE INPUT removeCallbacks() to cancel the Runnable if the user stops hovering over that widget. However, we do not know the exact sequence of hover events. It may be that we are given an ACTION_HOVER_ENTER event for a new widget prior to ACTION_HOVER_EXIT of the previous widget. Hence, we need to track per-widget state. In this case, the sample app holds onto a Runnable per widget for which we are displaying tooltips, in a SparseArray object: private SparseArray hoverTimers= new SparseArray<>(); (from KBMouse/Tooltip/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/MainActivity.java) A SparseArray is a data structure that allows ArrayList-style indexed access to objects, but it does not assume that the index values are consecutive. Basically, it replaces a HashMap of Integer objects. The SparseArray allows us to use widget IDs as the index values, so as long as each of our tooltip-enabled widgets have unique IDs, we can track their state in the SparseArray. Our private edition of onHover() uses this SparseArray: private void onHover(MotionEvent event, @StringRes final int message, final View anchor) { Runnable hover=hoverTimers.get(anchor.getId()); if (hover==null null && (event.getAction()==MotionEvent.ACTION_HOVER_ENTER || event.getAction()==MotionEvent.ACTION_HOVER_MOVE)) { hover=new new Runnable() { @Override public void run() { showTooltip(message); } }; hoverTimers.put(anchor.getId(), hover); thumbnailLarge.postDelayed(hover, TOOLTIP_DELAY); } else if (hover!=null null && event.getAction()==MotionEvent.ACTION_HOVER_EXIT) { thumbnailLarge.removeCallbacks(hover); hoverTimers.remove(anchor.getId()); 2371 KEYBOARD AND MOUSE INPUT } } (from KBMouse/Tooltip/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/MainActivity.java) There are two scenarios that we care about: 1. The user starts hovering over a widget, and we have not yet set up the timer Runnable, as it does not exist in the SparseArray. So, we create the Runnable to show our tooltip (via showTooltip()), stuff it in the SparseArray, and use postDelayed() to trigger the Runnable after a second. 2. The user stops hovering over a widget, and we already have the timer Runnable. In this case, we call removeCallbacks() to ensure that this Runnable is not run (if it has not run already), plus remove it from the SparseArray. The net effect is that our Runnable will be invoked if one second elapses after the user starts hovering over a widget and the user has not stopped hovering over that same widget. showTooltip() raises a Toast to serve as a crude tooltip: private void showTooltip(@StringRes int message) { if (tooltip!=null null) { tooltip.cancel(); } tooltip=Toast.makeText(this this, message, Toast.LENGTH_LONG); tooltip.show(); } (from KBMouse/Tooltip/app/src/main/java/com/commonsware/android/kbmouse/hotkeys/MainActivity.java) However, it is possible that the user displays one tooltip, then quickly hovers over another widget, and that our one-second delay is shorter than the Toast display duration. So, we hold onto each Toast that we display, and we cancel() it before showing the next one. That way, if one Toast is outstanding when we need to show a different Toast, we can make the switch immediately, rather than having to wait for the rest of the first Toast display duration to elapse before showing the next one. 2372 KEYBOARD AND MOUSE INPUT What We Are Missing However, the tooltip for the VideoView will not display. VideoView is an odd widget, consuming a lot of touch events for no really good reason. Most likely, for a sophisticated Android app, you will want to skip VideoView and use something else, such as a MediaPlayer tied to your own SurfaceView or TextureView. This sample app does not attempt to provide tooltips for the rows in the RecyclerView. Even though we are set up to show a tooltip for the RecyclerView overall, the hover events are for the rows, not the RecyclerView, as the RecyclerView itself is not visible. If you wanted tooltips here, your choices are: • Have the tooltip for the whole RecyclerView, forwarding hover events from rows up to your tooltip-management logic • Have tooltips per row, using some different system than our SparseArray, as the row widget IDs will all be the same by default Android 8.0+ Android has had the occasional tooltip-like feature, such as the tooltip that you get on action bar items when long-pressing them. Android 8.0 extends this to all widgets. Simply provide the desired text via android:tooltipText or setTooltipText(). A tooltip will then appear when either the user long-presses the widget or if the user hovers over the widget. In both cases, though, if the long-press or hover event is consumed by something else, the tooltip is not shown. The KBMouse/TooltipO sample project is a clone of the preceding sample app, where we switch to using the tooltip implementation in Android 8.0+. Specifically, our large-screen layout has tooltips for the VideoView and ImageView widgets, using android:tooltipText: > > > > (from KBMouse/TooltipO/app/src/main/res/layout-w800dp/main.xml) The result are tooltips reminiscent of those from the original sample: 2374 KEYBOARD AND MOUSE INPUT Figure 730: Tooltip From Long-Press of ImageView Hovering over either widget, or long-pressing either widget, will bring up the tooltip. Pointer Capture On a desktop operating system, the “pointer” refers to the mouse cursor. This feature is normally handled by the operating system. “Pointer capture” refers to when a widget blocks the normal mouse cursor, typically because it is going to use the mouse in some way for which the normal pointer would be inappropriate. In Android 8.0+, you can call requestPointerCapture() and releasePointerCapture() to have a widget operate in pointer-capture mode or not. The vast majority of Android apps should not need this. 2375 Viewing PDFs The Portable Document Format — better known as PDF — has been around for over two decades, and it is still going strong today. As a result, we often have a need to show PDF files to users, whether those files are: • Shipped with the app, such as documentation • Downloaded by the app, such as email attachments for the mail client that you are writing • Otherwise managed by the app, such as with PDF files held in cloud storage that your app is managing on behalf of the user • And so on This is another one of those topics that seems fairly simple on the surface, but can get complicated based on your requirements. In particular, if you want to try to present the PDF to the user in your app, as opposed to launching some external PDF viewing app, while you have a few options, they all have their issues. In this chapter, we will review several ways of displaying a PDF to the user, so you can choose what approach (or approaches) are the best fit for your requirements. Prerequisites Understanding this chapter requires that you have read the core chapters of this book. 2377 VIEWING PDFS The Criteria If there are several ways of displaying a PDF, we need some criteria by which to evaluate those options and make our choice. Here are some likely criteria to use, though you may have others that are more specific to your app’s requirements. Where is the PDF? Most of the PDF-viewing options assume that the PDF is on the device already. However, even within that, there are a few possibilities as to where the PDF might be: • Internal storage (e.g., getFilesDir()) of your app • External storage (e.g., getExternalFilesDir()) associated with your app • Common locations on external storage, such as the standard Documents directory • Some Uri that you obtained via ACTION_GET_CONTENT or ACTION_OPEN_DOCUMENT • An asset or raw resource within your app And, occasionally, developers get boxed into a corner, with a requirement to show a PDF without downloading the PDF. Does It Work Offline? The opposite problem is the offline viewing experience. If the PDF is on the device already, ideally, the PDF-viewing technology can show that PDF without having to have an active Internet connection. After all, many users do not have continuous Internet access. How Complex is the PDF? While the PDF file format has been around for years and years, it has expanded over that time. In the beginning, PDF did not offer things like form fields, annotations, and the like. The more feature-rich your PDF is, the more likely it is that some PDF viewers may be incapable of handling all of those features. This is not restricted to in-app viewing solutions. PDF viewing apps vary in capability, and there will be some that either do not support your desired features 2378 VIEWING PDFS (e.g., allow the user to fill in forms) or only will if the user unlocks the feature through some purchase. How Stable is the Solution? Many PDF-viewing apps are continuously updated. If the user happens to choose one that is not, that is the user’s fault, not yours. However, when you build in PDF viewing into your app, now you need to ensure that your solution is up to date and likely to stay stable for the duration of your app’s use. How Private is the PDF? The big one, in terms of the major options for viewing the PDF, is the degree of privacy that is tied to that PDF. If the document comes from the user — for example, it came in an email attachment to the user’s inbox that you are managing — you should assume a modest level of privacy. Do not ship that PDF to other servers without the user’s approval. However, if the user wants to view the PDF, you should not be afraid of allowing the user to do so using the user’s chosen PDF viewing app. If the document is more tightly controlled by your app — for example, it came as an attachment to some secure messaging client that you are writing — you may be nervous about granting other apps access to that PDF. After all, you do not necessarily know what those other apps might do with the PDF. Where things get very messy is when the developers think that they “own” the PDF, and therefore are trying to restrict that PDF’s access, much as how a DRM solution tries to restrict access to videos. Many PDF-viewing apps offer printing, sharing, and other things that the user might want, but that the developers do not want. In truth, it is rather likely that the user can get to the PDF anyway, whether the developers like it or not, by various means (e.g., extracting PDFs packaged in the APK using an ordinary ZIP file utility). But, this seems to be the #1 reason why some developers are trying to view PDF files within their own app: treating the user as the enemy. 2379 VIEWING PDFS The Classic Solution: ACTION_VIEW The quintessential solution — and the one that you should focus on first — is to use startActivity() with an ACTION_VIEW Intent, where the Uri in that Intent points to your PDF file: startActivity(new new Intent(Intent.ACTION_VIEW, uriToThePdf)); This is quick, easy, and gives the user control over how the PDF is rendered, as they can (usually) choose the PDF viewer to use. However, this is not a universal solution: • Android itself does not ship with a PDF viewer app, and therefore some devices will not ship with a PDF viewer app. You wind up with an ActivityNotFoundException from your startActivity() call, and then you need to guide the user to install a PDF viewer app. • The user may not be able to install such an app, due to limitations imposed by device owner APIs or because the user is using the device on a secondary user account that lacks app-installation capability. • For maximum compatibility, you will need to set up a FileProvider (or the equivalent) and serve your PDF through it, particularly on Android 7.0+ devices, where the file scheme for Uri values is banned, in effect. If you are concerned that the user might choose a PDF viewer app that is malware, or is one that has features that you dislike, you could use PackageManager and queryIntentActivities() to find all activities that support ACTION_VIEW for your PDF file. From there, you can find out the apps associated with those activities, and filter that based on a whitelist (or blacklist) of PDF viewer apps. Then, present your own “chooser”-style UI to allow the user to choose from among the valid options. The Really Bad Idea: Google Docs Some developers, though, try desperately to avoid using external PDF viewer apps. The approach that many of those developers try is the worst available option: have Google Docs render the PDF in a WebView, using code reminiscent of: WebView webview=(WebView)findViewById(R.id.webview); 2380 VIEWING PDFS webview.getSettings().setJavaScriptEnabled(true); webview.loadUrl("http://drive.google.com/viewerng/ viewer?embedded=true&url=" + urlToYourPdf); This has many poor characteristics: • It requires that the PDF be available publicly on the Web, for Google Docs to be able to access it. From a security standpoint, many more attackers can access the PDF online than can on an Android device. • If the PDF is not already available publicly on the Web, you would need to run a server, or employ some cloud storage or similar service, to host that PDF, adding to your complexity. • If the PDF needs to be uploaded, now you are consuming lots of extra bandwidth. Not only did you (probably) download the PDF from somewhere, but now you have to re-upload it somewhere, then download whatever bits and bytes the WebView winds up using to display it, as served from Google Docs. • There is no requirement that Google keep this Google Drive view-anarbitrary-PDF URL working. As soon as they change it, your app breaks. As soon as they discontinue it, this approach has to be replaced anyway. • This approach requires a live Internet connection. There is no offline option. Pretty much anything else will be better than this solution. The Built-In Option: PdfRenderer Routinely, developers are astonished that Android does not ship with some sort of PDF-viewing app, the way that desktop operating systems do. The closest thing that Android has to a built-in PDF viewer is PdfRenderer. This class was added in API Level 21 (Android 5.0), and it allows you to render pages of a PDF to Bitmap objects. In turn, you can then use those Bitmap objects to present the pages to the user, by one means or another. This solution has severe limitations: • As noted, it requires Android 5.0, leaving out older devices. • It requires a seekable stream on the content, in the form of a ParcelFileDescriptor. The net effect of this is that you can only reliably render something backed by a file. Conversely, you cannot render something 2381 VIEWING PDFS backed by a pipe. This means that you cannot render assets, raw resources, a PDF that you decrypt into a memory buffer, and so on. • It chokes on complex PDF files. For example, the author of this book started testing it with this short research paper, only to determine (eventually) that PdfRenderer simply cannot render that PDF. PdfRenderer was added with an eye towards print preview, and so its implementation may be focused on the sorts of PDFs that you can generate for printing, as opposed to arbitrary PDFs. • It only gives you Bitmap objects. You still have to implement a UI to present those Bitmap objects to the user. The PDF/PdfRenderer sample project illustrates the use of PdfRenderer. The RecyclerView We need to present pages to the user. In a typical PDF viewer, the user can scroll or swipe to move between pages. One could use a ViewPager for that role. However, large Bitmap objects really should be reused, and ViewPager does not make it easy to reuse objects. A RecyclerView would be a better choice. The chapter on advanced RecyclerView uses demonstrates setting up a RecyclerView as a replacement for ViewPager for page-at-a-time presentations. The PdfRenderer sample app uses one of those techniques, involving SnapHelper, for presenting the pages to the user. Hence, our UI is a RecyclerView with a light gray background: (from PDF/PdfRenderer/app/src/main/res/layout/main.xml) In onCreate(), our MainActivity sets up that RecyclerView with a LinearLayoutManager, along with a PagerSnapHelper named snapperCarr: pager.setLayoutManager(new new LinearLayoutManager(this this, LinearLayoutManager.HORIZONTAL, false false)); 2382 VIEWING PDFS snapperCarr.attachToRecyclerView(pager); (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/MainActivity.java) Eventually, we will tie in a RecyclerView.Adapter and RecyclerView.ViewHolder classes, named PageAdapter and PageController. However, there is nothing to render at the outset, as we do not have a PDF to use. Getting the PDF Later samples in this chapter happen to use PDF rendering technologies that can work with ordinary streams. In those cases, we can package some PDFs as assets, to provide sample behavior without the user having to rummage around and find a PDF. Alas, that is not an option with PdfRenderer. So, we need to let the user find a PDF on external or removable storage. To do that, we have an action bar item named “Open” that leads to an open() method on MainActivity: Intent i=new new Intent() .setType("application/pdf") .setAction(Intent.ACTION_OPEN_DOCUMENT) .addCategory(Intent.CATEGORY_OPENABLE); startActivityForResult(i, REQUEST_OPEN); } (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/MainActivity.java) Here, we use the Storage Access Framework, invoking an ACTION_OPEN_DOCUMENT Intent, requesting PDF files. We get control again in onActivityResult(): protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (resultCode==Activity.RESULT_OK) { pickedDocument=data.getData(); show(pickedDocument); } 2383 VIEWING PDFS } (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/MainActivity.java) If the user chose a PDF, we stuff its Uri into a pickedDocument field, plus call a private show() method: try { adapter=new new PageAdapter(getLayoutInflater(), getContentResolver().openFileDescriptor(uri, "r")); pager.setAdapter(adapter); } catch (java.io.IOException e) { Log.e("PdfRenderer", getString(R.string.toast_open), e); Toast.makeText(this this, R.string.toast_open, Toast.LENGTH_LONG).show(); } } (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/MainActivity.java) show() creates a PageAdapter, giving it a LayoutInflater and a ParcelFileDescriptor on the Uri, obtained by calling openFileDescriptor() on ContentResolver. We then attach PageAdapter to our pager-style RecyclerView. a To handle configuration changes, we hold onto pickedDocument in the saved instance state Bundle: protected void onSaveInstanceState(Bundle outState) { super super.onSaveInstanceState(outState); outState.putParcelable(STATE_PICKED, pickedDocument); } (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/MainActivity.java) …and restore it in onCreate(): public void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.main); pager=(RecyclerView)findViewById(R.id.pager); pager.setLayoutManager(new new LinearLayoutManager(this this, LinearLayoutManager.HORIZONTAL, false false)); snapperCarr.attachToRecyclerView(pager); 2384 VIEWING PDFS if (savedInstanceState!=null null) { pickedDocument=savedInstanceState.getParcelable(STATE_PICKED); if (pickedDocument!=null null) { show(pickedDocument); } } } (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/MainActivity.java) In onDestroy(), we call a close() method on PageAdapter — we will see the role of close() shortly: protected void onDestroy() { if (adapter!=null null) { adapter.close(); } super super.onDestroy(); } (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/MainActivity.java) Adding the PdfRenderer PageAdapter is surprisingly short RecyclerView.Adapter API: and mostly is focused on implementing the package com.commonsware.android.pdfrenderer; import import import import import import android.graphics.pdf.PdfRenderer android.graphics.pdf.PdfRenderer; android.os.ParcelFileDescriptor android.os.ParcelFileDescriptor; android.support.v7.widget.RecyclerView android.support.v7.widget.RecyclerView; android.view.LayoutInflater android.view.LayoutInflater; android.view.ViewGroup android.view.ViewGroup; java.io.IOException java.io.IOException; class PageAdapter extends RecyclerView.Adapter { private final LayoutInflater inflater; private final PdfRenderer renderer; PageAdapter(LayoutInflater inflater, ParcelFileDescriptor pfd) throws IOException { 2385 VIEWING PDFS this this.inflater=inflater; renderer=new new PdfRenderer(pfd); } @Override public PageController onCreateViewHolder(ViewGroup parent, int viewType) { return return(new new PageController(inflater.inflate(R.layout.page, parent, false false))); } @Override public void onBindViewHolder(PageController holder, int position) { PdfRenderer.Page page=renderer.openPage(position); holder.setPage(page); page.close(); } @Override public int getItemCount() { return return(renderer.getPageCount()); } void close() { renderer.close(); } } (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/PageAdapter.java) In the constructor, we create an instance of a PdfRenderer, passing in the ParcelFileDescriptor on our PDF file. In onCreateViewHolder(), we create an instance of a PageController, passing it an inflated layout representing the page contents — we will examine this in greater detail shortly. In onBindViewHolder(), we ask the PdfRenderer to give us a PdfRenderer.Page for the page identified by our position, via an openPage() method. We then pass that to the PageController via a setPage() method, before we close() the Page. It is the responsibility of PageController to ensure that it does everything that it needs to do with that page before returning from setPage(). getItemCount() returns getPageCount(). the number of pages in the PDF, as determined by 2386 VIEWING PDFS Finally, close() calls close() on the PdfRenderer, to let it release any resources that it is holding onto, such as that ParcelFileDescriptor. Showing the Pages The real fun, of course, is in PageController, for rendering a page of the PDF into a Bitmap to be shown in a page of our pager-style RecyclerView. To allow for pinch-to-zoom functionality, the PdfRenderer sample app uses Dave Morrissey’s SubsamplingScaleImageView: (from PDF/PdfRenderer/app/src/main/res/layout/page.xml) This has a 16dp margin on all four sides, causing each page of the PDF to appear to be floating over the light gray background of the RecyclerView itself. Android’s PdfRenderer does not put any frame around its rendered page, leaving that up to you. PageController grabs the SubsamplingScaleImageView in the PdfRenderer.Page and a Bitmap to populate it in setPage(): constructor, then uses package com.commonsware.android.pdfrenderer; import import import import import import import import import import import android.graphics.Bitmap android.graphics.Bitmap; android.graphics.pdf.PdfRenderer android.graphics.pdf.PdfRenderer; android.os.Environment android.os.Environment; android.support.v7.widget.RecyclerView android.support.v7.widget.RecyclerView; android.view.View android.view.View; android.widget.ImageView android.widget.ImageView; com.davemorrissey.labs.subscaleview.ImageSource com.davemorrissey.labs.subscaleview.ImageSource; com.davemorrissey.labs.subscaleview.SubsamplingScaleImageView com.davemorrissey.labs.subscaleview.SubsamplingScaleImageView; java.io.File java.io.File; java.io.FileNotFoundException java.io.FileNotFoundException; java.io.FileOutputStream java.io.FileOutputStream; class PageController extends RecyclerView.ViewHolder { private final SubsamplingScaleImageView iv; private Bitmap bitmap; 2387 VIEWING PDFS PageController(View itemView) { super super(itemView); iv=(SubsamplingScaleImageView)itemView.findViewById(R.id.page); } void setPage(PdfRenderer.Page page) { if (bitmap==null null) { int height=2000; int width=height * page.getWidth() / page.getHeight(); bitmap=Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888); } bitmap.eraseColor(0xFFFFFFFF); page.render(bitmap, null null, null null, PdfRenderer.Page.RENDER_MODE_FOR_DISPLAY); iv.resetScaleAndCenter(); iv.setImage(ImageSource.cachedBitmap(bitmap)); } } (from PDF/PdfRenderer/app/src/main/java/com/commonsware/android/pdfrenderer/PageController.java) In setPage(), we lazy-create a Bitmap, set to 2000 pixels high and whatever width would be appropriate based on the aspect ratio of the page. This is a simple implementation, suitable for a PDF where all pages have the same aspect ratio. A more sophisticated sample would use some form of object pool for Bitmap objects based on aspect ratio. Note that the Bitmap needs to be ARGB_8888, exacerbating its memory usage. Attempts to use RGB_565 — thereby cutting memory usage in half per page — fail with an error from PdfRenderer. Actually rendering the page to the Bitmap is performed by the render() method on the Page. It takes the Bitmap, an optional Rect indicating a subset of the page to be rendered, an optional Matrix to be applied to transform the rendering, and a “render mode” to indicate if this is for use on a screen or (somehow) on a printed page. However, render() does not do anything to the Bitmap other than render the page’s contents. In particular, it does not clear the Bitmap ahead of time. Since we are reusing the Bitmap objects, by default, as those Bitmap objects get reused, they would accumulate page contents, which is not what we want. Also, render() does not assume any particular background color for pages, if such a color was not specified in the PDF. Instead, it just renders the “ink” on top of the Bitmap, with 2388 VIEWING PDFS everything else left alone. So, we use eraseColor() to reset the Bitmap to white before we call render(), so we clear out any previous page’s content, and so we have a solid white background for our pages. Not only are we reusing the Bitmap, but we are reusing the SubsamplingScaleImageView. If the user used pinch-to-zoom and panned around a previous page, the SubsamplingScaleImageView will retain those settings. So, we call resetScaleAndCenter() to switch back to the starting point, then call setImage() to hand the SubsamplingScaleImageView the page to render. setImage() takes an ImageSource, and in this case we need to use cachedBitmap(), to indicate both that the image is in the form of an existing Bitmap and that we are caching the Bitmap ourselves (so the SubsamplingScaleImageView should not attempt to recycle() the Bitmap). The result is a PDF viewer, where we can pick a PDF from the “Open” action bar item, then swipe through the pages: Figure 731: PdfRenderer Sample App 2389 VIEWING PDFS The Thunder Lizard Choice: PDF.js PdfRenderer has many limitations, none bigger than the fact that it fails to render complex PDFs. If you have used the Firefox Web browser on your desktop or notebook in the past few years, you may have noticed that its built-in PDF viewer is actually written in JavaScript, in the form of PDF.js. This is designed to handle more complex PDF files, and so it is a more complete solution than is PdfRenderer. However, PDF.js requires a fairly robust Web rendering engine to work. On Android, that means we are limited to Android 4.4+, when the original WebView was replaced by the “Android System WebView” app’s implementation, which shares more of its guts with Chromium. The PDF/PdfJS sample project demonstrates the use of PDF.js. PDF.js needs a WebView, so we put one in our layout file: (from PDF/PdfJS/app/src/main/res/layout/activity_main.xml) Not surprisingly, it needs JavaScript to be enabled for that WebView. However, we also need to give JavaScript the ability to read from arbitrary URLs when we load the JavaScript itself from a file URL, as our PDF might come from somewhere else (e.g., content scheme for a document opened via ACTION_OPEN_DOCUMENT): wv=(WebView)findViewById(R.id.webview); wv.getSettings().setJavaScriptEnabled(true true); wv.getSettings().setAllowUniversalAccessFromFileURLs(true true); (from PDF/PdfJS/app/src/main/java/com/commonsware/android/pdfjs/MainActivity.java) PDF.js itself is stored in assets/pdfjs/ in our main source set. This consists of the JavaScript library (build/ directory) and the stock Web-based viewer wrapped around that library (web/ directory). Combined, these two directories represent 4.6MB of material. While some of that could be stripped out or tweaked for mobile 2390 VIEWING PDFS use, this highlights one of the problems with the PDF.js solution: it is large. Those assets will compress somewhat — expect about 2MB added to your APK file. This sample app now gives the “Open” action bar item a submenu, where the user can choose from two pre-packaged PDFs as assets (a set of presentation slides and the infamous 1040(A) tax form from the United States Internal Revenue Service) or to pick one from the filesystem: > > /> (from PDF/PdfJS/app/src/main/res/menu/pdf.xml) In onOptionsItemSelected() of MainActivity, we route to loadPdf() methods for the two assets and the open() method for the “Pick” option: @Override public boolean onOptionsItemSelected(MenuItem item) { if (item.getItemId()==R.id.preso) { loadPdf("MultiWindowAndYourApp.pdf"); return return(true true); } else if (item.getItemId()==R.id.taxes) { loadPdf("f1040a.pdf"); return return(true true); } else if (item.getItemId()==R.id.open) { open(); } return return(super super.onOptionsItemSelected(item)); } (from PDF/PdfJS/app/src/main/java/com/commonsware/android/pdfjs/MainActivity.java) 2391 VIEWING PDFS open() still uses ACTION_OPEN_DOCUMENT to allow the user to pick a PDF file. onActivityResult() still saves the Uri in the pickedDocument field but then loadPdfUri() method with the string representation of that Uri: calls a @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (resultCode==Activity.RESULT_OK) { pickedDocument=data.getData(); loadPdfUri(pickedDocument.toString()); } } (from PDF/PdfJS/app/src/main/java/com/commonsware/android/pdfjs/MainActivity.java) Similarly, the loadPdf() method used by onOptionsItemSelected() for the assets stores the chosen asset name in a chosenAsset field, then calls loadPdfUri() with the proper file:///android_asset/ URL: private void loadPdf(String name) { chosenAsset=name; loadPdfUri("file:///android_asset/"+name); } (from PDF/PdfJS/app/src/main/java/com/commonsware/android/pdfjs/MainActivity.java) loadPdfUri() then uses loadUrl() to load up the Web-based PDF viewer in assets, supplying the URL to the PDF in the file query parameter: private void loadPdfUri(String uri) { try { wv.loadUrl("file:///android_asset/pdfjs/web/viewer.html?file="+ URLEncoder.encode(uri, "UTF-8")); } catch (UnsupportedEncodingException e) { e.printStackTrace(); } } (from PDF/PdfJS/app/src/main/java/com/commonsware/android/pdfjs/MainActivity.java) This works “out of the box” for the assets, as both the Web viewer and the PDFs come from file URLs. To get the content scheme to work, you have to add file:// to HOSTED_VIEWER_ORIGINS in web/viewer.js, to tell the Web viewer that file:// is a valid origin for the viewer and that any reachable URL should be tried: 2392 VIEWING PDFS var HOSTED_VIEWER_ORIGINS = [ 'null', 'http://mozilla.github.io', 'https://mozilla.github.io', 'file://' ]; (from PDF/PdfJS/app/src/main/assets/pdfjs/web/viewer.js) We also need to hold onto chosenAsset in our saved instance state: @Override protected void onSaveInstanceState(Bundle outState) { super super.onSaveInstanceState(outState); outState.putString(STATE_ASSET, chosenAsset); outState.putParcelable(STATE_PICKED, pickedDocument); } (from PDF/PdfJS/app/src/main/java/com/commonsware/android/pdfjs/MainActivity.java) And we restore the PDF in onCreate(): @SuppressLint("SetJavaScriptEnabled") @Override protected void onCreate(Bundle savedInstanceState) { super super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); wv=(WebView)findViewById(R.id.webview); wv.getSettings().setJavaScriptEnabled(true true); wv.getSettings().setAllowUniversalAccessFromFileURLs(true true); if (savedInstanceState!=null null) { chosenAsset=savedInstanceState.getString(STATE_ASSET); if (chosenAsset==null null) { pickedDocument=savedInstanceState.getParcelable(STATE_PICKED); if (pickedDocument!=null null) { loadPdfUri(pickedDocument.toString()); } } else { loadPdf(chosenAsset); } } } 2393 VIEWING PDFS (from PDF/PdfJS/app/src/main/java/com/commonsware/android/pdfjs/MainActivity.java) The result is PDF.js’s stock PDF viewer, in our WebView, where the user can scroll vertically to browse all the pages in the PDF: Figure 732: PDF.js Rendering IRS 1040 Form The Native Approach: Pdfium The major downside to both PdfRenderer and PDF.js as in-process PDF viewing solutions is the required API level. Both work with Android 5.0+, and PDF.js works with Android 4.4. However, you may have a minSdkVersion below 19. One approach would be to use an external PDF viewer for those older devices, but if that were an option, you may be better off using that for all Android versions, not just older ones. Your remaining options involve using some C/C++ code for rendering PDFs. One popular native code base for PDF rendering is Pdfium, from Google, used in Chromium and Chrome. Roughly speaking, it fills the same role there as PDF.js does with Firefox. 2394 VIEWING PDFS Bartosz Schiller’s AndroidPdfViewer library wraps Pdfium in a View that handles rendering and standard gestures (e.g., horizontal swipes to move between pages). On the plus side, Pdfium works well on older Android versions. The author of this book tested it back to Android 4.1 (API Level 16) and had no problems, and the library itself claims to support back to API Level 11. However, there is a cost: APK size. By default, AndroidPdfViewer gives you NDK binaries that support the major CPU architectures: 32- and 64-bit ARM and x86, plus MIPS. As a result, the native binaries take up 30MB of space in your APK. Dropping support for CPU architectures that are less important to you (e.g., ARM) can help, and you can drop the per-APK cost to ~5MB if you use ABI splits and ship separate APKs per supported CPU architecture (on distribution channels where that is an option). The PDF/Pdfium sample project demonstrates the use of AndroidPdfViewer and Pdfium. It is very similar to the PDF.js sample. However, we need to pull in the AndroidPdfViewer library: apply plugin: 'com.android.application' android { compileSdkVersion 25 buildToolsVersion '26.0.2' defaultConfig { applicationId "com.commonsware.android.pdfium" minSdkVersion 16 targetSdkVersion 25 versionCode 1 versionName "1.0" } } dependencies { implementation 'com.github.barteksc:android-pdf-viewer:2.3.0' } (from PDF/Pdfium/app/build.gradle) Our layout now uses a PDFView widget, instead of a RecyclerView or WebView: (from PDF/Pdfium/app/src/main/res/layout/activity_main.xml) We also need open() to support ACTION_GET_CONTENT, since ACTION_OPEN_DOCUMENT is not supported prior to API Level 19: private void open() { if (Build.VERSION.SDK_INT > /> /> /> > > /> /> > /> /> (from AppWidget/PairOfDice/app/src/main/AndroidManifest.xml) Here, along with a do-nothing activity, we have a . Of note: 1. Our has android:label and android:icon attributes, which are not normally needed on BroadcastReceiver declarations. However, in this case, those are used for the entry that goes in the roster of available widgets to add to the home screen. Hence, you will probably want to supply values for both of those, and use appropriate resources in case you want translations for other languages. 2. Our has an for the android.appwidget.action.APPWIDGET_UPDATE action. This means we will get control whenever Android wants us to update the content of our app 2404 HOME SCREEN APP WIDGETS widget. There may be other actions we want to monitor — more on this in a later section. 3. Our also has a element, indicating that its android.appwidget.provider details can be found in the res/xml/ widget_provider.xml file. This metadata is described in greater detail shortly. The uses-feature Element If the central point of your application is to provide an app widget, you should strongly consider adding a element to advertise this fact to markets like the Play Store: In principle, having this element means that markets should block the installation of your app on devices where there is no app-widget-capable home screen or other known places for supporting app widgets. If, however, your app has an app widget, but it is an adjunct to other forms of UI (typically a launcher activity), then you may wish to leave off this element, or set it to android:required="false". The Metadata Next, we need to define the app widget provider metadata. This has to reside at the location indicated in the manifest — in this case, in res/xml/widget_provider.xml: (from AppWidget/PairOfDice/app/src/main/res/xml/widget_provider.xml) Here, we provide a few pieces of information: 1. The minimum width and height of the app widget (android:minWidth and android:minHeight). These are approximate — the app widget host (e.g., home screen) will tend to convert these values into “cells” based upon the 2405 HOME SCREEN APP WIDGETS overall layout of the UI where the app widgets will reside. However, they should be no smaller than the minimums cited here. Also, ideally, you use dip instead of px for the dimensions, so the number of cells will remain constant regardless of screen density. 2. The frequency in which Android should request an update of the widget’s contents (android:updatePeriodMillis). This is expressed in terms of milliseconds, so a value of 3600000 is a 60-minute update cycle. Note that the minimum value for this attribute is 30 minutes — values less than that will be “rounded up” to 30 minutes. Hence our 15-minute (900000 millisecond) request will actually result in an update every 30 minutes. 3. The initial layout to use for the app widget, for the time between when the user requests the app widget and when onUpdate() of our AppWidgetProvider gets control. Note that the calculations for determining the number of cells for an app widget varies. The dip dimension value for an N-cell dimension was (74 * N) - 2 (e.g., a 2x3 cell app widget would request a width of 146dip and a height of 220dip). The value as of API Level 14 (a.k.a., Ice Cream Sandwich) is now (70 * N) - 30 (e.g., a 2x3 cell app widget would request a width of 110dip and a height of 180dip). To have your app widgets maintain a consistent number of cells, you will need two versions of your app widget metadata XML, one in res/xml-v14/ (with the API Level 14 calculation) and one in res/xml/ (for prior versions of Android). The Layout Eventually, you are going to need a layout that describes what the app widget looks like. You need to stick to the widget and container classes noted above; otherwise, this layout works like any other layout in your project. For example, here is the layout for the PairOfDice app widget: (from AppWidget/PairOfDice/app/src/main/res/layout/widget.xml) All we have is a pair of ImageView widgets (one for each die), inside of a RelativeLayout. The RelativeLayout has a background, specified as a nine-patch PNG file. This allows the RelativeLayout to have guaranteed contrast with whatever wallpaper is behind it, so the user can tell the actual app widget bounds. The BroadcastReceiver Next, we need a BroadcastReceiver that can get control when Android wants us to update our RemoteViews for our app widget. To simplify this, Android supplies an AppWidgetProvider class we can extend, instead of the normal BroadcastReceiver. This simply looks at the received Intent and calls out to an appropriate lifecycle method based on the requested action. The one method that frequently needs to be implemented on the provider is onUpdate(). Other lifecycle methods may be of interest and are discussed later in this chapter. For example, here is the implementation of the AppWidgetProvider for PairOfDice: package com.commonsware.android.appwidget.dice; import import import import import import import android.app.PendingIntent android.app.PendingIntent; android.appwidget.AppWidgetManager android.appwidget.AppWidgetManager; android.appwidget.AppWidgetProvider android.appwidget.AppWidgetProvider; android.content.ComponentName android.content.ComponentName; android.content.Context android.content.Context; android.content.Intent android.content.Intent; android.widget.RemoteViews android.widget.RemoteViews; public class AppWidget extends AppWidgetProvider { 2407 HOME SCREEN APP WIDGETS private static final int[] IMAGES={R.drawable.die_1,R.drawable.die_2, R.drawable.die_3,R.drawable.die_4, R.drawable.die_5,R.drawable.die_6}; @Override public void onUpdate(Context ctxt, AppWidgetManager mgr, int[] appWidgetIds) { ComponentName me=new new ComponentName(ctxt, AppWidget.class); mgr.updateAppWidget(me, buildUpdate(ctxt, appWidgetIds)); } private RemoteViews buildUpdate(Context ctxt, int[] appWidgetIds) { RemoteViews updateViews=new new RemoteViews(ctxt.getPackageName(), R.layout.widget); Intent i=new new Intent(ctxt, AppWidget.class); i.setAction(AppWidgetManager.ACTION_APPWIDGET_UPDATE); i.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS, appWidgetIds); PendingIntent pi=PendingIntent.getBroadcast(ctxt, 0 , i, PendingIntent.FLAG_UPDATE_CURRENT); updateViews.setImageViewResource(R.id.left_die, IMAGES[(int)(Math.random()*6)]); updateViews.setOnClickPendingIntent(R.id.left_die, pi); updateViews.setImageViewResource(R.id.right_die, IMAGES[(int)(Math.random()*6)]); updateViews.setOnClickPendingIntent(R.id.right_die, pi); updateViews.setOnClickPendingIntent(R.id.background, pi); return return(updateViews); } } (from AppWidget/PairOfDice/app/src/main/java/com/commonsware/android/appwidget/dice/AppWidget.java) To update the RemoteViews for our app widget, we need to build those RemoteViews (delegated to a buildUpdate() helper method) and tell an AppWidgetManager to update the widget via updateAppWidget(). In this case, we use a version of updateAppWidget() that takes a ComponentName as the identifier of the widget to be updated. Note that this means that we will update all instances of this app widget presently in use — the concept of multiple app widget instances is covered in greater detail later in this chapter. Working with RemoteViews is a bit like trying to tie your shoes while wearing mittens — it may be possible, but it is a bit clumsy. In this case, rather than using methods like findViewById() and then calling methods on individual widgets, we need to call methods on RemoteViews itself, providing the identifier of the widget we wish to modify. This is so our requests for changes can be serialized for transport to the home screen process. It does, however, mean that our view-updating code looks 2408 HOME SCREEN APP WIDGETS a fair bit different than it would if this were the main View of an activity or row of a ListView. To create the RemoteViews, we use a constructor that takes our package name and the identifier of our layout. This gives us a RemoteViews that contains all of the widgets we declared in that layout, just as if we inflated the layout using a LayoutInflater. The difference, of course, is that we have a RemoteViews object, not a View, as the result. We then use methods like: 1. setImageViewResource() to set the image for each of our ImageView widgets, in this case a randomly chosen die face (using graphics created from a set of SVG files from the OpenClipArt site) 2. setOnClickPendingIntent() to provide a PendingIntent that should get fired off when a die, or the overall app widget background, is clicked We then supply that RemoteViews to the AppWidgetManager, which pushes the RemoteViews structure to the home screen, which renders our new app widget UI. The Result If you compile and install all of this, you will have a new app widget entry available. How you add app widgets to the home screen varies based upon Android version and the home screen implementation, and there are too many possibilities to try to list here. No matter how you add the Pair of Dice, the app widget will appear on the home screen: 2409 HOME SCREEN APP WIDGETS Figure 734: Pair of Dice, In Action Another and Another As indicated above, you can have multiple instances of the same app widget outstanding at any one time. For example, one might have multiple picture frames, or multiple “show-me-the-latest-RSS-entry” app widgets, one per feed. You will distinguish between these in your code via the identifier supplied in the relevant AppWidgetProvider callbacks (e.g., onUpdate()). If you want to support separate app widget instances, you will need to store your state on a per-app-widget-identifier basis. You will also need to use an appropriate version of updateAppWidget() on AppWidgetManager when you update the app widgets, one that takes app widget identifiers as the first parameter, so you update the proper app widget instances. Conversely, there is nothing requiring you to support multiple instances as independent entities. For example, if you add more than one PairOfDice app widget to your home screen, nothing blows up – they just show the same roll. That is because PairOfDice uses a version of updateAppWidget() that does not take any app widget IDs, and therefore updates all app widgets simultaneously. 2410 HOME SCREEN APP WIDGETS App Widgets: Their Life and Times There are three other lifecycle methods that AppWidgetProvider offers that you may be interested in: 1. onEnabled() will be called when the first widget instance is created for this particular widget provider, so if there is anything you need to do once for all supported widgets, you can implement that logic here 2. onDeleted() will be called when a widget instance is removed from the home screen, in case there is any data you need to clean up specific to that instance 3. onDisabled() will be called when the last widget instance for this provider is removed from the home screen, so you can clean up anything related to all such widgets You will need to add appropriate action strings to your for each of these events, such as ACTION_APPWIDGET_ENABLED to be notified about enabled events via onEnabled(). Controlling Your (App Widget’s) Destiny As PairOfDice illustrates, you are not limited to updating your app widget only based on the timetable specified in your metadata. That timetable is useful if you can get by with a fixed schedule. However, there are cases in which that will not work very well: 1. If you want the user to be able to configure the polling period (the metadata is baked into your APK and therefore cannot be modified at runtime) 2. If you want the app widget to be updated based on external factors, such as a change in location The recipe shown in PairOfDice will let you use AlarmManager (described in another chapter) or proximity alerts or whatever to trigger updates. All you need to do is: 1. Arrange for something to broadcast an Intent that will be picked up by the BroadcastReceiver you are using for your app widget provider 2. Have the provider process that Intent directly or pass it along to a Service (such as an IntentService) 2411 HOME SCREEN APP WIDGETS Also, note that the updatePeriodMillis setting not only tells the app widget to update every so often, it will even wake up the phone if it is asleep so the widget can perform its update. On the plus side, this means you can easily keep your widgets up to date regardless of the state of the device. On the minus side, this will tend to drain the battery, particularly if the period is too fast. If you want to avoid this wakeup behavior, set updatePeriodMillis to 0 and use AlarmManager to control the timing and behavior of your widget updates. Note that if there are multiple instances of your app widget on the user’s home screen, they will all update approximately simultaneously if you are using updatePeriodMillis. If you elect to set up your own update schedule, you can control which app widgets get updated when, if you choose. One Size May Not Fit All It may be that you want to offer multiple app widget sizes to your users. Some might only want a small app widget. Some might really like what you have to offer and want to give you more home screen space to work in. Android 1.x/2.x The good news: this is easy to do. The bad news: it requires you, in effect, to have one app widget per size. The size of an app widget is determined by the app widget metadata XML file. That XML file is tied to a element in the manifest representing one app widget. Hence, to have multiple sizes, you need multiple metadata files and multiple elements. This also means your app widgets will show up multiple times in the app widget selection list, when the user goes to add an app widget to their home screen. Hence, supporting many sizes will become annoying to the user, if they perceive you are “spamming” the app widget list. Try to keep the number of app widget sizes to a reasonable number (say, one or two sizes). Android 3.0+ As of API Level 11, it is possible to have a resizeable app widget. To do this, you can have an android:resizeMode attribute in your widget metadata, with a value of 2412 HOME SCREEN APP WIDGETS horizontal, vertical, or both (e.g., horizontal|vertical). When the user longtaps on an existing widget, they should see handles to allow the widget to be resized: Figure 735: API Demos App Widget, Resizing You can also have android:minResizeWidth and android:minResizeHeight attributes, measured in dp, that indicate the approximate smallest size that your app widget can support. These values will be interpreted in terms of “cells”, as with the android:minWidth and android:minHeight attributes, and so the dp values you supply will not be used precisely. However, for Android 3.x and 4.0 (API Level 11-15), your code would not be informed about being resized. You had to simply ensure that your layout would intelligently use any extra space automatically. Hence, resizing tended to be used primarily with adapter-driven app widgets, as will be discussed in the next chapter. Starting with API Level 16, though, you can find out when the user resizes your app widget, so you can perhaps use a different layout for a different size, or otherwise adapt to the available space. Finding out about resize events takes a bit more work, as is illustrated in the AppWidget/Resize sample project. 2413 HOME SCREEN APP WIDGETS This app widget project is similar to PairOfDice, described earlier in this chapter. However, our layout skips the dice, replacing them with a TextView widget in the RelativeLayout: > > (from AppWidget/Resize/app/src/main/res/layout/widget.xml) Our widget_provider.xml resource stipulates our desired android:resizeMode and minimum resize dimensions: (from AppWidget/Resize/app/src/main/res/xml/widget_provider.xml) Finding out about app widget resizing is a different event than finding out about app widget updates. Hence, we need to add a new element to the of our in the manifest, indicating that we want APPWIDGET_OPTIONS_CHANGED as well as ACTION_UPDATE: > > /> /> (from AppWidget/Resize/app/src/main/AndroidManifest.xml) Then, our app widget implementation can override an onAppWidgetOptionsChanged() method: @Override public void onAppWidgetOptionsChanged(Context ctxt, AppWidgetManager mgr, int appWidgetId, Bundle newOptions) { RemoteViews updateViews= new RemoteViews(ctxt.getPackageName(), R.layout.widget); String msg= String.format(Locale.getDefault(), "[%d-%d] x [%d-%d]", newOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_MIN_WIDTH), newOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_MAX_WIDTH), newOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_MIN_HEIGHT), newOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_MAX_HEIGHT)); updateViews.setTextViewText(R.id.size, msg); mgr.updateAppWidget(appWidgetId, updateViews); } (from AppWidget/Resize/app/src/main/java/com/commonsware/android/appwidget/resize/AppWidget.java) You will notice that we skip onUpdate(). We will be called with onAppWidgetOptionsChanged() when the app widget is added and resized. Hence, in the case of this app widget, we can define what the app widget looks like from onAppWidgetOptionsChanged(), avoiding onUpdate(). That being said, more typical app widgets will wind up implementing both methods, especially if they are supporting lower API levels than 16, where onAppWidgetOptionsChanged() will not be called. Also remember that your process may well be terminated in between calls to app widget lifecycle methods like onUpdate() and onAppWidgetOptionsChanged(). 2415 HOME SCREEN APP WIDGETS Hence, if there is data from one method that you want in the other, be sure to persist that data somewhere. In the AppWidget implementation of onAppWidgetOptionsChanged(), we can find out about our new app widget size by means of the Bundle supplied to our method. What we cannot find out is our exact size. Rather, we are provided minimum and maximum dimensions of our app widget via four values in the Bundle: • • • • AppWidgetManager.OPTION_APPWIDGET_MIN_WIDTH AppWidgetManager.OPTION_APPWIDGET_MAX_WIDTH AppWidgetManager.OPTION_APPWIDGET_MIN_HEIGHT AppWidgetManager.OPTION_APPWIDGET_MAX_HEIGHT In our case, we grab these int values and pour them into a String template, using that to fill in the TextView of the app widget’s contents. When our app widget is initially launched, we show our initial size ranges: Figure 736: Resize Widget, As Initially Added When the user resizes our app widget, we show the new size ranges: 2416 HOME SCREEN APP WIDGETS Figure 737: Resize Widget, During Resize Operation However, not all home screen implementations will necessarily send the APPWIDGET_OPTIONS_CHANGED when an app widget is added to the home screen, only when the user resizes it later. For example, while the emulator’s home screen for Android 4.1 broadcasts APPWIDGET_OPTIONS_CHANGED, it does not for 4.2 or 4.3. Hence, you may want to also examine the size information in onUpdate() as well, so that you react to the initial size as well as any future sizes. One way to do this is to simply iterate over the supplied app widget IDs and invoke your own onAppWidgetOptionsChanged() method: // based on http://stackoverflow.com/a/18552461/115145 @Override public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { super super.onUpdate(context, appWidgetManager, appWidgetIds); for (int appWidgetId : appWidgetIds) { Bundle options=appWidgetManager.getAppWidgetOptions(appWidgetId); onAppWidgetOptionsChanged(context, appWidgetManager, appWidgetId, options); 2417 HOME SCREEN APP WIDGETS } } (from AppWidget/Resize/app/src/main/java/com/commonsware/android/appwidget/resize/AppWidget.java) Lockscreen Widgets Android’s lockscreen (a.k.a., the keyguard) had long been unmodifiable by developers. This led to a number of developers creating so-called “replacement lockscreens”, which generally reduce device security, as they can be readily bypassed. However, on Android 4.2 through 4.4, developers can create app widgets that the user can deploy to the lockscreen, helping to eliminate the need for “replacement lockscreens”. However, note that this capability was dropped with Android 5.0. As a result, this particular app widget feature may not be something that you want to worry about. That being said, it is available for those versions, and you are welcome to support it for those versions. Declaring that an app widget supports being on the lockscreen instead of (or in addition to) the home screen is very easy. All you must do is add an android:widgetCategory attribute to your app widget metadata resource. That attribute should have a value of either keyguard (for the lockscreen), home_screen, or both (e.g., keyguard|home_screen), depending upon where you want the app widget to be eligible. By default, if this attribute is missing, Android assumes a default value of home_screen. Users cannot resize the lockscreen widgets at this time. However, you still will want to specify an android:resizeMode attribute in your app widget metadata, as whether or not you include vertical resizing will affect the height of your app widget. Lockscreen widgets without vertical will have a fixed small height on tablets, while lockscreen widgets with vertical will fill the available height. Lockscreen widgets on phones will always be small (to fit above the PIN/password entry area), and lockscreen widgets on all devices will stretch to fill available space horizontally. You can also specify a different starting layout to use when your app is added to the lockscreen, as opposed to being added to the home screen. To do this, just add an android:initialKeyguardLayout attribute to your app widget metadata, pointing to the lockscreen-specific layout to use. 2418 HOME SCREEN APP WIDGETS To see this in action, take a look at the AppWidget/TwoOrThreeDice sample project. This is a revised clone of the PairOfDice sample, allowing the dice to be added to the lockscreen, and showing three dice on the lockscreen instead of the two on the home screen. Our app widget metadata now contains the lockscreen-related attributes: android:widgetCategory and android:initialKeyguardLayout: (from AppWidget/TwoOrThreeDice/app/src/main/res/xml/widget_provider.xml) Our lockscreen layout simply adds a third die, middle_die: (from AppWidget/TwoOrThreeDice/app/src/main/res/layout/lockscreen.xml) However, by specifying a different layout for the lockscreen widget, we have a problem. We need to know, in our Java code, what layout to use for the RemoteViews and how many dice need to be updated. And, ideally, we would handle this in a backwards-compatible fashion, so our app widget will have its original functionality on older Android devices. Plus, supporting the lockscreen makes it that much more likely that the user will have more than one instance of our app widget (e.g., one on the lockscreen and one on the homescreen), so we should do a better job than PairOfDice did about handling multiple app widget instances. To deal with the latter point, our new onUpdate() method iterates over each of the app widget IDs supplied to it and calls a private updateWidget() method for each, so we can better support multiple instances: @Override public void onUpdate(Context ctxt, AppWidgetManager mgr, int[] appWidgetIds) { for (int appWidgetId : appWidgetIds) { updateWidget(ctxt, mgr, appWidgetId); } } (from AppWidget/TwoOrThreeDice/app/src/main/java/com/commonsware/android/appwidget/dice/AppWidget.java) The updateWidget() method is a bit more complicated than the PairOfDice equivalent code: @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR1) private void updateWidget(Context ctxt, AppWidgetManager mgr, int appWidgetId) { int layout=R.layout.widget; if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR1) { int category= mgr.getAppWidgetOptions(appWidgetId) .getInt(AppWidgetManager.OPTION_APPWIDGET_HOST_CATEGORY, 2420 HOME SCREEN APP WIDGETS -1); layout= (category == AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD) ? R.layout.lockscreen : R.layout.widget; } RemoteViews updateViews= new RemoteViews(ctxt.getPackageName(), layout); Intent i=new new Intent(ctxt, AppWidget.class); i.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); PendingIntent pi= PendingIntent.getBroadcast(ctxt, appWidgetId, i, PendingIntent.FLAG_UPDATE_CURRENT); updateViews.setImageViewResource(R.id.left_die, IMAGES[(int)(Math.random() * 6)]); updateViews.setOnClickPendingIntent(R.id.left_die, pi); updateViews.setImageViewResource(R.id.right_die, IMAGES[(int)(Math.random() * 6)]); updateViews.setOnClickPendingIntent(R.id.right_die, pi); updateViews.setOnClickPendingIntent(R.id.background, pi); if (layout == R.layout.lockscreen) { updateViews.setImageViewResource(R.id.middle_die, IMAGES[(int)(Math.random() * 6)]); updateViews.setOnClickPendingIntent(R.id.middle_die, pi); } mgr.updateAppWidget(appWidgetId, updateViews); } (from AppWidget/TwoOrThreeDice/app/src/main/java/com/commonsware/android/appwidget/dice/AppWidget.java) First, we need to choose which layout we are working with. We assume that we are to use the original R.layout.widget resource by default. But, if we are on API Level 17 or higher, we can call getAppWidgetOptions() on the AppWidgetManager, to get the Bundle of options — the same options that we could be delivered in onAppWidgetOptionsUpdate() as described in the previous section. One value that will be in this Bundle is AppWidgetManager.OPTION_APPWIDGET_HOST_CATEGORY, which will be an int with a value of AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD if our app widget is on the lockscreen. In that case, we switch to using R.layout.lockscreen. In addition, we know then we need to update the middle_die when we are updating the other dice. 2421 HOME SCREEN APP WIDGETS There is also a subtle change in our getBroadcast() call to PendingIntent: we pass in the app widget ID as the second parameter, whereas in PairOfDice we passed 0. PendingIntent objects are cached in our process, and by default we will get the same PendingIntent when we call getBroadcast() for the same Intent. However, in our case, we may want two or more different PendingIntent objects for the same Intent, with differing extras (EXTRA_APPWIDGET_ID). Since extras are not considered when evaluating equivalence of Intent objects, just having different extras is insufficient to get different PendingIntent objects for those Intent objects. The second parameter to getBroadcast() (and getActivity() and getService()) on PendingIntent is a unique identifier, to differentiate between two otherwise equivalent Intent objects, forcing PendingIntent to give us distinct PendingIntent objects. This way, we can support two or more app widget instances, each having their own PendingIntent objects for their click events. On an Android 4.2+ lockscreen, you should be able to swipe to one side (e.g., a bezel swipe from left to right), to expose an option to add an app widget: Figure 738: Lockscreen Add-A-Widget Panel, On a 4.2 Emulator Tapping the “+” indicator (and, if needed, entering your device PIN or password), brings up an app widget chooser: 2422 HOME SCREEN APP WIDGETS Figure 739: Lockscreen Widget Selection List, On a 4.2 Emulator Choosing TwoOrThreeDice will then add the app widget to the lockscreen, with three dice, not two: 2423 HOME SCREEN APP WIDGETS Figure 740: Lockscreen with TwoOrThreeDice, On a 4.2 Emulator Preview Images App widgets can have preview images attached. Preview images are drawable resources representing a preview of what the app widget might look like on the screen. On tablets, this will be used as part of an app widget gallery, replacing the simple context menu presentation you used to see on Android 1.x and 2.x phones: 2424 HOME SCREEN APP WIDGETS Figure 741: App Widget Gallery, on Android 5.0 To create the preview image itself, the Android 3.0+ emulator images contain a Widget Preview application that lets you run an app widget in its own container, outside of the home screen: 2425 HOME SCREEN APP WIDGETS Figure 742: The Widget Preview application, showing a preview of the Analog Clock app widget From here, you can take a snapshot and save it to external storage, copy it to your project’s res/drawable-nodpi/ directory (indicating that there is no intrinsic density assumed for this image), and reference it in your app widget metadata via an android:previewImage attribute. We will see an example of such an attribute in the chapter on advanced app widgets. Being a Good Host In addition to creating your own app widgets, it is possible to host app widgets. This is mostly aimed for those creating alternative home screen applications, so they can take advantage of the same app widget framework and all the app widgets being built for it. This is not very well documented, but it involves the AppWidgetHost and AppWidgetHostView classes. The latter is a View and so should be able to reside in an app widget host’s UI like any other ordinary widget. 2426 Adapter-Based App Widgets API Level 11 introduced a few new capabilities for app widgets, to make them more interactive and more powerful than before. The documentation lags a bit, though, so determining how to use these features takes a bit of exploring. Fortunately for you, the author did some of that exploring on your behalf, to save you some trouble. Prerequisites Understanding this chapter requires that you have read the preceding chapter and all of its prerequisites. AdapterViews for App Widgets In addition to the classic widgets available for use in app widgets and RemoteViews, five more were added for API Level 11: 1. 2. 3. 4. 5. GridView ListView StackView ViewFlipper AdapterViewFlipper Three of these (GridView, ListView, ViewFlipper) are widgets that existed in Android since the outset. StackView was added in API Level 11 to provide a “stack of cards” UI: 2427 ADAPTER-BASED APP WIDGETS Figure 743: The Google Books app widget, showing a StackView AdapterViewFlipper works like a ViewFlipper, allowing you to toggle between various children with only one visible at a time. However, whereas with ViewFlipper all children are fully-instantiated View objects held by the ViewFlipper parent, AdapterViewFlipper uses the Adapter model, so only a small number of actual View objects are held in memory, no matter how many potential children there are. With the exception of ViewFlipper, the other four all require the use of an Adapter. This might seem odd, as there is no way to provide an Adapter to a RemoteViews. That is true, but API Level 11 added new ways for Adapter-like communication between the app widget host (e.g., home screen) and your application. We will take an in-depth look at that in an upcoming section. Building Adapter-Based App Widgets In an activity, if you put a ListView or GridView into your layout, you will also need to hand it an Adapter, providing the actual row or cell View objects that make up the contents of those selection widgets. In an app widget, this becomes a bit more complicated. The host of the app widget does not have any Adapter class of yours. Hence, just as we have to send the contents of the app widget’s UI via a RemoteViews, we will need to provide the rows or cells via RemoteViews as well. Android, starting with API Level 11, has a RemoteViewsService and RemoteViewsFactory that you can use for this purpose. 2428 ADAPTER-BASED APP WIDGETS Let’s take a look, in the form of the AppWidget/LoremWidget sample project, which will put a ListView of 25 Latin words into an app widget. The AppWidgetProvider At its core, our AppWidgetProvider (named WidgetProvider, in a stunning display of creativity) still needs to create and configure a RemoteViews object with the app widget UI, then use updateAppWidget() to push that RemoteViews to the host via the AppWidgetManager. However, for an app widget that involves an AdapterView, like ListView, there are two more key steps: • You have to tell the RemoteViews the identity of a RemoteViewsService that will help fill the role that the Adapter would in an activity • You have to provide the RemoteViews with a “template” PendingIntent to be used when the user taps on a row or cell in the AdapterView, to replace the onListItemClick() or similar method you might have used in an activity For example, here is WidgetProvider for our Latin-word app widget: package com.commonsware.android.appwidget.lorem; import import import import import import import android.app.PendingIntent android.app.PendingIntent; android.appwidget.AppWidgetManager android.appwidget.AppWidgetManager; android.appwidget.AppWidgetProvider android.appwidget.AppWidgetProvider; android.content.Context android.content.Context; android.content.Intent android.content.Intent; android.net.Uri android.net.Uri; android.widget.RemoteViews android.widget.RemoteViews; public class WidgetProvider extends AppWidgetProvider { public static String EXTRA_WORD= "com.commonsware.android.appwidget.lorem.WORD"; @Override public void onUpdate(Context ctxt, AppWidgetManager appWidgetManager, int[] appWidgetIds) { for (int i=0; i to the RemoteViewsService and use an Intent based on that, but that would make your service more publicly visible than you might want. 2. Any extras that you package on the Intent — such as the app widget ID in this case — will be on the Intent that is delivered to the RemoteViewsService when it is invoked by the app widget host. Note that there are two flavors of setRemoteAdapter(). An older deprecated one takes the app widget ID as the first parameter. The current one does not. The current one, though, is only available on API Level 14 and higher. The call to setPendingIntentTemplate() is where we provide a PendingIntent that will be used as the template for all row or cell clicks. As we will see in a bit, the 2430 ADAPTER-BASED APP WIDGETS underlying Intent in the PendingIntent will have more data added to it by our RemoteViewsFactory. In all other respects, our WidgetProvider is unremarkable compared to other app widgets. It will need to be registered in the manifest as a , as with any other app widget. The RemoteViewsService Android supplies a RemoteViewsService class that you will need to extend, and this class is the one you must register with the RemoteViews for an AdapterView widget. For example, here is WidgetService (once again, a highly creative name) from the LoremWidget project: package com.commonsware.android.appwidget.lorem; import android.content.Intent android.content.Intent; import android.widget.RemoteViewsService android.widget.RemoteViewsService; public class WidgetService extends RemoteViewsService { @Override public RemoteViewsFactory onGetViewFactory(Intent intent) { return return(new new LoremViewsFactory(this this.getApplicationContext(), intent)); } } (from AppWidget/LoremWidget/app/src/main/java/com/commonsware/android/appwidget/lorem/WidgetService.java) As you can see, this service is practically trivial. You have to override one method, onGetViewFactory(), which will return the RemoteViewsFactory to use for supplying rows or cells for the AdapterView. You are passed in an Intent, the one used in the setRemoteAdapter() call. Hence, if you have more than one AdapterView widget in your app widget, you could elect to have two RemoteViewsService implementations, or one that discriminates between the two widgets via something in the Intent (e.g., custom action string). In our case, we only have one AdapterView, so we create an instance of a LoremViewFactory and return it. Google has suggested using getApplicationContext() here to supply the Context object to RemoteViewsFactory, instead of using the Service as a Context, though it is unclear why this is. Another thing different about the RemoteViewsService is how it is registered in the manifest: 2431 ADAPTER-BASED APP WIDGETS > /> /> > > /> /> > /> /> /> 2432 ADAPTER-BASED APP WIDGETS (from AppWidget/LoremWidget/app/src/main/AndroidManifest.xml) Note the use of android:permission, specifying that whoever sends an Intent to WidgetService must hold the BIND_REMOTEVIEWS permission. This can only be held by the operating system. This is a security measure, so arbitrary applications cannot find out about your service and attempt to spoof being the OS and cause you to supply them with RemoteViews for the rows, as this might leak private data. The RemoteViewsFactory A RemoteViewsFactory interface implementation looks and feels a lot like an Adapter. In fact, one could imagine that the Android developer community might create CursorRemoteViewsFactory and ArrayRemoteViewsFactory and such to further simplify writing these classes. For example, here is LoremViewsFactory, the one used by the LoremWidget project: package com.commonsware.android.appwidget.lorem; import import import import import import android.appwidget.AppWidgetManager android.appwidget.AppWidgetManager; android.content.Context android.content.Context; android.content.Intent android.content.Intent; android.os.Bundle android.os.Bundle; android.widget.RemoteViews android.widget.RemoteViews; android.widget.RemoteViewsService android.widget.RemoteViewsService; public class LoremViewsFactory implements RemoteViewsService.RemoteViewsFactory { private static final String[] items= { "lorem", "ipsum", "dolor", "sit", "amet", "consectetuer", "adipiscing", "elit", "morbi", "vel", "ligula", "vitae", "arcu", "aliquet", "mollis", "etiam", "vel", "erat", "placerat", "ante", "porttitor", "sodales", "pellentesque", "augue", "purus" }; private Context ctxt=null null; private int appWidgetId; public LoremViewsFactory(Context ctxt, Intent intent) { this this.ctxt=ctxt; appWidgetId= intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); } @Override public void onCreate() { 2433 ADAPTER-BASED APP WIDGETS // no-op } @Override public void onDestroy() { // no-op } @Override public int getCount() { return return(items.length); } @Override public RemoteViews getViewAt(int position) { RemoteViews row= new RemoteViews(ctxt.getPackageName(), R.layout.row); row.setTextViewText(android.R.id.text1, items[position]); Intent i=new new Intent(); Bundle extras=new new Bundle(); extras.putString(WidgetProvider.EXTRA_WORD, items[position]); extras.putInt(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); i.putExtras(extras); row.setOnClickFillInIntent(android.R.id.text1, i); return return(row); } @Override public RemoteViews getLoadingView() { return return(null null); } @Override public int getViewTypeCount() { return return(1); } @Override public long getItemId(int position) { return return(position); } @Override public boolean hasStableIds() { 2434 ADAPTER-BASED APP WIDGETS return return(true true); } @Override public void onDataSetChanged() { // no-op } } (from AppWidget/LoremWidget/app/src/main/java/com/commonsware/android/appwidget/lorem/LoremViewsFactory.java) You need to implement a handful of methods that have the same roles in a RemoteViewsFactory as they do in an Adapter, including: 1. 2. 3. 4. getCount() getViewTypeCount() getItemId() hasStableIds() In addition, you have onCreate() and onDestroy() methods that you must implement, even if they do nothing, to satisfy the interface. You will need to implement getLoadingView(), which will return a RemoteViews to use as a placeholder while the app widget host is getting the real contents for the app widget. If you return null, Android will use a default placeholder. The bulk of your work will go in getViewAt(). This serves the same role as getView() does for an Adapter, in that it returns the row or cell View for a given position in your data set. However: 1. You have to return a RemoteViews, instead of a View, just as you have to use RemoteViews for the main content of the app widget in your AppWidgetProvider 2. There is no recycling, so you do not get a View (or RemoteViews) back to somehow repopulate, meaning you will create a new RemoteViews every time The impact of the latter is that you do not want to put large data sets into an app widget, as scrolling may get sluggish, just as you do not want to implement an Adapter without recycling unused View objects. In LoremViewsFactory, the getViewAt() implementation creates a RemoteViews for a custom row layout, cribbed from one in the Android SDK: 2435 ADAPTER-BASED APP WIDGETS (from AppWidget/LoremWidget/app/src/main/res/layout/row.xml) Then, getViewAt() pours in a word from the static String array of Latin words into that RemoteViews for the TextView inside it. It also creates an Intent and puts the Latin word in as an EXTRA_WORD extra, then provides that Intent to setOnClickFillInIntent(). In addition, it adds the app widget instance ID as an extra, reusing the framework’s own AppWidgetManager.EXTRA_APPWIDGET_ID as the key. The contents of the “fill-in” Intent are merged into the “template” PendingIntent from setPendingIntentTemplate(), and the resulting PendingIntent is what is invoked when the user taps on an item in the AdapterView. The fully-configured RemoteViews is then returned. The Rest of the Story The app widget metadata needs no changes related to Adapter-based app widget contents. However, LoremWidget does add the android:previewImage attribute: (from AppWidget/LoremWidget/app/src/main/res/xml/widget_provider.xml) This points to the res/drawable-nodpi/preview.png file that represents a “widgetshot” of the app widget in isolation, obtained from the Widget Preview application: Figure 744: The preview of LoremWidget Also, the metadata specifies android:resizeMode="vertical". This attribute is new to Android 3.1, and allows the app widget to be resized by the user (in this case, only in the vertical direction, to show more rows). Older versions of Android will ignore this attribute, and the app widget will remain in your requested size. You can use vertical, horizontal, or both (via the pipe operator) as values for android:resizeMode. 2437 ADAPTER-BASED APP WIDGETS When the user taps on an item in the list, our PendingIntent is set to bring up LoremActivity. This activity has android:theme="@android:style/ Theme.Translucent.NoTitleBar" set in the manifest, meaning that it will not have its own user interface. Rather, it will extract our EXTRA_WORD — and the app widget ID — out of the Intent used to launch the activity and displays it in a Toast before finishing: package com.commonsware.android.appwidget.lorem; import import import import android.app.Activity android.app.Activity; android.appwidget.AppWidgetManager android.appwidget.AppWidgetManager; android.os.Bundle android.os.Bundle; android.widget.Toast android.widget.Toast; public class LoremActivity extends Activity { @Override public void onCreate(Bundle state) { super super.onCreate(state); String word=getIntent().getStringExtra(WidgetProvider.EXTRA_WORD); if (word == null null) { word="We did not get a word!"; } Toast.makeText(this this, String.format("#%d: %s", getIntent().getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID), word), Toast.LENGTH_LONG).show(); finish(); } } (from AppWidget/LoremWidget/app/src/main/java/com/commonsware/android/appwidget/lorem/LoremActivity.java) The Results When you compile and install the application, nothing new shows up in the home screen launcher, because we have no activity defined to respond to ACTION_MAIN and CATEGORY_HOME. This would be unusual for an application distributed through the Play Store, as users often get confused if they install something and then do not know how to start it. However, for the purposes of this example, we should be fine, as readers of programming books never get confused about such things. However, if you bring up the app widget gallery (e.g., long-tap on the home screen of an Android 6.0 device or emulator), you will see LoremWidget there, complete with preview image. You can drag it into one of the home screen panes and position it. When done, the app widget appears as expected: 2438 ADAPTER-BASED APP WIDGETS Figure 745: LoremWidget on Android Home Screen The ListView is live and can be scrolled. Tapping an entry brings up the corresponding Toast. If the user long-taps on the app widget, they will be able to reposition it. On Android 3.1 and beyond, when they lift their finger after the long-tap, the app widget will show resize handles on the sides designated by your android:resizeMode attribute: 2439 ADAPTER-BASED APP WIDGETS Figure 746: LoremWidget on Android Home Screen, with Resize Handles The user can then drag those handles to expand or shrink the app widget in the specified dimensions: 2440 ADAPTER-BASED APP WIDGETS Figure 747: Resized LoremWidget on Android Home Screen 2441 Trail: Data Storage and Retrieval Content Provider Theory Android publishes data to you via an abstraction known as a “content provider”. Access to contacts and the call log, for example, are given to you via a set of content providers. In a few places, Android expects you to supply a content provider, such as for integrating your own search suggestions with the Android Quick Search Box. And, content providers are one way for you to supply data to third party applications, or to consume information from third party applications. As such, content providers have the potential to be something you would encounter frequently, even if in practice they do not seem used much. Prerequisites Understanding this chapter requires that you have read the core chapters, particularly the one on working with local databases. Using a Content Provider Any Uri in Android that begins with the content:// scheme represents a resource served up by a content provider. Content providers offer data encapsulation using Uri instances as handles – you neither know nor care where the data represented by the Uri comes from, so long as it is available to you when needed. The data could be stored in a SQLite database, or in flat files, or retrieved off a device, or be stored on some far-off server accessed over the Internet. Given a Uri, you may be able to perform basic CRUD (create, read, update, delete) operations using a content provider. Uri instances can represent either collections or individual pieces of content. Given a collection Uri, you may be able to create new pieces of content via insert operations. Given an instance Uri, you may be able to 2445 CONTENT PROVIDER THEORY read data represented by the Uri, update that data, or delete the instance outright. Or, given a Uri, you may be able to open up a handle to what amounts to a file, that you can read and, possibly, write to. These are all phrased as “may” because the content provider system is a facade. The actual implementation of a content provider dictates what you can and cannot do, and not all content providers will support all capabilities. Pieces of a Uri A Uri for a ContentProvider is made up of two to four components. A provider Uri always has a content scheme. So, when represented as a string, you will see the Uri start with content://. After the scheme, where in an http:// URL you would find a domain name or IP address, a provider Uri always has the authority string. This is unique on the device — only one provider will be tied to a given authority string. What comes after the authority string is up to the provider. It is structured like the path segments of an http:// URL, but what those path segments mean is up to the provider implementation. The one approximate rule is that a Uri pointing to an individual piece of content — such as a row of a table or view in a database – frequently has the Uri end in a number, where the number indicates a unique identifier of that content. Most of the Android APIs expect these to be Uri objects, though in common discussion, it is simpler to think of them as strings. The Uri.parse() static method creates a Uri out of the string representation. Getting a Handle So, where do these Uri instances come from? Some Uri values are part of the framework. For example, ContactsContract.Contacts.CONTENT_URI is a Uri pointing at the collection of contacts. You might also get Uri instances handed to you from other sources, such as getting Uri handles for contacts via activities responding to ACTION_PICK or ACTION_GET_CONTENT Intent objects. 2446 CONTENT PROVIDER THEORY You can also hard-wire literal String objects (e.g., "content://contacts/people") and convert them into Uri instances via Uri.parse(). This is not an ideal solution, as the base Uri values could conceivably change over time. For example, while you used to access contacts via a Uri like content://contacts/people, that is no longer the case. ContactsContract.Contacts.CONTENT_URI is a different value and will give you better results. The Database-Style API Of the two flavors of API that a content provider may support, the database-style API is more prevalent. Using a ContentResolver, you can perform standard “CRUD” operations (create, read, update, delete) using what looks like a SQL interface. Makin’ Queries Given a base Uri, you can run a query to return data out of the content provider related to that Uri. This has much of the feel of SQL: you specify the “columns” to return, the constraints to determine which “rows” to return, a sort order, etc. The difference is that this request is being made of a content provider, not directly of some database (e.g., SQLite). You have two main options for running a query: 1. Use the query() method on ContentResolver from some sort of background thread 2. Use a CursorLoader, as is discussed in an upcoming chapter The standard query() method on ContentResolver takes five parameters: • The base Uri of the content provider to query, or the instance Uri of a specific object to query • An array of properties (think “columns”) from that content provider that you want returned by the query • A constraint statement, functioning like a SQL WHERE clause • An optional set of parameters to bind into the constraint clause, replacing any ? that appear there • An optional sort statement, functioning like a SQL ORDER BY clause This method returns a Cursor object, which you can use to retrieve the data returned by the query. 2447 CONTENT PROVIDER THEORY This will hopefully make more sense given an example. This chapter shows some sample bits of code from the ContentProvider/ConstantsPlus sample project. This is the same basic application as was first shown back in the chapter on database access, but rewritten to pull the database logic into a content provider, which is then used by a retained ListFragment. As before, in onViewCreated(), we kick off a LoadCursorTask if we do not already have our Cursor, such as via a configuration change: @Override public void onViewCreated(View view, Bundle savedInstanceState) { super super.onViewCreated(view, savedInstanceState); SimpleCursorAdapter adapter= new SimpleCursorAdapter(getActivity(), R.layout.row, current, new String[] { DatabaseHelper.TITLE, DatabaseHelper.VALUE }, new int[] { R.id.title, R.id.value }, 0); setListAdapter(adapter); if (current==null null) { task=new new LoadCursorTask(getActivity()).execute(); } } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/ConstantsFragment.java) LoadCursorTask inherits from a BaseTask. BaseTask and its subclasses need a ContentResolver to be able to work with our ContentProvider. So, BaseTask takes Context in its constructor and uses that to retrieve a ContentResolver: a abstract private class BaseTask BaseTask extends AsyncTask { final ContentResolver resolver; BaseTask(Context ctxt) { super super(); resolver=ctxt.getContentResolver(); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/ConstantsFragment.java) 2448 CONTENT PROVIDER THEORY In doInBackground(), LoadCursorTask calls a doQuery() method inherited from BaseTask, which in turn uses our ContentResolver to query our ContentProvider: protected Cursor doQuery() { Cursor result=resolver.query(Provider.Constants.CONTENT_URI, PROJECTION, null null, null null, null null); result.getCount(); return return(result); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/ConstantsFragment.java) In the call to query(), we provide: 1. The Uri for our provider (Provider.Constants.CONTENT_URI), in this case representing the collection of physical constants managed by the provider 2. A list of properties to retrieve 3. Three null values, indicating that we do not need a constraint clause (the Uri represents the instance we need), nor parameters for the constraint, nor a sort order (we should only get one entry back) The biggest “magic” here is the list of properties. The lineup of what properties are possible for a given provider should be provided by the documentation (or source code) for the content provider itself. In this case, we define logical values on the Provider provider implementation class that represent the various properties (namely, the unique identifier, the display name or title, and the value of the constant), and we refer to them with our PROJECTION: private static final String[] PROJECTION=new new String[] { Provider.Constants._ID, Provider.Constants.TITLE, Provider.Constants.VALUE }; (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/ConstantsFragment.java) Adapting to the Circumstances Now that we have a Cursor via query(), we have access to the query results and can do whatever we want with them. You might, for example, manually extract data from the Cursor to populate widgets or other objects. In our case, we are using the SimpleCursorAdapter, set up in onViewCreated(), to render our Cursor. This means that we need to take the Cursor that doQuery() 2449 CONTENT PROVIDER THEORY generates and arrange to hand that to the SimpleCursorAdapter. The onPostExecute() method on BaseTask handles this: @Override public void onPostExecute(Cursor result) { ((CursorAdapter)getListAdapter()).changeCursor(result); current=result; task=null null; } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/ConstantsFragment.java) Give and Take Of course, content providers would be astonishingly weak if you couldn’t add or remove data from them, and were instead limited to only update what is there. Fortunately, content providers offer these abilities as well. To insert data into a content provider, you have two options available on the ContentProvider interface (available through getContentResolver() to your activity): • Use insert() with a collection Uri and a ContentValues structure describing the initial set of data to put in the row • Use bulkInsert() with a collection Uri and an array of ContentValues structures to populate several rows at once The insert() method returns a Uri for you to use for future operations on that new object. The bulkInsert() method returns the number of created rows; you would need to do a query to get back at the data you just inserted. For example, if the user chooses our “Add” overflow item, we pop up a dialog to collect a new constant: private void add() { LayoutInflater inflater=getActivity().getLayoutInflater(); View addView=inflater.inflate(R.layout.add_edit, null null); AlertDialog.Builder builder=new new AlertDialog.Builder(getActivity()); builder.setTitle(R.string.add_title).setView(addView) .setPositiveButton(R.string.ok, this this) .setNegativeButton(R.string.cancel, null null).show(); } 2450 CONTENT PROVIDER THEORY (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/ConstantsFragment.java) Then, if the user taps the “OK” button in the dialog, our onClick() listener is called, where we collect the entered values from the user, pour them into a ContentValues structure, and pass that to an InsertTask: @Override public void onClick(DialogInterface dialog, int which) { ContentValues values=new new ContentValues(2); AlertDialog dlg=(AlertDialog)dialog; EditText title=(EditText)dlg.findViewById(R.id.title); EditText value=(EditText)dlg.findViewById(R.id.value); values.put(DatabaseHelper.TITLE, title.getText().toString()); values.put(DatabaseHelper.VALUE, value.getText().toString()); task=new new InsertTask(getActivity()).execute(values); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/ConstantsFragment.java) InsertTask, in its doInBackground() method, calls insert() on a ContentResolver to insert this row: @Override protected Cursor doInBackground(ContentValues... values) { resolver.insert(Provider.Constants.CONTENT_URI, values[0]); return return(doQuery()); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/ConstantsFragment.java) Notice that we also call doQuery() again. That is because our Cursor is now out of date, and we need to obtain a fresh Cursor with fresh results. And, as with LoadTask, InsertTask inherits from BaseTask, not only providing us with that doQuery() method but also the onPostExecute() method that puts the Cursor into the SimpleCursorAdapter. To delete one or more rows from the content provider, use the delete() method on ContentResolver. This works akin to a SQL DELETE statement and takes three parameters: • A Uri representing the collection (or instance) from which you wish to delete rows 2451 CONTENT PROVIDER THEORY • A constraint statement, functioning like a SQL WHERE clause, to determine which rows should be deleted • An optional set of parameters to bind into the constraint clause, replacing any ? that appear there The Streaming API Sometimes, what you are trying to retrieve does not look like a set of rows and columns, but rather looks like a stream. For example, the MediaStore provider manages the index of all music, video, and image files available on external storage, and you can use MediaStore to open up a stream to read in the contents of one of those files. Here, working with the Uri and the provider is much like working with a URL and a Web server. Some content providers, like MediaStore, support both the database-style and streaming APIs — you query to find media that matches your criteria, then can open some file that matches. Other content providers might only support the streaming API. Working with the Stream Given a Uri that represents some file managed by the content provider, you can use openInputStream() and openOutputStream() on a ContentResolver to access an InputStream or OutputStream, respectively. Note, though, that not all content providers may support both modes. For example, a content provider that serves files stored inside the application (e.g., assets in the APK file), you will not be able to get an OutputStream to modify the content. Also note that openInputStream() and openOutputStream() work with both file:// and content:// Uri values — you do not need to manually inspect the Uri and handle files separately if you do not want to. Retrieving Metadata You can call getType() on a ContentResolver, supplying a Uri as a parameter. This will return the MIME type reported by the ContentProvider for the data at that Uri. For the streaming API, this will give you results reminiscent of a Web server — some specific MIME type if the provider knows it, otherwise probably some generic MIME type (e.g., application/octet-stream). 2452 CONTENT PROVIDER THEORY You can also call query() on the ContentResolver. Your projection (the list of columns to return) can include: • OpenableColumns.SIZE, which will return the length of the file being streamed to you for that Uri, and • OpenableColumns.DISPLAY_NAME, which should be some name for the file that the user might recognize The DATA Anti-Pattern However, the authors of MediaStore screwed up developer expectations, due to a legacy convention. The legacy convention was that a content:// Uri might not be openable directly using something like openInputStream(). Instead, it pointed to a database row, retrievable via query(), and you would look in the DATA column for how to access the actual data. Some providers no doubt continue to use this pattern, as does MediaStore. The rules for what the DATA column would be were not well documented, but by convention they tended to be a path to a file. The problem is that this runs afoul of Google’s current guidance, as there is no guarantee that other apps can access such a file. Do not blindly assume that if you get a content:// Uri that it is for the DATA pattern. Try to open a stream on the Uri, and if that fails, then see if the DATA pattern is in play. Or, if you query() to get the size and/or display name first, also request the DATA column, and if it exists and is not null, try that if opening the stream directly does not work. Building Content Providers Building a content provider is a very tedious task. There are many requirements of a content provider, in terms of methods to implement and public data members to supply. And, until you try using it, you have no great way of telling if you did any of it correctly (versus, say, building an activity and getting validation errors from the resource compiler). That being said, building a content provider is of huge importance if your application wishes to make data available to other applications. If your application is keeping its data solely to itself, you may be able to avoid creating a content provider, just accessing the data directly from your activities. But, if you want your data to 2453 CONTENT PROVIDER THEORY possibly be used by others — for example, you are building a feed reader and you want other programs to be able to access the feeds you are downloading and caching — then a content provider is right for you. First, Some Dissection The content Uri is the linchpin behind accessing data inside a content provider. When using a content provider, all you really need to know is the provider’s base Uri; from there you can run queries as needed, or construct a Uri to a specific instance if you know the instance identifier. When building a content provider, though, you need to know a bit more about the innards of the content Uri. A content Uri has two to four pieces, depending on situation: 1. It always has a scheme (content://), indicating it is a content Uri instead of a Uri to a Web resource (http://). 2. It always has an authority, which is the first path segment after the scheme. The authority is a unique string identifying the content provider that handles the content associated with this Uri. 3. It may have a data type path, which is the list of path segments after the authority and before the instance identifier (if any). The data type path can be empty, if the content provider only handles one type of content. It can be a single path segment (foo) or a chain of path segments (foo/bar/goo) as needed to handle whatever data access scenarios the content provider requires. 4. It may have an instance identifier, which is an integer identifying a specific piece of content. A content Uri without an instance identifier refers to the collection of content represented by the authority (and, where provided, the data path). For example, a content Uri could be as simple as content://sekrits, which would refer to the collection of content held by whatever content provider was tied to the sekrits authority (e.g., SecretsProvider). Or, it could be as complex as content://sekrits/card/pin/17, which would refer to a piece of content (identified as 17) managed by the sekrits content provider that is of the data type card/pin. 2454 CONTENT PROVIDER THEORY Next, Some Typing Next, you need to come up with some MIME types corresponding with the content your content provider will provide. There are three basic patterns. For the streaming API, the MIME type that you will use should be the actual MIME type of the stream itself. Perhaps you already know the MIME type (e.g., you got it in an HTTP header when you downloaded the content from a Web server). Perhaps you will use MimeTypeMap to try to infer a MIME type based on a file extension. That is up to you, just as it is up to you to ensure that your Web server returns proper MIME types for streams that it serves up. For the database-style API, even though the MIME type system is not really designed for this sort of thing, we still use MIME types. Each Uri will have an associated MIME type, indicating what is represented by that Uri. A Uri that points to a collection of content (e.g., a database table or view) will use one MIME type structure, while a Uri that points to an individual piece of content (e.g., a row in that database table or view) will use a different MIME type structure. The collection MIME type should be of the form vnd.X.cursor.dir/Y, where X is the name of your firm, organization, or project, and Y is a dot-delimited type name. So, for example, you might use vnd.tlagency.cursor.dir/sekrits.card.pin as the MIME type for your collection of secrets. The instance MIME type, for an individual piece of content, should be of the form vnd.X.cursor.item/Y, usually for the same values of X and Y as you used for the collection MIME type (though that is not strictly required). Implementing the Database-Style API Just as an activity and a receiver are both Java classes, so is a content provider. So, the big step in creating a content provider is crafting its Java class, with a base class of ContentProvider. In your subclass of ContentProvider, you are responsible for implementing six methods that, when combined, perform the services that a content provider is supposed to offer to activities wishing to create, read, update, or delete content via the database-style API. 2455 CONTENT PROVIDER THEORY Implement onCreate() As with an activity, the main entry point to a content provider is onCreate(). Here, you can do whatever initialization you want. In particular, here is where you should lazy-initialize your data store. For example, if you plan on storing your data in suchand-so directory on external storage, with an XML file serving as a “table of contents”, you should check and see if that directory and XML file are there and, if not, create them so the rest of your content provider knows they are out there and available for use. Similarly, if you have rewritten your content provider sufficiently to cause the data store to shift structure, you should check to see what structure you have now and adjust it if what you have is out of date. Implement query() As one might expect, the query() method is where your content provider gets details on a query some activity wants to perform. It is up to you to actually process said query. The query method gets, as parameters: 1. A Uri representing the collection or instance being queried 2. A String array representing the list of properties that should be returned 3. A String representing what amounts to a SQL WHERE clause, constraining which instances should be considered for the query results 4. A String array representing values to “pour into” the WHERE clause, replacing any ? found there 5. A String representing what amounts to a SQL ORDER BY clause You are responsible for interpreting these parameters however they make sense and returning a Cursor that can be used to iterate over and access the data. As you can imagine, these parameters are aimed towards people using a SQLite database for storage. You are welcome to ignore some of these parameters (e.g., you elect not to try to roll your own SQL WHERE clause parser), but you need to document that fact so activities only attempt to query you by instance Uri and not by using parameters that you elect to ignore. 2456 CONTENT PROVIDER THEORY Implement insert() Your insert() method will receive a Uri representing the collection and a ContentValues structure with the initial data for the new instance. You are responsible for creating the new instance, filling in the supplied data, and returning a Uri to the new instance. Implement update() Your update() method gets the Uri of the instance or collection to change, a ContentValues structure with the new values to apply, a String for a SQL WHERE clause, and a String array with parameters to use to replace ? found in the WHERE clause. Your responsibility is to identify the instance(s) to be modified (based on the Uri and WHERE clause), then replace those instances’ current property values with the ones supplied. This will be annoying, unless you are using SQLite for storage. Then, you can pretty much pass all the parameters you received to the update() call to the database, though the update() call will vary slightly depending on whether you are updating one instance or several. Implement delete() As with update(), delete() receives a Uri representing the instance or collection to work with and a WHERE clause and parameters. If the activity is deleting a single instance, the Uri should represent that instance and the WHERE clause may be null. But, the activity might be requesting to delete an open-ended set of instances, using the WHERE clause to constrain which ones to delete. As with update(), though, this is simple if you are using SQLite for database storage (sense a theme?). You can let it handle the idiosyncrasies of parsing and applying the WHERE clause — all you have to do is call delete() on the database. Implement getType() The last method you need to implement is getType(). This takes a Uri and returns the MIME type associated with that Uri. The Uri could be a collection or an instance Uri; you need to determine which was provided and return the corresponding MIME type. 2457 CONTENT PROVIDER THEORY Update the Manifest The glue tying the content provider implementation to the rest of your application resides in your AndroidManifest.xml file. Simply add a element as a child of the element, such as: > /> /> > /> > /> /> (from ContentProvider/ConstantsPlus/app/src/main/AndroidManifest.xml) 2458 CONTENT PROVIDER THEORY The android:name property is the name of the content provider class, with a leading dot to indicate it is in the stock namespace for this application’s classes (just like you use with activities). The android:authorities property should be a semicolon-delimited list of the authority values supported by the content provider. Recall, from earlier in this chapter, that each content Uri is made up of a scheme, authority, data type path, and instance identifier. Each authority from each CONTENT_URI value should be included in the android:authorities list. Now, when Android encounters a content Uri, it can sift through the providers registered through manifests to find a matching authority. That tells Android which application and class implements the content provider, and from there Android can bridge between the calling activity and the content provider being called. Several other attributes relate to security: • android:exported indicates whether third-party apps are able to initiate communications with your provider on their own • android:readPermission and android:writePermission allow you to defend your provider with permissions; third-party apps have to have elements for those permissions to be able to work with your provider • android:grantUriPermissions indicates whether you are able to selectively “poke pinholes in the firewall” of your provider security, to say that for specific IPC operations (e.g., starting a third-party activity), that third party has limited access to your provider’s content These will be explored later in this book. Add Notify-On-Change Support A feature that your content provider can offer to its clients is notify-on-change support. This means that your content provider will let clients know if the data for a given content Uri changes. For example, suppose you have created a content provider that retrieves RSS and Atom feeds from the Internet based on the user’s feed subscriptions (via OPML, perhaps). The content provider offers read-only access to the contents of the feeds, with an eye towards several applications on the phone using those feeds versus everyone implementing their own feed poll-fetch-and-cache system. You have also implemented a service that will get updates to those feeds asynchronously, updating 2459 CONTENT PROVIDER THEORY the underlying data store. Your content provider could alert applications using the feeds that such-and-so feed was updated, so applications using that specific feed can refresh and get the latest data. On the content provider side, to do this, call notifyChange() on your ContentResolver instance (available in your content provider via getContext().getContentResolver()). This takes two parameters: the Uri of the piece of content that changed and the ContentObserver that initiated the change. In many cases, the latter will be null; a non-null value simply means that the observer that initiated the change will not be notified of its own changes. On the content consumer side, an activity can call registerContentObserver() on its ContentResolver (via getContentResolver()). This ties a ContentObserver instance to a supplied Uri — the observer will be notified whenever notifyChange() is called for that specific Uri. When the consumer is done with the Uri, unregisterContentObserver() releases the connection. Implementing the Streaming API If you want to have a ContentProvider support streaming data via the streaming API, you will still need to set up the element, choose an authority, and create a subclass of ContentProvider as with the database-style API. From there, whether you are adding the streaming API to an existing provider or creating a new one, there is some additional work to be done. Serving the Stream If you want consumers of your ContentProvider to be able to call openInputStream() or openOutputStream() on a Uri, the most likely approach is to implement the openFile() method. The openFile() method returns a curious object called a ParcelFileDescriptor. Given that, the ContentResolver can obtain the InputStream or OutputStream that was requested. There are various static methods on ParcelFileDescriptor to create instances of it, such as an open() method that takes a File object as the first parameter. Note that this works for both files on external storage and files within your own project’s app-local file storage (e.g., getFilesDir()). openFile() also gets a String parameter that is the “mode” for opening the file. This can be converted into appropriate flags for use with ParceFileDescriptor and its 2460 CONTENT PROVIDER THEORY open() method. Mostly, this is for determining whether we are opening the file for read or write operations. Serving the Metadata You should implement the query() method in your provider as well. If the Uri is pointing to one of your streams, you should create a one-row MatrixCursor and supply the OpenableColumns as the columns. OpenableColumns has two values: DISPLAY_NAME (for some human-readable name of the stream) and SIZE (the length of the stream in bytes). Based on the projection string array passed into query(), you can skip columns that the client is not requesting. You also need to implement getType(). For the database-style API, you pretty much invent your own MIME types. For the streaming API, you should be returning MIME types for the Uri values that really represent the contents of that Uri. In other words, your getType() method should behave like you would expect a Web server to do with respect to the Content-Type header. If you know the MIME type for certain (e.g., you got it yourself in an HTTP or IMAP operation and saved it), use that. If you do not know the MIME type for certain, you can try the MimeTypeMap class, which knows how to map common file extensions to their MIME type counterparts. Worstcase, return application/octet-stream. The Rest of the Requirements You also have to implement the following abstract methods: • • • • onCreate() insert() update() delete() If you are not supporting the database-style API, you are welcome to have insert(), update(), and delete() throw some RuntimeException, to indicate that those operations are not supported. Issues with Content Providers Content providers are not without their issues. 2461 CONTENT PROVIDER THEORY The biggest complaint seems to be the lack of an onDestroy() companion to the onCreate() method you can implement. Hence, if you open a database in onCreate(), you close it… never. Sometimes, you can alleviate this by initializing things on demand and releasing them immediately, such as opening a database as part of insert() and closing it within the same method. This does not always work, however — for example, you cannot close the database you query in query(), since the Cursor you return would become invalid. Holding onto an open SQLiteDatabase is not a problem, as all of your data changes are written to disk as part of committing transactions. So, many ContentProvider implementations settle for simply never closing the database. The fact that ContentProvider is effectively a facade means that a consumer of a ContentProvider has no idea what to expect. It is up to documentation to explain what Uri values can be used, what columns can be returned, what query syntax is supported, and so on. And, the fact that it is a facade means that much of the richness of the SQLite interface is lost, such as GROUP BY. To top it off, the API supported by ContentProvider is rather limited — if what you want to share does not look like a database and does not look like a file, it may be difficult to force it into the ContentProvider API. Another issue is the client’s dependence upon the provider itself. If, for whatever reason, the provider’s process is terminated while the client has an open Cursor on query results, the client’s process is also terminated. It is unclear if the same effect occurs when the client has an open stream from a provider through the streaming API, though it seems likely. Now, in theory, the importance of the provider’s process should be raised to the highest importance of any of its clients, though this behavior is not documented and may not occur in practice. This behavior by Android is rather drastic, more drastic than what happens to HTTP clients when the Web server they are connected to crashes. There, the client winds up with some sort of exception and can move on. The moral of this story is: when working with a ContentProvider, it behooves you to use the data quickly, particularly if your app is in the background at the time. 2462 Content Provider Implementation Patterns The previous chapter focused on the concepts, classes, and methods behind content providers. This chapter more closely examines some implementations of content providers, organized into simple patterns. Prerequisites Understanding this chapter requires that you have read the preceding chapter, along with the chapter on permissions. The Single-Table Database-Backed Content Provider The simplest database-backed content provider is one that only attempts to expose a single table’s worth of data to consumers. The CallLog content provider works this way, for example. Step #1: Create a Provider Class We start off with a custom subclass of ContentProvider, named, cunningly enough, Provider. Here we need the database-style API methods: query(), insert(), update(), delete(), and getType(). 2463 CONTENT PROVIDER IMPLEMENTATION PATTERNS onCreate() Here is the onCreate() method for Provider, from the ContentProvider/ ConstantsPlus sample application: @Override public boolean onCreate() { db=new new DatabaseHelper(getContext()); return return(true true); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/Provider.java) While that does not seem all that special, the “magic” is in the private DatabaseHelper object, a fairly conventional SQLiteOpenHelper implementation: package com.commonsware.android.constants; import import import import import import android.content.ContentValues android.content.ContentValues; android.content.Context android.content.Context; android.database.Cursor android.database.Cursor; android.database.sqlite.SQLiteOpenHelper android.database.sqlite.SQLiteOpenHelper; android.database.sqlite.SQLiteDatabase android.database.sqlite.SQLiteDatabase; android.hardware.SensorManager android.hardware.SensorManager; class DatabaseHelper extends SQLiteOpenHelper { private static final String DATABASE_NAME="constants.db"; static final String TITLE="title"; static final String VALUE="value"; public DatabaseHelper(Context context) { super super(context, DATABASE_NAME, null null, 1); } @Override public void onCreate(SQLiteDatabase db) { Cursor c=db.rawQuery("SELECT name FROM sqlite_master WHERE type='table' AND name='constants'", null null); try { if (c.getCount()==0) { db.execSQL("CREATE TABLE constants (_id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT, value REAL);"); ContentValues cv=new new ContentValues(); cv.put(Provider.Constants.TITLE, "Gravity, Death Star I"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_DEATH_STAR_I); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Earth"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_EARTH); db.insert("constants", Provider.Constants.TITLE, cv); 2464 CONTENT PROVIDER IMPLEMENTATION PATTERNS cv.put(Provider.Constants.TITLE, "Gravity, Jupiter"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_JUPITER); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Mars"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_MARS); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Mercury"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_MERCURY); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Moon"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_MOON); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Neptune"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_NEPTUNE); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Pluto"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_PLUTO); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Saturn"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_SATURN); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Sun"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_SUN); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, The Island"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_THE_ISLAND); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Uranus"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_URANUS); db.insert("constants", Provider.Constants.TITLE, cv); cv.put(Provider.Constants.TITLE, "Gravity, Venus"); cv.put(Provider.Constants.VALUE, SensorManager.GRAVITY_VENUS); db.insert("constants", Provider.Constants.TITLE, cv); } } finally { c.close(); } } @Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { android.util.Log.w("Constants", "Upgrading database, which will destroy all old data"); db.execSQL("DROP TABLE IF EXISTS constants"); onCreate(db); } } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/DatabaseHelper.java) 2465 CONTENT PROVIDER IMPLEMENTATION PATTERNS Note that we are creating the DatabaseHelper in onCreate() and are never closing it. That is because there is no onDestroy() (or equivalent) method in a ContentProvider. While we might be tempted to open and close the database on every operation, that will not work, as we cannot close the database and still hand back a live Cursor from the database. Hence, we leave it open and assume that SQLite’s transactional nature will ensure that our database is not corrupted when Android shuts down the ContentProvider. query() For SQLite-backed storage providers like this one, the query() method implementation should be largely boilerplate. Use a SQLiteQueryBuilder to convert the various parameters into a single SQL statement, then use query() on the builder to actually invoke the query and give you a Cursor back. The Cursor is what your query() method then returns. For example, here is query() from Provider: @Override public Cursor query(Uri url, String[] projection, String selection, String[] selectionArgs, String sort) { SQLiteQueryBuilder qb=new new SQLiteQueryBuilder(); qb.setTables(TABLE); String orderBy; if (TextUtils.isEmpty(sort)) { orderBy=Constants.DEFAULT_SORT_ORDER; } else { orderBy=sort; } Cursor c= qb.query(db.getReadableDatabase(), projection, selection, selectionArgs, null null, null null, orderBy); c.setNotificationUri(getContext().getContentResolver(), url); return return(c); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/Provider.java) 2466 CONTENT PROVIDER IMPLEMENTATION PATTERNS We create a SQLiteQueryBuilder and pour the query details into the builder, notably the name of the table that we query against and the sort order (substituting in a default sort if the caller did not request one). When done, we use the query() method on the builder to get a Cursor for the results. We also tell the resulting Cursor what Uri was used to create it, for use with the content observer system. insert() Since this is a SQLite-backed content provider, once again, the implementation is mostly boilerplate: validate that all required values were supplied by the activity, merge your own notion of default values with the supplied data, and call insert() on the database to actually create the instance. For example, here is insert() from Provider: @Override public Uri insert(Uri url, ContentValues initialValues) { long rowID= db.getWritableDatabase().insert(TABLE, Constants.TITLE, initialValues); if (rowID > 0) { Uri uri= ContentUris.withAppendedId(Provider.Constants.CONTENT_URI, rowID); getContext().getContentResolver().notifyChange(uri, null null); return return(uri); } throw new SQLException("Failed to insert row into " + url); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/Provider.java) The pattern is the same as before: use the provider particulars plus the data to be inserted to actually do the insertion. update() Here is update() from Provider: @Override public int update(Uri url, ContentValues values, String where, 2467 CONTENT PROVIDER IMPLEMENTATION PATTERNS String[] whereArgs) { int count= db.getWritableDatabase() .update(TABLE, values, where, whereArgs); getContext().getContentResolver().notifyChange(url, null null); return return(count); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/Provider.java) In this case, updates are always applied across the entire collection, though we could have a smarter implementation that supported updating a single instance via an instance Uri. delete() Similarly, here is delete() from Provider: @Override public int delete(Uri url, String where, String[] whereArgs) { int count=db.getWritableDatabase().delete(TABLE, where, whereArgs); getContext().getContentResolver().notifyChange(url, null null); return return(count); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/Provider.java) This is almost a clone of the update() implementation described above. getType() The last method you need to implement is getType(). This takes a Uri and returns the MIME type associated with that Uri. The Uri could be a collection or an instance Uri; you need to determine which was provided and return the corresponding MIME type. For example, here is getType() from Provider: @Override public String getType(Uri url) { if (isCollectionUri(url)) { 2468 CONTENT PROVIDER IMPLEMENTATION PATTERNS return return("vnd.android.cursor.dir/constant"); } return return("vnd.android.cursor.item/constant"); } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/Provider.java) Step #2: Supply a Uri You may wish to add a public static member… somewhere, containing the Uri for each collection your content provider supports, for use by your own application code. Typically, this is a public static final Uri put on the content provider class itself: public static final Uri CONTENT_URI= Uri.parse("content://com.commonsware.android.constants.Provider/constants"); (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/Provider.java) You may wish to use the same namespace for the content Uri that you use for your Java classes, to reduce the chance of collision with others. Bear in mind that if you intend for third parties to access your content provider, they will not have access to this public static data member, as your class is not in their project. Hence, you will need to publish the string representation of this Uri that they can hard-wire into their application. Step #3: Declare the “Columns” Remember those “columns” you referenced when you were using a content provider, in the previous chapter? Well, you may wish to publish public static values for those too for your own content provider. Specifically, you may want a public static class implementing BaseColumns that contains your available column names, such as this example from Provider: public static final class Constants implements BaseColumns { public static final Uri CONTENT_URI= Uri.parse("content://com.commonsware.android.constants.Provider/constants"); public static final String DEFAULT_SORT_ORDER="title"; public static final String TITLE="title"; public static final String VALUE="value"; } (from ContentProvider/ConstantsPlus/app/src/main/java/com/commonsware/android/constants/Provider.java) 2469 CONTENT PROVIDER IMPLEMENTATION PATTERNS Since we are using SQLite as a data store, the values for the column name constants should be the corresponding column names in the table, so you can just pass the projection (array of columns) to SQLite on a query(), or pass the ContentValues on an insert() or update(). Note that nothing in here stipulates the types of the properties. They could be strings, integers, or whatever. The biggest limitation is what a Cursor can provide access to via its property getters. The fact that there is nothing in code that enforces type safety means you should document the property types well, so people attempting to use your content provider know what they can expect. Step #4: Update the Manifest Finally, we need to add the provider to the AndroidManifest.xml file, by adding a element as a child of the element: > /> /> > /> > /> 2470 CONTENT PROVIDER IMPLEMENTATION PATTERNS /> (from ContentProvider/ConstantsPlus/app/src/main/AndroidManifest.xml) The Local-File Content Provider Implementing a content provider that supports serving up files based on Uri values is similar, and generally simpler, than creating a content provider for the databasestyle API. In this section, we will examine the ContentProvider/Files sample project. This project demonstrates a common use of the filesystem-style API: serving files from internal storage to third-party applications (who, by default, cannot read your internally-stored files). Note that this sample project will only work on devices that have an application capable of viewing PDF files accessed via content:// Uri values. The FileProvider Class Our ContentProvider is named FileProvider. However, most of the logic is contained in an AbstractFileProvider that will be used for a handful of sample apps in this chapter. We will look at both of those classes, focusing first on the FileProvider. onCreate() We have an onCreate() method. In many cases, this would not be needed for this sort of provider. After all, there is no database to open. In this case, we use onCreate() to copy the file(s) out of assets into the app-local file store. In principle, this would allow our application code to modify these files as the user uses the app (versus the unmodifiable editions in assets/). @Override public boolean onCreate() { File f=new new File(getContext().getFilesDir(), "test.pdf"); if (!f.exists()) { 2471 CONTENT PROVIDER IMPLEMENTATION PATTERNS AssetManager assets=getContext().getAssets(); try { copy(assets.open("test.pdf"), f); } catch (IOException e) { Log.e("FileProvider", "Exception copying from assets", e); return return(false false); } } return return(true true); } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/FileProvider.java) This uses a static copy() method, inherited from AbstractFileProvider, that can copy an InputStream from an asset to a local File. We will take a peek at this later in this chapter. openFile() We need to implement openFile(), to return a ParcelFileDescriptor corresponding to the supplied Uri: @Override public ParcelFileDescriptor openFile(Uri uri, String mode) throws FileNotFoundException { File root=getContext().getFilesDir(); File f=new new File(root, uri.getPath()).getAbsoluteFile(); if (!f.getPath().startsWith(root.getPath())) { throw new SecurityException("Resolved path jumped beyond root"); } if (f.exists()) { return return(ParcelFileDescriptor.open(f, parseMode(mode))); } throw new FileNotFoundException(uri.getPath()); } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/FileProvider.java) 2472 CONTENT PROVIDER IMPLEMENTATION PATTERNS We are passed in a *nix-style string mode, which will be a value like r for read access, wt for write access (and truncate the file), etc. In API Level 19+, ParcelFileDescriptor has a convenience method for converting such modes into the equivalent ParcelFileDescriptor flag values. For older devices, you can simply use the parseMode() code that Google added: // following is from ParcelFileDescriptor source code // Copyright (C) 2006 The Android Open Source Project // (even though this method was added much after 2006...) private static int parseMode(String mode) { final int modeBits; if ("r".equals(mode)) { modeBits=ParcelFileDescriptor.MODE_READ_ONLY; } else if ("w".equals(mode) || "wt".equals(mode)) { modeBits= ParcelFileDescriptor.MODE_WRITE_ONLY | ParcelFileDescriptor.MODE_CREATE | ParcelFileDescriptor.MODE_TRUNCATE; } else if ("wa".equals(mode)) { modeBits= ParcelFileDescriptor.MODE_WRITE_ONLY | ParcelFileDescriptor.MODE_CREATE | ParcelFileDescriptor.MODE_APPEND; } else if ("rw".equals(mode)) { modeBits= ParcelFileDescriptor.MODE_READ_WRITE | ParcelFileDescriptor.MODE_CREATE; } else if ("rwt".equals(mode)) { modeBits= ParcelFileDescriptor.MODE_READ_WRITE | ParcelFileDescriptor.MODE_CREATE | ParcelFileDescriptor.MODE_TRUNCATE; } else { throw new IllegalArgumentException("Bad mode '" + mode + "'"); } return modeBits; } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/FileProvider.java) 2473 CONTENT PROVIDER IMPLEMENTATION PATTERNS Our openFile() method then uses parseMode() in the call to the static open() method on ParcelFileDescriptor, which opens the file (with the desired access mode) and gives us our ParcelFileDescriptor back that we can return. If the file is not found, we can throw a FileNotFoundException to indicate that. However, we also check to see that the File that we are trying to access is inside getFilesDir(), by comparing paths. A Uri can have .. path segments to move up directory levels. Using that with the File constructor means that a rogue Uri could move outside of our designated root directory (getFilesDir()), to perhaps try to access other data on our internal storage (e.g., databases). getAbsoluteFile() will net out any path-traversal segments (e.g., ..). If getAbsoluteFile() lies within getFilesDir(), we go ahead, otherwise we throw a SecurityException. getDataLength() AbstractFileProvider gives us a callback — getDataLength() — where we can indicate how big a file is, given its Uri. That information will be made available to clients consuming this stream. The default will be to indicate that the file size is unknown… and that usually works. However, if it is easy for you to determine the file size, do so, and it will increase the compatibility of your app with possible consumers. In this case, determining the size of a local file is easy: @Override protected long getDataLength(Uri uri) { File f=new new File(getContext().getFilesDir(), uri.getPath()); return return(f.length()); } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/FileProvider.java) The AbstractFileProvider Class AbstractFileProvider is designed to handle a lot of common boilerplate for streaming providers like the one provided in this sample. getType() Just as our database-style ContentProvider needed to implement getType() to provide a MIME type given a Uri, so too do our streaming providers. The difference 2474 CONTENT PROVIDER IMPLEMENTATION PATTERNS is that a streaming provider usually wants to use “real” MIME types, values that third-party apps are likely to recognize. For example, a PDF file should use a MIME type of application/pdf, as that is what PDF viewing apps will expect. Android has some convenience code for determining a likely MIME type. You can use MimeTypeMap to convert a file extension to a MIME type, or you can use guessContentTypeFromName() onURLConnection to get a MIME type for a URL. Both use the same underlying database — the difference is mostly a matter of whether you have a bare file extension already or not. So, the default implementation of getType() in AbstractFileProvider uses guessContentTypeFromName(): @Override public String getType(Uri uri) { return return(URLConnection.guessContentTypeFromName(uri.toString())); } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/AbstractFileProvider.java) If you know that your MIME type is unlikely to be recognized by Android (e.g., you invented your own), a subclass of AbstractFileProvider could handle those cases, chaining to the superclass for other Uri values. insert(), update(), and delete() ContentProvider itself is abstract, requiring us to implement a variety of methods to satisfy the compiler. Three of them — insert(), update(), and delete() — have no role in a pure-streaming ContentProvider, so AbstractFileProvider has stub implementations: @Override public Uri insert(Uri uri, ContentValues initialValues) { throw new RuntimeException("Operation not supported"); } @Override public int update(Uri uri, ContentValues values, String where, String[] whereArgs) { throw new RuntimeException("Operation not supported"); } @Override public int delete(Uri uri, String where, String[] whereArgs) { throw new RuntimeException("Operation not supported"); } 2475 CONTENT PROVIDER IMPLEMENTATION PATTERNS (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/AbstractFileProvider.java) A ContentProvider that supports both the database-style and streaming APIs will need real implementations of those methods for the database operations, perhaps throwing an Exception for requests to insert, update, or delete a Uri that represents a stream. query() and getFileName() We also need to implement query(). You can get by with having this be a stub similar to insert() and kin. However, for better compatibility, you should have a more robust query() implementation, as it will be used by ContentResolver to retrieve two pieces of metadata about a Uri: • What is a valid filename to use to represent this Uri, should we need a human-readable name? After all, a ContentProvider Uri does not have to represent a human-readable path, and so the last segment of that Uri could be a cryptic string of hex digits or something, not a filename. • What is the length of the data that should be delivered by the stream? query() will be called with a projection that contains either OpenableColumns.DISPLAY_NAME, OpenableColumns.SIZE, or both. A streaming ContentProvider ideally supports returning a Cursor with this data. The AbstractFileProvider implementation of query() handles this for us: abstract class AbstractFileProvider extends ContentProvider { private final static String[] OPENABLE_PROJECTION= { OpenableColumns.DISPLAY_NAME, OpenableColumns.SIZE }; @Override public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) { if (projection == null null) { projection=OPENABLE_PROJECTION; } final MatrixCursor cursor=new new MatrixCursor(projection, 1); MatrixCursor.RowBuilder b=cursor.newRow(); for (String col : projection) { if (OpenableColumns.DISPLAY_NAME.equals(col)) { b.add(getFileName(uri)); } 2476 CONTENT PROVIDER IMPLEMENTATION PATTERNS else if (OpenableColumns.SIZE.equals(col)) { b.add(getDataLength(uri)); } else { // unknown, so just add null b.add(null null); } } return return(new new LegacyCompatCursorWrapper(cursor)); } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/AbstractFileProvider.java) If the supplied projection is null, we assume that the caller wants the standard OpenableColumns; otherwise, we will use the supplied projection. Our results will be packaged in a MatrixCursor. This amounts to a Cursor interface on a two-dimensional array, where you build up the rows in that array via a MatrixCursor.RowBuilder. In our case, there will only be one such row, for the relevant values for the file to be streamed in support of the requested Uri. We iterate over the columns in the projection, calling out to getFileName() and getDataLength() methods for OpenableColumns.DISPLAY_NAME and OpenableColumns.SIZE respectively (and using null as the result for anything else). The default implementations of those methods return the last path segment of the Uri and AssetFileDescriptor.UNKNOWN_LENGTH, respectively: protected String getFileName(Uri uri) { return return(uri.getLastPathSegment()); } protected long getDataLength(Uri uri) { return return(AssetFileDescriptor.UNKNOWN_LENGTH); } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/AbstractFileProvider.java) Subclasses can override those as needed, as we saw with getDataLength() in the concrete FileProvider class. However, query() does not return the MatrixCursor directly. Instead, it wraps it in a LegacyCompatCursorWrapper. This class comes from the CWAC-Provider project, from the author of this book. LegacyCompatCursorWrapper is designed to try to improve compatibility with clients that are expecting query() results to include a _DATA column, the way that MediaStore does. Poorly-written clients will crash if this 2477 CONTENT PROVIDER IMPLEMENTATION PATTERNS column does not exist. LegacyCompatCursorWrapper wraps a Cursor and serves up an empty _DATA column for those clients that need one. copy() AbstractFileProvider also has a convenience copy() static method that copies InputStream to a File, used from the FileProvider onCreate() method: an static void copy(InputStream in, File dst) throws IOException { FileOutputStream out=new new FileOutputStream(dst); byte[] buf=new new byte[1024]; int len; while ((len=in.read(buf)) >= 0) { out.write(buf, 0, len); } in.close(); out.close(); } } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/AbstractFileProvider.java) The Manifest Finally, we need to add the provider to the AndroidManifest.xml file, by adding a element as a child of the element, as with any other content provider: > /> /> 2478 CONTENT PROVIDER IMPLEMENTATION PATTERNS > > /> /> /> (from ContentProvider/Files/app/src/main/AndroidManifest.xml) Note, however, that we have android:exported="true" set in our element. This means that this content provider can be accessed from third-party apps or other external processes (e.g., the media framework for playing back videos). Using this Provider The activity is fairly trivial, simply creating an ACTION_VIEW Intent on our PDF file and starting up an activity for it, then finishing itself: package com.commonsware.android.cp.files; import import import import android.app.Activity android.app.Activity; android.content.Intent android.content.Intent; android.net.Uri android.net.Uri; android.os.Bundle android.os.Bundle; public class FilesCPDemo extends Activity { @Override public void onCreate(Bundle state) { super super.onCreate(state); 2479 CONTENT PROVIDER IMPLEMENTATION PATTERNS startActivity(new new Intent(Intent.ACTION_VIEW, Uri.parse(FileProvider.CONTENT_URI + "test.pdf"))); finish(); } } (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/FilesCPDemo.java) Here, we use a CONTENT_URI published by FileProvider as the basis for identifying the file: public static final Uri CONTENT_URI= Uri.parse("content://com.commonsware.android.cp.files/"); (from ContentProvider/Files/app/src/main/java/com/commonsware/android/cp/files/FileProvider.java) The Protected Provider The problem with the preceding example is that any app on the device, if it knows the right Uri to ask for, will be able to access the file. This may be desired, but often times it will not be. Instead, you may want to specifically indicate which apps, at specific points in time, can view the file. Particularly if your objective is to start a third-party app to work with that file, setting up this sort of security is not that difficult. To see how that works, we will walk through the ContentProvider/GrantUriPermissions sample project. This is a clone of the ContentProvider/Files project with this extra security added on. The way the defense works is by using Android’s permission system. We will mark the ContentProvider as being not exported, then selectively grant that access to a specific Uri to the app that we want to view our file. Step #1: Mark the Provider as Not Exported Putting android:exported="false" on the element indicates that no app has the ability to make requests of your ContentProvider, except for specific cases where you authorize it: > /> (from ContentProvider/GrantUriPermissions/app/src/main/AndroidManifest.xml) With no other changes, if we tried to use the app, the third-party PDF viewer would crash when trying to read our PDF file from the Uri. Step #2: Grant Access to the Uri To allow third parties to get access only when we specify, we need to make a few more changes. This element also has android:grantUriPermissions="false". That is the default value for this attribute, shown here purely for illustration purposes. It also has a child element, listing the local path (within the ContentProvider) to our PDF file. The element (or elements, plural) allow us to override the permission requirement for certain pieces of content, granting access to that content on a per-request basis. There are three possibilities: 1. If android:grantUriPermissions is true, then we will be able to grant access to any content within our provider 2. If android:grantUriPermissions is false, but we have sub-elements, we can only grant access to the content identified by the Uri paths specified in those sub-elements 3. If android:grantUriPermissions is false, and we have no sub-elements (the default case), we cannot grant access to any content within our provider In this case, we specify that we will only grant access to /test.pdf. Since that is the only content in this provider, we could have the same net effect by setting android:grantUriPermissions to true. Then, when we create an Intent used to interact with another component, we can include a flag indicating what permission we wish to grant: package com.commonsware.android.cp.perms; import android.app.Activity android.app.Activity; 2481 CONTENT PROVIDER IMPLEMENTATION PATTERNS import android.content.Intent android.content.Intent; import android.net.Uri android.net.Uri; import android.os.Bundle android.os.Bundle; public class FilesCPDemo extends Activity { @Override public void onCreate(Bundle state) { super super.onCreate(state); Intent i=new new Intent(Intent.ACTION_VIEW, Uri.parse(FileProvider.CONTENT_URI + "test.pdf")); i.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION); startActivity(i); finish(); } } (from ContentProvider/GrantUriPermissions/app/src/main/java/com/commonsware/android/cp/perms/FilesCPDemo.java) In this revised version of our activity, we add FLAG_GRANT_READ_URI_PERMISSION to the Intent used with startActivity(). This will grant the activity that responds to our Intent read access to the specific Uri in the Intent, overriding the exported status. That is why, when you run this app on a device, the PDF viewer will still be able to view the file. There is also FLAG_GRANT_WRITE_URI_PERMISSION for granting write access, not needed here, as our provider only supports read access. While this is most commonly used with startActivity() (e.g., allowing a mail program limited access to your attachments provider), this can also be used with startService(), bindService(), and the various flavors of sending broadcasts (e.g., sendBroadcast()). The Stream Provider Sometimes, we want a provider that looks like the local-file provider from the preceding section… but we do not have a file. Instead, we have data in some other form, such as a byte array, or a String, or an InputStream. Writing that material to a file may be problematic, or even counterproductive. For example, imagine an app that stores data on the user’s behalf in an encrypted fashion. One such file is a PDF, that the user would like to view. There are PDF viewers that can view files served via content:// Uri values, as the previous section demonstrated… but that assumes an unencrypted file. While we could decrypt the file, writing the decrypted results to another file, and serve the decrypted data to the PDF viewer, now we have a persistent decrypted version of the data. That opens a 2482 CONTENT PROVIDER IMPLEMENTATION PATTERNS window of time when the data might be accessed by people with nefarious intent, which is something we are trying to avoid by using the encrypted store in the first place. Rather, it would be nice if we could decrypt the data on the fly and give that decrypted result to the PDF viewer. Of course, there are security risks intrinsic to that too — after all, we do not know what the PDF viewer might do with the unencrypted data — but it is at least an improvement. The good news is that Android does support streaming options for openFile()-style ContentProvider implementations. However, as one might expect, they are not the simplest things to implement. In this section, we will examine the ContentProvider/Pipe sample project. This is a near clone of the ContentProvider/Files sample from the preceding section. However, rather than simply handing the file to Android to serve as content, we will stream it in ourselves. In principle, as part of this streaming, we could be decrypting it from an encrypted state. Since this sample shares much code with the previous sample, we will focus solely on the changes here. Note that this sample was inspired by the sample found at https://github.com/ nandeeshwar/Pfd-Create-Pipe. The Pipes Starting with API Level 9, it is possible to create a pipe between two processes, from the Android SDK, via ParcelFileDescriptor. In the previous section, we saw how ParcelFileDescriptor could be used to open a local file and make that available to other processes — the createPipe() method gives us a pipe. The “pipe” returned by createPipe() is a two-element array of ParcelFileDescriptor objects. The first element in the array represents the “read” end of the pipe. In our case, that is the end that should be used by a PDF viewer to read in the file contents. The second element of the array represents the “write” end of the pipe, which we will use to supply the file’s contents to the “read” end (and to the PDF viewer by extension). The Revised openFile() With that in mind, here is our revised openFile() method: @Override public ParcelFileDescriptor openFile(Uri uri, String mode) 2483 CONTENT PROVIDER IMPLEMENTATION PATTERNS throws FileNotFoundException { ParcelFileDescriptor[] pipe=null null; try { pipe=ParcelFileDescriptor.createPipe(); AssetManager assets=getContext().getAssets(); new TransferThread(assets.open(uri.getLastPathSegment()), new AutoCloseOutputStream(pipe[1])).start(); } catch (IOException e) { Log.e(getClass().getSimpleName(), "Exception opening pipe", e); throw new FileNotFoundException("Could not open pipe for: " + uri.toString()); } return return(pipe[0]); } (from ContentProvider/Pipe/app/src/main/java/com/commonsware/android/cp/pipe/PipeProvider.java) We create our pipe via createPipe(), then get an InputStream on our PDF file stored as an asset — unlike the ContentProvider/Files sample, we do not need to copy the asset to a local file now. We then kick off a background thread, implemented in an inner class named TransferThread, to actually copy the data from the asset to the write end of the pipe. Rather than supply TransferThread with a ParcelFileDescriptor for the write end of the pipe, we supply an OutputStream. Specifically, we pass in a ParcelFileDescriptor.AutoCloseOutputStream. This is an OutputStream that knows to close the ParcelFileDescriptor when we close the stream. Otherwise, it behaves like a fairly typical OutputStream. The Transfer TransferThread is a fairly conventional copy-data-from-stream-to-stream implementation: static class TransferThread extends Thread { InputStream in; OutputStream out; TransferThread(InputStream in, OutputStream out) { this this.in=in; this this.out=out; 2484 CONTENT PROVIDER IMPLEMENTATION PATTERNS } @Override public void run() { byte[] buf=new new byte[1024]; int len; try { while ((len=in.read(buf)) >= 0) { out.write(buf, 0, len); } in.close(); out.flush(); out.close(); } catch (IOException e) { Log.e(getClass().getSimpleName(), "Exception transferring file", e); } } } (from ContentProvider/Pipe/app/src/main/java/com/commonsware/android/cp/pipe/PipeProvider.java) Here, we read in data in 1KB blocks from the InputStream (our asset) and write the data to our OutputStream (obtained from the ParcelFileDescriptor). The Results Our activity logic has not substantially changed. We still create an ACTION_VIEW Intent on the content:// Uri from our provider, pointing to our test.pdf asset. Any PDF viewer capable of handling content:// Uri values will use a ContentResolver to open an InputStream for our Uri. In the ContentProvider/ Files sample, that InputStream would receive the contents of the file directly from Android. In this new sample, that InputStream is reading in bytes off of our pipe, until such time as it has read in all the streamed data and we have closed the OutputStream. Not every possible consumer of a Uri will be able to work with our stream, though. For example, MediaPlayer expects to be able to move forwards and backwards within the stream, and while that works for file-backed ParcelFileDescriptors, it does not work for those representing a pipe. Hence, MediaPlayer will crash when trying to use a Uri to a pipe-based stream, which is certainly unfortunate. 2485 CONTENT PROVIDER IMPLEMENTATION PATTERNS The author would like to thank Reuben Scratton for his assistance in tracking down this MediaPlayer limitation. FileProvider The Android Support package now contains its own implementation of a FileProvider that greatly simplifies serving files from internal or external storage to another app. Here, we will see Google’s FileProvider in action via the ContentProvider/ V4FileProvider sample project. This is a near clone of the ContentProvider/Pipe sample from the preceding section, just leveraging FileProvider to help us serve a file from internal storage. The Rationale The documentation for FileProvider states: Apps should generally avoid sending raw filesystem paths across process boundaries, since the receiving app may not have the same access as the sender. Instead, apps should send Uri backed by a provider like FileProvider. This is not just an issue for passing files from internal storage to other apps. On Android 4.2+ tablets, it could even be an issue for external storage, as each user account gets its own portion of external storage. There may be scenarios in which your app (associated with one user) winds up needing to pass the contents of a file on external storage to another app (associated with another user). Regular filesystem paths will not work in this case, as one user account cannot directly access another user account’s files, even on external storage. The Sources of Files Google’s FileProvider offers automatic serving of files from a few root points: • getFilesDir() (i.e., the standard portion of internal storage for your app) • getCacheDir() (i.e., internal storage, but files that the OS can purge if needed to free up disk space) • Environment.getExternalStorageDirectory() (i.e., the root of external storage) 2486 CONTENT PROVIDER IMPLEMENTATION PATTERNS • getExternalFilesDir(null) and getExternalCacheDir() (i.e., unique directories on external storage for your app) For each of these, you will be able to specify a specific subdirectory’s worth of files that should be served, if you do not want the entire directory’s contents published via FileProvider. You will also be able to specify an alias, which serves as the first path segment (after the authority in the content:// Uri) — FileProvider maps that path segment to a specific location of files to serve. The Manifest Entry The information about what files to serve comes in the form of an XML resource file. You can name the file whatever you like, but its content needs to be a root element, with a series of children for the different directories you wish to serve. Those directories will be denoted via child elements with specific names: • • • • • for getFilesDir() for getCacheDir() for Environment.getExternalStorageDirectory() for getExternalFilesDir(null) for getExternalCachePath() Note that the latter two require version 24.2.0 or higher of the support library, as they are fairly new. For example, our sample project has a res/xml/provider_paths.xml file with the following contents: (from ContentProvider/V4FileProvider/app/src/main/res/xml/provider_paths.xml) Here, we are saying that we want to serve the contents of getFilesDir(), using a virtual root path of stuff. With an authority of com.commonsware.android.cp.v4file, this means that a Uri of content://com.commonsware.android.cp.v4file/stuff/test.pdf would serve up a test.pdf file in the getFilesDir() directory. 2487 CONTENT PROVIDER IMPLEMENTATION PATTERNS The optional path attribute of the , etc. elements indicates a particular subdirectory, relative to the element-specific root, that should be used as the source of files. So, for example, had the provider_paths.xml file looked like: > …then content://com.commonsware.android.cp.v4file/stuff/test.pdf would map to help/test.pdf inside of getFilesDir(). You then point to this XML resource from a element in the element in the manifest, teaching FileProvider what to serve. For example, our element in this sample app is: > /> (from ContentProvider/V4FileProvider/app/src/main/AndroidManifest.xml) Here, our android:name points to a LegacyCompatFileProvider class that we will examine shortly. We still provide the android:authorities value, along with any permission rules that we want. Beyond that, we have a element, with an android:name of android.support.FILE_PROVIDER_PATHS, that points to our XML resource with the path information. You will also notice that our android:exported attribute is set to false. As it turns out, FLAG_GRANT_READ_URI_PERMISSION trumps the exported status of a provider. If you pass a Uri to an activity using FLAG_GRANT_READ_URI_PERMISSION, the activity will be able to read the contents of that Uri, even if the provider itself is not exported. 2488 CONTENT PROVIDER IMPLEMENTATION PATTERNS The Legacy Compatibility LegacyCompatFileProvider is a simple subclass of FileProvider, one that overrides query() and wraps its Cursor in a LegacyCompatCursorWrapper to try to improve compability with ill-behaved clients: package com.commonsware.android.cp.v4file; import import import import android.database.Cursor android.database.Cursor; android.net.Uri android.net.Uri; android.support.v4.content.FileProvider android.support.v4.content.FileProvider; com.commonsware.cwac.provider.LegacyCompatCursorWrapper com.commonsware.cwac.provider.LegacyCompatCursorWrapper; public class LegacyCompatFileProvider extends FileProvider { @Override public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) { return return(new new LegacyCompatCursorWrapper(super super.query(uri, projection, selection, selectionArgs, sortOrder))); } } (from ContentProvider/V4FileProvider/app/src/main/java/com/commonsware/android/cp/v4file/LegacyCompatFileProvider.java) The Usage At this point, the provider is ready for use, insofar as we can specify Uri values like content://com.commonsware.android.cp.v4file/stuff/test.pdf and get results. Of course, we actually need to have files in our internal storage, and we need to use such a Uri. Hence, our activity combines the unpack-the-file-from-assets logic from our own providers in earlier samples, plus starts up a PDF viewer on our designated test.pdf file: package com.commonsware.android.cp.v4file; import import import import import import import import import import android.app.Activity android.app.Activity; android.content.Intent android.content.Intent; android.content.res.AssetManager android.content.res.AssetManager; android.os.Bundle android.os.Bundle; android.support.v4.content.FileProvider android.support.v4.content.FileProvider; android.util.Log android.util.Log; java.io.File java.io.File; java.io.FileOutputStream java.io.FileOutputStream; java.io.IOException java.io.IOException; java.io.InputStream java.io.InputStream; 2489 CONTENT PROVIDER IMPLEMENTATION PATTERNS public class FilesCPDemo extends Activity { private static final String AUTHORITY="com.commonsware.android.cp.v4file"; @Override public void onCreate(Bundle state) { super super.onCreate(state); File f=new new File(getFilesDir(), "test.pdf"); if (!f.exists()) { AssetManager assets=getAssets(); try { copy(assets.open("test.pdf"), f); } catch (IOException e) { Log.e("FileProvider", "Exception copying from assets", e); } } Intent i= new Intent(Intent.ACTION_VIEW, FileProvider.getUriForFile(this this, AUTHORITY, f)); i.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION); startActivity(i); finish(); } static private void copy(InputStream in, File dst) throws IOException { FileOutputStream out=new new FileOutputStream(dst); byte[] buf=new new byte[1024]; int len; while ((len=in.read(buf)) > 0) { out.write(buf, 0, len); } in.close(); out.close(); } } (from ContentProvider/V4FileProvider/app/src/main/java/com/commonsware/android/cp/v4file/FilesCPDemo.java) FileProvider offers a handy getUriForFile() static helper method that will a Uri for a given file, incorporating our specified content provider authority. 2490 return CONTENT PROVIDER IMPLEMENTATION PATTERNS The result of running this activity is the same as the other file-serving provider samples from this chapter: a PDF viewer (if one is available) will display the test.pdf file. StreamProvider FileProvider is rather nice: you can serve up typical file-based content without having to roll your own implementation of ContentProvider and openFile(). However, it only supports a few sources of data. The author of this book has written StreamProvider, a fork of FileProvider that adds support for serving content from assets and raw resources. Plus, through subclassing, you can readily serve up content from other sources as well. StreamProvider can be found in the CWAC-Provider project. You can add this library to your Android Studio project much in the same way as you can other CWAC libraries: add the CWAC repository and request the dependency: repositories { maven { url "https://s3.amazonaws.com/repo.commonsware.com" } } dependencies { implementation 'com.commonsware.cwac:provider:0.5.0' } Once you have added the CWAC-Provider dependency to your project, you use it much the same as you would use FileProvider: • Define an XML metadata file with a root element, containing one or more elements describing what you want the provider to serve • Add com.commonsware.cwac.provider.StreamProvider as a to your manifest, under your own android:authority, with a element (with a name of com.commonsware.cwac.provider.STREAM_PROVIDER_PATHS), pointing to that XML metadata > /> /> • Consider adding the USE_LEGACY_CURSOR_WRAPPER element, shown in the above example, to automatically add in LegacyCompatCursorWrapper support, described elsewhere in this chapter • Use FLAG_GRANT_READ_URI_PERMISSION and FLAG_GRANT_WRITE_URI_PERMISSION in Intent objects you use to have third parties use the files the StreamProvider serves, to allow those apps selective, temporary access to the file Exporting and Usage Patterns If your StreamProvider is exported, all of your streams will be considered read-only, regardless of any other configuration. Mostly, this mode is here for cases where you need a streaming provider and cannot grant Uri permissions (e.g., implementing a ChooserTargetService). If your StreamProvider is not exported, and it has android:grantUriPermissions set, then you can control, on a per-Uri basis, which clients get access to your streams. This works identically to how FileProvider works. Whether a particular source of streams is read-only or read-write will depend on whether the stream is a file and your metadata configuration. Wherever possible, elect to not export the provider and use FLAG_GRANT_READ_URI_PERMISSIONS or similar techniques to selectively grant access to your content. Note that the exported-and-read-only rule is on a per-provider basis. If you have some content that needs to be published globally and others that are not: • Use StreamProvider and one element for one set of content, with one authority and android:exported setting 2492 CONTENT PROVIDER IMPLEMENTATION PATTERNS • Subclass StreamProvider and have a separate element for the other set of content, with a separate authority and android:exported setting Metadata Elements Google’s FileProvider supports: • for serving files from your app’s getFilesDir() • for serving files from Environment.getExternalStoragePublicDirectory() • for serving files from your app’s getCacheDir() • for serving files from getExternalFilesDir() • for serving files from getExternalCacheDir() Each of those take a name attribute, indicating the first path segment of the Uri that should identify this particular source of files. For example, a name of foo would mean that content://your.authority.here/foo/... would look for a ... file in that particular element’s source of files. Each of those optionally take a path attribute, indicating a subdirectory under the element-defined root to use as the source of files, rather than the root itself. So, a with a path="stuff" attribute would serve files from the stuff/ subdirectory within getFilesDir(). Note that path can point to a file as well, to limit access to a single file rather than a directory. Note that path is required for , so you do not accidentally serve everything under getFilesDir(). Also, each can optionally take a readOnly attribute. If this is set to true, then the files will be readable, but not writeable. also can take an optional dir attribute. If missing, the files are served from getExternalFilesDir(). If a valid value of dir is supplied, that value is passed into getExternalFilesDir(). As such, dir is limited to be one of the Environment.DIRECTORY_* constants: • • • • • • • Alarms DCIM Documents Download Movies Music Notifications 2493 CONTENT PROVIDER IMPLEMENTATION PATTERNS • Pictures • Podcasts • Ringtones However, you cannot have both with no dir (indicating that you are serving from getExternalFilesDir(null)) and one or more elements with dir values, as they will conflict. StreamProvider adds support for: • for serving a particular raw resource, where the path is the name of the raw resource (without file extension) • for serving files from assets/ • , for serving files from locations identified by getDir() • , for serving files from locations identified by Environment.getExternalStoragePublicDirectory() Hence, StreamProvider is especially useful when you want to package some content — such as a PDF file for online help — that you want to serve from your app. Just drop the file in assets/ in your project, set up StreamProvider to serve up assets, and use an appropriate Intent with startActivity() to view that file. In the case of , two attributes are required: • dir, which indicates what directory to serve (this is passed into getDir()) • path, which serves its normal role, to determine what to serve from the directory identified by dir In the case of , dir is required. It needs to be the string value of one of the Environment.DIRECTORY_* constants, listed above. Assets and Gradle For files you are looking to share from your app’s assets/, you will need to teach the build system to avoid compressing those files. While annoying, it helps StreamProvider be more compatible with various client apps. To do this, add an aaptOptions closure to your android closure in your module’s build.gradle file. For example, you might have: 2494 CONTENT PROVIDER IMPLEMENTATION PATTERNS android { compileSdkVersion 25 buildToolsVersion "25.0.0" aaptOptions { noCompress 'pdf', 'mp4', 'ogg' } } This would tell Gradle and the build system to not compress files ending in pdf, mp4, and ogg. For your own project, you would choose the file extensions of relevance for the content that you are looking to serve out of assets/. I Can Haz Uri? FileProvider has the static getUriForFile() convenience method, to build a Uri pointing to the FileProvider, given the File that you wish to serve. StreamProvider has a similar getUriForFile() method, with three key differences: 1. It only takes the authority string and the File; no Context is necessary 2. It only works for files, not assets or raw resources 3. Rather than throwing an exception for an unrecognized File (the way FileProvider does), StreamProvider just returns null, indicating that the File you requested is not one that the StreamProvider is configured to serve So, you can call StreamProvider.getUriForFile(AUTHORITY, f), for some String for your AUTHORITY and some File (here named f) to get a Uri pointing to that file, for the purposes of using that Uri in an Intent, etc. Uri Prefixes Activities that support ACTION_SEND through an appropriate are likely to have a flaw: they probably do not validate the Uri being supplied via EXTRA_STREAM. The “surreptitious sharing” attack takes advantage of this, tricking the app into sharing its own content. While the researchers who reported this flaw focused on file: Uri schemes, content: is also vulnerable, if your provider’s Uri values are predictable. To help defeat this attack, StreamProvider automatically adds a per-install UUID to each Uri. So, instead of: 2495 CONTENT PROVIDER IMPLEMENTATION PATTERNS content://your.authority.here/something/and/a/relative/path.xml the Uri will be something like: content://your.authority.here/9b80af30-4507-4f34-956a-3b47e4a7f27f/ something/and/a/relative/path.xml By using a UUID unique for this installation of your app, it makes your Uri values dependent upon the device. This makes it more difficult for attackers to hand you a valid Uri to your own content to send somewhere that you might not want. On the flip side, this makes constructing your own Uri values a bit more difficult. For files, you can use the getUriForFile() method. For assets and raw resources, you can call the static getUriPrefix() method to get the prefix that is being used, and add that to your Uri, such as by using a Uri.Builder: PROVIDER .buildUpon() .appendPath(StreamProvider.getUriPrefix(AUTHORITY)) .appendPath(path) .build() getUriPrefix() takes the authority string of your StreamProvider and returns prefix… or null, if by subclassing StreamProvider, you disabled this prefix. the Extending StreamProvider You are welcome to create subclasses of StreamProvider, to extend its capabilities for things that you may want to do in your app. For example, the instrumentation tests for StreamProvider demonstrate creating a subclass that supports serving database files, via a custom element in the metadata. By and large, you just create a subclass of StreamProvider and use it in your element. Of importance are the hooks in StreamProvider to allow subclasses to change critical behavior. 2496 CONTENT PROVIDER IMPLEMENTATION PATTERNS Customizing the Uri Prefix In your subclass, you have three options for changing the Uri prefix used by StreamProvider: • If you want a per-install value, but just not a UUID, override buildUriPrefix() and return your own generated String • If you want a fixed prefix, to be used for all installs of this provider, override getUriPrefix() and return your constant • If you do not want a prefix, override getUriPrefix() and return null Supporting Other Stream Locations You may have content located in directories other than what StreamProvider supports out of the box, such as the path for SQLite databases. To handle that, you can add support for new XML elements in the element (e.g., for serving up databases). To do this, in your StreamProvider subclass, override buildStrategy() and return a StreamStrategy implementation that is configured for your scenario. For files located in unusual spots, LocalPathStrategy should work. In the library’s androidTest/ source set, you will find a DatabaseProvider that, at the time of this writing, looks like this: public class DatabaseProvider extends StreamProvider { private static final String TAG="database-path"; @Override protected StreamStrategy buildStrategy(Context context, String tag, String name, String path, boolean readOnly, HashMap attrs) throws IOException { if (TAG.equals(tag)) { return return(new new LocalPathStrategy(name, context.getDatabasePath(path))); } return return(super super.buildStrategy(context, tag, name, path, attrs)); } } 2497 CONTENT PROVIDER IMPLEMENTATION PATTERNS The parameters to buildStrategy() are: • a Context, should you need one (though do not assume it is any particular sort of Context) • the tag we encountered (e.g., database-path) • the value of the name attribute, which all of these need to have, as that is how we determine which StreamStrategy handles this request • the value of the path attribute, which can be null • a HashMap of all attributes, in case you wish to have some custom ones Either return your own StreamStrategy instance based off of this information or chain to the superclass’ implementation, so StreamProvider can handle the stock tags. If your provider is intrinsically read-only (i.e., it is impossible to modify the content), you can ignore the readOnly flag. If, however, your content could be modified, and you support modification, please honor the readOnly flag and block modifications/deletions when that is set to true. Supporting Other Stream Strategies You may have content located in things that are not files, such as BLOB columns in a database. In theory, you can create a custom StreamStrategy implementation that handles this. However, this has not been tried much, and so there are likely to be some gaps in the implementation. That being said, you can examine the built-in strategies (e.g., AssetStrategy, LocalPathStrategy) and their superclasses (e.g., AbstractPipeStrategy) to see how to implement strategies. Adding Columns to query() You may wish to add other columns in response to a query() call, beyond the OpenableColumns that StreamProvider handles itself and the _DATA and MIME_TYPE columns added by LegacyCompatCursorWrapper. To do that, override getValueForQueryColumn() in your StreamProvider subclass. This is supplied the Uri of the content and the name of the column requested by the client. You can return an Object suitable for stuffing into a MatrixCursor to send back – typically, this will be a String, int, or long. 2498 CONTENT PROVIDER IMPLEMENTATION PATTERNS Totally Overhauling Uri Handling StreamProvider itself holds onto a CompositeStreamStrategy, delegating all operations to it. If you wish to extend CompositeStreamStrategy and do things differently, also override buildCompositeStrategy() on your StreamProvider subclass, to return the instance of the CompositeStreamStrategy that you want the StreamProvider to use. Overriding Standard Methods You can override standard ContentProvider methods (e.g., getType()) if needed. Alternatively, you can override the methods on a StreamStrategy, then use that alternative StreamStrategy implementation in your buildStrategy() method. Adding Support for insert() and update() By default, none of the StreamStrategy implementations support insert() or update(). However, your custom StreamStrategy can, whether you are extending one of the stock strategy classes or are implementing your own from scratch. First, override canInsert() and/or canUpdate(), returning true for those operations you do support. Then, you can override insert() and update(), which have the same method signatures on StreamStrategy as they do on ContentProvider. There, you can do what you wish. 2499 The Loader Framework One perpetual problem in Android development is getting work to run outside the main application thread. Every millisecond we spend on the main application thread is a millisecond that our UI is frozen and unresponsive. Disk I/O, in particular, is a common source of such slowdowns, particularly since this is one place where the emulator typically out-performs actual devices. While disk operations rarely get to the level of causing an “application not responding” (ANR) dialog to appear, they can make a UI “janky”. Android 3.0 introduced a new framework to help deal with loading bulk data off of disk, called “loaders”. The hope is that developers can use loaders to move database queries and similar operations into the background and off the main application thread. That being said, loaders themselves have issues, not the least of which is the fact that it is new to Android 3.0 and therefore presents some surmountable challenges for use in older Android devices. This chapter will outline the programming pattern loaders are designed to solve, how to use loaders (both built-in and third-party ones) in your activities, and how to create your own loaders for scenarios not already covered. Prerequisites Understanding this chapter requires that you have read the chapters on: • database access • content provider theory • content provider implementations 2501 THE LOADER FRAMEWORK Cursors: Issues with Management Android had the concept of “managed cursors” in Android 1.x/2.x. A managed Cursor was one that an Activity… well… manages. More specifically: 1. When the activity was stopped, the managed Cursor was deactivated, freeing up all of the memory associated with the result set, and thereby reducing the activity’s heap footprint while it was not in the foreground 2. When the activity was restarted, the managed Cursor was requeried, to bring back the deactivated data, along the way incorporating any changes in that data that may have occurred while the activity was off-screen 3. When the activity was destroyed, the managed Cursor was closed. This is a delightful set of functionality. Cursor objects obtained from a ContentProvider via managedQuery() were automatically managed; a Cursor from SQLiteDatabase could be managed by startManagingCursor(). The problem is that the requery() operation that was performed when the activity is restarted is executed on the main application thread. As has been noted elsewhere in the book, you really do not want to do disk I/O on the main application thread, as it freezes the UI and causes jank. This is particularly true for database I/O, where you may not know in advance exactly how much data you will get back or how long the query will take. Introducing the Loader Framework The Loader framework was designed to solve three issues with the old managed Cursor implementation: • Arranging for a requery() (or the equivalent) to be performed on a background thread) • Arranging for the original query that populated the data in the first place to also be performed on a background thread, which the managed Cursor solution did not address at all • Supporting loading things other than a Cursor, in case you have data from other sources (e.g., XML files, JSON files, Web service calls) that might be able to take advantage of the same capabilities as you can get from a Cursor via the loaders 2502 THE LOADER FRAMEWORK There are three major pieces to the Loader framework: LoaderManager, LoaderCallbacks, and the Loader itself. LoaderManager LoaderManager is your gateway to the Loader framework. You obtain one by calling getLoaderManager() (or getSupportLoaderManager(), as is described later in this chapter). Via the LoaderManager you can initialize a Loader, restart that Loader (e.g., if you have a different query to use for loading the data), etc. LoaderCallbacks Much of your interaction with the Loader, though, comes from your LoaderCallbacks object, such as your activity if that is where you elect to implement the LoaderCallbacks interface. Here, you will implement three “lifecycle” methods for consuming a Loader: 1. onCreateLoader() is called when your activity requests that a LoaderManager initialize a Loader. Here, you will create the instance of the Loader itself, teaching it whatever it needs to know to go load your data 2. onLoadFinished() is called when the Loader has actually loaded the data — you can take those results and pour them into your UI, such as calling swapCursor() on a CursorAdapter to supply the fresh Cursor’s worth of data 3. onLoaderReset() is called when you should stop using the data supplied to you in the last onLoadFinished() call (e.g., the Cursor is going to be closed), so you can arrange to make that happen (e.g., call swapCursor(null) on a CursorAdapter) When you implement the LoaderCallbacks interface, you will need to provide the data type of whatever it is that your Loader is loading (e.g., LoaderCallbacks). If you have several loaders returning different data types, you may wish to consider implementing LoaderCallbacks on multiple objects (e.g., instances of anonymous inner classes), so you can take advantage of the type safety offered by Java generics, rather than implementing LoaderCallbacks