adding README to sample plugins and cleaning up the animation plugin.

samples/BrowserPlugin/README

@@ -0,0 +1,173 @@
+# Copyright (C) 2009 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.
+#
+
+##############################
+######### CONTENTS ###########
+A. INTRODUCTION
+B. PLUGIN STRUCTURE
+C. HOW TO DEPLOY
+D. SUB-PLUGINS
+    1. ANIMATION
+    2. AUDIO
+    3. BACKGROUND
+    4. FORM
+    5. PAINT
+
+
+##############################
+## (A) INTRODUCTION ##########
+
+The sample plugin is intended to give plugin developers a point of reference to
+see how an android browser plugin is created and how to use the available APIs.
+A plugin is packaged like a standard apk and can be installed either via the 
+market or adb.  The sample plugin attempts to exercise as many of the APIs as
+possible but unfortunately not all are covered. 
+
+Trying to have a single plugin demonstrate all possible API interactions on one
+screen was not practical. On the other hand we also didn't want a separate
+plugin for each interction, as that would result in many separate apk's that
+would need to be maintained.  To solve this problem we developed the idea to use
+"sub-plugins". With a sub-plugin only one specific feature of the plugin would
+be active at a time, but they would all share as much common code as possible.
+A detailed description of each sub-plugin and its function can be found in the
+sub-plugins section.
+
+##############################
+## (B) PLUGIN STRUCTURE ######
+
+The sample plugin is packaged as one plugin but contains many unique sub-plugins
+(e.g. audio and paint).  The package consists of two pieces: (1) Java code
+containing the config; (2) C++ shared library containing the brower/plugin
+bindings and the sub-plugin classes.  
+
+~~~~ (1) JAVA ~~~~~
+Android.mk: specifies the name of the APK (SampleBrowserPlugin) as well as which
+            shared libraries to include.
+
+AndroidManifest.xml: similar to a standard android manifest file, except that it
+                     must contain the "uses-permission" and "intent-filter"
+                     elements that are plugin specific.
+
+src/*: location of the java files which in our case is just an empty service
+
+res/*: location of the static resources (e.g. an icon for the plugin)
+
+~~~~ (2) C++ ~~~~~
+jni/Android.mk: specifies the build parameters for the shared library that is to
+                be included with the apk. The library contains all the bindings
+                between the plugin and the browser.
+
+jni/main.*: this code is the binding point between the plugin and the browser.
+            It supports all of the functions required for a standard netscape
+            style plugin as well as all the android specific APIs. The initial
+            starting point for the plugin is the NP_Initialize function. The
+            NPP_New function is responsible for reading the input args and
+            selecting the appropriate sub-plugin to instantiate. Most other
+            functions either return fixed values or pass their inputs to the
+            sub-plugin for processing.
+
+jni/PluginObject.*: The pluginObject provides a convenient container in which to
+                    store variables (the plugin's state).  This objects two main
+                    responsibilities are (1) to construct and store the NPClass 
+                    object (done using code provided by Apple) and (2) provide
+                    the abstract class for the sub-plugin objects and a place to 
+                    store the sub-plugin after it is instantiated.  
+
+jni/*/*: Each of the sub-plugins has a folder that contains its class definition
+         and logic. The sub-plugin receives events from the browser and it can
+         also communicate with the browser using the netscape plugin functions
+         as well as the specialized android interfaces.
+
+
+##############################
+## (C) HOW TO DEPLOY #########
+
+To compile and install a plugin on a device/emulator simply...
+
+1. run "make SampleBrowserPlugin" (compiles libsampleplugin.so and builds the apk)
+2. the previous command produces an apk file so record its location
+3. run "adb install [apk_file]" to install it on a device/emulator
+4. the browser will auto recognize the plugin is available
+
+Now that the plugin is installed you can manage it just like you would any other
+application via Settings -> Applications -> Manage applications. To execute the
+plugin you need to include an html snippet (similar to the one found below) in
+a document that is accessible by the browser.  The mime-type cannot change but
+you can change the width, height, and parameters.  The parameters are used to
+notify the plugin which sub-plugin to execute and which drawing model to use.
+
+<object type="application/x-testbrowserplugin" height=50 width=250>
+    <param name="DrawingModel" value="Surface" />
+    <param name="PluginType" value="Background" />
+</object>
+
+
+##############################
+## (D) SUB-PLUGINS ###########
+
+Each sub-plugin corresponds to exactly one plugin type and can support one or
+more drawing models. In the subsections below there are descriptions of each of
+the sub-plugins as well as the information required to create the html snippets. 
+
+#######################
+## (D1) ANIMATION #####
+
+PLUGIN TYPE: Animation
+DRAWING MODEL: Bitmap
+
+This plugin draws a ball bouncing around the screen. If the plugin is not entirely
+on the screen and it it touched, then it will attempt to center itself on screen.
+
+#######################
+## (D2) AUDIO #########
+
+PLUGIN TYPE: Audio
+DRAWING MODEL: Bitmap
+
+This plugin plays a raw audio file located at /sdcard/sample.raw (need to supply
+your own). It uses touch to trigger the play, pause, and stop buttons.
+
+#######################
+## (D3) BACKGROUND ####
+
+PLUGIN TYPE: Background
+DRAWING MODEL: Surface
+
+This plugin has minimal visual components but mainly runs API tests in the 
+background. The  plugin handles scaling its own bitmap on zoom which in this
+case is a simple string of text. The output of this plugin is found in the logs
+as it prints errors if it detects any API failures. Some of the API's tested are
+timers, javascript access, and bitmap formatting.
+
+#######################
+## (D4) FORM ##########
+
+PLUGIN TYPE: Form
+DRAWING MODEL: Bitmap
+
+This plugin mimics a simple username/password form. You can select a textbox by
+either touching it or using the navigation keys.  Once selected the box will
+highlight and the keyboard will appear. If the textbox selected is not fully
+in view then the plugin will ensure it is centered on the screen.  
+
+#######################
+## (D5) PAINT #########
+
+PLUGIN TYPE: Paint
+DRAWING MODEL: Surface
+
+This plugin provides a surface that the user can "paint" on.  The inputs method
+can be toggled between mouse (dots) and touch (lines).  This plugin has a fixed
+surface and allows the browser to scale the surface when zooming. 

samples/BrowserPlugin/jni/animation/AnimationPlugin.cpp

@@ -25,9 +25,6 @@
 
 #include "AnimationPlugin.h"
 
-#include <stdio.h>
-#include <sys/time.h>
-#include <time.h>
 #include <math.h>
 #include <string.h>
 
@@ -36,13 +33,8 @@ extern ANPLogInterfaceV0       gLogI;
 extern ANPCanvasInterfaceV0    gCanvasI;
 extern ANPPaintInterfaceV0     gPaintI;
 extern ANPPathInterfaceV0      gPathI;
-extern ANPTypefaceInterfaceV0  gTypefaceI;
 extern ANPWindowInterfaceV0    gWindowI;
 
-static void inval(NPP instance) {
-    browser->invalidaterect(instance, NULL);
-}
-
 static uint16 rnd16(float x, int inset) {
     int ix = (int)roundf(x) + inset;
     if (ix < 0) {
@@ -54,7 +46,6 @@ static uint16 rnd16(float x, int inset) {
 static void inval(NPP instance, const ANPRectF& r, bool doAA) {
     const int inset = doAA ? -1 : 0;
 
-    PluginObject *obj = reinterpret_cast<PluginObject*>(instance->pdata);
     NPRect inval;
     inval.left = rnd16(r.left, inset);
     inval.top = rnd16(r.top, inset);
@@ -63,42 +54,6 @@ static void inval(NPP instance, const ANPRectF& r, bool doAA) {
     browser->invalidaterect(instance, &inval);
 }
 
-uint32_t getMSecs() {
-    struct timeval tv;
-    gettimeofday(&tv, NULL);
-    return (uint32_t) (tv.tv_sec * 1000 + tv.tv_usec / 1000 ); // microseconds to milliseconds
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-BallAnimation::BallAnimation(NPP inst) : SubPlugin(inst) {
-    m_x = m_y = 0;
-    m_dx = 7 * SCALE;
-    m_dy = 5 * SCALE;
-
-    memset(&m_oval, 0, sizeof(m_oval));
-
-    m_paint = gPaintI.newPaint();
-    gPaintI.setFlags(m_paint, gPaintI.getFlags(m_paint) | kAntiAlias_ANPPaintFlag);
-    gPaintI.setColor(m_paint, 0xFFFF0000);
-    gPaintI.setTextSize(m_paint, 24);
-
-    ANPTypeface* tf = gTypefaceI.createFromName("serif", kItalic_ANPTypefaceStyle);
-    gPaintI.setTypeface(m_paint, tf);
-    gTypefaceI.unref(tf);
-
-    //register for key and touch events
-    ANPEventFlags flags = kKey_ANPEventFlag | kTouch_ANPEventFlag;
-    NPError err = browser->setvalue(inst, kAcceptEvents_ANPSetValue, &flags);
-    if (err != NPERR_NO_ERROR) {
-        gLogI.log(inst, kError_ANPLogType, "Error selecting input events.");
-    }
-}
-
-BallAnimation::~BallAnimation() {
-    gPaintI.deletePaint(m_paint);
-}
-
 static void bounce(float* x, float* dx, const float max) {
     *x += *dx;
     if (*x < 0) {
@@ -113,14 +68,41 @@ static void bounce(float* x, float* dx, const float max) {
         }
     }
 }
+///////////////////////////////////////////////////////////////////////////////
+
+BallAnimation::BallAnimation(NPP inst) : SubPlugin(inst) {
+    m_x = m_y = 0;
+    m_dx = 7 * SCALE;
+    m_dy = 5 * SCALE;
+
+    memset(&m_oval, 0, sizeof(m_oval));
+
+    m_paint = gPaintI.newPaint();
+    gPaintI.setFlags(m_paint, gPaintI.getFlags(m_paint) | kAntiAlias_ANPPaintFlag);
+    gPaintI.setColor(m_paint, 0xFFFF0000);
+
+    //register for touch events
+    ANPEventFlags flags = kTouch_ANPEventFlag;
+    NPError err = browser->setvalue(inst, kAcceptEvents_ANPSetValue, &flags);
+    if (err != NPERR_NO_ERROR) {
+        gLogI.log(inst, kError_ANPLogType, "Error selecting input events.");
+    }
+}
+
+BallAnimation::~BallAnimation() {
+    gPaintI.deletePaint(m_paint);
+}
 
 bool BallAnimation::supportsDrawingModel(ANPDrawingModel model) {
     return (model == kBitmap_ANPDrawingModel);
 }
 
 void BallAnimation::drawPlugin(const ANPBitmap& bitmap, const ANPRectI& clip) {
+
+    // create a canvas
     ANPCanvas* canvas = gCanvasI.newCanvas(&bitmap);
 
+    // clip the canvas
     ANPRectF clipR;
     clipR.left = clip.left;
     clipR.top = clip.top;
@@ -128,28 +110,15 @@ void BallAnimation::drawPlugin(const ANPBitmap& bitmap, const ANPRectI& clip) {
     clipR.bottom = clip.bottom;
     gCanvasI.clipRect(canvas, &clipR);
 
-    draw(canvas);
+    // setup variables
-    gCanvasI.deleteCanvas(canvas);
+    PluginObject *obj = (PluginObject*) inst()->pdata;
-}
-
-void BallAnimation::draw(ANPCanvas* canvas) {
-    NPP instance = this->inst();
-    PluginObject *obj = (PluginObject*) instance->pdata;
     const float OW = 20;
     const float OH = 20;
     const int W = obj->window->width;
     const int H = obj->window->height;
 
-    inval(instance, m_oval, true);  // inval the old
+    // paint the canvas (using the path API)
-    m_oval.left = m_x;
-    m_oval.top = m_y;
-    m_oval.right = m_x + OW;
-    m_oval.bottom = m_y + OH;
-    inval(instance, m_oval, true);  // inval the new
-
     gCanvasI.drawColor(canvas, 0xFFFFFFFF);
-
-    // test out the Path API
     {
         ANPPath* path = gPathI.newPath();
 
@@ -167,28 +136,25 @@ void BallAnimation::draw(ANPCanvas* canvas) {
         ANPRectF bounds;
         memset(&bounds, 0, sizeof(bounds));
         gPathI.getBounds(path, &bounds);
-#if 0
-        gLogI.log(instance, kDebug_ANPLogType, "drawpath: center %g %g bounds [%g %g %g %g]\n",
-                  cx, cy,
-                  bounds.left, bounds.top, bounds.right, bounds.bottom);
-#endif
         gPathI.deletePath(path);
     }
 
+    // draw the oval
+    inval(inst(), m_oval, true);  // inval the old
+    m_oval.left = m_x;
+    m_oval.top = m_y;
+    m_oval.right = m_x + OW;
+    m_oval.bottom = m_y + OH;
+    inval(inst(), m_oval, true);  // inval the new
     gPaintI.setColor(m_paint, 0xFFFF0000);
     gCanvasI.drawOval(canvas, &m_oval, m_paint);
 
+    // update the coordinates of the oval
     bounce(&m_x, &m_dx, obj->window->width - OW);
     bounce(&m_y, &m_dy, obj->window->height - OH);
 
-    if (mUnichar) {
+    // delete the canvas
-        ANPFontMetrics fm;
+    gCanvasI.deleteCanvas(canvas);
-        gPaintI.getFontMetrics(m_paint, &fm);
-
-        gPaintI.setColor(m_paint, 0xFF0000FF);
-        char c = static_cast<char>(mUnichar);
-        gCanvasI.drawText(canvas, &c, 1, 10, -fm.fTop, m_paint);
-    }
 }
 
 void BallAnimation::showEntirePluginOnScreen() {
@@ -219,14 +185,6 @@ int16 BallAnimation::handleEvent(const ANPEvent* evt) {
                 default:
                     break;   // unknown drawing model
             }
-
-        case kKey_ANPEventType:
-            if (evt->data.key.action == kDown_ANPKeyAction) {
-                mUnichar = evt->data.key.unichar;
-                gLogI.log(instance, kDebug_ANPLogType, "ball downkey event");
-                browser->invalidaterect(instance, NULL);
-            }
-            return 1;
         case kTouch_ANPEventType:
              if (kDown_ANPTouchAction == evt->data.touch.action) {
                  showEntirePluginOnScreen();

samples/BrowserPlugin/jni/animation/AnimationPlugin.h

@@ -35,7 +35,6 @@ public:
     virtual bool supportsDrawingModel(ANPDrawingModel);
     virtual int16 handleEvent(const ANPEvent* evt);
 private:
-    void draw(ANPCanvas*);
     void drawPlugin(const ANPBitmap& bitmap, const ANPRectI& clip);
     void showEntirePluginOnScreen();
 
@@ -44,14 +43,10 @@ private:
     float m_dx;
     float m_dy;
 
-    int32_t mUnichar;
-
     ANPRectF    m_oval;
     ANPPaint*   m_paint;
 
     static const float SCALE = 0.1;
 };
 
-uint32_t getMSecs();
-
 #endif // pluginGraphics__DEFINED

samples/BrowserPlugin/jni/background/BackgroundPlugin.cpp

@@ -40,11 +40,13 @@ extern ANPPaintInterfaceV0     gPaintI;
 extern ANPSurfaceInterfaceV0   gSurfaceI;
 extern ANPTypefaceInterfaceV0  gTypefaceI;
 
-extern uint32_t getMSecs();
-
 #define ARRAY_COUNT(array)      (sizeof(array) / sizeof(array[0]))
 
-//#define LOG_ERROR(inst, string, params...) gLogI.log(inst, kError_ANPLogType, (log_prefix + string), inst, params)
+static uint32_t getMSecs() {
+    struct timeval tv;
+    gettimeofday(&tv, NULL);
+    return (uint32_t) (tv.tv_sec * 1000 + tv.tv_usec / 1000 ); // microseconds to milliseconds
+}
 
 ///////////////////////////////////////////////////////////////////////////////