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

doc: move C to en_US.UTF-8.

Browse Source
This commit is contained in:
Liang Chang
2022-01-20 02:27:30 +08:00
parent a1a43180ac
commit 53e4feeb32
2137 changed files with 43 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
cde/doc/en_US.UTF-8/guides/progGuide/BEntity.sgm Normal file
View File

@@ -0,0 +1,58 @@
<!-- $XConsortium: BEntity.sgm /main/7 1996/10/18 15:14:38 cdedoc $ -->
<!ENTITY PG.dndPG.fig.1 SYSTEM "./progGuide/graphics/valmovts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.2 SYSTEM "./progGuide/graphics/valmovss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.3 SYSTEM "./progGuide/graphics/valmovms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.4 SYSTEM "./progGuide/graphics/valcopts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.5 SYSTEM "./progGuide/graphics/valcopss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.6 SYSTEM "./progGuide/graphics/valcopms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.7 SYSTEM "./progGuide/graphics/vallnkts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.8 SYSTEM "./progGuide/graphics/vallnkss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.9 SYSTEM "./progGuide/graphics/vallnkms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.10 SYSTEM "./progGuide/graphics/invmovts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.11 SYSTEM "./progGuide/graphics/invmovss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.12 SYSTEM "./progGuide/graphics/invmovms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.13 SYSTEM "./progGuide/graphics/invcopts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.14 SYSTEM "./progGuide/graphics/invcopss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.15 SYSTEM "./progGuide/graphics/invcopms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.16 SYSTEM "./progGuide/graphics/invlnkts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.17 SYSTEM "./progGuide/graphics/invlnkss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.18 SYSTEM "./progGuide/graphics/invlnkms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.19 SYSTEM "./progGuide/graphics/basdrdr.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.20 SYSTEM "./progGuide/graphics/optdrdr.cgm" NDATA CGM-BINARY>
<!ENTITY PG.widgs.fig.1 SYSTEM "./progGuide/graphics/spnbxwid.cgm" NDATA CGM-BINARY>
<!ENTITY PG.widgs.fig.2 SYSTEM "./progGuide/graphics/txtflwid.cgm" NDATA CGM-BINARY>
<!ENTITY PG.widgs.fig.3 SYSTEM "./progGuide/graphics/mnbutwid.cgm" NDATA CGM-BINARY>
<!ENTITY PG.widgs.fig.4 SYSTEM "./progGuide/graphics/lstbxwid.cgm" NDATA CGM-BINARY>
<!ENTITY PG.calmg.fig.1 SYSTEM "./progGuide/graphics/poscal.cgm" NDATA CGM-BINARY>
<!ENTITY PG.calmg.fig.2 SYSTEM "./progGuide/graphics/compcal.cgm" NDATA CGM-BINARY>
<!ENTITY PG.basc1.fig.1 SYSTEM "./progGuide/graphics/noprint.cgm" NDATA CGM-BINARY>

3
cde/doc/en_US.UTF-8/guides/progGuide/Title.am Normal file
View File

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

3
cde/doc/en_US.UTF-8/guides/progGuide/Title.tmpl Normal file
View File

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

126
cde/doc/en_US.UTF-8/guides/progGuide/adbook.sgm Normal file
View File

@@ -0,0 +1,126 @@
<!-- $XConsortium: adbook.sgm /main/11 1996/10/18 15:14:47 cdedoc $ -->
<!DOCTYPE DocBook PUBLIC "-//HaL and O'Reilly//DTD DocBook V2.2.1//EN" [
<!ENTITY PG.dndPG.fig.1 SYSTEM "./graphics/valmovts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.2 SYSTEM "./graphics/valmovss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.3 SYSTEM "./graphics/valmovms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.4 SYSTEM "./graphics/valcopts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.5 SYSTEM "./graphics/valcopss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.6 SYSTEM "./graphics/valcopms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.7 SYSTEM "./graphics/vallnkts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.8 SYSTEM "./graphics/vallnkss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.9 SYSTEM "./graphics/vallnkms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.10 SYSTEM "./graphics/invmovts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.11 SYSTEM "./graphics/invmovss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.12 SYSTEM "./graphics/invmovms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.13 SYSTEM "./graphics/invcopts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.14 SYSTEM "./graphics/invcopss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.15 SYSTEM "./graphics/invcopms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.16 SYSTEM "./graphics/invlnkts.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.17 SYSTEM "./graphics/invlnkss.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.18 SYSTEM "./graphics/invlnkms.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.19 SYSTEM "./graphics/basdrdr.cgm" NDATA CGM-BINARY>
<!ENTITY PG.dndPG.fig.20 SYSTEM "./graphics/optdrdr.cgm" NDATA CGM-BINARY>
<!ENTITY PG.widgs.fig.1 SYSTEM "./graphics/spnbxwid.cgm" NDATA CGM-BINARY>
<!ENTITY PG.widgs.fig.2 SYSTEM "./graphics/txtflwid.cgm" NDATA CGM-BINARY>
<!ENTITY PG.widgs.fig.3 SYSTEM "./graphics/mnbutwid.cgm" NDATA CGM-BINARY>
<!ENTITY PG.widgs.fig.4 SYSTEM "./graphics/lstbxwid.cgm" NDATA CGM-BINARY>
<!ENTITY PG.calmg.fig.1 SYSTEM "./graphics/poscal.cgm" NDATA CGM-BINARY>
<!ENTITY PG.calmg.fig.2 SYSTEM "./graphics/compcal.cgm" NDATA CGM-BINARY>
<!ENTITY PG.basc1.fig.1 SYSTEM "./graphics/noprint.cgm" NDATA CGM-BINARY>
<!ENTITY % local.notations "| XPM | XBM | XWD">
<!NOTATION XPM SYSTEM "XPM">
<!NOTATION XBM SYSTEM "XBM">
<!NOTATION XWD SYSTEM "XWD">
<!ENTITY Pref SYSTEM "./preface.sgm">
<!ENTITY prtI SYSTEM "./part1.sgm">
<!ENTITY basc1 SYSTEM "./ch01.sgm">
<!ENTITY prt2 SYSTEM "./part2.sgm">
<!ENTITY fonts SYSTEM "./ch02.sgm">
<!ENTITY msgs SYSTEM "./ch03.sgm">
<!ENTITY smgr SYSTEM "./ch04.sgm">
<!ENTITY dndPG SYSTEM "./ch05.sgm">
<!ENTITY prt3 SYSTEM "./part3.sgm">
<!ENTITY wsmgr SYSTEM "./ch06.sgm">
<!ENTITY widgs SYSTEM "./ch07.sgm">
<!ENTITY aIII SYSTEM "./ch08.sgm">
<!ENTITY datat SYSTEM "./ch09.sgm">
<!ENTITY calmg SYSTEM "./ch10.sgm">
<!ENTITY info SYSTEM "./ch11.sgm">
<!ENTITY print SYSTEM "./ch12.sgm">
<!ENTITY gloss SYSTEM "./glossary.sgm">
]>
<!-- ____________________________________________________________________________ -->
<DocBook>
<Book>
<Title>Common Desktop Environment: Programmer's Guide</Title>
&Pref;
<Part Id="PG.prtI.div.1">
&prtI;
&basc1;
</Part>
<Part Id="PG.prt2.div.1">
&prt2;
&fonts;
&msgs;
&smgr;
&dndPG;
</Part>
<Part Id="PG.prt3.div.1">
&prt3;
&wsmgr;
&widgs;
&aIII;
&datat;
&calmg;
&info;
&print;
</Part>
&gloss;
</Book>
</DocBook>

101
cde/doc/en_US.UTF-8/guides/progGuide/book.sgm Normal file
View File

@@ -0,0 +1,101 @@
<!-- $XConsortium: book.sgm /main/7 1996/08/20 14:10:22 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 % ISOaddedMath PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN">
%ISOaddedMath;
<!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 "./progGuide/BEntity.sgm">
%BEntities;
<!ENTITY % local.notations "| XPM | XBM | XWD">
<!NOTATION XPM SYSTEM "XPM">
<!NOTATION XBM SYSTEM "XBM">
<!NOTATION XWD SYSTEM "XWD">
<!ENTITY Pref SYSTEM "./progGuide/preface.sgm">
<!ENTITY prtI SYSTEM "./progGuide/part1.sgm">
<!ENTITY basc1 SYSTEM "./progGuide/ch01.sgm">
<!ENTITY prt2 SYSTEM "./progGuide/part2.sgm">
<!ENTITY fonts SYSTEM "./progGuide/ch02.sgm">
<!ENTITY msgs SYSTEM "./progGuide/ch03.sgm">
<!ENTITY smgr SYSTEM "./progGuide/ch04.sgm">
<!ENTITY dndPG SYSTEM "./progGuide/ch05.sgm">
<!ENTITY prt3 SYSTEM "./progGuide/part3.sgm">
<!ENTITY wsmgr SYSTEM "./progGuide/ch06.sgm">
<!ENTITY widgs SYSTEM "./progGuide/ch07.sgm">
<!ENTITY aIII SYSTEM "./progGuide/ch08.sgm">
<!ENTITY datat SYSTEM "./progGuide/ch09.sgm">
<!ENTITY calmg SYSTEM "./progGuide/ch10.sgm">
<!ENTITY info SYSTEM "./progGuide/ch11.sgm">
<!ENTITY print SYSTEM "./progGuide/ch12.sgm">
<!ENTITY gloss SYSTEM "./progGuide/glossary.sgm">
]>
<!-- ____________________________________________________________________________ -->
<Book>
<Title>Common Desktop Environment: Programmer's Guide</Title>
&Pref;
<Part Id="PG.prtI.div.1">
&prtI;
&basc1;
</Part>
<Part Id="PG.prt2.div.1">
&prt2;
&fonts;
&msgs;
&smgr;
&dndPG;
</Part>
<Part Id="PG.prt3.div.1">
&prt3;
&wsmgr;
&widgs;
&aIII;
&datat;
&calmg;
&info;
&print;
</Part>
&gloss;
</Book>

554
cde/doc/en_US.UTF-8/guides/progGuide/ch01.sgm Normal file
View File

@@ -0,0 +1,554 @@
<!-- Fragment document type declaration subset:
ArborText, Inc., 1988-1995, v.4001
<!DOCTYPE DOCBOOK [
<!ENTITY PG.BIntg.fig.1 SYSTEM "./progGuide/graphics/NoPrint.eps" NDATA eps>
<!ENTITY PG.BIntg.fig.2 SYSTEM "./progGuide/graphics/package.eps" NDATA eps>
<!ENTITY PG.BIntg.fig.3 SYSTEM "./progGuide/graphics/approot.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.1 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.1.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.2 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.2.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.3 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.3.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.4 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.4.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.5 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.5.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.6 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.6.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.7 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.7.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.8 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.8.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.9 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.9.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.10 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.10.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.11 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.11.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.12 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.12.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.13 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.13.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.14 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.14.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.15 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.15.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.16 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.16.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.17 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.17.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.18 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.18.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.19 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.19.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.20 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.20.eps" NDATA eps>
<!ENTITY PG.widgs.fig.1 SYSTEM "./progGuide/graphics/PG.widgs.iFrame.1.eps" NDATA eps>
<!ENTITY PG.widgs.fig.2 SYSTEM "./progGuide/graphics/ComboBox.rs" NDATA eps>
<!ENTITY PG.widgs.fig.3 SYSTEM "./progGuide/graphics/MenuButton2.rs" NDATA eps>
<!ENTITY PG.calmg.fig.1 SYSTEM "./progGuide/graphics/PG.calmg.iFrame.1.eps" NDATA eps>
<!ENTITY PG.calmg.fig.2 SYSTEM "./progGuide/graphics/PG.calmg.iFrame.2.eps" NDATA eps>
<!ENTITY PG.basc1.fig.1 SYSTEM "./progGuide/graphics/NoPrint.eps" NDATA eps>
<!ENTITY PG.basic.fig.1 SYSTEM "./progGuide/graphics/NoPrint.eps" NDATA eps>
<!ENTITY PG.basic.fig.2 SYSTEM "./progGuide/graphics/package.eps" NDATA eps>
<!ENTITY PG.basic.fig.3 SYSTEM "./progGuide/graphics/approot.eps" NDATA eps>
<!ENTITY Copyr SYSTEM "./progGuide/copyright.sgm">
<!ENTITY Pref SYSTEM "./progGuide/preface.sgm">
<!ENTITY prtI SYSTEM "./progGuide/part1.sgm">
<!ENTITY prt2 SYSTEM "./progGuide/part2.sgm">
<!ENTITY fonts SYSTEM "./progGuide/ch02.sgm">
<!ENTITY msgs SYSTEM "./progGuide/ch03.sgm">
<!ENTITY smgr SYSTEM "./progGuide/ch04.sgm">
<!ENTITY dndPG SYSTEM "./progGuide/ch05.sgm">
<!ENTITY prt3 SYSTEM "./progGuide/part3.sgm">
<!ENTITY wsmgr SYSTEM "./progGuide/ch06.sgm">
<!ENTITY widgs SYSTEM "./progGuide/ch07.sgm">
<!ENTITY aIII SYSTEM "./progGuide/ch08.sgm">
<!ENTITY datat SYSTEM "./progGuide/ch09.sgm">
<!ENTITY calmg SYSTEM "./progGuide/ch10.sgm">
<!ENTITY gloss SYSTEM "./progGuide/glossary.sgm">
]>
-->
<!-- $XConsortium: ch01.sgm /main/8 1996/09/08 19:36:07 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="PG.basc1.div.1">
<title id="PG.basc1.mkr.1">Basic Application Integration</title>
<para>Basic application integration is a set of highly recommended tasks
you should perform.<indexterm><primary>basic integration</primary><secondary>definition</secondary></indexterm></para>
<informaltable id="PG.basc1.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 Features3'--><xref
role="JumpText" linkend="PG.basc1.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Basic Integration Tasks5'--><xref
role="JumpText" linkend="PG.basc1.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Complete Print Integration6'--><xref
role="JumpText" linkend="PG.basc1.mkr.6"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Partial Print Integration10'--><xref
role="JumpText" linkend="PG.basc1.mkr.8"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Nonintegrated Printing13'--><xref
role="JumpText" linkend="PG.basc1.mkr.9"></para></entry></row></tbody></tgroup>
</informaltable>
<para>Basic integration does not involve extensive use of the desktop application
programmer's interface (API). Therefore, it does not provide other interaction
with the desktop, such as drag and drop, session management, ToolTalk&reg;
messaging, and programmatic access to the actions and data typing database.
</para>
<para>A few of the integration tasks covered in this chapter require source
code modification. They are optional, and are discussed here because they
are closely related to basic integration tasks.</para>
<sect1 id="PG.basc1.div.2">
<title id="PG.basc1.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<indexterm><primary>registration
package</primary></indexterm> <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.<indexterm><primary>registration</primary><secondary>definition</secondary></indexterm></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 to help users
identify them. The data files also have meaningful desktop behavior. For
example, the user can start your application by double-clicking a data file;
dropping a data file on a desktop printer drop zone prints the file using
the appropriate print command.<indexterm><primary>data type</primary><secondary>purpose of</secondary></indexterm></para>
</listitem><listitem><para>Easy font and color selection using Style Manager<indexterm>
<primary>Style Manager</primary><secondary>integrating with</secondary></indexterm></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.<indexterm>
<primary>fonts</primary><secondary>getting from Style Manager</secondary>
</indexterm><indexterm><primary>colors</primary><secondary>getting from Style
Manager</secondary></indexterm></para>
</listitem></itemizedlist>
<para>Basic integration provides these advantages to system administrators:<indexterm>
<primary>basic integration</primary><secondary>advantages</secondary></indexterm></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 administrator wants to update it or to move it to a different application
server.</para>
</listitem></itemizedlist>
<sect2 id="PG.basc1.div.3">
<title>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
chapter &ldquo;Registering an Application&rdquo; in the <emphasis>Common
Desktop Environment: Advanced User's and System Administrator's Guide</emphasis>.
</para>
<para>This chapter guides you to that information and contains additional
information specific to application programmers.</para>
</sect2>
</sect1>
<sect1 id="PG.basc1.div.4">
<title id="PG.basc1.mkr.3">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.<indexterm><primary>basic integration</primary><secondary>summary of tasks</secondary></indexterm></para>
<para>See the section on modifying font and color resources in the chapter
&ldquo;Registering an Application&rdquo; in the <emphasis>Common Desktop
Environment: Advanced User's and System Administrator's Guide</emphasis>.
</para>
</listitem><listitem><para>Create the registration package for your application.
</para>
<para>See the text, <!--Original XRef content: '&xd2;Creating a Registration
Package for Your Application'--><xref role="SectionTitle" linkend="PG.basc1.mkr.11">
and &ldquo;Registering an Application&rdquo; in the <emphasis>Common Desktop
Environment: Advanced User's and System Administrator's Guide .</emphasis></para>
</listitem><listitem><para>Modify your application's installation script to
install the registration package files and perform the registration procedure.
</para>
<para id="pg.basc1.mkr.4">See the section on registering the application using <command>dtappintegrate</command> in the chapter &ldquo;Registering an Application&rdquo;
in the <emphasis>Common Desktop Environment: Advanced User's and System Administrator's
Guide</emphasis>.<indexterm><primary>data types</primary><secondary>printing</secondary></indexterm><indexterm><primary>registration package</primary>
<secondary>providing printing</secondary></indexterm><indexterm><primary>printing integration</primary></indexterm></para>
</listitem><listitem><para>Print application data files on networked and local
printers. The desktop printer model provides a graphical way for users to
print and is built on top of the native networking capabilities of the UNIX <command>lp</command> service.</para>
</listitem></itemizedlist>
<sect2 id="PG.basc1.div.5">
<title id="PG.basc1.mkr.5">Levels of Printing Integration<indexterm><primary>printing integration</primary></indexterm><indexterm><primary>basic integration</primary><secondary>printing</secondary></indexterm></title>
<para>The printing functionality available to the user depends on the level
of integration you use. There are three levels of integration:<indexterm>
<primary>print integration</primary><secondary>levels</secondary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para>Complete integration. See <!--Original
XRef content: '&xd2;Complete Print Integration&xd3; on page&numsp;6'--><xref
role="SecTitleAndPageNum" linkend="PG.basc1.mkr.6">.</para>
<para>You should do complete integration if you have the ability to modify
the application's source code.</para>
<para>When you do complete print integration, users can print data files on
various printers by dropping them on printer drop zones (the Front Panel
Printer control and printer icons in Print Manager). Certain other desktop
behaviors are also implemented (see <!--Original XRef content: '&xd2;Desktop
Printing Environment
Variables&xd3; on page&numsp;6'--><xref role="SecTitleAndPageNum" linkend="PG.basc1.mkr.7">).
</para>
</listitem><listitem><para>Partial integration. See <!--Original XRef content:
'&xd2;Partial Print Integration&xd3; on page&numsp;10'--><xref role="SecTitleAndPageNum"
linkend="PG.basc1.mkr.8">.</para>
<para>You should do partial integration if you do not have the ability to
modify the application's source code, but you do have the ability to invoke
printing via an action.</para>
<para>When you do partial integration, your application provides a subset
of full- integration functionality. For example, by using the <command>LPDEST</command> environment variable, your application's printing mechanism will
obtain the print destination from the drop zone.</para>
</listitem><listitem><para>No integration. See <!--Original XRef content:
'&xd2;Nonintegrated Printing&xd3; on page&numsp;13'--><xref role="SecTitleAndPageNum"
linkend="PG.basc1.mkr.9">.</para>
<para>If an application can not supply a print action for its data files,
you should configure the data files to display an error dialog box when users
drop the files on printer drop zones.</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="PG.basc1.div.6">
<title id="PG.basc1.mkr.6">Complete Print Integration<indexterm><primary>print integration</primary><secondary>complete</secondary></indexterm></title>
<para>To do complete print integration, your application must:</para>
<itemizedlist remap="Bullet1"><listitem><para>Provide a Print action</para>
</listitem><listitem><para>Use (dereference) the four desktop printing environment
variables</para>
</listitem></itemizedlist>
<sect3 id="PG.basc1.div.7">
<title id="PG.basc1.mkr.7">Desktop Printing Environment Variables<indexterm>
<primary>print integration</primary><secondary>environment variables</secondary>
</indexterm><indexterm><primary>environment variables,printing</primary>
</indexterm></title>
<para>To have fully integrated printing, your application must dereference
the following four environment variables. The <command>LPDEST</command> variable
is particularly important. It provides the ability for the user to choose
the print destination by using a particular printer drop zone.</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.58in">
<colspec align="left" colwidth="188*">
<colspec align="left" colwidth="355*">
<thead>
<row><entry align="left" valign="bottom"><para>Printing Variable</para></entry>
<entry align="left" valign="bottom"><para>Description</para></entry></row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><para><command>LPDEST</command><indexterm>
<primary>LPDEST variable</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>Uses the specified value as the printer
destination for the file. If the variable is not set, the default printing
device for your application should be used.<indexterm><primary>print integration</primary><secondary>specifying destination printer</secondary></indexterm></para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>DTPRINTUSERFILENAME</command><indexterm>
<primary>DTPRINTUSERFILENAME variable</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>Specifies the name of the file as it
should appear in the Print dialog or print output. If the variable is not
set, the actual file name should be used.<indexterm><primary>print integration</primary><secondary>specifying file name</secondary></indexterm></para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>DTPRINTSILENT</command><indexterm>
<primary>DTPRINTSILENT variable</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>Specifies whether to display a Print
dialog box. When the variable is set to True, the Print dialog should not
be displayed. If the variable is not set, the dialog box should be displayed.<indexterm>
<primary>print integration</primary><secondary>printing without Print dialog
box</secondary></indexterm><indexterm><primary>Print dialog box</primary>
</indexterm></para></entry></row>
<row>
<entry align="left" valign="top"><para><command>DTPRINTFILEREMOVE</command><indexterm>
<primary>DTPRINTFILEREMOVE variable</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>When the variable is set to True, the
file should be removed after it is printed. This functionality is intended
for temporary files that don't need to be retained after printing is complete.
If the variable is not set, the file should not be removed.<indexterm><primary>print integration</primary><secondary>removing temporary files</secondary>
</indexterm></para></entry></row></tbody></tgroup></informaltable>
</sect3>
<sect3 id="pg.basc1.div.8">
<title>A Fully Integrated Print Action<indexterm><primary>print actions</primary></indexterm></title>
<para>The Print action is part of the registration package, provided in a
configuration file, <symbol role="Variable">app_root</symbol><filename>/dt/appconfig/types/language/</filename><symbol role="Variable">name</symbol><filename>.dt</filename>.
</para>
<para>If your print action executes a program that dereferences the four environment
variables indicated in <!--Original XRef content: '&xd2;Desktop Printing
Environment Variables'--><xref role="SectionTitle" linkend="pg.basc1.mkr.7">,
then your data type is fully integrated. The Print action must be written
to be specific for the application's data type and should accept only a single
file.</para>
<para>For example, the following print action is specific for a data type
named <command>ThisAppData</command>:</para>
<programlisting>Print
{
ARG_TYPE ThisAppData
EXEC_STRING <symbol role="Variable">print_command</symbol> -file %(file)Arg_1%
}</programlisting>
<para>If your application handles the Print ToolTalk request, then your print
action could send a variant of it with the following actions. (If any of
the four environment variables are not set, the corresponding message argument
will be null. When the message argument is null, refer to &ldquo;Desktop
Printing Environment Variables&ldquo; for the default interpretation.)</para>
<programlisting>ACTION Print
{
ARG_TYPE ThisAppData
ARG_CLASS FILE
ARG_COUNT 1
TYPE TT_MSG
TT_CLASS TT_REQUEST
TT_SCOPE TT_SESSION
TT_OPERATION Print
TT_FILE %Arg_1%
TT_ARG0_MODE TT_IN
TT_ARG0_VTYPE %Arg_1%
TT_ARG1_MODE TT_IN
TT_ARG1_VTYPE LPDEST
TT_ARG1_VALUE $LPDEST
TT_ARG2_MODE TT_IN
TT_ARG2_VTYPE DTPRINTUSERFILENAME
TT_ARG2_VALUE $DTPRINTUSERFILENAME
TT_ARG3_MODE TT_IN
TT_ARG3_VTYPE DTPRINTSILENT
TT_ARG3_VALUE $DTPRINTSILENT
TT_ARG4_MODE TT_IN
TT_ARG4_VTYPE DTPRINTFILEREMOVE
TT_ARG4_VALUE $DTPRINTFILEREMOVE
}
ACTION Print
{
ARG_TYPE ThisAppData
ARG_CLASS BUFFER
ARG_COUNT 1
TYPE TT_MSG
TT_CLASS TT_REQUEST
TT_SCOPE TT_SESSION
TT_OPERATION Print
TT_ARG0_MODE TT_IN
TT_ARG0_VTYPE %Arg_1%
TT_ARG0_VALUE %Arg_1%
TT_ARG1_MODE TT_IN
TT_ARG1_VTYPE LPDEST
TT_ARG1_VALUE $LPDEST
TT_ARG2_MODE TT_IN
TT_ARG2_VTYPE DTPRINTUSERFILENAME
TT_ARG2_VALUE $DTPRINTUSERFILENAME
TT_ARG3_MODE TT_IN
TT_ARG3_VTYPE DTPRINTSILENT
TT_ARG3_VALUE $DTPRINTSILENT
TT_ARG4_MODE TT_IN
TT_ARG4_VTYPE DTPRINTFILEREMOVE
TT_ARG4_VALUE false
}</programlisting>
</sect3>
<sect3 id="PG.basc1.div.9">
<title>Creating Print Actions for Filtered Data or Data Ready to Print<indexterm>
<primary>print filters</primary></indexterm><indexterm><primary>filters,print</primary></indexterm><indexterm><primary>print actions</primary></indexterm></title>
<para>The desktop print utility <filename>/usr/dt/dtlp</filename> provides
functionality on top of the <command>lp</command> subsystem. It gathers <command>lp</command> print options and prints the specified file.</para>
<para>Your application can use <command>dtlp</command> if either of the following
conditions are true:</para>
<itemizedlist remap="Bullet1"><listitem><para>The data files do not need to
be processed before they are sent to a printer.</para>
</listitem><listitem><para><emphasis>Or</emphasis>, your application provides
a filter for converting its data files to a ready-to-print form.</para>
</listitem></itemizedlist>
<para>If your application's data files do not meet either of these conditions, you must
provide an entry point into the application's printing system. Your application
can then use the X Print Service to print the data file. For example,
</para>
<programlisting>
Print
{
ARG_TYPE ThisAppData
EXEC_STRING app_name -print %Arg_1%
}
</programlisting>
<para>Note that the <command>dtlp</command> services are intended for printing
through the action system (as opposed to printing through the application).
For detailed information about <command>dtlp</command>, see the <filename moreinfo="RefEntry">dtlp</filename>(1) reference page.</para>
<para>If the file is ready to print, the Print action runs <command>dtlp</command>
in the <command>EXEC_STRING.</command> For example:</para>
<programlisting>Print
{
ARG_TYPE ThisAppData
EXEC_STRING dtlp %Arg_1%
}</programlisting>
<para>If the application provides a conversion filter, the filter must be
run before running <filename>dtlp.</filename> For example:</para>
<programlisting>Print
{
ARG_TYPE MyAppData
EXEC_STRING /bin/sh `cat %Arg_1%| <symbol role="Variable">filter_name</symbol> | dtlp`
}</programlisting>
<para>where <symbol role="Variable">filter_name</symbol> is the name of the
print filter.</para>
</sect3>
</sect2>
<sect2 id="PG.basc1.div.10">
<title id="PG.basc1.mkr.8">Partial Print Integration<indexterm><primary>print integration</primary><secondary>partial</secondary></indexterm></title>
<para>To do partial print integration, your application must provide:</para>
<itemizedlist remap="Bullet1"><listitem><para>A Print action</para>
</listitem><listitem><para>The extent to which printing is integrated depends
on which, if any, of the printing environment variables are handled by the
action.</para>
</listitem></itemizedlist>
<para>If your application's data files are not in a ready-to-print state, you must provide
an entry point into the printing system. Then the application can use the X Print Service
to print the data files.
</para>
<sect3 id="pg.basc1.div.11">
<title>Providing the Print Command for Partial Integration<indexterm><primary>print command line</primary><secondary>partial integration</secondary></indexterm></title>
<para>To provide partial print integration, your application must provide
a print command line of the form:</para>
<programlisting><symbol role="Variable">print_command</symbol> [<symbol role="Variable">options</symbol>] -file <symbol role="Variable">filename</symbol></programlisting>
<para>where <symbol role="Variable">options</symbol> provides a mechanism
for dereferencing none, some, or all of the printing environment variables
(see <!--Original XRef content: '&xd2;Desktop Printing
Environment Variables&xd--><!--3;
on page&numsp;6'--><xref role="SecTitleAndPageNum" linkend="pg.basc1.mkr.7">).
</para>
<para>The simplest form of this print command line omits
options.</para>
<programlisting><symbol role="Variable">print_command</symbol> -file <symbol role="Variable">filename</symbol></programlisting>
<para>This command line lets users print your application's data files using
the desktop printer drop zones. However, printing destination is not set
by the drop zone. In addition, other print behaviors set by the environment
variables are not implemented. For example, the desktop may not be able to
direct silent printing or remove temporary files.</para>
<para>If your print command line provides additional command-line options that correspond to the desktop printing
environment variables, you can provide additional integration.</para>
<para>For example, the following command line provides the ability to dereference
<command>LPDEST</command>:</para>
<programlisting><symbol role="Variable">print_command</symbol> [-d <symbol role="Variable">destination</symbol>] [-file <symbol role="Variable">filename</symbol>]</programlisting>
<para>where:</para>
<para><symbol role="Variable">destination</symbol> is the destination printer.
</para>
<para>The next print command line provides options for dereferencing all four
variables:</para>
<programlisting><symbol role="Variable">print_command</symbol> [-d <symbol role="Variable">destination</symbol>] [-u <symbol role="Variable">user_file_name</symbol>] [-s] [-e] -file <symbol role="Variable">filename</symbol></programlisting>
<para>where:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="100*">
<colspec align="left" colwidth="356*">
<tbody>
<row>
<entry><para><symbol role="Variable">user_file_name</symbol></para></entry>
<entry><para>The file name as seen by the user.</para></entry></row>
<row>
<entry><para><filename>-s</filename></para></entry>
<entry><para>Printing is silent (no Print dialog box is displayed).</para></entry>
</row>
<row>
<entry><para><filename>-e</filename></para></entry>
<entry><para>The file is removed after it is printed.</para></entry></row>
</tbody></tgroup></informaltable>
<para>The dereferencing occurs in the action definition. See the section,
<!--Original XRef content: '&xd2;Desktop
Printing Environment Variables&xd--><!--3; on page&numsp;6'--><xref role="SecTitleAndPageNum"
linkend="pg.basc1.mkr.7"> for more information.</para>
</sect3>
<sect3 id="pg.basc1.div.11a">
<title>Turning Environment Variables into Command Line Switches</title>
<para>If your action is not capable of dereferencing the four environment
variables, but it is capable of taking corresponding command line options,
this subsection explains how to turn the environment variable values into
command line options.</para>
<para>For example, this is a simple Print action that deferences <command>LPDEST</command>:</para>
<programlisting>Print
{
ARG_TYPE <symbol role="Variable">data_type</symbol>
EXEC_STRING <symbol role="Variable">print_command</symbol> -d $LPDEST -file %(file)Arg_1%
}</programlisting>
<para>However, this Print action may create unpredictable behavior if <command>LPDEST</command> is not set.</para>
<para>One way to create a Print action that provides proper behavior when
variables are not set is to create a shell script that is used by the Print
action.</para>
<para>For example, the following action and the script it uses properly handle
all four environment variables:</para>
<programlisting>Print
ARG_TYPE <symbol role="Variable">data_type</symbol>
EXEC_STRING <symbol role="Variable">app_root</symbol>/bin/envprint %(File)Arg_1%
}</programlisting>
<para>The contents of the <command>envprint</command> script follows:<indexterm>
<primary>print integration</primary><secondary>script for</secondary></indexterm></para>
<programlisting>#!/bin/sh
# envprint - sample print script
DEST=&rdquo;&rdquo;
USERFILENAME=&rdquo;&rdquo;
REMOVE=&rdquo;&rdquo;
SILENT=&rdquo;&rdquo;
if [ $LPDEST ]; then
DEST=&rdquo;-d $LPDEST&rdquo;
fi
if [ $DTPRINTUSERFILENAME ]; then
USERFILENAME=&rdquo;-u $DTPRINTUSERFILENAME&rdquo;
fi
DTPRINTFILEREMOVE=echo $DTPRINTFILEREMOVE | tr &ldquo;[:upper:]&rdquo;
&ldquo;[:lower:]&rdquo;`
if [ &ldquo;$DTPRINTFILEREMOVE&rdquo; = &ldquo;true&rdquo; ]; then
REMOVE=&rdquo;-e&rdquo;
fi
DTPRINTSILENT=`echo $DTPRINTSILENT | tr &ldquo;[:upper:]&rdquo; &ldquo;[:lower:]&rdquo;`
if [ &ldquo;$DTPRINTSILENT&rdquo; = &ldquo;true&rdquo; ]; then
SILENT=&rdquo;-s&rdquo;
fi
<symbol role="Variable">print_command</symbol> $DEST $USERFILENAME $REMOVE $SILENT -file $1
</programlisting>
</sect3>
</sect2>
<sect2 id="PG.basc1.div.12">
<title id="PG.basc1.mkr.9">Nonintegrated Printing<indexterm><primary>print
integration</primary><secondary>using NoPrint action</secondary></indexterm></title>
<para>If your application does not integrate printing with the desktop, users
must open your application to properly print data files.</para>
<para>Nevertheless, you should provide a Print action that runs when users
drop your application's data files on a printer drop zone. Otherwise, the
desktop may assume that the file contains text data, and the print output
will be garbled.</para>
<para>The desktop provides a print action for this purpose named NoPrint.
The NoPrint action displays a dialog box telling users that the data files
cannot be printed using the printer drop zones.</para>
<para>The<indexterm><primary>NoPrint action</primary></indexterm> NoPrint
action displays the<indexterm><primary>Unable to Print dialog box</primary>
</indexterm> Unable to Print dialog box shown in <!--Original XRef content:
'Figure&numsp;1&hyphen;1'--><xref role="CodeOrFigureOrTable" linkend="PG.basc1.mkr.10">.
</para>
<figure>
<title id="PG.basc1.mkr.10">Dialog box displayed by the built-in NoPrint action</title>
<graphic id="PG.basc1.grph.1" entityref="PG.basc1.fig.1"></graphic>
</figure>
<para>To use the Unable to Print dialog box, create a print action specific
to your data type that maps to the NoPrint action. For example, suppose the
data type for your application is:</para>
<programlisting>DATA_ATTRIBUTES MySpreadSheet_Data1
{
&mdash;
}</programlisting>
<para>The following Print action maps to the NoPrint for this data type:</para>
<programlisting>ACTION Print
{
ARG_TYPE MySpreadSheet_Data1
TYPE MAP
MAP_ACTION NoPrint
}</programlisting>
</sect2>
<sect2 id="PG.basc1.div.13">
<title id="PG.basc1.mkr.11">Creating a Registration Package for Your Application<indexterm>
<primary>registration package</primary><secondary>creating</secondary></indexterm><indexterm>
<primary>basic integration</primary><secondary>registration package</secondary>
</indexterm></title>
<para>The desktop registration package you create for an application should
become part of the application's installation package. The procedures for
creating a registration package are also performed by system administrators
integrating existing applications into the desktop. These procedures are
documented in the chapter &ldquo;Registering an Application&rdquo; in the <emphasis>Common Desktop Environment: Advanced User's and System Administrator's Guide</emphasis>.</para>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->
<?Pub Caret>
<?Pub *0000030451>

433
cde/doc/en_US.UTF-8/guides/progGuide/ch02.sgm Normal file
View File

@@ -0,0 +1,433 @@
<!-- $XConsortium: ch02.sgm /main/5 1996/09/08 19:36:17 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="PG.fonts.div.1">
<Title Id="PG.fonts.mkr.1">Integrating Fonts</Title>
<Para>Your application may be used by someone sitting at an X terminal, or by
someone at a remote workstation across a network. In these situations, the
fonts available to the user's X display from the X window server might be
different from your application's defaults, and some fonts may not be
available.</Para>
<Para>The standard interface font names defined by CDE are guaranteed to be
available on all CDE-compliant systems. These names do not specify actual
fonts. Instead, they are aliases that each system vendor maps to its 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 CDE-compliant system.</Para>
<Para>These standard interface font names are guaranteed to be available for all
locales, whereas the standard application font names are only guaranteed for
ISO Latin locales. See the man pages, <Command>DtStdInterfaceFontNames</Command> and <Command>DtStdAppFontNames</Command> for more information.</Para>
<InformalTable Id="PG.fonts.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Standard Interface Fonts18'--><XRef Role="JumpText" Linkend="PG.fonts.mkr.2"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Using Fonts in CDE Configuration Files20'--><XRef Role="JumpText" Linkend="PG.fonts.mkr.4"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Standard Application Fonts21'--><XRef Role="JumpText" Linkend="PG.fonts.mkr.5"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
<Sect1 Id="PG.fonts.div.2">
<Title Id="PG.fonts.mkr.2">Standard Interface Fonts</Title>
<Sect2 Id="PG.fonts.div.3">
<Title>Default Font Names<IndexTerm>
<Primary>font names</Primary>
<Secondary>standard interface</Secondary>
</IndexTerm><IndexTerm>
<Primary>standard interface font names</Primary>
</IndexTerm><IndexTerm>
<Primary>font names, default</Primary>
</IndexTerm><IndexTerm>
<Primary>default font names</Primary>
</IndexTerm></Title>
<Para>The set of standard interface font names is defined by the XLFD field name
values described in
<!--Original XRef content: 'Table&numsp;2&hyphen;2'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.fonts.mkr.6">.</Para>
<Table Id="PG.fonts.tbl.1" Frame="Topbot">
<Title Id="PG.fonts.mkr.3">Field Name Values for Standard Interface Font Names</Title>
<TGroup Cols="3">
<ColSpec Colname="1" Colwidth="1.125 in">
<ColSpec Colname="2" Colwidth="1.5 in">
<ColSpec Colname="3" Colwidth="2.25 in">
<THead>
<Row>
<Entry><Para><Literal>Field</Literal></Para></Entry>
<Entry><Para><Literal>Value</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>FOUNDRY</Command></Para></Entry>
<Entry><Para><Command>dt</Command></Para></Entry>
<Entry><Para>CDE name</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>FAMILY_NAME</Filename></Para></Entry>
<Entry><Para><Command>interface system</Command>
or <Command>interface user</Command></Para></Entry>
<Entry><Para>CDE standard interface font name</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>WEIGHT_NAME</Filename></Para></Entry>
<Entry><Para><Command>medium</Command> or <Command>bold</Command></Para></Entry>
<Entry><Para>Weight of the font</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>SLANT</Command></Para></Entry>
<Entry><Para><Command>r</Command></Para></Entry>
<Entry><Para>Roman</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>SET_WIDTH</Filename></Para></Entry>
<Entry><Para><Command>normal</Command></Para></Entry>
<Entry><Para>Normal set width</Para></Entry>
</Row>
<Row>
<Entry><Para>SPACING</Para></Entry>
<Entry><Para>p or m</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>ADD_STYLE</Filename></Para></Entry>
<Entry><Para>size hint</Para><Para><Command>sans</Command> or <Command>serif</Command></Para></Entry>
<Entry><Para>Proportional or Monospace values
from xxs to xxl</Para><Para>Sans for sans serif font or
serif for serif</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>PIXEL_SIZE</Filename></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>POINT_SIZE</Filename></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>RESOLUTION_X</Filename></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>RESOLUTION_Y</Filename></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>AVERAGE_WIDTH</Filename></Para></Entry>
<Entry><Para><Command>m</Command></Para><Para>p</Para></Entry>
<Entry><Para>Monospace for user font</Para><Para>Proportional for system font</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>NUMERIC FIELD</Command></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>CHAR_SET_REGI
STRY</Filename></Para></Entry>
<Entry><Para>Locale Dependent</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Command>ENCODING</Command></Para></Entry>
<Entry><Para>Locale Dependent</Para></Entry>
<Entry></Entry>
</Row>
</TBody>
</TGroup>
</Table>
</Sect2>
<Sect2 Id="PG.fonts.div.4">
<Title>Point Sizes for Standard Interface Fonts</Title>
<Para>The seven named point sizes for each of the three styles are prepend in the
<Filename>ADD_STYLE_NAME</Filename> field. The font XLFD patterns matching these names can
match a named size, not a numeric size. These named sizes are used because
the exact size of an interface font is less important than its nominal size, and
implementation differences for the hand-tuned interface fonts do not allow
common numeric point sizes to be assured across systems.</Para>
<Para>The seven nominal sizes are as follows:</Para>
<ProgramListing>xxs extra extra small
xs extra small
s small
m medium
l large
xl extra large
xxl extra extra large</ProgramListing>
<Para>The goal of these named sizes is to provide enough fonts to display a variety
monitor sizes and resolutions that CDE will run on, and the range of user
preferences for comfortably reading button labels, window titles and so forth,
can be accommodated in the GUI. Both the smallest size, xxs, and the largest
size, xxl, are meant to be reasonable sizes for displaying and viewing the CDE
desktop on common displays and X terminals; they are not meant to imply
either hard-to-read fine print or headline-sized display type.</Para>
</Sect2>
<Sect2 Id="PG.fonts.div.5">
<Title>Patterns for the Standard Interface Font Names</Title>
<Para>Using these values, the XLFD pattern</Para>
<ProgramListing>-dt-interface*-*</ProgramListing>
<Para>logically matches the full set of XCDE Standard Interface Font Names. (Note
that no specific X server behavior is implied).</Para>
<Para>For example, in Western locales, the full set of 21 CDE Standard Interface Font
Names can be represented:</Para>
<ProgramListing>-dt-interface system-medium-r-normal-*-*-*-*-*-*-*-iso8859-1
-dt-interface user-medium-r-normal-*-*-*-*-*-m-*-iso8859-1
-dt-interface user-bold-r-normal-*-*-*-*-*-m-*-iso8859-1</ProgramListing>
<Para>The full set of patterns in the <Filename>app-defaults</Filename> files for all seven system font
sizes is:</Para>
<ProgramListing>-dt-interface system-medium-r-normal-xxs*-*-*-*-*-*-*-iso8859-1
-dt-interface system-medium-r-normal-xs*-*-*-*-*-*-*-iso8859-1
-dt-interface system-medium-r-normal-s*-*-*-*-*-*-*-iso8859-1
-dt-interface system-medium-r-normal-m*-*-*-*-*-*-*-iso8859-1
-dt-interface system-medium-r-normal-l*-*-*-*-*-*-*-iso8859-1
-dt-interface system-medium-r-normal-xl*-*-*-*-*-*-*-iso8859-1
-dt-interface system-medium-r-normal-xxl*-*-*-*-*-*-*-iso8859-1</ProgramListing>
<Para>These patterns could be used in a resource file and will match the full CDE
Standard Interface Names for the iso Latin-1 locales on all CDE-compliant
systems. For more information, see the <Filename>DtStdInterfaceFontNames(5)</Filename> man
page.</Para>
</Sect2>
</Sect1>
<Sect1 Id="PG.fonts.div.6">
<Title Id="PG.fonts.mkr.4">Using<IndexTerm>
<Primary>fonts</Primary>
<Secondary>in configuration files</Secondary>
</IndexTerm><IndexTerm>
<Primary>configuration file</Primary>
<Secondary>fonts</Secondary>
</IndexTerm> Fonts in CDE Configuration Files</Title>
<Para>CDE specifies a set of generic standard application font names, in several sizes,
that can be used by applications running under CDE on all platforms. Each
CDE vendor maps the standard set of font names to its available fonts. The
mapping of font names to existing fonts may vary from vendor to vendor.</Para>
<Para>When you use the standard application font names in your <Filename>app-defaults</Filename>
files, you can use a single<IndexTerm>
<Primary>&lt;Filename>app-defaults&lt;Default Para Font> file</Primary>
</IndexTerm>
<Filename>app-defaults</Filename> file across all CDE platforms. If you
do not use the standard font names, you must supply a different <ComputerOutput>app-
defaults</ComputerOutput> files for each application on each CDE platform.</Para>
<Para>All CDE systems provide a set of 13 standard application font names, in at
least 6 sizes, that represent 12 generic design and style variations (serif and
sans serif), as well as a symbol font. These standard names are provided in
addition to the names of the fonts that the standard names are mapped to for a
particular CDE platform. An additional four standard font names&mdash;to allow
both serif and sans serif designs in a monospaced font&mdash;may also be provided
by CDE platform vendors.</Para>
<Para>These 13 font names are provided in CDE platforms for the locales using the<IndexTerm>
<Primary>ISO 8859-1 character set</Primary>
</IndexTerm><IndexTerm>
<Primary>character set ISO 8859-1</Primary>
</IndexTerm>
ISO 8859-1 character set. See the <Emphasis>Common Desktop Environment:
Internationalization Programmer's Guide</Emphasis> for information on using standard font
names in other locales.</Para>
</Sect1>
<Sect1 Id="PG.fonts.div.7">
<Title Id="PG.fonts.mkr.5">Standard Application Fonts</Title>
<Sect2 Id="PG.fonts.div.8">
<Title>Default Font Names<IndexTerm>
<Primary>font names, default</Primary>
</IndexTerm><IndexTerm>
<Primary>default font names</Primary>
</IndexTerm></Title>
<Para>The set of standard application default font names is defined by the XLFD field
name values described in
<!--Original XRef content: 'Table&numsp;2&hyphen;2'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.fonts.mkr.3"></Para>
<Table Id="PG.fonts.tbl.2" Frame="Topbot">
<Title Id="PG.fonts.mkr.6">Field Name Values for Standard Application Font Names</Title>
<TGroup Cols="3">
<ColSpec Colname="1" Colwidth="1.5 in">
<ColSpec Colname="2" Colwidth="1.125 in">
<ColSpec Colname="3" Colwidth="2.375 in">
<THead>
<Row>
<Entry><Para><Literal>Field</Literal></Para></Entry>
<Entry><Para><Literal>Value</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>FOUNDRY</Command></Para></Entry>
<Entry><Para><Command>dt</Command></Para></Entry>
<Entry><Para>CDE name</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>FAMILY_NAME</Filename></Para></Entry>
<Entry><Para><Command>application</Command></Para></Entry>
<Entry><Para>CDE standard application font name</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>WEIGHT_NAME</Filename></Para></Entry>
<Entry><Para><Command>medium</Command> or <Command>bold</Command></Para></Entry>
<Entry><Para>Weight of the font</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>SLANT</Command></Para></Entry>
<Entry><Para><Command>r</Command></Para><Para><Command>i</Command></Para></Entry>
<Entry><Para>Roman</Para><Para>Italic</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>SET_WIDTH</Filename></Para></Entry>
<Entry><Para><Command>normal</Command></Para></Entry>
<Entry><Para>Normal set width</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>ADD_STYLE</Filename></Para></Entry>
<Entry><Para><Command>sans</Command></Para><Para><Command>serif</Command></Para></Entry>
<Entry><Para>Sans serif font</Para><Para>Serif font</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>PIXEL_SIZE</Filename></Para></Entry>
<Entry><Para><Filename>*</Filename></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>POINT_SIZE</Filename></Para></Entry>
<Entry><Para><Symbol Role="Variable">pointsize</Symbol></Para></Entry>
<Entry><Para>Point size of the desired font</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>RESOLUTION_X</Filename></Para></Entry>
<Entry><Para><Filename>*</Filename></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>RESOLUTION_Y</Filename></Para></Entry>
<Entry><Para><Filename>*</Filename></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>AVERAGE_WIDTH</Filename></Para></Entry>
<Entry><Para><Command>p</Command></Para><Para><Command>m</Command></Para></Entry>
<Entry><Para>Proportional</Para><Para>Monospace</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>NUMERIC FIELD</Command></Para></Entry>
<Entry><Para><Filename>*</Filename></Para></Entry>
<Entry><Para>Platform dependent</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>CHAR_SET_REGISTRY</Filename></Para></Entry>
<Entry><Para><Filename>iso8859-1</Filename></Para></Entry>
<Entry><Para>Defining standards authority</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>ENCODING</Command></Para></Entry>
<Entry><Para><Filename>1</Filename></Para></Entry>
<Entry><Para>Character set number</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>.</Para>
<Para>The standard names are available using the regular X Windows XLFD font-
naming scheme. When properly specified with appropriate wildcards for the
platform-dependent fields, a CDE font name is guaranteed to open a valid,
corresponding platform-dependent font. The <Command>XLFD</Command> name returned from a call
to the Xlib <ComputerOutput>XListFont</ComputerOutput> function, however, is not guaranteed to be the same on
all CDE platforms.</Para>
<Para>Using these values, the XLFD pattern</Para>
<ProgramListing>-dt-application-*</ProgramListing>
<Para>matches the full set of CDE standard application font names on a given
platform. The pattern</Para>
<ProgramListing>-dt-application-bold-*-*-*-*-*-*-*-p-*-*-*-</ProgramListing>
<Para>matches the bold, proportionally spaced CDE fonts, both serif and sans serif.
And the pattern</Para>
<ProgramListing>-dt-application-*-*-*-*-*-*-*-*-m-*-*-*-</ProgramListing>
<Para>matches the monospaced fonts (whether serif or sans serif, or both).</Para>
<Para>The full set of CDE Standard Application Font Names can be represented as
follows:</Para>
<ProgramListing>-dt-application-bold-i-normal-serif-*-*-*-*-p-*-iso8859-1
-dt-application-bold-r-normal-serif-*-*-*-*-p-*-iso8859-1
-dt-application-medium-i-normal-serif-*-*-*-*-p-*-iso8859-1
-dt-application-medium-r-normal-serif-*-*-*-*-p-*-iso8859-1
-dt-application-bold-i-normal-sans-*-*-*-*-p-*-iso8859-1
-dt-application-bold-r-normal-sans-*-*-*-*-p-*-iso8859-1
-dt-application-medium-i-normal-sans-*-*-*-*-p-*-iso8859-1
-dt-application-medium-r-normal-sans-*-*-*-*-p-*-iso8859-1
-dt-application-bold-i-normal-*-*-*-*-*-m-*-iso8859-1
-dt-application-bold-r-normal-*-*-*-*-*-m-*-iso8859-1
-dt-application-medium-i-normal-*-*-*-*-*-m-*-iso8859-1
-dt-application-medium-r-normal-*-*-*-*-*-m-*-iso8859-1
-dt-application-medium-r-normal-*-*-*-*-*-p-*-dtsymbol-1</ProgramListing>
</Sect2>
<Sect2 Id="PG.fonts.div.9">
<Title Id="PG.fonts.mkr.7">Point Sizes<IndexTerm>
<Primary>font point sizes</Primary>
</IndexTerm><IndexTerm>
<Primary>point sizes</Primary>
</IndexTerm>
for Standard Application Fonts</Title>
<Para>The complete set of point sizes available for each of the standard application
font names is determined by the set of fonts shipped with a vendor's CDE
platform, whether bitmapped only or both bitmapped and scalable outline.
The minimum set of sizes required and available on all CDE platforms
corresponds to the standard sizes of bitmapped fonts that make up the default
mapping for X11R5: 8, 10, 12, 14, 18, and 24.</Para>
<Para>For example, the entire set of six sizes of the plain monospaced font can be
represented by the patterns:</Para>
<ProgramListing>-dt-application-medium-r-normal-*-80-*-*-*-m-*-iso8859-1
-dt-application-medium-r-normal-*-100-*-*-*-m-*-iso8859-1
-dt-application-medium-r-normal-*-120-*-*-*-m-*-iso8859-1
-dt-application-medium-r-normal-*-140-*-*-*-m-*-iso8859-1
-dt-application-medium-r-normal-*-180-*-*-*-m-*-iso8859-1
-dt-application-medium-r-normal-*-240-*-*-*-m-*-iso8859-1</ProgramListing>
<Para>These patterns match the corresponding standard font name on any CDE
platform, even though the numeric fields other than <Command>POINTSIZE</Command> may be
different on various platforms, and the matched fonts may be either serif or
sans serif, depending on how the vendor implemented the set of standard
names.</Para>
</Sect2>
<Sect2 Id="PG.fonts.div.10">
<Title Id="PG.fonts.mkr.8">Standard Application Font Names in app-defaults files<IndexTerm>
<Primary>font names</Primary>
<Secondary>standard application</Secondary>
</IndexTerm><IndexTerm>
<Primary>standard application font names</Primary>
</IndexTerm></Title>
<Para>You can code a single <ComputerOutput>app-defaults</ComputerOutput> file to specify font resources for your
application and use it across all CDE platforms. Because the parts of the
standard names that are defined are the same across different vendors'
platforms, you can specify these values in the resource specification in the
<ComputerOutput>app-defaults</ComputerOutput> file. However, you must use wildcards for the other fields
(<Filename>PIXEL_SIZE</Filename>, <Filename>RESOLUTION_X</Filename>, <Filename>RESOLUTION_Y</Filename>, and <Filename>AVERAGE_WIDTH</Filename>)
because they may vary across platforms. For example, to specify some of the
default resource needs for an application named <Command>appOne</Command>, you might use:</Para>
<ProgramListing>appOne*headFont: -dt-application-bold-r-normal-sans-*-140-*-*-p-*-iso8859-1
appOne*linkFont: -dt-application-bold-i-normal-sans-*-100-*-*-p-*-iso8859-1</ProgramListing>
<Para>As another example, suppose that <Command>appTwo</Command> running on a vendor's platform
defines two font resources for headings and hypertext links. <Command>appTwo</Command> uses a 14
point bold, serif font (Lucidabright bold) and a 12-point bold, italic sans serif
font (Lucida bold-italic). You would then change the font definition from:</Para>
<ProgramListing>apptwo*headingFont: -b&amp;h-lucidabright-bold-r-normal--20-140-100-100-p-127-iso8859-1
apptwo*linkFont: -b&amp;h-lucida-bold-i-normal-sans-17-120-100-100-p-96-iso8859-1</ProgramListing>
<Para>to:</Para>
<ProgramListing>apptwo*headingFont: -dt-application-bold-r-normal-serif-*-140-*-*-p-*-iso8859-1
apptwo*linkFont: -dt-application-bold-i-normal-sans-*-120-*-*-p-*-iso8859-1</ProgramListing>
<Para>in your <Filename>app-defaults</Filename> file. Even though you may not know the names of the
fonts on other CDE platforms, these platform-independent patterns specified
with the CDE standard application font names match appropriate fonts on
each platform.</Para>
<Para>You encode them exactly as shown, complete with the <Filename>*</Filename> wildcards, in your
resource definitions. By applying the wildcards to the numeric fields other than
point size, you ensure that the resources match CDE fonts on all platforms,
even if the exact pixel size or average width of the fonts is slightly different.</Para>
<Para>See the <Emphasis>Common Desktop Environment Programmer's Reference</Emphasis> and <Command>DtStdAppFontNames(5)</Command> man page for more information.</Para>
</Sect2>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

211
cde/doc/en_US.UTF-8/guides/progGuide/ch03.sgm Normal file
View File

@@ -0,0 +1,211 @@
<!-- $XConsortium: ch03.sgm /main/8 1996/09/08 19:36:25 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="PG.msgs.div.1">
<title id="PG.msgs.mkr.1">Displaying and Logging Messages from Your Application</title>
<para>Users running your application expect messages to be displayed in message
footers, error dialogs, or warning dialogs, with further explanations available
in online help when appropriate. In some circumstances, messages may be logged
that aren't necessarily displayed to users. Applications in the Common Desktop Environment
follow common models for presenting and logging error messages and warnings.</para>
<informaltable id="PG.msgs.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'How to Present Error Messages23'--><xref
role="JumpText" linkend="PG.msgs.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Information to Present in Error Dialogs24'--><xref
role="JumpText" linkend="PG.msgs.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Linking Message Dialogs to Online
Help24'--><xref role="JumpText" linkend="PG.msgs.mkr.4"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Recovery Routines25'--><xref role="JumpText"
linkend="PG.msgs.mkr.5"></para></entry></row>
</tbody></tgroup></informaltable>
<sect1 id="PG.msgs.div.2">
<title id="pg.msgs.mkr.2">How to Present Error Messages<indexterm><primary>error messages</primary><secondary>displaying</secondary></indexterm></title>
<para>Because of the way message text is handled, users may not see messages
from your application unless you display them in a dialog, footer, or elsewhere
in the user interface.</para>
<para>In CDE, such messages are directed to log files that a casual user may
not routinely examine. Use the following rules when deciding where to tell
users about warnings, messages, and error conditions:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>If the message is
informational,</emphasis> display the text in the message footer of the application;
for example, &ldquo;MyDoc file copied.&rdquo;</para>
</listitem><listitem><para><emphasis>If the 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 or warning dialog.</para>
</listitem></itemizedlist>
</sect1>
<sect1 id="PG.msgs.div.3">
<title id="PG.msgs.mkr.3">Information to Present in Error Dialogs</title>
<para>A good error dialog or warning dialog gives the 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 that the user
can relate to the current task and environment</para>
</listitem><listitem><para>How to fix the problem</para>
</listitem></itemizedlist>
<para>If the information cannot be presented in four or five lines of the
error dialog, consider adding a help button to the dialog and link it to
a topic in the help volume for your application.</para>
<para>For more information on writing messages, see the <emphasis>Common Desktop
Environment: Internationalization Programmer's Guide</emphasis>.</para>
</sect1>
<sect1 id="pg.msgs.div.4">
<title id="pg.msgs.mkr.4">Linking Message Dialogs to Online Help</title>
<para>In cases where additional background information is required, or where
it takes more than four or five lines of a dialog to explain an error fully,
you should add a button that links the user to online help.</para>
<para>Adding online help for a dialog is a straightforward task. Once you
have decided that a particular dialog is a candidate for online help, do
the following:</para>
<orderedlist><listitem><para>Choose a unique ID for the error help.</para>
<para>This ID provides the link to the online help text. IDs should be 64
characters or less; for example, <filename>DiskSpaceError</filename>.</para>
</listitem><listitem><para>Create the dialog and add a help callback.</para>
<para>Use the <command>XmCreateErrorDialog</command> convenience function
for error messages and <command>XmCreateWarningDialog</command> for warnings,
adding the help callback as follows:</para>
<programlisting>XtAddCallback(dialog, XmNhelpCallback, <replaceable remap="Emphasis">helpfn</replaceable>, &ldquo;<replaceable remap="Emphasis">ID</replaceable>&rdquo;);</programlisting>
<para>In this example, <emphasis>helpfn</emphasis> is a help function you
have created to manage the help dialog, and the string &ldquo; <emphasis>ID</emphasis>&rdquo; is the ID you chose for the error message (for example, <filename>DiskSpaceError</filename>). In your help function, set the <command>XmNlocationId</command> resource to the value of <emphasis>ID</emphasis>. The
<filename>/usr/dt/examples/dthelp</filename> directory contains examples of how to set
up such a help function.</para>
<para>For detailed information about creating and managing help dialog widgets,
see the <emphasis>Common Desktop Environment: Help System Author's and Programmer's
Guide</emphasis>.</para>
</listitem><listitem><para>Write a corresponding help section for the error
message.</para>
<para>Document the message in the &ldquo;messages&rdquo; chapter of your
help volume. In the help source document, you should have a separate section
for each message, and the ID= attribute at the beginning of the section should
match the ID you chose in your code for the error.</para>
<para>For example, in the <command>s1</command> section heading, the ID is <computeroutput>DiskSpaceError</computeroutput>.</para>
<para>When the user's system has insufficient disk space, the error message
the user sees from the following heading is &ldquo;Could Not Save File.&rdquo;
</para>
<programlisting>&lt;s1 ID=DiskSpaceError>Could Not Save File &lt;\s1></programlisting>
<para>Note that by convention, the text of the section heading should correspond
closely to the text in the error dialog.</para>
</listitem><listitem><para>Rebuild the help file.</para>
<para>The new help section for the error message becomes active as soon as
you rebuild the help file (using the <command>dthelptag</command> program)
and recompile your application.</para>
</listitem></orderedlist>
<para>For information about writing and building online help, see the <emphasis>Common Desktop Environment: Help System Author's and Programmer's Guide</emphasis>.
</para>
</sect1>
<sect1 id="PG.msgs.div.5">
<title id="PG.msgs.mkr.5">Recovery Routines</title>
<para>If a recovery routine exists for an error condition, consider adding
a Retry button to the dialog. For example, if a file could not be copied
because the system had insufficient disk space, you might offer a Recopy
option in the dialog that users could choose once they have corrected a disk
space or permissions problem.</para>
</sect1>
<sect1 id="PG.msgs.div.6">
<title id="PG.msgs.mkr.6">Using Message Logging</title>
<indexterm><primary>error messages</primary><secondary>logging</secondary></indexterm>
<indexterm><primary>message logging</primary><secondary>general information</secondary></indexterm>
<para>The message logging service logs messages for CDE applications. This service provides
a central location for messages that a user or system administrator
can use to diagnose problems. In the desktop environment
applications are started via the <literal>File Manager</literal> or <literal>Front Panel</literal>
(as opposed to direct invocation from a shell). If an application
writes important information to <literal>stderr</literal>, the information may be lost.
For this reason, the application should use the CDE message logging service to
log the information so that users can find it in the log.
Libraries and applications that have no
user interface also use this service to log messages.
Such applications should use the message logging service
instead of writing to the system console or to <literal>stderr</literal>.
</para>
<para>The message logging service supports the following types of messages:
</para>
<itemizedlist remap="Bullet1">
<listitem><para>Information &mdash; informational messages to which users need
not be alerted (for example, status information). It may be acceptable
for the user never to see messages of this type.
</para></listitem>
<listitem><para>Stderr &mdash; if an application needs to log the <literal>stderr</literal>
from a child process, the captured <literal>stderr</literal> should be
logged as a Stderr message type. For example, the
<literal>dtexec</literal> program uses this message type to identify
the messages it logs (the <literal>stderr</literal> from command-type actions).
</para></listitem>
<listitem><para>Debug &mdash; an application's debugging messages
(for example, those seen when a <literal>-debug</literal>
command line option is used) should be logged as Debug type messages.
</para></listitem>
<listitem><para>Warning &mdash; this type is for errors that are
not severe enough to cause application program termination.
</para></listitem>
<listitem><para>Error &mdash; this type is for fatal errors that
require program termination.
</para></listitem>
</itemizedlist>
<para>For daemon-type applications that have no user interface
(for example, low-level services started by the <literal>inetd</literal>),
it is appropriate to use the system's "syslog" service
rather than the CDE message logging service.
</para>
<sect2 id="PG.msgs.div.7">
<Title>Format of Log Entries</title>
<indexterm><primary>message logging</primary><secondary>log entry format</secondary></indexterm>
<para>Entries in the message log are formatted as follows:
</para>
<para><literal>***</literal> <symbol role="Variable">msgtype_string</symbol> <literal>(</literal><symbol role="Variable">msg_type</symbol><literal>):</literal> <symbol role="Variable">program_name</symbol><literal>: PID</literal> <symbol role="Variable">proc_id</symbol><literal>:</literal> <symbol role="Variable">date</symbol>
</para>
<para><symbol role="Variable">message_text</symbol>
</para>
<para><literal>*** [</literal><symbol role="Variable">bytes_output</symbol><literal>]</literal>
</para>
<para>For example,
</para>
<programlisting>*** WARNING(3): fontview: PID 12312: Thu Jun 13 16:51:51 1995
The specified font 'fixed' could not be loaded.
*** [109]
</programlisting>
<Para>One newline is output after the date, one
newline after the message text, and
two after the number of bytes (a blank line separates log entries). The message type
string and date specification should be
retrieved from the current locale's message catalog;
it is the application's responsibility to localize the message to be logged.
</para>
</sect2>
<sect2 id="PG.msgs.div.8">
<title>The Message Logging API</title>
<para>The message logging API comprises the following functions:
</para>
<itemizedlist remap="Bullet1">
<listitem><para><function>DtMsgLogMessage</function> &mdash; logs a message to the message log.<indexterm><primary>DtMsgLogMessage</primary></indexterm>
</para></listitem>
<listitem><para><function>DtMsgLogSetHandler</function> &mdash; installs an alternate message
logging handler that is invoked when the application calls
<function>DtMsgLogMessage</function>. This function is optional
and should be used only to override the default message
logging handler.<indexterm><primary>DtMsgLogSetHandler</primary></indexterm>
</para>
</listitem>
<listitem><para><function>DtMsgLogOpenFile</function> &mdash; opens a message log file.<indexterm><primary>DtMsgLogOpenFile</primary></indexterm>
</para></listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

158
cde/doc/en_US.UTF-8/guides/progGuide/ch04.sgm Normal file
View File

@@ -0,0 +1,158 @@
<!-- $XConsortium: ch04.sgm /main/5 1996/09/08 19:36:34 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="PG.smgr.div.1">
<Title Id="PG.smgr.mkr.1">Integrating with Session Manager</Title>
<Para>Session Manager saves information about the Desktop environment and the
applications running when the user logs out (of the current session) or when
the user saves the environment (in a home session). For an application to be
saved as part of the current session or the home session and then restarted as
part of the next session, it must participate in the X Inter-Client
Communication Conventions Manual (ICCCM) 1.1 Session Management
Protocol. This chapter outlines how Session Manager saves and restores
sessions and details the steps necessary for an application to participate in
session management.</Para>
<InformalTable Id="PG.smgr.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'How Session Manager Saves Sessions and Applications27'--><XRef Role="JumpText" Linkend="PG.smgr.mkr.2"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'How to Program the Application for Session Management28'--><XRef Role="JumpText" Linkend="PG.smgr.mkr.3"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'How Session Manager Restores a Session30'--><XRef Role="JumpText" Linkend="PG.smgr.mkr.4"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
<Sect1 Id="PG.smgr.div.2">
<Title Id="PG.smgr.mkr.2">How Session Manager Saves Sessions and Applications</Title>
<Para>When you exit a session or when you save a Home session, Session Manager:</Para>
<OrderedList>
<ListItem>
<Para>Saves the selected resource settings and X server settings</Para>
</ListItem>
<ListItem>
<Para>Allows each application to save its state and waits for the save to be
completed</Para>
</ListItem>
<ListItem>
<Para>Obtains the command line required to restart the application</Para>
</ListItem>
</OrderedList>
</Sect1>
<Sect1 Id="PG.smgr.div.3">
<Title Id="PG.smgr.mkr.3">How to Program the Application for Session Management</Title>
<Sect2 Id="PG.smgr.div.4">
<Title>Setting the Program Environment</Title>
<Para>This section describes the programming steps necessary for an application to
be saved as part of the integration process.</Para>
<Para>Follow these steps to set the program environment:</Para>
<OrderedList>
<ListItem>
<Para>Include the following header files:</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para><Filename>Xm/Xm.h</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>Xm/Protocols.h</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>Dt/Session.h</Filename></Para>
</ListItem>
</ItemizedList>
</ListItem>
<ListItem>
<Para>Link with <Command>libXm</Command> and <Command>libDtSvc</Command>.</Para>
</ListItem>
<ListItem>
<Para>Initialize the toolkit and create a top-level widget.</Para>
</ListItem>
</OrderedList>
<Sect3 Id="PG.smgr.div.5">
<Title>Setting the WM_SAVE_YOURSELF Atom</Title>
<Para>Use the Motif <Filename>XmAddWMProtocol()</Filename> function to set the <Filename>WM_SAVE_YOURSELF</Filename>
atom on the <ComputerOutput>WM_PROTOCOLS</ComputerOutput> property for the top-level window of your
application, as shown in the following example.</Para>
<ProgramListing>Atom XaWmSaveYourself;
Display *dsp;
dsp = XtDisplay(toplevel);
XaWmSaveYourself =
XmInternAtom(dsp, &rdquo;WM_SAVE_YOURSELF&rdquo;, False);
XmAddWMProtocols(toplevel, &amp;XaWmSaveYourself, 1);</ProgramListing>
<Note>
<Para>Do not set the <ComputerOutput>WM_SAVE_YOURSELF</ComputerOutput> atom for more than one window.</Para>
</Note>
</Sect3>
<Sect3 Id="PG.smgr.div.6">
<Title>Prepare to Receive the WM_SAVE_YOURSELF Message</Title>
<Para>Use the Motif <Filename>XmAddWMProtocolCallback()</Filename> function to establish a callback
procedure to be called when the application receives a <Filename>WM_SAVE_YOURSELF</Filename>
client message:</Para>
<ProgramListing>XmAddWMProtocolCallback(toplevel, XaWmSaveYourself,
SaveYourselfProc,
toplevel);</ProgramListing>
</Sect3>
<Sect3 Id="PG.smgr.div.7">
<Title>Processing the WM_SAVE_YOURSELF Message</Title>
<Para>When Session Manager sends a <Filename>WM_SAVE_YOURSELF</Filename> client message to this
sample application's top-level window, the <Filename>SaveYourselfProc()</Filename> callback
procedure is called. Use thecallback to save the application's state. The
application can save its state by any means you want, but cannot interact with
the user during the save.</Para>
<Para>Session Manager provides the <Filename>DtSessionSavePath()</Filename> function as a way to
return a full path name and a base file name to use for saving the application's
state.</Para>
</Sect3>
<Sect3 Id="PG.smgr.div.8">
<Title>Setting the WM_COMMAND Property</Title>
<Para>After the application has finished processing the <Filename>WM_SAVE_YOURSELF</Filename>
message, either by saving its state or ignoring the message, the application
must set the <Filename>WM_COMMAND</Filename> property on its top-level window to tell Session
Manager that the save operation is complete.</Para>
<Para>Use the Xlib <Filename>XsetCommand()</Filename> function to set the <Filename>WM_COMMAND</Filename> property on the
application's top-level window. Setting this property lets Session Manager
know that the application has finished processing the <Filename>WM_SAVE_YOURSELF</Filename>
message and gives Session Manager the command line it needs to restart the
application.</Para>
<Para><Filename>XsetCommand()</Filename> accepts an array of command-line arguments. If the
application uses the <Filename>DtSessionSavePath()</Filename> function as part of the save
process, <Filename>XsetCommand()</Filename> needs an additional command-line argument: <Command>&hyphen;session</Command> <Symbol Role="Variable">basename</Symbol>, where <Symbol Role="Variable">basename</Symbol> is the base file name returned by
<Filename>DtSessionSavePath()</Filename>.</Para>
</Sect3>
</Sect2>
</Sect1>
<Sect1 Id="PG.smgr.div.9">
<Title Id="PG.smgr.mkr.4">How Session Manager Restores a Session</Title>
<Para>Session Manager restores a session by:</Para>
<OrderedList>
<ListItem>
<Para>Restoring the resource database and server settings</Para>
</ListItem>
<ListItem>
<Para>Restarting applications using the saved command lines</Para>
</ListItem>
</OrderedList>
<Para>If the application used <Filename>DtSessionSavePath()</Filename> to find a path for its saved
state, the application can pass the base file name from the <Filename>-session</Filename> argument
to the <Filename>DtSessionRestorePath()</Filename> function to find the full path name of its
saved-state file.</Para>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

1595
cde/doc/en_US.UTF-8/guides/progGuide/ch05.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

367
cde/doc/en_US.UTF-8/guides/progGuide/ch06.sgm Normal file
View File

@@ -0,0 +1,367 @@
<!-- $XConsortium: ch06.sgm /main/7 1996/10/30 15:04:48 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="PG.wsmgr.div.1">
<Title Id="PG.wsmgr.mkr.1">Integrating with the Workspace Manager</Title>
<Para>The<IndexTerm>
<Primary>Workspace Manager</Primary>
<Secondary>integrating with</Secondary>
</IndexTerm>
Workspace Manager provides the means for an application to manage its
windows within the desktop's multiple workspace environment. An
application can perform four major tasks by communicating with the
Workspace Manager:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Place the application's windows in one or more workspaces</Para>
</ListItem>
<ListItem>
<Para>Identify the workspaces in which the application's windows are located</Para>
</ListItem>
<ListItem>
<Para>Prevent the application's windows from moving to another workspace</Para>
</ListItem>
<ListItem>
<Para>Monitor changes to the workspaces, such as when a user switches from one
workspace to another</Para>
</ListItem>
</ItemizedList>
<Para>Normally, Session Manager will get your application main window into the
right workspace without your intervention. However, if your application has
multiple top-level windows, you should use the Workspace Manager API to
figure out where your windows are and save this data as part of your session
state.</Para>
<Para>See
<!--Original XRef content: 'Chapter&numsp;4, &xd2;Integrating with Session Manager'--><XRef Role="ChapNumAndTitle" Linkend="PG.smgr.mkr.1"> for details on saving
application-related information between sessions.</Para>
<InformalTable Id="PG.wsmgr.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Communicating with the Workspace Manager64'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.2"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Placing an Application Window in Workspaces64'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.3"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Identifying Workspaces Containing the Application Windows65'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.4"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Preventing Application Movement Among Workspaces66'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.5"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Monitoring Workspace Changes67'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.6"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
<Sect1 Id="PG.wsmgr.div.2">
<Title Id="PG.wsmgr.mkr.2">Communicating with the<IndexTerm>
<Primary>Workspace Manager</Primary>
<Secondary>communicating with</Secondary>
</IndexTerm> Workspace Manager</Title>
<Para>An application communicates with the Workspace Manager by using functions
provided by the desktop. These functions allow you to quickly and easily
perform a variety of tasks associated with workspace management. The
following is a list of these functions:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>DtWsmAddCurrentWorkspaceCallback</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmAddWorkspaceFunctions</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmAddWorkspaceModifiedCallback</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmFreeWorkspaceInfo</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmGetCurrentBackdropWindows</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmGetCurrentWorkspace</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmGetWorkspaceInfo</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmGetWorkspaceList</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmGetWorkspacesOccupied</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmOccupyAllWorkspaces</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmRemoveWorkspaceCallback</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmRemoveWorkspaceFunctions</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmSetCurrentWorkspace</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtWsmSetWorkspacesOccupied</Command></Para>
</ListItem>
</ItemizedList>
<Para>Segments of code from two demo programs (<Filename>occupy.c</Filename> and <Filename>wsinfo.c</Filename>)
illustrate the use of these functions. Listings for <Command>occupy.c, wsinfo.c</Command>, and
makefiles for several brands of workstations are in the directory
<Filename>/usr/dt/examples/dtwsm</Filename>. See the applicable man page for more
information on each function.</Para>
</Sect1>
<Sect1 Id="PG.wsmgr.div.3">
<Title Id="PG.wsmgr.mkr.3">Placing an Application Window in<IndexTerm>
<Primary>workspace</Primary>
<Secondary>placing application window in</Secondary>
</IndexTerm> Workspaces</Title>
<Para>An application can place its windows in any or all of the existing workspaces.
<Command>DtWsmOccupyAllWorkspaces</Command> places the windows in all currently defined
workspaces, while <Command>DtWsmSetWorkspacesOccupied</Command> places the windows in
all workspaces named in a list that is passed to the function.</Para>
<Sect2 Id="PG.wsmgr.div.4" Role="Procedure">
<Title>To Place an Application Window in All Workspaces</Title>
<OrderedList>
<ListItem>
<Para>Use <Command><IndexTerm>
<Primary>DtWsmOccupyAllWorkspaces</Primary>
</IndexTerm>DtWsmOccupyAllWorkspaces</Command>.</Para>
<Para>In <Filename>occupy.c</Filename>, the callback <Command>allWsCB</Command> for the Occupy All Workspaces push
button calls this function.</Para>
<ProgramListing>DtWsmOccupyAllWorkspaces (XtDisplay(toplevel),
XtWindow(toplevel));</ProgramListing>
<Para>where:</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para><Filename>XtDisplay(toplevel)</Filename> is the X display.</Para>
</ListItem>
<ListItem>
<Para><Filename>XtWindow(toplevel)</Filename> is the window to be placed in all workspaces.</Para>
</ListItem>
</ItemizedList>
</ListItem>
</OrderedList>
<Para>See the <Command>DtWsmOccupyAllWorkspaces</Command> man page for more information on this
function.</Para>
</Sect2>
<Sect2 Id="PG.wsmgr.div.5" Role="Procedure">
<Title>To Place an Application Window in Specified Workspaces</Title>
<OrderedList>
<ListItem>
<Para>Use <Command><IndexTerm>
<Primary>DtWsmSetWorkspacesOccupied</Primary>
</IndexTerm>DtWsmSetWorkspacesOccupied</Command>.</Para>
<Para>In <Filename>occupy.c</Filename>, the callback <Command>setCB</Command> for the Set Occupancy push button calls
this function.</Para>
<ProgramListing>DtWsmSetWorkSpacesOccupied (XtDisplay(toplevel),
XtWindow(toplevel), paWsSet, numSet);</ProgramListing>
<Para>where:</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para><Filename>XtDisplay(toplevel)</Filename> is the X display.</Para>
</ListItem>
<ListItem>
<Para><Filename>XtWindow(toplevel)</Filename> is the window to be placed in the workspaces.</Para>
</ListItem>
<ListItem>
<Para><Command>paWsSet</Command> is a pointer to a list of workspace names that have been
converted to X atoms.</Para>
</ListItem>
<ListItem>
<Para><Command>numSet</Command> is the number of workspaces in the list.</Para>
</ListItem>
</ItemizedList>
</ListItem>
</OrderedList>
<Para>See the <Command>DtWsmSetWorkspacesOccupied</Command> man page for more information on
this function.</Para>
</Sect2>
</Sect1>
<Sect1 Id="PG.wsmgr.div.6">
<Title Id="PG.wsmgr.mkr.4">Identifying<IndexTerm>
<Primary>workspace</Primary>
<Secondary>identifying</Secondary>
</IndexTerm> Workspaces Containing the Application Windows</Title>
<Para>The function <Command>DtWsmGetWorkspacesOccupied</Command> returns a list of the
workspaces in which a specified application window resides. In <Filename>occupy.c</Filename>, the
procedure <Command>ShowWorkspaceOccupancy</Command> calls this function. Based on the results
of this call, <Command>ShowWorkspaceOccupancy</Command> changes the appearance of the toggle
buttons that represent the workspaces. A check mark appears on every toggle
button in whose workspace the application window resides.</Para>
<Sect2 Id="PG.wsmgr.div.7" Role="Procedure">
<Title>To Identify Workspaces That Contain the Application Window</Title>
<OrderedList>
<ListItem>
<Para>Use <Command><IndexTerm>
<Primary>DtWsmGetWorkspacesOccupied</Primary>
</IndexTerm>DtWsmGetWorkspacesOccupied</Command>.</Para>
</ListItem>
</OrderedList>
<ProgramListing>rval = DtWsmGetWorkspacesOccupied(XtDisplay(toplevel)
XtWindow(toplevel), &amp;paWsIn, &amp;numWsIn);</ProgramListing>
<Para>where:</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para><Filename>XtDisplay(toplevel)</Filename> is the X display.</Para>
</ListItem>
<ListItem>
<Para><Filename>XtWindow(toplevel)</Filename> is the window to be searched for in the
workspaces.</Para>
</ListItem>
<ListItem>
<Para><Command>paWsIn</Command> is the address of a pointer to a list of workspace names that have
been converted to X atoms.</Para>
</ListItem>
<ListItem>
<Para><Command>numWsIn</Command> is the address of an integer into which the number of
workspaces in the list is placed.</Para>
</ListItem>
</ItemizedList>
<Para>After this call, loops are set up to compare the list of workspaces (found in the
procedure <Command>SetUpWorkspaceButtons</Command> by <Command>DtWsmGetWorkspaceList</Command>) with
the list of workspaces in which the application window was found to reside.
The toggle button resource <Command>XmNset</Command> is set to True for each toggle button that
represents a workspace in which the application window resides.</Para>
</Sect2>
</Sect1>
<Sect1 Id="PG.wsmgr.div.8">
<Title Id="PG.wsmgr.mkr.5">Preventing<IndexTerm>
<Primary>workspace</Primary>
<Secondary>preventing application movement</Secondary>
</IndexTerm> Application Movement Among Workspaces</Title>
<Para>The function <Command><IndexTerm>
<Primary>DtWsmRemoveWorkspaceFunctions</Primary>
</IndexTerm>DtWsmRemoveWorkspaceFunctions</Command> prevents an application
from:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Switching from one workspace to another</Para>
</ListItem>
<ListItem>
<Para>Occupying all workspaces</Para>
</ListItem>
<ListItem>
<Para>Being removed from the current workspace</Para>
</ListItem>
</ItemizedList>
<Para><Command>DtWsmRemoveWorkspaceFunctions</Command> does this by making that portion of the
desktop Workspace Manager (<Command>dtwm</Command>) window menu inactive. The application
should call <Command>DtWsmRemoveWorkspaceFunctions</Command> before its top-level window
is mapped because <Command>dtwm</Command> only checks workspace information at the time it
manages the application's top-level window. If you need to call
<Command>DtWsmRemoveWorkspaceFunctions</Command> after the application's top-level window
is managed, then you must first call the Xlib function <Command>XWithdrawWindow</Command>, call
<Filename>DtWsmRemoveWorkspaceFunctions,</Filename> and then call <Command>XMapWindow</Command> to remap
the top-level window.</Para>
<Sect2 Id="PG.wsmgr.div.9" Role="Procedure">
<Title>To Prevent Movement to Another Workspace</Title>
<OrderedList>
<ListItem>
<Para>Use <Command><IndexTerm>
<Primary>DtWsmRemoveWorkspaceFunctions</Primary>
</IndexTerm>DtWsmRemoveWorkspaceFunctions</Command>.</Para>
<ProgramListing>DtWsmRemoveWorkspaceFunctions(XtDisplay(toplevel),
XtWindow(toplevel));</ProgramListing>
<Para>where:</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para><Filename>XtDisplay(toplevel)</Filename> is the X display.</Para>
</ListItem>
<ListItem>
<Para><Filename>XtWindow(toplevel)</Filename> is the window for which workspace movement is
to be prevented.</Para>
</ListItem>
</ItemizedList>
</ListItem>
</OrderedList>
</Sect2>
</Sect1>
<Sect1 Id="PG.wsmgr.div.10">
<Title Id="PG.wsmgr.mkr.6">Monitoring<IndexTerm>
<Primary>workspace</Primary>
<Secondary>monitoring changes</Secondary>
</IndexTerm> Workspace Changes</Title>
<Para>You can monitor workspace changes by using either or both of the following
functions:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command><IndexTerm>
<Primary>DtWsmAddCurrentWorkspceCallback</Primary>
</IndexTerm>DtWsmAddCurrentWorkspaceCallback</Command></Para>
</ListItem>
<ListItem>
<Para><Command><IndexTerm>
<Primary>DtWsmWorkspaceModifiedCallback</Primary>
</IndexTerm>DtWsmWorkspaceModifiedCallback</Command></Para>
</ListItem>
</ItemizedList>
<Para><Command>DtWsmAddCurrentWorkspaceCallback</Command> registers an application callback to
be called whenever the Workspace Manager is switched to a new workspace.
See the <Filename>DtWsmAddCurrentWorkspaceCallback</Filename>(3) man page for more
information.</Para>
<Para><Command>DtWsmWorkspaceModifiedCallback</Command> registers an application callback to be
called whenever a workspace is added, deleted, or changed. See the
<Filename>DtWsmWorkspaceModifiedCallback</Filename>(3) man page for more information.</Para>
<Sect2 Id="PG.wsmgr.div.11" Role="Procedure">
<Title>To Monitor Workspace Switching</Title>
<OrderedList>
<ListItem>
<Para>Use <Command><IndexTerm>
<Primary>DtWsmAddCurrentWorkspaceCallback</Primary>
</IndexTerm>DtWsmAddCurrentWorkspaceCallback</Command>.</Para>
</ListItem>
</OrderedList>
<Para>In the demo program <Filename>wsinfo.c</Filename>, this function is called after the top-level
widget is realized.</Para>
<ProgramListing>DtWsmAddCurrentWorkspaceCallback (toplevel, wschangecb, NULL);</ProgramListing>
<Para>where</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para><Command>toplevel</Command> is the application's top level widget.</Para>
</ListItem>
<ListItem>
<Para><Command>wschangecb</Command> is the name of the function to be called.</Para>
</ListItem>
<ListItem>
<Para><Command>NULL</Command> is the parameter for client data to be passed to the callback. In this
case, no data is passed.</Para>
</ListItem>
</ItemizedList>
</Sect2>
<Sect2 Id="PG.wsmgr.div.12" Role="Procedure">
<Title>To Monitor Other Workspace Changes</Title>
<OrderedList>
<ListItem>
<Para>Use <Command><IndexTerm>
<Primary>DtWsmWorkspaceModifiedCallback</Primary>
</IndexTerm>DtWsmWorkspaceModifiedCallback</Command>.</Para>
<ProgramListing>DtWsmWorkspaceModifiedCallback (toplevel, wschangecb, NULL);</ProgramListing>
<Para>where:</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para><Command>toplevel</Command> is the application's top-level widget.</Para>
</ListItem>
<ListItem>
<Para><Command>wschangecb</Command> is the name of the function to be called.</Para>
</ListItem>
<ListItem>
<Para><Command>NULL</Command> is the parameter for client data to be passed to the callback. In this
case, no data is passed.</Para>
</ListItem>
</ItemizedList>
</ListItem>
</OrderedList>
</Sect2>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

3001
cde/doc/en_US.UTF-8/guides/progGuide/ch07.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

738
cde/doc/en_US.UTF-8/guides/progGuide/ch08.sgm Normal file
View File

@@ -0,0 +1,738 @@
<!-- $XConsortium: ch08.sgm /main/9 1996/10/30 15:30:28 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="PG.aIII.div.1">
<Title Id="PG.aIII.mkr.1">Invoking Actions from Applications</Title>
<Para Id="PG.aIII.mkr.2">If your application manages an extensible collection of data types, there is a
strong likelihood that it should be directly involved with action invocation.
This chapter explains how you can invoke an action from an application.
Included is an example program that shows you how to invoke an action.</Para>
<Para>For more information on<IndexTerm>
<Primary>actions</Primary>
</IndexTerm><IndexTerm>
<Primary>actions</Primary>
<Secondary>invoking from an application</Secondary>
</IndexTerm>
actions and how you create them, see
<!--Original XRef content: 'Chapter&numsp;9,
&xd2;Accessing the Data-Typing Database'--><XRef Role="ChapNumAndTitle" Linkend="PG.datat.mkr.1">, in this manual, and the following
chapters in the <Emphasis>Advanced User's and System Administrator's Guide</Emphasis>:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>&ldquo;Introduction to Actions and Data Types&rdquo;</Para>
</ListItem>
<ListItem>
<Para>&ldquo;Creating Actions and Data Types Using Create Action&rdquo;</Para>
</ListItem>
<ListItem>
<Para>&ldquo;Creating Actions Manually&rdquo;</Para>
</ListItem>
<ListItem>
<Para>&ldquo;Creating Data Types Manually&rdquo;</Para>
<InformalTable Id="PG.aIII.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Mechanisms for Invoking Actions from an Application110'--><XRef Role="JumpText" Linkend="PG.aIII.mkr.3"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Types of Actions111'--><XRef Role="JumpText" Linkend="PG.aIII.mkr.4"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Action Invocation API112'--><XRef Role="JumpText" Linkend="PG.aIII.mkr.5"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Related Information112'--><XRef Role="JumpText" Linkend="PG.aIII.mkr.6"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'actions.c Example Program113'--><XRef Role="JumpText" Linkend="PG.aIII.mkr.7"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Listing for actions.c118'--><XRef Role="JumpText" Linkend="PG.aIII.mkr.18"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
</ListItem>
</ItemizedList>
<Sect1 Id="PG.aIII.div.2">
<Title Id="PG.aIII.mkr.3">Mechanisms for Invoking Actions from an Application</Title>
<Para>The action invocation API exported by the Desktop Services library is one
mechanism available to your application to cause another application to be
invoked or to perform an operation. Other mechanisms include:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>The <Filename>fork/exec</Filename> system calls</Para>
</ListItem>
<ListItem>
<Para>ToolTalk messages</Para>
</ListItem>
</ItemizedList>
<Para>Each of these mechanisms has benefits and limitations, so you must evaluate
your specific situation to determine which is most appropriate.</Para>
<Para><IndexTerm>
<Primary>actions</Primary>
<Secondary>advantages of</Secondary>
</IndexTerm>The advantages of using the action invocation API include:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Actions can encapsulate both traditional command-line applications (that is,
<Command>COMMAND</Command> actions) and ToolTalk applications (that is, <Filename>TT_MSG</Filename> actions). The
application that invokes the action does not need to know whether a
command is forked or a message is sent.</Para>
</ListItem>
<ListItem>
<Para>Actions are polymorphic and are integrated with the desktop's data-typing
mechanisms. This means that an action, such as Open or Print, may have
different behavior depending on the type of argument that is supplied, but
the behavior differences are transparent to the application that invokes the
action.</Para>
</ListItem>
<ListItem>
<Para>Actions provide a great deal of configurability for the application developer,
system integrator, system administrator, and end user. Any one of these
people can edit the action database to modify the definition of how an
action is to be performed.</Para>
</ListItem>
<ListItem>
<Para>Actions work well in distributed environments. If an application uses
<Filename>fork/exec</Filename> to directly invoke another application, then both applications
must be available and able to run on the same system. By contrast, the
action invocation API uses information in the action database to determine
on which system a <Command>COMMAND</Command> action should be invoked.</Para>
</ListItem>
<ListItem>
<Para>Actions enable your application to behave consistently with the behavior of
the desktop. This is because the desktop's components interact by using
actions when manipulating the user's data files.</Para>
</ListItem>
</ItemizedList>
<Para>The disadvantage of using the action invocation API is that it is only an
invocation mechanism that has limited return value capabilities and has no
capabilities for a dialog with the invoked action handler. If these features are
required, <Command>fork/exec/pipes</Command> can be used. However, within CDE, ToolTalk is
the preferred cross process communications mechanism due to its generalized
client/server paradigm.</Para>
<Para>Returning to invocation, suppose your application manages data files in
several different formats (text and graphics) and needs to provide a way for
the user to edit and display these files. To implement this feature without using
actions, you would probably use one of the following mechanisms:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Use <Filename><IndexTerm>
<Primary>fork/exec</Primary>
</IndexTerm>fork/exec</Filename> to start the appropriate editor and invent some mechanism
(for example, environment variables) for the user to specify the names of the
editors. The limitations of this approach include the following:</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para>You must write complex code that uses system calls to invoke
subprocesses and monitors the resulting signals.</Para>
</ListItem>
<ListItem>
<Para>The editors must either be available on the same system as your
application or the system administrator must provide a complex
configuration using facilities such as <Command>rsh</Command>.</Para>
</ListItem>
<ListItem>
<Para>System administrators and users must learn and manage your
application's unique configuration model.</Para>
</ListItem>
</ItemizedList>
</ListItem>
<ListItem>
<Para>Use<IndexTerm>
<Primary>ToolTalk</Primary>
</IndexTerm>
ToolTalk messages to request that operations, such as Edit and Display,
be performed on the data. The limitation of this approach is that ToolTalk-
based editors must be available for all of your types of data.</Para>
</ListItem>
</ItemizedList>
<Para>To implement this feature using actions, you only have to invoke the Open
action on the buffer or on the data file. The action invocation API will use the
action database to determine the appropriate message to send or command to
invoke as well as handle all details, such as creating and cleaning up
temporary files and catching necessary signals.</Para>
</Sect1>
<Sect1 Id="PG.aIII.div.3">
<Title Id="PG.aIII.mkr.4"><IndexTerm>
<Primary>actions</Primary>
<Secondary>types</Secondary>
</IndexTerm><IndexTerm>
<Primary>2</Primary>
</IndexTerm><IndexTerm>
<Primary>2</Primary>
</IndexTerm><IndexTerm>
<Primary>actions</Primary>
<Secondary>types</Secondary>
</IndexTerm>Types of Actions</Title>
<Para>The action application program interface (API) works with any type of action.
Types of actions in the desktop include:</Para>
<InformalTable>
<TGroup Cols="2">
<TBody>
<Row>
<Entry><Para>Command actions</Para></Entry>
</Row>
<Row>
<Entry><Para>Specifies a command line to execute.</Para></Entry>
</Row>
<Row>
<Entry><Para>ToolTalk actions</Para></Entry>
</Row>
<Row>
<Entry><Para>Specifies a ToolTalk message to send, which is then
received by the appropriate application.</Para></Entry>
</Row>
<Row>
<Entry><Para>Map actions</Para></Entry>
</Row>
<Row>
<Entry><Para>Refers to another action instead of defining any specific
behavior.</Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
<Para>See &ldquo;Introduction to Actions and Data Types&rdquo; in the <Emphasis>Common Desktop
Environment: Advanced Users' and System Administrator's Guide</Emphasis> for more
information.</Para>
</Sect1>
<Sect1 Id="PG.aIII.div.4">
<Title Id="PG.aIII.mkr.5"><IndexTerm>
<Primary>action invocation library</Primary>
</IndexTerm>Action Invocation API</Title>
<Para>The action invocation API is exported from the Desktop Services library and
provides functions to accomplish a number of tasks, such as:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Initializing and loading the database of action and data-type definitions.
The database <Emphasis>must</Emphasis> be loaded before an action can be run.</Para>
</ListItem>
<ListItem>
<Para>Querying the database. There are functions to determine whether a specified
action or its associated icon image, label, or description exists.</Para>
</ListItem>
<ListItem>
<Para>Invoking an action. The application can pass file or buffer arguments to the
action.</Para>
</ListItem>
<ListItem>
<Para>Registering a callback to receive action status and return arguments.</Para>
</ListItem>
</ItemizedList>
</Sect1>
<Sect1 Id="PG.aIII.div.5">
<Title Id="PG.aIII.mkr.6">Related Information</Title>
<Para>For detailed information about action commands, functions, and data formats,
see the following man pages:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Filename>dtaction</Filename>(1)</Para>
</ListItem>
<ListItem>
<Para><Filename>dtactionfile(4)</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionCallbackProc</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionDescription</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionExists</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionIcon</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionInvoke</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionLabel</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionQuit</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionQuitType</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>DtActionStUpCb</Filename>(3)</Para>
</ListItem>
<ListItem>
<Para><Filename>dtexec</Filename>(1)</Para>
</ListItem>
</ItemizedList>
</Sect1>
<Sect1 Id="PG.aIII.div.6">
<Title Id="PG.aIII.mkr.7"><IndexTerm>
<Primary>actions</Primary>
<Secondary>example program</Secondary>
</IndexTerm><IndexTerm>
<Primary>actions</Primary>
<Secondary>example program</Secondary>
</IndexTerm>actions.c Example Program</Title>
<Para>This section describes a simple example program, <Filename>actions.c</Filename>. A complete
listing of <Filename>actions.c</Filename> is at the end of this chapter.</Para>
<Sect2 Id="PG.aIII.div.7">
<Title>Loading the Database of Actions and Data Types</Title>
<Para>Before your application can invoke an action, it <Emphasis>must</Emphasis> initialize the Desktop
Services library (which contains the action invocation API) and load the
database of action and data-type definitions.</Para>
</Sect2>
<Sect2 Id="PG.aIII.div.8" Role="Procedure">
<Title>To Initialize the Desktop Services Library</Title>
<OrderedList>
<ListItem>
<Para>Use the <Filename><IndexTerm>
<Primary>DtInitialize</Primary>
</IndexTerm>DtInitialize()</Filename> function to initialize the Desktop Services
Library.</Para>
<programlisting>DtInitialize(*<Symbol Role="Variable">display</Symbol>,<Symbol Role="Variable">widget</Symbol>,*<Symbol Role="Variable">name</Symbol>,*<Symbol Role="Variable">tool_class</Symbol>)</programlisting>
<Para><Filename>DtInitialize()</Filename> uses the default Intrinsic <Command>XtAppContext</Command>. The API
provides an additional function, <Filename><IndexTerm>
<Primary>DtAppInitialize</Primary>
</IndexTerm>DtAppInitialize()</Filename> to use when your
application must specify an <Symbol Role="Variable">app_context</Symbol>:</Para>
<programlisting>DtAppInitialize(<Symbol Role="Variable">app_context</Symbol>,*<Symbol Role="Variable">display</Symbol>,<Symbol Role="Variable">widget</Symbol>,*<Symbol Role="Variable">name</Symbol>, <Symbol Role="Variable">tool_class</Symbol>)</programlisting>
</ListItem>
</OrderedList>
<Sect3 Id="PG.aIII.div.9">
<Title>DtInitialize() Example</Title>
<Para>The following code segment shows how the example program <Filename>actions.c</Filename>
uses <Filename>DtInitialize()</Filename>.</Para>
<ProgramListing>if (DtInitialize(XtDisplay(shell), shell, argv[0],ApplicationClass)==False) {
/* DtInitialize() has already logged an appropriate error msg */
exit(1);
}</ProgramListing>
</Sect3>
</Sect2>
<Sect2 Id="PG.aIII.div.10" Role="Procedure">
<Title>To Load the Actions and Data-Typing Database</Title>
<OrderedList>
<ListItem>
<Para>Use the <Filename><IndexTerm>
<Primary>DtDbLoad</Primary>
</IndexTerm>DtDbLoad()</Filename> function to load the actions and data-typing database.</Para>
<programlisting>DtDbLoad(void)</programlisting>
<Para><Filename>DtDbLoad()</Filename> reads in the action and data-typing database. This function
determines the set of directories that are to be searched for database files (the
database search path) and loads the <Filename>*.dt</Filename> files found into the database. The
directory search path is based on the value of the <Command>DTDATABASESEARCHPATH</Command>
environment variable and internal defaults.</Para>
</ListItem>
</OrderedList>
</Sect2>
<Sect2 Id="PG.aIII.div.11" Role="Procedure">
<Title Id="PG.aIII.mkr.8">To Request Notification of Reload Events</Title>
<Para>If you use DtDbLoad() in a long-lived application, it must dynamically reload
the database whenever it is modified.</Para>
<OrderedList>
<ListItem>
<Para>Use the <Command><IndexTerm>
<Primary>DtDbReloadNotify</Primary>
</IndexTerm>DtDbReloadNotify()</Command>function to request notification of reload
events.</Para>
</ListItem>
</OrderedList>
<ProgramListing>/* Notice changes to the database without needing to restart
application */
DtDbReloadNotify(DbReloadCallbackProc, callback_proc,
XTPointer, client_data);
</ProgramListing>
<OrderedList>
<ListItem>
<Para>Supply a callback that:</Para>
<ItemizedList Remap="Bullet2">
<ListItem>
<Para>Destroys cached database information held by the application</Para>
</ListItem>
<ListItem>
<Para>Calls the <Filename>DtDbLoad()</Filename> function again</Para>
</ListItem>
</ItemizedList>
</ListItem>
</OrderedList>
<Para><Emphasis>C</Emphasis><Symbol Role="Variable">allback_proc</Symbol> cleans up any cached database information your application is
holding and then invokes <Filename>DtDbLoad()</Filename>. <Emphasis>Client_data</Emphasis> may be used to pass
additional client information to the callback routine.</Para>
</Sect2>
<Sect2 Id="PG.aIII.div.12">
<Title Id="PG.aIII.mkr.9">Checking the Actions Database</Title>
<ProgramListing>Your application accesses the database if it needs to display the icon or label for
an action. Also before invoking an action, your application can check that it
exists. An action is identified in the database by the action name:
ACTION <Symbol Role="Variable">action_name</symbol>
{
&hellip;
}</ProgramListing>
<Para>For example, the action definition for the Calculator looks like this:</Para>
<ProgramListing>ACTION Dtcalc
{
LABEL Calculator
ICON Dtcalc
ARG_COUNT 0
TYPE COMMAND
WINDOW_TYPE NO_STDIO
EXEC_STRING /usr/dt/bin/dtcalc
DESCRIPTION The Calculator (Dtcalc) action runs the \
desktop Calculator application.
}</ProgramListing>
<Para>The action name for the Calculator action is Dtcalc.</Para>
<Para>When an executable file has a file name that matches an action name in the
existing database, that file is an action file&mdash;a representation for the underlying
action. The information about the icon and label for that file are stored in the
database.</Para>
</Sect2>
<Sect2 Id="PG.aIII.div.13" Role="Procedure">
<Title>To Determine Whether a Specified Action Definition Exists</Title>
<OrderedList>
<ListItem>
<Para>Use the <Filename><IndexTerm>
<Primary>DtActionExists</Primary>
</IndexTerm><IndexTerm>
<Primary>actions</Primary>
<Secondary>icon image for</Secondary>
</IndexTerm>DtActionExists()</Filename> function to determine whether a specified
action definition exists.</Para>
<programlisting>DtActionExists(*<Symbol Role="Variable">name</Symbol>)</programlisting>
<Para><Filename>DtActionExists()</Filename> checks whether the specified <Symbol Role="Variable">name</Symbol> corresponds to the
name of an action in the database. The function returns True if <Symbol Role="Variable">name</Symbol>
corresponds to an action name, or False if no action with that name is found.</Para>
</ListItem>
</OrderedList>
</Sect2>
<Sect2 Id="PG.aIII.div.14" Role="Procedure">
<Title Id="PG.aIII.mkr.10">To Obtain the Icon Image Information for a Specified Action</Title>
<OrderedList>
<ListItem>
<Para>Use the <Filename Id="PG.aIII.mkr.11">DtActionIcon()</Filename> function to obtain the icon image information.</Para>
<programlisting>DtActionIcon(char *<Symbol Role="Variable">action_name</Symbol>)</programlisting>
</ListItem>
</OrderedList>
<Para>An action definition specifies the icon image used to represent the action in the
definition's ICON field:</Para>
<ProgramListing>ACTION <Symbol Role="Variable">action_name</Symbol>
{
ICON <Symbol Role="Variable">icon_image_base_name</symbol>
&hellip;
}</ProgramListing>
<Para><Filename>DtActionIcon()</Filename> returns a character string containing the value of the icon
image field. If the action definition does not contain an icon field, the function
returns the value of the default action icon image, <Command>Dtactn</Command>.</Para>
<Para>You then need to determine the location of the icon, and the size you want to
use. Icons can exist in four sizes and are available in bitmap or pixmap form.
For example, you can find the base name of the icon file from the action
definition for the Calculator. You then use the base name coupled with the
information given in
<!--Original XRef content: 'Table&numsp;8&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.aIII.mkr.13"> and knowledge of the location of all the icons to
find the specific icon file you want.</Para>
<Para Id="PG.aIII.mkr.12">The icon name for the calculator action is <Command>Dtcalc</Command>, but that is not the entire file
name. Icon file names are based on the size of the icon.
<!--Original XRef content: 'Table&numsp;8&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.aIII.mkr.13"> shows the
sizes and file-naming conventions for the desktop icons.</Para>
<Table Id="PG.aIII.tbl.1" Frame="Topbot">
<Title Id="PG.aIII.mkr.13">Icon Sizes and File Names</Title>
<TGroup Cols="3">
<ColSpec Colname="1" Colwidth="1.25 in">
<ColSpec Colname="2" Colwidth="1.25 in">
<ColSpec Colname="3" Colwidth="1.375 in">
<THead>
<Row>
<Entry><Para><Literal>Icon Size</Literal></Para></Entry>
<Entry><Para><Literal>Bitmap Name</Literal></Para></Entry>
<Entry><Para><Literal>Pixmap Name</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para>16 by 16 (tiny)</Para></Entry>
<Entry><Para><Symbol Role="Variable">name</Symbol><Filename>.t.bm</Filename></Para></Entry>
<Entry><Para><Symbol Role="Variable">name</Symbol><Filename>.t.pm</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para>24 by 24 (small)</Para></Entry>
<Entry><Para><Symbol Role="Variable">name</Symbol><Filename>.s.bm</Filename></Para></Entry>
<Entry><Para><Symbol Role="Variable">name</Symbol><Filename>.s.pm</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para>32 by 32 (medium)</Para></Entry>
<Entry><Para><Symbol Role="Variable">name</Symbol><Filename>.m.bm</Filename></Para></Entry>
<Entry><Para><Symbol Role="Variable">name</Symbol><Filename>.m.pm</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para>48 by 48 (large)</Para></Entry>
<Entry><Para><Symbol Role="Variable">name</Symbol><Filename>.l.bm</Filename></Para></Entry>
<Entry><Para><Symbol Role="Variable">name</Symbol><Filename>.l.pm</Filename></Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Note>
<Para>See &ldquo;Creating Icons for the Desktop&rdquo; in the <Emphasis>Advanced User's &amp; System
Administrator's Guide</Emphasis> for more information about the desktop icon files.</Para>
</Note>
<Para>For bitmaps, there is an additional file that is used as a mask, and its extension
ends with <Filename>_m.bm</Filename>. Thus, there can be a total of three files for each size icon.
Here are the icon files for the calculator:</Para>
<ProgramListing>Dtcalc.t.bm
Dtcalc.t.pm
Dtcalc.t_m.bm
Dtcalc.m.bm
Dtcalc.m.pm
Dtcalc.m_m.bm
Dtcalc.l.bm
Dtcalc.l.pm
Dtcalc.l_m.bm</ProgramListing>
<Note>
<Para>There are no small icons (<Filename>Dtcalc.s.bm</Filename>, <Filename>Dtcalc.s.pm</Filename>,
<Filename>Dtcalc.s_m.bm</Filename>) for the Calculator.</Para>
</Note>
<Para><Filename Id="PG.aIII.mkr.14">DtActionIcon()</Filename> returns only a base name; for the Calculator it is <Command>Dtcalc</Command>.
You must choose the type (pixmap or bitmap) and size (tiny, small, medium, or
large) and append the applicable extension to the base name. In addition, you
must know where the file resides.</Para>
</Sect2>
<Sect2 Id="PG.aIII.div.15" Role="Procedure">
<Title>To Get the Localized Label for an Action</Title>
<OrderedList>
<ListItem>
<Para>Use the<Command Id="PG.aIII.mkr.15"> DtActionLabel()</Command> function to get the localized label for an action.</Para>
<programlisting>char *DtActionLabel(char *<Symbol Role="Variable">actionName</Symbol>)</programlisting>
</ListItem>
</OrderedList>
<Para>An action definition may include a label. The label is defined using the
<Emphasis>label_text</Emphasis> field:</Para>
<ProgramListing>ACTION <Symbol Role="Variable">action_name</symbol>
{
LABEL <Symbol Role="Variable">label_text</symbol>
&hellip;
}</ProgramListing>
<Para>This label is used in graphical components (such as File Manager and the
Application Manager) to label the action's icon. If an action definition does not
include a <Emphasis>label_text</Emphasis> field, the <Symbol Role="Variable">action_name</Symbol> is used.</Para>
<Para>The value of <Emphasis>label_text</Emphasis> string should be used by all interface components to
identify the action to the end user.</Para>
<Para>The <Filename>DtActionLabel()</Filename> function returns the value of the <Emphasis>label_text</Emphasis> field in the
action definition of the action named <Symbol Role="Variable">actionName</Symbol>. If the <Emphasis>label_text</Emphasis> field does not
exist, the function returns the <Symbol Role="Variable">actionName</Symbol>.</Para>
</Sect2>
<Sect2 Id="PG.aIII.div.16">
<Title Id="PG.aIII.mkr.16">Invoking Actions</Title>
<Para>After your application has initialized the Desktop Services Library it can then
invoke an action.</Para>
</Sect2>
<Sect2 Id="PG.aIII.div.17" Role="Procedure">
<Title>To Invoke an Action</Title>
<OrderedList>
<ListItem>
<Para>Use the<Command Id="PG.aIII.mkr.17"> DtActionInvoke</Command> function to invoke an action.</Para>
<programlisting>DtActionInvokeID (<Symbol Role="Variable">widget</Symbol>, <Symbol Role="Variable">action</Symbol>, <Symbol Role="Variable">args</Symbol>, <Symbol Role="Variable">argCount</Symbol>, <Symbol Role="Variable">termOpts, execHost,</Symbol>
<Symbol Role="Variable">contexDir</Symbol>, <Symbol Role="Variable">useIndicator</Symbol>, <Symbol Role="Variable">statusUpdateCb</Symbol>, <Symbol Role="Variable">client_data</Symbol>)</programlisting>
</ListItem>
</OrderedList>
<Para><Filename>DtActionInvoke()</Filename> searches the action database for an entry that matches the
specified action name, and accepts arguments of the class, type, and count
provided. Remember that your application must initialize and load the database
before invoking an action.</Para>
</Sect2>
</Sect1>
<Sect1 Id="PG.aIII.div.18">
<Title Id="PG.aIII.mkr.18">Listing for actions.c</Title>
<ProgramListing>/*
* (c) Copyright 1993, 1994 Hewlett-Packard Company
* (c) Copyright 1993, 1994 International Business Machines Corp.
* (c) Copyright 1993, 1994 Sun Microsystems, Inc.
* (c) Copyright 1993, 1994 Novell, Inc.
*/
#include &lt;Xm/XmAll.h>
#include &lt;Dt/Dt.h>
#include &lt;Dt/Action.h>
#define ApplicationClass &ldquo;Dtaction&ldquo;
static Widget shell;
static XtAppContext appContext;
static Widget actionText;
static Widget fileText;
static void CreateWidgets(Widget);
static void InvokeActionCb(Widget, XtPointer, XtPointer);
static void InvokeAction(char*, char*);
static void DbReloadProc(XtPointer);
void main(int argc, char **argv)
{
Arg args[20];
int n=0;
int numArgs = 0;
shell = XtAppInitialize(&amp;appContext, ApplicationClass, NULL, 0,
&amp;argc, argv, NULL, args, n);
CreateWidgets(shell);
if (DtInitialize(XtDisplay(shell), shell, argv[0],
ApplicationClass)==False) {
/* DtInitialize() has already logged an appropriate error msg */
exit(-1);
}
/* Load the filetype/action databases */
DtDbLoad();
/* Notice changes to the database without needing to restart application */
DtDbReloadNotify(DbReloadProc, NULL);
XtRealizeWidget(shell);
XmProcessTraversal(actionText, XmTRAVERSE_CURRENT);
XtAppMainLoop(appContext);
}
static void CreateWidgets(Widget shell)
{
Widget messageBox, workArea, w;
Arg args[20];
int n;
XmString labelString;
labelString = XmStringCreateLocalized(&ldquo;Invoke&ldquo;);
n = 0;
XtSetArg(args[n], XmNdialogType, XmDIALOG_TEMPLATE); n++;
XtSetArg(args[n], XmNokLabelString, labelString); n++;
messageBox = XmCreateMessageBox(shell, &ldquo;messageBox&ldquo;, args, n);
XtManageChild(messageBox);
XmStringFree(labelString);
XtAddCallback(messageBox, XmNokCallback, InvokeActionCb, NULL);
n = 0;
XtSetArg(args[n], XmNorientation, XmVERTICAL); n++;
XtSetArg(args[n], XmNpacking, XmPACK_COLUMN); n++;
XtSetArg(args[n], XmNnumColumns, 2); n++;
XtSetArg(args[n], XmNentryAlignment, XmALIGNMENT_END); n++;
workArea = XmCreateWorkArea(messageBox, &ldquo;workArea&ldquo;, args, n);
XtManageChild(workArea);
labelString = XmStringCreateLocalized(&ldquo;Invoke Action:&ldquo;);
n = 0;
XtSetArg(args[n], XmNlabelString, labelString); n++;
w = XmCreateLabel(workArea, &ldquo;actionLabel&ldquo;, args, n);
XtManageChild(w);
XmStringFree(labelString);
labelString = XmStringCreateLocalized(&ldquo;On File:&ldquo;);
n = 0;
XtSetArg(args[n], XmNlabelString, labelString); n++;
w = XmCreateLabel(workArea, &ldquo;fileLabel&ldquo;, args, n);
XtManageChild(w);
XmStringFree(labelString);
n = 0;
XtSetArg(args[n], XmNcolumns, 12); n++;
actionText = XmCreateTextField(workArea, &ldquo;actionText&ldquo;, args, n);
XtManageChild(actionText);
n = 0;
XtSetArg(args[n], XmNcolumns, 12); n++;
fileText = XmCreateTextField(workArea, &ldquo;fileText&ldquo;, args, n);
XtManageChild(fileText);
}
static void DbReloadProc(XtPointer cd)
{
/* Pick up any dynamic changes to the database files */
DtDbLoad();
}
static void InvokeActionCb(Widget w, XtPointer cd, XtPointer cb)
{
char *action;
char *file;
action = XmTextFieldGetString(actionText);
if (action == NULL) return;
if (strlen(action) == 0) {
XtFree(action);
return;
}
file = XmTextFieldGetString(fileText);
InvokeAction(action, file);
XtFree(action);
XtFree(file);
XmTextFieldSetString(actionText, &ldquo;&ldquo;);
XmTextFieldSetString(fileText, &ldquo;&ldquo;);
XmProcessTraversal(actionText, XmTRAVERSE_CURRENT);
}
static void InvokeAction(char *action, char *file)
{
DtActionArg *ap = NULL;
int nap = 0;
DtActionInvocationID actionId;
/* If a file was specified, build the file argument list */
printf(&ldquo;&percnt;s(&percnt;s)\n&ldquo;,action,file);
if (file != NULL &amp;&amp; strlen(file) != 0) {
ap = (DtActionArg*) XtCalloc(1, sizeof(DtActionArg));
ap[0].argClass = DtACTION_FILE;
ap[0].u.file.name = file;
nap = 1;
}
/* Invoke the specified action */
actionId = DtActionInvoke(shell,action,ap,nap,NULL,NULL,NULL,True,NULL,NULL);
}
</ProgramListing>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

948
cde/doc/en_US.UTF-8/guides/progGuide/ch09.sgm Normal file
View File

@@ -0,0 +1,948 @@
<!-- $XConsortium: ch09.sgm /main/7 1996/09/08 19:37:22 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="PG.datat.div.1">
<Title Id="PG.datat.mkr.1">Accessing the Data-Typing Database</Title>
<Para>This chapter describes the data-typing functions and how to use the data-
typing database.</Para>
<InformalTable Id="PG.datat.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Summary121'--><XRef Role="JumpText" Linkend="PG.datat.mkr.2"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Data Criteria and Data Attributes122'--><XRef Role="JumpText" Linkend="PG.datat.mkr.5"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Data-Typing Functions129'--><XRef Role="JumpText" Linkend="PG.datat.mkr.9"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Registering Objects as Drop Zones133'--><XRef Role="JumpText" Linkend="PG.datat.mkr.12"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Example of Using the Data-Typing Database134'--><XRef Role="JumpText" Linkend="PG.datat.mkr.14"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
<Sect1 Id="PG.datat.div.2">
<Title Id="PG.datat.mkr.2">Summary</Title>
<Para>Data typing provides an extension to the attributes of files and data beyond
what is provided by the traditional UNIX file systems. These extensions consist
of attributes, such as icon names, descriptions, and actions, that can be
performed on files and data. This information is stored in name/value pairs in
the <Filename>DATA_ATTRIBUTES</Filename> table (or database). The desktop uses a certain set of
<Filename>DATA_ATTRIBUTES</Filename>, described in the following paragraphs. The
<Filename>DATA_ATTRIBUTES</Filename> table is extendable for future and application-specific
growth, although extending this table is not recommended because other
applications may not check the additions.</Para>
<Para>Data is matched with a specific file or data entry in a <Filename>DATA_CRITERIA</Filename> table.
The <Filename>DATA_CRITERIA</Filename> table entries are sorted in decreasing order from most
specific to least specific. For example, <Filename>/usr/lib/lib*</Filename> is more specific than
<Filename>/usr/*</Filename> and would, therefore, appear first. When a request to type a file or
data is made, the table is checked in sequence to find the best match using the
information provided either from the file or from the data. When an
information and entry match is found, <Filename>DATA_ATTRIBUTES_NAME</Filename> is used to
find the proper <Filename>DATA_ATTRIBUTES</Filename> entry.</Para>
<Sect2 Id="PG.datat.div.3">
<Title Id="PG.datat.mkr.3">Library and Header Files<IndexTerm>
<Primary>data typing</Primary>
<Secondary>library</Secondary>
</IndexTerm><IndexTerm>
<Primary>library</Primary>
<Secondary>data typing</Secondary>
</IndexTerm><IndexTerm>
<Primary>actions</Primary>
<Secondary>library</Secondary>
</IndexTerm><IndexTerm>
<Primary>library</Primary>
<Secondary>actions</Secondary>
</IndexTerm><IndexTerm>
<Primary>&lt;Filename>libDtSvc&lt;Default Para Font> library</Primary>
</IndexTerm><IndexTerm>
<Primary>&lt;Filename>libXm&lt;Default Para Font> library</Primary>
</IndexTerm><IndexTerm>
<Primary>&lt;Filename>libX11&lt;Default Para Font> library</Primary>
</IndexTerm></Title>
<Para>To use data typing, you need to link to the <Command>libDtSvc</Command> library. Actions are
usually loaded with the data-typing information. Actions require links to the
<Command>libXm</Command> and <Filename>libX11</Filename> libraries. The header files are <ComputerOutput>Dt/Dts.h</ComputerOutput> and <ComputerOutput>Dt/Dt.h</ComputerOutput>.</Para>
</Sect2>
<Sect2 Id="PG.datat.div.4">
<Title Id="PG.datat.mkr.4">Demo Program<IndexTerm>
<Primary>data typing</Primary>
<Secondary>demo program</Secondary>
</IndexTerm><IndexTerm>
<Primary>demo program</Primary>
<Secondary>data typing</Secondary>
</IndexTerm></Title>
<Para>A demo program containing an example of how to use the data-typing
database is in <Filename>/usr/dt/examples/dtdts/datatypes/datatyping.c</Filename>.</Para>
</Sect2>
</Sect1>
<Sect1 Id="PG.datat.div.5">
<Title Id="PG.datat.mkr.5">Data Criteria and Data Attributes<IndexTerm>
<Primary>data typing</Primary>
<Secondary>data criteria</Secondary>
</IndexTerm><IndexTerm>
<Primary>data criteria</Primary>
</IndexTerm><IndexTerm>
<Primary>data attributes</Primary>
</IndexTerm><IndexTerm>
<Primary>data typing</Primary>
<Secondary>data attributes</Secondary>
</IndexTerm></Title>
<Para>Data typing consists of two parts:</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 attributes of<IndexTerm>
<Primary>data typing</Primary>
<Secondary>criteria</Secondary>
</IndexTerm><IndexTerm>
<Primary>criteria, data typing</Primary>
</IndexTerm>
data criteria, in alphabetical order, are:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>CONTENT</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>DATA_ATTRIBUTES_NAME</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>LINK_NAME</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>LINK_PATH</Filename></Para>
</ListItem>
<ListItem>
<Para><Command>MODE</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>NAME_PATTERN</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>PATH_PATTERN</Filename></Para>
</ListItem>
</ItemizedList>
<Para><!--Original XRef content: 'Table&numsp;9&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.7"> describes the data criteria in the order in which you are most likely to
use them.</Para>
<Table Id="PG.datat.tbl.1" Frame="Topbot">
<Title Id="PG.datat.mkr.6">Data Criteria in Order of Most Likely Use</Title>
<TGroup Cols="3">
<ColSpec Colname="1" Colwidth="1.82341 in">
<ColSpec Colname="2" Colwidth="3.44445 in">
<ColSpec Colname="3" Colwidth="1.72817 in">
<THead>
<Row>
<Entry><Para><Literal>Criteria</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
<Entry><Para><Literal>Typical Usage</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Filename>DATA_ATTRIBUTES_NAME</Filename></Para></Entry>
<Entry><Para>The name of this type of data. This value is a
<Filename>record_name</Filename> in the data attributes table.</Para></Entry>
<Entry><Para>POSTSCRIPT</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>NAME_PATTERN</Filename></Para></Entry>
<Entry><Para>A shell pattern-matching expression describing the file
names that could match this data. The default is an empty
string, which means to ignore file patterns in matching.</Para></Entry>
<Entry><Para><Filename>*.ps</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>CONTENT</Command></Para></Entry>
<Entry><Para>Three values that are interpreted as the start, type, and
value fields of the magic file used by the file utility. See
the <Filename>file</Filename>(1) man page for more information. The default
is an empty field, which means to ignore contents in
matching. The following types are examples of what can
be matched: string, byte, short, long, and file name.</Para></Entry>
<Entry><Para><Command>0 string !&percnt;</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>MODE</Command></Para></Entry>
<Entry><Para>A string of zero to four characters that match the mode
field of a <Command>stat</Command> structure. See the <Filename>stat(2)</Filename> man page for
more information. The first character indicates:</Para><Para><Command>d</Command> matches a directory</Para><Para><Command>s</Command> matches a socket</Para><Para><Command>l</Command> matches a symbolic link</Para><Para><Command>f</Command> matches a regular file</Para><Para><Command>b</Command> matches a block file</Para><Para><Command>c</Command> matches a character special file</Para></Entry>
<Entry><Para><Filename>f&amp;!x</Filename></Para></Entry>
</Row>
<Row>
<Entry></Entry>
<Entry><Para>The characters listed below can be either the first or
subsequent characters:</Para><Para><Command>r</Command> matches any file with any of its user, group, or
other read permission bits set.</Para><Para><Command>w</Command> matches any file with any of its user, group, or
other write permission bits set.</Para><Para><Command>x</Command> matches any file with any of its user, group, or
other execute or directory-search permission
bits set.</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry></Entry>
<Entry><Para>For example, the <Command>MODE</Command> field of <Command>frw</Command> matches any regular
file that is readable or writable; <Command>x</Command> matches any file with
any of its executable or search bits set.</Para><Para>The default is an empty field, which means to ignore the
mode in matching.</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>PATH_PATTERN</Filename></Para></Entry>
<Entry><Para>A shell pattern-matching expression describing the
absolute path names that could match this data. The
default is an empty string, which means to ignore path
patterns in matching.</Para></Entry>
<Entry><Para>*/<Symbol Role="Variable">mysubdir</Symbol>/*</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>LINK_NAME</Filename></Para></Entry>
<Entry><Para>See <Filename>dtdtsfile(4)</Filename> man page.</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para><Filename>LINK_PATH</Filename></Para></Entry>
<Entry><Para>See <Filename>dtdtsfile(4)</Filename> man page.</Para></Entry>
<Entry></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>Some of the more common attributes of data types, in alphabetical order, are:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>ACTIONS</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>COPY_TO_ACTION</Filename></Para>
</ListItem>
<ListItem>
<Para><Command>DESCRIPTION</Command></Para>
</ListItem>
<ListItem>
<Para><Command>ICON</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>INSTANCE_ICON</Filename></Para>
</ListItem>
<ListItem>
<Para>IS_EXECUTABLE</Para>
</ListItem>
<ListItem>
<Para><Filename>IS_TEXT</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>LINK_TO_ACTION</Filename></Para>
</ListItem>
<ListItem>
<Para><Command>MEDIA</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>MIME_TYPE</Filename></Para>
</ListItem>
<ListItem>
<Para><Filename>MOVE_TO_ACTION</Filename></Para>
</ListItem>
<ListItem>
<Para>NAME_TEMPLATE</Para>
</ListItem>
<ListItem>
<Para><Command>PROPERTIES</Command></Para>
</ListItem>
<ListItem>
<Para><Filename>X400_TYPE</Filename></Para>
</ListItem>
</ItemizedList>
<Para><!--Original XRef content: 'Table&numsp;9&hyphen;1'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.6"> describes the data attributes in the order in which you are most likely
to use them.</Para>
<Table Id="PG.datat.tbl.2" Frame="Topbot">
<Title Id="PG.datat.mkr.7">Data Attributes in Order of Most Likely Use</Title>
<TGroup Cols="3">
<ColSpec Colname="1" Colwidth="1.82341 in">
<ColSpec Colname="2" Colwidth="3.20635 in">
<ColSpec Colname="3" Colwidth="1.9623 in">
<THead>
<Row>
<Entry><Para><Literal>Criteria</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
<Entry><Para><Literal>Typical Usage</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>DESCRIPTION</Command></Para></Entry>
<Entry><Para>A human-readable description of this data. If this
field is <Command>NULL</Command> or is not included in the data attribute
record, the name of the data attribute should be used.</Para></Entry>
<Entry><Para>This is a PostScript page
description.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>ICON</Command></Para></Entry>
<Entry><Para>The name of the icon to be used for this data. If this
field is <Command>NULL</Command> or is not included in the data attribute
record, the standard icon should be used. See
<Filename>dtdtsfile(4)</Filename> for more details on icon naming.</Para></Entry>
<Entry><Para><Command>Dtps</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>PROPERTIES</Command></Para></Entry>
<Entry><Para>Keywords to indicate properties for this data. Valid
values are invisible and visible. If this field is <Command>NULL</Command> or
is not included in the data attribute record, the visible
property should be assumed. Use this if you want to
completely hide files from the user.</Para></Entry>
<Entry><Para><Command>invisible</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>ACTIONS</Command></Para></Entry>
<Entry><Para>A list of actions that can be performed on this data.
This list refers to names in the action table for actions
that are to be presented to the user for objects of this
type. If this field is <Command>NULL</Command> or is not included in the data
attribute record, no action is available.</Para></Entry>
<Entry><Para><Filename>Open,Print</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>NAME_TEMPLATE Field</Command></Para></Entry>
<Entry><Para>A string used to create a new file for data of this type.
The string is passed to <Filename>sprintf</Filename>(3) with the file
name as the single argument. The default is empty.
Contrast this field with the <Filename>NAME_PATTERN</Filename> field of
the data criteria table in that the template is used to
create a specific file, such as <Filename>&percnt;s.c</Filename>, whereas the
pattern is used to find files, such as <Filename>*.c</Filename>.</Para></Entry>
<Entry><Para><Filename>&percnt;s.ps</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>IS_EXECUTABLE Field</Command></Para></Entry>
<Entry><Para>A string-Boolean value that tells users of this data
type that it can be executed as an application. If
<Filename>IS_EXECUTABLE</Filename> is set to <Command>true</Command> <Filename>(</Filename>see
<Filename>DtDtsIsTrue()</Filename>) the data is executable. If this field
is <Command>NULL</Command>, is not included in the data attribute record,
or is not set to true, then the data is considered not
executable.</Para></Entry>
<Entry><Para><Command>true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>MOVE_TO_ACTION</Filename></Para></Entry>
<Entry><Para>The name of an action to be invoked when an object
is moved to the current object.</Para></Entry>
<Entry><Para><Filename>FILESYSTEM_MOVE</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>COPY_TO_ACTION</Filename></Para></Entry>
<Entry><Para>The name of an action to be invoked when an object
is copied to the current object.</Para></Entry>
<Entry><Para><Filename>FILESYSTEM_COPY</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>LINK_TO_ACTION</Filename></Para></Entry>
<Entry><Para>The name of an action to be invoked when an object
is linked to the current object.</Para></Entry>
<Entry><Para><Filename>FILESYSTEM_LINK</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para>IS_TEXT</Para></Entry>
<Entry><Para>A string-Boolean value that tells users of this data
type that it is suitable for manipulation (viewing or
editing) in a text editor or text widget. The <Filename>IS_TEXT</Filename>
field is set to <Command>true</Command> <Filename>(</Filename>see <Filename>DtDtsIsTrue()</Filename>) if the data
is textual in nature and if it should be presented to
the user in text form. Criteria for making this
determination include whether data consists of
human language, is generated and maintained
manually, is usefully viewable and editable in a text
editor, or contains no (or only minimal) structuring
and formatting information.</Para></Entry>
<Entry><Para>See
<!--Original XRef content: 'Table&numsp;9&hyphen;3'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.8"> for more
examples.</Para></Entry>
</Row>
<Row>
<Entry></Entry>
<Entry><Para>If the <Filename>IS_TEXT</Filename> field is <Command>true</Command>, the data is eligible to be
displayed directly by an application. That is, the
application can load the data directly into a text
editing widget, such as <Command>XmText</Command>.</Para></Entry>
<Entry></Entry>
</Row>
<Row>
<Entry><Para>MEDIA Field</Para></Entry>
<Entry><Para>The names in the <Command>MEDIA</Command> name space describe the
form of the data itself. <Command>MEDIA</Command> names are used as
ICCCM selection targets, named in the <Command>MEDIA</Command> field of
the data-type records, and used in the type parameter
of ToolTalk Media Exchange messages.</Para><Para>The <Command>MEDIA</Command> name space is a subset of the name space
of selection target atoms as defined by the ICCCM.
All selection targets that specify a data format are
valid <Command>MEDIA</Command> names, and all valid <Command>MEDIA</Command> names can
be used directly as selection targets. Some selection
targets specify an attribute of the selection (for
example, <Filename>LIST_LENGTH</Filename>) or a side effect to occur (for
example, <Command>DELETE</Command>), rather than a data format. These
attribute selection targets are not part of the <Command>MEDIA</Command>
name space.</Para></Entry>
<Entry><Para><Command>POSTSCRIPT</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>MIME_TYPE</Filename></Para></Entry>
<Entry><Para><Command>MEDIA</Command> is the desktop internal, unique name for data
types. However, other external naming authorities
have also established name spaces. Multipurpose
Internet Message Extensions (MIME), as described in
the referenced MIME RFC, is one of those external
registries, and is the standard-type name space for the
desktop mailer.</Para></Entry>
<Entry><Para><Filename>application/postscript</Filename></Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>X400_TYPE</Filename></Para></Entry>
<Entry><Para>X.400 types are similar in structure to the <Command>MEDIA</Command> type,
but are formatted using different rules and have
different naming authorities.</Para></Entry>
<Entry><Para><Command>1 2 840 113556 3 2 850</Command></Para></Entry>
</Row>
<Row>
<Entry><Para><Command>INSTANCE_ICON Field</Command></Para></Entry>
<Entry><Para>The name of the icon to be used for this instance of
data, typically a value such as <Filename>&percnt;</Filename><Symbol Role="Variable">name</Symbol><Filename>&percnt;.icon</Filename> [Bug in
<Command>dtdtsfile(4)</Command> man page, too.] If <Filename>INSTANCE_ICON</Filename>
is set, the application should use it instead of <Command>ICON</Command>. If
this field is <Command>NULL</Command> or is not included in the data
attribute record, the <Command>ICON</Command> field should be used.</Para></Entry>
<Entry><Para><Filename>/</Filename><Symbol Role="Variable">myicondir</Symbol><Filename>/&percnt;</Filename><Symbol Role="Variable">name</Symbol><Filename>&percnt;.</Filename>bm</Para></Entry>
</Row>
<Row>
<Entry><Para><Filename>DATA_HOST</Filename></Para></Entry>
<Entry><Para>The <Filename>DATA_HOST</Filename> attribute is not a field that can be
added to the data attributes table in the <Filename>*.dt</Filename> file, but
it may be returned to an application reading
attributes from the table. The data-typing service
adds this attribute automatically to indicate the host
system from which the data type was loaded. If this
field is <Command>NULL</Command> or is not included in the data attribute
record, the data type was loaded from the local
system.</Para></Entry>
<Entry></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>The <Filename>IS_TEXT</Filename> field differs from the text attribute of the <Filename>MIME_TYPE</Filename> field,
which is the <Command>MIME</Command> content type, as described in the referenced <Command>MIME_ RFC</Command>. The
<Command>MIME</Command> content type determines whether the data consists of textual characters
or byte values. If the data consists of textual characters, and the data is labeled
as <Filename>text/*</Filename>, the <Filename>IS_TEXT</Filename> field determines whether it is appropriate for the data
to be presented to users in textual form.</Para>
<Para><!--Original XRef content: 'Table&numsp;9&hyphen;3'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.8"> shows some examples of <Filename>IS_TEXT</Filename> usage with different <Command>MIME_TYPE</Command> attributes.</Para>
<Table Id="PG.datat.tbl.3" Frame="Topbot">
<Title Id="PG.datat.mkr.8">IS_TEXT Attribute Examples</Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="3.67858 in">
<ColSpec Colname="2" Colwidth="1.33134 in">
<THead>
<Row>
<Entry><Para><Literal>Description and MIME_TYPE Attribute</Literal></Para></Entry>
<Entry><Para><Literal>IS_TEXT Value</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para>Human language encoded in ASCII with <Command>MIME_TYPE
text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Human language encoded in E*UC, JIS, Unicode, or an ISO
Latin charset with <Command>MIME_TYPE text/plain;
charset=XXX</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>CalendarAppointmentAttrs with a <Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>HyperText Markup Language (HTML) with a <Command>MIME_TYPE
text/html</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>PostScript with <Command>MIME_TYPE application/postscript</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>C program source (<Filename>C_SRC</Filename>) with <Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT true</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Bitmaps and pixmaps (<Command>XBM</Command> and <Command>XPM</Command>) with <Command>MIME_TYPE
text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Project or module files for the desktop application building
service with <Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Shell scripts with <Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>Encoded text produced by <Filename>uuencode</Filename>(1) with <Command>MIME_TYPE
text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
<Row>
<Entry><Para>*<Command>MIME_TYPE text/plain</Command></Para></Entry>
<Entry><Para><Command>IS_TEXT false</Command></Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>See the <Filename>dtdtsfile(4)</Filename> man page for more information about data-type
attributes.</Para>
</Sect1>
<Sect1 Id="PG.datat.div.6">
<Title Id="PG.datat.mkr.9">Data-Typing Functions<IndexTerm>
<Primary>functions</Primary>
<Secondary>data typing</Secondary>
</IndexTerm><IndexTerm>
<Primary>data typing</Primary>
<Secondary>functions</Secondary>
</IndexTerm><IndexTerm>
<Primary>data typing</Primary>
<Secondary>functions</Secondary>
</IndexTerm><IndexTerm>
<Primary>functions</Primary>
<Secondary>data typing</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
functions that you can use to query the database for data information are
shown in
<!--Original XRef content: 'Table&numsp;9&hyphen;4'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.datat.mkr.10">. Each of these functions has a man page in section 3.
Refer to the appropriate man page for more information.</Para>
<Table Id="PG.datat.tbl.4" Frame="Topbot">
<Title Id="PG.datat.mkr.10">Data-Typing Database Query Functions<IndexTerm>
<Primary>data typing</Primary>
<Secondary>database query functions</Secondary>
</IndexTerm><IndexTerm>
<Primary>database query functions, data typing</Primary>
</IndexTerm></Title>
<TGroup Cols="2">
<ColSpec Colname="1" Colwidth="2.5 in">
<ColSpec Colname="2" Colwidth="2.5 in">
<THead>
<Row>
<Entry><Para><Literal>Function</Literal></Para></Entry>
<Entry><Para><Literal>Description</Literal></Para></Entry>
</Row>
</THead>
<TBody>
<Row>
<Entry><Para><Command>DtDtsBufferToAttributeList</Command></Para></Entry>
<Entry><Para>Finds the list of data attributes for a
given buffer.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsBufferToAttributeValue</Command></Para></Entry>
<Entry><Para>Finds the data attribute for a given
buffer.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsBufferToDataType</Command></Para></Entry>
<Entry><Para>Finds the data-type name for a given
buffer.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataToDataType</Command></Para></Entry>
<Entry><Para>Finds the data type for a given set of
data.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataTypeIsAction</Command></Para></Entry>
<Entry><Para>Returns the resulting saved data type for
the directory.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataTypeNames</Command></Para></Entry>
<Entry><Para>Finds a complete list of available data
types.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataTypeToAttributeList</Command></Para></Entry>
<Entry><Para>Finds the attribute list for a given data
attribute name.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsDataTypeToAttributeValue</Command></Para></Entry>
<Entry><Para>Finds the attribute value for a given data
attribute name.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFileToAttributeList</Command></Para></Entry>
<Entry><Para>Finds the list of data attributes for a
given file.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFileToAttributeValue</Command></Para></Entry>
<Entry><Para>Finds the data attribute value for a given
file.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFileToDataType</Command></Para></Entry>
<Entry><Para>Finds the data type for a given file.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFindAttribute</Command></Para></Entry>
<Entry><Para>Finds the list of data types where
attribute <Command>name</Command> matches <Command>value</Command>.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFreeAttributeList</Command></Para></Entry>
<Entry><Para>Frees the memory of the given attribute
list.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFreeAttributeValue</Command></Para></Entry>
<Entry><Para>Frees the memory of the given attribute
value.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFreeDataType</Command></Para></Entry>
<Entry><Para>Frees the application memory for the
given data-type name.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsFreeDataTypeNames</Command></Para></Entry>
<Entry><Para>Releases memory created with the
<Command>DtDtsDataTypeNames</Command> or
<Command>DtDtsFindAttribute</Command> call.</Para></Entry>
</Row>
<Row>
<Entry><Para>DtDtsIsTrue</Para></Entry>
<Entry><Para>A convenience function that converts a
string to a Boolean.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsRelease</Command></Para></Entry>
<Entry><Para>Unloads the data-typing database
information, generally in preparation for
a reload.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtDtsSetDataType</Command></Para></Entry>
<Entry><Para>Sets the data type for the specified
directory.</Para></Entry>
</Row>
<Row>
<Entry><Para><Command>DtsLoadDataTypes</Command></Para></Entry>
<Entry><Para>Initializes and loads the database fields
for the data-typing functions. Use instead
of <Command>DtDbLoad</Command> when you do not need to
use actions or action types and you need
extra performance. Use <Command>DtDbLoad</Command> when
you need to use actions.</Para></Entry>
</Row>
</TBody>
</TGroup>
</Table>
<Para>You can type data and retrieve attributes in one of three ways: simple,
intermediate, or advanced.</Para>
<Sect2 Id="PG.datat.div.7">
<Title>Simple Data Typing</Title>
<Para>The simplest way to type data is to use the following functions:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>DtDtsFileToAttributeList</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtDtsFileToAttributeValue</Command></Para>
</ListItem>
</ItemizedList>
<Para>When you use these functions, a file is typed and a single attribute, or the
entire list, is retrieved. System calls are made, data is typed, and the attribute is
retrieved. These functions call the intermediate data-typing functions.</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>DtDtsBufferToAttributeList</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtDtsBufferToAttributeValue</Command></Para>
</ListItem>
</ItemizedList>
<Para>Buffers are assumed to have a mode that matches regular files that have
read/write permissions. See
<!--Original XRef content: '&xd2;Advanced Data Typing'--><XRef Role="SectionTitle" Linkend="PG.datat.mkr.11"> to type read-only
buffers.</Para>
</Sect2>
<Sect2 Id="PG.datat.div.8">
<Title>Intermediate Data Typing</Title>
<Para>When you type data and retrieve attributes, the data-typing part of the process
is the most expensive in terms of performance. You can type data in a second
way that improves performance by separating the data-typing and attribute-
retrieval functions. Use the following functions for intermediate data typing:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Command>DtDtsBufferToDataType</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtDtsFileToDataType</Command></Para>
</ListItem>
<ListItem>
<Para><Command>DtDtsDataTypeToAttributeList</Command></Para>
</ListItem>
<ListItem>
<Para>DtDtsDataTypeToAttributeValue</Para>
</ListItem>
</ItemizedList>
<Para>Use these functions if your application queries for more than a single attribute
value. When you use these functions, an object is typed and then that type is
used to retrieve one or more attributes from the attribute list.</Para>
<Para>Using the intermediate data-typing functions is the recommended way to type
data and retrieve attributes. These functions call the advanced data-typing
functions and make the same assumptions about buffers as the simpler data
typing.</Para>
</Sect2>
<Sect2 Id="PG.datat.div.9">
<Title Id="PG.datat.mkr.11">Advanced Data Typing</Title>
<Para>Advanced data typing separates system calls, data typing, and attribute
retrieval even further. Advanced data typing is more complicated to code
because it uses data from existing system calls, which are initialized in advance
and are not included as part of the data-typing function. Use the following
function for advanced data typing:</Para>
<Para><Command>DtDtsDataToDataType</Command></Para>
<Para>To type a read-only buffer, a <Command>stat</Command> structure should be passed that has the
<Filename>st_mode</Filename> field set to <Command>S_IFREG | S_IROTH | S_IRGRP | S_IRUSR</Command>.</Para>
</Sect2>
<Sect2 Id="PG.datat.div.10">
<Title>Data Types That Are Actions (DtDtsDataTypeIsAction)</Title>
<Para>For every action in a database a <Emphasis>synthetic data type</Emphasis> is generated when a
database is loaded that allows actions to be typed. These data types may have
two additional attributes:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para><Filename>IS_ACTION</Filename> is a string-Boolean value that tells users of this data type that it
is an action. If <Filename>IS_ACTION</Filename> is set to the string <Command>true</Command> (independent of case),
the data is an action.</Para>
</ListItem>
<ListItem>
<Para><Filename>IS_SYNTHETIC</Filename> is a string-Boolean value that tells users of this data type
that it was generated from an entry in the <Command>ACTION</Command> table. If <Filename>IS_SYNTHETIC</Filename>
is set to <Command>true</Command>, the data type was generated.</Para>
</ListItem>
</ItemizedList>
</Sect2>
</Sect1>
<Sect1 Id="PG.datat.div.11">
<Title Id="PG.datat.mkr.12">Registering Objects as Drop Zones<IndexTerm>
<Primary>data typing</Primary>
<Secondary>registering objects as drop zones</Secondary>
</IndexTerm><IndexTerm>
<Primary>drop zone</Primary>
<Secondary>registering objects</Secondary>
</IndexTerm><IndexTerm>
<Primary>registering objects as drop zones</Primary>
</IndexTerm></Title>
<Para>If your application defines data types, follow these steps to ensure that it
provides all the drag and drop behavior that you intend:</Para>
<OrderedList>
<ListItem>
<Para>In your application, decide if you need to define any data types.</Para>
</ListItem>
<ListItem>
<Para>For each data type you define, decide whether you want the associated
object to be a drop zone.</Para>
</ListItem>
<ListItem>
<Para>For each object that you want to register as a drop zone, decide which
operations&mdash;move, copy, or link&mdash;you want to define.</Para>
</ListItem>
<ListItem>
<Para>For the drop operations that are valid for each object, define the appropriate
drop actions (set the <Filename>MOVE_TO_ACTION</Filename>, <Filename>COPY_TO_ACTION</Filename>, and
<Filename>LINK_TO_ACTION</Filename> attributes).</Para>
</ListItem>
</OrderedList>
<Para>If your application displays icons for data objects, you may choose to support
those icons as drop zones. If so, you need to query the <Filename>MOVE_TO_ACTION</Filename>,
<Filename>COPY_TO_ACTION</Filename>, or <Filename>LINK_TO_ACTION</Filename> attributes to determine the drop
behavior for those data objects. Objects should support drop operations only if
the corresponding attribute value is not <Command>NULL</Command>. If all three attributes have <Command>NULL</Command>
values, the object should not be registered as a drop site. Whenever you set at
least one of these attributes for an object with a defined data type, your
application registers that object as a drop zone.</Para>
<Para>When a user drags an object to a drop zone, your application determines
which gesture (that is, which drag operation) was used to make the drop.
Based on the drag operation and the drop zone's data type, the application
retrieves a drop attribute from the data-typing database. It then calls
<Command>DtActionInvoke</Command>, using the following two rules to determine its parameters:</Para>
<OrderedList>
<ListItem>
<Para Id="PG.datat.mkr.13">If the user drops objects A and B onto object C, call <Command>DtActionInvoke</Command> with
C, A and B as <Symbol Role="Variable">args</Symbol>. The <Command>action</Command> is the value of either <Filename>MOVE_TO_ACTION</Filename>,
<Filename>COPY_TO_ACTION</Filename>, <Filename>LINK_TO_ACTION</Filename> of C. If object C is an action, the args
list does not include C. Also, the <Command>action</Command> is C.</Para>
</ListItem>
</OrderedList>
<Para>The File Manager, along with its directory and folder objects, exemplifies how
the desktop uses the move, copy, and link drop attributes. A user can drag and
drop objects (files) to directory folders. File Manager defines
<Filename>MOVE_TO_ACTION</Filename>, <Filename>COPY_TO_ACTION</Filename>, and <Filename>LINK_TO_ACTION</Filename> actions for
folder objects. These actions perform the appropriate file system move, copy,
and link system functions.</Para>
<Para>See <Filename>/usr/dt/appconfig/types/C/dtfile.dt</Filename> for an example of how to
define the <Filename>MOVE_TO_ACTION</Filename>, <Filename>COPY_TO_ACTION</Filename>, and <Filename>LINK_TO_ACTION</Filename>
attributes. See
<!--Original XRef content: 'Chapter&numsp;5, &xd2;Integrating with Drag and Drop'--><XRef Role="ChapNumAndTitle" Linkend="PG.dndPG.mkr.1">, for information
about how to use drag and drop.</Para>
</Sect1>
<Sect1 Id="PG.datat.div.12">
<Title Id="PG.datat.mkr.14">Example of Using the Data-Typing Database<IndexTerm>
<Primary>data typing</Primary>
<Secondary>code example</Secondary>
</IndexTerm><IndexTerm>
<Primary>code example</Primary>
<Secondary>data typing</Secondary>
</IndexTerm></Title>
<Para>This section contains example code of how to use data typing. You can find this
example code in <Filename>/usr/dt/examples/dtdts/datatyping.c</Filename>. The example
code displays the data type, icon name, and supported actions for each file
passed to it. You can then use the <Command>dtaction</Command> client to run a supported action
on the file. The usage for <Command>datatyping</Command> is:</Para>
<ProgramListing>datatyping <Symbol Role="Variable">file1</Symbol> [<Symbol Role="Variable">file2</Symbol> <Symbol Role="Variable">...</Symbol>]
#include &lt;Xm/Form.h>
#include &lt;Xm/Text.h>
#include &lt;Dt/Dts.h>
#define ApplicationClass &ldquo;DtDatatyping&ldquo;
static Widget text;
static void DisplayTypeInfo(int, char**);
int main(int argc, char **argv)
{
XtAppContext appContext;
Widget toplevel, form;
Arg args[20];
int n;
toplevel = XtAppInitialize(&amp;appContext, ApplicationClass,
NULL, 0,
argc, argv, NULL, NULL, 0);
if (argc == 1) {
printf(&ldquo;&percnt;s: No files specified.\n&ldquo;, argv[0]);
exit(1);
}
form = XmCreateForm(toplevel, &ldquo;form&ldquo;, NULL, 0);
XtManageChild(form);
n = 0;
XtSetArg(args[n], XmNleftAttachment, XmATTACH_FORM); n++;
XtSetArg(args[n], XmNrightAttachment, XmATTACH_FORM); n++;
XtSetArg(args[n], XmNtopAttachment, XmATTACH_FORM); n++;
XtSetArg(args[n], XmNbottomAttachment, XmATTACH_FORM); n++;
XtSetArg(args[n], XmNeditable, False); n++;
XtSetArg(args[n], XmNeditMode, XmMULTI_LINE_EDIT); n++;
XtSetArg(args[n], XmNrows, 25); n++;
XtSetArg(args[n], XmNcolumns, 90); n++;
text = XmCreateScrolledText(form, &ldquo;text&ldquo;, args, n);
XtManageChild(text);
XtRealizeWidget(toplevel);
if (DtAppInitialize(appContext, XtDisplay(toplevel), toplevel,
argv[0],
ApplicationClass) == False) {
printf(&ldquo;&percnt;s: Couldn't initialize Dt\n&ldquo;, argv[0]);
exit(1);
}
DtDbLoad();
DisplayTypeInfo(argc, argv);
XtAppMainLoop(appContext);
}
static void DisplayTypeInfo(int argc, char **argv)
{
char *file;
char *datatype;
char *icon;
char *actions;
char str[100];
int i;
sprintf(str, &ldquo;&percnt;-30s\t&percnt;-10s\t&percnt;-8s\t&percnt;-20s\n&ldquo;,
&ldquo;File&ldquo;,
&ldquo;DataType&ldquo;,
&ldquo;Icon&ldquo;,
&ldquo;Actions&ldquo;);
XmTextInsert(text, XmTextGetLastPosition(text), str);
sprintf(str, &ldquo;&percnt;-30s\t&percnt;-10s\t&percnt;-8s\t&percnt;-20s\n&ldquo;,
&ldquo;-------------------&ldquo;,
&ldquo;--------&ldquo;,
&ldquo;----&ldquo;,
&ldquo;-------&ldquo;);
XmTextInsert(text, XmTextGetLastPosition(text), str);
for(i=1; i &lt; argc; i++) {
char *file = argv[i];
/* find out the Dts data type */
datatype = DtDtsFileToDataType(file);
if(datatype) {
/* find the icon attribute for the data type */
icon = DtDtsDataTypeToAttributeValue(datatype,
DtDTS_DA_ICON, file);
}
/* Directly find the action attribute for a file */
actions = DtDtsFileToAttributeValue(file,
DtDTS_DA_ACTION_LIST);
sprintf(str, &ldquo;&percnt;-30s\t&percnt;-10s\t&percnt;-8s\t&percnt;s\n&ldquo;,
file,
datatype?datatype:&ldquo;unknown&ldquo;,
icon?icon:&ldquo;unknown&ldquo;,
actions?actions:&ldquo;unknown&ldquo;);
XmTextInsert(text, XmTextGetLastPosition(text), str);
/* Free the space allocated by Dts */
DtDtsFreeAttributeValue(icon);
DtDtsFreeAttributeValue(actions);
DtDtsFreeDataType(datatype);
}
</ProgramListing>
</Sect1>
</Chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

1441
cde/doc/en_US.UTF-8/guides/progGuide/ch10.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

744
cde/doc/en_US.UTF-8/guides/progGuide/ch11.sgm Normal file
View File

@@ -0,0 +1,744 @@
<chapter id="PG.info.div.1">
<title id="PG.info.mkr.1">Integrating with Information Manager</title>
<indexterm><primary>information manager integration</primary><secondary>general information</secondary></indexterm>
<indexterm><primary>on-line help integration</primary><secondary>general information</secondary></indexterm>
<indexterm><primary>dtinfo</primary><secondary>general information</secondary></indexterm>
<para>The <literal>dtinfo</literal> facility enables CDE users
to browse and search large collections of SGML-formatted
on-line documentation containing graphics and hypertext links.
These collections are referred to as information libraries.
An information library consists of a collection of book cases,
each of which contains a collection of books.
</para>
<para>The information manager is available on the CDE desktop from a number of locations.
<literal>dtinfo</literal> is started automatically by the session manager as part of the initial
user session.
Information libraries are available as DtInfoLib objects on the
desktop from File Manager.
The <literal>dtinfo</literal> application can be started directly from the front panel
or from the <literal>Info Manager</literal> action in the
<literal>Desktop_Apps</literal> application group in <literal>Application Manager</literal>.
</para>
<para>A CDE application calls a small API to integrate
the <literal>dtinfo</literal> browser and so enable access to
information libraries. Should <literal>dtinfo</literal> be unsuited to your application
environment, you can extend it or replace it with your own browser,
using the dtinfo database engine API.
Following some general discussions of the dtinfo facility, this chapter
summarizes both the <literal>dtinfo</literal> API and the
<literal>dtinfo</literal> database engine API.
</para>
<sect1 id="PG.info.div.2">
<title id="PG.info.mkr.2">Server Architecture</title>
<indexterm><primary>dtinfo</primary><secondary>server architecture</secondary></indexterm>
<para>Information management in CDE is based on a server architecture.
This means that only one instance of the main book list window for
<literal>dtinfo</literal> is normally displayed at any time within a CDE desktop session.
User or application requests for new document library connections within
the session are handled by the one instance, maximizing the user's
ability to organize and search on-line documentation, and minimizing
system response time.
</para>
<para>An exception to this behavior occurs when the user
or application requests access to an infolib that
is not accessible from any host on which an existing
<literal>dtinfo</literal> instance is running. When this situation occurs,
the desktop mechanisms automatically launch a new instance
of <literal>dtinfo</literal> on a host that has access to the requested
information library. A similar situation occurs when the
user or application requests access to an infolib in a
locale that is different from those used by any currently
executing <literal>dtinfo</literal> process. In this case, the desktop mechanisms
launch a new instance of <literal>dtinfo</literal> on the same host but in the new
locale. If both conditions apply, the new <literal>dtinfo</literal> instance is
started on a host that has access to the information library
in the requested locale.
</para>
<para>It is possible to create multiple instances on a given execution host in a given
locale by invoking <literal>dtinfo</literal> from the command line. In this case,
<literal>dtinfo</literal> does not take advantage of the ToolTalk mechanisms
to ensure that a single instance only is running on the desktop.
</para>
</sect1>
<sect1 id="PG.info.div.3">
<title id="PG.info.mkr.3">Search Path</title>
<indexterm><primary>dtinfo</primary><secondary>search path</secondary></indexterm>
<indexterm><primary>dtinfo</primary><secondary>environment variables</secondary></indexterm>
<para>The <systemitem class="environvar">DTINFOLIBSEARCHPATH</systemitem> and
<systemitem class="environvar">DTINFOLIBDEFAULT</systemitem> environment
variables are defined at installation time by <command>dtsearchpath</command>.
The infolib search path directs the desktop to search
specified locations for information libraries that are to be
be registered on your system.
</para>
<sect2 id="PG.info.div.4">
<title id="PG.info.mkr.4">Default Infolib Search Path</title>
<para>The default infolib search path includes system-wide and
built-in locations:
</para>
<itemizedlist>
<listitem>
<para>System-wide location &mdash <literal>/etc/dt/infolib/%L/%I.dti</literal>
</para>
</listitem>
<listitem>
<para>Built-in location &mdash <literal>/usr/dt/infolib/%L/%I.dti</literal>
</para>
</listitem>
</itemizedlist>
<para>The default language is C. The value of
<systemitem class="environvar">DTINFOLIBDEFAULT</systemitem> is substituted for %I. The initial default value for
<systemitem class="environvar">DTINFOLIBDEFAULT</systemitem> is <literal>cde</literal>.
</para>
</sect2>
<sect2 id="PG.info.div.5">
<title id="PG.info.mkr.5">How the Application Search Path Affects the Infolib Search Path</title>
<para>When a location is added to the application search path, the appropriate
infolib subdirectory is automatically added to the infolib search path.
For example, if the application server
<literal>hosta:</literal> is added to the
application search path, the directory
<literal>hosta:/etc/dt/infolib/%L</literal> is automatically added to the infolib search path.
</para>
</sect2>
<sect2 id="PG.info.div.6">
<title id="PG.info.mkr.6">Infolib Search Path Environment Variables</title>
<para>The infolib search path is assembled from the built-in locations and the following input variables:
</para>
<itemizedlist>
<listitem>
<para><systemitem class="environvar">DTSPSYSINFOLIB</systemitem> &mdash System-wide infolib search path input variable
</para>
</listitem>
<listitem>
<para><systemitem class="environvar">DTSPUSERINFOLIB</systemitem> &mdash Personal infolib search path input variable
</para>
</listitem>
</itemizedlist>
<para>Use these input variables to specify locations outside the application search path.
The assembled database search path is specified by the output variable <systemitem class="environvar">DTINFOLIBSEARCHPATH</systemitem>.
</para>
</sect2>
<sect2 id="PG.info.div.7">
<title id="PG.info.mkr.7">Syntax for the Infolib Search Path Input Variables</title>
<para>The syntax for the variables <systemitem class="environvar">DTSPSYSINFOLIB</SYSTEMITEM> and <systemitem class="environvar">DTSPUSERINFOLIB</systemitem> is:
</para>
<para><symbol role="variable">VARIABLE</symbol> <literal>=</literal> <symbol role="variable">location [,location...]</symbol>
</para>
<para>where <symbol role="variable">location</symbol> can have the syntax, <Filename>/</Filename><symbol role="variable">path</symbol>,
which specifies a directory on the local (session server) system. Use this syntax to add a local directory.
To specify a location on another system, use its network file name &mdash for example,
<Filename>/nfs/servera/projects/infolib</Filename>.
</para>
</sect2>
<sect2 id="PG.info.div.8">
<title id="PG.info.mkr.8">How the Infolib Search Path Is Assembled</title>
<para>The value of the infolib search path
(<systemitem class="environvar">DTINFOLIBSEARCHPATH</systemitem>) is created by assembling the following locations,
listed in order of precedence:
</para>
<itemizedlist>
<listitem>
<para>Locations specified using the <systemitem class="environvar">DTSPUSERINFOLIB</systemitem> variable
</para>
</listitem>
<listitem>
<para>Locations derived from the <systemitem class="environvar">DTSPUSERAPPHOSTS</systemitem> variable
</para>
</listitem>
<listitem>
<para>The default location: <literal>/etc/dt/infolib/%L/%I.dti</literal>
</para>
</listitem>
<listitem>
<para>Locations specified using the <systemitem class="environvar">DTSPSYSINFOLIB</systemitem> variable
</para>
</listitem>
<listitem>
<para>Locations derived from the <systemitem class="environvar">DTSPSYSAPPHOSTS</systemitem> variable
</para>
</listitem>
<listitem>
<para><literal>/usr/dt/infolib/%L/%I.dti</literal>
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="PG.info.div.9">
<title id="PG.info.mkr.9">Workspace Management</title>
<indexterm><primary>dtinfo</primary><secondary>workspace management</secondary></indexterm>
<para>The browser is workspace-aware to provide
predictable behavior regardless of the workspace
in which it is running at the time of a connection request.
Windows are mapped to workspaces according to the following rules:
</para>
<itemizedlist>
<listitem>
<para>When primary windows are mapped to a new workspace,
all associated secondary windows are also mapped to the new workspace
</para>
</listitem>
<listitem>
<para>When secondary windows are mapped to a new workspace, the
associated primary window and all its associated secondary
windows are also mapped to the new workspace
</para>
</listitem>
<listitem>
<para>When a primary window is mapped to a new workspace, any
other primary windows associated with the application remain in the current workspace
</para>
</listitem>
</itemizedlist>
<para>The <function>DtInfo_LoadInfoLib</function>
and <function>DtInfo_ShowInfoAtLoc</function> messages
cause the browser window to be mapped to the
current workspace. The user can also map application
windows to a new workspaces through the <literal>dtwm</literal> menu.
</para>
</sect1>
<sect1 id="PG.info.div.10">
<title id="PG.info.mkr.10">Application Linkage</title>
<indexterm><primary>dtinfo</primary><secondary>application linkage</secondary></indexterm>
<para>Applications are provided with a means to
activate <literal>dtinfo</literal> for specific
on-line documentation display purposes. One use of
the <literal>dtinfo</literal> External API might be an application that
manages or automates information display or navigation.
</para>
<para>Connecting to <literal>dtinfo</literal>
from an application (using an explicit locator value with the
<function>DtShowInfoAtLoc</function> action) displays the browser if it is not already visible.
The following situations vary this result:
</para>
<itemizedlist>
<listitem>
<para>Only an infolib path is specified for the
browser to access (using the
<function>DtLoadInfoLib</function> action), in which case
only the top <literal>dtinfo</literal> (booklist) window is presented,
including the newly loaded infolib's bookcases.
</para>
</listitem>
<listitem>
<para><literal>dtinfo</literal> is active in the workspace, but the
Book List window and/or a browser is iconified.
</para>
<itemizedlist>
<listitem>
<para>The Book List window and any "pinned" browser window(s)
remains iconified. If there is no unpinned browser window
(iconified or not), a new browser window is presented for the requested topic.
</para>
</listitem>
<listitem>
<para>If an iconified Browser window is not pinned, it is mapped
and the requested topic supplants the previous topic.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>The desktop and a <literal>dtinfo</literal> instance were started on one host
(<literal>host1</literal>) in a locale (<literal>locale1</literal>), but an application that uses <literal>dtinfo</literal>
is started from a remote shell on a different (<literal>host2</literal>) and/or a different locale
(<literal>locale2</literal>) during the same CDE session.
</para>
<itemizedlist>
<listitem>
<para>The request from the application is examined by all <literal>dtinfo</literal>
processes in the current session to determine if it can be processed.
For a <literal>dtinfo</literal> process to accept the request it must
be running in the same locale <emphasis>and</emphasis> be able to access the specified information libraries.
</para>
</listitem>
<listitem>
<para>If no such process exists, an independent copy of the browser is started on
<literal>host2</literal> in <literal>locale2</literal>. The original message is forwarded to the new
instance for processing.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="PG.info.div.11">
<title id="PG.info.mkr.11">ToolTalk Messages</title>
<indexterm><primary>dtinfo</primary><secondary>ToolTalk messages</secondary></indexterm>
<para>The <literal>dtinfo</literal> command registers with ToolTalk to
handle the following messages:
</para>
<itemizedlist>
<listitem>
<para><function>DtInfo_LoadInfoLib</function> (scope <Symbol>TT_SESSION</Symbol>)
</para>
</listitem>
<listitem>
<para><function>DtInfo_ShowInfoAtLoc</function> (scope <Symbol>TT_SESSION</Symbol>)
</para>
</listitem>
</itemizedlist>
<para>A <literal>dtinfo</literal> instance observes the following messages:
</para>
<itemizedlist>
<listitem>
<para><function>DtInfo_Quit</function> (scope <Symbol>TT_SESSION</Symbol>)
</para>
</listitem>
</itemizedlist>
<para>The Information Management system also defines a ptype "DtInfo"
that is used to launch a <literal>dtinfo</literal> process if
there is not a currently available <literal>dtinfo</literal>
process that can handle a ToolTalk request.
</para>
</sect1>
<sect1 id="PG.info.div.12">
<title id="PG.info.mkr.12">Generalized Locator Format</title>
<indexterm><primary>dtinfo</primary><secondary>information locator format</secondary></indexterm>
<para>For the purpose of addressing infolibs as document collections
with external navigation references, a generalized locator format
is defined for use in applications and by the end-user. This
mechanism is more precise than those that operate on the
<Symbol>DtInfoLib</Symbol> level. This mechanism can be
used by applications that want to integrate their
on-line documentation tightly, within the action system, or for printing
specific sections from a command line.
</para>
<para>The following BNF defines the syntax of a generalized locator format string:
</para>
<programlisting>&lt;GLF&gt; ::= &lt;MMDB&gt; | &lt;ULV&gt; | &lt;URI&gt;
&lt;MMDB&gt; ::= mmdb: &lt;IBL&gt; | &lt;IB&gt; | &lt;IL&gt; | &lt;INFOLIB&gt; | &lt;BL&gt; | &lt;BOOKCASE&gt; |
&lt;LOCATOR&gt;
&lt;IBL&gt; ::= &lt;INFOLIB&gt; &amp; &lt;BOOKCASE&gt; &amp; &lt;LOCATOR&gt;
&lt;IB&gt; ::= &lt;INFOLIB&gt; &amp; &lt;BOOKCASE&gt;
&lt;IL&gt; ::= &lt;INFOLIB&gt; &amp; &lt;LOCATOR&gt;
&lt;BL&gt; ::= &lt;BOOKCASE&gt; &amp; &lt;LOCATOR&gt;
&lt;INFOLIB&gt; ::= INFOLIB= &lt;NAME&gt;
&lt;BOOKCASE&gt; ::= BOOKCASE= &lt;NAME&gt;
&lt;LOCATOR&gt; ::= LOCATOR= &lt;ULV&gt; &lt;NAME&gt;
&lt;ULV&gt; ::= uuid_ | xsm_ | isbn_
&lt;NAME&gt; ::= &lt;CHAR&gt; { &lt;CHAR&gt;)
&lt;CHAR&gt; ::= a-z | A-Z | 0-9 | &lt;SPECIAL_CHAR&gt;
&lt;SPECIAL_CHAR&gt; ::= everything but ":" and "&amp;"
&lt;URI&gt; ::= Uniform Resource Identifier (as defined by the Web Consortium)
</programlisting>
<para>As shown above, there are several reserved terms that are used to
identify locator format, including <literal>uuid</literal> (for DCE-style Universal Unique ID),
<literal>xsm</literal> (for XSession Manager style Unique ID), and <literal>isbn</literal> (for
International Standard Book Number). Of these, only <literal>xsm</literal> is
supported directly in the sample implementation.
</para>
</sect1>
<sect1 id="PG.info.div.13">
<title id="PG.info.mkr.13">Summary of the DtInfo API</title>
<indexterm><primary>dtinfo</primary><secondary>API</secondary></indexterm>
<para>Following is a summary of the Desktop Information Manager API.
</para>
<variablelist>
<varlistentry><term><function>DtInfoLib</function></term>
<listitem>
<para><function>DtInfoLib</function> is a desktop object that represents a collection
of bookcases of documents that can be accessed
through the Information Manager. DtInfoLib data
criteria and data attributes are identified for
use by desktop facilities. These are part of the CDE built-in
data types.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtInfoShowTopic</function></term>
<listitem>
<para>This is a C API callable by an application
to provide the user access to body of information
at a specific location. The location may
identify anything from the top of a bookcase
to a specific topic or to a section within a bookcase.
Targets within sections are also possible, where
they have been given externally unique link IDs
during construction of the data.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtActionInvoke</function></term>
<listitem>
<para>This function displays a specified topic under
<function>dtinfo</function> using the available CDE desktop
action API from a desktop application.
It invokes (or connects to) <function>dtinfo</function>. The anchor point may be as
broad as the top of a bookcase, or as fine as a specific
topic (section). Targets within sections are also possible,
where they have been given externally unique link IDs during
construction of the data.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>Browse</function></term>
<listitem>
<para>The <function>Browse</function> for an infolib is a remap
to the <function>DtLoadInfoLib</function> action.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>Open</function></term>
<listitem>
<para>The <function>Open</function> action is used to invoke <function>DtLoadInfoLib</function> for the
associated <function>DtInfoLib</function> object.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtShowInfoAtLoc</function></term>
<listitem>
<para>The <function>DtShowInfoAtLoc</function> action distributes a ToolTalk message for
the browser to display a specific point in the infolib.
A client application requests that <function>dtinfo</function> display a particular
section of data, or topic, by invoking this action.
The browser is started if it is not already running.
This corresponds to invoking the <command>dtinfo</command> command with
the <literal>-sect</literal> option from the command line.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtLoadInfoLib</function></term>
<listitem>
<para>The <function>DtLoadInfoLib</function> action distributes a ToolTalk message
for <function>dtinfo</function> to load a specific infolib.
A client application can request that <function>dtinfo</function> load a particular
information library by invoking this action. The browser is started if it is not
already running. This corresponds to invoking the <command>dtinfo</command> command with the
<literal>-l</literal> option from the command line.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtInfo_LoadInfoLib</function></term>
<listitem>
<para>The <function>DtInfo_LoadInfoLib</function> ToolTalk operation is used to load a specified infolib.
A client application can request that <function>dtinfo</function> load a particular
information library by sending this request. The browser is started if it is not
already running. This corresponds to invoking the <command>dtinfo</command> command with the
<literal>-l</literal> option from the command line.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtInfo_ShowInfoAtLoc</function></term>
<listitem>
<para>A client application requests that <function>dtinfo</function> display a particular
section of data, or topic, by sending this process-oriented ToolTalk message.
ToolTalk starts the browser if it is not already running. This
corresponds to invoking the <command>dtinfo</command> command with the
<literal>-sect</literal> option from the command line.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtInfo_Quit</function></term>
<listitem>
<para>This is a process-oriented ToolTalk message for observers interested only
in the status of <function>dtinfo</function>. The browser posts this message
when it exits normally. It is not sent for desktop
session-wide exit.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="PG.info.div.14">
<title id="PG.info.mkr.14">Summary of the DtInfo Database Engine API</title>
<indexterm><primary>dtinfo</primary><secondary>database engine API</secondary></indexterm>
<para>This section summarizes the application programming interface to the DtInfo Database Engine.
The DtInfo Database Engine stores and provides access to the on-line document data for the
DtInfo.
</para>
<sect2 id="PG.info.div.15">
<title id="PG.info.mkr.15">Functions</title>
<variablelist>
<varlistentry><term><function>DtMmdbInit</function></term>
<listitem>
<para>Prepare the database engine to provide access service.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbQuit</function></term>
<listitem>
<para>Free memory resource allocated by the database engine and ask the engine to stop service.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbOpenInfoLib</function></term>
<listitem>
<para>Obtain an infolib descriptor.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbInfoLibGetInfo</function></term>
<listitem>
<para>Get descriptive information about an infolib.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbInfoLibFreeInfo</function></term>
<listitem>
<para>Free space occupied by an infolib structure.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbCloseInfoLib</function></term>
<listitem>
<para>Declare that the infolib is no longer needed.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbGetBookCaseByName</function></term>
<listitem>
<para>Obtain a descriptor to a bookcase identified by name.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbGetBookCaseByIndex</function></term>
<listitem>
<para>Obtain a descriptor to a bookcase identified by index.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbGetBookCaseByLoc</function></term>
<listitem>
<para>Obtain a descriptor to a bookcase identified by location.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbGetBookCaseByLocs</function></term>
<listitem>
<para>Obtain a list of bookcase descriptors.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbBookCaseGetInfo</function></term>
<listitem>
<para>Get information about a bookcase.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbBookCaseFreeInfo</function></term>
<listitem>
<para>Free space occupied by a bookcase information structure.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbSectionGetLoc</function></term>
<listitem>
<para>Get a section's locator.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbSectionGetLongTitle</function></term>
<listitem>
<para>Return the long title of the section, given its identifier.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbSectionGetShortTitle</function></term>
<listitem>
<para>Get a section's short title.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbSectionGetData</function></term>
<listitem>
<para>Get a section's data.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbSectionGetDataSize</function></term>
<listitem>
<para>Get the number of bytes for the section's data.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbSectionGetTocLoc</function></term>
<listitem>
<para>Given a section's identifier, get the locator of its TOC section.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbSectionGetBookId</function></term>
<listitem>
<para>Given a section's identifier, get the DtInfo Database object identifier of the book
in which this section appears.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbSectionGetStyleSheetId</function></term>
<listitem>
<para>Given a section's identifier, get the DtInfo Database object Identifier of the stylesheet applicable to this section.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbTocGetParentId</function></term>
<listitem>
<para>Get the DtInfo Database object identifier of the section that is the parent of this section.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbTocGetChildIds</function></term>
<listitem>
<para>Get a list of DtInfo Database object identifiers for the child sections.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbTocGetNumOfChildren</function></term>
<listitem>
<para>Get the number of child sections.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbLocatorGetSectionLoc</function></term>
<listitem>
<para>Get the locator of a section, given the locator of a component inside the section.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbLocatorGetSectionObjectId</function></term>
<listitem>
<para>Get the DtInfo Database object identifier of the section, given the locator of a component inside the section.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbGraphicGetData</function></term>
<listitem>
<para>Obtain the data of a graphic object.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbGraphicGetInfo</function></term>
<listitem>
<para>Obtain the information of a graphic object.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbStylesheetGetName</function></term>
<listitem>
<para>Obtain the name of a stylesheet object.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbStylesheetGetData</function></term>
<listitem>
<para>Obtain the data of a stylesheet object.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbBookGetTocObjectId</function></term>
<listitem>
<para>Obtain the locator of a TOC section.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbBookGetShortTitle</function></term>
<listitem>
<para>Obtain the short title of a book.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbBookGetLongTitle</function></term>
<listitem>
<para>Obtain the long title of a book.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbBookGetSeqNum</function></term>
<listitem>
<para>Obtain the sequence number of a book.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbBookGetLicense</function></term>
<listitem>
<para>Obtain the license terms of a book.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbBookGetTabList</function></term>
<listitem>
<para>Obtain the list of tabbed sections in the book.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbDlpGetPrevSectionId</function></term>
<listitem>
<para>Obtain the DtInfo Database object identifier of the previous section, given the identifier of this section.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbDlpGetNextSectionId</function></term>
<listitem>
<para>Obtain the DtInfo Database object identifier of the next section.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbFreeHandle</function></term>
<listitem>
<para>Free memory resource used by a DtMmdbHandle.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbFreeHandleList</function></term>
<listitem>
<para>Free memory resource used by a DtMmdbHandle array, including the contained handlers.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtMmdbFreeGraphicInfo</function></term>
<listitem>
<para>Free memory used by a DtMmdbGraphicInfo structure.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="PG.info.div.16">
<title id="PG.info.mkr.16">Data Structures</title>
<indexterm><primary>dtinfo</primary><secondary>database engine data structures</secondary></indexterm>
<variablelist>
<varlistentry><term><structname role="typedef">DtMmdbInfoLib</structname></term>
<listitem>
<para>Contains information about an information library (infolib).
</para>
</listitem>
</varlistentry>
<varlistentry><term><structname role="typedef">DtMmdbBookCase</structname></term>
<listitem>
<para>Contains information about a bookcase.
</para>
</listitem>
</varlistentry>
<varlistentry><term><structname role="typedef">DtMmdbHandle</structname></term>
<listitem>
<para>Contains information about the identifier of a DtInfo object.
</para>
</listitem>
</varlistentry>
<varlistentry><term><structname role="typedef">DtMmdbInfoRequest</structname></term>
<listitem>
<para>Describes a request to get information from the DtInfo Database Engine.
</para>
</listitem>
</varlistentry>
<varlistentry><term><structname role="typedef">DtMmdbGraphicInfo</structname></term>
<listitem>
<para>Describes various features of a graphic object.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
</chapter>
<!-- $XConsortium: ch11.sgm /main/5 1996/09/08 19:37:42 rws $ -->
<!-- (c) Copyright 1996 Digital Equipment Corporation. -->
<!-- (c) Copyright 1996 Hewlett-Packard Company. -->
<!-- (c) Copyright 1996 International Business Machines Corp. -->
<!-- (c) Copyright 1996 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1996 Novell, Inc. -->
<!-- (c) Copyright 1996 FUJITSU LIMITED. -->
<!-- (c) Copyright 1996 Hitachi. -->

350
cde/doc/en_US.UTF-8/guides/progGuide/ch12.sgm Normal file
View File

@@ -0,0 +1,350 @@
<!-- $XConsortium: ch12.sgm /main/6 1996/09/08 19:37:51 rws $ -->
<!-- (c) Copyright 1996 Digital Equipment Corporation. -->
<!-- (c) Copyright 1996 Hewlett-Packard Company. -->
<!-- (c) Copyright 1996 International Business Machines Corp. -->
<!-- (c) Copyright 1996 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1996 Novell, Inc. -->
<!-- (c) Copyright 1996 FUJITSU LIMITED. -->
<!-- (c) Copyright 1996 Hitachi. -->
<chapter id="PG.print.div.1">
<title id="PG.print.mkr.1">CDE Printing Widgets and APIs</title>
<para><indexterm><primary>printing</primary><secondary>general information</secondary></indexterm>CDE users typically print files through a series of dialogs,
the first one being initiated by selecting (for example) the
pulldown menu for printing a file. This chapter documents a set
of dialogs provided by CDEnext for use primarily by applications
that perform X printing:
</para>
<itemizedlist>
<listitem>
<para>The initial print dialog is provided as
the <function>DtPrintSetupBox</function> widget. This consists of the set of generic
print options, a possible application-specific set of print
options, and a set of command buttons at the bottom to start or
cancel the print operation, bring up the Print Dialog Manager (PDM), or bring up a help
dialog.
</para>
</listitem>
<listitem>
<para>The <function>DtPrinterSelectionDialog</function> is for selecting
X Printers and is accessible through the <function>DtPrintSetupBox</function> widget.
</para>
</listitem>
<listitem>
<para>A dialog for obtaining additional printer information, the
<function>DtPrinterInfoDialog</function>, is accessible through either the
<function>DtPrintSetupBox</function> or the
<function>DtPrinterSelectionDialog</function>.
</para>
</listitem>
</itemizedlist>
<para>There is also a file selection dialog (accessible through <function>DtPrintSetupBox</function>)
that enables users to select files to be printed. All of these sub-dialogs
are considered part of the <function>DtPrintSetupBox</function> widget, and
as such, there is no external API for them.
</para>
<para>Although <function>DtPrintSetupBox</function> is designed primarily for X printing,
it is also designed for use as a general application
print dialog for use in any CDEnext application that provides printing.
<function>DtPrintSetupBox</function> is also designed to allow simple
integration with the Print Dialog Manager, which
provides additional printer and spooler specific
X printing setup dialogs.
</para>
<para>The remaining sections of this chapter document the
DtPrint convenience functions, the DtPrint Dialog Manager, and how to integrate help
with the printing widgets.
</para>
<sect1 id="PG.print.div.2">
<title id="PG.print.mkr.2">DtPrint Functions</title>
<indexterm><primary>printing</primary><secondary>dtprint functions</secondary></indexterm>
<indexterm><primary>dtprint functions</primary></indexterm>
<para>This section summarizes DtPrint functions. Sample code
illustrating their use can be found in the <Filename>/proj/cde/examples/dtprint</Filename> directory.
<variablelist>
<varlistentry><term><function>DtPrintSetupBox</function></term>
<listitem>
<para><function>DtPrintSetupBox</function> is a widget that is typically the initial window used to set various options prior to printing from an application. This widget is primarily designed for use by applications that utilize the X Print Service. However, the widget interface is also designed to be flexible enough for use by applications employing other printing methods.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtCreatePrintSetupBox</function></term>
<listitem>
<para><function>DtCreatePrintSetupBox</function> is a convenience function that creates an unmanaged instance of a <function>DtPrintSetupBox</function> widget, and returns its widget ID.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtCreatePrintSetupDialog</function></term>
<listitem>
<para><function>DtCreatePrintSetupDialog</function> is a convenience function that creates an instance of a dialog containing a <function>DtPrintSetupBox</function> widget, and returns the <function>DtPrintSetupBox</function> widget ID.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtPrintFillSetupData</function></term>
<listitem>
<para><function>DtPrintFillSetupData</function> is used to obtain an X printer connection in order to
initiate an X printing job in situations other than direct interaction with a
<function>DtPrintSetupBox</function> (for example, a "quick print" button on a toolbar). This printer
connection information can be obtained from an existing <function>DtPrintSetupBox</function>
widget instance, or if a <function>DtPrintSetupBox</function> widget instance is unavailable,
<function>DtPrintFillSetupData</function> will provide a new X printer connection.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtPrintCopySetupData</function></term>
<listitem>
<para><function>DtPrintCopySetupData</function> is used to copy a <function>DtPrintSetupData</function> structure. An element in the target is updated only if different from the corresponding element in the source. For elements that point to allocated memory, <function>DtPrintCopySetupData</function> allocates new memory for those elements updated in target. Existing elements in target are freed.
All elements in a <function>DtPrintSetupData</function> structure can be freed by calling <function>DtPrintFreeSetupData</function>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtPrintFreeSetupData</function></term>
<listitem>
<para>Free the memory pointed to by <function>DtPrintSetupData</function> structure elements.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtPrintResetConnection</function></term>
<listitem>
<para><function>DtPrintResetConnection</function> is a convenience function provided by the
<function>DtPrintSetupBox</function> widget that allows applications to direct the
widget to stop managing the X print server connection. A mode
parameter is included in order to direct the widget to close the
print connection or simply to relinquish
control of the connection without closing it.
</para>
<para><function>DtPrintResetConnection</function> is intended to be used by
applications that fork a child process to perform
the print rendering operation. Immediately after the
fork is performed, the parent process closes its
X print server connection and retains its connection to
the video X server. The forked child, on the other hand,
closes its video X server connection and performs the
rendering operation on the X print server connection.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtPrintSetupProc</function></term>
<listitem>
<para><function>DtPrintSetupProc</function> is a type definition for
procedure resources of the <function>DtPrintSetupBox</function> widget.
</para>
</listitem>
</varlistentry>
<varlistentry><term><function>DtPrinterSelectionDialog</function></term>
<listitem>
<para>The <function>DtPrinterSelectionDialog</function> enables the user to select an
X printer from a complete list of printers for the client server (provided
the server supports the Xp extension), plus each server indicated by either the
<systemitem class="resource">XpServerList</systemitem> resource or the
<systemitem class="environvar">XPSERVERLIST</systemitem> environment variable. The user
typically selects one of the printers and chooses the "OK" button to return the selected printer to the caller.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="PG.print.div.3">
<title id="PG.print.mkr.3">Print Dialog Manager</title>
<indexterm><primary>printing</primary><secondary>print dialog manager</secondary></indexterm>
<indexterm><primary>Print Dialog Manager</primary></indexterm>
<para>A Print Dialog Manager (PDM) is a process separate from the
X Print Server and X Printing Application that provides
printer-specific and spooler-specific setup GUIs.
An application could choose to understand and display
such GUIs itself, but is advised to offload the task
to a PDM so that new printers and spoolers can be
supported by providing new PDMs, rather than requiring
changes to all applications.
</para>
<para>This section describes the CDEnext
implementation of a PDM that uses the PDM
Selection Protocol. The CDEnext implementation involves
a Print Dialog Manager Daemon (PDMD) executable
(<command>dtpdmd</command>) that is initially engaged by the protocol.
It then determines which PDM is needed and starts
it on behalf of the application. Within CDEnext, the
executable <command>dtpdm</command> is the general purpose PDM that the <command>dtpdmd</command> can start.
</para>
<para>Printer vendors can choose to introduce new GUIs by
one of the following techniques:
</para>
<itemizedlist>
<listitem>
<para>Developing their own PDM implementation that conforms to
the PDM Selection Protocol.
</para>
</listitem>
<listitem>
<para>Develop a PDM that can be started by the <command>dtpdmd</command>; this is the recommended technique.
</para>
</listitem>
<listitem>
<para>Possibly integrate new shared or dynamic libraries into the <command>dtpdmd</command>. This technique is vendor-dependent.
</para>
</listitem>
</itemizedlist>
<para>The <command>dtpdm</command> executable implements a reasonably
general-purpose print dialog manager capable of providing
dialogs suitable for a number of different printers, but is
specifically tuned to the needs of the two reference
printers, the PCL based HP DeskJet 1600C, and the
Postscript based Sun SPARCprinter 2. The <command>dtpdm</command> uses the
attributes of the particular printer
to provide a limited amount of automatic configuration of the options
displayed in its printer setup dialog. The <command>dtpdm</command>'s job setup dialog
is designed for use with the lp spooler.
</para>
<para>The <command>dtpdmd</command> executable implements a PDM startup mechanism.
This two-layer mechanism means that the PDM Selection Protocol,
PDM selection and startup, and security concerns can be dealt with
by the <command>dtpdmd</command>, and that resulting PDMs called by the <command>dtpdmd</command> are
left with the minimal and simple task of displaying GUIs.
</para>
<sect2 id="PG.print.div.4">
<title id="PG.print.mkr.4">Dt Print Dialog Manager Daemon &mdash; dtpdmd</title>
<indexterm><primary>printing</primary><secondary>dtprint dialog manager daemon</secondary></indexterm>
<indexterm><primary>dtpdmd</primary></indexterm>
<para>The <command>dtpdmd</command> is a long-lived daemon process that receives
client requests for a PDM, uses some lookup rules, and then
starts an appropriate PDM to service the request. When the
PDM finishes, control is returned to the <command>dtpdmd</command>, and the
<command>dtpdmd</command> in turn responds to the client with final status.
</para>
<para>The <command>dtpdmd</command> uses the
PDMD/PDM Protocol to communicate with the
PDM. Communication "to" the PDM is done via a
standardized command line. Communication "from"
the PDM is done via standardized exit codes.
</para>
</sect2>
<sect2 id="PG.print.div.5">
<title id="PG.print.mkr.5">Dt Print Dialog Manager</title>
<indexterm><primary>printing</primary><secondary>dtprint dialog manager</secondary></indexterm>
<indexterm><primary>dtpdm</primary></indexterm>
<para>The dialog manager is a process separate from the
print server. It provides the printer-specific GUIs
on behalf of a printing application
At an application's request, <command>dtpdm</command> posts to the
user's display a set of printer-specific dialogs enabling
the user to set printer specific and
job specific options. Though the setup dialog appears to be
part of the application, it is actually managed by the
<command>dtpdm</command> program on behalf of the application. It is capable of
providing dialogs in all locales for which there are applicable
message catalogs.
</para>
<para><command>dtpdm</command> presents a dialog containing an <function>XmNotebook</function>
widget. This notebook widget contains two tabs: one for the
Printer Setup Box and one for the Job Setup Box. Each of these
boxes provide controls that allow for configuration of various
printing options. The <command>dtpdm</command> dialog also contains three pushbuttons
labelled: "OK", "Cancel", and "Help". When the "OK" button is
activated, the dialog is dismissed and the newly configured
printing options are set in the current print context (via <function>XpSetAttributes</function>).
When the "Cancel" button is activated, the dialog is dismissed and no
changes are made to the print context.
</para>
</sect2>
</sect1>
<sect1 id="PG.print.div.6">
<title>Help for CDE Printing Widgets</title>
<indexterm><primary>printing</primary><secondary>integrating help</secondary></indexterm>
<para>The <function>DtPrintSetupBox</function> widget provides built-in support for its
sub-dialogs. That is, when the user clicks on the Help button in
one of these sub-dialogs, a help dialog is displayed containing the
relevant help text. The help volume and location IDs used for this purpose are
as follows:
</para>
<itemizedlist>
<listitem>
<para>Printer Info &mdash; HelpVolume = <literal>LibDtPrint</literal>, LocationId = <literal>PrinterInfo</literal>
</para>
</listitem>
<listitem>
<para>Printer Selection &mdash; HelpVolume = <literal>LibDtPrint</literal>, LocationId = <literal>SelectPrinter</literal>
</para>
</listitem>
<listitem>
<para>File Selection &mdash; HelpVolume = <literal>LibDtPrint</literal>, LocationId = <literal>SelectFile</literal>
</para>
</listitem>
</itemizedlist>
<para>For the main dialog, however, no help dialog is automatically displayed
when the user presses the Help button. However, the <function>DtPrintSetupBox</function>
does provides the hooks that enable the application writer to easily
supply help for both the generic and the application-specific portions.
These hooks include:
</para>
<itemizedlist>
<listitem>
<para>A "public" <function>DtPrintSetupBox</function> help volume with one or more location IDs
for the generic printing options.
</para>
</listitem>
<listitem>
<para>An activation callback installed on the <function>DtPrintSetupBox</function> Help
button that ensures that any <function>XmNhelpCallback</function>s installed on
the <function>DtPrintSetupBox</function> by the application are called.
</para>
</listitem>
</itemizedlist>
<para>In order to integrate help for the <function>DtPrintSetupBox</function> into an application,
you must:
</para>
<itemizedlist>
<listitem>
<para>Supply a help volume containing help for the relevant topics.
Note that if there are no application-specific printing options,
the public help volume supplied with the <function>DtPrintSetupBox</function> will
suffice. Otherwise, the authors of the application's help volume
will need to supply internal links to the <function>DtPrintSetupBox</function> volume.
For example, the help volume for a calendar manager might look
something like this:
</para>
<programlisting>
Calendar Print Setup Dialog Box
-------------------------------
<symbol role="variable">some graphic</symbol>
Report Type Choose to print Day View, Week View, Month View, or
Year View, plus Appointment List or To Do List.
From/To The dates for which you want to print
calendar data. With the From and To SpinBox,
you can select ...
See Also:
* Generic Print options <symbol role="variable">link1</symbol>
* To Print Your Appointment List <symbol role="variable">link2</symbol>
* To Print Your To Do List <symbol role="variable">link3</symbol>
</programlisting>
<para>where <symbol role="variable">link1</symbol> is a link to the "public" <function>DtPrintSetupBox</function> help volume.
</para>
</listitem>
<listitem>
<para>Define a set of location IDs to mark the locations in the
application's help volume pertaining to printing. It is up
the application to determine how "fine grained" to make the IDs
(for example, one for the entire print setup dialog, or one for every print
option in the print setup dialog, or some other organization).
The more "fine grained" the location IDs, the more specific
the help that is displayed when supporting a help system that
allows users to select the item for which they want help.
</para>
</listitem>
<listitem>
<para>Define a callback that is added to the <systemitem class="resource">XmNhelpCallback</systemitem> resource
of the <function>DtPrintSetupBox</function>. This callback would display a
<function>DtHelpDialogWidget</function> or <function>DtHelpQuickDialogWidget</function> setting the
<systemitem class="resource">DtNhelpVolume</systemitem> and <systemitem class="resource">DtNlocationId</systemitem> resources appropriately.
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>

1032
cde/doc/en_US.UTF-8/guides/progGuide/glossary.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/basdrdr.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/compcal.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invcopms.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invcopss.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invcopts.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invlnkms.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invlnkss.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invlnkts.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invmovms.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invmovss.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/invmovts.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/lstbxwid.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/mnbutwid.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/noprint.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/optdrdr.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/poscal.cdr Normal file
View File

Binary file not shown.

28
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/script3.txt Normal file
View File

@@ -0,0 +1,28 @@
cp ~/stage1/valmovts.cdr ./valmovts.cdr
cp ~/stage1/valmovss.cdr ./valmovss.cdr
cp ~/stage1/valmovms.cdr ./valmovms.cdr
cp ~/stage1/valcopts.cdr ./valcopts.cdr
cp ~/stage1/valcopss.cdr ./valcopss.cdr
cp ~/stage1/valcopms.cdr ./valcopms.cdr
cp ~/stage1/vallnkts.cdr ./vallnkts.cdr
cp ~/stage1/vallnkss.cdr ./vallnkss.cdr
cp ~/stage1/vallnkms.cdr ./vallnkms.cdr
cp ~/stage1/invmovts.cdr ./invmovts.cdr
cp ~/stage1/invmovss.cdr ./invmovss.cdr
cp ~/stage1/invmovms.cdr ./invmovms.cdr
cp ~/stage1/invcopts.cdr ./invcopts.cdr
cp ~/stage1/invcopss.cdr ./invcopss.cdr
cp ~/stage1/invcopms.cdr ./invcopms.cdr
cp ~/stage1/invlnkts.cdr ./invlnkts.cdr
cp ~/stage1/invlnkss.cdr ./invlnkss.cdr
cp ~/stage1/invlnkms.cdr ./invlnkms.cdr
cp ~/stage1/basdrdr.cdr ./basdrdr.cdr
cp ~/stage1/optdrdr.cdr ./optdrdr.cdr
cp ~/stage1/spnbxwid.cdr ./spnbxwid.cdr
cp ~/stage1/txtflwid.cdr ./txtflwid.cdr
cp ~/stage1/mnbutwid.cdr ./mnbutwid.cdr
cp ~/stage1/lstbxwid.cdr ./lstbxwid.cdr
cp ~/stage1/poscal.cdr ./poscal.cdr
cp ~/stage1/compcal.cdr ./compcal.cdr
cp ~/stage1/noprint.cdr ./noprint.cdr

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/spnbxwid.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/txtflwid.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/valcopms.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/valcopss.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/valcopts.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/vallnkms.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/vallnkss.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/vallnkts.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/valmovms.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/valmovss.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/CDR/valmovts.cdr Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/ComboBo3.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/ComboBox.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/MenuBut2.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/NoPrint.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/approot.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/basdrdr.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/compcal.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invcopms.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invcopss.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invcopts.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invlnkms.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invlnkss.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invlnkts.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invmovms.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invmovss.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/invmovts.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/lstbxwid.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/mnbutwid.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/noprint.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/optdrdr.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/package.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/poscal.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/spnbxwid.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/txtflwid.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/valcopms.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/valcopss.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/valcopts.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/vallnkms.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/vallnkss.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/vallnkts.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/valmovms.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/valmovss.cgm Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/progGuide/graphics/valmovts.cgm Normal file
View File

Binary file not shown.

23
cde/doc/en_US.UTF-8/guides/progGuide/part1.sgm Normal file
View File

@@ -0,0 +1,23 @@
<!-- $XConsortium: part1.sgm /main/3 1996/09/08 19:38: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. -->
<Title Id="PG.prtI.mkr.1">Basic Integration</Title>
<PartIntro>
<Para>Chapter 1 describes some basic integration and printing features.</Para>
<InformalTable Id="PG.prtI.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Basic Application Integration3'--><XRef Role="JumpText" Linkend="PG.basc1.mkr.1"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
</PartIntro>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

50
cde/doc/en_US.UTF-8/guides/progGuide/part2.sgm Normal file
View File

@@ -0,0 +1,50 @@
<!-- $XConsortium: part2.sgm /main/5 1996/09/08 19:38:17 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. -->
<Title Id="PG.prt2.mkr.1">Recommended Integration</Title>
<PartIntro>
<Para>Chapters 2 through 5 describe how to perform the following recommended
integration tasks:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Use standard font aliases so that your application uses the closest matching
font on any desktop-compliant system.</Para>
</ListItem>
<ListItem>
<Para>Display and log messages from your application.</Para>
</ListItem>
<ListItem>
<Para>Integrate with the Session Manager to preserve the state of the application
at logout.</Para>
</ListItem>
<ListItem>
<Para>Implement drag and drop in your application as a direct-manipulation
accelerato<Emphasis>r for existing functionality.</Emphasis></Para>
<InformalTable Id="PG.prt2.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Integrating Fonts17'--><XRef Role="JumpText" Linkend="PG.fonts.mkr.1"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Displaying Errors from Your Application25'--><XRef Role="JumpText" Linkend="PG.msgs.mkr.1"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Integrating with Session Manager29'--><XRef Role="JumpText" Linkend="PG.smgr.mkr.1"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Integrating with Drag and Drop33'--><XRef Role="JumpText" Linkend="PG.dndPG.mkr.1"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
</ListItem>
</ItemizedList>
</PartIntro>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

60
cde/doc/en_US.UTF-8/guides/progGuide/part3.sgm Normal file
View File

@@ -0,0 +1,60 @@
<!-- $XConsortium: part3.sgm /main/5 1996/09/08 19:38:24 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. -->
<Title Id="PG.prt3.mkr.1">Optional Integration</Title>
<PartIntro>
<Para>Chapters 6 through 12 describe how to perform the following optional
integration tasks:</Para>
<ItemizedList Remap="Bullet1">
<ListItem>
<Para>Integrate with the Workspace Manager to enable your application to
determine the workspace location of each session at session start time</Para>
</ListItem>
<ListItem>
<Para>Use the CDE custom widgets</Para>
</ListItem>
<ListItem>
<Para>Invoke actions from within an application</Para>
</ListItem>
<ListItem>
<Para>Access the data-typing database</Para>
</ListItem>
<ListItem>
<Para>Access the Calendar API</Para>
</ListItem>
<ListItem>
<Para>Access the Information Manager API</Para>
</ListItem>
<ListItem>
<Para>Access the printing widgets and API</Para>
<InformalTable Id="PG.prt3.itbl.1" Frame="All">
<TGroup Cols="1">
<ColSpec Colname="1" Colwidth="4.0 in">
<TBody>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Integrating with the Workspace Manager63'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.1"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Common Desktop Environment Motif Widgets69'--><XRef Role="JumpText" Linkend="PG.widgs.mkr.1"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Invoking Actions from Applications109'--><XRef Role="JumpText" Linkend="PG.aIII.mkr.1"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Accessing the Data-Typing Database123'--><XRef Role="JumpText" Linkend="PG.datat.mkr.1"></Para></Entry>
</Row>
<Row Rowsep="1">
<Entry><Para><!--Original XRef content: 'Integrating with Calendar139'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.1"></Para></Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
</ListItem>
</ItemizedList>
</PartIntro>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->

374
cde/doc/en_US.UTF-8/guides/progGuide/preface.sgm Normal file
View File

@@ -0,0 +1,374 @@
<!-- Fragment document type declaration subset:
ArborText, Inc., 1988-1995, v.4001
<!DOCTYPE DOCBOOK [
<!ENTITY PG.BIntg.fig.1 SYSTEM "./progGuide/graphics/NoPrint.eps" NDATA eps>
<!ENTITY PG.BIntg.fig.2 SYSTEM "./progGuide/graphics/package.eps" NDATA eps>
<!ENTITY PG.BIntg.fig.3 SYSTEM "./progGuide/graphics/approot.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.1 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.1.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.2 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.2.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.3 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.3.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.4 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.4.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.5 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.5.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.6 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.6.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.7 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.7.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.8 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.8.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.9 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.9.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.10 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.10.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.11 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.11.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.12 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.12.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.13 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.13.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.14 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.14.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.15 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.15.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.16 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.16.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.17 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.17.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.18 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.18.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.19 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.19.eps" NDATA eps>
<!ENTITY PG.dndPG.fig.20 SYSTEM "./progGuide/graphics/PG.dndPG.iFrame.20.eps" NDATA eps>
<!ENTITY PG.widgs.fig.1 SYSTEM "./progGuide/graphics/PG.widgs.iFrame.1.eps" NDATA eps>
<!ENTITY PG.widgs.fig.2 SYSTEM "./progGuide/graphics/ComboBox.rs" NDATA eps>
<!ENTITY PG.widgs.fig.3 SYSTEM "./progGuide/graphics/MenuButton2.rs" NDATA eps>
<!ENTITY PG.calmg.fig.1 SYSTEM "./progGuide/graphics/PG.calmg.iFrame.1.eps" NDATA eps>
<!ENTITY PG.calmg.fig.2 SYSTEM "./progGuide/graphics/PG.calmg.iFrame.2.eps" NDATA eps>
<!ENTITY PG.basc1.fig.1 SYSTEM "./progGuide/graphics/NoPrint.eps" NDATA eps>
<!ENTITY PG.basic.fig.1 SYSTEM "./progGuide/graphics/NoPrint.eps" NDATA eps>
<!ENTITY PG.basic.fig.2 SYSTEM "./progGuide/graphics/package.eps" NDATA eps>
<!ENTITY PG.basic.fig.3 SYSTEM "./progGuide/graphics/approot.eps" NDATA eps>
<!ENTITY Copyr SYSTEM "./progGuide/copyright.sgm">
<!ENTITY prtI SYSTEM "./progGuide/part1.sgm">
<!ENTITY basc1 SYSTEM "./progGuide/ch01.sgm">
<!ENTITY prt2 SYSTEM "./progGuide/part2.sgm">
<!ENTITY fonts SYSTEM "./progGuide/ch02.sgm">
<!ENTITY msgs SYSTEM "./progGuide/ch03.sgm">
<!ENTITY smgr SYSTEM "./progGuide/ch04.sgm">
<!ENTITY dndPG SYSTEM "./progGuide/ch05.sgm">
<!ENTITY prt3 SYSTEM "./progGuide/part3.sgm">
<!ENTITY wsmgr SYSTEM "./progGuide/ch06.sgm">
<!ENTITY widgs SYSTEM "./progGuide/ch07.sgm">
<!ENTITY aIII SYSTEM "./progGuide/ch08.sgm">
<!ENTITY datat SYSTEM "./progGuide/ch09.sgm">
<!ENTITY calmg SYSTEM "./progGuide/ch10.sgm">
<!ENTITY gloss SYSTEM "./progGuide/glossary.sgm">
]>
-->
<!-- $XConsortium: preface.sgm /main/9 1996/09/08 19:38: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. -->
<preface id="PG.Pref.div.1">
<title>Preface</title>
<sect1 id="PG.Pref.div.2">
<title>Who Should Use This Book</title>
<para>Use this book if you are a programmer interested in integrating an existing
application into the Common Desktop Environment (CDE), or in developing a
new application that uses the features and functionality of CDE. This book
describes the CDE development environment, and assumes that you are familiar
with Motif&reg;, X, UNIX&reg;, or C programming.</para>
</sect1>
<sect1 id="PG.Pref.div.3">
<title>Before You Read This Book</title>
<para>The Common Desktop Environment: <emphasis>Programmer's Guide</emphasis>
is a collection of programming information. The manuals listed in the section
<!--Original XRef content: '&xd2;Related Books'--><xref role="SectionTitle"
linkend="PG.Pref.mkr.1"> should be read before you begin integration
of any applications to CDE.</para>
<para>The <emphasis>Common Desktop Environment: Programmer's Overview</emphasis>
provides a description of CDE and introduces the programming environment.
</para>
</sect1>
<sect1 id="PG.Pref.div.4">
<title>How This Book Is Organized</title>
<para>The <emphasis>Common Desktop Environment: Programmer's Guide</emphasis>
has two parts. Each part provides a detailed description of each element
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><emphasis role="Lead-in">Part 1 &ndash;</emphasis> <!--Original XRef
content: '&xd2;Basic Integration'--><xref role="SectionTitleLead-in" linkend="PG.prtI.mkr.1"> introduces how to register your application
and printing levels.</para>
<para><!--Original XRef content: 'Chapter&numsp;1, &xd2;Basic Application
Integration'--><xref role="ChapNumAndTitleLead-in" linkend="PG.basc1.mkr.1">
describes the steps involved with the
basic integration of an existing application into CDE.</para>
<para><emphasis role="Lead-in">Part 2 &ndash;</emphasis> <!--Original XRef
content: '&xd2;Recommended Integration'--><xref role="SectionTitleLead-in"
linkend="PG.prt2.mkr.1"> introduces
how to integrate existing applications into the Common Desktop Environment.
</para>
<para><!--Original XRef content: 'Chapter&numsp;2, &xd2;Integrating Fonts'--><xref
role="ChapNumAndTitleLead-in" linkend="PG.fonts.mkr.1"> describes how to use generic standard font descriptions
to ensure that you get the closest matching font for your application on
any CDE-compliant system.</para>
<para><!--Original XRef content: 'Chapter&numsp;3, &xd2;Displaying Errors
from Your Application'--><xref role="ChapNumAndTitleLead-in" linkend="PG.msgs.mkr.1"> describes a common model for presenting
information and error messages.</para>
<para><!--Original XRef content: 'Chapter&numsp;4, &xd2;Integrating with Session
Manager'--><xref role="ChapNumAndTitleLead-in" linkend="PG.smgr.mkr.1">
describes the ICCM session management
protocol and provides examples of how to integrate your application with
Session Manager.</para>
<para><!--Original XRef content: 'Chapter&numsp;5, &xd2;Integrating with Drag
and Drop'--><xref role="ChapNumAndTitleLead-in" linkend="PG.dndPG.mkr.1">
describes the drag-and-drop user model,
the new drag-and-drop application program interface (API), and how to use
drag and drop.</para>
<para><emphasis role="Lead-in">Part3 &ndash;</emphasis> <!--Original XRef
content: '&xd2;Optional Integration'--><xref role="SectionTitleLead-in" linkend="PG.prt3.mkr.1"> describes how to integrate new applications
with the Session Manager and with drag and drop. It also explains how locales
affect the Login Manager, Window Manager, and the terminal emulator.</para>
<para><!--Original XRef content: 'Chapter&numsp;6, &xd2;Integrating with the
Workspace Manager'--><xref role="ChapNumAndTitleLead-in" linkend="PG.wsmgr.mkr.1"> describes how to integrate your application
with the Workspace Manager in specialized ways.</para>
<para><!--Original XRef content: 'Chapter&numsp;7, &xd2;Common Desktop Environment
Motif Widgets'--><xref role="ChapNumAndTitleLead-in" linkend="PG.widgs.mkr.1">
describes how to use the custom widgets
that are provided as part of CDE.</para>
<para><!--Original XRef content: 'Chapter&numsp;8, &xd2;Invoking Actions from
Applications'--><xref role="ChapNumAndTitleLead-in" linkend="PG.aIII.mkr.1">
describes how to create actions within
your application.</para>
<para><!--Original XRef content: 'Chapter&numsp;9, &xd2;Accessing the Data-Typing
Database'--><xref role="ChapNumAndTitleLead-in" linkend="PG.datat.mkr.1">
describes the data-typing functions and
how to use the data-typing database.</para>
<para><!--Original XRef content: 'Chapter&numsp;10, &xd2;Integrating with
Calendar'--><xref role="ChapNumAndTitleLead-in" linkend="PG.calmg.mkr.1">
introduces the Calendar API, including
functions, data structures, calendar attributes, and entry attributes. It
also describes how to use the Calendar API.</para>
<para>Chapter 11 explains how to integrate
your application with the <command>dtinfo</command> on-line documentation browser; this chapter
also summarizes the DtInfo database engine API, which you may use to write
your own browser.
</para>
<para>Chapter 12 explains the CDE printing widgets and APIs.
</para>
<para><emphasis role="Lead-in">Glossary</emphasis> is a list of words and
phrases found in this book and their definitions.</para>
</sect1>
<sect1 id="PG.Pref.div.5">
<title id="PG.Pref.mkr.1">Related Books</title>
<para>Before beginning integration of your application into CDE, you should
become familiar with the other books in the documentation set. See <!--Original
XRef content: '&xd2;Development
Environment Documentation'--><xref role="SectionTitle" linkend="PG.Pref.mkr.2">
for a list of the companion books.</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>
<para>For more information about the Calendaring and Scheduling API, contact
the X.400 API Association for the latest copy of the <emphasis>XAPIA Specification</emphasis>. The address is X.400 API Association, 800 El Camino Real, Mountain
View, California, 94043.</para>
<sect2 id="PG.Pref.div.6">
<title id="PG.Pref.mkr.2">Development Environment Documentation</title>
<para>This section provides an overview of each manual&mdash;except for the <emphasis>Programmer's Guide</emphasis>&mdash;in the developer documentation set. In
addition to the <emphasis>Programmer's Guide</emphasis>, the development
environment documentation set consists of:<indexterm><primary>documentation
set</primary><secondary>development environment</secondary></indexterm></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
Overview</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 Korn
Shell User's Guide</emphasis></para>
</listitem><listitem><para><emphasis>Common Desktop Environment</emphasis>:
Glossary</para>
</listitem><listitem><para>Online man pages</para>
</listitem></itemizedlist>
<sect3 id="PG.Pref.div.7">
<title>Common Desktop Environment: Programmer's Overview</title>
<para>The <emphasis>Common Desktop Environment: Programmer's Overview</emphasis>
has two parts. Part 1 contains an architectural overview of the Common Desktop
Environment, including high-level information on both the run-time and development
environments. Part 2 contains information useful to know before developing
an application, and describes the development environment components.</para>
<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>
</sect3>
<sect3 id="PG.Pref.div.8">
<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 Version 1.2 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 represented using a virtual button mechanism to specify behavior independent
of 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>
</sect3>
<sect3 id="PG.Pref.div.9">
<title>Common Desktop Environment: Application Builder User's Guide</title>
<para>The Common Desktop Environment Application Builder (also called <emphasis>App Builder</emphasis>) is an interactive tool for developing Common Desktop
Environment applications. AppBuilder 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, and 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. The guide also explains
how to make connections between objects in the interface, use the application
framework editor to easily integrate desktop services, generate C code, and
add application code to the App Builder output to produce a finished application.
</para>
</sect3>
<sect3 id="PG.Pref.div.10">
<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 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. Part1 describes the collaborative role that
authors and developers undertake to design application help. Part 2 provides
information for authors organizing and writing online help. Part 3 describes
the Help System application programmer's toolkit. Part 4 contains information
for both authors and programmers about preparing online help for different
language environments.</para>
</sect3>
<sect3 id="PG.Pref.div.11">
<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&reg;
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>.</para>
</sect3>
<sect3 id="PG.Pref.div.12">
<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 references 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>
</sect3>
<sect3 id="PG.Pref.div.13">
<title>Common Desktop Environment: Desktop Korn Shell User's Guide</title>
<para>The <emphasis>Common Desktop Environment: Desktop Korn Shell User's
Guide</emphasis> describes how to create Motif applications with Desktop
Korn Shell (<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 Korn
Shell programming, Motif, the Xt Intrinsics, and, to a lesser extent, Xlib.
</para>
</sect3>
<sect3 id="PG.Pref.div.14">
<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>
</sect3>
</sect2>
</sect1>
<sect1 id="PG.Pref.div.15">
<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="PG.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 09:54:57-->
<?Pub *0000023383>