The Desktop uses file typing rules (FTRs) to evaluate all files that are presented within the Desktop. This chapter describes each of the file typing rules in detail, and offers suggestions for good file typing style and strategies. “Defining the Behavior of Icons With FTRs” in Chapter 2 in IRIX Interactive User Interface Guidelines describes the behaviors your icon should support.
This chapter contains these sections:
“A Table of the FTRs With Descriptions” provides a reference table listing the FTRs along with brief descriptions.
“Naming File Types: The TYPE Rule” describes the TYPE rule, used to name a file typ.
“Categorizing File Types: The SUPERTYPE Rule” describes the SUPERTYPE rule, used to categorize file types.
“Matching File Types With Applications: The MATCH Rule” describes the MATCH rule, used to match the application with the corresponding file type.
“Matching Non-Plain Files: The SPECIALFILE Rule” describes the SPECIALFILE rule, used to match non-plain files.
“Adding a Descriptive Phrase: The LEGEND Rule” describes the LEGEND rule, used to provide a brief phrase describing the application or data file.
“Setting FTR Variables: The SETVAR Rule” describes how to set variables that affect the way your icon behaves.
“Programming Open Behavior: The CMD OPEN Rule” describes the CMD OPEN rule, used to define what happens when users open the icon.
“Programming Alt-Open Behavior: The CMD ALTOPEN Rule” describes the CMD ALTOPEN rule, used to define what happens when users double-click your icon while pressing the <Alt> key.
“Programming Drag and Drop Behavior: The CMD DROP and DROPIF Rules” describes the CMD DROP rule, used to define what happens when a user drags another icon and drops it on top of your application's icon.
“Mapping Names: The MAP Rule” describes the MAP rule, used to specify a list of all mappings from the desktop name space.
“Programming Print Behavior: The CMD PRINT Rule” describes the CMD PRINT rule, used to tell the Desktop what to do when a user selects your icon, then selects “Print” from the Desktop popup menu.
“Adding Menu Items: The MENUCMD Rule” describes the MENUCMD rule, used to add menu items to the Desktop menu
“Getting the Icon Picture: The ICON Rule” describes how to tell the Desktop where to find the file(s) containing the picture(s) of the icon for a file type
“Creating a File Type: An Example” provides a detailed example of how to program an icon.
Table 13-1 lists the rules that appear in a filetype definition along with brief descriptions.
Table 13-1. Rules That Appear in a Filetype Definition
Rules | Function |
|---|---|
TYPE | |
Tells the Desktop to treat the file as a subset of another type under certain circumstances. | |
Lets the Desktop determine if a file is of the declared type. | |
Tells the Desktop to use the file typing rule only on non-plain files. | |
Provides a text description of the file type. | |
Sets variables that affect the operation of your icon. | |
Defines a series of actions that occur when a user double-clicks the mouse on an icon or selects “open” from the main menu. | |
Defines a series of actions that occur when a user alt-double-clicks the mouse on an icon. | |
Defines a series of actions that occur when a user “drops” one icon on top of another. | |
Defines a set of file types that the icon will allow to be dropped on it. | |
Defines a series of actions that occur when a user chooses “Print” from the Desktop or Directory View menus. | |
Defines menu entries that appear in the Desktop menu and the Selected toolchest when an icon is selected. | |
Defines the appearance (geometry) of the file type's icon. | |
Maps the Desktop file-type name with the ICCCM or MIME target-type names. |
All file types must begin with a TYPE rule. Aside from that, the rules can appear in any order; however, the most efficient order for parsing is to include the MATCH rule second and the ICON rule last.
It is important that your file type have a unique name so that it doesn't collide with Silicon Graphics types or types added by other developers. A good way to generate a unique file type name is to base your file type name on your application name (which is presumably unique). Another method is to include your company's initials or stock symbol in the file type name. You can also use the grep(1) command to search through existing .ftr files:
% grep name /usr/lib/filetype/*/*.ftr |
Substitute your proposed new type name for the words name. If grep doesn't find your name, then go ahead and use it.
You name a file type by using the TYPE rule. You can define more than one file type in a single file, as long as each new file type begins with the TYPE rule. The TYPE rule always goes on the first line of the file type definition.
Here is the syntax and description for the TYPE rule:
| Syntax: | TYPE type-name | |
| Description: | type-name is a one-word ASCII string. You can use a legal C language variable as a type name. Choose a name that is in some way descriptive of the file type it represents. All rules that follow a TYPE declaration apply to that type, until the next TYPE declaration is encountered in the FTR file. Each TYPE declaration must have a unique type name. | |
| Example: | TYPE GenericExecutable |
Use the SUPERTYPE rule to tell other file types that your file type should be treated as a “subset” of a larger type such as executables or directories. For example, you can create an executable with a custom icon, then use the SUPERTYPE rule to tell other Desktop file types that the icon represents an executable.
 | Note: In general, file types don't “inherit” icons, rules, or any other behavior from SUPERTYPEs. Directories are a special case. The Desktop automatically handles the DROP, OPEN, and ALTOPEN behavior for all directories marked as “SUPERTYPE Directory.” You can't override the DROP, OPEN, or ALTOPEN behavior if you include “SUPERTYPE Directory.” |
You can use any existing file type as a SUPERTYPE. Appendix E, “Predefined File Types”, lists some of the file types defined by Silicon Graphics. You can generate a complete list of file types installed on your system using the grep(1) command:
% grep TYPE /usr/lib/filetype/*/*.ftr |
| Note: The list of file types generated by the above command is very long and unsorted. |
Here is the syntax and description for the SUPERTYPE rule:
| Syntax: | SUPERTYPE type-name [type-name … ] | |
| Description: | type-name is the TYPE name of any valid file type. Use SUPERTYPE to identify the file type as a “subset” of one or more other file types. This information can be accessed by other file types by calling isSuper(1) from within their CMD rules (OPEN, ALTOPEN, and so on). A file type can have multiple SUPERTYPEs. (For example, the Script file type has both Ascii and SourceFile SUPERTYPES.) See the isSuper(1) reference page for more information. | |
| Example: | SUPERTYPE Executable |
A common use for SUPERTYPEs is to allow users to drag data files onto other application icons to open and manipulate them. For example, if your application uses ASCII data files but you create a custom data type for those files, you can include in the file type declaration:
SUPERTYPE Ascii |
This allows users to drag your application's data files onto any text editor to open and view them. If your application creates images files, you could make a similar declaration to allow users to drag data file icons to appropriate image viewers such as ipaste(1).
The Desktop needs some way to figure out which FTRs pair up with which files. Your FTRs will not work if they don't include some way for the Desktop to match them with the appropriate files. To do this, include the MATCH rule in your file type definition. This section explains how to use the MATCH rule to identify your files. The method you use depends on the kind of file you are matching and on the file permissions. First, here's the MATCH rule syntax and description:
| Syntax: | MATCH match-expression; | |
| Description: | match-expression is a logical expression that should evaluate to true if, and only if, a file is of the type declared by TYPE. The match-expression must consist only of valid MATCH functions, as described later in this section. The match-expression can use multiple lines, but must terminate with a semicolon (;). Multiple match-expressions are not permitted for a given type. The MATCH rule is employed each time a file is encountered by the Desktop, to assign a type to that file. | |
| Examples: | MATCH tag == 0x00001005; |
The easiest way to match your application with its FTRs is to use the tag(1) command to assign a unique number to the application itself. You can then label the associated FTRs with this same unique number, using the MATCH rule, as shown in the example above.
There are a few situations in which you cannot use tag to label your files. You cannot use tag if:
your file is neither an executable nor a shell script
you don't have the necessary permissions to change the file
For more information on matching your files without using the tag command, see “Matching Files Without the tag Command”.
To tag your application and its associated FTRs using the tag command, follow these steps:
The tag command attaches an identification number to your application. Before you tag your application, select a number that is not already in use. Silicon Graphics assigns each company (or individual developer) a block of ID numbers for tagging files at no cost. If your company doesn't already have an assigned block of numbers, just send a request to Silicon Graphics. The best way is to e-mail your request to this address:
desktoptags@sgi.com
Once you have your block of numbers, you can select a number from the block of numbers assigned to your company. Make sure that you select a number that no one else in your company is using.
After you select a unique tag number for your application, go to the directory that contains your application and tag it using the tag command. This is the syntax:
% tag number filename
Replace the word number with the number that you are assigning to the application and filename with the name of your application. For more information on the tag command, see the tag(1) reference page.
After tagging the application itself, include the tag in your application's FTRs, using the MATCH rule. Just include a line like this in your FTR file:
MATCH tag == number;where number is the unique tag number assigned to your application.
You can also use the tag command to automatically assign a tag number for a predefined file type. Silicon Graphics provides a set of generic types, called predefined types, that you can use for utilities that do not require a personalized look. These predefined file types come complete with icons, FTRs, and tag numbers. Use the appropriate tag command arguments to get the desired file type features. For more information on tag arguments, see the tag(1) reference page. The predefined file types are listed in Appendix E, “Predefined File Types”.
If you cannot use the tag command to match your application with the corresponding FTRs, you need to write a sequence of expressions that check files for distinguishing characteristics. Once you have written a sequence of expressions that adequately defines your application file, include that sequence in your FTR file, using the MATCH rule. For example, you can use this MATCH rule to match a C source file:
MATCH glob("*.c") && ascii;
|
The glob function returns TRUE if the filename matches the string within the quotes. The ascii function returns TRUE if the first 512 bytes of the file are all printable ASCII characters. (Table 13-3 lists all of the available match-expression functions.) The && conditional operator tells the Desktop that the functions on either side of it must both return TRUE for a valid match. See “Valid Match-Expressions” for a list of all of the operators, constants, and numerical representations that you can use in your match-expressions.
The most effective way to order match-expressions in a single MATCH rule is to choose a set of expressions, each of which tests for a single characteristic, and conjoin them all using “and” conditionals (&&).
The order in which you list the expressions in a MATCH rule is important. Order the expressions so that the maximum number of files are “weeded out” by the first expressions. This is advised because the conditional operator, &&, stops evaluation as soon as one side of the conditional is found to be false. Therefore, the more likely an expression is to be false, the further to the left of the MATCH rule you should place it.
For instance, in the previous MATCH expression example, it is more efficient to place the glob("*.c") expression first because there are many more ASCII text files than there are files that end in .c.
Since the Desktop scans FTR files sequentially, you must make sure that your match rule is specific enough not to “catch” any unwanted files. For example, suppose you define a type named “myDataFile” using this MATCH rule:
MATCH ascii; |
Now every text file in your system will be defined as a file of type “myDataFile.”
This section describes the syntax and function of valid match-expressions. You can use these C language operators in a match-expression:
+ | - |
* | / |
& | | |
^ | ! |
% | ( ) |
You can use these C language conditional operators in a match-expression:
&& | || |
== | != |
< | > |
<= | >= |
The `==' operator works for string comparisons in addition to numerical comparisons.
You can use these constants in a match-expression:
true false |
You can represent numbers in match-expressions in decimal, octal, or hexadecimal notation. See Table 13-2.
Table 13-2. Numerical Representations in Match-Expressions
Representation | Syntax |
|---|---|
decimal | num |
octal | 0num |
hexadecimal | 0xnum |
Table 13-3 lists the valid match-expression functions.
Table 13-3. Match-Expression Functions
Function Syntax | Definition |
|---|---|
ascii | Returns TRUE if the first 512 bytes of the file are all printable ASCII characters. |
char(n) | Returns the nth byte in the file as a signed character; range is -128 to 127. |
dircontains("string") | Returns TRUE if the file is a directory and contains the file named by string. Allows use of the following expansions in string for pattern matching: { } [ ] * ? and backslash (see sh(1) filename expansion). See “Using dircontains()” for more information. |
glob("string") | Returns TRUE if the file's name matches string;. Allows use of the following expansions in string for pattern matching: { } [ ] * ? and backslash (see sh(1) filename expansion). |
linkcount | Returns the number of hard links to the file. |
long(n) | Returns the nth byte in the file as a signed long integer; range is -231 to 231 - 1. |
mode | Returns the mode bits of the file (see chmod(1)). |
print(expr or "string") | Prints the value of the expression expr or string to stdout each time the rule is evaluated; used for debugging. Always returns true. |
short(n) | Returns the nth byte of the file as a signed short integer; range is -32768 to 32767. |
size | Returns the size of the file in bytes. |
string(n,m) | Returns a string from the file that is m bytes (characters) long, beginning at the nth byte of the file. |
uchar (n) | Returns the nth byte of the file as an unsigned character; range is 0 to 255. |
tag | Returns the specific Desktop application tag injected into an executable file by the tag injection tool (see the tag(1) reference page.) Returns -1 if the file is not a tagged file. |
ushort(n) | Returns the nth byte of the file as an unsigned short integer; range is 0 to 65535. |
In order to use the dircontains() function, you need to include these two rules in your filetype definition:
SUPERTYPE SpecialFile
SPECIALFILE
|
You can declare more than one SUPERTYPE in a file type, so the following would be a legal FTR file:
TYPE scrimshawToolsDir
MATCH dircontains(".toolsPref");
LEGEND Scrimshaw drawing tools directory
SUPERTYPE Directory
SUPERTYPE SpecialFile
SPECIALFILE
ICON {
if (opened) {
include("../iconlib/generic.folder.open.fti");
} else {
include("../iconlib/generic.folder.closed.fti");
}
include("iconlib/scrimshaw.tools.dir.fti");
}
|
For some applications, you may not want to create a unique file type and icon. Several predefined file types exist and you can use them as necessary. If you use a predefined file type for your application, tag can automatically assign it a tag number. Just use the appropriate command line arguments as described in the tag(1) reference page. The predefined file types and their tag numbers are listed in Appendix E, “Predefined File Types”.
SPECIALFILE is used to distinguish a file typing rule used for matching non-plain files. Device files and other non-plain files can cause damage to physical devices if they are matched using standard file typing rules (which might alter the device state by opening and reading the first block of the file).
| Syntax: | SPECIALFILE | ||||
| Description: | Special files are matched using only rules containing SPECIALFILE, which are written so as not to interfere with actual physical devices. Similarly, plain files are not matched using rules containing a SPECIALFILE rule. | ||||
| Example: | SPECIALFILE
|
The SUPERTYPE declaration allows applications to use isSuper(1) to test whether your file type is a SPECIALFILE.
Use the LEGEND rule to provide the Desktop with a short phrase that describes the file type. This phrase appears when users view your icon's directory as a list. It also appears when a user selects your icon, then selects the “Get File Info” item from the Desktop menu. Make your legend simple and informative and keep it to 25 characters or less.
Here is the syntax and description for the LEGEND rule:
| Syntax: | LEGEND text-string | |
| Description: | text-string is a string that describes the file type in plain language that a user can understand. Legends that are longer than 25 characters might be truncated in some circumstances. | |
| Example: | LEGEND C program source file |
You might also see a LEGEND rule that is prepended with a number between two colons—something like this:
LEGEND :290:image in RGB format |
The colons and the number between them are used for internationalization. For more information, refer to “Internationalizing File Typing Rule Strings” in Chapter 4 of the Topics in IRIX Programming.
The SETVAR rule allows you to set variables that affect operation of your icon.
| Syntax: | SETVAR variable value | |
| Description: | variable is a FTR variable and value is the value to assign to the variable. Currently, two FTR variables are supported: noLaunchEffect and noLaunchSound. Set noLaunchEffect to True to turn off the visual launch effect when the user opens your icon. Set noLaunchSound to True to turn off the launch sound effect when the user opens your icon. | |
| Example: | SETVAR noLaunchEffect True |
Use the CMD OPEN rule to tell the Desktop what to do when a user opens your icon. Users can open an icon in any of these ways:
double-clicking it
selecting it and then choosing the “Open” item from the Desktop popup menu (the Desktop menu is the menu that appears when you hold down the right mouse button while the cursor is over the Desktop background)
selecting it and then choosing the “Open Icon” selection in the Selected tool chest.
Note: Directories are a special case. The Desktop automatically handles the OPEN behavior for all files marked as “SUPERTYPE Directory.” You can't override the OPEN behavior if you include “SUPERTYPE Directory.”
Here is the syntax and description for the CMD OPEN rule:
| Syntax: | CMD OPEN sh-expression[; sh-expression; … ; sh-expression] | |
| Description: | The OPEN rule should reflect the most frequently used function that would be applied to a file of the given type. sh-expression can be any valid Bourne shell expression. Any expression can use multiple lines. Any number of expressions can be used, and must be separated by semicolons (;). The final expression should not end with a semicolon. Variables can be defined and used as in a Bourne shell script, including environment variables. See Appendix B, “Desktop Variables” for a list of special environment variables set by the Desktop. These environment variables can be used to refer to the currently selected icons within the Desktop or Directory View. | |
| Examples: | CMD OPEN $WINEDITOR $SELECTED The CMD OPEN rule for the “Makefile” file type is more complex: TYPE Makefile ... CMD OPEN echo "make -f $LEADER |& tee $LEADER.log; rm $LEADER.run" \ > $LEADER.run; winterm -H -t make -c csh -f $LEADER.run |
By using the CMD ALTOPEN rule, you can tell the Desktop what to do when users double-click your icon while pressing the <Alt> key.
| Note: Directories are a special case. The Desktop automatically handles the ALTOPEN behavior for all files marked as “SUPERTYPE Directory.” You can't override the ALTOPEN behavior if you include “SUPERTYPE Directory.” |
Here is the syntax and description for the CMD ALTOPEN rule:
| Syntax: | CMD ALTOPEN sh-expression[; sh-expression; … ; sh-expression] | ||
| Description: | The ALTOPEN rule provides added functionality for power users. Typically, you set ALTOPEN to pop up a launch window to let the user edit arguments. sh-expression can be any valid Bourne shell expression. Any expression can use multiple lines. Any number of expressions can be used, and must be separated by semicolons (;). The final expression should not end with a semicolon. Variables can be defined and used as in a Bourne shell script, including environment variables. See Appendix B, “Desktop Variables” for a list of special environment variables set by the Desktop. These environment variables can be used to refer to the currently selected icons within the Desktop or Directory View. | ||
| Examples: | CMD ALTOPEN launch -c $LEADER $REST The CMD ALTOPEN rule for the “SGIImage” file type, defined in /usr/lib/filetype/system/sgiimage.ftr, is more complex:
|
In the previous example:
This filetype uses the IMGVIEWER environment variable. This is one of six environment variables the user can set on the Desktop Utilities panel (/usr/sbin/dtUtilities). Your filetype should make use of such utilities as well, if appropriate. For example, if your application needs to open some data into an editor for one of its rules, then the rule should check for the WINEDITOR variable and use it to open the data. For more information on dtUtilities, see Chapter 10, “Using the Default Viewer and Editor Utilities Panel” in Chapter 10.
This filetype posts a dialog if it can't find any appropriate applications in which to open the SGIImage file. This dialog has text that you can translate into other languages; the embedded gettxt commands retrieve the text in the appropriate language from the specified uxsgidesktop message catalog. You can make a message catalog to hold your own messages, then use gettxt to make your filetypes use these messages. For more information, see Chapter 11, “Step Three: Programming Your Icon” in Chapter 11.
Users can perform certain functions by dragging an icon and dropping it on top of another icon. For example, users can move a file from one directory to another by dragging the icon representing the file and dropping it onto the icon representing the new directory. You use the CMD DROP rule to tell the Desktop what to do when a user drags another icon and drops it on top of your application's icon.
| Note: Directories are a special case. The Desktop automatically handles the DROP behavior for all files marked as “SUPERTYPE Directory.” You can't override the DROP behavior if you include “SUPERTYPE Directory.” |
Here is the syntax and description for the CMP DROP rule:
| Syntax: | CMD DROP sh-expression[; sh-expression; … ; sh-expression] | |
| Description: | The DROP rule is invoked whenever a selected (file) icon is “dropped” onto another icon in the Desktop or Directory View windows. When this happens, the Desktop checks to see if the file type being dropped upon has a DROP rule to handle the files being dropped. In this way, you can write rules that allow one icon to process the contents of other icons. Simply drag the selected icons that you want processed and put them on top of the target icon (that is, the one with the DROP rule). | |
| Example: | CMD DROP $TARGET $SELECTED |
By default, the CMD DROP rule handles all icons dropped on the target icon. However, if you include a DROPIF rule in your file type, only those icons whose file types are listed in the DROPIF rule are accepted as drop candidates; the Desktop doesn't allow the user to drop other types of icons on the target icon. Here is the syntax and description for the DROPIF rule:
| Syntax: | DROPIF file-type [ file-type … file-type] | |
| Description: | Specifies the allowable file types that a user can drop on the icon. | |
| Example: | DROPIF MailFile |
Using the DROPIF rule in conjunction with the CMD DROP rule is a good practice to follow to ensure that the file types of selected icons are compatible with the selected icon. You can also use the environment variables set by the Desktop, listed in Appendix B, “Desktop Variables”, to determine other attributes of the selected icons.
For example, the following CMD DROP and DROPIF rules accept only a single icon with the type “MyAppDataFile”:
DROPIF MyAppDataFile
CMD DROP if [ $ARGC -gt 1 ]
then
inform "Only one data file allowed."
else
$TARGET $SELECTED
|
In the example above, the DROPIF rule prevents users from dropping any file on the target icon except those with the type “MyAppDataFile.” The CMD DROP rule is invoked only after a successful drop. It checks the value of the environment variable ARGC to see how many icons were dropped on the target icon. If more than one icon is dropped, it displays an error message; if only one is dropped, it invokes the application with the dropped file as an argument.
| Note: The DROPIF rule doesn't “follow” SUPERTYPES. If you specify a file type in a DROPIF rule, only files of that type are accepted, not files that have that type as a SUPERTYPE. |
If you want to handle all files with a given SUPERTYPE, you must use isSuper(1) to test for that SUPERTYPE in the CMD DROP rule. The following CMD DROP definition demonstrates this by accepting one or more files with an “Ascii” SUPERTYPE:
CMD DROP okfile='true'
for i in $SELECTEDTYPELIST
do
if isSuper Ascii $i > /dev/null
then
okfile='true'
else
okfile='false'
fi
done
if [ $okfile = 'true' ]
then
$TARGET $SELECTED
else
xconfirm "$TARGET accepts only ASCII files."
fi
|
If you want your datafile to work with the GoldenGate conversion, which is based on ICCCM target type names, you need to use the MAP rule to associate the desktop file-type name with the ICCCM target-type name. Then GoldenGate can access the ICCCM type.
| Syntax: | MAP namespace value | ||
| Description: | The MAP rules specify a list of all mappings from desktop name space to a non-desktop name. Desktop namespace is defined by the TYPE names. The value is mapped onto the desktop type, which you can obtain based on the value or TYPE name. You can use the MAP rule to translate from a desktop TYPE to another name space, such as ICCCM or MIME types. In the example below, the keyword SelectionTarget indicates a ICCCM name space. | ||
| ICCCM Example: |
|
For more information about GoldenGate conversion, see Appendix G, “Using GoldenGate Data Conversion Services”, and “Data Conversion Service” in Chapter 7.
Use the CMD PRINT rule to tell the Desktop what to do when a user selects your icon, then selects “Print” from the Desktop popup menu. Here is the syntax and description for the CMD PRINT rule; see also Chapter 14, “Printing From the Desktop”, for information on writing rules to convert your new file type into one of the printable types.
| Syntax: | CMD PRINT sh-expression[; sh-expression; … ; sh-expression] | |
| Description: | sh-expression can be any valid Bourne shell expression. Any expression can use multiple lines. Any number of expressions can be used, and must be separated by semicolons (;). The final expression should not end with a semicolon. Variables can be defined and used as in a Bourne shell script, including environment variables. See Appendix B, “Desktop Variables” for a list of special environment variables set by the Desktop. These environment variables can be used to refer to the currently selected icons within the Desktop or Directory View. The recommended method of implementing the PRINT rule is to use routeprint, the Desktop's print-job routing utility, as in the example below. routeprint uses print conversion rules to automatically convert the selected files into formats accepted by the system's printers. See the routeprint(1) reference page for details on its syntax. See Chapter 14, “Printing From the Desktop” for information on setting up print conversion rules. | |
| Example: | CMD PRINT routeprint $LEADER $REST |
Use the MENUCMD rule to add items to the bottom of both the Desktop menu and the Selected toolchest menu. The Desktop menu is the menu that appears when you hold down the right mouse button while the cursor is positioned on the Desktop. The Selected toolchest menu is the menu that appears when you hold down the left mouse button while the cursor is positioned over the Selected toolchest menu.
Menu items added to the Desktop menu and the Selected toolchest menu appear only when the icon is selected (highlighted in yellow) on the Desktop.
You can add as many menu items as you like by adding multiple MENUCMD rules to your file type. Any menu items added using the MENUCMD rule are added both to the Desktop menu and the Selected toolchest menu—you can't add menu items to just one of these menus.
Here is the syntax and description for the MENUCMD rule:
| Syntax: | MENUCMD "string" sh-expression[; sh-expression; … ; sh-expression] | |
| Description: | MENUCMD inserts the menu entry string into the Desktop or Directory View menu if a single file of the appropriate type is selected, or if a group of all of the same, appropriate type is selected. If the menu entry is chosen, the actions described by the sh-expressions are performed on each of the selected files. | |
| Example: | MENUCMD "Empty Dumpster" compress $LEADER $REST |
You might also see a MENUCMD rule that is prepended with a number between two colons—something like this:
MENUCMD :472:"make install" winterm -H -t 'make install' \
-c make -f $LEADER install
|
The colons and the number between them are used for internationalization. For more information, refer to “Internationalizing File Typing Rule Strings” in Chapter 4 of the Topics in IRIX Programming.
To add more than one menu item to the Desktop popup menu, just add a MENUCMD rule for each item. For example, the “Makefile” file type includes all of the following MENUCMD rules:
MENUCMD "make install" winterm -H -t 'make install' \
-c make -f $LEADER install
MENUCMD "make clean" winterm -H -t 'make clean' \
-c make -f $LEADER clean
MENUCMD "make clobber" winterm -H -t 'make clobber' \
-c make -f $LEADER clobber
MENUCMD "Edit" $WINEDITOR $LEADER $REST
|
Use the ICON rule, described in this section, to tell the Desktop where to find the file(s) containing the picture(s) of the icon for a file type. The simplest way to do this is to provide the full IRIX pathname. For example, if the .fti file is in the directory called /usr/lib/filetype/install/iconlib, you would simply write that pathname directly into your FTR file.
If you prefer not to use the absolute pathname in your FTR, you can use a relative pathname, as long as the icon file resides anywhere within the /usr/lib/filetype directory structure. To make use of relative pathnames, list the pathname relative to the directory containing the FTR file that contains the ICON rule. If you choose to do this, take care to keep path names used in FTR files synchronized with icon locations.
The Desktop sets Boolean status variables to indicate the state of an icon. You can use conditional statements that test these variables to alter the appearance of an icon based on its state. The state variables are: opened, which is True when the icon is opened; and selected, which is True when the icon is selected.
As described in “Importing Generic Icon Components (Magic Carpet)” in Chapter 12, a common technique is to draw a unique badge to identify an application and then combine that badge with a generic icon component. This works well if you also use conditional statements to change the appearance of an icon depending on its state. You can then combine the unique badge with a generic icon component appropriate to the icon's state. The example shown below demonstrates this technique.
Use the basic format from the example below to tell the Desktop where to find your icon files (the files that you created using IconSmith). Here is the syntax and description for the ICON rule:
| Syntax: | ICON icon-description-routine | ||||
| Description: | icon-description-routine is a routine written using the icon description language, detailed below. The routine can continue for any number of lines. The ICON rule is invoked any time a file of the specified type needs to be displayed in the Desktop or Directory View. The rule is evaluated each time the icon is painted by the application that needs it. | ||||
| Examples: | ICON {
The example above shows you exactly how to write the standard ICON rule. The first line invokes the ICON rule. The next two lines tell the Desktop where to find the parts of the icon representing the open and closed “magic carpet” that makes up the generic executable icons. The unique badge is in a file named ack.fti.
|
If you have two separate badges, one for the open and one for the closed state, your ICON rule is:
ICON {
if (opened) {
include("../iconlib/generic.exec.open.fti");
include("iconlib/ack.open.fti");
} else {
include("../iconlib/generic.exec.closed.fti");
include("iconlib/ack.closed.fti");
}
}
|
Notice that this example gives the pathname of the icon files (.fti files) relative to the directory in which the FTR file is located. You can use the full pathname if you prefer. Your icon description routine would then look like this, assuming that ack.fti was placed in /usr/lib/filetype/install/iconlib:
ICON {
if (opened) {
include("/usr/lib/filetype/iconlib/genericexec.open..fti");
else {
include("/usr/lib/filetype/iconlib/generic.exec.close.fti");
}
include("/usr/lib/filetype/install/iconlib/ack.fti");
}
|
This section provides an example that demonstrates how to write a file type. In this example, assume we're writing a file type for a simple text editor called scribble and that we've decided on these behaviors for the scribble icon:
When a user double-clicks the scribble icon, the Desktop runs the application.
When a user drops another icon onto the scribble icon, the Desktop brings up the scribble application with the file represented by the dropped icon. Users can then use the scribble application to edit this file.
Note: We're making no provision for rejecting icons that represent files unsuitable for editing. You could enhance the scribble file type by including a line that tells the Desktop to notify users when they drop an icon of the wrong type onto the scribble icon.
(This section assumes that we're writing the file type completely from scratch. You might prefer instead to modify an existing file type. To learn how to find the FTRs for an existing icon, see “Add the FTRs: An Alternate Method” in Chapter 11.)
For the purposes of this example, assume we're creating a new FTR file, rather than adding to an existing one. We just open a new file using any editor we choose, then type in whatever file typing rules we decide to use.
Now that we've opened a file for the FTRs, we just type in the rules we need to program the icon. The file type has to begin with the TYPE rule on the first line. The TYPE rule names the file type. This section discusses each line we use to create the file type.
Each file type has to have a unique name. Since our application is called scribble, assume that we decide to name the new file type “scribbleExecutable.” By basing the file type name on the application name, we help insure a unique file type name.
Before using the name, scribbleExecutable, we search for it in the /usr/lib/filetype directory, to make sure that the name is not already in use:
Change to the /usr/lib/filetype directory:
% cd /usr/lib/filetype
Search for the name scribbleExecutable:
% grep "scribbleExecutable" */*.ftr
Assume that we do not find an existing file type with the name “scribbleExecutable,” so that's what we name the new file type.
Now we use the TYPE rule to name the file type by typing this line into our FTR file:
TYPE scribbleExecutable |
For more information on the TYPE rule, see “Naming File Types: The TYPE Rule”.
Next we use the SUPERTYPE rule to tell the Desktop what type of file the icon represents. Since scribble is an executable, we add this line to the FTRs:
SUPERTYPE Executable |
For more information on the SUPERTYPE rule, see “Categorizing File Types: The SUPERTYPE Rule”.
Now we add the scribble executable's tag number to the file type definition by adding this line to the FTRs:
MATCH tag == 0x00001001; |
This step assumes that we've already tagged the executable itself with the tag 0X001001, as described in “Step One: Tagging Your Application” in Chapter 11.
(Since scribble is an executable, we're able to use the tag command to tag it. If we were unable to use the tag command to assign an identification number to the application itself, we would need a slightly more complicated MATCH rule to match the application with its FTRs. For more information, see “Matching File Types With Applications: The MATCH Rule” and “Matching Non-Plain Files: The SPECIALFILE Rule”.)
Next we use the LEGEND rule to provide a legend for the file type. The legend is a brief descriptive phrase that appears when users view a directory as a list or select “Get File Info” from the Desktop menu. It should be simple, informative, and 25 characters or less. To add the legend for scribble, add this line to the FTRs:
LEGEND scribble text editor |
For more information on using the LEGEND rule, see “Adding a Descriptive Phrase: The LEGEND Rule”.
We use the CMD OPEN rule to tell the Desktop what to do when users open the scribble icon. In this example we want the Desktop to run the scribble application when the icon is opened, so we include this line in the FTRs:
CMD OPEN $LEADER $REST |
$LEADER refers to the opened application, in this case scribble. The Desktop uses $LEADER to open $REST. In this case, $REST means any other selected icons in the same window. $LEADER and $REST are Desktop environmental variables. These variables are listed and described in Appendix B, “Desktop Variables”.
For more information on using the CMD OPEN rule, see “Programming Open Behavior: The CMD OPEN Rule”.
We use the CMD DROP rule to tell the Desktop what to do when users drop another icon onto the scribble icon. In this example we want the Desktop to open the scribble application with the contents of the dropped file, so we include this line in the FTRs:
CMD DROP $TARGET $SELECTED |
$TARGET refers to the icon that the user dropped another icon on, in this case scribble; $SELECTED refers to the icon that the user dropped onto the scribble icon. $TARGET and $SELECTED are Desktop environmental variables. These variables are listed and described in Appendix B, “Desktop Variables”.
For more information on the CMD DROP rule, see “Programming Drag and Drop Behavior: The CMD DROP and DROPIF Rules”.
We use the ALTOPEN rule to tell the Desktop what to do when users open the scribble icon while holding down the <Alt> key. In this example, we want the Desktop to run the launch(1) program, so we include this line in the FTRs:
CMD ALTOPEN launch -c $LEADER $REST |
Again, $LEADER refers to the opened application, scribble and $REST refers to any other selected icons in the same window. launch runs the launch program, and -c is a command line argument to launch.
For more information on the CMD ALTOPEN rule, see “Programming Alt-Open Behavior: The CMD ALTOPEN Rule”. See the launch(1) reference page for more information about using the launch command.
We use the ICON rule to tell the Desktop where to find the picture for the scribble icon. Assume we have an icon picture in the file /usr/local/lib/install/iconlib/scribble.fti. In this example, we add these lines to the FTRs:
ICON{
if (opened) {
include("../iconlib/generic.open.fti");
} else {
include("../iconlib/generic.closed.fti");
}
include("iconlib/scribble.fti");
}
|
These lines tell the Desktop how to find pictures for the scribble icon in the opened and closed states.The pathname of the icon (.fti) files is listed relative to the location of the FTR file containing the ICON rule. Relative pathnames work as long as the icon files are located within the /usr/lib/filetype directory structure. Alternatively, you can use the absolute pathnames to the files:
/usr/local/lib/iconlib/generic.open.fti
/usr/local/lib/iconlib/generic.closed.fti
/usr/local/lib/iconlib/scribble.fti
For more information on the ICON rule, see “Getting the Icon Picture: The ICON Rule”.
Assume the name of our company is Shakespeare. Then according to the naming conventions in “Naming FTR Files” in Chapter 11, we should name our FTR file Shakespeare.scribble.ftr. We put the file in the /usr/lib/filetype/install directory.
Here is the set of FTRs that we created to define the file type called “scribbleExecutable.”
TYPE scribbleExecutable
SUPERTYPE Executable
MATCH tag == 0x00001001;
LEGEND scribble text editor
CMD OPEN $LEADER $REST
CMD ALTOPEN launch -c $LEADER $REST
CMD DROP $TARGET $SELECTED
ICON {
if (opened) {
include("../iconlib/generic.open.fti");
} else {
include("../iconlib/generic.closed.fti");
}
include("iconlib/scribble.fti"):
}
|