README for 3magic Coffee Table
Version 2.1.3 - Release october 1, 1999.
©1996-1999 3magic, All Rights Reserved Worldwide.
ABOUT THIS FILE
This readme provides important supplementary information on installing and using 3magic Coffee Table. Please read
this file before reporting any problems.
This readme contains the following sections:
* About this version
* Installation Notes
* Documentation
* About the Sample Applet
* About the PrintSample Application
* Known Problems
* Copyright
* Limited Warranty
* Limitation of Liability
ABOUT THIS VERSION
What's new in version 2.1.3:
* We used to be known as Argent Software of Cupertino, California. We have changed our name and are now known as 3magic. Argent Coffee Table has also been renamed, and is now called 3magic Coffee Table.
* Product names and packaging changed to reflect corporate name change from Argent Software to 3magic.
* The GridPrinter class, which is a utility class to enable printing of reports using the Grid data under JDK 1.1, has been broken up into a GridPrinterBase and it's subclass, GridPrinter. Additionally, a new sub-class GridPrintable (in the JDK_1.2_Printing directory) is provided for JDK 1.2 printing support. This class extends the GridPrinterBase class to implement the Printable interface.
What's new in version 2.1.2:
* JDK 1.2/Java 2 compatiblity. Fixed a rendering bug while scrolling under JDK 1.2.
* Added a new JDK 1.2 (Java 2)/JFC 1.1 version using the new JFC 1.1 package name scheme. This new version is enclosed in the file Argent_JFC_1.1.jar in the directory For_JFC1.1.
* Added support for cell attributes as well as individual col and row header attributes. Added new methods setCellAttributes(), setColHeaderAttributes, setRowHeaderAttributes. Attributes are additive where a cell's attributes is computed using the grid, col, row and finally cell attributes in that order. You can share a single GridAttributes object between cells, rows, or columns to prevent multiple object instances. This helps in reducing the amount of instantiated objects. Previous versions would always clone the passed in Attributes object for each column or row, now we just store a reference to it, cloning is your responsiblity if you want it.
* Added new feature flag SORT_ROW_HEADERS (enabled by default) that moves the row header data with the rows while sorting. Aded new accessor methods setSortRowHeaders() and isSortRowHeaders().
* Added support for drawing images in cells. Added new cell type - IMAGE, and a new method drawCellImage() to draw the cell image. It is your responsiblity to load the image and call setCellData() with the Image.
* Added keyboard based selection using the shift key to extend selections.
* Maintenance update to fix a slowdown bug introduced in Version 2.1.1B.
What's new in version 2.1.1A:
* Maintenance update to fix problems with the latest version of Microsoft's JVM, and Symantec Cafe 3.0.
What's new in version 2.1.1:
* Added new methods setApplet() and getApplet() to associate an applet with the component. This is used by the GridPanel when it needs to obtain the AppletContext to display a URL or mailer in the browser. You need to set this only if the component is to be used in an applet and there are any cells with the URL or MAIL cell type attribute.
* Added a new method goToURL(String urlStr) whose default implementation creates a URL from the passed in String and then displays the URL by calling
getApplet().getAppletContext().showDocument(theURL, "_blank");
This method can be overridden to change how the URL is created or displayed.
What's new in version 2.1:
* Added support to specify minimum column widths for column resizing.
* Added support to activate editing with a single-click. The default behavior is still to activate editing with a double-click. There are new methods setSingleClickEditing() and isSingleClickEditing().
* Added new lightweight JFC based version - JGridPanel. Similar API as AWT based GridPanel. Please refer API documentation for details.
* Fixed bugs and some minor optimizations.
* Moved some static routines like drawJustString(), getNumLines() etc. to the GridUtils class.
* The JFC version doesn't support the setThreeDBorder() method. It uses a Border to achieve this functionality.
What's new in version 2.0.6:
* Added new feature flag AUTO_RESIZE_ROWS to automatically resize row heights based on word wrapping if WORD_WRAP is enabled forany of the cells in a row. Also added new methods:
setAutoResizeRows()
isAutoResizeRows()
autoResizeRow()
autoResizeRows()
* Added new feature flag AUTO_RESIZE_COLS to proportionally resize columns to always fit within the GridPanel area. Once this feature is enabled columns will always resize to fit whenever the GridPanel's width changes. In addition, when the user resizes any column, other columns may be resized to compensate for the change. The column resize mode can be used to specify how the other columns may be resize. Added the following new methods:
setAutoResizeColumns()
isAutoresizeColumns()
setColResizeMode()
getColresizeMode()
recalcColumnWidths()
* Added a new GridPrinter helper class to assist in printing Grid data in a report style format. Once you instantiate a GridPrinter object, associating a GridPanel and PrintJob with it, you can use the print() method to print a report. You can specify various settings to control printed output. The GridPrinter class can also be overridden to customize it's imaging routines. You may notice problems with printing under JDK 1.1.4 or older. It is recommended that you use JDK 1.1.5 or better since that version fixes a host of Printing releated bugs in teh AWT.
NOTE: Symantec Visual Cafe 2.1 or older ships with the earlier versions of the JDK (1.1.4 and 1.1.3). These VMs have known problems with printing.
* Fixed various miscellaneous bugs.
What's new in version 2.0.5:
* Added new cell type "CHOICE" that lets the user edit a cell using a choice list. To use feature, the Attribute's cell type should be set to CHOICE and the items for the Choice list should be specified by calling the setItems() method. When the user double-clicks in cells of the above type, a Choice list will be display letting the user pick his selection from the list of items. The selected item text will be set as the cell data for that cell.
* Added new feature method setResizeMultiple(). Setting this flag causes row or column resizing to affect all selected rows or columns (spreadsheet like behavior). This flag is turned on as the default.
* Added support for row tags and methods getRowTag()/setRowTag(). Any Object reference can be stored as a tag for each row in the grid. The row tags will be maintained even after rows move around after a sort.
* Fixed a bug where trying to print the GridPanel would cause the system to lock up under certain circumstances.
What's new in version 2.0.2:
* This version is implemented as a Java Bean and distributed as a set of class files or a .jar file which can be
installed as a component in Symantec Visual Cafe 2.0 or other Java Bean design environments.
* Clicking on a sorted column will sort in the opposite direction. In addition new versions of the setSortColumn()
and sortRows() methosd have been added to contain an extra parameter - sortOrder.
* Added a new method setVisibleCells() to set the Grid's size based on the specified number of rows and columns.
* Added new method getEditor() to replace getEditTextArea().
* Added new method createEditor() that is used to create and return an Editor component for editable cells.
* Added method getSelBounds() that returns the GridPanels current selection.
* Added support for cell validation. Now, when cell editing is committed, the validate() method is called to validate
the text. If validation succeeds, the text changes are committed, otherwise editing is not committed.
In addition, the endEdit() method has been modified to return a boolean value to specify whether or not the
endEdit operation succeeded. If you override endEdit() you will need to modify your code.
* Preformance and memory enhancements to support larger grids.
What's new in version 2.0:
* Version 2.0 is functionally equivalent to version 1.2, but is based on JDK 1.1 It supports the new event delegation
model and provides a slightly different GridEvent class and additional GridListener and GridAdapter class.
* Added new GridEvent event types:
CELLS_RELEASED
START_EDIT
COMMIT_EDIT
CANCEL_EDIT
RESIZE_ROW
RESIZE_COL
SORT_COL
SEL_CHANGED
* Added new flag SORT_ATTRIBUTES to move row attributes and row sizes with rows while sorting. Setting this flag
uses a new sortRows method in GridPanel. If this flag is not set then the default sortRows in the GridData class
is used.
* createGridData() is called automatically when you create a Grid so you don't need to call it explicitly. If you
do't need a GridData object associated with your grid, you may want to call setGridData(null) after you create
the Grid.
* Added new methods to insert/delete rows and columns from the grid. These methods also update the GridData if
present, and adjust the attributes, height/widths of of rows/columns being moved due to the insert or delete. The
new methods related to these changes are:
insertCol()
insertCols()
insertRow()
insertRows()
deleteCol()
deleteCols()
deleteRow()
deleteRows()
* Also added new methods to the GridData object to support inserting and deleting of rows and columns:
insertCols()
insertRows()
deleteCols()
deleteRows()
* Added support to specify a URL or MAIL text with a description and URL text in the form "Argent Software
Web Site<http://www.argent.com>". The description text will be displayed in the cell, and the URL text
within the "<" and ">" will be handled when the user clicks in the cell.
* Added new constructor to GridData object to allow for not allocating any storage for row and column headers.
This instance of the GridData could be used as a utility class to provide storage for a selection of cells.
* Added new methods get/setGridData in GridPanel and GridData. This lets you set the cell data to be any arbitrary
class. The getCellText method returns the string representation of the Object instances by calling the toString()
method.
* Added a new Interface class "Comparable". IF you create objects that implement this interface and it's
compareTo method, you can use the Objects for cell data, and the GridData's compare method will call the Objects'
compareTo method if appropriate. You can use this to sany non-textual data in the Grid.
* Added a new method setPreferredSize(). If you set the GridPanel's preferredSize specified in Pixels, it will
return that size when the getPreferredSize() method is called. You may use this to change the Grid's default preferred
size of 2 columns and 3 rows.
* Added support to allow the user to resize row/column headers. There are a couple of new flags RESIZE_ROW_HEADERS
and RESIZE_COL_HEADERS and new methods setResizeRowHeaders() and setResizeColHeaders().
* Removed flag EDIT_CELLS. Now you only need to set the attributes type in the grid, row or column attributes to
EDIT_TEXT to enable editing.
* Removed flag SORT_ENABLE. Now you only need to call sortEnable() method for the appropriate columns and it will
enable sorting. In addition there is a new method setSortEnable() with 1 boolean parameter which will set/unset
sorting for all the columns. Sorting is disabled as a default and sorting will have to be set for any news columns
is desired.
* Added new flag ROW_NUMBERS to automatically number rows in the row headers if row headers are displayed (rowHeaderWidth
is greater 0). Also added method setRowNumbers() to set this flag.
* Added support to paint the background of sorted columns using a different background color. Added new methods
get/setSortedColumnColor().
* Added new methods setGridJustification() and setHeaderJustification().
* Added new method revealCell() to scroll a cell into view.
* Modified drawing of headers to have a better 3D appearance.
* Added new methods setVScrollAmount() and getVScrollAmount(). You can use this setting to modify vertical scrolling
to scroll by a fixed amount rather than row heights.
* Added new methods getSelectedCols(), getSelectedRows() and getSelectedCells(). These methods return a Vector
containing the currently selected columns, row or cells.
* While editing a cell, hitting the return or enter key accepts your changes and ends editing, while hitting the
Escape key cancels your changes for that cell.
* Various bug fixes and optimizations added.
* Modified the Sample applet Sample.java to provide a better illustration of using the GridPanel API.
Editing
=================================================================
To activate editing, you need to specify the cellType attribute as EDIT_TEXT wherever applicable. When, you double-click
in any cell with the EDIT_TEXT type, the startEdit() method will be called, and editing will be activated. If you
then click in any other cell, scroll, hit Return, Enter or Esc, the endEdit method will be called and editing will
be deactivated, and your changes will be canceled or committed (by calling the SetCellText method) depending on
whether or not you hit the ESC key.
Sorting
To activate sorting, you need to call the setSortEnable() method. This will enable sorting for all the columns.
You can individually enable/disable sorting for a column by calling setSortEnable(int). The default sorting algorithm
uses shellsort and compares the data by calling the compare() method on the string representation of the data.
This can be overridden to customize sorting. Column selection is disabled if you enable sorting.
URL and MAIL support
Any cells designated as URL or MAIL will be drawn with an underline. Clicking on the cell will cause the handleURLClick()
or handleMailClick() method to be called, whose default behavior will call the AppletContext.showDocument() method
with the appropriate URL. The cell data can contain the desired URL in the form "http://www.3magic.com"
or "mailto:info@3magic.com". Additionally, you can also use "3magic's Web Site<http://www.3magic.com>"
as the URL cell data. In this case, the text "3magic's Web Site" will be displayed in the cell, but
the URL "http://www.3magic.com" will be used.
INSTALLATION NOTES
The class files are provided in the Argent directory. In addition, a JAR archive file "Argent.jar" is
also provided. You can install either one of these into your CLASSPATH or your project folder.
If you are using any IDE such as Symantec Visual Cafe 2.0 you can install Coffee Table as a component in it's component
palette. If you have any problems in Visual Cafe after installing Coffee Table as a component, you might try deleting
*.rps, *.reg and *.vws from \VisualCafeXXX\bin directory.
DOCUMENTATION
The GridPanel documentation is provided in the Docs folder and consists of Java AWT style html documentation.
In-addition, online documentation is available at the Argent Web site at the URL http://www.argent.com/products/coffeetable/Docs/index.html
ABOUT THE SAMPLE APPLET
Sample is an applet that demonstrates a very simple use of the GridPanel component. This applet instantiates a
GridPanel, sets it up. It then reads a tab-delimited text file specified as a parameter, parses it and sets the
grid data.
Sample.html embeds a version of the Applet that displays the text file "urls.txt"
ABOUT THE PRINTSAMPLE APPLICATION
PrintSample is an application that demonstrates some of the printing capabilities of the GridPrinter helper class.
KNOWN PROBLEMS
The Scrollbar class behaves differently in all the Win32 implementations of the VM (version 1.1.3). These problems
are not present in JDK version 1.1.2 or version 1.1.4.
Printing works best under JDK 1.1.5 or better. There are known bugs with Printing under older versions of the VM.
There are clipping problems when printing the GridPanel component under MRJ 2.0.
COPYRIGHT
All intellectual property rights in the Software and user documentation are owned by 3magic and are protected
by United States copyright laws and other applicable copyright laws. 3magic retains all rights not expressly granted.
LIMITED WARRANTY
3magic warrants that the Software will substantially conform to the applicable user documentation. Except as
specifically provided herein, 3magic makes no warranty or representation, either express or implied, with respect
to the Software or user documentation, including their quality, performance, merchantability or fitness for a particular
purpose. The warranty and remedies set forth herein are exclusive and in lieu of all others, oral or written, express
or implied.
LIMITATION OF LIABILITY
Because software is inherently complex and may not be completely free of errors, you are advised to verify your
work and to make backup copies. In no event will 3magic be liable for direct, indirect, special, incidental cover
or consequential damages arising out of the use of or inability to use the Software or user documentation, even
if advised of the possibility of such damages. In no case shall 3magic's liability exceed the amount paid by you
for the Software. To the extent that applicable law does not allow the exclusion or limitation of implied warranties
or limitation of liability for incidental or consequential damages, the above limitation or exclusion may not apply
to you.
Please report all bugs, comments and feature requests to support@3magic.com.