(+) Appearance (+) Standard (+) Console
TOOLBOX [FN] functionName [(arg1 [,arg2...])]¬ [= returnParam] [`0x0000,0x0000...]
In earlier versions of FutureBASIC, access to toolbox calls was limited to modification of internal resources or LOCAL FNs that accessed the 68K traps through assembly language calls. In FB, the source for all toolbox calls is located in editable source code. By convention, these items are stored in the Headers folder (path: FB Extensions/Compiler/Headers) and are give a name that begins with "Tlbx". This is not an absolute requirement. You may create toolbox calls and place them in any project include so long as they are defined before they are called. Routine Name The name of a routine is case sensitive. This is the only instance in FB where upper and lower case letters may not be freely exchanged. The reason for this is that PPC code actually uses the text of the routine name in a look up table where older 68K code used a hexadecimal trap address. When you examine the text of a toolbox call, the name appears to be in upper case. This is because the editor uses an internal look-up table to determine how the name should be formatted. In reality, the text stored in memory looks very different. You can see this difference by placing an apostrophe in front of the text to make it a remark. TOOLBOX FN GETCICON(SHORT) = LONG `0xAA1E 'toolbox FN GetCIcon(short) =long `0xAA1E In this example, the case of GetCIcon is specific and will not work if there is any modification. You may determine what case is required by looking at the C code used by Apple in defining the toolbox. Toolbox Functions Functions (as opposed to procedures) return a value. Unlike BASIC, the Mac's toolbox routines only return numeric variables. Common results are LONG, SHORT, and BOOLEAN. The toolbox does not return strings or records. Toolbox functions begin with TOOLBOX FN. Procedures omit the "FN". Functions also provide a size for the return value with syntax like "= SHORT". TOOLBOX FN FunctionName(param) = SHORT Toolbox Procedures Procedures work much the same as toolbox functions, except that the "FN" prefix is omitted and the return value is no longer necessary. TOOLBOX ProcName(param) 68K & PPC Using only a text description, toolbox calls can be created and used in PPC. FB makes all of the necessary conversions into assembly language and sets up the proper look-up tables in your application. If you want the calls to work in 68K as well as PPC, then you will need to add the required assembly language to the end of the TOOLBOX statement for the selector and the trap. TOOLBOX FN Alert(SHORT,LONG) = SHORT `0xA985 While this may look complex, it is really a modification to something that looks very similar in C code. The following was taken from Apple's headers. Alert(SInt16 alertID,ModalFilterUPP modalFilter) ONEWORDINLINE(0xA985);Note that the upper/lower case of the name in FB's toolbox function exactly matches the one from Apple (even though it will be reformatted when used in the editor). The code from ONEWORDINLINE was moved to the end of the statement after the back apostrophe (also called a grave symbol). While C requires that you predict the number of hex instructions that follow (ONEWORDINLINE, TWOWORDSINLINE, etc.) FB automatically reads the hex digits up to the end of the line or a remark, whichever comes first.