TealTools User's Manual

Description

Thank you for trying TealTools. TealTools is a collection of handy popup utilities.
Included in the package are TealFiles, a popup file/backup manager; TealTime, a combination clock stopwatch and timer; TealPad, a pop-up memo pad; TealCalc, a pop-up calculator; TealPrefs, a preferences utility; and TealEdit, a text editing aide.
These utilities are designed to make your Palm device a more efficient tool.

This archive contains the following files:

Program files:

TEALTOOL.PRC
The TealTools menu startup application

TEALTHCK.PRC
The TealTools Hack system extension launcher

HACKMSTR.PRC
The Hackmaster system extensions manager

Utility files:

TEALFILE.PRC
The TealFiles file/backup management utility

TEALTIME.PRC
The TealTime clock/stopwatch/timer

TEALCALC.PRC
The TealCalc popup calculator

TEALPREF.PRC
The TealPrefs quick access preferences utility

TEALEDIT.PRC
The TealEdit text-editing helper utility

TEALPAD.PRC
The TealPad popup memo pad

Document files:

TOOLDOC.PDF
This document in Adobe Acrobat (PDF) format

TOOLDOC.HTM
This document in HTML format (sans images)

TOOLDOC.PRC
This document in TealDoc format

Installing

Use the Palm Install Tool that comes with your organizer to install the individual utility modules TEALFILE.PRC, TEALTIME.PRC, TEALCALC.PRC, TEALPREF.PRC, TEALEDIT.PRC, and TEALPAD.PRC.

YouÆll also need to arrange a method of launching the utility modules.
If you are already running a popup/DA-compatible launcher like TealLaunch, you can configure it to launch the modules.
If not, install TEALTHCK.PRC, the TealTools Hack system extension.
Also install HACKMSTR.PRC if you do not already have it or an alternate system extensions manager on your organizer.

Optionally install the TealTools launcher menu program TEALTOOL.PRC, to start any of the tools from the standard applications launcher. This manual is provided in this archive as the PalmPilot document TOOLDOC.PRC, which you may also install for viewing with our program TealDoc.

Instructions on how to use the Palm installer are in the Palm Handbook that came with your Pilot, PalmPilot, or WorkPad.

Important Note: Before updating or deleting any Hackmaster system extension like TealLaunch, you must to disable the extension first in the Hackmaster control screen.

Overview

TealTools is a collection of handy Palm desk accessories, or ôDAö modules, designed to be run with the aid of a popup launcher program, like TealLaunch or the included TealTools Hack.
As desk accessories, TealTools modules can be configured to pop-up over the current application, so you can run them without leaving the current app.

Typically, you configure TealTools modules to appear using a specific button press combination or pen stroke.
In TealLaunch, you can link both desk accessories and applications to launch in response to button presses, button combinations, and pen strokes in the graffiti text area, and mapping is fully configurable.
The included TealTools Hack is similar, but it is configured only to launch TealTools modules using six predefined pen strokes.

TealTools also includes the TealTools menu program, which is a standard PalmPilot application with buttons to directly launch each of the TealTools utilities without aid of a popup launcher program.
Some utilities, such as TealEdit, are not particularly useful when run in this manner, but the menu program allows you to preview the modules easily to determine each oneÆs functionality and interface.

What are Desk Accessories?

Palm desk accessories (DAs) are small programs designed to pop up over your current program.
You can run them without leaving your current app.
Thus, they lend themselves to quick operations or even operations that interact directly with the current app such text-editing aides.

The Palm OS does not come with built-in support for desk accessories, so it doesn't come with a way to launch them.
TealTools Hack is a simple DA launcher designed only to launch TealTools utilities.
A number of configurable launching programs like TealLaunch exist, each with their own unique and sometimes configurable ways of activating selected accessories.

For more info on the DA standard, visit http://member.nifty.ne.jp/yamakado/da/.

Using TealTools

TealTools Menu App

To quickly try each of the TealTools utilities, start the TealTools menu app.
Tap on the button corresponding to the utility you want to run.

TealTools Hack

To launch a utility as a popup application, run the Hackmaster

system extensions manager.
Activate the TealTools Hack by checking the checkbox next to the TealTools Hack listing.
Once this is done, you can bring up any of the tools using a corresponding pen stroke in the silkscreen area below the display:

TealTools Hack Activation strokes

1) TealFiles û stroke from Apps button to Menu

2) TealTime û stroke from Calc button to Find

3) TealPrefs û stroke from Apps button to graffiti area

4) TealEdit û stroke from Menu button to graffiti area

5) TealCalc û stroke from Calc button to graffiti area

6) TealPad û stroke from Find button to graffiti area

Alternatively, to use a configurable popup/DA launcher, follow its directions on how to add and activate a Palm desk accessory file.
TealLaunch 2.0 or higher supports desk accessories as well as applications.
Simply select and activate the desk accessory the same way you would select and launch an application.

Using TealTools Utility Modules

When started, a utility will pop-up a window over the current screen.
You may move the window by dragging the title bar of the window with a pen, or dismiss it by tapping the close button in the upper left hand corner or anywhere on the screen outside the window.

TealFiles

Perhaps the most ambitious utility in the package, TealFiles lets you view all the files on your Palm device, viewing critical information such as size, flags, type, creator, records, modification date, backup date, and more.
More importantly, it's a full backup manager, letting you set or clear backup flags and dates for individual files or lists of files based on type.
You can even delete or rename selected files, but do so with caution, of course.

Viewing Files

TealFiles lists all the files installed on the organizer falling under a specified category.
Three popup lists appear on top of the list display.
The first selects the category to show.
Using the remaining two, you can select two different file characteristics to display for each file in addition to its name.
To seek to a particular file, you can use graffiti to enter the first letter of the file to show.

List Categories

All

Shows all files currently installed.

Applications

Shows only stand-alone application files

Desk Accessories

Shows only desk accessory files like TealTools utilities

Hacks

Shows only Hackmaster-compatible system extensions like TealLaunch.

TealDocs

Shows only standard Doc files and TealDoc native documents.

TealInfo Folios

Shows only TealInfo folio files.

TealPaint Pictures

Shows only TealPaint-format image databases.

.PDB Databases

Shows only Palm database files.
This includes almost all data (non-program) files.

.PRC Resource Files

Shows only Palm resource files, which typically includes programs, hacks, desk accessories, and data for a few applications that use the resource data format.

RAM-Based

Shows only writable files in RAM.

ROM/Flash

Shows only non-readable files, typically because they reside in ROM or flash memory.

By Palm

Shows only files with Creator IDs (see appendix) indicating that they are programs or data associated with programs created by Palm Computing.

Non-Palm

Shows only files with Creator IDs (see appendix) indicating that they are third-party programs or data associated with such programs.

Orphans

Shows only non-system data files without an associated program, hack, or desk accessory.
This may indicate that the file is left over from a previous program and is no longer needed.
Some files, however, like Doc files, may not be associated with any single program and may appear as an ôorphanö even if it can be used by an installed program.
Others, may be coded to not correspond to a programÆs Creator ID or may follow a standard TealFiles does not recognize.

File Characteristics

Size

The size of the file in Kilobytes.

Attribute Flags

Attributes of the file, including:

b - Backup bit, enabled.
The file is checked at every HotSync, but has not been modified since the last time it was backed up and will thus not be copied to the PC at that time.

B - Backup bit, enabled and modified.
The file is marked for backup and has also been modified since the last time it was backed up. It will be copied to the PC at the next HotSync.

D -
The file is a database file.
All Palm files are either database (.PDB) files or resource (.PRC) files.
The former are data files, while the latter are typically applications.

R - The file is read-only, either because it is marked as a read-only file internally or it resides in ROM or flash memory.

O - The file is either still in use by an application or has not been properly closed.

Type

The four-letter file-type, used to indicate the purpose of the file.
For instance, the Palm OS recognizes all resource files with the type æapplÆ as applications.

Creator

The four-letter Creator-ID for a program or the program associated with a file.
Palm Computing requires every application to have a unique Creator-ID registered with them.
Palm Computing reserves use of all Creator IDs consisting entirely of lower-case letters.

Num Records

The number of records in the database or resource file.

Modification Date

The date the file was last modified.

Backup Date

The date the file was last backed up.

Backing Up Files

In TealFiles, you turn on and off the backup bit of a selected writable file by tapping on the Enable button at the bottom of the window.
If you tap on the Force button, youÆll set the backup bit and also change the modification date to force a backup at the next HotSync.
For more information about file management and the Palm backup mechanism please refer to Appendix A.

Performing a Full Backup

ItÆs inescapableà batteries shake loose, hardware can suffer from glitches, and software sometimes has bugs.
ItÆs a good idea to periodically backup your data and applications just in case.
With TealFiles, you can easily backup all your data so it will be restored in case the worst happens.

Several menu items exist to facilitate a full backup.
First, the Enable all in list menu can be used to set the backup bits for all currently listed files.
The Force all enabled menu will then update the modification date of these files to force a backup.
To restore the backup bits to their previous state, the Take Snapshot and Restore from Snapshot menus can be used to respectively save off the current state of all backup bits and subsequently set them back.

The sequence for performing a full backup is:

1) Set view category to Show All

2) Select Take Snapshot

3) Select Enable all in list

4) Select Force all enabled

5) HotSync

6) Select Restore from Snapshot

You may also want to first move current files out of your backup folder on the PC.
This will keep only current files in your backup and thus prevent older files from being restored onto your Palm.

Deleting Files

You can delete a selected file using the Delete selected file menu if the file is not marked as read-only.
Be very careful when using this menu item, of course.

Renaming Files

You can also rename a selected file using the Rename selected file menu if the file is not marked as read-only.
Use this menu with care, as many programs are not written to expect files with specific names and may get confused with renamed files.

TealPrefs

The TealPrefs utility lets you set common Preferences settings like volume, beaming, and sleep time.
You can even turn sleep time off altogether, an option not found in normal preferences.
With TealPrefs running under a popup launcher, you can quickly change, for example, volume levels, without exiting your current application.
When changing volumes you can check the ôpreview soundö checkbox to select whether a sound is when a volume level is changed.

TealEdit

TealEdit lets you perform some cool editing tricks on selected text such as capitalization, indenting, phone number manipulation, or adding bullet points.
You can even scramble and unscramble selected text or sort multiple lines.

Capitalization

Selecting a capitalization option will change selected text to upper case, lower case, or mixed case, where the first letter of each word is in upper case.

Lists

Multi-line lists can be created with this option.
Simply select multiple lines of text and select a bullet style to apply to the lines.
Plain bullets, numerical, and alphabetic styles are supported.
Select the option again to turn off the bullets.

Phone Numbers

A phone number can be automatically formatted into one of three formats using this option:
period, hyphen, and parentheses:
e.g. 1.415.555.1212, 1-415-555-1212, and 1 (415) 555-1212.
The cursor need only be within the phone number; the code will automatically select and modify the numbers removing any existing formatting.
The formatting is intelligent, understanding valid phone number formats calling from within the USA only, including an optional leading ô1ö, optional area codes, and international calling prefixes for numbers starting with ô011ö or ô+ö.

Indenting

A block of text can be indented in our out using the indentation options.
Note that only lines following a hard break will be affected; lines broken by automatic word wrapping will not be indented.

Sorting

With the sorting buttons, multiple lines of text can be sorted alphabetically in either ascending or descending order.

Insert Date/Time

The current date or time can be inserted into a text field using this option.
The date and time format follows the current global settings in system preferences.

Cut/Copy/Paste/Select All

Common clipboard editing functions are available; handy for programs or dialogs which do not provide the corresponding menu items.

Crypto

Encrypting a block of text is a quick way to easily obscure the contents of a selected block of text.
The encryption is neither rigorous nor password-protected, but it is useful for keeping wandering eyes from casually overlooking a sensitive item in your datebook or checklist, particularly if they donÆt know about TealEdit.

TealPad

A popup memo pad with 8 switchable pages, TealPad is handy to quickly jot down notes or provide commonly needed reference items, like your TealLaunch mappings.
To view or modify TealPad memos, simply choose one of eight available pages by tapping on the page number.
TealPadÆs memos are stored in a database separate from the standard memopad application.

By tapping the silk-screened æMenuÆ button, you can access menus to cut, copy, and paste selections of text.
You can also choose the Export to MemoPad menu to copy the current page to a new record in the standard MemoPad applicationÆs database.

TealCalc

No popup utilities collection is complete without a popup calculator.
TealCalc functions like any basic calculator with two useful extra functions.
If a number is highlighted in a text field when TealCalc is opened, that number will automatically be entered into TealCalc.
You can also paste a result of a calculation back into a text field by pressing the Paste button.
You have the ability to toggle between two different sizes for TealCalc pop-up screen in order to best fit your needs, by tapping the size button in the upper left corner of the window next to the close button.

TealTime

TealTime is a full-featured clock/stopwatch/timer.
You can run it as a simple clock, 4 independent on/off timers, 2-4 runner lap timer, or a countdown timer.

A row of mode-selectors exist along the top edge of the window, while buttons to start and stop the active timer (when applicable) appear along the bottom.

The Page-Up and Page-Down hardware scroll buttons also emulate these buttons.
Page-Up is equivalent to the Start/Stop button, while pressing the Page-Down button performs a reset.

Clock

The TealTime clock shows the date and time and supports 12-hour and 24-hour format.
You can optionally also configure the program play a ôtickö sound every second by selecting the speaker icon.

StopWatch

The TealTime stopwatch supports four independent stopwatch channels.
Select a channel by clicking on one of the four dashed selector boxes.
Once a channel is selected, it can be started or stopped with the Start/Stop button (or Page-Up), or set to zero with the Reset button (or Page-Down).

Lap Timer

The TealTime lap timer is very similar to the stopwatch function, except that it automatically synchronizes up to four channels to facilitate simultaneous events such as multi-person races.
Select the number of active channels (2-4) using the lap-count selectors at the top of the window.

In lap timer mode, the Reset button resets all active channels, and the Start/Stop button starts all the channels simultaneously.
Once the timers are running, the Start/Stop button stops the first running channel, and subsequence taps stops the other channels one at a time in sequence.
Lastly unlike the case in stopwatch mode, once all the channels are stopped, the Start/Stop button wonÆt restart them until the timers are Reset, but will instead just cycle through each of the channels for easy viewing of the individual times.

Timer

The TealTime countdown timer, provide a simple reverse timer that counts down from a set time to zero, playing at alarm sound when expired. Use on-screen the up and down arrows to set the initial time, and tap the Start/Stop button to begin the descending countdown.

APPENDIX A û The Palm File System

The Palm file system differs significantly from that of any computing platform and is both the source of both much of the Palm Operating SystemÆs popularity over other handheld platforms and of confusion from consumers as well.
Proper use of the TealFiles requires a good understanding of the file systemÆs structure and functionality.

File Structure

Most operating systems including Macs, PCs, and Windows CE, have file systems designed primarily for slow, mass storage peripherals like hard disks.
Programs and data are stored on the peripheral, but must be loading into RAM to be viewed or edited, then saved back to disk when done.
While this process might be for a desktop computer, it is very painfully slow and wasteful of memory on a handheld device, where the files are already in RAM to begin with, making the load and saving process wasteful.

The Palm OS solves this problem by designing a file format designed on memory-based records rather than a linear file.
The data can be accessed, modified, and sized directly in file memory, eliminating the save and load steps, and making application-switching quick and efficient.

File Formats

The Palm OS supports two different file types.
The first, called Databases, are memory-based collections of data records used to store blocks of information.
Each block can be manipulated individually, and created, deleted, or moved relative to other data records.
The Address book database, for instance, stored each address book entry as an individual record.
The Datebook app stores each entered event as a record in the DatebookDB database, sorted by time.

The second file type, a Resource, is actually just a modified database, where individual records have a four-letter type and a numerical ID number used to access them.
Palm applications are resource databases, where storing program code, UI definitions, icons, and version information as separate resource records.
While some programs use resources to store data as well, most resource files are programs.

Files on the Desktop

The Database or Resource files appear on the desktop, theyÆre given an extension to indicate their type.
Databases are given the .PDB extension, and Resources are given the .PRC extension.
These file extensions are only for the benefit of the desktop software, however, as the Palm OS does not use file extensions.
In fact, the wrong extension is sometimes given to Palm files.
For instance, the Doc file format specifies a database file, but many Doc files are mistakenly given the .PRC extension instead of the correct .PDB extension.

A side effect of the Database and Resource formats in that the Palm cannot use any standard desktop file formats, as they donÆt fit the Palm file format model.
Text files, images, databasesùall must be converted before they can even be installed onto a Palm, as the Palm OS file system cannot handle an arbitrary file of data without a special file header and structure.
This one limitation of the Palm file system negates the meaning of ôstandardö image viewers, HTML browsers, or other data-dependent applications, as data for such programs must all be manipulated and converted anyway.

Another common source of confusion occurs around the meaning of the .PDB and .PRC file extensions.
As all Palm files appear on the PC with one of these two extensions, it says nothing about what the files actually contain.
For instance, a file with a .PDB extension can be an image, shopping list, document, address book, or any number of file formats designed for completely different programs, but you canÆt determine itÆs specific purpose from the file extension, as the Palm OS does not use them.

Type and Creator ID

Instead, the Palm OS uses two four-letter codes to determine a fileÆs purpose and origin.
These, the Type and CreatorID, are buried in the header of Palm files, but can only be seen on a desktop computer with a hex dump of the data.

The CreatorID is a four-letter code that indicates the creator, or owner of the resource or database.
All CreatorIDs are required to be registered with Palm Computing, so that no two application developers will use the same CreatorID for different purposes.
Typically, a program and its data are given the same CreatorID, so that the Palm OS will instantly know which program to which a data file belongs.
For instance, the Address Book application has a CreatorID of ôaddrö.
ItÆs database, ôAddressBookDBö has the same CreatorID as well.

The Type code for an application indicates the purpose of a file.
A few Type codes are standardized, but many are custom for an application.
For instance, applications always have the Type value ôapplö, desk accessories ôDAccö, and ôDocö files ôTEXtö.

Incidentally, both CreatorIDs and Type codes are case-sensitive.
Palm reserves all codes consisting of four lower case letters.
Thus, all files lower case codes indicate programs written by Palm or data intended for such programs.

File Management

Surprisingly, the PalmPilot is unique in that it does not ship with a file management program like TealFiles.
In fact, on a base device, there is no way to individually rename or delete files.
Instead, PalmOS only ships with the Launcher appÆs Delete menu, which really more of a program uninstaller than a file management screen.

In the Delete screen, listed files are grouped so that files with the same CreatorID are lumped together.
If one of the files in each entry is an application, then its name is used for the list entry.
If not, then the name of the first file found of each CreatorID is used.

The advantage of this approach is that it makes uninstalling an application a snap.
When you delete a program, all of its data is deleted as well.

The downside occurs when one needs to delete a single data file rather than all files and the corresponding program.
It canÆt be done without a tool like TealFiles. Worse yet, when working with files shared between programs like Doc files, no application with may be present that corresponds to the files, and the Delete menu will simply show the name of a single file.
Commonly, customers use the standard Delete menu to remove what they single Doc file, and end up deleting all of their docs instead.

Backup Mechanism

A similar vacancy exists in the PalmOS backup mechanism.
While a mechanism exists to backup all files back to the desktop PC, not program is included to manage the backup of files, and all such control is left to individual applications.

During a HotSync, files are backed up from the Palm to the PC using one of two mechanisms.
For some files, the Palm program communicates with special code on the PC called a conduit, which facilitates synchronization of the data between the PC and Palm.
The built-in Palm applications use this mechanism.

Most other files on the Palm use the second default backup mechanism, based on backup bits and modification dates.
Every file on the Palm has a flag, or bit, in itÆs header that indicates whether the file should be backed up.
When you HotSync, the HotSync program looks at all the files that have this flag enabled.

Not all of these files automatically get backed up, however.
To save time, only files that have changed actually make the journey back to the desktop.
To determine this, the HotSync App compares each fileÆs modification date to its last backup date, and only copies files that have changed since itÆs last backup.

The files appear on the desktop in a backup folder stored two levels inside Palm install folder.
For instance, if the Palm Software is installed in the folder C:\Palm, for a user name John Doe, his backup files would be in the folder C:\Palm\DoeJ\Backup.

APPENDIX B - Compatibility

As we cannot control the style and robustness of other products, we cannot guarantee compatibility with PalmPilot applications beyond those included from Palm Computing. However, we try to resolve compatibility issues as best we can.

TealLaunch

TealLaunch recognizes TealTools utilities as standard DA files and can launch them the same as any application.

APPENDIX C - Revision History

Release 1.03 August 4, 2000

╖ Initial program release

APPENDIX D - Credits

Manual by Vince Lee, Tex Tennison, and Sara Houseman

APPENDIX E - Contact Info

TealTools, TealFiles, TealTime, TealCalc, TealPrefs, and TealEdit by TealPoint Software

TealPoint Software

454 Las Gallinas Ave #318

San Rafael, CA 94903-3618

We look forward to hearing from you.

Please visit us at www.tealpoint.com, or email us at contact@tealpoint.com.

APPENDIX F - Registering

Currently, you may register by snail mail, electronically through our website at www.tealpoint.com with a credit card and a secured server, or through PalmGear HQ at 1-800-741-9070. For the first option, the enclosed registration form is provided for your convenience. You may use this form or simply send the following to the address above.

º Product Name

º E-Mail Address

º HotSync User ID (Pilot Name Required for Passkey generation. It can be found on the main screen of the HotSync application on the Pilot as "Welcome ________" or in the corner on a Palm III or higher)

º Check (drawn off a US Bank) or Money Order for ($19.95 US) to TealPoint Software

Disclaimer

We at TealPoint Software are committed to providing quality, easy-to-use software. However, this product is provided without warranty and the user accepts full responsibility for any damages, consequential or otherwise, resulting from its use.

This archive is freely redistributable, provided it is made available only in its complete, unmodified form with no additional files and for noncommercial purposes only. Any other use must have prior written authorization from TealPoint Software.

Unauthorized commercial use includes, but is not limited to:

º A product for sale.

º Accompanying a product for sale.

º Accompanying a magazine, book or other publication for sale.

º Distribution with "Media", "Copying" or other incidental costs.

º Available for download with access or download fees.

This program may be used on a trial basis for 30 days. The program will continue to function afterwards. However, if after this time you wish to continue using it, please register with us for the nominal fee listed in the program.

Thank you.

*HackMaster is By Edward Keyes, DaggerWare Software
www.daggerware.com