An example program, DTSESSIONEXAMPLE.C, is provided as a guide. The example program creates a main window with a toggle button and saves the state of the button during execution of the save/restore routine.
The example program is available in the following location:
CDE$SYSTEM_DEFAULTS:[EXAMPLES.DTSESSION]
For general information about the example directories, see
Section 5.10.
5.4 Create Action Application
To enable an application to be launched from the New Desktop, certain application configuration files must be created and installed. You can create and install the configuration files for most applications by using the Create Action application, which automates the process of creating these files. You can access the Create Action application from the Desktop Tools application group in Application Manager.
For more information about Create Action, see Section 4.1.
5.5 File Type Support
The New Desktop contains a set of file types with preconfigured icons and associated actions. The icons and actions can be modified with Create Action, the action database and execution management tool.
Examples of file types are executable files (with the file extension
.EXE) and data files (with the file extension .TXT). Examples of
actions
include running a file if it is an executable file, and
printing and opening (in order to edit) a file if it
is
a data file.
5.6 CDE Standard Fonts
CDE defines two types of standard fonts: application fonts and interface fonts. Use the application fonts for application data. Use the interface fonts with the Motif widgets.
The CDE standard application fonts supplied with the New Desktop are names of generic fonts that are available on all CDE platforms. They are mapped to different fonts on different CDE platforms, typically using the X font alias mechanism. You specify the fonts for these resources in your APP-DEFAULTS file.
The CDE standard interface fonts ensure that, for any application development that you do with Motif widgets, the application's windows look like other CDE desktop client windows, and users can change the size of these fonts using Style Manager. If you override the supplied fonts by changing the Motif font list resource specifications, then you must provide additional functionality if you want users to be able to customize the fonts in your application.
By observing these guidelines, your application will find the
appropriate fonts on all CDE platforms. For more information, see the
Common Desktop Environment: Programmer's Overview and the
Common Desktop Environment: Programmer's Guide.
5.7 Help Programming
The New Desktop help system is a complete system for developing and displaying online help for application software. This section briefly describes the process and tools that are provided for developing help. The aspects that are unique to the OpenVMS implementation are fully documented here. For more information about the process, the SGML markup language, the writing tasks, and the programming tasks that comprise this process, see the Common Desktop Environment: Help System Author's and Programmer's Guide.
The following New Desktop programming components are provided for developing help:
Online help is written in text files whose file extension is .HTG. The SGML markup language named HelpTag is used to specify how elements of the text are formatted.
HelpTag consists of a set of tags that specify the formatting of elements such as headings, paragraphs, and lists. After composing the help text and labeling the elements of the text with the appropriate tags, you process these tagged files with the DTHELPTAG.COM command procedure. DTHELPTAG.COM produces run-time help files (with the extension .SDL) that you can view with the Help Viewer.
Two styles of SGML can be used with the HelpTag markup language:
shorthand SGML or fully compliant SGML. The
shorthand style is simpler and quicker to code.
5.7.2 Help Compiler Interface
The Help compiler interface consists of three executable files that are invoked from DTHELPTAG.COM. The executable files, described in Table 5-3, are in the CDE$SYSTEM_DEFAULTS:[BIN] directory, which is referenced by the CDE$PATH logical name.
| File | Purpose |
|---|---|
| DTHELP_CTAG1.EXE | Parser for fully compliant SGML-based help topics. |
| DTHELP_HTAG1.EXE | Parser for shorthand SGML-based help topics. |
| DTHELP_HTAG2.EXE | Runs after either parser for enhancement of distribution file. |
The main function of DTHELPTAG.COM is to compile a help source file. DTHELPTAG.COM can also be used for the following tasks:
DTHELPTAG.COM was ported from the UNIX version of
the dthelptag shell script. DTHELPTAG.COM supports all the
functions found in the UNIX version of this utility except file
compression
and decompression.
5.7.3 DTHELPTAG.COM Format and Options
The format for DTHELPTAG.COM is:
@CDE$PATH:DTHELPTAG [options] filename
where filename specifies the name of the input help source file.
The DTHELPTAG.COM options, which require a leading hyphen (-), are described in Table 5-4.
| Option | Purpose |
|---|---|
| -formal | Specifies the parser for fully compliant SGML-based help topics. If you do not specify -formal, the parser for the shorthand SGML-based help topics is used. |
| -nooptimize | Eliminates certain optimizations that normally take place during translation of HelpTag markup to the run-time format. Using this option speeds the translation process. |
| -memo | Includes a writer's memos entered with the memo tag (<memo>) in the help file. |
| -debug | Saves the intermediate files; otherwise, they are deleted. |
| -clean | Removes all files generated by DTHELPTAG.COM for a particular help volume. |
| -files | Lists all the files associated with for a particular help file. The files include intermediate files generated during the DTHELPTAG.COM command procedure and graphics files included in the help file. |
| -help | Invokes command line help for DTHELPTAG.COM. |
For application programmers, the New Desktop provides a help API that allows the addition of help dialog boxes to any Motif application. The New Desktop help library (CDE$LIBDTHELP.EXE) provides the following two types of help dialog boxes:
For more information on the New Desktop help API, refer
to the Common Desktop Environment: Help System Author's and
Programmer's Guide.
5.7.5 HelpTag Examples
HelpTag example files are in the following directory:
CDE$SYSTEM_DEFAULTS:[EXAMPLES.DTHELP]
The following example uses an example file to illustrate the -files HelpTag option:
$ @CDE$PATH:DTHELPTAG -files HELPDEMO.HTG
The output from this command follows:
Workfile is --> HELPDEMO.HTG MARKUP PARSER (with non-canonical SGML enhancements) (c) Copyright 1993, 1994 Hewlett-Packard Company (c) Copyright 1993, 1994 International Business Machines Corp. (c) Copyright 1993, 1994 Sun Microsystems, Inc. (c) Copyright 1993, 1994 Unix System Labs, Inc., a subsidiary of Novell, Inc. CDE HelpTag Formatting System. - Version B.00.00 (DTD Version A.01.23) Interface generated from help.if on Thu Dec 28 09:01:10 1995 helpdemo.htg Warning: could not open locale translation database. [.graphics]AppWithHelp.xwd [.graphics]cauticon.pm [.graphics]clock.xwd [.graphics]clouds.xpm [.graphics]bee.xwd [.graphics]deadjim.xwd [.graphics]GeneralHelp.xwd [.graphics]head-down.xwd [.graphics]helpchar.ent [.graphics]helpicon.ent [.graphics]helplang.ent [.graphics]helpShelf.pm [.graphics]integral.bm [.graphics]noteicon.pm [.graphics]QuickHelp.xwd [.graphics]rooster.xpm [.graphics]Snapshot.bm [.graphics]Snapshot.xwd [.graphics]speaker.pm [.graphics]shuttle2.xwd [.graphics]sunset.xwd [.graphics]tribe.xwd [.graphics]warnicon.pm [.graphics]xload.xwd Exiting HelpTag Utility... $
You can create additional screen savers for the New Desktop. An example screen saver is provided in CDE$SYSTEM_DEFAULTS:[EXAMPLES.DTSCREEN].
Creating a screen saver involves the following steps:
DTSCREENSAVERLIST == "SampleScreenSaver"
After completing these steps, the new screen saver appears in the list of available screen savers in the Screen option of Style Manager.
For more information about creating new screen savers, see
the README. file in the examples directory.
5.9 Header Files
Header files for the CDE components, shown in Table 5-5, are supplied with the New Desktop. They enable application developers to take advantage of the Desktop APIs (drag and drop, save and restore, Workspace Manager, and so forth), Help services, and custom widgets.
The header files are in the DECW$INCLUDE directory. They are referenced in the source files of the examples directory with the following syntax:
#include <DT/filename.H>
where DT is a logical name that is defined as DECW$INCLUDE.
Include must be specified in lowercase, and the brackets surrounding the include phrase must be angle brackets.
| File | Function |
|---|---|
| Desktop Services APIs | |
| DT/ACTION.H | Action-related structures and functions |
| DT/DND.H | Drag-and-drop functions |
| DT/DT.H | CDE version information, DtInitialize, and DtAppInitialize functions |
| DT/DTS.H | Data typing constants and functions |
| DT/SAVER.H | Screen saver API functions |
| DT/SESSION.H | Session Manager API (save and restore) functions |
| DT/WSM.H | Workspace Manager API related data and functions |
| Help Services | |
| DT/HELP.H | Define functions for dtfile help |
| DT/HELPQUICKD.H | Quick Help dialog resources and functions |
| Custom Widgets (available in libdtwidget.exe) | |
| DT/COMBOBOX.H | For combo box widget |
| DT/EDITOR.H | For editor widget |
| DT/MENUBUTTON.H | For menu button widget |
| DT/SPINBOX.H | For spin box widget |
Several CDE example programs are included in the New Desktop and are described in Table 5-6. The example programs show how to use the various CDE APIs and other programming resources provided with the New Desktop. Each example directory contains a readme file (README.) that describes the example programs and a command file (nnnn.com) that can be used to build the example programs for that directory.
The top-level example directory can be referenced by using the CDE$EXAMPLES logical, as shown in the following example:
$ DIR CDE$EXAMPLES
Directory CDE$SYSTEM_DEFAULTS:[EXAMPLES]
DTACTION.DIR;1 DTDTS.DIR;1 DTHELP.DIR;1
DTSCREEN.DIR;1 DTSESSION.DIR;1 DTWIDGET.DIR;1
DTWSM.DIR;1
The header files for these example programs are included in the form:
#include <DT/filename.H>
where DT is a logical that is defined as DECW$INCLUDE.
| Name | Purpose |
|---|---|
| DTACTION | Shows the use of the action API to invoke actions on a file. The application displays two text entry fields. Enter an action name in the first field and the name of the file to which the action is to be applied in the second field; then press Return. |
| DTDND | Demonstrates how to use the drag-and-drop functions so that an application can be moved by dragging and dropping its icon. The example program consists of a row of three different sources for text, file name, and application-named data drags. It also has a type-in field that can accept either text or file name drops and a data area that accepts file-name or data drops. |
| DTDTS | Demonstrates the use of the Dts data typing API. This program displays the data type, icon name, and supported actions for each file passed to it. The dtaction client can be used to execute a supported action on the file. |
| DTHELP | Illustrates the use of the CDE help system's HelpTag language and the building of a CDE help file. You can invoke the Help Viewer to display the compiled help file (HELPDEMO.SDL). |
| DTSCREEN | Contains an example program (SCREENSAVER.EXE) of the screen saver API. It is an example of a simple screen saver that uses the screen saver API and certain techniques to make the screen saver available to all desktop users or your own session. (Alternatively, you can select a screen saver from the set provided with the New Desktop for use in desktop sessions. You can preview and select these screen savers from the Style Manager Screen dialog box.) |
| DTSESSION | Demonstrates the session mechanism and API. The program SESSION.EXE is an example of an application that supports the Dt session management protocol using the DtSession API. The application saves its current state (the value of a toggle button) when the session is terminated. When the session is restarted, the state of the toggle button is restored. (For more information about save and restore, see Section 5.3.) |
| DTWIDGET | Contains demonstrations of the widget library. The CONTROLS.EXE program demonstrates DtSpinBox, DtComboBox and DtMenuButton controls. The EDITOR.EXE program demonstrates the DtEditor widget. |
| DTWSM | Contains demonstrations of the Workspace Manager API. The OCCUPY.EXE program demonstrates how to set and query an application's presence in CDE workspaces. The WSINFO.EXE program demonstrates how to query for information about the attributes of an application's current workspace. |
The CDE programming documentation includes the CDE help system with
context-sensitive help, online CDE manuals, and online reference pages
(also
known as manpages). Printed CDE manuals are also available.
5.11.1 CDE Programming Manuals
The following CDE programming manuals are available on line:
For instructions on how to access these manuals or obtain printed
copies,
see Table 1-2.
5.11.2 Reference Pages
CDE reference pages (manpages) are provided on the kit as an installation option. Some of the commands described in the reference pages are not implemented in the New Desktop.
The reference pages are divided into sections. On OpenVMS Alpha, the file extension is used to indicate the section type, as shown in Table 5-7.
| Section | Section Type | Section Number¹ |
|---|---|---|
| 1 | Applications | filename.1 |
| 3 | Libraries/programming | filename.3 |
| 4 | Programming | filename.4 |
| 5 | Include file formats | filename.5 |
For instructions on how to access the reference pages, see Table 1-2.
This appendix describes the most significant differences between the New Desktop on OpenVMS Alpha and CDE on UNIX systems. The New Desktop provides an environment that looks similar to any CDE environment, except for several components that are not included on OpenVMS Alpha (see Table 5-1).
The differences between
the common components are primarily due to differences in the operating
systems. For example, the file name syntax is different, and logical
names are
used by the New Desktop in place of environment variables.
A.1 Overall Differences
File names are always displayed and accepted in OpenVMS syntax. However, UNIX path specifications can be used as input to any New Desktop application. For example, /sys$manager/login.com is equivalent to SYS$MANAGER:LOGIN.COM.
Some CDE files are expected to appear in multiple places on UNIX systems through the use of symbolic links. With the New Desktop, files only appear in a single location. There is no dtappintegrate application to create symbolic links in the system directories for application-specific files residing in application-specific directory trees. New application files must be placed in the CDE$USER_DEFAULTS:[*...] system directory.
File names on OpenVMS are case insensitive. When a
file name is used in other contexts, such as in the name of an action
used to match an action (stub) file or in the description resource
names for palettes and backdrops, the reference to the
file name must be lowercase.
A.2 Login Manager Differences
Although the user interface for the login process is basically the same on the New Desktop as on CDE, the implementation of the Login Manager dtlogin on OpenVMS Alpha is different. The main differences are:
The New Desktop login process does use an XSESSION.COM file to start
the dtsession process, and the New Desktop does support an
CDE$SYSTEM_DEFAULTS:[BIN.XSESSION_D]
directory for processing specialized startup command files. In
addition, the
New Desktop supports the standard set of resource files, including
their
localized versions.
A.3 File Manager Differences
The OpenVMS implementation of File Manager differs from the UNIX implementation in the following areas:
The New Desktop printing implementation differs from the CDE printing implementation. The current implementation of CDE printing relies heavily on the UNIX line printer command, lp(1), and the line printer daemon, lpd(8), for its underlying functionality. Because the printing environment for CDE has not been standardized, it was not practical to port this type of operating system specific implementation to OpenVMS Alpha.
On OpenVMS Alpha, the New Desktop printing environment consists of a new application called Print Dialog. It uses the User Interface Language (UIL) and the DECwindows Print Widget (part of the DECWindows Extensions to Motif library) to provide access to printing on OpenVMS Alpha.
Although the New Desktop implementation differs, an attempt was made to integrate OpenVMS Alpha printing with the CDE printing paradigm so that printing would "feel" similar to printing on UNIX systems running CDE. Printers are still managed as objects on the desktop, with print jobs initiated either by dragging file icons and dropping them on printer icons or by selecting them and using the Print Dialog dialog box.
The Print Dialog executable file is located with the other New Desktop executables in the following directory:
CDE$SYSTEM_DEFAULTS:[BIN]PRINTDIALOG.EXE
Messaging capabilities of the New Desktop are more limited than those of CDE. Some activities that appear synchronous with CDE on UNIX are not synchronous in the New Desktop or may require user intervention. This limitation is noticeable in the following cases:
Most processes invoked within the New Desktop are started using actions
with associated execution strings (EXEC_STRINGs). With the New
Desktop,
these EXEC_STRINGs
must be a single valid DCL command. Strings that begin with file
names are automatically converted to foreign command lines.
A.7 Directory Hierarchies of the New Desktop and CDE
This section describes the differences between the directory hierarchies of the New Desktop and those of CDE.
CDE was developed for UNIX systems. The CDE documentation, which is
provided on line with the New Desktop, uses UNIX path
specifications.
A.7.1 System Default Configuration Directories
Table A-1 shows the CDE path specifications that correspond to the New Desktop system default configuration directory names. For more information about the CDE file system or directory tree structure, see the dtfilsys.5 reference page, which you can access with the Man Page Viewer.
The Man Page Viewer is located in the Desktop Apps group in Application Manager. To view dtfilsys.5, access the Man Page Viewer and enter dtfilsys.5 at the Man Page prompt.
| OpenVMS Directory Name | UNIX Path Specification |
|---|---|
| CDE$SYSTEM_DEFAULTS:[000000] | /usr/dt |
| CDE$SYSTEM_DEFAULTS:[APP-DEFAULTS.lang¹]² | /usr/dt/app-defaults/<lang> |
| CDE$SYSTEM_DEFAULTS:[APPCONFIG] | /usr/dt/appconfig |
| CDE$SYSTEM_DEFAULTS: - [APPCONFIG.APPMANAGER.lang¹] |
/usr/dt/appconfig/appmanager |
| CDE$SYSTEM_DEFAULTS:[APPCONFIG.HELP.lang¹] | /usr/dt/appconfig/help |
| CDE$SYSTEM_DEFAULTS:[APPCONFIG.ICONS.lang¹]³ | /usr/dt/appconfig/icons |
| CDE$SYSTEM_DEFAULTS:[APPCONFIG.TYPES.lang¹] | /usr/dt/appconfig/types |
| CDE$SYSTEM_DEFAULTS:[BACKDROPS] | /usr/dt/backdrops4 |
| CDE$SYSTEM_DEFAULTS:[BIN] | /usr/dt/bin |
| CDE$SYSTEM_DEFAULTS:[CONFIG] | /usr/dt/config |
| CDE$SYSTEM_DEFAULTS:[CONFIG.lang¹] | /usr/dt/config/<lang> |
| --- | /usr/dt/dthelp5 |
| CDE$SYSTEM_DEFAULTS:[EXAMPLES] | /usr/dt/examples4 |
| --- | /usr/dt/include5 |
| DECW$INCLUDE:, DT: | /usr/dt/include/Dt4 |
| SYS$MANAGER:CDE$STARTUP.COM | /usr/dt/install/dec/start.cde.dec |
| CDE$SYSTEM_DEFAULTS:[LIB] | /usr/dt/lib |
| CDE$SYSTEM_DEFAULTS:[MAN] | /usr/dt/man4 |
| CDE$SYSTEM_DEFAULTS:[PALETTES] | /usr/dt/palettes4 |
| --- | /usr/dt/share5 |
Table A-2 shows the directories that a system manager creates for any resource, application default, or configuration files that have been customized for systemwide use. The corresponding UNIX path specifications are also shown.