[an error occurred while processing this directive]

Shead Spreet Documentation

v3.4.2

Where to Find the Documentation

The complete documentation can be viewed either through the Help menu item from within the app or can be viewed on the web at http://keithwiley.com/software/sheadSpreetDocs.shtml.

Lite vs. Pro Versions

All features are fully enabled in the lite version. The following list describes the differences between the lite and pro versions:

-- The lite version restricts the number of rows and columns.
-- The lite version forces the splash screen to be displayed on every app launch while the pro version provides a setting to skip many such occurrences.

Files and Filenames

Shead Spreet reads and writes all files to a public directory on the SD card. This makes it very easy to access the files from a computer when the device is attached by USB and mounted as an external storage device. This public directory is located at /sdcard/SheadSpreet_files/. If this directory doesn't exist the first time it is needed, Shead Spreet will create it automatically.

Note that Shead Spreet prefers (and assumes) that the SD card be named precisely sdcard. However, if you have changed the name of your SD card Shead Spreet should ask you to choose a location for the database. This is a difficult feature for me to test however since my own Android device conforms to the default convention in this regard.

To transfer files between a computer and Shead Spreet, connect the Android device to the computer with the USB cable and mount the device's SD card as an external storage device (an external disk). On your computer you will be able to navigate the device's file system, including the top directory /sdcard/. To retrieve saved or exported tables and plots, copy them from /sdcard/SheadSpreet_files/ to your computer. To upload an importable file to your device, put it in that same directory. Feel free to create that directory manually if it doesn't exist yet.

You may notice Shead Spreet doing a few strange things with file names. I will try to explain such behavior here. When a new table is created, it gets a default name of "Untitled", with the exception that if that name already exists, then "Untitled" will be suffixed with a number so that the new table's default name is always unique and will not represent a file-overwrite risk.

Shead Spreet will automatically save the table to a file under several circumstances, e.g., when the back button is pressed to return to the table-list, when the keyboard is opened or closed, thus flipping the orientation, when the Preferences or Plot views are opened, or when you transfer to another app, thus putting Shead Spreet in the background. Because many of these situations occur without the user necessarily intending to save, there is no explicit way to exit a table via the back button such that it is not saved on exit. The table must be manually deleted from the table-list.

A table's name at the time it is saved (as indicated in the editable text box at the top of the table) may represent an overwrite risk. While the default name that was assigned to a new empty table was generated to be unique, the user may have changed the name such that it now risks a file-overwrite with an existing file. When this occurs, Shead Spreet will rename the existing file, appending to its name the suffix "_moved". The open table will then assume the intended filename as it is saved.

If you cancel a long operation and then choose to save before exiting, the file name will be appended with a "_canceled" suffix so that later, you can easily tell that the file might be corrupted. It will make sense when you see it.

Shead Spreet also provides the option of autosaved files. These did not work properly in v1.2.2, often producing numerous files. The intended behavior, however, is that there should only exist a single auto-saved file in correspondance with a given nonauto-saved file, the auto-saved file's name always suffixed with "_auto". The purpose of auto-saved files is to permit the user to regain some data if the app crashes while in table view and before a standard save is performed, as described above.

Whenever an auto-saved file is opened in Shead Spreet, its "_auto" suffix will automatically be converted to "_restored", from which the user may then assign a new name of course. Ultimately, if you find the auto-saved files to be a cluttering nuisance, then simply disable the auto-saving feature in the preferences and no more auto-saved files should be saved.

Occasionally a new version of Shead Spreet will be accompanied by a completely new file format (ffv2, ffv3, ffv4, etc.) from that used in earlier versions. In most cases, the transition should go smoothly. After opening and then closing a file which originated from an earlier version of Shead Spreet, the original file will be left unchanged and a new file of the up-to-date file format version will appear in the table-list. Once you are confident that the new file has properly transferred the old file's contents and any new changes you have made while editing the file, you can safely delete the old file (always keep backups on your computer of course).

Note that if you revert to an older version of Shead Spreet which does not support a more recent file format, you will not be able to read such files anymore. There is a preference setting that will force Shead Spreet to save tables to older file formats for exactly this purpose, although I do not anticipate much need for it.

Renaming, Duplicating, and Deleting Tables

If you long-press a table's name in the table list, you will get a pop-up menu of additional file options, such as renaming, duplicating, and deleting tables.

Importing Tables

Tables can be imported from a number of common spread sheet formats: tab-delimited (.txt), comma-delimited (.csv), and Excel (.xls, .xlt, note that .xlsx is not supported).

Tables can be imported by selecting them from the table-list. Note that files must have the proper extension (case insensitive) before they can be imported. In the table-list you can long-press a file's name to rename it and alter its extension.

Shead Spreet identifies importable files by extension, as listed above. If you are certain you uploaded an importable file into the SheadSpreet_files directory, but do not see it in the import file list, then there is a good chance the file extension is incorrect. Return to the table-list and rename the file so that it has the proper extension.

Exporting Tables

Tables can be exported to a number of common spread sheet formats: tab-delimited (.txt), comma-delimited (.csv), Excel (.xls, .xlt, note that .xlsx is not supported) and HTML table code (.html).

Tables can be exported to email in tab-delimited, comma-delimited, HTML, or Excel format. The tables can be sent either as attachments or inline as plain text, as per the corresponding preference setting. Note, however, that Excel tables are always emailed as attachments. In order to email a table, you must have an email app installed which can handle the export. I recommend K-9, which is available on the Market.

Saving, Emailing, and Picture-Messaging Screen Captures

Images (screen captures) of tables can be saved as PNG files through the Export menu command.\n\n Screen captures can be sent to an email or picture-messaging app using the Export menu command. Note that Android converts images from high quality PNGs to heavily compressed JPEG when emailing images or sending picture-messages. I'm still trying to solve this problem.

Interfacing with Other Apps

Other apps can explicitly launch Shead Spreet and trigger an import operation on a file. For example, in Linda Manager, you can press a .txt, .csv, .xls, or .xlt file to open it with Shead Spreet. Note that .xlsx is not supported.

It is important to note that if the table is then changed and saved, it will aways be saved into Shead Spreet's default location: /sdcard/SheadSpreet_files, regardless of where the original file came from.

Depending on the email app you are using it may be difficult to send a file attachment directly to Shead Spreet, becuse the correct options may not be presented to you. For example, K-9 saves most files to the SD card without offering an option to send them to another app. If you have trouble, save the attachment to the SD card and then use a file manager app (like Linda Manager to send the file to Shead Spreet).

Transfer to/from Excel-Like Programs

Shead Spreet should be able to import and export .xls and .xlt files, which are a common Excel file format available not only to Excel, but also to Apple Numbers and many other spread sheet apps. Note that Shead Spreet is not able to import the more modern .xlsx format. Stick to .xls files you should be able to move formulas back and forth intact.

Please read the note in the Formulas section about function support.

Exporting Plots to File, Email, or Picture-Messenger

Plots are exported or sent to an email or picture-messaging app as PNG images. These images should be viewable in virtually any graphics application, including most browsers.

Note that while plots exported to files produce uncompressed PNG files, plots sent to an email or picture-messaging app unfortunately produce heavily compressed jpeg files. I'm still trying to solve this problem.

Dialing Phone Numbers

You can send phone numbers from a cell directly to the Dialer app via the contextual menu. The contextual menu can be reached by long-pressing a cell or by selecting the cell and choosing the associated main menu item.

Note that other than converting letters to their keypad numerical equivalents, very little attempt will be made to format or verifiy a cell's contents as a valid phone number. Android's behavior is to simply drop illegal characters from the text comprising a phone number. For example, if a cell contained "A1@" the dialer would receive "21" by converting the 'A' to a 2 and by dropping the '@' entirely.

Cell Formatting

Shead Spreet provides a variety of formatting options.

When you touch various formatting elements in the formatting dialog, they turn red. When you press the OK button, only those elements which are red are applied to the target cells. This enables you to apply partial formats to multiple cells at once. For example, if you only touch the italic checkbox, then you can set all the cells in a row or column (or the entire table) to be italic (or be nonitalic) without assigning the rest of the formatting elements at the same time (without conforming all of the cells to the same bold setting or the same color, for example).

If a cell is assigned the Number format it will only accept numerical input. In addition, if the soft-keyboard is used, it will default to the numerical keyboard which can save a considerable amount of effort over repetitious series of interactions.

Note that you can apply formatting commands to a single cell, a row, a column, or the entire table. Please read the hint included in the formatting dialog. It provides some important information on how to format multiple cells at once.

Sans serif italic text is not very pretty in Shead Spreet. This problem arises from the fact that Android's stock fonts do not actually support sans serif italic text. Shead Spreet fakes a sans serif italic appearance by skewing the image of a cell's contents. The result is of mediocre graphical quality.

There are two mutually exclusive text size selectors. One lists actual text sizes and the other lists percentage text size changes. The latter is particularly useful if you want to scale the entire table (to zoom, in effect) without losing the relative text sizes between cells of the table.

There is a preference setting which tells Shead Spreet to label a cell's formatting so you can see it at a glance. The label shows some of the formatting parameters in the form of a small-fonted short (and cryptic) message in the upper-left corner of the cell, built from left to right in the following way:

-- The assigned currency symbol
-- The assigned format type (#, Ud, Ut, or Udt)
-- The numerical precision

For example, 'L$#2' would indicate a locked cell with a leading dollar-sign, formatted as a number, and written to two points of precision.

Cell Locks

Cells can be locked to prevent any changes to them by the user. Such changes would include direct typing, pasting, fills from other cells, sorting of the cell's row or column, insertion of timestamps, locations, scanned barcodes, etc. The formatting of a locked cell also cannot be altered. However, if a cell contains a formula that references other cells, its evaluation and displayed result will change as usual in accordance with changes to its inputs.

A cell that is locked will be displayed with a small triangle in the upper-left corner.

Formulas

Formulas work pretty much like they do in other spread sheet programs, with the exception of more limited set of functions and a slightly weaker parsing engine (explained below). I am always willing to implement additional functions at the request of users. Please just email me and tell me which ones would be useful to you (of course, I also need the corresponding equation if it is a complicated function). Each function must be implemented individually and many are so esoteric that I don't feel inclined to do the work unless I know someone has a use for them.

Formulas always begin with an equals sign '=', just like Excel. Even if you think your phone's on-screen keyboard doesn't have an equals sign, I assure you it does. Read the phone's manual to learn how to access extended characters. Alternatively, if you choose the Insert Function menu command when focused on an empty cell, the equals sign will be inserted automatically for you.

I have tested the formula parsing and evaluation engine pretty thoroughly and am unaware of any existing errors. However, it is possible that I may have missed something. Please send any erroneous examples to me.

The current set of supported operators is +-*/^%.

Absolute cell references are indicated with a preceding dollar sign '$' exactly as in Excel.

NOTE: When copying and pasting cells via the contextual menu, you must use the Smart Copy and Smart Paste options if you want relative cell references to propagate correctly.

Legal Formula Examples:
=1.414
="hello"
=A1
=A1/2
=A1+B1%-C1*D1/E1^F1%
=SUM(A1,B2+2)
=SUM(A1:B2)
=SUM(A1:$B2,C$3,$D$4)
=A1*34%+SUM(B1:C2)%
=AVERAGE(A1:A3)/MAX(B1:B3)
=(A1+2)*$B$1*53.3%
=ROUND(SUM(A1:A3,4.5,PI(),B2,C3),3)
=IF(AND(NOT(A1),B1>5),"yes","no")

If you are absolutely positively certain a formula is legal but you get strange or erroneous results from it, one thing to check is that you have properly set the decimal and formula separator preference setting.

Row/Column Fills

Fills can be performed either down rows or across columns. In either case, a fill must be initiated from the cell that currently contains data which will dictate the fill's behavior, i.e., the cell above or to the left of the first cell that will be filled. It is incorrect usage to initiate a fill from the first cell intended to be filled.

Whether a fill is interpreted as numerical or textual depends on whether the focused cell contains a number. If the fill is numerical, the default increment will be the difference between the focused cell and the cell above it or to its left, and will assume 0 if both the cell above it and to its left are not numbers. You can easily input a different increment if you prefer.

Inserting Timestamps, Barcodes, and Locations

There are menu options for inserting timestamps, barcodes, and locations into cells. The timestamp is always the current system time.

Inserting a barcode uses the external app Barcode Scanner to read the barcode with the camera, so that app must be installed on the Android device (it is freely available on the Market). Product descriptions found for barcodes should perfectly match the first page of results from a Google product search on the barcode.

An inserted location is always the location most recently captured and stored by the system (from the chosen provider: cell network, gps, etc.). Pay close attention to the reported age of the indicated location capture; it may be quite old. In addition, note that gps will appear in the list of available providers even if the gps unit is currently turned off. It must be turned on through the system settings in order to work of course.

Resizing Columns

You will quickly discover that you can scroll through a large table simply by dragging your finger across the screen. However, if you perform a double-tap-drag (tap the screen twice rapidly, but leave your finger down after the second tap; then drag) Shead Spreet's behavior will be to adjust the column widths instead of scrolling the view.

Freezing Row/Column Headers

You can freeze the top row and/or the left column such that when you scroll across the table, that row and column remain visible on the screen (as part of the row/column headers in effect). This is accomplished with the menu option of the same name. Note that you can only freeze row 1 and column A, not any other rows or columns.

Colors

Each cell can be individually formatted from the Format menu. The default colors can be configured in the preferences. The following list describes the system defaults:

Text:
-- Black: nonnumerical text.
-- Blue: literal numbers.
-- Green: valid formulas and their evaluated numerical value.s
-- Orange: Parsable formulas that contain function names unknown to Shead Spreet.
-- Magenta: parsable formulas in a cycle.
-- Purple: Formulas that contain functions which have received an invalid number of arguments.
-- Red: nonparsable formulas or parsable formulas whose row/column range exceed the table size.

Cell background:
-- White: default (will always be white when importing an Excel file, regardless of this setting).
-- Gray: cursor focus.
-- Dim Yellow: a cell whose formula range includes the focused cell.
-- Bright Yellow: a self-cycling formula that is currently focused.

Cell border:
-- Thin black: default.
-- Thick green: range boundary of the focused cell's formula.

Zooming

There are two forms of zooming. The first is the Navigator menu command, which zooms out to enable you to view large areas of the table on a small screen. You can drag to navigate around the table and then press anywhere to zoom back in to resume editting. You cannot edit in the zoomed-out view however. Note that selecting the Navigator menu command twice will zoom out even further.

The second form of zooming is to effectively scale all text sizes in the table proportionally and simultaneously. This can be done in or out. To perform a proportional text size change, focus on any cell and select the Format menu command. Choose the All target option so the change will affect the entire table. Then manipulate the proportional text size selector as you see fit and press the OK button. Note that at the current time, cell-widths are not scaled in a corresponding fashion. I was undecided whether to implement such behavior.

Menu Keyboard Shortcuts

Most menu options have an associated keyboard shortcut. To perform a shortcut, press 'menu' once so the menu opens, then press the corresponding shortcut key. For example, to insert a function, press 'menu', then press 'F'. The shortcuts for the items in the extended more menu are always shown in the menu itself. To see the first five or six shortcuts however, you must press and hold down 'menu' while the menu is open.

Mitigating Memory Errors

Android devices are much weaker than desktop and laptop computers. Not only are they slower, but they have less RAM (less memory). Consequently, large spread sheets may not open at all, or may crash (force close) while you are working with them.

If you experience an out-of-memory error, try any of the following possible solutions, in approximately this order:

-- Download a task manager app (e.g., TasKiller or Task Manager) and kill as many processes as possible.

-- Use the back button to back all the way out of Shead Spreet to the Android home screen. Then run Shead Spreet again from scratch.

-- Reboot the phone.

-- Increase the minimum column width preference.

-- Decrease the maximum column width preference.

-- If you import an Excel file but get a memory error while using the table, try this: Import the file again, but first immediately exit to the table list, ending the session, purging the fragmented memory that resulted from accessing the complex Excel file format, and converting the table to a much tighter native Shead Spreet file. Then reopen the table from the native file for future use.

However, bear in mind that the suggestions listed above might not work for you, i.e., that your table might ultimately be too large for a pocket computer to process.

Speed and Performance

Some operations may take quite a while to perform on large tables. The most serious offenders are those operations which require many cells to be updated at once, i.e., operations which change the number of rows or columns or which require loading the table back into memory.

When a slow operation occurs, the Android OS may present you with a dialog after a few seconds saying that Shead Spreet is not responding and asking whether you would like to force close or wait. If you simply choose to wait, you will frequently discover that Shead Spreet will eventually complete the operation in question without trouble.

Occasionally, when opening the Preferences or Plot views, you will receive a warning that predicts a requisite delay while the table is safely backed up. Note that your Android device may go to sleep before the Preferences or Plot views appear, in which case you will have to wake it up with the power button.

Face it, processing large spread sheets is a tough task to ask of a pocket-sized computer.

Hints 'n Tricks

The 'enter' key jumps down a row, adding a new row if necessary.

The 'tab' key jumps right a column, adding a column if necessary. Note that on the G1, the 'tab' key requires two key presses, 'alt' and 'Q' (you can either press and release 'alt', then press 'Q', or you can hold 'alt' down while pressing 'Q', either way works). Note that the soft-keyboard (the on-screen keyboard) has no 'tab' key.

'Shift'-'enter' jumps up a row (you must hold 'shift' down while pressing 'enter', at least on a G1).

'Shift'-'tab' jumps left a column. You must press 'alt' before pressing 'shift' and 'tab' (releasing 'alt' before proceeding is easier than trying to hold it down with the next two keys), and you must hold 'shift' down while pressing 'tab'.

Notice the pop-up contextual menu (long press on a cell, i.e., press and hold down on a cell or the trackball). This menu lets you copy/cut/paste. This menu also lets you copy and paste entire rows and columns and will propagate relative cell references properly.

Many menu options have keyboard shortcuts. Master them and you will become much more efficient. See the Menu Keyboard Shortcuts section for more information.

The screen is small; make best use of it by hiding the status bar and/or the title bar and by reducing column widths as much as possible.

If you are working with a large table, learn to use the navigator (menu option). Note that invoking the navigator twice zooms out even further.

If you are using a soft-keyboard (on-screen keyboard) preformat cells to 'number/currency' so they will default to the numerical soft-keyboard instead of the alphabetic soft-keyboard.

Always save tables by pressing the back button to return to the table-list, as opposed to pressing the home or power buttons. All these methods should work, but there is potential for serious problems when applied to large tables that take a while to save (Consider the implications of pressing 'home', then reentering Shead Spreet and attempting to read the same table before the previous process finishes writing it!).

Don't perform orientation flips while reading or writing a file. I can't even begin to explain the complexity involved in such scenarios.

Future Work

I attempted to interface Shead Spreet with Google Docs at one point but never finished it. That would be pretty nifty.

There are various online and cloud-based systems, like DropBox, that would be nice to work with.

Extended character support could use a lot of work.

Beta Testing

Beta testing is a pre-release development phase during which a developer gives a copy of a program to a small group of users who help the developer find bugs before the wide-spread public release. If you are a paid user and would like to become a beta tester, please contact me. I will add you to a mailing list of beta-testers to be notified when I have a new version ready for beta-testing. I will show you how to install the beta-version directly off my website (not through the Market), and let you use the application for a short period before the public release.

By volunteering to be a beta-tester, you agree to the following terms:

-- You will not give the beta-version to anyone else.
-- You will back up all of your data before installing the beta-version by copying the entire /sdcard/SheadSpreet_files/ directory to another location on the phone, or better yet, to your computer.
-- You will be patient and pleasant when you encounter bugs and will go to the small trouble of reporting them to me.
-- You will entertain a few back-and-forth emails to help me clarify and characterize the bug as best as possible.
-- You will agree to send me the error log file that Shead Spreet generates when it encounters problems.

In turn, I will agree to the following terms:

-- I will never abuse the beta-tester mailing list for any form of spam. I will only contact you when I have a new version ready for beta-testing (usually about a week before I intend a public release).
-- I will remove you from the beta-tester mailing list anytime you ask.
-- When asking you to help clarify and characterize a bug, I will attempt to bother you as little as possible and keep such communication to a minimum.

Thank you very much for considering the glorious beta-tester lifestyle, with its many sports-car and super-model associated benefits.

Plea for Donations

This is a large and complex program. The end product represents hundreds of hours of labor and the Google Market provides no means to charge or pay for upgrades, which means users who purchase an early version for a low price get all future upgrades -- and all their associated functionality -- for free.

If, after using Shead Spreet for a while, you decide that it usefulness is worth more to you than you initially spent, I would greatly appreciate a small additional donation of your choosing ($1 to $3 would be fine) as compensation for all my hard work.

The easiest way to donate is by PayPal to kwiley@cs.unm.edu for donations under $12 (which is much more than I'm asking for). If you feel you absolutely must make a larger donation, please PayPal to kwiley@keithwiley.com instead, for which I am charged a lower PayPal fee on payments over $12.

If you prefer snail mail for donations, please email me for a mailing address.

Thank you for your consideration on this matter.

Contact

Keith Wiley

kwiley@keithwiley.com

http://keithwiley.com

[an error occurred while processing this directive]