HP OpenVMS Systems Documentation
Content starts here
Common Desktop Environment: Programmer's Overview

6 Recommended Integration

Contents of Chapter:
Help System
Library and Header Files
Demo Programs
ToolTalk Messaging Service
Library and Header Files
Demo Programs
Session Manager
Library and Header Files
Demo Programs
Drag and Drop
Library and Header Files
Demo Programs
Internationalization
Demo Programs
Standard Font Names
Application Fonts
Interface Fonts
Demo Programs
Displaying Error Messages from Your Application
How to Present Error Messages
What Information to Present in Error Dialogs
Linking Message Dialogs to Online Help
User Customization Issues
Color Use
Font Use
Accessibility
Mouse Double-Click Speed
Demo Programs
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.

Note: In addition to incorporating the components and following the guidelines in this section, you should also follow the basic integration steps outlined in Chapter 5, "Basic Application Integration."

For more information on recommended integration, see the CDE 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:

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 Graphic 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 CDE 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 "Handle Desktop" and "Send Desktop" for information on windowing behavior. See "Desktop File" 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 "Send Media" and "Handle Media."

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 CDE 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 CDE 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 "Workspace Manager" 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.

Note: 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 CDE Programmer's Guide.

Drag and Drop

The Common Desktop Environment provides a drag-and-drop API, that is layered on top of the Motif 1.2 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 1.2 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 1.2 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 1.2 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 1.2.

  • Defines a buffer transfer protocol.

    Motif 1.2 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.

Note: 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 CDE 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:

If you intend to internationalize your application, you must ensure that it supports input and output of multibyte characters. 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 CDE Internationalization Programmer's Guide.

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 CDE Programmer's Guide.

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 CDE Programmer's Guide.

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 "Standard Font Names."

Note: The Style Manager only controls fonts for applications written using Motif version 1.2 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 CDE Style Guide and Certification Checklist.