Home | History | Annotate | only in /development/samples/BrowserPlugin
Up to higher level directory
NameDateSize
Android.mk28-Mar-20121.2K
AndroidManifest.xml28-Mar-20121.3K
jni/28-Mar-2012
MODULE_LICENSE_APACHE228-Mar-20120
NOTICE28-Mar-201210.4K
README28-Mar-20127.4K
res/28-Mar-2012
src/28-Mar-2012

README

      1 # Copyright (C) 2009 The Android Open Source Project
      2 #
      3 # Licensed under the Apache License, Version 2.0 (the "License");
      4 # you may not use this file except in compliance with the License.
      5 # You may obtain a copy of the License at
      6 #
      7 #      http://www.apache.org/licenses/LICENSE-2.0
      8 #
      9 # Unless required by applicable law or agreed to in writing, software
     10 # distributed under the License is distributed on an "AS IS" BASIS,
     11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     12 # See the License for the specific language governing permissions and
     13 # limitations under the License.
     14 #
     15 
     16 ##############################
     17 ######### CONTENTS ###########
     18 A. INTRODUCTION
     19 B. PLUGIN STRUCTURE
     20 C. HOW TO DEPLOY
     21 D. SUB-PLUGINS
     22     1. ANIMATION
     23     2. AUDIO
     24     3. BACKGROUND
     25     4. FORM
     26     5. PAINT
     27 
     28 
     29 ##############################
     30 ## (A) INTRODUCTION ##########
     31 
     32 The sample plugin is intended to give plugin developers a point of reference to
     33 see how an android browser plugin is created and how to use the available APIs.
     34 A plugin is packaged like a standard apk and can be installed either via the 
     35 market or adb.  The sample plugin attempts to exercise as many of the APIs as
     36 possible but unfortunately not all are covered. 
     37 
     38 Trying to have a single plugin demonstrate all possible API interactions on one
     39 screen was not practical. On the other hand we also didn't want a separate
     40 plugin for each interction, as that would result in many separate apk's that
     41 would need to be maintained.  To solve this problem we developed the idea to use
     42 "sub-plugins". With a sub-plugin only one specific feature of the plugin would
     43 be active at a time, but they would all share as much common code as possible.
     44 A detailed description of each sub-plugin and its function can be found in the
     45 sub-plugins section.
     46 
     47 ##############################
     48 ## (B) PLUGIN STRUCTURE ######
     49 
     50 The sample plugin is packaged as one plugin but contains many unique sub-plugins
     51 (e.g. audio and paint).  The package consists of two pieces: (1) Java code
     52 containing the config; (2) C++ shared library containing the brower/plugin
     53 bindings and the sub-plugin classes.  
     54 
     55 ~~~~ (1) JAVA ~~~~~
     56 Android.mk: specifies the name of the APK (SampleBrowserPlugin) as well as which
     57             shared libraries to include.
     58 
     59 AndroidManifest.xml: similar to a standard android manifest file, except that it
     60                      must contain the "uses-permission" and "service"
     61                      elements that are plugin specific. The "service" element
     62                      contains sub-elements that describe the java component of
     63                      the service.
     64 
     65 src/*: location of the java source files.  This contains the SamplePlugin.class
     66        which is the java component of our plugin.  The component must exist and
     67        implement the required interfaces, though simply returning null is valid.
     68 
     69 res/*: location of the static resources (e.g. an icon for the plugin)
     70 
     71 ~~~~ (2) C++ ~~~~~
     72 jni/Android.mk: specifies the build parameters for the shared library that is to
     73                 be included with the apk. The library contains all the bindings
     74                 between the plugin and the browser.
     75 
     76 jni/main.*: this code is the binding point between the plugin and the browser.
     77             It supports all of the functions required for a standard netscape
     78             style plugin as well as all the android specific APIs. The initial
     79             starting point for the plugin is the NP_Initialize function. The
     80             NPP_New function is responsible for reading the input args and
     81             selecting the appropriate sub-plugin to instantiate. Most other
     82             functions either return fixed values or pass their inputs to the
     83             sub-plugin for processing.
     84 
     85 jni/PluginObject.*: The pluginObject provides a convenient container in which to
     86                     store variables (the plugin's state).  This objects two main
     87                     responsibilities are (1) to construct and store the NPClass 
     88                     object (done using code provided by Apple) and (2) provide
     89                     the abstract class for the sub-plugin objects and a place to 
     90                     store the sub-plugin after it is instantiated.  
     91 
     92 jni/*/*: Each of the sub-plugins has a folder that contains its class definition
     93          and logic. The sub-plugin receives events from the browser and it can
     94          also communicate with the browser using the netscape plugin functions
     95          as well as the specialized android interfaces.
     96 
     97 
     98 ##############################
     99 ## (C) HOW TO DEPLOY #########
    100 
    101 To compile and install a plugin on a device/emulator simply...
    102 
    103 1. run "make SampleBrowserPlugin" (compiles libsampleplugin.so and builds the apk)
    104 2. the previous command produces an apk file so record its location
    105 3. run "adb install [apk_file]" to install it on a device/emulator
    106 4. the browser will auto recognize the plugin is available
    107 
    108 Now that the plugin is installed you can manage it just like you would any other
    109 application via Settings -> Applications -> Manage applications. To execute the
    110 plugin you need to include an html snippet (similar to the one found below) in
    111 a document that is accessible by the browser.  The mime-type cannot change but
    112 you can change the width, height, and parameters.  The parameters are used to
    113 notify the plugin which sub-plugin to execute and which drawing model to use.
    114 
    115 <object type="application/x-testbrowserplugin" height=50 width=250>
    116     <param name="DrawingModel" value="Surface" />
    117     <param name="PluginType" value="Background" />
    118 </object>
    119 
    120 
    121 ##############################
    122 ## (D) SUB-PLUGINS ###########
    123 
    124 Each sub-plugin corresponds to exactly one plugin type and can support one or
    125 more drawing models. In the subsections below there are descriptions of each of
    126 the sub-plugins as well as the information required to create the html snippets. 
    127 
    128 #######################
    129 ## (D1) ANIMATION #####
    130 
    131 PLUGIN TYPE: Animation
    132 DRAWING MODEL: Bitmap
    133 
    134 This plugin draws a ball bouncing around the screen. If the plugin is not entirely
    135 on the screen and it it touched, then it will attempt to center itself on screen.
    136 
    137 #######################
    138 ## (D2) AUDIO #########
    139 
    140 PLUGIN TYPE: Audio
    141 DRAWING MODEL: Bitmap
    142 
    143 This plugin plays a raw audio file located at /sdcard/sample.raw (need to supply
    144 your own). It uses touch to trigger the play, pause, and stop buttons.
    145 
    146 #######################
    147 ## (D3) BACKGROUND ####
    148 
    149 PLUGIN TYPE: Background
    150 DRAWING MODEL: Surface
    151 
    152 This plugin has minimal visual components but mainly runs API tests in the 
    153 background. The  plugin handles scaling its own bitmap on zoom which in this
    154 case is a simple string of text. The output of this plugin is found in the logs
    155 as it prints errors if it detects any API failures. Some of the API's tested are
    156 timers, javascript access, and bitmap formatting.
    157 
    158 #######################
    159 ## (D4) FORM ##########
    160 
    161 PLUGIN TYPE: Form
    162 DRAWING MODEL: Bitmap
    163 
    164 This plugin mimics a simple username/password form. You can select a textbox by
    165 either touching it or using the navigation keys.  Once selected the box will
    166 highlight and the keyboard will appear. If the textbox selected is not fully
    167 in view then the plugin will ensure it is centered on the screen.  
    168 
    169 #######################
    170 ## (D5) PAINT #########
    171 
    172 PLUGIN TYPE: Paint
    173 DRAWING MODEL: Surface
    174 
    175 This plugin provides a surface that the user can "paint" on.  The inputs method
    176 can be toggled between mouse (dots) and touch (lines).  This plugin has a fixed
    177 surface and allows the browser to scale the surface when zooming. 
    178