test

Common Desktop Environment: Programmer's Overview

Part II Development Environment Overview

Chapter 2 Development Environment Considerations

This chapter discusses general information you should know before starting to use the Common Desktop Environment application program interfaces (APIs).

Before you integrate your application into the desktop, you should have a basic understanding of how the desktop works. Install the Common Desktop Environment on your platform and familiarize yourself with its features. For an introduction to the desktop, see the Solaris Common Desktop Environment: User's Guide or the Desktop Introduction online help volume.

Common Desktop Environment Characteristics

The Common Desktop Environment provides a productive and comfortable desktop environment for UNIX users. As you develop your application, keep in mind the experience that the Common Desktop Environment delivers to its users. Develop your application with the following characteristics in mind, to help make it a powerful, consistent, and predictable part of the Common Desktop Environment:

Underlying Foundations

To compile an application that uses the desktop APIs, you need:

The resulting binary file must be run in an environment in which matching libraries are installed. The run-time libraries are in /usr/dt/lib, and they include the directories listed in Table 2-2.

To run properly, Common Desktop Environment-based applications require an environment in which some files from the following run-time directories are installed:

Your application should depend on only those run-time files explicitly mentioned in the X/Open XCDE standard. It should not depend on files not mentioned in the standard; for example, /usr/dt/appconfig/icons. If you build such dependencies into your application, it should be robust enough to run in an environment in which such files are missing or have changed.

For a listing of the minimum run-time environment required to run a Common Desktop Environment application, see the dtfilsys(5) man page.

The run-time environment includes Common Desktop Environment Motif, which is Motif 2.1 with bug fixes and enhancements. (For a description of these enhancements, see Appendix A, Common Desktop Environment Motif.) For more information on the Common Desktop Environment run-time environment, see the run-time documentation set.

Running Existing Applications

Existing X Window System-based applications that are not compiled with any Common Desktop Environment libraries run under the desktop window manager (dtwm) similarly to the way they run under the Motif window manager: they still work. The level of interoperability with the Common Desktop Environment follows these guidelines.

Table 2-1 Interoperability of Existing X-Based Applications with the Common Desktop Environment

Characteristics of Existing X-based Applications 

Interoperability Status with Desktop 

Motif 1.2 (and later) drag and drop (using preregister protocol) 

Yes 

Motif 1.2 (and later) drag and drop (using dynamic protocol) 

No [This is a Motif 1.2 drag-and-drop dynamic protocol interoperability problem, and it is not due to the Common Desktop Environment.]

Cut and paste (all applications) 

Yes  

OPEN LOOK drag and drop 

Yes (except multiple-item  

drag and drop) [This is implemented through a protocol translation mechanism in the drop site database manager (dsdm).]

ToolTalk Media Exchange and Desktop protocols 

Yes 

If you want to recompile and relink an existing Motif application with the Common Desktop Environment Motif shared libraries, the application must be compatible with Motif 1.2.

Libraries and Header Files

Compile Common Desktop Environment applications against X11R5 header files and libraries, which reside in vendor-specific locations. Table 2-2 lists the locations of all development environment libraries and header files, as subdirectories of /usr/dt.

Demo Programs

The /usr/dt/examples subdirectories contain source code for development environment component demos, as well as a template application. See Table 2-2 for a listing of all demo subdirectories.

Each demo subdirectory contains source files for one or more demo programs, along with makefiles for the programs. It also contains a README file that describes the demos.

The demo whose source is in the template subdirectory is a simple drawing program. This demo illustrates the basic structure of a Common Desktop Environment application that is integrated with the desktop. It is internationalized and contains all localized components in a separate subdirectory. You can use the drawing program source as a template for your application.

Man Pages

The Common Desktop Environment man pages reside in /usr/dt/man. To view them using either the man() command or the desktop man page viewer, you must add /usr/dt/man to the MANPATH environment variable. For example, in your ~/.dtprofile file, set:

MANPATH =

$MANPATH:/usr/dt/man

For a listing of the /usr/dt/man subdirectories and contents, see Table 2-2. For more information on the man() command, see the man(1) man page.

Development Environment Directory Structure

Table 2-2 lists the top-level directories in the development environment directory structure and lists their subdirectories. (All of the top-level directory names are prefixed by /usr/dt.)

Table 2-2 Development Environment Directories in /usr/dt

Directory 

Subdirectory 

Contents 

examples

 

Subdirectories that contain source code for development environment component demo programs 

 

 

README file 

 

dtaction

Action invocation API demos 

 

dtbuilder

Application Builder examples 

 

dtcalendar

Calendar API demos 

 

dtdnd

Drag-and-drop API demos 

 

dtdts

Data-typing API demos 

 

dthelp

Help API demos 

 

dtksh

dtksh example scripts

 

dtsession

Session Manager API demos 

 

dtterm

Terminal Emulator widget API demos 

 

dtwidget

Common Desktop Environment Motif widgets demos 

 

dtwsm

Workspace Manager API demos 

 

template

Template Common Desktop Environment application 

 

motif

Motif 1.2 API demos 

 

motif/clipboard

XmClipboard API demo

 

motif/dogs

Widget binary compatibility mechanism demo 

 

motif/draganddrop

Motif 1.2 drag-and-drop API demo 

 

motif/periodic

Motif widgets demo 

 

tt

ToolTalk Messaging Service demos 

include

 

Development environment library header files 

 

csa

Calendar header files 

 

Dt

Header files for DtSvc, DtWidget, DtHelp, and

DtTerm

 

Mrm

Motif 1.2 resource manager header files 

 

Tt

ToolTalk Messaging Service header files 

 

Xm

Motif 1.2 toolkit header files 

 

uil

Motif 1.2-callable UIL compiler header files 

lib

 

Library files for libcsa (Calendar),

libDtHelp (Help system),

libDtSvc (actions, data typing, drag and drop, Session Manager, Workspace Manager),

libDtTerm (Terminal Emulator),

libDtWidget (Common Desktop Environment Motif control and editor widgets),

libMrm (Motif 1.2 resource manager),

libUil (Motif 1.2-callable UIL compiler),

libXm (Motif 1.2 toolkit),

libtt (ToolTalk)

sparcv9 (a subdirectory containing 64-bit versions of all the libraries in the lib sudirectory)

man

 

Development environment man pages 

 

man1

Client and utility man pages 

 

man3

API man pages 

 

man4

Data formats 

 

man5

Header file and action man pages

64-bit Libraries

The libraries listed under the lib subdirectory are available in 64-bit versions in the sparcv9 subdirectory (see Table 2-2). These libraries enable the development of 64-bit applications for CDE.

Chapter 3 Developing an Application

This chapter presents information specific to developing a Common Desktop Environment application, such as naming conventions and other guidelines. It introduces levels of integration, which are the guidelines for determining the desktop functionality to incorporate into your application to make it increasingly integrated with the desktop. It also provides an overview of the Application Builder, a tool to simplify Common Desktop Environment application development.

Levels of Desktop Integration

Users can run any X11-based application from a shell command line in the Common Desktop Environment. If you want to integrate your application into the desktop, however, there are guidelines for you to follow. The Common Desktop Environment defines three levels of integration to give you maximum flexibility in designing your application or porting an existing application:

For more information on all three levels of integration, see the Solaris Common Desktop Environment: Programmer's Guide. Basic Integration is also discussed in the Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide.

Desktop Naming Conventions

The Common Desktop Environment uses naming conventions similar to those used by X and Motif. Desktop clients, desktop libraries, and other desktop components share a common prefix for externally visible names: dt, Dt, or DT. Private desktop structures, functions, and defines (found in the Common Desktop Environment code; not for developer use) have an _dt, _Dt, or _DT prefix. Table 3-1 lists the desktop naming conventions.

Table 3-1 Desktop Naming Conventions

Name  

Prefix 

Example 

Desktop clients and utilities 

dt

dthelpview

Resource names and classes 

Dt

DtNhelpType, DtCHelpType

Library names 

Dt

libDtHelp

Include references 

Dt

#include <Dt/Help.h>

Public function names 

Dt

DtCreateHelpDialog

Public data structure names 

Dt

DtHelpDialogCallbackStruct

Constant names 

Dt

DtHELP_NEW_WINDOW

Environment variables 

DT

DTHELPSEARCHPATH

Private desktop symbols (structures, functions, defines) 

_dt, _Dt, _DT

_DtHelpFunction, _DtHELP_DEFINE

Table 3-2 lists the exceptions to the preceding naming conventions.

Table 3-2 Exceptions to Desktop Naming Conventions

Name 

Prefix 

Example 

Common Desktop Environment Motif

Xm

XmCreateLabel

dtksh Convenience Functions

Dtksh

DtkshAddButtons

ToolTalk Messaging Service

tt (for functions)

Tt (for typedefs) 

TT (for constants) 

tt_open

Tt_message 

TT_NOTICE 

X11R5

X, Xt

XOpenDisplay, XtCreateWidget

Caution - Caution -

Do not use the prefixes dt, Dt, DT, _dt, _Dt, _DT, Xm, tt, Tt, TT, X, or Xt to define new symbols in your application code. If you do, you might define one that has already been defined--or might be defined in the future--in the Common Desktop Environment, ToolTalk, X11R5, or Motif code.

Public and Private Interfaces

If a Common Desktop Environment interface is documented in the man pages or the Common Desktop Environment documentation set, you can assume that the interface is public unless otherwise stated. An interface is not necessarily public just because it has a header file associated with it. Interfaces that are not documented are private to the Common Desktop Environment and are subject to change without notice.

Guidelines for Common Desktop Environment Databases

You can find the syntax for the desktop databases, such as those used for actions and data types, in man pages located in the /usr/dt/man/man4 directory.

For more information on databases, see the Solaris Common Desktop Environment: Programmer's Guide.

Application Initialization and libDtSvc

If your application uses any of the libDtSvc APIs (for actions, data typing, drag and drop, Session Manager, or Workspace Manager), it must first initialize the libDtSvc library by calling either DtInitialize() or DtAppInitialize(). Refer to the DtInitialize(3) or DtAppInitialize(3) man page for more information.

Application Builder

Application Builder (App Builder) is a tool that enables you to easily create your first graphical user interfaces (GUI) for Common Desktop Environment applications, without having to write code to call the desktop application program interfaces (APIs). It abstracts the Motif toolkit into simple object palettes and object property sheets. You can use App Builder to construct a wide range of applications, from simple GUI-based programs to complex, integrated systems. It supports User Interface Language (UIL) file import and export to enable you to migrate your application among other Motif-based tools and products.

App Builder is ideally suited for use if you:

In fact, even if you do not fit into any of the preceding categories, you will likely find App Builder to be appropriate and helpful for your application development.

Using App Builder, you can:

You can compile and invoke your application from within App Builder. You can execute the build, run, and debug cycles all from a common environment without having to exit and restart App Builder.

Tip -

App Builder is a good learning tool. A full-featured Motif GUI builder called XDesigner is available for purchase from the Sun Microsystems Advanced Developer Tools organization.

Demo Programs

You can find the App Builder example programs in /usr/dt/examples/dtbuilder. Read the README file for detailed information on these programs.

Related Documentation

For more information on Application Builder, see the appropriate man pages, the App Builder help volume, and the Common Desktop Environment: Application Builder User's Guide.

Chapter 4 Portability and Maintenance

This chapter contains information you can use to write highly portable applications and use to ensure that your application will be compatible with future Common Desktop Environment releases.

Portability Issues

This section presents issues that might affect your application's portability between different platforms that support the Common Desktop Environment.

Standards

To be Common Desktop Environment-compliant, your application must follow the Motif 2.1, ANSI-C, and X11R6 standards. If you are developing your application in C++, use C++ version 2.0 or later. No further assumptions are made that you adhere to any standards, such as POSIX, when you write a Common Desktop Environment application. Applications that use the desktop application program interfaces (APIs) will be portable to other Common Desktop Environment platforms. However, using POSIX can enhance your software's portability.

The POSIX standard, IEEE Std 1003.1-1990, is entitled IEEE Standard for Information Technology--Portable Operating System Interface (POSIX)--Part 1: System Application Program Interface (API) [C Language], ISBN 1-55937-061-0.

The Motif 1.2 standard, IEEE Std 1295, is entitled Standard for Information Technology--X Window System Graphical User Interface--Modular Toolkit Environment.

For information on ordering IEEE Std 1003.1-1990 and IEEE Std 1295, see "Related Books".

Makefiles

Certain libraries that the Common Desktop Environment depends on, for example X11R6, are likely to be installed in different locations on different platforms. Include platform-specific references to accommodate this or write a separate makefile for each platform.

Also, the make program functionality can differ across platforms. If you want to write just one makefile for your application, use the common make functionality used by the platforms to which you want to port your program. Avoid platform-specific make features.

The Common Desktop Environment requires no additional defined constants (-D parameters) to integrate with the desktop. If you do follow a standard, such as POSIX, you might need to compile with additional standard-specific flags. Read about the standard to find out if it includes special compiler considerations.

Each subdirectory of /usr/dt/examples contains sample makefile source files for different platforms. These makefiles take into account system differences. In particular, see the /usr/dt/examples/dtdts directory for generic examples of makefiles.

Compile Options

To enable your application to find the desktop include files, add:

-I/usr/dt/include

to each makefile's compile line.

Link Options

To enable your application to reference desktop libraries, add:

-L/usr/dt/lib

-l<libname1>

-l<libname2>...

to each makefile's link line, where libname1, libname2 are the names of libraries your application needs to reference. You can include as many desktop library names in this line as you want. For example: 

-L/usr/dt/lib -lDtSvc

-ltt -lXm

enables your application to reference the Desktop Services, ToolTalk Messaging System, and Motif 1.2 libraries.

File-Naming Conventions

You should limit your application file names, and the file names your application generates, to 14 characters. This will make your application portable to platforms that have this limitation. Some platforms can be configured to have this constraint.

Do not place length limitations on file names that an end user generates.

Display Support

Your application should support the following display options and configurations:

If you use the Icon Editor to create color icons, your application will share colors with other desktop applications more readily. This helps conserve color cells when running on a Pseudo Color display.

Common Desktop Environment Motif Widget Binary Compatibility Guidelines

Any widget subclass that you implement using the standard Xt APIs that rely on the size of data structures of widgets from which you have subclassed might not be compatible with any new version of Motif or the Common Desktop Environment. The reason for this is that new fields may be added to the superclasses in the new version of Motif. An example is that new fields have been added to the XmManager and XmPrimitive classes in Motif 2.0.

The incompatibility occurs because a subclass must contain compiled-in references to its instance fields that are specified relative to the start address of the widget instance. When you install a new Motif library for a widget whose superclass instance structure has been extended, the compiled-in references will point to the wrong memory location.

To avoid this difficulty, Motif provides a mechanism for defining resources and accessing widget fields that allows you to reference all fields in the instance and constraint structures relative to the start of the widget part structure, instead of the overall widget structure. (The overall widget structure includes the superclass part structure.) The mechanism resolves these relative references at run time, when the widget class is first initialized. To resolve references, it factors in the size of the widget's superclass instance structure, which it reads from the currently linked Motif library.

Note -

If you implement subclassing, you must use the Motif reference-resolving mechanism if you want your application to be binary compatible with future releases of the Common Desktop Environment.

For details regarding this Motif mechanism, consult the Motif 1.2 XmResolvePartOffsets(3x) and XmResolveAllPartOffsets(3x) man pages and the Motif 2.1 Programmer's Reference. You can find example source code in /usr/dt/examples/motif/dogs.

Chapter 5 Basic Application Integration

Basic application integration is a set of highly recommended tasks you should perform. These tasks do not require modification of the source code for your application.

Basic integration does not involve extensive use of the desktop application program interface (API). Therefore, it does not provide other interaction with the desktop, such as drag and drop, session management, ToolTalk messaging, and programmatic access to the actions and data types database.

Basic Integration Features

Basic application integration provides these features for end users:

Basic integration provides these advantages to system administrators:

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 Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide.

The Solaris Common Desktop Environment: Programmer's Guide contains a chapter on basic integration. Where appropriate, the chapter refers you to the information contained in the Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide. It also contains additional information specific to application programmers.

Basic Integration Tasks

These are the general tasks involved in basic integration:



Chapter 6 Recommended Integration


The Common Desktop Environment contains components and guidelines
to use  so that your application will integrate well with other applications
on the  desktop. This chapter provides an overview of each recommended component
and  guideline that you should use to enhance your application's level of
 consistency with the desktop.



Note - 
In addition to incorporating the components and following the
guidelines  in this section, you should also follow the basic integration
steps outlined  in Chapter 5, Basic Application Integration					.




For more information on recommended integration, see the  Solaris Common Desktop Environment: Programmer's
Guide.


Help System


The Common Desktop Environment Help system is a complete system for
 developing and displaying online help for application software. It enables
 authors to write online help that includes rich graphics and text formatting,
 hyperlinks, and access to the Help system from within the application. The
 Help system provides a programmer's toolkit for integrating the help  facilities
into an application.


Creating and integrating online help into an application can be done
as  a collaborative project. Developers design and implement how an application
 responds to a user's request for help. Authors organize and write the  actual
help information that is displayed. 


The Help system includes:


For Authors



Authors create help topics using the Help tag set and follow Structured
 Graphic Markup Language (SGML) tagging conventions. SGML markup is the primary
 data format. When compiled, the run-time distribution format is  SGML-compliant.



The Help system also supports non-SGML formats such as UNIX man pages,
 text files, and text  strings.



For  Programmers



Library and Header Files


The Help library, libDtHelp, provides support for  creating
and managing help dialogs based on Motif. The  libDtHelp
header files are:



Demo Programs


You
can find the Help system demos in  /usr/dt/examples/dthelp.
Read the  README file for detailed information on the
demos.


Related Documentation
For more information on the Help system, see the relevant man pages
and  the Common Desktop
Environment: Help System Author's and Programmer's Guide.


ToolTalk Messaging Service


The Common Desktop Environment defines two standard ToolTalk protocols
 known as message sets. A message set contains a number
of  messages that can be exchanged between a sender and a handler process.
These  message are grouped together because they describe related requests
and  notices. The sender and recipient can be within the same process or on
 different hosts. Message sets have associated utility functions that enable
 you to concentrate on the semantics of the protocol without getting too 
involved in low-level details. Some message set functions enable you to easily
 defer to default behavior.   



The desktop message set encompasses three areas:
 




See "Handle Desktop" and "Send Desktop"
for information on windowing behavior. See "Desktop File"
for information on file access and short-term file lifecycle control.  Implementing
the Do_Command request is specific to the  application's
extension language and is not assisted by the ToolTalk Messaging  Service.


The media message set enables an application to
be  a container for arbitrary media or to be a media player and editor that
can be  driven from such a container. The media message set enables a container
 application to compose, display, edit, and print a document of an arbitrary
 media type, without understanding anything about the format of that media
 type. The ToolTalk Messaging Service routes a container's requests to the
 user's preferred tool for the given media type and operation. This includes
 routing the request to an already-running instance of the tool, if that 
instance can best handle the request. See "Send Media"
and "Handle Media".



Message Sets


The ToolTalk Messaging Service provides support for these message  sets:


Handle Desktop


Handling desktop requests is the most basic level of messaging  integration.
Any application that sends ToolTalk messages, either through  calling tt_message_send() or  DtActionInvoke(), should
handle the desktop requests.  This enables other applications to set or query
things such as your  application's current directory, iconic state, and  $DISPLAY. For further information, see the man pages for  ttdt_open(), ttdt_session_join(),  ttdt_session_quit(), and  ttdt_close().


Send Desktop


When an application is started by ttsession to handle
 some ToolTalk request, it is a child of ttsession rather
 than of the request sender. The application will usually be started on the
 same X display session as the sender, but not necessarily on the same X11
 screen or in the same current directory context. If the application is  implemented
as a server process, it may already be displaying on a particular  screen
or in a particular directory context. 


Using desktop requests, a handling application can inherit from the
 sender attributes that might otherwise be inherited through command-line
 invocation. Use the desktop message set in this way to reset the  handler's
locale, current working directory, and even  $DISPLAY.
This enables a carefully coded receiving  application to come up on the same
X11 screen as the sender. A request handler  can also find out the request
sender's current directory and window  geometry. Knowing the window geometry
enables the request handler's  window to avoid obscuring the request sender's
window, if possible. For  more information, see the ttdt_sender_imprint_on() man  page.


Handle Media


The ToolTalk Messaging Service enables an editor to easily handle the
 standard media requests for the media types for which the editor is  responsible.
For further information, see the man pages for  ttmedia_ptype_declare(),  ttdt_message_accept(),  ttmedia_load_reply(), and  ttmedia_Deposit().


Send Media


The ToolTalk Messaging Service enables a container to easily send media
 requests and manage the subsequent document updates sent back by the handler.
 In those cases in which the container doesn't engage in any ongoing ToolTalk
 dialog with a media handler, use the actions API instead of directly using
 these ToolTalk APIs. Equivalent actions (Open and Print) represent a higher
 level of abstraction that supports the equivalent of ToolTalk and non-ToolTalk
 aware media handlers. For further information, see the man pages for  ttmedia_load() and  ttdt_subcontract_manage().
Note that, in most cases, a  container application should perform operations
on objects using  DtActionInvoke() instead of  ttmedia_load(). See the  Common Desktop Environment: ToolTalk Messaging Overview
for a description of how ToolTalk applications  can be driven using actions.


Desktop File


The ToolTalk Messaging Service makes it easy to send and receive the
 desktop messages about files. These messages enable applications to coordinate
 access to files. For further information, see the man pages for  ttdt_file_join(), ttdt_file_quit(),  ttdt_file_event(),  ttdt_Get_Modified(), ttdt_Save(),  and ttdt_Revert().


Examples of applications that already use the ToolTalk Messaging Service
 include the Common Desktop Environment Icon Editor, Mailer, Text Editor,
and  Calendar. Other parts of the Common Desktop Environment use the ToolTalk
 Messaging Service indirectly by defining actions that send messages.


Library and Header Files


The ToolTalk messaging library is called libtt. The
 libtt header files are:



Demo Programs


You can find the ToolTalk Messaging Service demos in  /usr/dt/examples/tt. Read the README  file
for detailed information on the demos.


Related Documentation
For more information on the ToolTalk Messaging Service, see the relevant
 man pages and the Common Desktop Environment: ToolTalk Messaging Overview.


Session Manager


Session Manager supports the ICCCM 1.1 WM_COMMAND
and  WM_SAVE_YOURSELF protocols, which permit:       




Session Manager also provides an API to assist your application in 
saving and restoring its state at logout and login.


Session Manager is responsible for restarting applications at login.
To  do this, your application must tell Session Manager what command and 
command-line options are required to restart it. Use Xlib's  XSetCommand() to set the WM_COMMAND  property on your application's
top-level window.


When Session Manager saves a session, such as at logout, your  application
might need to save some state information so it can be restored to  a similar
state. Session Manager can optionally notify your application that  the session
is being saved. Your application must inform Session Manager that  it wants
such notification. It does this by registering the  WM_SAVE_YOURSELF protocol with its top-level window  WM_PROTOCOLS
property and setting up a callback procedure  to handle the notification.
To do this, use the  XmAddWMProtocols() and  XmAddWMProtocolsCallback() functions. Your application  should not
interact with the user in any way when processing the  WM_SAVE_YOURSELF callback. (For example, it should not  display a Save As dialog
box.) It must set the WM_COMMAND  property on its top-level
window to notify Session Manager that it is done  saving its state. 



To enable your application to save state information, use the  DtSessionSavePath() function to obtain the full path name  of a file
in which this information can be saved. At session restore time, use  the DtSessionRestorePath() function to obtain the full  path name of
the state file your application uses to restore its  state.



The Common Desktop Environment Workspace Manager is responsible for
 restoring an application's main top-level window (containing the  WM_COMMAND) property to the proper workspace, geometry, and  icon
state. If an application has multiple top-level windows, it is the  application's
responsibility to restore the states of the other  top-level windows. Refer
to "Workspace Manager"   for additional  information.



Library and Header Files


The Desktop Services library, libDtSvc, provides  access
to many desktop APIs, including the one for session management. Include  the Dt/Dt.h and Dt/Session.h header  files to
access the Session Manager API.


Note - 
If your application uses any of the Session Manager APIs, it must
first  initialize the libDtSvc library by calling either
 DtInitialize() or DtAppInitialize().
 Refer to the DtInitialize(3) or  DtAppInitialize(3) man page for more  information.





Demo Programs


You
can find the Session Manager demos in  /usr/dt/examples/dtsession. Read the  README file for detailed information
on the demos.


Related Documentation
For more information on Session Manager, see the relevant man pages
and  the Solaris Common
Desktop Environment: Programmer's Guide.


Drag and Drop


The Common Desktop Environment provides a drag-and-drop API, that is
 layered on top of the Motif 2.1 drag-and-drop API, to provide convenient,
 consistent, and interoperable drag and drop across the desktop. The Common
 Desktop Environment drag-and-drop API makes it easier for developers to 
implement drag and drop. With drag and drop, users can manipulate objects
on  the screen directly by grabbing them, dragging them around the display,
and  dropping them on other objects to change the object's location or  perform
a data transfer.


Motif 2.1 drag and drop provides low-level drag-and-drop mechanisms;
 Common Desktop Environment drag and drop incorporates policies for those
 mechanisms. 



Common Desktop Environment drag and drop consists of an API and  protocols
to simplify the interface to Motif drag and drop. It implements  policies
such as the buffer transfer protocol and the drag cursors'  appearances. Use
the Common Desktop Environment drag-and-drop API, with its  built-in policies,
to ensure interoperability through consistency. Common  Desktop Environment
drag-and-drop policies are compatible with standard Motif  2.1 drag-and-drop
protocols for text and file name transfers.


Common Desktop Environment drag and drop uses the X selection mechanism
 to transfer data. Suitable targets exist and are registered with the X  Consortium.
Two desktop applications can agree to transfer data through the  text, file
name, or data transfer protocols.


The existing Motif 2.1 API for drag and drop is flexible and, therefore,
 is somewhat difficult for nonexpert developers to use. The Common Desktop
 Environment drag-and-drop API provides some convenience functions that result
 in an API that is simpler and easier to use:



Library and Header Files


The Desktop Services library, libDtSvc, provides  access
to many desktop APIs, including that for drag and drop. Include the  Dt/Dt.h and Dt/Dnd.h header files to  access
the drag-and-drop API.


Note - 
If your application uses any of the drag-and-drop APIs, it must
first  initialize the libDtSvc library by calling either
 DtInitialize() or DtAppInitialize().
 Refer to the DtInitialize(3) or  DtAppInitialize(3) man page for more information.   





Demo Programs


You can find
the drag-and-drop demos in  /usr/dt/examples/dtdnd. Read
the  README file for detailed information on the demos.


Related Documentation
For more information on Common Desktop Environment drag and drop, see
 the relevant man pages and the  Solaris Common Desktop Environment: Programmer's Guide.


Internationalization


The Common Desktop Environment is internationalized to support  single-byte
and multibyte locales. Developers can write internationalized  applications
that can be easily localized to run on any Common Desktop  Environment platform.       



Common Desktop Environment applications (both source and binary) can
be  localized into regional languages and territories, and across multiple
vendors  and hardware platforms:  




The Common Desktop Environment takes advantage of internationalization
 features in these standards:   




If you intend to internationalize your application, you must ensure
that  it supports input and output of multibyte characters. Also, make sure
that  message catalogs are used and code can be fully localized. 


Demo Programs


The
drawing program demo in  /usr/dt/examples/template is
internationalized. Read the  README file for detailed
information on this demo.


Related Documentation
For more information on Common Desktop Environment internationalization,
 see the development environment component man pages and the  Common Desktop Environment: Internationalization
Programmer's Guide.  



Standard Font Names


The standard font names defined by the Common Desktop Environment are
 guaranteed to be available on all Common Desktop Environment-compliant  systems.
These names do not specify actual fonts. Instead, they are aliases  that each
system vendor maps to the vendor's best available fonts. If  you use only
these font names in your application, you can be sure of getting  the closest
matching font on any Common Desktop Environment-compliant system.  These comprise
a set of X Window System font names you can use for the most  common categories
of type designs and styles.  



The standard font names are mapped to different fonts on different 
Common Desktop Environment platforms, typically using the X font alias  mechanism.
This eliminates the problem of having to select from a varying set  of fonts
on different platforms. It also enables you to make use of the  default set
of fonts on a particular vendor's Common Desktop Environment  implementation. 


The Common Desktop Environment defines two types of standard fonts:
 application fonts and interface fonts. Use the application fonts for output
 produced by your application. Motif widgets and the desktop use interface
 fonts; do not change their default  fonts.



Application Fonts


At least six point sizes are available on all Common Desktop Environment 
platforms for each font associated with a Standard Font Name: 8, 10, 12, 14,
 18, and 24. XLFD font descriptions for Common Desktop Environment fonts look
 like:


-dt-application-*



when used where such patterns are valid.


Two of the most common design variations in fonts used to display text
 are the presence or absence of serifs and the choice between proportional
or  regularly spaced (monospaced) characters. Combining these two design 
variations yields four generic font designs:



Common examples of each of these four designs (in corresponding order)
 are:



Each of these designs for text fonts typically come in four styles 
(combinations of weight and slant):



The four styles of each of the four design variations yield 16 generic
 font variations. These 16 generic fonts are among the most commonly used
in  general desktop computing. For example, Times Roman, Helvetica, and Courier,
 each in the four style variations, along with the Symbol font, constitute
the  Adobe\256 13--the minimum set of fonts built
into  all PostScript printers. 


Your application might not require an exact font family or name, but
 will need to use, for example, a monospaced font, a sans serif font, or a
 serif font. You do not have to know the exact font names present on a  particular
Common Desktop Environment platform. The Common Desktop Environment  standard
fonts default to the vendor's selection of the best font of a  particular
design on the vendor's platform.


Specify the XLFD font names for the standard application fonts your
 application needs as font resource values in the application's  app-defaults file. If you do not use these font names,  you might
need to supply a different app-defaults file for each application on  each
Common Desktop Environment platform.        



Interface Fonts


Interface fonts are
the small set of finely optimized fonts that define  the look of the desktop
on a particular platform. These fonts cleanly and  quickly convey small amounts
of information, such as that appearing in window  titles, buttons, menus,
and text fields. 


The desktop and the Motif toolkit widgets use interface fonts. Do not
 use these fonts directly within your application windows. 


The standard interface font names are different from the standard  application
font names. They, like the application font names, are mapped to  different
fonts on different Common Desktop Environment platforms. Interface  fonts
come in three styles:



Each style comes in seven sizes. Using the Style Manager, users can
 choose the size of interface fonts they want on their  desktop.



Demo Programs


The drawing
program demo in  /usr/dt/examples/template does not specify
any of its own  interface fonts. It serves as an example of how the Common
Desktop Environment  Motif interface fonts appear. However, this demo does
not take advantage of  application fonts.


Related Documentation
For more information on standard fonts, see the relevant man  pages--particularly DtStdAppFontNames(5) and  DtStdInterfaceFontNames(5)
for the list of XLFD font  names--and the Solaris Common Desktop Environment: Programmer's
Guide.     



Displaying Error Messages from Your Application


Applications in the Common Desktop Environment
follow a common model for  presenting error messages and warnings. Users running
your application expect  messages to be displayed in message footers, error
dialog boxes, or warning  dialog boxes, with further explanations available
in online help, when  appropriate.


This section outlines conventions for displaying error messages in your
 application. Because of the way message text is handled, it is important
to  follow these error presentation guidelines precisely. For example, casual
 users who start your application from the Front Panel never see messages
that  you send to standard error or standard out. In the Common Desktop Environment,
 such messages are directed to log files ($HOME/.dt/*log)
 that many users do not routinely examine or know about.


How to Present Error Messages


Follow these
rules when deciding where to tell users about warnings,  messages, and error
conditions:



What Information to Present in Error Dialogs


A good error dialog or warning dialog gives a user the following  information:



Linking Message Dialogs to Online Help


In cases where additional background information is required, or where
 it takes more than four or five lines of a dialog to completely explain an
 error, add a button that links the user to the appropriate section of online
 help.


Related Documentation
For details on displaying error messages in your application and linking
 message dialogs to online help, see the  Solaris Common Desktop Environment: Programmer's Guide.



User Customization Issues


This section presents guidelines to follow when designing your  application's
user interface.


Color Use


When you design
your application's user interface, do not specify  color settings that override
the default color scheme that the Common Desktop  Environment provides for
Motif and desktop widgets. For application-defined  colors, use the following
colors to promote sharing with other desktop  applications:



In most cases, you should not specify colors, so that your application
 uses the colors chosen by the end user in the desktop Style Manager.


Font Use


For your Motif widgets, use the fonts supplied by the Common Desktop
 Environment so that your application's windows look like other desktop  client
windows and so that users can change the size of these fonts using the  Style
Manager. If you override the supplied fonts by changing the Motif  fontList
resource specifications, then you must provide additional  functionality if
you want users to be able to customize the fonts in your  application.


Use the fonts from the Common Desktop Environment standard application
 font names to specify--in your app-defaults file--resources you
use  within your application (aside from the ones Motif uses for its widgets).
This  ensures that your application finds the appropriate fonts on all Common
 Desktop Environment platforms, which makes your application more portable
 across such platforms. For more information, see  "Standard Font Names"
 .



Note - 
The Style Manager only controls fonts for applications written
using  Motif version 1.2 or later. It will not supply
correct  fonts for Motif 1.1 (or earlier) applications. These applications
must specify  their own fonts in the app-defaults  file.





Accessibility


This section provides guidelines
for making software applications  accessible to people with disabilities.


Physical Disabilities


Provide keyboard access to all application features,
such as those  usually accessible through menus or drag and drop, to enable
people with  physical disabilities to more easily use your application.


Visual Disabilities


Follow these guidelines to make your application more accessible
to  people with visual disabilities:



Hearing Disabilities


Follow these guidelines to make your application more accessible
to  people with hearing disabilities:



Language, Cognitive, and Other Disabilities


The access guidelines outlined for visual, hearing, and physical  disabilities
typically benefit end users with cognitive, language, and other  disabilities.
In addition to those guidelines, include tear-off menus and  user-configurable
menus for important application features whenever  possible.



Mouse Double-Click Speed


For the end user to experience consistency across applications,
you  should not hardcode double-click durations into your application or  app-defaults files. This way, when the user changes the  double-click
time in the Style Manager, your application responds along with  the other
desktop applications.   



Demo Programs


The drawing
program demo in  /usr/dt/examples/template uses the Common
Desktop  Environment's default colors and fonts. This enables the user to
 customize the colors and fonts in this program by using the Style Manager.
 Read the README file for detailed information on this
 demo.


Related Documentation
For more information on user customization issues, see the  Common Desktop Environment: Style Guide and Certification
Checklist.



Chapter 7 Optional Integration


The Common Desktop Environment components discussed in this
chapter  enable you to leverage services provided by the desktop for achieving
 specialized tasks.



Note - 
In addition to incorporating any components described in this
section  into your application, you should also follow the basic integration
steps  outlined in Chapter 5, Basic Application Integration					. The components discussed
in Chapter 6, Recommended Integration are critical to making your application
highly integrated with the  desktop.




For more information on optional integration, see the  Solaris Common Desktop Environment: Programmer's
Guide.


Common Desktop Environment Motif Control Widgets


The Common Desktop Environment Motif control widgets are designed to
 ease porting OPEN LOOK and Microsoft Windows applications to the Common 
Desktop Environment by providing equivalent functionality in Common Desktop
 Environment Motif. The Common Desktop Environment Motif widgets library  libDtWidget contains widgets and functions that are used to  provide
common functionality across all Common Desktop Environment  applications.
The widgets provided include:    




The Common Desktop Environment Motif Widget library  libDtWidget supports drivability between Common Desktop  Environment applications
and legacy OPEN LOOK applications. That is, it  enables you to write applications
that operate the same way OPEN LOOK  applications do, in areas such as cut,
copy, paste, and mouse-button  functionality.


Note - 
The Common Desktop Environment supports all Motif 1.2 widgets.
See  Appendix A, Common Desktop Environment Motif for more information on Common Desktop
Environment  Motif.






Table 7-1  Common Desktop Environment Control Widgets









Widget  Name 



Description 












DtSpinBox





TextField  widget with additional controls for incrementing and
decrementing numeric  values, or browsing through and selecting from a list
of text  strings










DtComboBox




Combination of  TextField and pop-up List widgets that
provides a list of  valid choices for the TextField











DtMenuButton




Command widget that  provides menu cascading functionality of an XmCascadeButton  widget outside of a Menu Bar, or a Menu Pane (a
pull-down menu, a pop-up menu,  or an option menu)









 

Compatibility with Motif 2.1


The APIs of the DtSpinBox and  DtComboBox widgets are similar to the Motif 2.1 release of  XmSpinBox and XmComboBox widgets. The  APIs are designed
so an application can easily switch to the Motif 2.1 version  of these widgets.
To switch, change the Dt names for the  class, types, and
creation routines to Xm. For example,  change all occurrences
of DtSpinBox in your code to  XmSpinBox.
This information is supplied in case you choose  to port your application
to Motif 2.1, but it is not a  recommendation that you
do  so.



Note - 
The Common Desktop Environment does not guarantee
 strict API or binary compatibility between its widgets and the Motif 2.1
 widgets.





Library and Header Files


The library libDtWidget provides access
to the  DtSpinBox, DtComboBox, and  DtMenuButton widgets. The libDtWidget  header
files for these widgets are:



Demo Programs


You can find the Common Desktop Environment Motif
control widgets demos  in /usr/dt/examples/dtwidget.
Read the  README file for detailed information on the
demos.


Related Documentation
For more information on Common Desktop Environment Motif control  widgets,
see the relevant man pages and the  Solaris Common Desktop Environment: Programmer's Guide.
 



Data Typing


You can define data types when you perform basic integration for your
 application. This section focuses on a different aspect of data typing: 
extracting information from the actions and data-types database.


Data typing provides an extension to the attributes of files and data
 beyond what is provided by traditional UNIX file systems. These extensions
 include typing and attribute management. Use the data-typing API if your
 application receives data from external sources and must act on it. For 
example, your application might want to display an icon or execute an action
 that has a system-wide  definition.



Data typing consist of two  parts:




The data-typing system determines a type for a file or byte vector based
 on a set of criteria. These criteria include its name, permissions, symbolic
 link value, and contents. The attributes associated with a type describe
its  user-visible interfaces, including a description, the icon to represent
it  graphically, and the actions that apply to it. Attributes also exist that
name  the interchange formats to which the data conforms.


The Common Desktop Environment File Manager and Common Desktop  Environment
Mail attachment window use data typing to determine the icon and  actions
associated with a file. For example, for a C file  filename.c, File Manager uses the  .c extension to
determine the file's data type,  C_SOURCE. It then uses C_SOURCE to determine
the icon file name for the icon  that it can use for filename.c. 


Database Loading


This section discusses the loading API for the
actions and data-types  database. The syntax for this and any Common Desktop
Environment databases a  developer defines is discussed in man pages in the
 /usr/dt/man/man4 directory. 


The external database loading API consists of two functions:




DtDbLoad() reads in the actions and data-types  database.
It determines the set of directories that are searched for database  files,
and it loads into the database the .dt files that  are
found. Your application must call DtDbLoad() before  calling
any of the routines that query the actions and data-types database.   



Use DtDbReLoadNotify() to request notification of
 actions and data-types database reload events. It registers an  application's
interest in database reload messages.   



Your application should reload the database whenever it changes, so
that  the end user will notice updates without having to restart the  application.


Database Queries


To look up an attribute for a data
object, you must first determine the  type of the object and then ask for
the appropriate attribute value for that  type. The database query functions
enable you to perform operations such as  retrieve type data and attributes,
free memory, and load and unload the  database. These functions are documented
in the  Solaris Common
Desktop Environment: Programmer's Guide and also in man
pages in the  man3 directory.


Library and Header Files


The Desktop Services library, libDtSvc, provides  access
to many desktop APIs, including that for data typing. Include the  Dt/Dt.h and Dt/Dts.h header files to  access
the data-typing API. 


Note - 
If your application uses any of the data-typing APIs, or loads
the  actions and data-types database, it must first initialize the  libDtSvc library by calling either  DtInitialize()
or DtAppInitialize().  Refer to the DtInitialize(3) or  DtAppInitialize(3) man page for more information.
  





Demo Programs


You
can find the data typing demos in  /usr/dt/examples/dtdts.
Read the  README file for detailed information on the
demos.


Related Documentation
For more information on data typing, see the relevant man pages and
the  Solaris Common Desktop
Environment: Programmer's Guide.


Action Invocation


The action invocation API enables applications to invoke desktop actions
 on file or buffer arguments. It chooses a suitable action for the file or
 buffer based on the Class, Type,  Mode, and Number of the action  arguments. For
example, an Open action might invoke an image viewer for GIF  files, a word
processor for complex documents, and a simple text editor for  ordinary ASCII
files. Your application need not concern itself with the  details of action
selection or invocation. 


Use the action invocation API so that your application uses the same
 mechanisms as the rest of the desktop. The user can then experience uniform
 desktop behavior.


The action functions in the libDtSvc library provide
 a way to invoke desktop actions (such as Open and Print) for files or buffers.
 They contain parameters that enable you to modify an action's behavior. 
The action invocation API consists of the following functions:  










DtActionInvoke()




Invokes the specified  action on its arguments, which can be files or buffers 










DtActionLabel()




Provides access to  the localizable label string associated with an action 










DtActionDescription()




 









 



Returns a string
 containing the description information associated with the action your  application
called 










DtActionExists()




a Boolean function  that checks whether a given name corresponds to an existing
 action 










DtActionIcon()




Returns the name of  the icon associated with the specified action 









 

 

Library and Header Files


The desktop services library, libDtSvc, provides  access
to many desktop APIs, including that for actions. Include the  Dt/Dt.h and Dt/Action.h header files  to access
the actions API.


Note - 
If your application uses any of the action invocation APIs, it
must  first initialize the libDtSvc library by calling
either  DtInitialize() or DtAppInitialize().
 Refer to the DtInitialize(3) or  DtAppInitialize(3) man page for more  information.





Demo Programs


You
can find the action invocation demos in  /usr/dt/examples/dtaction. Read the  README file for detailed information
on the demos.


Related Documentation
For more information on actions, see the relevant man pages and the
 Solaris Common Desktop
Environment: Programmer's Guide.


Workspace Manager


The Common Desktop Environment Workspace Manager provides support for
 multiple workspaces. Each workspace is a virtual screen.
 Windows can be placed in a single workspace, all workspaces, or any  combination
of individual workspaces. Workspaces can be added, deleted, or  renamed dynamically
by the user.


The Workspace Manager API provides functions for applications that need
 to know in which workspaces their windows reside, or that need to have some
 control over how the windows are placed in the workspaces. Additionally,
the  API enables applications to monitor changes to the overall workspace
state,  such as which workspace is the current one.


The Common Desktop Environment does not require applications to use
the  Workspace Manager API to run on the desktop. Most desktop applications
can run  as expected without knowledge of the Workspace Manager. In particular,
if your  application has a single, main, top-level window and complies with
ICCCM 1.1  and Motif 1.2, you do not have to integrate with the Common Desktop
 Environment Workspace Manager for the application to run on the desktop.
 



However, more complex applications with multiple top-level windows need
 to use the Workspace Manager API in conjunction with the Session Manager
API  to properly save and restore the application's state. The Workspace 
Manager API enables an application to find out which workspaces each of its
 windows is in. The API also enables an application to display its windows
in  the correct workspace when the session resumes.  



The Workspace Manager API addresses the following tasks:



All Workspace Manager API functions share the prefix  DtWsm. 


Library and Header Files


The desktop services library, libDtSvc, provides  access
to many desktop APIs, including that for Workspace Manager. Include the  Dt/Dt.h and Dt/Wsm.h header files to  access
the Workspace Manager API.


Note - 
If your application uses any of the Workspace Manager APIs, it
must  first initialize the libDtSvc library by calling
either  DtInitialize() or DtAppInitialize().
 Refer to the DtInitialize(3) or  DtAppInitialize(3) man page for more  information.





Demo Programs


You
can find the Workspace Manager demos in  /usr/dt/examples/dtwsm. Read the  README file for detailed information
on the demos.


Related Documentation
For more information on Workspace Manager, see the relevant man pages
 and the Solaris Common
Desktop Environment: Programmer's Guide.


Terminal Emulator Widget


The DtTerm widget provides the functionality required
 to emulate an ANSI X3.64-1979-style terminal emulator (specifically a DEC
 VT220-like terminal with extensions). The Terminal Emulator widget library,
 libDtTerm, provides the DtTerm widget
 for use in adding a terminal emulator window to a GUI. If you include a 
terminal emulator in your application, use Common Desktop Environment Motif
 widgets to add display enhancements to it such as pop-up menus and scroll
 bars.    



The Common Desktop Environment Terminal Emulator, which is a part of
the  run-time environment, is a window that behaves as a terminal, enabling
access  to traditional terminal-based applications from within the desktop.
The  DtTerm widget is the foundation for the desktop run-time
 terminal emulator,  dtterm.



The libDtTerm library includes a set of convenience
 functions to create, access, and support the DtTerm widget. 


Library and Header Files


The libDtTerm library provides a set of widgets based
 on Motif for designing a terminal emulator or for adding a terminal emulator
 window to a GUI.


Include the Dt/Term.h header file to access  libDtTerm APIs in your application.


Demo Programs


You can find the Terminal Emulator demos in  /usr/dt/examples/dtterm. Read the  README
file for detailed information on the demos.


Related Documentation
For more information on the DtTerm widget, see the
 relevant man pages.


For more information on the desktop terminal emulator, see the terminal
 emulator help volume, the relevant man pages, or the  Solaris Common Desktop Environment: User's Guide.


Text Editor Widget


The Common Desktop Environment text editing system consists of two 
components:



Although the Motif text widget also provides a programmatic interface,
 applications that want to assure a system-wide uniform editor should use
the  DtEditor widget. The Common Desktop Environment Text
Editor  and Mailer use the editor widget. Use this widget in the following
 circumstances:




Library and Header Files


The DtEditor widget is in the  libDtWidget
library. The header file is  Dt/Editor.h.


Demo Programs


A demo containing
an example of the DtEditor widget  (editor.c) is in  /usr/dt/examples/dtwidget directory.
Read the  README file for detailed information on the
demo.


Related Documentation
For more information on the Text Editor widget, see the relevant man
 pages and theSolaris
Common Desktop Environment: Programmer's Guide.


Calendar


The Common Desktop Environment Calendar comprises the infrastructure
and  API that enables users to schedule their time and resources in a networked
 environment. The Calendar GUI is part of the Common Desktop Environment 
run-time environment.



Calendar consists of:



Additionally, it provides a user interface for both GUI and TTY  interaction.
The system supports entering, deleting, and modifying calendar  entries, as
well as browsing and search features. You can access all this  functionality
through the network.


The development environment provides a library for client access to
the  Calendar data. It is extensible in that it allows users to define their
own  calendar entry attributes. The library provides a client callback mechanism
for  notification of database updates.


The calendar daemon implements the services behind the library of  calendar
and scheduling API calls. It supports deleting, inserting, and  modifying
calendar entries. It also manages calendar reminders and supports  the creation
and removal of the Calendar database. It also provides mechanisms  for retrieving
Calendar data.


Calendar entry data integrates with the desktop through drag and drop
 and the ToolTalk messaging interfaces.


The calendar and scheduling API is an implementation of the X.400  Application
Programming Interface Association (XAPIA) Calendaring and  Scheduling API
1.0. Use the calendar and scheduling API to integrate your  application with
Calendar, or to develop your own calendar  application.



Library and Header Files


The Calendar
library, libcsa, provides a programmatic  way to access
and manage Calendar data in a networked environment.


Include the csa/csa.h header file to access  libcsa APIs in your application.


Demo Programs


You
can find the Calendar demos in  /usr/dt/examples/dtcalendar.
Read the  README file for detailed information on the
demos.


Related Documentation
For more information on the calendar, see the relevant man pages, the
 Calendar help volume, and the  Solaris Common Desktop Environment: Programmer's Guide.


Desktop Korn Shell (dtksh)


Desktop Korn shell (which is dtksh) provides a way
to  engage in graphic user interaction through shell scripts. The user interface
 capabilities are based on the Common Desktop Environment Motif widget set,
the  Xt Intrinsics, and the X11  library.




dtksh is a version of ksh-93 
extended to access many X, Xt, Motif, and Common Desktop Environment  facilities. ksh-93 is a version of Korn shell, the command  shell and programming
language ksh.  dtksh extends ksh to provide support  for:




Demo Programs


You can find the dtksh demos in  /usr/dt/examples/dtksh. Read the  README file
for detailed information on the demos.


Related Documentation
For more information on dtksh, see the relevant man
 pages and Common Desktop
Environment: Desktop KornShell User's Guide.