
pyEdit for S60

Copyright 2005-2007 by Lasse Huovinen

Contents
    1. ........	Introduction
    1.1 ....... Requirements
    2. ........	Usage
    2.1 ....... Document handling
    2.2 ....... File browsing
    2.3 ....... Copy/Cut'n'Paste
    2.4 ....... Search and replace
    2.5 ....... Sentences
    2.6 .......	Sentences file
    2.7 ....... Sending text message
    2.8 ....... Sending text over BlueTooth
    2.9 ....... Editor configuration
    3. ........	Release Notes
    4. ........	ToDo List
    5. ........	List of Files
    6. ........ Credits



1. Introduction

pyEdit for S60 (pyEditS60) is a powerful text editor for Symbian S60 phones written in Python. Basically the editor works as any other text editor for the mobile phones. However, it has some advanced features such as multiple documents, copy/cut'n'paste, user definable pre-written sentences, possibility to save text in ASCII or Unicode format and a proper file browser.

The Python for S60 phones must have been installed to the phone before pyEditS60 can be used. Python for S60 can be downloaded and installed from http://forum.nokia.com/python for free of charge.

1.1 Requirements

- Series 60 mobile phone
- PyS60 version 1.3.1 or later installed into the phone

2. Usage

This section shortly describes how to use pyEditS60.

The text is typed in as normally with the mobile phones. The cursor may be moved using joystick as normally. However, in order to jump to the beginning or end of the document, press joystick and then turn it up or down, respectively. In order to jump to the beginning or end of the current, press joystick and then turn it left or right, respectively. Pressing joystick for the second time resumes the regular movements.

If pyFileManagerS60 has been installed it shows in pyEditS60 Tools menu where it can be launched.

2.1 Document handling

The user may load an existing document by selecting "Favorites" or "Load" from the Options->Load/Insert menu. The list of favorite documents are assigned as described in Section 2.9. Normal file selection is describes in Section 2.2. Once the user has made her selection the she will be prompted to select appropriate text coded amongst UTF-8, UTF-16, Latin-1, Iso-8859-1, ASCII, or Binary-Hex. 

The Binary-Hex codec means that the file is read in binary format and the content of the file is shown as a colon separated list of files. Value of each byte is represented as two-digit hexadecimal number.

The user may insert an existing document to the currently active document by selecting "Insert" from the Option->Load/Insert menu and then selecting the file to be inserted.

The user may create a new blank document by selecting "New" from the Options menu. Initially the blank document is named <noname>.

If there are more than one open documents item "Switch document (X)" will appear into the Options menu. Using this the user may switch between the open documents.

The currently active document can use saved through the Options->Save(as) menu. Before writing the document to the disk file it will be encoded using currently selected codec. The currently selected codec may be checked from "Document info" in the Options menu. The codec may be changed through "Settings" in the Options menu (see Section 2.9 for further information).

Note: if certain characters cannot be saved using certain coding those characters will be replaced and the user will be notified. Currently € (Euro sign) will be replaced with 'e' and other uncodable characters with '?'. The replacement applies only to document written to the file not to the the text in the editor!

2.2 File browsing

The files and directories are selected using directory browsing functionality. This section applies to all the menus where the user is requested to select a file or directory.

The joystick is used to navigate in the directory tree in the following way:
a) joystick pressed = selection made. If the user is requested to select a file the currently highlighted file will be considered selection. If the user is requested to select a directory the current directory will be considered selection.
b) joystick up = move up in file list of the current directory.
c) joystick down = move down in file list of the current directory.
d) joystick right = open the currently highlighted directory. If the highlighted item is not a directory the event has no effect.
e) joystick left = open the parent directory of the current directory.
f) Key 2 pressed = go to the top of the listing of the current directory.
g) Key 5 pressed = go to the middle of the listing of the current directory.
h) Key 8 pressed = go to the bottom of the listing of the current directory.
i) Key 0 pressed = go to the root directory (i.e. drive listing).

2.3 Copy/Cut'n'Paste

The editor has two different ways for performing Copy/Cut'n'Paste functionality: I) the native 'Edit' key method, and II) editor internal method.

 I: Using native 'Edit' key

This is a standard feature in (Nokia) terminals and works between (almost) all applications, too. Hold down the 'Edit' key (the one that looks like a pen), and then select appropriate region moving the cursor with joystick.

Once you have selected the region, press the 'Copy' key to save the region and then delete key 'C' if you want also cut out the text. Copied text may be pasted to the editor or another application holding down the 'Edit' key and then pressing the 'Paste' key.

Note1: if you are pasting text to the editor from another application, the font, color, and size of the pasted text may not be set correctly. In order to fix this select "Redraw" from Options->Edit menu.

Note2: this method may be used to copy and paste text to the another editor dialogs such as Search.

 II: Using the editor internal Copy/Cut'n'Paste

The Copy/Cut'n'Paste works as follows. The cursor is moved to the position where the region to be copied/cut will begin and then the item "Mark region" is selected from the Options->Edit menu. The beginning of the region is marked with a spcecial highlighted character.

Then the joystick is moved (backward or forward) to the position where the region to be copied/cut will end. Either the item "Copy region" or "Cut region" is selected from the Options menu. The text within the region is copied to editor internal clipboard (internal means the text is not available to other applications), the text in the region is deleted if applicable, and the region marker is removed.

The operation may be cancelled by selecting "Quit Region" from the Options menu (also "Undo and Quit" will do the same).

In order to paste the previously selected text the cursor is moved to the appropriate position and then "Paste clipboard" is selected from the Options->Edit menu.

2.4 Search and replace

To be written...

2.5 Sentences

The user may insert pre-written words, sentences or character combinations to the current cursor position from the list of sentences available in Options->Sentences menu. The list items may be assigned dynamically by selecting <load sentences> item. The user may create her own Sentences file. The file format is described in the following section. The default Sentences file which is load once pyEditS60 starts may be configured as instructed in Section 2.9 ("Editor configuration").

2.6 Sentences file

The sentences file format is such that each line of the file represents one sentence or one item in the Sentences menu. For example, if the content of the sentences file was

Hello,
Best Regards

the Sentences menu would look as follows after loading the sentences file in question.

 Hello,
 Best Regards
 <load sentences>

Note: <load sentences> is reserved for the internal use of pyEditS60.

There are a couple of special strings that can be used in the sentences file. The first one is <tabulator>N where 'N' stands for an integer number. Once the user selects a menu item having <tabulator>N the editor inserts N spaces instead of the actual menu item text. For example, if the Sentences menu items were
 Hello,
 <tabulator>8
 <load sentences>
the editor would insert 8 spaces once the user selects the second menu item.

The second special string is similar to the first one: <tabulator>N+'text'. Once the user selects a menu item having <tabulator>N+'text' the editor inserts N spaces and the 'text' instead of the actual menu item text. For example, if the Sentences menu items were
 Hello,
 <tabulator>8
 <tabulator>4+Regards,
 <load sentences>
the editor would insert 4 spaces and 'Regards,' once the user selects the third menu item.

Important: the sentences file must be saved in UTF-16 format!

2.7 Sending text message

The current editor content may be sent as a text message or several text messages. One text message can accommodate 160 characters. If the length of the current editor content is more than 160 characters then more than one text message is needed to deliver the content to the recipient.

In order to send the editor content using text message service select "Send as text message" from the Options->Tools menu. Then type recipients phone number and send the message. If more than one text message is required you will be asked to confirm sending of several messages.

2.8 Sending text over BlueTooth

To be written...

2.9 Editor configuration

The editor has a few settings that can be configured. Select "Settings" from the Options menu, configure the editor as you like, and exit from the configuration. You will be prompted whether you want to save the setting as default settings. If not then they are valid until you exit the editor.

Note that the configurable items are grouped into different tabs. Use joystick to move between the tabs. The following configurable items are currently available:
a) Text codec: select text codec amongst 'UTF-8', 'UTF-16', 'Latin', 'ISO-8859-1', 'ASCII', or Binary-Hex. Note: if certain characters cannot be saved using certain coding those characters will be replaced. Currently € (Euro sign) will be replaced with 'e' and other uncodable characters with '?'.
b) Favorite documents: (re)assign the items of the favorite documents list
c) Misc: default sentence file selection, default work directory, screen mode (normal, large, or full) font, font size and font color.

3. Release Notes
0.19	   October 17, 2007
Missing module notification fixed. Unhandled exception in stand alone app will be caught in default.py and reported to the user before exiting. Old 'About' dialog replaced with a new one. If selected region is larger than 50 characters, then 25 first and last charactes will be shown after copy or cut is selected. Directory and document names show more nicely in the settings dialogs. If sencetences are unassigned take the default hard coded list into use. Options key not shown in configuration dialog.
0.18	   August 15, 2007
Icon (3rd ed) modified. Configuration saving fix. Notification about missing UITRICK module. SMS may be inserted from the Sent, Draft and Outbox folders, too. Document info shown in 'File Viewer'. The current font, font size, and screen mode shown in the configuration menu. Search, replace, region edit dialogues heavily changed in order to make them easier to use. Some additions to the documentation.
0.17	   August 1, 2007
Added configurable font size. Configuration management rewritten (pyS60cnfutil module taken into use). Icon for 3rd edition phones. Some bugs fixed.
0.16	   June 3, 2007
Added feature for inserting an SMS from the Inbox to the currently active text document (see 'Tools'). Th pyFileManager removed from the 'Tools' menu.
0.15	   May 5, 2007
Contacts enabled for 3rd ed phones. Added MMS sending for 3rd ed phones. Fix for empty Contact database handling. Improved exception handling for file reading. Minor editorial changes.
0.14	   April 11, 2007
Added possibility to revert the currently edited document to the document saved on the disk.
0.13	   November 30, 2006
Modifications required to support 3rd edition phones. The uikludges library was replaced with more general uitricks library. In 2nd edition phones the library is included into the .SIS package but in 3rd edition it must be installed separately. The editor works w/o the library but the right softkey label is not just set correctly.
0.12	   September 27, 2006
A fatal bug fixed. The original file was accidentally destroyed when the active document was sent over BlueTooth.
0.11	   September 18, 2006
BlueTooth handling bug fix.
0.10	   September 17, 2006
Added feature to send the currently active document over BlueTooth. A minor improvement to exception handling while saving files. Help file modified.
0.9	   August 17, 2006
Exit key renamed and reused in text editing mode, the pre-written sentences menu is now opened with the key. The options menu was slightly re-organized to make it faster to use. Help file updated. Note: documentation is still out of date.
0.8	   April 28, 2006
New features: icon, SMS number fetching from the Contacts database, Binary-Hex codec (hex editor), search, replace, sub-menu for editing. Fixed: 'pyFileManager for S60' launching, cursor position after text cut. Enhancements: module importing. Note: documentation is not up to date.
0.7	   February 16, 2006
Documentation updated. The library pyUtilsS60 was renamed pyS60uiutil and now version 0.4.0 of that library is required.
0.6	   February 1, 2006
The editor is capable to handle multiple documents simultaneously. The main options menu utilizes sub-menus. User selectable screen size. Code optimizations and cleaning. Copy/Cut'n'Paste enhanced. This version requires Python for S60 v1.3.1 or later.
0.5	   December 5, 2005
Text codecs ASCII, Latin, ISO-8859-1 fixed. Font and font color made user configurable. Note: at least some phones have problems with these. In those phones the default font and color should be used. This version requires Python for S60 v1.2.
0.4	   October 27, 2005
The version numbering scheme changed, i.e., the least significant digit dropped because py2sisng supports only two digit version numbers. The SYMBIAN_UID was changed to 0x1027972E which was officially allocated from Symbian. The tab handling of the 'Editor settings' was fixed; previously the tabs were used in an incorrect way which may have caused minor problems.
0.3.0	   August 20, 2005
Improved cursor movements (jumping with joystick), and copy/cut and paste usage changed. Options menu made more efficient. Error checking improved. Documentation improved. Some cosmetic enhancements to the code and user interface.
0.2.0	   May 5, 2005.
The following features were added: Editor settings menu, copy/cut and paste, favorite documents list.
0.1.0	   March 8, 2005.
This is the initial release. In addition to basic text handling, the editor contains already quite a few useful features.

4. ToDo List

- Update and polish the documentation.
- Possibility to insert the text of the MMS/Bt/etc messages in addition to
  the SMS from the Inbox. Currently this would require a separate native
  C++ module.
- Jumping to the beginning/end of line does not work properly if the current
  cursor position is either "in the beginning of the doc" or
  "in the end of the doc".
- Some features require fine tuning. For example:
  * clipboard should be able to store multiple entries
- Possibility to add links to attachments and open them separately?
- Add simple and fast voice recorder?

5. List of Files

The pyEditS60 consist of the following files.

Python source files:
- pyEdit.py			The main program of pyEditS60.
- sms_ui.py			User interface for sending and importing 
				the text messages.
- bt_ui.py			User interface for sending the text over
				BlueTooth.
- default.py			Used to launch the editor in the case it is
				ran as a standalone application.

Text files:
- DISCLAIMER			Read this file before using pyEditS60.
- pyedits60help.txt		Content for the 'Help' menu item.
- README.txt			This file.

Bitmap image files:
- pyEditS60icon.mbm		pyEditS60 icon for the 2nd edition.

Scalable vector graphics files:
- pyEditS60iconR0.svg(t)	pyEditS60 icon for the 3rd edition.

6. Credits

Thanks to Tero Hasu for providing patch for the font size configuration.

