The QuickTime framework is included and linked by default; your source code does not need 'include library "QuickTime"'. The OpenGL framework is automatically included and linked if your project uses one of the relevant Headers files such as Tlbx gl.incl or Tlbx agl.incl.

Optional files in the built app package

Copying of specified files into <app>/Contents/Resources
The include resources statement allows you to specify any number of files for copying:

#if def _FBtoC
include resources "SomeImage.png"
include resources "SomeMovie.mpeg"
include resources "SomeSound.aiff"
#endif

FBtoC copies such files into the built app package. Note: the files must be in same folder as the FB project or standalone source file.

*.icns file from 'icns' resource (to <app>/Contents/Resources)
If an 'icns' resource exists in a project resource file, the 'icns' resource is saved as a file in /Contents/Resources. This is automatic and does not require the use of the include resource statement. The file name is derived from the resID of the 'icns' resource, eg. 128.icns. This is the same method used by MakeBundle.

Info.plist (in <app>/Contents/)
FBtoC automatically copies a generic Info.plist into the compiled bundle's Contents directory. That generic Info.plist template can be found in FBtoC at: build_goodies/BuiltApplication.app/Contents/Info.plist.in

A consequence of using that generic template is that it indicates FBtoC's generic BlueLeafC.icns as the *.icns file. Hence, the compiled application will display FBtoC's generic BlueLeaf icon.

The user may override the default behavior based on "Info.plist.in" by including a user-supplied Info.plist file in the FB source folder. FBtoC will automatically find the user-supplied Info.plist and use that, thus overriding its default behavior.

In that case, the user will also have to include a *.icns file corresponding to that pointed to by CFBundleIconFile in the custom Info.plist. The user's custom *.icns file can be copied to the compiled application bundle with 'include resources':

#if def _FBtoC
include resources "AppIcon.icns"
#endif

Pointer- and Handle-typed functions (the new "as type" syntax)
Ordinary FB functions that return a pointer or Handle give rise to a gcc warning.

local fn MyPointerToSomething
dim as pointer p
//...
end fn = p

In function 'MyPointerToSomething':
warning: return makes integer from pointer without a cast

The warning can be eliminated by supplying a pointer type for the declaration:

local fn MyPointerToSomething as pointer // new syntax
dim as pointer p
//...
end fn = p

// Example of a function with arguments
local fn AFuncWithArguments( id as SInt32, size as SInt16 ) as Handle
dim as Handle h

h = fn NewHandle( size )
end fn = h 

appearance button statement for text controls
When creating or changing text controls with the appearance button statement, FB ignores the title param, but FBtoC inserts the text in the control:

appearance button 1,,,,, "My text", @r, _kControlEditUnicodeTextProc
appearance button 1,,,,, "Changed text"

files$ statement
In addition to FSSpecs, FBtoC's files$ statement supports FSRefs and CFURLRefs. These do NOT work in FB.

Examples ("ref" is an FSRef, "url" is a CFURLRef):

#if def _FBtoC	// FBtoC only
fileName = files$( _FSRefOpen,,, ref )
#endif

#if def _FBtoC	// FBtoC only
fileName = files$( _FSRefSave,,, ref )
#endif

#if def _FBtoC	// FBtoC only
fileName = files$( _CFURLRefOpen,,, url )
#endif

#if def _FBtoC	// FBtoC only
fileName = files$( _CFURLRefSave,,, url )
#endif

open statement
In addition to FSSpecs, FBtoC's open statement supports FSRefs and CFURLRefs.

String length errors not reported
String length errors are not reported by FBtoC-built apps. Instead, strings are silently truncated to the maximum length that will fit in the destination variable.

NavDialog function

NavDialog( dialogType [ + options ], message, typeList | defaultSaveName, callbackFn, userData )

The new NavDialog function, an FBtoC-only option, is similar to the FB Files$ keyword but provides more functionality. Using Navigation Services, the details are hidden in the C runtime, so it is easy to call NavDialog ( and several other NavDialogxxxxxx helper functions ) as shown in the NavDialog demos.

The parameters
dialogType

_kNavDialogGetFile

_kNavDialogPutFile

_kNavDialogChooseFolder

_kNavDialogChooseFile

_kNavDialogChooseVolume

_kNavDialogChooseObject

options
The programmer may control what the user sees in the dialog and how it is presented. Option constants are combined with the dialogType parameter.

_kNavDialogSheet	requests a sheet dialog attached to a parent window
_kNavDialogMultiple	allows the user to select multiple files
_kNavDialogInvisible	allows the user to see and select invisible files
_kNavDialogSupportPackages	allows the user to see packages
_kNavDialogOpenPackages	allows the user to open packages ( like OS X application packages )

typeList
Used in _kNavDialogGetFile and _kNavDialogChooseFile dialog types. This parameter allows the programmer to filter by file type. The typeList parameter can be a null string. Same operation as similar parameter in FB's Files$

defaultSaveName
Only appropriate with the _kNavDialogPutFile dialog type. This parameter can be a null string. If supplied, this name is automatically supplied in the "save as.." dialog. The user can obviously replace it with a name of their choosing. Same operation as similar parameter in FB's Files$

callbackFn
The address of a programmer created function. This parameter is always required - see below for more details.

userData
Optional data that can be sent to the callbackFn - The NavDialog_demo uses it to pass a window number but could easily pass a windowRef or other data

Overview of NavDialog Process ( order of operation )
(1) Prior to the actual call of NavDialog(), the code establishes:

	(a) The dialogType - in other words, getting a file, putting a file, choosing a file
	(b) The options, userData, defaultSaveName as described above in parameters
	(c) The callBackFN - this is where the code processes the user file/folder selection(s)
	(d) If a filterFN is used, NavDialog_SetFilterFN is called with the name of the FN that will filter the files ( also see NavDialog_SetFilterFN below )

(2) NavDialog() is called. It interacts with the user and collects the files(s)/folders selected

(3) While (2) is executing the filterFN, if used, is busy deciding which files to show to the user in the dialog

(4) When the user dismisses the dialog ( presumably having completed their selections ), NavDialog passes control to the callbackFN where the selected files are processed

(5) When the callbackFN ends, control returns to the next sequential instruction after the NavDialog() call. Note: If you specify a sheet window, the NavDialog function returns immediately.

The callback function
The programmer identifies a callback function in their own code. This is done simply by passing the address of the FN in the NavDialog call ( i.e. @fn MyGetFileHandler ). This callback function ( FN ) is called by NavDialog to process the results of the dialog interaction with the user. So this is where the program would process the file(s) or folder the user picked in the dialog. Example callback function:

local fn MyGetFileHandler( reply as ^NavReplyRecord, userData as pointer )
   dim as FSSpec spec

   NavDialog_GetItemFSSpec( #reply, 1, _false, @spec )
	
   // do something with file spec

end fn

The callback function always takes two parameters: NavReplyRecord and userData.

Ancillary functions to assist with retrieving results:

NavDialog_GetItemCount	returns the number of items selected by the user. Useful if the program allows multiple file selection with _kNavDialogMultiple
NavDialog_GetItemFSSpec	returns the FSSpec of a file/folder selected
NavDialog_GetItemFSRef	returns the FSRef of a file/folder selected
NavDialog_CopyItemCFURLRef	returns the CFURLRef of a file/folder
NavDialog_GetSaveFileNameAsPascalString	what it says
NavDialog_CopySaveFileName	returns the saveFileName as a CFStringRef

Optional helper functions
A few helper functions are provided to add features to NavDialog.

NavDialog_AddUTIPascalString	If used, must be called before NavDialog(). UTIs are Uniform Type Identifiers and are the modern filtering method. UTIs are broader and more powerful than OSTypes ( i.e. TEXT PICT etc. ). An overview can be found in the Apple docs at "Introduction to Uniform Type Identifiers Overview" ( /Reference Library/Guides/Carbon/Data Management/Uniform Type Identifiers Overview ).
NavDialog_SetFilterFn	If used, must be called before NavDialog() and establishes the name of the filter function ( i.e. filterFn ). A filter function limits which files the user sees. In the NavDialog_demo the filter function uses UTIs to filter.
NavDialog_UTIConformsTo	May be used in a filter callback. Used to filter by UTIs. The filter checks to see if the UTI of the item passed ( first parameter ) "conforms" ( or is a member of ) the UTI group named in the second parameter. If the item is a member, it returns _true ( else _false ) so it can be included in the list presented to the user.
Other Functions	Many other features/functions are available for use and can be found in FilesDollarFunction.c ( within build_goodies ) but are not documented here.