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

7 Optional Integration

Contents of Chapter:
Common Desktop Environment Motif Control Widgets
Compatibility with Motif 2.0
Library and Header Files
Demo Programs
Data Typing
Database Loading
Database Queries
Library and Header Files
Demo Programs
Action Invocation
Library and Header Files
Demo Programs
Workspace Manager
Library and Header Files
Demo Programs
Terminal Emulator Widget
Library and Header Files
Demo Programs
Text Editor Widget
Library and Header Files
Demo Programs
Calendar
Library and Header Files
Demo Programs
Desktop Korn Shell (dtksh)
Demo Programs
The Common Desktop Environment components discussed in this chapter enable you to leverage services provided by the desktop for achieving specialized tasks.

Note: In addition to incorporating any components described in this section into your application, you should also follow the basic integration steps outlined in Chapter 5, "Basic Application Integration." The components discussed in Chapter 6, "Recommended Integration," are critical to making your application highly integrated with the desktop.

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

Common Desktop Environment Motif Control Widgets

The Common Desktop Environment Motif control widgets are designed to ease porting OPEN LOOK and Microsoft Windows applications to the Common Desktop Environment by providing equivalent functionality in Common Desktop Environment Motif. The Common Desktop Environment Motif widgets library libDtWidget contains widgets and functions that are used to provide common functionality across all Common Desktop Environment applications. The widgets provided include:

The Common Desktop Environment Motif Widget library libDtWidget supports drivability between Common Desktop Environment applications and legacy OPEN LOOK applications. That is, it enables you to write applications that operate the same way OPEN LOOK applications do, in areas such as cut, copy, paste, and mouse-button functionality.

Note: The Common Desktop Environment supports all Motif 1.2 widgets. See Appendix A, "Common Desktop Environment Motif," for more information on Common Desktop Environment Motif.

Table 7-1 Common Desktop Environment Control Widgets

Compatibility with Motif 2.0

The APIs of the DtSpinBox and DtComboBox widgets are similar to the Motif 2.0 release of XmSpinBox and XmComboBox widgets. The APIs are designed so an application can easily switch to the Motif 2.0 version of these widgets. To switch, change the Dt names for the class, types, and creation routines to Xm. For example, change all occurrences of DtSpinBox in your code to XmSpinBox. This information is supplied in case you choose to port your application to Motif 2.0, but it is not a recommendation that you do so.

Note: The Common Desktop Environment does not guarantee strict API or binary compatibility between its widgets and the Motif 2.0 widgets.

Library and Header Files

The library libDtWidget provides access to the DtSpinBox, DtComboBox, and DtMenuButton widgets. The libDtWidget header files for these widgets are:

  • Dt/SpinBox.h
  • Dt/ComboBox.h
  • Dt/MenuButton.h

Demo Programs

You can find the Common Desktop Environment Motif control widgets demos in /usr/dt/examples/dtwidget. Read the README file for detailed information on the demos.

Related Documentation
For more information on Common Desktop Environment Motif control widgets, see the relevant man pages and the CDE Programmer's Guide.

Data Typing

You can define data types when you perform basic integration for your application. This section focuses on a different aspect of data typing: extracting information from the actions and data-types database.

Data typing provides an extension to the attributes of files and data beyond what is provided by traditional UNIX file systems. These extensions include typing and attribute management. Use the data-typing API if your application receives data from external sources and must act on it. For example, your application might want to display an icon or execute an action that has a system-wide definition.

Data typing consist of two parts:

  • A database that stores data criteria and data attributes
  • A collection of routines that query the database

The data-typing system determines a type for a file or byte vector based on a set of criteria. These criteria include its name, permissions, symbolic link value, and contents. The attributes associated with a type describe its user-visible interfaces, including a description, the icon to represent it graphically, and the actions that apply to it. Attributes also exist that name the interchange formats to which the data conforms.

The Common Desktop Environment File Manager and Common Desktop Environment Mail attachment window use data typing to determine the icon and actions associated with a file. For example, for a C file filename.c, File Manager uses the .c extension to determine the file's data type, C_SOURCE. It then uses C_SOURCE to determine the icon file name for the icon that it can use for filename.c.

Database Loading

This section discusses the loading API for the actions and data-types database. The syntax for this and any Common Desktop Environment databases a developer defines is discussed in man pages in the /usr/dt/man/man4 directory.

The external database loading API consists of two functions:

  • DtDbLoad()
  • DtDbReloadNotify()

DtDbLoad() reads in the actions and data-types database. It determines the set of directories that are searched for database files, and it loads into the database the .dt files that are found. Your application must call DtDbLoad() before calling any of the routines that query the actions and data-types database.

Use DtDbReLoadNotify() to request notification of actions and data-types database reload events. It registers an application's interest in database reload messages.

Your application should reload the database whenever it changes, so that the end user will notice updates without having to restart the application.

Database Queries

To look up an attribute for a data object, you must first determine the type of the object and then ask for the appropriate attribute value for that type. The database query functions enable you to perform operations such as retrieve type data and attributes, free memory, and load and unload the database. These functions are documented in the CDE Programmer's Guide and also in man pages in the man3 directory.

Library and Header Files

The Desktop Services library, libDtSvc, provides access to many desktop APIs, including that for data typing. Include the Dt/Dt.h and Dt/Dts.h header files to access the data-typing API.

Note: If your application uses any of the data-typing APIs, or loads the actions and data-types database, 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 data typing demos in /usr/dt/examples/dtdts. Read the README file for detailed information on the demos.

Related Documentation
For more information on data typing, see the relevant man pages and the CDE Programmer's Guide.

Action Invocation

The action invocation API enables applications to invoke desktop actions on file or buffer arguments. It chooses a suitable action for the file or buffer based on the Class, Type, Mode, and Number of the action arguments. For example, an Open action might invoke an image viewer for GIF files, a word processor for complex documents, and a simple text editor for ordinary ASCII files. Your application need not concern itself with the details of action selection or invocation.

Use the action invocation API so that your application uses the same mechanisms as the rest of the desktop. The user can then experience uniform desktop behavior.

The action functions in the libDtSvc library provide a way to invoke desktop actions (such as Open and Print) for files or buffers. They contain parameters that enable you to modify an action's behavior. The action invocation API consists of the following functions:

DtActionInvoke()
Invokes the specified action on its arguments,
which can be files or buffers

DtActionLabel()
Provides access to the localizable label string ssociated with an action

DtActionDescription()
Returns a string containing the description information associated with the action your application called

DtActionExists()
a Boolean function that checks whether a given name corresponds to an existing action

DtActionIcon()
Returns the name of the icon associated with the specified action

Library and Header Files

The desktop services library, libDtSvc, provides access to many desktop APIs, including that for actions. Include the Dt/Dt.h and Dt/Action.h header files to access the actions API.

Note: If your application uses any of the action invocation 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 action invocation demos in /usr/dt/examples/dtaction. Read the README file for detailed information on the demos.

Related Documentation
For more information on actions, see the relevant man pages and the CDE Programmer's Guide.

Workspace Manager

The Common Desktop Environment Workspace Manager provides support for multiple workspaces. Each workspace is a virtual screen. Windows can be placed in a single workspace, all workspaces, or any combination of individual workspaces. Workspaces can be added, deleted, or renamed dynamically by the user.

The Workspace Manager API provides functions for applications that need to know in which workspaces their windows reside, or that need to have some control over how the windows are placed in the workspaces. Additionally, the API enables applications to monitor changes to the overall workspace state, such as which workspace is the current one.

The Common Desktop Environment does not require applications to use the Workspace Manager API to run on the desktop. Most desktop applications can run as expected without knowledge of the Workspace Manager. In particular, if your application has a single, main, top-level window and complies with ICCCM 1.1 and Motif 1.2, you do not have to integrate with the Common Desktop Environment Workspace Manager for the application to run on the desktop.

However, more complex applications with multiple top-level windows need to use the Workspace Manager API in conjunction with the Session Manager API to properly save and restore the application's state. The Workspace Manager API enables an application to find out which workspaces each of its windows is in. The API also enables an application to display its windows in the correct workspace when the session resumes.

The Workspace Manager API addresses the following tasks:

  • Get information on workspaces
  • Get and set the current workspace
  • Notify a client of changes to workspace state
  • Add and remove workspace functions for a client
  • Get and set the workspaces occupied by a client
  • Identify backdrop windows

All Workspace Manager API functions share the prefix DtWsm.

Library and Header Files

The desktop services library, libDtSvc, provides access to many desktop APIs, including that for Workspace Manager. Include the Dt/Dt.h and Dt/Wsm.h header files to access the Workspace Manager API.

Note: If your application uses any of the Workspace 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 Workspace Manager demos in /usr/dt/examples/dtwsm. Read the README file for detailed information on the demos.

Related Documentation
For more information on Workspace Manager, see the relevant man pages and the CDE Programmer's Guide.

Terminal Emulator Widget

The DtTerm widget provides the functionality required to emulate an ANSI X3.64-1979-style terminal emulator (specifically a DEC VT220-like terminal with extensions). The Terminal Emulator widget library, libDtTerm, provides the DtTerm widget for use in adding a terminal emulator window to a GUI. If you include a terminal emulator in your application, use Common Desktop Environment Motif widgets to add display enhancements to it such as pop-up menus and scroll bars.

The Common Desktop Environment Terminal Emulator, which is a part of the run-time environment, is a window that behaves as a terminal, enabling access to traditional terminal-based applications from within the desktop. The DtTerm widget is the foundation for the desktop run-time terminal emulator, dtterm.

The libDtTerm library includes a set of convenience functions to create, access, and support the DtTerm widget.

Library and Header Files

The libDtTerm library provides a set of widgets based on Motif for designing a terminal emulator or for adding a terminal emulator window to a GUI.

Include the Dt/Term.h header file to access libDtTerm APIs in your application.

Demo Programs

You can find the Terminal Emulator demos in /usr/dt/examples/dtterm. Read the README file for detailed information on the demos.

Related Documentation
For more information on the DtTerm widget, see the relevant man pages.

For more information on the desktop terminal emulator, see the terminal emulator help volume, the relevant man pages, or the CDE User's Guide.

Text Editor Widget

The Common Desktop Environment text editing system consists of two components:

  • The text editor application, dtpad, which provides editing services through graphical, action, and ToolTalk interfaces

  • The editor widget, DtEditor, which provides a programmatic interface for the following editing services:

    • Cut and paste

    • Search and replace

    • Simple formatting

    • Spell checking (for 8-bit locales)

    • Undo previous edit

    • Enhanced I/O handling capabilities that support input and output of ASCII text, multibyte text, and buffers of data

    • Support for reading and writing files directly

Although the Motif text widget also provides a programmatic interface, applications that want to assure a system-wide uniform editor should use the DtEditor widget. The Common Desktop Environment Text Editor and Mailer use the editor widget. Use this widget in the following circumstances:

  • You need the functionality, such as spell checking, undo, and find/change, that is provided by the DtEditor widget.

  • You want users to be able to read and write data to and from a file.

  • When your program does not need to edit the text while the widget has control of the text.

Library and Header Files

The DtEditor widget is in the libDtWidget library. The header file is Dt/Editor.h.

Demo Programs

A demo containing an example of the DtEditor widget (editor.c) is in /usr/dt/examples/dtwidget directory. Read the README file for detailed information on the demo.

Related Documentation
For more information on the Text Editor widget, see the relevant man pages and the CDE Programmer's Guide.

Calendar

The Common Desktop Environment Calendar comprises the infrastructure and API that enables users to schedule their time and resources in a networked environment. The Calendar GUI is part of the Common Desktop Environment run-time environment.

Calendar consists of:

  • A daemon that manages the calendar database

  • A calendar and scheduling API that defines a set of high-level functions so that calendar-enabled applications can access the functionality supported by the daemon

  • A library implementation of the calendar and scheduling API

Additionally, it provides a user interface for both GUI and TTY interaction. The system supports entering, deleting, and modifying calendar entries, as well as browsing and search features. You can access all this functionality through the network.

The development environment provides a library for client access to the Calendar data. It is extensible in that it allows users to define their own calendar entry attributes.The library provides a client callback mechanism for notification of database updates.

The calendar daemon implements the services behind the library of calendar and scheduling API calls. It supports deleting, inserting, and modifying calendar entries. It also manages calendar reminders and supports the creation and removal of the Calendar database. It also provides mechanisms for retrieving Calendar data.

Calendar entry data integrates with the desktop through drag and drop and the ToolTalk messaging interfaces.

The calendar and scheduling API is an implementation of the X.400 Application Programming Interface Association (XAPIA) Calendaring and Scheduling API 1.0. Use the calendar and scheduling API to integrate your application with Calendar, or to develop your own calendar application.

Library and Header Files

The Calendar library, libcsa, provides a programmatic way to access and manage Calendar data in a networked environment.

Include the csa/csa.h header file to access libcsa APIs in your application.

Demo Programs

You can find the Calendar demos in /usr/dt/examples/dtcalendar. Read the README file for detailed information on the demos.

Related Documentation
For more information on the calendar, see the relevant man pages, the Calendar help volume, and the CDE Programmer's Guide.

Desktop Korn Shell (dtksh)

Desktop Korn shell (which is dtksh) provides a way to engage in graphic user interaction through shell scripts. The user interface capabilities are based on the Common Desktop Environment Motif widget set, the Xt Intrinsics, and the X11 library.

dtksh is a version of ksh-93 extended to access many X, Xt, Motif, and Common Desktop Environment facilities. ksh-93 is a version of Korn shell, the command shell and programming language ksh. dtksh extends ksh to provide support for:

  • Access to the Common Desktop Environment Motif widget set from within a shell script

  • Fully localized shell scripts--dtksh scripts can use catopen and catgets commands

  • Access to the Common Desktop Environment application Help system

  • Response to session-management Save state directives

  • Access to most of the Common Desktop Environment Desktop Services Message Set

  • Access to many of the Common Desktop Environment data-typing API functions

  • Access to most of the Common Desktop Environment action API functions

Demo Programs

You can find the dtksh demos in /usr/dt/examples/dtksh. Read the README file for detailed information on the demos.

Related Documentation
For more information on dtksh, see the relevant man pages and CDE Desktop KornShell User's Guide.