# Recommended Integration

The
Common Desktop Environment contains components and guidelines to use so that your application will integrate well with other applications on the desktop. This chapter provides an overview of each recommended component and guideline that you should use to enhance your application's level of consistency with the desktop.

RDMAP.recin.mkr.2
RDMAP.recin.mkr.3
RDMAP.recin.mkr.9
RDMAP.recin.mkr.10
RDMAP.recin.mkr.11
RDMAP.recin.mkr.12
RDMAP.recin.mkr.13
Printing ??
RDMAP.recin.mkr.14

In addition to incorporating the components and following the guidelines in this section, you should also follow the basic integration steps outlined in RDMAP.BIntg.mkr.1.

For more information on recommended integration, see the Programmer's Guide.

## Help System

The Common Desktop Environment Help system is a complete system for developing and displaying online help for application software. It enables authors to write online help that includes rich graphics and text formatting, hyperlinks, and access to the Help system from within the application. The Help system provides a programmer's toolkit for integrating the help facilities into an application.

Creating and integrating online help into an application can be done as a collaborative project. Developers design and implement how an application responds to a user's request for help. Authors organize and write the actual help information that is displayed.

The Help system includes support for authors and programmers.

### For Authors

- Common Desktop Environment HelpTag markup language—a set of tags used in text files to mark organization and content of online help

- Common Desktop Environment HelpTag software—a set of software tools for converting HelpTag files into run-time help files

- Common Desktop Environment Helpview application—a viewer program for displaying online help

Authors create help topics using the Help tag set and follow Structured Generalized Markup Language (SGML) tagging conventions. SGML markup is the primary data format. When compiled, the run-time distribution format is SGML-compliant.

The Help system also supports non-SGML formats such as UNIX man pages, text files, and text strings.

#### For Programmers

- `DtHelp` programming library—Application program interface (API) for creating and integrating help windows into your application

- `DtHelp`
  widgets— `DtHelpDialog` and `DtHelpQuickDialog` widgets to create help dialog boxes and quick help dialog boxes (these are also part of the Help library)

###
Library and Header Files

The Help library, `libDtHelp`, provides support for creating and managing help dialogs based on Motif. The `libDtHelp` header files are:

- `Dt/Help.h`

- `Dt/HelpDialog.h`

- `Dt/HelpQuickD.h`

### Demo Programs

You can find the Help system demos in `/usr/dt/examples/dthelp`. Read the `README` file for detailed information on the demos.

#### Related Documentation

For more information on the Help system, see the relevant man pages and the Help System Author's and Programmer's Guide.

## ToolTalk Messaging Service

The Common Desktop Environment defines two standard ToolTalk protocols known as
message sets. A message set contains a number of messages that can be exchanged between a sender and a handler process. These message are grouped together because they describe related requests and notices. The sender and recipient can be within the same process or on different hosts. Message sets have associated utility functions that enable you to concentrate on the semantics of the protocol without getting too involved in low-level details. Some message set functions enable you to easily defer to default behavior.

The desktop message set encompasses three areas:

- Windowing behavior

- File access and short-term file lifecycle control

- Application extension languages

See RDMAP.recin.mkr.4 and RDMAP.recin.mkr.5 for information on windowing behavior. See RDMAP.recin.mkr.8 for information on file access and short-term file lifecycle control. Implementing the `Do_Command` request is specific to the application's extension language and is not assisted by the ToolTalk Messaging Service.

The
media message set enables an application to be a container for arbitrary media or to be a media player and editor that can be driven from such a container. The media message set enables a container application to compose, display, edit, and print a document of an arbitrary media type, without understanding anything about the format of that media type. The ToolTalk Messaging Service routes a container's requests to the user's preferred tool for the given media type and operation. This includes routing the request to an already-running instance of the tool, if that instance can best handle the request. See RDMAP.recin.mkr.7 and RDMAP.recin.mkr.6.

The ToolTalk Messaging Service provides support for these message sets:

- Handle Desktop

  Handling desktop requests is the most basic level of messaging integration. Any application that sends ToolTalk messages, either through calling `tt_message_send()` or `DtActionInvoke()`, should handle the desktop requests. This enables other applications to set or query things such as your application's current directory, iconic state, and `$DISPLAY`. For further information, see the man pages for `ttdt_open()`, `ttdt_session_join()`, `ttdt_session_quit()`, and `ttdt_close()`.

- Send Desktop

  When an application is started by `ttsession` to handle some ToolTalk request, it is a child of `ttsession` rather than of the request sender. The application will usually be started on the same X display session as the sender, but not necessarily on the same X11 screen or in the same current directory context. If the application is implemented as a server process, it may already be displaying on a particular screen or in a particular directory context.

  Using desktop requests, a handling application can inherit from the sender attributes that might otherwise be inherited through command-line invocation. Use the desktop message set in this way to reset the handler's locale, current working directory, and even `$DISPLAY`. This enables a carefully coded receiving application to come up on the same X11 screen as the sender. A request handler can also find out the request sender's current directory and window geometry. Knowing the window geometry enables the request handler's window to avoid obscuring the request sender's window, if possible. For more information, see the `ttdt_sender_imprint_on()` man page.

- Handle Media

  The ToolTalk Messaging Service enables an editor to easily handle the standard media requests for the media types for which the editor is responsible. For further information, see the man pages for `ttmedia_ptype_declare()`, `ttdt_message_accept()`, `ttmedia_load_reply()`, and `ttmedia_Deposit()`.

- Send Media

  The ToolTalk Messaging Service enables a container to easily send media requests and manage the subsequent document updates sent back by the handler. In those cases in which the container doesn't engage in any ongoing ToolTalk dialog with a media handler, use the actions API instead of directly using these ToolTalk APIs. Equivalent actions (Open and Print) represent a higher level of abstraction that supports the equivalent of ToolTalk and non- ToolTalk aware media handlers.For further information, see the man pages for `ttmedia_load()` and `ttdt_subcontract_manage()`. Note that, in most cases, a container application should perform operations on objects using `DtActionInvoke()` instead of `ttmedia_load()`. See the ToolTalk Messaging Overview for a description of how ToolTalk applications can be driven using actions.

- Desktop File

  The ToolTalk Messaging Service makes it easy to send and receive the desktop messages about files. These messages enable applications to coordinate access to files. For further information, see the man pages for `ttdt_file_join()`, `ttdt_file_quit()`, `ttdt_file_event()`, `ttdt_Get_Modified()`, `ttdt_Save()`, and `ttdt_Revert()`.

Examples of applications that already use the ToolTalk Messaging Service include the Common Desktop Environment Icon Editor, Mailer, Text Editor, and Calendar. Other parts of the Common Desktop Environment use the ToolTalk Messaging Service indirectly by defining actions that send messages.

### Library and Header Files

The ToolTalk messaging library is called `libtt`. The `libtt` header files are:

- `Tt/tt_c.h`

- `Tt/tttk.h`

### Demo Programs

You can find the ToolTalk Messaging Service demos in `/usr/dt/examples/tt`. Read the `README` file for detailed information on the demos.

#### Related Documentation

For more information on the ToolTalk Messaging Service, see the relevant man pages and the ToolTalk Messaging Overview.

## Session Manager

Session Manager supports the ICCCM 1.1 `
WM_COMMAND` and `
WM_SAVE_YOURSELF`
protocols, which permit:

- Your application to save state information at logout

- Session Manager to restart your application at login

Session Manager also provides an API to assist your application in saving and restoring its state at logout and login.

Session Manager is responsible for restarting applications at login. To do this, your application must tell Session Manager what command and command-line options are required to restart it. Use Xlib's `XSetCommand()` to set the `WM_COMMAND` property on your application's top-level window.

When Session Manager saves a session, such as at logout, your application might need to save some state information so it can be restored to a similar state. Session Manager can optionally notify your application that the session is being saved. Your application must inform Session Manager that it wants such notification. It does this by registering the `WM_SAVE_YOURSELF` protocol with its top-level window `WM_PROTOCOLS` property and setting up a callback procedure to handle the notification. To do this, use the `
XmAddWMProtocols()` and `
XmAddWMProtocolsCallback()` functions. Your application should not interact with the user in any way when processing the `WM_SAVE_YOURSELF` callback. (For example, it should not display a Save As dialog box.) It must set the `WM_COMMAND` property on its top-level window to notify Session Manager that it is done saving its state.

To enable your application to save state information, use the `
DtSessionSavePath()` function to obtain the full path name of a file in which this information can be saved. At session restore time, use the `
DtSessionRestorePath()` function to obtain the full path name of the state file your application uses to restore its state.

The Common Desktop Environment
Workspace Manager is responsible for restoring an application's main top-level window (containing the `WM_COMMAND`) property to the proper workspace, geometry, and icon state. If an application has multiple top-level windows, it is the application's responsibility to restore the states of the other top-level windows. Refer to RDMAP.optin.mkr.5 for additional information.

### Library and Header Files

The Desktop Services library, `libDtSvc`, provides access to many desktop APIs, including the one for session management. Include the `Dt/Dt.h` and `Dt/Session.h` header files to access the Session Manager API.

If your application uses any of the Session Manager APIs, it must first initialize the `libDtSvc` library by calling either `
DtInitialize()` or `
DtAppInitialize()`. Refer to the `DtInitialize`(3) or `DtAppInitialize`(3) man page for more information.

### Demo Programs

You can find the Session Manager demos in `/usr/dt/examples/dtsession`. Read the `README` file for detailed information on the demos.

#### Related Documentation

For more information on Session Manager, see the relevant man pages and the Programmer's Guide.

## Drag and Drop

The Common Desktop Environment provides a drag-and-drop API, that is layered on top of the Motif 2.1 drag-and-drop API, to provide convenient, consistent, and interoperable drag and drop across the desktop. The Common Desktop Environment drag-and-drop API makes it easier for developers to implement drag and drop. With drag and drop, users can manipulate objects on the screen directly by grabbing them, dragging them around the display, and dropping them on other objects to change the object's location or perform a data transfer.

Motif 2.1 drag and drop provides low-level drag-and-drop mechanisms; Common Desktop Environment drag and drop incorporates policies for those mechanisms.

Common Desktop Environment drag and drop consists of an API and protocols to simplify the interface to Motif drag and drop. It implements policies such as the buffer transfer protocol and the drag cursors' appearances. Use the Common Desktop Environment drag-and-drop API, with its built-in policies, to ensure interoperability through consistency. Common Desktop Environment drag-and-drop policies are compatible with standard Motif 2.1 drag-and-drop protocols for text and file name transfers.

Common Desktop Environment drag and drop uses the X selection mechanism to transfer data. Suitable targets exist and are registered with the X Consortium. Two desktop applications can agree to transfer data through the text, file name, or data transfer protocols.

The existing Motif 2.1 API for drag and drop is flexible and, therefore, is somewhat difficult for nonexpert developers to use. The Common Desktop Environment drag-and-drop API provides some convenience functions that result in an API that is simpler and easier to use:

- Manages the configuration and appearance of drag icons.

  Common Desktop Environment drag and drop provides graphics for the default source, state, and operation icons that compose the drag icon in Motif 2.1.

- Defines a buffer transfer protocol.

  Motif 2.1 drag and drop defines protocols for file name and text string only.

- Enables animation upon drop.

  The drop zone can define an animation procedure that is called when the drop completes.

- Provides enumeration of targets for `TEXT` and `FILE_NAME` transfers.

- Provides dual registration.

  You can register a text widget as a drop zone for data other than text, while preserving the ability to accept text drops.

- Provides prioritized drop formats.

  The order in which you specify protocols for the drop zone indicates the relative priority of the protocols desired.

### Library and Header Files

The Desktop Services library, `libDtSvc`, provides access to many desktop APIs, including that for drag and drop. Include the `Dt/Dt.h` and `Dt/Dnd.h` header files to access the drag-and-drop API.

If your application uses any of the drag-and-drop APIs, it must first initialize the `libDtSvc` library by calling either `
DtInitialize()` or `
DtAppInitialize()`. Refer to the `DtInitialize`(3) or `DtAppInitialize`(3) man page for more information.

### Demo Programs

You can find the drag-and-drop demos in `/usr/dt/examples/dtdnd`. Read the `README` file for detailed information on the demos.

#### Related Documentation

For more information on Common Desktop Environment drag and drop, see the relevant man pages and the Programmer's Guide.

## Internationalization

The Common Desktop Environment is internationalized to support single-byte and multibyte locales. Developers can write internationalized applications that can be easily localized to run on any Common Desktop Environment platform.

Common Desktop Environment applications (both source and binary) can be localized into regional languages and territories, and across multiple vendors and hardware platforms:

- Latin American

- Western European

- Japanese

- Korean

- Chinese (Traditional and Simplified)

The Common Desktop Environment takes advantage of internationalization features in these standards:

- IEEE 1003.2-1992 (
  POSIX.2 Annex B)

- X Window System, Version 11 Release 6.2 (Locales and Internationalization Text Functions)

- Motif 2.1 (Internationalizing and Localizing Motif clients)

If you intend to internationalize your application, you must ensure that it supports input and output of multibyte characters. CDE supports vertical writing, which is useful for rendering some Asian languages. Also, make sure that message catalogs are used and code can be fully localized.

### Demo Programs

The drawing program demo in `/usr/dt/examples/template` is internationalized. Read the `README` file for detailed information on this demo.

#### Related Documentation

For more information on Common Desktop Environment internationalization, see the development environment component man pages and the Internationalization Programmer's Guid e.

## Standard Font Names

The standard font names defined by the Common Desktop Environment are guaranteed to be available on all Common Desktop Environment-compliant systems. These names do not specify actual fonts. Instead, they are aliases that each system vendor maps to the vendor's best available fonts. If you use only these font names in your application, you can be sure of getting the closest matching font on any Common Desktop Environment-compliant system. These comprise a set of X Window System font names you can use for the most common categories of type designs and styles.

The standard font names are mapped to different fonts on different Common Desktop Environment platforms, typically using the X font alias mechanism. This eliminates the problem of having to select from a varying set of fonts on different platforms. It also enables you to make use of the default set of fonts on a particular vendor's Common Desktop Environment implementation.

The Common Desktop Environment defines two types of standard fonts: application fonts and interface fonts. Use the application fonts for output produced by your application. Motif widgets and the desktop use interface fonts; do not change their default fonts.

### Application Fonts

At least six point sizes are available on all Common Desktop Environment platforms for each font associated with a Standard Font Name: 8, 10, 12, 14, 18, and 24. XLFD font descriptions for Common Desktop Environment fonts look like:

    -dt-application-*

when used where such patterns are valid.

Two of the most common design variations in fonts used to display text are the presence or absence of serifs and the choice between proportional or regularly spaced (monospaced) characters. Combining these two design variations yields four generic font designs:

- Serif proportionally spaced

- Sans serif proportionally spaced

- Serif monospaced

- Sans serif monospaced

Common examples of each of these four designs (in corresponding order) are:

- Times Roman

- Helvetica

- Courier

- Lucida Typewriter

Each of these designs for text fonts typically come in four styles (combinations of weight and slant):

- Plain

- Bold

- Italic

- Bold-italic

The four styles of each of the four design variations yield 16 generic font variations. These 16 generic fonts are among the most commonly used in general desktop computing. For example, Times Roman, Helvetica, and Courier, each in the four style variations, along with the Symbol font, constitute the Adobe® 13—the minimum set of fonts built into all PostScript printers.

Your application might not require an exact font family or name, but will need to use, for example, a monospaced font, a sans serif font, or a serif font. You do not have to know the exact font names present on a particular Common Desktop Environment platform. The Common Desktop Environment standard fonts default to the vendor's selection of the best font of a particular design on the vendor's platform.

Specify the
XLFD font names for the standard application fonts your application needs as font resource values in the application's `
app-defaults` file. If you do not use these font names, you might need to supply a different `app-defaults` file for each application on each Common Desktop Environment platform`
`.

### Interface Fonts

Interface fonts are the small set of finely optimized fonts that define the look of the desktop on a particular platform. These fonts cleanly and quickly convey small amounts of information, such as that appearing in window titles, buttons, menus, and text fields.

The desktop and the Motif toolkit widgets use interface fonts. Do not use these fonts directly within your application windows.

The standard interface font names are different from the standard application font names. They, like the application font names, are mapped to different fonts on different Common Desktop Environment platforms. Interface fonts come in three styles:

- System—Read-only text (used for limited amounts of text, for example, on menus, buttons, and labels)

- User—Text the end user enters, or text appearing in objects built from `XmText`-type and `DtTerm`-type widgets

- User bold—Like the User font, but in bold

Each style comes in seven sizes. Using the
Style Manager, users can choose the size of interface fonts they want on their desktop.

### Demo Programs

The drawing program demo in `/usr/dt/examples/template` does not specify any of its own interface fonts. It serves as an example of how the Common Desktop Environment Motif interface fonts appear. However, this demo does not take advantage of application fonts.

#### Related Documentation

For more information on standard fonts, see the relevant man pages—particularly `DtStdAppFontNames(5)` and `DtStdInterfaceFontNames(5)` for the list of XLFD font names—and the Programmer's Guid e.

## Displaying Error Messages from Your Application

Applications in the Common Desktop Environment follow a common model for presenting error messages and warnings. Users running your application expect messages to be displayed in message footers, error dialog boxes, or warning dialog boxes, with further explanations available in online help, when appropriate.

This section outlines conventions for displaying error messages in your application. Because of the way message text is handled, it is important to follow these error presentation guidelines precisely. For example, casual users who start your application from the Front Panel never see messages that you send to standard error or standard out. In the Common Desktop Environment, such messages are directed to log files (`$HOME/.dt/*log`) that many users do not routinely examine or know about.

### How to Present Error Messages

Follow these rules when deciding where to tell users about warnings, messages, and error conditions:

- If this message is informational, display the text in the message footer of the application. (Example: “`MyDoc` file copied.”)

- If this message is about an error or serious warning—a problem where an operation important to the user has failed—display an error dialog box or warning dialog box.

### What Information to Present in Error Dialogs

A good error dialog or warning dialog gives a user the following information:

- What happened (from the user's point of view)

- Why it happened, in simple language

- How to fix the problem

### Linking Message Dialogs to Online Help

In cases where additional background information is required, or where it takes more than four or five lines of a dialog to completely explain an error, add a button that links the user to the appropriate section of online help.

#### Related Documentation

For details on displaying error messages in your application and linking message dialogs to online help, see the Programmer's Guide .

### Using Message Logging

The message logging service logs messages for CDE applications. This service provides a central location for messages that users and system administrators can consult to diagnose problems.

The message logging service supports several message types: Informational, Stderr, Debug, Warning, and Error. In addition to logging messages, the API supports the use of alternative message logging handlers and the ability to open message log files.

## Printing

The CDE printing facility is for use primarily by applications that perform X printing, but is sufficiently generalized for use by any CDE application. The application user typically prints files through a set of dialogs that are invoked when the user selects (for example) the application's pull-down menu for printing a file.

Two facilities for supporting printing are available to the application developer:

- The DtPrint convenience functions &mdash These provide the user dialogs for setting print options. This facility also establishes and maintains print connections, initiates printing, and maintains the print setup data.

- The Print Dialog Manager &mdash This process is separate from the X Print Server and X Printing Application; it provides printer- and spooler-specific setup dialogs.

## User Customization Issues

This section presents guidelines to follow when designing your application's user interface.

### Color Use

When you design your application's user interface, do not specify color settings that override the default color scheme that the Common Desktop Environment provides for Motif and desktop widgets. For application-defined colors, use the following colors to promote sharing with other desktop applications:

- Black

- White

- Red

- Green

- Blue

- Yellow

- Cyan

- Magenta

- Gray (eight shades: #de, #bd, #ab, #94, #73, #63, #42, and #21)

In most cases, you should not specify colors, so that your application uses the colors chosen by the end user in the desktop Style Manager.

### Font Use

For your Motif widgets, use the fonts supplied by the Common Desktop Environment so that your application's windows look like other desktop client windows and so that users can change the size of these fonts using the Style Manager. If you override the supplied fonts by changing the Motif `fontList` resource specifications, then you must provide additional functionality if you want users to be able to customize the fonts in your application.

Use the fonts from the Common Desktop Environment standard application font names to specify—in your `
app-defaults` file—resources you use within your application (aside from the ones Motif uses for its widgets). This ensures that your application finds the appropriate fonts on all Common Desktop Environment platforms, which makes your application more portable across such platforms. For more information, see RDMAP.recin.mkr.12.

The
Style Manager only controls fonts for applications written using Motif version 2.1 or later. It will not supply correct fonts for Motif 1.1 (or earlier) applications. These applications must specify their own fonts in the `app-defaults` file.

### Accessibility

This section provides guidelines for making software applications accessible to people with disabilities.

#### Physical Disabilities

Provide keyboard access to all application features, such as those usually accessible through menus or drag and drop, to enable people with physical disabilities to more easily use your application.

#### Visual Disabilities

Follow these guidelines to make your application more accessible to people with visual disabilities:

- Do not hardcode application colors.

- Do not hardcode graphic attributes such as line, border, and shadow thickness. These attributes should scale with font size.

- Do not hardcode font sizes and styles.

- Provide descriptive names for all widgets. In particular, include descriptive names in your application code for widgets that do not display labels on the screen; for example, palette items or icons. This often enables screen-reading software to provide descriptive information to blind users.

#### Hearing Disabilities

Follow these guidelines to make your application more accessible to people with hearing disabilities:

- Never assume that an end user will hear an audible notification.

- Where appropriate, allow end users to choose between audible or visual cues.

- Do not overuse or rely exclusively on audible cues.

- Enable end users to configure frequency and volume of audible cues.

#### Language, Cognitive, and Other Disabilities

The access guidelines outlined for visual, hearing, and physical disabilities typically benefit end users with cognitive, language, and other disabilities. In addition to those guidelines, include tear-off menus and user-configurable menus for important application features whenever possible.

### Mouse Double-Click Speed

For the end user to experience consistency across applications, you should not hardcode double-click durations into your application or `
app-defaults` files. This way, when the user changes the double-click time in the
Style Manager, your application responds along with the other desktop applications.

### Demo Programs

The drawing program demo in `/usr/dt/examples/template` uses the Common Desktop Environment's default colors and fonts. This enables the user to customize the colors and fonts in this program by using the Style Manager. Read the `README` file for detailed information on this demo.

#### Related Documentation

For more information on user customization issues, see the Style Guide and Certification Checklist.