• Nano
• Home
• Licence
• Mailing List
• Screenshots
• Version History
• Getting Started
• Quick Start
• Building Nano
• Getting the Code
• Contributing Code
• Reporting Bugs
• Nano Features
• High Performance
• Nano Features
• Nano Views
• Nano Resources
• Custom Cursors
• Custom Menu Items
• Building Applications
• Building Applications
• Adding Documents
• Adding Preferences
• Adding One-Line Undo
• Adding Software Update
• Using Controllers
• Using Carbon Events
• Using HIViews
• Using Functors
• Reference Guide
• Utility Code
• Class Overview
• Coding Standards

Adding Documents

Nano makes no distinction between document-less applications, and those which support a single or multiple documents.

Document related features, such as an Open Recent menu, are automatically enabled if any instances of NDocument are created.

Some important features of document objects are described below. A document-based template is available within Xcode, that provides an initial implementation you can adjust or replace as necessary.

Creating Documents

To create a document object, an application should sub-class NDocument and override NApplication::CreateDocument.

When CreateDocument is called, your application should create an instance of your NDocument sub-class, and return it to NApplication.

NApplication will then initialize the document (e.g., by loading its content from a file), and then select the new document's window.

Document Types

Nano's document model is based around Universal Type Identifiers (UTIs), rather than the legacy approach of type/creator or file extensions.

A UTI is an identifier that identifies a particular type of content, and that can be mapped to one or more type-systems.

They are best thought of as an opaque reference to "a type", which can be queried to obtain a particular representation of that type (such as file type, extension, MIME-type, etc). For example, the UTI for a Windows Bitmap Image could be queried to obtain BMPf, .bmp, or image/x-ms-bmp.

In Nano, each NDocument sub-class has an associated UTI. The UTI is the definitive "type" of the document, and additional meta-data such as the file type or extension are retrieved from the UTI as required.

NApplication automatically uses the UTIs defined in your Info.plist to populate file open dialogs, allowing the user to select only those files that your application can edit or view.

NDocument performs a similar task for save sheets, allowing the user to save documents in one of the available formats that your application can edit. NDocument will also set the file type or extension for saved files automatically, based on the UTI.

This model can be overriden, however for most applications the default behaviour is appropriate.

Loading and Saving

NDocument automatically provides load/save/revert behaviour for sub-classes, as well as a default file format based on key-value encoding.

This file format allows documents to be forward and backwards compatible, and allows NDocument to store its own state (such as window position) beside document-specific content.

Documents that use this file format should override EncodeProperties and DecodeProperties, and archive or restore their state from the supplied NDictionary.

Documents that wish to override a custom file format should override LoadSelf and SaveSelf, and then archive or restore their state from the supplied NFile.

Printing

NDocument provides both job management and page-level printing behaviour, and manages the user interface for configuring a print job.

Documents that contain multi-page content should override PrintSelf for complete control over the printing process, while simpler documents can override GetPrintView to return a single view.

NDocument's default implementation of PrintSelf will invoke GetPrintView, then center and scale the returned view to fit the printed page.