Mac OS X 10.1 File Name Extension Guidelines
Mac OS X 10.1 File Name Extension Guidelines
- Subject: Mac OS X 10.1 File Name Extension Guidelines
- From: John Geleynse <email@hidden>
- Date: Fri, 07 Sep 2001 10:54:39 -0700
Dear Cocoa Developer,
Mac OS X introduces file name extensions. In adding this capability to Mac
OS X, we've worked hard to provide maximum compatibility with other
operating systems, as well as files exchanged with other users over the
Internet, while preserving the user experience Macintosh users are familiar
with.
The guidelines below provide an in-depth explanation about how this will
work in Mac OS X 10.1, and what your responsibilities are as a developer.
Please note that the NSFileManager class (in Puma) now supports setting the
HFS type & creator code, so Cocoa apps do not need to call Carbon directly
to do this anymore.
Note too, that Apple *will* be co-ordinating and managing a file name
extension registry (much like what we do today for creator and type codes).
Stay tuned for more info.
Please read these guidelines in their entirety *and* try out the described
behaviours for yourself on a Puma 5G48 build or later. As of Puma 5G50,
these guidelines will be included in the Developer Release notes.
I trust you'll find this information valuable.
John Geleynse
User Experience Technology Manager
Apple Worldwide Developer Relations
===========================================
File Name Extension Guidelines
File Name Extension Hiding
File name extensions and file types are two ways to associate the same
information with a single file: What format the file is. Mac OS 9 stores
this information in a file's meta data as HFS file types. Most other
operating systems, including Windows and most UNIX systems, use file name
extensions to store format information for a file.
Mac OS X aims to provide maximum compatibility with other operating systems,
as well as files exchanged with other users over the Internet, while
preserving the user experience Macintosh users are familiar with. To
accomplish this, Mac OS X version 10.1 introduces per-file hiding of file
name extensions. This feature allows applications to store type information
in file name extensions (enabling easy exchange of files with users on other
platforms or over the Internet) while still presenting a simple, human
readable name to the user. The experience Mac OS X presents to the user is
simple: What you see is what you type. That is, the file name shown in the
Finder matches the file name you typed in the Save dialog or in the Finder.
If you type a file name with an extension, you see the extension. If you
type a file name with no extension, you see no extension.
Finder Handling of File Name Extensions
The Finder in Mac OS X 10.1 has been enhanced to respect the presence of a
file name extension hidden flag stored for each file. The Finder works in
conjunction with Launch Services to determine what extensions are known to
the system. Known extensions are those claimed by an application in any of
the "regular" application search paths, or claimed by an application the
user has previously launched that is installed in some other location. (For
information on search paths and how the Finder deals with applications, see
Inside Mac OS X: System Overview, specifically the chapters on the File
System and the Finder.)
Files created by Mac OS 9, downloaded from the Internet, or obtained from
some other source always have the hide extension flag unset initially,
regardless of whether or not they have an extension. Therefore, when a user
downloads a file "image.jpg" from the Internet, it does not magically rename
itself to "image" in the Mac OS X Finder. What the user sees stays
consistent. If the user later renames the file to "mygroovyimage", the .jpg
extension is maintained, but becomes hidden. Again, what the user typed
matches what is displayed. In no case will Mac OS X rename an existing file
without the user taking a specific action to rename that file, nor will
renaming a file ever result in accidental multiple extensions (like "
mygroovyimage.jpg.jpg").
Any file with the hide extension flag set and a known extension has that
extension hidden in the Finder. When users edit the name of such a file,
they edit only the user-visible portion. If they explicitly type in a known
file name extension for the file, either the Finder warns them that what
they're doing may change the type of the file (if they enter a different
file name extension), or the Finder changes the state of the hide extension
flag to show the extension (if they enter a new file name with the proper,
currently hidden extension for the file). In all cases, the Finder allows
users to make the changes if they wish. What users see in the Finder is what
they typed when renaming the file, whether or not they included an
extension.
The Finder also allows users to choose to always display file name
extensions, disabling the smart extension hiding behavior that is on by
default. If users want to keep the smart extension hiding on, but need to
know the exact on-disk file name for a given file, they can see it in that
file's Info window in the Finder. Users can also control whether a specific
file's extension is hidden using a checkbox in the Info window.
Interoperability
With the addition of file name extension hiding, it's possible for every
file on the system that has a specific format to also have an extension
indicating that format. Users don't need to be aware of the extension, and
will not accidentally remove it using the Finder. When a user copies the
file to a non-Mac OS system, the file name extension is present and gives
the operating system the information it needs to handle the file correctly.
On Mac OS X, applications that already write out file name extensions for
interoperability purposes now provide an enhanced user experience; these
file name extensions can be hidden on Mac OS X but automatically get
transferred with the file as it moves to a non-HFS file system. An example
of this is when a user uploads a web site containing html and movie files.
Since the movie files already have their proper file name extensions they
don't need to be renamed and links in associated web pages aren't broken as
a result.
Application Responsibilities
To preserve the "what you see is what you typed" user experience, while
supporting robust interoperability by using file name extensions to indicate
file format, applications have several responsibilities. Apple recommends
that applications adopt the following behavior:
* All document files should have an extension indicating the file's
format.
* When displaying file names in their user interface, applications should
use the display name for the file. Mac OS X version 10.1 includes an API to
get the display name for a file. See the "Support" section below for
details.
* When saving files, users should be able to control whether file name
extensions are hidden. For more details, see "Save Dialog Behavior," below.
* Applications should save newly created document files with a file name
extension, for easy exchange with other operating systems and other users
over the Internet. This file name extension can be hidden, as described in
"Save Dialog Behavior," below.
* When opening and saving a document file, applications should preserve
the value of the document file name extension hidden flag.
* When opening and saving a document file, applications should preserve
the existing file name extension unless the user creates a new document file
by choosing Save As.
* When opening and saving a document file without an extension,
applications should not append an extension or change the value of the hide
extension flag.
* When saving a document file without an extension as a new file in a
Save As operation, applications should add an extension just as they would
when creating a new document file.
Applications may set an HFS file type for documents they create if they
wish. The benefit is increased interoperability with Mac OS 9 applications.
Any existing HFS type of a file opened and saved by an application should be
preserved, unless the user does an explicit Save As operation that creates a
new file, or the application changes the type of the file as a result of the
editing. If the user performs a Save As operation, the application may
choose what file name extension and file type to use for the newly created
file. If the application changes the type of the file as a result of editing
it, the application should generally save it as a new file.
Applications may set an HFS creator for documents they create if they wish.
This creates a tight binding between the newly created document and the
application that created it. Users can always change which application is
used to open a specific document, or all documents with a specific type and
creator code, by using the Info window in the Finder. If an application
wants to change the creator code for a file it opens, the application should
bring up a Save dialog when the user saves the file. At this point it is
also appropriate to add an extension to indicate the type of the file.
Applications that are not a primary editor for documents of a given type
should not set a creator code for those documents. The main example of this
is an Internet browser that downloads files of many different types. In Mac
OS X, users can associate applications with files of a given type using file
name extensions. Browsers downloading files from the Internet should allow
the user to choose which application to use to view those files by simply
allowing the Finder to open them with the user's default application for
that file type.
Save Dialog Behavior
Applications should support ease of interoperation with other operating
systems and Internet services by saving files with file name extensions.
Your application should claim the file name extensions it saves by making
appropriate entries in its Info.plist. See the discussion of file types in
the "Installation and Integration" chapter of Inside Mac OS X: System
Overview for details.
To support user controlled per-file file name extension hiding, applications
need to explicitly enable the new behavior provided by Carbon and Cocoa in
their Save dialogs.
Applications that enable this new functionality will see the following new
behavior in their save dialogs. A hide extension checkbox appears to the
left of the Save and Cancel buttons in the expanded view of the Save dialog.
(This checkbox does not appear in the collapsed version of the Save dialog.)
The state of this checkbox controls whether the file name extension is
displayed both in the Finder and the application. The Save dialog remembers
the last state of the hide extension checkbox as set by the user and
preserves it for future save operations.
There are three scenarios to consider when the user is saving a file:
1. The user types a file name with no extension or with an extension not
known to the system (for example 3My Document.old2).
The hide extension checkbox is checked, and the file is saved with the file
name extension appended to the name the user entered. The hide extension
flag is set in the file system for the new file. The Finder displays the
document name as 3My Document.old2.
2. The user types a file name with the known, correct extension.
The hide extension checkbox is automatically deselected, and the file is
saved with the file name and extension as entered by the user. The hide
extension flag is set to "no" in the file system for the new file.
3. The user types a file name with a known, incorrect extension.
The Save dialog displays an alert warning the user that they can not save
the file with the incorrect extension, and indicates what the correct
extension is. The dialog gives the user the choice of saving the file with
the correct extension, saving the file with both extensions, or canceling
the operation.
For example, if a user tries to save a TextEdit document as "MyFile.jpg",
the alert reads, "You cannot save this document with the extension '.jpg' at
the end of the name. The required extension is '.rtf'. You can choose to use
both, so that your file name ends in '.jpg.rtf'." The buttons are Use .rtf,
Cancel, and Use both. ".rtf" is the correct extension for this document as
set by TextEdit, and Use .rtf is the default button. In no case will the
system hide an extension if doing so would make the file appear to have a
different, valid extension. Therefore, if the user choosed "Use both", the
Finder will display the full saved filename, "MyFile.jpg.rtf".
Support
Carbon and Cocoa both provide API to support the above described behavior.
Getting a File's Display Name
Carbon: Use LSCopyDisplayNameForRef or LSCopyDisplayNameForURL.
Cocoa: Use NSFileManager's displayNameAtPath: method.
Applications should always use the file's display name in their user
interface, as returned by the above functions. The display name can vary
depending on several factors, and using the proper API is the only way to
guarantee that the file name you display in your user interface matches the
file name displayed in the Finder.
Enabling File Name Extension Hiding in Save Dialogs
Carbon: Enable the kNavPreserveSaveFileExtension dialog option bit for the
Navigation Services save dialog, call NavCompleteSave after creating the new
file, and use LSCopyDisplayNameForRef or LSCopyDisplayNameForURL after
saving a file so you can set the file name displayed in the window's title
bar to the correct display name.
Cocoa: Use NSSavePanel's setCanSelectHiddenExtension: method to enable this
feature before displaying the save panel. NSDocument automatically sets the
hide extension flag appropriately for applications that use it. Applications
that do not use NSDocument should query the Save panel themselves and set
the flag using NSFileManager's createFileAtPath:contents:attributes: method.
* Copyright ) 2001 Apple Computer, Inc.
===========================================