Setting a Window’s Title and Represented File

A titled window can display an arbitrary title or one derived from a filename. The setTitle: method puts an arbitrary string on the title bar. The setTitleWithRepresentedFilename: method formats a filename in the title bar in a readable format and associates the window with that file. You can set the associated file without changing the title using setRepresentedFilename:. You can use the association between the window and the file in any way you see fit. One convenience offered by the NSWindow class is marking the file as having been changed, so that the user is prompted to save it on closing the window. The method for marking the document as having been changed is setDocumentEdited:. When the window closes, its delegate can check if the files has been changed using isDocumentEdited to see whether the document needs to be saved.

Additionally, starting in OS X version 10.5, you can set a window’s represented document by URL using the setRepresentedURL: method. You can get the URL of the document currently represented by a window using the representedURL method. The window will automatically use the known icon for the file type of the specified file, if one exists. To customize the document icon, you can use the following code segment:

[[NSWindow standardWindowButton:NSWindowDocumentIconButton] setImage:customImage].

By default, a Command-click or Control-click on the rectangle containing a window’s document icon button and title will show a path popup. To customize this behavior, you can implement window:shouldPopUpDocumentPathMenu: in your window’s delegate. You can return NO from this method to stop the window from showing the path popup.

You can also customize the document icon’s default drag behavior by implementing the window:shouldDragDocumentWithEvent:from:withPasteboard: in the window’s delegate. You can return NO to prohibit dragging the document icon.