MiscTableScroll
By Paul S. McCarthy and Eric Sunshine
Copyright (C) 1995,1996,1997,1998,1999 by Paul S. McCarthy and Eric Sunshine
August 20, 1999
OVERVIEW
========
This is the source code for the MiscTableScroll framework and palette for
MacOS/X Server and OPENSTEP. MiscTableScroll is similar to Apple's
NSTableView class, and is accessible from both Objective-C and Java. This
version of MiscTableScroll is compatible with MacOS/X Server for Mach and
Windows, OPENSTEP 4.2 for Mach and Windows, as well as OPENSTEP 4.1 for Mach.
*WARNING* Users of previous releases of MiscTableScroll should read the
"Release Notes" section in this document. It details changes in this version
which are incompatible with previous releases.
User Interface Highlights
-------------------------
- Column and row titles.
- Resizing of columns and rows.
- Dragging rows and columns to rearrange them.
- Automatic sorting of rows as columns are rearranged.
- A button in column titles to toggle between ascending and descending sort
direction.
- Incremental search.
- In-cell text editing.
- Exporting contents as ASCII, ASCII-delimited or dBASE through the Save Panel.
- Full keyboard and mouse control.
- Interacts with the Pasteboard, Font Panel, and Services.
Programmatic Highlights
-----------------------
- Accessible from Objective-C and Java.
- Each column and row can have its own size.
- Each cell can have its own color and font or inherit them from the table.
- Each column can have its own cell type.
- Lazy mode for large or expensive-to-generate data sets.
- Full control over selection.
- Smart memory management -- you don't pay for features you don't use.
- Simple indexed access to rows and columns regardless of visual order.
- Uniform treatment of rows and columns -- referred to generically as slots.
- Support for dragging images directly out of cells.
- Extensive delegate hooks and notifications.
INSTALLATION
============
MiscTableScroll is normally distributed with the MiscKit for MacOS/X Server
and OPENSTEP. However, since it does not use nor rely on any other part of
the MiscKit, it can be used as a stand-alone framework and palette.
Consequently, this package can be used to create a stand-alone framework and
palette or to replace an out-of-date copy of MiscTableScroll which was
included with the MiscKit.
Directory organization differs between MacOS/X Server and OPENSTEP, as well as
between Mach and Windows installations. At installation time, environment
variables can be used as an abstraction to overcome these differences. The
process of defining environment variables differs from shell to shell. If you
are using the C-shell then you can define an environment variable, for
instance MISC_DEV, by typing:
% setenv MISC_DEV "example"
If you are using the Bourne shell then you can define an environment variable
by typing:
$ MISC_DEV="example"
$ export MISC_DEV
All of the instructions below assume that the environment variables MISC_LIB
and MISC_DEV have been defined. MISC_LIB is the directory which contains the
standard library resources such as frameworks and documentation. MISC_DEV is
the standard development directory which contains source code, Interface
Builder palettes, and example programs.
On MacOS/X Server for Mach, and YellowBox for Windows, these variables should
be defined as follows:
Variable Mach Windows
-------- ---- -------
MISC_LIB /Local/Library ${NEXT_ROOT}/Local/Library
MISC_DEV /Local/Developer ${NEXT_ROOT}/Local/Developer
For OPENSTEP for Mach and Windows, they should be defined as:
Variable Mach Windows
-------- ---- -------
MISC_LIB /LocalLibrary ${NEXT_ROOT}/Local/Library
MISC_DEV /LocalDeveloper ${NEXT_ROOT}/Local/Developer
If these locations are inappropriate for your site, configure them to suit
your needs.
Next, follow these steps to install the MiscTableScroll package:
- Check version numbers
- Remove previous version
- Unpack
- Compile and install framework and palette
- Compile and install Java support
- Compile the example programs (optional)
- Clean up
Check Version Numbers
---------------------
If you have a previous version of MiscTableScroll for MacOS/X Server or
OPENSTEP installed, check the version number of the package which you already
have by looking in the PACKAGE_NUMBER file in the source code directory or
inside either the installed framework or palette. Compare that number with
the version number encoded in the name of the package file
MiscTableScroll.???.?.gnutar.gz. This way you can tell which version is newer
or older, and decide whether to proceed.
Remove Previous Version
-----------------------
If you have a previous version of the MiscTableScroll that you want to replace
with this package, then you need to remove the old version before unpacking
the new version.
If you used the standard MiscKit directory structure then these commands will
remove the previous version. If you used a different directory structure,
then you may need to adjust the commands to match your installation.
# Remove source
% rm -rf ${MISC_DEV}/Source/MiscKit2/Palettes/MiscTableScroll \
${MISC_DEV}/Source/MiscKit2/Examples/JavaScrollDir \
${MISC_DEV}/Source/MiscKit2/Examples/LazyScrollDir \
${MISC_DEV}/Source/MiscKit2/Examples/ScrollDir
# Remove targets
% rm -rf ${MISC_LIB}/Frameworks/MiscTableScroll.framework \
${MISC_DEV}/Palettes/MiscTableScroll.palette \
${MISC_DEV}/Examples/MiscKit2/JavaScrollDir \
${MISC_DEV}/Examples/MiscKit2/LazyScrollDir \
${MISC_DEV}/Examples/MiscKit2/ScrollDir
Unpack
------
Unpack the MiscTableScroll package by choosing a convenient directory for the
source code, such as ${MISC_DEV}/Source, and performing the following
commands:
% mkdir ${MISC_DEV}
% mkdir ${MISC_DEV}/Source
% cd ${MISC_DEV}/Source
% gunzip MiscTableScroll*.gnutar.gz
% gnutar xvf MiscTableScroll*.gnutar
Unpacking the MiscTableScroll package creates the following directory
structure:
MiscKit2
Examples
JavaScrollDir
LazyScrollDir
ScrollDir
Palettes
MiscTableScroll
Framework
Documentation
Java
Notes
Palette
Compile and Install Framework and Palette
-----------------------------------------
By default, MiscTableScroll is configured to install its components in the
following locations:
Component Installation Location
--------- ---------------------
MiscTableScroll.framework ${MISC_LIB}/Frameworks
MiscTableScroll.palette ${MISC_DEV}/Palettes
On Windows 95 and NT these additional resources are also installed:
MiscTableScroll.dll ${MISC_LIB}/Executables
MiscTableScrollJava.dll ${MISC_LIB}/Executables
If these locations are inappropriate for your site, you can adjust them using
Project Builder's Inspector panel. The installation directory can be
configured individually for both the framework and the palette.
To build and install the MiscTableScroll framework and palette using Project
Builder, follow these steps:
- Open the project file contained within the top-level MiscTableScroll source
directory: ${MISC_DEV}/Source/MiscKit2/Palettes/MiscTableScroll/PB.project
- Select the install target on the Build Options panel.
- If you wish to build the project for multiple architectures, such as
PowerPC, Intel, Motorola, etc., choose the appropriate options on the Build
Options panel.
- Press the Build button.
If you are using Windows 95 or NT then you must also add the framework's
executable path to your system PATH variable. For instance, with YellowBox,
if ${NEXT_ROOT} at your site is defined as C:/Apple/, then you should add
C:\Apple\Local\Library\Executables to the PATH. For OPENSTEP, with
${NEXT_ROOT} defined as C:/NeXT/, you should add
C:\NeXT\LocalLibrary\Executables to your PATH. Consult the Windows
documentation if you need help setting the PATH environment variable.
Compile and Install Java Support
--------------------------------
As of MacOS/X Server (DR2), MiscTableScroll and its supporting classes are
accessible from Java. OPENSTEP does not provide Java support, so OPENSTEP
users may proceed to the next section. Java support for MiscTableScroll is
discussed in the document MiscTableScroll.rtf.
The MiscTableScroll Java-related resources are installed within the
MiscTableScroll framework. On Windows, an additional file,
MiscTableScrollJava.dll is also installed in ${MISC_LIB}/Executables alongside
MiscTableScroll.dll.
To build and install the MiscTableScroll Java support facilities using Project
Builder, follow these steps:
- Open the project file contained within MiscTableScroll's Java subdirectory:
${MISC_DEV}/Source/MiscKit2/Palettes/MiscTableScroll/Java/PB.project
- Select the install target on the Build Options panel.
- If you wish to build the Java support library for multiple architectures,
such as PowerPC or Intel, choose the appropriate options on the Build
Options panel.
- Press the Build button.
Compile Example Programs (optional)
------------------------
You can build the example programs JavaScrollDir, LazyScrollDir, and ScrollDir
using Project Builder. JavaScrollDir can be built for MacOS/X Server and
YellowBox, but not for OPENSTEP which lacks Java support. To build the
example programs with Project Builder:
- Open the PB.project file contained within the each source directory.
- Choose the appropriate architectures from the Build Options panel.
- Press the Build button.
The project files for the example programs are:
${MISC_DEV}/Source/MiscKit2/Examples/JavaScrollDir/PB.project
${MISC_DEV}/Source/MiscKit2/Examples/LazyScrollDir/PB.project
${MISC_DEV}/Source/MiscKit2/Examples/ScrollDir/PB.project
Finally, if you would like to have the source code for the example programs
available for perusal, you can install them in ${MISC_DEV}/Examples/MiscKit2,
either by copying the directories using the File Viewer or by typing the
following commands:
% cd ${MISC_DEV}
% rm -rf Examples/MiscKit2/JavaScrollDir Examples/MiscKit2/LazyScrollDir \
Examples/MiscKit2/ScrollDir
% mkdir Examples
% mkdir Examples/MiscKit2
% cp -r Source/MiscKit2/Examples/JavaScrollDir \
Source/MiscKit2/Examples/LazyScrollDir Source/MiscKit2/Examples/ScrollDir \
Examples/MiscKit2
Clean Up
--------
At this point the installation is complete. To reclaim disk space, remove the
temporary files which were created during the build process by pressing the
Clean button on Project Builder's Build panel. Or, if you do not plan to
refer back to the source code at all, then you can delete the project
directory entirely:
% rm -rf ${MISC_DEV}/Source/MiscKit2
CONVERSION
==========
This package comes with a "tops" script to assist in the process of porting
NEXTSTEP programs which use MiscTableScroll to MacOS/X Server and OPENSTEP.
The script should be used after running the standard NEXTSTEP to OPENSTEP
conversion scripts which are supplied with OPENSTEP. The MiscTableScroll
conversion script is located within the framework at:
MiscTableScroll.framework/Resources/MiscTableScroll-3.3-4.x.tops
DOCUMENTATION
=============
Documentation for the public classes is located within the framework's
Documentation directory in these files:
- MiscTableScroll.rtf
- MiscTableCell.rtf
- MiscExporter.rtf
A full discussion of the use of MiscTableScroll from Java is included in the
document MiscTableScroll.rtf in the section titled "Java".
The example programs demonstrate how to use the most important features of
MiscTableScroll:
- JavaScrollDir
- LazyScrollDir
- ScrollDir
The following files also provide valuable information. Except for
PACKAGE_NUMBER which is located in the top-level source directory, all of the
remaining files reside in the Notes subdirectory.
PACKAGE_NUMBER MiscTableScroll version.
HISTORY.txt Description of changes between versions.
OPENSTEP-HISTORY.txt Description of MacOS/X & OPENSTEP changes between
versions.
TODO.txt A list of future enhancements.
OPENSTEP-TODO.txt A list of MacOS/X Server & OPENSTEP future
enhancements.
BUGS.txt A list of known bugs.
OPENSTEP-BUGS.txt A list of MacOS/X Server & OPENSTEP related bugs.
JAVA-TODO.txt A list of Java specific future enhancements.
JAVA-BUGS.txt A list of Java specific bugs.
MACH-NT-4.2.txt Description of issues which arose when porting
MiscTableScroll from OPENSTEP 4.1 for Mach to OPENSTEP
4.2 for both Mach and Microsoft Windows.
Finally, the source code itself is commented and may be consulted as needed.
It has been formatted with tab-stops of 8 characters and indentation of 4
spaces.
RELEASE NOTES
=============
The most significant item of note in this release of MiscTableScroll is that
it is now accessible from Java. Extensive documentation detailing use of
MiscTableScroll from Java is included in MiscTableScroll.rtf, and is
demonstrated concretely by the new example program, JavaScrollDir.
To be consistent with other MacOS/X Server and OPENSTEP classes,
MiscTableScroll now sends notifications in places where it used to solely
dispatch certain delegate messages. As with other OPENSTEP classes which have
delegates, MiscTableScroll automatically registers its own delegates to
receive these notifications if the delegates implement the appropriate
messages. Each notification-style delegate message now receives an
NSNotification object as its sole argument. The documentation in
MiscTableScroll.rtf lists the contents of the "userInfo" dictionary for each
notification.
*WARNING* A number of MiscTableScroll methods have been renamed. Most
notably, as a result of the move to notifications, the names of several
delegate messages changed. This is significant because your application may
cease to work correctly, even though it compiles cleanly, since the old
delegate methods are no longer called. The delegate methods which were
renamed are listed in OPENSTEP-HISTORY.txt. As a consequence of this
incompatible change, the framework's version identification has been advanced
from "A" to "B".
The final significant change is the addition of support for "represented
objects", which complements represented object support in NSCell. A
represented object may be associated with the entire table as well as each row
and column.
CONCLUSION
==========
MiscTableScroll was written by Paul S. McCarthy and Eric Sunshine and is
copyright (C) 1995, 1996, 1997, 1998, 1999 by Paul S. McCarthy and Eric
Sunshine. It is included in the MiscKit by permission from the authors and is
governed by the MiscKit license found in the file License.rtf in the MiscKit
distribution.
Please direct comments, questions, and complaints to:
- Paul S. McCarthy
- Eric Sunshine
MIME and ASCII mail accepted.