debian/cdesktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import of the CDE 2.1.30 sources from the Open Group.

Browse Source
This commit is contained in:
Peter Howkins
2012-03-10 18:21:40 +00:00
commit 83b6996daa
18978 changed files with 3945623 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
cde/doc/C/guides/progOview/BEntity.sgm Normal file
View File

@@ -0,0 +1,12 @@
<!-- $XConsortium: BEntity.sgm /main/7 1996/08/07 14:59:45 cdedoc $ -->
<!ENTITY RDMAP.archo.fig.1 SYSTEM "./progOview/graphics/road1.cgm" NDATA CGM-BINARY>
<!ENTITY RDMAP.archo.fig.2 SYSTEM "./progOview/graphics/fpanel.tif" NDATA TIFF>
<!ENTITY RDMAP.optin.fig.1 SYSTEM "./progOview/graphics/SpinBox.tif" NDATA TIFF>
<!ENTITY RDMAP.optin.fig.2 SYSTEM "./progOview/graphics/ComboBox.tif" NDATA TIFF>
<!ENTITY RDMAP.optin.fig.3 SYSTEM "./progOview/graphics/MenuBut2.tif" NDATA TIFF>
<!ENTITY RDMAP.optin.fig.4 SYSTEM "./progOview/graphics/ComboBo3.tif" NDATA TIFF>

3
cde/doc/C/guides/progOview/Title.tmpl Normal file
View File

@@ -0,0 +1,3 @@
/* $XConsortium: Title.tmpl /main/2 1996/06/19 16:04:23 drk $ */
/* TOC title, only what's between quotes should be modified. */
title = "Programmer's Overview"

72
cde/doc/C/guides/progOview/adbook.sgm Normal file
View File

@@ -0,0 +1,72 @@
<!-- $XConsortium: adbook.sgm /main/9 1996/08/21 11:52:30 cdedoc $ -->
<!DOCTYPE DocBook PUBLIC "-//HaL and O'Reilly//DTD DocBook V2.2.1//EN" [
<!ENTITY RDMAP.archo.fig.1 SYSTEM "./graphics/road1.cgm" NDATA CGM-BINARY>
<!ENTITY RDMAP.archo.fig.2 SYSTEM "./graphics/fpanel.tif" NDATA TIFF>
<!ENTITY RDMAP.optin.fig.1 SYSTEM "./graphics/SpinBox.tif" NDATA TIFF>
<!ENTITY RDMAP.optin.fig.2 SYSTEM "./graphics/ComboBox.tif" NDATA TIFF>
<!ENTITY RDMAP.optin.fig.3 SYSTEM "./graphics/MenuBut2.tif" NDATA TIFF>
<!ENTITY RDMAP.optin.fig.4 SYSTEM "./graphics/ComboBo3.tif" NDATA TIFF>
<!ENTITY % local.notations "| XPM | XBM | XWD">
<!NOTATION XPM SYSTEM "XPM">
<!NOTATION XBM SYSTEM "XBM">
<!NOTATION XWD SYSTEM "XWD">
<!ENTITY credi SYSTEM "./credits.sgm">
<!ENTITY pref SYSTEM "./preface.sgm">
<!ENTITY part1 SYSTEM "./part1.sgm">
<!ENTITY archo SYSTEM "./ch01.sgm">
<!ENTITY part2 SYSTEM "./part2.sgm">
<!ENTITY consi SYSTEM "./ch02.sgm">
<!ENTITY devap SYSTEM "./ch03.sgm">
<!ENTITY port SYSTEM "./ch04.sgm">
<!ENTITY BIntg SYSTEM "./ch05.sgm">
<!ENTITY recin SYSTEM "./ch06.sgm">
<!ENTITY optin SYSTEM "./ch07.sgm">
<!-- <!ENTITY motif SYSTEM "./appa.sgm"> rmname'd per Bob Scheifler -->
<!ENTITY compr SYSTEM "./appa.sgm">
]>
<!-- ____________________________________________________________________________ -->
<DocBook>
<Book>
<Title>Common Desktop Environment: Programmer's Overview</Title>
&credi;
&pref;
<Part Id="RDMAP.part1.div.1">
&part1;
&archo;
</Part>
<Part Id="RDMAP.part2.div.1">
&part2;
&consi;
&devap;
&port;
&BIntg;
&recin;
&optin;
</Part>
&compr;
</Book>
</DocBook>

159
cde/doc/C/guides/progOview/appa.sgm Normal file
View File

@@ -0,0 +1,159 @@
<!-- $XConsortium: appa.sgm /main/7 1996/08/25 15:13:16 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<appendix id="RDMAP.compr.div.1">
<title id="RDMAP.compr.mkr.1">Component and Guideline Reference</title>
<para>This appendix alphabetically lists all the CDE development environment
components and guidelines, along with any associated library and header files,
and provides references to associated documentation. In addition to the
documentation listed, all components provide man pages, which are located
in the <filename>/usr/dt/man</filename> directory. All header files are located
in the <command>Dt</command> subdirectory of <filename>/usr/dt/include</filename>
unless otherwise noted.</para>
<table id="rdmap.compr.tbl.1" frame="topbot">
<title>Components and Associated Documentation</title>
<tgroup cols="4" colsep="0" rowsep="0">
<colspec colwidth="1.54in">
<colspec colwidth="1.43in">
<colspec colwidth="1.76in">
<colspec colwidth="2.45in">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Component</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Library</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Header Files</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Documentation</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>Actions and Action Invocation</para></entry>
<entry align="left" valign="top"><para><command>libDtSvc</command></para></entry>
<entry align="left" valign="top"><para><filename>Action.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis>; <emphasis>User's Guide</emphasis>; man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Application Builder</para></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><emphasis>Application Builder User's
Guide</emphasis>; <emphasis>Application Builder Help</emphasis></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Calendar</para></entry>
<entry align="left" valign="top"><para><command>libcsa</command></para></entry>
<entry align="left" valign="top"><para><filename>csa/csa.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis>; <emphasis>Calendar Help</emphasis></para></entry></row>
<row>
<entry align="left" valign="top"><para>Control Widgets</para></entry>
<entry align="left" valign="top"><para><command>libDtWidget</command></para></entry>
<entry align="left" valign="top"><para><command>ComboBox.h, SpinBox.h, MenuButton.h</command></para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis>;
man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Data Typing</para></entry>
<entry align="left" valign="top"><para><command>libDtSvc</command></para></entry>
<entry align="left" valign="top"><para><filename>Dts.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis>; <emphasis>User's Guide</emphasis>; man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Drag and Drop</para></entry>
<entry align="left" valign="top"><para><command>libDtSvc</command></para></entry>
<entry align="left" valign="top"><para><filename>Dnd.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis>;
man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Desktop KornShell</para></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><emphasis>Desktop KornShell User's
Guide</emphasis>; man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Help System</para></entry>
<entry align="left" valign="top"><para><command>libDtHelp</command></para></entry>
<entry align="left" valign="top"><para><command>Help.h, HelpDialog.h, HelpQuickD.h</command></para></entry>
<entry align="left" valign="top"><para><emphasis>Help System Author's and
Programmer's Guide</emphasis>; man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Common Desktop</para><para>Environment
Motif</para></entry>
<entry align="left" valign="top"><para><command>libMrm</command></para></entry>
<entry align="left" valign="top"><para><filename>Mrm/MrmPublic.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Motif Programmer's
Guide</emphasis>; <emphasis>Motif Reference Guide</emphasis>; man
pages</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><command>libUil</command></para></entry>
<entry align="left" valign="top"><para><filename>uil/UilDef.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Motif Programmer's
Guide</emphasis>; <emphasis>Motif Reference Guide</emphasis>; man
pages</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><command>libXm</command></para></entry>
<entry align="left" valign="top"><para><filename>Xm/*.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Motif Programmer's
Guide</emphasis>; <emphasis>Motif Reference Guide</emphasis>; man
pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Session Manager</para></entry>
<entry align="left" valign="top"><para><command>libDtSvc</command></para></entry>
<entry align="left" valign="top"><para><filename>Session.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis>;
man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Terminal Emulator</para><para>Widget
</para></entry>
<entry align="left" valign="top"><para><command>libDtTerm</command></para></entry>
<entry align="left" valign="top"><para><filename>Term.h</filename></para></entry>
<entry align="left" valign="top"><para>man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Text Editor Widget</para></entry>
<entry align="left" valign="top"><para><command>libDtWidget</command></para></entry>
<entry align="left" valign="top"><para><filename>Editor.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis>;
man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>ToolTalk Messaging Service</para></entry>
<entry align="left" valign="top"><para><command>libtt</command></para></entry>
<entry align="left" valign="top"><para><command>Tt/tt_c.h, Tt/tttk.h</command></para></entry>
<entry align="left" valign="top"><para><emphasis>ToolTalk Messaging Overview</emphasis>; man pages</para></entry></row>
<row>
<entry align="left" valign="top"><para>Workspace Manager</para></entry>
<entry align="left" valign="top"><para><command>libDtSvc</command></para></entry>
<entry align="left" valign="top"><para><filename>Wsm.h</filename></para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis>;
man pages</para></entry></row></tbody></tgroup><?Pub Caret></table>
<table id="rdmap.compr.tbl.2" frame="topbot">
<title>Guidelines and Associated Documentation</title>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="2.14in">
<colspec colwidth="3.55in">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Guideline</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Documentation</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>Internationalization</para></entry>
<entry align="left" valign="top"><para><emphasis>Internationalization Programmer's
Guide</emphasis></para></entry></row>
<row>
<entry align="left" valign="top"><para>Standard Font Names</para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Displaying Error Messages</para></entry>
<entry align="left" valign="top"><para><emphasis>Programmer's Guide</emphasis></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>User Customization</para><para>(color
use, accessibility, mouse</para><para>double-click speed)</para></entry>
<entry align="left" valign="top"><para><emphasis>Style Guide and Certification
Checklist</emphasis></para></entry></row></tbody></tgroup></table>
</appendix>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->
<?Pub *0000010088>

84
cde/doc/C/guides/progOview/book.sgm Normal file
View File

@@ -0,0 +1,84 @@
<!-- $XConsortium: book.sgm /main/5 1996/08/21 11:52:39 cdedoc $ -->
<!DOCTYPE Book PUBLIC "-//HaL and O'Reilly//DTD DocBook//EN" [
<!ENTITY % ISOpublishing PUBLIC "ISO 8879-1986//ENTITIES Publishing//EN">
%ISOpublishing;
<!ENTITY % ISOnumeric PUBLIC "ISO 8879-1986//ENTITIES Numeric and Special Graphic//EN">
%ISOnumeric;
<!ENTITY % ISOdiacritical PUBLIC "ISO 8879-1986//ENTITIES Diacritical Marks//EN">
%ISOdiacritical;
<!ENTITY % ISOgeneraltech PUBLIC "ISO 8879-1986//ENTITIES General Technical//EN">
%ISOgeneraltech;
<!ENTITY % ISOalatin1 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN">
%ISOalatin1;
<!ENTITY % ISOalatin2 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 2//EN">
%ISOalatin2;
<!ENTITY % ISOgreek PUBLIC "ISO 8879-1986//ENTITIES Greek Symbols//EN">
%ISOgreek;
<!ENTITY % ISOboxandline PUBLIC "ISO 8879-1986//ENTITIES Box and Line Drawing//EN">
%ISOboxandline;
<!ENTITY % BEntities SYSTEM "./progOview/BEntity.sgm">
%BEntities;
<!ENTITY % local.notations "| XPM | XBM | XWD">
<!NOTATION XPM SYSTEM "XPM">
<!NOTATION XBM SYSTEM "XBM">
<!NOTATION XWD SYSTEM "XWD">
<!ENTITY credi SYSTEM "./progOview/credits.sgm">
<!ENTITY pref SYSTEM "./progOview/preface.sgm">
<!ENTITY part1 SYSTEM "./progOview/part1.sgm">
<!ENTITY archo SYSTEM "./progOview/ch01.sgm">
<!ENTITY part2 SYSTEM "./progOview/part2.sgm">
<!ENTITY consi SYSTEM "./progOview/ch02.sgm">
<!ENTITY devap SYSTEM "./progOview/ch03.sgm">
<!ENTITY port SYSTEM "./progOview/ch04.sgm">
<!ENTITY BIntg SYSTEM "./progOview/ch05.sgm">
<!ENTITY recin SYSTEM "./progOview/ch06.sgm">
<!ENTITY optin SYSTEM "./progOview/ch07.sgm">
<!-- <!ENTITY motif SYSTEM "./progOview/appa.sgm"> rmname'd per Bob Scheifler -->
<!ENTITY compr SYSTEM "./progOview/appa.sgm">
]>
<!-- ____________________________________________________________________________ -->
<Book>
<Title>Common Desktop Environment: Programmer's Overview</Title>
&credi;
&pref;
<Part Id="RDMAP.part1.div.1">
&part1;
&archo;
</Part>
<Part Id="RDMAP.part2.div.1">
&part2;
&consi;
&devap;
&port;
&BIntg;
&recin;
&optin;
</Part>
&compr;
</Book>

758
cde/doc/C/guides/progOview/ch01.sgm Normal file
View File

@@ -0,0 +1,758 @@
<!-- $XConsortium: ch01.sgm /main/13 1996/10/30 14:58:57 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<chapter id="RDMAP.archo.div.1">
<title id="RDMAP.archo.mkr.1">Architectural Overview</title>
<para>This chapter presents a high-level architectural view of the Common
Desktop Environment. For details regarding the desktop run-time environment,
consult the run-time documentation set and the online help volumes. For details
regarding the desktop development environment components, see
<!--Original
XRef content: 'Chapter&numsp;6, &xd2;Recommended Integration'--><xref role="ChapNumAndTitle"
linkend="RDMAP.recin.mkr.1">, <!--Original XRef content: 'Chapter&numsp;7,
&xd2;Optional Integration'--><xref role="ChapNumAndTitle" linkend="RDMAP.optin.mkr.1">,
the development environment documentation set, and the online man pages.
</para>
<informaltable id="RDMAP.archo.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Conceptual Overview3'--><xref role="JumpText"
linkend="RDMAP.archo.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Data Interaction GUIs5'--><xref role="JumpText"
linkend="RDMAP.archo.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Multiuser Collaboration6'--><xref
role="JumpText" linkend="RDMAP.archo.mkr.4"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Desktop Management7'--><xref role="JumpText"
linkend="RDMAP.archo.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Motif GUI Engine12'--><xref role="JumpText"
linkend="RDMAP.archo.mkr.7"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Integration Technologies15'--><xref
role="JumpText" linkend="RDMAP.archo.mkr.8"></para></entry></row>
<row rowsep="1">
<entry><para>Information Technologies ??
</para></entry></row>
</tbody>
</tgroup></informaltable>
<sect1 id="RDMAP.archo.div.2">
<title id="RDMAP.archo.mkr.2">Conceptual Overview</title>
<para>The Common Desktop Environment<indexterm><primary>architecture, Common
Desktop Environment</primary></indexterm> architecture has many cross-process
relationships. The three-process relationship of an X client, a window manager,
and the X Window System&trade; server seems simple by comparison. The area
covered by the Common Desktop Environment is broad, but the layering in the
system is not as rigorous as that of<indexterm><primary>Motif</primary>
</indexterm> Motif, Xt, and Xlib. The relationships between high-level system
components are diverse and extensible. This chapter groups the technologies
to illustrate that each desktop component fits into an overall whole. The
Common Desktop Environment can be divided into:</para>
<figure>
<title>Conceptual overview of Common Desktop Environment</title>
<graphic id="rdmap.archo.igrph.1" entityref="RDMAP.archo.fig.1"></graphic>
</figure>
<itemizedlist remap="Bullet1"><listitem><para>Data interaction graphical user
interfaces (GUIs)&mdash;Application-level components that are available for
user interaction, invocable by other applications. Think of these as programming
components at a larger granularity than widgets.<indexterm><primary>data
interaction graphical user interfaces</primary></indexterm></para>
</listitem><listitem><para>Multiuser collaboration&mdash;Defines and uses
application program interfaces (APIs) that enable collaboration between users
on the network, particularly in the areas of calendar management, network
resource naming, and network file sharing.<indexterm><primary>multiuser collaboration</primary></indexterm></para>
</listitem><listitem><para>Desktop management&mdash;Provides components that
negotiate the visual relationships between entities on the desktop. These
include the following: Window Manager, Workspace Manager, Session Manager,
Application Manager, File Manager, Style Manager, and the Front Panel.<indexterm>
<primary>desktop management</primary></indexterm></para>
</listitem><listitem><para>Motif GUI engine&mdash;Includes those components
that implement the controls available to the user and includes the Common
Desktop Environment Motif toolkit, additional widgets, a GUI shell (Desktop
KornShell), and a GUI construction tool (Application Builder).<indexterm>
<primary>graphical user interface engine</primary></indexterm></para>
</listitem><listitem><para>Integration technologies&mdash;Represent technologies
that do not generate GUIs, but are used as infrastructure by the rest of
the desktop. These technologies include process execution control, application
messaging (mechanism and protocols), data typing, and method invocation.<indexterm>
<primary>integration technologies</primary></indexterm></para>
</listitem></itemizedlist>
</sect1>
<sect1 id="RDMAP.archo.div.3">
<title id="RDMAP.archo.mkr.3">Data Interaction GUIs<indexterm><primary>data
interaction graphical user interfaces &lt;$startrange></primary></indexterm></title>
<para>The Common Desktop Environment supplies a registration service, the
ToolTalk Messaging Service, that enables an application to find an available
service provider. ToolTalk provides the low-level messaging infrastructure.
A companion mechanism, called the actions system, provides a consistent
abstraction layer on top of both the traditional<indexterm><primary>UNIX</primary></indexterm> UNIX&trade; command-line interface to applications
and the Common Desktop Environment-recommended ToolTalk interface to applications.
Actions, as semantic entities, are exposed to the end user through higher
levels of software. Both actions and ToolTalk are discussed in more detail
in <!--Original XRef content: '&xd2;Integration Technologies&xd3; on page&numsp;15'--><xref
role="SecTitleAndPageNum" linkend="RDMAP.archo.mkr.8">.</para>
<para>The desktop contains components that are available through<indexterm>
<primary>actions</primary></indexterm> action and ToolTalk APIs. Examples
include GUIs to show a view of a directory, submit a print job, view the
contents of the Trash Can, edit some text, show help information, compose
a calendar appointment, and compose a mail message.</para>
<para>You can also incorporate actions and<indexterm><primary>ToolTalk Messaging
Service</primary></indexterm> ToolTalk message support into your application
so that the application-specific services they supply are available to the
desktop and other applications. Particularly, applications should provide
the composition, viewing, editing, and printing services for both proprietary
and standard format data. This way, applications that are coded to accept
an extensible set of data types automatically gain more capabilities as more <emphasis>media</emphasis> handlers are added to the system. The Common Desktop Environment<indexterm><primary>File Manager</primary></indexterm>
File Manager,<indexterm>
<primary>Front Panel</primary></indexterm> Front Panel, and<indexterm><primary>Mailer</primary></indexterm> Mailer attachment GUI are examples of such applications.
</para>
<para>Media is used as a generic term for anything that can be presented to
the user to convey information. The desktop provides media handlers for
appointments, mail messages, mail folders, text, icons, and help data. Vendors
have extended the desktop with additional media handlers, including PostScript&trade;,
many kinds of image file formats, and audio <literal><indexterm><primary>data interaction graphical user interfaces &lt;$endrange></primary></indexterm></literal>data.</para>
</sect1>
<sect1 id="RDMAP.archo.div.4">
<title id="RDMAP.archo.mkr.4">Multiuser Collaboration<indexterm><primary>multiuser collaboration &lt;$startrange></primary></indexterm></title>
<para>While the ToolTalk and action mechanisms encourage cooperation between
applications, the desktop also defines cross-user collaboration technologies.
This means distributed access to shared user data. The desktop has defined
some basic sharing mechanisms and has also built on top of existing mechanisms.
</para>
<para>An example of building on an existing mechanism is the<indexterm>
<primary>remote procedure call (RPC)</primary></indexterm> remote procedure
call (RPC) client/service implementation of calendar management. The desktop
provides a client-side library and API, RPC protocol, and daemon/service
that enables users to share appointment information. (The API is being standardized
through<indexterm><primary>X.400 API Association (XAPIA)</primary></indexterm> X.400
Application Programming Interface Association (XAPIA) to enable a cross-UNIX,
PC, and palmtop calendar standard.) The RPC protocol enables a user to browse
and directly edit another user's calendar. Access is controlled by a user-specific
access control mechanism. Calendars are tied to hosts, and a calendar's data
is maintained by a host- specific daemon. The desktop names calendars through
a <computeroutput>user@host</computeroutput> format.</para>
<para>The Common Desktop Environment uses conventional distributed file systems
to name files that are sharable on the network. To provide an interface that
is independent of the distributed file system, the desktop provides an API
to translate host-relative file names into locally expressible file names.
Although the desktop is based on the NFS&reg; system, it can be ported to
run on top of other distributed file systems. Using the desktop file-name
mapping API, an opaque file name object can be constructed and passed between
desktop clients across the network and resolved in a host-specific way. Also,
to simplify the programming task and end user metaphor, Common Desktop Environment
applications should present remote file references as local file paths.</para>
<para>One of the fundamentals of building multiuser collaboration applications
is the ability to share files. The conventions for naming network files,
in conjunction with a ToolTalk file-sharing mechanism called <emphasis><indexterm>
<primary>file scoping</primary></indexterm>file scoping</emphasis>, enable
multiuser collaboration through file sharing. File scoping is more than a
mechanism for simple, exclusive access control. Cooperating clients can use
file-scope access to negotiate for access to files. For example, an application
that has exclusive access to a file could ask whether the user was done with
the file when another application wanted to gain exclusive access to the file.<literal><indexterm>
<primary>multiuser collaboration &lt;$endrange></primary></indexterm></literal></para>
</sect1>
<sect1 id="RDMAP.archo.div.5">
<title id="RDMAP.archo.mkr.5">Desktop Management</title>
<para>The physical metaphor associated with the Common Desktop Environment
is loosely one of a user sitting in a chair surrounded by a bank of desks
(workspaces). As the user swivels the chair (by clicking a push button on
the Front Panel), another desk becomes accessible. On each desk, the following
is available:</para>
<itemizedlist remap="Bullet1"><listitem><para>A collection of drawers (<indexterm>
<primary>File Manager</primary></indexterm> File Manager views) in which folders
(directories) and reports (files) are organized.</para>
</listitem><listitem><para>A collection of papers in use on the desktop (windows).
Some papers are pushed out of the way (as icons), but are within easy reach.
</para>
</listitem><listitem><para>Continuous display (through<indexterm><primary>Front Panel</primary></indexterm> Front Panel icons) of a clock, the date,
an indication of new mail, and an indication of something in the trash can.
</para>
</listitem><listitem><para>Direct access (through Front Panel buttons) to
an appointment book (<indexterm><primary>Calendar</primary></indexterm>Calendar),
a pad of paper (<indexterm><primary>Text Editor</primary></indexterm>Text
Editor), a terminal (emulator), a mail box (<indexterm><primary>Mailer</primary>
</indexterm>Mailer), a printer (<indexterm><primary>Print Manager</primary>
</indexterm>Print Manager), office lighting controls (<indexterm><primary>Style Manager</primary></indexterm>Style Manager), a list of electronic agents
(<indexterm><primary>Application Manager</primary></indexterm>Application
Manager and Front Panel personal tool box), a guide book (<indexterm>
<primary>Help system</primary></indexterm>Help), and a library (Information
Manager).</para>
</listitem></itemizedlist>
<para>The user drags and drops objects to change their location and make copies
of them. By dropping objects on services, the user gains assistance with
appointment scheduling, editing, mail composition, printing, and other tasks.</para>
<sect2 id="RDMAP.archo.div.6">
<title>Session Management<indexterm><primary>desktop management</primary>
<secondary>session management &lt;$startrange></secondary></indexterm><indexterm><primary>Session Manager &lt;$startrange></primary></indexterm></title>
<para>The state of the desktop can be remembered. At a later time, and perhaps
at a different X display station, the state of the desktop can be re-created.
A session is a snapshot of the state of a user's desktop at a point in time.
The Common Desktop Environment supports the following sessions from which the user
can choose at login:</para>
<itemizedlist remap="Bullet1"><listitem><para>Home session&mdash;A snapshot
of the desktop state that reassembles in the same way each time it is started.
</para>
</listitem><listitem><para>Current session&mdash;The state of a desktop saved
at logout time.</para>
</listitem>
<listitem>
<para>Display-specific Home session&mdash;A Home session created by the user for a specific display;
if it exists, it takes precedence over the generic Home session.
</para>
</listitem>
<listitem>
<para>Display-specific Current session&mdash;A Current session created by the user for a specific
display; if it exists, it takes precedence over the generic Current session.
</para>
</listitem>
<listitem>
<para>Failsafe session&mdash;A minimal session that can be used to access the system if the normal
<command>login</command> fails.
</para>
</listitem>
</itemizedlist>
<para>The Common Desktop Environment Session Manager coordinates these activities,
but applications are responsible for saving their own state.</para>
<para>The desktop supports the X11R6 X Session Management Protocol and
the X11R5 Interclient Communication Conventions style
of session management. This consists mostly of conventions for setting properties
on top-level windows. The desktop extends this by providing a facility that
allocates specific files into which applications can store their state. A
command-line flag then points to this file when the application is restarted.
Applications that maintain multiple top-level windows must save the state
of each of them.</para>
<para>A session is associated with a particular user. In the Common Desktop
Environment, the Login Manager is responsible for initial user login. The<indexterm><primary>Login Manager</primary></indexterm>
Login Manager is
an alternative GUI for the<indexterm><primary>UNIX</primary></indexterm> UNIX
login program. Normally, it checks the entered password with the user's registered
password. However, vendors can provide authentication schemes tuned to their
platform.</para>
<para>The Login Manager is network-aware. When faced with an X display that
is normally served by host A, the user can log into the user's desktop by
running a session from host B that has full access to the user's normal set
of files and services on host B. This is possible by Login Manager acting
as the desktop's<indexterm><primary>X11 Display Manager (XDM)</primary>
</indexterm> X11 Display Manager (XDM). The XDM Control Protocol (XDMCP) is
used between X11 window servers and XDMs on the network. The Login Manager
displays its login window or host chooser window on any X11 server requesting
either XDM service. This makes the Common Desktop Environment a good match
for use with XDMCP-aware X terminals.</para>
<para>For connections to the X server, the desktop uses the X magic cookie
scheme to control access. If a user on some host machine can read a certain
file within a session owner's home directory, then access to the X server
is granted. An alternative to this per-user authorization is per-host authorization.
This is useful for installations supporting pre-X11R4 clients, which will
be unable to connect to X servers using the<indexterm><primary>X magic
cookie scheme</primary></indexterm> X magic cookie scheme.</para>
<para>X resource files are handled in the context of Common Desktop Environment
sessions as follows: a set of Common Desktop Environment default resources
is merged with a host version of this file, followed by the user's <filename>$HOME/.Xdefaults</filename> file, followed by a session-specific file of resources
that have changed through user interaction with the Style Manager. The result
is stored in the <filename>RESOURCE_MANAGER</filename> property of the root
window. To enable fine- grain customization, the C preprocessor is run on
resource files.<literal><indexterm><primary>desktop management</primary><secondary>session management &lt;$endrange></secondary></indexterm><indexterm><primary>Session Manager &lt;$endrange></primary></indexterm></literal>
</para>
</sect2>
<sect2 id="RDMAP.archo.div.7">
<title>Application Management<indexterm><primary>desktop management</primary>
<secondary>application management &lt;$startrange></secondary></indexterm></title>
<para>One of the obstacles preventing end users from taking full advantage
of the network environment is the difficulty of accessing remote applications.
The Common Desktop Environment provides conventions for:</para>
<itemizedlist remap="Bullet1"><listitem><para>Installation of applications
so that they can be run remotely</para>
</listitem><listitem><para>User navigation of available applications</para>
</listitem><listitem><para>Execution of remote applications</para>
</listitem></itemizedlist>
<para>The user can browse the collection of available applications with a
GUI tool called Application Manager. Applications can be dragged onto the
desktop for easier access. Even remote applications are started by a simple
double-click, hiding the network location of a running application. The user
is not aware of any distinction between local and remote applications.</para>
<para>This network transparency is accomplished by installing applications
on network hosts designated as <emphasis><indexterm><primary>application
servers</primary></indexterm>application servers</emphasis>. The parts of
the installation relevant to the desktop require placing certain files in
conventional places in the application's installation hierarchy. The application
server maintains a list of applications that it is serving. Each host on
the network maintains a list of the application servers on the network that
it queries when a user logs into the desktop. This process is referred to
as <emphasis>application gathering</emphasis>. It results in a dynamically-generated
file hierarchy of actions arranged in folders. (Actions represent operations
that end users can invoke, including starting applications.<indexterm><primary>actions</primary></indexterm>)</para>
<para>The Common Desktop Environment<indexterm><primary>Application Manager</primary></indexterm> Application Manager provides a specialized view of
the file system for the end user. Applications are arranged into groups and
groups can be nested (such as in a directory hierarchy). Your application's
installation script associates the application to a group. This association
can be overridden by the system administrator as part of application server
configuration. The set and arrangement of the actions shown through the Application
Manager is a system resource that is typically shared between multiple users.
Users cannot modify this view.</para>
<para>The user can drag an icon from the<indexterm><primary>Application
Manager</primary></indexterm> Application Manager onto the desktop, File Manager,
Front Panel, and so on. The associated action remains valid as long as the
gathered application that it refers to remains valid. Because actions represent
a form of abstraction and indirection, the actual location of the application
can change over time. This change remains transparent to the end user (this
is explained further in <!--Original XRef content: '&xd2;Method Invocation&xd3;
on page&numsp;18'--><xref role="SecTitleAndPageNum" linkend="RDMAP.archo.mkr.9">).
The user double-clicks on an action icon to invoke it.<indexterm>
<primary>desktop management</primary><secondary>application management &lt;$endrange></secondary></indexterm></para>
</sect2>
<sect2 id="RDMAP.archo.div.8">
<title>Object Management</title>
<para>T<literal><indexterm><primary>desktop management</primary><secondary>object management</secondary></indexterm><indexterm><primary>object management</primary></indexterm></literal>he Common Desktop Environment captures some
object-oriented system attributes without being dependent upon a completely
object-oriented infrastructure. The desktop provides graphic onscreen images
that the user can pick up and move about, dropping them anywhere it makes
semantic sense. These are viewed as <symbol role="Variable">objects</symbol>
by the user. The<indexterm><primary>File Manager</primary></indexterm> File
Manager promotes the object abstraction by providing a graphical way to browse
and modify file and directory objects within the file system. It also provides
a GUI to invoke actions. When the user selects a file, the actions that are
defined for the selected type of file are presented to the user.</para>
<para>Objects managed by desktop-based applications do not have to be file-based;
in-memory buffers can represent desktop objects, too. The Common Desktop
Environment Mailer handles<indexterm><primary>Multipurpose Internet Mail
Extensions (MIME)</primary></indexterm> Multipurpose Internet Mail Extensions
(MIME) messages by displaying attachments to a message as icons in a scrollable
panel. These are objects that behave just like file-based objects during
activities such as drag and drop. The user can drag between the File Manager
and the<indexterm><primary>Mailer</primary></indexterm> Mailer. Applications
that use drag and drop should maintain this important user model by supporting
both file-based and buffer-based objects. The desktop drag-and-drop API and
protocol make this straightforward.</para>
</sect2>
<sect2 id="RDMAP.archo.div.9">
<title>Window Management</title>
<para>The <literal><indexterm><primary>desktop management</primary><secondary>window management</secondary></indexterm><indexterm><primary>Window Manager &lt;$startrange></primary></indexterm></literal>Window
Manager is essentially the Motif window manager with extensions to provide
the<indexterm><primary>Front Panel</primary></indexterm> Front Panel GUI
and workspace abstraction.</para>
<para>The Front Panel can be thought of as a graphic version of the root window
menu supported by many window managers. It can also be thought of as a tuned
object manager in which common objects are readily available to the user.
The Front Panel can show dynamic system information, and it enables the user
to invoke actions and system functions. The user dynamically customizes the
Front Panel by dragging and dropping action icons from the<indexterm><primary>Application Manager</primary></indexterm> Application Manager and<indexterm>
<primary>File Manager</primary></indexterm> File Manager onto subpanels. Applications
can come equipped with special configuration files that extend the Front
Panel, possibly defining drop behavior, drop zone animation feedback, and
so on. The user can optionally install these configuration files depending
on customization preferences. <!--Original XRef content: 'Figure&numsp;1&hyphen;2'--><xref
role="CodeOrFigureOrTable" linkend="RDMAP.archo.mkr.6"> displays a typical
desktop Front Panel.</para>
<figure>
<title id="RDMAP.archo.mkr.6">Typical Front Panel</title>
<graphic id="RDMAP.archo.grph.1" entityref="RDMAP.archo.fig.2"></graphic>
</figure>
<para>Workspaces are abstractions supported by the Window Manager that can
be thought of as virtual desktops. Application windows exist within one,
some, or all available workspaces. The user usually determines which workspaces
an application window exists in as part of the user's customization. You
should rarely use the workspace API other than to explicitly designate in
which workspace your application appears on session restart. In general,
do not place your application within multiple workspaces, because this overrides
the user's prerogative.<indexterm><primary>desktop management</primary><secondary>window management</secondary></indexterm><indexterm>
<primary>Window Manager &lt;$endrange></primary></indexterm></para>
</sect2>
<sect2 id="RDMAP.archo.div.10">
<title>Style Management</title>
<para>The <literal><indexterm><primary>desktop management</primary><secondary>style management</secondary></indexterm><indexterm><primary>Style Manager &lt;$startrange></primary></indexterm></literal>Style
Manager enables users to customize their desktop using a GUI. Users are shielded
from advanced concepts, such as X resources, for most common customization
options. Style Manager provides controls for desktop-wide properties that
adjust backdrops, keyboard settings, mouse settings, screen saver options,
window management, and session management. These properties either do not
affect applications directly or indirectly affect them through the X server
or window manager.</para>
<para>You, as an application developer, are more directly influenced by font
choices, color choices, and input device mappings. The Motif toolkit and
the Common Desktop Environment handle many of these settings transparently
for widgets. However, your application will appear more integrated with the
rest of the desktop if it responds to user font and color preferences. Applications
that directly interact with the mouse will feel more integrated with the
rest of the desktop if they are consistent with other applications; for example,
by using the same mouse button double-click minimum interval value ( <command>multiClickTime</command> resource).</para>
<para>To accommodate differences between platform vendor's display technology
and available font sets, the Common Desktop Environment defines font aliases
that are indirect names to actual font names. Use these aliases in the same
way as the rest of desktop uses them.</para>
<para>The Style Manager provides the user with color selection options to
adjust the desktop color scheme. This color information is private to the
Common Desktop Environment. Applications doing widget subclassing can indirectly
access some of the color scheme by looking at inherited background pixel
values. A call to <computeroutput>XmGetColors()</computeroutput> generates
3-D shadow colors.</para>
<para>The Common Desktop Environment does not dictate color usage for static
colors, such as those used within icons. For these situations, however, your
application should attempt to use the colors offered by the Common Desktop
Environment Icon Editor, to enhance color sharing.<indexterm>
<primary>desktop management</primary><secondary>style management</secondary>
</indexterm><indexterm><primary>Style Manager &lt;$endrange></primary></indexterm></para>
</sect2>
</sect1>
<sect1 id="RDMAP.archo.div.11">
<title id="RDMAP.archo.mkr.7">Motif GUI Engine</title>
<para>Think of the Motif toolkit as the GUI engine of the desktop. This section
discusses Common Desktop Environment Motif, Common Desktop Environment widgets,
and alternative modes of Motif programming.</para>
<sect2 id="RDMAP.archo.div.12">
<title>Common Desktop Environment Motif Toolkit</title>
<para>The<indexterm><primary>graphical user interface engine</primary><secondary>Common Desktop Environment Motif Toolkit</secondary></indexterm><indexterm>
<primary>Common Desktop Environment Motif &lt;$startrange></primary></indexterm> Common Desktop Environment Motif
toolkit is Motif 1.2.3 with bug fixes, enhancements, and some new features.
You must explicitly set resources to enable the new features. Functional
additions include file selection box GUI modifications, different default
settings of existing resources (primarily to lighten up the default border
widths), color management enhancements, internationalization of error messages,
and minor usability fixes (some of which have the effect of easing migration
of<indexterm><primary>OPEN LOOK</primary></indexterm> OPEN LOOK users to
the Common Desktop Environment).</para>
<para>Common Desktop Environment Motif and<indexterm><primary>Motif 2.0</primary></indexterm> Motif 2.0 are also highly compatible. Most functions
put into Common Desktop Environment Motif have been introduced into Motif
2.0. As a result, developers have compiled their applications with Common
Desktop Environment Motif, relinked to Motif 2.0, and ran the applications
successfully. Widget subclassing that has not followed Motif 1.2 subclassing
guidelines designed to shield programs from widget size changes are likely
to fail.</para>
<para>A drag-and-drop convenience layer has been added on top of the Motif
1.2 drag-and-drop API. In addition, the Common Desktop Environment uses the
Motif 1.2 preregister drag feedback protocol. A drop site drag manager process
keeps track of visible drop zones on the desktop. This data is used by a
drag source client process to manage drag feedback interaction. Limited drag
time validation of drop zones is followed by full validation at drop time,
with <emphasis>snap- back-to-source</emphasis> animation if the drop fails.
</para>
<para>Common Desktop Environment Motif includes a GUI style guide and certification
checklist that has substantially expanded on the Motif 1.2 style guide. Additions
affect the input models, window management, and GUI design principles.<indexterm>
<primary>graphical user interface engine</primary><secondary>Common Desktop
Environment Motif Toolkit</secondary></indexterm><indexterm><primary>Common
Desktop Environment Motif &lt;$endrange></primary></indexterm></para>
</sect2>
<sect2 id="RDMAP.archo.div.13">
<title>Common Desktop Environment Motif Widgets</title>
<para><indexterm><primary>graphical user interface engine</primary><secondary>Common Desktop Environment Motif widgets</secondary></indexterm><indexterm>
<primary>Common Desktop Environment widgets</primary></indexterm>Common Desktop
Environment Motif provides two types of widgets that are not available in
Motif 1.2.3:</para>
<itemizedlist remap="Bullet1"><listitem><para>Low-level control widgets:
</para>
<itemizedlist remap="Bullet2"><listitem><para>SpinBox&mdash;A text field and
arrow button widget</para>
</listitem><listitem><para>ComboBox&mdash;A text field and list box widget
</para>
</listitem><listitem><para>MenuButton&mdash;A menu that doesn't need to be
in a row column widget</para>
</listitem></itemizedlist>
<para>These were added primarily to help you port applications from a Microsoft&reg;
Windows or OPEN LOOK environment. The SpinBox and ComboBox widgets have equivalents
in Motif 2.0.</para>
</listitem><listitem><para>Rich and full-featured widgets:</para>
<itemizedlist remap="Bullet2"><listitem><para>Terminal Emulator widget&mdash;Useful
for applications designed to mix the best of a command-line user interface
with a GUI</para>
</listitem><listitem><para>Editor widget&mdash;Available for embedding a more
full-featured plain text editor than that available from the Motif Text widget
</para>
</listitem><listitem><para>Help widgets&mdash;Handle navigation and interaction
with application help volumes</para>
<para>Help is delivered with an application in the form of<indexterm><primary>Semantic Description Language (SDL)</primary></indexterm> Semantic Description
Language (SDL) files that have been compiled from <emphasis><indexterm><primary>HelpTag</primary></indexterm>HelpTag</emphasis>, a form of<indexterm><primary>Standard Generalized Markup Language (SGML)</primary></indexterm> Standard
Generalized Markup Language (SGML) files. The Help system features mixed
text and graphics, hyper links, dynamic reformatting of text, and structured
navigation capabilities.</para>
</listitem></itemizedlist>
</listitem></itemizedlist>
</sect2>
<sect2 id="RDMAP.archo.div.14">
<title>GUI Shell</title>
<para>The<indexterm><primary>graphical user interface engine</primary><secondary>Desktop KornShell</secondary></indexterm><indexterm><primary>Desktop KornShell
(dtksh) &lt;$startrange></primary>
</indexterm> Common Desktop Environment includes Desktop KornShell, an interpreted
scripting language alternative to C programming of the Motif toolkit. Desktop
KornShell includes selected frequently-used Common Desktop Environment, Xt,
and Xlib APIs. You must use a compiled language to access the full power
of the environment. However, you can write Desktop KornShell scripts that
participate in desktop integration activities such as drag and drop, session
management, and ToolTalk messaging.</para>
<para>If you are comfortable with shell programming, you may prefer to use
Desktop KornShell for modest programming tasks because it is:</para>
<itemizedlist remap="Bullet1"><listitem><para>Well suited to system-administration-type
applications because the shell commands intermix easily with GUI control.
</para>
</listitem><listitem><para>Good for putting a GUI control program on top of
character-based applications because the shell environment handles character-based
interaction in a natural way.</para>
</listitem><listitem><para>A good way to deliver instruction-set-independent
programs to a heterogeneous collection of hosts. For example, use the Common
Desktop Environment<indexterm><primary>Mailer</primary></indexterm> Mailer
to attach a script to a message that the recipient simply double-clicks to
invoke.<indexterm><primary>graphical user interface engine</primary><secondary>Desktop KornShell</secondary></indexterm><indexterm><primary>Desktop KornShell
(dtksh) &lt;$endrange></primary>
</indexterm></para>
</listitem></itemizedlist>
</sect2>
<sect2 id="RDMAP.archo.div.15">
<title>GUI Construction</title>
<para>The<indexterm><primary>graphical user interface engine</primary><secondary>Application Builder</secondary></indexterm><indexterm><primary>Application
Builder &lt;$startrange></primary>
</indexterm> easiest way to produce a Common Desktop Environment application,
and perhaps the fastest, is to do almost no Motif toolkit programming at
all. Use the Common Desktop Environment Application Builder, also known as
App Builder, to construct the GUI control portion of your application. App
Builder focuses on making default widget behavior easy to access. It does
this by hiding many of the more esoteric resources that are available on
most widgets. App Builder also makes it as easy to incorporate desktop integration
infrastructure into your application, including drag and drop, session management,
and ToolTalk messaging.</para>
<para>App Builder maintains the user interface state in<indexterm><primary>Builder Interface Language (BIL)</primary></indexterm> Builder Interface Language
(BIL) files. A code generator takes the BIL files and produces Motif toolkit
code. App Builder can also generate<indexterm><primary>User Interface Language
(UIL)</primary></indexterm> User Interface Language (UIL) files.</para>
<para>As you make changes to your application's user interface, App Builder
merges your custom code with the code it generates. Generated code is a good
source of example code, even if you do not using App Builder to maintain
your application's GUI state.</para>
<para>In addition, nonprogrammers can use App Builder to produce an application
GUI prototype. The prototype can roll forward to programmers for the production
phase of development.<indexterm><primary>graphical user interface engine</primary><secondary>Application Builder</secondary></indexterm><indexterm>
<primary>Application Builder &lt;$endrange></primary></indexterm></para>
</sect2>
</sect1>
<sect1 id="RDMAP.archo.div.16">
<title id="RDMAP.archo.mkr.8">Integration Technologies</title>
<para>Common Desktop Environment technologies discussed thus far have been
directly involved with putting a GUI onto the screen. The integration technologies
described in this section are underlying infrastructure, not GUI providers.
</para>
<sect2 id="RDMAP.archo.div.17">
<title>Process Execution<indexterm><primary>integration technologies</primary>
<secondary>process execution</secondary></indexterm><indexterm><primary>process
execution</primary></indexterm></title>
<para>To provide a network-leveraging environment, the Common Desktop Environment
provides the<indexterm><primary>Sub Process Control (SPC)</primary></indexterm> Sub
Process Control (SPC) mechanism to start, manage, and collect results from
applications running on a remote host. A remote host installs an SPC daemon
that serves as the remote end of a socket- based control mechanism. This control
mechanism tries to maintain the illusion that the remote process is a local <symbol role="Variable">child</symbol> to the <symbol role="Variable">parent</symbol>
process. Authentication of the user that owns the parent process is based
upon the ability of the parent process to write a <command>setuid</command>
file to the user's home directory <emphasis>and</emphasis> the ability of
the child process to read the result.</para>
<para>The SPC API and associated control programs are private to the Common
Desktop Environment. Actions represent the public API for running applications
remotely.</para>
</sect2>
<sect2 id="RDMAP.archo.div.18">
<title>Application Messaging<indexterm><primary>integration technologies</primary>
<secondary>application messaging</secondary></indexterm><indexterm><primary>ToolTalk Messaging Service &lt;$startrange></primary></indexterm></title>
<para>The ToolTalk Messaging Service is the application messaging mechanism
for the Common Desktop Environment. Application messaging addresses inter-
application control and cooperation for applications working on behalf of
a single user. The ToolTalk session daemon is a local message-routing process
whose control scope typically corresponds to that of the X server. This means
that clients within a session issue requests, the ToolTalk session manager
finds or starts some client within a session that is able to handle the request,
and the ToolTalk session daemon tracks the request until completion.</para>
<para>The desktop provides two standard ToolTalk protocols known as <emphasis>messages sets</emphasis>. A message set contains a number of messages that
can be exchanged between a sender and a handler process. These messages are
grouped together because they describe related requests and notices. The
sender and recipient may be within the same process or on different hosts.
Message sets have associated utility functions that allow you to concentrate
on the semantics of the protocol without getting involved in the low-level
messaging details. Some of the message set functions enable you to defer
to default behavior with almost no work on your part.</para>
<sect3 id="RDMAP.archo.div.19">
<title>Desktop Message Set</title>
<para>The Desktop Message Set encompasses three areas. The first is windowing
behavior. The second involves file access and short term file life cycle
control. The third is specific to applications that have extension languages
and is not generic enough to warrant library support.</para>
</sect3>
<sect3 id="RDMAP.archo.div.20">
<title>Media Message Set</title>
<para>The Media Message Set allows an application to be a container for arbitrary
media, or to be a media player/editor that can be driven from such a container.
The Media message interface allows a container application (such as<indexterm>
<primary>Mailer</primary></indexterm> Mailer or<indexterm><primary>File Manager</primary></indexterm> File Manager) to compose, display, edit, or print a
file or buffer of an arbitrary media type, without understanding anything
about the format of that media type. ToolTalk 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.<indexterm>
<primary>integration technologies</primary><secondary>application messaging</secondary></indexterm><indexterm><primary>ToolTalk Messaging Service &lt;$endrange></primary></indexterm></para>
</sect3>
</sect2>
<sect2 id="RDMAP.archo.div.21">
<title>Data Typing<indexterm><primary>data typing &lt;$startrange></primary></indexterm></title>
<para>The Common Desktop Environment provides a uniform user interface to
the objects contained on the desktop. To do this, the desktop has a mechanism,
called data typing, to determine an object's type using a set of criteria.
The criteria includes properties potentially shared by file-based and buffer-based
objects such as name pattern and content pattern. Other criteria are exclusive
to files, and include path-name pattern and file permissions. Associated
with every desktop type is an extensible set of attributes, including icon
name, name template pattern, list of actions suitable for presentation to
a user, equivalent type names for other type spaces (for example, MIME type),
and a textual description of this type. The <emphasis>actions and data-types
database</emphasis> stores data criteria and data attributes.</para>
<para>The Common Desktop Environment defines, and platform vendors supply,
a set of desktop type definitions. Your application should augment the database
with both proprietary and public data types at application installation time.
</para>
<para>Information is extracted from the actions and data-types through a Common
Desktop Environment library API. The data typing API matches an object's
properties with the database type criteria to determine the object's desktop
type. The matching algorithm uses a set of precedence rules to resolve conflicts.
</para>
<para>The Common Desktop Environment type space is defined by the X/Open
Common Desktop Environment standard and exists primarily to support desktop-oriented
activities such as icon display and action association. The MIME type space
is defined by the Internet Engineering Task Force and exists to deal with
exchange of mail message parts. A ToolTalk media type space exists in order
to match data with handlers, and is a subset of X selection target types
defined by the X Consortium. Thus, to do a complete job of type definition,
you have to define a Common Desktop Environment type, X selection target,
and MIME type. For private Common Desktop Environment types, append the type
name to an organization's name. This partitions the name space without need
for centralized allocation of types. The Common Desktop Environment claims
the <emphasis>Dt</emphasis> prefix, for <emphasis>Desktop</emphasis>.<indexterm>
<primary>data typing &lt;$endrange></primary></indexterm></para>
</sect2>
<sect2 id="RDMAP.archo.div.22">
<title id="RDMAP.archo.mkr.9">Method Invocation<indexterm><primary>actions &lt;$startrange></primary></indexterm></title>
<para>A Common Desktop Environment type can be thought of as the class of
a desktop object. Using this analogy, actions can be thought of as the<indexterm>
<primary>methods, and actions</primary></indexterm> methods available on instances
of a class. Thus, the actions attribute in a type attribute list describes
operations that are available for the type. A single action in the actions
and data-types database has multiple parts, many of which are optional. These
parts include:</para>
<itemizedlist remap="Bullet1"><listitem><para>A description of how to invoke
the operation: for example, through ToolTalk, through an execution string
passed to the SPC mechanism, from within a terminal emulator, and so on.
</para>
</listitem><listitem><para>A description of the type of arguments associated
with the action. The type of the desktop objects (files and buffers) that
it accepts is defined by the actions and data-types database. Actions are
polymorphic with respect to data types. For example, the Open action invokes
a text editor for arguments that are text files and a graphics editor for
arguments that are graphics files.</para>
</listitem><listitem><para>A description of the number of arguments, if any,
associated with the action.</para>
</listitem><listitem><para>An optional indication as to where to carry out
the operation: the local machine, a particular remote machine, the machine
on which the executable resides, and so on. In addition, these execution
locations can be included in a list so that if a host is not available then
the next host on the list is tried. This provides a measure of redundancy
that can be used to increase the likelihood of application launch, even in
the face of remote host unavailability. Thus, actions provide network distribution
guidance, implemented either through built-in ToolTalk facilities or through
the SPC mechanism directly.</para>
</listitem><listitem><para>An optional label, help string, and icon that the
user sees when interacting with the action's GUI. These are hints to an application
about how to represent the action to the user. These hints may be ignored,
as the Front Panel does by ignoring the icon if the Front Panel configuration
file supplies an alternative icon.</para>
</listitem></itemizedlist>
<para>The collection of actions available to the user is assembled at the
same time as the system is collecting type database information. In fact,
related action and type information usually reside together in the same file.
Desktop-defined, system-administrator-defined (host-specific), and user-defined
files are assembled in order into a single (actions and data-types) database,
with later definitions taking precedence. This ordering of search path precedence
and traversal is used elsewhere by the desktop for such things as help volume
and icon file searches.</para>
<para>The actions and data-types<indexterm><primary>database</primary></indexterm> database
and the File Manager use action files to instantiate actions as file system
objects that can be viewed, invoked, moved, copied, and so on. The database
contains references to an action's implementation (for example &ldquo;run <filename>/usr/bin/app</filename> on machine <filename>net_app_svr</filename>&rdquo;).
However, a representation is needed of an action as an object that the user
can directly manipulate. This is achieved by using an object's name, which
identifies it as an action to any object manager that is looking for actions.
Thus, if there is an executable file named <command>Dtstyle</command> and
an action named Dtstyle, the File Manager will interpret that file, regardless
of its content, as the Dtstyle action reference. In addition, the File Manager
uses the action's label as the name that the user sees for this file. Action
labels are localizable, whereas action names are programmatic entities that
should not be localized.</para>
<para>The good feature about using files simply as pointers into the actions
and data- types database is that the underlying implementation can evolve
without the user having to do anything. However, one user's actions and data-types
database may not match another user's actions and data-types database. Thus,
a user cannot exchange an action reference, for example as a mail message
attachment, and expect another person to have a comparable definition for
that action. Exchanging a Desktop KornShell script is the best solution to
this problem.</para>
<para>Actions are useful because they integrate both legacy command-line
applications and ToolTalk applications into the desktop as polymorphic, distributed
operations on desktop objects.<literal><indexterm><primary>actions &lt;$endrange></primary>
</indexterm></literal></para>
</sect2>
</sect1>
<sect1 id="RDMAP.archo.div.23">
<title id="RDMAP.archo.mkr.10">Information Technologies</title>
<para>CDE information technologies comprise
</para>
<itemizedlist>
<listitem>
<para>The Help system, which provides help on the CDE user interface, and potentially,
the help you provide for your CDE applications.
</para>
</listitem>
<listitem>
<para>The Information Manager, an on-line documentation access facility
that provides access to CDE documentation, and potentially, your application-specific documentation.
</para>
</listitem>
</itemizedlist>
<sect2 id="RDMAP.archo.div.24">
<title id="RDMAP.archo.mkr.11">Help System</title>
<indexterm><primary>help</primary><secondary>general information</secondary></indexterm>
<para>The Help system provides a complete set of authoring and programming
tools to develop on-line help for CDE applications:
</para>
<itemizedlist>
<listitem>
<para>It enables authors to include formatted text, graphics, hyperlinks, and communication
with the application.
</para>
</listitem>
<listitem>
<para>It provides programmers with a toolkit for integrating on-line
help into an application. The toolkit includes specialized Help dialogs and supporting
routines that enable users to display, navigate, search, and print on-line help.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="RDMAP.archo.div.25">
<title id="RDMAP.archo.mkr.12">Information Manager</title>
<indexterm><primary>information manager</primary><secondary>general information</secondary></indexterm>
<para>The Information Manager provides on-line access to documentation organized into hierarchies
of information libraries, bookcases, books, book sections, and smaller divisions of documentation.
All CDE documentation is shipped with the Information Manager.
</para>
<para>To integrate application-specific documentation with the Information Manager,
a CDE application calls a small API (<Symbol>DtInfo</Symbol>).
Alternatively, programmers may
develop their own browsers using the DtInfo Database Engine API (<Symbol>DtMmdb</Symbol>).
</para>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->

428
cde/doc/C/guides/progOview/ch02.sgm Normal file
View File

@@ -0,0 +1,428 @@
<!-- $XConsortium: ch02.sgm /main/10 1996/09/08 19:46:32 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<chapter id="RDMAP.consi.div.1">
<title id="RDMAP.consi.mkr.1">Development Environment Considerations</title>
<para>This chapter discusses general information you should know before starting
to use the Common Desktop Environment application program interfaces (APIs).
</para>
<para>Before you integrate your application into the desktop, you should have
a basic understanding of how the desktop works. Install the Common Desktop
Environment on your platform and familiarize yourself with its features.
For an introduction to the desktop, see the <emphasis>User's Guide</emphasis>
or the <emphasis>Desktop Introduction</emphasis> online help volume.</para>
<informaltable id="RDMAP.consi.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Common Desktop Environment Characteristics24'--><xref
role="JumpText" linkend="RDMAP.consi.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Underlying Foundations25'--><xref
role="JumpText" linkend="RDMAP.consi.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Running Existing Applications26'--><xref
role="JumpText" linkend="RDMAP.consi.mkr.4"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Libraries and Header Files27'--><xref
role="JumpText" linkend="RDMAP.consi.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Demo Programs27'--><xref role="JumpText"
linkend="RDMAP.consi.mkr.6"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Man Pages27'--><xref role="JumpText"
linkend="RDMAP.consi.mkr.7"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Development Environment Directory
Structure28'--><xref role="JumpText" linkend="RDMAP.consi.mkr.8"></para></entry>
</row></tbody></tgroup></informaltable>
<sect1 id="RDMAP.consi.div.2">
<title id="RDMAP.consi.mkr.2">Common Desktop Environment Characteristics</title>
<para>The Common Desktop Environment provides a productive and comfortable
desktop environment for UNIX users. As you develop your application, keep
in mind the experience that the Common Desktop Environment delivers to its
users. Develop your application with the following<indexterm><primary>guidelines</primary><secondary>application development</secondary></indexterm><indexterm>
<primary>goals for desktop look and feel</primary></indexterm><indexterm>
<primary>application development</primary><secondary>guidelines &lt;$startrange></secondary></indexterm> characteristics
in mind, to help make it a powerful, consistent, and predictable part of
the Common Desktop Environment:</para>
<itemizedlist remap="Bullet1"><listitem><para>Hide the complexities of UNIX.<indexterm>
<primary>UNIX</primary></indexterm></para>
<para>Because the Common Desktop Environment targets end users as its primary
customers, providing an application that hides UNIX as much as possible is
a key ingredient to a successful product.</para>
</listitem><listitem><para>Provide a common look and feel.<indexterm><primary>look and feel</primary></indexterm></para>
<para>Successful applications in the Common Desktop Environment share look-
and-feel characteristics with other applications on the desktop. Follow the
style and other guidelines (such as the Common Desktop Environment standard
font names) so that your application encompasses the Common Desktop Environment
Motif look and feel.</para>
</listitem><listitem><para>Make applications easy to use.<indexterm><primary>ease of use</primary></indexterm></para>
<para>Provide an easily readable default font size, and provide keyboard
accelerators for mouse-oriented actions. Use the desktop online help component
to integrate a complete Help system into your application. Basic computer
interaction styles should be consistent across platforms wherever possible.
</para>
</listitem><listitem><para>Take advantage of desktop integration services.<indexterm>
<primary>desktop</primary><secondary>integration services</secondary></indexterm><indexterm>
<primary>integration</primary><secondary>services, desktop</secondary></indexterm><indexterm>
<primary>services, desktop integration</primary></indexterm></para>
<para>The Common Desktop Environment provides a set of desktop integration
services that enable applications to be well-integrated into the desktop.
Users benefit because they do not have to know whether an application is
running on a local machine or somewhere on the network, or which toolkit
(if any) was used to write the application they are running. Provide mechanisms
in your application that enable it to be launched from the desktop and to
communicate with other Common Desktop Environment applications. Use the online
Help system to provide users with quick information. Use drag and drop to
provide users with a more predictable way to use their systems.</para>
</listitem><listitem><para>Design for individual and cultural differences.
</para>
<para>By following the Common Desktop Environment conventions and policies,
your application will naturally provide for smooth, consistent, and appropriate
customization of:<indexterm><primary>customization</primary><secondary>of
desktop</secondary></indexterm><indexterm><primary>desktop</primary><secondary>customization</secondary></indexterm></para>
<itemizedlist remap="Bullet2"><listitem><para>Fonts</para>
</listitem><listitem><para>Color</para>
</listitem><listitem><para>Keyboard and mouse bindings</para>
</listitem><listitem><para>Locale-specific configuration files</para>
<para>For more about locale-specific configuration files, see the localization
section of the <emphasis>Advanced User's and System Administration Guide</emphasis> .<indexterm><primary>guidelines</primary><secondary>for application
development</secondary></indexterm><indexterm><primary>goals for desktop
look and feel</primary></indexterm><indexterm><primary>application development</primary><secondary>guidelines &lt;$endrange></secondary></indexterm></para>
</listitem></itemizedlist>
</listitem></itemizedlist>
</sect1>
<sect1 id="RDMAP.consi.div.3">
<title id="RDMAP.consi.mkr.3">Underlying Foundations</title>
<para>To compile an application that uses the desktop APIs, you need:<indexterm>
<primary>compiling</primary><secondary>an application</secondary></indexterm><indexterm>
<primary>software requirements, for application development</primary></indexterm><indexterm>
<primary>requirements (software), for application development</primary></indexterm><indexterm>
<primary>application development</primary><secondary>required software</secondary>
</indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para>Common Desktop Environment header
files and libraries</para>
</listitem><listitem><para>X11R6.2 or later header files and libraries<indexterm>
<primary>X11R6.2</primary></indexterm></para>
</listitem><listitem><para>ANSI C compiler; or C++ compiler, version 2.0 or
later, if you are developing a C++ application<indexterm><primary>compilers,
used for application development</primary></indexterm><indexterm><primary>ANSI C</primary></indexterm><indexterm><primary>C++</primary></indexterm></para>
</listitem></itemizedlist>
<para>The resulting binary file must be run in an environment in which matching
libraries are installed. The run-time libraries are in <filename>/usr/dt/lib</filename>, and they include the directories listed in <!--Original XRef
content: 'Table&numsp;2&hyphen;2 on page&numsp;28'--><xref role="CodeOrFigOrTabAndPNum"
linkend="RDMAP.consi.mkr.9">.</para>
<para>To run properly, Common Desktop Environment-based applications require
an environment in which some files from the following run-time directories
are installed:<indexterm><primary>run-time</primary><secondary>directories,
and running applications</secondary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para><filename>/etc/dt/*</filename></para>
</listitem><listitem><para><filename>/var/dt/*</filename></para>
</listitem><listitem><para>The following subdirectories of <filename>/usr/dt</filename>:</para>
<itemizedlist remap="Bullet2"><listitem><para><filename>app-defaults</filename></para>
</listitem><listitem><para><command>appconfig</command></para>
</listitem><listitem><para><command>bin</command></para>
</listitem><listitem><para><command>dthelp</command></para>
</listitem><listitem><para><command>lib</command></para>
</listitem></itemizedlist>
</listitem></itemizedlist>
<para>Your application should depend on only those run-time files <emphasis>explicitly</emphasis> mentioned in the X/Open XCDE standard. It should <symbol role="Variable">not</symbol> depend on files not mentioned in the standard;
for example, <filename>/usr/dt/appconfig/icons</filename>. If you build such
dependencies into your application, it should be robust enough to run in
an environment in which such files are missing or have changed.</para>
<para>For a listing of the minimum run-time environment required to run a
Common Desktop Environment application, see the <filename>dtfilsys(5)</filename>
man page.</para>
<para>The run-time environment includes Common Desktop Environment Motif,
which is Motif 1.2.3 with bug fixes and enhancements.
For more information on the Common Desktop Environment run-time environment,
see the run-time documentation set.<indexterm><primary>run-time</primary>
<secondary>environment</secondary></indexterm></para>
</sect1>
<sect1 id="RDMAP.consi.div.4">
<title id="RDMAP.consi.mkr.4">Running Existing Applications<indexterm><primary>applications, running existing</primary></indexterm><indexterm><primary>existing applications, and Common Desktop Environment</primary></indexterm></title>
<para>Existing<indexterm><primary>X-based applications</primary></indexterm> X
Window System-based applications that are not compiled with any Common Desktop
Environment libraries run under the desktop window manager (<command>dtwm</command>) similarly to the way they run under the Motif window manager:
they still work. The level of interoperability with the Common Desktop Environment
follows these guidelines.</para>
<table id="rdmap.consi.tbl.1" frame="topbot">
<title>Interoperability of Existing X-Based Applications with the Common
Desktop Environment</title>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="3.35in">
<colspec align="left" colwidth="2.92in">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Characteristics of
Existing X-based Applications</literal></para></entry><entry align="left"
valign="bottom"><para><literal>Interoperability Status with Desktop</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>Motif 1.2 (and later) drag and drop
(using preregister protocol)</para></entry>
<entry align="left" valign="top"><para>Yes</para></entry></row>
<row>
<entry align="left" valign="top"><para>Motif 1.2 (and later) drag and drop
(using dynamic protocol)</para></entry>
<entry align="left" valign="top"><para>No<footnoteref linkend="rdmap.consi.fn.10"></footnoteref> <footnote
id="rdmap.consi.fn.10"><para>This is a Motif 1.2 drag-and-drop dynamic protocol
interoperability problem, and it is <symbol role="Variable">not</symbol> due
to the Common Desktop Environment.</para>
</footnote></para></entry></row>
<row>
<entry align="left" valign="top"><para>Cut and paste (all applications)</para></entry>
<entry align="left" valign="top"><para>Yes</para></entry></row>
<row>
<entry align="left" valign="top"><para>OPEN LOOK drag and drop</para></entry>
<entry align="left" valign="top"><para>Yes (except multiple-item drag and
drop)<footnoteref linkend="rdmap.consi.fn.11"></footnoteref> <footnote id="rdmap.consi.fn.11">
<para>This is implemented through a protocol translation mechanism in the
drop site database manager (<command>dsdm</command>).</para>
</footnote></para></entry></row>
<row>
<entry align="left" valign="top"><para>ToolTalk Media Exchange and Desktop
protocols</para></entry>
<entry align="left" valign="top"><para>Yes</para></entry></row></tbody></tgroup>
</table>
<para>If you want to recompile and relink an existing Motif application with
the Common Desktop Environment Motif shared libraries, the application must
be compatible with Motif 1.2.<indexterm><primary>Motif 1.2</primary></indexterm></para>
</sect1>
<sect1 id="RDMAP.consi.div.5">
<title id="RDMAP.consi.mkr.5">Libraries and Header Files<indexterm><primary>libraries, development environment</primary></indexterm><indexterm><primary>header files, development environment</primary></indexterm></title>
<para>Compile Common Desktop Environment applications against X11R6.2 header
files and libraries, which reside in vendor-specific locations. <!--Original
XRef content: 'Table&numsp;2&hyphen;2 on
page&numsp;28'--><xref role="CodeOrFigOrTabAndPNum" linkend="RDMAP.consi.mkr.9">
lists the locations of all development environment libraries and header files,
as subdirectories of <filename>/usr/dt</filename>.</para>
</sect1>
<sect1 id="RDMAP.consi.div.6">
<title id="RDMAP.consi.mkr.6">Demo Programs<indexterm><primary>demo programs</primary></indexterm><indexterm><primary>sample programs</primary></indexterm><indexterm>
<primary>example programs</primary></indexterm><indexterm><primary>programs,
demo</primary></indexterm></title>
<para>The <filename>/usr/dt/examples</filename> subdirectories contain source
code for development environment component demos, as well as a <emphasis>template</emphasis> application. See <!--Original XRef content: 'Table&numsp;2&hyphen;2
on page&numsp;28'--><xref role="CodeOrFigOrTabAndPNum" linkend="RDMAP.consi.mkr.9">
for a listing of all demo subdirectories.</para>
<para>Each demo subdirectory contains source files for one or more demo programs,
along with makefiles for the programs. It also contains a <command>README</command> file that describes the demos.</para>
<para>The demo whose source is in the <command>template</command> subdirectory
is a simple drawing program. This demo illustrates the basic structure of
a Common Desktop Environment application that is integrated with the desktop.
It is internationalized and contains all localized components in a separate
subdirectory. You can use the drawing program source as a template for your
application.</para>
</sect1>
<sect1 id="RDMAP.consi.div.7">
<title id="RDMAP.consi.mkr.7">Man Pages</title>
<para>The Common Desktop Environment man pages reside in <filename>/usr/dt/man</filename>. To view them using either the <filename>man()</filename> command
or the desktop man page viewer, you must add <filename>/usr/dt/man</filename>
to the <command>MANPATH</command> environment variable. For example, in your <filename>~/.dtprofile</filename> file, set:</para>
<programlisting>MANPATH = $MANPATH:/usr/dt/man</programlisting>
<para>For a listing of the <filename>/usr/dt/man</filename> subdirectories
and contents, see <!--Original XRef content: 'Table&numsp;2&hyphen;2'--><xref
role="CodeOrFigureOrTable" linkend="RDMAP.consi.mkr.9">. For more information
on the <filename>man()</filename> command, see the <filename>man</filename>(1)
man page.</para>
</sect1>
<sect1 id="RDMAP.consi.div.8">
<title id="RDMAP.consi.mkr.8">Development Environment Directory Structure<indexterm>
<primary>directory structure &lt;$startrange></primary></indexterm></title>
<para><!--Original XRef content: 'Table&numsp;2&hyphen;2'--><xref role="CodeOrFigureOrTable"
linkend="RDMAP.consi.mkr.9"> lists the top-level directories in the development
environment directory structure and lists their subdirectories. (All of the
top-level directory names are prefixed by <filename>/usr/dt</filename>.)
</para>
<table id="rdmap.consi.tbl.2" frame="topbot">
<title id="rdmap.consi.mkr.9">Development Environment Directories in /usr/dt</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colwidth="1.22in">
<colspec colwidth="1.71in">
<colspec colwidth="4.13in">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Directory</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Subdirectory</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Contents</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para><command>examples</command></para></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>Subdirectories that contain source
code for development environment component demo programs</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>README file</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtaction</para></entry>
<entry align="left" valign="top"><para>Action invocation API demos</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtbuilder</para></entry>
<entry align="left" valign="top"><para>Application Builder examples</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtcalendar</para></entry>
<entry align="left" valign="top"><para>Calendar API demos</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtdnd</para></entry>
<entry align="left" valign="top"><para>Drag-and-drop API demos</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtdts</para></entry>
<entry align="left" valign="top"><para>Data-typing API demos</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dthelp</para></entry>
<entry align="left" valign="top"><para>Help API demos</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtksh</para></entry>
<entry align="left" valign="top"><para><command>dtksh</command> example scripts
</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtsession</para></entry>
<entry align="left" valign="top"><para>Session Manager API demos</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtterm</para></entry>
<entry align="left" valign="top"><para>Terminal Emulator widget API demos
</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtwidget</para></entry>
<entry align="left" valign="top"><para>Common Desktop Environment Motif widgets
demos</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>dtwsm</para></entry>
<entry align="left" valign="top"><para>Workspace Manager API demos</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>template</para></entry>
<entry align="left" valign="top"><para>Template Common Desktop Environment
application</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>motif</para></entry>
<entry align="left" valign="top"><para>Motif 1.2 API demos</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>motif/clipboard</para></entry>
<entry align="left" valign="top"><para><command>XmClipboard</command> API
demo</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>motif/dogs</para></entry>
<entry align="left" valign="top"><para>Widget binary compatibility mechanism
demo</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>motif/draganddrop</para></entry>
<entry align="left" valign="top"><para>Motif 1.2 drag-and-drop API demo</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>motif/periodic</para></entry>
<entry align="left" valign="top"><para>Motif widgets demo</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>tt</para></entry>
<entry align="left" valign="top"><para>ToolTalk Messaging Service demos</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>include<indexterm><primary>header files</primary></indexterm></command></para></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>Development environment library header
files</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>csa</para></entry>
<entry align="left" valign="top"><para>Calendar header files</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><command>Dt</command></para></entry>
<entry align="left" valign="top"><para>Header files for <command>DtSvc</command>, <command>DtWidget</command>, <command>DtHelp</command>, and</para><para><command>DtTerm</command></para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><command>Mrm</command></para></entry>
<entry align="left" valign="top"><para>Motif 1.2 resource manager header files
</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><command>Tt</command></para></entry>
<entry align="left" valign="top"><para>ToolTalk Messaging Service header files
</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><command>Xm</command></para></entry>
<entry align="left" valign="top"><para>Motif 1.2 toolkit header files</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><command>uil</command></para></entry>
<entry align="left" valign="top"><para>Motif 1.2-callable UIL compiler header
files</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>lib</command><indexterm><primary>libraries, development environment</primary></indexterm></para></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>Library files for <command>libcsa</command>
(Calendar),</para><para><command>libDtHelp</command> (Help system),</para><para><command>libDtSvc</command> (actions, data typing, drag and drop, Session Manager,
Workspace Manager),</para><para><command>libDtTerm</command> (Terminal Emulator),
</para><para><command>libDtWidget</command> (Common Desktop Environment Motif
control and editor widgets),</para><para><command>libMrm</command> (Motif
1.2 resource manager),</para><para><command>libUil</command> (Motif 1.2-callable
UIL compiler),</para><para><command>libXm</command> (Motif 1.2 toolkit),
</para><para><command>libtt</command> (ToolTalk)</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>man<indexterm><primary>man
pages</primary></indexterm></command></para></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>Development environment man pages</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><filename>man1</filename></para></entry>
<entry align="left" valign="top"><para>Client and utility man pages</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><filename>man3</filename></para></entry>
<entry align="left" valign="top"><para>API man pages</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><filename>man4</filename></para></entry>
<entry align="left" valign="top"><para>Data formats</para></entry></row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para><filename>man5</filename></para></entry>
<entry align="left" valign="top"><para>Header file and action man pages<literal><indexterm>
<primary>directory structure &lt;$endrange></primary></indexterm></literal></para></entry></row></tbody></tgroup><?Pub Caret>
</table>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->
<?Pub *0000026382>

289
cde/doc/C/guides/progOview/ch03.sgm Normal file
View File

@@ -0,0 +1,289 @@
<!-- $XConsortium: ch03.sgm /main/9 1996/09/08 19:46:41 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<chapter id="RDMAP.devap.div.1">
<title id="RDMAP.devap.mkr.1">Developing an Application</title>
<para>This chapter presents information specific to developing a Common Desktop
Environment application, such as naming conventions and other guidelines.
It introduces levels of integration, which are the guidelines for determining
the desktop functionality to incorporate into your application to make it
increasingly integrated with the desktop. It also provides an overview of
the Application Builder, a tool to simplify Common Desktop Environment application
development.</para>
<informaltable id="RDMAP.devap.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Levels of Desktop Integration32'--><xref
role="JumpText" linkend="RDMAP.devap.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Desktop Naming Conventions32'--><xref
role="JumpText" linkend="RDMAP.devap.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Public and Private Interfaces33'--><xref
role="JumpText" linkend="RDMAP.devap.mkr.6"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Guidelines for Common Desktop Environment
Databases34'--><xref role="JumpText" linkend="RDMAP.devap.mkr.7"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Application Initialization and libDtSvc34'--><xref
role="JumpText" linkend="RDMAP.devap.mkr.8"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Application Builder34'--><xref role="JumpText"
linkend="RDMAP.devap.mkr.9"></para></entry></row></tbody></tgroup></informaltable>
<sect1 id="RDMAP.devap.div.2">
<title id="RDMAP.devap.mkr.2">Levels of Desktop Integration<indexterm><primary>desktop</primary><secondary>integration, levels of</secondary></indexterm><indexterm>
<primary>integration</primary><secondary>levels of</secondary></indexterm><indexterm>
<primary>application development</primary><secondary>levels of integration</secondary></indexterm></title>
<para>Users can run any<indexterm><primary>X-based applications</primary>
</indexterm> X11-based application from a shell command line in the Common
Desktop Environment. If you want to integrate your application into the desktop,
however, there are guidelines for you to follow. The Common Desktop Environment
defines three levels of integration to give you maximum flexibility in designing
your application or porting an existing application:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Basic Integration</emphasis> &mdash;Enables your application to be launched from the desktop.
You do <emphasis>not</emphasis> need to change your application code to perform
basic integration. See <!--Original XRef content: 'Chapter&numsp;5, &xd2;Basic
Application Integration'--><xref role="ChapNumAndTitle" linkend="RDMAP.BIntg.mkr.1">,
for more information.<indexterm><primary>basic integration</primary></indexterm><indexterm>
<primary>levels of integration</primary><secondary>basic</secondary></indexterm></para>
</listitem><listitem><para><emphasis>Recommended Integration</emphasis>&mdash;Enables
your application to enhance its level of consistency with the desktop. See
<!--Original XRef content: 'Chapter&numsp;6, &xd2;Recommended Integration'--><xref
role="ChapNumAndTitle" linkend="RDMAP.recin.mkr.1">, for more information.<indexterm>
<primary>recommended integration</primary></indexterm><indexterm><primary>levels of integration</primary><secondary>recommended</secondary></indexterm></para>
</listitem><listitem><para><emphasis>Optional Integration</emphasis>&mdash;Enables
you to leverage services provided by the desktop for achieving specialized
tasks. See <!--Original XRef content: 'Chapter&numsp;7, &xd2;Optional
Integration'--><xref role="ChapNumAndTitle" linkend="RDMAP.optin.mkr.1">,
for more information.<indexterm><primary>optional integration</primary></indexterm><indexterm>
<primary>levels of integration</primary><secondary>optional</secondary>
</indexterm></para>
</listitem></itemizedlist>
<para>For more information on all three levels of integration, see the <emphasis>Programmer's Guide.</emphasis> Basic Integration is also discussed in the <emphasis>Advanced User's and System Administrator's Guide</emphasis>.</para>
</sect1>
<sect1 id="RDMAP.devap.div.3">
<title id="RDMAP.devap.mkr.3">Desktop Naming Conventions<indexterm><primary>desktop</primary><secondary>naming conventions</secondary></indexterm><indexterm>
<primary>naming conventions</primary><secondary>desktop</secondary></indexterm><indexterm>
<primary>conventions, desktop naming</primary></indexterm><indexterm><primary>application development</primary><secondary>desktop naming conventions &lt;$startrange></secondary></indexterm></title>
<para>The Common Desktop Environment uses naming conventions similar to those
used by X and Motif. Desktop clients, desktop libraries, and other desktop
components share a common prefix for externally visible names: <command>dt</command>, <command>Dt</command>, or <command>DT</command>. Private desktop
structures, functions, and defines (found in the Common Desktop Environment
code; not for developer use) have an <filename>_dt</filename>, <filename>_Dt</filename>, or <filename>_DT</filename> prefix. <!--Original XRef content:
'Table&numsp;3&hyphen;1'--><xref role="CodeOrFigureOrTable" linkend="RDMAP.devap.mkr.4">
lists the desktop naming conventions.</para>
<table id="RDMAP.devap.tbl.1" frame="Topbot">
<title id="RDMAP.devap.mkr.4">Desktop Naming Conventions</title>
<tgroup cols="3" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.69in">
<colspec colwidth="207*">
<colspec colwidth="83*">
<colspec colwidth="262*">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Name</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Prefix</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Example</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>Desktop clients and utilities</para></entry>
<entry align="left" valign="top"><para><command>dt</command></para></entry>
<entry align="left" valign="top"><para><command>dthelpview</command></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Resource names and classes</para></entry>
<entry align="left" valign="top"><para><command>Dt</command></para></entry>
<entry align="left" valign="top"><para><command>DtNhelpType, DtCHelpType</command></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Library names</para></entry>
<entry align="left" valign="top"><para><command>Dt</command></para></entry>
<entry align="left" valign="top"><para><command>libDtHelp</command></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Include references</para></entry>
<entry align="left" valign="top"><para><command>Dt</command></para></entry>
<entry align="left" valign="top"><para><command>#include &lt;Dt/Help.h></command>
</para></entry></row>
<row>
<entry align="left" valign="top"><para>Public function names</para></entry>
<entry align="left" valign="top"><para><command>Dt</command></para></entry>
<entry align="left" valign="top"><para><command>DtCreateHelpDialog</command></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Public data structure names</para></entry>
<entry align="left" valign="top"><para><command>Dt</command></para></entry>
<entry align="left" valign="top"><para><command>DtHelpDialogCallbackStruct</command></para></entry></row>
<row>
<entry align="left" valign="top"><para>Constant names</para></entry>
<entry align="left" valign="top"><para><command>Dt</command></para></entry>
<entry align="left" valign="top"><para><filename>DtHELP_NEW_WINDOW</filename></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Environment variables</para></entry>
<entry align="left" valign="top"><para><command>DT</command></para></entry>
<entry align="left" valign="top"><para><command>DTHELPSEARCHPATH</command></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Private desktop symbols (structures,
functions, defines)</para></entry>
<entry align="left" valign="top"><para><filename>_dt</filename>, <filename>_Dt</filename>, <filename>_DT</filename></para></entry>
<entry align="left" valign="top"><para><command>_DtHelpFunction, _DtHELP_DEFINE</command></para></entry></row></tbody></tgroup></table>
<para><!--Original XRef content: 'Table&numsp;3&hyphen;2'--><xref role="CodeOrFigureOrTable"
linkend="RDMAP.devap.mkr.5"> lists the exceptions to the preceding naming
conventions.</para>
<table id="rdmap.devap.tbl.2" frame="topbot">
<title id="rdmap.devap.mkr.5">Exceptions to Desktop Naming Conventions</title>
<tgroup cols="3" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.74in">
<colspec colwidth="207*">
<colspec colwidth="189*">
<colspec colwidth="160*">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Name</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Prefix</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Example</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>Common Desktop Environment Motif<indexterm>
<primary>Motif</primary></indexterm></para></entry>
<entry align="left" valign="top"><para><command>Xm</command></para></entry>
<entry align="left" valign="top"><para><command>XmCreateLabel</command></para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>dtksh</command> Convenience
Functions</para></entry>
<entry align="left" valign="top"><para><command>Dtksh</command></para></entry>
<entry align="left" valign="top"><para><command>DtkshAddButtons</command></para></entry>
</row>
<row>
<entry align="left" valign="top"><para>ToolTalk Messaging Service<indexterm>
<primary>ToolTalk Messaging Service</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>tt (for functions), Tt (for typedefs),
TT (for constants)</para></entry>
<entry align="left" valign="top"><para><filename>tt_open</filename>, Tt_message,
TT_NOTICE</para></entry></row>
<row>
<entry align="left" valign="top"><para><indexterm><primary>X11R6.2</primary>
</indexterm>X11R6.2</para></entry>
<entry align="left" valign="top"><para><command>X</command>, <command>Xt</command></para></entry>
<entry align="left" valign="top"><para><command>XOpenDisplay, XtCreateWidget</command></para></entry></row></tbody></tgroup></table>
<caution>
<para>Do <emphasis>not</emphasis> use the prefixes <command>dt</command>, <command>Dt</command>, <command>DT</command>, <filename>_dt</filename>, <filename>_Dt</filename>, <filename>_DT</filename>, <command>Xm</command>, <command>tt</command>, <command>Tt</command>, <command>TT</command>, <command>X</command>,
or <command>Xt</command> to define new symbols in your application code.
If you do, you might define one that has already been defined&mdash;or might
be defined in the future&mdash;in the Common Desktop Environment, ToolTalk,
X11, or Motif code.<indexterm><primary>naming conventions</primary><secondary>caution notice</secondary></indexterm><indexterm><primary>desktop</primary>
<secondary>naming conventions</secondary></indexterm><indexterm><primary>naming conventions</primary><secondary>desktop</secondary></indexterm><indexterm>
<primary>conventions, desktop naming</primary></indexterm><indexterm><primary>application development</primary><secondary>desktop naming conventions &lt;$endrange></secondary></indexterm></para>
</caution>
</sect1>
<sect1 id="RDMAP.devap.div.4">
<title id="RDMAP.devap.mkr.6">Public and Private Interfaces<indexterm><primary>public interfaces</primary></indexterm><indexterm><primary>private interfaces</primary></indexterm><indexterm><primary>interfaces</primary><secondary>private</secondary></indexterm><indexterm><primary>interfaces</primary><secondary>public</secondary></indexterm><indexterm><primary>application development</primary><secondary>public and private interfaces</secondary></indexterm></title>
<para>If a Common Desktop Environment interface is documented in the man pages
or the Common Desktop Environment documentation set, you can assume that
the interface is public unless otherwise stated. An interface is not necessarily
public just because it has a header file associated with it. Interfaces that
are not documented are private to the Common Desktop Environment and are
subject to change without notice.</para>
</sect1>
<sect1 id="RDMAP.devap.div.5">
<title id="RDMAP.devap.mkr.7">Guidelines for Common Desktop Environment Databases<indexterm>
<primary>guidelines</primary><secondary>database syntax</secondary></indexterm><indexterm>
<primary>database</primary><secondary>syntax</secondary></indexterm><indexterm>
<primary>syntax, for databases</primary></indexterm><indexterm><primary>application development</primary><secondary>databases, guidelines for</secondary>
</indexterm></title>
<para>You can find the syntax for the desktop databases, such as those used
for actions and data types, in man pages located in the <filename>/usr/dt/man/man4</filename> directory.</para>
<para>For more information on databases, see the <emphasis>Programmer's Guide</emphasis>.</para>
</sect1>
<sect1 id="RDMAP.devap.div.6">
<title id="RDMAP.devap.mkr.8">Application Initialization and libDtSvc<indexterm>
<primary>application development</primary><secondary>initialization and libDtSvc</secondary></indexterm><indexterm><primary>desktop</primary><secondary>libDtSvc and application initialization</secondary></indexterm></title>
<para>If your application uses any of the <command>libDtSvc</command> APIs
(for actions, data typing, drag and drop, Session Manager, or Workspace Manager),
it must first initialize the <command>libDtSvc</command> library by calling
either <filename>DtInitialize()</filename><indexterm><primary>DtInitialize()</primary></indexterm> or <filename>DtAppInitialize()</filename><indexterm>
<primary>DtAppInitialize()</primary></indexterm>. Refer to the <filename>DtInitialize</filename>(3) or <filename>DtAppInitialize</filename>(3) man
page for more information.</para>
</sect1>
<sect1 id="RDMAP.devap.div.7">
<title id="RDMAP.devap.mkr.9">Application Builder<indexterm><primary>application
development</primary><secondary>Application Builder &lt;$startrange></secondary></indexterm></title>
<para>Application Builder (App Builder) is a tool that enables you to easily
create the graphical user interface (GUI) for Common Desktop Environment
applications, without having to write code to call the desktop application
program interfaces (APIs). It abstracts the Motif toolkit into simple object
palettes and object property sheets. You can use App Builder to construct
a wide range of applications, from simple GUI-based programs to complex,
integrated systems. It supports User Interface Language (UIL) file import
and export to enable you to migrate your application among other Motif-based
tools and products.<indexterm><primary>Application Builder</primary><secondary>App Builder</secondary></indexterm><indexterm><primary>App Builder (Application
Builder)</primary></indexterm></para>
<para>App Builder is ideally suited for use if you:<indexterm><primary>Application
Builder</primary><secondary>when to use</secondary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para>Are not an expert Motif programmer
</para>
</listitem><listitem><para>Are not familiar with the Common Desktop Environment
Motif widgets</para>
</listitem><listitem><para>Are not familiar with the desktop services (for
example,<indexterm><primary>drag and drop</primary></indexterm> drag and
drop,<indexterm><primary>ToolTalk Messaging Service</primary></indexterm> ToolTalk
messaging,<indexterm><primary>Session Manager</primary></indexterm> sessioning,<indexterm><primary>Help system</primary></indexterm>
help, and<indexterm>
<primary>internationalization</primary></indexterm> internationalization)</para>
</listitem><listitem><para>Want to build your application user interface quickly
and be able to change it easily</para>
</listitem><listitem><para>Are working collaboratively with other people to
build a single application</para>
</listitem></itemizedlist>
<para>In fact, even if you do not fit into any of the preceding categories,
you will likely find App Builder to be appropriate and helpful for your application
development.</para>
<para>Using App Builder, you can:</para>
<itemizedlist remap="Bullet1"><listitem><para>Lay out the user interface for
an application, constructing it piece-by-piece from a collection of objects
from the Common Desktop Environment<indexterm><primary>Motif</primary></indexterm> Motif
toolkit</para>
</listitem><listitem><para>Define connections between objects to provide application
GUI behavior, then use the test mode that enables connections to be tested
</para>
</listitem><listitem><para>Add some of the desktop services functionality
to your application</para>
</listitem><listitem><para>Edit applications that were previously created
using App Builder</para>
</listitem><listitem><para>Merge automatically generated code with hand-generated
code</para>
</listitem><listitem><para>Generate C-language source code and associated
project files (for example, message catalogs) for the application</para>
</listitem></itemizedlist>
<para>You can<indexterm><primary>compiling</primary><secondary>an application</secondary></indexterm> compile and invoke your application from within App
Builder. You can execute the build, run, and debug cycles all from a common
environment without having to exit and restart App Builder.</para>
<sect2 id="RDMAP.devap.div.8">
<title>Demo Programs<indexterm><primary>Application Builder</primary><secondary>demo programs</secondary></indexterm><indexterm><primary>demo programs</primary>
</indexterm></title>
<para>You can find the App Builder example programs in <filename>/usr/dt/examples/dtbuilder</filename>. Read the <command>README</command> file for detailed information
on these programs.</para>
<sect3 id="RDMAP.devap.div.9">
<title>Related Documentation</title>
<para>For more information on Application Builder, see the appropriate man
pages, the App Builder help volume, and the <emphasis>Application Builder
User's Guide</emphasis>.<indexterm><primary>application
development</primary><secondary>Application Builder &lt;$endrange></secondary></indexterm><?Pub Caret></para>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->
<?Pub *0000020547>

158
cde/doc/C/guides/progOview/ch04.sgm Normal file
View File

@@ -0,0 +1,158 @@
<!-- $XConsortium: ch04.sgm /main/7 1996/09/08 19:46:50 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<chapter id="RDMAP.port.div.1">
<title id="RDMAP.port.mkr.1">Portability and Maintenance</title>
<para>This chapter contains information you can use to write highly portable
applications and use to ensure that your application will be compatible with
future Common Desktop Environment releases.</para>
<informaltable id="RDMAP.port.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Portability Issues37'--><xref role="JumpText"
linkend="RDMAP.port.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Common Desktop Environment Motif
Widget Binary Compatibility Guidelines40'--><xref role="JumpText" linkend="RDMAP.port.mkr.4"></para></entry>
</row></tbody></tgroup></informaltable>
<sect1 id="RDMAP.port.div.2">
<title id="RDMAP.port.mkr.2">Portability Issues<indexterm><primary>portability
issues &lt;$startrange></primary>
</indexterm></title>
<para>This section presents issues that might affect your application's portability
between different platforms that support the Common Desktop Environment.
</para>
<sect2 id="RDMAP.port.div.3">
<title id="RDMAP.port.mkr.3">Standards<indexterm><primary>standards &lt;$startrange></primary></indexterm></title>
<para>To be Common Desktop Environment-compliant, your application must<indexterm>
<primary>Motif 2.1</primary></indexterm> follow the Motif 2.1,<indexterm>
<primary>ANSI C</primary></indexterm> ANSI-C, and<indexterm><primary>X11R6.2</primary></indexterm> X11R6.2 standards. If you are developing your application
in C++, use C++ version 2.0 or later. No further assumptions are made that
you adhere to any standards, such as POSIX, when you write a Common Desktop
Environment application. Applications that use the desktop application program
interfaces (APIs) will be portable to other Common Desktop Environment platforms.
However, using POSIX can enhance your software's portability.</para>
<para>The<indexterm><primary>POSIX</primary></indexterm> POSIX standard,
IEEE Std 1003.1-1990, is entitled <emphasis>IEEE Standard for Information
Technology&mdash;Portable Operating System Interface (POSIX)&mdash;Part 1:
System Application Program Interface (API) [C Language],</emphasis> ISBN
1-55937-061-0.</para>
<para>The Motif 2.1 standard, IEEE Std 1295, is entitled <emphasis>Standard
for Information Technology&mdash;X Window System Graphical User Interface&mdash;Modular
Toolkit Environment.</emphasis><indexterm><primary>standards &lt;$endrange></primary></indexterm></para>
<para>For information on ordering IEEE Std 1003.1-1990 and IEEE Std 1295,
see <!--Original XRef content: '&xd2;Related Books&xd3; on page&numsp;xv'--><xref
role="SecTitleAndPageNum" linkend="RDMAP.pref.mkr.2">.</para>
</sect2>
<sect2 id="RDMAP.port.div.4">
<title>Makefiles<indexterm><primary>makefiles &lt;$startrange></primary></indexterm></title>
<para>Certain libraries that the Common Desktop Environment depends on, for
example X11, are likely to be installed in different locations on different
platforms. Include platform-specific references to accommodate this or write
a separate makefile for each platform.</para>
<para>Also, the <command>make</command> program functionality can differ across
platforms. If you want to write just one makefile for your application, use
the common <command>make</command> functionality used by the platforms to
which you want to port your program. Avoid platform-specific <command>make</command> features.</para>
<para>The Common Desktop Environment requires no additional defined constants
(<filename>-D</filename> parameters) to integrate with the desktop. If you
do follow a standard, such as POSIX, you might need to compile with additional
standard-specific flags. Read about the standard to find out if it includes
special compiler considerations.</para>
<para>Each subdirectory of <filename>/usr/dt/examples</filename> contains
sample makefile source files for different platforms. These makefiles take
into account system differences. In particular, see the <filename>/usr/dt/examples/dtdts</filename> <command>directory</command> for generic examples of makefiles.
</para>
<sect3 id="RDMAP.port.div.5">
<title>Compile Options</title>
<para>To enable your application to find the desktop <command>include</command>
files, add:</para>
<programlisting>-I/usr/dt/include</programlisting>
<para>to each makefile's compile line.</para>
</sect3>
<sect3 id="RDMAP.port.div.6">
<title>Link Options</title>
<para>To enable your application to reference desktop libraries, add:</para>
<programlisting>-L/usr/dt/lib -l&lt;<symbol role="Variable">libname1</symbol>> -l&lt;<symbol role="Variable">libname2</symbol>>...</programlisting>
<para>to each makefile's link line, where <symbol role="Variable">libname1</symbol>, <symbol role="Variable">libname2</symbol> are the names of libraries
your application needs to reference.<indexterm><primary>makefiles &lt;$endrange></primary>
</indexterm> You can include as many desktop library names in this line as
you want. For example:</para>
<programlisting>-L/usr/dt/lib -lDtSvc -ltt -lXm</programlisting>
<para>enables your application to reference the Desktop Services, ToolTalk
Messaging System, and Motif 2.1 libraries.</para>
</sect3>
</sect2>
<sect2 id="RDMAP.port.div.7">
<title>File-Naming Conventions<indexterm><primary>file naming conventions</primary></indexterm><indexterm><primary>naming conventions</primary><secondary>file</secondary></indexterm></title>
<para>You should limit your application file names, and the file names your
application generates, to 14 characters. This will make your application
portable to platforms that have this limitation. Some platforms can be configured
to have this constraint.</para>
<para>Do not place length limitations on file names that an end user generates.
</para>
</sect2>
<sect2 id="RDMAP.port.div.8">
<title>Display Support<indexterm><primary>display support</primary></indexterm></title>
<para>Your application should support the following display options and configurations:
</para>
<itemizedlist remap="Bullet1"><listitem><para>Monochrome (including black-and-white
icons)</para>
</listitem><listitem><para>Color (including color icons)</para>
</listitem><listitem><para>Small screens, such as<indexterm><primary>VGA</primary></indexterm> VGA (640x480&mdash;scale application window or font
size to fit completely on the screen)</para>
</listitem></itemizedlist>
<para>If you use the<indexterm><primary>Icon Editor</primary></indexterm> Icon
Editor to create color icons, your application will share colors with other
desktop applications more readily. This helps conserve color cells when running
on a<indexterm><primary>Pseudo Color display</primary></indexterm> Pseudo
Color display.<literal><indexterm><primary>portability issues &lt;$endrange></primary></indexterm></literal></para>
</sect2>
</sect1>
<sect1 id="RDMAP.port.div.9">
<title id="RDMAP.port.mkr.4">Common Desktop Environment Motif Widget Binary
Compatibility Guidelines<indexterm><primary>guidelines</primary><secondary>Common Desktop Environment Motif widget binary compatibility</secondary>
</indexterm><indexterm><primary>compatibility</primary><secondary>guidelines,
for Common Desktop Environment widgets</secondary></indexterm><indexterm>
<primary>widget</primary><secondary>compatibility guidelines &lt;$startrange></secondary></indexterm></title>
<para>Any widget subclass that you implement using the standard Xt APIs that
rely on the size of data structures of widgets from which you have subclassed
might not be compatible with any new version of Motif or the Common Desktop
Environment. The reason for this is that new fields may be added to the superclasses
in the new version of Motif. An example is that new fields have been added
to the <command>XmManager</command> and <command>XmPrimitive</command> classes
in Motif 2.0.</para>
<para>The incompatibility occurs because a subclass must contain compiled-in
references to its instance fields that are specified relative to the start
address of the widget instance. When you install a new Motif library for
a widget whose superclass instance structure has been extended, the compiled-in
references will point to the wrong memory location.</para>
<para>To avoid this difficulty, Motif provides a mechanism for defining resources
and accessing widget fields that allows you to reference all fields in the
instance and constraint structures relative to the start of the widget <command>part</command> structure, instead of the overall widget structure. (The overall
widget structure includes the superclass part structure.) The mechanism resolves
these relative references at run time, when the widget class is first initialized.
To resolve references, it factors in the size of the widget's superclass
instance structure, which it reads from the currently linked Motif library.
</para>
<note>
<para>If you implement subclassing, you <emphasis>must</emphasis> use the
Motif reference- resolving mechanism if you want your application to be binary
compatible with future releases of the Common Desktop Environment.</para>
</note>
<para>For details regarding this Motif mechanism, consult the Motif 2.1 <filename>XmResolvePartOffsets(3x)</filename> and <filename>XmResolveAllPartOffsets(3x)</filename> man pages and the <emphasis>Motif Programmer's Reference</emphasis>. You can find example source code in <filename>/usr/dt/examples/motif/dogs</filename><literal><indexterm><primary>guidelines</primary><secondary>Common
Desktop Environment Motif widget binary compatibility</secondary></indexterm><indexterm>
<primary>compatibility</primary><secondary>guidelines, for Common Desktop
Environment widgets</secondary></indexterm><indexterm><primary>widget</primary>
<secondary>compatibility guidelines &lt;$endrange></secondary></indexterm></literal>.</para>
</sect1>
</chapter><?Pub Caret>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->
<?Pub *0000011964>

123
cde/doc/C/guides/progOview/ch05.sgm Normal file
View File

@@ -0,0 +1,123 @@
<!-- $XConsortium: ch05.sgm /main/5 1996/08/25 15:13:45 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<chapter id="RDMAP.BIntg.div.1">
<title id="RDMAP.BIntg.mkr.1">Basic Application Integration</title>
<para>Basic application integration is a set of highly recommended tasks you
should perform. These tasks <emphasis>do not</emphasis> require modification
of the source code for your application.</para>
<informaltable id="RDMAP.BIntg.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Basic Integration Features41'--><xref
role="JumpText" linkend="RDMAP.BIntg.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Organization of Basic Integration
Information42'--><xref role="JumpText" linkend="RDMAP.BIntg.mkr.3"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Basic Integration Tasks43'--><xref
role="JumpText" linkend="RDMAP.BIntg.mkr.4"></para></entry></row></tbody>
</tgroup></informaltable>
<para>Basic integration does not involve extensive use of the desktop application
program interface (API). Therefore, it does not provide other interaction
with the desktop, such as drag and drop, session management, ToolTalk messaging,
and programmatic access to the actions and data types database.</para>
<sect1 id="RDMAP.BIntg.div.2">
<title id="RDMAP.BIntg.mkr.2">Basic Integration Features</title>
<para>Basic application integration provides these features for end users:
</para>
<itemizedlist remap="Bullet1"><listitem><para>A graphical way to locate and
start your application on the desktop.</para>
<para>Your application will provide a desktop <symbol role="Variable">registration
package</symbol>, and your installation script will automatically register
your application.</para>
<para>Registration creates an application group at the top level of Application
Manager. The application group contains an icon the user double-clicks to
start the application.</para>
</listitem><listitem><para>The ability to recognize and manipulate your application's
data files.</para>
<para>Your application will provide data types for its data files.</para>
<para>Data typing configures data files to use a unique icon in File Manager
to help users identify them. The data files also have meaningful desktop
behavior. Two examples are:</para>
<itemizedlist remap="Bullet2"><listitem><para>The user can start your application
by double-clicking a data file.</para>
</listitem><listitem><para>Dropping a data file on a desktop printer drop
zone prints the file using the appropriate print command.</para>
</listitem></itemizedlist>
</listitem><listitem><para>Easy font and color selection using Style Manager.
</para>
<para>Your application will change interface fonts and background, foreground,
and shadow colors dynamically.</para>
<para>The desktop defines general interface font and color resources that
are used if no corresponding application-specific resources exist.</para>
</listitem></itemizedlist>
<para>Basic integration provides these advantages to system administrators:
</para>
<itemizedlist remap="Bullet1"><listitem><para>Easy installation and registration.
</para>
<para>Upon installation, the application is automatically registered. The
system administrator has little or no additional work to do.</para>
</listitem><listitem><para>Easy ongoing administration.</para>
<para>All the desktop's configuration files are gathered in one location.
Furthermore, the application can easily be unregistered if, for example,
the system administrator wants to update it or to move it to a different
application server.</para>
</listitem></itemizedlist>
</sect1>
<sect1 id="RDMAP.BIntg.div.3">
<title id="RDMAP.BIntg.mkr.3">Organization of Basic Integration Information</title>
<para>Most of the tasks involved in basic integration are also performed by
system administrators who are integrating an existing application into the
desktop. Therefore, most basic integration documentation is located in the <emphasis>Advanced User's and System Administrator's Guide</emphasis>.</para>
<para>The <emphasis>Programmer's Guide</emphasis> contains a chapter on basic
integration. Where appropriate, the chapter refers you to the information
contained in the <emphasis>Advanced User's and System Administrator's Guide</emphasis>. It also contains additional information specific to application
programmers.</para>
</sect1>
<sect1 id="RDMAP.BIntg.div.4">
<title id="RDMAP.BIntg.mkr.4">Basic Integration Tasks</title>
<para>These are the general tasks involved in basic integration:</para>
<itemizedlist remap="Bullet1"><listitem><para>Modify any application resources
that set fonts and colors. This allows users to change the application's
interface fonts and colors using Style Manager.</para>
<para>See the section on modifying font and color resources in the <emphasis>Advanced User's and System Administrator's Guide</emphasis>.</para>
</listitem><listitem><para>Provide printing for your application's data files.
</para>
<para>See the <emphasis>Programmer's Guide</emphasis> basic integration chapter
for details.</para>
<para>Some types of printing integration require that you modify your application
code. They are optional, and are discussed in the <emphasis>Programmer's
Guide</emphasis> basic integration chapter because they are closely related
to basic integration tasks.</para>
</listitem><listitem><para>Create the registration package for your application.
</para>
<para>See this documentation:</para>
<itemizedlist remap="Bullet2"><listitem><para><emphasis>Programmer`s Guide</emphasis> basic integration chapter</para>
</listitem><listitem><para><emphasis>Advanced User's and System Administrator's
Guide</emphasis></para>
</listitem></itemizedlist>
</listitem><listitem><para>Modify your application's installation script to
install the registration package files and perform the registration procedure.
</para>
<para>See this documentation:</para>
<itemizedlist remap="Bullet2"><listitem><para><emphasis>Programmer's Guide</emphasis> basic integration chapter</para>
</listitem><listitem><para>The section on registering the application using <command>dtappintegrate</command> in the <emphasis>Advanced User's and System Administrator's
Guide</emphasis></para>
</listitem></itemizedlist>
</listitem></itemizedlist>
<programlisting></programlisting>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->
<?Pub Caret>
<?Pub *0000007986>

810
cde/doc/C/guides/progOview/ch06.sgm Normal file
View File

@@ -0,0 +1,810 @@
<!-- $XConsortium: ch06.sgm /main/10 1996/09/08 19:46:58 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<chapter id="RDMAP.recin.div.1">
<title id="RDMAP.recin.mkr.1">Recommended Integration</title>
<para>The<indexterm><primary>recommended integration &lt;$startrange></primary></indexterm><indexterm><primary>levels of
integration</primary><secondary>recommended &lt;$startrange></secondary></indexterm><indexterm><primary>integration</primary><secondary>recommended &lt;$startrange></secondary></indexterm> 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.</para>
<informaltable id="RDMAP.recin.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Help System46'--><xref role="JumpText"
linkend="RDMAP.recin.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'ToolTalk Messaging Service47'--><xref
role="JumpText" linkend="RDMAP.recin.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Session Manager50'--><xref role="JumpText"
linkend="RDMAP.recin.mkr.9"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Drag and Drop52'--><xref role="JumpText"
linkend="RDMAP.recin.mkr.10"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Internationalization54'--><xref role="JumpText"
linkend="RDMAP.recin.mkr.11"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Standard Font Names55'--><xref role="JumpText"
linkend="RDMAP.recin.mkr.12"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Displaying Error Messages from Your
Application57'--><xref role="JumpText" linkend="RDMAP.recin.mkr.13"></para></entry>
</row>
<row rowsep="1">
<entry><para>Printing ??
</para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'User Customization Issues59'--><xref
role="JumpText" linkend="RDMAP.recin.mkr.14"></para></entry></row></tbody>
</tgroup></informaltable>
<note>
<para>In addition to incorporating the components and following the guidelines
in this section, you should also follow the basic integration steps outlined
in <!--Original XRef content: 'Chapter&numsp;5, &xd2;Basic Application Integration'--><xref
role="ChapNumAndTitle" linkend="RDMAP.BIntg.mkr.1">.</para>
</note>
<para>For more information on recommended integration, see the <emphasis>Programmer's Guide</emphasis>.</para>
<sect1 id="RDMAP.recin.div.2">
<title id="RDMAP.recin.mkr.2">Help System</title>
<para>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.</para>
<para>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.</para>
<para>The Help system includes support for authors and programmers.</para>
<sect2 id="RDMAP.recin.div.3">
<title>For Authors<indexterm><primary>Help system</primary><secondary>authors,
for</secondary></indexterm></title>
<itemizedlist remap="Bullet1"><listitem><para>Common Desktop Environment HelpTag
markup language&mdash;a set of <symbol role="Variable">tags</symbol> used
in text files to mark organization and content of online help<indexterm><primary>HelpTag</primary></indexterm><indexterm><primary>Help system</primary><secondary>Help Tag</secondary></indexterm></para>
</listitem><listitem><para>Common Desktop Environment HelpTag software&mdash;a
set of software tools for converting HelpTag files into run-time help files
</para>
</listitem><listitem><para>Common Desktop Environment Helpview application&mdash;a
viewer program for displaying online help</para>
</listitem></itemizedlist>
<para>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.<indexterm>
<primary>Standard Generalized Markup Language (SGML)</primary></indexterm><indexterm>
<primary>Help system</primary><secondary>SGML</secondary></indexterm></para>
<para>The Help system also supports non-SGML formats such as UNIX man pages,
text files, and text strings.<indexterm><primary>UNIX</primary></indexterm><indexterm>
<primary>Help system</primary><secondary>UNIX man pages</secondary></indexterm>
</para>
<sect3 id="RDMAP.recin.div.4">
<title>For Programmers<indexterm><primary>Help system</primary><secondary>programmers, for</secondary></indexterm></title>
<itemizedlist remap="Bullet1"><listitem><para><command>DtHelp</command> programming
library&mdash;Application program interface (API) for creating and integrating
help windows into your application</para>
</listitem><listitem><para><command>DtHelp</command><indexterm><primary>widget</primary><secondary>Help system</secondary></indexterm> widgets&mdash; <command>DtHelpDialog</command> and <command>DtHelpQuickDialog</command> widgets to
create help dialog boxes and quick help dialog boxes (these are also part
of the Help library)</para>
</listitem></itemizedlist>
</sect3>
</sect2>
<sect2 id="RDMAP.recin.div.5">
<title><indexterm><primary>Help system</primary><secondary>library and header
files</secondary></indexterm>Library and Header Files</title>
<para>The Help library, <command>libDtHelp</command>, provides support for
creating and managing help dialogs based on Motif. The <command>libDtHelp</command> header files are:</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>Dt/Help.h</filename></para>
</listitem><listitem><para><filename>Dt/HelpDialog.h</filename></para>
</listitem><listitem><para><filename>Dt/HelpQuickD.h</filename></para>
</listitem></itemizedlist>
</sect2>
<sect2 id="RDMAP.recin.div.6">
<title>Demo Programs<indexterm><primary>Help system</primary><secondary>demo
programs</secondary></indexterm><indexterm><primary>demo programs</primary>
</indexterm></title>
<para>You can find the Help system demos in <filename>/usr/dt/examples/dthelp</filename>. Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.recin.div.7">
<title>Related Documentation</title>
<para>For more information on the Help system, see the relevant man pages
and the <emphasis>Help System Author's and Programmer's Guide</emphasis>.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.recin.div.8">
<title id="RDMAP.recin.mkr.3">ToolTalk Messaging Service</title>
<para>The Common Desktop Environment defines two standard ToolTalk protocols
known as <emphasis><indexterm><primary>message sets</primary></indexterm><indexterm>
<primary>ToolTalk Messaging Service</primary><secondary>message sets</secondary>
</indexterm>message sets</emphasis>. 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.</para>
<para>The <emphasis>desktop message set</emphasis> encompasses three areas:<indexterm>
<primary>desktop message set</primary></indexterm><indexterm><primary>ToolTalk
Messaging Service</primary><secondary>desktop message set</secondary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para>Windowing behavior</para>
</listitem><listitem><para>File access and short-term file lifecycle control
</para>
</listitem><listitem><para>Application extension languages</para>
</listitem></itemizedlist>
<para>See <!--Original XRef content: '&xd2;Handle Desktop'--><xref role="SectionTitle"
linkend="RDMAP.recin.mkr.4"> and <!--Original XRef content: '&xd2;Send
Desktop'--><xref role="SectionTitle" linkend="RDMAP.recin.mkr.5">
for information on windowing behavior. See <!--Original XRef content: '&xd2;Desktop
File'--><xref role="SectionTitle" linkend="RDMAP.recin.mkr.8"> for
information on file access and short-term file lifecycle control. Implementing
the <filename>Do_Command</filename> request is specific to the application's
extension language and is not assisted by the ToolTalk Messaging Service.
</para>
<para>The <emphasis><indexterm><primary>media message set</primary></indexterm><indexterm>
<primary>ToolTalk Messaging Service</primary><secondary>media message set</secondary></indexterm>media message set</emphasis> 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 <!--Original XRef content:
'&xd2;Send Media'--><xref role="SectionTitle" linkend="RDMAP.recin.mkr.7">
and <!--Original XRef content: '&xd2;Handle Media&xd3; on page&numsp;49'--><xref
role="SecTitleAndPageNum" linkend="RDMAP.recin.mkr.6">.</para>
<para>The ToolTalk Messaging Service provides support for these message sets:
</para>
<itemizedlist remap="Bullet1"><listitem><para id="RDMAP.recin.mkr.4">Handle
Desktop</para>
<para>Handling desktop requests is the most basic level of messaging integration.
Any application that sends ToolTalk messages, either through calling
<filename>tt_message_send()</filename> or <filename>DtActionInvoke()</filename>, should
handle the desktop requests. This enables other applications to set or query
things such as your application's current directory, iconic state, and
<filename>$DISPLAY</filename>. For further information, see the man pages for
<filename>ttdt_open()</filename>, <filename>ttdt_session_join()</filename>,
<filename>ttdt_session_quit()</filename>, and <filename>ttdt_close()</filename>.</para>
</listitem><listitem><para id="RDMAP.recin.mkr.5">Send Desktop</para>
<para>When an application is started by <command>ttsession</command> to handle
some ToolTalk request, it is a child of <command>ttsession</command> 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.</para>
<para>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 <filename>$DISPLAY</filename>.
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 <filename>ttdt_sender_imprint_on()</filename> man page.</para>
</listitem><listitem><para id="RDMAP.recin.mkr.6">Handle Media</para>
<para>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 <filename>ttmedia_ptype_declare()</filename>, <filename>ttdt_message_accept()</filename>, <filename>ttmedia_load_reply()</filename>, and <filename>ttmedia_Deposit()</filename>.</para>
</listitem><listitem><para id="RDMAP.recin.mkr.7">Send Media</para>
<para>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
<filename>ttmedia_load()</filename> and <filename>ttdt_subcontract_manage()</filename>.
Note that, in most cases, a container application should perform operations
on objects using <filename>DtActionInvoke()</filename> instead of
<filename>ttmedia_load()</filename>. See the <emphasis>ToolTalk Messaging Overview</emphasis> for a description of how ToolTalk applications can be driven
using actions.</para>
</listitem><listitem><para id="RDMAP.recin.mkr.8">Desktop File</para>
<para>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
<filename>ttdt_file_join()</filename>, <filename>ttdt_file_quit()</filename>,
<filename>ttdt_file_event()</filename>, <filename>ttdt_Get_Modified()</filename>,
<filename>ttdt_Save()</filename>, and <filename>ttdt_Revert()</filename>.</para>
</listitem></itemizedlist>
<para>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.</para>
<sect2 id="RDMAP.recin.div.9">
<title>Library and Header Files<indexterm><primary>ToolTalk Messaging Service</primary><secondary>library and header files</secondary></indexterm></title>
<para>The ToolTalk messaging library is called <command>libtt</command>. The <command>libtt</command> header files are:</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>Tt/tt_c.h</filename></para>
</listitem><listitem><para><filename>Tt/tttk.h</filename></para>
</listitem></itemizedlist>
</sect2>
<sect2 id="RDMAP.recin.div.10">
<title>Demo Programs<indexterm><primary>ToolTalk Messaging Service</primary>
<secondary>demo programs</secondary></indexterm><indexterm><primary>demo
programs</primary></indexterm></title>
<para>You can find the ToolTalk Messaging Service demos in <filename>/usr/dt/examples/tt</filename>. Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.recin.div.11">
<title>Related Documentation</title>
<para>For more information on the ToolTalk Messaging Service, see the relevant
man pages and the <emphasis>ToolTalk Messaging</emphasis> <emphasis>Overview</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.recin.div.12">
<title id="RDMAP.recin.mkr.9">Session Manager</title>
<para>Session Manager supports the ICCCM 1.1 <filename><indexterm><primary>WM_COMMAND</primary></indexterm><indexterm><primary>Session Manager</primary>
<secondary>WM_COMMAND</secondary></indexterm>WM_COMMAND</filename> and <filename><indexterm>
<primary>WM_SAVE_YOURSELF</primary></indexterm><indexterm><primary>Session
Manager</primary><secondary>WM_SAVE_YOURSELF</secondary></indexterm>WM_SAVE_YOURSELF</filename><indexterm><primary>protocols</primary><secondary>WM_COMMAND</secondary></indexterm><indexterm><primary>protocols</primary><secondary>WM_SAVE_YOURSELF</secondary></indexterm> protocols, which permit:</para>
<itemizedlist remap="Bullet1"><listitem><para>Your application to save state
information at logout</para>
</listitem><listitem><para>Session Manager to restart your application at
login</para>
</listitem></itemizedlist>
<para>Session Manager also provides an API to assist your application in saving
and restoring its state at logout and login.</para>
<para>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 <filename>XSetCommand()</filename>
to set the <filename>WM_COMMAND</filename> property on your application's
top-level window.</para>
<para>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 <filename>WM_SAVE_YOURSELF</filename> protocol with its top-level window <filename>WM_PROTOCOLS</filename>
property and setting up a callback procedure to handle the notification.
To do this, use the <filename><indexterm><primary>XmAddWMProtocols()</primary>
</indexterm><indexterm><primary>Session Manager</primary><secondary>XmAddWMProtocols()</secondary></indexterm>XmAddWMProtocols()</filename> and <filename><indexterm>
<primary>XmAddWMProtocolsCallback()</primary></indexterm><indexterm><primary>Session Manager</primary><secondary>XmAddWMProtocolsCallback()</secondary>
</indexterm>XmAddWMProtocolsCallback()</filename> functions. Your application
should not interact with the user in any way when processing the
<filename>WM_SAVE_YOURSELF</filename> callback. (For example, it should not display
a Save As dialog box.) It must set the <filename>WM_COMMAND</filename> property
on its top-level window to notify Session Manager that it is done saving
its state.</para>
<para>To enable your application to save state information, use the <filename><indexterm>
<primary>DtSessionSavePath()</primary></indexterm><indexterm><primary>Session
Manager</primary><secondary>DtSessionSavePath()</secondary></indexterm>DtSessionSavePath()</filename> function to obtain the full path name of a file in which this
information can be saved. At session restore time, use the <filename><indexterm>
<primary>DtSessionRestorePath()</primary></indexterm><indexterm><primary>Session Manager</primary><secondary>DtSessionRestorePath()</secondary></indexterm>DtSessionRestorePath()</filename> function to obtain the full path name of the state file your
application uses to restore its state.</para>
<para>The Common Desktop Environment<indexterm><primary>Workspace Manager</primary></indexterm> Workspace Manager is responsible for restoring an application's
main top-level window (containing the <filename>WM_COMMAND</filename>) 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 <!--Original XRef content:
'&xd2;Workspace Manager&xd3; on page&numsp;70'--><xref role="SecTitleAndPageNum"
linkend="RDMAP.optin.mkr.5"> for additional information.</para>
<sect2 id="RDMAP.recin.div.13">
<title>Library and Header Files<indexterm><primary>Session Manager</primary>
<secondary>library and header files</secondary></indexterm></title>
<para>The Desktop Services library, <command>libDtSvc</command>, provides
access to many desktop APIs, including the one for session management. Include
the <filename>Dt/Dt.h</filename> and <filename>Dt/Session.h</filename> header
files to access the Session Manager API.</para>
<note>
<para>If your application uses any of the Session Manager APIs, it must first
initialize the <command>libDtSvc</command> library by calling either <filename><indexterm>
<primary>DtInitialize()</primary></indexterm>DtInitialize()</filename> or
<filename><indexterm><primary>DtAppInitialize()</primary></indexterm>DtAppInitialize()</filename>. Refer to the <filename>DtInitialize</filename>(3) or
<filename>DtAppInitialize</filename>(3) man page for more information.</para>
</note>
</sect2>
<sect2 id="RDMAP.recin.div.14">
<title>Demo Programs<indexterm><primary>Session Manager</primary><secondary>demo programs</secondary></indexterm><indexterm><primary>demo programs</primary>
</indexterm></title>
<para>You can find the Session Manager demos in <filename>/usr/dt/examples/dtsession</filename>. Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.recin.div.15">
<title>Related Documentation</title>
<para>For more information on Session Manager, see the relevant man pages
and the <emphasis>Programmer's Guide</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.recin.div.16">
<title id="RDMAP.recin.mkr.10">Drag and Drop</title>
<para>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.</para>
<para>Motif 2.1 drag and drop provides low-level drag-and-drop mechanisms;
Common Desktop Environment drag and drop incorporates policies for those
mechanisms.<indexterm><primary>drag and drop</primary><secondary>and Motif
2.1 drag and drop</secondary></indexterm></para>
<para>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.</para>
<para>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.</para>
<para>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:</para>
<itemizedlist remap="Bullet1"><listitem><para>Manages the configuration and
appearance of drag icons.</para>
<para>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.</para>
</listitem><listitem><para>Defines a buffer transfer protocol.</para>
<para>Motif 2.1 drag and drop defines protocols for file name and text string
only.</para>
</listitem><listitem><para>Enables animation upon drop.</para>
<para>The drop zone can define an animation procedure that is called when
the drop completes.</para>
</listitem><listitem><para>Provides enumeration of targets for <command>TEXT</command> and <filename>FILE_NAME</filename> transfers.</para>
</listitem><listitem><para>Provides dual registration.</para>
<para>You can register a text widget as a drop zone for data other than text,
while preserving the ability to accept text drops.</para>
</listitem><listitem><para>Provides prioritized drop formats.</para>
<para>The order in which you specify protocols for the drop zone indicates
the relative priority of the protocols desired.</para>
</listitem></itemizedlist>
<sect2 id="RDMAP.recin.div.17">
<title>Library and Header Files<indexterm><primary>drag and drop</primary>
<secondary>library and header files</secondary></indexterm></title>
<para>The Desktop Services library, <command>libDtSvc</command>, provides
access to many desktop APIs, including that for drag and drop. Include the
<filename>Dt/Dt.h</filename> and <filename>Dt/Dnd.h</filename> header files to access
the drag-and-drop API.</para>
<note>
<para>If your application uses any of the drag-and-drop APIs, it must first
initialize the <command>libDtSvc</command> library by calling either <filename><indexterm>
<primary>DtInitialize()</primary></indexterm>DtInitialize()</filename> or
<filename><indexterm><primary>DtAppInitialize()</primary></indexterm>DtAppInitialize()</filename>. Refer to the <filename>DtInitialize</filename>(3) or
<filename>DtAppInitialize</filename>(3) man page for more information.</para>
</note>
</sect2>
<sect2 id="RDMAP.recin.div.18">
<title>Demo Programs<indexterm><primary>drag and drop</primary><secondary>demo programs</secondary></indexterm></title>
<para>You can find the drag-and-drop demos in <filename>/usr/dt/examples/dtdnd</filename>. Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.recin.div.19">
<title>Related Documentation</title>
<para>For more information on Common Desktop Environment drag and drop, see
the relevant man pages and the <emphasis>Programmer's Guide</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.recin.div.20">
<title id="RDMAP.recin.mkr.11">Internationalization</title>
<para>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.<indexterm>
<primary>guidelines</primary><secondary>internationalization &lt;$startrange></secondary></indexterm><indexterm>
<primary>single-byte locales</primary></indexterm><indexterm><primary>locales</primary><secondary>single-byte</secondary></indexterm><indexterm><primary>internationalization</primary><secondary>single-byte locales</secondary>
</indexterm><indexterm><primary>multibyte locales</primary></indexterm><indexterm>
<primary>locales</primary><secondary>multibyte</secondary></indexterm><indexterm>
<primary>internationalization</primary><secondary>multibyte locales</secondary>
</indexterm></para>
<para>Common Desktop Environment applications (both source and binary) can
be localized into regional languages and territories, and across multiple
vendors and hardware platforms:<indexterm><primary>locales</primary><secondary>applications can be localized into</secondary></indexterm><indexterm><primary>internationalization</primary><secondary>locales</secondary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para>Latin American</para>
</listitem><listitem><para>Western European</para>
</listitem><listitem><para>Japanese</para>
</listitem><listitem><para>Korean</para>
</listitem><listitem><para>Chinese (Traditional and Simplified)</para>
</listitem></itemizedlist>
<para>The Common Desktop Environment takes advantage of internationalization
features in these standards:<indexterm><primary>standards</primary><secondary>internationalization</secondary></indexterm><indexterm><primary>internationalization</primary><secondary>standards</secondary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para>IEEE 1003.2-1992 (<indexterm>
<primary>POSIX</primary></indexterm> POSIX.2 Annex B)</para>
</listitem><listitem><para>X Window System, Version 11 Release 6.2 (Locales
and Internationalization Text Functions)<indexterm><primary>X11R6.2</primary>
</indexterm></para>
</listitem><listitem><para>Motif 2.1 (Internationalizing and Localizing Motif
clients)<indexterm><primary>Motif 2.1</primary></indexterm></para>
</listitem></itemizedlist>
<para>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.</para>
<sect2 id="RDMAP.recin.div.21">
<title>Demo Programs<indexterm><primary>internationalization</primary><secondary>demo programs</secondary></indexterm><indexterm><primary>demo programs</primary>
</indexterm></title>
<para>The drawing program demo in <filename>/usr/dt/examples/template</filename>
is internationalized. Read the <command>README</command> file for detailed
information on this demo.</para>
<sect3 id="RDMAP.recin.div.22">
<title>Related Documentation</title>
<para>For more information on Common Desktop Environment internationalization,
see the development environment component man pages and the <emphasis>Internationalization
Programmer's Guid</emphasis><emphasis>e</emphasis>.<indexterm><primary>guidelines</primary><secondary>internationalization &lt;$endrange></secondary></indexterm></para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.recin.div.23">
<title id="RDMAP.recin.mkr.12">Standard Font Names</title>
<para>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.<indexterm><primary>fonts</primary>
<secondary>standard font names</secondary></indexterm><indexterm><primary>guidelines</primary><secondary>font use &lt;$startrange></secondary></indexterm></para>
<para>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.
</para>
<para>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 <symbol role="Variable">not</symbol> change their default fonts.<indexterm>
<primary>interface fonts</primary></indexterm><indexterm><primary>fonts</primary><secondary>interface</secondary></indexterm></para>
<sect2 id="RDMAP.recin.div.24">
<title>Application Fonts<indexterm><primary>application fonts &lt;$startrange></primary></indexterm><indexterm>
<primary>fonts</primary><secondary>application &lt;$startrange></secondary></indexterm></title>
<para>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:</para>
<programlisting><filename>-dt-application-*</filename></programlisting>
<para>when used where such patterns are valid.</para>
<para>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:</para>
<itemizedlist remap="Bullet1"><listitem><para>Serif proportionally spaced
</para>
</listitem><listitem><para>Sans serif proportionally spaced</para>
</listitem><listitem><para>Serif monospaced</para>
</listitem><listitem><para>Sans serif monospaced</para>
</listitem></itemizedlist>
<para>Common examples of each of these four designs (in corresponding order)
are:</para>
<itemizedlist remap="Bullet1"><listitem><para>Times Roman</para>
</listitem><listitem><para>Helvetica</para>
</listitem><listitem><para>Courier</para>
</listitem><listitem><para>Lucida Typewriter</para>
</listitem></itemizedlist>
<para>Each of these designs for text fonts typically come in four styles (combinations
of weight and slant):</para>
<itemizedlist remap="Bullet1"><listitem><para>Plain</para>
</listitem><listitem><para>Bold</para>
</listitem><listitem><para>Italic</para>
</listitem><listitem><para>Bold-italic</para>
</listitem></itemizedlist>
<para>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 <emphasis>Adobe&reg; 13</emphasis>&mdash;the minimum set of fonts built
into all PostScript printers.</para>
<para>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.</para>
<para>Specify the<indexterm><primary>XLFD font names</primary></indexterm><indexterm>
<primary>fonts</primary><secondary>XLFD</secondary></indexterm><indexterm>
<primary>standard font names</primary><secondary>XLFD font names</secondary>
</indexterm> XLFD font names for the standard application fonts your application
needs as font resource values in the application's <filename><indexterm><primary>app-defaults file</primary></indexterm><indexterm><primary>standard font
names</primary><secondary>app-defaults file</secondary></indexterm>app-defaults</filename> file. If you do not use these font names, you might need to supply
a different <computeroutput>app-defaults</computeroutput> file for each application
on each Common Desktop Environment platform<literal><indexterm><primary>application fonts &lt;$endrange></primary></indexterm><indexterm><primary>fonts</primary><secondary>application &lt;$endrange></secondary></indexterm></literal>.
</para>
</sect2>
<sect2 id="RDMAP.recin.div.25">
<title>Interface Fonts<indexterm><primary>interface fonts</primary></indexterm><indexterm>
<primary>fonts</primary><secondary>interface</secondary></indexterm><indexterm>
<primary>standard font names</primary><secondary>interface fonts</secondary>
</indexterm></title>
<para>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.</para>
<para>The desktop and the Motif toolkit widgets use interface fonts. Do not
use these fonts directly within your application windows.</para>
<para>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:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>System</emphasis>&mdash;Read-only
text (used for limited amounts of text, for example, on menus, buttons, and
labels)</para>
</listitem><listitem><para><emphasis>User</emphasis>&mdash;Text the end user
enters, or text appearing in objects built from <command>XmText</command>-type
and <command>DtTerm</command>-type widgets</para>
</listitem><listitem><para><emphasis>User bold</emphasis>&mdash;Like the User
font, but in bold</para>
</listitem></itemizedlist>
<para>Each style comes in seven sizes. Using the<indexterm><primary>Style
Manager</primary></indexterm><indexterm><primary>fonts</primary><secondary>interface</secondary><tertiary>and the Style Manager</tertiary></indexterm> Style
Manager, users can choose the size of interface fonts they want on their
desktop.</para>
</sect2>
<sect2 id="RDMAP.recin.div.26">
<title>Demo Programs<indexterm><primary>standard font names</primary><secondary>demo programs</secondary></indexterm></title>
<para>The drawing program demo in <filename>/usr/dt/examples/template</filename>
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.</para>
<sect3 id="RDMAP.recin.div.27">
<title>Related Documentation</title>
<para>For more information on standard fonts, see the relevant man pages&mdash;particularly
<filename>DtStdAppFontNames(5)</filename> and <filename>DtStdInterfaceFontNames(5)</filename> for the list of XLFD font names&mdash;and the <emphasis>Programmer's
Guid</emphasis><emphasis>e</emphasis>.<indexterm><primary>XLFD font names</primary></indexterm><indexterm><primary>fonts</primary><secondary>XLFD</secondary></indexterm><indexterm><primary>fonts</primary><secondary>standard
font names</secondary></indexterm><indexterm><primary>guidelines</primary>
<secondary>font use &lt;$endrange></secondary></indexterm></para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.recin.div.28">
<title id="rdmap.recin.mkr.13">Displaying Error Messages from Your Application<indexterm>
<primary>error messages</primary><secondary>displaying</secondary></indexterm><indexterm>
<primary>guidelines</primary><secondary>error message display &lt;$startrange></secondary></indexterm></title>
<para>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.</para>
<para>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 (<filename>$HOME/.dt/*log</filename>)
that many users do not routinely examine or know about.</para>
<sect2 id="RDMAP.recin.div.29">
<title>How to Present Error Messages<indexterm><primary>error messages</primary>
<secondary>how to display</secondary></indexterm></title>
<para>Follow these rules when deciding where to tell users about warnings,
messages, and error conditions:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>If this message is
informational,</emphasis> display the text in the message footer of the application.
(<emphasis>Example:</emphasis> &ldquo;<command>MyDoc</command> file copied.&rdquo;)
</para>
</listitem><listitem><para><emphasis>If this message is about an error or
serious warning</emphasis>&mdash;a problem where an operation important to
the user has failed&mdash;display an error dialog box or warning dialog box.
</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="RDMAP.recin.div.30">
<title>What Information to Present in Error Dialogs<indexterm><primary>error
messages</primary><secondary>information to present in error dialogs</secondary>
</indexterm></title>
<para>A good error dialog or warning dialog gives a user the following information:
</para>
<itemizedlist remap="Bullet1"><listitem><para>What happened (from the user's
point of view)</para>
</listitem><listitem><para>Why it happened, in simple language</para>
</listitem><listitem><para>How to fix the problem</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="RDMAP.recin.div.31">
<title>Linking Message Dialogs to Online Help<indexterm><primary>error messages</primary><secondary>linking message dialogs to online help</secondary></indexterm></title>
<para>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.</para>
<sect3 id="RDMAP.recin.div.32">
<title>Related Documentation</title>
<para>For details on displaying error messages in your application and linking
message dialogs to online help, see the <emphasis>Programmer's Guide</emphasis> .<indexterm>
<primary>error messages</primary><secondary>displaying</secondary></indexterm><indexterm>
<primary>guidelines</primary><secondary>error message display &lt;$endrange></secondary></indexterm></para>
</sect3>
</sect2>
<sect2 id="RDMAP.recin.div.32a">
<title>Using Message Logging</title>
<indexterm><primary>error messages</primary><secondary>logging</secondary></indexterm>
<para>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.
</para>
<para>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.
</para>
</sect2>
</sect1>
<sect1 id="RDMAP.recin.div.32b">
<title>Printing</title>
<indexterm><primary>printing</primary></indexterm>
<para>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.
</para>
<para>Two facilities for supporting printing are available to the application
developer:
</para>
<itemizedlist>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>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.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="RDMAP.recin.div.33">
<title id="RDMAP.recin.mkr.14">User Customization Issues<indexterm><primary>user customization issues</primary></indexterm><indexterm><primary>customization</primary><secondary>user issues &lt;$startrange></secondary></indexterm></title>
<para>This section presents guidelines to follow when designing your application's
user interface.</para>
<sect2 id="RDMAP.recin.div.34">
<title>Color Use<indexterm><primary>user customization issues</primary><secondary>color use</secondary></indexterm><indexterm><primary>color use and user
customization</primary></indexterm><indexterm><primary>guidelines</primary>
<secondary>color use</secondary></indexterm></title>
<para>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:
</para>
<itemizedlist remap="Bullet1"><listitem><para>Black</para>
</listitem><listitem><para>White</para>
</listitem><listitem><para>Red</para>
</listitem><listitem><para>Green</para>
</listitem><listitem><para>Blue</para>
</listitem><listitem><para>Yellow</para>
</listitem><listitem><para>Cyan</para>
</listitem><listitem><para>Magenta</para>
</listitem><listitem><para>Gray (eight shades: #de, #bd, #ab, #94, #73, #63,
#42, and #21)</para>
</listitem></itemizedlist>
<para>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.</para>
</sect2>
<sect2 id="RDMAP.recin.div.35">
<title>Font Use<indexterm><primary>user customization issues</primary><secondary>font use</secondary></indexterm><indexterm><primary>fonts</primary><secondary>user customization issues</secondary></indexterm><indexterm><primary>guidelines</primary><secondary>font use</secondary></indexterm></title>
<para>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 <computeroutput>fontList</computeroutput> resource specifications, then you must provide
additional functionality if you want users to be able to customize the fonts
in your application.</para>
<para>Use the fonts from the Common Desktop Environment standard application
font names to specify&mdash;in your <computeroutput><indexterm><primary>app-defaults file</primary></indexterm>app-defaults</computeroutput> file&mdash;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 <!--Original XRef content:
'&xd2;Standard Font Names&xd3; on page&numsp;55'--><xref role="SecTitleAndPageNum"
linkend="RDMAP.recin.mkr.12">.</para>
<note>
<para>The<indexterm><primary>Style Manager</primary></indexterm> Style Manager
only controls fonts for applications written using Motif version 2.1 or later.
It will <symbol role="Variable">not</symbol> supply correct fonts for Motif
1.1 (or earlier) applications. These applications must specify their own
fonts in the <filename>app-defaults</filename> file.</para>
</note>
</sect2>
<sect2 id="RDMAP.recin.div.36">
<title>Accessibility<indexterm><primary>user customization issues</primary>
<secondary>accessibility &lt;$startrange></secondary></indexterm><indexterm><primary>guidelines</primary>
<secondary>accessibility &lt;$startrange></secondary></indexterm></title>
<para>This section provides guidelines for making software applications accessible
to people with disabilities.</para>
<sect3 id="RDMAP.recin.div.37">
<title>Physical Disabilities<indexterm><primary>accessibility</primary><secondary>physical disabilities</secondary></indexterm><indexterm><primary>physical
disabilities and user customization</primary></indexterm><indexterm><primary>disabilities and user customization</primary><secondary>physical</secondary>
</indexterm></title>
<para>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.</para>
</sect3>
<sect3 id="RDMAP.recin.div.38">
<title>Visual Disabilities<indexterm><primary>accessibility</primary><secondary>visual disabilities</secondary></indexterm><indexterm><primary>visual disabilities
and user customization</primary></indexterm><indexterm><primary>disabilities
and user customization</primary><secondary>visual</secondary></indexterm></title>
<para>Follow these guidelines to make your application more accessible to
people with visual disabilities:</para>
<itemizedlist remap="Bullet1"><listitem><para>Do not hardcode application
colors.</para>
</listitem><listitem><para>Do not hardcode graphic attributes such as line,
border, and shadow thickness. These attributes should scale with font size.
</para>
</listitem><listitem><para>Do not hardcode font sizes and styles.</para>
</listitem><listitem><para>Provide descriptive names for all widgets. In particular,
include descriptive names <emphasis>in your application code</emphasis> 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.</para>
</listitem></itemizedlist>
</sect3>
<sect3 id="RDMAP.recin.div.39">
<title>Hearing Disabilities<indexterm><primary>accessibility</primary><secondary>hearing disabilities</secondary></indexterm><indexterm><primary>hearing disabilities
and user customization</primary></indexterm><indexterm><primary>disabilities
and user customization</primary><secondary>hearing</secondary></indexterm></title>
<para>Follow these guidelines to make your application more accessible to
people with hearing disabilities:</para>
<itemizedlist remap="Bullet1"><listitem><para>Never assume that an end user
will hear an audible notification.</para>
</listitem><listitem><para>Where appropriate, allow end users to choose between
audible or visual cues.</para>
</listitem><listitem><para>Do not overuse or rely exclusively on audible cues.
</para>
</listitem><listitem><para>Enable end users to configure frequency and volume
of audible cues.</para>
</listitem></itemizedlist>
</sect3>
<sect3 id="RDMAP.recin.div.40">
<title>Language, Cognitive, and Other Disabilities<indexterm><primary>accessibility</primary><secondary>language, cognitive, and other disabilities</secondary>
</indexterm><indexterm><primary>language disabilities and user customization</primary></indexterm><indexterm><primary>disabilities and user customization</primary><secondary>language, cognitive, and other</secondary></indexterm></title>
<para>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.<indexterm>
<primary>user customization issues</primary><secondary>accessibility &lt;$endrange></secondary></indexterm><indexterm>
<primary>guidelines</primary><secondary>accessibility &lt;$endrange></secondary></indexterm></para>
</sect3>
</sect2>
<sect2 id="RDMAP.recin.div.41">
<title>Mouse Double-Click Speed<indexterm><primary>mouse double-click speed</primary></indexterm><indexterm><primary>guidelines</primary><secondary>mouse double-click speed</secondary></indexterm><indexterm><primary>user
customization issues</primary><secondary>mouse double-click speed</secondary>
</indexterm></title>
<para>For the end user to experience consistency across applications, you
should not hardcode double-click durations into your application or <filename><indexterm>
<primary>app-defaults file</primary></indexterm>app-defaults</filename> files.
This way, when the user changes the double-click time in the<indexterm>
<primary>Style Manager</primary></indexterm> Style Manager, your application
responds along with the other desktop applications.</para>
</sect2>
<sect2 id="RDMAP.recin.div.42">
<title>Demo Programs<indexterm><primary>user customization issues</primary>
<secondary>demo program</secondary></indexterm></title>
<para>The drawing program demo in <filename>/usr/dt/examples/template</filename>
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 <command>README</command> file for detailed information
on this demo.</para>
<sect3 id="RDMAP.recin.div.43">
<title>Related Documentation</title>
<para>For more information on user customization issues, see the <emphasis>Style Guide and Certification Checklist</emphasis>.<indexterm><primary>customization</primary><secondary>user issues &lt;$endrange></secondary></indexterm><indexterm><primary>recommended integration &lt;$endrange></primary></indexterm><indexterm>
<primary>levels of integration</primary><secondary>recommended &lt;$endrange></secondary></indexterm><indexterm>
<primary>integration</primary><secondary>recommended &lt;$endrange></secondary></indexterm></para>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->
<?Pub *0000053768>

619
cde/doc/C/guides/progOview/ch07.sgm Normal file
View File

@@ -0,0 +1,619 @@
<!-- $XConsortium: ch07.sgm /main/12 1996/09/08 19:47:09 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<chapter id="RDMAP.optin.div.1">
<title id="RDMAP.optin.mkr.1">Optional Integration</title>
<para>The Common Desktop Environment components discussed in this chapter
enable you to leverage services provided by the desktop for achieving specialized
tasks.<indexterm><primary>optional integration &lt;$startrange></primary></indexterm><indexterm><primary>integration</primary><secondary>optional</secondary></indexterm><indexterm><primary>levels of integration</primary><secondary>optional &lt;$startrange></secondary></indexterm></para>
<informaltable id="RDMAP.optin.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Common Desktop Environment Motif
Control Widgets64'--><xref role="JumpText" linkend="RDMAP.optin.mkr.2"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Data Typing67'--><xref role="JumpText"
linkend="RDMAP.optin.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Action Invocation69'--><xref role="JumpText"
linkend="RDMAP.optin.mkr.4"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Workspace Manager70'--><xref role="JumpText"
linkend="RDMAP.optin.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Terminal Emulator Widget72'--><xref
role="JumpText" linkend="RDMAP.optin.mkr.6"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Text Editor Widget73'--><xref role="JumpText"
linkend="RDMAP.optin.mkr.7"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Calendar74'--><xref role="JumpText"
linkend="RDMAP.optin.mkr.8"></para></entry></row>
<row rowsep="1">
<entry><para>Information Manager ??</para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Desktop KornShell (dtksh)76'--><xref
role="JumpText" linkend="RDMAP.optin.mkr.9"></para></entry></row></tbody>
</tgroup></informaltable>
<note>
<para>In addition to incorporating any components described in this section
into your application, you should also follow the basic integration steps
outlined in <!--Original XRef content: 'Chapter&numsp;5, &xd2;Basic Application
Integration'--><xref role="ChapNumAndTitle" linkend="RDMAP.BIntg.mkr.1">.
The components discussed in <!--Original XRef content: 'Chapter&numsp;6,
&xd2;Recommended Integration'--><xref role="ChapNumAndTitle" linkend="RDMAP.recin.mkr.1">,
are critical to making your application highly integrated with the desktop.
</para>
</note>
<para>For more information on optional integration, see the <emphasis>Programmer's
Guide</emphasis>.</para>
<sect1 id="RDMAP.optin.div.2">
<title id="RDMAP.optin.mkr.2">Common Desktop Environment Motif Control Widgets</title>
<para>The Common Desktop Environment Motif<indexterm><primary>widget</primary>
<secondary>Common Desktop Environment &lt;$startrange></secondary></indexterm> control widgets are designed to
ease porting<indexterm><primary>OPEN LOOK</primary></indexterm> OPEN LOOK
and<indexterm><primary>Microsoft Windows</primary></indexterm> Microsoft
Windows applications to the Common Desktop Environment by providing equivalent
functionality in Common Desktop Environment Motif. The Common Desktop Environment
Motif widgets library <command>libDtWidget</command> contains widgets and
functions that are used to provide common functionality across all Common
Desktop Environment applications. The widgets provided include:</para>
<itemizedlist remap="Bullet1"><listitem><para>Text field and arrow button
widget (<filename>DtSpinBox)<indexterm><primary>text field and arrow button
widget (DtSpinBox)</primary></indexterm><indexterm><primary>DtSpinBox</primary>
</indexterm><indexterm><primary>Common Desktop Environment widgets</primary>
<secondary>DtSpinBox</secondary></indexterm></filename></para>
</listitem></itemizedlist>
<figure>
<title>Example of text field and arrow button widget (<command>DtSpinBox</command>)</title>
<graphic id="RDMAP.optin.grph.1" entityref="RDMAP.optin.fig.1"></graphic>
</figure>
<itemizedlist remap="Bullet1"><listitem><para>Text field and list box widget
(<filename>DtComboBox)<indexterm><primary>text field and list box widget (DtComboBox)</primary></indexterm><indexterm><primary>DtComboBox</primary></indexterm><indexterm>
<primary>Common Desktop Environment widgets</primary><secondary>DtComboBox</secondary></indexterm></filename></para>
</listitem></itemizedlist>
<figure>
<title>Examples of text field and list box widget (<command>DtComboBox</command>)</title>
<graphic id="RDMAP.optin.grph.2" entityref="RDMAP.optin.fig.2"></graphic>
<graphic id="RDMAP.optin.grph.4" Entityref="RDMAP.optin.fig.4"></graphic>
</figure>
<itemizedlist remap="Bullet1"><listitem><para>Menu button widget
(<filename>DtMenuButton)<indexterm><primary>menu button widget (DtMenuButton)</primary>
</indexterm><indexterm><primary>DtMenuButton</primary></indexterm><indexterm>
<primary>Common Desktop Environment widgets</primary><secondary>DtMenuButton</secondary></indexterm></filename></para>
</listitem></itemizedlist>
<figure>
<title>Example of menu button widget (<command>DtMenuButton</command>)</title>
<graphic id="RDMAP.optin.grph.3" entityref="RDMAP.optin.fig.3"></graphic>
</figure>
<para>The Common Desktop Environment Motif Widget library <command>libDtWidget</command> 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.</para>
<note>
<para>The Common Desktop Environment supports all<indexterm><primary>Motif</primary></indexterm><indexterm><primary>widget</primary><secondary>Motif</secondary></indexterm> Motif widgets.</para>
</note>
<table id="RDMAP.optin.tbl.1" frame="Topbot">
<title>Common Desktop Environment Control Widgets</title>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="143*">
<colspec colwidth="313*">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Widget Name</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Description</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para><command>DtSpinBox</command></para></entry>
<entry align="left" valign="top"><para><command>TextField</command> widget
with additional controls for incrementing and decrementing numeric values,
or browsing through and selecting from a list of text strings</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>DtComboBox</command></para></entry>
<entry align="left" valign="top"><para>Combination of <command>TextField</command>
and pop-up List widgets that provides a list of valid choices for the <command>TextField</command></para></entry></row>
<row>
<entry align="left" valign="top"><para><command>DtMenuButton</command></para></entry>
<entry align="left" valign="top"><para>Command widget that provides menu cascading
functionality of an <command>XmCascadeButton</command> widget outside of
a Menu Bar, or a Menu Pane (a pull-down menu, a pop-up menu, or an option
menu)</para></entry></row></tbody></tgroup></table>
<sect2 id="RDMAP.optin.div.4">
<title>Library and Header Files<indexterm><primary>Common Desktop Environment
widgets</primary><secondary>library and header files</secondary></indexterm></title>
<para>The library <command>libDtWidget</command> provides access to the <command>DtSpinBox</command>, <command>DtComboBox</command>, and <command>DtMenuButton</command> widgets. The <command>libDtWidget</command> header files for these
widgets are:</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>Dt/SpinBox.h</filename></para>
</listitem><listitem><para><filename>Dt/ComboBox.h</filename></para>
</listitem><listitem><para><filename>Dt/MenuButton.h</filename></para>
</listitem></itemizedlist>
</sect2>
<sect2 id="RDMAP.optin.div.5">
<title>Demo Programs<indexterm><primary>Common Desktop Environment widgets</primary><secondary>demo programs</secondary></indexterm><indexterm><primary>demo programs</primary></indexterm></title>
<para>You can find the Common Desktop Environment Motif control widgets demos
in <filename>/usr/dt/examples/dtwidget</filename>. Read the <command>README</command> file for detailed information on the demos.</para>
<sect3 id="RDMAP.optin.div.6">
<title>Related Documentation</title>
<para>For more information on Common Desktop Environment Motif control widgets,
see the relevant man pages and the <emphasis>Programmer's Guide</emphasis>.<indexterm>
<primary>widget</primary><secondary>Common Desktop Environment &lt;$endrange></secondary></indexterm></para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.optin.div.7">
<title id="RDMAP.optin.mkr.3">Data Typing</title>
<para>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.</para>
<para>Data typing provides an extension to the attributes of files and data
beyond what is provided by traditional<indexterm><primary>UNIX</primary>
</indexterm> 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.
</para>
<para>Data typing consist of two parts:<indexterm><primary>data typing</primary>
<secondary>two parts of</secondary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para>A database that stores data
criteria and data attributes</para>
</listitem><listitem><para>A collection of routines that query the database
</para>
</listitem></itemizedlist>
<para>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.</para>
<para>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 <symbol role="Variable">filename</symbol>.<command>c</command>, File Manager uses the. <command>c</command> 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 <symbol role="Variable">filename</symbol>.<command>c</command>.</para>
<sect2 id="RDMAP.optin.div.8">
<title>Database Loading<indexterm><primary>database</primary><secondary>loading</secondary></indexterm><indexterm><primary>data typing</primary><secondary>database loading</secondary></indexterm></title>
<para>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
<filename>/usr/dt/man/man4</filename> directory.</para>
<para>The external database loading API consists of two functions:</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>DtDbLoad()</filename></para>
</listitem><listitem><para><filename>DtDbReloadNotify()</filename></para>
</listitem></itemizedlist>
<para><filename>DtDbLoad()</filename> 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 <filename>.dt</filename> files
that are found. Your application must call <filename>DtDbLoad()</filename>
before calling any of the routines that query the actions and data-types
database.<indexterm><primary>DtDbLoad()</primary></indexterm><indexterm>
<primary>database</primary><secondary>DtDbLoad()</secondary></indexterm></para>
<para><filename>Use DtDbReLoadNotify()</filename> to request notification
of actions and data-types database reload events. It registers an application's
interest in database reload messages. <filename><indexterm><primary>DtDbReLoadNotify()</primary></indexterm><indexterm><primary>database</primary><secondary>DtDbReLoadNotify()</secondary></indexterm></filename></para>
<para>Your application should reload the database whenever it changes, so
that the end user will notice updates without having to restart the application.
</para>
</sect2>
<sect2 id="RDMAP.optin.div.9">
<title>Database Queries<indexterm><primary>database</primary><secondary>query
functions</secondary></indexterm><indexterm><primary>data typing</primary>
<secondary>database query functions</secondary></indexterm></title>
<para>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 <emphasis>Programmer's
Guide</emphasis> and also in man pages in the <filename>man3</filename> directory.
</para>
</sect2>
<sect2 id="RDMAP.optin.div.10">
<title>Library and Header Files<indexterm><primary>data typing</primary><secondary>library and header files</secondary></indexterm></title>
<para>The Desktop Services library, <command>libDtSvc</command>, provides
access to many desktop APIs, including that for data typing. Include the
<filename>Dt/Dt.h</filename> <command>and Dt/Dts.h</command> header files to access
the data-typing API.</para>
<note>
<para>If your application uses any of the data-typing APIs, or loads the
actions and data-types database, it must first initialize the <command>libDtSvc</command> library by calling either <filename><indexterm><primary>DtInitialize()</primary></indexterm>DtInitialize()</filename> or <filename><indexterm><primary>DtAppInitialize()</primary></indexterm>DtAppInitialize()</filename>. Refer
to the <filename>DtInitialize</filename>(3) or
<filename>DtAppInitialize</filename>(3) man page for more information.</para>
</note>
</sect2>
<sect2 id="RDMAP.optin.div.11">
<title>Demo Programs<indexterm><primary>data typing</primary><secondary>demo
programs</secondary></indexterm><indexterm><primary>demo programs</primary>
</indexterm></title>
<para>You can find the data typing demos in
<filename>/usr/dt/examples/dtdts</filename>.
Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.optin.div.12">
<title>Related Documentation</title>
<para>For more information on data typing, see the relevant man pages and
the <emphasis>Programmer's Guide</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.optin.div.13">
<title id="RDMAP.optin.mkr.4">Action Invocation</title>
<para>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 <command>Class</command>, <command>Type</command>, <command>Mode</command>, and <command>Number</command> 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.</para>
<para>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.</para>
<para>The action functions in the <command>libDtSvc</command> 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:<indexterm><primary>action invocation</primary><secondary>API</secondary></indexterm></para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.13in">
<colspec align="left" colwidth="216*">
<colspec align="left" colwidth="289*">
<tbody>
<row>
<entry align="left" valign="top"><para><filename>DtActionInvoke()</filename></para></entry>
<entry align="left" valign="top"><para>Invokes the specified action on its
arguments, which can be files or buffers</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>DtActionLabel()</filename></para></entry>
<entry align="left" valign="top"><para>Provides access to the localizable
label string associated with an action</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>DtActionDescription()</filename></para></entry>
<entry align="left" valign="top"><para>Returns a string containing the description
information associated with the action your application called</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>DtActionExists()</filename></para></entry>
<entry align="left" valign="top"><para>A Boolean function that checks whether
a given name corresponds to an existing action</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>DtActionIcon()</filename></para></entry>
<entry align="left" valign="top"><para>Returns the name of the icon associated
with the specified action</para></entry></row></tbody></tgroup></informaltable>
<sect2 id="rdmap.optin.div.14">
<title>Library and Header Files<indexterm><primary>action invocation</primary>
<secondary>library and header files</secondary></indexterm></title>
<para>The desktop services library, <command>libDtSvc</command>, provides
access to many desktop APIs, including that for actions. Include the
<filename>Dt/Dt.h</filename> and <filename>Dt/Action.h</filename> header files to access
the actions API.</para>
<note>
<para>If your application uses any of the action invocation APIs, it must
first initialize the <command>libDtSvc</command> library by calling either <filename><indexterm>
<primary>DtInitialize()</primary></indexterm>DtInitialize()</filename> or
<filename><indexterm><primary>DtAppInitialize()</primary></indexterm>DtAppInitialize()</filename>. Refer to the <filename>DtInitialize</filename>(3) or
<filename>DtAppInitialize</filename>(3) man page for more information.</para>
</note>
</sect2>
<sect2 id="rdmap.optin.div.15">
<title>Demo Programs<indexterm><primary>action invocation</primary><secondary>demo programs</secondary></indexterm><indexterm><primary>demo programs</primary>
</indexterm></title>
<para>You can find the action invocation demos in
<filename>/usr/dt/examples/dtaction</filename>.
Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="rdmap.optin.div.16">
<title>Related Documentation</title>
<para>For more information on actions, see the relevant man pages and the <emphasis>Programmer's Guide</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.optin.div.17">
<title id="RDMAP.optin.mkr.5">Workspace Manager</title>
<para>The Common Desktop Environment Workspace Manager provides support for
multiple workspaces. Each workspace is a <emphasis>virtual screen</emphasis>.
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.</para>
<para>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.</para>
<para>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<indexterm><primary>Motif 1.2</primary></indexterm> Motif 1.2,
you do not have to integrate with the Common Desktop Environment Workspace
Manager for the application to run on the desktop.</para>
<para>However, more complex applications with multiple top-level windows need
to use the Workspace Manager API in conjunction with the<indexterm><primary>Session Manager</primary></indexterm> 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.</para>
<para>The Workspace Manager API addresses the following tasks:</para>
<itemizedlist remap="Bullet1"><listitem><para>Get information on workspaces
</para>
</listitem><listitem><para>Get and set the current workspace</para>
</listitem><listitem><para>Notify a client of changes to workspace state</para>
</listitem><listitem><para>Add and remove workspace functions for a client
</para>
</listitem><listitem><para>Get and set the workspaces occupied by a client
</para>
</listitem><listitem><para>Identify backdrop windows</para>
</listitem></itemizedlist>
<para>All Workspace Manager API functions share the prefix <command>DtWsm</command>.</para>
<sect2 id="RDMAP.optin.div.18">
<title>Library and Header Files<indexterm><primary>Workspace Manager</primary>
<secondary>library and header files</secondary></indexterm></title>
<para>The desktop services library, <command>libDtSvc</command>, provides
access to many desktop APIs, including that for Workspace Manager. Include
the <filename>Dt/Dt.h</filename> and <filename>Dt/Wsm.h</filename> header
files to access the Workspace Manager API.</para>
<note>
<para>If your application uses any of the Workspace Manager APIs, it must
first initialize the <command>libDtSvc</command> library by calling either <filename><indexterm>
<primary>DtInitialize()</primary></indexterm>DtInitialize()</filename> or
<filename><indexterm><primary>DtAppInitialize()</primary></indexterm>DtAppInitialize()</filename>.
Refer to the <filename>DtInitialize</filename>(3) or
<filename>DtAppInitialize</filename>(3) man page for more information.</para>
</note>
</sect2>
<sect2 id="RDMAP.optin.div.19">
<title>Demo Programs<indexterm><primary>Workspace Manager</primary><secondary>demo programs</secondary></indexterm><indexterm><primary>demo programs</primary>
</indexterm></title>
<para>You can find the Workspace Manager demos in
<filename>/usr/dt/examples/dtwsm</filename>.
Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.optin.div.20">
<title>Related Documentation</title>
<para>For more information on Workspace Manager, see the relevant man pages
and the <emphasis>Programmer's Guide</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.optin.div.21">
<title id="RDMAP.optin.mkr.6">Terminal Emulator Widget</title>
<para>The <command>DtTerm</command> 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,
<filename>libDtTerm,</filename> provides the <command>DtTerm</command> 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.<indexterm><primary>DEC VT220</primary></indexterm><indexterm><primary>Terminal Emulator</primary>
<secondary>DEC VT220-like</secondary></indexterm><indexterm><primary>widget</primary><secondary>DtTerm</secondary></indexterm><indexterm><primary>Terminal
Emulator</primary><secondary>DtTerm widget</secondary></indexterm></para>
<para>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 <command>DtTerm</command> widget is the foundation for the desktop run-time
terminal emulator, <command>dtterm</command>.<indexterm><primary>run-time</primary><secondary>terminal emulator</secondary></indexterm></para>
<para>The <command>libDtTerm</command> library includes a set of convenience
functions to create, access, and support the <command>DtTerm</command> widget.
</para>
<sect2 id="RDMAP.optin.div.22">
<title>Library and Header Files<indexterm><primary>Terminal Emulator Widget</primary><secondary>library and header files</secondary></indexterm></title>
<para>The <command>libDtTerm</command> library provides a set of widgets based
on Motif for designing a terminal emulator or for adding a terminal emulator
window to a GUI.</para>
<para>Include the <filename>Dt/Term.h</filename> header file to access <command>libDtTerm</command> APIs in your application.</para>
</sect2>
<sect2 id="RDMAP.optin.div.23">
<title>Demo Programs<indexterm><primary>Terminal Emulator Widget</primary>
<secondary>demo programs</secondary></indexterm><indexterm><primary>demo
programs</primary></indexterm></title>
<para>You can find the Terminal Emulator demos in
<filename>/usr/dt/examples/dtterm</filename>.
Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.optin.div.24">
<title>Related Documentation</title>
<para>For more information on the <command>DtTerm</command> widget, see the
relevant man pages.</para>
<para>For more information on the desktop terminal emulator, see the terminal
emulator help volume, the relevant man pages, or the <emphasis>User's Guide</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.optin.div.25">
<title id="RDMAP.optin.mkr.7">Text Editor Widget</title>
<para>The Common Desktop Environment text editing system consists of two
components:</para>
<itemizedlist remap="Bullet1"><listitem><para><command>The text editor application,
dtpad</command>, which provides editing services through graphical, action,
and ToolTalk interfaces<command><indexterm><primary>dtpad</primary></indexterm><indexterm>
<primary>Text Editor</primary><secondary>dtpad</secondary></indexterm></command></para>
</listitem><listitem><para><command>The editor widget, DtEditor</command>,
which provides a programmatic interface for the following editing services:<command><indexterm>
<primary>Text Editor</primary><secondary>DtEditor widget</secondary></indexterm></command></para>
<itemizedlist remap="Bullet2"><listitem><para>Cut and paste</para>
</listitem><listitem><para>Search and replace</para>
</listitem><listitem><para>Simple formatting</para>
</listitem><listitem><para>Spell checking (for 8-bit locales)</para>
</listitem><listitem><para>Undo previous edit</para>
</listitem><listitem><para>Enhanced I/O handling capabilities that support
input and output of ASCII text, multibyte text, and buffers of data</para>
</listitem><listitem><para>Support for reading and writing files directly
</para>
</listitem></itemizedlist>
</listitem></itemizedlist>
<para>Although the Motif text widget also provides a programmatic interface,
applications that want to assure a system-wide uniform editor should use
the <command>DtEditor</command> widget. The Common Desktop Environment Text
Editor and Mailer use the editor widget. Use this widget in the following
circumstances:<indexterm><primary>Text Editor</primary><secondary>when to
use widget &lt;$startrange></secondary>
</indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para>You need the functionality,
such as spell checking, undo, and find/change, that is provided by the <command>DtEditor</command> widget.</para>
</listitem><listitem><para>You want users to be able to read and write data
to and from a file.</para>
</listitem><listitem><para>When your program does not need to edit the text
while the widget has control of the text<indexterm><primary>Text Editor</primary><secondary>when to use widget &lt;$endrange></secondary></indexterm>.</para>
</listitem></itemizedlist>
<sect2 id="RDMAP.optin.div.26">
<title>Library and Header Files<indexterm><primary>Text Editor</primary><secondary>library and header files</secondary></indexterm></title>
<para>The <command>DtEditor</command> widget is in the <command>libDtWidget</command> library. The header file is <filename>Dt/Editor.h</filename>.
</para>
</sect2>
<sect2 id="RDMAP.optin.div.27">
<title>Demo Programs<indexterm><primary>Text Editor</primary><secondary>demo programs</secondary></indexterm></title>
<para>A demo containing an example of the <command>DtEditor</command> widget
(<filename>editor.c</filename>) is in
<filename>/usr/dt/examples/dtwidget</filename> directory.
Read the <command>README</command> file for detailed
information on the demo.</para>
<sect3 id="RDMAP.optin.div.28">
<title>Related Documentation</title>
<para>For more information on the Text Editor widget, see the relevant man
pages and the <emphasis>Programmer's Guide</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.optin.div.29">
<title id="RDMAP.optin.mkr.8">Calendar</title>
<para>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.<indexterm><primary>run-time</primary><secondary>Calendar GUI</secondary></indexterm></para>
<para>Calendar consists of:</para>
<itemizedlist remap="Bullet1"><listitem><para>A daemon that manages the calendar
database</para>
</listitem><listitem><para>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</para>
</listitem><listitem><para>A library implementation of the calendar and scheduling
API</para>
</listitem></itemizedlist>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>Calendar entry data integrates with the desktop through drag and drop
and the ToolTalk messaging interfaces.</para>
<para>The calendar and scheduling API is an implementation of the X.400 Application
Programming Interface Association (<indexterm><primary>X.400 API Association
(XAPIA)</primary></indexterm><indexterm><primary>Calendar</primary><secondary>XAPIA</secondary></indexterm>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.</para>
<sect2 id="RDMAP.optin.div.30">
<title>Library and Header Files<indexterm><primary>Calendar</primary><secondary>library and header files</secondary></indexterm></title>
<para>The Calendar library, <command>libcsa</command>, provides a programmatic
way to access and manage Calendar data in a networked environment.</para>
<para>Include the <filename>csa/csa.h</filename> header file to access <command>libcsa</command> APIs in your application.</para>
</sect2>
<sect2 id="RDMAP.optin.div.31">
<title>Demo Programs<indexterm><primary>Calendar</primary><secondary>demo
programs</secondary></indexterm><indexterm><primary>demo programs</primary>
</indexterm></title>
<para>You can find the Calendar demos in
<filename>/usr/dt/examples/dtcalendar</filename>.
Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.optin.div.32">
<title>Related Documentation</title>
<para>For more information on the calendar, see the relevant man pages, the
Calendar help volume, and the <emphasis>Programmer's Guide</emphasis>.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="RDMAP.optin.div.32a">
<title id="RDMAP.optin.mkr.8a">Information Manager</title>
<para><indexterm><primary>information manager</primary><secondary>general information</secondary></indexterm>The Information Manager provides access to on-line documentation, organized
in a manner that is typical of hardcopy manuals: bookcases contain books, which
contain sections, which in turn contain subsections, and so on. The Information Manager is
is separate from the Help facility.
</para>
<sect2 id="RDMAP.optin.div.32b">
<title>Header Files</title>
<indexterm><primary>information manager</primary><secondary>header files</secondary></indexterm>
<para>The header files are:
</para>
<itemizedlist>
<listitem>
<para><Filename>/usr/dt/include/Dt/Info.h</Filename>
</para>
</listitem>
<listitem>
<para><Filename>/usr/dt/include/Dt/Search.h</Filename>
</para>
</listitem>
<listitem>
<para><Filename>/usr/dt/include/Dt/Mmdb.h</Filename> (for extending or replacing the default
browser, <command>dtinfo</command>)
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="RDMAP.optin.div.32c">
<title>Related Documentation</title>
<indexterm><primary>information manager</primary><secondary>documentation</secondary></indexterm>
<para>For more information on the Information Manager, refer to
<citetitle>Information System Author's and Programmer's Guide</citetitle>.
</para>
</sect2>
</sect1>
<sect1 id="RDMAP.optin.div.33">
<title id="RDMAP.optin.mkr.9">Desktop KornShell (dtksh)</title>
<para>Desktop KornShell<indexterm><primary>dtksh</primary></indexterm><indexterm>
<primary>Desktop KornShell (dtksh)</primary></indexterm> (which is <command>dtksh</command>) 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.</para>
<para><command>dtksh</command> is a version of <filename><indexterm><primary>ksh-93</primary></indexterm>ksh-93</filename> extended to access many X, Xt,
Motif, and Common Desktop Environment facilities. <filename>ksh-93</filename>
is a version of<indexterm><primary>KornShell</primary></indexterm> KornShell,
the command shell and programming language <command>ksh</command>. <command>dtksh</command> extends <command>ksh</command> to provide support
for:<emphasis><indexterm><primary>Desktop KornShell (dtksh)</primary><secondary>extension of ksh</secondary></indexterm></emphasis></para>
<itemizedlist remap="Bullet1"><listitem><para>Access to the Common Desktop
Environment Motif widget set from within a shell script</para>
</listitem><listitem><para>Fully localized shell scripts&mdash;<command>dtksh</command> scripts can use <command>catopen</command> and <command>catgets</command> commands</para>
</listitem><listitem><para>Access to the Common Desktop Environment application
Help system</para>
</listitem><listitem><para>Response to session-management Save state directives
</para>
</listitem><listitem><para>Access to most of the Common Desktop Environment
Desktop Services Message Set</para>
</listitem><listitem><para>Access to many of the Common Desktop Environment
data-typing API functions</para>
</listitem><listitem><para>Access to most of the Common Desktop Environment
action API functions</para>
</listitem></itemizedlist>
<sect2 id="RDMAP.optin.div.34">
<title>Demo Programs<indexterm><primary>Desktop KornShell (dtksh)</primary>
<secondary>demo programs</secondary></indexterm><indexterm><primary>demo programs</primary></indexterm></title>
<para>You can find the <command>dtksh</command> demos in
<filename>/usr/dt/examples/dtksh</filename>.
Read the <command>README</command> file for detailed information
on the demos.</para>
<sect3 id="RDMAP.optin.div.35">
<title>Related Documentation<?Pub Caret></title>
<para>For more information on <command>dtksh</command>, see the relevant man
pages and <emphasis>Desktop KornShell User's Guide</emphasis>.<indexterm>
<primary>optional integration &lt;$endrange></primary></indexterm><indexterm><primary>integration</primary>
<secondary>optional</secondary></indexterm><indexterm><primary>levels of integration</primary><secondary>optional &lt;$endrange></secondary></indexterm></para>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->
<?Pub *0000039352>

37
cde/doc/C/guides/progOview/credits.sgm Normal file
View File

@@ -0,0 +1,37 @@
<!-- $XConsortium: credits.sgm /main/3 1996/08/18 19:47:18 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<!--Para: Copyright &xd3; 1994, 1995 Hewlett-Packard Company
Copyright &xd3; 1994, 1995 International Business Machines Corp.
Copyright &xd3; 1994, 1995 Sun Microsystems, Inc.
Copyright &xd3; 1994, 1995 Novell, Inc.-->
<!--Para: All rights reserved. This product and related documentation are protected by copyright and distributed under licenses
restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be
reproduced in any form by any means without prior written authorization.-->
<!--Para: RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions
set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19.-->
<!--Para: THIS PUBLICATION IS PROVIDED &xd2;AS IS&xd3; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, OR NON-INFRINGEMENT.-->
<!--Para: The code and documentation for the DtComboBox and DtSpinBox widgets were contributed by Interleaf, Inc. Copyright 1993,
Interleaf, Inc.-->
<!--Para: TRADEMARKS:-->
<!--Para: OPEN LOOK is a registered trademark of Novell, Inc.-->
<!--Para: OpenWindows is a trademark of Sun Microsystems, Inc.-->
<!--Para: ToolTalk is a registered trademark of Sun Microsystems, Inc.-->
<!--Para: NFS is a registered trademark of Sun Microsystems, Inc.-->
<!--Para: X Window System is a trademark of X Consortium, Inc.-->
<!--Para: UNIX is a trademark exclusively licensed through X/Open Company, Ltd.-->
<!--Para: Motif and Motif are trademarks of Open Software Foundation, Ltd.-->
<!--Para: Adobe is a registered trademark of Adobe Systems, Inc.-->
<!--Para: PostScript is a trademark of Adobe Systems, Inc., which may be registered in certain jurisdictions.-->
<!--Para: Microsoft is a registered trademark of Microsoft Corporation.-->
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->

BIN
cde/doc/C/guides/progOview/graphics/ComboBo3.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/progOview/graphics/ComboBox.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/progOview/graphics/MenuBut2.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/progOview/graphics/SpinBox.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/progOview/graphics/fpanel.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/progOview/graphics/road1.cgm Normal file
View File

Binary file not shown.

10
cde/doc/C/guides/progOview/part1.sgm Normal file
View File

@@ -0,0 +1,10 @@
<!-- $XConsortium: part1.sgm /main/1 1996/01/23 18:53:09 vobadm $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Title>Common Desktop Environment Architectural Overview</Title>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->

10
cde/doc/C/guides/progOview/part2.sgm Normal file
View File

@@ -0,0 +1,10 @@
<!-- $XConsortium: part2.sgm /main/1 1996/01/23 18:53:36 vobadm $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<Title>Development Environment Overview</Title>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->

385
cde/doc/C/guides/progOview/preface.sgm Normal file
View File

@@ -0,0 +1,385 @@
<!-- $XConsortium: preface.sgm /main/8 1996/09/08 19:47:18 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<preface id="RDMAP.pref.div.1">
<title id="RDMAP.pref.mkr.1">Preface</title>
<para>The <emphasis>Common Desktop Environment: Programmer's Overview</emphasis>
provides a high-level view of the Common Desktop Environment development
environment and the developer documentation set. Read this book first before
starting application design and development.</para>
<note>
<para>In this manual, the terms <emphasis>(the) Common Desktop Environment</emphasis> and <emphasis>the</emphasis> <emphasis><indexterm><primary>desktop</primary><secondary>Common Desktop Environment</secondary></indexterm>desktop</emphasis> are used interchangeably.</para>
</note>
<para>Outside of the Preface, this manual omits the <emphasis>Common Desktop
Environment</emphasis> prefix when referring to a Common Desktop Environment
development or run-time environment manual. For example, the <emphasis>Common
Desktop Environment: Programmer's Overview</emphasis> is referred to as the <emphasis>Programmer's Overview</emphasis>.</para>
<sect1 id="RDMAP.pref.div.2">
<title>Who Should Use This Book</title>
<para>Read the <emphasis>Programmer's Overview</emphasis> if you are:</para>
<itemizedlist remap="Bullet1"><listitem><para>An application developer who
wants to develop a new Common Desktop Environment application, or integrate
an existing<indexterm><primary>Motif</primary></indexterm> Motif<superscript>
&reg;</superscript> or<indexterm><primary>OPEN LOOK</primary></indexterm> OPEN
LOOK<superscript>&reg;</superscript> application into the desktop</para>
</listitem><listitem><para>A manager, architect, or project lead interested
in designing a project involving applications that will run on the Common
Desktop Environment desktop</para>
</listitem></itemizedlist>
<para>For the remainder of this manual, Motif is referred to as Motif&reg;.
</para>
</sect1>
<sect1 id="RDMAP.pref.div.3">
<title>How This Book Is Organized</title>
<para>The Programmer's Overview is divided into two parts. Part I contains
an architectural overview of the Common Desktop Environment, including high-
level information on both the run-time and development environments. Part
II contains information useful to know before developing an application,
and describes the development environment components.</para>
<para>This section provides brief descriptions of the chapters and appendixes
contained in this manual.</para>
<para><!--Original XRef content: 'Chapter&numsp;1, &xd2;Architectural Overview'--><xref
role="ChapNumAndTitleLead-in" linkend="RDMAP.archo.mkr.1"><emphasis role="Lead-in">,</emphasis> presents an overview of the Common Desktop Environment
architecture.</para>
<para><!--Original XRef content: 'Chapter&numsp;2, &xd2;Development Environment
Considerations'--><xref role="ChapNumAndTitleLead-in" linkend="RDMAP.consi.mkr.1"><emphasis
role="Lead-in">,</emphasis> discusses information you should know
about the environment before you start to develop an application.</para>
<para><!--Original XRef content: 'Chapter&numsp;3, &xd2;Developing an Application'--><xref
role="ChapNumAndTitleLead-in" linkend="RDMAP.devap.mkr.1"><emphasis role="Lead-in">,</emphasis> presents information specific to developing a Common
Desktop Environment application, such as naming conventions and guidelines
to follow.</para>
<para><!--Original XRef content: 'Chapter&numsp;4, &xd2;Portability and Maintenance'--><xref
role="ChapNumAndTitleLead-in" linkend="RDMAP.port.mkr.1"><emphasis role="Lead-in">,</emphasis> discusses issues pertaining to writing portable and
maintainable applications.</para>
<para><!--Original XRef content: 'Chapter&numsp;5, &xd2;Basic Application
Integration'--><xref role="ChapNumAndTitleLead-in" linkend="RDMAP.BIntg.mkr.1"><emphasis
role="Lead-in">,</emphasis> summarizes how to make your application
launch-integrated (that is, started by double-clicking an icon on the desktop).
</para>
<para><!--Original XRef content: 'Chapter&numsp;6, &xd2;Recommended Integration'--><xref
role="ChapNumAndTitleLead-in" linkend="RDMAP.recin.mkr.1"><emphasis role="Lead-in">,</emphasis> provides overviews of all components and guidelines
that you should use so your application has the same look and feel as, and
interoperates well with, other Common Desktop Environment desktop applications.
</para>
<para><!--Original XRef content: 'Chapter&numsp;7, &xd2;Optional Integration'--><xref
role="ChapNumAndTitleLead-in" linkend="RDMAP.optin.mkr.1"><emphasis role="Lead-in">,</emphasis> provides overviews of the components to incorporate
into your application as needed for added functionality.</para>
<para><!--Original XRef content: 'Appendix&numsp;A, &xd2;Component and Guideline
Reference'--><xref role="AppendixNumAndTitleLead-in" linkend="RDMAP.compr.mkr.1"><emphasis
role="Lead-in">,</emphasis> lists in alphabetical order all development
environment components and guidelines, with associated library, header files,
and documentation.</para>
</sect1>
<sect1 id="RDMAP.pref.div.4">
<title id="RDMAP.pref.mkr.2">Related Books</title>
<para>For information on<indexterm><primary>Motif</primary><secondary>related
documentation</secondary></indexterm> Motif, see:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Motif Programmer's
Guide</emphasis>, Release 1.2, by Open Software Foundation, 11 Cambridge
Center, Cambridge, MA 02142, published by PTR Prentice Hall, Englewood Cliffs,
NJ 07632</para>
</listitem><listitem><para><emphasis>Motif Programmer's Reference</emphasis>,
Release 1.2, by Open Software Foundation, 11 Cambridge Center, Cambridge,
MA 02142, published by PTR Prentice Hall, Englewood Cliffs, NJ 07632</para>
</listitem><listitem><para><emphasis>Motif Reference Guide</emphasis>,
by Douglas A. Young, published by PTR Prentice Hall, Englewood Cliffs, NJ
07632</para>
</listitem><listitem><para><emphasis>Motif 1.2 Style Guide</emphasis>,
by Open Software Foundation, 11 Cambridge Center, Cambridge, MA 02142, published
by PTR Prentice Hall, Englewood Cliffs, NJ 07632</para>
</listitem></itemizedlist>
<note>
<para>The <emphasis>Common Desktop Environment: Style Guide and Certification
Checklist</emphasis> is an extension of the <emphasis>Motif 1.2 Style
Guide</emphasis> to the Common Desktop Environment.</para>
</note>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>OSF Application Environment
Specification (AES) User Environment Volume</emphasis>, Revision C, by Open
Software Foundation, 11 Cambridge Center, Cambridge, MA 02142, published
by PTR Prentice Hall, Englewood Cliffs, NJ 07632</para>
</listitem></itemizedlist>
<para>Motif 1.2 IEEE Std 1295 standard, which you can order from: IEEE Service
Center, 445 Hoes Lane, P.O. Box 1331, Piscataway, NJ 08855</para>
<para>For information on POSIX<indexterm><primary>POSIX</primary></indexterm>,
see the IEEE Std 1003.1-1990 standard, which you can order from: IEEE Service
Center, 445 Hoes Lane, P.O. Box 1331, Piscataway, NJ 08855</para>
<para>For information on<indexterm><primary>Xlib documentation</primary>
</indexterm> Xlib, see:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Xlib Programming Manual</emphasis> <emphasis>for Version 11 (Volume 1) by Adrian Nye, published
by O'Reilly &amp; Associates, Sebastopol, CA, 95472</emphasis></para>
</listitem><listitem><para><emphasis>Xlib Reference Manual</emphasis> <emphasis>for Version 11 (Volume 2), published by O'Reilly &amp; Associates, Sebastopol,
CA, 95472</emphasis></para>
</listitem></itemizedlist>
<para>For information on<indexterm><primary>Xt documentation</primary></indexterm> Xt,
see:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>X Toolkit Intrinsics
Programming Manual</emphasis>, (Volume 4) by Adrian Nye and Tim O'Reilly,
published by O'Reilly and Associates, Sebastopol, CA 95472.</para>
</listitem><listitem><para><emphasis>X Toolkit Intrinsics Reference Manual,</emphasis> (Volume 5) edited by Tim O'Reilly, published by O'Reilly and
Associates, Sebastopol, CA 95472.</para>
</listitem></itemizedlist>
<para>For more information on<indexterm><primary>ToolTalk documentation</primary></indexterm> ToolTalk&reg;, see:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>The ToolTalk Service:
An Inter-Operability Solution</emphasis>, published by SunSoft Press and
PTR Prentice Hall, Englewood Cliffs, NJ 07632, ISBN 0-13-088717-X</para>
</listitem><listitem><para><emphasis>ToolTalk and Open Protocols: Inter-Application
Communication</emphasis>, by Astrid Julienne and Brian Holtz, published by
SunSoft Press and PTR Prentice Hall, Englewood Cliffs, NJ 07632, ISBN 013-031055-7
</para>
</listitem></itemizedlist>
<para>In addition to the <emphasis>Programmer's Overview</emphasis>, the<indexterm>
<primary>documentation set</primary><secondary>development environment</secondary>
</indexterm> development environment documentation set consists of:</para>
<itemizedlist remap="Bullet1">
<listitem><para><emphasis>Common Desktop Environment:
Style Guide and Certification Checklist</emphasis></para>
</listitem>
<listitem><para><emphasis>Common Desktop Environment: Application
Builder User's Guide</emphasis></para>
</listitem>
<listitem><para><emphasis>Common Desktop Environment: Programmer's
Guide</emphasis></para>
</listitem>
<listitem><para><emphasis>Common Desktop Environment: Help System
Author's and Programmer's Guide</emphasis></para>
</listitem>
<listitem><para><emphasis>Common Desktop Environment: ToolTalk
Messaging Overview</emphasis></para>
</listitem>
<listitem><para><emphasis>Common Desktop Environment: Internationalization
Programmer's Guide</emphasis></para>
</listitem>
<listitem><para><emphasis>Common Desktop Environment: Desktop KornShell
User's Guide</emphasis></para>
</listitem>
<listitem><para><citetitle>Common Desktop Environment: Information
System Author's and Programmer's Guide</citetitle></para></listitem>
<listitem><para><emphasis>Common Desktop Environment</emphasis>:
Glossary</para>
</listitem><listitem><para>Online man pages</para>
</listitem></itemizedlist>
<para>For more information on these development environment books, see the
following section, <!--Original XRef content: '&xd2;Development Environment
Documentation'--><xref role="SectionTitle" linkend="RDMAP.pref.mkr.3">.
</para>
<para>The run-time environment documentation set consists of:<indexterm>
<primary>documentation set</primary><secondary>run-time</secondary></indexterm><indexterm>
<primary>run-time</primary><secondary>documentation set</secondary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Common Desktop Environment:
User's Guide</emphasis></para>
</listitem><listitem><para><emphasis>Common Desktop Environment: Advanced
User's and System Administrator's Guide</emphasis></para>
</listitem><listitem><para>Online help volumes</para>
</listitem></itemizedlist>
<note>
<para>The <emphasis>Advanced User's and System Administrator's Guide</emphasis>
contains information to help you integrate an application into the desktop.
</para>
</note>
</sect1>
<sect1 id="RDMAP.pref.div.5">
<title id="RDMAP.pref.mkr.3">Development Environment Documentation</title>
<para>This section provides an overview of each manual&mdash;except for the
<emphasis>Programmer's Overview</emphasis>&mdash;in the developer documentation
set.</para>
<sect2 id="RDMAP.pref.div.6">
<title>Common Desktop Environment: Style Guide and Certification Checklist</title>
<para>The <emphasis>Common Desktop Environment: Style Guide and Certification
Checklist</emphasis> provides application design style guidelines and the
list of requirements for Common Desktop Environment application-level certification.
These requirements consist of the Motif requirements with Common Desktop
Environment-specific additions.</para>
<para>The checklist describes keys using a model keyboard mechanism. It assumes
that your application is being designed for a left-to-right language environment
in an English-language locale. Wherever keyboard input is specified, the
keys are indicated by the engravings on the Motif model keyboard. Mouse buttons
are described using a virtual button mechanism to better describe behavior
independent from the number of buttons on the mouse.</para>
<para>This book provides information to assist the application designer in
developing consistent applications and behaviors within the applications.
</para>
</sect2>
<sect2 id="RDMAP.pref.div.7">
<title>Common Desktop Environment: Application Builder User's Guide</title>
<para>The Common Desktop Environment Application Builder (also called App
Builder) is an interactive tool for developing Common Desktop Environment
applications. It provides features that facilitate both the construction
of an application graphical user interface (GUI) and the incorporation of
the desktop's many useful desktop services (such as Help, ToolTalk, Drag
and Drop). The <emphasis>Common Desktop Environment: Application Builder
User's Guide</emphasis> explains how to create an interface by dragging and
dropping &ldquo;objects&rdquo; from a palette. It also explains how to
make connections between objects in the interface, how to use the application
framework editor to easily integrate desktop services, how to generate C
code, and how to add application code to the App Builder output to produce
a finished application.</para>
</sect2>
<sect2 id="RDMAP.pref.div.8">
<title>Common Desktop Environment: Programmer's Guide</title>
<para>The <emphasis>Common Desktop Environment: Programmer's Guide</emphasis>
has two parts. Each part provides a detailed description of elements of the
Common Desktop Environment, a conceptual diagram, and a task-oriented description
of how to use each element, complete with code examples.</para>
<para>Part I, &ldquo;Recommended Integration,&rdquo; provides an overview
of basic integration, and describes how to integrate new applications with
the Session Manager, fonts, and drag and drop. It also discusses displaying
error messages.</para>
<para>Part II, &ldquo;Optional Integration,&rdquo; describes how to integrate
new applications with the Workspace Manager, Common Desktop Environment Motif
widgets, actions, data types, and Calendar.</para>
<para>The <emphasis>Programmer's Guide</emphasis> provides an introduction
to the application program interfaces (APIs) for the components referred
to in the descriptions of Parts I and II above, with cross-references to
the relevant man pages. Details are covered in the man pages.</para>
</sect2>
<sect2 id="RDMAP.pref.div.9">
<title>Common Desktop Environment: Help System Author's and Programmer's
Guide</title>
<para>The <emphasis>Common Desktop Environment: Help System Author's and Programmer's
Guide</emphasis> describes how to develop online help for application software.
It covers how to create help topics and how to integrate online help into
a Motif application.</para>
<para>The audience for this book includes:</para>
<itemizedlist remap="Bullet1"><listitem><para>Authors who design, create,
and view online help information</para>
</listitem><listitem><para>Developers who want to create software applications
that provide a fully integrated help facility</para>
</listitem></itemizedlist>
<para>This book has four parts. Part I describes the collaborative role that
authors and developers undertake to design application help. Part II provides
information for authors organizing and writing online help. Part III describes
the Help System application programmer's toolkit. Part IV contains information
for both authors and programmers about preparing online help for different
language environments.</para>
</sect2>
<sect2 id="RDMAP.pref.div.10">
<title>Common Desktop Environment: ToolTalk Messaging Overview</title>
<para>The <emphasis>Common Desktop Environment: ToolTalk Messaging Overview</emphasis> describes the ToolTalk components, commands, and error messages
offered as convenience routines to enable your application to conform to
Media Exchange and Desktop Services message set conventions. This manual
is for developers who create or maintain applications that use the ToolTalk
service to interoperate with other applications.</para>
<para>The <emphasis>ToolTalk Messaging Overview</emphasis> does <symbol role="Variable">not</symbol> describe general ToolTalk functionality. For detailed information
about the ToolTalk service, refer to <emphasis>The ToolTalk Service: An Inter-Operability
Solution</emphasis>. For tips and techniques to help make using ToolTalk
easier, read <emphasis>ToolTalk and Open Protocols: Inter-Application Communication</emphasis>. Both of these books are listed in <!--Original XRef content:
'&xd2;Related Books&xd3; on page&numsp;xv'--><xref role="SecTitleAndPageNum"
linkend="RDMAP.pref.mkr.2">.</para>
</sect2>
<sect2 id="RDMAP.pref.div.11">
<title>Common Desktop Environment: Internationalization Programmer's Guide</title>
<para>The <emphasis>Common Desktop Environment: Internationalization Programmer's
Guide</emphasis> provides information for internationalizing an application
so that it can be easily localized to support various languages and cultural
conventions in a consistent user interface.</para>
<para>Specifically, this guide:</para>
<itemizedlist remap="Bullet1"><listitem><para>Provides guidelines and hints
for developers on how to write applications for worldwide distribution</para>
</listitem><listitem><para>Provides an overall view of internationalization
topics that span different layers within the desktop</para>
</listitem><listitem><para>Provides pointers to reference and more detailed
documentation. In some cases, standard documentation is referenced.</para>
</listitem></itemizedlist>
<para>This guide is not intended to duplicate the existing reference or conceptual
documentation, but rather to provide guidelines and conventions on specific
internationalization topics. It focuses on internationalization topics and
not on any specific component or layer in an open software environment.</para>
</sect2>
<sect2 id="RDMAP.pref.div.12">
<title>Common Desktop Environment: Desktop KornShell User's Guide</title>
<para>The <emphasis>Common Desktop Environment: Desktop KornShell User's Guide</emphasis> describes how to create Motif applications with Desktop KornShell
(<command>dtksh</command>) scripts. It contains several example scripts of
increasing complexity, in addition to the basic information a developer needs
to get started.</para>
<para>This guide is intended for developers who find a shell-style scripting
environment suitable for a particular task. It assumes a knowledge of KornShell
programming, Motif, the Xt Intrinsics, and, to a lesser extent, Xlib.</para>
</sect2>
<sect2 id="RDMAP.pref.div.12a">
<title>Common Desktop Environment: Information System Author's
and Programmer's Guide</title>
<para>The <citetitle>Common Desktop Environment: Information System
Author's and Programmer's Guide</citetitle> describes how to
develop and integrate on-line documentation. This manual is addressed
to two audiences: the documentation author, who
develops the documentation content; and the programmer,
who integrates the documentation with the CDE documentation
browser, <command>dtinfo</command>.
</para>
</sect2>
<sect2 id="RDMAP.pref.div.13">
<title>Common Desktop Environment: Glossary</title>
<para>The <emphasis>Common Desktop Environment: Glossary</emphasis> provides
a comprehensive list of terms used in the Common Desktop Environment. The
Glossary is the source and reference base for all users of the desktop. Because
the audience for this glossary consists of many different types of users&mdash;from
end users to developers to translators&mdash;the format for a glossary definition
may include information about the audience, where the term originated, and
the Common Desktop Environment component that uses the term in its graphical
user interface.</para>
</sect2>
</sect1>
<sect1 id="RDMAP.pref.div.14">
<title>What DocBook SGML Markup Means</title>
<para>This book is written in the Structured Generalized Markup
Language (SGML) using the DocBook Document Type Definition (DTD).
The following table describes the DocBook markup used for
various semantic elements.
</para>
<table id="RDMAP.pref.tbl.1" frame="Topbot">
<title>DocBook SGML Markup</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colwidth="1.65in">
<colspec colwidth="2.63in">
<colspec colwidth="2.92in">
<thead>
<row>
<entry align="left" valign="bottom"><para><literal>Markup Appearance</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Semantic Element(s)</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Example</literal></para></entry></row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><para><command>AaBbCc123</command></para></entry>
<entry align="left" valign="top"><para>The names of commands.</para></entry>
<entry align="left" valign="top"><para>Use the <command>ls</command> command to list files.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><literal>AaBbCc123</literal></para></entry>
<entry align="left" valign="top"><para>The names of command options.</para></entry>
<entry align="left" valign="top"><para>Use <command>ls</command> <literal>&minus;a</literal>
to list all files.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">AaBbCc123</symbol></para></entry>
<entry align="left" valign="top"><para>Command-line placeholder:
replace with a real name or value.</para></entry>
<entry align="left" valign="top"><para>To delete a file, type <command>rm</command> <symbol role="Variable">filename</symbol>.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>AaBbCc123</filename></para></entry>
<entry align="left" valign="top"><para>The names of files and
directories.</para></entry>
<entry align="left" valign="top"><para>Edit your <filename>.login</filename>
file.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><emphasis>AaBbCc123</emphasis></para></entry>
<entry align="left" valign="top"><para>Book titles, new words or terms, or
words to be emphasized.</para></entry>
<entry align="left" valign="top"><para>Read Chapter 6 in <emphasis>User's
Guide</emphasis>.
These are called <emphasis>class</emphasis> options.
You <emphasis>must</emphasis> be root to do this.</para></entry>
</row></tbody></tgroup></table>
</sect1>
</preface>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 04:30:53-->
<?Pub *0000023399>