3D Controls in Sys 7 Apps
Volume Number: 13
Issue Number: 6
Column Tag: Look And Feel
Adding 3D Controls to your System 7 App
by Jeff Beeghly
Custom controls can be used to provide Apple's Grayscale
Appearance for System 7 applications
Applications containing 3D controls are becoming the standard in the computer
industry. Users and developers prefer applications which contain a "3D object" look
and feel. For some time now, developers have been implementing their own version of
3D controls. The intent of this article is to demonstrate how to effortlessly transform
an application from the standard 2D appearance into a 3D appearance.
Transforming Dialogs into the 3D World
By following these simple steps, you can transform your dialog boxes and give them a
new "3D look and feel":
1. Add 3D Buttons CDEF.rsrc to your project. This file is in the source code
package which accompanies this article.
2. Change the content color of every dialog box (and alert box) within your
projects' resource from white to gray. If you're using ResEdit, this is
accomplished by opening a DLOG resource, changing the color from Default to
Custom and changing the content color to light gray (Figure 1).
Figure 1. Setting the Content Color to Gray Within ResEdit.
If you're using Resorcerer, this is accomplished by opening a DLOG resource,
selecting the Set Dialog Info... menu item, selecting the Window Color Content
item, then setting each of the RGB values to 56797 (0xDDDD Hex).
Figure 2. Setting the Content Color to Gray Within Resorcerer.
3. Every edit text item within the dialog box must have its background color
set to white. This is accomplished by creating a dialog item list color table
('ictb') resource for each dialog. If you're using ResEdit you will have to
create an 'ictb' resource that has the same ID as the 'DITL' resource you are
working with. ResEdit does not have an 'ictb' editor, so you will have to
assemble one by hand using ResEdit's Hex editor. For more information on the
'ictb' resource and its' format, please consult "The Item Color Table Resource
within Inside Macintosh: Toolbox Essentials, or consult the "NewCDialog" topic
within THINK Reference.
If you're using Resorcerer, you will need to select the edit text item, then
select the Color and Text Styles... menu item (which will bring up the Color
and Text Styles dialog box). Since the default background color is white, the
only thing you need to do here is select the Backcolor checkbox.
Figure 3. Setting the background color of an edit text item within
Resorcerer.
4. Add Update3DDialog.c to your project.
5. In each dialog of your application, there should be a modal dialog filter.
Within each filter, add the function Update3DDialog() to the update switch
(Listing 1) and include Update3DDialog.h within the source code.
Listing 1: ExampleDialogProc
// Add this include
#include "Update3DDialog.h
pascal Boolean ExampleDialogProc(DialogPtr pTheDialog,
EventRecord *pTheEvent, short *pnItem)
{
WindowPtr pWindow;
GrafPtr pOldPort;
short nType;
Handle hItem;
Rect rItem;
switch( pTheEvent->what )
{
case updateEvt:
pWindow = (WindowPtr )pTheEvent->message;
if(pWindow == (WindowPtr )pTheDialog)
{
GetPort(&pOldPort);
SetPort(pTheDialog);
BeginUpdate(pTheDialog);
UpdateDialog(pTheDialog, pTheDialog->visRgn);
DrawDefaultButtonOutline(pTheDialog, OK_ITEM);
hPic = GetPicture(USER_PIC_ID);
GetDItem(pTheDialog, USER_ITEM, &nType,
&hItem, &rItem);
DrawPicture(hPic, &rItem);
// Add this function
Update3DDialog(pTheDialog);
EndUpdate(pTheDialog);
SetPort(pOldPort);
}
break;
.
.
.
6. Recompile and run your application.
What could be simpler?
What's Going on in There?
The CDEF that was added to the project is a modified version of the 3D Buttons CDEF
v1.08 written by Zig Zichterman (located at http://www.best.com/~ziggr/ as well as
many InfoMac and UMICH ftp mirrors). By adding the 3D Buttons CDEF and giving it a
resource ID of 0, the standard system controls (which are contained within the
System's CDEF 0) are replaced with the 3D Buttons CDEF when the application is
launched. The standard push button, radio button, and check box now contain the new
3D appearance (Figure 4). Please note that the standard controls will only be
modified for your application, not system-wide. If you switch to other applications
while your application is running, you will notice that the other applications still
contain the standard system controls they had before.
Figure 4. 3D Push Button, 3D Radio Button, and 3D Check Box.
Our CDEF is also very intelligent; it knows when it should be drawn in 3D and when it
should be drawn in 2D. When the control is drawn, it checks for the following three
conditions:
• Does the machine have color Quickdraw?
• Is the GDevice in which the control will be drawn set to at least 256
colors?
• Does the dialog box have a colored background?
If all three conditions are met, the control is drawn in 3D, otherwise the standard 2D
control is drawn. Using this convention, dialog boxes only appear in 3D when
specifically intended to be that way.
When wouldn't you want dialogs to look 3D? While working on a recent project I
noticed a discrepancy within the StandardPutFile dialog box. Every control contained
the 3D appearance except the New Folder button. This control is not a standard control
and is not overwritten by the added CDEF. In this situation, consistency is more
important than having a 3D appearance, so the dialog was left with it's original 2D
appearance.
Why Not Use the Original 3D Buttons CDEF?
The original 3D Buttons CDEF is modeled after the suggested 3D style guide described
in the article, "Working in the Third Dimension" which appeared in the September
1993 issue of develop (issue 15). Since the publication of this article, Apple has
released a document titled "Apple Grayscale Appearance For System 7.5," located
atftp://ftpdev.info.apple.com/Developer_Services/Technical_Documentation/Human_
Interface/Apple_Grayscale_Appearance.sit.hqx. The new version of the CDEF
incorporates the new Apple Grayscale Appearance guidelines, separates the push
button CDEF from the standard controls CDEF, fixes two bugs that were in the original
1.08 code, and includes several project-wide #ifdefs.
The project was also converted from C++ to C. By converting the source from C++ to
C, I was able to take out redundant code, redundant code paths, and eliminate a lot of
overhead that's inherent with C++. I analyzed the performance of the drawing of the
CDEFs and found that the C version of the push button was 30% faster then the C++
version, and the C version of the icon button was 67% faster then the C++ version. An
added benefit is that the size of the C CDEFs are smaller than the size of the C++
versions. The downside is that the C version isn't as readable as the C++ version. For
more detailed information on the changes that were made, please consult the Read Me
file within the 3D Plug&Play:3D CDEFs f folder.
Example 1
Example 1 is a simple dialog demonstrating a little bit of everything. Each of the three
button styles are represented and the example also displays the buttons in their
disabled state. If you observe the edit text item and the list box item, you will notice
that both items contain a 3D rim (Figure 5). The rim has been added to give the
appearance of depth to each object. The rim is drawn with the Update3DDialog routine,
which parses the DILT of a dialog. The current incarnation of Update3DDialog looks at
each item within the DITL list, and draws the rim if the item is an editText, picItem,
or userItem.
Figure 5. 3D Rim Around a List Box.
Example 2
One of the purposes of this article is to provide developers an effortless (or near
effortless) way to give their dialog boxes a 3D look and feel. To ensure that the
routines would be widely usable and not dependent on my methodology or style, I added
the routines to several different building blocks. I used TransSkel's DialogSkel
example, Metrowerk's CDialogsApp PowerPlant example, a Resorcerer-generated
dialog, and a code snippet called Dim Text.
The easiest example to convert was the TransSkel example which required only the
added files and modifications listed before. The PowerPlant example was very simple
as well, however it is not complete. The PowerPlant example creates windows instead
of dialog boxes and 'DITL' resources, so my Update3DDialog routine was useless in this
case. Rather than write a class that overrides any of the PowerPlant classes (which
has a high chance of conflicting with the other classes), this has been left as an
exercise for the reader.
The Resorcerer example was also easy to convert, except I had to create an unique
version of Update3DDialog (Update3DDialog-Resorcerer.c). Resorcerer uses user
items to display group boxes, and the original update routine draws a 3D rim around
user items. Dim Text was also easy to convert, however, some minor modifications
were required. For more information on the changes made to each of these projects,
please consult the notes file located within each project's folder.
Example 3
Example 3 is an expansion of Example 1. Within Example 3 you may open a 3D or 2D
dialog box. Some users may not prefer to have 3D buttons (or may choose their own
interface with Mac OS 8). Within the Example 3 application is a preferences dialog.
The sole purpose of this dialog box is to change the appearance of the controls from 3D
to 2D and back. This is accomplished by using Get1Resource and SetResInfo to move the
3D CDEF resource out (and back into) the CDEF 0 location, and changing the
background color of DITL and WIND resources. When the CDEF is not in the 0 location,
the standard controls that are built into the System are used instead of our custom
CDEF. This technique allows the user to decide upon the appearance of the application.
This technique also allows the application to be compatible with MacOS 8. As stated
earlier, the application achieves its 3D look by overriding the standard CDEF 0 that is
built into the system. By this same convention, it will probably override any
appearance setting the user has set with the Appearance Manager in MacOS 8. By
providing this mechanism, the user has the ability to use the advance controls with the
current system, and use MacOS 8's customizable controls when it is released.
Example 4
Example 4 demonstrates what you can achieve when you use 3D controls. The example
not only incorporates the 3D controls demonstrated earlier, it also contains an Icon
button, Group Box, and a Plus/Minus (Spindial) CDEF, all of which can be displayed in
3D (Figure 6) or 2D.
Figure 6. 3D Buttons CDEF along with Icon button, Group Box, and Plus/Minus
CDEFs.
In addition to this dialog box, Example 4 also contains dialog boxes which focus on the
different kinds of Group Box, Plus/Minus, and Icon Button variations that are
available. Of special importance is the Icon Button CDEF. Developers are increasingly
incorporating tool pallets within their applications. Within these tool palettes are
usually a large number of icon buttons. The behavior of icon buttons typically act as
push buttons, yet some icon buttons may act as checkboxes (like Microsoft Word's text
alignment buttons) or radio buttons (like Photoshop's Tool palette).
While working on the code for Example 4's Icon Button dialog, I noticed that the icon
buttons that were intended to act as checkboxes or radio buttons produced a flickering
effect. The problem is when the control is selected and the mouse button is released,
the control is sent a redraw message from the system, and the control is drawn in the
off position. The code within the application then changed the value of the control and
displayed the control in a selected position (Figure 7).
Figure 7. Flicker Producing Drawing Process.
To overcome the unwanted flicker, I added code within the CDEF to handle this special
case and I added a new variation number to the Icon Button CDEF. Use variation 3 for a
push button style icon button, and variation 4 for a checkbox or radio button style icon
button. For example, if the ID of the Icon Button CDEF is 1101, the ProcID of a push
button style icon button is 17619 (1101 * 16 + 3 = 17619) and 17620 for a
checkbox or radio button style icon button (1101 * 16 + 4 = 17620).
Conclusion
What has been demonstrated here is just the tip of the iceberg. There is plenty of room
for development of more 3D controls. There is also room for implementing user
interface elements that are controlled by the user. For example, the Preferences dialog
could not only relocate the 3D Buttons CDEF, it could change the background color of
each dialog and alert back and forth between white and gray.
For More Information
If you are interested in developing CDEFs, I'd suggest the following materials:
1. 3D Buttons CDEF, by Zig Zichterman, located on
http://www.best.com/~ziggr/.
2. CDEF Template, by Chris Larson, located on
ftp://mirrors.apple.com/mirrors/info-mac/dev/src/cdef-template-10.hqx.
3. Jim's CDEFs, by Jim Stout, located on
ftp://mirrors.apple.com/mirrors/info-mac/dev/lib/jims-cdefs-15.hqx.
4. A Fragment of Your Imagination, by Joe Zobkiw, Adison-Wesley
5. More Mac Programming Techniques, by Dan Sydow, M&T Books