README for 3magic Coffee Table
Version 1.2.10 - Release September 15, 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 Sample.java
* Known Problems
* Copyright
* Limited Warranty
* Limitation of Liability
What's new in version 1.2.10:
* Changed package name to Argent.Grid from CoffeeTable.Grid to reflect company name change from Argent Software to 3magic.
* Maintenance update to fix a range checking problem.
What's new in version 1.2.9:
* 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 1.2.8B.
What's new in version 1.2.8B:
* Maintenance update to fix problems with the JDK 1.2/Java 2 VM.
What's new in version 1.2.8A:
* Maintenance update to fix problems with the latest version of Microsoft's JVM.
What's new in version 1.2.8:
* 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 1.2.7:
* Added a new feature flag AUTO_RESIZE_COLS and a method setAutoResizeCols() to automatically resize the columns to proportionally fit within the GridPanel's visible area.
* Added a new method setColResizeMode() to control how the Grid resizes other columns when AUTO_RESIZE_COLS is enabled.
What's new in version 1.2.6:
* Added new methods autoResizeRows() and autoResizeRow() to support resizing row heights based on cell text and the cell width when WORD_WRAP is enabled for those cells. Also added feature flag AUTO_RESIZE_ROWS and method setAutoResizeRows() to automatically resize rows when needed.
* Bug fixes for X Windows environments.
What's new in version 1.2.5:
* Bug fixes to support IE 4.0 and Netscape 3.0 under Windows 95 .
What's new in version 1.2.4:
* 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.
* Other bug fixes and workarounds for IE 4.0 and Netscape's 1.1 VM.
What's new in version 1.2.2:
* 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.
* Changed the behavior of setPreferredSize() to be the same as in version 1.2 i.e. set the size in pixels. 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 getEditTextField().
* Added new method createEditor() that is used to create and return an Editor component for editable cells.
What's new in version 1.2.1:
* Modified the GridPanel's preferredSize() and minimumSize() methods to return the GridPanel's actual size as in other Java components. Depending on the layout manager used, the GridPanel's size w or reshape() methods.
In addition, the setPreferredSize() method has been modified to resize the grid to the specified number of rows and columns.
* 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.
* Preformance and memory enhancements to support larger grids.
What's new in version 1.2:
* 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 don'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 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 class files are provided in the CoffeeTable directory. In addition, a ZIP archive file "CoffeeTable.zip" 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 you might have to set set it's CLASSPATH options so it can locate the CoffeeTable Classes or CoffeeTable.zip file.
Additional documentation for Symantec Visual Cafe integration can be found at:
http://www.3magic.com/products/coffeetable/Docs/VCInstall.html
http://www.3magic.com/products/coffeetable/Docs/VCInstallMac.html
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 3magic Web site at the URL http://www.3magic.com/products/coffeetable/Docs/index.html
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"
The Scrollbar class behaves differently in all the Win32 implementations of the AWT (Netscape, Internet Explorer, Cafe etc). We have tried our best to work around these problems in our implementation and will continue to provide updates as and when available. The real fix will be when Sun reimplements the AWT for Win32, which is promised for the end of the year.
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.