The DataVision User Interface
Windows
The Report Design Window
The Report Design window is the main window used to edit, save, and run
a report. To the left are section labels, to the right are the sections
containing report fields. The labels, sections, and fields all have popup
menus that appear when you right-click them.
Drag the bars to re-size report sections.
To select a field, single-click it. To select more than one field, hold
down the shift key while selecting the fields. Not yet
implemented: You may also select fields by clicking and dragging a
selection box with the mouse.
Click and drag a field to move it. Drag the edges to re-size it. Moving
and dragging operate on the current selection. If multiple fields are
selected they will all be moved or re-sized.
Field commands (format, re-size) operate on the set of currently
selected fields.
To insert a new section, right-click on a section label or section and
select ``Insert Section''.
Menus
Fields have popup menus. Sections have popup menus. The section labels
on the left side have popup menus.
The File Menu
New Creates a new, empty report and opens the Database Connection
dialog box (see The Database Connection
Dialog).
Open Opens a dialog box that lets you select a report XML file to
open.
Save Saves the report. If you have not yet specified a report XML
file because this is a new report, you will be asked to do so.
Save As... Saves the report to a file you specify.
Page Size This submenu lets you select the report's paper size.
One could argue this belongs in the Report menu,
but print-related menu items usually appear in an application's
File menu.
Close Closes the report and the design window. If the file has
been changed, you will be asked if you want to save the report first.
Quit Closes all reports and quits DataVision. If any file has been
changed, you will be asked about saving it. If you answer ``Cancel'' to any
request (instead of saving or confirming that you don't want to save the
report), DataVision does not quit.
The Edit Menu
Undo Not yet implemented.
Cut Deletes the currently selected fields (same as
Delete Selected Fields).
Copy Not yet implemented.
Paste Not yet implemented.
Delete Selected Fields Deletes the currently selected fields.
Delete Group Deletes the group containing the selected field. If
more than one field is selected, the group containing the first (earliest)
selected field is deleted.
Delete Section Deletes the section containing the selected field.
If more than one field is selected, the section containing the first
(earliest) selected field is deleted.
The Insert Menu
For more information about the Field Picker window, see The Field Picker Window.
Database Field... Opens the Field Picker window and jumps to the
Database Fields section. (In a newly created report, there will be no
database columns in this section yet. Open the ``All Database Fields''
sections by double-clicking it.)
Text The cursor changes to a text-editing cursor. Click on a
report section and begin typing to add a text label.
Formula Field... Opens the Field Picker window and jumps to the
Formula Field section.
Parameter Field... Opens the Field Picker window and jumps to the
Parameter Field section.
Special Field... Opens the Field Picker window and jumps to the
Special Field section.
Running Total Field... Opens the Subtotal dialog on the currently
selected field. If more than one field is selected, uses the first
(earliest) selected field. See The Subtotal
Dialog.
Line Not yet implemented.
Group... Inserts a new group below all the other groups. This
menu item is disabled if there are no fields in the report.
To reorder groups or change a group's sort order, select
Group By... from the Report
menu.
Section Inserts a new section after the one containing the
selected field. If more than one field is selected, the new section is
inserted below the section containing the first (earliest) selected
field.
The Format Menu
Format Field... Opens the Format dialog (see The Format
Dialog).
Border... Opens the Format dialog (see The Format
Dialog) with the border tab displayed.
Position and Size... Opens the Position and Size dialog (see The Position and Size Dialog).
Align Opens the Align submenu. Selecting a menu item aligns all
currently selected fields to the top, bottom, left, or right edge of the
first selected field or snaps all selected fields to the grid.
Size Opens the Size submenu. Selecting a menu item re-sizes all
currently selected fields to the same width, height, or size (both width
and height) of the first selected field.
The Database Menu
Table Linker Opens the Table Linker dialog (see The Visual Table Linker Dialog).
SQL Query Text... Opens a dialog containing the SQL query that
will be used to run the report. This text is not editable. It is, however,
selectable: you can copy the text and paste it anywhere else.
Connection... Opens the Database Connection dialog (see The Database Connection Dialog).
The Report Menu
Run Runs the report and displays the results.
Export... Opens a dialog that lets you choose which format to use
for exporting the report data. When you click OK, a
File Save dialog box opens to let you specify an output file.
Select Records... Opens a dialog that lets you edit text inserted
into the WHERE clause of the SQL statement used to generate report data.
See The ``Select Records'' Dialog.
Sort By... Opens the dialog box used to specify which fields should
be sorted, and in what order. See The ``Sort
By'' Dialog. To change the sort order of a group, use the
Group By... menu item.
Group By... Opens the dialog box used to specify how records should
be grouped, and in what order. See The
``Group By'' Dialog.
Summary... Lets you specify the report's author, name, title, and
description. See The ``Summary''
Dialog.
The Help Menu
Help Opens a window on the DataVision User's Manual. The manual
is displayed as HTML and the links really work.
About DataVision... Opens a dialog that displays the DataVision
version number and other exciting information.
The Field Picker Window
When you select one of the field types from the
Insert menu on the design window, this window opens. It
contains a tree list containing all database field types except text
labels. Click and drag a field to add it to the report.
The first item in the window is ``Database Fields'' and the last item is
``All Database Fields''. In a newly created report, the first ``Database
Fields'' item will be empty, because it displays database columns that are
already in the report.
Drag database columns, formulas, parameters, user columns, or special
fields from the Field Picker window into the report. As an added bonus,
when you drag a database column into a ``Detail'' section, the name of the
column will automagically appear in the ``Page Header'' section.
This window also lets you create and edit formulas and parameters.
Select the appropriate menu item from the Field
menu.
The Report View
When you run a report by selecting Run
Report... from the Report menu, a report
view window opens and displays the report output.
From this window you may print the report or export it using one of the
other layout engines.
See Running a Report for more
information on the Report View window.
Dialogs
The Subtotal Dialog
Open by selecting Subtotals... from a numeric
field's popup menu or by selecting Running Total
Field... from the Insert menu.
This dialog will open. It contains check boxes for each group in the
report, along with a ``Grand Total'' check box. Select groups and ``Grand
Total'' to make (sub)totals appear.
The Grand Total will be created in the Report Footer section of the
report.
The Format Dialog
The Format Dialog has two tabs labeled ``Format'' and ``Border''. The
contents of the ``Format'' tab edit the look of a field (its size, font,
alignment, etc.) The contents of the ``Border'' tab edit the borders that
surround a field. These borders are not yet displayed by the GUI,
though they are output by layout engines such as the LaTeX engine that
understand them.
The title of the Format Dialog displays the name of the field whose format
you are editing. If more than one field is selected, a plus sign (``+'')
appears after the field name and that field is the prototype. Its format
will be used to populate the Format Dialog.
The ``Format'' tab lets you edit a fields font family name, text size,
color, text attributes such as bold, italic, underline, and wrap, text
alignment, and the printing format of numbers and dates.
Though field colors respect their alpha component, there is no way
in this dialog to edit that value. You can manually edit the alpha value by
editing the report XML file and changing the final value of the color
string. See Field Formats
for the format of the color string.
The ``Format'' string needs a bit of explaining. It is used by a Java
formatting object that is appropriate for the type of field. For numeric
fields, this string is used as input to a DecimalFormat object. For date
fields, it is used as input to a SimpleDateFormat object.
For numeric fields, you create a ``picture'' of how you want the number to
appear. Use either `#' or `0' characters to represent numbers; `#' will
print blanks if no digit is needed, `0' will print a zero. Add commas or
decimal points where appropriate. The number of `#' characters you use is
not important. To print negative numbers by using a leading minus sign (or
whatever is appropriate for your locale), you need do nothing. To print
negative numbers by using parenthesis, you need to add the string ``;(#)''
to the end of your format string.
For a complete and detailed discussion of the numeric format strings,
see the java.text.DecimalFormat
documentation.
Here are a few example numeric format strings, using the separator
characters used in the USA. We will apply each to the number
1,234.0078.
- #,####
- Print with commas but with no decimal places:
``1,234''
- ####
- Print with no commas and no decimal places:
``1234''.
- ####.#
- Print with no commas and one decimal place:
``1234''. No decimal places are printed here because we asked
for one decimal place only if it is non-zero.
- #,###.00
- Print with commas and exactly two decimal places:
``1,234.01''.
- $#,###.00
- Print as money: ``$1,234.01''.
- $#,###.00;(#)
- Print as money, but use parenthesis if the
amount is negative: ``$1,234.01''.
For date fields, you create a format string that is understandable by
the SimpleDateFormat class. Briefly, use `y' for year, `M'
for month, `d' for day, `E' for day of the week, and `h', `m', and `s' for
hours, minutes, and seconds. Use 'yyyy' for four-character years and 'yy'
for two-character years. For a complete and detailed discussion of the date
format strings, see the java.text.SimpleDateFormat
documentation.
Here are a few example date format strings, using the date/time August
27, 2002, 12:36 PM.
- yyyy.MM.dd
- 2002.08.27
- EEE, MMM d, ''yy
- Tue, August 27, '02
- h:mm a
- 12:36 PM
- hh 'o''clock' a, zzzz
- 12 o'clock PM, Eastern Standard
Time
- yyyyy.MMMMM.dd GGG hh:mm aaa
- 2002.August.27 AD 12:36
PM
The ``Border'' tab lets you edit the border surrounding a field. You can
specify top, bottom, left, and right borders. Each is defined by a count
(zero, one, two, or three lines), a style (line, dashed, or dotted), and a
thickness in points. Remember: not all layout engines support borders.
Only the line style works.
The Position and Size Dialog
To be written.
The Database Connection Dialog
This dialog lets you edit the information needed to connect to the
database: the driver class name, connection info string, database (schema)
name, user name, and password. For information about each field in this
dialog, see Connecting to the
Database.
The Visual Table Linker Dialog
Use this dialog to create or edit links (joins) between tables. The top
of the window displays a list of joins or links between table columns.
New reports start with no joins between any columns. When you first open
this dialog, the area above the Add and
Delete Selected buttons will be empty.
To add a new link, click the Add button.
To delete links, select them with the check boxes on the left side of the
window and then click Delete Selected.
Each row above the Add and Delete
Selected buttons represents one link between two database
fields. To the left and right are combo boxes (drop down menus) that let
you select database fields. In the middle is a combo box that defines the
relationship between the two fields (for example, ``equals'' or ``greater
than'').
To further limit the records retrieved by a report, enter a SQL where
clause by using the ``Select Records'' dialog (see The ``Select Records'' Dialog).
The Parameter Editor Dialogs
To be written.
The Formula Editor Dialog
The main text pane in this window lets you edit the text of a formula. You
can drag database fields, formulas, parameters, user columns, and special
fields into this window.
To open a formula editor, double-click on a formula field in the report.
Within the Field Picker window, select a formula then select
Edit Formula... from the
Field menu.
For a description of the simple formula language, see Ruby.
The Suppression Proc Dialog
A suppression proc determines if a section should be displayed or not. See
Section Suppression
Procs for details.
The suppression proc dialog is a formula dialog with one difference: a
checkbox at the top labeled ``Always Hide''. When this checkbox is
selected, the section will always be hidden. When the checkbox is not
selected, the formula determines the visibility of the section.
The formula may be empty. If it is (and ``Always Hide'' is not selected),
the section is always displayed.
The Startup Script Dialog
The startup script is a formula. This dialog is the same as the Formula Editor dialog.
The startup script is run at the beginning of each report run. Here, you
can set Ruby variables that are available to all of the rest of your
formulas.
The ``Select Records'' Dialog
The main text pane in this window lets you edit text that limits the
selection of records from the data source. You can drag database fields,
formulas, parameters, user columns, and special fields into this window.
If the data source is a database, the text is a SQL where clause. If the
data source is a character-separated file, the text is a Ruby script. For
more information about what can go in the dialog, see Selecting Records.
The ``Sort By'' Dialog
Database columns that are used by groups will not appear in this
dialog.
The ``Group By'' Dialog
To add a group to a report use either this dialog or the
Group... menu item in the
Insert menu.
To add a group using the ``Group By'' dialog, select a database column from
the list on the left. Click the button with the right-pointing arrow
(``>'') to create a new group that uses that column. To remove a group,
select the group from the list on the right. Click the button with the
left-pointing arrow (``<'') to remove the group from the report.
To edit the sort order of a group's values, select the group from the
list on the right side. The Ascending and
Descending radio buttons will become enabled, and
you can change the group's sort order.
To edit the nesting order of a group, select it and click the
Move Up and Move Down
buttons.
The ``Summary'' Dialog
This dialog lets you specify the report's name, its title, the author's
name, and descriptive text. These values may be inserted into a report
using special value fields.
Language Settings
If DataVision has been translated into your language, that language
should be used automatically. The Java runtime sets the default language
and region when you start DataVision. If you don't see the proper
translation, use the command line arguments to set the language and region.
See Running DataVision from the Command
Line for a command synopsis.
Tony Tomov, who translated DataVision into Bulgarian, warns that
Cyrillic characters don't display properly with Java 1.2. Once he upgraded
to Java 1.3, they displayed fine.
See the file Credits for translators' names.