cde/examples/template/README

   1 /* $XConsortium: README /main/3 1996/07/15 14:05:55 drk $ */
   2 The Template Application
   3 ------------------------
   4 This is a template Dt application. It illustrates how to write
   5 a simple application integrated with the Dt desktop.
   6
   7 The application provides a simple airbrush drawing facility using
   8 Motif. It defines a new file type '*.template' which contains a list
   9 of x, y coordinates for the drawn points. The application and data
  10 format favor simplicity over performance, and could obviously
  11 be improved.
  12
  13 Actions
  14 -------
  15 A set of actions are provided to allow integration into the Dt desktop:
  16
  17         TemplateNew (labeled New) - to create a new Template data file.
  18         TemplateOpen (labeled Open) - to open an existing Template data file.
  19         TemplatePrint (labeled Print) - to Print a Template data file.
  20
  21 Datatypes
  22 ---------
  23 The template data file is described by the datatype TemplateData, defined
  24 in C/template.dt
  25
  26 Icons
  27 -----
  28 A minimal set of icons are provided to integrate with the Dt desktop. The
  29 application group icons, window manager icon, Action icons and data file
  30 icons are identical. In a more sophisticated application, these would
  31 most likely be similar, but visually differentiated in some way.
  32
  33 Help
  34 ----
  35 A simple help file is provided. This can be displayed from within the
  36 application using the Help viewer widget (by selecting 'Overview' in the
  37 'Help' menu. It can also be view using the dthelpview tool.
  38
  39 Message Catalog
  40 ---------------
  41 All user-visible text in the application is loaded from the message catalog
  42 template.cat.
  43
  44 Example file
  45 ------------
  46 As recommended in the Programmer's Guide, an example.template file is
  47 provided.
  48
  49 App-defaults file
  50 -----------------
  51 The app-defaults file 'Template' contains resources to set the initial
  52 size of the application window.
  53
  54 The Application Package
  55 -----------------------
  56 The Makefile provided will build the application binary ("templatebin") and
  57 associated files. It then copies these into the newly created application
  58 package directory hierarchy ("template"). The ./dt/ subdirectory hierarchy
  59 is a Dt standard and is described in the Programmer's Guide. The other
  60 directories (bin, app-defaults, msg) are not standard directories and may
  61 vary for your application and installation script.
  62
  63 The binary templatebin will function on its own, however to fully install
  64 the application and integrate with the Dt desktop you will need to write a
  65 platform-specific installation script.  The installation script will
  66 typically need to be run with root privileges.
  67
  68 This script should be written to ensure that the binary, app-defaults and
  69 message catalog get installed correctly on your target system, and are
  70 available in the appropriate user or system search paths.
  71
  72 This script should also install the ToolTalk ptype into the system by
  73 running the command 'tt_type_comp -d system template.ptype'.
  74
  75     NOTE: There is a bug in the system that may prevent tt_type_comp from
  76     notifying an existing desktop session that new types have been added.
  77     The symptom of this bug will be that the application will fail with the
  78     following error message:
  79
  80         templatebin: ttmedia_ptype_declare failed
  81
  82     If this occurs, a workaround is to send SIGUSR2 to the running ttsession
  83     process, like so:
  84
  85         $ /usr/bin/ps -e | grep ttsess
  86           7850 console  0:08 ttsessio
  87         $ kill -USR2 7850
  88
  89     This will cause ttsession to reread its types files.  See ttsession(1)
  90     for further information.  An alternative workaround is to logout from
  91     the desktop and restart.
  92 If you choose to test the templatebin binary before integrating it with
  93 the Dt desktop, you will need to set the following (this assumes you
  94 have built out of /usr/dt/examples/template):
  95
  96   export XMICONBMSEARCHPATH=$XMICONBMSEARCHPATH:/usr/dt/examples/template/template/dt/appconfig/icons/C/%B:
  97
  98   export XMICONSEARCHPATH=$XMICONSEARCHPATH:/usr/dt/examples/template/template/dt/appconfig/icons/C/%B:
  99
 100   export DTHELPSEARCHPATH=$DTHELPSEARCHPATH:/usr/dt/examples/template/template/dt/appconfig/help/C/%H.sdl:
 101
 102 The installation script should be written to ensure that the bin, app-defaults
 103 and message catalog get installed correctly on your target system, and
 104
 105 The final step of the installation script should be to execute
 106 'dtappintegrate -s template'.  This will ensure that the desktop
 107 files under the ./dt/ subdirectory are installed correctly and
 108 inserted into the appropriate Dt system and user paths.
 109
 110 Localization
 111 ------------
 112 The application is ready for localization. This directory contains
 113 the non-localizable portions of the application.
 114
 115 The ./C/ directory contains the localizable portions of the application
 116 in US English. Some or all of these files should be translated and
 117 placed in a separate locale-specific directory.
 118