path: root/README

==================================
  dzen, (c) 2007 by Robert Manea
==================================

A general purpose messaging, notification and menu program

Script archive with a collection of interesting ideas:
  http://gotmor.googlepages.com/dzenscriptarchive


Features
--------

    * scriptable in any language

	* dynamic colorizer

    * keyboard support

    * single line and/or windows holding multiple lines

    * menu functionality

    * flexible event/action mechanism

    * hideable, collapsable

    * Xinerama support


Requirements
------------
In order to build dzen you need the Xlib header files.


Installation
------------
Edit config.mk to match your local setup (dzen is installed into
the /usr/local namespace by default).

Afterwards enter the following command to build and install dzen (if
necessary as root):

    make clean install


Note:       By default dzen will not be compiled with Xinerama support.
            Uncomment the respective lines in config.mk to change this.


Contact:
--------
Feature requests, patches or anything else related to dzen can be send
to: rob dot manea at gmail dot com


Running dzen
------------
dzen accepts a couple of options:

    -fg     foreground color
    -bg     background color
    -fn     font 
    -ta     alignement of title window content 
            l(eft), c(center), r(right)
    -tw     title window width
    -sa     alignment of slave window, see "-ta"
    -l      lines, see (1)
    -e      events and actions, see (2)
    -m      menu mode, see (3)
    -u      update contents of title and 
            slave window simultaneously, see (4)
    -p      persist EOF (optional timeout in seconds)
    -x      x position
    -y      y position
    -w      width
    -xs     number of Xinerama screen
    -v      version information

    For dynamic color support see (5).


Termination:
------------
dzen uses two different approaches to terminate itself:

    * Timed termination: if EOF is received -> terminate
        - unless the '-p' option is set
            · '-p' without argument persist forever
            · '-p' with argument n  persist n seconds

    * Interactive termination: if mouse button3 is clicked -> terminate
        - this is the default behaviour, see (2)
        - in some modes the Escape key terminates too, see (2)



Return values:
--------------
0               -   dzen received EOF
1               -   some error occured, inspect the error message
user defined    -   set with 'exit:retval' action, see (2))



(1) Option "-l": Slave window
--------------------------------

Enables support for displaying multiple lines. The parameter to "-l"
specifies the number of lines to be displayed.

These lines of input are held in the slave window which becomes active as soon
as the pointer enters the title (default action) window.

If the mouse leaves the slave window it will be hidden unless it is set
sticky by clicking with Button2 into it (default action).

Button4 and Button5 (mouse wheel) will scroll the slave window up
and down if the content exceeds the window height (default action).



(2) Option '-e': Events and actions
----------------------------------

dzen allows the user to associate actions to events.

The command line syntax is as follows:
-e 'event1=action1:option1:...option<n>,...,action<m>;...;event<l>'

Every event can take any number of actions and every action can take any number
of options. (Currently limited to 64 each, easily changable in action.h)

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

    Meaning:

    button1=exec:xterm:firefox;
    on Button1 event (Button1 press on the mouse) execute xterm and
    firefox. 
    (Note: xterm and firefox are options to the exec action)

    entertitle=uncollapse,unhide;
    on entertitle (mouse pointer enters the title window) uncollapse
    slave window and unhide the title window

    button3=exit
    on button3 event exit dzen


Supported events:
    onstart             Perform actions right after startup
    onexit              Perform actions just before exiting
    button1             Mouse button1 released 
    button2             Mouse button2 released
    button3             Mouse button3 released
    button4             Mouse button4 released (usually scrollwheel)
    button5             Mouse button5 released (usually scrollwheel)
    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 (*)


    (*) 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 (usually: /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
    stick               stick slave window
    unstick             unstick slave window
    togglestick         toggle sticky state
    hide                hide title window
    unhide              unhide title window
    raise               raise window to view (above all others)
    lower               lower window (behind all others)
    scrollhome          show head of input
    scrollup:n          scroll slave window n lines up   (default n=1)
    scrolldown:n        scroll slave window n lines down (default n=1)


Note:   If no events/actions are specified dzen defaults to:

        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 behaviour,
        i.e. you will have to specify _all_ events/actions you want to
        use.



(3) Option '-m', Menu
---------------------

Dzen provides two menu modes, vertical and horizontal menus. You can
access these modes by adding 'v'(ertical) or 'h'(horizontal) to the 
'-m' option. If nothing is specified dzen defaults to vertical menus.

Vertical menu, both invocations beeing equivalent:
    dzen2 -p -l 4 -m < file
    dzen2 -p -l 4 -m v < file

Horizontal menu:
    dzen2 -p -l 4 -m h < file


All actions beginning with "menu" work on the selected menu entry.

Note:   Menu mode only makes sense if '-l <n>' is specified!

        Horizontal menus have no title window, so all actions
        affecting the title window will be silently discarded
        in this mode.



(4) Option '-u', Simultaneous updates
-------------------------------------

This option provides facilities to update the title and slave window at
the same time.

The way it works is best described by an example:

  Motivation:

  We want to display an updating clock in the title and some log
  output in the slave window.

  Solution:

  while true; do
        date                # output goes to the title window
        dmesg | tail -n 10  # output goes to the slave window
        sleep 1
  done | dzen2 -l 10 -u

For this to work correctly it is essential to provide exactly the number
of lines to the slave window as defined by the parameter to '-l'.



(5) Dynamic color support:
--------------------------

This feature allows to dynamically (at runtime) set foreground and
background colors for dzen's input (colored text) working in all 
modes (title only, slave window and menu mode).

The input must be in the following format:

  * Setting only the foreground color:

    ^#rrggbbThe text to colorize


  * Setting foreground and background color:

    ^#rrggbb^#rrggbbThe text to colorize

An example:

  echo "^#ffffff^#000000I am white text on black background" | ./dzen2 -p




Examples:
---------

* Display message and timeout after 10 seconds:
    (echo "This is a message"; sleep 10) | dzen2 -bg darkred -fg grey80 -fn fixed 


* Display message and never timeout:
    echo "This is a message"| dzen2 -p


* Display updating single line message:
    for i in $(seq 1 20); do A=${A}'='; print $A; sleep 1; done | dzen2


* Display header and a message with multiple lines:
    (echo Header; cal; sleep 20) | dzen2 -l 8

    Displays "Header" in the main alert window and
    the output of cal in the 8 lines high slave
    window.


* Display updating messages:
    (echo Header; while true; do echo test$((i++)); sleep 1; done) | dzen2 -l 12

    The slave window will update contents if new input has arrived.


* Display log files:
    (su -c "echo LOGFILENAME; tail -f /var/log/messages") | dzen2 -l 20 -x 100 -y 300 -w 500


* Monthly schedule with remind:
    (echo Monthly Schedule; remind -c1 -m) | dzen2 -l 52 -w 410 -p -fn lime -bg '#e0e8ea' -fg black -x 635


* Simple menu:
    echo "Applications" | dzen2 -l 4 -p -m < menufile


* Horizontal menu without any files:
    {echo Menu; echo -e "xterm\nxclock\nxeyes\nxfontsel"} | dzen2 -l 4 -m h -p


* Extract PIDs from the process table:

    {echo Procs; ps -a} | dzen2 -m -l 12 -p \
    -e 'button1=menuprint;button3=exit;button4=scrollup:3;button5=scrolldown:3;entertitle=uncollapse;leaveslave=collapse' \
            | awk '{print $1}'


* Dzen as xmonad (see http://xmonad.org) statusbar:

    status.sh | dzen2 -ta r -fn '-*-profont-*-*-*-*-11-*-*-*-*-*-iso8859' -bg '#aecf96' -fg black \
        -p -e 'sigusr1=raise;sigusr2=lower;onquit=exec:rm /tmp/dzen2-pid;button3=exit' & echo $! > /tmp/dzen2-pid




Have fun.