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

\newlength{\screenwidth}
\setlength{\screenwidth}{0.3\textwidth}
\label{sec:appuifw}

\section{\module{appuifw} ---
	 Interface to the S60 GUI framework}

\declaremodule{standard}{appuifw}
\platform{S60}
\modulesynopsis{Interface to the S60 GUI framework}

The \module{appuifw} module offers an interface to the S60 UI application
framework. \figurename~\ref{fig:ui-overview} provides an overview of
the Python for S60 environment for UI application programming.

\note{The services of this interface may only be used in the context of 
the main thread, that is, the initial thread of a UI application script.}

\begin{figure}
\centering
\includegraphics[width=\textwidth]{ui-overview}
\caption{Python for S60 UI environment overview}
\label{fig:ui-overview}
\end{figure}

\subsection{Basics of appuifw Module}
\label{subsec:basics}
Figure \ref{fig:normal-uilayout} shows the layout of a S60 application 
UI in the normal screen mode and a summary of how it relates to the services 
available at the \module{appuifw} API. For alternative layouts, see 
Figure \ref{fig:alternate-uilayouts}.

\begin{figure}
\centering
%\includegraphics[width=0.7\textwidth]{screen-parts}
\includegraphics{screen-parts}
\caption{The different parts of the screen when using the 'normal' layout}
\label{fig:normal-uilayout}
\end{figure}

\begin{figure}
\centering
\includegraphics[width=\screenwidth]{layout-normal}
\includegraphics[width=\screenwidth]{layout-large}
\includegraphics[width=\screenwidth]{layout-full}
\caption{UI layouts. left: 'normal', middle: 'large', right: 'full'}
\label{fig:alternate-uilayouts}
\end{figure}

The main application window may be set up to be occupied by a UI control.

A multi-view application can show the different views as tabs in the 
navigation pane and react as the users navigate between tabs. 

Dialogs always take precedence over the usual UI controls and appear on top 
of them.

UI controls are implemented as Python types. These types are available:

\begin{itemize}
\item \class{Text}
\item \class{Listbox}
\item \class{Canvas}
\end{itemize}
UI controls appear on the screen as soon as an instance of the corresponding 
Python type is set to the body field (\var{app.body}) of the current application UI.

\class{Form} is a versatile dialog implemented as a type.

The \class{Content_handler} type facilitates interfacing to other UI
applications and common high-level UI components. It is based on the
notion that designated handlers can reduce UI application interaction
to operations on MIME-type content.

The following dialogs are implemented as functions:

\begin{itemize}
\item \function{note}
\item \function{query}
\item \function{multi_query}
\item \function{selection_list}
\item \function{multi_selection_list}
\item \function{popup_menu}
\end{itemize}
A dialog becomes visible as soon as the corresponding Python function has 
been called. The function returns with the eventual user input or 
information on the cancellation of the dialog. \class{Form} is an 
exception; it is shown when its \method{execute} method is called.

\subsection{Softkeys}
\label{subsec:softkeys}
The softkeys are managed by the underlying S60 Platform. When no
dialog is visible, the right softkey is bound to application exit and
the left one represents an Options menu. Python for S60 offers
an interface for manipulating the menu and for binding the Exit key to
a Python-callable object (see Section \ref{subsec:application}). 

The native code that implements a dialog also manages the softkeys of the 
dialog, typically OK and Cancel. When the user input needs to be validated 
before accepting it and dismissing the dialog, it is best to use 
\class{Form}.

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

\begin{funcdesc}{available_fonts}{}
Returns a list (Unicode) of all fonts available in the device.
\end{funcdesc}

\begin{funcdesc}{query}{label, type\optional{, initial_value}}
Performs a query with a single-field dialog. The prompt is set to 
\var{label}, and the type of the dialog is defined by \var{type}. The 
value of \var{type} can be any of the following strings:

\begin{itemize}
\item \code{'text'}
\item \code{'code'}
\item \code{'number'}
\item \code{'date'}
\item \code{'time'}
\item \code{'query'}
\item \code{'float'}
\end{itemize}

The type of the optional \var{initial_value} parameter and the 
returned input depend on the value of \var{type}:

\begin{itemize}
\item For text fields, (\code{'text'}, \code{'code'}) it is Unicode
\item For number fields, it is numeric
\item For date fields, it is seconds since epoch rounded down to the nearest local midnight
\end{itemize}

A simple confirmation query and time query take no initial value and return 
\code{True/None} and seconds since local midnight, correspondingly. All 
queries return \code{None} if the users cancel the dialog. 

For \code{'float'} query the \var{initial_value} setting has no 
effect.
\end{funcdesc}


\begin{funcdesc}{multi_query}{label_1, label_2}
A two-field text (Unicode) input dialog. Returns the inputted values
as a 2-tuple. Returns \code{None} if the users cancel the dialog.
\end{funcdesc}

\begin{funcdesc}{note}{text\optional{, type\optional{, global}}}
Displays a note dialog of the chosen type with \var{text} 
(Unicode). The default value for \var{type} is \code{'info'}, which is 
automatically used if \var{type} is not set. \var{type} can be one of 
the following strings: \code{'error'}, \code{'info'}, or 
\code{'conf'}. 

If \var{global} (integer) is any other value than zero a global note is 
displayed. A global note is displayed even if the Python application calling 
this function is in background. The same set of \var{type}s is supported as in 
standard note.
\end{funcdesc}

\begin{funcdesc}{popup_menu}{list\optional{, label}}
A pop-up menu style dialog. \var{list} representing the menu 
contents can be a list of Unicode strings or a list of Unicode string pairs 
(tuples). The resulting dialog list is then a single-style or a double-style 
list. A single-style list is shown in full; whereas a double-style list 
shows the items one at a time. Returns \code{None} if the user cancels the 
operation.
\end{funcdesc}

\begin{funcdesc}{selection_list}{choices\optional{, search_field=0}}
Executes a dialog that allows the users to select a list item and
returns the \var{index} of the chosen item, or \code{None} if the
selection is cancelled by the users. \var{choices} is a list of
Unicode strings.
\var{search_field} is \code{0} (disabled) by default and is optional. Setting it to \code{1} enables a search field (find pane) that facilitates searching for items in long lists. If enabled, the search field appears after you press a letter key.
\end{funcdesc}

\begin{funcdesc}{multi_selection_list}{choices\optional{, style='checkbox', search_field=0}}
  Executes a dialog that allows the users to select multiple list
  items.  Returns a tuple of indexes (a pair of Unicode strings) of
  the chosen items, or empty tuple if the selection is cancelled by
  the users. \var{choices} is a list of Unicode strings.  \var{style}
  is an optional string; the default value being \code{'checkbox'}.
  If \code{'checkbox'} is given, the list will be a checkbox list,
  where empty checkboxes indicate what items can be marked. The other
  possible value that can be set for \var{style} is
  \code{'checkmark'}. If \code{'checkmark'} is given, the list will be
  a markable list, which lists items but does not indicate
  specifically that items can be selected. To select items on a
  markable list, use the Navigation key to browse the list and the
  Edit key to select an item. For example views on checkbox and
  markable lists, see
  \figurename~\ref{fig:checkbox-and-markable-list}.
  \var{search_field} is \code{0} (disabled) by default and is
  optional. Setting it to \code{1} enables a search field (find pane)
  that facilitates searching for items in long lists. If enabled, the
  search field is always visible with checkbox lists; with markable
  lists it appears by pressing a letter key.

Example:
\begin{verbatim}
tuple = appuifw.multi_selection_list(L, style='checkmark', search_field=1)
\end{verbatim}
\end{funcdesc}

\begin{figure}[htbp]
\centering
\includegraphics[width=\screenwidth]{checkbox-list}
\includegraphics[width=\screenwidth]{markable-list}
\caption{Examples of a checkbox list (left) and a markable list (right)}
\label{fig:checkbox-and-markable-list}
\end{figure}

\subsection{Application Type}
\label{subsec:application}
A single implicit instance of this type always exists when \module{appuifw} 
module is present and can be referred to with the name \code{app}. New 
instances cannot be created by a Python program.

\begin{classdesc*}{Application}
Instances of \class{Application} type have the following attributes:

\begin{memberdesc}[Application]{body}
The UI control that is visible in the application's main window. Currently 
either \class{Text}, a \class{Listbox} object, \class{Canvas}, or 
\code{None}.
\end{memberdesc}

\begin{memberdesc}[Application]{exit_key_handler}
A callable object that is called when the user presses the Exit softkey. 
Setting \member{exit_key_handler} to \code{None} sets it back to the 
default value.
\end{memberdesc}

\begin{memberdesc}[Application]{menu}
This is a list of the following kinds of items:
\begin{itemize}
\item \code{(title, callback)} which creates a regular menu item
\item \code{(title, ((title, callback)\optional{...}))} which creates a submenu
\end{itemize}

\var{title} (Unicode) is the name of the item and \var{callback} the associated callable object. 
The maximum allowed number of items in a menu, or items in a submenu,
or submenus in a menu is 30.

Example:
\begin{verbatim}
appuifw.app.menu = [(u"Item 1", item1),
                    (u"Submenu 1", 
                        ((u"Subitem 1", subitem1),
                         (u"Subitem 2", subitem2)))]
\end{verbatim}
\end{memberdesc}

\begin{memberdesc}[Application]{screen}
The screen area used by an application. See \figurename~\ref{fig:alternate-uilayouts} for
example screens. The appearance of the application on the screen can
be affected by setting one of the following values: \code{'normal'},
\code{'large'}, and \code{'full'}.

Examples:
\begin{verbatim}
appuifw.app.screen='normal' # (a normal screen with title pane and softkeys)
appuifw.app.screen='large'  # (only softkeys visible)
appuifw.app.screen='full'   # (a full screen)
\end{verbatim}
\end{memberdesc}

\begin{memberdesc}[Application]{title}
The title the application that is visible in the application's title
pane. Must be Unicode.
\end{memberdesc}

\begin{memberdesc}[Application]{focus}
A callable object that is called with integer as parameter (0 = focus lost, 
1 = focus regained) when the application receives focus or it is switched to 
background. Focus is received e.g. when the application is switched from 
background to foreground or when the focus is regained from screensaver. 
Similarly when the screensaver is displayed, focus is lost.

Examples:
\begin{verbatim}
>>> import appuifw
>>> def cb(fg):
...   if(fg):
...     print "foreground"
...   else:
...     print "background"
...
>>> appuifw.app.focus=cb
>>> # switch to background, following text is printed from callback:
>>> background
>>> # switch to foreground, following text is printed from callback:
>>> foreground
\end{verbatim}

\begin{notice}
An improper callback can cause adverse effects. If you, for example,
define a callback which takes no parameters you will receive
never-ending \exception{TypeError} exceptions on the Nokia 6600.
\end{notice}

\end{memberdesc}

\begin{memberdesc}[Application]{orientation}
Available only for S60 3rdEd. 
The orientation of the application. The orientation of the application can be 
one of the following values: \code{'automatic'} (this is the default value), 
\code{'portrait'} or \code{'landscape'}.
\end{memberdesc}

Instances of \class{Application} type have the following methods:

\begin{methoddesc}[Application]{activate_tab}{index}
Activates the tab \var{index} counting from zero.
\end{methoddesc}

\begin{methoddesc}[Application]{full_name}{}
Returns the full name, in Unicode, of the native application in whose 
context the current Python interpreter session runs.
\end{methoddesc}

\begin{methoddesc}[Application]{uid}{}
Returns the UID, in Unicode, of the native application in whose 
context the current Python interpreter session runs.
\end{methoddesc}

\begin{methoddesc}[Application]{set_exit}{}
Requests a graceful exit from the application as soon as the current script 
execution returns.
\end{methoddesc}

\begin{methoddesc}[Application]{set_tabs}{tab_texts\optional{,callback=None}}
Sets tabs with given names on them in the navigation bar; 
\var{tab_texts} is a list of Unicode strings. When the users 
navigate between tabs, \var{callback} gets called with the index 
of the active tab as an argument. Tabs can be disabled by giving an empty or 
one-item \var{tab_texts} list.
\end{methoddesc}


\begin{methoddesc}[Application]{layout}{layout_id}

\begin{notice}[note]
Available from S60 2ndEd FP3 onwards (inclusive).
\end{notice}

Returns as a tuple the size and the position of the requested \code{layout_id}. 
The logical layouts are outlined partly in Figure \ref{fig:normal-uilayout}. The