About 3D Additions Library ========================== Version 1.7 October 24, 1995 ©1994-95 J.Rodden, DD/MF & Associates. All rights reserved. This source code is loosely based on and heavily inspired by source code by James W. Osborne, copyright (c) 1993, Apple Computer. The accompanying source code is released as 'freeware'. And as such you are free to use it in any way that you see fit. The only exception is that you cannot sell for profit, the source on its own. It is ok to use the source in other products which are then sold for profit. 3D Buttons CDEF by Zig Zichterman is public domain. See associated ReadMe files. Description ----------- The classes in this archive provide a simple 3D interface as described in Develop issue 15. Subclasses of LAttachment, LPane, and LEditField are available plus stand-alone drawing routines. Lines, rectangles and ovals are supported, all elements can be drawn either raised or inset and use either a global color scheme or individualized (per routine) colors. 3D Buttons CDEF by Zig Zichterman is also included for drawing push buttons, checkboxes, radio buttons, and icon buttons. (Two radio button styles are provided.) Low level drawing is done by ANSI C routines so C++ and PowerPlant are not needed. Higher level (PP/C++ dependent) routines are fully bit depth smart. The differences between these classes and those in Develop are 1) these use PowerPlant rather than MacApp, and 2) these are much simpler. Most of the functionality is contained in 3DUtilities.cp. It contains the actual drawing routines used by the other files. You can use these on their own, or in concert with the pane and attachment classes in the other two .cp files. There is also a wrapper class for the basic drawing routines which automatically takes care of different bit depths. I've included comments that should help you get started using these classes quickly. Also included is a demo program and corresponding project and source files. Important Notes --------------- *** WARNING: Naming scheme changed for panes (new in V1.4). Default color and resource defined panes had their names swapped. The 3D Buttons CDEF package included is NOT the same as that distributed by Zig Zichterman (though I hope he'll incorporate my changes in his release :) There are TWO radio button styles: that described in Develop 15 with convex/concave buttons, and a circular version of the embedded checkbox. The latter style is very similar (if not the same) as that used on other platforms (Motif, OS/2, Windows), and I simply like it better. See CDEF Notes below for more information. Library summary --------------- 3DGrays.h : Defines 16 shades of gray for using with the drawing routines. 3DUtilities : Actual drawing routines. ANSI C procedures designed to be usable as a stand alone library (it requires 3DGrays.h) with an API style similar to Mac Toolbox managers complete with state and accessor functions. There are four basic types of 3D elements: lines, frames (outlines), borders, and panels. Each type can be rendered to appear raised or inset, rectangular or oval. Panels draw and entire area raised or inset. Frames only draw an outline, but the outline lines are inset or raised. The only difference between borders and panels is whether an outline only is drawn or the area is filled as well. This distinction was made to eliminate excessive screen flashing in some cases. 3DAttachments: Attachment classes for frame, border, and panel 3D interface elements. 3DPanes: Pane subclasses for automatic frame and panel 3D elements. 3DDrawingUtils: Provides a wrapper class for the procedures in 3DUtilities. Handles multiple bit depths automatically. 3DTextFields: Factory classes for creating inset text fields (both editable and captions). LStdCDEFControl:Provides 3D versions of LStdButton, LStdCheckBox, and LStdRadioButton. Uses 3D Buttons CDEF by Zig Zichterman and modified by J.Rodden. There are two pane implementations for each type of 3D element. The differences are in how much programmer control and flexibility there is over color usage and appearance. The first implementation uses the 3DUtilities color settings to determine the colors chosen and makes the most effecient usage of memory. The second implementation allows each instance to have a unique color combination controlled by PPob resources. Both implementations use Constructor templates. You will need to copy the CLSS resource into your project resource file from the demo project resource file or from the 3D Constructor Tmpls file in the 3D Additions folder. *** Make sure to put the 3D Additions folder in your CW directory tree. CDEF Notes ---------- The CDEF has a resource id of 1000. In order to use it from PowerPlant you must change the Control Kind value in Constructor's StdControl window. To determine what value to enter use the equation N * 16 + V where N is the resource id (1000) and V is the variation code as described in Inside Macintosh. The basic variation codes built into the Toolbox work the same (pushButProc(0), checkBoxProc(1), radioButProc(2), & useWFont(8)). An additional variation code (indentHighlighted(4)) is also available and works the same as useWFont--it modifies the control type when ORed with the basic control typecodes. When ORed with pushButProc, the button's title will indented when the button is pressed. When ORed with radioButProc, the radio button will be drawn as an embedded circle instead of the default convex/concave style. Currently, indentHighlighted has no effect when ORed with checkBoxProc, but I'm open to suggestions. (Perhaps a stylized checkmark). Problems and Future Work ------------------------ € Refine B&W "Pseudo-3D" Drawing routines. € Determine why the top radio button in the PPC version of the demo doesn't draw properly. Contact Address --------------- EMail: rodden@cse.ucsc.edu or rodden@alumni.cse.ucsc.edu (not in effect yet) SMail: James Rodden 2071 Robinhood Lane Los Altos, CA 94024 Change History -------------- ???. ?? '96: V1.7.1 Added #pragma unused to ExecuteSelf routines in 3DAttachements.cp Oct. 24 '95: V1.7 Added inspirational copyright credit to James W. Osborne and Apple Computer, Inc. Added setter and getter for resource defined 3D panel color schemes, fixed a bug in constructing resource defined panes' color settings, and changed resource color definitions to read real RGBColors now that Constructor 2.0 supports this. Made all low level routines deal strictly with consts (except getters). Made U3DDrawingUtils routines more C++ like by overloading with call-by-reference versions. Updated for CW7, incl. Constructor 2.0 style custom pane template resources. Dropped PPC-based demo app to speed and simplify releases--not really necessary anyway. Made 3DPanes and 3DStdControls self-registering with URegistrar (PP should adopt this, IMHO). Jul. 9 '95: V1.6 (released on Celestin's Apprentice CD) Fixed compiler type checking errors from CW6. Added text field factory classes. Attempted to implement "Pseudo-3D" drawing routines to get shaded effect in B&W modes. I think I made some other changes/improvements, but frankly I don't remember--school got in the way of documenting them promptly :) Jan. 31 '95: V1.5 Fixed problem when drawing to 4 bit color screens by defaulting to B&W. Made 3D pen state saving class public. Optimized U3DDrawingUtils routines for minimal code bloat while retaining maximum speed. Jan. 19 '95: V1.4 Added oval drawing routines. Added push button, check box, and radio button controls via 3D Buttons CDEF by Zig Zichterman (thanks Zig!). Performance tuning for panes. Normalized class naming scheme. RegisterAll3DClasses routine available for stream (resource) definable classes. Dec. 12 '94: V1.3 Added wrapper class to utility drawing procedures which handles different bit depths. Dec. 11 '94: V1.2 Added device loop to panes and attachments, handles different bit depths correctly. Dec. 3 '94: V1.1 Mixture of resource and programatic control over color usage and appearance. Pane subclasses optimized to use minimal memory and use 3D drawing routines directly to minimize drawing stack usage. 3D drawing routines packaged to mimick Mac Toolbox Manager style API and written to ANSI C. Nov. 30 '94: V1.0 First release. All appearence control from code. Pane subclasses used attachments.