This is the user guide for non-E17 EFL programs.

3.4 - Engage

Introduction:

Engage is a dockbar based on the Enlightenment Foundation Libraries. There are two versions of Engage. There's a standalone version and a module version for E17. If you have E17 installed while you build it, the module version will be compiled in addition to the standalone version.

Engage E17 module:

The module Engage currently works as an app-launcher, taskbar and a system tray. You can open the Engage configuration menu by right clicking on Engage. One nice feature (something you probably won't find it if you don't know about it) that's only in the module version is the ability to switch desktops by moving the mousewheel on an icon; the desktop will switch to the one where the application is running. If you have more than one running instance of the application, it'll shuffle between them in a logical way (mousewheel down switches to the lower subicon etc). Future development is focused on the module version. The Engage project owner is Andrew Williams (HandyAndE).

Note that the E17 dependency is optional - if you have it installed the module will be built in addition to the standalone version. If you don't have E17 installed, it will only build the standalone version.

Engage uses EAP icon files in ~/.e/e/applications/all. You can also download EAP files from this site, just check the main menu on the left. One can also edit EAP files with e_util_eapp_edit if you have e_utils (e17/apps/e_utils) and Engrave (e17/libs/engrave) installed. Please see the icons section of this guide for more in-depth information. After you've created some EAP files and moved them to ~/.e/e/applications/all, you'll need to create a ".order" text file in ~/.e/e/applications/bar/engage. This directory doesn't exist by default and isn't created by default - you'll have it make it. The ".order" file is simply a list of EAP files in the order you want them to show up in the bar. Check the "Icons and the menu" section for examples. You can also drag EAP files to Engage from Evidence and from the e_utils_eapp_edit icon. There's also a graphical menu editor called Entangle in the e_utils package - it can manage Engage menus as well. Check the "Binary formats, icon files and the menu" section for details.

The E17 Engage module is not loaded by default when starting E17. To load the module use the command:

$ enlightenment_remote -module-load engage

If you don't like how the default Engage module theme looks like, you can make it completely transparent (as long as Engage is on the bottom of the screen) by editing data/themes/module.edc before compiling it. You'll need to add "color: 255 255 255 0;" at line 34 - without the quotes of course. It should look like this:

             rel2 {
                relative: 1.0  1.0;
                offset:   -1   -1;
                to:       "overlay";
             }
             color: 255 255 255 0;
             image {
                normal: "bg_h.png";

If you also want to remove the text from Engage, make it transparent too.
To do so, edit the color variables in module.edc starting from line 346 to look like this:

      part {
         name: "EngageIconText";
	 type: TEXT;
	 mouse_events: 0;
	 effect: SOFT_SHADOW;
	 description {
	    state: "default" 0.0;
	    rel1 {
	       relative: 0.0  0.5;
	       offset:   0   0;
	    }
	    rel2 {
	       relative: 1.0  0.5;
	       offset:   300 0;
	    }
	    color: 255 255 255 255;
	    color3: 255 255 255 255;
	    text {
	       text: "";
	       font: "Edje Vera";
	       size: 12;
	       min: 1 1;
	       align: 0.0 0.0;
	    }
	 }
	 description {
	    state: "visible" 0.0;
	    rel1 {
	       relative: 0.0  0.5;
	       offset:   0   0;
	    }
	    rel2 {
	       relative: 1.0  0.5;
	       offset:   300 0;
	    }
	    color: 255 255 255 0;
	    color3: 255 255 255 0;
	    text {
	       text: "";
	       font: "Edje Vera";
	       size: 12;
	       min: 1 1;
	       align: 0.0 0.0;
	    }
	 }
	 description {
	    state: "hidden" 0.0;
	    rel1 {
	       relative: 0.0  0.5;
	       offset:   0   0;
	    }
	    rel2 {
	       relative: 1.0  0.5;
	       offset:   300 0;
	    }
	    color: 0 0 0 0;
	    color3: 255 255 255 0;
	    text {
	       text: "";
	       font: "Edje Vera";
	       size: 12;
	       min: 1 1;
	       align: 0.0 0.0;
	    }
	 }
      }   

Standalone Engage specific information:

The standalone Engage should work in almost any windowmanager, except E17. This version of Engage is not meant to be used in E17 - you should use the module version instead if you run E17. This information only applies to the standalone version, not to the E17 module. There are two ways to configure the standalone Engage: using commandline arguments or with the included EFL configuration GUI. The standalone version works as a dockbar, system tray and can even hold special applications, for example a clock. It's also worth noting that the standalone Engage version is not actively developed, as the priority is with the E17 module version.

Usage: engage [OPTION] ...

 -h, --help                        Print this text
 -I, --ignore-iconified    [bool]  Ignore iconified windows
 -i, --ignore-running      [bool]  Ignore running apps
 -T, --tray                [bool]  Enable system tray
 -D, --appear-time         [flt]   Time taken (in seconds) for new icons to appear
 -b, --bg-main-color       [rgb]   Background main color
 -B, --bg-outline-color    [rgb]   Background outline color
 -d, --zoom-time           [flt]   Time taken (in seconds) for icons to zoom
 -Z, --zoom-factor         [flt]   Zoom factor of the icons - 1.0 == 100% == nozoom
 -z, --zoom                [bool]  Should we zoom icons?
 -S, --spacing             [int]   Space in pixels between each icon
 -s, --size                [int]   Size of icons in default state
 -A, --auto-hide           [bool]  Auto hide the engage bar
 -G, --grab-app            [bool]  Capture the icons of all running applications
 -g, --grab-min            [bool]  Capture the icons of minimised applications
 -R, --reserve             [int]   The amount of space reserved at the bottom of the screen
 -m, --mode                [int]   The display mode, 0 = ontop + shaped, 1 = below + transp.
 -e, --engine              [str]   The X11 engine to use - either software or gl
 -t, --theme               [str]   The theme name to use (minus path and extension)
 -H, --height              [int]   The overall height of the application area
 -W, --width               [int]   The overall width of the application area

Note that the standlone Engage version does NOT save the settings you set via commandline arguments! Any changes made with the EFL gui (right click on Engage and select configure) will be saved. The config file used by the standalone Engage is ~/.e/apps/engage/config.eet. If you wish to start with the default config after saving something you don't like, just delete it and restart Engage.

Here is an example commandline for the standalone Engage:

$ engage -W 1280 -T 0 -I 1 -i 1 -e software -H 80 -s 28 -Z 1.9

Note that the openGL mode, while available, is still in development and too unstable to be used. For most systems the software mode will even perform better right now.

This is how everything works at least with the default theme:

left click - launch app (for launch icons) restore app (iconified icons)
left hold - raise/unminimize window ("hold" definition is broken in the default
theme it will create another instance of the app you wish to unminimize.)
middle click - iconify apps
right click - config menu (for this to work you need to have examine installed. It's in e17/apps/examine in cvs)

FAQ regarding the standlone Engage:

Q: How can I make the standalone Engage completely transparent?

Use this -b and -B value: #00000000.
For example:

$ engage -b "#00000000" -B "#00000000"

Please don't forget the "" or it won't work. If you want to go back to the default look, the values are: #7f000000 (-b) and #7fffffff (-B).

Q: I don't want to use E17, why can't I just use it in other window managers without having to learn E17?

You can use the standalone Engage in other windowmanagers. It is fairly integrated with E17 as that's where the main focus of development is. You'll need to learn using E17 tools in order to be able to configure it, at least if you want to make icons or customize them.

Q: I'm using the standalone version - where should I move my theme files?

By default, Engage looks for themes in the following directories:

~/.e/apps/engage/themes
/usr/share/engage/themes

Q: I've heard that the standalone Engage can have a clock?

It can hold various applets like clocks etc. If you want to add a nice clock, you need to get either expedition.edj or digital.edj from http://cvs.sourceforge.net/viewcvs.py/enlightenment/misc/engage/ and copy it to ~/.e/apps/engage/sysicons. Expedition is a classic clock and digital is of course a digital one.