diff options
Diffstat (limited to 'samples/BrowserPlugin/README')
| -rw-r--r-- | samples/BrowserPlugin/README | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/samples/BrowserPlugin/README b/samples/BrowserPlugin/README new file mode 100644 index 000000000..08b04a517 --- /dev/null +++ b/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. |