<h1>FAQs</h1><h2>How do I add new toolbox calls?</h2><p>FB contains the calls necessary to create toolbox procedures and functions for standard routines and for library routines.</p>
<p>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 <span class="pre">TBALIAS</span> and use either the new or the old syntax.</p>
<pre>TOOLBOX FN Name(parameters) = result ` 68K code</pre>
<span class="pre">TOOLBOX</span> is a keyword that tells FB to add the following information to its list of toolbox routines.</p>
<p>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 "<span class="pre">= result</span>" portion.</p>
<p>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.</p>
<p>68K code is taken directly from the headers supplied by Apple. This code is prefaced with the grave symbol (<span class="pre"> ` </span>) which is also called the back apostrophe by programmers.</p>
<h3>TOOLBOX procedure</h3>
<p>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.</p>
<pre>
PenNormal (void) ONEWORDINLINE(0xA89E);
</pre>
In FB, the translation is very easy.
<pre>
TOOLBOX PenNormal `0xA89E
</pre>
<p>Parameters add another layer of complexity. Understanding what type of variable is to be passed can sometimes be difficult.</p>
<pre>
PenSize(short width,short height)
ONEWORDINLINE(0xA89B);
</pre>
<p>In C-dom, two or more words are used to describe parameters. The first word tells the size of the value required. The word "<span class="pre">short</span>" indicates that an integer is to be used. The word "<span class="pre">width</span>" is just an assigned variable name. This one is also easy to translate.</p>
<pre>
TOOLBOX PenSize(SHORT,SHORT) `0A89B
</pre>
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.</p>
<p>FB has a special syntax for this type of parameter. It uses the <span class="pre">@</span> 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.</p>
<pre>
FrameRect(const Rect * r)
ONEWORDINLINE(0xA8A1);
</pre>
<p>There is a difference here that is easy to spot. The "<span class="pre">r</span>" variable is preceded by a star. In C-speak, this is very similar to FB’s <span class="pre">@</span> symbol. The translated toolbox call can also handle these parameters.</p>
<pre>
TOOLBOX FrameRect(@INT) `0xA8A1
</pre>
<p>If the parameter type is defined (as is the case with RECT), you may optionally duplicate C’s syntax as follows:</p>
<pre>
TOOLBOX FrameRect(const RECT *r) `0xA8A1
</pre>
<p>FB is smart enough to know that the <span class="pre">@</span> symbol forces a long integer pointer. So using <span class="pre">@INT</span> 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.</p>
<p>There is one exception to these rules:</p>
<p>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.</p>
<pre>
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
</pre>
<p>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.)</p>
<pre>
EXTERN_API( RgnHandle )
NewRgn (void) ONEWORDINLINE(0xA8D8);
</pre>
<p>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 "<span class="pre">FN</span>" into the toolbox definition and the second is the use of the size of the result variable.</p>
<pre>
TOOLBOX FN NewRgn = LONG `0xA8D8
</pre>
<h3>TBALIAS</h3>
<p>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 <span class="pre">GetDItem</span> to <span class="pre">GetDialogItem</span>. We can tell FB that we want to be able to use either of these calls via the <span class="pre">TBALIAS</span> statement.</p>
<pre>
TBALIAS GetDialogItem,GetDItem
</pre>
<p>The first parameter (<span class="pre">GetDialogItem</span>) must be defined before the <span class="pre">TBALIAS</span> 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.</p>
<pre>
TBALIAS GetDialogItem,GoAndFetchThatItem
</pre>
<h3>LIBRARY</h3>
<p>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.</p>
<pre>
Library "AppearanceLib"
TOOLBOX FN RegisterAppearanceClient = SHORT ...
TOOLBOX FN UnregisterAppearanceClient = SHORT ...
... more toolbox definitions here...
LIBRARY
</pre>
<p>The first <span class="pre">LIBRARY</span> statement tells FB to get information from the library named "<span class="pre">AppearanceLib</span>". After that, all toolbox calls from that library are defined. The final <span class="pre">LIBRARY</span> call tells FB to return to the standard library that was previously in use.</p>
