Eagle Mode -
emFileMan Customization
Copyright © 2008 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 documents 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). Commands of subgroups are located in
corresponding subdirectories.
Adding a new command consists of adding a new script file to one of those
directories. To make a change visible to Eagle Mode, trigger the button
Reload Files.
Remember to make backups of your modifications, because they could be removed
when reinstalling Eagle Mode.
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
$EM_DIR/etc/emFileMan/Commands/PlainText/Kate.pl 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 (somewhere in
$EM_DIR/etc/emFileMan/Commands). 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 |
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).