libgraphics.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.

\newcommand{\notinfirsted}{
\begin{notice}
Not supported in S60 1st Edition!
\end{notice}

}

\section{\module{graphics} ---
  A graphics related services package}
\label{sec:graphics}

\declaremodule{extension}{graphics}
\platform{S60}
\modulesynopsis{A graphics related services package.}

The \module{graphics} module provides access to the graphics primitives and 
image loading, saving, resizing, and transformation capabilities provided by 
the Symbian OS. 

The module is usable from both graphical Python applications and
background Python processes. However, background processes have some
restrictions, namely that plain string symbolic font names are not
supported in background processes since background processes have no
access to the UI framework (see also Section
\ref{subsubsec:font-specs}).

For an example on using this module, see \cite{PyS60Prog}.

Functions \function{Image.open} and \function{Image.inspect} and \class{Image} 
object methods \method{load}, \method{save}, \method{resize}, and 
\method{transpose} are not available for S60 1st Edition.

\subsection{Module Level Functions}
\label{subsec:mylabel7}
The following free functions - functions that do not belong to any class 
- are defined in the \module{graphics} module:

\begin{funcdesc}{screenshot}{}
Takes a screen shot and returns the image in \class{Image} format.
\end{funcdesc}

\subsection{Image Class Static Methods}
\label{subsec:image}
The following \class{Image} class static methods are defined in the 
\module{graphics} module:

\begin{funcdesc}{Image.new}{size\optional{, mode='RGB16'}}
Creates and returns a new \class{Image} object with the given size and 
mode. \var{size} is a two-element tuple. \var{mode} specifies the 
color mode of the \class{Image} to be created. It can be one of the 
following:

\begin{itemize}
\item \code{'1'}: Black and white (1 bit per pixel)
\item \code{'L'}: 256 gray shades (8 bits per pixel)
\item \code{'RGB12'}: 4096 colors (12 bits per pixel)
\item \code{'RGB16'}: 65536 colors (16 bits per pixel)
\item \code{'RGB'}: 16.7 million colors (24 bits per pixel)
\end{itemize}
\notinfirsted
It will also set the image size in twips according to the density of the device's primary screen. 
\end{funcdesc}

\begin{funcdesc}{Image.open}{filename}
\notinfirsted
Returns a new \class{Image} object (mode \code{RGB16}) that contains the 
contents of the named file. The supported file formats are JPEG and PNG. The 
file format is automatically detected based on file contents. 
\var{filename} should be a full path name.
\end{funcdesc}

\begin{funcdesc}{Image.inspect}{filename}
\notinfirsted
Examines the given file and returns a dictionary of the attributes of the 
file. At present the dictionary contains only the image size in pixels as a 
two-element tuple, indexed by key \code{'size'}. 
\var{filename} should be a full path name.
\end{funcdesc}

\subsection{Image Objects}
\label{subsec:image-objects}
An \class{Image} object encapsulates an in-memory bitmap. 

Note on asynchronous methods: Methods \method{resize}, \method{transpose}, 
\method{save}, and \method{load} have an optional callback argument. If the 
callback is not given, the method call is synchronous; when the method
returns, the operation is complete or an exception has been raised. If
the callback is given, the method calls are asynchronous. If all
parameters are valid and the operation can start, the method call will
return immediately.  The actual computation then proceeds in the
background. When it is finished, the callback is called with an error
code as the argument. If the given code is \code{0}, the operation
completed without errors, otherwise an error occurred.

It is legal to use an unfinished image as a source in a blit operation; this 
will use the image data as it is at the moment the blit is made and may thus 
show an incomplete result.

\class{Image} objects have the following methods:

\begin{methoddesc}[Image]{resize}{newsize\optional{, callback=None, keepaspect=0}}
\notinfirsted
Returns a new image that contains a resized copy of this image. If 
\var{keepaspect} is set to \code{1}, the resize will maintain the 
aspect ratio of the image, otherwise the new image will be exactly the given 
size. 

If \var{callback} is given, the operation is asynchronous, and the 
returned image will be only partially complete until \var{callback} is 
called.
\end{methoddesc}

\begin{methoddesc}[Image]{transpose}{direction\optional{, callback=None}}
\notinfirsted

Creates a new image that contains a transformed copy of this image. The 
\var{direction} parameter can be one of the following:

\begin{itemize}
\item \code{FLIP_LEFT_RIGHT}: Flips the image horizontally, exchanging left and right edges.
\item \code{FLIP_TOP_BOTTOM}: Flips the image vertically, exchanging top and bottom edges.
\item \code{ROTATE_90}: Rotates the image 90 degrees counterclockwise.
\item \code{ROTATE_180}: Rotates the image 180 degrees.
\item \code{ROTATE_270}: Rotates the image 270 degrees counterclockwise.
\end{itemize}

If \var{callback} is given, the operation is asynchronous and the 
returned image will be only partially complete until \var{callback} is 
called.
\end{methoddesc}

\begin{methoddesc}[Image]{load}{filename\optional{, callback=None}}
\notinfirsted
Replaces the contents of this \class{Image} with the contents of the named 
file, while keeping the current image mode. This \class{Image} object must 
be of the same size as the file to be loaded.

If \var{callback} is given, the operation is asynchronous and the loaded 
image will be only partially complete until \var{callback} is called. 
\var{filename} should be a full path name.
\end{methoddesc}

\begin{methoddesc}[Image]{save}{filename\optional{,callback=None, format=None, quality=75, bpp=24, compression='default'}}
\notinfirsted
Saves the image into the given file. The supported formats are JPEG and PNG. 
If \var{format} is not given or is set to \code{None}, the format is 
determined based on the file name extension: \code{'.jpg'} or 
\code{'.jpeg'} are interpreted to be in JPEG format and \code{'.png'} to 
be in PNG format. \var{filename} should be a full path name.

When saving in JPEG format, the \var{quality} argument specifies the 
quality to be used and can range from 1 to 100. 

When saving in PNG format, the \var{bpp} argument specifies how many bits 
per pixel the resulting file should have, and \var{compression} specifies 
the compression level to be used. 

Valid values for \var{bpp} are:

\begin{itemize}
\item \code{1}: Black and white, 1 bit per pixel
\item \code{8}: 256 gray shades, 8 bits per pixel
\item \code{24}: 16.7 million colors, 24 bits per pixel
\end{itemize}

Valid values for \var{compression} are:

\begin{itemize}
\item \code{'best'}: The highest possible compression ratio, the slowest speed
\item \code{'fast'}: The fastest possible saving, moderate compression
\item \code{'no'}: No compression, very large file size
\item \code{'default'}: Default compression, a compromise between file size and speed 
\end{itemize}

If \var{callback} is given, the operation is asynchronous. When the 
saving is complete, the \var{callback} is called with the result code.
\end{methoddesc}


\begin{methoddesc}[Image]{stop}{}
Stops the current asynchronous operation, if any. If an asynchronous call is 
not in progress, this method has no effect.
\end{methoddesc}

\class{Image} objects have the following attributes:

\begin{memberdesc}[Image]{size}
A two-element tuple that contains the size of the \class{Image}. Read-only.
\end{memberdesc}

\begin{memberdesc}[Image]{twipsize}
A two-element tuple that contains the size of the \class{Image} in twips. Read/Write.
\end{memberdesc}

\subsection{Common Features of Drawable Objects}
\label{subsec:common}
Objects that represent a surface that can be drawn on support a set of 
common drawing methods, described in this section. At present there are two 
such objects: \class{Canvas} from the \refmodule{appuifw} module and 
\class{Image} from the \module{graphics} module. 

\subsubsection{Options}
\label{subsubsec:options}
Many of these methods support a set of standard options. This set of options 
is as follows:

\begin{itemize}
\item \var{outline}: The color to be used for drawing outlines of primitives and text. If \code{None}, the outlines of primitives are not drawn.
\item \var{fill}: The color to be used for filling the insides of primitives. If \code{None}, the insides of primitives are not drawn. If \var{pattern} is also specified, \var{fill} specifies the color to be used for areas where the pattern is white.
\item \var{width}: The line width to be used for drawing the outlines of primitives.
\item \var{pattern}: Specifies the pattern to be used for filling the insides of primitives. If given, this must be either \code{None} or a 1-bit (black and white) \class{Image}.
\end{itemize}

\subsubsection{Coordinate representation}
\label{subsubsec:coordinate}
The methods accept an ordered set of coordinates in the form of a coordinate 
sequence. Coordinates can be of type \code{int}, \code{long}, or 
\code{float}. A valid coordinate sequence is a non-empty sequence of 
either