Working With Documents

Almost all applications handle documents of some kind. A document is a file containing data which the QuickSharp application will load and use in some form. Generally, plugins will supply the functionality required to handle the document data and provide a means of loading and saving documents to and from the file system.

This is of necessity very generic; a document could contain anything from simple text to complex numerical data. A plugin may simply present the data but could also provide more complex editing or processing functionality.

To integrate documents into the QuickSharp framework a general purpose document management system is provided. This provides the user interface elements and plumbing necessary to load documents and identify the plugins responsible for handling them.

This requires two things: a means to identify a document type and a mechanism to associate the document type with a plugin.

Document types

QuickSharp determines a document's type from it's file extension. To define a document within QuickSharp use the 'DocumentType' class; this provides a type-safe wrapper for a document's file extension and ensures it will be used consistently throughout the application. For example, C# files are represented by a DocumentType object created like this:

new DocumentType(".cs");

For a QuickSharp application to be able to load a document, an 'open document handler' must be defined for the document type. Also, to allow new documents of a particular type to be created a 'new document handler' must also be defined. In each case a plugin will provide the handler and must implement the correct functionality to be successfully registered with the document management system.

Document handlers

Document handlers provide the code required to open or create documents of a particular type. Multiple open document handlers may be registered with the document system but only a single handler may be registered to create new documents.

Opening a document allows QuickSharp to determine the document type required from its file name; given the document type the correct document handler can be identified and the document loaded correctly. However, requesting a new document provides no such information so QuickSharp cannot decide which type of document to create unless an explicit 'new document type' has been defined. Consequently, only a single new document handler can be registered with the document management system. This is achieved using the 'NewDocumentType' and 'NewDocumentHandler' properties of application manager.

The document handler must implement the following method signature:

public IDockContent NewDocument()

The method must return either null or an object created from a class derived from the document base type QuickSharp.Core.Document. Assign both properties to allow new documents to be created from the application's 'New' toolbar button and File menu item.

Multiple open document handlers may be registered, one for each document type the application is to support. A handler is registered using the application manager, as in this example for text files:

DocumentType documentType = new DocumentType(".txt");
    documentType, OpenDocument);

OpenDocument is a method implementing the signature required for an open document handler:

public IDockContent OpenDocument(string path, bool readOnly)

As before the method returns null or an object derived from the Document base class. The path parameter provides the location of the file to be opened while the readOnly parameter allows the handler to implement read-only functionality if required.

Document loading

A request to open a document passes through a number of stages. First the path of the document is passed to the document loader, this allows the document type to be determined.

Next, the document type is passed to the document pre-load handlers registered with the application manager. A pre-load handler receives notification that a document of a particular type has been requested. The handler can return true, to allow the loading process to continue, or false to cancel it. Pre-load handlers must implement the following signature:

public bool DocumentPreLoadHandler(DocumentType documentType)

Pre-load handlers can be used to prevent certain document types from being loaded or provide some other type-dependent functionality to augment or replace the normal loading process.

The loader next attempts to retrieve the open handler registered for the document type. If it is found the handler is called and the document content retrieved by the handler returned; the loading process is now complete.

If a handler is not found the loader will next attempt to open the document using the Windows shell. This allows documents to be loaded in external applications from the QuickSharp application user interface. Shell loading can be disabled if required.

If shell loading fails, the loader will finally attempt to retrieve the unknown document handler. This is a handler that may be registered to load unregistered document types. The unknown document handler is actually a handler registered for a particular document type (for example plain text files) and is selected as the unknown document handler by setting the 'UnknownDocumentType' property of the application manager to the document type it has been registered for. In other words setting the unknown document type property causes all unregistered document types to be treated as that type and loaded with the type's registered open handler.

The unknown document type can be null in which case the load process fails and the document will not be loaded. An optional message can be displayed to inform the user that a document handler has not been found.