Events and actions

Dzen allows the user to associate actions to events with the -e option. Every event can take any number of colon separated actions. Similarly, every action can take any number of comma separated options. By default they are limited to 64 each, which is easily changable in action.h.

The command line syntax is as follows:

-e 'event1=action1:option1:...option<n>,...,action<m>;...;event<l>'

Example event string

-e 'button1=exec:xterm:firefox;entertitle=uncollapse,unhide;button3=exit'

The event string button1=exec:xterm:firefox; will cause dzen to execute xterm and Firefox on a mouse click. Note that xterm and firefox are options that have been assigned to the exec action, which in turn is assigned to the button1 event.

The event string entertitle=uncollapse,unhide; will cause dzen to uncollapse slave window and unhide the title window when the mouse pointer enters the title window.

The event string button3=exit will cause dzen to exit on a button3 event.

Supported events

• onstart - Perform actions right after startup
• onexit - Perform actions just before exiting
• onnewinput - Perform actions if there is new input for the slave window
• button1 - Mouse button1 released
• button2 - Mouse button2 released
• button3 - Mouse button3 released
• button4 - Mouse button4 released (usually scrollwheel)
• button5 - Mouse button5 released (usually scrollwheel)
• button6 - Mouse button6 released
• button7 - Mouse button7 released
• entertitle - Mouse enters the title window
• leavetitle - Mouse leaves the title window
• enterslave - Mouse enters the slave window
• leaveslave - Mouse leaves the slave window
• sigusr1 - SIGUSR1 received
• sigusr2 - SIGUSR2 received
• key_KEYNAME - Keyboard events (see below)

Keyboard events:

Every key can be bound to an action (see below). The format is: key_KEYNAME where KEYNAME is the name of the key as defined in keysymdef.h, which often resides in /usr/include/X11/keysymdef.h. The part after XK_ in keysymdef.h must be used for KEYNAME.

Supported actions

• exec:command1:..:n - execute all given options
• menuexec - executes selected menu entry
• exit:retval - exit dzen and return 'retval'
• print:str1:...:n - write all given options to STDOUT
• menuprint - write selected menu entry to STDOUT
• collapse - collapse (roll-up) slave window
• uncollapse - uncollapse (roll-down) slave window
• togglecollapse - toggle collapsed state
• stick - stick slave window
• unstick - unstick slave window
• togglestick - toggle sticky state
• hide - hide title window
• unhide - unhide title window
• togglehide - toggle hide state
• raise - raise window to view (above all others)
• lower - lower window (behind all others)
• scrollhome - show head of input
• scrollend - show tail of input
• scrollup:n - scroll slave window n lines up (default n=1)
• scrolldown:n - scroll slave window n lines down (default n=1)
• grabkeys - enable keyboard support
• ungrabkeys - disable keyboard support
• grabmouse* - enable mouse support
• ungrabmouse* - release mouse

*Only needed with specific window managers, such as fluxbox

Default actions and events

If no events string is specified dzen defaults to the following.

Title only mode

-e 'button3=exit:13'

Multiple lines and vertical menu mode

-e 'entertitle=uncollapse,grabkeys;
    enterslave=grabkeys;leaveslave=collapse,ungrabkeys;
    button1=menuexec;button2=togglestick;button3=exit:13;
    button4=scrollup;button5=scrolldown;
    key_Escape=ungrabkeys,exit'

Horizontal menu mode

-e 'enterslave=grabkeys;leaveslave=ungrabkeys;
    button4=scrollup;button5=scrolldown;
    key_Left=scrollup;key_Right=scrolldown;
    button1=menuexec;button3=exit:13
    key_Escape=ungrabkeys,exit'

If you define any events/actions there is no default behavior. You will have to specify all events and actions you want to use.