Utility Code

Although most code within Nano is packaged in a well-defined object, there are often situations where a stand-alone function is required.

This type of function is typically a simplifying wrapper around a system API, and often combines multiple APIs into a single call that hides unnecessary complexity from the caller.

Rather than provide these functions as static methods on a somewhat-related object, this code is grouped into a set of utility classes that contain related functionality.

Example

For example, creating a CGImageRef from a file on disk can be achieved with:

cgImage = NCoreGraphicsUtilities::CreateImageFromFile(theFile);

This function provides the simple "given an image file, load the image" interface that is most commonly needed, and hides the complexity of how that image is obtained from the caller.

Internally, CreateImageFromFile will use a series of strategies to load the image - first by trying a direct JPEG or PNG data provider, then by using ImageIO, and finally using a QuickTime importer.

Utilities

Utility code is contained within the Library/Source/Utilities directory, and is organized as a set of NFooUtilities classes (where each class is concerned with Foo-related functionality).

Utility calls are typically one-liners, and include functions to:

  • NAppKitUtilities
    Stack-based auto-release pool management.

  • NCoreFoundationUtilities
    Create immutable and mutable copies of objects, NULL-safe retain/release, inline comparison operators for CF types.

  • NCoreGraphicsUtilities
    Create an image from a file/data, scale/rotate/flip an image, create an IconRef from a CGImageRef, encode an image to a particular format.

  • NFileUtilities
    Get/set the contents of a file as a string or as data, get unique or temporary file names, manipulate .dmgs, or move a file to the trash.

  • NGeometryUtilities
    Convert between point/rect types, scale rectangles, transform between coordinate spaces, inline comparison operators for CG types.

  • NHelpUtilities
    Get/set a help string on a view, get the Help menu.

  • NHIViewUtilities
    Get the clickable part of a view, embed a view in a scroll view, construct an HILayoutInfo.

  • NIBUtilities
    Create an NHIView wrapper, construct an HILayoutInfo, get the "clickable part" for a view, embed a view within a scroll view, replace part of view's text value.

  • NKeyboardUtilities
    Test keyboard state.

  • NLaunchServicesUtilities
    Open files or URLs.

  • NMathUtilities
    Floating point equality, fast square roots, rotate left/right, radian/degree conversion.

  • NMouseUtilities
    Get the mouse position in a given coordinate space.

  • NNetworkUtilities
    Test for host reachability.

  • NProcessUtilities
    Get the list of processes, launch a replacement for the current process.

  • NQuickTimeUtilities
    Create a Data Reference from a pointer/handle, add meta-data to a Data Reference.

  • NSTLUtilities
    Reverse, append, combine, and uniquify containers. Extract the front/last element of a vector.

  • NSystemUtilities
    Smart version compare, get Finder label names, get system version.

  • NTextUtilities
    Convert to and from NStrings, URL en/decoding, tilde expansion, construct Safari-style progress strings from bytes-done/throughput/ETA values.

  • NThemeUtilities
    Show animation effects, measure text, get theme metrics.

  • NTimeUtilities
    Get the current time, get the interval between two dates, convert between date formats.