From 4b54df524a318680d93382f8253c8da5a7546b58 Mon Sep 17 00:00:00 2001 From: gotmor Date: Wed, 28 Mar 2007 17:11:37 +0000 Subject: 0.1.9 initial svn release git-svn-id: http://dzen.googlecode.com/svn/trunk@1 f2baff5b-bf2c-0410-a398-912abdc3d8b2 --- README | 222 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..11ecb43 --- /dev/null +++ b/README @@ -0,0 +1,222 @@ +dzen +===== +A general purpose messaging, notification and launcher programm. + + +Features +-------- + + * scritable in any language + * single line and/or multi + line windows + * menu functionality + * flexible event/action + mechanism + * hideable, collapsable + + +Requirements +------------ +In order to build dzen you need the Xlib and phtread 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 + + +Running dzen +------------ +dzen accepts a couple of options: + + -fg foreground color + -bg background color + -fn font + -a autohide, see 1) + -l lines, see 2) + -e events and actions, see 3) + -m menu, see 4) + -p persistent, never time out + -x x position + -y y position + -w width + -v version information + +Termination: +------------ +dzen2 uses to different approaches to terminate itself: + + * If EOF is received -> terminate + - unless the '-p' flag is set + + * If mouse button3 is clicked -> terminate + - this is the default behaviour, see 3) + + +Return values: +-------------- +0 - dzen received EOF +1 - some error occured, inspect the error message +user defined - set with 'exit:retval' action, see 3) + + + +1) Option "-a": Autohide +------------------------ + +Hides the title window as soon as the pointer leaves it (default). This +very much resembles autohiding panels known from most desktops. + +Note: See the 3) for events/actions to use with autohide. + + +2) 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 multiline 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 multiline window up +and down if the content exceeds the window height (default action). + + +3) Option '-e': Events and actions +---------------------------------- + +dzen allows the user to associate actions to events. + +The command line syntax is as follow: +-e 'event1=action1:option1:...option,...,action;...;event' + +Every event can take any number of actions and every action can take any number +of options. (Currently limited to 256 each) + +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 + multiline window and unhide the title window + + button3=exit + on button3 event exit dzen + + +Supported events: + 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 Ń•lave window + leaveslave Mouse leaves the slave window + sigusr1 SIGUSR1 received + sigusr2 SIGUSR2 received + +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 multiline window + uncollapse uncollapse multiline window + stick stick multiline window + unstick unstick multiline window + togglestick toggle sticky state + hide hide title window + unhide unhide title window + scrollup scroll slave window one line up + scrolldown scroll slave window one line down + + +Note: If no events/actions are specified dzen defaults to: + + -e 'entertitle=uncollapse;leaveslave=collapse; + button1=menuexec; + button2=togglestick;button3=exit:13; + button4=scrollup;button5=scrolldown' + + If you define any events/actions, there is no default behaviour, + i.e. you will need to specify _all_ events/actions you want to + use. + + +Note: The hide/unhide actions can only be used if '-a' is supplied on + the command line. This is subject to change as soon as a + autohide action will be introduced. + + + +4) Option '-m', Menu +-------------------- + +If menu mode is activated the line under the pointer will be +highlighted. +All actions beginning with "menu" work on the selected menu entry. + +Note: Menu mode only makes sense if '-l ' is specified! + + + +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 multiline message: + (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 multiline + 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 + +* Menu without any files: + {echo Menu; echo -e "xterm\nxclock\nxeyes\nxfontsel"} | dzen2 -l 4 -m -p + +* Extract PIDs from the process table + + {echo Procs; ps -a} | dzen2 -m -l 12 -p -e 'button1=menuprint;button3=exit; + button4=scrollup;button5=scrolldown' | awk '{print $1}' -- cgit v1.2.3-54-g00ecf