# JCards Help

### Nick Sydenham

Copyright `<nsydenham@yahoo.co.uk>`

## Introduction

### What is JCards?

JCards is an application that acts as a simple repository for user-defined data. It can be used for storing any structured data but some examples are contacts, passwords, lists, to-do, etc. It is generic enough to act as a general purpose storage tool and can therefore replace numerous other tools which would otherwise require the user to install and learn how to use several other applications.

### What platforms does it run on?

JCards was written in Java so will run on any platform with a Java Virtual Machine (JVM) such as Linux, Sun, Mac, Windows, etc.

JCards is available in two versions. Version 5 (original) was designed to work as well on PDAs as it does on desktops. To do this the feature set is limited so that it works using a simple version of Java based on the J2ME Personal Profile. Version 6 is a complete rewrite using Java 6 and the Swing GUI toolkit to enable more features and a modern desktop application.

Version 6 can read and write all previous database versions. Version 5 can only read version 5 and previous database versions.

### How does it work?

The user first defines one or more fields to define the database structure. So for example, to create a music database you may define the fields, Artist, Album, Year, Date released, etc. To enter data the user creates one or more Cards, where a Card represents one record in the database. So in the music database example you'd have one Card for Pink Floyd's Dark Side of the Moon album, another Card for U2's Greatest Hits and so on.

### How many cards can I enter?

As many as you like. The only limitation is the memory in your computer.

### Getting started

There are a number of ways to get started with JCards as follows:

1. Enter fields manually as described below.

2. Select the See an example JCards database item from the Help / Welcome screen

3. Download and open an example database from the JCards website.

4. Read the tutorial to guide you through creating a database and entering data.

## Fields

### Creating fields

You can either select the DB / Fields... menu option or click the button on the toolbar. Then click the button to add a new field.

### Field types

The field type can be chosen from the drop-down list and defines the type of data allowed to be entered into the field by the user.

Field Type | Description | Example
--- | --- | ---
Boolean | True or false | Y
Calculated | A numeric field whose value comes from a calculation involving other numeric fields | 23.45
Category | Choose from a user-defined list | Option 1
Counter | An incrementing field | 34
Date | Date or time or both | 15/10/2005 12:43
Image | Display an image |
Memo | Any number of lines of text |
    A multi-line
    text string
Number | A number (subtypes - integer, double, percentage, currency) | 123, 123.23, 123%, £123
String | A single line of text | A text string

#### Boolean

A boolean field can be used for storing simple Yes / No, True / False values.

#### Calculated

Calculated fields get their values by evaluating a user entered formula. The formula can use numbers, operators (+, -, /, *, ^), field names and mathematical functions defined by the `java.lang.Math` Java class. More information on the Math functions can be found within the Java Documentation. Note that field names must be quoted (e.g. 'field') to separate them from mathematical functions and that the calculation is case sensitive. Also, referenced fields must be of one of the following types: Number, Counter or Calculated.

The edit card dialog has an update button on it, but this is only so users can see the results of any changes made. When the user clicks OK all calculated fields are updated anyway.

Formulas are defined using postfix notation in the default text field on the edit field dialog. The table below shows some examples:

Standard notation | Postfix notation
--- | ---
5 * tan(67) | 5 67 tan *
5 * (3 + 2) | 5 3 2 + *
5 * 'Unit Price' | 5 'Unit Price' *

The mathematical functions available are:

Function | Args | Description
--- | --- | ---
abs | 1 | Returns the absolute value of a double value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.
acos | 1 | Returns the arc cosine of an angle, in the range of 0.0 through pi.
asin | 1 | Returns the arc sine of an angle, in the range of -pi/2 through pi/2.
atan | 1 | Returns the arc tangent of an angle, in the range of -pi/2 through pi/2.
atan2 | 2 | Converts rectangular coordinates (x,y) to polar (r,theta). This method computes the phase theta by computing an arc tangent of y/x in the range of -pi to pi.
ceil | 1 | Returns the smallest (closest to negative infinity) double value that is not less than the argument and is equal to a mathematical integer.
cos | 1 | Returns the trigonometric cosine of an angle.
exp | 1 | Returns Euler's number e raised to the power of a double value.
floor | 1 | Returns the largest (closest to positive infinity) double value that is not greater than the argument and is equal to a mathematical integer.
IEEEremainder | 2 | Computes the remainder operation on two arguments as prescribed by the IEEE 754 standard.
log | 1 | Returns the natural logarithm (base e) of a double value.
max | 2 | Returns the greater of two values.
min | 2 | Returns the smaller of two values.
pow | 2 | Returns a value of the first argument raised to the power of the second argument.
random | 0 | Returns a double value with a positive sign, greater than or equal to 0.0 and less than 1.0. Returned values are chosen pseudorandomly with (approximately) uniform distribution from that range.
round | 1 | Returns the closest long to the argument.
sin | 1 | Returns the trigonometric sine of an angle.
sqrt | 1 | Returns the correctly rounded positive square root.
tan | 1 | Returns the trigonometric tangent of an angle.
toDegrees | 1 | Converts an angle measured in radians to an approximately equivalent angle measured in degrees.
toRadians | 1 | Converts an angle measured in degrees to an approximately equivalent angle measured in radians.

The Args column shows how many numbers must be passed to the function.

Mathematical constants supported

- PI - The double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter.
- E - The double value that is closer than any other to e, the base of the natural logarithms.

#### Category

Categories are fields that can be thought of as either a quick way of repeatedly selecting a value from the same set or limiting the valid set of values. For example, an address book might have a type category which is limited to Work or Home.

Once categories are created you can filter the cards being shown in the main list by selecting one from the View menu.

To use a category, first create it on the Category tab and then assign a field's type as Category. The category can then be selected from the category list.

#### Counter

Counters are fields which increment every time you create a new card. The initial value and increment can be negative if required. An example usage may be where you want every new Card to have a new ID, i.e. 1, 2, 3, etc.

Note that clicking the OK button on the edit counter dialog will not update the counter settings. Only the update button does this.

#### Date

Date fields can have different date formats associated with them, e.g. dd/MM/yyyy. This is different behaviour than version 5 when the date format was common to all date fields in the database.

When date fields are being edited their content must match the format specified.

#### Memo

Memo fields are used for entering multiple lines of text. If the Display as HTML checkbox is set in the field definition the text will be rendered as HTML when viewed.

The size (number of lines) of memo fields is set on an individual basis. Edit the field definition to change it.

#### Number

Number fields are by default integers. In the fields dialog you can change the formatting of the field to double, percentage or currency. When editing a Card the number is displayed and editied as a double with the percentage or currency symbol only displayed when viewing a Card in view mode or in the table.

When entering values into numeric fields set to percentage or currency the user shouldn't enter anything other than numbers or related indicators such as decimal point (.), operand (E) or negative (-).

#### Image

An image field allows you to display an image that resides on your local file system. Alternatively, you can select to store the image in the JCards database. This increases the size of the database but does allow you to carry around images as well.

Automatic resizing is available if you are importing large images. This doesn't change the image, just the view size.

#### String

String fields are used for displaying a single line of text. If however, the text begins with http:// or ftp:// the text can be clicked on and the URL will be displayed in your web browser. This applies to both Card's when viewed and the table view.

### Change field type

You can change an existing field's type to String or Memo which will convert any existing values into strings. This cannot be undone once you press the OK button except by reloading the database (if you haven't saved it first).

Note that if a Memo field is converted to the String type any newlines will be converted to spaces.

### Add new fields

New fields can be defined as and when required with existing Cards having these fields set to a null value. If you define a new field and then make it the first field the table will display a blank line for any existing records.

### Edit a field

Open the DB dialog and select the field you want to edit on the Fields tab.

You can change a field's name and whether it is mandatory or not. Fields can also be deleted and its position relative to other fields can be altered.

### Delete a field

Open the DB Dialog and select the field you want to delete and click the Delete button.

### Default values

A field can have a default value defined but this must correlate to the field's type. So for example a Number field can have a default of `1` or `1.1` but not `abc`.

When you create a new Card the default is automatically populated, but can be overridden if required.

If specifying a default for a boolean field the permissible values for true are: Y, true, 1. The permissible values for false are: N, false, 0. New in 5.0 - you can specify the first letter of Yes or No in your language as long as there is support included for your particular language.

### Field restrictions

- The first field defined in the database is always mandatory. This ensures that something is visible in the table for every Card.

- A boolean entry cannot be the first entry.

- You can only select a Category field type if you have previously defined one or more categories.

- You can only select a Counter field type if you have previously defined one or more counters.

- Categories and counters cannot be deleted if in use by a field.

- You can only select a Calculated field type if there is already one or more numeric fields defined.

- Calculated fields can only operate on other numeric fields.

## Cards

Cards are the individual records in your database and are represnted as rows in the table.

### Adding new cards

To add a new card to the database click the button. Only when you click the OK button is any data saved and the main table updated.

### Delete a card

To delete a card select it in the main list and click the button or select the Edit / Delete card menu item.

### Undelete a card

The last deleted Card can be recovered from the Edit / Card / Undelete menu option. This option is only available during the current session; i.e. won't be remembered following a stop and restart.

### Edit a card

Cards can either be edited in-line in the table by double clicking the relevant field or the entire Card can be opened in a separate window. To open the Card in a separate window select it in the table and either:

- click the icon
- Ctrl left click on the Card
- middle click on the Card
- right click on the Card and select Edit
- type Ctrl-e

### Copy a card

Copying a card creates a new card and fills in the values from the currently selected card in the table. Either select the Edit / Copy card menu item or right click on a Card and select Copy card

### Find a card

To find a particular card you can either click the search icon , type Ctrl-F or select Edit / Find. You can either search in all fields or limit the search to one field. Once a search has completed the results will be displayed in the table. This subset can then be further searched if required (Find within results checkbox). If the table is displaying search results the toolbar will display an indicator in the status bar to show how many Cards are being displayed.

Select the Match case checkbox to only match values with the same case (e.g. upper or lower).

Select the Whole words to match either an entire value or words within a value.

Select the Edit / Reset Find menu item, type Ctrl-R or click the statusbar indicator to display all cards.

### Find/replace

To do a global find/replace select Edit / Replace or type Ctrl-H. This has the same options as the find option but allows you to replace any found text with a replacement. Note that this only works on text fields to prevent 'breaking' any of the formatted values such as dates.

## Table View

The table view provides a summary of the cards in your database. It can be configured to display whichever columns (fields) the user requires although one column will always be displayed. Once added, a column can be moved by right-clicking on a column's table header and selecting an option from the pop-up menu.

Most table cells are editable but some aren't due to their type. Calculated, Counter and Memo field type cells cannot be edited in-line.

### Visible fields

Click the button in the top right corner of the table to select the fields shown in the table.

### Column Resizing

Columns can be resized manually using the mouse. However, the column resize policy (set using the button) will affect how other colums behave when the selected column is resized.

### Sorting

Sorting can be set by clicking on a column header, after which an arrow will be displayed in the column header to indicate an ascending sort order. Clicking on the same column header will sort in descending order. Clicking the same column header a third time will remove the sorting criteria.

### Searching

As well as searching using the search box, you can click anywhere on the table and start typing letters to automatically look for the closest match. Once a match is found, hitting the Enter key will repeat the search from the current location.

## Other Fucntions

### Statistics

Statistics can be shown for either the database as a whole or for a particular field. Either can be selected from the DB menu.

### Encryption

You can optionally set a password which will encrypt your data using the Blowfish encryption algorithm. Note that if you forget your password you cannot retrieve your data. The padlock symbol on the statusbar indicates if the current database is encrypted or not. Clicking the icon will allow you to set or unset the password and is equivalent to selecting the File / Set password... menu item.

The password digest algorithm used is SHA-256.

### Import/export

Data can be read into and written out of JCards using comma-separated values (CSV) files. The import/export is flexible enough to allow the user to specify what field and text delimiters they want to use and whether they want multi-line fields to be concatenated.

- CSV files which contain the field names as the first line can be used to automatically define the database fields by selecting the Header row option. All fields are defined as String type although they can later be changed to the Memo type if required.

- If you have already defined the fields and the CSV file has the field names defined on the first line then still select the Header row to indicate that the first line of the CSV file should be ignored.

- Data can be imported/exported to/from standard ASCII format or any other supported character set.

- If the number of defined database fields doesn't match with the number of fields being imported the import will probably fail silently.

Other options for export include XML and XHTML. You can also export categories separately.

### Opening remote databases

If you have a database that you want to access from multiple locations and don't want to carry it around with you, you can upload the JCards database to a web server and then access it using the File / Open URL... menu item. You can read and make changes to the database as normal, but updates will not be written back to the JCards file on the web server.

### Preferences

Preferences are split across three tabs. The Global tab displays application specific preferences while the Database tab displays database specific preferences. The Icons tab allows you to customise the icons shown on the toolbar.

#### Global preferences

- Save confirm - If selected a dialog box will confirm file saves. This is just feedback and replicates the status bar message.

- Load last file - If selected, when the application starts it will automatically load the last viewed database.

- Auto edit card - When opening a card, if this option is selected the user can immediately start editing the card. If turned off, the user views the card first. This has the advantage of filtering out fields with no data.

- Word wrap - Long memo fields are wrapped.

- Table editing - Enable/disable in-table editing of values

- Use system web browser - Use the operating system specified default web browser.

- Web Browser - Location of web browser for displaying help, link to home page, etc.

- Font - set the base font that JCards uses.

#### Database preferences

- Show field labels - Show field labels when viewing cards.

- Add colon - A colon is added to the end of field names as a separator, e.g. Name: .

#### Icons

Allows the user to select which icons to dispay in the toolbar.

### Saving databases

By default, new databases will be saved using the JCards v6 database format to take advantage of all available field types. If a version 5 or below database is opened it will by default be saved as a version 5 database. This means that any of the new field types, if added, will be automatically converted to a version 5 comparable field type such as a String. This can be explicitly overridden by selecting the JCards Files (*.jca) file filter in the Save As dialog.

### JCA file format

The data format for saved data is a zip file containing a database definition and the data. Both entries are stored in one XML file (Card Data) so can be read in a text editor unless it has been encrypted.

The separate Header file contains the following information: creation and modification time, file version, encryption.

If encrypted, the data will be encrypted using the Blowfish algorithm and can only be recovered by entering the password.