libsensor.tex

python s60 1.4.5版本的源代码

% Copyright (c) 2005-2007 Nokia Corporation
%
% 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.

\section{\module{sensor} ---
  Module to access the device sensors.}
\label{sec:sensor}

\declaremodule{extension}{sensor}
\platform{S60}
\modulesynopsis{Module to access the device sensors.}

The \module{sensor} module offers direct access to a device's physical sensors. It has been tested
with
\begin{itemize}
\item acceleration sensor: raises events about the 3-axes acceleration of the device
\item tapping sensor: raises an event when the device was tapped twice on the front side
\item rotation sensor: raises an event based on the orientation of the device.
\end{itemize}

Instead of just passing on raised events, event filtering is also supported. Two 
examples of using an event filter are also provided by the \module{sensor} 
module, namely the class \class{OrientationEventFilter} and 
\class{RotEventFilter}. Both filters can be used to raise events when the 
device's orientation changes (e.g. when it's turned to the right). The support 
is device dependent, e.g. Nokia 5500 supports \class{OrientationEventFilter} and 
Nokia N95 supports \class{RotEventFilter}.

\begin{notice}[note]
The module \module{sensor} is available from S60 3rd Edition onwards 
(inclusive).
\end{notice}

\subsection{Module Level Functions}
\label{subsec:sensormodule}
On the module level, \module{sensor} provides the following functions:

\begin{funcdesc}{sensors}{}

Returns a dictionary containing all available sensors. The dictionary's format is
\begin{verbatim}
{
  { 'sensor name 1': { 'id': sensor_id_1, 'category': category_id_1 } },
  { 'sensor name 2': { 'id': sensor_id_2, 'category': category_id_2 } },
  ...
}
\end{verbatim}

with \code{sensor_id_X} and \code{category_id_X} being integer values.

\end{funcdesc}


\subsection{Constants}
\label{subsec:sensorconstants}
The following \code{orientation} constants are used by the \class{OrientationEventFilter} class.
Callbacks which have been connected to a \class{Sensor} object that utilises the
\class{OrientationEventFilter} event filter will receive one of these constants as an argument
upon a detected orientation change. The constants' names are the side of the device that
is currently turned upwards from the user's point of view. (For example \code{FRONT} means that
the device is lying on its back - its front side is turned upwards.)

\begin{memberdesc}{orientation.TOP}
Represents the orientation where the device is held upwards.
\end{memberdesc}
\begin{memberdesc}{orientation.BOTTOM}
Represents the orientation where the device is held upside down.
\end{memberdesc}
\begin{memberdesc}{orientation.LEFT}
Represents the orientation where the side of the device that is left of the display is turned downwards.
\end{memberdesc}
\begin{memberdesc}{orientation.RIGHT}
Represents the orientation where the side of the device that is right of the display is turned downwards.
\end{memberdesc}
\begin{memberdesc}{orientation.FRONT}
Represents the orientation where the device is lying on its back, i.e. the front side points upwards.
\end{memberdesc}
\begin{memberdesc}{orientation.BACK}
Represents the orientation where the device is lying on its front, i.e. the back side points upwards.
\end{memberdesc}


\subsection{Classes}
\label{subsec:sensorclasses}
The following classes are provided by the \module{sensor} module:

\begin{classdesc*}{Sensor}

The \class{Sensor} class represents a physical sensor which delivers (possibly filtered) events.
By default, events are not filtered. A filter can be applied by using the \method{set_event_filter}
method. An example for an event filter is given by \class{OrientationEventFilter}, which can
be applied to a device's acceleration sensor.

In case different filters should be used for the same physical sensor, different \class{Sensor}
objects have to be created for the same physical sensor.

\begin{methoddesc}[Sensor]{__init__}{sensor_id, category_id}
Initialises the \class{Sensor} object. \code{sensor_id} and \code{category_id}
must represent a valid sensor id and category id, respectively. This means that
the ids passed on to \code{__init__} must also appear in the dictionary returned by
the \code{sensors} function.
In case \code{sensor_id} and \code{category_id} do not represent a valid sensor,
the \code{connect} method will raise an exception.
\end{methoddesc}

\begin{methoddesc}[Sensor]{connect}{callback}
This method connects the sensor to the given \code{callback}. A sensor can only be connected
to one callback, so this will destroy any pre-existing connection to another callback.
If an event filter has been set, the events passed on to \code{callback} will pass
this \class{Sensor} object's event filter first.
If the connection was properly established, this method returns 1, otherwise 0.
Note: The connection can be established also if the callback does not exist or cannot be
called for any other reason.
\end{methoddesc}

\begin{methoddesc}[Sensor]{disconnect}{}
Disconnects this \class{Sensor} object's callback connection. After a successful call
to this method, a callback that has been previously connected via \method{connect} will
not receive any events anymore.
If a connection existed and was successfully removed, this method returns 1, otherwise 0.
\end{methoddesc}

\begin{methoddesc}[Sensor]{connected}{}
Retrieves this \class{Sensor} object's connection status.
Returns \code{True} if the sensor is connected, \code{False} otherwise.
\end{methoddesc}

\begin{methoddesc}[Sensor]{set_event_filter}{event_filter}
Sets an event filter for this \class{Sensor} object. After the event filter has been
successfully installed, this \class{Sensor} object's connected callback will
receive only events that have passed the filter. \code{event_filter} must be derived
from \class{EventFilter} in order to function properly.
If a callback connection has already been established before calling this method,
the connection will be re-established after the event filter has been installed.
\end{methoddesc}

\end{classdesc*}

\begin{classdesc*}{EventFilter}

The \class{EventFilter} class provides a generic interface for event filters.
The default implementation only passes events on, i.e. events are not filtered.
Classes deriving from \class{EventFilter} can decide if an event should be
delivered at all as well as they can alter the data that is passed on to
the callback.

\begin{memberdesc}[EventFilter]{callback}
This is where the event filter's callback is stored. In case the \class{EventFilter}
object is used together with a \class{Sensor} object, the \class{Sensor} object will
handle correct setting of this variable.
\end{memberdesc}

\begin{methoddesc}[EventFilter]{__init__}{}
Initialises the event filter object. The \code{callback} member is initialised to
\code{None}.
\end{methoddesc}

\begin{methoddesc}[EventFilter]{__del__}{}
Destructs the event filter object. This method calls \method{cleanup},
which can be overridden by deriving classes to clean up resources.
\end{methoddesc}

\begin{methoddesc}[EventFilter]{event}{data}
This method is the place where event filtering takes place, and hence
this method should be overridden by deriving classes. Overridden \method{event}
methods can deliver their own data to the callback; the data delivered may be
\code{data} or any other set of data.
In case the event is decided to be delivered, overriding instances should
call \code{self.callback}, which by default takes one argument.
\end{methoddesc}

\begin{methoddesc}[EventFilter]{cleanup}{}
Cleans up any resources needed by the event filter. The default implementation
does not need this feature.
This method is called by the destructor \method{__del__}.
\end{methoddesc}

\end{classdesc*}

\begin{classdesc*}{OrientationEventFilter}

Derived from \class{EventFilter}.
This event filter is meant to be used together with the device's acceleration
sensors. Note that it does not make sense to use it with any other sensor
type. It generates events when the devices orientation changes, e.g. if it
is turned from the upright position to lying on the back side.
If an \class{OrientationEventFiler} is used with a \class{Sensor} object,
the \class{Sensor} object's callback will not receive the raw acceleration data
as an argument, but only one of the \code{orientation} constants, representing
the device's new orientation. In case the algorithm needs calibration on the
device to be used, please check the \code{OrientationCalibration} variables
in the file \code{sensor.py}.

\begin{methoddesc}[OrientationEventFilter]{__init__}{}
Initialises the \class{OrientationEventFilter} object.
\end{methoddesc}

\begin{methoddesc}[OrientationEventFilter]{event}{sensor_val}
Overridden method. Filters 3-axis acceleration events such that
it detects orientation changes. Only upon detection of such an orientation
change, the callback is invoked. The argument passed to the callback is a
value from this module's \code{orientation} constants.
\end{methoddesc}

\begin{methoddesc}[OrientationEventFilter]{cleanup}{}
Cleans up this filter's timer resource. This will be called by \class{EventFilter}'s
destructor.
\end{methoddesc}

\end{classdesc*}

\begin{classdesc*}{RotEventFilter}

Derived from \class{EventFilter}.

This event filter generates events when the devices orientation changes, e.g. if 
it is turned from the left side up position to right side up position. This 
sensor is resident e.g. in Nokia N95.

\begin{methoddesc}[OrientationEventFilter]{event}{sensor_val}
Overridden method. Upon detection of an orientation change, the callback is 
invoked. The argument passed to the callback is a value from this module's 
\code{orientation} constants.
\end{methoddesc}

\end{classdesc*}