cde/doc/C/guides/sysAdminGuide/ch04.sgm

   1 <!-- $XConsortium: ch04.sgm /main/11 1996/09/08 19:32:44 rws $ -->
   2 <!-- (c) Copyright 1995 Digital Equipment Corporation. -->
   3 <!-- (c) Copyright 1995 Hewlett-Packard Company. -->
   4 <!-- (c) Copyright 1995 International Business Machines Corp. -->
   5 <!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
   6 <!-- (c) Copyright 1995 Novell, Inc. -->
   7 <!-- (c) Copyright 1995 FUJITSU LIMITED. -->
   8 <!-- (c) Copyright 1995 Hitachi. -->
   9 <Chapter Id="SAG.RegAp.div.1">
  10 <Title Id="SAG.RegAp.mkr.1">Registering an Application</Title>
  11 <Para><IndexTerm>
  12 <Primary>&lt;$nopage>application registration, See registration</Primary>
  13 </IndexTerm>This chapter describes how to create a registration package for an application
  14 and how to register the application onto the desktop.</Para>
  15 <InformalTable Id="SAG.RegAp.itbl.1" Frame="All">
  16 <TGroup Cols="1">
  17 <ColSpec Colname="1" Colwidth="4.125 in">
  18 <TBody>
  19 <Row Rowsep="1">
  20 <Entry><Para><!--Original XRef content: 'Overview of Application Registration54'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.2"></Para></Entry>
  21 </Row>
  22 <Row Rowsep="1">
  23 <Entry><Para><!--Original XRef content: 'General Steps for Registering an Application57'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.5"></Para></Entry>
  24 </Row>
  25 <Row Rowsep="1">
  26 <Entry><Para><!--Original XRef content: 'Step 1: Modifying Font and Color Resources58'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.6"></Para></Entry>
  27 </Row>
  28 <Row Rowsep="1">
  29 <Entry><Para><!--Original XRef content: 'Step 2: Creating the Desktop Application Root60'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.9"></Para></Entry>
  30 </Row>
  31 <Row Rowsep="1">
  32 <Entry><Para><!--Original XRef content: 'Step 3: Creating the Registration Package Directories60'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.10"></Para></Entry>
  33 </Row>
  34 <Row Rowsep="1">
  35 <Entry><Para><!--Original XRef content: 'Step 4: Creating the Actions and Data Types for the Application62'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.13"></Para></Entry>
  36 </Row>
  37 <Row Rowsep="1">
  38 <Entry><Para><!--Original XRef content: 'Step 5: Putting the Help Files in the Registration Package66'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.19"></Para></Entry>
  39 </Row>
  40 <Row Rowsep="1">
  41 <Entry><Para><!--Original XRef content: 'Step 6: Putting Information Libraries in the Registration Package'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.19a"></Para></Entry>
  42 </Row>
  43 <Row Rowsep="1">
  44 <Entry><Para><!--Original XRef content: 'Step 7: Creating Icons for the Application67'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.20"></Para></Entry>
  45 </Row>
  46 <Row Rowsep="1">
  47 <Entry><Para><!--Original XRef content: 'Step 8: Creating the Application Group68'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.22"></Para></Entry>
  48 </Row>
  49 <Row Rowsep="1">
  50 <Entry><Para><!--Original XRef content: 'Step 9: Registering the Application Using dtappintegrate75'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.30"></Para></Entry>
  51 </Row>
  52 <Row Rowsep="1">
  53 <Entry><Para><!--Original XRef content: 'Example of Creating a Registration Package77'--><XRef Role="JumpText" Linkend="SAG.RegAp.div.38"></Para></Entry>
  54 </Row>
  55 </TBody>
  56 </TGroup>
  57 </InformalTable>
  58 <Para Id="SAG.RegAp.mkr.2">When an application is fully registered onto the desktop, it has:</Para>
  59 <ItemizedList Remap="Bullet1">
  60 <ListItem>
  61 <Para>Its own application group at the top level of the Application Manager</Para>
  62 </ListItem>
  63 <ListItem>
  64 <Para>An action that starts the application. The action is represented by an icon in
  65 the application group</Para>
  66 </ListItem>
  67 <ListItem>
  68 <Para>Optionally, data types for its data files</Para>
  69 </ListItem>
  70 </ItemizedList>
  71 <Para>Application registration is a non-invasive operation to the application:</Para>
  72 <ItemizedList Remap="Bullet1">
  73 <ListItem>
  74 <Para>It does not involve modification of the application executable itself.
  75 Therefore, you can register existing applications on a system.</Para>
  76 </ListItem>
  77 <ListItem>
  78 <Para>It does not require that any of the application's delivered files (such as the
  79 executable and <Filename>app-defaults</Filename>) be moved to other file locations.</Para>
  80 </ListItem>
  81 <ListItem>
  82 <Para>It can be undone easily. The <Command>dtappintegrate</Command> tool, which is used to
  83 register applications, provides a command-line option for reversing the
  84 process.</Para>
  85 </ListItem>
  86 </ItemizedList>
  87 <Para>You will want to create a registration package if you are:</Para>
  88 <ItemizedList Remap="Bullet1">
  89 <ListItem>
  90 <Para>A system administrator who wants to register an existing application onto
  91 the desktop</Para>
  92 </ListItem>
  93 <ListItem>
  94 <Para>A software programmer who wants to create an installation package for a
  95 desktop-smart application</Para>
  96 </ListItem>
  97 </ItemizedList>
  98 <Sect1 Id="SAG.RegAp.div.2">
  99 <Title Id="SAG.RegAp.mkr.3">Overview of Application Registration<IndexTerm><Primary>applications</Primary><Secondary>registering, See registration</Secondary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>overview</Secondary></IndexTerm></Title>
 100 <Para>This section explains:</Para>
 101 <ItemizedList Remap="Bullet1">
 102 <ListItem>
 103 <Para>The purpose of application registration</Para>
 104 </ListItem>
 105 <ListItem>
 106 <Para>Features provided to your application by application registration</Para>
 107 </ListItem>
 108 </ItemizedList>
 109 <Note>
 110 <Para>For a detailed example that shows how to register an existing
 111 application, see
 112 <!--Original XRef content: '&xd2;Example of Creating a Registration Package&xd3; on page&numsp;77'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.38">.</Para>
 113 </Note>
 114 <Sect2 Id="SAG.RegAp.div.3">
 115 <Title>Features Provided by Application Registration<IndexTerm><Primary>applications</Primary><Secondary>features of registration</Secondary></IndexTerm><IndexTerm><Primary>registration package</Primary><Secondary>purpose of</Secondary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>features provided by</Secondary></IndexTerm></Title>
 116 <Para><IndexTerm>
 117 <Primary>Application Manager</Primary>
 118 <Secondary>integrating applications with</Secondary>
 119 </IndexTerm>Application registration provides a graphical way for users to:</Para>
 120 <ItemizedList Remap="Bullet1">
 121 <ListItem>
 122 <Para>Locate your application.</Para>
 123 <Para>Upon installation, your application is &ldquo;registered&rdquo; into the Application
 124 Manager and has its own application group.</Para>
 125 </ListItem>
 126 </ItemizedList>
 127 <Figure>
 128 <Title Id="SAG.RegAp.mkr.4">Application groups at the top level of Application Manager</Title>
 129 <Graphic Entityref="SAG.RegAp.fig.1" Id="SAG.RegAp.grph.1"></Graphic>
 130 </Figure>
 131 <ItemizedList Remap="Bullet1">
 132 <ListItem>
 133 <Para>Start your application.</Para>
 134 <Para>The application group for your application contains an icon the user can
 135 double-click to start your application.</Para>
 136 </ListItem>
 137 </ItemizedList>
 138 <Figure>
 139 <Title>An application group containing an icon to start the application</Title>
 140 <Graphic Entityref="SAG.RegAp.fig.2" Id="SAG.RegAp.grph.2"></Graphic>
 141 </Figure>
 142 <ItemizedList Remap="Bullet1">
 143 <ListItem>
 144 <Para><IndexTerm>
 145 <Primary>applications</Primary>
 146 <Secondary>purpose for data types</Secondary>
 147 </IndexTerm><IndexTerm>
 148 <Primary>data types</Primary>
 149 <Secondary>purpose for creating</Secondary>
 150 </IndexTerm>Identify and manipulate data files. The application's data files will have a
 151 unique icon in File Manager.</Para>
 152 <Para>The user can use data file icons to:</Para>
 153 <ItemizedList Remap="Bullet2">
 154 <ListItem>
 155 <Para>Start (Open) the application</Para>
 156 </ListItem>
 157 <ListItem>
 158 <Para>Print data files</Para>
 159 </ListItem>
 160 </ItemizedList>
 161 </ListItem>
 162 </ItemizedList>
 163 <Figure>
 164 <Title>A data file's pop-up menu containing ``Open'' and ``Print''</Title>
 165 <Graphic Entityref="SAG.RegAp.fig.3" Id="SAG.RegAp.grph.3"></Graphic>
 166 </Figure>
 167 <ItemizedList Remap="Bullet1">
 168 <ListItem>
 169 <Para>Perform other operations, such as mailing, compressing, viewing, or playing
 170 (audio) data</Para>
 171 </ListItem>
 172 </ItemizedList>
 173 </Sect2>
 174 <Sect2 Id="SAG.RegAp.div.4">
 175 <Title>The Purpose of Application Registration<IndexTerm><Primary>registration</Primary><Secondary>purpose of</Secondary></IndexTerm></Title>
 176 <Para><IndexTerm>
 177 <Primary>configuration files</Primary>
 178 <Secondary>in registration package</Secondary>
 179 </IndexTerm>A registered desktop application has certain configuration files used by the
 180 desktop to provide the application's user interface:</Para>
 181 <ItemizedList Remap="Bullet1">
 182 <ListItem>
 183 <Para>Action and data type definition files</Para>
 184 </ListItem>
 185 <ListItem>
 186 <Para>Icon image (pixmap or bitmap) files</Para>
 187 </ListItem>
 188 <ListItem>
 189 <Para>A directory and files that create the application group</Para>
 190 </ListItem>
 191 <ListItem>
 192 <Para>Optionally, online documentation files, desktop help files,
 193 and Front Panel definition files</Para>
 194 </ListItem>
 195 </ItemizedList>
 196 <Para>In order for these files to be recognized and used by the desktop, they must be
 197 in certain directories specified by the desktop's search paths.</Para>
 198 <Para>It can be difficult to administer an application when its configuration files are
 199 scattered among numerous directories. Therefore, the desktop allows an
 200 application to keep all its desktop configuration files gathered under a single
 201 directory. This grouping of files is called a<IndexTerm>
 202 <Primary>registration package</Primary>
 203 <Secondary>definition</Secondary>
 204 </IndexTerm>
 205 <Symbol Role="Variable">registration package</Symbol>.</Para>
 206 <Para>If the application is desktop smart, it supplies a registration package as part of
 207 its installation package. If you are a system administrator creating the
 208 configuration files yourself, you can create the registration package yourself.</Para>
 209 <Para>The configuration files in the registration package are not available to the
 210 desktop because they are not located in the proper search path directories. The
 211 process of placing these files in the proper locations is called<IndexTerm>
 212 <Primary>registration</Primary>
 213 <Secondary>definition</Secondary>
 214 </IndexTerm>
 215 <Symbol Role="Variable">registering</Symbol>, or
 216 <Symbol Role="Variable">integrating</Symbol>, the application.</Para>
 217 <Para>The desktop provides a tool, <Command>dtappintegrate</Command>, that performs the registration
 218 by creating symbolically linked representations of the files in the proper search
 219 path directories.</Para>
 220 <Para>Many desktop-smart applications will automatically run <Command>dtappintegrate</Command>
 221 during the installation process. If you are a system administrator integrating an
 222 existing application, you can run it yourself after you've created the
 223 registration package.</Para>
 224 <Para>Once an application is registered on a system's desktop, the application is
 225 available to all users on the system. If the system is configured as a desktop<IndexTerm>
 226 <Primary>application servers</Primary>
 227 <Secondary>availability of applications</Secondary>
 228 </IndexTerm>
 229 application server, the application will also be available to other systems
 230 throughout the network.</Para>
 231 <Para>The <Command>dtappintegrate</Command> tool has a command-line option that reverses the
 232 process by breaking the links. This makes it easy to remove the application
 233 from the Application Manager so that it can be moved to a different
 234 application server or updated.</Para>
 235 </Sect2>
 236 </Sect1>
 237 <Sect1 Id="SAG.RegAp.div.5">
 238 <Title Id="SAG.RegAp.mkr.5">General Steps for Registering an Application<IndexTerm><Primary>registration</Primary><Secondary>general steps</Secondary></IndexTerm></Title>
 239 <Note>
 240 <Para>For a detailed example that uses these steps to create an application
 241 package, see
 242 <!--Original XRef content: '&xd2;Example of Creating a Registration Package&xd3; on page&numsp;77'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.38">.</Para>
 243 </Note>
 244 <OrderedList>
 245 <ListItem>
 246 <Para Id="SAG.RegAp.mkr.6">Modify any application resources that set fonts and colors. Otherwise, the
 247 desktop's dynamic fonts and colors will not work properly.</Para>
 248 <Para>See
 249 <!--Original XRef content: '&xd2;Step 1: Modifying Font and Color Resources&xd3; on page&numsp;58'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.6">.</Para>
 250 </ListItem>
 251 <ListItem>
 252 <Para Id="SAG.RegAp.mkr.7">Create an application root location.</Para>
 253 <Para>See
 254 <!--Original XRef content: '&xd2;Step 2: Creating the Desktop Application Root&xd3; on page&numsp;60'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.9">.</Para>
 255 </ListItem>
 256 <ListItem>
 257 <Para Id="SAG.RegAp.mkr.8">Create the directory structure underneath the application root.</Para>
 258 <Para>See
 259 <!--Original XRef content: '&xd2;Step 3: Creating the Registration Package Directories&xd3; on page&numsp;60'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.10"></Para>
 260 </ListItem>
 261 <ListItem>
 262 <Para Id="SAG.RegAp.mkr.9">Create the actions and data types for the application.</Para>
 263 <Para>See
 264 <!--Original XRef content: '&xd2;Step 4: Creating the Actions and Data Types for the Application&xd3; on
 265 page&numsp;62'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.13">.</Para>
 266 </ListItem>
 267 <ListItem>
 268 <Para Id="SAG.RegAp.mkr.10">Put the help files in an appropriate directory.</Para>
 269 <Para>See
 270 <!--Original XRef content: '&xd2;Step 5: Putting the Help Files in the Registration Package&xd3; on page&numsp;66'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.19">.</Para>
 271 </ListItem>
 272 <ListItem>
 273 <Para Id="SAG.RegAp.mkr.10a">Put the online documentation (infolib)
 274 files in the appropriate directory.</Para>
 275 <Para>See
 276 <!--Original XRef content: '&xd2;Step 6: Putting the Infolib Files in the
 277 Registration Package&xd3; on page&numsp;66'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.19a">.</Para>
 278 </ListItem>
 279 <ListItem>
 280 <Para Id="SAG.RegAp.mkr.11">Create the icons for the application</Para>
 281 <Para>See
 282 <!--Original XRef content: '&xd2;Step 7: Creating Icons for the Application&xd3; on page&numsp;67'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.20">.</Para>
 283 </ListItem>
 284 <ListItem>
 285 <Para Id="SAG.RegAp.mkr.12">Create the application group for the application.</Para>
 286 <Para>See
 287 <!--Original XRef content: '&xd2;Step 8: Creating the Application Group&xd3; on page&numsp;68'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.22">.</Para>
 288 </ListItem>
 289 <ListItem>
 290 <Para Id="SAG.RegAp.mkr.13">Register the application using <Command>dtappintegrate</Command>.</Para>
 291 <Para>See
 292 <!--Original XRef content: '&xd2;Step 9: Registering the Application Using dtappintegrate&xd3; on page&numsp;75'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.30">.</Para>
 293 </ListItem>
 294 </OrderedList>
 295 </Sect1>
 296 <Sect1 Id="SAG.RegAp.div.6">
 297 <Title Id="SAG.RegAp.mkr.14">Step 1: Modifying Font and Color Resources<IndexTerm><Primary>registration</Primary><Secondary>resource modification</Secondary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>modifying resources</Secondary></IndexTerm></Title>
 298 <Note>
 299 <Para>For an example of modifying resources for an application, see
 300 <!--Original XRef content: 'Step&numsp;1'--><XRef Role="Step" Linkend="SAG.RegAp.mkr.6"> of
 301 the
 302 <!--Original XRef content: '&xd2;Example of Creating a Registration Package'--><XRef Role="SectionTitle" Linkend="SAG.RegAp.div.38"> on
 303 <!--Original XRef content: 'page&numsp;78'--><XRef Role="PageNum" Linkend="SAG.RegAp.mkr.16">.</Para>
 304 </Note>
 305 <Para>The desktop provides mechanisms for setting and manipulating interface fonts
 306 and window colors. In order for an application to use these mechanisms
 307 properly, you may have to modify the application's <Filename>app-defaults</Filename> file.</Para>
 308 <Sect2 Id="SAG.RegAp.div.7">
 309 <Title>Modifying Font Resources<IndexTerm><Primary>Style Manager</Primary><Secondary>font integration with</Secondary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>font modifications</Secondary></IndexTerm><IndexTerm><Primary>fonts</Primary><Secondary>resources, modifying for registration</Secondary></IndexTerm></Title>
 310 <Note>
 311 <Para>This section applies to applications created using Motif 1.2&trade; (or
 312 later versions). Style Manager cannot set interface fonts for applications
 313 written using earlier versions of Motif.</Para>
 314 </Note>
 315 <Para>The desktop Style Manager will set interface fonts for applications created
 316 using Motif 1.2 (or later versions) if the application does not specify
 317 application-specific interface fonts.</Para>
 318 <Para>Style Manager provides two fonts:</Para>
 319 <InformalTable>
 320 <TGroup Cols="2" colsep="0" rowsep="0">
 321 <colspec colwidth="95*">
 322 <colspec colwidth="433*">
 323 <TBody>
 324 <Row>
 325 <Entry><Para>system font</Para></Entry>
 326 <Entry><Para>Used by system areas such as labels, menus, and buttons</Para></Entry>
 327 </Row>
 328 <Row>
 329 <Entry><Para>user font</Para></Entry>
 330 <Entry><Para>Used for editable areas such as text fields</Para></Entry>
 331 </Row>
 332 </TBody>
 333 </TGroup>
 334 </InformalTable>
 335 <Para>Each font is provided in seven sizes, labeled 1 through 7 in the Fonts dialog
 336 box. The Style Manager fonts are connected to actual fonts on the system
 337 through Style Manager resources set in
 338 <Filename>/usr/dt/app-defaults/</Filename><Symbol Role="Variable">language</Symbol><Filename>/Dtstyle</Filename>.</Para>
 339 <Para>If you want the application to use the Style Manager fonts, you should remove
 340 any application resources that specify fonts. The desktop will
 341 automatically set the application's resources appropriately:</Para>
 342 <InformalTable>
 343 <TGroup Cols="2" colsep="0" rowsep="0">
 344 <colspec colwidth="207*">
 345 <colspec colwidth="321*">
 346 <TBody>
 347 <Row>
 348 <Entry><Para><Command>FontList</Command></Para></Entry>
 349 <Entry><Para>Set to system font</Para></Entry>
 350 </Row>
 351 <Row>
 352 <Entry><Para><Filename>XmText*FontList</Filename></Para></Entry>
 353 <Entry><Para>Set to user font</Para></Entry>
 354 </Row>
 355 <Row>
 356 <Entry><Para><Filename>XmTextField*FontList</Filename></Para></Entry>
 357 <Entry><Para>Set to user font</Para></Entry>
 358 </Row>
 359 </TBody>
 360 </TGroup>
 361 </InformalTable>
 362 </Sect2>
 363 <Sect2 Id="SAG.RegAp.div.8">
 364 <Title>Modifying Color Resources<IndexTerm><Primary>registration</Primary><Secondary>color modifications</Secondary></IndexTerm><IndexTerm><Primary>color resources,modifying for registration</Primary></IndexTerm></Title>
 365 <Para><IndexTerm>
 366 <Primary>Style Manager</Primary>
 367 <Secondary>color integration with</Secondary>
 368 </IndexTerm>Style Manager provides the ability to change application colors dynamically.
 369 The application must be a Motif 1.1 or later client. Clients written with
 370 other toolkits cannot change color dynamically; color changes take effect when
 371 the client is restarted.</Para>
 372 <Para>The easiest way to use the dynamic colors provided by the desktop is to
 373 remove any application color resources for background and foreground color.</Para>
 374 </Sect2>
 375 </Sect1>
 376 <Sect1 Id="SAG.RegAp.div.9">
 377 <Title Id="SAG.RegAp.mkr.15">Step 2: Creating the Desktop Application Root<IndexTerm><Primary>applications</Primary><Secondary>root directory</Secondary></IndexTerm><IndexTerm><Primary>applications</Primary><Secondary>app_root directory</Secondary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>application root directory</Secondary></IndexTerm><IndexTerm><Primary>application root directory</Primary></IndexTerm></Title>
 378 <Note>
 379 <Para>For an example of creating the desktop application root directory for an
 380 application, see
 381 <!--Original XRef content: 'Step&numsp;2'--><XRef Role="Step" Linkend="SAG.RegAp.mkr.7"> of
 382 <!--Original XRef content: '&xd2;Example of Creating a Registration Package'--><XRef Role="SectionTitle" Linkend="SAG.RegAp.div.38"> on
 383 <!--Original XRef content: 'page&numsp;78'--><XRef Role="PageNum" Linkend="SAG.RegAp.mkr.17">.</Para>
 384 </Note>
 385 <Para>The registration package files for the application are grouped beneath a
 386 directory called the application root, or <Symbol Role="Variable"><IndexTerm>
 387 <Primary>&lt;$nopage>app_root, See application root directory</Primary>
 388 </IndexTerm>app_root</Symbol>. The <Symbol Role="Variable">app_root</Symbol> directory used
 389 for the desktop configuration files can be the same directory as the
 390 application's installation <Symbol Role="Variable">app_root</Symbol> or some other location.</Para>
 391 <Para>For example, suppose an application is installed under a directory <Filename>/usr/BTE</Filename>.
 392 This same directory could be used as the <Symbol Role="Variable">app_root</Symbol> for the desktop configuration
 393 files. However, if you are integrating an existing non-desktop smart
 394 application, it is recommended that you create a different desktop <Symbol Role="Variable">app_root</Symbol>
 395 directory. This will prevent the configuration files you create from being
 396 overwritten when you update the application.</Para>
 397 <Para>For example, a system administrator might want to create a directory
 398 <Filename>/etc/desktop_approots/BTE</Filename> as the desktop <Symbol Role="Variable">app_root</Symbol> directory.</Para>
 399 </Sect1>
 400 <Sect1 Id="SAG.RegAp.div.10">
 401 <Title Id="SAG.RegAp.mkr.16">Step 3: Creating the Registration Package Directories<IndexTerm><Primary>registration package</Primary><Secondary>directories</Secondary></IndexTerm></Title>
 402 <Note>
 403 <Para>For an example of creating the registration package directories for an
 404 application, see
 405 <!--Original XRef content: 'Step&numsp;3'--><XRef Role="Step" Linkend="SAG.RegAp.mkr.8"> of
 406 <!--Original XRef content: '&xd2;Example of Creating a Registration Package'--><XRef Role="SectionTitle" Linkend="SAG.RegAp.div.38"> on
 407 <!--Original XRef content: 'page&numsp;79'--><XRef Role="PageNum" Linkend="SAG.RegAp.mkr.18">.</Para>
 408 </Note>
 409 <Para>The registration package is the group of desktop configuration files used by the
 410 desktop to provide a graphical interface for the application.</Para>
 411 <Sect2 Id="SAG.RegAp.div.11">
 412 <Title>Registration Package Contents</Title>
 413 <Para>The desktop configuration files include:</Para>
 414 <ItemizedList Remap="Bullet1">
 415 <ListItem>
 416 <Para>Action and data type definition files</Para>
 417 </ListItem>
 418 <ListItem>
 419 <Para>Icon image files</Para>
 420 </ListItem>
 421 <ListItem>
 422 <Para>An application group directory and its contents</Para>
 423 </ListItem>
 424 <ListItem>
 425 <Para>Optionally: online documentation (infolib) files,
 426 help data files and a Front Panel configuration file</Para>
 427 </ListItem>
 428 </ItemizedList>
 429 <Para>The registration package is gathered under a top-level directory called the
 430 application root, or <Symbol Role="Variable">app_root</Symbol>.</Para>
 431 <Figure>
 432 <Title Id="SAG.RegAp.mkr.17">A registration package beneath an application root directory</Title>
 433 <Graphic Entityref="SAG.RegAp.fig.4" Id="SAG.RegAp.grph.4"></Graphic>
 434 </Figure>
 435 <Para>The major categories of configuration files under the
 436 <Symbol Role="Variable">app_root</Symbol> directory are:</Para>
 437 <InformalTable>
 438 <TGroup Cols="2" colsep="0" rowsep="0">
 439 <colspec colwidth="1.21in">
 440 <colspec colwidth="4.55in">
 441 <THead>
 442 <Row>
 443 <Entry><Para>Subdirectory</Para></Entry>
 444 <Entry><Para>Contents</Para></Entry>
 445 </Row>
 446 </THead>
 447 <TBody>
 448 <Row>
 449 <Entry><Para><filename>types</filename></Para></Entry>
 450 <Entry><Para>Action and data type definition files</Para></Entry>
 451 </Row>
 452 <Row>
 453 <Entry><Para><filename>help</filename></Para></Entry>
 454 <Entry><Para>Desktop help files</Para></Entry>
 455 </Row>
 456 <Row>
 457 <Entry><Para><filename>icons</filename></Para></Entry>
 458 <Entry><Para>Bitmap and pixmap image files used by the application's
 459 actions and data types</Para></Entry>
 460 </Row>
 461 <Row>
 462 <Entry><Para><filename>appmanager</filename></Para></Entry>
 463 <Entry><Para>The directory and contents that create the application group</Para></Entry>
 464 </Row>
 465 <Row>
 466 <Entry><Para><filename>infolib</filename></Para></Entry>
 467 <Entry><Para>Online documentation files organized as infolibs, bookcases, and books</Para></Entry>
 468 </Row>
 469 </TBody>
 470 </TGroup>
 471 </InformalTable>
 472 <Para>Each of the major categories has subdirectories for language-dependent files.
 473 Default-language files are placed in the <Command>C</Command> directory.</Para>
 474 <Sect3 Id="SAG.RegAp.div.12">
 475 <Title>To Create the Registration Package</Title>
 476 <OrderedList>
 477 <ListItem>
 478 <Para>Create these directories. If you are providing language-dependent
 479 configuration files, create a separate directory for each language. If you are
 480 supplying only one language, put the files in the <Command>C</Command> directory.</Para>
 481 <ItemizedList Remap="Bullet2">
 482 <ListItem>
 483 <Para><Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/types/</Filename><Symbol Role="Variable">language</Symbol></Para>
 484 </ListItem>
 485 <ListItem>
 486 <Para><Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/help/</Filename><Symbol Role="Variable">language</Symbol></Para>
 487 </ListItem>
 488 <ListItem>
 489 <Para><Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/icons/</Filename><Symbol Role="Variable">language</Symbol></Para>
 490 </ListItem>
 491 <ListItem>
 492 <Para><Symbol Role="Variable">app_root</Symbol><Filename>/dt/infolib/</Filename><Symbol Role="Variable">language</Symbol>
 493 </Para>
 494 </ListItem>
 495 <ListItem>
 496 <Para><Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/appmanager/</Filename><Symbol Role="Variable">language</Symbol><Symbol Role="Variable">/</Symbol><Symbol Role="Variable">appgroup_name,</Symbol> where
 497 <Symbol Role="Variable">appgroup_name</Symbol> is the name of the application group
 498 </Para>
 499 </ListItem>
 500 </ItemizedList>
 501 <Para>For example,
 502 <!--Original XRef content: 'Figure&numsp;4&hyphen;5'--><XRef Role="CodeOrFigureOrTable" Linkend="SAG.RegAp.mkr.11"> shows Application Manager containing an group
 503 whose <Symbol Role="Variable">appgroup_name</Symbol> is &ldquo;Media_Tools.&rdquo;</Para>
 504 </ListItem>
 505 </OrderedList>
 506 <Figure>
 507 <Title Id="SAG.RegAp.mkr.18">Application group at the top level of the Application Manager</Title>
 508 <Graphic Entityref="SAG.RegAp.fig.5" Id="SAG.RegAp.grph.5"></Graphic>
 509 </Figure>
 510 <Para>The <Command>dtappintegrate</Command> tool operates only on the desktop configuration files in
 511 the <Filename>types</Filename>, <Filename>help</Filename>, <Filename>icons</Filename>,
 512 <Filename>infolib</Filename>, and <Filename>appmanager</Filename> directories. The application's
 513 binary executable, <Filename>app-defaults</Filename>, and message catalog files are administered
 514 separately.</Para>
 515 </Sect3>
 516 </Sect2>
 517 </Sect1>
 518 <Sect1 Id="SAG.RegAp.div.13">
 519 <Title Id="SAG.RegAp.mkr.19">Step 4: Creating the Actions and Data Types for the Application<IndexTerm><Primary>actions</Primary><Secondary>required for registration</Secondary></IndexTerm><IndexTerm><Primary>data types</Primary><Secondary>required for registration</Secondary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>actions needed</Secondary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>data types needed</Secondary></IndexTerm></Title>
 520 <Note>
 521 <Para>For an example of creating the actions and data types for an
 522 application, see
 523 <!--Original XRef content: 'Step&numsp;4'--><XRef Role="Step" Linkend="SAG.RegAp.mkr.9"> of
 524 <!--Original XRef content: '&xd2;Example of Creating a Registration Package'--><XRef Role="SectionTitle" Linkend="SAG.RegAp.div.38"> on
 525 <!--Original XRef content: 'page&numsp;79'--><XRef Role="PageNum" Linkend="SAG.RegAp.mkr.19">.</Para>
 526 </Note>
 527 <Para>Actions and data types provide a user interface for the application.</Para>
 528 <ItemizedList Remap="Bullet1">
 529 <ListItem>
 530 <Para>Actions provide a user interface for the command to launch the application.</Para>
 531 </ListItem>
 532 <ListItem>
 533 <Para>Data types provide customized appearance and behavior for the
 534 application's data files.</Para>
 535 </ListItem>
 536 </ItemizedList>
 537 <Sect2 Id="SAG.RegAp.div.14">
 538 <Title>Actions and Data Types Required by an Application<IndexTerm><Primary>applications</Primary><Secondary>actions required</Secondary></IndexTerm><IndexTerm><Primary>applications</Primary><Secondary>data types required</Secondary></IndexTerm></Title>
 539 <Para>Typical applications require the following action and data type definitions:</Para>
 540 <ItemizedList Remap="Bullet1">
 541 <ListItem>
 542 <Para>An action that opens the application.</Para>
 543 </ListItem>
 544 <ListItem>
 545 <Para>A data type for the data files of your application. If you create a data type,
 546 you will also want to create:</Para>
 547 <ItemizedList Remap="Bullet2">
 548 <ListItem>
 549 <Para>An Open action for the data files of your application</Para>
 550 </ListItem>
 551 <ListItem>
 552 <Para>A Print action for the data files of your application</Para>
 553 </ListItem>
 554 </ItemizedList>
 555 </ListItem>
 556 <ListItem>
 557 <Para>A data type for the application group (see
 558 <!--Original XRef content: '&xd2;Configuring the Application
 559 Group To Use a Unique Icon&xd3; on page&numsp;70'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.25">).</Para>
 560 </ListItem>
 561 </ItemizedList>
 562 <Para>For an introduction to how actions and data types are used in the desktop, see
 563 <!--Original XRef content: 'Chapter&numsp;8, &xd2;Introduction to Actions and Data Types'--><XRef Role="ChapNumAndTitle" Linkend="SAG.IntAc.div.1">.</Para>
 564 </Sect2>
 565 <Sect2 Id="SAG.RegAp.div.15">
 566 <Title>Location for Action and Data Type Definition Configuration Files</Title>
 567 <Para>Actions and data types are defined in configuration files. The only naming
 568 requirement for files containing action and data type definitions is that they
 569 must have a <Filename>.dt</Filename> suffix. By convention, you may want to name the file
 570 <Symbol Role="Variable">action_name</Symbol><Filename>.dt</Filename> or <Symbol Role="Variable">application_name</Symbol><Filename>.dt</Filename>.</Para>
 571 <Para>Place files containing actions and data types under the application root in the
 572 directory:
 573 </para>
 574 <programlisting><Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/types/</Filename><Symbol Role="Variable">language</Symbol>
 575 </programlisting>
 576 <Para>The default <Symbol Role="Variable">language</Symbol> is <Command>C</Command>.
 577 </Para>
 578 <Figure>
 579 <Title>Action and data type definition files</Title>
 580 <Graphic Entityref="SAG.RegAp.fig.6" Id="SAG.RegAp.grph.6"></Graphic>
 581 </Figure>
 582 </Sect2>
 583 <Sect2 Id="SAG.RegAp.div.16">
 584 <Title>Ways to Create Actions and Data Types</Title>
 585 <Para>You can create action and data type definitions for an application in either of
 586 two ways:</Para>
 587 <ItemizedList Remap="Bullet1">
 588 <ListItem>
 589 <Para>Use the Create Action tool.</Para>
 590 <Para>Create Action provides an easy-to-use interface with text fields that you fill
 591 in. However, the tool has certain limitations.</Para>
 592 </ListItem>
 593 <ListItem>
 594 <Para>Create the definitions manually.</Para>
 595 <Para>This requires you to learn the syntax for creating the definitions, but
 596 provides access to the full range of functionality.</Para>
 597 </ListItem>
 598 </ItemizedList>
 599 </Sect2>
 600 <Sect2 Id="SAG.RegAp.div.17" Role="Procedure">
 601 <Title>To Create Actions and Data Types Using Create Action</Title>
 602 <Para>This procedure uses the Create Action utility to create an action and data types
 603 for the application.</Para>
 604 <Para>For more information about Create Action, use its online help or see
 605 <!--Original XRef content: 'Chapter&numsp;9,
 606 &xd2;Creating Actions and Data Types Using Create Action'--><XRef Role="ChapNumAndTitle" Linkend="SAG.dtCrA.div.1">.</Para>
 607 <OrderedList>
 608 <ListItem>
 609 <Para Id="SAG.RegAp.mkr.20">Open the Desktop_Apps application group and double-click Create Action.</Para>
 610 </ListItem>
 611 <ListItem>
 612 <Para>Use Create Action to create the action and data type definitions for the
 613 application and its data type.</Para>
 614 <Para>The configuration file created by Create Action will be written to
 615 <Symbol Role="Variable">HomeDirectory</Symbol><Filename>/.dt/type/</Filename><Symbol Role="Variable">action_name</Symbol><Filename>.dt.</Filename> The action file (the executable
 616 file with the same name as the action) is placed in your home directory.</Para>
 617 </ListItem>
 618 <ListItem>
 619 <Para>Test the action using the action file created in your home directory.</Para>
 620 </ListItem>
 621 <ListItem>
 622 <Para>Copy the action definition file <Symbol Role="Variable">HomeDirectory</Symbol><Filename>/.dt/type/</Filename><Symbol Role="Variable">action_name</Symbol><Filename>.dt</Filename> to
 623 the directory:
 624 </para>
 625 <programlisting><Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/types/</Filename><Symbol Role="Variable">language</Symbol>
 626 </programlisting>
 627 </ListItem>
 628 <ListItem>
 629 <Para>After the application group directory has been created (see
 630 <!--Original XRef content: 'Section&numsp;, &xd2;Step 7:
 631 Creating the Application Group,&xd3; on page&numsp;68'--><XRef Role="SecNumTitleAnsPage" Linkend="SAG.RegAp.div.22">), copy the action file
 632 <Symbol Role="Variable">HomeDirectory</Symbol><Filename>/</Filename><Symbol Role="Variable">action_name</Symbol> to the
 633 <Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/appmanager/</Filename><Symbol Role="Variable">language</Symbol><Symbol Role="Variable">/</Symbol><Symbol Role="Variable">appgroup_name</Symbol> directory.</Para>
 634 </ListItem>
 635 </OrderedList>
 636 </Sect2>
 637 <Sect2 Id="SAG.RegAp.div.18" Role="Procedure">
 638 <Title>To Create Actions and Data Types Manually</Title>
 639 <OrderedList>
 640 <ListItem>
 641 <Para>Create a configuration file containing the action and data type definitions
 642 for the application.</Para>
 643 </ListItem>
 644 </OrderedList>
 645 <Para>Action and data type definition files must follow the naming convention
 646 <Symbol Role="Variable">name</Symbol><Filename>.dt</Filename>.</Para>
 647 <Para>You can place all your action and data type definitions in one file or distribute
 648 them among multiple files. For each file, use a file name that system
 649 administrators will easily connect with your application.</Para>
 650 <Para>Action and data type names must be one word (no embedded spaces). You can
 651 use an underscore character. By convention, the first letter of the action or data
 652 type name is capitalized. Do not use an existing action name or file name. Use
 653 a name that advanced users and system administrators will easily connect with
 654 your application.</Para>
 655 <Para>If you want the application's icon labeled with a different name than the action
 656 name, include a <Command>LABEL</Command> field in the action definition.</Para>
 657 <Para>For more information about creating actions and data types, see:</Para>
 658 <ItemizedList Remap="Bullet1">
 659 <ListItem>
 660 <Para><!--Original XRef content: 'Chapter&numsp;8, &xd2;Introduction to Actions and Data Types'--><XRef Role="ChapNumAndTitle" Linkend="SAG.IntAc.div.1"></Para>
 661 </ListItem>
 662 <ListItem>
 663 <Para><!--Original XRef content: 'Chapter&numsp;9, &xd2;Creating Actions and Data Types Using Create Action'--><XRef Role="ChapNumAndTitle" Linkend="SAG.dtCrA.div.1"></Para>
 664 </ListItem>
 665 <ListItem>
 666 <Para><!--Original XRef content: 'Chapter&numsp;10, &xd2;Creating Actions Manually'--><XRef Role="ChapNumAndTitle" Linkend="SAG.CrAct.div.1"></Para>
 667 </ListItem>
 668 <ListItem>
 669 <Para><!--Original XRef content: 'Chapter&numsp;11, &xd2;Creating Data Types Manually'--><XRef Role="ChapNumAndTitle" Linkend="SAG.CrDT.div.1"></Para>
 670 </ListItem>
 671 </ItemizedList>
 672 </Sect2>
 673 </Sect1>
 674 <Sect1 Id="SAG.RegAp.div.19">
 675 <Title Id="SAG.RegAp.mkr.21">Step 5: Putting the Help Files in the Registration Package<IndexTerm><Primary>registration</Primary><Secondary>help files</Secondary></IndexTerm><IndexTerm><Primary>help files</Primary><Secondary>in regisration package</Secondary></IndexTerm></Title>
 676 <Note>
 677 <Para>For an example of adding help files to a registration package, see
 678 <!--Original XRef content: 'Step&numsp;5'--><XRef Role="Step" Linkend="SAG.RegAp.mkr.10">
 679 of
 680 <!--Original XRef content: '&xd2;Example of Creating a Registration Package'--><XRef Role="SectionTitle" Linkend="SAG.RegAp.div.38"> on
 681 <!--Original XRef content: 'page&numsp;81'--><XRef Role="PageNum" Linkend="SAG.RegAp.mkr.20">.</Para>
 682 </Note>
 683 <Para>If the application includes a desktop<IndexTerm>
 684 <Primary>help volume</Primary>
 685 <Secondary>location in regisration package</Secondary>
 686 </IndexTerm>
 687 help volume (a help volume created with
 688 the desktop Help Developer's Kit), the help volume master file (<Filename>*.sdl</Filename>) should
 689 be placed in the directory <Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/help/</Filename><Symbol Role="Variable">language</Symbol>.</Para>
 690 <Para><IndexTerm>
 691 <Primary>&lt;$nopage>help</Primary>
 692 <Secondary>See also help volume, help files</Secondary>
 693 </IndexTerm>Graphics used by the help files are usually placed in a <Command>graphics</Command> subdirectory.
 694 The graphics must be located in the same directory relative to the master help
 695 volume (<Filename>*.sdl</Filename>) file as when the help volume was created.</Para>
 696 <Para>If the application does not provide a help volume, you can create one if you
 697 have the<IndexTerm>
 698 <Primary>Help Developer'</Primary>
 699 </IndexTerm><IndexTerm>
 700 <Primary>s Kit</Primary>
 701 </IndexTerm>
 702 Help Developer's Kit.</Para>
 703 <Para>There are two levels of integration of a<IndexTerm>
 704 <Primary>help volume</Primary>
 705 <Secondary>levels of integrtion</Secondary>
 706 </IndexTerm>
 707 help volume:</Para>
 708 <ItemizedList Remap="Bullet1">
 709 <ListItem>
 710 <Para><IndexTerm>
 711 <Primary>help</Primary>
 712 <Secondary>full integration</Secondary>
 713 </IndexTerm>Full integration.</Para>
 714 <Para>When desktop help is fully integrated, the help volume can be accessed
 715 from the application&mdash;for example, by on-item help and the Help menu. Full
 716 integration involves modification to the application's executables.</Para>
 717 </ListItem>
 718 <ListItem>
 719 <Para><IndexTerm>
 720 <Primary>help</Primary>
 721 <Secondary>partial integration</Secondary>
 722 </IndexTerm>Partial integration.</Para>
 723 <Para>When desktop help is partially integrated, it is available from the top level
 724 of the Help Manager. However, you cannot access the help volume from the
 725 application's windows. You can also provide an action to access the help
 726 from the application group. The following example action displays the help
 727 volume located in the
 728 help master file <Filename>MyApp.sdl</Filename>:<IndexTerm><Primary>help volume</Primary><Secondary>master help file</Secondary></IndexTerm><IndexTerm><Primary>.sdl files</Primary></IndexTerm>
 729 </Para>
 730 <programlisting>ACTION OpenMyAppHelp
 731 {
 732   LABEL           MyAppHelp
 733   ARG_COUNT       0
 734   TYPE            COMMAND
 735   WINDOW_TYPE     NO_STDIO
 736   EXEC_STRING     /usr/dt/bin/dthelpview -helpVolume MyApp
 737   DESCRIPTION     Displays help for the MyApp application.
 738 }
 739 </programlisting>
 740 </ListItem>
 741 </ItemizedList>
 742 </Sect1>
 743 <Sect1 Id="SAG.RegAp.div.19a">
 744 <Title Id="SAG.RegAp.mkr.21a">Step 6: Putting Information Libraries in the Registration Package<IndexTerm><Primary>registration</Primary><Secondary>infolibs</Secondary></IndexTerm><IndexTerm><Primary>infolibs</Primary><Secondary>in regisration package</Secondary></IndexTerm></Title>
 745 <Para>If the application includes online documentation (created with
 746 the desktop Information System Developer's Kit), the information
 747 library (<Filename>*.dti</Filename>) containing the documentation should
 748 be placed in the directory:<IndexTerm><Primary>infolib</Primary><Secondary>location in regisration package</Secondary></IndexTerm>
 749 </para>
 750 <programlisting><Symbol Role="Variable">app_root</Symbol><Filename>/dt/infolib/</Filename><Symbol Role="Variable">language</Symbol>
 751 </programlisting>
 752 <Para>Graphics used by the DocBook book files
 753 (<Filename>*.sgm</Filename>) are usually placed in a
 754 <Command>graphics</Command> subdirectory.
 755 The graphics must be located in the same directory relative to the infolib
 756 (<Filename>*.dti</Filename>) file as when the infolib was created.</Para>
 757 <Para>If the application does not provide online documentation, you can create it
 758 if you have the Information System Developer's Kit.<IndexTerm><Primary>Information System Developer's Kit</Primary></IndexTerm>
 759 </Para>
 760 <Para>There are two levels of integration of an infolib:<IndexTerm><Primary>infolib</Primary><Secondary>levels of integrtion</Secondary></IndexTerm>
 761 </Para>
 762 <ItemizedList Remap="Bullet1">
 763 <ListItem>
 764 <Para>Full integration.<IndexTerm><Primary>infolib</Primary><Secondary>full integration</Secondary></IndexTerm>
 765 </Para>
 766 <Para>When an infolib is fully integrated, it can be accessed
 767 from the application&mdash;by using <Symbol>DtActionInvoke</Symbol>
 768 to display a specific topic under the Information Manager.
 769 Full integration involves modification to the application's executables.</Para>
 770 </ListItem>
 771 <ListItem>
 772 <Para>Partial integration.<IndexTerm><Primary>infolib</Primary><Secondary>partial integration</Secondary></IndexTerm>
 773 </Para>
 774 <Para>When an infolib is partially integrated, it is available from the top level
 775 of the Information Manager. However, you cannot access the infolib from the
 776 application's windows. You can also provide an action to access the infolib
 777 from the application group. The following example action displays the infolib
 778 located in the infolib <Filename>MyApp.dti</Filename>:</Para>
 779 <programlisting>ACTION OpenMyAppInfolib
 780 {
 781   LABEL           MyAppInfolib
 782   ARG_TYPE        InfoLib
 783   TYPE            MAP
 784   MAP_ACTION      DtLoadInfoLib /usr/dt/infolib/C/MyAppInfolib.dti
 785   DESCRIPTION     Invokes the Information Manager to display the online
 786                   documentation for MyApp application.
 787 }
 788 </programlisting>
 789 </ListItem>
 790 </ItemizedList>
 791 </Sect1>
 792 <Sect1 Id="SAG.RegAp.div.20">
 793 <Title Id="SAG.RegAp.mkr.22">Step 7: Creating Icons for the Application<IndexTerm><Primary>registration</Primary><Secondary>icon requirements</Secondary></IndexTerm><IndexTerm><Primary>icons</Primary><Secondary>required for registration</Secondary></IndexTerm></Title>
 794 <Note>
 795 <Para>For an example of creating the icon files for an application, see
 796 <!--Original XRef content: 'Step&numsp;6'--><XRef Role="Step" Linkend="SAG.RegAp.mkr.11"> of
 797 <!--Original XRef content: '&xd2;Example of Creating a Registration Package'--><XRef Role="SectionTitle" Linkend="SAG.RegAp.div.38"> on
 798 <!--Original XRef content: 'page&numsp;82'--><XRef Role="PageNum" Linkend="SAG.RegAp.mkr.21">.</Para>
 799 </Note>
 800 <Para>The desktop provides default icons for actions, data types, and application
 801 groups. However, you will probably want to create unique icons for the
 802 application.</Para>
 803 <Para>Icons are placed in the directory <Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/icons/</Filename><Symbol Role="Variable">language</Symbol>.</Para>
 804 <Sect2 Id="SAG.RegAp.div.21">
 805 <Title>Icons Required for the Desktop</Title>
 806 <Para>The application uses these icon images on the desktop:</Para>
 807 <ItemizedList Remap="Bullet1">
 808 <ListItem>
 809 <Para><Emphasis Role="Lead-in">Action icon</Emphasis>.
 810 This is the icon the user double-clicks to start your application
 811 (actions). It is referenced in the <Command>ICON</Command> field of the action that launches the
 812 application.<IndexTerm><Primary>icons</Primary><Secondary>starting application</Secondary></IndexTerm><IndexTerm><Primary>application icon</Primary><Secondary>required by desktop</Secondary></IndexTerm><IndexTerm><Primary>action icon</Primary><Secondary>required by desktop</Secondary></IndexTerm>
 813 </Para>
 814 <Para>Supply three sizes: tiny, medium, and large.</Para>
 815 </ListItem>
 816 <ListItem>
 817 <Para><Emphasis Role="Lead-in">Data type icon</Emphasis>.
 818 This icon is used to represent the application's data files in
 819 File Manager. It is referenced in the <Command>ICON</Command> field of the data type definition.</Para>
 820 <Para>If your application supports multiple data types, you should provide a
 821 different icon for each data type.<IndexTerm><Primary>icons</Primary><Secondary>data type</Secondary></IndexTerm><IndexTerm><Primary>data types</Primary><Secondary>icons for</Secondary></IndexTerm>
 822 </Para>
 823 <Para>Supply two sizes: tiny and medium.</Para>
 824 </ListItem>
 825 <ListItem>
 826 <Para><Emphasis Role="Lead-in"><IndexTerm>
 827 <Primary>icons</Primary>
 828 <Secondary>application groups</Secondary>
 829 </IndexTerm><IndexTerm>
 830 <Primary>application groups</Primary>
 831 <Secondary>icons for</Secondary>
 832 </IndexTerm>Application group icon</Emphasis>. This is the icon representing the directory at the
 833 top level of the Application Manager. It is referenced in the <Command>ICON</Command> field of the
 834 data type definition for the application group. (See
 835 <!--Original XRef content: '&xd2;Step 7: Creating the
 836 Application Group&xd3; on page&numsp;68'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.22">.)</Para>
 837 <Para>Supply two sizes: tiny and medium.</Para>
 838 </ListItem>
 839 </ItemizedList>
 840 <Para>You may need to supply both pixmap and bitmap versions of each icon to
 841 support color (eight-bit and larger) and monochrome (fewer than eight bits)
 842 displays.</Para>
 843 <Table Id="SAG.RegAp.tbl.1" Frame="Topbot">
 844 <Title>Naming Conventions for Icon Files</Title>
 845 <TGroup Cols="4" colsep="0" rowsep="0">
 846 <ColSpec Colname="1" Colwidth="0.65 in">
 847 <ColSpec Colname="2" Colwidth="1.70 in">
 848 <ColSpec Colname="3" Colwidth="1.30 in">
 849 <ColSpec Colname="4" Colwidth="1.35 in">
 850 <THead>
 851 <Row>
 852 <Entry><Para><Literal>Size</Literal></Para></Entry>
 853 <Entry><Para><Literal>Pixel Dimensions</Literal></Para></Entry>
 854 <Entry><Para><Literal>Bitmap Name</Literal></Para></Entry>
 855 <Entry><Para><Literal>Pixmap Name</Literal></Para></Entry>
 856 </Row>
 857 </THead>
 858 <TBody>
 859 <Row>
 860 <Entry><Para>tiny</Para></Entry>
 861 <Entry><Para>16 by 16</Para></Entry>
 862 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.t.bm</Filename></Para></Entry>
 863 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.t.pm</Filename></Para></Entry>
 864 </Row>
 865 <Row>
 866 <Entry><Para>medium</Para></Entry>
 867 <Entry><Para>32 by 32</Para></Entry>
 868 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.m.bm</Filename></Para></Entry>
 869 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.m.pm</Filename></Para></Entry>
 870 </Row>
 871 <Row>
 872 <Entry><Para>large</Para></Entry>
 873 <Entry><Para>48 by 48</Para></Entry>
 874 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.l.bm</Filename></Para></Entry>
 875 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.l.pm</Filename></Para></Entry>
 876 </Row>
 877 </TBody>
 878 </TGroup>
 879 </Table>
 880 <Para>If you do not provide bitmap files, the desktop maps the color specifications of
 881 the pixmap files into black and white. However, this mapping may not
 882 produce the appearance you want.</Para>
 883 <Para>For more information about icons, see
 884 <!--Original XRef content: '&xd2;Icon Image Files&xd3; on page&numsp;201'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.CrIcn.div.2">.</Para>
 885 </Sect2>
 886 </Sect1>
 887 <Sect1 Id="SAG.RegAp.div.22">
 888 <Title Id="SAG.RegAp.mkr.23">Step 8: Creating the Application Group<IndexTerm><Primary>registration</Primary><Secondary>application group</Secondary></IndexTerm><IndexTerm><Primary>application groups</Primary><Secondary>creating in regisration package</Secondary></IndexTerm></Title>
 889 <Note>
 890 <Para>For an example of creating the application group, see
 891 <!--Original XRef content: 'Step&numsp;7'--><XRef Role="Step" Linkend="SAG.RegAp.mkr.12"> of
 892 <!--Original XRef content: '&xd2;Example of Creating a Registration Package'--><XRef Role="SectionTitle" Linkend="SAG.RegAp.div.38"> on
 893 <!--Original XRef content: 'page&numsp;82'--><XRef Role="PageNum" Linkend="SAG.RegAp.mkr.22">.</Para>
 894 </Note>
 895 <Para>Once you have created the action and data type definitions for the application,
 896 you must create the configuration files responsible for creating what the user
 897 actually sees&mdash;the application group and its contents.</Para>
 898 <Para><IndexTerm>
 899 <Primary>application groups</Primary>
 900 <Secondary>directories for</Secondary>
 901 </IndexTerm>The application group is a directory at the top level of the Application
 902 Manager (see
 903 <!--Original XRef content: 'Figure&numsp;4&hyphen;1 on page&numsp;55'--><XRef Role="CodeOrFigOrTabAndPNum" Linkend="SAG.RegAp.mkr.4">).</Para>
 904 <Para>There are three steps to creating the application group:</Para>
 905 <ItemizedList Remap="Bullet1">
 906 <ListItem>
 907 <Para>Create the application group directory in the registration package.</Para>
 908 </ListItem>
 909 <ListItem>
 910 <Para>Optional: configure the application group to use a unique icon. This
 911 involves creating the data type definition for the application group
 912 directory.</Para>
 913 </ListItem>
 914 <ListItem>
 915 <Para>Create the contents of the application group.</Para>
 916 </ListItem>
 917 </ItemizedList>
 918 <Sect2 Id="SAG.RegAp.div.23">
 919 <Title>Creating the Application Group Directory</Title>
 920 <Para>To create an application group, create the directories in the registration
 921 package under <Command>appmanager</Command>, as shown in
 922 <!--Original XRef content: 'Figure&numsp;4&hyphen;7'--><XRef Role="CodeOrFigureOrTable" Linkend="SAG.RegAp.mkr.13">.</Para>
 923 <Figure>
 924 <Title Id="SAG.RegAp.mkr.24">The appmanager directory</Title>
 925 <Graphic Entityref="SAG.RegAp.fig.7" Id="SAG.RegAp.grph.7"></Graphic>
 926 </Figure>
 927 </Sect2>
 928 <Sect2 Id="SAG.RegAp.div.24">
 929 <Title>Application Group Name<IndexTerm><Primary>application groups</Primary><Secondary>names</Secondary></IndexTerm></Title>
 930 <Para>The &lt;appgroup_name> in
 931 <!--Original XRef content: 'Figure&numsp;4&hyphen;7'--><XRef Role="CodeOrFigureOrTable" Linkend="SAG.RegAp.mkr.24"> is the name for the application group.</Para>
 932 <Figure>
 933 <Title>The application group name (&lt;appgroup_name>)</Title>
 934 <Graphic Entityref="SAG.RegAp.fig.8" Id="SAG.RegAp.grph.8"></Graphic>
 935 </Figure>
 936 <Para>The name can be any allowable file (directory) name. Use a name that
 937 describes the application.</Para>
 938 </Sect2>
 939 <Sect2 Id="SAG.RegAp.div.25">
 940 <Title Id="SAG.RegAp.mkr.25">Configuring the Application Group To Use a Unique Icon<IndexTerm><Primary>icons</Primary><Secondary>application groups</Secondary></IndexTerm><IndexTerm><Primary>application groups</Primary><Secondary>icons for</Secondary></IndexTerm></Title>
 941 <Para>The desktop provides a default application-group icon. However, you will
 942 probably want to provide a custom icon.</Para>
 943 <Para>If you want to provide a unique icon for the application group, you must
 944 create:</Para>
 945 <ItemizedList Remap="Bullet1">
 946 <ListItem>
 947 <Para>A data type for the directory that appears at the top level of Application
 948 Manager.</Para>
 949 </ListItem>
 950 <ListItem>
 951 <Para>Open and Print actions for the data type.</Para>
 952 </ListItem>
 953 </ItemizedList>
 954 <Para>For example, suppose you want to create an application group named
 955 Media_Tools. The following data type definition, placed in a file
 956 <Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/types/</Filename><Symbol Role="Variable">language</Symbol><Filename>/</Filename><Symbol Role="Variable">name</Symbol><Filename>.dt</Filename>,
 957 assigns a unique icon to the application group icon.</Para>
 958 <programlisting>DATA_ATTRIBUTES  Media_ToolsAppgroup
 959 {
 960    ACTIONS       OpenInPlace,OpenNewView
 961    ICON          MediaTools
 962    DESCRIPTION   Double-click to open the Media_Tools \
 963                  application group
 964 }
 965 DATA_CRITERIA           Media_ToolsAppgroupCriteria1
 966 {
 967    DATA_ATTRIBUTES_NAME Media_ToolsAppgroup
 968    MODE                 d
 969    PATH_PATTERN         */appmanager/*/Media_Tools
 970 }
 971 </ProgramListing>
 972 <Para>The attributes section of the definition specifies the icon to be used. The criteria
 973 section of the definition specifies that the data type be defined to any directory
 974 named <Filename>Media_Tools</Filename> that is a subdirectory of a directory named <Command>appmanager</Command>.</Para>
 975 <Para><!--Original XRef content: 'Figure&numsp;4&hyphen;9'--><XRef Role="CodeOrFigureOrTable" Linkend="SAG.RegAp.mkr.14"> shows the relationship between the application group name and the
 976 data type definition. The <Filename>PATH_PATTERN</Filename> field in the data type definition
 977 connects a unique icon to the application group.</Para>
 978 <Figure>
 979 <Title Id="SAG.RegAp.mkr.26">How an application group gets a unique icon</Title>
 980 <Graphic Entityref="SAG.RegAp.fig.9" Id="SAG.RegAp.grph.9"></Graphic>
 981 </Figure>
 982 <Para>You should also create an Open and Print action for the<IndexTerm>
 983 <Primary>application groups</Primary>
 984 <Secondary>action for</Secondary>
 985 </IndexTerm><IndexTerm>
 986 <Primary>application groups</Primary>
 987 <Secondary>data types for</Secondary>
 988 </IndexTerm>
 989 application group data
 990 type:</Para>
 991 <ProgramListing>ACTION Open
 992 {
 993  ARG_TYPE   Media_ToolsAppGroup
 994  TYPE   MAP
 995  MAP_ACTION   OpenAppGroup
 996 }
 997 ACTION Print
 998 {
 999  ARG_TYPE   Media_ToolsAppGroup
1000  TYPE   MAP
1001  MAP_ACTION   PrintAppGroup
1002 }
1003 </ProgramListing>
1004 <Para>OpenAppGroup and PrintAppGroup actions are built-in actions defined in
1005 <Filename>/usr/dt/appconfig/types/</Filename><Symbol Role="Variable">language</Symbol><Filename>/dtappman.dt</Filename>.</Para>
1006 </Sect2>
1007 <Sect2 Id="SAG.RegAp.div.26">
1008 <Title>Creating the Contents of the Application Group<IndexTerm><Primary>application groups</Primary><Secondary>contents</Secondary></IndexTerm><IndexTerm><Primary>registration package</Primary><Secondary>application group contents</Secondary></IndexTerm></Title>
1009 <Para>The most important item in the application group is an icon to start the
1010 application (an action icon). If the application group contains a suite of
1011 applications, there is usually an icon for each application.</Para>
1012 <Para>In addition to one or more action icons, the application group may contain:</Para>
1013 <ItemizedList Remap="Bullet1">
1014 <ListItem>
1015 <Para>One or more README files</Para>
1016 </ListItem>
1017 <ListItem>
1018 <Para>One or more sample data files</Para>
1019 </ListItem>
1020 <ListItem>
1021 <Para>Templates</Para>
1022 </ListItem>
1023 <ListItem>
1024 <Para>An icon the user can double-click to view help information</Para>
1025 </ListItem>
1026 <ListItem>
1027 <Para>A man page</Para>
1028 </ListItem>
1029 <ListItem>
1030 <Para>A specialized Front Panel control</Para>
1031 </ListItem>
1032 </ItemizedList>
1033 <Para>The application group can contain subdirectories.</Para>
1034 <Sect3 Id="SAG.RegAp.div.27">
1035 <Title>Creating the Action File (Application Icon)<IndexTerm><Primary>icons</Primary><Secondary>representing applications</Secondary></IndexTerm><IndexTerm><Primary>registration package</Primary><Secondary>application icon</Secondary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>See also registration package</Secondary></IndexTerm><IndexTerm><Primary>registration package</Primary><Secondary>See also registration</Secondary></IndexTerm></Title>
1036 <Para>The application group should contain an icon that launches the application. If
1037 the group supplies a suite of applications, there should be an icon for each one.
1038 These icons are called <Symbol Role="Variable">application icons,</Symbol> or <Symbol Role="Variable">action icons,</Symbol> since they represent an
1039 underlying action.</Para>
1040 <Para>An action icon is created by creating an executable file with the same name as
1041 the action it will run:</Para>
1042 <ProgramListing><Symbol Role="Variable">app_root</Symbol>/dt/appconfig/appmanager/<Symbol Role="Variable">appgroup_name</Symbol>/<Symbol Role="Variable">action_name</Symbol></ProgramListing>
1043 <Para>The file is called an<IndexTerm>
1044 <Primary>action file</Primary>
1045 <Secondary>creating</Secondary>
1046 </IndexTerm>
1047 <Symbol Role="Variable">action file</Symbol>, because its purpose is to create a visual
1048 representation of the underlying action.</Para>
1049 <Para>For example, if you've created an action named BestTextEditor that runs the
1050 BestTextEditor application, you would create an executable file named
1051 BestTextEditor. In File Manager and the Application Manager, the action file
1052 will use the icon image specified in the action definition.</Para>
1053 <Para><!--Original XRef content: 'Figure&numsp;4&hyphen;10'--><XRef Role="CodeOrFigureOrTable" Linkend="SAG.RegAp.mkr.15"> illustrates the relationship between the action definition, action file,
1054 and actual entry in the Application Manager window.</Para>
1055 <Figure>
1056 <Title Id="SAG.RegAp.mkr.27">The application icon is a file in the application group</Title>
1057 <Graphic Entityref="SAG.RegAp.fig.10" Id="SAG.RegAp.grph.10"></Graphic>
1058 </Figure>
1059 </Sect3>
1060 <Sect3 Id="SAG.RegAp.div.28">
1061 <Title>Read Me Files<IndexTerm><Primary>application package, See registration package</Primary></IndexTerm><IndexTerm><Primary>readme files</Primary></IndexTerm><IndexTerm><Primary>registration package</Primary><Secondary>readme files</Secondary></IndexTerm><IndexTerm><Primary>application groups</Primary><Secondary>readme files</Secondary></IndexTerm></Title>
1062 <Para>The desktop provides a README data type that you can use for your
1063 application's README files. Use one of these naming conventions:</Para>
1064 <ItemizedList Remap="Bullet1">
1065 <ListItem>
1066 <Para><Command>README</Command></Para>
1067 </ListItem>
1068 <ListItem>
1069 <Para><Command>readme</Command></Para>
1070 </ListItem>
1071 <ListItem>
1072 <Para><Filename>README.*</Filename></Para>
1073 </ListItem>
1074 <ListItem>
1075 <Para><Filename>Read.*.Me</Filename></Para>
1076 </ListItem>
1077 <ListItem>
1078 <Para><Filename>read.*.me</Filename></Para>
1079 </ListItem>
1080 <ListItem>
1081 <Para><Filename>READ.*.ME</Filename></Para>
1082 </ListItem>
1083 </ItemizedList>
1084 </Sect3>
1085 <Sect3 Id="SAG.RegAp.div.29">
1086 <Title>Creating a Specialized Front Panel Control<IndexTerm><Primary>Front Panel</Primary><Secondary>control in registration package</Secondary></IndexTerm><IndexTerm><Primary>registration package</Primary><Secondary>Front Panel control</Secondary></IndexTerm></Title>
1087 <Para>In most cases, you do not need to provide a Front Panel control definition; the
1088 user can add the application to the Front Panel by dropping the action icon on
1089 the Install Icon control in a subpanel.</Para>
1090 <Para>You might want to create a Front Panel configuration file containing a control
1091 definition for your application if you want users to be able to install a control
1092 that behaves differently than the action icon&mdash;for example, if the control
1093 monitors a file and changes appearance when the monitored file changes.</Para>
1094 <Para>Front Panel configuration files are placed in the
1095 <Symbol Role="Variable">app_root</Symbol><Filename>/dt/appconfig/types/</Filename><Symbol Role="Variable">language</Symbol> directory. The naming convention is
1096 <Symbol Role="Variable">name</Symbol><Filename>.fp</Filename>.</Para>
1097 <Para>If you supply a configuration file containing a control, the user can add the
1098 control to a subpanel by dropping the <Filename>*.fp</Filename> file on the Install Icon control in
1099 the subpanel.</Para>
1100 <Para>For example, the following definition can be placed in a Front Panel
1101 configuration file in the application group. If the user drops this file on an
1102 Install Icon control in a subpanel, a control is created in the subpanel that runs
1103 a single instance of the BestTextEditor application. If BestTextEditor is already
1104 running, the window is moved to the top of the window stack in the current
1105 workspace.</Para>
1106 <programlisting>CONTROL BestTextEditorControl
1107 {
1108  TYPE    icon
1109  ICON    BTEFPanel
1110  PUSH_RECALL    True
1111  CLIENT_NAME    BTEd
1112  PUSH_ACTION    BTEditor
1113  DROP_ACTION    BTEditor
1114  HELP_STRING    Starts the BestTextEditor application.
1115 }
1116 </ProgramListing>
1117 <Para>For additional information about creating Front Panel configuration files, see:</Para>
1118 <ItemizedList Remap="Bullet1">
1119 <ListItem>
1120 <Para><!--Original XRef content: 'Chapter&numsp;13, &xd2;Advanced Front Panel Customization'--><XRef Role="ChapNumAndTitle" Linkend="SAG.FrPC.div.1"></Para>
1121 </ListItem>
1122 <ListItem>
1123 <Para>The <Filename MoreInfo="RefEntry">dtfpfile(4)</Filename> man page</Para>
1124 </ListItem>
1125 </ItemizedList>
1126 </Sect3>
1127 </Sect2>
1128 </Sect1>
1129 <Sect1 Id="SAG.RegAp.div.30">
1130 <Title Id="SAG.RegAp.mkr.28">Step 9: Registering the Application Using dtappintegrate<IndexTerm><Primary>dtappintegrate</Primary></IndexTerm><IndexTerm><Primary>registration</Primary><Secondary>dtappintegrate</Secondary></IndexTerm></Title>
1131 <Note>
1132 <Para>For an example of registering an application, see
1133 <!--Original XRef content: 'Step&numsp;8'--><XRef Role="Step" Linkend="SAG.RegAp.mkr.13"> of
1134 <!--Original XRef content: '&xd2;Example of
1135 Creating a Registration Package'--><XRef Role="SectionTitle" Linkend="SAG.RegAp.div.38"> on
1136 <!--Original XRef content: 'page&numsp;83'--><XRef Role="PageNum" Linkend="SAG.RegAp.mkr.23">.</Para>
1137 </Note>
1138 <Para>Once you've created a registration package under an application root, you are
1139 ready to perform the actual application registration.</Para>
1140 <Para>Application registration creates links between the registration package and the
1141 directories located along the desktop search paths (see
1142 <!--Original XRef content: '&xd2;How dtappintegrate
1143 Integrates Applications&xd3; on page&numsp;76'--><XRef Role="SecTitleAndPageNum" Linkend="SAG.RegAp.div.33">).</Para>
1144 <Sect2 Id="SAG.RegAp.div.31" Role="Procedure">
1145 <Title>To Register an Application with dtappintegrate</Title>
1146 <Para>If the application is desktop-smart, <Command>dtappintegrate</Command> is usually run
1147 automatically as the final step in the installation process. If it is not run
1148 automatically, or if you have created the configuration files to integrate a non-
1149 desktop smart application, then you can run <Command>dtappintegrate</Command> manually.</Para>
1150 <OrderedList>
1151 <ListItem>
1152 <Para>Log in as root.</Para>
1153 </ListItem>
1154 <ListItem>
1155 <Para>Run the command:</Para>
1156 <ProgramListing>/usr/dt/bin/dtappintegrate -s <Symbol Role="Variable">app_root</Symbol></ProgramListing>
1157 <Para>where <Symbol Role="Variable">app_root</Symbol> is the desktop application root directory. For more
1158 information, see the <Filename MoreInfo="RefEntry">dtappintegrate</Filename>(1) man page.</Para>
1159 </ListItem>
1160 <ListItem>
1161 <Para>Open the Desktop_Tools application group and double-click Reload
1162 Applications.</Para>
1163 </ListItem>
1164 <ListItem>
1165 <Para>Verify that the application is properly registered:</Para>
1166 <OrderedList>
1167 <ListItem>
1168 <Para>Display the top level of the Application Manager. The new application
1169 group should appear in the Application Manager.</Para>
1170 </ListItem>
1171 <ListItem>
1172 <Para>Open the application group and double-click the action icon.</Para>
1173 </ListItem>
1174 </OrderedList>
1175 </ListItem>
1176 </OrderedList>
1177 <Sect3 Id="SAG.RegAp.div.32">
1178 <Title>Syntax and Options for dtappintegrate<IndexTerm><Primary>dtappintegrate</Primary><Secondary>syntax</Secondary></IndexTerm></Title>
1179 <ProgramListing>dtappintegrate -s <Symbol Role="Variable">app_root</Symbol> [-t <Symbol Role="Variable">target_path</Symbol> ] [-l <Symbol Role="Variable">language</Symbol> ] [-u]</ProgramListing>
1180 <InformalTable>
1181 <TGroup Cols="2" colsep="0" rowsep="0">
1182 <colspec colwidth="106*">
1183 <colspec colwidth="422*">
1184 <TBody>
1185 <Row>
1186 <Entry><Para><literal>-s</literal> <Symbol Role="Variable">app_root</Symbol></Para></Entry>
1187 <Entry><Para>Required parameter. Specifies the application root
1188 under which the appication has been installed.</Para></Entry>
1189 </Row>
1190 <Row>
1191 <Entry><Para><literal>-t</literal> <Symbol Role="Variable">target_path</Symbol></Para></Entry>
1192 <Entry><Para>Optional parameter, defaults to the system location
1193 <Command>/etc/dt/appconfig.</Command> Specifies the location to which
1194 the desktop configuration files are linked. You must
1195 use a location on the application search path.</Para></Entry>
1196 </Row>
1197 <Row>
1198 <Entry><Para><literal>-l</literal> <Symbol Role="Variable">language</Symbol></Para></Entry>
1199 <Entry><Para>Optional parameter, defaults to all languages. Specifies
1200 which language-dependent desktop configuration files
1201 to integrate.</Para></Entry>
1202 </Row>
1203 <Row>
1204 <Entry><Para><Filename>-u</Filename></Para></Entry>
1205 <Entry><Para>Optional parameter. Un-integrates the application,
1206 removing all the links set up during integration.</Para></Entry>
1207 </Row>
1208 </TBody>
1209 </TGroup>
1210 </InformalTable>
1211 </Sect3>
1212 </Sect2>
1213 <Sect2 Id="SAG.RegAp.div.33">
1214 <Title Id="SAG.RegAp.mkr.29">How dtappintegrate Integrates Applications<IndexTerm><Primary>symbolic links</Primary><Secondary>created during registration</Secondary></IndexTerm><IndexTerm><Primary>dtappintegrate</Primary><Secondary>functionality</Secondary></IndexTerm></Title>
1215 <Para>The function of <Command>dtappintegrate</Command> is to set up links between the installed files
1216 and the locations where the desktop looks for configuration files.</Para>
1217 <Sect3 Id="SAG.RegAp.div.34">
1218 <Title>Actions and Data Types<IndexTerm><Primary>actions</Primary><Secondary>integrated with dtappintegrate</Secondary></IndexTerm><IndexTerm><Primary>data types</Primary><Secondary>integrated with dtappintegrate</Secondary></IndexTerm></Title>
1219 <Para><Command>dtappintegrate</Command> creates symbolic links from the action and data type
1220 definition files in the registration package to the system-wide directory along
1221 the action database search path. This is done by creating links from</Para>
1222 <ProgramListing><Symbol Role="Variable">app_root</Symbol>/dt/appconfig/types/<Symbol Role="Variable">language</Symbol>/*.dt</ProgramListing>
1223 <Para>to</Para>
1224 <ProgramListing>/etc/dt/appconfig/types/<Symbol Role="Variable">language</Symbol><Filename>/*</Filename>.dt</ProgramListing>
1225 </sect3>
1226 <Sect3 Id="SAG.RegAp.div.34a">
1227 <Title>Information Libraries<IndexTerm><Primary>infolibs</Primary><Secondary>integrated with dtappintegrate</Secondary></IndexTerm></Title>
1228 <Para><Command>dtappintegrate</Command> creates symbolic links from the information
1229 libraries (infolibs) in the registration package to the system-wide directory along
1230 the infolib search path. This is done by creating links from
1231 </Para>
1232 <programlisting><Symbol Role="Variable">app_root</Symbol>/dt/infolib/<Symbol Role="Variable">language</Symbol>/*.dti
1233 </ProgramListing>
1234 <Para>to</Para>
1235 <programlisting>/etc/dt/infolib/<Symbol Role="Variable">language</Symbol>/*.dti
1236 </ProgramListing>
1237 </sect3>
1238 <Sect3 Id="SAG.RegAp.div.35">
1239 <Title>Help Files<IndexTerm><Primary>help files</Primary><Secondary>integrated with dtappintegrate</Secondary></IndexTerm></Title>
1240 <Para><Command>dtappintegrate</Command> creates symbolic links from the help files in the registration
1241 package to the system-wide directory along the help search path. This is done
1242 by creating links from</Para>
1243 <ProgramListing><Symbol Role="Variable">app_root</Symbol>/dt/appconfig/help/<Symbol Role="Variable">language</Symbol>/<Symbol Role="Variable">help_file.</Symbol>sdl</ProgramListing>
1244 <Para>to</Para>
1245 <ProgramListing>/etc/dt/appconfig/help/<Symbol Role="Variable">language</Symbol>/<Symbol Role="Variable">help_file.</Symbol>sdl</ProgramListing>
1246 </Sect3>
1247 <Sect3 Id="SAG.RegAp.div.36">
1248 <Title>Icon Files<IndexTerm><Primary>icons</Primary><Secondary>integrated with dtappintegrate</Secondary></IndexTerm></Title>
1249 <Para><Command>dtappintegrate</Command> creates symbolic links from the icon files in the registration
1250 package to the system-wide directory along the icon search path. This is done
1251 by creating links from</Para>
1252 <ProgramListing><Symbol Role="Variable">app_root</Symbol>/dt/appconfig/icons/<Symbol Role="Variable">language</Symbol>/<Symbol Role="Variable">icon_files</Symbol></ProgramListing>
1253 <Para>to</Para>
1254 <ProgramListing>/etc/dt/appconfig/icons/<Symbol Role="Variable">language</Symbol>/<Symbol Role="Variable">icon_files</Symbol></ProgramListing>
1255 </Sect3>
1256 <Sect3 Id="SAG.RegAp.div.37">
1257 <Title>Application Group<IndexTerm><Primary>application groups</Primary><Secondary>integrated with dtappintegrate</Secondary></IndexTerm></Title>
1258 <Para>To place the application group for the application into the top level of
1259 Application Manager, <Command>dtappintegrate</Command> creates a link between the application
1260 group directory in the registration package and the system-wide location along
1261 the application search path. This is done by creating links from the directory</Para>
1262 <ProgramListing><Symbol Role="Variable">app_root</Symbol>/dt/appconfig/appmanager/<Symbol Role="Variable">language</Symbol>/<Symbol Role="Variable">appgroup_name</Symbol></ProgramListing>
1263 <Para>to</Para>
1264 <ProgramListing>/etc/dt/appconfig/appmanager/<Symbol Role="Variable">language</Symbol>/<Symbol Role="Variable">appgroup_name</Symbol></ProgramListing>
1265 </Sect3>
1266 </Sect2>
1267 </Sect1>
1268 <Sect1 Id="SAG.RegAp.div.38">
1269 <Title Id="SAG.RegAp.mkr.30">Example of Creating a Registration Package<IndexTerm><Primary>registration</Primary><Secondary>example</Secondary></IndexTerm><IndexTerm><Primary>registration package</Primary><Secondary>example of creating</Secondary></IndexTerm></Title>
1270 <Para>The following steps create a registration package for an existing, non-desktop
1271 smart application named BestTextEditor.</Para>
1272 <Sect2 Id="SAG.RegAp.div.39">
1273 <Title>Information You Need to Know About ``BestTextEditor''</Title>
1274 <Para>The example assumes the following facts about the BestTextEditor application:</Para>
1275 <ItemizedList Remap="Bullet1">
1276 <ListItem>
1277 <Para>It was installed into the directory <Filename>/usr/BTE</Filename>.</Para>
1278 </ListItem>
1279 <ListItem>
1280 <Para>The user's session language is the default value, <Command>C</Command>.</Para>
1281 </ListItem>
1282 <ListItem>
1283 <Para>The command line to start BestTextEditor is:</Para>
1284 <ProgramListing>BTEd [<Symbol Role="Variable">filename</Symbol>]</ProgramListing>
1285 <Para>where <Symbol Role="Variable">filename</Symbol> is the name of the data file to open in the new window.
1286 BestTextEditor creates its own window&mdash;that is, it does not run inside a
1287 terminal emulator window.</Para>
1288 </ListItem>
1289 <ListItem>
1290 <Para>BestTextEditor creates and uses two types of data files:</Para>
1291 <ItemizedList Remap="Bullet2">
1292 <ListItem>
1293 <Para>Documentation files. They use the naming convention <Filename>*.bte</Filename>.
1294 BestTextEditor provides a command line for printing its <Filename>.bte</Filename> data files.
1295 The syntax of this command is:</Para>
1296 <ProgramListing>BTEPrint [-d <Symbol Role="Variable">destination</Symbol>] [-s] <Symbol Role="Variable">filename</Symbol></ProgramListing>
1297 <Para>where:</Para>
1298 <variablelist>
1299 <varlistentry><term><literal>-d</literal> <Symbol Role="Variable">destination</Symbol></term>
1300 <listitem>
1301 <para>Specifies destination printer.
1302 </para>
1303 </listitem>
1304 </varlistentry>
1305 <varlistentry><term><literal>-s</literal></term>
1306 <listitem>
1307 <para>Specifies silent printing. The application's print dialog
1308 box is not displayed.
1309 </para>
1310 </listitem>
1311 </varlistentry>
1312 <varlistentry><term><Symbol Role="Variable">filename</Symbol></term>
1313 <listitem>
1314 <para>Specifies the file to be printed.
1315 </para>
1316 </listitem>
1317 </varlistentry>
1318 </variablelist>
1319 </ListItem>
1320 <ListItem>
1321 <Para>Template files. They use the naming convention <Filename>*.tpl</Filename>. Template files
1322 cannot be printed.</Para>
1323 </ListItem>
1324 </ItemizedList>
1325 </ListItem>
1326 <ListItem>
1327 <Para>The existing, non-desktop app-defaults files for BestTextEditor contain
1328 resources for interface fonts and foreground and background colors.</Para>
1329 </ListItem>
1330 <ListItem>
1331 <Para>An online help volume for BestTextEditor was created using the desktop
1332 Help Developer's Kit. When the online help volume was built, it used the
1333 following source files:</Para>
1334 <programlisting>&hellip;/BTEHelp.htg
1335 &hellip;/graphics/BTE1.xwd
1336 &hellip;/graphics/BTE2.xwd
1337 </Programlisting>
1338 <Para>and generated the file &hellip;<Filename>/</Filename><Filename>BTEHelp.sdl</Filename>.</Para>
1339 </ListItem>
1340 </ItemizedList>
1341 <Sect3 Id="SAG.RegAp.div.40">
1342 <Title>Steps to Registering ``BestTextEditor''</Title>
1343 <Para>The following step-wise procedure registers BestTextEditor.</Para>
1344 <OrderedList>
1345 <ListItem>
1346 <Para><Emphasis Role="Lead-in" Id="SAG.RegAp.mkr.31">Modify font and color resources.</Emphasis></Para>
1347 <Para>In BestTextEditor's app-defaults file, remove resources that set:</Para>
1348 <ItemizedList Remap="Bullet2">
1349 <ListItem>
1350 <Para>Fonts for text.</Para>
1351 </ListItem>
1352 <ListItem>
1353 <Para>Colors for foreground and background.</Para>
1354 </ListItem>
1355 </ItemizedList>
1356 </ListItem>
1357 <ListItem>
1358 <Para><Emphasis Role="Lead-in" Id="SAG.RegAp.mkr.32">Create the application root.</Emphasis></Para>
1359 <Para>Create the directory:</Para>
1360 <ProgramListing>/desktop_approots/BTE</ProgramListing>
1361 <Para>If you are integrating an existing application, you should create the
1362 application root directory elsewhere than in the installation location for the
1363 application; otherwise, the configuration files you create may be removed
1364 when you update the application.</Para>
1365 </ListItem>
1366 <ListItem>
1367 <Para><Emphasis Role="Lead-in" Id="SAG.RegAp.mkr.33">Create the registration package directories</Emphasis>.</Para>
1368 <Para>Create these directories:</Para>
1369 <ProgramListing><Filename>/desktop_approots/BTE/dt/appconfig/types/C</Filename>
1370 <Filename>/desktop_approots/BTE/dt/appconfig/help/C</Filename>
1371 <Filename>/desktop_approots/BTE/dt/appconfig/icons/C</Filename>
1372 <Filename>/desktop_approots/BTE/dt/appconfig/appmanager/C/BestTextEditor</Filename></ProgramListing>
1373 </ListItem>
1374 <ListItem>
1375 <Para><Emphasis Role="Lead-in" Id="SAG.RegAp.mkr.34">Create the actions and data types for the application.</Emphasis></Para>
1376 <orderedlist>
1377 <ListItem>
1378 <Para>Create the configuration file for the action and data type definitions:</Para>
1379 <ProgramListing>/desktop_approots/BTE/dt/appconfig/types/C/BTE.dt</ProgramListing>
1380 </ListItem>
1381 <ListItem>
1382 <Para>Create the action definition for running BestTextEditor:</Para>
1383 <programlisting>ACTION BTEditor
1384 {
1385   WINDOW_TYPE    NO_STDIO
1386   ICON    BTERun
1387   DESCRIPTION    Double-click this icon or drop a BTE data \
1388       file on it to run BestTextEditor.
1389   EXEC_STRING    /usr/BTE/BTEd &percnt;Arg_1&percnt;
1390 }
1391 </programlisting>
1392 </ListItem>
1393 <ListItem>
1394 <Para>Create the data type for <Command>*.bte</Command> files:</Para>
1395 <programlisting>DATA_ATTRIBUTES BTEDataFile
1396 {
1397   DESCRIPTION    BestTextEditor data file.
1398   ICON    BTEData
1399   ACTIONS    Open,Print
1400 }
1401
1402 DATA_CRITERIA BTEDataFileCriteria1
1403 {
1404   DATA_ATTRIBUTES_NAME      BTEDataFile
1405   NAME_PATTERN      *.bte
1406   MODE      f
1407 }
1408 </programlisting>
1409 </ListItem>
1410 <ListItem>
1411 <Para>Create the data type for <Filename>*.tpl</Filename> files:</Para>
1412 <programlisting>DATA_ATTRIBUTES BTETemplateFile
1413 {
1414   DESCRIPTION    BestTextEditor template file.
1415   ICON    BTETempl
1416   ACTIONS    Open
1417 }
1418
1419 DATA_CRITERIAL BTETemplateFileCriteria1
1420 {
1421   DATA_ATTRIBUTES_NAME      BTETemplateFile
1422   NAME_PATTERN      *.tpl
1423   MODE      f
1424 }
1425 </programlisting>
1426 </ListItem>
1427 <ListItem>
1428 <Para>Create the Open action for <Filename>*.bte</Filename> files.</Para>
1429 <programlisting>ACTION Open
1430 {
1431   ARG_TYPE   BTEDataFile
1432   TYPE   MAP
1433   MAP_ACTION   BTEditor
1434 }
1435 </programlisting>
1436 </ListItem>
1437 <ListItem>
1438 <Para>Create the Print action for <Filename>*.bte</Filename> files.</Para>
1439 <Para>Here are simple Print actions that will print the data files. These actions
1440 require a value for the LPDEST environment variable and ignore the <Command>-s</Command> print option. (If LPDEST isn't set, the action may fail.)</Para>
1441 <programlisting>ACTION Print
1442 {
1443   ARG_TYPE    BTEDataFile
1444   TYPE    MAP
1445   MAP_ACTION    BTEPrintData
1446 }
1447 ACTION BTEPrintData
1448 }
1449   WINDOW_TYPE     NO_STDIO
1450   EXEC_STRING     BTEPrint -d $LPDEST &percnt;Arg_1&percnt;
1451 }
1452 </programlisting>
1453 <Para>Here is another version of the BTEPrintData action and an accompanying
1454 script. Together, they handle situations where LPDEST is not set or if
1455 silent printing is requested.</Para>
1456 <programlisting>ACTION BTEPrintData
1457 {
1458   WINDOW_TYPE    NO_STDIO
1459   EXEC_STRING    /usr/BTE/bin/BTEenvprint &percnt;(File)Arg_1&percnt;
1460 }
1461 </programlisting>
1462 <Para>The contents of the <Filename>/usr/BTE/bin/BTEenvprint</Filename> script is:</Para>
1463 <programlisting># BTEenvprint
1464 #!/bin/sh
1465 DEST=&rdquo;&rdquo;
1466 SILENT=&rdquo;&rdquo;
1467 if [ $LPDEST ]; then
1468   DEST=&rdquo;-d $LPDEST&rdquo;
1469 fi
1470 <Command>BTEPrint $DEST $SILENT $1</Command>
1471 </programlisting>
1472 </ListItem>
1473 <ListItem>
1474 <Para>Create the Open action for <Command>*.tpl</Command> files:</Para>
1475 <programlisting>ACTION Open
1476 {
1477   ARG_TYPE   BTETemplateFile
1478   TYPE   MAP
1479   MAP_ACTION   BTEditor
1480 }
1481 </programlisting>
1482 </ListItem>
1483 <ListItem>
1484 <Para>Create the Print action for <Filename>*.tpl</Filename> files:</Para>
1485 <programlisting>ACTION Print
1486 {
1487   ARG_TYPES    BTETemplateFile
1488   TYPE    MAP
1489   MAP_ACTION    NoPrint
1490 }
1491 </programlisting>
1492 <Para>NoPrint is a built-in action that displays a dialog box telling the user the
1493 file cannot be printed.</Para>
1494 </ListItem>
1495 </orderedlist>
1496 </ListItem>
1497 <ListItem>
1498 <Para><Emphasis Role="Lead-in" Id="SAG.RegAp.mkr.35">Put the help files into the registration package</Emphasis>.</Para>
1499 <orderedlist>
1500 <ListItem>
1501 <Para>Place the help files in the following locations:</Para>
1502 <programlisting>/desktop_approots/BTE/dt/appconfig/help/C/BTEHelp.sdl
1503 /desktop_approots/BTE/dt/appconfig/help/C/graphics/BTE1.xwd
1504 /desktop_approots/BTE/dt/appconfig/help/C/graphics/BTE2.xwd
1505 </programlisting>
1506 </ListItem>
1507 <ListItem>
1508 <Para>Create the file:</Para>
1509 <programlisting>/desktop_approots/BTE/dt/appconfig/types/C/BTEhelp.dt
1510 </programlisting>
1511 <Para>Put the following action definition in the file:</Para>
1512 <programlisting>ACTION BTEHelp
1513 {
1514   WINDOW_TYPE    NO_STDIO
1515   EXEC_STRING    /usr/dt/bin/dthelpview -helpVolume \
1516       BTEHelp.sdl
1517   DESCRIPTION    Opens the BestTextEditor help volume.
1518 }
1519 </programlisting>
1520 </ListItem>
1521 </orderedlist>
1522 </ListItem>
1523 <ListItem>
1524 <Para><Emphasis Role="Lead-in" Id="SAG.RegAp.mkr.36">Create icons for the application.</Emphasis></Para>
1525 <Para>Use Icon Editor to create the icons. Use these size guidelines:</Para>
1526 <InformalTable>
1527 <TGroup Cols="2" colsep="0" rowsep="0">
1528 <colspec colwidth="117*">
1529 <colspec colwidth="411*">
1530 <THead>
1531 <Row>
1532 <Entry><Para>Name</Para></Entry>
1533 <Entry><Para>Size</Para></Entry>
1534 </Row>
1535 </THead>
1536 <TBody>
1537 <Row>
1538 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.t.pm</Filename></Para></Entry>
1539 <Entry><Para>16 by 16</Para></Entry>
1540 </Row>
1541 <Row>
1542 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.m.pm</Filename></Para></Entry>
1543 <Entry><Para>32 by 32</Para></Entry>
1544 </Row>
1545 <Row>
1546 <Entry><Para><Symbol Role="Variable">basename</Symbol><Filename>.l.pm</Filename></Para></Entry>
1547 <Entry><Para>64 by 64</Para></Entry>
1548 </Row>
1549 </TBody>
1550 </TGroup>
1551 </InformalTable>
1552 <Para>Create these icon files in the directory
1553 <Filename>/desktop_approots/BTE/dt/appconfig/icons/C</Filename>:</Para>
1554 <ItemizedList Remap="Bullet2">
1555 <ListItem>
1556 <Para>Icons to represent the action that runs the application: <Filename>BTERun.t.pm</Filename>,
1557 <Filename>BTERun.m.pm</Filename>, <Filename>BTERun.l.pm</Filename></Para>
1558 </ListItem>
1559 <ListItem>
1560 <Para>Icons to represent <Filename>*.bte</Filename> files: <Filename>BTEData.t.pm</Filename>, <Filename>BTEData.m.pm</Filename>,</Para>
1561 </ListItem>
1562 <ListItem>
1563 <Para>Icons to represent <Filename>*.tpl</Filename> files: <Filename>BTETempl.t.pm</Filename>, <Filename>BTETempl.m.pm</Filename></Para>
1564 </ListItem>
1565 <ListItem>
1566 <Para>Icons to represent the application group (used in step 7): <Filename>BTEApp.t.pm</Filename>,
1567 <Filename>BTEApp.m.pm</Filename></Para>
1568 </ListItem>
1569 </ItemizedList>
1570 </ListItem>
1571 <ListItem>
1572 <Para><Emphasis Role="Lead-in" Id="SAG.RegAp.mkr.37">Create the application group</Emphasis>.<IndexTerm><Primary>application groups</Primary><Secondary>example of creating</Secondary></IndexTerm>
1573 </Para>
1574 <orderedlist>
1575 <ListItem>
1576 <Para>If you haven't already done so, create the directory.</Para>
1577 <ProgramListing>/desktop_approots/BTE/dt/appconfig/appmanager/C/BestTextEditor</ProgramListing>
1578 </ListItem>
1579 <ListItem>
1580 <Para>This step is optional. It provides a unique icon for the application group
1581 icon by creating a data type and associated actions for the application
1582 group. If you omit this step, the application group will use the default
1583 icon.</Para>
1584 <Para>Add the following data type and action definitions to the file
1585 <Filename>/desktop_approots/BTE/dt/appconfig/types/C/BTE.dt</Filename>.The
1586 data type specifies the icon to be used by the BestTextEditor application
1587 group. The actions provide the same Open and Print behavior as the
1588 built-in application groups.</Para>
1589 <programlisting>DATA_ATTRIBUTES BestTextEditorAppGroup
1590 {
1591   ACTIONS   OpenInPlace,OpenNewView
1592   ICON   BTEApp
1593 }
1594 DATA_CRITERIA BestTextEditorAppGroupCriterial
1595 {
1596   DATA_ATTRIBUTES_NAME      BestTextEditorAppGroup
1597   MODE      d
1598   PATH_PATTERN      */appmanager/*/BestTextEditor
1599 }
1600 ACTION Open
1601 {
1602   ARG_TYPE   BestTextEditorAppGroup
1603   TYPE   MAP
1604   MAP_ACTION   OpenAppGroup
1605 }
1606 ACTION Print
1607 {
1608   ARG_TYPE   BestTextEditorAppGroup
1609   TYPE   MAP
1610   MAP_ACTION   PrintAppGroup
1611 }
1612 </programlisting>
1613 </ListItem>
1614 <ListItem>
1615 <Para>Create an icon in the application group that will start the application. To
1616 do this, create the file:</Para>
1617 <ProgramListing><Filename>/desktop_approots/BTE/dt/appconfig/appmanager/C/BestTextEditor/BTEditor</Filename></ProgramListing>
1618 <Para>and make the file executable.</Para>
1619 </ListItem>
1620 <ListItem>
1621 <Para>Create the action file in the application group that will open the help
1622 volume. To do this, create the file:</Para>
1623 <ProgramListing><Filename>/desktop_approots/BTE/dt/appconfig/appmanager/C/BestTextEditor/BTEHelp</Filename></ProgramListing>
1624 <Para>and make the file executable.</Para>
1625 </ListItem>
1626 <ListItem>
1627 <Para>Put other files into the application group; for example, &ldquo;read me&rdquo; files,
1628 sample data and template files.</Para>
1629 </ListItem>
1630 </orderedlist>
1631 </listitem>
1632 <ListItem>
1633 <Para><Emphasis Role="Lead-in" Id="SAG.RegAp.mkr.38">Register the application.</Emphasis></Para>
1634 <Para>In a terminal emulator window:</Para>
1635 <orderedlist>
1636 <ListItem>
1637 <Para>Log in as root.</Para>
1638 </ListItem>
1639 <ListItem>
1640 <Para>Run the command:</Para>
1641 <ProgramListing>/usr/dt/bin/dtappintegrate -s /desktop_approots/BTE</ProgramListing>
1642 </ListItem>
1643 <ListItem>
1644 <Para>Open the Desktop_Tools application group and double-click Reload
1645 Applications.
1646 </Para>
1647 </ListItem>
1648 </OrderedList>
1649 </ListItem>
1650 </OrderedList>
1651 </Sect3>
1652 </Sect2>
1653 </Sect1>
1654 </Chapter>
1655 <!--fickle 1.14 mif-to-docbook 1.7 01/02/96 06:16:56-->