I released my first app to the Android Market recently. It was just complicated enough that I thought I should provide some help screens inside the app. I have taken what I did there and built a demo app, in order to illustrate how one can build a simple help screen in Android.
My simple Help screen consists of a summary page where there is an image and a brief description for each help topic. Touching the image takes you to the full help text for a topic. The figures below show what the two activities look like.
Figure 1 – Help screen
Figures 2-3 – Topic screen for topics 1 and 2
It is easy to build this kind of help screen. You need two layouts: one for the help activity and one for the topics. All of the help text comes from xml files in the resource folders. The help text can include paragraphs, text formatting (bold, italics), and even links to web pages. Even if you do not need a Help screen for your app, knowing how to have formatted Html text in an Android text view could be of use to you.
Help Activity
The demo app starts out in the HelpActivity. Its layout file is help.xml.
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:background="@color/light_background"
android:orientation="vertical" >
<ScrollView android:id="@+id/ScrollView1"
android:layout_width="fill_parent"
android:layout_height="fill_parent">
<LinearLayout
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:layout_weight="1"
android:padding="6dip"
>
<TextView
android:id="@+id/help_page_intro"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/help_page_intro"
android:padding="2dip"
android:layout_weight="1"
/>
...
</LinearLayout>
</ScrollView>
</LinearLayout>
The first thing to note is that it starts with a ScrollView that encloses a single LinearLayout. Doing that is all you need to have scrolling on the Help screen.
After the two items that support scrolling and the text view for the introduction, there are four LinearLayout views that use the horizontal orientation. Each one includes an image button and some summary text. This is what the first one looks like.
<LinearLayout
android:orientation="horizontal"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:layout_weight="1"
android:padding="4dip">
<Button android:id="@+id/help_button1"
android:layout_weight="1"
android:layout_width="180dip"
android:layout_height="wrap_content"
style="@style/HelpButton.Dark"
android:onClick="onClickHelp"
android:text="@string/help_title_section1"
android:drawableTop="@drawable/help_image1"/>
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/help_text_section1"
android:padding="8dip"
android:layout_weight="1"
/>
</LinearLayout>
The image button has an image with text underneath it. The text comes from the resource string help_title_section1 (which has a value “Topics”). The drawable is defined by the help_image1 definition in the drawable folder. What makes this interesting is that it is not an image file, but an xml file.
<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_focused="true" android:state_pressed="true"
android:drawable="@drawable/light_bulb_pressed"/>
<item android:state_focused="false" android:state_pressed="true"
android:drawable="@drawable/light_bulb_pressed"/>
<item android:state_focused="true" android:drawable="@drawable/light_bulb_selected"/>
<item android:state_focused="false" android:state_pressed="false"
android:drawable="@drawable/light_bulb_default"/>
</selector>
I used three distinct images so that the “selected” button looks different from the “pressed” button, and both are different from the button in its normal state. (For more on how to use these state lists, see StateListDrawable.)
Like other buttons, you can define the onClick handler in the xml file. In this case, the handler is onClickHelp. In fact, all four of the buttons use the same handler. The id of the view is used to determine which of the buttons was clicked.
The definition of onClickHelp is in HelpActivity. It looks at the id of the view to determine the resource id of the text to display in a TopicActivity. Note how it passes that argument as it starts the TopicActivity using an Intent.
public void onClickHelp (View v)
{
int id = v.getId ();
int textId = -1;
switch (id) {
case R.id.help_button1 :
textId = R.string.topic_section1;
break;
case R.id.help_button2 :
textId = R.string.topic_section2;
break;
case R.id.help_button3 :
textId = R.string.topic_section3;
break;
case R.id.help_button4 :
textId = R.string.topic_section4;
break;
default:
break;
}
if (textId >= 0) startInfoActivity (textId);
else toast ("Detailed Help for that topic is not available.", true);
}
public void startInfoActivity (int textId)
{
if (textId >= 0) {
Intent intent = (new Intent(this, TopicActivity.class));
intent.putExtra (ARG_TEXT_ID, textId);
startActivity (intent);
}
}
Topic Activity
It may be a bit of a surprise to see how little code there is in the TopicActivity. It starts up and sets its content view. Then it reads the id of the string resource that is to be displayed on the screen. It locates the resource string and processes it as Html text and assigns that to the text view defined in the topic.xml.
protected void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView (R.layout.topic);
// Read the arguments from the Intent object.
Intent in = getIntent ();
mTextResourceId = in.getIntExtra (HelpActivity.ARG_TEXT_ID, 0);
if (mTextResourceId <= 0) mTextResourceId = R.string.no_help_available;
TextView textView = (TextView) findViewById (R.id.topic_text);
textView.setMovementMethod (LinkMovementMethod.getInstance());
textView.setText (Html.fromHtml (getString (mTextResourceId)));
}
The line with the LinkMovementMethod is also important. Without that, links displayed on the screen are not active.
The Html.fromHtml method allows you to define paragraphs, bold, italics and links in the resource strings that define the help text. Figures 2-3 above showed what the formatted text looks like. The following is the string topic_section2 defined in the help_strings.xml file.
<string name="topic_section2">
<![CDATA[
<p>
You can display simple forms of Html in a text view.
You use the Html class and its fromHtml static method.
See
<a href="http://developer.android.com/reference/android/text/Html.html">Html
on Android Developers</a>.
</p>
<p>
As shown here, paragraphs are supported,
as are <b>bold text</b> and <i>italics</i>.
The preceding paragraph has a link in it.
</p>
<p><b>Return to the previous screen by touching the Back button.</b>
</p>
]]>
</string>
Source Code
The source code for this demo app can be downloaded from these two locations: (1) download source from Google Docs; (2) download source from Wglxy.com. The zip file at Google Docs is shared with everyone, but sometimes people outside the US have trouble downloading it. If you have problems, try the second location.
This demo app was built with Android API 10. Be sure to rebuild the project using the “Clean” command on the Build menu in Eclipse.
Integrating Help Into Your App
If you decide to you want a Help screen in your app, you can start with the code above. If you would like to have a form of context-sensitive help, you could consider doing what I did in my Gomoku League app.
In Gomoku League, I used the Help and Topic activities so I could explain how to play the game of Gomoku and how the league part of the app works. Gomoku League has a user interface based on the dashboard pattern. In the action bar for each section of the app, there is a “?” button that takes you directly to the help for that activity.
Even if you do not have an action bar at the top of the screen, you can find other ways to support context-sensitive help. The simplest is to include a Help item on the menu that you display when the user pushes the Menu button.
Recent Comments