V1.2

The xmpiano program shows how to write a Motif Interface to Dumb Instruments (MIDI) application. Both a staff, for writing music, and keyboard are provided.

At the bottom of the window is a set of notes that may be used on the staff. Selecting one of these note buttons changes the active note accordingly. The selected note is also displayed as the new mouse cursor.

Though the note selection is limited, it is possible to play sharps as well as naturals. The program interface has not been written to play flats. The staff automatically resizes larger as notes are added past the right side of the staff. To see these notes, scroll the score window as needed.

To use this application, press the right mouse button on a staff that is visible. The following menu items are displayed:

• Add Voice
  Connects another display to a new staff. After selecting this command, you are prompted for the display to connect. Any music written in the new staff plays to this display. Note that pressing the right mouse button on the new staff shows the name of the display in the menu title. In addition, the menu commands in the menu bar relate to the staff that is being displayed.
• Remove Voice
  Removes the staff as well as the connection to the corresponding display. There is no undo for this command---all music written in this staff is deleted.
• Clear Voice
  Erases all notes on the staff. This does not affect the display connection.
• Play Voice
  Plays the voice of the staff in which the right mouse was pressed. If the voice is the same as the local host, the keys on the keyboard that correspond to the notes appear as though they are being pressed as the notes are played. It is possible to make the keyboard play along with all voices at the same time; however, the code must be compiled with the -DCHORDS option. Note that this can slow down the application significantly on many servers.
• Play All
  Plays all voices at the same time on each of the specified displays.
• Save Voice
  Saves the corresponding voice to a file. A FileSelectionDialog is displayed to prompt for the name of the file in which to save the voice. The display connection information is not saved.
• Load Voice
  Loads (appends) a previously saved voice to the corresponding staff.
• Quit
  Exits the example program.

This version does not allow editing of notes. To edit, clear the staff and start again, or read the data from a saved file.

To set the color of the notes, change the foreground color of the application. To do this, use the -fg option on the command line. For example:

$ xmpiano :== $DECW$EXAMPLES:xmpiano $ xmpiano -fg blue

B.4.13 Motif Sample Programs

Table B-6 lists sample programs showing various Motif Toolkit functionality.

Table B-6 Motif Sample Programs

File Name	Description
xmdialogs.c	dialog sampler
xmfonts.c	font browser
xmeditor.c	text editor
xmlist.c	list example
xmprotocol.c	window manager protocols example
xmter.c	shape & animation example
xmform.c	form attachment example
xmforc.c	form attachment + rowcolumn example
xmmap.c	drawingarea + scrolledwindow example
xmgetres.c	resource fetching example
xmapdef.c	app defined scrolled window example

The following notes apply to these sample programs:

1. The xmfonts program defaults to displaying the fonts whose name length are less than 10 characters. On some systems, the font path contains only long XLFD font names. It may be necessary either to set the resource XMFONTS*maxLen to a larger number (80), or to specify a numColumns resource of 1.
2. If you run the program xmter with a window manager other than Motif Window Manager, that window manager has to remove all the window decorations (for example, borders). The program xmter directs Motif Window Manager to remove the window decorations.
3. The xmform program displays a string made of Motif widgets embedded in a Form. Use the following commands:

   $ xmform :== $DECW$EXAMPLES:xmform $ xmform string

   The variable string is optional. If string is supplied, the available letters for string are F,I,M,O,T. The string of letters that you use must be in uppercase and enclosed in quotation marks. If string is omitted, xmform returns "MOTIF".

4. The xmgetres program is an example of how to use XmGetSecondaryResourceData. Use the following commands to invoke xmgetres:

   $ xmgetres :== $DECW$EXAMPLES:xmgetres $ xmgetres WidgetClass

   The variable WidgetClass is optional. If WidgetClass is omitted, it defaults to a class named "Widget". You can also use the class "All", which displays the resources for all the Xt and the Motif widgets. See the OSF/Motif Programmer's Reference manual for a list of available widget classes.

V1.2

The xmtravel example is a front end to a travel agent client and flight database. The program is designed to illustrate various user-interface design concepts as well as be compliant with the OSF/Motif Style Guide.

The program is just an example, many of the functions are either not implemented or use predefined settings.

B.4.15 Resource Files for Example Programs

V1.2

Many of the example programs have associated resource files for defining various display attributes. To use these files, either copy them from the directory DECW$EXAMPLES to your DECW$USER_DEFAULTS directory, or add their contents to your DECW$XDEFAULTS.DAT file.

The list of example programs and the resource files associated with them is as follows:

Example Program	Resource File
DECW$CDPLAYER.EXE	DECW$CDPLAYER.DAT
FILEVIEW.EXE	FILEVIEW.DAT
PERIODIC.EXE	PERIODIC.DAT
MOTIFANM.EXE	MOTIFANIM.DAT
XMAPDEF.EXE	XMDEMOS.DAT
XMDIALOGS.EXE	XMDEMOS.DAT
XMEDITOR.EXE	XMDEMOS.DAT
XMFONTS.EXE	XMDEMOS.DAT
XMFORC.EXE	XMDEMOS.DAT
XMFORM.EXE	XMDEMOS.DAT
XMGETRES.EXE	XMDEMOS.DAT
XMLIST.EXE	XMDEMOS.DAT
XMMAP.EXE	XMDEMOS.DAT
XMPROTOCOL.EXE	XMDEMOS.DAT
XMTER.EXE	XMDEMOS.DAT
XMTRAVEL.EXE	XMTRAVEL.DAT

If a resource file is not found, the example programs run, but some of the display attributes may be incorrect.

B.4.16 UID Files for Example Programs

V1.2

The UID files used by the example programs must be located in either the current directory or your DECW$USER_DEFAULTS directory. If they are not found, the application fails to start. The UID files can be copied from the DECW$EXAMPLES directory.

B.5 OSF/Motif List of Known Problems

Included in the DECwindows Motif software is an OSF file that contains the OSF/Motif known problems. During the installation this file is copied from the kit to SYS$HELP:DECW$MOTIF_OSF_BUGLIST_V12.TXT.

Compaq DECwindows Motif for OpenVMS provides the National Center for Supercomputing Applications (NCSA) Mosaic Version 2.4 browser to let you navigate and access information on the Internet.

The NCSA Mosaic browser is provided as sample, "as is" software to introduce you to the Internet and help you get started using a World Wide Web viewer. Because the NCSA Mosaic browser that ships with this release is only a sample implementation, we have placed Mosaic with the other sample software in the DECW$UTILS directory.

The Mosaic browser enables OpenVMS users to search, retrieve, display, store, and forward data using the Internet. Mosaic functions in conjunction with the World Wide Web environment, which is a collection of information servers.

Note that the graphical user interface for Mosaic is not compliant with the Motif style guide; therefore, the Mosaic browser does not look the same as the DECwindows Motif out-of-the-box (OOTB) applications.

The following information about Mosaic is included in this appendix:

• Section C.1, Starting Mosaic Software
• Section C.2, Creating a Home Page
• Section C.3, Configuring Mosaic to Process Multimedia Files
• Section C.4, Customizing the Mosaic Browser
• Section C.5, Restrictions for Using Mosaic from Behind a Firewall

V1.2--3

The Mosaic browser, which is located in the DECW$UTILS directory, is installed as part of the product installation for the Compaq DECwindows Motif for OpenVMS product.

To access the verb and start Mosaic, select Menus... from the Options Menu in FileView. Mosaic is listed in the Item Names list. Add the verb Mosaic to a menu, such as the Applications Menu, so that you can invoke Mosaic and display the DECwindows Motif home page. Refer to Using DECwindows Motif for OpenVMS for information about adding verbs to menus.

V1.2--3

A home page lets you make information about yourself, your company, your products, and so on available on the Internet. Click on the On HTML... topic in the Help menu for information about using HTML (Hypertext Markup Language) to create a home page. HTML uses markup tags to tell Mosaic how to format text. A Beginner's Guide to HTML is displayed, which provides information about markup tags, examples, formatting, creating links, troubleshooting, and so on. Note that you can access topics in the Help menu only if your system is connected to the TCP/IP network using Compaq TCP/IP Services for OpenVMS.

As an example of an HTML source, see the DECwindows Motif sample home page. Click on View Source... from the File menu to see the HTML source.

C.3 Configuring Mosaic to Process Multimedia Files

V1.2--4

The Mosaic browser that is included with Compaq DECwindows Motif for OpenVMS provides support for recognizing and processing the following types of files:

• GIF
• Audio
• MPEG
• MIME

If Mosaic encounters a hyperlink (or an anchor) to any of these file types, it attempts to start an external program to display the image or to play the sound. If Mosaic cannot locate an appropriate external viewer, it prompts the user to enter a file name where the data file can be stored in case the data is needed outside of Mosaic.

To determine what external viewer will display the image or play the sound, Mosaic does the following:

1. Determines the MIME type of the incoming file according to either the file extension or the way the file is specified by the document server.
   If the file extension is used to determine the external viewer, Mosaic uses either a built-in default list or an extension map file that can be configured by the user.
2. Matches the MIME file type of the incoming file to an external viewer according to either the built-in default list or a setup that is configured by the user and specified in the file DECW$UTILS:XMOSAIC-SETUP.COM.

For example, GIF files are mapped to the xv viewer. The xv viewer is shareware software that is not provided with DECwindows Motif. However, the xv viewer is available from the following location as an OpenVMS freeware offering:

http://www.openvms.compaq.com/openvms/internetnetworks.html

The xv mapping is defined in the file DECW$UTILS:XMOSAIC-SETUP.COM, a self-documented command procedure, as follows:

$ XV :== $DECW$EXAMPLES:PICT.EXE

The executable PICT.EXE is used to display the GIF file. Note that PICT.EXE cannot be used to display a JPEG file.

Other mappings include the following:

Image Type	Display/Sound Logical Name
audio/*	-> showaudio
image/xwd	-> xwud
image/x-xwd	-> xwud
image/x-xwindowdump	-> xwud
image/*	-> xv

Mappings in the previous list that are followed by an asterisk (*) are available in some versions of Mosaic (for example, Version 2.4) that contain native HDF/netCDF support.

Additional examples of external view setup in the file DECW$UTILS:XMOSAIC-SETUP.COM can include the following definitions:

$ APLAY :== mcr decsound -volume 70 -speaker -play $ SHOWAUDIO :== mcr decsound -volume 70 -speaker -play $ XWUD :== $decw$utils:xwud.exe

C.4 Customizing the Mosaic Browser

V1.2--4

You can customize the Mosaic browser by setting any of the NCSA Mosaic X resources in the file DECW$USER_DEFAULTS:MOSAIC.DAT.

The class name for Mosaic for X is Mosaic. The information that follows shows the names and descriptions of the X resources. Note that class and resource names are the same except that the first character in the resource name is capitalized.

The following resources are listed:

• Functional resources
• Visual resources
• Font resources
• Proxy gateway resources

Functional Resources

Table C-1 lists the functional resources and descriptions.

Table C-1 Functional Resources

Resource	Description
annotationsOnTop: Boolean	Indicates whether inlined document annotation hyperlinks are prepended to the document (if true) or postpended (if false). (Default is false).
autoPlaceWindows: Boolean	If set to false, the new Document View windows are not automatically positioned by the program itself; your Window Manager determines the placement. (Default is true.)
catchPriorAndNext: Boolean	Controls whether using the keys Prior and Next (Page Up and Page Down on most keyboards) are explicitly caught in the Document View window and passed to the vertical scrollbar, or whether the normal Motif scrolled window mechanism is relied upon to automatically take this action. (Default is false.) If the Page Up and Page Down key sequences are not functioning appropriately for your environment, set this resource to true. (Refer to the information about hot keys.)
confirmDeleteAnnotation: Boolean	Confirms deleted annotations through a confirmation dialog box. (Default is true.)
confirmExit: Boolean	Determines whether the NCSA Mosaic browser pops up a dialog box to confirm exiting from the program when the Exit Program menu option is selected. (Default is true.)
defaultAuthorName: string	Identifies your full name (for example, John Q. Public). Your full name is normally stored in the system password file, and Mosaic extracts the name from that file if this resource is NULL; otherwise, the value of this resource is used. (Default is NULL.)
defaultHeight: integer	Specifies the default height in pixels for a Document View window. (Default is 680.)
defaultHotlistFile: string	Specifies a file name to store the default hotlist (or a list of bookmarks). (Default is ".mosaic-hotlist-default". The value of the environment variable $HOME is prepended to this string.)
defaultWidth: integer	Specifies the default width in pixels for a Document View window. (Default is 620.)
delayImageLoads: Boolean	Selects delayed image loading, which is for users with slow network connections. If set to true, Mosaic substitutes a small icon for inlined-images and an arrow icon for inlined-images that also act as hyperlinks. Clicking on an icon tells Mosaic to load that inlined-image; clicking on the arrow is equivalent to following the associated hyperlink. Selecting Load Images in Current from the Mosaic Options menu loads and displays all the inlined-images in the current document. Delayed image loading can also be selected with the -dil command-line flag or on a per-window basis from the Options menu in Mosaic. (Default is false.)
displayURLsNotTitles: Boolean	Displays URLs wherever document titles are usually displayed, if set to true. (Default is false.)
DocsDirectory: string	Overrides the location of the help documents. (Default is NULL.)
documentsMenuSpecfile: string	Specifies the name of the file that holds an optional "Documents Menu Specfile" to allow sites to add their own Documents menu to the Mosaic menu bar. For more information, see the documentation about creating a configurable Documents menu. (Default is "/usr/local/lib/mosaic/documents.menu".)
fancySelections: Boolean	Cuts and pastes from the Document View window with fancy selections enabled in the HTML widget, which results in underlined headers, bulleted lists, and so on, if set to true. Uses normal selection behavior if set to false. Note that selections can be for each window at any time. (Default is false.)
fullHostname: string	Allows explicit setting of the fully qualified host name for systems that fail on a call to gethostbyname(). Use the fullHostname resource only if necessary, in conjunction with gethostbynameIsEvil.
gethostbynameIsEvil: Boolean	Set to true if you are running your system on a Sun set up so that when the system attempts to find its own full host name through gethostbyname(), the system coredumps. (Default is false.)
globalExtensionMap: string	Set to the location of the system-wide extension map config file of your choice. (Default is "/usr/local/lib/mosaic/mime.types".)
globalHistoryFile: string	Specifies the name of the file to store the global history of all documents accessed from session to session. (Default is .mosaic-global-history. The value of the environment variable $HOME will be prepended to this string.)
globalTypeMap: string	Specifies the location of the system-wide mailcap (type map config) file of your choice. (Default is "/usr/local/lib/mosaic/mailcap".)
gunzipCommand: string	Specifies the command to uncompress gzip files (that is, files with an extension of .z.) You can obtain gunzip from prep.ai.mit.edu in /pub/gnu. (Default is gunzip -n -f, which requires the 1.2.4 version of gzip.)
hdfMaxImageDimension: integer	Specifies the maximum height and/or width of an HDF inlined image in pixels. (Default is 400.)
hdfMaxDisplayedDatasets: integer	Specifies the maximum number of displayed data sets while browsing HDF files. If more than the maximum number exist in an HDF file, Mosaic displays the HDF file in "brief mode". (Default is 15.)
hdfMaxDisplayedAttributes: integer	Specifies the maximum number of displayed attributes while browsing HDF files. If more than the maximum number exist in an HDF file, Mosaic displays the HDF file in "brief mode." (Default is 10.)
hdfPowerUser: Boolean	Set to true if most of the supporting text in an HDF file will be removed. (Default is false.)
homeDocument: string	Specifies the document to access at program startup. See the information about on specifying your home document. (Default is http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/ NCSAMosaicHome.html)
imageCacheSize: integer	Specifies the size of the inlined-image cache in kilobytes. The -ics command-line flag can also be used. All the images in a given document are (temporarily) cached while on that page, regardless of the imageCacheSize value. Cache flushes the least recently viewed. (Default is 2048.)
initialWindowIconic: Boolean	Set to true if the first Document View window opened (when the program starts) will be iconified. (Default is false.)
maxWaisResponses: integer	Controls the maximum number of matches Mosaic accesses from a WAIS server. (Default is 200.)
personalAnnotationDirectory: string	Specifies the name of the directory in which to store personal annotations (as well as the log file of all personal annotations currently in existence). If the named directory does not exist, it is created. However, intermediate directories, if any are named, are not created. (Default is .mosaic-personal-annotations. The value of the environment variable $HOME will be prepended to this string.)
personalExtensionMap: string	Specifies the location of the personal extension map configuration file of your choice. The value of the environment variable HOME is prepended. (Default is .mime.types)
personalTypeMap: string	Specifies the location of the personal mailcap file of your choice. The value of the environment variable HOME is prepended. (Default is .mailcap)
printCommand: string	Specifies the name of the default command for the Print menu option. This command accepts a single argument: the name of the file to print. Note that this location can be changed at any time through the Print option's dialog box. (Default is lpr)
recordCommandLocation: string	Specifies the location (full path name) of the command used to record audio annotations (on Sun, SGI, and HP platforms). If the named command does not exist when Mosaic is started, audio annotations are disabled (the menu entry becomes insensitive). (Default is "/usr/sbin/recordaiff" on SGI; "/usr/demo/SOUND/record" on Sun; "/usr/audio/bin/srecorder" on HP.)
recordCommand: string	Specifies the command used to record audio annotations; this is the full command, using the command named in recordCommandLocation as the first word. (Default is "recordaiff -n 1 -s 8 -r 8000" on SGI; "record" on Sun; "srecorder -au" on HP. The named command accepts a single additional argument: the file name of the new audio file. The command also correctly terminates recording when a SIGINT is sent.)
reloadReloadsImages: Boolean	Clears out the Reload option cached image data for the current document before reloading the document if set to true; thus causing the images to also be reloaded. This is useful for HTML authors who are using Mosaic to view their work. (Default is false.)
sendmailCommand: string	Specifies a pointer to the sendmail binary. It assumes that this program accepts command-line arguments that specify addresses to which messages should be mailed and accepts other headers and message text from stdin. (Default is "/usr/lib/sendmail".)
simpleInterface: Boolean	Allows the Mosaic menu bar and bottom button configuration to be minimized considerably. (Default is false).
tmpDirectory: string	Specifies the name of the directory in which to store temporary files generated by Mosaic. This directory should contain at least 10 or 20 megabytes, in case you to pull down a very large data file. Setting this resource is equivalent to using the command-line flag, -tmpdir, or setting the environment variable TMPDIR.
trackFullURLs: Boolean	Enables prototypical smart display of "where you're going" during mouse tracking, including format definition, if set to false. (Default is true.)
trackPointerMotion: Boolean	Sets the mouse pointer so that it will not be tracked so that URLs are visible on the lower status line, if set to false. (Default is true.)
trackVisitedAnchors: Boolean	Displays visited anchors (that is, anchors that point to documents that have previously been viewed) with a different style than anchors that are not yet visited, if set to true. (On slow systems, changing this resource to false may substantially improve the performance of Mosaic.) (Default is true.)
tweakGopherTypes: Boolean	Mosaic interprets Gopher documents strictly by the Gopher typing system, if set to false. When set to true, Mosaic uses its own mechanism to determine the file types of Gopher documents. (Default is true.)
twirlIncrement: integer	Indicates the minimum number of bytes that are are transferred between updates of the twirling transfer icon for normal (FTP, Gopher, HTTP) transfers. (Default is 4096.)
twirlingTransferIcon: Boolean	Set to false to turn off the twirling NCSA logo during document transfers. Clicking the icon still interrupts a transfer. (Default is true.)
uncompressCommand: string	Specifies the command to uncompress compressed files (that is, files with an extension of .Z). (Default is uncompress).
useDefaultExtensionMap: Boolean	Set to false to keep any default file-extension-to-MIME-type mappings from Mosaic. Keeping this resource setting to true and overriding the default as necessary is strongly recommended. (Default is true.)
useDefaultTypeMap: Boolean	Set to false to keep any default MIME-type-to-external-viewer mappings from Mosaic. It is strongly recommended that you leave this resource set to true; override the setting as necessary. (Default is true.)
useGlobalHistory: Boolean	Automatically stores a global history of everywhere you visit, if set to true. (This history is used to shade anchors in different colors based on whether you visited the corresponding documents, if the resource trackVisitedAnchors is set to true.) (Default is true.)
xtermCommand: string	Specifies the name of the command used to start a terminal window for a telnet session. (Default is xterm on most platforms; the default is aixterm -v on IBM AIX 3.x systems.)