# Basic Application Integration

Basic application integration is a set of highly recommended tasks you should perform.

PG.basc1.mkr.2
PG.basc1.mkr.3
PG.basc1.mkr.6
PG.basc1.mkr.8
PG.basc1.mkr.9

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® messaging, and programmatic access to the actions and data typing database.

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.

## Basic Integration Features

Basic application integration provides these features for end users:

- A graphical way to locate and start your application on the desktop

  Your application will provide a desktop
  registration package, and your installation script will automatically register your application.

  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.

- The ability to recognize and manipulate your application's data files

  Your application will provide data types for its data files.

  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.

- Easy font and color selection using Style Manager

  Your application will change interface fonts and background, foreground, and shadow colors dynamically.

  The desktop defines general interface font and color resources that are used if no corresponding application-specific resources exist.

Basic integration provides these advantages to system administrators:

- Easy installation and registration

  Upon installation, the application is automatically registered. The system administrator has little or no additional work to do.

- Easy ongoing administration

  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.

### Organization of Basic Integration Information

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 “Registering an Application” in the Common Desktop Environment: Advanced User's and System Administrator's Guide.

This chapter guides you to that information and contains additional information specific to application programmers.

## Basic Integration Tasks

These are the general tasks involved in basic integration:

- Modify any application resources that set fonts and colors. This allows users to change the application's interface fonts and colors using Style Manager.

  See the section on modifying font and color resources in the chapter “Registering an Application” in the Common Desktop Environment: Advanced User's and System Administrator's Guide.

- Create the registration package for your application.

  See the text, PG.basc1.mkr.11 and “Registering an Application” in the Common Desktop Environment: Advanced User's and System Administrator's Guide .

- Modify your application's installation script to install the registration package files and perform the registration procedure.

  See the section on registering the application using `dtappintegrate` in the chapter “Registering an Application” in the Common Desktop Environment: Advanced User's and System Administrator's Guide.

- 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 `lp` service.

### Levels of Printing Integration

The printing functionality available to the user depends on the level of integration you use. There are three levels of integration:

- Complete integration. See PG.basc1.mkr.6.

  You should do complete integration if you have the ability to modify the application's source code.

  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 PG.basc1.mkr.7).

- Partial integration. See PG.basc1.mkr.8.

  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.

  When you do partial integration, your application provides a subset of full- integration functionality. For example, by using the `LPDEST` environment variable, your application's printing mechanism will obtain the print destination from the drop zone.

- No integration. See PG.basc1.mkr.9.

  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.

### Complete Print Integration

To do complete print integration, your application must:

- Provide a Print action

- Use (dereference) the four desktop printing environment variables

#### Desktop Printing Environment Variables

To have fully integrated printing, your application must dereference the following four environment variables. The `LPDEST` variable is particularly important. It provides the ability for the user to choose the print destination by using a particular printer drop zone.

Printing Variable | Description
`LPDEST` | 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.
`DTPRINTUSERFILENAME` | 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.
`DTPRINTSILENT` | 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.
`DTPRINTFILEREMOVE` | 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.

#### A Fully Integrated Print Action

The Print action is part of the registration package, provided in a configuration file, app_root`/dt/appconfig/types/language/`name`.dt`.

If your print action executes a program that dereferences the four environment variables indicated in 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.

For example, the following print action is specific for a data type named `ThisAppData`:

    Print
    {
      ARG_TYPE    ThisAppData
      EXEC_STRING print_command -file %(file)Arg_1%
    }

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 “Desktop Printing Environment Variables“ for the default interpretation.)

    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
    }

#### Creating Print Actions for Filtered Data or Data Ready to Print

The desktop print utility `/usr/dt/dtlp` provides functionality on top of the `lp` subsystem. It gathers `lp` print options and prints the specified file.

Your application can use `dtlp` if either of the following conditions are true:

- The data files do not need to be processed before they are sent to a printer.

- Or, your application provides a filter for converting its data files to a ready-to-print form.

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,

    Print
    {
     ARG_TYPE    ThisAppData
     EXEC_STRING app_name -print %Arg_1%
    }

Note that the `dtlp` services are intended for printing through the action system (as opposed to printing through the application). For detailed information about `dtlp`, see the `dtlp`(1) reference page.

If the file is ready to print, the Print action runs `dtlp` in the `EXEC_STRING.` For example:

    Print
    {
     ARG_TYPE    ThisAppData
     EXEC_STRING dtlp %Arg_1%

    }

If the application provides a conversion filter, the filter must be run before running `dtlp.` For example:

    Print
    {
     ARG_TYPE    MyAppData
     EXEC_STRING /bin/sh `cat %Arg_1%| filter_name | dtlp`
    }

where filter_name is the name of the print filter.

### Partial Print Integration

To do partial print integration, your application must provide:

- A Print action

- The extent to which printing is integrated depends on which, if any, of the printing environment variables are handled by the action.

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.

#### Providing the Print Command for Partial Integration

To provide partial print integration, your application must provide a print command line of the form:

    print_command [options] -file filename

where options provides a mechanism for dereferencing none, some, or all of the printing environment variables (see pg.basc1.mkr.7).

The simplest form of this print command line omits options.

    print_command -file filename

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.

If your print command line provides additional command-line options that correspond to the desktop printing environment variables, you can provide additional integration.

For example, the following command line provides the ability to dereference `LPDEST`:

    print_command [-d destination] [-file filename]

where:

destination is the destination printer.

The next print command line provides options for dereferencing all four variables:

    print_command [-d destination] [-u user_file_name] [-s] [-e] -file filename

where:

user_file_name | The file name as seen by the user.
`-s` | Printing is silent (no Print dialog box is displayed).
`-e` | The file is removed after it is printed.

The dereferencing occurs in the action definition. See the section, pg.basc1.mkr.7 for more information.

#### Turning Environment Variables into Command Line Switches

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.

For example, this is a simple Print action that deferences `LPDEST`:

    Print
    {
      ARG_TYPE    data_type
      EXEC_STRING print_command -d $LPDEST -file %(file)Arg_1%
    }

However, this Print action may create unpredictable behavior if `LPDEST` is not set.

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.

For example, the following action and the script it uses properly handle all four environment variables:

    Print
      ARG_TYPE    data_type
      EXEC_STRING app_root/bin/envprint %(File)Arg_1%
    }

The contents of the `envprint` script follows:

    #!/bin/sh
    # envprint - sample print script
    DEST=””
    USERFILENAME=””
    REMOVE=””
    SILENT=””

    if [ $LPDEST ]; then
       DEST=”-d $LPDEST”
    fi

    if [ $DTPRINTUSERFILENAME ]; then
       USERFILENAME=”-u $DTPRINTUSERFILENAME”
    fi

    DTPRINTFILEREMOVE=echo $DTPRINTFILEREMOVE | tr “[:upper:]”
    “[:lower:]”`
    if [ “$DTPRINTFILEREMOVE” = “true” ]; then
       REMOVE=”-e”
    fi

    DTPRINTSILENT=`echo $DTPRINTSILENT | tr “[:upper:]” “[:lower:]”`
    if [ “$DTPRINTSILENT” = “true” ]; then
       SILENT=”-s”
    fi

    print_command $DEST $USERFILENAME $REMOVE $SILENT -file $1

### Nonintegrated Printing

If your application does not integrate printing with the desktop, users must open your application to properly print data files.

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.

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.

The
NoPrint action displays the
Unable to Print dialog box shown in PG.basc1.mkr.10.

#### Dialog box displayed by the built-in NoPrint action

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:

    DATA_ATTRIBUTES MySpreadSheet_Data1
    {
     —
    }

The following Print action maps to the NoPrint for this data type:

    ACTION Print
    {
     ARG_TYPE   MySpreadSheet_Data1
     TYPE       MAP
     MAP_ACTION NoPrint
    }

### Creating a Registration Package for Your Application

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 “Registering an Application” in the Common Desktop Environment: Advanced User's and System Administrator's Guide.