*******
SUMMARY
*******

FieldPlus enables users to use their 5-way navigation button
to select text in standard PalmOS text input fields. Third
party word processing applications typically use their own
text routines, so FieldPlus will not affect them.

***************
VERSION HISTORY
***************

v1.1

Initial public release. Supports basic selection, toggling
between word- and character-based selection, and opening
the Palm Command Bar by holding the Menu key.

v1.2

- Disabled execution on Tungsten T5 due to the lack of a
keyboard.
- Fixed selecting beyond the field boundary (previously
selection was lost if the field scrolled). Note that scroll
bar locations will not update until selecting is done. There
are no adverse effects from this behavior.
- Added option to set how non-alphanumeric characters
(refered to in documentation as space characters) are treated
while selecting in word mode.

v1.3

- Fixed field overrun bug when selecting words with spaces
at the beginning of a field.
- Added option for how symbols are treated during selection.
- Added autodial option for things that 'look' like phone
numbers. Additional autodial options will be forthcoming.

v1.3.1

- The standard Treo Dial Number dialog is opened when a number
is selected and autodial is enabled.

v2.0

- Added additional selection operations including: select
word, select line, select sentence, select all.
- Added additional operations that can be performed on
selections including: use selection, cut, copy, and paste.
- Expanded use of center button to be disabled, perform
a single selected action, or open a popup with all operations.
- Optional optimized support after a cut or copy operation.
- Removed auto-use option. (this was a temporary addition
until a more active means of using selections was devised).
- Fixed previous disabling of shift+backspace deletes word
behavior.

v2.1

- Added Exclusion list to prevent FieldPlus from running in
high-performance applications; for example NesEm or other
games.
- Added Quick quit option to allow disabling FieldPlus for
the duration of the current program.
- Fixed initial focuson Treo 600 preference panel.
- Fixed center action setting keeps FieldPlus active problem.

v2.2

- Added move-without-select behavior
- Fixed erroneous activation of behavior when insert point not active

v2.2.1

- Fixed bug that lost exclusion settings when 2.2 was installed over
2.1
- Fixed improper version reporting. 2.2 was listed as 2.2a. Current
version should show 2.2.1
- Fixed unable to select certain non-typical characters, such as the
bullet character.
- Fixed date jumping and selection problems when running in DateBk.
- Fixed jumping problems in SnapperMail.
- Fixed crash problem when clicking menus in Phone app
- Added check to try to minimize application cross-talk
- Fixed incomplete clearing of graffiti state

v2.2.2

- Fixed compatibility with DateBk (be sure to be running the most
recent version of DateBk; tested on 5.4a,p7)
- Added a few more device compatibility checks

v2.2.3

- Post edit setting was not being honored

************
KNOWN ISSUES
************


*************
Configuration
*************

FieldPlus is installed as a Preferences applet, meaning it is
not visible in the normal Launcher. To access the configuration
screens for FieldPlus, open the Preferences application. On
a Treo 600, FieldPlus will be visible as an option in the popup
list at the top-right corner. On a Treo 650, scroll down to
the Other section and you will see FieldPlus listed there.

Layout

There are 4 main configuration areas for FieldPlus split into 4
separate screens. Switch between screens by using the popup list
immediately below the Preferences title bar.

Selection: sets whether selection is enabled, and the default
selection behavior

Center Action: sets whether to use the center button for FieldPlus
operations, and how to use it

Command Bar: sets whether to use the menu button to open the
Palm Command Bar

Exclusions: sets where not to run FieldPlus. FieldPlus can
affect the performance of resource0intensive software, such
as games.

Available Settings

Selection

5-way does: whether selection or movement using the 5-way
navigation control, or both are enabled. If not enabled,
center actions will not be enabled either.

nothing: neither selection nor movement is enabled. This
also disables the shift+center action setting.

select only: only selection using shift is enabled.
Movement is not enabled.

move only: only left/right movement using option is enabled.
Selection and the shift+center action are disabled.

both: selection and the shift+center action, and left/right
movement using option are bth enabled.

Right and left select: sets whether the default selection
mode is by letter, or by word. This option is hidden
when selection is not enabled.

Word mode skips spaces: When selecting by word, this
sets whether to jump over whitespace between words.
When checked, whitespace is skipped. When unchecked,
Spaces are selected space-by-space. This option is
hidden when selection is not enabled. This option is
relevant even when the default selection mode is,
Letter, as users may toggle between word and letter
mode while selecting. This option also impacts how
option movement jumps over words.

Treat symbols as letters: When selecting by word, this
sets whether to include symbols as letters. When
checked, symbols are selected as part of a word. When
unchecked, symbols are selected character-by-character.
This option is hidden when selection is not enabled.
This option is relevant even when the default selection
mode is, Letter, as users may toggle between word and
letter mode while selecting. This option also impacts
how option movement jumps over words.

Center Action

Center button does: sets the general behavior of the center
button while selecting.

no action: the center button is not used for selection
operations.

single action: the center button always performs a
single selected action.

action menu: the center button opens a popup allowing
users to select an action to perform. The popup can
be cancelled without selecting an action by pressing
left, right, shift, or option.

Single action: displayed when 'Center button does' is set
to 'single action'. Allows the user to select the
single action that will be performed when the center
button is pressed.

toggle mode: toggle between Letter and Word selection mode.
The cursor remains at the current position, and the user
may continue selecting the new mode. Toggling again will
switch back to the original mode. Note that if select
mode is terminated (either by terminating one-hand mode,
or by releasing the shift key) the default select mode
will be active when selection is re-activated, not the
last toggled mode.

use selection: look for 'usable' content in the current
selection. This content need not start at the beginning
of the selection. Supported content includes:

phone number: prompts the user to dial or SMS
the selected number. Users may cancel this action
at this time.

url: opens the url in the default browser.

email: opens a new email to the selected address
in the default mail client.

If the user cancels using a phone number, they will remain
in selection mode and can continue with the current
selection.

select word: selects the current word at the insert point.
The user remains in selection mode with the cursor at the
end of the new selection.

select line: selects the entire line at the insert point.
The user remains in selection mode with the cursor at the
end of the new selection.

select sentence: selects an entire sentence (which can
span multiple lines) at the insert point. Note that mid-
sentence terminal punctuation (especially periods used in
abbreviations) will prevent full sentence identification.
The user remains in selection mode with the cursor at the
end of the new selection.

select all: selects the contents of the entire field.
The user remains in selection mode with the cursor at the
end of the new selection.

cut: cuts the selected text, removing it from the field and
placing it on the clipboard. The user will no longer be in
selection mode so that they can move to a new location
(presumably to paste what they just cut) without selecting
intervening text.

paste: pastes the current contents of the clipboard at the
insertion point. The user will no longer be in
selection mode after the paste operation.

copy: copies the selected text to the system clipboard.
The user will no longer be in selection mode so that they
can move to a new location (presumably to paste what they
just copied) without selecting intervening text.

Optimize after cut or copy: displayed only when 'Center
button does' is set to 'action menu'. When in one-hand
operation (discussed below), this will place FieldPlus
into a special mode after performing a cut or a copy.
Until the shift key is pressed again, the user will be
able to move about the current field, and even enter
text, and when the center button is pressed, the menu will
open without holding or pressing shift again (typically
a cut, copy or paste will cause one-hand mode to end).

Press shift after a cut or copy to terminate this mode,
then shift again to re-enter one-hand mode. To avoid this
behvaior (in which case, the post action state will be as
described for each action above) uncheck this option.

Command Bar

Holding menu opens command bar: allows the System Command Bar
to be opened by holding the Menu key for a short time. This
is usually opened by a special pen motion written in the
Graffiti area, but as many users do not enable Graffiti input
on their Treo's the functionality that some applications add
to the Command Bar can be hidden. The Command Bar will open
automatically when the hold time has passed. This option
can be enabled or disabled separately from the other
selection options.

Exclusion

The list here presents all discoverable applications in main
memory. Applications on the card will not be listed. Most
shortcut style applications (such as those created by PowerRUN
or ZLauncher) should appear and function as normal. By
checking an application, FieldPlus will not run while that
application is active. While most applications will be
unaffected by the few resources used by FieldPlus, this is
useful for high-performance applications such as games (or
emulator like NesEm). Disabling FieldPlus in these
applications will leave all system resources to that
application, enabling better performance.

Quick quit: For applications that don't appear in main memory,
it is still possible to disable FieldPlus completely for
the duration of an application. If Quick quit is enabled,
press shift + hard key 4 (power button) will terminate
FieldPlus completely until another application starts. If
you are using a high-performance application from a ROM-
based card (retail), this will still allow you to get the
most performance while such an application runs.

*****
Usage
*****

Activating selection mode

To activate selection mode, first the 'Enable 5-way selecting'
option must be enabled. This is accessed in the Selection
section of the FieldPlus configuration (in the Preferences
application).

Selection can only be activated while in a standard PalmOS field.
This is typically used for short text input in dialogs, Memo Pad
is one large field, VersaMail uses fields for writing emails,
Messaging uses fields for composing SMS messages, Blazer (Web)
uses fields for most text input. Fields are very common
throughout PalmOS applications.

HOWEVER, most word processing programs use their own custom
methods of inputing and displaying text. FieldPlus will not
affect these applications.

Selecting can be activated in 2 ways:

1) Press and release the Shift key. This activates one-hand
mode. Press and release again to exit.

2) Press and hold the Shift key. Selecting will be enabled
until the Shift key is released.

While in shift mode, the following key actions are in effect:

- Up selects up to the next line.
- Right selects to the right (according to the selection
configuration settings).
- Down selects down to the next line.
- Left selects to the left (according to the selection
configuration settings).

Pressing the center button will perform the action assigned to
the center button.

When the center button is set to open the action menu, pressing
the center button will open a small popup list of actions that
can be performed. The order of the options is always the same
as the order in this document (and the order of actions when
selecting a single action in the FieldPlus configuration). To
close the popup without making a selection, press either left,
right, shift, or option.

Toggle mode is always displayed first, so to quickly toggle
between selection modes, just press the center button twice.
The other options are listed to try to put more common actions
close to the first position. Cut, paste, and copy are placed
at the end of the normal list, because users can wrap around
the action list (push up from toggle mode to wrap to the
bottom of the list). Therefore, copy is actually only one item
away from toggle mode, and paste is only 2 away.

If the user is holding the shift key when the popup opens, and
continues to hold it through selecting an action, they will
remain in selection mode even for cases that say they will not.
Likewise, if they are holding the shift key when the popup opens,
but release it, they will not be in selection mode after they
select an action. The resulting selection states apply only
when the user is in one-hand mode.

Fast movement can be activated in 2 ways:

1) Press and release the Option key. This activates one-hand
mode. Press and release again to exit.

2) Press and hold the Options key. Movement will be enabled
until the Option key is released.

While in option mode, the following key actions are in effect:

- Right moves one word to the right (according to the selection
configuration settings). If at the end of a field, the motion
event is handled by the underlying application.
- Left moves one word to the left (according to the selection
configuration settings). If at the start of a field, the motion
event is handled by the underlying application.

Option+up/down currently has no special meaning, and any observed
behaviors are caused by the underlying application. Option
movement, unlike selection, can actually move the focus out of the
current field. This is a result of application specific behavior.
Calendar, for instance, allows users to scroll by week when option
is held. On the Treo 600, if you have put the focus in an event
field, it's actually somewhat difficult to extract it again to allow
Calendar to process the option+keystroke. This is complicated by
the option key 'selecting' a calendar entry. So as not to override
any of the built in behaviors, FieldPlus will return control to the
application when it has no effect on the insert point motion.

This is an issue I'm continuing to think about. If you have any
strong feelings about it, please mail me about it.

****************
Acknowledgements
****************

Several key users have contributed ideas, suggestions, and testing
resources to help me improve this utility. You know who you are!

Thanks a lot!

*******
Contact
*******

Email questions, comments, or bugs to: arognlie@earthlink.net

Be aware that I use an email whitelist, so don't be surprised
if you receive an email from Earthlink for you to request being
added to my list.

You can also post feedback at PalmGear.com.