n4mJwnTu

1PyS60 Library Reference
2
3Release 1.4.1 final
404 July 2007
5Nokia
6
7
8Copyright c 2004-2007 Nokia Corporation.
9This is Python for S60 version 1.4.1 final created by Nokia Corporation. Files added by Nokia Corpo-
10ration are licensed under Apache License Version 2.0. The original software, including modifications of
11Nokia Corporation therein, is licensed under the applicable license(s) for Python 2.2.2, unless specifically
12indicated otherwise in the relevant source code file.
13See http://www.apache.org/licenses/LICENSE-2.0 and http://www.python.org/2.2.2/license.html
14
15Abstract
16The Python for S60 Platform (Python for S60) simplifies application development and provides a scripting
17solution for the Symbian C++ APIs. This document is for Python for S60 version 1.4.1 final that is
18based on Python 2.2.2.
19
20
21CONTENTS
221 Introduction
231
241.1
25Scope . . . . . 1
261.2
27Audience . . . . . 2
281.3
29Naming Conventions . . . . . 2
302 API Summary
313
322.1
33Python Standard Library . . . . . 3
342.2
35Python for S60 Extensions . . . . . 3
362.3
37Third-Party Extensions . . . . . 4
383 Selected Issues on Python Programming for S60
395
403.1
41Concurrency Aspects . . . . . 5
423.2
43Running Python for S60 Scripts . . . . . 5
443.3
45Standard I/O Streams . . . . . 6
463.4
47Usage of Unicode . . . . . 6
483.5
49Date and Time . . . . . 6
503.6
51Limitations of Thread Support . . . . . 6
523.7
53Scalable User Interface . . . . . 7
543.8
55Error Handling . . . . . 7
563.9
57Limitations and Areas of Development . . . . . 7
584 Operating System Services and Information
599
604.1
61e32 — A Symbian OS related services package . . . . . 9
624.2
63sysinfo — Access to system information . . . . . 11
645 User Interface and Graphics
6513
665.1
67appuifw — Interface to the S60 GUI framework . . . . . 13
685.2
69graphics — A graphics related services package . . . . . 27
705.3
71camera — Interface for taking photographs and video recording . . . . . 33
725.4
73keycapture — Interface for global capturing of key events. . . . . 36
745.5
75topwindow — Interface for creating windows that are shown on top of other applications. 37
765.6
77gles — Bindings to OpenGL ES . . . . . 38
785.7
79glcanvas — UI Control for Displaying OpenGL ES Graphics . . . . . 45
805.8
81sensor — Module to access the device sensors. . . . . 46
826 Audio and Communication Services
8349
846.1
85audio — An audio related services package . . . . . 49
866.2
87telephone — Telephone services . . . . . 51
886.3
89messaging — A messaging services package . . . . . 52
906.4
91inbox — Interface to device inbox . . . . . 53
926.5
93location — GSM location information . . . . . 54
946.6
95positioning — Simplified interface to the position information . . . . . 55
967 Data Management
9759
98i
99Page 6
1007.1
101contacts — A contacts related services package . . . . . 59
1027.2
103calendar — Access to calendar related services . . . . . 64
1047.3
105calendar for EKA2 — Access to calendar related services . . . . . 69
1067.4
107e32db — Interface to the Symbian native DB . . . . . 74
1087.5
109e32dbm — DBM implemented using the Symbian native DBMS . . . . . 77
1108 Standard Library Support and Extensions
11179
1128.1
113Support for Python Standard Library . . . . . 79
1148.2
115Extensions to Standard Library Modules . . . . . 80
1169 Extending and Embedding
11783
1189.1
119Python/C API Extensions . . . . . 83
1209.2
121Extending Python for S60 . . . . . 84
12210 Terms and Abbreviations
12387
124A Reporting Bugs
12591
126Module Index
12793
128Index
12995
130ii
131
132
133CHAPTER
134ONE
135Introduction
136The Python for S60 Platform (Python for S60) simplifies application development and provides a scripting
137solution for the Symbian C++ APIs. This document is for Python for S60 release 1.4.1 final that is
138based on Python 2.2.2.
139The documentation for Python for S60 includes three documents:
140• Getting Started with Python for S60 Platform [5] contains information on how to install Python
141for S60 and how to write your first program.
142• This document contains API and other reference material.
143• Programming with Python for S60 Platform [6] contains code examples and programming patterns
144for S60 devices that can be used as a basis for programs.
145The Python for S60 as installed on a S60 device consists of:
146• Python runtime package that consists of:
147– Python interpreter DLL
148– Standard and proprietary Python library modules
149– S60 UI application framework adaptation component (a DLL) that connects the scripting
150domain components to the S60 UI
151• Python script shell package that consists of:
152– an application written in Python and visible in the application menu of the device that provides
153an execution environment for Python scripts.
154– For S60 platform versions prior to 3rd Edition: Python Installer program for installing Python
155files on the device, which consists of:
156∗ A recognizer plug-in that recognizes .py, .pyc, .pyd and .pyo files as belonging to Python.
157∗ Symbian application written in Python that handles the installation of recognized Python
158files into the script shell environment.
159A plugin for the S60 C++ SDK is also available. This plugin makes it possible to run Python scripts in
160the S60 emulator environment and to compile Python extension modules (PYDs) for the emulator and
161the device.
162The Python for S60 developer discussion board [9] on the Forum Nokia Web site is a useful resource for
163finding out information on specific topics concerning Python for S60. You are welcome to give feedback
164or ask questions about Python for S60 through this discussion board.
1651.1 Scope
166This document includes the information required by developers to create applications that use Python
167for S60, and some advice on extending the platform.
1681
169Page 8
1701.2 Audience
171This guide is intended for developers looking to create programs that use the native features and re-
172sources of the S60 phones. The reader should be familiar with the Python programming language
173(http://www.python.org/) and the basics of using Python for S60 (see Getting Started with Python for S60
174Platform [5]).
1751.3 Naming Conventions
176Most names of the type ESomething typically indicate a constant defined by the Symbian SDK. More
177information about these constants can be found in the Symbian SDK documentation.
1782
179Chapter 1. Introduction
180Page 9
181CHAPTER
182TWO
183API Summary
184All built-in object types of the Python language are supported in the S60 environment. The rest of the
185programming interfaces are implemented by various library modules as summarized in this chapter.
1862.1 Python Standard Library
187Python for S60 platform distribution does not include all of the Python’s standard and optional library
188modules to save storage space in the phone. Nevertheless, many of the excluded modules also work in
189the S60 Python environment without any modifications. Some modules are included in the SDK version
190but not installed in the phone. For a summary of supported library modules, see Chapter 8.
191When Python, available at http://www.python.org/, is installed on a PC, the library modules are by default
192located in ‘\Python22\Lib’ on Windows and in ‘/usr/lib/python2.2’ on Linux. The Python library modules’
193APIs are documented in [1].
194Python for S60 extends some standard modules. These extensions are described in this document, see
195Chapter 8.2.
1962.2 Python for S60 Extensions
197There are two kinds of native C++ extensions in the Python for S60 Platform: built-in extensions and
198dynamically loadable extensions.
1992.2.1 Built-in extensions
200There are two built-in extensions in the Python for S60 package:
201• The e32 extension module is built into the Python interpreter on Symbian OS, and implements
202interfaces to special Symbian OS Platform services that are not accessible via Python standard
203library modules.
204• The appuifw module for Python for S60 Platform offers UI application framework related Python
205interfaces.
2062.2.2 Dynamically loadable extensions
207These dynamically loadable extension modules provide proprietary APIs to S60 Platform’s services:
208• graphics: see Chapter 5.2
209• e32db: see Chapter 7.4
210• messaging: see Chapter 6.3
2113
212Page 10
213• inbox: see Chapter 6.4
214• location: see Chapter 6.5
215• sysinfo: see Chapter 4.2
216• camera: see Chapter 5.3
217• audio: see Chapter 6.1
218• telephone: see Chapter 6.2
219• calendar: see Chapter 7.2
220• contacts: see Chapter 7.1
221• keycapture: see Chapter 5.4
222• topwindow: see Chapter 5.5
223• gles: see Chapter 5.6
224• glcanvas: see Chapter 5.7
2252.3 Third-Party Extensions
226It is also possible to write your own Python extensions. S60 related extensions to Python/C API are
227described in Chapter 9.1. For some further guidelines on writing extensions in C/C++, see Chapter 9.2.
228In addition, for an example on porting a simple extension to S60, see [6].
2294
230Chapter 2. API Summary
231Page 11
232CHAPTER
233THREE
234Selected Issues on Python Programming for
235S60
236The following issues must be considered when using Python on S60.
2373.1 Concurrency Aspects
238The thread that initializes the Python interpreter becomes the main Python thread. This is usually the
239main thread of a UI application. When an application written in Python launches, the Symbian platform
240infrastructure creates the main UI thread that starts the Python environment. If a Python program is
241started as a server with e32.start server, then the Python main thread is not a UI thread.
242It is possible to launch new threads via the services of thread module. Examples of such situations could
243be to overcome eventual problems with the fixed, relatively small stack size of the main UI application
244thread; or to perform some background processing while still keeping the UI responsive. These new
245threads are not allowed to directly manipulate the UI; in other words, they may not use the appuifw
246module.
247Because of the limitations of the Python interpreter’s final cleanup, Python applications on the Symbian
248OS should be designed in such a way that the main thread is the last thread alive.
249A facility called active object is used extensively on the Symbian OS to implement co-operative, non-
250preemptive scheduling within operating system threads. This facility is also utilized with native APIs. A
251Python programmer is exposed to related concurrency issues particularly in UI programming. Preserving
252the responsiveness of the UI with the help of active objects needs to be considered when designing the
253application logic. At the same time it is necessary to take into account the resulting concurrent behavior
254within the application when active objects are used. While the main execution path of a UI script is
255blocked in wait for an active object to complete – either explicitly as a result of using e32.Ao lock, or
256indirectly within some other Python API implementation – the UI-related callbacks may still get called.
257The standard thread.lock cannot normally be used for synchronization in the UI application main
258thread, as it blocks the UI event handling that takes place in the same thread context. The Symbian
259active object based synchronization service called e32.Ao lock has been implemented to overcome this
260problem. The main thread can wait in this lock, while the UI remains responsive.
261Python for S60 tries to minimize the unwanted exposure of a Python programmer to the active objects
262of the Symbian OS. The programmer may choose to implement the eventual concurrent behavior of the
263application with normal threads. However, certain active object based facilities are offered as an option
264in the e32 module.
2653.2 Running Python for S60 Scripts
266The current options for installing Python scripts to a S60 device are: a stand-alone installation to the
267device’s main application menu, and an installation to a folder hierarchy maintained by the Python script
2685
269Page 12
270shell. For more details on this topic, see Programming with Python for S60 Platform [6]. In the first
271case the script application is launched via application menu, and it executes in its own process context.
272The latter case is suitable for development, testing, and trying out new scripts.
273The Python script shell delivered with Python for S60 package has itself been written in Python. It is a
274collection of scripts that offer an interactive Python console and a possibility to execute scripts located
275in the directory of the script shell. Due to this kind of design the scripts are not fully isolated from each
276other. This means that any changes a script makes in the script shell namespace are visible to other
277scripts as well. This may be helpful during the development of a script suite, as long as care is taken to
278avoid unwanted interference between scripts.
279For some special issues to consider when writing Python scripts to be run in the current Python script
280shell, see Programming with Python for S60 Platform [6]. These include the arrangements for standard
281output and the maintenance of the Options menu contents.
282Note: Note that unlike some previous releases, the current version of the Python for S60 script shell
283takes care of restoring appuifw.app.menu, appuifw.app.title, appuifw.app.exit key handler,
284appuifw.app.screen, appuifw.app.body, sys.stderr and ?? after a script has been run, and The
285application programmer doesn’t need to save and restore these settings.
2863.3 Standard I/O Streams
287The standard Python I/O streams in the sys module are by default connected to underlying C STDLIB’s
288stdio streams that in turn are terminated by dummy file descriptors. Usually Python scripts set the
289I/O streams suitably by manipulating them at Python level via sys module interface. The e32 extension
290module offers a Python interface for attaching to C STDLIB’s output streams, but this service is only
291recommended for debugging purposes. The e32. stdo function takes as its argument the name of the
292file where C STDLIB’s stdout and stderr are to be redirected. This makes it possible to capture the
293low-level error output when the Python interpreter has detected a fatal error and aborts.
2943.4 Usage of Unicode
295No changes have been made to the standard library modules with regard to string argument and return
296value types. S60 extensions generally accept both plain strings and Unicode strings as arguments, but
297they return only Unicode strings. APIs that take string arguments for the purpose of showing them on
298the UI expect Unicode strings. Giving something else may result in garbled appearance of the text on
299the screen.
3003.5 Date and Time
301Unix time, seconds since January 1, 1970, 00:00:00 UTC (Coordinated Universal Time), is generally used
302as the time format in the Python for S60 APIs described in this document. The float type is used for
303storing time values.
3043.6 Limitations of Thread Support
305Python for S60 supports starting native threads via the standard thread module. However, the native
306APIs Python for S60 uses have certain limitations that a Python programmer must be aware of.
307Objects that wrap native resources can typically be used only in the thread they are created in. This is
308because native resources cannot be shared between native threads. Examples:
309Note:
3106
311Chapter 3. Selected Issues on Python Programming for S60
312Page 13
313• Symbian OS STDLIB implementation has some limitations that are reflected at OS module support
314(see S60 SDK documentation [4]). For example, STDLIB file descriptors cannot be shared between
315threads, and for that reason, Python file objects cannot either.
316• Sockets as implemented in the S60 version of the socket module.
317Warning: Trying to use native objects from the wrong thread can crash the interpreter. If display of
318panic codes is enabled, a typical panic code displayed in this case is “KERN-EXEC 3”.
3193.7 Scalable User Interface
320Note: S60 2nd Edition FP3 and further releases.
321S60 2nd Edition FP3 enables a new feature called scalable user interface. For Python developers this
322feature is currently visible in new APIs supporting the scalable UI, icon loading, and new screen resolu-
323tions. For more information on scalable user interface, see Section 5.1.8, Icon Type of this document, as
324well as Programming with Python for S60 Platform [6].
3253.8 Error Handling
326The APIs described in this document may raise any standard Python exceptions. In situations where a
327Symbian error code is returned, its symbolic name is given as the value parameter of a SymbianError
328exception.
329In case where the functions have nothing special to return, they return None on success.
3303.9 Limitations and Areas of Development
331Some OS level concepts to which the standard os library module offers an interface do not exist as such
332in Symbian OS environment. An example of this is the concept of current working directory.
333Reference cycle garbage collection is not in use. Because of this, special care needs to be taken to
334dismantle cyclic references when a Python program exits. This prevents error messages related to native
335resources that are left open. The problem could be removed by developing support for collection of cyclic
336garbage or by performing a special cleanup action on interpreter exit. The gc module has been ported
337to the Symbian OS, and it has been verified to work. However, the current distribution has been built
338without gc support.
3393.7. Scalable User Interface
3407
341Page 14
3428
343Page 15
344CHAPTER
345FOUR
346Operating System Services and Information
3474.1 e32 — A Symbian OS related services package
348The e32 module offers Symbian OS related utilities that are not related to the UI and are not provided
349by the standard Python library modules.
3504.1.1 Module Level Functions
351The following free functions - functions that do not belong to any class - are defined in the e32 module:
352ao yield()
353Yields to the active scheduler to have ready active objects with priority above normal scheduled for
354running. This has the effect of flushing the eventual pending UI events. Note that the UI callback
355code may be run in the context of the thread that performs an ao yield. For information on
356active scheduler, see S60 SDK documentation [4].
357ao sleep(interval [, callback ])
358Sleeps for the given interval without blocking the active scheduler. When the optional callback is
359given, the call to ao sleep returns immediately and the callback gets called after interval. See
360also Section 4.1.3, Ao timer Type.
361ao callgate(wrapped callable)
362Wraps wrapped callable into returned callable object callgate that can be called in any thread. As
363a result of a call to callgate, wrapped callable gets called in the context of the thread that originally
364created the callgate. Arguments can be given to the call. This is actually a simple wrapping of the
365Symbian active object facility.
366drive list()
367Returns a list of currently visible drives as a list of Unicode strings ’<driveletter>:’
368file copy(target name, source name)
369Copies the file source name to target name. The names must be complete paths.
370in emulator()
371Returns 1 if running in an emulator, or 0 if running on a device.
372set home time(time)
373Set the device’s time to time (see Section 3.5).
374pys60 version
375A string containing the version number of the Python for S60 and some additional information.
376Example:
377>>> import e32
378>>> e32.pys60_version
379’1.2 final’
380pys60 version info
3819
382Page 16
383A tuple containing the five components of the Python for S60 version number: major, minor, micro,
384release tag, and serial. All values except release level are integers; the release tag is a string. A value
385other than ’final’ for the release tag signifies a development release. The pys60 version info
386value corresponding to the Python for S60 version 1.2 is (1, 2, 0, ’final’, 0).
387s60 version info
388The SDK version with which this Python was compiled (tuple). The following values are possible:
389•(1, 2) for S60 1st Edition
390•(2, 0) for S60 2nd Edition
391•(2, 6) S60 2nd Edition Feature Pack 2
392•(2, 8) S60 2nd Edition Feature Pack 3
393•(3, 0) S60 3rd Edition
394Examples:
395>>> import e32
396>>> e32.pys60_version
397’1.2.0 final’
398>>> e32.pys60_version_info
399(1, 2, 0, ’final’, 0)
400>>> e32.s60_version_info
401(2, 0)
402>>>
403is ui thread()
404Returns True if the code that calls this function runs in the context of the UI thread; otherwise
405returns False.
406start exe(filename, command [,wait ])
407Launches the native Symbian OS executable filename (Unicode) and passes it the command string.
408When wait is set, the function synchronously waits for the exit of the executable and returns a
409value that describes the exit type. Possible values are 0 for normal exit and 2 for abnormal exit.
410start server(filename)
411Starts the Python script in file filename (Unicode) as a server in its own process. Note that appuifw
412module is not available to a server script.
413reset inactivity()
414Resets the timers since the user was last active. As a consequence, the device backlight is normally
415turned on when this function is invoked.
416inactivity()
417Returns the time in seconds since the user of the device was last active.
4184.1.2 Ao lock Type
419class Ao lock()
420Creates an Ao lock instance. A Symbian active object based synchronization service. This can
421be used in the main thread without blocking the handling of UI events. The application should
422not exit while a thread is waiting in Ao lock. If Ao lock.wait is called while another wait call
423is already in progress, an AssertionError is raised.
424Instances of Ao lock type have the following methods:
425wait()
426If the lock has already been signaled, returns immediately. Otherwise blocks in wait for the lock
427to be signaled. Only one waiter is allowed, so you should avoid recursive calls to this service. wait
428can only be called in the thread that created the lock object. During the wait, other Symbian-
429active objects are being served, so the UI will not freeze. This may result in the UI callback code
43010
431Chapter 4. Operating System Services and Information
432Page 17
433being run in the context of the thread that is waiting in Ao lock. This must be considered when
434designing the application logic.
435signal()
436Signals the lock. The waiter is released.
4374.1.3 Ao timer Type
438The rationale for the Ao timer type is that you cannot cancel a pending e32.ao sleep. This is
439problematic if e.g. the user exits an application which is sleeping. In this case a panic would occur
440since the sleep is not cancelled - this is the reason you should avoid using e32.ao sleep and instead
441use the Ao timer with appropriate cancel calls if there is for example a possibility for the user to exit
442the application during a sleep.
443class Ao timer()
444Creates an Ao timer instance. A Symbian active object based sleeping service. This can be used
445in the main thread without blocking the handling of UI events. The application should not exit
446while a thread has a pending after call in Ao timer. Only one after invocation can be pending
447at time for each instance of this type.
448Instances of Ao timer type have the following methods:
449after(interval [,callback ])
450Sleeps for the given interval without blocking the active scheduler. When the optional callback is
451given, the call to after returns immediately and the callback gets called after interval.
452cancel()
453Cancels a pending after call.
4544.2 sysinfo — Access to system information
455The sysinfo module offers an API for checking the system information of a S60 mobile device.
456Note: The method ring type is not available for S60 1st Edition.
457The sysinfo module has the following functions:
458active profile()
459Returns the current active profile as a string, which can be one of the following: ’general’,
460’silent’, ’meeting’,
461’outdoor’, ’pager’, ’offline’, , ’drive’, or ’user <profile
462value>’.
463battery()
464Returns the current battery level. On devices based on S60 2nd Edition Feature Pack 1 (S60 2.1)
465or earlier the value ranges from 0 (empty) to 7 (full). On newer devices the value ranges from 0
466(empty) to 100 (full). On the emulator the value is always 0.
467Note: The returned value may be incorrect while the device is being charged.
468display twips()
469Returns the width and height of the display in twips. For a definition of a twip, see Chapter 10,
470Terms and Abbreviations.
471display pixels()
472Returns the width and height of the display in pixels.
473free drivespace()
474Returns the amount of free space left on the drives in bytes, for example {u’C:’ 100}. The keys
475in the dictionary are the drive letters followed by a colon (:).
476imei()
477Returns the IMEI code of the device as a Unicode string or, if running on the emulator, the
478hardcoded string u’000000000000000’.
4794.2. sysinfo — Access to system information
48011
481Page 18
482max ramdrive size()
483Returns the maximum size of the RAM drive on the device.
484total ram()
485Returns the amount of RAM memory on the device.
486free ram()
487Returns the amount of free RAM memory available on the device.
488total rom()
489Returns the amount of read-only ROM memory on the device.
490ring type()
491Not supported in 1st Edition! Returns the current ringing type as a string, which can be one
492of the following: ’normal’, ’ascending’, ’ring once’, ’beep’, or ’silent’.
493os version()
494Returns the operating system version number of the device as a three element tuple (major version,
495minor version, build number). The elements are as follows1:
496•The major version number, ranging from 0 to 127 inclusive
497•The minor version number, ranging from 0 to 99 inclusive
498•The build number, ranging from 0 to 32767 inclusive.
499signal bars()
500Returns the current network signal strength ranging from 0 to 7, with 0 meaning no signal and 7
501meaning a strong signal. If using an emulator, value 0 is always returned.
502signal dbm()
503Returns the current network signal strength in dBm. This is available SDK 2.8 onwards. If using
504an emulator value 0 is always returned.
505sw version()
506Returns the software version as a Unicode string. On the emulator, returns the hardcoded string
507u’emulator’. For example, a software version can be returned as u’V 4.09.1 26-02-04 NHL-10
508(c) NMP’.
5091Descriptions for these values are based on information found in S60 SDK documentation [4].
51012
511Chapter 4. Operating System Services and Information
512Page 19
513CHAPTER
514FIVE
515User Interface and Graphics
5165.1 appuifw — Interface to the S60 GUI framework
517The appuifw module offers an interface to the S60 UI application framework. Figure 5.1 provides an
518overview of the Python for S60 environment for UI application programming.
519Note: The services of this interface may only be used in the context of the main thread, that is, the
520initial thread of a UI application script.
5215.1.1 Basics of appuifw Module
522Figure 5.2 shows the layout of a S60 application UI in the normal screen mode and a summary of how
523it relates to the services available at the appuifw API. For alternative layouts, see Figure 5.3.
524The main application window may be set up to be occupied by a UI control.
525A multi-view application can show the different views as tabs in the navigation pane and react as the
526users navigate between tabs.
527Dialogs always take precedence over the usual UI controls and appear on top of them.
528UI controls are implemented as Python types. These types are available:
529• Text
530• Listbox
531• Canvas
532UI controls appear on the screen as soon as an instance of the corresponding Python type is set to the
533body field (app.body) of the current application UI.
534Form is a versatile dialog implemented as a type.
535The Content handler type facilitates interfacing to other UI applications and common high-level UI
536components. It is based on the notion that designated handlers can reduce UI application interaction to
537operations on MIME-type content.
538The following dialogs are implemented as functions:
539• note
540• query
541• multi query
542• selection list
543• multi selection list
54413
545Page 20
546Figure 5.1: Python for S60 UI environment overview
547Figure 5.2: The different parts of the screen when using the ’normal’ layout
54814
549Chapter 5. User Interface and Graphics
550Page 21
551Figure 5.3: UI layouts. left: ’normal’, middle: ’large’, right: ’full’
552• popup menu
553A dialog becomes visible as soon as the corresponding Python function has been called. The function
554returns with the eventual user input or information on the cancellation of the dialog. Form is an exception;
555it is shown when its execute method is called.
5565.1.2 Softkeys
557The softkeys are managed by the underlying S60 Platform. When no dialog is visible, the right softkey is
558bound to application exit and the left one represents an Options menu. Python for S60 offers an interface
559for manipulating the menu and for binding the Exit key to a Python-callable object (see Section 5.1.4).
560The native code that implements a dialog also manages the softkeys of the dialog, typically OK and
561Cancel. When the user input needs to be validated before accepting it and dismissing the dialog, it is
562best to use Form.
5635.1.3 Module Level Functions
564The following free functions - functions that do not belong to any class - are defined in the appuifw
565module:
566available fonts()
567Returns a list (Unicode) of all fonts available in the device.
568query(label, type[, initial value ])
569Performs a query with a single-field dialog. The prompt is set to label, and the type of the dialog
570is defined by type. The value of type can be any of the following strings:
571•’text’
572•’code’
573•’number’
574•’date’
575•’time’
576•’query’
577•’float’
578The type of the optional initial value parameter and the returned input depend on the value of
579type:
5805.1. appuifw — Interface to the S60 GUI framework
58115
582Page 22
583•For text fields, (’text’, ’code’) it is Unicode
584•For number fields, it is numeric
585•For date fields, it is seconds since epoch rounded down to the nearest local midnight
586A simple confirmation query and time query take no initial value and return True/None and seconds
587since local midnight, correspondingly. All queries return None if the users cancel the dialog.
588For ’float’ query the initial value setting has no effect.
589multi query(label 1, label 2)
590A two-field text (Unicode) input dialog. Returns the inputted values as a 2-tuple. Returns None if
591the users cancel the dialog.
592note(text[, type[, global ]])
593Displays a note dialog of the chosen type with text (Unicode). The default value for type is ’info’,
594which is automatically used if type is not set. type can be one of the following strings: ’error’,
595’info’, or ’conf’.
596If global (integer) is any other value than zero a global note is displayed. A global note is displayed
597even if the Python application calling this function is in background. The same set of types is
598supported as in standard note.
599popup menu(list[, label ])
600A pop-up menu style dialog. list representing the menu contents can be a list of Unicode strings
601or a list of Unicode string pairs (tuples). The resulting dialog list is then a single-style or a double-
602style list. A single-style list is shown in full; whereas a double-style list shows the items one at a
603time. Returns None if the user cancels the operation.
604selection list(choices[, search field=0 ])
605Executes a dialog that allows the users to select a list item and returns the index of the chosen item,
606or None if the selection is cancelled by the users. choices is a list of Unicode strings. search field
607is 0 (disabled) by default and is optional. Setting it to 1 enables a search field (find pane) that
608facilitates searching for items in long lists. If enabled, the search field appears after you press a
609letter key.
610multi selection list(choices[, style=’checkbox’, search field=0 ])
611Executes a dialog that allows the users to select multiple list items. Returns a tuple of indexes (a
612pair of Unicode strings) of the chosen items, or empty tuple if the selection is cancelled by the users.
613choices is a list of Unicode strings. style is an optional string; the default value being ’checkbox’.
614If ’checkbox’ is given, the list will be a checkbox list, where empty checkboxes indicate what items
615can be marked. The other possible value that can be set for style is ’checkmark’. If ’checkmark’
616is given, the list will be a markable list, which lists items but does not indicate specifically that
617items can be selected. To select items on a markable list, use the Navigation key to browse the
618list and the Edit key to select an item. For example views on checkbox and markable lists, see
619Figure 5.4. search field is 0 (disabled) by default and is optional. Setting it to 1 enables a search
620field (find pane) that facilitates searching for items in long lists. If enabled, the search field is
621always visible with checkbox lists; with markable lists it appears by pressing a letter key.
622Example:
623tuple = appuifw.multi_selection_list(L, style=’checkmark’, search_field=1)
6245.1.4 Application Type
625A single implicit instance of this type always exists when appuifw module is present and can be referred
626to with the name app. New instances cannot be created by a Python program.
627class Application
628Instances of Application type have the following attributes:
62916
630Chapter 5. User Interface and Graphics
631Page 23
632Figure 5.4: Examples of a checkbox list (left) and a markable list (right)
633body
634The UI control that is visible in the application’s main window. Currently either Text, a
635Listbox object, Canvas, or None.
636exit key handler
637A callable object that is called when the user presses the Exit softkey.
638Setting
639exit key handler to None sets it back to the default value.
640menu
641This is a list of the following kinds of items:
642•(title, callback) which creates a regular menu item
643•(title, ((title, callback)[...])) which creates a submenu
644title (Unicode) is the name of the item and callback the associated callable object. The
645maximum allowed number of items in a menu, or items in a submenu, or submenus in a menu
646is 30.
647Example:
648appuifw.app.menu = [(u"Item 1", item1),
649(u"Submenu 1",
650((u"Subitem 1", subitem1),
651(u"Subitem 2", subitem2)))]
652screen
653The screen area used by an application. See Figure 5.3 for example screens. The appearance of
654the application on the screen can be affected by setting one of the following values: ’normal’,
655’large’, and ’full’.
656Examples:
657appuifw.app.screen=’normal’ # (a normal screen with title pane and softkeys)
658appuifw.app.screen=’large’ # (only softkeys visible)
659appuifw.app.screen=’full’
660# (a full screen)
661title
662The title the application that is visible in the application’s title pane. Must be Unicode.
663focus
664A callable object that is called with integer as parameter (0 = focus lost, 1 = focus regained)
665when the application receives focus or it is switched to background. Focus is received e.g. when
666the application is switched from background to foreground or when the focus is regained from
667screensaver. Similarly when the screensaver is displayed, focus is lost.
668Examples:
669>>> import appuifw
670>>> def cb(fg):
6715.1. appuifw — Interface to the S60 GUI framework
67217
673Page 24
674...
675if(fg):
676...
677print "foreground"
678...
679else:
680...
681print "background"
682...
683>>> appuifw.app.focus=cb
684>>> # switch to background, following text is printed from callback:
685>>> background
686>>> # switch to foreground, following text is printed from callback:
687>>> foreground
688Note: An improper callback can cause adverse effects. If you, for example, define a callback
689which takes no parameters you will receive never-ending TypeError exceptions on the Nokia
6906600.
691orientation
692Available only for S60 3rdEd. The orientation of the application. The orientation of the appli-
693cation can be one of the following values: ’automatic’ (this is the default value), ’portrait’
694or ’landscape’.
695Instances of Application type have the following methods:
696activate tab(index)
697Activates the tab index counting from zero.
698full name()
699Returns the full name, in Unicode, of the native application in whose context the current
700Python interpreter session runs.
701uid()
702Returns the UID, in Unicode, of the native application in whose context the current Python
703interpreter session runs.
704set exit()
705Requests a graceful exit from the application as soon as the current script execution returns.
706set tabs(tab texts[,callback=None ])
707Sets tabs with given names on them in the navigation bar; tab texts is a list of Unicode
708strings. When the users navigate between tabs, callback gets called with the index of the
709active tab as an argument. Tabs can be disabled by giving an empty or one-item tab texts
710list.
711layout(layout id)
712Note: Available from S60 2ndEd FP3 onwards (inclusive).
713Returns as a tuple the size and the position of the requested layout id. The logical lay-
714outs are outlined partly in Figure 5.2. The position is given from the top left corner. The
715layout id can be one of the constants defined in module appuifw1:
716EScreen
717Screen.
718EApplicationWindow
719Window that fills the entire screen.
720EStatusPane
721Indicates common components for most of the applications.
722EMainPane
723The application main pane is used in all the applications.
724EControlPane
725Control pane.
726ESignalPane
727The signal pane is used to indicate signal strength.
728EContextPane
729The context pane is used to indicate an active application.
730ETitlePane
731Used to indicate the subject or the name of the main pane content.
7321Descriptions of the values are from the S60 SDK documentation [4].
73318
734Chapter 5. User Interface and Graphics
735Page 25
736EBatteryPane
737The battery pane is used to indicate battery strength.
738EUniversalIndicatorPane
739The universal indicator pane is used to indicate items that require the user’s attention
740while browsing applications.
741ENaviPane
742The navi pane is used to indicate navigation within an application, to provide context
743sensitive information to the user while entering or editing data, or to show additional
744information.
745EFindPane
746A fixed find pane is used with lists instead of the find pop-up window.
747EWallpaperPane
748Wallpaper pane.
749EIndicatorPane
750The universal indicator pane is used to indicate items that require the user’s attention
751while browsing applications.
752EAColumn
753Used generally to display small sized graphics or heading texts.
754EBColumn
755Used generally to display large sized icons or heading texts.
756ECColumn
757Used generally to display data entered by the user. Overlaps with the D column.
758EDColumn
759Used generally to display additional icons. Overlaps with the C column.
760EStaconTop
761Top part of status and control panes in landscape layout.
762EStaconBottom
763Bottom part of status and control panes in landscape layout.
764EStatusPaneBottom
765Bottom part of status pane in landscape layout.
766EControlPaneBottom
767Bottom part of control pane in landscape layout.
768EControlPaneTop
769Top part of control pane in landscape layout.
770EStatusPaneTop
771Top part of status pane in landscape layout.
772Example:
773>>> import appuifw
774>>> appuifw.app.layout(appuifw.EMainPane)
775((176, 144), (0, 44))
776>>> # size and position (x, y) of the main pane in Nokia N70
7775.1.5 Form Type
778Form implements a dynamically configurable, editable multi-field dialog. Form caters for advanced dialog
779use cases with requirements such as free selectability of the combination of fields, possibility of validating
780the user input, and automatically producing the contents of some dialog fields before allowing the closing
781of the dialog.
782class Form(fields[, flags=0 ])
783Creates a Form instance. fields is a list of field descriptors: (label, type[, value]) where
784label is a Unicode string
785type is one of the following strings: ’text’, ’number’, ’date’, ’time’, ’combo’ or ’float’
7865.1. appuifw — Interface to the S60 GUI framework
78719
788Page 26
789value, depending on type: Unicode string, numeric, float (seconds since Unix epoch rounded down to
790the nearest local midnight), float (seconds since local midnight), ([choice label ...], index)
791of float. For ’float’ type the initial value setting might not be shown in the UI.
792Form can also be configured and populated after construction. The configuration flags are visible as
793an attribute. Form implements the list protocol that can be used for setting the form fields, as well as
794obtaining their values after the dialog has been executed.
795Instances of Form type have the following attributes:
796flags
797This attribute holds the values of the various configuration flags. Currently supported flags are:
798FFormEditModeOnly
799When this flag is set, the form remains in edit mode while execute runs.
800FFormViewModeOnly
801When this flag is set, the form cannot be edited at all.
802FFormAutoLabelEdit
803This flag enables support for allowing the end-users to edit the labels of the form fields.
804FFormAutoFormEdit
805This flag enables automatic support for allowing the end-users to add and delete the form
806fields. Note that this is an experimental feature and is not guaranteed to work with all SDK
807versions.
808FFormDoubleSpaced
809When this flag is set, double-spaced layout is applied when the form is executed: one field
810takes two lines, as the label and the value field are on different lines.
811menu
812A list of (title, callback) pairs, where each pair describes an item in the form’s menu bar that
813is active while the dialog is being executed. title (Unicode) is the name of the item and callback
814the associated callable object.
815save hook
816This attribute can be set to a callable object that receives one argument and returns a Boolean
817value. It gets called every time the users want to save the contents of an executing Form dialog.
818A candidate list for new form content - a list representing the currently visible state of the UI - is
819given as an argument. The list can be modified by save hook. If save hook returns True, the
820candidate list is set as the new contents of the form. Otherwise, the form UI is reset to reflect the
821field list contained in Form object.
822Instances of Form type have the following methods:
823execute()
824Executes the dialog by making it visible on the UI.
825insert(index, field descriptor)
826Inserts the field descriptor into the Form before the given index.
827pop()
828Removes the last field descriptor from the Form and returns it.
829length()
830the number of field descriptors in the form.
831The subscript notation f[i] can be used to access or modify the i-th element of the form f. Same
832limitations as discussed above in the context of the flag FFormAutoFormEdit apply to modifying a form
833while it is executing. The ability to change the schema of a form while it is executing is an experimental
834feature.
8355.1.6 Text Type
836Text is a text editor UI control. For examples on the options available with Text, see Figure 5.5.
83720
838Chapter 5. User Interface and Graphics
839Page 27
840Figure 5.5: Examples of the options available for Text type
841Instances of Text type have the following attributes:
842color
843The color of the text. color supports the same color representation models as the graphics
844module. For the supported color representation models, see Section 5.2.
845focus
846A Boolean attribute that indicates the focus state of the control. Editor control also takes the
847ownership of the navigation bar, and this feature is needed to enable the usage of this control in
848applications that use the navigation bar - for example, navigation tabs.
849font
850The font of the text. There are two possible ways to set this attribute:
851•Using a supported Unicode font, for example u"Latin12". Trying to set a font which is not
852supported by the device has no effect. A list of supported fonts can be retrieved by using
853appuifw.available fonts.
854Example, setting font:
855t = appuifw.Text()
856t.font = u"albi17b" # sets font to Albi 17 bold
857t.font = u"LatinPlain12" # sets font to Latin Plain 12
858•Using one of the default device fonts that are associated with the following labels (plain
859strings): ’annotation’, ’title’, ’legend’, ’symbol’, ’dense’, ’normal’ Example,
860setting font:
861t.font = "title" # sets font to the one used in titles
862Example, checking the currently set font:
863unicodeFont = t.font
864The attribute value retrieved is always a Unicode string. If the font has been set with a label, for
865example, ’title’, the attribute will retrieve the font associated with that label.
866highlight color
867The highlight color of the text. highlight color supports the same color representation models
868as the graphics module. For the supported color representation models, see Section 5.2.
869style
870The style of the text. The flags for this attribute are defined in the appuifw module. These flags
871can be combined by using the binary operator |. The flags can be divided into two types: text
872style and text highlight. Text style flags can be freely combined with each other. However, one or
873more text style flags can be combined with only one text highlight flag. The flags are:
874Text style:
8755.1. appuifw — Interface to the S60 GUI framework
87621
877Page 28
878STYLE BOLD
879Enables bold text.
880STYLE UNDERLINE
881Enables underlined text.
882STYLE ITALIC
883Enables italic text.
884STYLE STRIKETHROUGH
885Enables strikethrough.
886Text highlight:
887HIGHLIGHT STANDARD
888Enables standard highlight.
889HIGHLIGHT ROUNDED
890Enables rounded highlight.
891HIGHLIGHT SHADOW
892Enables shadow highlight.
893Only one highlight is allowed to be used at once. Therefore, it is possible to combine only one
894highlight with one or more text styles.
895Examples:
896t = appuifw.Text()
897# These and other similar values and combinations are valid:
898t.style = appuifw.STYLE_BOLD
899t.style = appuifw.STYLE_UNDERLINE
900t.style = appuifw.STYLE_ITALIC
901t.style = appuifw.STYLE_STRIKETHROUGH
902t.style = (appuifw.STYLE_BOLD|
903appuifw.STYLE_ITALIC|
904appuifw.STYLE_UNDERLINE)
905# These values are valid:
906t.style = appuifw.HIGHLIGHT_STANDARD
907t.style = appuifw.HIGHLIGHT_ROUNDED
908t.style = appuifw.HIGHLIGHT_SHADOW
909# This combination is NOT valid:
910# Invalid code, do not try!
911t.style = (appuifw.HIGHLIGHT_SHADOW|appuifw.HIGHLIGHT_ROUNDED)
912Instances of Text type have the following methods:
913add(text)
914Inserts the Unicode string text to the current cursor position.
915bind(event code, callback)
916Binds the callable Python object callback to event event code. The key codes are defined in the
917key codes library module. The call bind(event code, None) clears an existing binding. In the
918current implementation the event is always passed also to the underlying native UI control.
919clear()
920Clears the editor.
921delete([pos=0, length=len() ])
922Deletes length characters of the text held by the editor control, starting from the position pos.
923get pos()
924Returns the current cursor position.
925len()
926Returns the length of the text string held by the editor control.
92722
928Chapter 5. User Interface and Graphics
929Page 29
930get([pos=0, length=len() ])
931Retrieves length characters of the text held by the editor control, starting from the position pos.
932set(text)
933Sets the text content of the editor control to Unicode string text.
934set pos(cursor pos)
935Sets the cursor to cursor pos.
9365.1.7 Listbox Type
937Figure 5.6: Listbox with icons
938An instance of this UI control type is visible as a listbox, also known as a list in Symbian, that can be
939configured to be a single-line item or a double-item listbox. Figure 5.6 shows a single-line item Listbox
940with icons. For more information on the MBM and MIF formats, see Section 5.1.8.
941class Listbox(list, callback)
942Creates a Listbox instance. A callable object callback gets called when a listbox selection has
943been made. list defines the content of the listbox and can be one of the following:
944•A normal (single-line item) listbox: a list of Unicode strings, for example [unicode string
945item1, unicode string item2]
946•A double-item listbox:
947a two-element tuple of Unicode strings , for exam-
948ple [(unicode string item1, unicode string item1description), (unicode string
949item2, unicode string item2description)]
950•A normal (single-line item) listbox with graphics: a two-element tuple consisting of
951a Unicode string and an Icon object, for example [(unicode string item1, icon1),
952(unicode string item2, icon2)].
953•A
954double-item
955listbox
956with
957graphics:
958a three-element tuple consisting of
959two Unicode strings and one
960Icon
961object, for example
962[(unicode string
963item1, unicode string item1description, icon1), (unicode string item2,
964unicode string item2description, icon2)]
965Example: To produce a normal (single-line item) listbox with graphics:
966icon1 = appuifw.Icon(u"z:\\system\\data\\avkon.mbm", 28, 29)
967icon2 = appuifw.Icon(u"z:\\system\\data\\avkon.mbm", 40, 41)
968entries = [(u"Signal", icon1),
969(u"Battery", icon2)]
970lb = appuifw.Listbox(entries, lbox_observe)
971Instances of Listbox type have the following methods and properties:
9725.1. appuifw — Interface to the S60 GUI framework
97323
974Page 30
975bind(event code, callback)
976Binds the callable Python object callback to event event code. The key codes are defined in the
977key codes library module. The call bind(event code, None) clears an existing binding. In the
978current implementation the event is always passed also to the underlying native UI control.
979current()
980Returns the currently selected item’s index in the Listbox.
981set list(list[, current ])
982Sets the Listbox content to a list of Unicode strings or a list of tuples of Unicode strings. The
983accepted structures of list are the same as in the Listbox constructor. The optional argument
984current is the index of the focused list item.
985size
986The size of the Listbox as a tuple (width, height) - Read only. Only on S60 3rd Ed, and higher.
987position
988The coordinates (as a tuple) of the top left corner of the Listbox - Read only. Only on S60 3rd
989Ed. and higher.
9905.1.8 Icon Type
991An instance of Icon type encapsulates an icon to be used together with a Listbox instance. Note that
992currently Icon can only be used with Listbox (see Section 5.1.7).
993MBM is the native Symbian OS format used for pictures. It is a compressed file format where the files
994can contain several bitmaps and can be referred to by a number. An .mbg file is the header file usually
995associated with an .mbm file, which includes symbolic definitions for each bitmap in the file. For example,
996an ‘avkon.mbm’ file has an associated index file called ‘avkon.mbg’, which is included in S60 SDKs. For
997more information on the MBM format and the bitmap converter tool, see [4] and search the topics with
998the key term ”How to provide Icons”; this topic also points you to the Bitmap Converter tool that can
999be used for converting bitmaps into the MBM format.
1000S60 2nd Edition FP3 introduces a new format for icons called Multi-Image File (MIF). This format is
1001very similar to the MBM format and also contains several compressed files. The files to be compressed
1002should be in Scalable Vector Graphics Tiny (SVG-T) format. For more information on the SVG format,
1003see Scalable Vector Graphics (SVG) 1.1 Specification [10].
1004class Icon(filename, bitmap, bitmapMask)
1005Creates an icon. filename is a Unicode file name and must include the whole path. Note that
1006MBM and MIF (MIF only in S60 2nd Edition FP3) are the only file formats supported. bitmap
1007and bitmapMask are integers that represent the index of the icon and icon mask inside that file
1008respectively.
1009Example: The following builds an icon with the standard signal symbol:
1010icon = appuifw.Icon(u"z:\\system\\data\\avkon.mbm", 28, 29)
10115.1.9 Content handler Type
1012An instance of Content handler handles data content by its MIME type.
1013class Content handler([callback ])
1014Creates a Content handler instance. A Content handler handles data content by its MIME
1015type. The optional callback is called when the embedded handler application started with the open
1016method finishes.
1017Instances of Content handler type have the following methods:
1018open(filename)
1019Opens the file filename (Unicode) in its handler application if one has been registered for the
1020particular MIME type. The handler application is embedded in the caller’s thread. The call to
102124
1022Chapter 5. User Interface and Graphics
1023Page 31
1024this function returns immediately. When the handler application finishes, the callback that was
1025given to the Content handler constructor is called.
1026open standalone(filename)
1027Opens the file filename (Unicode) in its handler application if one has been registered for the
1028particular MIME type. The handler application is started in its own process. The call to this
1029function returns immediately. Note that callback is not called for applications started with this
1030method.
10315.1.10 Canvas Type
1032Canvas is a UI control that provides a drawable area on the screen and support for handling raw key
1033events. Canvas supports the standard drawing methods that are documented in Section 5.2.
1034class Canvas([redraw callback=None, event callback=None, resize callback=None ])
1035Constructs a Canvas. The optional parameters are callbacks that are called when specific events
1036occur.
1037Note: Watch out for cyclic references here. For example, if the callbacks are methods of an object
1038that holds a reference to the Canvas, a reference cycle is formed that must be broken at cleanup
1039time or the Canvas will not be freed.
1040redraw callback is called whenever a part of the Canvas has been obscured by something, is then
1041revealed, and needs to be redrawn. This can typically happen, for example, when the user switches
1042away from the Python application and back again, or after displaying a pop-up menu. The callback
1043takes as its argument a four-element tuple that contains the top-left and the bottom-right corner
1044of the area that needs to be redrawn. In many cases redrawing the whole Canvas is a reasonable
1045option.
1046event callback is called whenever a raw key event is received. There are three kinds of key
1047events: EEventKeyDown, EEventKey, and EEventKeyUp. When a user presses a key down, events
1048EEventKeyDown and EEventKey are generated. When the key is released, an EEventKeyUp event is
1049generated.
1050The argument to the event callback is a dictionary that contains the following data for key events:
1051•’type’: one of EEventKeyDown, EEventKey, or EEventKeyUp
1052•’keycode’: the keycode of the key
1053•’scancode’: the scancode of the key
1054•’modifiers’: the modifiers that apply to this key event
1055Each key on the keyboard has one or more scancodes and zero or more keycodes associated with it.
1056A scancode represents the physical key itself and a keycode is the result of state-related operating
1057system defined processing done on the key. For keys that correspond to a symbol in the current
1058character set of the phone, the keycode is equal to the code of the corresponding symbol in that
1059character set. For example, if you are using the Nokia Wireless Keyboard (SU-8W), pressing the
1060key A will always produce the scancode 65 (ASCII code for an upper case A), but the keycode
1061could be either 65 or 91 (ASCII code for a lower case A) depending on whether or not the Shift
1062key is pressed or Caps Lock is active.
1063The key codes module contains definitions for the keycodes and scancodes. See Figure 5.7 for the
1064codes of the most common keys on the phone keypad.
1065Some keys are handled in a special way:
1066•A short press of the Edit key causes it to stay down, meaning that no EEventKeyUp event is
1067sent. The event is only sent after a long press.
1068•Detecting presses of the Voice tags key or the Power key is not supported.
1069•If the right softkey is pressed, the appuifw.app.exit key handler callback is always exe-
1070cuted.
10715.1. appuifw — Interface to the S60 GUI framework
107225
1073Page 32
1074Key Keycode
1075Scancode
10761.
1077EKeyLeftSoftkey
1078EScancodeLeftSoftkey
10792.
1080EKeyYes
1081EScancodeYes
10823.
1083EKeyMenu
1084EScancodeMenu
10854.
1086EKey0...9
1087EScancode0...9
10885.
1089EKeyStar
1090EScancodeStar
10916.
1092EKeyLeftArrow
1093EScancodeLeftArrow
10947.
1095EKeyUpArrow
1096EScancodeUpArrow
10978.
1098EKeySelect
1099EScancodeSelect
11009.
1101EKeyRightArrow
1102EScancodeRightArrow
110310.
1104EKeyDownArrow
1105EScancodeDownArrow
110611.
1107EKeyRightSoftkey EScancodeRightSoftkey
110812.
1109EKeyNo
1110EScancodeNo
111113.
1112EKeyBackspace
1113EScancodeBackspace
111414.
1115EKeyEdit
1116EScancodeEdit
111715.
1118EKeyHash
1119EScancodeHash
1120Figure 5.7: Keycodes and scancodes for phone keys usable from Python applications
1121There is no way to prevent the standard action of the Hang-up key, the Menu key, the Power key
1122or the Voice tags key from taking place.
1123resize callback is called when screen size is changed when the Canvas rect size has been changed.
1124The callback takes as its argument a two-element tuple that contains the new clientRect width and
1125height.
1126Instances of Canvas type have the following attribute:
1127size
1128A two-element tuple that contains the current width and height of the Canvas as integers.
1129Instances of Canvas type have the same standard drawing methods that are documented in Section 5.2.
11305.1.11 InfoPopup Type
1131Note: Available from S60 3rd Ed onwards (inclusive).
1132An instance of InfoPopup type encapsulates an UI tip widget. This widget can be placed on top of other
1133widgets to provide e.g. usage information to the user. The widget disappears as soon as the device’s
113426
1135Chapter 5. User Interface and Graphics
1136Page 33
1137user presses any key or when the timer behind the InfoPopup is triggered.
1138class InfoPopup()
1139Creates an InfoPopup.
1140show(text, [(x coord, y coord), time shown, time before, alignment ])
1141Show text (Unicode) in the InfoPopup. The optional parameters are the location (a tuple from
1142the upper left corner), the time the popup is visible, time shown (in milliseconds), the time before
1143the popup, time before (in milliseconds) and the alignment of the popup.
1144The default values are: the coordinates (0, 0), time shown 5 seconds, time before 0 seconds and
1145for the alignment appuifw.EHLeftVTop.
1146The alignment can be one of the constants defined in module appuifw2:
1147EHLeftVTop
1148Object is left and top aligned.
1149EHLeftVCenter
1150Object is left aligned and centred vertically.
1151EHLeftVBottom
1152Object is left aligned and at the bottom.
1153EHCenterVTop
1154Object is centre aligned horizontally and at the top.
1155EHCenterVCenter
1156Object is centred horizontally and vertically.
1157EHCenterVBottom
1158Object is centred horizontally and at the bottom.
1159EHRightVTop
1160Object is right and top aligned.
1161EHRightVCenter
1162Object is right aligned and centred vertically.
1163EHRightVBottom
1164Object is right aligned and at the bottom.
1165hide()
1166Hides the popup immediately.
1167Example:
1168>>> import appuifw
1169>>> i=appuifw.InfoPopup()
1170>>> i.show(u"Here is the tip.", (0, 0), 5000, 0, appuifw.EHRightVCenter)
1171>>>
11725.2 graphics — A graphics related services package
1173The graphics module provides access to the graphics primitives and image loading, saving, resizing, and
1174transformation capabilities provided by the Symbian OS.
1175The module is usable from both graphical Python applications and background Python processes. How-
1176ever, background processes have some restrictions, namely that plain string symbolic font names are not
1177supported in background processes since background processes have no access to the UI framework (see
1178also Section 5.2.4).
1179For an example on using this module, see [6].
1180Functions Image.open and Image.inspect and Image object methods load, save, resize, and
1181transpose are not available for S60 1st Edition.
11822Descriptions of the values are from the S60 SDK documentation [4].
11835.2. graphics — A graphics related services package
118427
1185Page 34
11865.2.1 Module Level Functions
1187The following free functions - functions that do not belong to any class - are defined in the graphics
1188module:
1189screenshot()
1190Takes a screen shot and returns the image in Image format.
11915.2.2 Image Class Static Methods
1192The following Image class static methods are defined in the graphics module:
1193Image.new(size[, mode=’RGB16’ ])
1194Creates and returns a new Image object with the given size and mode. size is a two-element tuple.
1195mode specifies the color mode of the Image to be created. It can be one of the following:
1196•’1’: Black and white (1 bit per pixel)
1197•’L’: 256 gray shades (8 bits per pixel)
1198•’RGB12’: 4096 colors (12 bits per pixel)
1199•’RGB16’: 65536 colors (16 bits per pixel)
1200•’RGB’: 16.7 million colors (24 bits per pixel)
1201Image.open(filename)
1202Note: Not supported in S60 1st Edition!
1203Returns a new Image object (mode RGB16) that contains the contents of the named file. The
1204supported file formats are JPEG and PNG. The file format is automatically detected based on file
1205contents. filename should be a full path name.
1206Image.inspect(filename)
1207Note: Not supported in S60 1st Edition!
1208Examines the given file and returns a dictionary of the attributes of the file. At present the
1209dictionary contains only the image size in pixels as a two-element tuple, indexed by key ’size’.
1210filename should be a full path name.
12115.2.3 Image Objects
1212An Image object encapsulates an in-memory bitmap.
1213Note on asynchronous methods: Methods resize, transpose, save, and load have an optional callback
1214argument. If the callback is not given, the method call is synchronous; when the method returns,
1215the operation is complete or an exception has been raised. If the callback is given, the method calls
1216are asynchronous. If all parameters are valid and the operation can start, the method call will return
1217immediately. The actual computation then proceeds in the background. When it is finished, the callback
1218is called with an error code as the argument. If the given code is 0, the operation completed without
1219errors, otherwise an error occurred.
1220It is legal to use an unfinished image as a source in a blit operation; this will use the image data as it is
1221at the moment the blit is made and may thus show an incomplete result.
1222Image objects have the following methods:
1223resize(newsize[, callback=None, keepaspect=0 ])
1224Note: Not supported in S60 1st Edition!
1225Returns a new image that contains a resized copy of this image. If keepaspect is set to 1, the resize
1226will maintain the aspect ratio of the image, otherwise the new image will be exactly the given size.
1227If callback is given, the operation is asynchronous, and the returned image will be only partially
1228complete until callback is called.
122928
1230Chapter 5. User Interface and Graphics
1231Page 35
1232transpose(direction[, callback=None ])
1233Note: Not supported in S60 1st Edition!
1234Creates a new image that contains a transformed copy of this image. The direction parameter can
1235be one of the following:
1236•FLIP LEFT RIGHT: Flips the image horizontally, exchanging left and right edges.
1237•FLIP TOP BOTTOM: Flips the image vertically, exchanging top and bottom edges.
1238•ROTATE 90: Rotates the image 90 degrees counterclockwise.
1239•ROTATE 180: Rotates the image 180 degrees.
1240•ROTATE 270: Rotates the image 270 degrees counterclockwise.
1241If callback is given, the operation is asynchronous and the returned image will be only partially
1242complete until callback is called.
1243load(filename[, callback=None ])
1244Note: Not supported in S60 1st Edition!
1245Replaces the contents of this Image with the contents of the named file, while keeping the current
1246image mode. This Image object must be of the same size as the file to be loaded.
1247If callback is given, the operation is asynchronous and the loaded image will be only partially
1248complete until callback is called. filename should be a full path name.
1249save(filename[,callback=None, format=None, quality=75, bpp=24, compression=’default’ ])
1250Note: Not supported in S60 1st Edition!
1251Saves the image into the given file. The supported formats are JPEG and PNG. If format is not
1252given or is set to None, the format is determined based on the file name extension: ’.jpg’ or
1253’.jpeg’ are interpreted to be in JPEG format and ’.png’ to be in PNG format. filename should
1254be a full path name.
1255When saving in JPEG format, the quality argument specifies the quality to be used and can range
1256from 1 to 100.
1257When saving in PNG format, the bpp argument specifies how many bits per pixel the resulting file
1258should have, and compression specifies the compression level to be used.
1259Valid values for bpp are:
1260•1: Black and white, 1 bit per pixel
1261•8: 256 gray shades, 8 bits per pixel
1262•24: 16.7 million colors, 24 bits per pixel
1263Valid values for compression are:
1264•’best’: The highest possible compression ratio, the slowest speed
1265•’fast’: The fastest possible saving, moderate compression
1266•’no’: No compression, very large file size
1267•’default’: Default compression, a compromise between file size and speed
1268If callback is given, the operation is asynchronous. When the saving is complete, the callback is
1269called with the result code.
1270stop()
1271Stops the current asynchronous operation, if any. If an asynchronous call is not in progress, this
1272method has no effect.
1273Image objects have the following attribute:
1274size
1275A two-element tuple that contains the size of the Image. Read-only.
12765.2. graphics — A graphics related services package
127729
1278Page 36
12795.2.4 Common Features of Drawable Objects
1280Objects that represent a surface that can be drawn on support a set of common drawing methods,
1281described in this section. At present there are two such objects: Canvas from the appuifw module and
1282Image from the graphics module.
1283Options
1284Many of these methods support a set of standard options. This set of options is as follows:
1285• outline: The color to be used for drawing outlines of primitives and text. If None, the outlines of
1286primitives are not drawn.
1287• fill: The color to be used for filling the insides of primitives. If None, the insides of primitives are
1288not drawn. If pattern is also specified, fill specifies the color to be used for areas where the pattern
1289is white.
1290• width: The line width to be used for drawing the outlines of primitives.
1291• pattern: Specifies the pattern to be used for filling the insides of primitives. If given, this must be
1292either None or a 1-bit (black and white) Image.
1293Coordinate representation
1294The methods accept an ordered set of coordinates in the form of a coordinate sequence. Coordinates
1295can be of type int, long, or float. A valid coordinate sequence is a non-empty sequence of either
1296• Alternating x and y coordinates. In this case the sequence length must be even, or
1297• Sequences of two elements, that specify x and y coordinates.
1298Examples of valid coordinate sequences:
1299• (1, 221L, 3, 4, 5.85, -3): A sequence of three coordinates
1300• [(1,221L),(3,4),[5.12,6]): A sequence of three coordinates
1301• (1,5): A sequence of one coordinate
1302• [(1,5)]: A sequence of one coordinate
1303• [[1,5]]: A sequence of one coordinate
1304Examples of invalid coordinate sequences:
1305Invalid code, do not use!
1306• []: An empty sequence
1307• (1,2,3): Odd number of elements in a flat sequence
1308• [(1,2),(3,4),None]: Contains an invalid element
1309• ([1,2],3,4): Mixing the flat and nested form is not allowed
131030
1311Chapter 5. User Interface and Graphics
1312Page 37
1313Color representation
1314All methods that take color arguments accept the following two color representations:
1315• A three-element tuple of integers in the range from 0 to 255 inclusive, representing the red, green,
1316and blue components of the color.
1317• An integer of the form 0xrrggbb, where rr is the red, gg the green, and bb the blue component of
1318the color.
1319For 12 and 16 bit color modes the color component values are simply truncated to the lower bit depth. For
1320the 8-bit grayscale mode images the color is converted into grayscale using the formula (2*r+5*g+b)/8,
1321rounded down to the nearest integer. For 1-bit black and white mode images the color is converted into
1322black (0) or white (1) using the formula (2*r+5*g+b)/1024.
1323Examples of valid colors:
1324• 0xffff00: Bright yellow
1325• 0x004000: Dark green
1326• (255,0,0): Bright red
1327• 0: Black
1328• 255: Bright blue
1329• (128,128,128): Medium gray
1330Examples of invalid colors:
1331Invalid code, do not use!
1332• (0,0.5,0.9): Floats are not supported
1333• ’#ff80c0’: The HTML color format is not supported
1334• (-1,0,1000): Out-of-range values
1335• (1,2): The sequence is too short
1336• [128,128,192]: This is not a tuple
1337Font specifications
1338A font can be specified in three ways:
1339• None, meaning the default font
1340• a Unicode string that represents a full font name, such as u’LatinBold19’
1341• a plain string symbolic name that refers to a font setting currently specified by the UI framework
1342• as a two or three element tuple, where
1343– the first element is the font name (unicode or string) or None for default font
1344– the second element is the font height in pixels or None for default size
1345– the third (optional) element is the flags applied to the font or None for default options.
1346The flags are the following:
1347• FONT BOLD bold
13485.2. graphics — A graphics related services package
134931
1350Page 38
1351• FONT ITALIC italic
1352• FONT SUBSCRIPT subscript
1353• FONT SUPERSCRIPT superscript
1354• FONT ANTIALIAS forces the font to be antialiased
1355• FONT NO ANTIALIAS forces the font to not be antialiased
1356You can combine the flags with the binary or operator “—”. For example, the flags setting
1357FONT BOLD|FONT ITALIC will produce text that is both bold and italic.
1358Note: Antialiasing support is only available for scalable fonts.
1359You can obtain a list of all available fonts with the appuifw module function available fonts.
1360The symbolic names for UI fonts are:
1361• ’normal’
1362• ’dense’
1363• ’title’
1364• ’symbol’
1365• ’legend’
1366• ’annotation’
1367Since background processes have no access to the UI framework, these symbolic names are not supported
1368in them. You need to specify the full font name.
1369Common Methods of Drawable Objects
1370line(coordseq[, <options>])
1371Draws a line connecting the points in the given coordinate sequence. For more information about
1372the choices available for options, see Section 5.2.4.
1373polygon(coordseq[, <options>])
1374Draws a line connecting the points in the given coordinate sequence, and additionally draws an
1375extra line connecting the first and the last point in the sequence. If a fill color or pattern is specified,
1376the polygon is filled with that color or pattern. For more information about the choices available
1377for options, see Section 5.2.4.
1378rectangle(coordseq[, <options>])
1379Draws rectangles between pairs of coordinates in the given sequence. The coordinates specify the
1380top-left and the bottom- right corners of the rectangle. The sequence must have an even number
1381of coordinates. For more information about the choices available for options, see Section 5.2.4.
1382ellipse(coordseq[, <options>])
1383Draws ellipses between pairs of coordinates in the given sequence. The coordinates specify the top-
1384left and bottom-right corners of the rectangle inside which the ellipse is contained. The sequence
1385must have an even number of coordinates. For more information about the choices available for
1386options, see Section 5.2.4.
1387pieslice(coordseq, start, end[, <options>])
1388Draws pie slices contained in ellipses between pairs of coordinates in the given sequence. The start
1389and end parameters are floats that specify the start and end points of pie slice as the starting and
1390ending angle in radians. The angle 0 is to the right, the angle pi/2 is straight up, pi is to the left
1391and-pi/2 is straight down. coordseq is interpreted the same way as for the ellipse method. For
1392more information about the choices available for options, see Section 5.2.4.
139332
1394Chapter 5. User Interface and Graphics
1395Page 39
1396arc(coordseq, start, end[, <options>])
1397Draws arcs contained in ellipses between pairs of coordinates in the given sequence. The start
1398and end parameters are floats that specify the start and end points of pie slice as the starting and
1399ending angle in radians. The angle 0 is to the right, the angle pi/2 is straight up, pi is to the left
1400and-pi/2 is straight down. coordseq is interpreted the same way as for the ellipse method. For
1401more information about the choices available for options, see Section 5.2.4.
1402point(coordseq[, <options>])
1403Draws points in each coordinate in the given coordinate sequence. If the width option is set to
1404greater than 1, draws a crude approximation of a circle filled with the outline color in the locations.
1405Note that the approximation is not very accurate for large widths; use the ellipse method if you
1406need a precisely formed circle. For more information about the choices available for options, see
1407Section 5.2.4.
1408clear([color=0xffffff ])
1409Sets the entire surface of the drawable to the given color, white by default.
1410text(coordseq, text[fill=0, font=None ])
1411Draws the given text in the points in the given coordinate sequence with the given color (default
1412value is black) and the given font. The font specification format is described above.
1413measure text(text[font=None, maxwidth=-1, maxadvance=-1 ])
1414Measures the size of the given text when drawn using the given font. Optionally you can specify
1415the maximum width of the text or the maximum amount the graphics cursor is allowed to move
1416(both in pixels).
1417Returns a tuple of three values:
1418•the bounding box for the text as a 4-tuple: (topleft-x, topleft-y, bottomright-x, bottomright-y)
1419•the number of pixels the graphics cursor would move to the right
1420•the number of characters of the text that fits into the given maximum width and advance
1421blit(image[,target=(0,0), source=((0,0),image.size), mask=None, scale=0 ])
1422Copies the source area from the given image to the target area in this drawable. The source area
1423is copied in its entirety if mask is not given or is set to None. If the mask is given, the source area
1424is copied where the mask is white. mask can be either None, a 1-bit (black and white) Image or
1425(on S60 2nd edition FP2 and later) a grayscale Image, and must be of the same size as the source
1426image. A grayscale mask acts as an alpha channel, i.e. partial transparency.
1427target and source specify the target area in this image and the source area in the given source. They
1428are coordinate sequences of one or two coordinates. If they specify one coordinate, it is interpreted
1429as the upper-left corner for the area; if they specify two coordinates, they are interpreted as the
1430top-left and bottom-right corners of the area.
1431If scale is other than zero, scaling is performed on the fly while copying the source area to the
1432target area. If scale is zero, no scaling is performed, and the size of the copied area is clipped to
1433the smaller of source and target areas.
1434Note that a blit operation with scaling is slower than one without scaling. If you need to blit the
1435same Image many times in a scaled form, consider making a temporary Image of the scaling result
1436and blitting it without scaling. Note also that the scaling performed by the blit operation is much
1437faster but of worse quality than the one done by the resize method, since the blit method does
1438not perform any antialiasing.
14395.3 camera — Interface for taking photographs and video recording
1440Note: Not available for S60 1st Edition.
1441The camera module enables taking photographs and video recording.
1442The following data items for state information are available in camera:
14435.3. camera — Interface for taking photographs and video recording
144433
1445Page 40
1446EOpenComplete
1447The opening of the video clip has succeeded.
1448ERecordComplete
1449The video recording has completed (not called on explicit stop recording call).
1450EPrepareComplete
1451The device is ready to begin video recording.
1452The camera module has the following functions3:
1453cameras available()
1454Returns the number of cameras available in the device.
1455image modes()
1456Returns the image modes supported in the device as a list of strings, for example: [’RGB12’,
1457’RGB’, ’JPEG Exif’, ’RGB16’].
1458image sizes()
1459Returns the image sizes (resolution) supported in the device as a list of (x, y) tuples, for example:
1460[(640, 480), (160, 120)].
1461flash modes()
1462Returns the flash modes available in the device as a list of strings.
1463max zoom()
1464Returns the maximum digital zoom value supported in the device as an integer.
1465exposure modes()
1466Returns the exposure settings supported in the device as a list of strings.
1467white balance modes()
1468Returns the white balance modes available in the device as a list of strings.
1469take photo([mode, size, flash, zoom, exposure, white balance, position ])
1470Takes a photograph and returns the image in:
14711.Image format (for more information on Image format, see Chapter 5.2 graphics Module) or
14722.Raw JPEG data4.
1473The settings listed below describe all settings that are supported by the camera module. You can
1474retrieve the mode settings available for your device by using the appropriate functions listed at the
1475beginning of this chapter.
1476•mode is the display mode of the image. The default value is ’RGB16’. The following display
1477modes are supported for the Image format pictures taken:
1478–’RGB12’: 4096 colors (12 bits per pixel)
1479–’RGB16’: 65536 colors (16 bits per pixel). Default value, always supported
1480–’RGB’: 16.7 million colors (24 bits per pixel)
1481For the JPEG data format images the following modes are supported:
1482–’JPEG Exif’: JPEG Exchangeable image file format
1483–’JPEG JFIF’: JPEG File Interchange Format
1484Note that there is variety between the devices and the supported formats.
1485•size is the resolution of the image. The default value is (640, 480). The following sizes are
1486supported, for example, in Nokia 6630: (1280, 960), (640, 480) and (160, 120).
1487•flash is the flash mode setting. The default value is ’none’. The following flash mode settings
1488are supported:
1489–’none’
1490No flash. Default value, always supported
14913Descriptions for some of the values are based on information found in S60 SDK documentation [4]
14924For more information, see e.g. http://en.wikipedia.org/wiki/JPEG.
149334
1494Chapter 5. User Interface and Graphics
1495Page 41
1496–’auto’
1497Flash will automatically fire when required
1498–’forced’
1499Flash will always fire
1500–’fill in’
1501Reduced flash for general lighting
1502–’red eye reduce’
1503Red-eye reduction mode
1504•zoom is the digital zoom factor. It is assumed to be on a linear scale from 0 to the maximum
1505zoom value allowed in the device. The default value is 0, meaning that zoom is not used.
1506•exposure is the exposure adjustment of the device. Exposure is a combination of lens aperture
1507and shutter speed used in taking a photograph. The default value is ’auto’. The following
1508exposure modes are supported:
1509–’auto’
1510Sets exposure automatically. Default value, always supported
1511–’night’
1512Night-time setting for long exposures
1513–’backlight’
1514Backlight setting for bright backgrounds
1515–’center’
1516Centered mode for ignoring surroundings
1517•white balance can be used to adjust white balance to match the main source of light. The
1518term white balance refers to the color temperature of the current light. A digital camera
1519requires a reference point to represent white. It will then calculate all the other colors based
1520on this white point. The default value for white balance is ’auto’ and the following white
1521balance modes are supported:
1522–’auto’
1523Sets white balance automatically. Default value, always supported
1524–’daylight’
1525Sets white balance to normal daylight
1526–’cloudy’
1527Sets white balance to overcast daylight
1528–’tungsten’
1529Sets white balance to tungsten filament lighting
1530–’fluorescent’
1531Sets white balance to fluorescent tube lighting
1532–’flash’
1533Sets white balance to flash lighting
1534•position is the camera used if the device, such as Nokia 6680, has several cameras. In Nokia
15356680, the camera pointing to the user of the device is located in position 1, whereas the one
1536pointing away from the user is located in position 0. The default position is 0.
1537If some other application is using the camera, this operation fails, with error SymbianError:
1538KErrInUse. Invoking this function right after the device boot, might result in SymbianError:
1539KErrNotReady error.
1540start finder(callable[, backlight on=1, size=main pane size ])
1541Starts the camera viewfinder and binds a callback to receive Image format feed. When a new
1542viewfinder frame is ready the callback is invoked with the Image as parameter.
1543The optional parameter backlight on determines whether the device backlight is kept on when
1544the camera view finder is in operation. By default, the backlight is on (1 = on, 0 = off).
1545The optional parameter size (of type tuple, e.g. (176, 144)) can be used to change the size of
1546the Image received in the callback. The default size is the same as the application’s main pane
1547size.
1548Example view finder code:
15495.3. camera — Interface for taking photographs and video recording
155035
1551Page 42
1552>>> import appuifw
1553>>> import camera
1554>>> def cb(im):
1555...
1556appuifw.app.body.blit(im)
1557...
1558>>> import graphics
1559>>> appuifw.app.body=appuifw.Canvas()
1560>>> camera.start_finder(cb)
1561>>>
1562stop finder()
1563Stops the viewfinder.
1564release()
1565Releases the camera – After invocation other applications can access the camera hardware.
1566start record(filename, callable)
1567Starts video recording. filename is the file where the video clip is saved and callable will be called
1568with possible error code (int) and status information (see data in module camera) as parameter.
1569Prior calling this function, the view finder needs to be started.
1570stop record()
1571Stops the video recording.
15725.4 keycapture — Interface for global capturing of key events.
1573The keycapture module offers an API for global capturing of key events. The keycapture module
1574provides the KeyCapturer object as a tool for listening the events.
1575The KeyCapturer object uses a callback method to report the key events. The callback method is called
1576each time any of the specified keys is pressed.
1577Currently the keycapture module does not support capturing separate key-up or key-down events.
1578Note: Keycapture module requires capability SwEvent to work in 3rd Edition devices.
15795.4.1 Module Level Constants
1580The following constants are defined in the keycapture module:
1581all keys
1582A list of all key codes defined in the key codes module.
15835.4.2 KeyCapturer objects
1584KeyCapturer object takes a callback method as a mandatory parameter to its constructor. The callback
1585method must have one single parameter for forwarding the key code of the captured key.
1586There can be several KeyCapturer objects existing at the same time.
1587KeyCapturer object has following methods and properties:
1588keys
1589List of keys to be captured. Can be read and written.
1590Example:
1591keys = (key_codes.EkeyUpArrow,)
1592keys = keycapture.all_keys
159336
1594Chapter 5. User Interface and Graphics
1595Page 43
1596forwarding
1597Specifies whether captured key events are forwarded to other applications or not. Either has value
15981 or 0. Can be read and written.
1599start()
1600Starts the actual capturing of key events.
1601stop()
1602Stops the actual capturing of key events.
1603last key()
1604Returns last key code that is captured.
16055.5 topwindow — Interface for creating windows that are shown on top of
1606other applications.
1607The topwindow module offers an API for creating windows that are shown on top of other applications
1608and managing the content of these windows. Images can be inserted into the windows and the background
1609color, visibility, corner type and shadow of the window can be manipulated.
1610topwindow extension does not provide sophisticated drawing capabilities by any means but rather relies
1611on services provided by the graphics extension: topwindow allows graphics Image objects to be put
1612into the windows that are represented by TopWindow objects.
1613TopWindow object provides mainly only two services: TopWindow objects can be shown or hidden and
1614Images can be put into the windows. However, several images can be added into one TopWindow object
1615and several TopWindow objects can be created and shown. Since the images can be manipulated using
1616the graphics extension this makes it possible to create many kind of content to the TopWindow objects.
16175.5.1 TopWindow objects
1618class TopWindow()
1619Create a TopWindow object.
1620TopWindow objects have the following methods and properties:
1621show()
1622Shows the window. The window is not shown until show() is called.
1623hide()
1624Hides the window.
1625add image(image, position)
1626Inserts an image object graphics.Image into the window. The position of the image is specified
1627by the ( position) parameter. If only the coordinates of the top left corner are specified, like (x1,
1628y1) the image is not resized. If four coordinates are given, like(x1, y1, x2, y2), the image is resized
1629to fit to the specified area. Example:
1630add_image(image, (10,20))
1631add_image(image, (10,20,20,30))
1632remove image(image[,position ])
1633Removes the image from the window. Mandatory parameter image must be a graphics.Image
1634object. Parameter position may specify the top-left corner coordinates of the image or the rectan-
1635gular area of the image. If only image parameter is given, all the pictures representing this image
1636object are removed from the window. If both parameters are given, only the picture that matches
1637both parameters is removed.
1638Example:
1639remove_image(image)
1640remove_image(image, (10,10))
16415.5. topwindow — Interface for creating windows that are shown on top of other applications.
164237
1643Page 44
1644remove_image(image, (10,10,20,20))
1645position
1646Specifies the coordinates of the top left corner of the window. Can be read and written.
1647Example:
1648position = (10, 20)
1649size
1650Specifies the size of the window. Can be read and written.
1651Example:
1652size = (100, 200)
1653images
1654The images inserted into the window. Defined as a list of tuple objects. Each tuple contains a
1655graphics.Image object and the position of the image. The position may specify the top-left coor-
1656dinate of the image and optionally also the bottom-right coordinate of the image. Parameter (x,y)
1657specifies the top-left coordinate, but does not resize the image while parameter like (x1,y1,x2,y2)
1658specifies both the top-left and bottom-right coordinates and possibly also resizes the image. Can
1659be read and written. Also see the add image() and remove image() methods.
1660Example:
1661images = [(image1,(x1,y1)), (image2,(x1,y1,x2,y2)), (image3,(50,50,100,100))]
1662sets the window content to be 3 images. image2 and image3 are possibly resized while the image1
1663is not)
1664shadow
1665Specifies if the shadow of the window is shown and the length of the shadow. Can be read and
1666written. Setting shadow = 0 makes the shadow invisible.
1667Example: shadow = 5
1668corner type
1669Specifies the corner type of the window. Can be read and written. Corner type can be one of the
1670following values:
1671•square
1672•corner1
1673•corner2
1674•corner3
1675•corner5
1676Example: corner type = square
1677maximum size
1678Returns the maximum size of the window as a tuple (width, height). Read only property.
1679background color
1680The background color of the window as an integer (e.g. 0xaabbcc). The two greatest hexadecimal
1681digits specify the red, the next two specify the blue and the last ones specify the green color. Can
1682be read and written.
1683Example: background color = 0xffffff (sets the white color)
1684visible
1685Can be set to 0 or 1. 1 means that window is visible, 0 means that it is not. Can be read and
1686written. Also see the show and hide methods.
16875.6 gles — Bindings to OpenGL ES
168838
1689Chapter 5. User Interface and Graphics
1690Page 45
1691The gles module provides Python bindings to OpenGL ES 2D/3D graphics C API. OpenGL ES is a
1692standard defined by Khronos Group (www.khronos.org). Currently S60 Python supports OpenGL ES
1693version 1.0 from Series 60 version 2.6 onwards. Support for OpenGL ES version 1.1 should also become
1694available in the near future, and both versions are documented here. OpenGL ES 1.1 will require Series
169560 version 3.0 or newer.
1696For detailed description of the OpenGL ES API see the official specifications at
1697http://www.khronos.org/opengles. This documentation contains only information that is specific
1698to the S60 Python bindings to OpenGL ES. Where possible, the conventions of the PyOpenGL desktop
1699OpenGL bindings (http://pyopengl.sourceforge.net) have been followed.
1700The display of OpenGL ES graphics is handled by separate module, glcanvas. See glcanvas module
1701documentation for more information.
17025.6.1 array type
1703gles module defines array type for representing numerical data of specific GL type. array objects are
1704convenient when numerical data for OpenGL ES calls is specified in Python code. Class array also
1705defines the standard Python sequence methods so its instances can be iterated and individual items in
1706arrays can be manipulated easily.
1707class array(type, dimension, sequence)
1708Constructs a new array object that contains the given type of data that is taken from sequence.
1709Parameter dimension specifies how many items there are in each array element. The dimension
1710information is stored with the array and is used by those functions that need to know the element
1711size of the input data, for example, if colors are specified with three or four components. The
1712dimension does not affect the length of an array or its indexing: both are based on individual
1713items.
1714Value of type must be one of the following: GL FLOAT, GL BYTE, GL UNSIGNED BYTE, GL SHORT,
1715GL UNSIGNED SHORT, or GL FIXED.
1716The data in sequence is flattened before it is used to fill the array. When type is GL FLOAT, the
1717sequence can contains floats or integers. With all other types, sequence must only contain integers.
1718Values in sequence are casted in C to the requested type, so if the requested type cannot properly
1719represent all the values the results can be unexpected.
1720len
1721()
1722Returns the number of items in the array. Note that array dimension does not affect the
1723calculation of the length.
1724getitem
1725(index)
1726Returns the item in array with index. Note that array dimension does not affect indexing.
1727setitem
1728(index, value)
1729Sets the value of the item in position index to value. Note that array dimension does not
1730affect indexing.
17315.6.2 Error handling
1732Errors generated by the API calls are handled similarly as in PyOpenGL: all GL errors are reported
1733as Python exceptions of type gles.GLerror. The wrapper code checks GL error status after each call
1734automatically. There is no Python binding for glGetError call.
17355.6.3 Differences to OpenGL ES C API
1736Certain OpenGL ES functions require special handling in Python, mainly because of the pointer pa-
1737rameters in the C API. Additionally, special Python versions for some OpenGL ES functions have been
1738added. Both of sets of functions are documented below. If a function is not listed here its Python version
1739should exactly match the C version defined in the official OpenGL ES 1.0 and 1.1 specifications.
17405.6. gles — Bindings to OpenGL ES
174139
1742Page 46
1743OpenGL ES 1.0
1744glColorPointer(size, type, stride, sequence)
1745Parameter sequence must be either a gles.array object or some other Python sequence object.
1746gles.array objects require less processing and can be therefore slightly faster. If gles.array
1747object is used, the type and dimension of its data are ignored and size and type are used instead.
1748glColorPointerub(sequence)
1749Special Python version of glColorPointer that accepts either a gles.array object or some other
1750Python sequence object. Other parameters of glColorPointer will be determined as follows:
1751•size If sequence is an instance of gles.array, its dimension is used; otherwise the length of
1752sequence is used.
1753•type GL UNSIGNED BYTE
1754•stride 0
1755glColorPointerf(sequence)
1756Special Python version of glColorPointer that behaves exactly as glColorPointerub except
1757GL FLOAT is used as type.
1758glColorPointerx(sequence)
1759Special Python version of glColorPointer that behaves exactly as glColorPointerub except
1760GL FIXED is used as type.
1761glCompressedTexImage2D(target, level, internalformat, width, height, border, imageSize, data)
1762Parameter data must be either a gles.array or a Python string.
1763glCompressedTexSubImage2D(target, level, xoffset, yoffset, width, height, format, imageSize, data)
1764Parameter data must be either a gles.array or a Python string.
1765glDeleteTextures(sequence)
1766Parameter sequence must be a Python sequence containing integers.
1767glDrawElements(mode, count, type, indices)
1768Parameter indices must be either a gles.array or some other Python sequence object. gles.array
1769objects require less processing and can be therefore slightly faster. If gles.array object is used,
1770the type of its data is ignored and type is used instead.
1771glDrawElementsub(mode, indices)
1772Special Python version of glDrawElements that uses length of the sequence indices as count and
1773GL UNSIGNED BYTE as type.
1774glDrawElementsus(mode, indices)
1775Special Python version of glDrawElements that uses length of the sequence indices as count and
1776GL UNSIGNED SHORT as type.
1777glFogv(pname, params)
1778Parameter params must be a Python sequence containing float values.
1779glFogxv(pname, params)
1780Parameter params must be a Python sequence containing integer values.
1781glGenTextures(n)
1782The generated texture names are returned in a Python tuple.
1783glGetIntegerv(pname)
1784The values are returned in a Python tuple.
1785glGetString(name)
1786The value is return as a Python string.
1787glLightModelfv(pname, params)
1788Parameter params must be a Python sequence containing float values.
1789glLightModelxv(pname, params)
1790Parameter params must be a Python sequence containing integer values.
179140
1792Chapter 5. User Interface and Graphics
1793Page 47
1794glLightfv(light, pname, params)
1795Parameter params must be a Python sequence containing float values.
1796glLightxv(light, pname, params)
1797Parameter params must be a Python sequence containing integer values.
1798glLoadMatrixf(m)
1799Parameter m must be a Python sequence containing float values. The sequence is flattened before
1800its items are read.
1801glLoadMatrixx(m)
1802Parameter m must be a Python sequence containing integer values. The sequence is flattened
1803before its items are read.
1804glMaterialfv(face, pname, params)
1805Parameter params must be a Python sequence containing float values.
1806glMaterialxv(face, pname, params)
1807Parameter params must be a Python sequence containing integer values.
1808glMultMatrixf(m)
1809Parameter m must be a Python sequence containing float values. The sequence is flattened before
1810its items are read.
1811glMultMatrixx(m)
1812Parameter m must be a Python sequence containing integer values. The sequence is flattened
1813before its items are read.
1814glNormalPointer(type, stride, sequence)
1815Parameter sequence must be either a gles.array object or some other Python sequence object.
1816gles.array objects require less processing and can be therefore slightly faster. If gles.array
1817object is used, the type of its data is ignored and type is used instead.
1818glNormalPointerb(sequence)
1819Special Python version of glNormalPointer that uses type GL BYTE and stride 0.
1820glNormalPointers(sequence)
1821Special Python version of glNormalPointer that uses type GL SHORT and stride 0.
1822glNormalPointerf(sequence)
1823Special Python version of glNormalPointer that uses type GL FLOAT and stride 0.
1824glNormalPointerx(sequence)
1825Special Python version of glNormalPointer that uses type GL FIXED and stride 0.
1826glReadPixels(x, y, width, height, format, type)
1827The pixel data read is returned in a Python string.
1828glTexCoordPointer(size, type, stride, sequence)
1829Parameter sequence must be either a gles.array object or some other Python sequence object.
1830gles.array objects require less processing and can be therefore slightly faster. If gles.array
1831object is used, the dimension and type of its data are ignored and size and type are used instead.
1832glTexCoordPointerb(sequence)
1833Special Python version of glTexCoordPointer that accepts either a gles.array object or some
1834other Python sequence object. Other parameters of glTexCoordPointer will be determined as
1835follows:
1836•size If sequence is an instance of gles.array, its dimension is used; otherwise the length of
1837sequence is used.
1838•type GL BYTE
1839•stride 0
1840glTexCoordPointers(sequence)
1841Special Python version of glTexCoordPointer that behaves exactly as glTexCoordPointerb ex-
1842cept GL SHORT is used as type.
18435.6. gles — Bindings to OpenGL ES
184441
1845Page 48
1846glTexCoordPointerf(sequence)
1847Special Python version of glTexCoordPointer that behaves exactly as glTexCoordPointerb ex-
1848cept GL FLOAT is used as type.
1849glTexCoordPointerx(sequence)
1850Special Python version of glTexCoordPointer that behaves exactly as glTexCoordPointerb ex-
1851cept GL FIXED is used as type.
1852glTexEnvfv(face, pname, params)
1853Parameter params must be a Python sequence containing float values.
1854glTexEnvxv(face, pname, params)
1855Parameter params must be a Python sequence containing integer values.
1856glTexImage2D(target, level, internalformat, width, height, border, format, type, pixels)
1857Parameter pixels must be either a Python string, a gles.array object, or graphics.Image object.
1858Python strings are taken as literal data with no conversion. The dimension and type of data in
1859gles.array objects are ignored: the raw data in the array is used.
1860Use of graphics.Image objects is limited to only some combinations of format and type. Ta-
1861ble 5.6.3 below shows the accepted combinations. To get the best results and performance, the
1862CFbsBitmap object in the graphics.Image object should be in the equivalent display mode, also
1863shown in the table below. Otherwise, the CFbsBitmap object will be first converted to the equiva-
1864lent display mode before reading its pixel data, which can degrade the visual quality in some cases.
1865Table 5.1: Legal combinations of format and type with the equivalent Symbian display mode.
1866format
1867type
1868The equivalent display mode
1869GL LUMINANCE, GL ALPHA GL UNSIGNED BYTE
1870EGray256
1871GL RGB
1872GL UNSIGNED BYTE
1873EColor16M
1874GL RGB
1875GL UNSIGNED SHORT 5 6 5 EColor64K
1876glTexSubImage2D(target, level, xoffset, yoffset, width, height, format, type, pixels)
1877The handling of pixels is the same as with glTexImage2D.
1878glVertexPointer(size, type, stride, sequence)
1879Parameter sequence must be either a gles.array object or some other Python sequence object.
1880gles.array objects require less processing and can be therefore slightly faster. If gles.array
1881object is used, the dimension and type of its data are ignored and size and type are used instead.
1882glVertexPointerb(sequence)
1883Special Python version of glVertexPointer that accepts either a gles.array object or some other
1884Python sequence object. Other parameters of glVertexPointer will be determined as follows:
1885•size If sequence is an instance of gles.array, its dimension is used; otherwise the length of
1886sequence is used.
1887•type GL BYTE
1888•stride 0
1889glVertexPointers(sequence)
1890Special Python version of glVertexPointer that behaves exactly as glVertexPointerb except
1891GL SHORT is used as type.
1892glVertexPointerf(sequence)
1893Special Python version of glVertexPointer that behaves exactly as glVertexPointerb except
1894GL FLOAT is used as type.
1895glVertexPointerx(sequence)
1896Special Python version of glVertexPointer that behaves exactly as glVertexPointerb except
1897GL FIXED is used as type.
189842
1899Chapter 5. User Interface and Graphics
1900Page 49
1901OpenGL ES 1.1
1902glBufferData(target, size, data, usage)
1903Parameter data must be a gles.array object. If size is -1, the in-memory size of data is used in
1904its place.
1905glBufferDatab(target, data, usage)
1906Special Python version of glBufferData that accepts either a gles.array object or some other
1907Python sequence object for data. If gles.array object is used, its in-memory size in bytes is used
1908as size. Other sequences are first converted to flat lists of GL BYTE data by casting. The length of
1909the resulting sequence in bytes is used as size.
1910glBufferDataub(target, data, usage)
1911Special Python version of glBufferData that works exactly like glBufferDatab except
1912GL UNSIGNED BYTE is used instead of GL BYTE.
1913glBufferDatas(target, data, usage)
1914Special Python version of glBufferData that works exactly like glBufferDatab except GL SHORT
1915is used instead of GL BYTE.
1916glBufferDataus(target, data, usage)
1917Special Python version of glBufferData that works exactly like glBufferDatab except
1918GL UNSIGNED SHORT is used instead of GL BYTE.
1919glBufferDataf(target, data, usage)
1920Special Python version of glBufferData that works exactly like glBufferDatab except GL FLOAT
1921is used instead of GL BYTE.
1922glBufferDatax(target, data, usage)
1923Special Python version of glBufferData that works exactly like glBufferDatab except GL FIXED
1924is used instead of GL BYTE.
1925glBufferSubData(target, size, data, usage)
1926Parameter data must be a gles.array object. If size is -1, the in-memory size of data is used in
1927its place.
1928glBufferSubDatab(target, data, usage)
1929Special Python version of glBufferSubData that accepts either a gles.array object or some other
1930Python sequence object for data. If gles.array object is used, its in-memory size (in bytes) is
1931used as size. Other sequences are first converted to flat lists of GL BYTE data by casting. The
1932length of the resulting sequence is used as size.
1933glBufferSubDataub(target, data, usage)
1934Special Python version of glBufferSubData that works exactly like glBufferSubDatab except
1935GL UNSIGNED BYTE is used instead of GL BYTE.
1936glBufferSubDatas(target, data, usage)
1937Special Python version of glBufferSubData that works exactly like glBufferSubDatab except
1938GL SHORT is used instead of GL BYTE.
1939glBufferSubDataus(target, data, usage)
1940Special Python version of glBufferSubData that works exactly like glBufferSubDatab except
1941GL UNSIGNED SHORT is used instead of GL BYTE.
1942glBufferSubDataf(target, data, usage)
1943Special Python version of glBufferSubData that works exactly like glBufferSubDatab except
1944GL FLOAT is used instead of GL BYTE.
1945glBufferSubDatax(target, data, usage)
1946Special Python version of glBufferSubData that works exactly like glBufferSubDatab except
1947GL FIXED is used instead of GL BYTE.
1948glClipPlanef(plane, equation)
1949Parameter equation must be a Python sequence that contains four float values.
1950glClipPlanex(plane, equation)
19515.6. gles — Bindings to OpenGL ES
195243
1953Page 50
1954Parameter equation must be a Python sequence that contains four integer values.
1955glDeleteBuffers(buffers)
1956Parameter buffers must be a Python sequence that contains integer values.
1957glDrawTexsvOES(coords)
1958Parameter coords must be a Python sequence that contains integer values.
1959glDrawTexivOES(coords)
1960Parameter coords must be a Python sequence that contains integer values.
1961glDrawTexfvOES(coords)
1962Parameter coords must be a Python sequence that contains float values.
1963glDrawTexfvOES(coords)
1964Parameter coords must be a Python sequence that contains integer values.
1965glGenBuffers(n)
1966The generated buffer names are returned in a Python tuple.
1967glGetBooleanv(pname)
1968The values are returned in a Python tuple.
1969glGetBufferParameteriv(target, pname)
1970The value is returned as an integer.
1971glGetClipPlanef(plane)
1972The values are returned in a Python tuple.
1973glGetClipPlanef(plane)
1974The values are returned in a Python tuple.
1975glGetFixedv(pname)
1976The values are returned in a Python tuple.
1977glGetFloatv(pname)
1978The values are returned in a Python tuple.
1979glGetLightfv(light, pname)
1980The values are returned in a Python tuple.
1981glGetLightxv(light, pname)
1982The values are returned in a Python tuple.
1983glGetMaterialfv(face, pname)
1984The values are returned in a Python tuple.
1985glGetMaterialxv(face, pname)
1986The values are returned in a Python tuple.
1987glGetTexEnvf(face, pname)
1988The values are returned in a Python tuple.
1989glGetTexEnvx(face, pname)
1990The values are returned in a Python tuple.
1991glGetTexParameterf(target, pname)
1992The value is returned as a float.
1993glGetTexParameterx(target, pname)
1994The value is returned as an integer.
1995glMatrixIndexPointerOES(size, type, stride, sequence)
1996Parameter sequence must be either a gles.array object or some other Python sequence object.
1997gles.array objects require less processing and can be therefore slightly faster. If gles.array
1998object is used, the dimension and type of its data are ignored and size and type are used instead.
1999glMatrixIndexPointerOESub(sequence)
2000Special Python version of glMatrixIndexPointerOES that accepts either a gles.array object
2001or some other Python sequence object. Other parameters of glMatrixIndexPointerOES will be
200244
2003Chapter 5. User Interface and Graphics
2004Page 51
2005determined as follows:
2006•size If sequence is an instance of gles.array, its dimension is used; otherwise the length of
2007sequence is used.
2008•type GL UNSIGNED BYTE
2009•stride 0
2010glPointParameterfv(pname, params)
2011Parameter params must be a Python sequence containing float values.
2012glPointParameterxv(pname, params)
2013Parameter params must be a Python sequence containing integer values.
2014glPointSizePointerOES(type, stride, sequence)
2015Parameter sequence must be either a gles.array object or some other Python sequence object.
2016gles.array objects require less processing and can be therefore slightly faster. If gles.array
2017object is used, the type of its data is ignored and type is used instead.
2018glPointSizePointerOESf(sequence)
2019Special Python version of glPointSizePointerOES uses GL FLOAT as type and 0 as stride.
2020glPointSizePointerOESx(target, data, usage)
2021Special Python version of glPointSizePointerOES uses GL FIXED as type and 0 as stride.
2022glWeightPointerOES(size, type, stride, sequence)
2023Parameter sequence must be either a gles.array object or some other Python sequence object.
2024gles.array objects require less processing and can be therefore slightly faster. If gles.array
2025object is used, the dimension and type of its data are ignored and size and type are used instead.
2026glWeightPointerOESf(sequence)
2027Special Python version of glWeightPointerOES that accepts either a gles.array object or some
2028other Python sequence object. Other parameters of glWeightPointerOES will be determined as
2029follows:
2030•size If sequence is an instance of gles.array, its dimension is used; otherwise the length of
2031sequence is used.
2032•type GL FLOAT
2033•stride 0
2034glWeightPointerOESx(sequence)
2035Special Python version of glWeightPointerOES that behaves exactly as glWeightPointerOESf
2036except GL FIXED is used as type.
20375.7 glcanvas — UI Control for Displaying OpenGL ES Graphics
2038The glcanvas module provides a UI control, GLCanvas, for displaying OpenGL ES graphics. GLCanvas
2039component is similar to the appuifw Canvas component that supports Symbian OS -level drawing.
2040Internally GLCanvas uses EGL for displaying the OpenGL ES graphics. EGL, as OpenGL ES, is a
2041standard API defined by the Khronos Group (www.khronos.org). Specifically, GLCanvas uses an EGL
2042window surface, which supports double-buffered rendering. It is possible to affect selection of the EGL
2043config that is used to create the window surface; for details, see the documentation of the GLCanvas
2044constructor.
2045GLCanvas instances also hold the OpenGL ES context object, which together with the surface, are needed
2046for rendering. When one wants to render with a specific OpenGL ES context to a specific surface, they
2047need to be made current. This also applies to GLCanvas, which has the makeCurrent method for this
2048purpose. Generally, calling makeCurrent has to be done only if multiple GLCanvas objects are used in
2049the same program, as each GLCanvas object is automatically made current when it is created and it
2050remains current until it is destroyed or makeCurrent of some other GLCanvas object is called.
20515.7. glcanvas — UI Control for Displaying OpenGL ES Graphics
205245
2053Page 52
2054class GLCanvas(redraw callback, [event callback=None, resize callback=None, attributes=None ])
2055Constructs a new GLCanvas object that can be used as a UI control for displaying OpenGL ES
2056graphics. Parameters redraw callback, event callback, and resize callback have the same meaning
2057as with appuifw module Canvas. Using redraw callback to specify the OpenGL ES drawing is
2058preferred as it will be automatically called by drawNow method.
2059Parameter attributes can be used to specify attributes used in EGL config selection. It must
2060be a Python dictionary where keys are EGL attribute names (which are defined in the glcanvas
2061module) and values are integers defining the desired attribute values. Unless specified in attributes,
2062EGL BUFFER SIZE is set to value based on the display mode of the window owned by the underlying
2063CCoeControl object and EGL DEPTH SIZE is set to 16. Attributes specified in attributes are given
2064to eglChooseConfig. Refer to the EGL specification for a detailed list of config attributes and
2065explanation of how the selection of EGL configs works.
2066The new GLCanvas object will be made current when the constructor returns so makeCurrent does
2067not have to be called before starting to use OpenGL ES calls.
2068bind(key code, c)
2069Sets a callback to be called when a specific key is pressed. Parameter key code should be one
2070of the standard Symbian key codes defined in key codes. Parameter c must be a callable
2071object.
2072drawNow()
2073Calls the redraw callback (if set) and then calls eglSwapBuffers to render and display the
2074OpenGL ES graphics.
2075makeCurrent()
2076Makes this GLCanvas object current, meaning that it will be used to display the results of the
2077subsequent OpenGL ES calls. In EGL terms this means that the EGL context and surface
2078held by this object will be passed to eglMakeCurrent. Using makeCurrent makes it possible
2079to use several GLCanvas objects in a single application: the receiver of the OpenGL ES calls
2080can be switched with makeCurrent easily.
20815.8 sensor — Module to access the device sensors.
2082The sensor module offers direct access to a device’s physical sensors. It has been tested with
2083• acceleration sensor: raises events about the 3-axes acceleration of the device
2084• tapping sensor: raises an event when the device was tapped twice on the front side
2085• rotation sensor: raises an event based on the orientation of the device.
2086Instead of just passing on raised events, event filtering is also supported. Two examples of using
2087an event filter are also provided by the sensor module, namely the class OrientationEventFilter
2088and RotEventFilter. Both filters can be used to raise events when the device’s orientation changes
2089(e.g. when it’s turned to the right). The support is device dependent, e.g. Nokia 5500 supports
2090OrientationEventFilter and Nokia N95 supports RotEventFilter.
2091Note: The module sensor is available from S60 3rd Edition onwards (inclusive).
20925.8.1 Module Level Functions
2093On the module level, sensor provides the following functions:
2094sensors()
2095Returns a dictionary containing all available sensors. The dictionary’s format is
2096{
2097{ ’sensor name 1’: { ’id’: sensor_id_1, ’category’: category_id_1 } },
2098{ ’sensor name 2’: { ’id’: sensor_id_2, ’category’: category_id_2 } },
209946
2100Chapter 5. User Interface and Graphics
2101Page 53
2102...
2103}
2104with sensor id X and category id X being integer values.
21055.8.2 Constants
2106The following orientation constants are used by the OrientationEventFilter class. Callbacks which
2107have been connected to a Sensor object that utilises the OrientationEventFilter event filter will
2108receive one of these constants as an argument upon a detected orientation change. The constants’ names
2109are the side of the device that is currently turned upwards from the user’s point of view. (For example
2110FRONT means that the device is lying on its back - its front side is turned upwards.)
2111orientation.TOP
2112Represents the orientation where the device is held upwards.
2113orientation.BOTTOM
2114Represents the orientation where the device is held upside down.
2115orientation.LEFT
2116Represents the orientation where the side of the device that is left of the display is turned down-
2117wards.
2118orientation.RIGHT
2119Represents the orientation where the side of the device that is right of the display is turned down-
2120wards.
2121orientation.FRONT
2122Represents the orientation where the device is lying on its back, i.e. the front side points upwards.
2123orientation.BACK
2124Represents the orientation where the device is lying on its front, i.e. the back side points upwards.
21255.8.3 Classes
2126The following classes are provided by the sensor module:
2127class Sensor
2128The Sensor class represents a physical sensor which delivers (possibly filtered) events. By default,
2129events are not filtered. A filter can be applied by using the set event filter method. An
2130example for an event filter is given by OrientationEventFilter, which can be applied to a device’s
2131acceleration sensor.
2132In case different filters should be used for the same physical sensor, different Sensor objects have
2133to be created for the same physical sensor.
2134init
2135(sensor id, category id)
2136Initialises the Sensor object. sensor id and category id must represent a valid sensor
2137id and category id, respectively. This means that the ids passed on to
2138init
2139must
2140also appear in the dictionary returned by the sensors function. In case sensor id and
2141category id do not represent a valid sensor, the connect method will raise an exception.
2142connect(callback)
2143This method connects the sensor to the given callback. A sensor can only be connected to
2144one callback, so this will destroy any pre-existing connection to another callback. If an event
2145filter has been set, the events passed on to callback will pass this Sensor object’s event filter
2146first. If the connection was properly established, this method returns 1, otherwise 0. Note:
2147The connection can be established also if the callback does not exist or cannot be called for
2148any other reason.
2149disconnect()
2150Disconnects this Sensor object’s callback connection. After a successful call to this method, a
2151callback that has been previously connected via connect will not receive any events anymore.
2152If a connection existed and was successfully removed, this method returns 1, otherwise 0.
21535.8. sensor — Module to access the device sensors.
215447
2155Page 54
2156connected()
2157Retrieves this Sensor object’s connection status. Returns True if the sensor is connected,
2158False otherwise.
2159set event filter(event filter)
2160Sets an event filter for this Sensor object. After the event filter has been successfully installed,
2161this Sensor object’s connected callback will receive only events that have passed the filter.
2162event filter must be derived from EventFilter in order to function properly. If a callback
2163connection has already been established before calling this method, the connection will be
2164re-established after the event filter has been installed.
2165class EventFilter
2166The EventFilter class provides a generic interface for event filters. The default implementation
2167only passes events on, i.e. events are not filtered. Classes deriving from EventFilter can decide
2168if an event should be delivered at all as well as they can alter the data that is passed on to the
2169callback.
2170callback
2171This is where the event filter’s callback is stored. In case the EventFilter object is used
2172together with a Sensor object, the Sensor object will handle correct setting of this variable.
2173init
2174()
2175Initialises the event filter object. The callback member is initialised to None.
2176del
2177()
2178Destructs the event filter object. This method calls cleanup, which can be overridden by
2179deriving classes to clean up resources.
2180event(data)
2181This method is the place where event filtering takes place, and hence this method should be
2182overridden by deriving classes. Overridden event methods can deliver their own data to the
2183callback; the data delivered may be data or any other set of data. In case the event is decided
2184to be delivered, overriding instances should call self.callback, which by default takes one
2185argument.
2186cleanup()
2187Cleans up any resources needed by the event filter. The default implementation does not need
2188this feature. This method is called by the destructor
2189del
2190.
2191class OrientationEventFilter
2192Derived from EventFilter. This event filter is meant to be used together with the device’s accel-
2193eration sensors. Note that it does not make sense to use it with any other sensor type. It generates
2194events when the devices orientation changes, e.g. if it is turned from the upright position to lying
2195on the back side. If an OrientationEventFiler is used with a Sensor object, the Sensor object’s
2196callback will not receive the raw acceleration data as an argument, but only one of the orientation
2197constants, representing the device’s new orientation. In case the algorithm needs calibration on
2198the device to be used, please check the OrientationCalibration variables in the file sensor.py.
2199init
2200()
2201Initialises the OrientationEventFilter object.
2202event(sensor val)
2203Overridden method. Filters 3-axis acceleration events such that it detects orientation changes.
2204Only upon detection of such an orientation change, the callback is invoked. The argument
2205passed to the callback is a value from this module’s orientation constants.
2206cleanup()
2207Cleans up this filter’s timer resource. This will be called by EventFilter’s destructor.
2208class RotEventFilter
2209Derived from EventFilter.
2210This event filter generates events when the devices orientation changes, e.g. if it is turned from the
2211left side up position to right side up position. This sensor is resident e.g. in Nokia N95.
2212event(sensor val)
2213Overridden method. Upon detection of an orientation change, the callback is invoked. The
2214argument passed to the callback is a value from this module’s orientation constants.
221548
2216Chapter 5. User Interface and Graphics
2217Page 55
2218CHAPTER
2219SIX
2220Audio and Communication Services
22216.1 audio — An audio related services package
2222The audio module enables recording and playing audio files and access to device text-to-speech engine.
2223The audio module supports all the formats supported by the device, typically: WAV, AMR, MIDI, MP3,
2224AAC, and Real Audio1. For more information on the audio types supported by different devices, see the
2225Forum Nokia Web site [7] and S60 Platform Web site [8].
2226The following Sound class static methods are defined in the audio module:
2227Sound.open(filename)
2228Returns a new initialized Sound object with the named file opened. Note that filename should be
2229a full Unicode path name and must also include the file extension, for example u’c:\\foo.wav’.
2230The following data items for state information are available in audio:
2231ENotReady
2232The Sound object has been constructed but no audio file is open.
2233EOpen
2234An audio file is open but no playing or recording operation is in progress.
2235EPlaying
2236An audio file is playing.
2237ERecording
2238An audio file is being recorded.
2239The following data item is provided for continuous playback of an audio file:
2240KMdaRepeatForever
2241Possible value for times parameter in open.
2242The following method is available in the audio module:
2243say(text, prefix=audio.TTS PREFIX)
2244Passes the text to the device text-to-speech engine. The default prefix is the text-to-speech prefix
2245"(tts)".
22466.1.1 Sound Objects
2247Note: The method current volume is not available for S60 1st Edition.
2248class Sound
2249Sound objects have the following functions:
2250play([times=1, interval=0, callback=None ])
2251Starts playback of an audio file from the beginning. Without the parameters times and
22521The dynamically loaded audio codec for the sound file is based on the MIME-type information inside the audio file
2253and file extension.
225449
2255Page 56
2256interval it plays the audio file one time. times defines the number of times the audio file is
2257played, the default being 1. If the audio file is played several times, interval gives the time
2258interval between the subsequent plays in microseconds.
2259The optional callback is called when the playing starts and when the end of the sound file
2260is reached. The callback should take three parameters: the previous state, the current state
2261and the possible error code. The possible states given as parameters to the callback are data
2262items in the module audio.
2263Other issues:
2264•Calling play(audio.KMdaRepeatForever) will repeat the file forever.
2265•If an audio file is played but not stopped before exiting, the Python script will leave audio
2266playing on; therefore stop needs to be called explicitly prior to exit.
2267•Currently the module does not support playing simultaneous audio files, calling play to a
2268second Sound instance while another audio file is playing, stops the earlier audio file and
2269starts to play the second Sound instance.
2270•Calling play while a telephone call is ongoing plays the sound file to uplink. In some
2271devices the sound file is also played to the device speaker.
2272•Calling play when already playing or recording results in RuntimeError. Calling stop
2273prior to play will prevent this from happening.
2274stop()
2275Stops playback or recording of an audio file.
2276record()
2277Starts recording audio data to a file. If the file already exists, the operation appends to the
2278file. For Nokia devices, WAV is typically supported for recording. For more information on
2279the audio types supported by different devices, see the Forum Nokia Web site [7] and S60
2280Platform Web site [8]. Other issues:
2281•Calling record while a telephone call is ongoing starts the recording of the telephone call.
2282•Calling record when already playing or recording results in RuntimeError. Calling stop
2283prior to record will prevent this from happening.
2284close()
2285Closes an opened audio file.
2286state()
2287Returns the current state of the Sound type instance. The different states (constants) are
2288defined in the audio module. The possible states2 are:
2289•ENotReady
2290The Sound object has been constructed but no audio file is open.
2291•EOpen
2292An audio file is open but no playing or recording operation is in progress.
2293•EPlaying
2294An audio file is playing.
2295•ERecording
2296An audio file is being recorded.
2297max volume()
2298Returns the maximum volume of the device.
2299set volume(volume)
2300Sets the volume. If the given volume is negative, then the volume is set to zero which mutes
2301the device. If the volume is greater than max volume, then max volume is used.
2302current volume()
2303Returns the current volume set.
2304duration()
2305Returns the duration of the file in microseconds.
2306set position(microseconds)
2307Set the position for the playhead.
23082Descriptions for these options are based on information found in S60 SDK documentation [4].
230950
2310Chapter 6. Audio and Communication Services
2311Page 57
2312current position()
2313Returns the current playhead position in microseconds.
23146.2 telephone — Telephone services
2315This module provides an API to a telephone.
2316Since the users of the device can also hang-up the phone explicitly, they might affect the current status
2317of the call. In addition, using this extension in an emulator has no effect since no calls can be connected.
2318The telephone module has the following functions:
2319dial(number)
2320Dials the number set in number. number is a string, for example u’+358501234567’ where ’+’ is
2321the international prefix, ’358’ is the country code, ’50’ is the mobile network code (or the area
2322code), and ’1234567’ is the subscriber number. If there is an ongoing phone call prior to calling
2323dial from Python, then the earlier call is put on hold and a new call is established. Calling dial
2324multiple times when, for example, the first call has been answered and a line has been established
2325results in subsequent calls not being connected.
2326hang up()
2327Hangs up if a call initiated by dial is in process. If this call has already been finished,
2328SymbianError: KErrNotReady is raised.
2329Note: The following functions and data items are available from S60 3rd Edition onwards (inclusive).
2330incoming call()
2331Wait for incoming call, returns immediately. If a call arrives, answer can be called to answer the
2332call. Without the invocation of function incoming call, the function answer has no effect.
2333answer()
2334Answers an incoming call - see also incoming call.
2335call state(callable)
2336The callable will be called when there are changes in the telephone line (lines) in the device. The
2337argument for the call is a tuple with first item the possible new state and the second item, the
2338possible incoming call number as a Unicode string.
2339The possible states in the tuple are defined as telephone module constants.
2340The following data items for state information are available in telephone3:
2341EStatusUnknown
2342Indicates that the status is unknown.
2343EStatusIdle
2344Idle line status (no active calls).
2345EStatusDialling
2346Call dialling status.
2347EStatusRinging
2348Call ringing status.
2349EStatusAnswering
2350Call answering status.
2351EStatusConnecting
2352Call connecting status.
2353EStatusConnected
2354Call connected status.
2355EStatusReconnectPending
2356Call is undergoing temporary channel loss and it may or may not be reconnected.
23573The descriptions are taken from the S60 SDK documentation [4]
23586.2. telephone — Telephone services
235951
2360Page 58
2361EStatusDisconnecting
2362Call disconnecting status.
2363EStatusHold
2364Call on hold.
2365EStatusTransferring
2366Call is transferring.
2367EStatusTransferAlerting
2368Call in transfer is alerting the remote party.
23696.3 messaging — A messaging services package
2370The messaging module offers APIs to messaging services. Currently, the messaging module has func-
2371tions:
2372sms send(recipient, message, [encoding=’7bit’, callback=None ])
2373Sends an SMS message with body text message (Unicode) to telephone number recipient (string).
2374The optional parameter encoding is used to define encoding in the message. The parameter values
2375can be ’7bit’, ’8bit’ or ’UCS2’.
2376The optional parameter callback is invoked with the current status of the send operation as param-
2377eter. The possible states are data items in the module messaging. Invoking another send while a
2378previous send request is ongoing will result in RuntimeError being raised.
2379If the callback is not given, the sms send function will block until the message in the queue is
2380either deleted or the sending has failed4.
2381mms send(recipient, message, [attachment=None ])
2382Note: Available from S60 3.0 onwards (inclusive).
2383Sends an MMS message with body text message (Unicode) to telephone number recipient (string).
2384The optional parameter attachment is full path to e.g. image file attached to the message.
2385The following data items for SMS sending state information are available in the module messaging:
2386ECreated
2387EMovedToOutBox
2388EScheduledForSend
2389ESent
2390The SMS message has been sent.
2391EDeleted
2392The SMS message has been deleted from device’s outbox queue. The sms send operation has
2393finalized and subsequent SMS sending is possible.
2394EScheduleFailed
2395ESendFailed
2396This state information is returned when the SMS subsystem has tried to send the message several
2397times in vain. The sms send operation has finalized and subsequent SMS sending is possible.
2398ENoServiceCentre
2399This state information is returned by the SMS subsystem in S60 3.x emulator. In emulator this
2400indicates that the sms send operation has finalized and subsequent SMS sending is possible.
2401EFatalServerError
2402The underlying messaging subsystem in S60 devices might give error messages to the user if the device
2403is not connected to a network while trying to send a message – An ”SMS send failed!” note is a common
2404error message.
24054Please note that this blocking might last for several minutes and hence supplying the callback might be more suitable
2406in many cases.
240752
2408Chapter 6. Audio and Communication Services
2409Page 59
2410When sending messages in offline-mode or with no network connection these messages are actually added
2411to an outgoing message queue and they might be sent if the device is later on connected to a suitable
2412network5. This occurs despite the possibly misleading error messages. The current network conditions
2413can be checked e.g. with sysinfo.active profile() and sysinfo.signal bars() invocations.
2414The following is example code for state information processing with sms send operation:
2415>>> import messaging
2416>>>
2417>>> def cb(state):
2418...
2419if state==messaging.ESent:
2420...
2421print "**Message was sent**"
2422...
2423if state==messaging.ESendFailed:
2424...
2425print "**Something went wrong - Truly sorry for this**"
2426...
2427>>> messaging.sms_send("1234567", "Hello from PyS60!", ’7bit’, cb)
2428>>> **Message was sent** # This is printed from the callback
24296.4 inbox — Interface to device inbox
2430The inbox module offers APIs to device inbox, outbox, sent and drafts folders. Currently, the inbox
2431module supports only SMS handling and notifications of incoming messages to the device inbox.
2432class Inbox([folder type ])
2433Create an Inbox object.
2434The optional parameter folder type defines the type of the folder to which the created Inbox
2435object has access to. The default is the device’s inbox folder, inbox.EInbox.
2436The following data items are available in the inbox module to define the type of the folder for Inbox
2437objects:
2438EInbox
2439The device’s inbox folder.
2440EOutbox
2441The device’s outbox folder.
2442ESent
2443The sent messages folder.
2444EDraft
2445The draft messages folder.
24466.4.1 Inbox Objects
2447Inbox objects have the following functions:
2448sms messages()
2449Returns a list of SMS message IDs in device inbox.
2450content(sms id)
2451Retrieve the SMS message content in Unicode.
2452time(sms id)
2453Retrieve the SMS message time of arrival in seconds since epoch.
2454address(sms id)
2455Retrieve the SMS message sender address in Unicode.
24565Note also that prior this the user of the device can explicitly delete the messages from the native messaging application.
2457The amount of resending is approx. 4 times – After this the sending operation is cancelled and the user of the device will
2458see a visual cue of the failure in the status pane.
24596.4. inbox — Interface to device inbox
246053
2461Page 60
2462delete(sms id)
2463Delete the SMS message from inbox.
2464unread(( )
2465sms id) Returns the status (1=unread, 0=read) of the SMS with id.
2466bind(callable)
2467Bind a callback to receive new message events in device inbox. When a new message arrives to the
2468device inbox the callback gets called with the received message ID. The received message can be
2469other than an SMS message.
2470If the message received is deleted immediately after e.g. checking the message content, the ”new
2471message” sound and dialog are not activated. This functionality might be useful in notification
2472type of applications.
2473Examples:
2474>>> import inbox
2475>>> i=inbox.Inbox() # Give inbox.ESent as parameter for sent SMSes
2476>>> m=i.sms_messages()
2477>>> i.content(m[0])
2478u’foobar’
2479>>> i.time(m[0])
24801130267365.03125
2481>>> i.address(m[0])
2482u’John Doe’
2483>>> i.delete(m[0])
2484>>>
2485>>> import inbox
2486>>> id=0
2487>>> def cb(id_cb):
2488... global id
2489... id=id_cb
2490...
2491>>> i=inbox.Inbox()
2492>>> i.bind(cb)
2493>>> # Send an SMS to your inbox here. The "id" gets updated
2494>>> i.address(id)
2495u’John Doe’
2496>>> i.content(id)
2497u’print 1’
2498>>>
24996.5 location — GSM location information
2500The location module offers APIs to location information related services. Currently, the location has
2501one function:
2502Note:
2503Location module requires capabilities ReadDeviceData, ReadUserData and Location in 3rd
2504Edition devices.
2505gsm location()
2506Retrieves GSM location information: Mobile Country Code, Mobile Network Code, Location Area
2507Code, and Cell ID. A location area normally consists of several base stations. It is the area where
2508the terminal can move without notifying the network about its exact position. mcc and mnc
2509together form a unique identification number of the network into which the phone is logged.
25106.5.1 Examples
2511Here is an example of how to use the location package to fetch the location information:
251254
2513Chapter 6. Audio and Communication Services
2514Page 61
2515>>> import location
2516>>> print location.gsm_location()
25176.6 positioning — Simplified interface to the position information
2518The positioning module provides basic access to the S60 position information 6. The module can be
2519e.g. used to access position information provided by external Bluetooth GPS-devices and by built-in
2520GPS-receivers7 from S60 2nd Edition FP 2 onwards.
2521The module offers a large amount of information (cost of service, device power consumption etc.) about
2522accessible positioning devices (like GPS-modules), position, course, accuracy and satellite information
2523(depending on the position device used) and much more. This module can also be used to obtain
2524device/vendor specific extended information.
2525Note: The module position requires Location capability to work fully in S60 3rd Edition devices.
2526The following data items are available in positioning:
2527POSITION INTERVAL
2528The time interval (in microseconds) between the position function callback invocation. The
2529default value set is 1 000 000 microseconds (= 1 second)
2530The positioning module has the following functions (for examples of the values returned, see Section
25316.6.1):
2532modules()
2533Get information about available positioning modules.
2534default module()
2535Get default module id.
2536module info(module id)
2537Get detailed information about the specified module.
2538select module(module id)
2539Select a module.
2540set requestors(requestors)
2541Set the requestors of the service (at least one must be set).
2542position(course=0,satellites=0,callback=None, interval=positioning.POSITION INTERVAL, partial=0)
2543By default, returns the position information in a dictionary. With course and/or satellites set to
25441, information about course and satellites is also returned (if available).
2545With no callback provided, this call blocks until the position information is available.
2546The call returns immediately if a valid callback function is given. This callback function is then
2547invoked with the specified time interval (in microseconds) in between the invocations. The callback
2548function is called with the the current position information as parameter.
2549If partial update is set to 1, the function might return e.g. information about satellites before the
2550final location fix has been calculated.
2551For an example of the dictionary returned and the detailed keys, see Section 6.6.1.
2552stop position()
2553Stops an ongoing position request.
25546For details, please see the Location Acquisition API in the S60 API documentation. The Location Acquisition API
2555gathers different positioning technologies together to be used through a consistent interface.
25567For more information on GPS, please see http://en.wikipedia.org/wiki/Global Positioning System.
25576.6. positioning — Simplified interface to the position information
255855
2559Page 62
25606.6.1 Example
2561The following example (invoked in a Nokia N95 device) demonstrates how to use the Python positioning
2562module to obtain information about the positioning technologies in the device:
2563>>> positioning.modules()
2564[{’available’: 0, ’id’: 270526873, ’name’: u’Bluetooth GPS’}, {’available’: 1, ’
2565id’: 270526858, ’name’: u’Integrated GPS’}, {’available’: 1, ’id’: 270559509, ’n
2566ame’: u’Network based’}]
2567>>> positioning.default_module()
2568270526858
2569>>> positioning.module_info(270526858)
2570{’available’: 1, ’status’: {’data_quality’: 3, ’device_status’: 7}, ’version’: u
2571’1.00(0)’, ’name’: u’Integrated GPS’, ’position_quality’: {’vertical_accuracy’:
257210.0, ’time_to_first_fix’: 1000000L, ’cost’: 1, ’time_to_next_fix’: 1000000L, ’h
2573orizontal_accuracy’: 10.0, ’power_consumption’: 3}, ’technology’: 1, ’id’: 27052
25746858, ’capabilities’: 127, ’location’: 1}
2575>>>
2576The following example demonstrates how to use the Python positioning module.
2577# information about available positioning modules
2578print "***available modules***"
2579print positioning.modules()
2580print ""
2581# id of the default positioning module
2582print "***default module***"
2583print positioning.default_module()
2584print ""
2585# detailed information about the default positioning module
2586print "***detailed module info***"
2587print positioning.module_info(positioning.default_module())
2588print ""
2589# select a module (in practise, selecting default module has no
2590# relevance.).
2591positioning.select_module(positioning.default_module())
2592# set requestors.
2593# at least one requestor must be set before requesting the position.
2594# the last requestor must always be service requestor
2595# (whether or not there are other requestors).
2596positioning.set_requestors([{"type":"service",
2597"format":"application",
2598"data":"test_app"}])
2599# Example 1. Blocking call
2600# get the position.
2601# note that the first position()-call may take a long time
2602# (because of gps technology).
2603print "***position info***"
2604print positioning.position()
2605print ""
2606# re-get the position.
2607# this call should be much quicker.
2608# ask also course and satellite information.
2609print "***course and satellites***"
2610print positioning.position(course=1,satellites=1)
261156
2612Chapter 6. Audio and Communication Services
2613Page 63
2614print ""
2615# Example 2. Non-blocking call
2616def cb(event):
2617print "---"
2618print event
2619print "---"
2620print "***starts the position feed***"
2621print positioning.position(course=1,satellites=1,
2622callback=cb, interval=500000,
2623partial=0)
2624An example dictionary returned/printed from the above example script could be as follows:
2625{’satellites’: {’horizontal_dop’: 2.34999990463257, ’used_satellites’: 5, ’verti
2626cal_dop’: 2.29999995231628, ’time’: 1187167353.0, ’satellites’: 11, ’time_dop’:
26271.26999998092651}, ’position’: {’latitude’: 60.217033666473, ’altitude’: 42.0, ’
2628vertical_accuracy’: 58.0, ’longitude’: 24.878942093007, ’horizontal_accuracy’: 4
26297.531005859375}, ’course’: {’speed’: 0.0500000007450581, ’heading’: 68.959999084
26304727, ’heading_accuracy’: 359.989990234375, ’speed_accuracy’: NaN}}
2631To run the script in the emulator you must configure PSY emulation from your emulator (SimPSYCon-
2632figurator → Select Config File → <some config files>or Tools → Position).
26336.6. positioning — Simplified interface to the position information
263457
2635Page 64
263658
2637Page 65
2638CHAPTER
2639SEVEN
2640Data Management
26417.1 contacts — A contacts related services package
2642The contacts module offers an API to address book services allowing the creation of contact information
2643databases. The contacts module represents a Symbian contact database as a dictionary-like ContactDb
2644object, which contains Contact objects and which is indexed using the unique IDs of those objects. A
2645Contact object is itself a list-like object, which contains ContactField objects and which is indexed using
2646the field indices. Unique IDs and field indices are integers. The ContactDb object supports a limited
2647subset of dictionary functionality. Therefore, only
2648iter
2649,
2650getitem
2651,
2652delitem
2653,
2654len
2655,
2656keys, values, and items are included.
2657ContactDb objects represent a live view into the database. If a contact is changed outside your Python ap-
2658plication, the changes are visible immediately, and conversely any changes you commit into the database
2659are visible immediately to other applications. It is possible to lock a contact for editing, which will pre-
2660vent other applications from modifying the contact for as long as the lock is held. This can be done in,
2661for example, a contacts editor application when a contact is opened for editing, very much like with the
2662Contacts application in your Nokia device. If you try to modify a contact without locking it for editing,
2663the contact is automatically locked before the modification and released immediately afterwards.
26647.1.1 Module Level Functions
2665The following free functions - functions that do not belong to any class - are defined in the Contact
2666module:
2667open([filename[, mode ]])
2668Opens a contacts database and returns a ContactDb object. filename should be a full Unicode
2669path name. If filename is not given, opens the default contacts database. If mode is not given, the
2670database must exist. If mode is ’c’, the database is created if it does not already exist. If mode is
2671’n’, a new, empty database is created, overwriting the possible previous database.
2672Warning: Using open together with the additional parameters filename or mode is intended for testing
2673purposes only. Due to S60 SDK functionality, the open method can sometimes be unreliable with these
2674parameters.
26757.1.2 ContactDb Object
2676There is one default contact database, but it is possible to create several databases with the open function.
2677class ContactDb
2678ContactDb objects have the following methods:
2679add contact()
2680Adds a new contact into the database. Returns a Contact object that represents the new
2681contact. The returned object is already locked for modification. Note that a newly created
2682contact will contain some empty default fields. If you do not want to use the default fields for
2683anything, you can ignore them.
268459
2685Page 66
2686find(searchterm)
2687Finds the contacts that contain the given Unicode string as a substring and returns them as
2688a list.
2689import vcards(vcards)
2690Imports the vCard(s) in the given string into the database.
2691export vcards(ids)
2692Converts the contacts corresponding to the ID’s in the given tuple ids to vCards and returns
2693them as a string.
2694keys()
2695Returns a list of unique IDs of all Contact objects in the database.
2696compact required()
2697Verifies whether compacting is recommended. Returns an integer value indicating either a
2698true or false state. Returns True if more than 32K of space is unused and if this comprises
2699more than 50 percent of the database file, or if more than 256K is wasted in the database file.
2700compact()
2701Compacts the database to its minimum size.
2702delitem
2703(id)
2704Deletes the given contact from the database.
2705field types()
2706Returns a list of dictionary objects that contains information on all supported field types.
2707The list contains dictionary objects, which each describe one field type. The most important
2708keys in the dictionary are ’type’ and ’location’ which together indentify the field type.
2709’type’ can have string values such as ’email address’. ’location’ can have the string
2710values ’none’, ’home’, or ’work’. Another important key is ’storagetype’, which defines
2711the storage type of the field. ’storagetype’ can have the string values ’text’, ’datetime’,
2712’item id’, or ’binary’. Note that the Contacts extension does not support adding, read-
2713ing, or modifying fields of any other type than ’text’ or ’datetime’. The other content
2714returned by field types is considered to be advanced knowledge and is not documented
2715here.
2716groups
2717Returns contact groups of the database. Read-only.
27187.1.3 Contact Object
2719A Contact object represents a live view into the state of a single contact in the database. You can access
2720the fields either with a contact’s numeric field ID as contact[fieldid], or using the find method.
2721Attempting to modify a contact while it has been locked for editing in another application will raise the
2722exception ContactBusy.
2723class Contact
2724Contact objects have the following attributes:
2725id
2726The unique ID of this Contact. Read-only.
2727title
2728The title of this Contact. Read-only.
2729is group
2730Returns 1 if this contact is a contact group. Returns 0 if normal contact entry. Read-only.
2731Contact objects have the following methods:
2732begin()
2733Locks the contact for editing. This prevents other applications from modifying the contact for
2734as long as the lock is held. This method will raise the exception ContactBusy if the contact
2735has already been locked.
2736commit()
2737Releases the lock and commits the changes made into the database.
273860
2739Chapter 7. Data Management
2740Page 67
2741rollback()
2742Releases the lock and discards all changes that were made. The contact remains in the state
2743it was before begin.
2744as vcard()
2745Returns the contact as a string in vCard format.
2746add field(type [, value [, label=field label ][, location=location spec ]])
2747Adds a new field into this Contact. This method raises ContactBusy if the contact has been
2748locked by some other application. type can be one of the supported field types as a string.
2749In Series 60 editions older than the 3rd one the following field types can be added:
2750•city
2751•company name
2752•country
2753•date
2754•dtmf string
2755•email address
2756•extended address
2757•fax number
2758•first name
2759•job title
2760•last name
2761•mobile number
2762•note
2763•pager number
2764•phone number
2765•po box
2766•postal address
2767•postal code
2768•state
2769•street address
2770•url
2771•video number
2772•wvid
2773The following field types are recognized but cannot be created:
2774•first name reading
2775•last name reading
2776•picture
2777•speed dial
2778•thumbnail image
2779•voicetag
2780If 3rd edition of Series 60 is used the following field types can be added:
2781•city
2782•company name
2783•country
2784•date
2785•dtmf string
2786•email address
2787•extended address
2788•fax number
2789•first name
2790•job title
27917.1. contacts — A contacts related services package
279261
2793Page 68
2794•last name
2795•mobile number
2796•note
2797•pager number
2798•phone number
2799•po box
2800•postal address
2801•postal code
2802•state
2803•street address
2804•url
2805•video number
2806•picture
2807•second name
2808•voip
2809•sip id
2810•personal ringtone
2811•share view
2812•prefix
2813•suffix
2814•push to talk
2815•locationid indication
2816The following field types are recognized but cannot be created at present:
2817•first name reading
2818•last name reading
2819•speed dial
2820•thumbnail image
2821•voice tag
2822•wvid
2823All supported field types are passed as strings or Unicode strings, except for ’date’ which is
2824a float that represents Unix time. For more information on Unix time, see Section 3.5, Date
2825and Time.
2826field label is the name of the field shown to the user. If you do not pass a label, the default
2827label for the field type is used.
2828location spec, if given, must be ’home’ or ’work’. Note that not all combinations of type
2829and location are valid. The settings of the current contacts database in use determine which
2830ones are valid.
2831find([type=field type ][, location=field location ])
2832Finds the fields of this contact that match the given search specifications. If no parameters
2833are given, all fields are returned.
2834delitem
2835(fieldindex)
2836Deletes the given field from this contact. Note that since this will change the indices of all
2837fields that appear after this field in the contact, and since the ContactField objects refer to
2838the fields by index, old ContactField objects that refer to fields after the deleted field will
2839refer to different fields after this operation.
28407.1.4 ContactField Object
2841A ContactField represents a field of a Contact at a certain index. A ContactField has attributes,
2842some of which can be modified. If the parent Contact has not been locked for editing, modifications
2843are committed immediately to the database. If the parent Contact has been locked, the changes are
2844committed only when commit is called on the Contact.
284562
2846Chapter 7. Data Management
2847Page 69
2848class ContactField
2849ContactField objects have the following attributes:
2850label
2851The user-visible label of this field. Read-write.
2852value
2853The value of this field. Read-write.
2854type
2855The type of this field. Read-only.
2856location
2857The location of this field. This can be ’none’, ’work’, or ’home’.
2858schema
2859A dictionary that contains some properties of this field. The contents of this dictionary
2860correspond to those returned by the ContactDb method field types.
28617.1.5 Groups Object
2862A Groups object represents Symbian contact groups as a dictionary like object with limited subset of
2863dictionary functionality. Each group can be accessed using the group’s unique id as a key. The Groups
2864object returns a list like Group object as the value matching the given key.
2865The following common methods are supported:
2866iter
2867,
2868getitem
2869,
2870delitem
2871and
2872len
2873.
2874class Groups
2875Groups objects have the following attributes:
2876add group([name ])
2877Creates new contact group and returns corresponding Group object. Group name can be given
2878as an optional parameter.
28797.1.6 Group Object
2880A Group object represents single Symbian contact group as a list object with limited subset of list
2881functionality. The Group object lists Contact entry ids that belong to the group.
2882The native Symbian group objects are represented as Symbian contact entries in the database. Therefore
2883they can also be accessed as Python Contact objects, but this way their group handling properties cannot
2884be used from Python. Use Groups and Group objects to access group functionalities.
2885The following common methods are supported:
2886iter
2887,
2888getitem
2889,
2890delitem
2891and
2892len
2893.
2894class Group
2895Group objects have the following attributes:
2896id
2897The unique id of the Group object. Read-only.
2898name
2899The name of the Group object. Read-write.
29007.1. contacts — A contacts related services package
290163
2902Page 70
2903Figure 7.1: The calendar module objects
29047.2 calendar — Access to calendar related services
2905The calendar module offers an API to calendar services. The calendar module represents a Symbian
2906agenda database as a dictionary-like CalendarDb object, which contains Entry objects and which is
2907indexed using the unique IDs of those objects. There are four types of entry objects: AppointmentEntry,
2908EventEntry, AnniversaryEntry, and TodoEntry.
2909CalendarDb objects represent a live view into the database. If an entry is changed outside your Python
2910application, the changes are visible immediately, and conversely any changes you commit into the
2911database are visible immediately to other applications.
2912In addition to entries, there are todo lists which contain todo entries. Todo lists are accessed using the
2913dictionary-like TodoListDict and TodoList objects.
2914All time parameters use Unix time unless stated otherwise. For more information on Unix time, see
2915Section 3.5, Date and Time.
2916Figure 7.1 demonstrates the relationships of the calendar module objects.
29177.2.1 Module Level Functions
2918The following free functions - functions that do not belong to any class - are defined in the calendar
2919module:
2920open([filename=None, mode=None ])
2921Opens a calendar database and returns a new CalendarDb object.
2922If filename is None, the default database is opened.
2923If filename is given, it should be a full, absolute path name in Unicode that specifies the calendar
2924database to open.
2925mode can be:
2926•None: Opens an existing calendar database.
2927•’c’: Opens an existing calendar database, or creates it if it doesn’t exist.
2928•’n’: Creates a new, empty calendar database. If filename exists, the previous contents are
2929erased.
293064
2931Chapter 7. Data Management
2932Page 71
29337.2.2 CalendarDb Objects
2934Calendar entries and todo lists are stored in a calendar database. There is one default calendar database
2935but more calendar databases can be created by invoking open with parameters ’n’ or ’c’.
2936class CalendarDb
2937CalendarDb objects have the following methods:
2938add appointment()
2939Creates and returns a new appointment entry AppointmentEntry. The entry is not added
2940and saved into the database until Entry.commit is called.
2941add event()
2942Creates and returns a new event entry EventEntry. The entry is not added and saved into
2943the database until Entry.commit is called.
2944add anniversary()
2945Creates and returns a new anniversary entry AnniversaryEntry. The entry is not added and
2946saved into the database until Entry.commit is called.
2947add todo()
2948Creates and returns new todo entry TodoEntry. The entry is not added and saved into the
2949database until Entry.commit is called.
2950find instances(start date, end date, search str=u”[ ,appointments=0,events=0,anniversaries=0,todos=0 ])
2951The parameters for this function include the start date, end date, search string, and optional
2952parameters. The optional parameters define the entry types to be included into the search.
2953By default all entry types are included. Returns a list that contains Entry instances found in
2954the search. An instance is a dictionary that contains the entry ID and the datetime value. An
2955entry may have several instances if it is repeated, for example once every week, etc. However,
2956all the returned instances occur on the same day, i.e. on the first day between the start
2957and end datetime values that contains instances. To search all instances between the initial
2958start and end datetime values, you may have to execute several searches and change the start
2959datetime value for each search. A match is detected if the search string is a substring of an
2960entry’s content.
2961monthly instances(month, appointments=0, events=0, anniversaries=0, todos=0)
2962The parameters for this function include month (float) and optional parameters. The optional
2963parameters define the entry types to be returned. Returns a list that contains entry instances
2964occurring during the specified calendar month.
2965daily instances(day, appointments=0, events=0, anniversaries=0, todos=0)
2966The parameters for this function include day (float) and optional parameters. The optional
2967parameters define the entry types to be returned. Returns a list that contains entry instances
2968occurring on the specified day.
2969add todo list([name=None ])
2970Creates a new todo list. name sets the name of the todo list (Unicode). Returns the ID of
2971the created todo list.
2972export vcalendars((int,...))
2973Returns a vcalendar string that contains the specified entries in vCalendar format. The
2974parameter for this function is a tuple that contains the entry IDs of the exported entries.
2975import vcalendars(string)
2976Imports vcalendar entries, given in the string parameter, to the database. Returns a tuple
2977that contains the unique IDs of the imported entries.
2978todo lists
2979Contains a dictionary-like TodoListDict object for accessing the todo lists of this database.
2980delitem
2981(id)
2982Deletes the given calendar Entry from the database. id is the unique ID of the calendar
2983Entry.
2984getitem
2985(id)
2986Returns a calendar Entry object indicated by the unique ID. The returned object can be one
29877.2. calendar — Access to calendar related services
298865
2989Page 72
2990of the following: AppointmentEntry, EventEntry, AnniversaryEntry, or TodoEntry. id is
2991the unique ID of the calendar Entry.
2992compact()
2993Compacts the database file. The returned value (integer) indicates the success of compaction;
2994a value other than zero means that the compaction was successful.
29957.2.3 Entry Objects
2996An Entry object represents a live view into the state of a single entry in the database. You can access
2997the entries with an entry’s unique ID. If you create a new entry using db.add appointment etc., it is
2998saved into the database only if you call the entry’s commit method. In case an entry is already saved
2999into the database, the autocommit mode is on by default and all the changes are automatically saved
3000into the database, unless you call the entry’s begin method. If you call the entry’s begin method, the
3001changes are not saved into the database until you call the entry’s commit method.
3002Database entries cannot be locked. In other words, other applications are able to make changes to the
3003database entries you are using (not directly to the EntryObjects you are using, but to their representation
3004in the database) at the same time you are modifying them, even if you use begin and commit methods.
3005class Entry
3006Entry objects have the following methods and properties:
3007content
3008Sets or returns the entry’s content text (Unicode).
3009commit()
3010Saves the entry or in case of a new entry adds the entry into the database. Note that this can
3011be called only in case of a new entry, created with db.add appointment etc., or after begin
3012is called.
3013rollback()
3014Undoes the changes made after last commit.
3015set repeat(dictionary)
3016Sets the repeat data of the entry. dictionary is a repeat data dictionary that contains all the
3017repeat rules. For more information on repeat rules, see Section 7.3.4, Repeat Rules.
3018get repeat()
3019Returns the repeat data dictionary of the entry.
3020location
3021Sets or returns the entry’s location data (Unicode), for example meeting room information.
3022set time(start[, end ])
3023Sets the start and end datetime values of the entry (floats). If only one parameter is given,
3024the other will have the same value.
3025In case of events, anniversaries, and todo entries the datetime values are truncated to corre-
3026sponding date values.
3027TodoEntries can be made undated with TodoEntry.set time(None). Making the todo entry
3028undated means removing the start and end date and all the repeat rules.
3029start time
3030The start datetime value (float) of the entry or None if the start datetime of the entry is not
3031set.
3032end time
3033The end datetime value (float) of the entry or None if the end datetime of the entry is not set.
3034id
3035The unique ID of the entry.
3036last modified
3037The datetime value (float) of the entry’s last modification in universal time.
303866
3039Chapter 7. Data Management
3040Page 73
3041alarm
3042The alarm datetime value (float) for the entry. None if alarm is not set. Alternatively removes
3043the alarm if the value is set to None.
3044Alarms can be set to all Entry types. However, only alarms set to Appointments and Anniver-
3045saries will actually cause an alarm; this is similar to the Calendar application in your Nokia
3046device, which allows you to set an alarm only for Meetings and Anniversaries. In addition,
3047alarms set to any entries residing in a database other than the default database do not cause
3048actual alarms either.
3049priority
3050The priority of the entry, which can be an integer ranging from 0 to 255. Native Phonebook
3051and Calendar applications in Nokia devices use value 1 for high priority, 2 for normal priority,
3052and 3 for low priority.
3053crossed out
3054The crossed out value of an entry. A value that is interpreted as false means that the entry is
3055not crossed out, whereas a value that is interpreted as true means that the entry is crossed out.
3056Note that TodoEntries must also have a cross-out time while the other entry types cannot
3057have one. If TodoEntry is crossed out using this method, the moment of crossing out is set
3058to the cross-out time of the TodoEntry. See also Section 7.3.3, TodoEntry, cross out time.
3059replication
3060Sets or returns the entry’s replication status, which can be one of the following: ’open’,
3061’private’, or ’restricted’.
3062as vcalendar()
3063Returns this entry as a vCalendar string.
3064AppointmentEntry Objects
3065class AppointmentEntry
3066AppointmentEntry class contains no additional methods compared to the Entry class from which it is
3067derived.
3068EventEntry
3069class EventEntry
3070EventEntry class contains no additional methods compared to the Entry class from which it is derived.
3071AnniversaryEntry
3072class AnniversaryEntry
3073AnniversaryEntry class contains no additional methods compared to the Entry class from which it is
3074derived.
3075TodoEntry
3076TodoEntryobjects represent todo entry types. They have additional properties compared to the Entry
3077class from which they are derived.
3078class TodoEntry
3079TodoEntryobjects have the following additional properties:
3080cross out time
3081The cross-out date value of the entry. The value can be None meaning that the entry is
3082not crossed out, or the cross-out date (float). The set value must be date (float). Setting a
3083cross-out time also crosses out the entry. See also Section 7.3.3, Entry Object, crossed out.
30847.2. calendar — Access to calendar related services
308567
3086Page 74
3087todo list
3088The ID of the todo list to which this entry belongs.
3089TodoListDict
3090TodoListDict objects are dictionary-like objects that enable accessing todo lists.
3091class TodoListDict
3092TodoListDict objects have the following property:
3093default list
3094The ID of the default todo list.
3095TodoList
3096TodoList objects are dictionary-like objects that enable accessesing todo lists.
3097class TodoList
3098TodoList objects have the following properties:
3099name
3100The name of the todo list as a Unicode string.
3101id
3102Returns the ID of the todo list as an integer.
31037.2.4 Repeat Rules
3104Repeat rules specify an entry’s repeat status, that is, the recurrence of the entry. There are six repeat
3105types:
3106• daily: repeated daily
3107• weekly: repeat on the specified days of the week, such as Monday and Wednesday, etc.
3108• monthly by dates: repeat monthly on the specified dates, such as the 15th and 17th day of the
3109month
3110• monthly by days: repeat monthly on the specified days, such as the fourth Wednesday of the
3111month, or the last Monday of the month
3112• yearly by date: repeat yearly on the specified date, such as December 24
3113• yearly by day: repeat yearly on the specified day, such as every third Tuesday of May
3114There are exceptions to repeat rules. For example, you can specify the datetime value (float) in such a
3115way that the entry is not repeated on a specific day even if the repeat rule would specify otherwise.
3116You must set the start and end dates (floats) of the repeat. The end date can also be set to None to
3117indicate that the repeating continues forever. You can set interval defining how often the repeat occurs,
3118for example in a daily repeat: 1 means every day, 2 means every second day, etc. You can also set the
3119days specifier which lets you explicitly specify the repeat days; for example in a weekly repeat you can
3120set "days":[0,2] which sets the repeat to occur on Mondays and Wednesdays. If you do not set the
3121days specifier, the repeat days are calculated automatically based on the start date.
3122You can modify repeat data by calling rep data = entry.get repeat(), then making changes to
3123rep data dictionary, and then calling entry.set repeat(rep data).
3124Repeating can be cancelled by calling entry.set repeat with a parameter that is interpreted to be
3125false, such as entry.set repeat(None).
3126Repeat definition examples:
312768
3128Chapter 7. Data Management
3129Page 75
3130repeat = {"type":"daily", #repeat type
3131"exceptions":[exception_day, exception_day+2*24*60*60],
3132#no appointment on those days
3133"start":appt_start_date, #start of the repeat
3134"end":appt_start_date+30*24*60*60, #end of the repeat
3135"interval":1} #interval (1=every day, 2=every second day etc.)
3136repeat = {"type":"weekly", #repeat type
3137"days":[0,1], #which days in a week (Monday, Tuesday)
3138"exceptions":[exception_day], #no appointment on that day
3139"start":appt_start_date, #start of the repeat
3140"end":appt_start_date+30*24*60*60, #end of the repeat
3141"interval":1}
3142#interval (1=every week, 2=every second week etc.)
3143repeat = {"type":"monthly_by_days", #repeat type
3144# appointments on second Tuesday and last Monday of the month
3145"days":[{"week":1, "day":1},{"week":4, "day":0}],
3146"exceptions":[exception_day], #no appointment on that day
3147"start":appt_start_date, #start of the repeat
3148"end":appt_start_date+30*24*60*60, #end of the repeat
3149"interval":1}
3150#interval (1=every month, 2=every second month etc.)
3151repeat = {"type":"monthly_by_dates", #repeat type
3152"days":[0,15],
3153# appointments on the 1st and 16th day of the month.
3154"exceptions":[exception_day], #no appointment on that day
3155"start":appt_start_date, #start of the repeat
3156"end":appt_start_date+30*24*60*60, #end of the repeat
3157"interval":1}
3158#interval (1=every month, 2=every second month etc.)
3159repeat = {"type":"yearly_by_date", #repeat type
3160"exceptions":[exception_day], #no appointment on that day
3161"start":appt_start_date, #start of the repeat
3162"end":appt_start_date+3*365*24*60*60, #end of the repeat
3163"interval":1}
3164#interval (1=every year, 2=every second year etc.)
3165repeat = {"type":"yearly_by_day", #repeat type
3166# appointments on the second Tuesday of February
3167"days":{"day":1, "week":1, "month":1},
3168"exceptions":[exception_day], #no appointment on that day
3169"start":appt_start_date, #start of the repeat
3170"end":appt_start_date+3*365*24*60*60, #end of the repeat
3171"interval":1}
3172#interval (1=every year, 2=every second year etc.)
31737.3 calendar for EKA2 — Access to calendar related services
3174The calendar module offers an API to calendar services. The calendar module represents a Symbian
3175agenda database as a dictionary-like CalendarDb object, which contains Entry objects and which is
3176indexed using the unique IDs of those objects. There are five types of entry objects: AppointmentEntry,
3177EventEntry, AnniversaryEntry, ReminderEntry, and TodoEntry.
3178CalendarDb objects represent a live view into the database. If an entry is changed outside your Python
3179application, the changes are visible immediately, and conversely any changes you commit into the
3180database are visible immediately to other applications.
31817.3. calendar for EKA2 — Access to calendar related services
318269
3183Page 76
3184All time parameters use Unix time unless stated otherwise. For more information on Unix time, see
3185Section 3.5, Date and Time.
31867.3.1 Module Level Functions
3187The following free functions - functions that do not belong to any class - are defined in the calendar
3188module:
3189open([filename=None, mode=None ])
3190Opens a calendar database and returns a new CalendarDb object.
3191If filename is None, the default database is opened.
3192If filename is given, it should contain drive letter, colon and file’s name, but no absolute path.
3193mode can be:
3194•None: Opens an existing calendar database.
3195•’c’: Opens an existing calendar database, or creates it if it doesn’t exist.
3196•’n’: Creates a new, empty calendar database. If filename exists, the previous contents are
3197erased.
31987.3.2 CalendarDb Objects
3199Calendar entries are stored in a calendar database. There is one default calendar database but more
3200calendar databases can be created by invoking open with parameters ’n’ or ’c’.
3201class CalendarDb
3202CalendarDb objects have the following methods:
3203add appointment()
3204Creates and returns a new appointment entry AppointmentEntry. The entry is not added
3205and saved into the database until Entry.commit is called.
3206add event()
3207Creates and returns a new event entry EventEntry. The entry is not added and saved into
3208the database until Entry.commit is called.
3209add anniversary()
3210Creates and returns a new anniversary entry AnniversaryEntry. The entry is not added and
3211saved into the database until Entry.commit is called.
3212add todo()
3213Creates and returns new todo entry TodoEntry. The entry is not added and saved into the
3214database until Entry.commit is called.
3215add reminder()
3216Creates and returns new reminder entry ReminderEntry. The entry is not added and saved
3217into the database until Entry.commit is called.
3218find instances(start date, end date, search str=u”[ ,appointments=0,events=0,anniversaries=0,todos=0,reminders=0 ])
3219The parameters for this function include the start date, end date, search string, and optional
3220parameters. The optional parameters define the entry types to be included into the search.
3221By default all entry types are included. Returns a list that contains Entry instances found
3222in the search. An instance is a dictionary that contains the entry ID and the datetime value.
3223An entry may have several instances if it is repeated, for example once every week, etc.
3224monthly instances(month, appointments=0, events=0, anniversaries=0, todos=0, reminders=0)
3225The parameters for this function include month (float) and optional parameters. The optional
3226parameters define the entry types to be returned. Returns a list that contains entry instances
3227occurring during the specified calendar month.
322870
3229Chapter 7. Data Management
3230Page 77
3231daily instances(day, appointments=0, events=0, anniversaries=0, todos=0)
3232The parameters for this function include day (float) and optional parameters. The optional
3233parameters define the entry types to be returned. Returns a list that contains entry instances
3234occurring on the specified day.
3235export vcalendars((int,...))
3236Returns a vcalendar string that contains the specified entries in vCalendar format. The
3237parameter for this function is a tuple that contains the entry IDs of the exported entries.
3238import vcalendars(string)
3239Imports vcalendar entries, given in the string parameter, to the database. Returns a list
3240that contains the unique IDs of the imported entries.
3241delitem
3242(id)
3243Deletes the given calendar Entry from the database. id is the unique ID of the calendar
3244Entry.
3245getitem
3246(id)
3247Returns a calendar Entry object indicated by the unique ID. The returned object can be one
3248of the following: AppointmentEntry, EventEntry, AnniversaryEntry, ReminderEntry, or
3249TodoEntry. id is the unique ID of the calendar Entry.
32507.3.3 Entry Objects
3251An Entry object represents a live view into the state of a single entry in the database. You can access
3252the entries with an entry’s unique ID. If you create a new entry using db.add appointment etc., it is
3253saved into the database only if you call the entry’s commit method. In case an entry is already saved
3254into the database, the autocommit mode is on by default and all the changes are automatically saved
3255into the database, unless you call the entry’s begin method. If you call the entry’s begin method, the
3256changes are not saved into the database until you call the entry’s commit method.
3257Database entries cannot be locked. In other words, other applications are able to make changes to the
3258database entries you are using (not directly to the EntryObjects you are using, but to their representation
3259in the database) at the same time you are modifying them, even if you use begin and commit methods.
3260class Entry
3261Entry objects have the following methods and properties:
3262content
3263Sets or returns the entry’s content text (Unicode).
3264commit()
3265Saves the entry or in case of a new entry adds the entry into the database. Note that this can
3266be called only in case of a new entry, created with db.add appointment etc., or after begin
3267is called.
3268rollback()
3269Undoes the changes made after last commit.
3270set repeat(dictionary)
3271Sets the repeat data of the entry. dictionary is a repeat data dictionary that contains all the
3272repeat rules. For more information on repeat rules, see Section 7.3.4, Repeat Rules.
3273get repeat()
3274Returns the repeat data dictionary of the entry.
3275location
3276Sets or returns the entry’s location data (Unicode), for example meeting room information.
3277set time(start[, end ])
3278Sets the start and end datetime values of the entry (floats). If only one parameter is given,
3279the other will have the same value.
3280In case of events, anniversaries, and todo entries the datetime values are truncated to corre-
3281sponding date values.
3282TodoEntries can be made undated with TodoEntry.set time(None). Making the todo entry
3283undated means removing the start and end date and all the repeat rules.
32847.3. calendar for EKA2 — Access to calendar related services
328571
3286Page 78
3287start time
3288The start datetime value (float) of the entry or None if the start datetime of the entry is not
3289set.
3290end time
3291The end datetime value (float) of the entry or None if the end datetime of the entry is not set.
3292id
3293The unique ID of the entry.
3294last modified
3295The datetime value (float) of the entry’s last modification in universal time.
3296originating
3297An integer value indicating if the entry is an originating entry or a modifying entry.
3298alarm
3299The alarm datetime value (float) for the entry. None if alarm is not set. Alternatively removes
3300the alarm if the value is set to None.
3301Alarms can be set to all Entry types. However, only alarms set to Appointments and Anniver-
3302saries will actually cause an alarm; this is similar to the Calendar application in your Nokia
3303device, which allows you to set an alarm only for Meetings and Anniversaries. In addition,
3304alarms set to any entries residing in a database other than the default database do not cause
3305actual alarms either.
3306priority
3307The priority of the entry, which can be an integer ranging from 0 to 255. Native Phonebook
3308and Calendar applications in Nokia devices use value 1 for high priority, 2 for normal priority,
3309and 3 for low priority.
3310crossed out
3311The crossed out value of an entry. Only valid for todo entries. A value that is interpreted as
3312false means that the entry is not crossed out, whereas a value that is interpreted as true means
3313that the entry is crossed out. Note that TodoEntries must also have a cross-out time. If
3314TodoEntry is crossed out using this method, the moment of crossing out is set to the cross-out
3315time of the TodoEntry. See also Section 7.3.3, TodoEntry, cross out time.
3316replication
3317Sets or returns the entry’s replication status, which can be one of the following: ’open’,
3318’private’, or ’restricted’.
3319as vcalendar()
3320Returns this entry as a vCalendar string.
3321AppointmentEntry Objects
3322class AppointmentEntry
3323AppointmentEntry class contains no additional methods compared to the Entry class from which it is
3324derived.
3325EventEntry
3326class EventEntry
3327EventEntry class contains no additional methods compared to the Entry class from which it is derived.
3328AnniversaryEntry
3329class AnniversaryEntry
3330AnniversaryEntry class contains no additional methods compared to the Entry class from which it is
3331derived.
333272
3333Chapter 7. Data Management
3334Page 79
3335ReminderEntry
3336class ReminderEntry
3337ReminderEntry class contains no additional methods compared to the Entry class from which it is
3338derived.
3339TodoEntry
3340TodoEntryobjects represent todo entry types. They have additional properties compared to the Entry
3341class from which they are derived.
3342class TodoEntry
3343TodoEntryobjects have the following additional properties:
3344cross out time
3345The cross-out date value of the entry. The value can be None meaning that the entry is
3346not crossed out, or the cross-out date (float). The set value must be date (float). Setting a
3347cross-out time also crosses out the entry. See also Section 7.3.3, Entry Object, crossed out.
33487.3.4 Repeat Rules
3349Repeat rules specify an entry’s repeat status, that is, the recurrence of the entry. There are six repeat
3350types:
3351• daily: repeated daily
3352• weekly: repeat on the specified days of the week, such as Monday and Wednesday, etc.
3353• monthly by dates: repeat monthly on the specified dates, such as the 15th and 17th day of the
3354month
3355• monthly by days: repeat monthly on the specified days, such as the fourth Wednesday of the
3356month, or the last Monday of the month
3357• yearly by date: repeat yearly on the specified date, such as December 24
3358• yearly by day: repeat yearly on the specified day, such as every third Tuesday of May
3359There are exceptions to repeat rules. For example, you can specify the datetime value (float) in such a
3360way that the entry is not repeated on a specific day even if the repeat rule would specify otherwise.
3361You must set the start and end dates (floats) of the repeat. The end date can also be set to None to
3362indicate that the repeating continues forever. You can set interval defining how often the repeat occurs,
3363for example in a daily repeat: 1 means every day, 2 means every second day, etc. You can also set the
3364days specifier which lets you explicitly specify the repeat days; for example in a weekly repeat you can
3365set "days":[0,2] which sets the repeat to occur on Mondays and Wednesdays. If you do not set the
3366days specifier, the repeat days are calculated automatically based on the start date.
3367You can modify repeat data by calling rep data = entry.get repeat(), then making changes to
3368rep data dictionary, and then calling entry.set repeat(rep data).
3369Repeating can be cancelled by calling entry.set repeat with a parameter that is interpreted to be
3370false, such as entry.set repeat(None).
3371Repeat definition examples:
3372repeat = {"type":"daily", #repeat type
3373"exceptions":[exception_day, exception_day+2*24*60*60],
3374#no appointment on those days
3375"start":appt_start_date, #start of the repeat
33767.3. calendar for EKA2 — Access to calendar related services
337773
3378Page 80
3379"end":appt_start_date+30*24*60*60, #end of the repeat
3380"interval":1} #interval (1=every day, 2=every second day etc.)
3381repeat = {"type":"weekly", #repeat type
3382"days":[0,1], #which days in a week (Monday, Tuesday)
3383"exceptions":[exception_day], #no appointment on that day
3384"start":appt_start_date, #start of the repeat
3385"end":appt_start_date+30*24*60*60, #end of the repeat
3386"interval":1}
3387#interval (1=every week, 2=every second week etc.)
3388repeat = {"type":"monthly_by_days", #repeat type
3389# appointments on second Tuesday and last Monday of the month
3390"days":[{"week":1, "day":1},{"week":4, "day":0}],
3391"exceptions":[exception_day], #no appointment on that day
3392"start":appt_start_date, #start of the repeat
3393"end":appt_start_date+30*24*60*60, #end of the repeat
3394"interval":1}
3395#interval (1=every month, 2=every second month etc.)
3396repeat = {"type":"monthly_by_dates", #repeat type
3397"days":[0,15],
3398# appointments on the 1st and 16th day of the month.
3399"exceptions":[exception_day], #no appointment on that day
3400"start":appt_start_date, #start of the repeat
3401"end":appt_start_date+30*24*60*60, #end of the repeat
3402"interval":1}
3403#interval (1=every month, 2=every second month etc.)
3404repeat = {"type":"yearly_by_date", #repeat type
3405"exceptions":[exception_day], #no appointment on that day
3406"start":appt_start_date, #start of the repeat
3407"end":appt_start_date+3*365*24*60*60, #end of the repeat
3408"interval":1}
3409#interval (1=every year, 2=every second year etc.)
3410repeat = {"type":"yearly_by_day", #repeat type
3411# appointments on the second Tuesday of February
3412"days":{"day":1, "week":1, "month":1},
3413"exceptions":[exception_day], #no appointment on that day
3414"start":appt_start_date, #start of the repeat
3415"end":appt_start_date+3*365*24*60*60, #end of the repeat
3416"interval":1}
3417#interval (1=every year, 2=every second year etc.)
34187.4 e32db — Interface to the Symbian native DB
3419The e32db module provides an API for relational database manipulation with a restricted SQL syntax.
3420For details of DBMS support, see the S60 SDK documentation. For examples on using this module, see
3421[6].
3422The e32db module defines the following functions:
3423format rawtime(timevalue)
3424Formats timevalue (Symbian time) according to the current system’s date/time formatting rules
3425and returns it as a Unicode string.
3426format time(timevalue)
3427Formats timevalue according to the current system’s date/time formatting rules and returns it as
3428a Unicode string.
342974
3430Chapter 7. Data Management
3431Page 81
34327.4.1 Dbms Objects
3433class Dbms()
3434Creates a Dbms object. Dbms objects support basic operations on a database.
3435Dbms objects have the following methods:
3436begin()
3437Begins a transaction on the database.
3438close()
3439Closes the database object. It is safe to try to close a database object even if it is not open.
3440commit()
3441Commits the current transaction.
3442compact()
3443Compacts the database, reclaiming unused space in the database file.
3444create(dbname)
3445Creates a database with path dbname.
3446execute(query)
3447Executes an SQL query. On success, returns 0 if a DDL (SQL schema update) statement was
3448executed. Returns the number of rows inserted, updated, or deleted, if a DML (SQL data update)
3449statement was executed.
3450open(dbname)
3451Opens the database in file dbname. This should be a full Unicode path name, for example,
3452u’c:\\foo.db’.
3453rollback()
3454Rolls back the current transaction.
34557.4.2 DB view Objects
3456class Db view()
3457Creates a Db view object. DB view objects generate rowsets from a SQL query. They provide
3458functions to parse and evaluate the rowsets.
3459Db view objects have the following methods:
3460col(column)
3461Returns the value in column. The first column of the rowset has the index 1. If the type of the
3462column is not supported, a TypeError is raised. See Table 7.1 for a list of supported data types.
3463col count()
3464Returns the number of columns defined in the rowset.
3465col length(column)
3466Gets the length of the value in column. Empty columns have a length of zero; non-empty numerical
3467and date/time columns have a length of 1. For text columns, the length is the character count,
3468and for binary columns, the length is the byte count.
3469col raw(column)
3470Extracts the value of column as raw binary data, and returns it as a Python string. The first
3471column of the rowset has the index 1. See Table 7.1 for a list of supported data types.
3472col rawtime(column)
3473Extracts the value of a date/time column at index column as a long integer, which represents the
3474raw Symbian time value. The first column of the rowset has the index 1. See Table 7.1 for a list
3475of the supported data types.
3476col type(column)
3477Returns the numeric type of the given column as an integer from a Symbian-specific list of types.
3478This function is used in the implementation of method col.
34797.4. e32db — Interface to the Symbian native DB
348075
3481Page 82
3482count line()
3483Returns the number of rows available in the rowset.
3484first line()
3485Positions the cursor on the first row in the rowset.
3486get line()
3487Gets the current row data for access.
3488is col null(column)
3489Tests whether column is empty. Empty columns can be accessed like normal columns. Empty
3490numerical columns return a 0 or an equivalent value, and text and binary columns have a zero
3491length.
3492next line()
3493Moves the cursor to the next row in the rowset.
3494prepare(db, query)
3495Prepares the view object for evaluating an SQL select statement. db is a Dbms object and query
3496the SQL query to be executed.
34977.4.3 Mapping Between SQL and Python Data Types
3498See Table 7.1 for a summary of mapping between SQL and Python data types. The col function can
3499extract any value except LONG VARBINARY and return it as the proper Python value. In addition, the
3500col raw function can extract any column type except LONG VARCHAR and LONG VARBINARY as raw binary
3501data and return it as a Python string.
3502Inserting, updating, or searching for BINARY, VARBINARY, or LONG VARBINARY values is not supported.
3503BINARY and VARBINARY values can be read with col or col raw.
3504SQLtype
3505Symbian column type (in the
3506DBMS C++ API)
3507Python type
3508Supported
3509BIT
3510EDbColBit
3511int
3512yes
3513TINYINT
3514EDbColInt8
3515UNSIGNED TINYINT
3516EDbColUint8
3517SMALLINT
3518EDbColInt16
3519UNSIGNED SMALLINT
3520EDbColUint16
3521INTEGER
3522EDbColInt32
3523UNSIGNED INTEGER
3524EDbColUint32
3525COUNTER
3526EDbColUint32 (with the TDb-
3527Col::EAutoIncrement attribute)
3528BIGINT
3529EDbColInt64
3530long
3531REAL
3532EDbColReal32
3533float
3534FLOAT
3535EDbColReal64
3536DOUBLE
3537DOUBLE PRECISION
3538DATE
3539EDbColDateTime
3540float (or long, with col rawtime())
3541TIME
3542TIMESTAMP
3543CHAR(n)
3544EDbColText
3545Unicode
3546VARCHAR(n)
3547LONG VARCHAR
3548EDbColLongText
3549BINARY(n)
3550EDbColBinary
3551str
3552read only
3553VARBINARY(n)
3554LONG VARBINARY
3555EDbColLongBinary
3556n/a
3557no
3558Table 7.1: Mapping between SQL and Python types
355976
3560Chapter 7. Data Management
3561Page 83
35627.4.4 Date and Time Handling
3563The functions col and format time use Unix time, seconds since January 1, 1970, 00:00:00 UTC, as the
3564time format. Internally the database uses the native Symbian time representation that provides greater
3565precision and range than the Unix time. The native Symbian time format is a 64-bit value that represents
3566microseconds since January 1st 0 AD 00:00:00 local time, nominal Gregorian. BC dates are represented
3567by negative values. Since converting this format to Unix time and back may cause slight round-off errors,
3568you have to use the functions col rawtime and format rawtime if you need to be able to handle these
3569values with full precision.
3570The representation of date and time literals in SQL statements depends on the current system date and
3571time format. Note that the only accepted ordering of day, month, and year is the one that the system is
3572currently configured to use. Dates in other order are rejected. The recommended way to form date/time
3573literals for SQL statements is to use the functions format time or format rawtime that format the
3574given date/time values properly according to the current system’s date/time format settings.
35757.5 e32dbm — DBM implemented using the Symbian native DBMS
3576The e32dbm module provides a DBM API that uses the native Symbian RDBMS as its storage back-end.
3577The module API resembles that of the gdbm module. The main differences are:
3578• The firstkey() - nextkey() interface for iterating through keys is not supported. Use the "for
3579key in db" idiom or the keys or keysiter methods instead.
3580• This module supports a more complete set of dictionary features than gdbm
3581• The values are always stored as Unicode, and thus the values returned are Unicode strings even if
3582they were given to the DBM as normal strings.
35837.5.1 Module Level Functions
3584The e32dbm defines the following functions:
3585open(dbname[,flags, mode ])
3586Opens or creates the given database file and returns an e32dbm object. Note that dbname should
3587be a full path name, for example, u’c:\\foo.db’. Flags can be:
3588•’r’: opens an existing database in read-only mode. This is the default value.
3589•’w’: opens an existing database in read-write mode.
3590•’c’: opens a database in read-write mode. Creates a new database if the database does not
3591exist.
3592•’n’: creates a new empty database and opens it in read-write mode.
3593If the character ’f’ is appended to flags, the database is opened in fast mode. In fast mode, updates
3594are written to the database only when one of these methods is called: sync, close, reorganize,
3595or clear.
3596Since the connection object destructor calls close, it is not strictly necessary to close the database before
3597exiting to ensure that data is saved, but it is still good practice to call the close method when you are
3598done with using the database. Closing the database releases the lock on the file and allows the file to be
3599reopened or deleted without exiting the interpreter.
3600If you plan to do several updates, it is highly recommended that you open the database in fast mode,
3601since inserts and updates are more efficient when they are bundled together in a larger transaction. This
3602is especially important when you plan to insert large amounts of data, since inserting records to e32db
3603is very slow if done one record at a time.
36047.5. e32dbm — DBM implemented using the Symbian native DBMS
360577
3606Page 84
36077.5.2 e32dbm Objects
3608The e32dbm objects returned by the open function support most of the standard dictionary methods.
3609The supported dictionary methods are:
3610•
3611getitem
3612•
3613setitem
3614•
3615delitem
3616• has key
3617• update
3618•
3619len
3620•
3621iter
3622• iterkeys
3623• iteritems
3624• itervalues
3625• get
3626• setdefault
3627• pop
3628• popitem
3629• clear
3630These work the same way as the corresponding methods in a normal dictionary.
3631In addition, e32dbm objects have the following methods:
3632close()
3633Closes the database. In fast mode, commits all pending updates to disk. close raises an exception
3634if called on a database that is not open.
3635reorganize()
3636Reorganizes the database. Reorganization calls compact on the underlying e32db database file,
3637which reclaims unused space in the file. Reorganizing the database is recommended after several
3638updates.
3639sync()
3640In fast mode, commits all pending updates to disk.
364178
3642Chapter 7. Data Management
3643Page 85
3644CHAPTER
3645EIGHT
3646Standard Library Support and Extensions
36478.1 Support for Python Standard Library
3648The standard library support in Python for S60 is summarized in Table 8.1. For API descriptions, see
3649[1].
3650Name
3651Type
3652Status Remarks
3653testcapi
3654PYD
3655Y
3656anydbm
3657PY
3658X
3659DBM API is implemented by PY e32dbm that
3660relies on PYD e32db (see Chapter 7.5, e32dbm
3661Module)
3662atexit
3663PY
3664X
3665base64
3666PY
3667X
3668bdb
3669PY
3670(X)
3671binascii
3672built-in X
3673cmd
3674PY
3675(X)
3676code
3677PY
3678X
3679codecs
3680PY
3681X
3682codeop
3683PY
3684X
3685copy
3686PY
3687X
3688copy reg
3689PY
3690X
3691cStringIO
3692built-in X
3693dis
3694PY
3695(X)
3696errno
3697built-in X
3698exceptions
3699built-in X
3700future
3701PY
3702X
3703httplib
3704PY
3705X
3706imp
3707built-in X
3708keyword
3709PY
3710X
3711linecache
3712PY
3713X
3714marshal
3715built-in X
3716math
3717built-in X
3718md51
3719built-in X
3720mimetools
3721PY
3722X
3723operator
3724built-in X
3725os, os.path
3726PY
3727X
3728Wraps built-in e32posix. Limitations dis-
3729cussed in Section 3.9, Limitations and Areas
3730of Development.
3731pdb
3732PY
3733(X)
3734quopri
3735PY
3736X
3737Name
3738Type
3739Status
3740Remarks
37411Derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm.
374279
3743Page 86
3744random
3745PY
3746X
3747re
3748PY
3749X
3750Uses PY sre as its engine.
3751repr
3752PY
3753X
3754rfc822
3755PY
3756X
3757select
3758PY
3759X
3760A minimal implementation: select is sup-
3761ported only for input from sockets.
3762socket
3763PY
3764X
3765Requires PYD e32socket. Contains exten-
3766sions as described in Section 8.2.2, socket
3767Module. Limitations discussed in Section 3.9,
3768Limitations and Areas of Development.
3769sre
3770PY
3771X
3772Wraps built-in sre.
3773string
3774PY
3775X
3776StringIO
3777PY
3778X
3779struct
3780built-in X
3781sys
3782built-in X
3783thread
3784built-in X
3785Contains extensions as described in Section
37868.2.1, thread Module
3787threading
3788PY
3789(X)
3790time
3791built-in X
3792traceback
3793PY
3794X
3795types
3796PY
3797X
3798urllib
3799PY
3800X
3801urlparse(urlsplit only) PY
3802X
3803uu
3804PY
3805X
3806warnings
3807PY
3808X
3809whichdb
3810PY
3811X
3812xreadlines
3813built-in X
3814zipfile
3815PY
3816X
3817zlib
3818PYD
3819X
3820Table 8.1: Status of library module support.
3821Table 8.1 uses the following coding for module types:
3822• PY – module is implemented in Python.
3823• Built-in – module is a built-in C/C++ module.
3824• PYD – module is a dynamically loadable C/C++ module.
3825For support status, the following codes are used:
3826• X – included to the Series 60 Python distribution.
3827• (X) – not included to the Series 60 Python distribution, but works both on phone and SDK.
3828• Y – included only to the SDK distribution.
38298.2 Extensions to Standard Library Modules
3830The following standard modules have been extended.
383180
3832Chapter 8. Standard Library Support and Extensions
3833Page 87
38348.2.1 thread — S60 extensions to standard thread module
3835The following function has been added to the standard thread module:
3836ao waittid(thread id)
3837Synchronizes with the end of the execution of the thread identified by the given thread id. The
3838implementation is based on a Symbian OS active object. For the blocking behavior, see Section
38394.1.2, Ao lock Type.
38408.2.2 socket — S60 extensions to standard socket module
3841Bluetooth (BT) support has been added to the standard socket module. The following related constants
3842and functions are defined:
3843Note:
3844In release 1.0 the functions bt advertise service, bt obex receive, and
3845bt rfcomm get available server channel incorrectly expected to be given the internal
3846e32socket.socket object as the socket parameter instead of the proper socket object. Now the func-
3847tions work correctly. The old calling convention is still supported but it is deprecated and may be
3848removed in a future release.
3849AF BT
3850Represents the Bluetooth address family.
3851BTPROTO RFCOMM
3852This constant represents the Bluetooth protocol RFCOMM.
3853RFCOMM
3854OBEX
3855Bluetooth service classes supported by bt advertise service.
3856AUTH
3857ENCRYPT
3858AUTHOR
3859Bluetooth security mode flags.
3860bt advertise service(name, socket, flag, class)
3861Sets a service advertising the service name (Unicode) on local channel that is bound to socket.
3862If flag is True, the advertising is turned on, otherwise it is turned off. The service class to be
3863advertised is either RFCOMM or OBEX.
3864bt discover([address ])
3865Performs the Bluetooth device discovery (if the optional BT device address is not given) and the
3866discovery of RFCOMM class services on the chosen device. Returns a pair: BT device address,
3867dictionary of services, where Unicode service name is the key and the corresponding port is the
3868value.
3869bt obex discover([address ])
3870Same as discover, but for discovery of OBEX class services on the chosen device.
3871bt obex send file(address, channel, filename)
3872Sends file filename (Unicode) wrapped into an OBEX object to remote address, channel.
3873bt obex receive(socket, filename)
3874Receives a file as an OBEX object, unwraps and stores it into filename (Unicode). socket is a
3875bound OBEX socket.
3876bt rfcomm get available server channel(socket)
3877Returns an available RFCOMM server channel for socket.
3878set security(socket, mode)
3879Sets the security level of the given bound socket. The mode is an integer flag that is formed using
3880a binary or operation of one or more of: AUTH (authentication), ENCRYPT, AUTHOR (authorization).
3881Example: set security(s, AUTH | AUTHOR).
38828.2. Extensions to Standard Library Modules
388381
3884Page 88
3885Note: When listening to a Bluetooth socket on the phone, it is necessary to set the security level.
3886Note: SSL is not supported in S60 1st Edition. SSL client certificates are not supported at all.
3887For examples on the usage of these functions, see Programming with Python for S60 Platform [6].
3888Setting default Access Point (AP) has been added to the standard socket module. The following related
3889constants and functions are defined:
3890select access point()
3891This opens popup selection where access points are listed and can be selected. Returns selected
3892access point id.
3893access point(apid)
3894This creates access point object by given apid. Returns access point object.
3895set default access point(apo)
3896This sets the default access point that is used when socket is opened. Setting apo to "None" will
3897clear default access point.
3898access points()
3899This lists access points id’s and names that are available.
3900Example 1:
3901#access point is selected from the list
3902apid = select_access_point()
3903apo = access_point(apid)
3904set_default_access_point(apo)
3905s = socket(AF_INET, SOCK_STREAM)
3906print apo.ip()
3907s.connect((’www.sourceforge.net’,80))
3908s.send(’GET /\r\n\r\n’)
3909s.recv(100)
3910s.close()
3911apo.stop()
3912Example 2:
3913#Access point id is already known
3914apo = access_point(1)
3915set_default_access_point(apo)
3916s = socket(AF_INET, SOCK_STREAM)
3917s.connect((’www.sourceforge.net’,80))
3918s.send(’GET /\r\n\r\n’)
3919s.recv(100)
3920s.close()
3921apo.stop()
3922Example 3:
3923#display interface ip.
3924#access point is selected from the list
3925apid = select_access_point()
3926apo = access_point(apid)
3927apo.start()
3928#Note that ip-address is given by operator, if static ip-address is not defined,
3929#when connection is started
3930print apo.ip()
3931#When connection is closed dynamic ip-address is released
3932apo.stop()
393382
3934Chapter 8. Standard Library Support and Extensions
3935Page 89
3936CHAPTER
3937NINE
3938Extending and Embedding
39399.1 Python/C API Extensions
3940The native API exported by the interpreter in S60 environment consists of class CSPyInterpreter,
3941Python/C API (see [3]) and and a small set of extensions to Python/C API.
39429.1.1 class CSPyInterpreter
3943The class CSPyInterpreter offers an interface for initializing the interpreter and for running scripts. It
3944exports the following public interface:
3945static CSPyInterpreter*
3946NewInterpreterL(TBool aCloseStdlib = ETrue,
3947void(*aStdioInitFunc)(void*) = NULL,
3948void* aStdioInitCookie = NULL);
3949TInt RunScript(int argc, char** argv);
3950void PrintError();
3951void (*iStdI)(char* buf, int n);
3952void (*iStdO)(const char* buf, int n);
3953The caller of the constructor CSPyInterpreter::NewInterpreterL() may provide its own function
3954aStdioInitFunc for initializing Symbian OS STDLIB’s standard I/O descriptors. It gets called with the
3955argument aStdioInitCookie. The CSPyInterpreter class can also be requested to leave STDLIB open
3956at its destruction.
3957The RunScript method establishes a Python interpreter context and runs the script file whose full path
3958name is in argv[0] with the given argument vector. After completion, it leaves the interpreter context
3959and returns a Symbian error code to indicate success or failure.
3960The CSPyInterpreter::PrintError method can be used to print current Python exception information
3961to the standard error output.
39629.1.2 Extensions to Python/C API
3963Defined in symbian python ext util.h
3964PyObject* SPyErr SetFromSymbianOSErr(int error)
3965Sets Python exception of type PyExc SymbianError with the value field set to symbolic name of
3966the Symbian OS enumeration value error and returns NULL. In case error has the special value
3967KErrPython, it assumes that a Python exception has already been set and returns NULL.
3968The following functions can be used for storing the global data in a module implementa-
3969tion. They are thin wrappers around PyDict SetItem, PyDict SetItemString, PyDict GetItem,
3970PyDict GetItemString, PyDict DelItem and PyDict DelItemString, respectively, and can be used
3971in the same way. The data is stored in a special completely global dictionary shared by all modules and
3972threads in the current interpreter.
397383
3974Page 90
3975int SPyAddGlobal(PyObject *key, PyObject *value)
3976int SPyAddGlobalString(char *key, PyObject *value)
3977PyObject* SPyGetGlobal(PyObject *key)
3978PyObject* SPyGetGlobalString(char *key)
3979void SPyRemoveGlobal(PyObject *key)
3980void SPyRemoveGlobalString(char *key)
3981Defined in python globals.h
3982PyThreadState* PYTHON TLS->thread state
3983Current thread state.
3984Thread state and interpreter lock management must be performed according to the instructions; see
3985[3]. Python for S60 Platform extends the Python/C API by offering a facility for querying the related
3986Python thread state (PYTHON TLS->thread state) from the context of the currently running thread.
3987This can be used to re-establish the interpreter context with PyEval RestoreThread in C/C++ code.
3988To save/restore the interpreter context:
3989Py_BEGIN_ALLOW_THREADS
3990/* ...your code... */
3991Py_END_ALLOW_THREADS
3992To restore/save the interpreter context:
3993PyEval_RestoreThread(PYTHON_TLS-$>$thread_state)
3994/* ...your code... */
3995PyEval_SaveThread()
3996Defined in pythread.h
3997int PyThread AtExit(void(*)())
3998An extenstion to the standard thread module’s C API that can be used for registering thread-
3999specific exit functions. In the main thread calling this function has the same effect as calling
4000Py AtExit. For more information, see [1].
40019.2 Extending Python for S60
4002The general rules and guidelines for writing Python extensions apply in the S60 Python environment as
4003well; for more information, see [2]. The Python/C API is available, see [3] In addition, for an example
4004on porting a simple extension to S60, see [6].
4005The issues that need to be considered in the implementation of the extension modules include:
4006• Preparation of the data structures that make the C/C++ coded extensions visible to the Python
4007interpreter and make it possible to perform calls from Python to C/C++ code
4008• Conversions between C/C++ representations of the Python objects and object types used in the
4009extension code
4010• Maintenance of the reference counts of the C/C++ representations of the Python objects
4011• Passing of exceptions between C/C++ code and Python
4012• Management of interpreter’s thread state and the interpreter lock
401384
4014Chapter 9. Extending and Embedding
4015Page 91
4016In addition to the concerns common for all Python C extensions, the following principles should be
4017considered when implementing new Python interfaces in the S60 environment:
4018• Maximize the usage of Python’s built-in types at the interfaces.
4019• Related to the above: design interfaces in such a way that information can be passed between them
4020with minimal conversions.
4021• Convert Symbian operating system exceptions / errors to Python exceptions.
4022• Unicode strings are used at the interfaces to represent text that gets shown on the GUI. They can
4023be passed to and from Symbian operating system without conversions.
4024• While performing potentially long-lasting / blocking calls from an extension implementation to
4025services outside the interpreter, the interpreter lock must be released and then re-acquired after
4026the call.
4027• Rather than always implementing a thin wrapper on top of a Symbian OS facility, consider the
4028actual task for which the script writer needs the particular interface. For example, if the task
4029involves interaction with the users using the GUI, the script writer’s interest may well be limited
4030to performing the interaction / information exchange in a way that is compatible with the UI style
4031rather than having full control of the low-level details of the GUI implementation.
4032• The C/C++ implementation of a Python interface should be optimized for performance and cov-
4033ering access to the necessary features of the underlying Platform. Where necessary, the Python
4034programming interface can be further refined by wrapper modules written in Python.
4035An extension module is packaged in its own dynamically loadable library that must be installed into
4036‘\system\libs’ directory and named ‘module name.pyd’. The module initialization function must be ex-
4037ported at ordinal 1. The module identification is based on the filename only. As a special feature of
4038PyS60, an optional module finalizer function may be exported at ordinal 2.
4039The macro versions of memory-management functions PyMem MALLOC and PyObject NEW are not in-
4040cluded. Use the functions PyMem Malloc and PyObject New instead.
40419.2.1 Services for Extensions
4042S60 Python Platform implements an adaptation layer between S60 UI application framework and script
4043language UI extensions to simplify UI extension development. This API is used by the implementation of
4044the appuifw module but not exported in the current release. Some general utility services for extensions
4045are also provided, see Chapter 9.1.
40469.2.2 Example
4047This extension code snippet demonstrates some of the issues mentioned in this chapter, such as:
4048• Conversion from Python data types, usage of built-in data types at extension interface, usage of
4049Unicode strings (lines 8-12)
4050• Maintenance of the reference counts (line 36)
4051• Passing of exceptions between C/C++ code and Python (line 34)
4052• Releasing the interpreter lock while performing a blocking call to a service outside the interpreter
4053(lines 29, 31)
4054• Simplifying the API to the note facility of the Platform
40559.2. Extending Python for S60
405685
4057Page 92
405801 extern "C" PyObject *
405902 note(PyObject* /*self*/, PyObject *args)
406003 {
406104
4062TInt error = KErrNone;
406305
4064int l_tx, l_ty;
406506
4066char *b_tx, *b_ty;
406707
406808
4069if (!PyArg_ParseTuple(args, "u#s#", &b_tx, &l_tx, &b_ty, &l_ty))
407009
4071return NULL;
407210
407311
4074TPtrC8 stype((TUint8*)b_ty, l_ty);
407512
4076TPtrC note_text((TUint16 *)b_tx, l_tx);
407713
4078CAknResourceNoteDialog* dlg = NULL;
407914
408015
4081if (stype.Compare(KErrorNoteType) == 0)
408216
4083dlg = new CAknErrorNote(ETrue);
408417
4085else if (stype.Compare(KInfoNoteType) == 0)
408618
4087dlg = new CAknInformationNote(ETrue);
408819
4089else if (stype.Compare(KConfNoteType) == 0)
409020
4091dlg = new CAknConfirmationNote(ETrue);
409221
4093else {
409422
4095PyErr_BadArgument();
409623
4097return NULL;
409824
4099}
410025
410126
4102if (dlg == NULL)
410327
4104return PyErr_NoMemory();
410528
410629
4107Py_BEGIN_ALLOW_THREADS
410830
4109TRAP(error, dlg->ExecuteLD(note_text));
411031
4111Py_END_ALLOW_THREADS
411232
411333
4114if (error != KErrNone)
411534
4116return SPyErr_SetFromSymbianOSErr(error);
411735
4118else {
411936
4120Py_INCREF(Py_None);
412137
4122return Py_None;
412338
4124}
412539 }
412686
4127Chapter 9. Extending and Embedding
4128Page 93
4129CHAPTER
4130TEN
4131Terms and Abbreviations
4132The following list defines the terms and abbreviations used in this document:
4133Term
4134Definition
4135AAC; Adaptive
4136Audio Coding
4137AAC provides basically the same sound quality as MP3 while using a
4138smaller bit rate. AAC is mainly used to compress music.
4139Advertise
4140Advertise service in Bluetooth makes it known that a certain Bluetooth
4141service is available.
4142AMR
4143Adaptive Multi-rate Codec file format.
4144API
4145Application Programming Interface
4146Bluetooth
4147Bluetooth is a technology for wireless communication between devices that
4148is based on a low-cost short-range radio link.
4149BPP
4150Bits Per Pixel
4151C STDLIB
4152Symbian OS’s implementation of the C standard library
4153Dialog
4154A temporary user interface window for presenting context-specific informa-
4155tion to the user, or prompting for information in a specific context.
4156Discovery
4157Discovery is a process where Bluetooth finds other nearby Bluetooth devices
4158and their advertised services.
4159DLL
4160Dynamic link library
4161GSM;
4162Global
4163System
4164for
4165Mobile commu-
4166nication
4167GSM is a digital mobile telephone system that uses a variation of time
4168division multiple access. It digitizes and compresses data, then sends it
4169down a channel with two other streams of user data, each in its own time
4170slot.
4171GUI
4172Graphical User Interface
4173I/O
4174input/output
4175IP
4176Internet Protocol
4177MBM;
4178Multi-
4179BitMap
4180The native Symbian OS format used for pictures. MBM files can be gener-
4181ated with the bmconv.exe tool included in the S60 SDK.
4182MIDI;
4183Musi-
4184cal Instrument
4185Digital Interface
4186A protocol and a set of commands for storing and transmitting information
4187about music.
4188MIF;
4189Multi-
4190Image File
4191MIF files are similar to MBM files and can contain compressed SVG-T files.
4192This file type can be generated with the MifConv.exe tool.
4193MIME; Multi-
4194purpose Internet
4195Mail Extensions
4196MIME is an extension of the original Internet e-mail protocol that can be
4197used to exchange different kinds of data files on the Internet.
4198MP3
4199A standard technology and format for compressing a sound sequence into
4200a very small file while preserving the original level of sound quality when
4201it is played.
4202OS
4203Operating System
4204Real Audio
4205An audio format developed by Real Networks.
4206RDBMS
4207Relational database management system
4208SMS;
4209Short
4210Message System
4211(within GSM)
4212SMS is a service for sending messages of up to 160 characters, or 224 charac-
4213ters if using a 5-bit mode, to mobile phones that use GSM communication.
421487
4215Page 94
4216Term
4217Definition
4218Softkey
4219Softkey is a key that does not have a fixed function nor a function label
4220printed on it. On a phone, selection keys reside below or above on the
4221side of the screen, and derive their meaning from what is presently on the
4222screen.
4223SQL
4224Structured Query Language
4225SVG,
4226SVG-T;
4227Scalable
4228Vec-
4229tor
4230Graphics
4231(-Tiny)
4232XML-based vector graphics format for describing two-dimensional graphics
4233and graphical applications.
4234Twip
4235Twips are screen-independent units to ensure that the proportion of screen
4236elements are the same on all display systems. A twip is defined as 1/1440
4237of an inch, or 1/567 of a centimeter.
4238UI
4239User Interface
4240UI control
4241UI control is a GUI component that enables user interaction and represents
4242properties or operations of an object.
4243WAV
4244A file format for recording sound, especially in multimedia applications.
424588
4246Chapter 10. Terms and Abbreviations
4247Page 95
4248BIBLIOGRAPHY
4249[1] G. van Rossum, and F.L. Drake, Jr., editor. [Python] Library Reference. Available at
4250http://www.python.org/doc
4251[2] G. van Rossum, and F.L. Drake, Jr., editor. Extending and Embedding [the Python Interpreter].
4252Available at http://www.python.org/doc
4253[3] G. van Rossum, and F.L. Drake, Jr., editor. Python/C API [Reference Manual]. Available at
4254http://www.python.org/doc
4255[4] S60 SDK documentation, available at http://www.forum.nokia.com/
4256[5] Getting Started with Python for S60 Platform, available at http://www.forum.nokia.com/
4257[6] Programming with Python for S60 Platform, available at http://www.forum.nokia.com/
4258[7] Audio &
4259Video section
4260on
4261the
4262Forum
4263Nokia
4264Web
4265site (for Nokia devices),
4266http://www.forum.nokia.com/audiovideo
4267[8] Developers section on the S60 Platform Web site (for all S60 devices), http://www.s60.com/
4268[9] Python for S60 developer discussion board http://discussion.forum.nokia.com/
4269[10] Scalable Vector Graphics (SVG) 1.1 Specification http://www.w3.org/TR/SVG/
427089
4271Page 96
427290
4273Page 97
4274APPENDIX
4275A
4276Reporting Bugs
4277In order to improve the quality of Python for S60 the developers would like to know of any deficiencies
4278you find in Python for S60 or its documentation.
4279Before submitting a report, you will be required to log into SourceForge; this will make it possible for
4280the developers to contact you for additional information if needed. It is not possible to submit a bug
4281report anonymously.
4282All bug reports should be submitted via the project PyS60 Bug Tracker on SourceForge
4283(http://sourceforge.net/tracker/?group id=154155). The bug tracker offers a Web form which allows per-
4284tinent information to be entered and submitted to the developers.
4285The first step in filing a report is to determine whether the problem has already been reported. The
4286advantage in doing so, aside from saving the developers time, is that you learn what has been done to
4287fix it; it may be that the problem has already been fixed for the next release, or additional information
4288is needed (in which case you are welcome to provide it if you can!). To do this, search the bug database
4289using the search box near the bottom of the page.
4290If the problem you’re reporting is not already in the bug tracker, go back to the project PyS60 Bug
4291Tracker (http://sourceforge.net/tracker/?group id=154155). Select the “Submit a Bug” link at the top of
4292the page to open the bug reporting form.
4293The submission form has a number of fields. The only fields that are required are the “Summary” and
4294“Details” fields. For the summary, enter a very short description of the problem; less than ten words is
4295good. In the Details field, describe the problem in detail, including what you expected to happen and
4296what did happen. Be sure to include the version of Python for S60 you used, whether any extension
4297modules were involved and what hardware (the S60 device model or emulator) you were using, including
4298version information of the S60 SDK and your device firmware version as appropriate. You can see the
4299device firmware version by entering *#0000# on the device keypad - please include all information that
4300is shown by this code.
4301The only other field that you may want to set is the “Category” field, which allows you to place the bug
4302report into a broad category (such as “Documentation” or “Library”).
4303Each bug report will be assigned to a developer who will determine what needs to be done to correct the
4304problem. You will receive an update each time action is taken on the bug.
4305See Also:
4306How to Report Bugs Effectively
4307(http://www-mice.cs.ucl.ac.uk/multimedia/software/documentation/ReportingBugs.html)
4308Article which goes into some detail about how to create a useful bug report. This describes what
4309kind of information is useful and why it is useful.
4310Bug Writing Guidelines
4311(http://www.mozilla.org/quality/bug-writing-guidelines.html)
4312Information about writing a good bug report. Some of this is specific to the Mozilla project, but
4313describes general good practices.
431491
4315Page 98
431692
4317Page 99
4318MODULE INDEX
4319appuifw, 13
4320audio, 49
4321calendar, 64, 69
4322camera, 33
4323contacts, 59
4324e32, 9
4325e32db, 74
4326e32dbm, 77
4327glcanvas, 45
4328gles, 38
4329graphics, 27
4330inbox, 53
4331keycapture, 36
4332location, 54
4333messaging, 52
4334positioning, 55
4335sensor, 46
4336socket, 81
4337sysinfo, 11
4338telephone, 51
4339thread, 81
4340topwindow, 37
434193
4342Page 100
434394
4344Page 101
4345INDEX
4346del
4347() (EventFilter method), 48
4348delitem
4349() (CalendarDb method), 65, 71
4350delitem
4351() (ContactDb method), 60
4352delitem
4353() (Contact method), 62
4354getitem
4355() (CalendarDb method), 65, 71
4356getitem
4357() (array method), 39
4358init
4359() (EventFilter method), 48
4360init
4361() (OrientationEventFilter method), 48
4362init
4363() (Sensor method), 47
4364len
4365() (array method), 39
4366setitem
4367() (array method), 39
4368access point() (in module socket), 82
4369access points() (in module socket), 82
4370activate tab() (Application method), 18
4371active profile() (in module sysinfo), 11
4372add() (Text method), 22
4373add anniversary() (CalendarDb method), 65, 70
4374add appointment() (CalendarDb method), 65, 70
4375add contact() (ContactDb method), 59
4376add event() (CalendarDb method), 65, 70
4377add field() (Contact method), 61
4378add group() (Groups method), 63
4379add image() (TopWindow method), 37
4380add reminder() (CalendarDb method), 70
4381add todo() (CalendarDb method), 65, 70
4382add todo list() (CalendarDb method), 65
4383address() (Inbox method), 53
4384AF BT (data in socket), 81
4385after() (Ao timer method), 11
4386alarm (Entry attribute), 67, 72
4387all keys (data in keycapture), 36
4388AnniversaryEntry (class in calendar), 67, 72
4389answer() (in module telephone), 51
4390ao callgate() (in module e32), 9
4391Ao lock (class in e32), 10
4392ao sleep() (in module e32), 9
4393Ao timer (class in e32), 11
4394ao waittid() (in module thread), 81
4395ao yield() (in module e32), 9
4396Application (class in appuifw), 16
4397AppointmentEntry (class in calendar), 67, 72
4398appuifw (standard module), 13
4399arc() ( method), 33
4400array (class in gles), 39
4401as vcalendar() (Entry method), 67, 72
4402as vcard() (Contact method), 61
4403audio (extension module), 49
4404AUTH (data in socket), 81
4405AUTHOR (data in socket), 81
4406available fonts() (in module appuifw), 15
4407background color (TopWindow attribute), 38
4408battery() (in module sysinfo), 11
4409begin()
4410Contact method, 60
4411Dbms method, 75
4412bind()
4413GLCanvas method, 46
4414Inbox method, 54
4415Listbox method, 24
4416Text method, 22
4417blit() ( method), 33
4418body (Application attribute), 16
4419bt advertise service() (in module socket), 81
4420bt discover() (in module socket), 81
4421bt obex discover() (in module socket), 81
4422bt obex receive() (in module socket), 81
4423bt obex send file() (in module socket), 81
4424bt rfcomm get available server channel()
4425(in module socket), 81
4426BTPROTO RFCOMM (data in socket), 81
4427calendar (extension module), 64, 69
4428CalendarDb (class in calendar), 65, 70
4429call state() (in module telephone), 51
4430callback (EventFilter attribute), 48
4431camera (extension module), 33
4432cameras available() (in module camera), 34
4433cancel() (Ao timer method), 11
4434Canvas (class in appuifw), 25
4435cleanup()
4436EventFilter method, 48
4437OrientationEventFilter method, 48
4438clear()
4439method, 33
4440Text method, 22
4441close()
4442Dbms method, 75
4443e32dbm method, 78
4444Sound method, 50
4445col() (Db view method), 75
444695
4447Page 102
4448col count() (Db view method), 75
4449col length() (Db view method), 75
4450col raw() (Db view method), 75
4451col rawtime() (Db view method), 75
4452col type() (Db view method), 75
4453color (Text attribute), 21
4454commit()
4455Contact method, 60
4456Dbms method, 75
4457Entry method, 66, 71
4458compact()
4459CalendarDb method, 66
4460ContactDb method, 60
4461Dbms method, 75
4462compact required() (ContactDb method), 60
4463connect() (Sensor method), 47
4464connected() (Sensor method), 48
4465Contact (class in contacts), 60
4466ContactDb (class in contacts), 59
4467ContactField (class in contacts), 63
4468contacts (extension module), 59
4469content() (Inbox method), 53
4470content (Entry attribute), 66, 71
4471Content handler (class in appuifw), 24
4472corner type (TopWindow attribute), 38
4473count line() (Db view method), 76
4474create() (Dbms method), 75
4475cross out time (TodoEntry attribute), 67, 73
4476crossed out (Entry attribute), 67, 72
4477current() (Listbox method), 24
4478current position() (Sound method), 51
4479current volume() (Sound method), 50
4480daily instances() (CalendarDb method), 65, 71
4481Db view (class in e32db), 75
4482Dbms (class in e32db), 75
4483default list (TodoListDict attribute), 68
4484default module() (in module positioning), 55
4485delete()
4486Inbox method, 54
4487Text method, 22
4488dial() (in module telephone), 51
4489disconnect() (Sensor method), 47
4490display pixels() (in module sysinfo), 11
4491display twips() (in module sysinfo), 11
4492drawNow() (GLCanvas method), 46
4493drive list() (in module e32), 9
4494duration() (Sound method), 50
4495e32 (extension module), 9
4496e32db (extension module), 74
4497e32dbm (module), 77
4498EAColumn (data in appuifw), 19
4499EApplicationWindow (data in appuifw), 18
4500EBatteryPane (data in appuifw), 19
4501EBColumn (data in appuifw), 19
4502ECColumn (data in appuifw), 19
4503EContextPane (data in appuifw), 18
4504EControlPane (data in appuifw), 18
4505EControlPaneBottom (data in appuifw), 19
4506EControlPaneTop (data in appuifw), 19
4507ECreated (data in messaging), 52
4508EDColumn (data in appuifw), 19
4509EDeleted (data in messaging), 52
4510EDraft (data in inbox), 53
4511EFatalServerError (data in messaging), 52
4512EFindPane (data in appuifw), 19
4513EHCenterVBottom (data in appuifw), 27
4514EHCenterVCenter (data in appuifw), 27
4515EHCenterVTop (data in appuifw), 27
4516EHLeftVBottom (data in appuifw), 27
4517EHLeftVCenter (data in appuifw), 27
4518EHLeftVTop (data in appuifw), 27
4519EHRightVBottom (data in appuifw), 27
4520EHRightVCenter (data in appuifw), 27
4521EHRightVTop (data in appuifw), 27
4522EInbox (data in inbox), 53
4523EIndicatorPane (data in appuifw), 19
4524ellipse() ( method), 32
4525EMainPane (data in appuifw), 18
4526EMovedToOutBox (data in messaging), 52
4527ENaviPane (data in appuifw), 19
4528ENCRYPT (data in socket), 81
4529end time (Entry attribute), 66, 72
4530ENoServiceCentre (data in messaging), 52
4531ENotReady (data in audio), 49
4532Entry (class in calendar), 66, 71
4533EOpen (data in audio), 49
4534EOpenComplete (data in camera), 34
4535EOutbox (data in inbox), 53
4536EPlaying (data in audio), 49
4537EPrepareComplete (data in camera), 34
4538ERecordComplete (data in camera), 34
4539ERecording (data in audio), 49
4540EScheduledForSend (data in messaging), 52
4541EScheduleFailed (data in messaging), 52
4542EScreen (data in appuifw), 18
4543ESendFailed (data in messaging), 52
4544ESent
4545data in inbox, 53
4546data in messaging, 52
4547ESignalPane (data in appuifw), 18
4548EStaconBottom (data in appuifw), 19
4549EStaconTop (data in appuifw), 19
4550EStatusAnswering (data in telephone), 51
4551EStatusConnected (data in telephone), 51
4552EStatusConnecting (data in telephone), 51
4553EStatusDialling (data in telephone), 51
4554EStatusDisconnecting (data in telephone), 52
4555EStatusHold (data in telephone), 52
4556EStatusIdle (data in telephone), 51
4557EStatusPane (data in appuifw), 18
4558EStatusPaneBottom (data in appuifw), 19
4559EStatusPaneTop (data in appuifw), 19
4560EStatusReconnectPending (data in telephone), 51
4561EStatusRinging (data in telephone), 51
4562EStatusTransferAlerting (data in telephone), 52
456396
4564Index
4565Page 103
4566EStatusTransferring (data in telephone), 52
4567EStatusUnknown (data in telephone), 51
4568ETitlePane (data in appuifw), 18
4569EUniversalIndicatorPane (data in appuifw), 19
4570event()
4571EventFilter method, 48
4572OrientationEventFilter method, 48
4573EventEntry (class in calendar), 67, 72
4574EventFilter (class in sensor), 48
4575EWallpaperPane (data in appuifw), 19
4576execute()
4577Dbms method, 75
4578Form method, 20
4579exit key handler (Application attribute), 17
4580export vcalendars() (CalendarDb method), 65,
458171
4582export vcards() (ContactDb method), 60
4583exposure modes() (in module camera), 34
4584FFormAutoFormEdit (data in appuifw), 20
4585FFormAutoLabelEdit (data in appuifw), 20
4586FFormDoubleSpaced (data in appuifw), 20
4587FFormEditModeOnly (data in appuifw), 20
4588FFormViewModeOnly (data in appuifw), 20
4589field types() (ContactDb method), 60
4590file copy() (in module e32), 9
4591find()
4592Contact method, 62
4593ContactDb method, 60
4594find instances() (CalendarDb method), 65, 70
4595first line() (Db view method), 76
4596flags (Form attribute), 20
4597flash modes() (in module camera), 34
4598focus
4599Application attribute, 17
4600Text attribute, 21
4601font (Text attribute), 21
4602Form (class in appuifw), 19
4603format rawtime() (in module e32db), 74
4604format time() (in module e32db), 74
4605forwarding (KeyCapturer attribute), 37
4606free drivespace() (in module sysinfo), 11
4607free ram() (in module sysinfo), 12
4608full name() (Application method), 18
4609get() (Text method), 23
4610get line() (Db view method), 76
4611get pos() (Text method), 22
4612get repeat() (Entry method), 66, 71
4613glBufferData() (in module gles), 43
4614glBufferDatab() (in module gles), 43
4615glBufferDataf() (in module gles), 43
4616glBufferDatas() (in module gles), 43
4617glBufferDataub() (in module gles), 43
4618glBufferDataus() (in module gles), 43
4619glBufferDatax() (in module gles), 43
4620glBufferSubData() (in module gles), 43
4621glBufferSubDatab() (in module gles), 43
4622glBufferSubDataf() (in module gles), 43
4623glBufferSubDatas() (in module gles), 43
4624glBufferSubDataub() (in module gles), 43
4625glBufferSubDataus() (in module gles), 43
4626glBufferSubDatax() (in module gles), 43
4627GLCanvas (class in glcanvas), 46
4628glcanvas (extension module), 45
4629glClipPlanef() (in module gles), 43
4630glClipPlanex() (in module gles), 43
4631glColorPointer() (in module gles), 40
4632glColorPointerf() (in module gles), 40
4633glColorPointerub() (in module gles), 40
4634glColorPointerx() (in module gles), 40
4635glCompressedTexImage2D() (in module gles), 40
4636glCompressedTexSubImage2D() (in module gles),
463740
4638glDeleteBuffers() (in module gles), 44
4639glDeleteTextures() (in module gles), 40
4640glDrawElements() (in module gles), 40
4641glDrawElementsub() (in module gles), 40
4642glDrawElementsus() (in module gles), 40
4643glDrawTexfvOES() (in module gles), 44
4644glDrawTexivOES() (in module gles), 44
4645glDrawTexsvOES() (in module gles), 44
4646gles (extension module), 38
4647glFogv() (in module gles), 40
4648glFogxv() (in module gles), 40
4649glGenBuffers() (in module gles), 44
4650glGenTextures() (in module gles), 40
4651glGetBooleanv() (in module gles), 44
4652glGetBufferParameteriv() (in module gles), 44
4653glGetClipPlanef() (in module gles), 44
4654glGetFixedv() (in module gles), 44
4655glGetFloatv() (in module gles), 44
4656glGetIntegerv() (in module gles), 40
4657glGetLightfv() (in module gles), 44
4658glGetLightxv() (in module gles), 44
4659glGetMaterialfv() (in module gles), 44
4660glGetMaterialxv() (in module gles), 44
4661glGetString() (in module gles), 40
4662glGetTexEnvf() (in module gles), 44
4663glGetTexEnvx() (in module gles), 44
4664glGetTexParameterf() (in module gles), 44
4665glGetTexParameterx() (in module gles), 44
4666glLightfv() (in module gles), 41
4667glLightModelfv() (in module gles), 40
4668glLightModelxv() (in module gles), 40
4669glLightxv() (in module gles), 41
4670glLoadMatrixf() (in module gles), 41
4671glLoadMatrixx() (in module gles), 41
4672glMaterialfv() (in module gles), 41
4673glMaterialxv() (in module gles), 41
4674glMatrixIndexPointerOES() (in module gles), 44
4675glMatrixIndexPointerOESub() (in module gles),
467644
4677glMultMatrixf() (in module gles), 41
4678glMultMatrixx() (in module gles), 41
4679glNormalPointer() (in module gles), 41
4680glNormalPointerb() (in module gles), 41
4681Index
468297
4683Page 104
4684glNormalPointerf() (in module gles), 41
4685glNormalPointers() (in module gles), 41
4686glNormalPointerx() (in module gles), 41
4687glPointParameterfv() (in module gles), 45
4688glPointParameterxv() (in module gles), 45
4689glPointSizePointerOES() (in module gles), 45
4690glPointSizePointerOESf() (in module gles), 45
4691glPointSizePointerOESx() (in module gles), 45
4692glReadPixels() (in module gles), 41
4693glTexCoordPointer() (in module gles), 41
4694glTexCoordPointerb() (in module gles), 41
4695glTexCoordPointerf() (in module gles), 42
4696glTexCoordPointers() (in module gles), 41
4697glTexCoordPointerx() (in module gles), 42
4698glTexEnvfv() (in module gles), 42
4699glTexEnvxv() (in module gles), 42
4700glTexImage2D() (in module gles), 42
4701glTexSubImage2D() (in module gles), 42
4702glVertexPointer() (in module gles), 42
4703glVertexPointerb() (in module gles), 42
4704glVertexPointerf() (in module gles), 42
4705glVertexPointers() (in module gles), 42
4706glVertexPointerx() (in module gles), 42
4707glWeightPointerOES() (in module gles), 45
4708glWeightPointerOESf() (in module gles), 45
4709glWeightPointerOESx() (in module gles), 45
4710graphics (extension module), 27
4711Group (class in contacts), 63
4712Groups (class in contacts), 63
4713groups (ContactDb attribute), 60
4714gsm location() (in module location), 54
4715hang up() (in module telephone), 51
4716hide()
4717InfoPopup method, 27
4718TopWindow method, 37
4719highlight color (Text attribute), 21
4720HIGHLIGHT ROUNDED (data in appuifw), 22
4721HIGHLIGHT SHADOW (data in appuifw), 22
4722HIGHLIGHT STANDARD (data in appuifw), 22
4723Icon (class in appuifw), 24
4724id
4725Contact attribute, 60
4726Entry attribute, 66, 72
4727Group attribute, 63
4728TodoList attribute, 68
4729Image.inspect() (in module graphics), 28
4730Image.new() (in module graphics), 28
4731Image.open() (in module graphics), 28
4732image modes() (in module camera), 34
4733image sizes() (in module camera), 34
4734images (TopWindow attribute), 38
4735imei() (in module sysinfo), 11
4736import vcalendars() (CalendarDb method), 65,
473771
4738import vcards() (ContactDb method), 60
4739in emulator() (in module e32), 9
4740inactivity() (in module e32), 10
4741Inbox (class in inbox), 53
4742inbox (extension module), 53
4743incoming call() (in module telephone), 51
4744InfoPopup (class in appuifw), 27
4745insert() (Form method), 20
4746is col null() (Db view method), 76
4747is group (Contact attribute), 60
4748is ui thread() (in module e32), 10
4749keycapture (extension module), 36
4750keys() (ContactDb method), 60
4751keys (KeyCapturer attribute), 36
4752KMdaRepeatForever (data in audio), 49
4753label (ContactField attribute), 63
4754last key() (KeyCapturer method), 37
4755last modified (Entry attribute), 66, 72
4756layout() (Application method), 18
4757len() (Text method), 22
4758length() (Form method), 20
4759line() ( method), 32
4760Listbox (class in appuifw), 23
4761load() (Image method), 29
4762location
4763ContactField attribute, 63
4764Entry attribute, 66, 71
4765extension module, 54
4766makeCurrent() (GLCanvas method), 46
4767max ramdrive size() (in module sysinfo), 12
4768max volume() (Sound method), 50
4769max zoom() (in module camera), 34
4770maximum size (TopWindow attribute), 38
4771measure text() ( method), 33
4772menu
4773Application attribute, 17
4774Form attribute, 20
4775messaging (extension module), 52
4776mms send() (in module messaging), 52
4777module info() (in module positioning), 55
4778modules() (in module positioning), 55
4779monthly instances() (CalendarDb method), 65,
478070
4781multi query() (in module appuifw), 16
4782multi selection list() (in module appuifw),
478316
4784name
4785Group attribute, 63
4786TodoList attribute, 68
4787next line() (Db view method), 76
4788note() (in module appuifw), 16
4789OBEX (data in socket), 81
4790open()
4791Content handler method, 24
4792Dbms method, 75
4793in module calendar, 64, 70
4794in module contacts, 59
479598
4796Index
4797Page 105
4798in module e32dbm, 77
4799open standalone() (Content handler method),
480025
4801orientation (Application attribute), 18
4802orientation.BACK ( attribute), 47
4803orientation.BOTTOM ( attribute), 47
4804orientation.FRONT ( attribute), 47
4805orientation.LEFT ( attribute), 47
4806orientation.RIGHT ( attribute), 47
4807orientation.TOP ( attribute), 47
4808OrientationEventFilter (class in sensor), 48
4809originating (Entry attribute), 72
4810os version() (in module sysinfo), 12
4811pieslice() ( method), 32
4812play() (Sound method), 49
4813point() ( method), 33
4814polygon() ( method), 32
4815pop() (Form method), 20
4816popup menu() (in module appuifw), 16
4817position() (in module positioning), 55
4818position
4819Listbox attribute, 24
4820TopWindow attribute, 38
4821POSITION INTERVAL (data in positioning), 55
4822positioning (extension module), 55
4823prepare() (Db view method), 76
4824priority (Entry attribute), 67, 72
4825pys60 version (data in e32), 9
4826pys60 version info (data in e32), 9
4827PYTHON TLS->thread state, 84
4828PyThread AtExit(), 84
4829query() (in module appuifw), 15
4830record() (Sound method), 50
4831rectangle() ( method), 32
4832release() (in module camera), 36
4833ReminderEntry (class in calendar), 73
4834remove image() (TopWindow method), 37
4835reorganize() (e32dbm method), 78
4836replication (Entry attribute), 67, 72
4837reset inactivity() (in module e32), 10
4838resize() (Image method), 28
4839RFCOMM (data in socket), 81
4840ring type() (in module sysinfo), 12
4841rollback()
4842Contact method, 61
4843Dbms method, 75
4844Entry method, 66, 71
4845RotEventFilter (class in sensor), 48
4846s60 version info (data in e32), 10
4847save() (Image method), 29
4848save hook (Form attribute), 20
4849say() (in module audio), 49
4850schema (ContactField attribute), 63
4851screen (Application attribute), 17
4852screenshot() (in module graphics), 28
4853select access point() (in module socket), 82
4854select module() (in module positioning), 55
4855selection list() (in module appuifw), 16
4856Sensor (class in sensor), 47
4857sensor (extension module), 46
4858sensors() (in module sensor), 46
4859set() (Text method), 23
4860set default access point()
4861(in
4862module
4863socket), 82
4864set event filter() (Sensor method), 48
4865set exit() (Application method), 18
4866set home time() (in module e32), 9
4867set list() (Listbox method), 24
4868set pos() (Text method), 23
4869set position() (Sound method), 50
4870set repeat() (Entry method), 66, 71
4871set requestors() (in module positioning), 55
4872set security() (in module socket), 81
4873set tabs() (Application method), 18
4874set time() (Entry method), 66, 71
4875set volume() (Sound method), 50
4876shadow (TopWindow attribute), 38
4877show()
4878InfoPopup method, 27
4879TopWindow method, 37
4880signal() (Ao lock method), 11
4881signal bars() (in module sysinfo), 12
4882signal dbm() (in module sysinfo), 12
4883size
4884Canvas attribute, 26
4885Image attribute, 29
4886Listbox attribute, 24
4887TopWindow attribute, 38
4888sms messages() (Inbox method), 53
4889sms send() (in module messaging), 52
4890socket (extension module), 81
4891Sound (class in audio), 49
4892Sound.open() (in module audio), 49
4893SPyAddGlobal(), 84
4894SPyAddGlobalString(), 84
4895SPyErr SetFromSymbianOSErr(), 83
4896SPyGetGlobal(), 84
4897SPyGetGlobalString(), 84
4898SPyRemoveGlobal(), 84
4899SPyRemoveGlobalString(), 84
4900start() (KeyCapturer method), 37
4901start exe() (in module e32), 10
4902start finder() (in module camera), 35
4903start record() (in module camera), 36
4904start server() (in module e32), 10
4905start time (Entry attribute), 66, 72
4906state() (Sound method), 50
4907stop()
4908Image method, 29
4909KeyCapturer method, 37
4910Sound method, 50
4911stop finder() (in module camera), 36
4912stop position() (in module positioning), 55
4913Index
491499
4915Page 106
4916stop record() (in module camera), 36
4917style (Text attribute), 21
4918STYLE BOLD (data in appuifw), 22
4919STYLE ITALIC (data in appuifw), 22
4920STYLE STRIKETHROUGH (data in appuifw), 22
4921STYLE UNDERLINE (data in appuifw), 22
4922sw version() (in module sysinfo), 12
4923sync() (e32dbm method), 78
4924sysinfo (extension module), 11
4925take photo() (in module camera), 34
4926telephone (extension module), 51
4927text() ( method), 33
4928thread (extension module), 81
4929time() (Inbox method), 53
4930title
4931Application attribute, 17
4932Contact attribute, 60
4933todo list (TodoEntry attribute), 68
4934todo lists (CalendarDb attribute), 65
4935TodoEntry (class in calendar), 67, 73
4936TodoList (class in calendar), 68
4937TodoListDict (class in calendar), 68
4938TopWindow (class in topwindow), 37
4939topwindow (extension module), 37
4940total ram() (in module sysinfo), 12
4941total rom() (in module sysinfo), 12
4942transpose() (Image method), 29
4943type (ContactField attribute), 63
4944uid() (Application method), 18
4945unread() (Inbox method), 54
4946value (ContactField attribute), 63
4947visible (TopWindow attribute), 38
4948wait() (Ao lock method), 10
4949white balance modes() (in module camera), 34
4950100
4951Index