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.