When an application is fully registered onto the desktop, it has:
Upon installation, your application is "registered" into the Application Manager and has its own application group.
Figure 4-1 Application groups at the top level of Application Manager
The application group for your application contains an icon the user can double-click to start your application.
Figure 4-2 An application group containing an icon to start the application
The user can use data file icons to:
Figure 4-3 A data file's pop-up menu containing ``Open'' and ``Print''
It can be difficult to administer an application when its configuration files are scattered among numerous directories. Therefore, the desktop allows an application to keep all its desktop configuration files gathered under a single directory. This grouping of files is called a registration package.
If the application is desktop smart, it supplies a registration package as part of its installation package. If you are a system administrator creating the configuration files yourself, you can create the registration package yourself.
The configuration files in the registration package are not available to the desktop because they are not located in the proper search path directories. The process of placing these files in the proper locations is called registering, or integrating, the application.
The desktop provides a tool, dtappintegrate, that performs the registration by creating symbolically linked representations of the files in the proper search path directories.
Many desktop-smart applications will automatically run dtappintegrate during the installation process. If you are a system administrator integrating an existing application, you can run it yourself after you've created the registration package.
Once an application is registered on a system's desktop, the application is available to all users on the system. If the system is configured as a desktop application server, the application will also be available to other systems throughout the network.
The dtappintegrate tool has a command-line option that reverses the process by breaking the links. This makes it easy to remove the application from the Application Manager so that it can be moved to a different application server or updated.
See "Step 1: Modifying Font and Color Resources".
See "Step 2: Creating the Desktop Application Root".
See "Step 3: Creating the Registration Package Directories"
See "Step 4: Creating the Actions and Data Types for the Application".
See "Step 5: Putting the Help Files in the Registration Package".
See "Step 6: Creating Icons for the Application".
See "Step 7: Creating the Application Group".
See "Step 8: Registering the Application Using dtappintegrate".
The desktop provides mechanisms for setting and manipulating interface fonts and window colors. In order for an application to use these mechanisms properly, you may have to modify the application's app-defaults file.
The desktop Style Manager will set interface fonts for applications created using OSF/Motif 1.2 (or later versions) if the application does not specify application-specific interface fonts.
Style Manager provides two fonts:
If you want the application to use the Style Manager fonts, you should remove any application resources that interface specify fonts. The desktop will automatically set the application's resources appropriately:
The easiest way to use the dynamic colors provided by the desktop is to remove any application color resources for background and foreground color.
The registration package files for the application are grouped beneath a directory called the application root, or app_root. The app_root directory used for the desktop configuration files can be the same directory as the application's installation app_root or some other location.
For example, suppose an application is installed under a directory /usr/BTE. This same directory could be used as the app_root for the desktop configuration files. However, if you are integrating an existing non-desktop smart application, it is recommended that you create a different desktop app_root directory. This will prevent the configuration files you create from being overwritten when you update the application.
For example, a system administrator might want to create a directory /etc/desktop_approots/BTE as the desktop app_root directory.
The registration package is the group of desktop configuration files used by the desktop to provide a graphical interface for the application.
Figure 4-4 A registration package beneath an application root directory
The major categories of configuration fields under the app_root/dt/appconfig directory are:
Figure 4-5 Application group at the top level of the Application Manager
The dtappintegrate tool operates only on the desktop configuration files in the types, help, icons, and appmanager directories. The application's binary executable, app-defaults, and message catalog files are administered separately.
Actions and data types provide a user interface for the application.
Place files containing actions and data types under the application root in the directory app_root/dt/appconfig/types/language. The default language is C.
Figure 4-6 Action and data type definition files
Create Action provides an easy-to-use interface with text fields that you fill in. However, the tool has certain limitations.
This requires you to learn the syntax for creating the definitions, but provides access to the full range of functionality.
For more information about Create Action, use its online help or see Chapter 9, "Creating Actions and Data Types Using Create Action."
The configuration file created by Create Action will be written to HomeDirectory/.dt/type/action_name.dt. The action file (the executable file with the same name as the action) is placed in your home directory.
Action and data type definition files must follow the naming convention name.dt.
You can place all your action and data type definitions in one file or distribute them among multiple files. For each file, use a file name that system administrators will easily connect with your application.
Action and data type names must be one word (no embedded spaces). You can use an underscore character. By convention, the first letter of the action or data type name is capitalized. Do not use an existing action name or file name. Use a name that advanced users and system administrators will easily connect with your application.
If you want the application's icon labeled with a different name than the action name, include a LABEL field in the action definition.
For more information about creating actions and data types, see:
If the application includes a desktop help volume (a help volume created with the desktop Help Developer's Kit), the help volume master file (*.sdl) should be placed in the directory app_root/appconfig/help/language.
Graphics used by the help files are usually placed in a graphics subdirectory. The graphics must be located in the same directory relative to the master help volume (*.sdl) file as when the help volume was created.
If the application does not provide a help volume, you can create one if you have the Help Developer's Kit.
There are two levels of integration of a help volume:
When desktop help is fully integrated, the help volume can be accessed from the application--for example, by on-item help and the Help menu. Full integration involves modification to the application's executables.
When desktop help is partially integrated, it is available from the top level of the Help Manager. However, you cannot access the help volume from the application's windows. You can also provide an action to access the help from the application group. The following example action displays the help volume located in the help master file MyApp.sdl:
ACTION OpenMyAppHelp
{
LABEL MyAppHelp
ARG_COUNT 0
TYPE COMMAND
WINDOW_TYPE NO_STDIO
EXEC_STRING /usr/dt/bin/dthelpview -helpVolume MyApp
DESCRIPTION Displays help for the MyApp application.
}
The desktop provides default icons for actions, data types, and application groups. However, you will probably want to create unique icons for the application.
Icons are placed in the directory app_root/dt/appconfig/icons/language.
Supply three sizes: tiny, medium, and large.
If your application supports multiple data types, you should provide a different icon for each data type.
Supply two sizes: tiny and medium.
Supply two sizes: tiny and medium.
.
If you do not provide bitmap files, the desktop maps the color specifications of the pixmap files into black and white. However, this mapping may not produce the appearance you want.
For more information about icons, see "Icon Image Files".
Once you have created the action and data type definitions for the application, you must create the configuration files responsible for creating what the user actually sees--the application group and its contents.
The application group is a directory at the top level of the Application Manager (see Figure 4-1).
There are three steps to creating the application group:
Figure 4-7 The appmanager directory
Figure 4-8 The application group name (<appgroup_name>)
The name can be any allowable file (directory) name. Use a name that describes the application.
If you want to provide a unique icon for the application group, you must create:
The attributes section of the definition specifies the icon to be used. The criteria section of the definition specifies that the data type be defined to any directory named Media_Tools that is a subdirectory of a directory named appmanager.DATA_ATTRIBUTES Media_ToolsAppgroup { ACTIONS OpenInPlace,OpenNewView ICON MediaTools DESCRIPTION Double-click to open the Media_Tools \ application group }DATA_CRITERIA Media_ToolsAppgroupCriteria1 { DATA_ATTRIBUTES_NAME Media_ToolsAppgroup MODE d PATH_PATTERN */appmanager/*/Media_Tools }
Figure 4-9 shows the relationship between the application group name and the data type definition. The PATH_PATTERN field in the data type definition connects a unique icon to the application group.
Figure 4-9 How an application group gets a unique icon
You should also create an Open and Print action for the application group data type:
OpenAppGroup and PrintAppGroup actions are built-in actions defined in /usr/dt/appconfig/types/language/dtappman.dt.ACTION Open { ARG_TYPE Media_ToolsAppGroup TYPE MAP MAP_ACTION OpenAppGroup }ACTION Print { ARG_TYPE Media_ToolsAppGroup TYPE MAP MAP_ACTION PrintAppGroup }
In addition to one or more action icons, the application group may contain:
An action icon is created by creating an executable file with the same name as the action it will run:
app_root/dt/appconfig/appmanager/appgroup_name/action_name
The file is called an action file, because its purpose is to create a visual representation of the underlying action.For example, if you've created an action named BestTextEditor that runs the BestTextEditor application, you would create an executable file named BestTextEditor. In File Manager and the Application Manager, the action file will use the icon image specified in the action definition.
Figure 4-10 illustrates the relationship between the action definition, action file, and actual entry in the Application Manager window.
Figure 4-10 The application icon is a file in the application group
You might want to create a Front Panel configuration file containing a control definition for your application if you want users to be able to install a control that behaves differently than the action icon--for example, if the control monitors a file and changes appearance when the monitored file changes.
Front Panel configuration files are placed in the app_root/dt/appconfig/types/language directory. The naming convention is name.fp.
If you supply a configuration file containing a control, the user can add the control to a subpanel by dropping the *.fp file on the Install Icon control in the subpanel.
For example, the following definition can be placed in a Front Panel configuration file in the application group. If the user drops this file on an Install Icon control in a subpanel, a control is created in the subpanel that runs a single instance of the BestTextEditor application. If BestTextEditor is already running, the window is moved to the top of the window stack in the current workspace.
CONTROL BestTextEditorControl
{
TYPE icon
ICON BTEFPanel
PUSH_RECALL True
CLIENT_NAME BTEd
PUSH_ACTION BTEditor
DROP_ACTION BTEditor
HELP_STRING Starts the BestTextEditor application.
}
For additional information about creating Front Panel configuration files,
see:
Once you've created a registration package under an application root, you are ready to perform the actual application registration.
Application registration creates links between the registration package and the directories located along the desktop search paths (see "How dtappintegrate Integrates Applications").
/usr/dt/bin/dtappintegrate -s app_root
where app_root is the desktop application root directory. For more information, see the dtappintegrate(1) man page.
a. Display the top level of the Application Manager. The new application group should appear in the Application Manager.
b. Open the application group and double-click the action icon.
dtappintegrate -s app_root [-t target_path ] [-l language ] [-u]
-s app_root Required parameter. Specifies the application root under which the appication has been installed.
-t target_path Optional parameter, defaults to the system location /etc/dt/appconfig. Specifies the location to which the desktop configuration files are linked. You must use a location on the application search path.
-l language Optional parameter, defaults to all languages. Specifies which language-dependent desktop configuration files to integrate.
app_root/dt/appconfig/types/language/*.dt
to
/etc/dt/appconfig/types/language/*.dt
app_root/dt/appconfig/help/language/help_file.sdl
to
/etc/dt/appconfig/help/language/help_file.sdl
app_root/dt/appconfig/icons/language/icon_files
to
/etc/dt/appconfig/icons/language/icon_files
app_root/dt/appconfig/appmanager/language/appgroup_name
to
/etc/dt/appconfig/appmanager/language/appgroup_name
BTEd {filename]
where filename is the name of the data file to open in the new window. BestTextEditor creates its own window--that is, it does not run inside a terminal emulator window.
BTEPrint [-d destination] [-s] filename
where:
... /BTEHelp.htg
... /graphics/BTE1.xwd
... /graphics/BTE2.xwd
and generated the file ... /BTEHelp.sdl.
In BestTextEditor's app-defaults file, remove resources that set:
Create the directory:
/desktop_approots/BTE
If you are integrating an existing application, you should create the application root directory elsewhere than in the installation location for the application; otherwise, the configuration files you create may be removed when you update the application.
Create these directories:
/desktop_approots/BTE/dt/appconfig/types/C
/desktop_approots/BTE/dt/appconfig/help/C
/desktop_approots/BTE/dt/appconfig/icons/C
/desktop_approots/BTE/dt/appconfig/appmanager/C/BestTextEditor
a. Create the configuration file for the action and data type definitions:
/desktop_approots/BTE/dt/appconfig/types/C/BTE.dt
b. Create the action definition for running BestTextEditor:
ACTION BTEditor
{
WINDOW_TYPE NO_STDIO
ICON BTERun
DESCRIPTION Double-click this icon or drop a BTE data \
file on it to run BestTextEditor.
EXEC_STRING /usr/BTE/BTEd %Arg_1%
}
c. Create the data type for *.bte files:
DATA_ATTRIBUTES BTEDataFile
{
DESCRIPTION BestTextEditor data file.
ICON BTEData
ACTIONS Open,Print
}
DATA_CRITERIA BTEDataFileCriteria1
{
DATA_ATTRIBUTES_NAME BTEDataFile
NAME_PATTERN *.bte
MODE f
}
d. Create the data type for *.tpl files:
DATA_ATTRIBUTES BTETemplateFile
{
DESCRIPTION BestTextEditor template file.
ICON BTETempl
ACTIONS Open
}
DATA_CRITERIAL BTETemplateFileCriteria1
{
DATA_ATTRIBUTES_NAME BTETemplateFile
NAME_PATTERN *.tpl
MODE f
}
e. Create the Open action for *.bte files.
ACTION Open
{
ARG_TYPE BTEDataFile
TYPE MAP
MAP_ACTION BTEditor
}
f. Create the Print action for *.bte files. Here are simple Print actions that will print the data files. These actions require a value for the LPDEST environment variable and ignore the -s print option. (If LPDEST isn't set, the action may fail.)
Here is another version of the BTEPrintData action and an accompanying script. Together, they handle situations where LPDEST is not set or if silent printing is requested.ACTION Print { ARG_TYPE BTEDataFile TYPE MAP MAP_ACTION BTEPrintData }ACTION BTEPrintData } WINDOW_TYPE NO_STDIO EXEC_STRING BTEPrint -d $LPDEST %Arg_1% }
ACTION BTEPrintData
{
WINDOW_TYPE NO_STDIO
EXEC_STRING /usr/BTE/bin/BTEenvprint %(File)Arg_1%
}
The contents of the /usr/BTE/bin/BTEenvprint script is:
# BTEenvprint
#!/bin/sh
DEST=""
SILENT=""
if [ $LPDEST ] ; then
DEST="-d $LPDEST"
fi
BTEPrint $DEST SILENT $1
g. Create the Open action for *.tpl files:
ACTION Open
{
ARG_TYPE BTETemplateFile
TYPE MAP
MAP_ACTION BTEditor
}
h. Create the Print action for *.tpl files:
ACTION Print
{
ARG_TYPES BTETemplateFile
TYPE MAP
MAP_ACTION NoPrint
}
NoPrint is a built-in action that displays a dialog box telling the user the file cannot be printed.
a. Place the help files in the following locations:
/desktop_approots/BTE/dt/appconfig/help/C/BTEHelp.sdl
/desktop_approots/BTE/dt/appconfig/help/C/graphics/BTE1.xwd
/desktop_approots/BTE/dt/appconfig/help/C/graphics/BTE2.xwd
b. Create the file:
/desktop_approots/BTE/dt/appconfig/types/C/BTEhelp.dt.
Put the following action definition in the file:
ACTION BTEHelp
{
WINDOW_TYPE NO_STDIO
EXEC_STRING /usr/dt/bin/dthelpview -helpVolume \
BTEHelp.sdl
DESCRIPTION Opens the BestTextEditor help volume.
}
Use Icon Editor to create the icons. Use these size guidelines:
a. If you haven't already done so, create the directory.
/desktop_approots/BTE/dt/appconfig/appmanager/C/BestTextEditor
b. This step is optional. It provides a unique icon for the application group icon by creating a data type and associated actions for the application group. If you omit this step, the application group will use the default icon.Add the following data type and action definitions to the file /desktop_approots/BTE/dt/appconfig/types/C/BTE.dt.The data type specifies the icon to be used by the BestTextEditor application group. The actions provide the same Open and Print behavior as the built-in application groups.
c. Create an icon in the application group that will start the application. To do this, create the file:DATA_ATTRIBUTES BestTextEditorAppGroup { ACTIONS OpenInPlace,OpenNewView ICON BTEApp {DATA_CRITERIA BestTextEditorAppGroupCriterial { DATA_ATTRIBUTES_NAME BestTextEditorAppGroup MODE d PATH_PATTERN */appmanager/*/BestTextEditor }ACTION Open { ARG_TYPE BestTextEditorAppGroup TYPE MAP MAP_ACTION OpenAppGroup }ACTION Print { ARG_TYPE BestTextEditorAppGroup TYPE MAP MAP_ACTION PrintAppGroup }
/desktop_approots/BTE/dt/appconfig/appmanager/C/BestTextEditor/BTEditor
and make the file executable.d. Create the action file in the application group that will open the help volume. To do this, create the file:
/desktop_approots/BTE/dt/appconfig/appmanager/C/BestTextEditor/BTEHelp
and make the file executable.e. Put other files into the application group; for example, "read me" files, sample data and template files.
In a terminal emulator window:
a. Log in as root.
b. Run the command:
/usr/dt/bin/dtappintegrate -s /desktop_approots/BTE
c. Open the Desktop_Tools application group and double-click Reload Applications.