This program is copyright, but free. See the distribution details at the end of this document.
One of the (few) nice things about HyperCard is how easily new types of buttons can be defined. With Buttoneer it is almost as easy for programmers to define a new type of button that will work in a standard Macintosh application. The hardest part of making a new button is the artwork itself.
All you need to do is to create one or more 'PICT' resources, create a control using the Buttoneer 'CDEF' and give it a refCon that indicates which 'PICT' resource to use. Buttoneer will add the refCon to the current control value and use the result as a resource ID to obtain a PICT handle. That is what the control will look like. In other words the control's appearance is completely arbitrary. Since the appearance is also determined by the control's value you can make "check boxes" or "radio controls" that look like anything.
The demo program included with this file shows a couple of weird check boxes. Source code (Think C) for the demo program is also distributed. In addition to showing how Buttoneer is used this code illustrates a number of useful Mac programming techniques. Anyone who wants to understand how to write a modal dialog should look at this code.
To use Buttoneer you must install the CDEF, create your PICT resources and use the proper toolbox calls to create the Buttoneer control properly. Most of this can be done easily using ResEdit. In simple cases you should be able to substitute an arbitrary Buttoneer control using ResEdit alone.
To install Buttoneer you should copy the CDEF resource from the demo program into your own resource file. (It can be in the system file instead, but that is not reccomended.) The resource is CDEF ID#200 but the ID number does not matter. If you do change the ID number you must keep track of which ID you choose, since you will need it later.
To create PICT resources you will use any "paint" type program. MacPaint works just fine. Create any image you want, select it with the lasso tool, copy it to the clipboard and then switch to ResEdit. Paste the image into your resource file. Be sure a new PICT resource is created. If you use more than one PICT you should be sure that the picture bounds are all the same width and height as your control's bounds rect. Otherwise the pictures will be scaled to fit the control which may not look very nice. The resource IDs for the PICTs don't matter but must correspond to the values which your control may have. For example, suppose your control can have the values -1, 2, 3, or 5 and no other values. If you use a base resource ID of 200 then your PICT resources should be 199, 202, 203 and 205. Controls used like check boxes generally only have values of zero and one so two sequential PICTs are sufficient.
The final step is only a little bit more tricky. The exact way you create a Buttoneer control depends upon the needs of your program. In general you can create a Buttoneer control just like any other control with two exceptions. You must be sure that the control's bounding Rect is the same shape (width and height) as the PICT resources, and you must set the control's reference value (refCon) to the base value for your resource IDs. In the previous example your control's refCon should be 200.
You may create a CNTL resource to describe the control. The CNTL gives the controls bounding Rect, reference value and procID. The procID is computed from the resource ID of the CDEF and its variation code. Buttoneer ignores the variation code (for now) so the procID is just 16 times the CDEFs resource ID. The resource ID for Buttoneer is 200, unless you change it, so its procID is 3200. The bounding Rect can be anything, but its height and width should match the PICT unless you want it scaled.
To use Buttoneer in a dialog you must create a CNTL resource. Then create a dialog item whose type is "Control". Open the item and set the resource ID to point to the CNTL resource (not to the CDEF resource). The CNTL resource in turn points to the CDEF using the procID value. (See Inside Mac, vol. I page 329).
In a dialog the control's location will be taken from the dialog item's bounding rect eventually, but it may first be displayed using the bounding Rect from the CNTL resource. This will cause the control to appear at one point and then jump to its correct location. Make sure the two Rects match or make the dialog be invisible at first. Stranger still, the width and height seem to be determined by the CNTL resource, but the location is determined by the DITL. Hence the easist way to set this up is to make the CNTL bounding rect top and left be zero, the bottom and right be the PICT width and height. Then set the location as the top, left point of the dialog items bounding rect ignoring its bottom and right. You will discover that ResEdit's CNTL editor stinks. (Setting the rect is a pain in the rect...)
For a control in a normal window you will use either NewControl or GetNewControl. GetNewControl uses a CNTL resource as described in the previous paragraph. NewControl is the same, except that the refCon and bounding Rect must be set in the program's code.
Buttoneer looks up the control's refCon and uses GetResource to obtain the PICT every time it draws the control. If the PICT is not found it will not draw anything but will not crash either. The control will still be defined and active, although invisible. Because Buttoneer does not store the refCon or PICT you may change these on the fly if you want. Be sure to call InvalRect on the control's bounding rect to force a redraw.
Currently the variation code is ignored but it should be zero in case I revise the CDEF. Feel free to send me your suggestions of useful variations.
Butoneer ignores the control's title. In dialogs you can create a static text item next to the control if you like.
Buttoneer treats all hilite values other than zero in the same way. It will draw the PICT and then use the Quickdraw InvertRect call to reverse it. The special 255 value for disabled controls is not handled differently.
I had to stay home today because I have a cold. Around noon I felt well enough so that I could *start* to implement Buttoneer. So if you think that there have been hundreds of people doing years of testing on this code you are crazy.
