libappuifw.tex

python s60 1.4.5版本的源代码

\end{methoddesc}

\begin{methoddesc}[Text]{clear}{}
Clears the editor.
\end{methoddesc}

\begin{methoddesc}[Text]{delete}{\optional{pos=0, length=len()}}
Deletes \var{length} characters of the text held by the editor control, 
starting from the position \var{pos}.
\end{methoddesc}

\begin{methoddesc}[Text]{get_pos}{}
Returns the current cursor position.
\end{methoddesc}

\begin{methoddesc}[Text]{len}{}
Returns the length of the text string held by the editor control.
\end{methoddesc}

\begin{methoddesc}[Text]{get}{\optional{pos=0, length=len()}}
Retrieves \code{length} characters of the text held by the editor control, 
starting from the position \var{pos}.
\end{methoddesc}

\begin{methoddesc}[Text]{set}{text}
Sets the text content of the editor control to Unicode string 
\var{text}.
\end{methoddesc}

\begin{methoddesc}[Text]{set_pos}{cursor_pos}
Sets the cursor to \var{cursor_pos}.
\end{methoddesc}

\subsection{Listbox Type}
\label{subsec:listbox}

\begin{figure}[htbp]
\centering
\includegraphics[width=\screenwidth]{listbox-with-icons}
\caption{Listbox with icons}
\label{fig:listbox-with-icons}
\end{figure}

An instance of this UI control type is visible as a listbox, also known as a 
list in Symbian, that can be configured to be a single-line item or a 
double-item listbox. Figure \ref{fig:listbox-with-icons} shows a single-line 
item Listbox with icons. For more information on the MBM and MIF formats, 
see Section \ref{subsec:icon}.

\begin{classdesc}{Listbox}{list, callback}
Creates a \class{Listbox} instance. A callable object 
\var{callback} gets called when a listbox selection has been 
made. \code{list} defines the content of the listbox and can be one of the 
following:

\begin{itemize}
\item A normal (single-line item) listbox: a list of Unicode strings, for example \code{[unicode_string item1, unicode_string item2]}
\item A double-item listbox: a two-element tuple of Unicode strings , for example \code{[(unicode_string item1, unicode_string item1description), (unicode_string item2, unicode_string item2description)]}
\item A normal (single-line item) listbox with graphics: a two-element tuple consisting of a Unicode string and an \class{Icon} object, for example \code{[(unicode_string item1, icon1), (unicode_string item2, icon2)]}.
\item A double-item listbox with graphics: a three-element tuple consisting of two Unicode strings and one \class{Icon} object, for example \code{[(unicode_string item1, unicode_string item1description, icon1), (unicode_string item2, unicode_string item2description, icon2)]}
\end{itemize}

Example: To produce a normal (single-line item) listbox with graphics:
\begin{verbatim}
icon1 = appuifw.Icon(u"z:\\system\\data\\avkon.mbm", 28, 29)
icon2 = appuifw.Icon(u"z:\\system\\data\\avkon.mbm", 40, 41)
entries = [(u"Signal", icon1),
           (u"Battery", icon2)]
lb = appuifw.Listbox(entries, lbox_observe)
\end{verbatim}
\end{classdesc}

Instances of \class{Listbox} type have the following methods and properties:

\begin{methoddesc}[Listbox]{bind}{event_code, callback}
Binds the callable Python object \var{callback} to event 
\var{event_code}. The key codes are defined in 
the \module{key_codes} library module. The call
\code{bind(event_code, None)} clears an 
existing binding. In the current implementation the event is always passed 
also to the underlying native UI control.
\end{methoddesc}

\begin{methoddesc}[Listbox]{current}{}
Returns the currently selected item's index in the \class{Listbox}.
\end{methoddesc}

\begin{methoddesc}[Listbox]{set_list}{list\optional{, current}}
Sets the \class{Listbox} content to a list of Unicode strings or a
list of tuples of Unicode strings. The accepted structures of \var{list} are the
same as in the \class{Listbox} constructor. The optional argument \var{current} is the index of the focused list item.
\end{methoddesc}

\begin{memberdesc}[Listbox]{size}
The size of the \class{Listbox} as a tuple (width, height) - Read only. Only on S60 3rd Ed, and higher.
\end{memberdesc}

\begin{memberdesc}[Listbox]{position}
The coordinates (as a tuple) of the top left corner of the \class{Listbox} -
Read only. Only on S60 3rd Ed. and higher.
\end{memberdesc}

\subsection{Icon Type}
\label{subsec:icon}
An instance of \class{Icon} type encapsulates an icon to be used together 
with a \class{Listbox} instance. Note that currently \class{Icon} can only 
be used with \class{Listbox} (see Section \ref{subsec:listbox}).

MBM is the native Symbian OS format used for pictures. It is a
compressed file format where the files can contain several bitmaps and
can be referred to by a number. An \code{.mbg} file is the header file
usually associated with an \code{.mbm} file, which includes symbolic
definitions for each bitmap in the file. For example, an
\file{avkon.mbm} file has an associated index file called
\file{avkon.mbg}, which is included in S60 SDKs. For more information
on the MBM format and the bitmap converter tool, see \cite{S60Doc} and
search the topics with the key term "How to provide Icons"; this topic
also points you to the Bitmap Converter tool that can be used for
converting bitmaps into the MBM format.

S60 2$^{nd}$ Edition FP3 introduces a new format for icons called 
Multi-Image File (MIF). This format is very similar to the MBM format and 
also contains several compressed files. The files to be compressed should be 
in Scalable Vector Graphics Tiny (SVG-T) format. For more information on the 
SVG format, see Scalable Vector Graphics (SVG) 1.1 Specification 
[10].

\begin{classdesc}{Icon}{filename, bitmap, bitmapMask}
Creates an icon. \var{filename} is a Unicode file name and must 
include the whole path. Note that MBM and MIF (MIF only in S60 2nd 
Edition FP3) are the only file formats supported. \var{bitmap} 
and \var{bitmapMask} are integers that represent the index of 
the icon and icon mask inside that file respectively.
\end{classdesc}

Example: The following builds an icon with the standard signal symbol:
\begin{verbatim}
icon = appuifw.Icon(u"z:\\system\\data\\avkon.mbm", 28, 29)
\end{verbatim}

\subsection{Content_handler Type}
\label{subsec:content}

An instance of \class{Content_handler} handles data content by its MIME 
type.

\begin{classdesc}{Content_handler}{\optional{callback}}
Creates a \class{Content_handler} instance. A Content_handler handles
data content by its MIME type. The optional
\var{callback} is called when the embedded handler application 
started with the \method{open} method finishes. 
\end{classdesc}

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

\begin{methoddesc}[Content_handler]{open}{filename}
Opens the file \var{filename} (Unicode) in its handler 
application if one has been registered for the particular MIME type. The 
handler application is embedded in the caller's thread. The call to this 
function returns immediately. When the handler application finishes, the 
\var{callback} that was given to the \class{Content_handler} 
constructor is called.
\end{methoddesc}

\begin{methoddesc}[Content_handler]{open_standalone}{filename}
Opens the file \var{filename} (Unicode) in its handler 
application if one has been registered for the particular MIME type. The 
handler application is started in its own process. The call to this function 
returns immediately. Note that \var{callback} is not called for 
applications started with this method.
\end{methoddesc}

\subsection{Canvas Type}
\label{subsec:canvas}
\class{Canvas} is a UI control that provides a drawable area on the screen 
and support for handling raw key events. \class{Canvas} supports the 
standard drawing methods that are documented in Section \ref{sec:graphics}.

\begin{classdesc}{Canvas}{\optional{redraw_callback=None, event_callback=None,
                                  resize_callback=None}}
Constructs a \class{Canvas}. The optional parameters are callbacks
that are called when specific events occur. 

\note{Watch out for cyclic
references here. For example, if the callbacks are methods of an
object that holds a reference to the \class{Canvas}, a reference cycle
is formed that must be broken at cleanup time or the
\class{Canvas} will not be freed.}

\var{redraw_callback} is called whenever a part of the \class{Canvas} 
has been obscured by something, is then revealed, and needs to be
redrawn. This can typically happen, for example, when the user
switches away from the Python application and back again, or after
displaying a pop-up menu. The callback takes as its argument a
four-element tuple that contains the top-left and the bottom-right
corner of the area that needs to be redrawn. In many cases redrawing
the whole
\class{Canvas} is a reasonable option. 

\var{event_callback} is called whenever a raw key event is received.
There are three kinds of key events: \code{EEventKeyDown},
\code{EEventKey}, and \code{EEventKeyUp}. When a user presses a key 
down, events \code{EEventKeyDown} and \code{EEventKey} are generated. 
When the key is released, an \code{EEventKeyUp} event is generated.

The argument to the \var{event_callback} is a dictionary that contains 
the following data for key events:

\begin{itemize}
\item \code{'type'}: one of \code{EEventKeyDown}, \code{EEventKey}, or \code{EEventKeyUp}
\item \code{'keycode'}: the keycode of the key
\item \code{'scancode'}: the scancode of the key
\item \code{'modifiers'}: the modifiers that apply to this key event
\end{itemize}

Each key on the keyboard has one or more scancodes and zero or more keycodes 
associated with it. A scancode represents the physical key itself and a 
keycode is the result of state-related operating system defined processing 
done on the key. For keys that correspond to a symbol in the current 
character set of the phone, the keycode is equal to the code of the 
corresponding symbol in that character set. For example, if you are using 
the Nokia Wireless Keyboard (SU-8W), pressing the key A will always produce 
the scancode 65 (ASCII code for an upper case A), but the keycode 
could be either 65 or 91 (ASCII code for a lower case A) depending on 
whether or not the Shift key is pressed or Caps Lock is active. 

The \module{key_codes} module contains definitions for the keycodes and 
scancodes. See \figurename~\ref{fig:keyboard} for the codes of the most 
common keys on the phone keypad. 

Some keys are handled in a special way:

\begin{itemize}
\item A short press of the Edit key causes it to stay down, meaning that no \code{EEventKeyUp} event is sent. The event is only sent after a long press.
\item Detecting presses of the Voice tags key or the Power key is not supported.
\item If the right softkey is pressed, the \code{appuifw.app.exit_key_handler} callback is always executed.
\end{itemize}

There is no way to prevent the standard action of the Hang-up key, the Menu 
key, the Power key or the Voice tags key from taking place.

\begin{figure}
\centering
\includegraphics[width=5in]{6630keyboard}
%\includegraphics[width=3.60in,height=2.58in]{6630keyboard}
%\centerline{\includegraphics[width=3.60in,height=2.58in]{API_Reference_for_Python11.eps}} \par & 
\begin{tableiii}{lll}{textrm}{Key}{Keycode}{Scancode}
\lineiii{1.}{EKeyLeftSoftkey}{EScancodeLeftSoftkey}
\lineiii{2.}{EKeyYes}{EScancodeYes}
\lineiii{3.}{EKeyMenu}{EScancodeMenu}
\lineiii{4.}{EKey0...9}{EScancode0...9}
\lineiii{5.}{EKeyStar}{EScancodeStar}
\lineiii{6.}{EKeyLeftArrow}{EScancodeLeftArrow}
\lineiii{7.}{EKeyUpArrow}{EScancodeUpArrow}
\lineiii{8.}{EKeySelect}{EScancodeSelect}
\lineiii{9.}{EKeyRightArrow}{EScancodeRightArrow}
\lineiii{10.}{EKeyDownArrow}{EScancodeDownArrow}
\lineiii{11.}{EKeyRightSoftkey}{EScancodeRightSoftkey}
\lineiii{12.}{EKeyNo}{EScancodeNo}
\lineiii{13.}{EKeyBackspace}{EScancodeBackspace}
\lineiii{14.}{EKeyEdit}{EScancodeEdit}
\lineiii{15.}{EKeyHash}{EScancodeHash}
\end{tableiii}
\caption{Keycodes and scancodes for phone keys usable from Python applications}
\label{fig:keyboard}
\end{figure}

\var{resize_callback} is called when screen size is changed when the 
\class{Canvas} rect size has been changed. The callback takes as its argument a
two-element tuple that contains the new clientRect width and height. 

\end{classdesc}

Instances of \class{Canvas} type have the following attribute:

\begin{memberdesc}[Canvas]{size}
A two-element tuple that contains the current width and height of the 
\class{Canvas} as integers.
\end{memberdesc}

Instances of \class{Canvas} type have the same standard drawing methods 
that are documented in Section \ref{sec:graphics}.

\subsection{InfoPopup Type}
\label{subsec:infopopup}

\begin{notice}[note]
Available from S60 3rd Ed onwards (inclusive).
\end{notice}

An instance of \class{InfoPopup} type encapsulates an UI tip widget. This widget 
can be placed on top of other widgets to provide e.g. usage information to the 
user. The widget disappears as soon as the device's user presses any key or when 
the timer behind the \class{InfoPopup} is triggered.

\begin{classdesc}{InfoPopup}{}
Creates an \class{InfoPopup}.
\end{classdesc}

\begin{methoddesc}[InfoPopup]{show}{text, \optional{(x_coord, y_coord), 
time_shown, time_before, alignment}}
Show \var{text} (Unicode) in the \class{InfoPopup}. The optional parameters are 
the location (a tuple from the upper left corner), the time the popup is 
visible, \var{time_shown} (in milliseconds), the time before the popup, 
\var{time_before} (in milliseconds) and the alignment of the popup.

The default values are: the coordinates \code{(0, 0)}, \var{time_shown} 5 
seconds, \var{time_before} 0 seconds and for the alignment 
\code{appuifw.EHLeftVTop}.

The \var{alignment} can be one of the constants defined in module 
\code{appuifw}\footnote{Descriptions of the values are from the S60 SDK 
documentation \cite{S60Doc}.}:

\begin{datadesc}{EHLeftVTop} 
Object is left and top aligned. 
\end{datadesc}

\begin{datadesc}{EHLeftVCenter} 
Object is left aligned and centred vertically. 
\end{datadesc}

\begin{datadesc}{EHLeftVBottom} 
Object is left aligned and at the bottom. 
\end{datadesc}

\begin{datadesc}{EHCenterVTop} 
Object is centre aligned horizontally and at the top. 
\end{datadesc}

\begin{datadesc}{EHCenterVCenter} 
Object is centred horizontally and vertically. 
\end{datadesc}

\begin{datadesc}{EHCenterVBottom} 
Object is centred horizontally and at the bottom. 
\end{datadesc}

\begin{datadesc}{EHRightVTop} 
Object is right and top aligned. 
\end{datadesc}
 
\begin{datadesc}{EHRightVCenter} 
Object is right aligned and centred vertically. 
\end{datadesc}

\begin{datadesc}{EHRightVBottom} 
Object is right aligned and at the bottom. 
\end{datadesc}

\end{methoddesc}

\begin{methoddesc}[InfoPopup]{hide}{}
Hides the popup immediately.
\end{methoddesc}

Example:

\begin{verbatim}
>>> import appuifw
>>> i=appuifw.InfoPopup()
>>> i.show(u"Here is the tip.", (0, 0), 5000, 0, appuifw.EHRightVCenter)
>>>
\end{verbatim}