PortaBase 1.9

- A portable database -

1)Introduction
2)File selector
3)Columns editor
4)Enum manager
5)Enum editor
6)Calculation editor
7)Image editor
8)Image viewer
9)View editor
10)Data viewer
11)Row editor
12)Row viewer
13)Note editor/viewer
14)Sorting editor
15)Filter editor
16)CSV import
17)Data export
18)Preferences dialog
19)Command line usage
20)Encryption


1)Introduction
PortaBase is a small database program for creating, browsing, and editing custom tables of data. Typical uses are media inventories, reference charts, TODO lists, shopping lists, etc. Notable features include:
2)File selector
Unless the program was launched by clicking on a PortaBase file, the first screen shown will be the file selector. You may open any listed file by clicking on it (in the Zaurus version), or choose one of the following options from the "File" menu or toolbar:
3)Columns editor
Each PortaBase file contains one table of a user-defined format. The format of this table is determined by a sequence of data columns, each of which has its own name, data type, and default value. When creating a new PortaBase file, this dialog is shown so the data columns can be defined. The columns of an existing file can also be edited at any time using this dialog by selecting the "Edit Columns" item in the "File" menu of the data viewer.

The current column definitions are displayed as rows in a list, in the order in which they appear in the row editor. These column definitions are manipulated using the buttons at the bottom of the dialog:
None of the changes made to the table format are applied until the "OK" button is pressed; if the "X"/"Cancel" button is pressed instead, the changes are discarded and the file format is left as it was. If the "X"/"Cancel" button is pressed while defining the columns of a new file, the file creation is aborted; otherwise, pressing either of the dialog closing buttons takes you to the data viewer.

4)Enum manager
PortaBase supports enum column types, in which each value in the column is one of a set of possible string values. The enum manager dialog lets you create, edit, delete, and change the listing order of these enums.

Most of the dialog is occupied by a list of the currently defined enums. At the bottom is a row of buttons identical to those in the columns editor:
Click "OK" to apply any changes made to the enum listing order or "X"/"Cancel" to leave the sequence unchanged (other than any added or deleted enums).

5)Enum editor
This dialog lets you define the name and list of options for an enum column type. It has a list of the enum's options and the same set of buttons as most of the other editor dialogs:
Just below the enum name are more buttons which allow you to change the list of options:
Click "OK" to accept any changes that were made or "X"/"Cancel" to leave the options unchanged (or cancel adding a new enum).

6)Calculation editor
This dialog allows you to define columns which contain values calculated from the values of other columns in the same row. It is launched by pressing the "Edit calculation" button in the column editor, which appears only for columns of type "Calculation". At the top of the dialog are the name of the column, a read-only display of the current calculation written as a one-line expression, and a spin box that allows you to specify how many decimal places should be shown for the calculation results.

Most of the dialog is filled by a widget which shows the current calculation as a tree, similar to many file explorer programs. Each node in the tree represents either the value of another column, a constant value, or the result of an operation. To edit the calculation, select a node from the tree (if any are present) and use the buttons at the bottom of the dialog:
Usually you want to start by adding an operation node, such as "+", and then add its arguments (which may themselves be operations with arguments of their own). The buttons automatically update when a node is selected in order to indicate which actions are possible; typical actions not allowed are:
Some points worth noting:
7)Image editor
An Image column stores pictures imported from JPEG or PNG image files. After you select an image file to import into a field in the database, this dialog is shown so you can make minor changes to the copy of the image that will be saved in the database. The top row contains the following controls:
Note that because memory on the Zaurus is limited, very large pictures will be rejected. JPEG images larger than 6400 x 4800 pixels cannot be imported, and ones larger than 800 x 600 will be shrunk to at most that size. Similarly, PNG images larger than 800 x 600 cannot be imported.

Click "OK" to store the image as it is shown or "X"/"Cancel" to leave the field unchanged.

8)Image viewer
The image viewer is a simple dialog that displays the image contained in one field of an Image column. If launched from the data viewer, the left arrow key shows the image in the same column from the previous row in the current filter; similarly, the right arrow key shows the image from the next row. Double-clicking on the image shows it in full-screen mode; click on the full-screen image again to close the viewer.

9)View editor
Whenever you browse a database's content in the data viewer, you are looking at one "view" of the data. A view is a subset of the columns in the database, displayed in a particular order and with specified display widths. Each database has a default "All Columns" view which shows all the columns in the database in the same order as they appear in the row editor.

Views are defined using the view editor dialog. At the top of the dialog is a text box containing the name of the view; changing this renames the view. Next are droplists allowing you to pick a default sorting and/or filter that will be applied whenever you switch to this view; selecting "None" leaves the current sorting or filter unchanged. (This avoids the need to select a view, then a sorting, then a filter if there are certain combinations of these you use often.) Below those is a table showing the names of all the columns in the database, with a checkbox next to each indicating whether or not it is included in this view. Click this checkbox to include or exclude the column. At the bottom of the dialog are "Up" and "Down" buttons for moving the selected row up or down in the table, changing the order of the columns in the view. Click "OK" to accept the currently shown settings or "X"/"Cancel" to revert to the previous values (or to cancel adding a new view).

10)Data viewer
This is the main screen of the application, where you can browse the database's content and launch most of the other dialogs. The contents of this screen are:
Note that some of the menus may be shown as sub-menus under the File menu, depending on current settings in the Preferences dialog.

Row display and navigation
Most of the data viewer screen is occupied by a table showing one view of a set of rows in the database. The spin box at the bottom left of the screen specifies the maximum number of rows to display at once for the current view; you can edit this to be any positive integer (setting it low enough eliminates the scrollbar on the right of the display table, giving a little more horizontal space). To the right of this "rows per page" box are the page navigation buttons. Click on one of the numbered buttons to go to that page of rows; the current page is shown pressed. Click on the arrow buttons at the ends to show the page buttons for the next or previous five pages.

Clicking on a cell in the data display and holding down for 1/2 second or longer before releasing executes special functions. If you do this on a cell in a Note column, the note viewer is displayed showing the content of that note. When done on a cell in an Image column, the image contained in that cell is shown in the image viewer. If you do it in any other type of column, the row editor for the row you clicked on is launched.

Double-tapping on a row or pressing enter or space while a row is selected launches the row viewer.

Column labels
The row of column labels has several features in addition to informing you of the column names. To change the widths of the columns in the current view, click on the border between two column labels (or the right edge of the last column) and drag it to the desired location. Clicking on a column label sorts all the rows by the content of that column in ascending order; clicking it again sorts in descending order. If you press a column label and hold it for half a second or more before releasing, a dialog containing summary information for that column is displayed; only rows that pass the current filter are included in the summary.

File menu
The "File" menu contains options that apply to the database file as a whole. These are:
Row menu
The "Row" menu contains actions that apply to individual rows of data. These are:
View menu
The "View" menu allows you to select and manage views. The top section of this menu has three options:
Below these items in the menu is a list of all the views defined for the current database, with a check next to the one currently displayed. To switch to a different view, simply select the one you want to see from the menu.

Sort menu
The "Sort" menu allows you to select and manage sorting configurations. The top section of this menu has three options:
Below these items in the menu is a list of all the sortings defined for the current database, with a check next to the one currently in use (if any). To change the way the rows are sorted, simply select the sorting configuration you want to use from the menu. If you just want to sort by a single column that is displayed in the current view, it is probably faster to use the "click on a column label to sort" feature instead.

Filter menu
The "Filter" menu contains options that let you choose which rows of data to display. The top section of this menu has four options:
Below these items in the menu is a list of all the filters defined for the current database, with a check next to the one currently in use (if any). To select a different filter, simply select the one you want to use from the menu.

Toolbar buttons
There is a toolbar of buttons that provide quick access to commonly used operations. These are:
Note that some of the toolbar buttons may not be shown, depending on current settings in the Preferences dialog.

11)Row editor
The row editor is shown whenever a row of data is added or edited. It has one row for each column in the database; on the left is the name of the column, and on the right is its current value. When adding a new row of data, the default values are shown; when editing an existing row of data, the current values are shown. Some comments about editing certain data types:
After editing the values as desired, click "OK" to accept the currently displayed values, or "X"/"Cancel" to cancel the row addition (if adding a row) or leave the current values unchanged (if editing a row).

12)Row viewer
The row viewer is a dialog designed to conveniently see all of the data for one row at a time. Like the row editor, it has the column labels on the left and values on the right. But the values are not editable, and they wrap so you don't have to scroll horizontally to see everything. The complete content of note fields is shown as well, instead of just the first few words. By default, only the columns in the current view are shown (in the view-specified order); to see a different set of columns, select the appropriate view from the droplist at the bottom of the dialog. Pressing the left and right arrows at the bottom of the screen or the left and right directions on the direction pad allows you to navigate between rows in the current view. Pressing the edit button at the bottom of the dialog lets you launch the row editor for the current row; if you click "OK" in the row editor you will be taken back to the data viewer, otherwise you will be returned to the row viewer. Finally, there is a copy button at the bottom of the dialog which copies the currently selected text (if any) to the clipboard.

13)Note editor/viewer
The "Note" column type is for blocks of text which may contain multiple lines (as opposed to the "String" type, which is better suited for relatively short single lines of text). The larger size of the content of such columns merits its own (very simple) dialog. Both in the row editor and in the default value section of the column editor, a Note value is shown as a button containing a note icon and the beginning of the Note's content (as much as will fit). To see and/or change the full text, press this button; a full-screen text editor dialog will appear, showing the current text of the Note. Click "OK" to accept any changes you have made or "X"/"Cancel" to revert to the original content.

Note columns are treated a little specially in the data viewer also. The column label for Note columns contains a note icon indicating that it is not just a String column. The cells in the column each show as much of the Note content as will fit. If you press on one of these cells and hold for half a second or longer before releasing, a read-only version of the Note editor is shown. Click either "OK" or "X"/"Cancel" to dismiss it and return to the data viewer.

14)Sorting editor
Clicking on a column label in the data viewer is a convenient way to sort the database contents by a single column. But sometimes you may want to sort by a combination of columns; sort by the content of column A, within groups of the same value of A sort by the content of column B, etc. To do this or to sort by a column that isn't shown in the current view, you need to define a named sorting.

Sortings are defined using the sorting editor dialog, which is very similar to the view editor dialog. At the top of the dialog is a text box containing the name of the sorting; changing this renames the sorting. Below that is a table showing the names of all the columns in the database, with a checkbox next to each indicating whether or not it is to be sorted. Click this checkbox to add or remove the column from the set of ones to be sorted. The third column in the table shows either "Ascending" or "Descending" for checked rows, indicating which direction to sort in; click this indicator to change it to the opposite value. At the bottom of the dialog are "Up" and "Down" buttons for moving the selected row up or down in the table, changing the sequence in which the columns are sorted. The rows are sorted by the topmost checked column first, rows with the same value in that column are sorted by the next highest checked column, etc. Click "OK" to accept the currently shown settings or "X"/"Cancel" to revert to the previous values (or to cancel adding a new sorting).

15)Filter editor
This dialog allows you to define filters which are used to select which rows to display in the data viewer. A filter may be as simple as "count = 1" or something more complicated like "any text column contains 'java', chapters > 10, pages <= 400, and instock is checked". When you choose a filter from the "Filter" menu, the data viewer is updated to show only the rows which match the conditions you have defined.

At the top of the dialog is a text box containing the name of the filter; changing this renames the filter. Below that is a list of the conditions which make up the filter; a row must satisfy all of these conditions in order to pass the filter. "Add", "Edit", "Delete", "Up", and "Down" buttons let you edit the condition list in basically the same way as the columns editor works. But instead of the column editor dialog, a condition editor dialog is launched by the "Add" and "Edit" buttons. This dialog lets you choose the column whose value to compare, the comparison operation to use, and the constant value to compare against. For text comparisons, there is also a checkbox that lets you indicate whether the comparison should be case sensitive or not. Instead of a single column, you can choose to compare the value of "Any text column"; if the value of any String or Note column in a row satisfies such a condition, the row is considered to pass the condition. Click "OK" to accept the currently shown settings or "X"/"Cancel" to revert to the previous values (or to cancel adding a new filter).

16)CSV import
PortaBase can import rows of data from CSV (Comma-Separated Value) files. This allows you to import data exported from a spreadsheet or another database program. To do this:
  1. Open the PortaBase file you want to import the data into. If you wish to import the data into a new file, create a new file and define a column structure that matches that of the data to be imported.
  2. From the "File" menu in the data viewer, select "Import". A file selector will appear showing all the CSV files that are available; pick the one you want to import from. The CSV file must have the same number of columns as the open database file, and the values in those columns must be appropriate for the specified column types. You may specify the encoding of the text file in order to import non-ASCII characters correctly; the default is UTF-8 (which supports text in many languages), but you may also choose Latin-1 (which is used by most software configured for use primarily with Western European languages).
  3. The rows in the imported file are added to the database. Rows from other files can be added by repeating this process, or another copy of the same rows can be added by importing the same file again.
Notes:
  1. Boolean fields must have a value of either 0 or 1
  2. Date fields may be formated as YYYYMMDD, YYYY/MM/DD, YYYY-MM-DD, or YYYY.MM.DD
  3. Time fields may be formated as HH:MM:SS, HH:MM:SS AM, HH:MM, HH:MM AM, or the number of seconds past midnight. Blank or -1 values are interpreted as "None".
  4. Calculation fields may be left as 0 or whatever; the actual values will be calculated during import.
  5. Image fields should contain either nothing (for no image loaded) or the relative or absolute path to a suitable image file.
17)Data export
PortaBase currently supports export to two formats: CSV and XML. The inverse of data import, this allows you to move database content into a spreadsheet, text editor, other database program, etc. for further manipulation. To export the current database's contents:
  1. Select "Export" from the "File" menu in the data viewer.
  2. Choose the format you want to export to from the droplist. If you export to CSV, only the rows passing the current filter will be exported. If you export to XML, the entire database structure (including column definitions, views, filters, etc.) will be exported; note that the result may be over twice the size of the actual data file, so make sure you have enough free storage space.
  3. Enter the name of the CSV or XML file you wish to create.
  4. Click "OK" to complete the export, or the "X"/"Cancel" button to cancel the operation.
18)Preferences dialog
This dialog allows you to set your preferences for the PortaBase application. Click "OK" to accept the current preferences on all tabs, or the "X"/"Cancel" button to leave them unchanged. The tabs are:
Options
The "General" section of the Options tab contains the following options:
In the PC versions of PortaBase, there is also a "Date and Time" section on the Options tab. On the Zaurus, PortaBase uses the system date and time settings; but since there is not a good cross-platform way to retrieve this information from desktop PCs, the following must be specified here:
Appearance
In the "Font" section of the Appearance tab you can pick any font that is available for use, in any size it is available in. That font will then be used for all text in PortaBase (even after exiting the application and restarting it) until you pick a different one. You may pick, for example "unifont, 16" in order to display Japanese characters, or "smallsmooth, 9" in order to fit more text on the screen.

The "Row Colors" section contains two buttons which allow you to choose the colors which will be used for the backgrounds of rows in the data viewer, columns editor, view editor, and sorting editor. Each button shows one of the current colors; clicking on one launches a color selection dialog in which you can pick a different color to use.

Menus
This tab lets you control which menus are shown, and in which order; this is particularly important on some Zaurus models which may not have enough space on the screen to show all of the menus. A list of menus is shown; the ones which are checked will be shown as top-level menus, while those which are not checked will be shown as sub-menus under the "File" menu. At the bottom of the dialog are "Up" and "Down" buttons for moving the selected menu up or down in the list, changing the order in which the menus are shown.

Buttons
This tab lets you control which toolbar buttons are shown, and in which order; as with the menus tab, this is especially useful on low-resolution Zaurus models. A list of buttons is shown; only the ones which are checked will be shown in the toolbar. At the bottom of the dialog are "Up" and "Down" buttons for moving the selected button up or down in the list, changing the order in which the buttons are shown.

19)Command line usage
PortaBase can be used from a Linux/Zaurus terminal or DOS prompt to import or export data without needing to go through the graphical interface. This can be particularly useful if you want to write scripts that automatically generate, update, or otherwise manipulate PortaBase data files. Run "portabase -h" for usage instructions; in summary, you can do the following:
To extract data from, add rows to, or create an encrypted file, type -p password immediately after the conversion command (before the other options described below).

The following options can be used between "toxml" or "tocsv" and the PortaBase file to export from:
For more information about the PortaBase XML format and tools for doing useful things with it (like converting to HTML), see the PortaBase homepage (http://portabase.sourceforge.net).

20)Encryption
PortaBase data files can be encrypted in order to protect sensitive information like passwords. Each encrypted file is accessed by providing a password specified by the file's creator. (This password can be changed later from the File menu's "Change Password" action.) Because this password must be relatively easy to remember, this is the weakest point in the encryption scheme; therefore, it is important to choose a good password. Passwords should meet the following guidelines:

For security and implementation reasons, the entire content of encrypted files must be held in memory at once; thus encrypted files cannot scale to large sizes as well as non-encrypted files. Files of a few hundred or a few thousand rows should still perform well, but files containing many thousands of rows of data probably won't (at least on the Zaurus; desktop computers with lots of memory can handle quite large encrypted files).

For more information about encryption in PortaBase (including details on the algorithms used), see the PortaBase homepage (http://portabase.sourceforge.net).

----
Copyright 2002-2004 by Jeremy Bowman.
(jmbowman at alum dot mit dot edu)