libappuifw.tex

python s60 1.4.5版本的源代码

position is given from the top left corner. The \code{layout_id} can be one of 
the constants defined in module \module{appuifw}\footnote{Descriptions of the 
values are from the S60 SDK documentation \cite{S60Doc}.}:

\begin{datadesc}{EScreen} 
Screen.  
\end{datadesc}

\begin{datadesc}{EApplicationWindow} 
 Window that fills the entire screen.
\end{datadesc}

\begin{datadesc}{EStatusPane} 
Indicates common components for most of the applications.  
\end{datadesc}

\begin{datadesc}{EMainPane} 
The application main pane is used in all the applications.  
\end{datadesc}

\begin{datadesc}{EControlPane} 
Control pane.
\end{datadesc}

\begin{datadesc}{ESignalPane} 
The signal pane is used to indicate signal strength.  
\end{datadesc}

\begin{datadesc}{EContextPane} 
The context pane is used to indicate an active application.
\end{datadesc}

\begin{datadesc}{ETitlePane} 
Used to indicate the subject or the name of the main pane content. 
\end{datadesc}

\begin{datadesc}{EBatteryPane} 
The battery pane is used to indicate battery strength.  
\end{datadesc}

\begin{datadesc}{EUniversalIndicatorPane} 
The universal indicator pane is used to indicate items that require the user's 
attention while browsing applications. 
\end{datadesc}

\begin{datadesc}{ENaviPane} 
The navi pane is used to indicate navigation within an application, to provide 
context sensitive information to the user while entering or editing data, or to 
show additional information.  
\end{datadesc}

\begin{datadesc}{EFindPane} 
A fixed find pane is used with lists instead of the find pop-up window.  
\end{datadesc}

\begin{datadesc}{EWallpaperPane} 
Wallpaper pane.  
\end{datadesc}

\begin{datadesc}{EIndicatorPane} 
The universal indicator pane is used to indicate items that require the user's 
attention while browsing applications.  
\end{datadesc}

\begin{datadesc}{EAColumn} 
Used generally to display small sized graphics or heading texts.  
\end{datadesc}

\begin{datadesc}{EBColumn} 
Used generally to display large sized icons or heading texts.  
\end{datadesc}

\begin{datadesc}{ECColumn} 
Used generally to display data entered by the user. Overlaps with the D column. 
\end{datadesc}

\begin{datadesc}{EDColumn} 
Used generally to display additional icons. Overlaps with the C column. 
\end{datadesc}

\begin{datadesc}{EStaconTop} 
Top part of status and control panes in landscape layout.  
\end{datadesc}

\begin{datadesc}{EStaconBottom} 
Bottom part of status and control panes in landscape layout.  
\end{datadesc}

\begin{datadesc}{EStatusPaneBottom} 
Bottom part of status pane in landscape layout.  
\end{datadesc}

\begin{datadesc}{EControlPaneBottom} 
Bottom part of control pane in landscape layout.  
\end{datadesc}

\begin{datadesc}{EControlPaneTop} 
Top part of control pane in landscape layout.  
\end{datadesc}

\begin{datadesc}{EStatusPaneTop} 
Top part of status pane in landscape layout.
\end{datadesc}

Example:
\begin{verbatim}
>>> import appuifw
>>> appuifw.app.layout(appuifw.EMainPane)
((176, 144), (0, 44))
>>> # size and position (x, y) of the main pane in Nokia N70
\end{verbatim}

\end{methoddesc}

\end{classdesc*}

\subsection{Form Type}
\label{subsec:form}
\class{Form} implements a dynamically configurable, editable multi-field 
dialog. \class{Form} caters for advanced dialog use cases with requirements 
such as free selectability of the combination of fields, possibility of 
validating the user input, and automatically producing the contents of some 
dialog fields before allowing the closing of the dialog. 

\begin{classdesc}{Form}{fields\optional{, flags=0}}
Creates a \class{Form} instance.
\var{fields} is a list of \emph{field descriptors}: \code{(label, type\optional{, value})} where

\var{label} is a Unicode string

\var{type} is one of the following strings: 
\code{'text'}, \code{'number'}, \code{'date'}, \code{'time'}, \code{'combo'}
or \code{'float'}

\var{value}, depending on \var{type}: Unicode string, numeric, float (seconds 
since Unix epoch rounded down to the nearest local midnight), float (seconds 
since local midnight), \code{([choice_label ...], index)} of float. For 
\code{'float'} \var{type} the initial value setting might not be shown in the 
UI.
\end{classdesc}

\class{Form} can also be configured and populated after construction. The 
configuration flags are visible as an attribute. \class{Form} implements 
the list protocol that can be used for setting the form fields, as well as 
obtaining their values after the dialog has been executed.

Instances of \class{Form} type have the following attributes:

\begin{memberdesc}[Form]{flags}
This attribute holds the values of the various configuration flags. 
Currently supported flags are:

\begin{datadesc}{FFormEditModeOnly}
When this flag is set, the form remains in edit mode while \method{execute} 
runs.
\end{datadesc}

\begin{datadesc}{FFormViewModeOnly}
When this flag is set, the form cannot be edited at all.
\end{datadesc}

\begin{datadesc}{FFormAutoLabelEdit}
This flag enables support for allowing the end-users to edit the labels of 
the form fields.
\end{datadesc}

\begin{datadesc}{FFormAutoFormEdit}
This flag enables automatic support for allowing the end-users to add and 
delete the form fields. Note that this is an experimental feature and is not 
guaranteed to work with all SDK versions.
\end{datadesc}

\begin{datadesc}{FFormDoubleSpaced}
When this flag is set, double-spaced layout is applied when the form is 
executed: one field takes two lines, as the label and the value field are on 
different lines.
\end{datadesc}
\end{memberdesc}

\begin{memberdesc}[Form]{menu}
A list of \code{(title, callback)} pairs, where 
each pair describes an item in the form's menu bar that is active while the 
dialog is being executed. \var{title} (Unicode) is the name of 
the item and \var{callback} the associated callable object.
\end{memberdesc}

\begin{memberdesc}[Form]{save_hook}
This attribute can be set to a callable object that receives one argument 
and returns a Boolean value. It gets called every time the users want to 
save the contents of an executing \class{Form} dialog. A candidate list for 
new form content - a list representing the currently visible state of the 
UI - is given as an argument. The list can be modified by 
\member{save_hook}. If \member{save_hook} returns \code{True}, the 
candidate list is set as the new contents of the form. Otherwise, the form 
UI is reset to reflect the field list contained in \class{Form} object.
\end{memberdesc}

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

\begin{methoddesc}[Form]{execute}{}
Executes the dialog by making it visible on the UI.
\end{methoddesc}

\begin{methoddesc}[Form]{insert}{index, field_descriptor}
Inserts the field descriptor into the \class{Form} before the given \var{index}.
\end{methoddesc}

\begin{methoddesc}[Form]{pop}{}
Removes the last field descriptor from the \class{Form} and returns it.
\end{methoddesc}

\begin{methoddesc}[Form]{length}{}the number of field descriptors in the form.
\end{methoddesc}

The subscript notation \code{f[i]} can be used to access or modify the
i-th element of the form \code{f}. Same limitations as discussed above
in the context of the flag \constant{FFormAutoFormEdit} apply to
modifying a form while it is executing. The ability to change the
schema of a form while it is executing is an experimental feature.

\subsection{Text Type}
\label{subsec:mylabel5}
\class{Text} is a text editor UI control. For examples on the options 
available with \class{Text}, see Figure \ref{fig:text-styles}.

\begin{figure}[htbp]
\centering
\includegraphics[width=\screenwidth]{text-styles-1}
\includegraphics[width=\screenwidth]{text-styles-2}
\caption{Examples of the options available for Text type}
\label{fig:text-styles}
\end{figure}

Instances of \class{Text} type have the following attributes:

\begin{memberdesc}[Text]{color}
The color of the text. \code{color} supports the same color representation 
models as the \module{graphics} module. For the supported color 
representation models, see Section \ref{sec:graphics}.
\end{memberdesc}

\begin{memberdesc}[Text]{focus}
A Boolean attribute that indicates the focus state of the control. Editor 
control also takes the ownership of the navigation bar, and this feature is 
needed to enable the usage of this control in applications that use the 
navigation bar - for example, navigation tabs.
\end{memberdesc}

\begin{memberdesc}[Text]{font} 
The font of the text. There are two possible ways to set this attribute:

\begin{itemize}

\item Using a supported Unicode font, for example \code{u"Latin12"}. Trying to set a font which is not supported by the device has no effect. A list of supported fonts can be retrieved by using \function{appuifw.available_fonts}.

Example, setting font:
\begin{verbatim}
t = appuifw.Text()
t.font = u"albi17b" # sets font to Albi 17 bold
t.font = u"LatinPlain12" # sets font to Latin Plain 12
\end{verbatim}
\item Using one of the default device fonts that are associated with the following labels (plain strings):
\code{'annotation', 'title', 'legend', 'symbol', 'dense', 'normal'}
Example, setting font: 
\begin{verbatim}
t.font = "title" # sets font to the one used in titles
\end{verbatim}

Example, checking the currently set font: 
\begin{verbatim}
unicodeFont = t.font
\end{verbatim}
\end{itemize}

The attribute value retrieved is always a Unicode string. If the font has 
been set with a label, for example, \code{'title'}, the attribute will 
retrieve the font associated with that label. 
\end{memberdesc}

\begin{memberdesc}[Text]{highlight_color}
The highlight color of the text. \code{highlight_color} supports the 
same color representation models as the \module{graphics} module. For the 
supported color representation models, see Section \ref{sec:graphics}.
\end{memberdesc}

\begin{memberdesc}[Text]{style}
The style of the text. The flags for this attribute are defined in the 
\module{appuifw} module. These flags can be combined by using the binary 
operator \code{|}. The flags can be divided into two types: text style 
and text highlight. Text style flags can be freely combined with each other. 
However, one or more text style flags can be combined with only one text 
highlight flag. The flags are:

Text style:

\begin{datadesc}{STYLE_BOLD} 
Enables bold text.
\end{datadesc}

\begin{datadesc}{STYLE_UNDERLINE}
Enables underlined text.
\end{datadesc}

\begin{datadesc}{STYLE_ITALIC} 
Enables italic text.
\end{datadesc}

\begin{datadesc}{STYLE_STRIKETHROUGH } 
Enables strikethrough.
\end{datadesc}

Text highlight:

\begin{datadesc}{HIGHLIGHT_STANDARD}
Enables standard highlight.
\end{datadesc}

\begin{datadesc}{HIGHLIGHT_ROUNDED}
Enables rounded highlight.
\end{datadesc}

\begin{datadesc}{HIGHLIGHT_SHADOW}
Enables shadow highlight.
\end{datadesc}

Only one highlight is allowed to be used at once. Therefore, it is possible 
to combine only one highlight with one or more text styles.

Examples:
\begin{verbatim}
t = appuifw.Text()

# These and other similar values and combinations are valid:
t.style = appuifw.STYLE_BOLD
t.style = appuifw.STYLE_UNDERLINE
t.style = appuifw.STYLE_ITALIC
t.style = appuifw.STYLE_STRIKETHROUGH
t.style = (appuifw.STYLE_BOLD|
	   appuifw.STYLE_ITALIC|
	   appuifw.STYLE_UNDERLINE)

# These values are valid:
t.style = appuifw.HIGHLIGHT_STANDARD
t.style = appuifw.HIGHLIGHT_ROUNDED
t.style = appuifw.HIGHLIGHT_SHADOW

# This combination is NOT valid:
# Invalid code, do not try!
t.style = (appuifw.HIGHLIGHT_SHADOW|appuifw.HIGHLIGHT_ROUNDED)
\end{verbatim}
\end{memberdesc}

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

\begin{methoddesc}[Text]{add}{text}
Inserts the Unicode string \var{text} to the current cursor position.
\end{methoddesc}

\begin{methoddesc}[Text]{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.