Legacy Document

Inside Macintosh: Files /

Chapter 1 - Introduction to File Management / Using Files

Defining a Document Record

When a user creates a new document or opens an existing document, your application displays the contents of the document in a window, which provides a standard interface for the user to view and possibly edit the document data. It is useful for your application to define a document record, an application-specific data structure that contains information about the window, any controls in the window (such as scroll bars), and the file (if any) whose contents are displayed in the window. Listing 1-3 illustrates a sample document record for an application that handles text files.

Listing 1-3 A sample document record

TYPE
   MyDocRecHnd    = ^MyDocRecPtr;
   MyDocRecPtr    = ^MyDocRec;
   MyDocRec       =
   RECORD
      editRec:       TEHandle;         {handle to TextEdit record}
      vScrollBar:    ControlHandle;    {vertical scroll bar}

      hScrollBar:    ControlHandle;    {horizontal scroll bar}
      fileRefNum:    Integer;          {ref num for window's file}
      fileFSSpec:    FSSpec;           {file's FSSpec}
      windowDirty:   Boolean;          {has window data changed?}
   END;

Some fields in the MyDocRec record hold information about the TextEdit record that contains the window's text data. Other fields describe the horizontal and vertical scroll bars in the window. The myDocRec record also contains a field for the file reference number of the open file (if any) whose data is displayed in the window and a field for the file system specification that identifies that file. The file reference number is needed when the application manipulates the open file (for example, when it reads data from or writes data to the file, and when it closes the file). The FSSpec record is needed when a "safe-save" procedure is used to save data in a file.

The last field of the MyDocRec data type is a Boolean value that indicates whether the contents of the document in the TextEdit record differ from the contents of the document in the associated file. When your application first reads a file into the window, you should set this field to FALSE. Then, when any subsequent operations alter the contents of the document, you should set the field to TRUE. Your application can inspect this field whenever appropriate to determine if special processing is needed. For example, when the user closes a document window and the value of the windowDirty flag is TRUE, your application should ask the user whether to save the changed version of the document in the file. See Listing 1-16 (page 1-33) for details.

To associate a document record with a particular window, you can simply set a handle to that record as the reference constant of the window (by using the Window Manager procedure SetWRefCon). Then you can retrieve the document record by calling the GetWRefCon function. Listing 1-15 illustrates this process.