Eagle Mode -
emFileMan Customization

Copyright © 2008-2010 Oliver Hamann. Homepage: http://eaglemode.sourceforge.net/

# Contents

1 Introduction
2 Simple modifications
2.1 Setting the preferred application for a file type
2.2 Adding a new application for a file type
3 Reference
3.1 Properties
3.2 Precedence of default commands
3.3 The Perl utility functions
3.4 Arguments
3.5 Environment variables
3.6 The file manager's emMiniIpc server

# 1 Introduction

This document describes how to customize the commands of the Eagle Mode File Manager. The commands are made of small script files written in the Perl programming language. But for simple modifications described below, you do not need to know anything about Perl.

The script files are located in the directory `$EM_DIR/etc/emFileMan/Commands` (replace `$EM_DIR` by the installation directory of Eagle Mode, and replace etc by etcw if on Windows). Commands of subgroups are located in corresponding subdirectories. You could modify the commands directly there, but this may require administrator privileges. Alternatively, you could create a copy of the whole directory tree, so that it is possible to modify the files with user privileges. The required path for that copy is `$HOME/.eaglemode/emFileMan/Commands` (or on Windows: `%APPDATA%\eaglemode\emFileMan\Commands`). If that directory exists and seems okay, the script files are loaded from there, and the other is ignored.

Adding a new command simply consists of adding a new script file. To make a change visible to Eagle Mode, trigger the button Reload Files. Error messages for bad script files are printed to STDERR, and therefore it is a good idea to run Eagle Mode from a terminal while working on the commands (exception: on Windows the messages are written to `%TMP%\emCoreBasedAppLog.log`).

Remember to make backups of your modifications, because they could be removed when reinstalling Eagle Mode.

Note: This document describes the UNIX version where the scripts are written in Perl. On Windows, everything is very similar, but the scripts are in Javascript.

# 2 Simple modifications

## 2.1 Setting the preferred application for a file type

For example, if you want to make Kate the default text editor, edit the file `PlainText/Kate.pl` (below the Commands directory described above) and find the following line in it:

`# Order = 3.0`

Simply set the order number to zero:

`# Order = 0.0`

Thereby, Kate gets precedence over all the other text editors. And besides, the button moves to the beginning of the group.

## 2.2 Adding a new application for a file type

Assumed you have an application that can edit or show files of a certain file type, and you want to be able to run it out of the file manager. Then you have to create a new file in the desired group directory. Give it a name that ends with `.pl` and fill it with this template:

`#!/usr/bin/perl #[[BEGIN PROPERTIES]] # Type = Command # Order = 0.0 # Interpreter = perl # DefaultFor =` type`# Caption =` name`#[[END PROPERTIES]] use strict; use warnings; BEGIN { require "$ENV{'EM_DIR'}/res/emFileMan/scripts/cmd-util.pl"; } OpenSingleTargetFileWith('`program`');`

And then replace three things in the template:

type | Replace this by the file type the application is able to handle. It must be a file name ending including the leading dot (something like `.avi`), or a colon-separated list of such (e.g. `.avi:.mpg`), or the special keyword `file` for the case the application is a plain text editor.
name | Replace this by the application name. It is shown in the button.
program | Replace this by the executable file name of the application, like it is called in a shell, with or without path.

If you want to be able to open multiple files at once, and if supported by the application, you could replace, in the last line of the script, the word `OpenSingleTargetFileWith` by `OpenTargetFilesWith`.

# 3 Reference

## 3.1 Properties

Each command script file has a special section containing properties. And for each command group directory, there is a file which even has such a section. The properties are configuration parameters read and used by the file manager.

The format of the properties section is:

`#[[BEGIN PROPERTIES]]`
`#` name`=` value
`#` name`=` value
`#` name`=` value
...
`#[[END PROPERTIES]]`

Possible properties are:

Name | Description
`Type` | Type of the element. Possible values are: `Command` - The file is a command script. `Group` - The file describes a command group. This property must always be there.
`Order` | Order of the element. This can be any number. Within a group, the elements are sorted by these numbers. The element with the lowest number is at the beginning.
`Interpreter` | This property is only for commands. It specifies the program to be called as the interpreter for the script. For Perl scripts, say `perl`.
`Directory` | This property is only for groups, and there it is always required. It specifies the name (without path) of a subdirectory containing the elements of the group.
`DefaultFor` | This property is only for commands. It specifies the file types for which the command is a default command. The value for this property must be one of:
* | A colon-separated list of file name endings, each including the leading dot.
* | The keyword `file`. This means to match all regular files.
* | The keyword `directory`. This means to match directories.
`Caption` | A caption to be shown in the label of the button or group.
`Description` or `Descr` | A description to be shown in the label of the button or group. This property can be given multiple times for creating a multi-line description.
`Icon` | An icon to be shown in the label of the button or group. It can be specified by a file name (without path) of a TGA file in the directory `$EM_DIR/res/icons`.
`BgColor FgColor ButtonBgColor ButtonFgColor` | Background and foreground colors of the borders and buttons. The colors of a group are used as the default for the elements of the group. A color can be specified as a color name like `Powder Blue`, or as a hexadecimal RGB value like `#B0E0E6` or `#BEE`.
`Hotkey` | This property specifies a hotkey for the command. Sample values are: `Ctrl+C`, `Shift+Alt+D`, `Meta+F10`
`BorderScaling` | Scale factor for the size of the border. The default is 1.0. Zero means to make a group panel unfocusable.
`PrefChildTallness` | Preferred height/width ratio of the elements of the group. The default is 0.2.

## 3.2 Precedence of default commands

By setting the `DefaultFor` property, you can make a command the default command for a file type. But if multiple commands are the default for the same file, there is a conflict. In that case, the file manager chooses a command by the following rules (strongest-first):

- If a command A matches the file by file name ending and a command B matches just by matching every file (keyword `file`), then A has precedence over B.

- If a command A matches the file by a longer file name ending than a command B (e.g. `.tar.gz` vs. `.gz`), then A has precedence over B.

- If a command A lies in a parent group (or ancestor group) of the group of a command B, then A has precedence over B.

- If a command A has a lower `Order` number than a command B, then A has precedence over B.

The rest is tree sorting by captions, case-sensitive.

## 3.3 The Perl utility functions

The original command scripts are implemented in Perl, and the first lines are always:

`use strict;
use warnings;
BEGIN { require "$ENV{'EM_DIR'}/res/emFileMan/scripts/cmd-util.pl"; }`

This loads and executes a framework which performs some initializations and defines a lot of of utility functions. For information about those functions, please have a look into the file `$EM_DIR/res/emFileMan/scripts/cmd-util.pl`, and take all the existing command scripts as usage examples.

The rest of this document may be of interest only for understanding the implementation of the framework, or for writing a new framework in another scripting language.

## 3.4 Arguments

The file manager calls the command scripts with certain arguments: The first argument is the number of source-selected files and the second argument is the number of target-selected files. Then there are the absolute paths of the selected files, with one argument per file, and with the source-selected files first.

## 3.5 Environment variables

When the file manager calls a command script, following environment variables are set in addition to normal variables:

Name | Description
`EM_DIR` | Directory where Eagle Mode has been installed.
`LD_LIBRARY_PATH` | Contains $EM_DIR/lib, for that the libraries can be found.
`EM_FM_SERVER_NAME` | Name of the file manager's emMiniIpc server.
`EM_COMMAND_RUN_ID` | An identification for this run of a command.
`EM_X EM_Y EM_WIDTH EM_HEIGHT` | Position and size of the application window. This can be used to calculate a good position for popup dialogs.

## 3.6 The file manager's emMiniIpc server

A command script can send certain requests to the file manager. For doing that, the script can use the program `emSendMiniIpc` in the directory `$EM_DIR/bin`. The first argument must be the server name (say `$EM_FM_SERVER_NAME`), and all further arguments are making up the request, which can be one of these:

`update`
  Require the file manager to reload all the shown files and directories (mostly only if the file modification time has really changed).

`select` <command-run-id> [<file> [<file> ...]]
  Like `update`, but also require the file manager to target-select the given files, or to clear the target selection if no files are given. As usual, the source selection is set to the old target selection. The <command-run-id> must be set to the value given with the environment variable `EM_COMMAND_RUN_ID`. The sense of that id is: If the user has modified the selection since the file manager command has been started, or if another command has been started afterwards, the selection request is ignored automatically.

`selectks` <command-run-id> [<file> [<file> ...]]
  Like above, but the source selection is not changed (ks = keep source).

`selectcs` <command-run-id> [<file> [<file> ...]]
  Like above, but the source selection is cleared (cs = clear source).