Common Desktop Environment: Style Guide and Certification Checklist

Using Attachments in Your Application

This section discusses the user model and guidelines for attaching documents to documents in the Common Desktop Environment 1.0. This functionality can be seen in the Mailer software application. If you plan to include an attachment list in the interface of your application, then you should read this section.

Note -

This set of guidelines is not a description of an embedded document architecture.

For the Common Desktop Environment, attachment and attachment list are defined as follows:


Suppose you had two documents called A and B. If a document, A, is attached to another document, B, then A continues to exist as a separate document that is "carried" by B. A is shown as an icon within B. A can be opened and viewed independently and can be detached from B at a later time, as if never attached at all.

attachment list

The area in which attachments are displayed. Should be scrollable and include room for showing icon labels.

Note -

Users do not think of a document that has several attached documents as a container. Containers are an implementation concept that should not appear in the attachments human interface. For that purpose, the term container should not be used to describe attachments to the user. (It may be an appropriate term elsewhere.)

Attachment User Model

Attachments are shown as icons where they are attached. These icons are the same icons as those used in File Manager and other places in the Common Desktop Environment. The basic rule of behavior is that if the same icon is used in File Manager as in an attachment, then every effort should be made to make the two behave the same in every situation.

There are three levels of functionality for attached documents:

  1. Ability to attach and detach documents

  2. Ability to open, view, and quit an attached document in a separate window

  3. Ability to edit the attachment in a separate window and save changes back to the attached document

The goal is to provide Level 3 functionality whenever possible. If an attachment cannot provide this level, then it should degrade its level of functionality in the steps shown. This section is written assuming Level 3 functionality.

If a document provides significantly different functionality as an attachment from that provided as a File Manager icon, then provide a different icon for the attachment to clearly indicate to the user the difference in functionality.

Attachment Functionality

To incorporate attachments into an application, several issues should be considered.

What Can Be Attached?

You should determine for each application what items it can attach. For example, Mailer can attach documents, scripts, and applications, but not folders.

What is the Method for Attaching?

There are two methods of attachment, through the file selection dialog box that comes up when you choose Add File from the Attachment menu, and through drag and drop from File Manager or another application.



Drag and drop should not be the only method for attaching objects. 



When the user chooses something to attach from the file selection dialog box that is not an attachable item, then the user receives an error message explaining why the chosen item cannot be attached. For example: 

The folder "My.Stuff" cannot be attached because it is a folder. Only documents, applications, and scripts can be attached. 



When the user attempts to drop something into the attachment list that is not attachable, then the drop fails and the item is snapped back to its source. 

What Happens When Something Is Attached?

The act of attaching document A to document B copies the bits of document A into document B. There is no further connection with the original file. If the user opens the attached document and makes changes, the changes are saved back to the attached document only, not back to a file in the file system.

Attachments in Attachments

Users can attach messages or text files that have attachments inside them. This is sometimes referred to as "nesting". The user reading the text file would perhaps see a mail message icon that the user could then open, which may have a text message and more attachments.

Editing and Saving Attachments

The user should be able to open an attachment, edit it, and save the changes back to the attachment. If the attachment does not have the ability to do this, then the Open action should not appear in the Actions portion of the menu when that attachment is selected and double-clicking should not open the attachment.



Double-clicking is a shortcut for selecting the attachment and choosing the Open menu item for attachments and should never be the only way to access attachments. 



When the user has one or more attachments open for editing and attempts to do any operation that would result in potentially losing the user's edits, the user should be clearly warned and given the opportunity to save changes. 

Executing Attachments

If the user tries to open or double-click on an executable attachment, then there may be times when the user should be asked to confirm this operation. Both the name of the attachment and the name of the action being taken on the attachment should be variables. An example error message follows:

"Invitation" is an executable attachment. Do you want to Run it?
 Buttons: Run, Cancel, Help

Read-Only Attachments

Read-only attachments can be opened for reading only. This state should be indicated to the user by inactivating the menus in the attachment application, inactivating the selection cursor, or some other obvious method. At a minimum, the Save menu item in the attachment application should be dimmed.

Drag Load and Attachments

Drag load can be accomplished in two ways. In applications that directly support drag load, users can drag an icon, from File Manager, over the open window for that application and drop it which loads the file represented by that icon. The same result can be accomplished by dropping an icon onto an action icon. The action starts an editor, which then loads the file represented by the icon. When an icon from File Manager is drag loaded, it is equivalent to choosing Open from the File menu. The open file can be edited and saved.

In the case of attachments, users can drag and drop an attachment onto editors or actions that support drag load but any edits made are not saved back to the attachment. Attachments, which are implemented as buffers, are loaded as read only data.

When the user tries to save changes to a loaded attachment, the editor displays a file selection dialog box and asks the user to confirm the name and to choose a place in the file system to save the file. The name used in the file selection dialog box is the same as the attachment name. If the editor (command line application) cannot bring up a file selection dialog box, then it should clearly and visibly indicate to the user that the loaded file is read-only.

If the user wants to edit the attachment directly, the user must select the attachment in the attachment list, choose Open from the Attachment menu or double-click on the attachment. This opens the attachment in a manner that allows for editing and saving changes.

Another option is to drag load an attachment, edit it, save it to a new file name, and replace the old attachment with the new one manually.

Attachment Menu Contents



If your application uses an attachment menu, it contains the following choices, with the specified functionality, when the actions are actually supported by your application. 


Add File... 

Selects files and other items to be attached. A file selection box is displayed allowing the user to select the desired files to attach. The default button in the file selection box is Attach. 


Save As... 

Saves the currently selected attachments. The user is prompted with a file selection dialog box for indicating where in the file system the attachments are to be saved. When multiple attachments are selected, the name field is inactive and the current names of the attachments are used as the name of the new file. This menu item is active only when one or more attachments are selected. 



Renames the attachment icon. The application should provide in-line renaming of attachment icons, such as File Manager uses. If the application cannot provide in-line renaming, then Rename allows the user to rename an attachment by displaying a dialog box, requesting the name from the user. This menu item is active only when a single attachment is selected. It is not active when multiple attachments are selected. 



Deletes attachments from the attachment list. This menu item is active only when an attachment is selected. 


Select All 

Selects all the attachments in the attachment list.