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 ###########
18A. INTRODUCTION
19B. PLUGIN STRUCTURE
20C. HOW TO DEPLOY
21D. SUB-PLUGINS
22 1. ANIMATION
23 2. AUDIO
24 3. BACKGROUND
25 4. FORM
26 5. PAINT
27
28
29##############################
30## (A) INTRODUCTION ##########
31
32The sample plugin is intended to give plugin developers a point of reference to
33see how an android browser plugin is created and how to use the available APIs.
34A plugin is packaged like a standard apk and can be installed either via the
35market or adb. The sample plugin attempts to exercise as many of the APIs as
36possible but unfortunately not all are covered.
37
38Trying to have a single plugin demonstrate all possible API interactions on one
39screen was not practical. On the other hand we also didn't want a separate
40plugin for each interction, as that would result in many separate apk's that
41would 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
43be active at a time, but they would all share as much common code as possible.
44A detailed description of each sub-plugin and its function can be found in the
45sub-plugins section.
46
47##############################
48## (B) PLUGIN STRUCTURE ######
49
50The 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
52containing the config; (2) C++ shared library containing the brower/plugin
53bindings and the sub-plugin classes.
54
55~~~~ (1) JAVA ~~~~~
56Android.mk: specifies the name of the APK (SampleBrowserPlugin) as well as which
57 shared libraries to include.
58
59AndroidManifest.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
65src/*: 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
69res/*: location of the static resources (e.g. an icon for the plugin)
70
71~~~~ (2) C++ ~~~~~
72jni/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
76jni/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
85jni/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
92jni/*/*: 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
101To compile and install a plugin on a device/emulator simply...
102
1031. run "make SampleBrowserPlugin" (compiles libsampleplugin.so and builds the apk)
1042. the previous command produces an apk file so record its location
1053. run "adb install [apk_file]" to install it on a device/emulator
1064. the browser will auto recognize the plugin is available
107
108Now that the plugin is installed you can manage it just like you would any other
109application via Settings -> Applications -> Manage applications. To execute the
110plugin you need to include an html snippet (similar to the one found below) in
111a document that is accessible by the browser. The mime-type cannot change but
112you can change the width, height, and parameters. The parameters are used to
113notify 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
124Each sub-plugin corresponds to exactly one plugin type and can support one or
125more drawing models. In the subsections below there are descriptions of each of
126the sub-plugins as well as the information required to create the html snippets.
127
128#######################
129## (D1) ANIMATION #####
130
131PLUGIN TYPE: Animation
132DRAWING MODEL: Bitmap
133
134This plugin draws a ball bouncing around the screen. If the plugin is not entirely
135on the screen and it it touched, then it will attempt to center itself on screen.
136
137#######################
138## (D2) AUDIO #########
139
140PLUGIN TYPE: Audio
141DRAWING MODEL: Bitmap
142
143This plugin plays a raw audio file located at /sdcard/sample.raw (need to supply
144your own). It uses touch to trigger the play, pause, and stop buttons.
145
146#######################
147## (D3) BACKGROUND ####
148
149PLUGIN TYPE: Background
150DRAWING MODEL: Surface
151
152This plugin has minimal visual components but mainly runs API tests in the
153background. The plugin handles scaling its own bitmap on zoom which in this
154case is a simple string of text. The output of this plugin is found in the logs
155as it prints errors if it detects any API failures. Some of the API's tested are
156timers, javascript access, and bitmap formatting.
157
158#######################
159## (D4) FORM ##########
160
161PLUGIN TYPE: Form
162DRAWING MODEL: Bitmap
163
164This plugin mimics a simple username/password form. You can select a textbox by
165either touching it or using the navigation keys. Once selected the box will
166highlight and the keyboard will appear. If the textbox selected is not fully
167in view then the plugin will ensure it is centered on the screen.
168
169#######################
170## (D5) PAINT #########
171
172PLUGIN TYPE: Paint
173DRAWING MODEL: Surface
174
175This plugin provides a surface that the user can "paint" on. The inputs method
176can be toggled between mouse (dots) and touch (lines). This plugin has a fixed
177surface and allows the browser to scale the surface when zooming.
178