FutureBasic Logo

 <<    Index    >> FutureBasic
NSLog   function


Syntax
NSLog( format [ , expr [ , ...] ] )

Description
NSLog is a flexible set of tools to assist the FB programmer. The tools consist of two primary components: The NSLog command is coded like other FB code and its output is automatically emitted to an independent window (which is automatically created if not already present) known as the NSLog window. The string sent to the NSLog window can be optionally prefixed with the date, time, app name and the process ID. The sent string is composed with a format string, format, and arguments to be inserted into the string. FB's NSLog accepts the same format specification as those used with CFString/NSString formatting. The supported specifiers are described and found in String format specifiers including Length Modifiers. A final hard return is added to the message if one is not present in the format.

Similarities to Xcode's NSLog
NSLog is named after a similar Xcode facility for logging debugging information to Xcode's console window. FB's NSLog accepts the same string format specifiers as its Xcode version but FB's version offers more programmer options (see Buttons and Settings below).

Possible Uses
FB's NSLog is most often used to display the contents of variables while debugging code. NSLog is usually turned off for production deployment to prevent users from seeing the NSLog window; it also removes extra code and extra framework thus reducing the app's size.

To incorporate NSLog into an Xcode project, see: Make Xcode Project
 

Buttons
NSLog window
 
Settings
NSLog settings
Setting
 Description
Date Prefix message with the current date using a @"yyyy-MM-dd" format
Time Prefix message with the current time using a @"HH:mm:ss.SSS" format
App name Prefix message with the application name
Process ID Prefix message with the app's process ID
Console Forward message to Console.app
Floating Make NSLog window float above all other windows
Hide on deactivate Hide NSLog window when the app becomes inactive
Font Set default font and size
Appearance Set default appearance (System, Light, Dark)
ⓘ Display escape characters, string format specifiers and length modifiers
 

 
Escape characters
Character
 Description
\a Alert - When appended to a message, displays a modal alert, pausing program execution.
\b Backspace - Suppresses the hard return, allowing the subsequent NSLog call to continue on the same line
\n, \r \n is a newline characer and \r is a return character
\t Tab
\u 4-digit unicode character
\U 8-digit unicode character
\x Hex
\\ Backslash
\" Double quote
 

Ancillary functions
Function
 Description
NSLogAlert( format, ... ) Displays the message in a modal alert, pausing program execution. This is similar to appending the '\a' escape sequence to the message
NSLogAlertV( format, args ) This alternative to NSLogAlert requires a prepared va_list in the args argument
NSLogAddAttributes( attributes ) Sets log text attributes. attributes is a CFDictionaryRef
NSLogClear Clears the log window
NSLogHide Hides the log window. NSLog messages continue to be received by the window. The log window remains hidden until NSLogShow is called or the app is relaunched.
NSLogPascal( pString ) Prints a pascal string to the log
NSLogProgressSetValue( value ) When value is in the range 0.0 to 100.0, displays a horizontal progress bar at the top of the log window. A negative value hides the progress bar
NSLogProgressStart Call this function to display and animate an indeterminate circular progress indicator at the top right of the NSLog window titlebar.
NSLogProgressStop Call this function to hide the circular progress indicator in the NSLog window titlebar.
NSLogScrollToTop Scrolls the log window to the top
NSLogSetBackgroundColor( color ) Sets the log window background color. color is a ColorRef
NSLogSetFont( font ) Sets the log text font. font is a FontRef
NSLogSetFrame( frame ) Set the log window frame. frame is a CGRect
NSLogSetTabInterval( interval ) Sets the tab interval
NSLogSetTextAlignment( alignment ) Sets the text alignment. Options are:
NSTextAlignmentLeft
NSTextAlignmentRight
NSTextAlignmentCenter
NSTextAlignmentJustified
NSTextAlignmentNatural
NSLogSetTextColor( color ) Sets the log text color. color is a ColorRef
NSLogSetTitle( title ) Sets the log window title. title is a CFStringRef
NSLogShow( title ) Shows the log window when it's been hidden with NSLogHide
string = fn NSLogString Returns the log text as a CFStringRef
NSLogV( format, args ) This alternative to NSLog requires a prepared va_list in the args argument
bool = fn NSLogWriteToURL( url ) Writes the log text to a URL. The returned BOOL indicates success or failure. url is a CFURLRef
 

Suppressing CocoaUI alerts
When CocoaUI alerts are suppressed (CUI_SetSuppressAlerts), the alert message and info text are redirected to NSLog.
Note: suppressing CocoaUI alerts is not recommended for the release version of an app.
 

See also
Make Xcode Project; print (to window); String format specifiers