MiscTableScroll

By Paul S. McCarthy and Eric Sunshine
Copyright (C) 1995,1996,1997,1998,1999 by Paul S. McCarthy and Eric Sunshine
June 27, 1999


OVERVIEW
========
This is the source code for the NEXTSTEP 3.x MiscTableScroll palette.
MiscTableScroll is similar to NeXT's DBTableView and NXTableView classes.

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
-----------------------
- 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.


INSTALLATION
============
MiscTableScroll is normally distributed with the MiscKit for NextStep.
However, since it does not use nor rely on any other part of the MiscKit, it
can be used as a stand-alone palette.  Consequently, this package can be used
to create a stand-alone palette or to replace an out-of-date copy of
MiscTableScroll which was included with the MiscKit.

Follow these steps to install the MiscTableScroll package:

- Check version numbers
- Remove previous version
- Unpack
- Compile and install palette
- Compile the example programs (optional)
- Clean up


Check Version Numbers
---------------------
If you have a previous version of MiscTableScroll installed, check the version
number of the MiscTableScroll palette that you already have by looking in the
PACKAGE_NUMBER file in the source code directory or inside the palette itself.
Compare that number with the version number encoded in the name of the package
file MiscTableScroll.???.s.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 /LocalDeveloper/Source/MiscKit/Palettes/MiscTableScroll \
    /LocalDeveloper/Source/MiscKit/Documentation/Classes/MiscTableScroll.rtf \
    /LocalDeveloper/Source/MiscKit/Documentation/Classes/MiscTableCell.rtf \
    /LocalDeveloper/Source/MiscKit/Documentation/Classes/MiscExporter.rtf \
    /LocalDeveloper/Source/MiscKit/Documentation/Classes/MiscIntList.rtf \
    /LocalDeveloper/Source/MiscKit/Examples/LazyScrollDir \
    /LocalDeveloper/Source/MiscKit/Examples/ScrollDir

# Remove targets
% rm -rf /LocalDeveloper/Palettes/MiscTableScroll.palette \
    /LocalDeveloper/Libraries/libMiscTableScroll.a \
    /LocalDeveloper/Headers/misckit/MiscTableTypes.h \
    /LocalDeveloper/Headers/misckit/MiscTableScroll.h \
    /LocalDeveloper/Headers/misckit/MiscTableCell.h \
    /LocalDeveloper/Headers/misckit/MiscExporter.h \
    /LocalDeveloper/Headers/misckit/MiscIntList.h \
    /LocalDeveloper/Documentation/MiscKit/Classes/MiscTableScroll.rtf \
    /LocalDeveloper/Documentation/MiscKit/Classes/MiscTableCell.rtf \
    /LocalDeveloper/Documentation/MiscKit/Classes/MiscExporter.rtf \
    /LocalDeveloper/Documentation/MiscKit/Classes/MiscIntList.rtf \
    /LocalDeveloper/Examples/MiscKit/LazyScrollDir \
    /LocalDeveloper/Examples/MiscKit/ScrollDir


Unpack
------
Unpack the MiscTableScroll package by choosing a convenient directory for the
source code, such as /LocalDeveloper/Source, and performing the following
commands:

% mkdirs /LocalDeveloper/Source
% cd /LocalDeveloper/Source
% gnutar xvfz MiscTableScroll.???.s.gnutar.gz

Unpacking the MiscTableScroll package creates the following directory
structure:

MiscKit
    Documentation
        Classes
    Examples
        LazyScrollDir
        ScrollDir
    Palettes
        MiscTableScroll


Compile and Install Palette
---------------------------
By default, MiscTableScroll is configured to install its components in the
following locations:

    Component                 Installation Location
    ---------                 ---------------------
    MiscTableScroll.palette   /LocalDeveloper/Palettes
    libMiscTableScroll.a      /LocalDeveloper/Libraries
    Headers (*.h)             /LocalDeveloper/Headers/misckit
    Documentation (*.rtf)     /LocalDeveloper/Documentation/MiscKit

If these locations are inappropriate for your site, you can adjust them by
editing MiscTableScroll/Makefile.preamble.

The following make targets are defined in MiscTableScroll/Makefile.postamble:

    install           Installs MiscTableScroll.palette.
    install_lib       Installs libMiscTableScroll.a.
    install_headers   Installs the public headers.
    install_docs      Installs the documentation.
    install_all       All of the above.

You can build and install MiscTableScroll either from the command-line or via
Project Builder.  To build from the command-line, type:

% cd /LocalDeveloper/Source/MiscKit/Palettes/MiscTableScroll
% make TARGET_ARCHS="m68k i386 sparc hppa" install_all

To use Project Builder, follow these steps:

- Open the PB.project file contained within the MiscTableScroll source
  directory.
- If you wish to build the project for multiple architectures (Intel, Sparc,
  Motorola, etc.), choose the appropriate architectures from the Options panel.
- Pick "Add..." from the Target pop-up control and add a target named
  "install_all".
- Press the Build button.


Compile Example Programs (optional)
------------------------
You can build the example programs LazyScrollDir and ScrollDir either from the
command line or with Project Builder.  If you choose Project Builder then open
the PB.project file from each example, select the appropriate architectures,
and press the Build button.  Otherwise, from the command line type:

% cd /LocalDeveloper/Source/MiscKit/Examples/LazyScrollDir
% make TARGET_ARCHS="m68k i386 sparc hppa"
% cd ../ScrollDir
% make TARGET_ARCHS="m68k i386 sparc hppa"

Finally, if you would like to have the source code for the example programs
available for perusal, you can install them in
/LocalDeveloper/Examples/MiscKit, either by copying the directories using the
Workspace or by typing the following commands:

% cd /LocalDeveloper
% rm -rf Examples/MiscKit/LazyScrollDir Examples/MiscKit/ScrollDir
% mkdirs Examples/MiscKit
% cp -r Source/MiscKit/Examples/LazyScrollDir \
    Source/MiscKit/Examples/ScrollDir Examples/MiscKit


Clean Up
--------
At this point the installation is complete.  To reclaim disk space, remove the
temporary files which were created during the build process:

% cd /LocalDeveloper/Source/MiscKit/Palettes/MiscTableScroll
% make clean

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 /LocalDeveloper/Source/MiscKit


DOCUMENTATION
=============
Documentation for the public classes can be found in the files:

- MiscTableScroll.rtf
- MiscTableCell.rtf
- MiscExporter.rtf
- MiscIntList.rtf

The example programs demonstrate how to use the most important features of
MiscTableScroll:

- LazyScrollDir
- ScrollDir

The following files in the source directory also provide valuable information:

PACKAGE_NUMBER  MiscTableScroll version.
HISTORY.txt     Description of changes between different versions.
TODO.txt        A list of future enhancements.
BUGS.txt        A list of known bugs.

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.


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 <zarnuk@zarnuk.com>
- Eric Sunshine <sunshine@sunshineco.com>

MIME and ASCII mail accepted.
