174 lines
7.1 KiB
Plaintext
174 lines
7.1 KiB
Plaintext
# 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.
|