HP OpenVMS Systems Documentation

Registering an application is the phrase used in CDE documentation for integrating and installing an application into the New Desktop. The files required for integrating an application are called a registration package. Registering an application is described in Chapter 4 of the Common Desktop Environment: Advanced User's and System Administrator's Guide.

The process on UNIX systems differs from the process on OpenVMS Alpha systems. The most significant difference is that the CDE application dtappintegrate is not included with the New Desktop. However, the rest of the process on the New Desktop is similar.

An application is considered fully registered into the New Desktop when it has the following components:

• Its own application group at the top level of Application Manager.
• An action that starts the application. The action is represented by an icon in the application group.
• Optionally, data types for its data files.

The registration package consists of the following components:

• Files that are created for integrating an application into the New Desktop. The number and types of files will vary, depending on the type of application and the level of integration you choose (minimal, recommended, or optional).
• A new directory file and associated files for a new application group to be placed in the CDE$USER_DEFAULTS:[APPCONFIG.APPMANAGER.C] directory, as shown in Figure 4-7.

The installation procedure for a registration package must perform the following tasks:

• Test to determine that the appropriate directories are present in the CDE$USER_DEFAULTS:[*...] hierarchy. Files of the following file types should be placed in this hierarchy (see Figure 4-7):
  • *.DT
  • *.FP
  • *.SDL
  • *.HV
  • *.PM
  • *.BM
  • Action files
  • Readme files
  
  If the directories are not present, then the installation procedure must create them.
• Install the files for the new application group that you created for one or more applications that you are installing into that group.
• Install the application integration files that you created for each application into the appropriate directories in the CDE$USER_DEFAULTS hierarchy.
• Install the application executable files, shareable images, and resource files into their respective locations: SYS$SYSTEM, SYS$SHARE, and CDE$USER_DEFAULTS.

Figure 4-7 CDE$USER_DEFAULTS Directory Hierarchy

After your installation has completed and the session has restarted, you can then access the new application group and the applications in it with the following steps:

1. Single click on the icon representing Application Manager.
2. Double click on the icon representing the new application group that you installed. An icon for each application in the group will be displayed.
3. Double click on the application you want to start.

If you have created reference pages (manpages) on a UNIX system that you would like to add to the reference pages on the New Desktop, you can do so in the following way:

• On the UNIX system, format the reference page and capture the output as follows:

  % man dtwmrc > dtwmrc.1

• Copy the formatted file to the OpenVMS system. Use dcp, ftp, or another copy command.
  The following example shows copying with dcp:

  % dcp dtwmrc.1 node"user password"::'cde$system_defaults:[man]'

  
  The following example shows copying with ftp:

  ftp node ftp> cd cde$system_defaults:[man] ftp> put dtwmrc.1 ftp> bye

After you have copied the reference page, you can view it by selecting the Man Page Viewer from the Desktop Apps group of Application Manager.

4.7 CDE Documentation for Integrating Applications

For more detailed information about integrating applications, see the related online help, especially the Create Action help, and the following CDE manuals:

• Common Desktop Environment: Programmer's Overview
• Common Desktop Environment: Advanced User's and System Administrator's Guide.

For instructions on how to access either manual on line or obtain printed copies, see Table 1-2.

DECwindows Motif for OpenVMS Alpha provides the same programming resources as DECwindows Motif for OpenVMS VAX, as well as programming resources for the New Desktop. These include a subset of CDE APIs and integration services and additional CDE resources.

This chapter provides information about the following topics:

• Standards supported by the New Desktop ( Section 5.1 )
• APIs and application integration services ( Section 5.2)
• Save and restore support ( Section 5.3)
• Create Action application ( Section 5.4)
• File type support ( Section 5.5)
• CDE standard fonts ( Section 5.6)
• Help programming ( Section 5.7)
• Header files ( Section 5.9)
• CDE example programs ( Section 5.10)
• CDE programming documentation ( Section 5.11)

The New Desktop supports the following standards:

• CDE Motif 1.0 toolkit (OSF/Motif Release 1.2.5)
  The New Desktop provides run-time support for the CDE Motif 1.0, OSF/Motif Release 1.1.3, and XUI toolkits. DECwindows applications built with these toolkits will run under the New Desktop.
• X11 R5
• UIL compiler
  Although the UIL compiler is supported, CDE applications do not use it. Therefore, no .uid files are associated with any of the CDE applications.
• Motif Resource Manager (Mrm)
• Inter-Client Communication Conventions Manual (ICCCM)
• CDE programming libraries (see Section 5.2)

Table 5-1 lists the subset of CDE application programming interfaces (APIs) and the CDE application integration services available with the New Desktop. They are in the following shareable libraries (pointed to by the logical SYS$LIBRARY):

• CDE$LIBDTSVC.EXE
• CDE$LIBDTHELP.EXE
• CDE$LIBDTWIDGET.EXE

The corresponding header files are also shown in Table 5-1. For a list of all CDE API routines, see Appendix C. Most of the CDE API routines are supported on the New Desktop, but a small subset are not. Those not supported are noted.

In addition to these new APIs and application integration services, all the DECwindows Motif APIs and application integration services are available in the New Desktop.

Table 5-2 lists the CDE APIs, application integration services, and tools that are not included in the New Desktop.

For examples of how these routines are used in applications, see the example programs, as described in Section 5.10.

5.3 Save and Restore Support

The New Desktop provides session save and restore utility functions. If these are integrated into your application, the application state is saved upon exiting Session Manager and is restored when the session is restarted.

Use the XmAddWMProtocol() function to set the WM_SAVE_YOURSELF atom on the WM_PROTOCOLS property for the top level of the application. You can view window properties by using the xprop utility program located in the DECW$UTILS directory.

Use the XmAddWMProtocolCallback() function to declare a callback procedure for when the application receives a WM_SAVE_YOURSELF client message. Session Manager sends a WM_SAVE_YOURSELF client message to your application, and the callback function is called.

The application should not interact with the user during save or restore. For example, a dialog box should not be displayed during save or restore.

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:

• Help compiler interface (DTHELPTAG.COM)
• Help utility functions (CDE$LIBDTHELP.EXE)
• HelpTag examples

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.

The main function of DTHELPTAG.COM is to compile a help source file. DTHELPTAG.COM can also be used for the following tasks:

• Removing all intermediate files generated by DTHELPTAG.COM
• Listing all the files associated with a help volume

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:

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.

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:

• General help dialog boxes (DtCreateHelpDialog())
  General help dialog boxes have a menu bar, a topic tree, and a help topic display area.
• Quick help dialog boxes (DtCreateQuickHelpDialog())
  Quick help dialog boxes have only a topic display area and one or more dialog buttons located at the bottom of the display area.

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...
$