Created an HTML help system, which is hooked up to the Menu/Help button. It also runs automatically the first time a new version of the app is run on a particular device. I wrote up a bunch of pages, which feature great art by Joseph, including a What's New page that we can edit for every release.

git-svn-id: https://zxing.googlecode.com/svn/trunk@761 59b500cc-1b3d-0410-9834-0bbf25fbcc57
2024-11-09 20:44:03 -08:00 · 2008-11-25 22:12:02 +00:00 · 2008-11-25 22:12:02 +00:00 · fd327c94c4
parent b300a0a4b4
commit fd327c94c4
22 changed files with 315 additions and 14 deletions
--- a/android/AndroidManifest.xml
+++ b/android/AndroidManifest.xml
@ -85,6 +85,13 @@ versionName is 2.31, 2.4, or 3.0. -->
        <category android:name="android.intent.category.DEFAULT"/>
      </intent-filter>
    </activity>
+    <activity android:name="HelpActivity"
+              android:screenOrientation="user">
+      <intent-filter>
+        <action android:name="android.intent.action.VIEW"/>
+        <category android:name="android.intent.category.DEFAULT"/>
+      </intent-filter>
+    </activity>
  </application>
  <uses-permission android:name="android.permission.CAMERA"/>
  <uses-permission android:name="android.permission.READ_CONTACTS"/>
--- a/android/assets/html/about1d.html
+++ b/android/assets/html/about1d.html
@ -0,0 +1,15 @@
+<html>
+<title>About 1D Barcodes</title>
+<body>
+<link rel="StyleSheet" href="style.css" type="text/css">
+<h3><center>About 1D Barcodes</center></h3>
+<p>Traditional barcodes are also known as one dimensional barcodes. There are several varieties,
+  including UPC and EAN in common use. Most look similar to this:</p>
+<center><p><img src="../images/big-1d.png"></p></center>
+<p>These 1D barcodes contain a unique code which typically describes a product, like a CD or a book.
+  You can look this code up on the internet to find prices, reviews, and more.</p>
+<p>If you scan a book, you can also search the contents of the book for a word or phrase, and find
+  all the pages where it appears:</p>
+<center><p><img src="../images/search-book-contents.jpg"></p></center>
+</body>
+</html>
--- a/android/assets/html/about2d.html
+++ b/android/assets/html/about2d.html
@ -0,0 +1,22 @@
+<html>
+<title>About 2D Barcodes</title>
+<body>
+<link rel="StyleSheet" href="style.css" type="text/css">
+<h3><center>About 2D Barcodes</center></h3>
+<p><b>Barcode Scanner</b> also understands how to read two dimensional barcodes called QR Codes. For
+  example, the QR Code below contains a hyperlink to the ZXing Project home page:</p>
+<center><p><img src="../images/big-qr.png"></p></center>
+<p>You can also represent contact information in a QR Code, and put it on a business card or web
+  site. When you scan it, the results screen provides a choice of actions:</p>
+<center><p><img src="../images/contact-results-screen.jpg"></p></center>
+<p>Besides URLs and contact info, QR Codes can also contain:</p>
+<ul>
+  <li>Calendar events, which you can add to your Calendar</li>
+  <li>Phone numbers, which you can dial</li>
+  <li>SMS numbers, which you can text message</li>
+  <li>Email addresses, which you can email</li>
+  <li>Geographic coordinates, which you can open in Maps</li>
+  <li>Plain text, which you can read, then share with a friend</li>
+</ul>
+</body>
+</html>
--- a/android/assets/html/index.html
+++ b/android/assets/html/index.html
@ -0,0 +1,19 @@
+<html>
+<title>Barcode Scanner Help</title>
+<body>
+<link rel="StyleSheet" href="style.css" type="text/css">
+<h3><center>Welcome to Barcode Scanner</center></h3>
+<p><b>Barcode Scanner</b> lets you use your Android camera phone to read barcodes, then look up
+  product information such as prices and reviews.</p>
+<center><p><img src="../images/scan-example.png"></p></center>
+<p>It can also read 2D barcodes called QR Codes, which can contain links to web sites, contact
+  info like phone number and email, and more. Click below to learn more.</p>
+<ul>
+  <li><a href="whatsnew.html">What's New</a></li>
+  <li><a href="scanning.html">How To Scan</a></li>
+  <li><a href="about1d.html">About 1D Barcodes</a></li>
+  <li><a href="about2d.html">About 2D Barcodes</a></li>
+  <li><a href="sharing.html">How To Share Data With Friends</a></li>
+</ul>
+</body>
+</html>
--- a/android/assets/html/scanning.html
+++ b/android/assets/html/scanning.html
@ -0,0 +1,21 @@
+<html>
+<title>How To Scan</title>
+<body>
+<link rel="StyleSheet" href="style.css" type="text/css">
+<h3><center>How To Scan</center></h3>
+<p>Scanning a barcode is fast and easy. <b>Barcode Scanner</b> continuously scans the viewfinder
+  rectangle, so there's no need to press the shutter button. Just move the phone until the barcode
+  is completely inside:</p>
+<center><p>
+  <img src="../images/demo-yes.png">&nbsp;&nbsp;&nbsp;<img src="../images/demo-no.png">
+</p></center>
+<p>If you're having trouble, make sure to hold the phone steady. If the camera is unable to focus,
+  try moving further back from the barcode.</p>
+<p>When a barcode is found, the phone will beep and take you to the results screen, which describes
+  what you found, and offers a choice of actions. Learn more:</p>
+<ul>
+  <li><a href="about1d.html">About 1D Barcodes</a></li>
+  <li><a href="about2d.html">About 2D Barcodes</a></li>
+</ul>
+</body>
+</html>
--- a/android/assets/html/sharing.html
+++ b/android/assets/html/sharing.html
@ -0,0 +1,14 @@
+<html>
+<title>How To Share</title>
+<body>
+<link rel="StyleSheet" href="style.css" type="text/css">
+<h3><center>How To Share</center></h3>
+<p>In addition to <a href="about2d.html">scanning 2D barcodes</a>, <b>Barcode Scanner</b> can also
+  generate a QR Code and display it on your screen. Then you can show it to a friend, and let them
+  scan the barcode with their phone:</p>
+<center><p><img src="../images/scan-from-phone.png"></p></center>
+<p>To use this feature, press the Menu button from the main scanning screen, and tap Share. Then
+  choose whether you want to share a contact, a bookmark, or the contents of the clipboard. A QR
+  Code will be generated automatically. When you're done, press Back or Home.</p>
+</body>
+</html>
--- a/android/assets/html/style.css
+++ b/android/assets/html/style.css
@ -0,0 +1,6 @@
+body {
+  background-color: white;
+  color: black;
+  font-family: arial;
+  font-size: 16;
+}
--- a/android/assets/html/whatsnew.html
+++ b/android/assets/html/whatsnew.html
@ -0,0 +1,20 @@
+<html>
+<title>What's New</title>
+<body>
+<link rel="StyleSheet" href="style.css" type="text/css">
+<h3><center>What's New</center></h3>
+<p>New in version 2.4, you can <a href="sharing.html">share information with your friends</a> using
+  barcodes:</p>
+<center><p><img src="../images/scan-from-phone.png"></p></center>
+<p>There are lots of other improvements too:</p>
+<ul>
+  <li>Scanning is now twice as fast</li>
+  <li>Contact info can now contain URLs, birthdays, and more</li>
+  <li>Calendar events can be read from QR Codes, and added to your calendar</li>
+  <li>Improved support for reading Japanese characters in QR Codes</li>
+  <li>Searching Google will now use the phone's locale and go to the local site, instead of always
+  using google.com</li>
+  <li>This new HTML help system</li>
+</ul>
+</body>
+</html>
--- a/android/assets/images/big-1d.png
+++ b/android/assets/images/big-1d.png
--- a/android/assets/images/big-qr.png
+++ b/android/assets/images/big-qr.png
--- a/android/assets/images/contact-results-screen.jpg
+++ b/android/assets/images/contact-results-screen.jpg
--- a/android/assets/images/demo-no.png
+++ b/android/assets/images/demo-no.png
--- a/android/assets/images/demo-yes.png
+++ b/android/assets/images/demo-yes.png
--- a/android/assets/images/scan-example.png
+++ b/android/assets/images/scan-example.png
--- a/android/assets/images/scan-from-phone.png
+++ b/android/assets/images/scan-from-phone.png
--- a/android/assets/images/search-book-contents.jpg
+++ b/android/assets/images/search-book-contents.jpg
--- a/android/res/layout/help.xml
+++ b/android/res/layout/help.xml
@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (C) 2008 ZXing authors
+
+ 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.
+ -->
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+              android:layout_width="fill_parent"
+              android:layout_height="fill_parent"
+              android:background="@color/help_view"
+              android:orientation="vertical">
+
+  <WebView android:id="@+id/help_contents"
+           android:layout_width="fill_parent"
+           android:layout_height="wrap_content"
+           android:layout_weight="1"/>
+
+  <LinearLayout
+      android:layout_width="fill_parent"
+      android:layout_height="wrap_content"
+      android:layout_weight="0"
+      android:orientation="horizontal"
+      android:gravity="right"
+      android:padding="8px"
+      android:background="@color/help_button_view">
+
+    <Button android:id="@+id/back_button"
+            android:layout_width="100px"
+            android:layout_height="wrap_content"
+            android:text="@string/button_back"/>
+
+    <Button android:id="@+id/exit_button"
+            android:layout_width="100px"
+            android:layout_height="wrap_content"
+            android:text="@string/button_exit"/>
+
+  </LinearLayout>
+
+</LinearLayout>
--- a/android/res/values/colors.xml
+++ b/android/res/values/colors.xml
@ -17,6 +17,8 @@
 <resources>
  <color name="contents_text">#ff000000</color>
  <color name="encode_view">#ffffffff</color>
+  <color name="help_button_view">#ffcccccc</color>
+  <color name="help_view">#ffffffff</color>
  <color name="result_image_border">#ffffffff</color>
  <color name="result_minor_text">#ffc0c0c0</color>
  <color name="result_points">#c000ff00</color>
--- a/android/res/values/strings.xml
+++ b/android/res/values/strings.xml
@ -20,11 +20,13 @@

  <string name="button_add_calendar">Add event to calendar</string>
  <string name="button_add_contact">Add contact</string>
+  <string name="button_back">Back</string>
  <string name="button_book_search">Open Book Search</string>
  <string name="button_cancel">Cancel</string>
  <string name="button_clipboard_empty">Clipboard empty</string>
  <string name="button_dial">Dial number</string>
  <string name="button_email">Send email</string>
+  <string name="button_exit">Exit</string>
  <string name="button_get_directions">Get directions</string>
  <string name="button_mms">Send MMS</string>
  <string name="button_ok">OK</string>
@ -56,17 +58,13 @@
  <string name="msg_default_contents">Contents</string>
  <string name="msg_default_format">Format</string>
  <string name="msg_default_mms_subject">Hi</string>
-  <string name="msg_default_status">Place a barcode inside the viewfinder rectangle to read it.
+  <string name="msg_default_status">Place a barcode inside the viewfinder rectangle to scan it.
  </string>
  <string name="msg_default_type">Type</string>
  <string name="msg_encode_barcode_failed">Could not generate the requested barcode.</string>
  <string name="msg_encode_contents_failed">Could not encode a barcode from the data provided.
  </string>
  <string name="msg_encode_in_progress">Generating a barcode\u2026</string>
-  <string name="msg_help">Barcode Scanner continuously scans the viewfinder rectangle, so there\'s
-    no need to press the shutter button. If you\'re having trouble, make sure to hold the phone
-    steady. If the camera is unable to focus, try moving further back from the barcode.
-  </string>
  <string name="msg_sbc_failed">Sorry, the search encountered a problem.</string>
  <string name="msg_sbc_no_page_returned">No page returned</string>
  <string name="msg_sbc_page">Page</string>
@ -99,7 +97,6 @@
  <string name="share_name">Share via barcode</string>

  <string name="title_about">About Barcode Scanner</string>
-  <string name="title_help">Help</string>

  <string name="zxing_url">http://code.google.com/p/zxing</string>
  <string name="zxing_user_agent">ZXing-Android/1.1</string>
--- a/android/src/com/google/zxing/client/android/CaptureActivity.java
+++ b/android/src/com/google/zxing/client/android/CaptureActivity.java
@ -21,6 +21,8 @@ import android.app.AlertDialog;
 import android.content.DialogInterface;
 import android.content.Intent;
 import android.content.SharedPreferences;
+import android.content.pm.PackageInfo;
+import android.content.pm.PackageManager;
 import android.content.res.AssetFileDescriptor;
 import android.content.res.Configuration;
 import android.graphics.Bitmap;
@ -72,6 +74,8 @@ public final class CaptureActivity extends Activity implements SurfaceHolder.Cal
  private static final int INTENT_RESULT_DURATION = 1500;
  private static final float BEEP_VOLUME = 0.15f;

+  private static final String PACKAGE_NAME = "com.google.zxing.client.android";
+
  public CaptureActivityHandler mHandler;

  private ViewfinderView mViewfinderView;
@ -83,9 +87,7 @@ public final class CaptureActivity extends Activity implements SurfaceHolder.Cal
  private boolean mPlayBeep;
  private boolean mScanIntent;
  private String mDecodeMode;
-  /**
-   * When the beep has finished playing, rewind to queue up another one.
-   */
+
  private final OnCompletionListener mBeepListener = new BeepListener();

  @Override
@ -103,6 +105,8 @@ public final class CaptureActivity extends Activity implements SurfaceHolder.Cal
    mHandler = null;
    mLastResult = null;
    mHasSurface = false;
+
+    showHelpOnFirstLaunch();
  }

  @Override
@ -206,11 +210,9 @@ public final class CaptureActivity extends Activity implements SurfaceHolder.Cal
        break;
      }
      case HELP_ID: {
-        AlertDialog.Builder builder = new AlertDialog.Builder(this);
-        builder.setTitle(R.string.title_help);
-        builder.setMessage(R.string.msg_help);
-        builder.setPositiveButton(R.string.button_ok, null);
-        builder.show();
+        Intent intent = new Intent(Intent.ACTION_VIEW);
+        intent.setClassName(this, HelpActivity.class.getName());
+        startActivity(intent);
        break;
      }
      case ABOUT_ID: {
@ -366,6 +368,28 @@ public final class CaptureActivity extends Activity implements SurfaceHolder.Cal
    mHandler.sendMessageDelayed(message, INTENT_RESULT_DURATION);
  }

+  /**
+   * We want the help screen to be shown automatically the first time a new version of the app is
+   * run. The easiest way to do this is to check android:versionCode from the manifest, and compare
+   * it to a value stored as a preference.
+   */
+  private void showHelpOnFirstLaunch() {
+    try {
+      PackageInfo info = getPackageManager().getPackageInfo(PACKAGE_NAME, 0);
+      int currentVersion = info.versionCode;
+      SharedPreferences prefs = PreferenceManager.getDefaultSharedPreferences(this);
+      int lastVersion = prefs.getInt(PreferencesActivity.KEY_HELP_VERSION_SHOWN, 0);
+      if (currentVersion > lastVersion) {
+        prefs.edit().putInt(PreferencesActivity.KEY_HELP_VERSION_SHOWN, currentVersion).commit();
+        Intent intent = new Intent(Intent.ACTION_VIEW);
+        intent.setClassName(this, HelpActivity.class.getName());
+        startActivity(intent);
+      }
+    } catch (PackageManager.NameNotFoundException e) {
+
+    }
+  }
+
  /**
   * Creates the beep MediaPlayer in advance so that the sound can be triggered with the least
   * latency possible.
@ -420,9 +444,13 @@ public final class CaptureActivity extends Activity implements SurfaceHolder.Cal
    mViewfinderView.drawViewfinder();
  }

+  /**
+   * When the beep has finished playing, rewind to queue up another one.
+   */
  private static class BeepListener implements OnCompletionListener {
    public void onCompletion(MediaPlayer mediaPlayer) {
      mediaPlayer.seekTo(0);
    }
  }
+
 }
--- a/android/src/com/google/zxing/client/android/HelpActivity.java
+++ b/android/src/com/google/zxing/client/android/HelpActivity.java
@ -0,0 +1,100 @@
+/*
+ * Copyright 2008 ZXing authors
+ *
+ * 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.
+ */
+
+package com.google.zxing.client.android;
+
+import android.app.Activity;
+import android.os.Bundle;
+import android.view.View;
+import android.view.KeyEvent;
+import android.webkit.WebView;
+import android.webkit.WebViewClient;
+import android.widget.Button;
+
+/**
+ * @author dswitkin@google.com (Daniel Switkin)
+ */
+public final class HelpActivity extends Activity {
+
+  private static final String DEFAULT_URL = "file:///android_asset/html/index.html";
+
+  private WebView mWebView;
+  private Button mBackButton;
+
+  @Override
+  protected void onCreate(Bundle icicle) {
+    super.onCreate(icicle);
+    setContentView(R.layout.help);
+
+    mWebView = (WebView)findViewById(R.id.help_contents);
+    mWebView.setWebViewClient(new HelpClient());
+    if (icicle != null) {
+      mWebView.restoreState(icicle);
+    } else {
+      mWebView.loadUrl(DEFAULT_URL);
+    }
+
+    mBackButton = (Button)findViewById(R.id.back_button);
+    mBackButton.setOnClickListener(mBackListener);
+
+    Button exitButton = (Button)findViewById(R.id.exit_button);
+    exitButton.setOnClickListener(mExitListener);
+  }
+
+  @Override
+  public void onResume() {
+    super.onResume();
+  }
+
+  @Override
+  protected void onSaveInstanceState(Bundle state) {
+    mWebView.saveState(state);
+  }
+
+  @Override
+  public boolean onKeyDown(int keyCode, KeyEvent event) {
+    if (keyCode == KeyEvent.KEYCODE_BACK) {
+      if (mWebView.canGoBack()) {
+        mWebView.goBack();
+        return true;
+      }
+    }
+    return super.onKeyDown(keyCode, event);
+  }
+
+  private final Button.OnClickListener mBackListener = new Button.OnClickListener() {
+    public void onClick(View view) {
+      mWebView.goBack();
+    }
+  };
+
+  private final Button.OnClickListener mExitListener = new Button.OnClickListener() {
+    public void onClick(View view) {
+      finish();
+    }
+  };
+
+  private final class HelpClient extends WebViewClient {
+
+    @Override
+    public void onPageFinished(WebView view, String url) {
+      setTitle(view.getTitle());
+      mBackButton.setEnabled(view.canGoBack());
+    }
+
+  }
+
+}
--- a/android/src/com/google/zxing/client/android/PreferencesActivity.java
+++ b/android/src/com/google/zxing/client/android/PreferencesActivity.java
@ -28,6 +28,7 @@ public final class PreferencesActivity extends android.preference.PreferenceActi
  static final String KEY_DECODE_1D = "preferences_decode_1D";
  static final String KEY_DECODE_QR = "preferences_decode_QR";
  static final String KEY_PLAY_BEEP = "preferences_play_beep";
+  static final String KEY_HELP_VERSION_SHOWN = "preferences_help_version_shown";

  CheckBoxPreference mDecode1D;
  CheckBoxPreference mDecodeQR;