FAQs

How do I add new toolbox calls?

FB contains the calls necessary to create toolbox procedures and functions for standard routines and for library routines.

FB uses a syntax that is very similar to that of C when defining toolboxes (except that it is really much easier). FB also has the unique ability to offer aliases to toolbox calls. When Apple changes the name of a Toolbox routine, you can build a simple TBALIAS and use either the new or the old syntax.

TOOLBOX FN Name(parameters) = result ` 68K code

TOOLBOX is a keyword that tells FB to add the following information to its list of toolbox routines.

FN means that this routine will return a result. If you are building a routine for a procedure, you eliminate this word. If this is a FN, the line must also contain the "= result" portion.

Name is case sensitive. It is one of the few things in FB that must exactly match Apple’s upper and lower case designations. If you don’t get this right, the PPC version of your application will crash when the toolbox is used.

68K code is taken directly from the headers supplied by Apple. This code is prefaced with the grave symbol ( ` ) which is also called the back apostrophe by programmers.

TOOLBOX procedure

A procedure may have parameters (or not). It does not return a value. This first example shows a very simple conversion from a C headers file.

PenNormal (void) ONEWORDINLINE(0xA89E);

In FB, the translation is very easy.

TOOLBOX PenNormal `0xA89E

Parameters add another layer of complexity. Understanding what type of variable is to be passed can sometimes be difficult.

PenSize(short width,short height)
        ONEWORDINLINE(0xA89B);

In C-dom, two or more words are used to describe parameters. The first word tells the size of the value required. The word "short" indicates that an integer is to be used. The word "width" is just an assigned variable name. This one is also easy to translate.

TOOLBOX PenSize(SHORT,SHORT) `0A89B

A byte, an integer (a short), or a long integer can be passed to the toolbox on the stack or in a register. When parameters are more than 4 bytes (the size of a long integer) then a pointer to the record is passed. As an example, a rectangle takes up 8 bytes in memory. Since we can’t pass something that large on the stack, it is necessary to pass its address as a pointer.

FB has a special syntax for this type of parameter. It uses the @ symbol in the parameter list to indicate that the address of a variable, rather than the contents of a variable, should be passed to a toolbox routine.

FrameRect(const Rect * r)
          ONEWORDINLINE(0xA8A1);

There is a difference here that is easy to spot. The "r" variable is preceded by a star. In C-speak, this is very similar to FB’s @ symbol. The translated toolbox call can also handle these parameters.

TOOLBOX FrameRect(@INT) `0xA8A1

If the parameter type is defined (as is the case with RECT), you may optionally duplicate C’s syntax as follows:

TOOLBOX FrameRect(const RECT *r) `0xA8A1

FB is smart enough to know that the @ symbol forces a long integer pointer. So using @INT means that a parameter is being passed which probably starts as an integer (but does not have to). FB passes the address of the integer (or long, or record) rather than the contents of that structure.

There is one exception to these rules:

If you use the C syntax of assigning a variable, then you must use the C syntax of a star (or asterisk) as the pointer. Either of the following would be acceptable.

TOOLBOX FN GraphicsImportSetBoundsRect(¬
     GraphicsImportComponent ci,¬
     const RECT *bounds) ¬
   = ComponentResult ¬
    `0x2F3C, 0x0004, 0x0014, 0x7000, 0xA82A

TOOLBOX FN GraphicsImportSetBoundsRect(¬
     GraphicsImportComponent ci,¬
     @INT) ¬
   = ComponentResult  ¬
    `0x2F3C, 0x0004, 0x0014, 0x7000, 0xA82A

The only difference between a function and a procedure is that a function returns a result. This result is either a byte, an integer, or a long integer. (You can’t return string results in toolbox calls.)

EXTERN_API( RgnHandle )
NewRgn (void) ONEWORDINLINE(0xA8D8);

There are only two additions that we need to make in order to work with a toolbox function. The first is the addition of the term "FN" into the toolbox definition and the second is the use of the size of the result variable.

TOOLBOX FN NewRgn = LONG `0xA8D8

TBALIAS

The name of a toolbox call is often changed to make it easier to understand and use. As one example, Apple changed one toolbox name from GetDItem to GetDialogItem. We can tell FB that we want to be able to use either of these calls via the TBALIAS statement.

TBALIAS GetDialogItem,GetDItem

The first parameter (GetDialogItem) must be defined before the TBALIAS statement is encountered. This is the toolbox that was actually defined in FB. You could easily make up your own name for a toolbox call. The following would work just as well.

TBALIAS GetDialogItem,GoAndFetchThatItem

LIBRARY

The most common toolboxes are available as part of the system software. Other calls are loaded from shared libraries which are located in the extension folder, the application folder, or embedded in the application itself. This is how you would define a toolbox routine that is embedded in a library.

Library "AppearanceLib"
TOOLBOX FN RegisterAppearanceClient = SHORT ...
TOOLBOX FN UnregisterAppearanceClient = SHORT ...
... more toolbox definitions here...
LIBRARY

The first LIBRARY statement tells FB to get information from the library named "AppearanceLib". After that, all toolbox calls from that library are defined. The final LIBRARY call tells FB to return to the standard library that was previously in use.