Debian Codegraph @

README

raw
1 ====================================
2 dzen, (c) 2007-2010 by Robert Manea
3 ====================================
4
5 Dzen is a general purpose messaging, notification and menuing program for X11.
6 It was designed to be fast, tiny and scriptable in any language.
7
8
9 Features
10 --------
11
12 * Small, fast, very tiny set of dependencies (Xlib only by default)
13 * Scriptable in any language
14 * Sophisticated formating language - including colours, icons, graphics
15 * Versatile - display all sorts of information
16 * Interactive - user defined mouse and keyboard actions
17 * Optional XFT support
18 * Optional XINERAMA support
19
20
21 Requirements
22 ------------
23 In order to build dzen you need the Xlib header files.
24
25
26 Installation
27 ------------
28 Edit config.mk to match your local setup (dzen is installed into
29 the /usr/local namespace by default).
30
31 Afterwards enter the following command to build and install dzen (if
32 necessary as root):
33
34 make clean install
35
36
37 Optionally if you want to use dzen's gadgets:
38
39 cd gadgets
40 make clean install
41
42
43 Note: By default dzen will not be compiled with Xinerama and XPM support.
44 Uncomment the respective lines in config.mk to change this.
45
46
47 Contact:
48 --------
49 Feature requests, patches or anything else related to dzen can be send
50 to: rob dot manea at gmail dot com
51
52
53 Running dzen
54 ------------
55 dzen accepts a couple of options:
56
57 -fg foreground color
58 -bg background color
59 -fn font
60 -ta alignement of title window content
61 l(eft), c(center), r(ight)
62 -tw title window width
63 -sa alignment of slave window, see "-ta"
64 -l lines, see (1)
65 -e events and actions, see (2)
66 -m menu mode, see (3)
67 -u update contents of title and
68 slave window simultaneously, see (4)
69 -p persist EOF (optional timeout in seconds)
70 -x x position
71 -y y position
72 -h line height (default: fontheight + 2 pixels)
73 -w width
74 -xs number of Xinerama screen
75 -v version information
76
77 see (5) for the in-text formating language.
78
79
80
81 X resources
82 -----------
83
84 Dzen is able to read font and color setting from X resources.
85 As an example you can add following lines to ~/.Xresources
86
87 dzen2.font: -*-fixed-*-*-*-*-*-*-*-*-*-*-*-*
88 dzen2.foreground: #22EE11
89 dzen2.background: black
90
91
92
93 Window layout
94 -------------
95
96 Dzen's window layout is as follows:
97
98 ------------------------------------------
99 | Title window, single line |
100 `------------------------------------------´
101 | |
102 | scrollable |
103 | Slave window |
104 | multiple lines |
105 | lines to display simultaneously |
106 | controlled with the |
107 | '-l' option |
108 | |
109 | |
110 `------------------------------------------´
111
112 The first line you provide to dzen always goes to the title window,
113 all other consecutive lines will be drawn to the slave window unless
114 you explicitly overide this with the (5) In-text formating language
115 command ^tw().
116
117
118 QA:
119 ---
120
121 Q1: I don't want a slave window, what to do?
122
123 A1: Do not provide the '-l' option, all lines will be displayed
124 in the title window, this is the default behaviour.
125
126
127 Q2: I used the '-l' option but no slave window appears.
128
129 A2: With the default event/action handling the slave window will
130 only be displayed if you hoover with the mouse over the title
131 window. See "(2) Events and actions" if you'd like to change
132 this.
133
134
135 Q3: If I echo some text or cat a file dzen closes itself imediatelly.
136
137 A3: There are 2 different approaches dzen uses to terminate itself,
138 see next section "Termination".
139
140
141 Q4: Ok, the title and slave thing works, can I update the
142 contents of both windows at the same time?
143
144 A4: Sure, see "(4) Simultaneous updates" or use the in-text
145 command "^tw()" to explicitly draw to the title windwow.
146 See section (5) for further details
147
148
149 Q5: Can i chnage color of my input at runtime?
150
151 A5: Yes, you can change both background and foreground colors and
152 much more See "(5) In-Text formating language"
153
154
155 Q6: Can I use dzen as a menu?
156
157 A6: Yes, both vertical and horizontal menus are supported.
158 See "(3) Menu" for further details.
159
160
161
162
163 Termination:
164 ------------
165 dzen uses two different approaches to terminate itself:
166
167 * Timed termination: if EOF is received -> terminate
168 - unless the '-p' option is set
169 · '-p' without argument persist forever
170 · '-p' with argument n persist for n seconds
171
172 * Interactive termination: if mouse button3 is clicked -> terminate
173 - this is the default behaviour, see (2)
174 - in some modes the Escape key terminates too, see (2)
175
176
177
178 Return values:
179 --------------
180 0 - dzen received EOF
181 1 - some error occured, inspect the error message
182 user defined - set with 'exit:retval' action, see (2)
183
184
185
186 (1) Option "-l": Slave window
187 --------------------------------
188
189 Enables support for displaying multiple lines. The parameter to "-l"
190 specifies the number of lines to be displayed.
191
192 These lines of input are held in the slave window which becomes active as soon
193 as the pointer enters the title (default action) window.
194
195 If the mouse leaves the slave window it will be hidden unless it is set
196 sticky by clicking with Button2 into it (default action).
197
198 Button4 and Button5 (mouse wheel) will scroll the slave window up
199 and down if the content exceeds the window height (default action).
200
201
202
203 (2) Option '-e': Events and actions
204 -----------------------------------
205
206 dzen allows the user to associate actions to events.
207
208 The command line syntax is as follows:
209 -e 'event1=action1:option1:...option<n>,...,action<m>;...;event<l>'
210
211 Every event can take any number of actions and every action can take any number
212 of options. (By default limited to 64 each, easily changable in action.h)
213
214 An example:
215 -e 'button1=exec:xterm:firefox;entertitle=uncollapse,unhide;button3=exit'
216
217 Meaning:
218
219 button1=exec:xterm:firefox;
220 on Button1 event (Button1 press on the mouse) execute xterm and
221 firefox.
222 Note: xterm and firefox are options to the exec action
223
224 entertitle=uncollapse,unhide;
225 on entertitle (mouse pointer enters the title window) uncollapse
226 slave window and unhide the title window
227
228 button3=exit
229 on button3 event exit dzen
230
231
232 Supported events:
233 -----------------
234
235 onstart Perform actions right after startup
236 onexit Perform actions just before exiting
237 onnewinput Perform actions if there is new input for the slave window
238 button1 Mouse button1 released
239 button2 Mouse button2 released
240 button3 Mouse button3 released
241 button4 Mouse button4 released (usually scrollwheel)
242 button5 Mouse button5 released (usually scrollwheel)
243 button6 Mouse button6 released
244 button7 Mouse button7 released
245 entertitle Mouse enters the title window
246 leavetitle Mouse leaves the title window
247 enterslave Mouse enters the slave window
248 leaveslave Mouse leaves the slave window
249 sigusr1 SIGUSR1 received
250 sigusr2 SIGUSR2 received
251 key_KEYNAME Keyboard events (*)
252
253
254 (*) Keyboard events:
255 --------------------
256
257 Every key can be bound to an action (see below). The format is:
258 key_KEYNAME where KEYNAME is the name of the key as defined in
259 keysymdef.h (usually: /usr/include/X11/keysymdef.h). The part
260 after 'XK_' in keysymdef.h must be used for KEYNAME.
261
262
263
264 Supported actions:
265 ------------------
266
267 exec:command1:..:n execute all given options
268 menuexec executes selected menu entry
269 exit:retval exit dzen and return 'retval'
270 print:str1:...:n write all given options to STDOUT
271 menuprint write selected menu entry to STDOUT
272 collapse collapse (roll-up) slave window
273 uncollapse uncollapse (roll-down) slave window
274 togglecollapse toggle collapsed state
275 stick stick slave window
276 unstick unstick slave window
277 togglestick toggle sticky state
278 hide hide title window
279 unhide unhide title window
280 togglehide toggle hide state
281 raise raise window to view (above all others)
282 lower lower window (behind all others)
283 scrollhome show head of input
284 scrollend show tail of input
285 scrollup:n scroll slave window n lines up (default n=1)
286 scrolldown:n scroll slave window n lines down (default n=1)
287 grabkeys enable keyboard support
288 ungrabkeys disable keyboard support
289 grabmouse enable mouse support
290 only needed with specific windowmanagers, such as fluxbox
291 ungrabmouse release mouse
292 only needed with specific windowmanagers, such as fluxbox
293
294
295 Note: If no events/actions are specified dzen defaults to:
296
297 Title only mode:
298 ----------------
299
300 -e 'button3=exit:13'
301
302
303 Multiple lines and vertical menu mode:
304 --------------------------------------
305
306 -e 'entertitle=uncollapse,grabkeys;
307 enterslave=grabkeys;leaveslave=collapse,ungrabkeys;
308 button1=menuexec;button2=togglestick;button3=exit:13;
309 button4=scrollup;button5=scrolldown;
310 key_Escape=ungrabkeys,exit'
311
312
313 Horizontal menu mode:
314 ---------------------
315
316 -e 'enterslave=grabkeys;leaveslave=ungrabkeys;
317 button4=scrollup;button5=scrolldown;
318 key_Left=scrollup;key_Right=scrolldown;
319 button1=menuexec;button3=exit:13
320 key_Escape=ungrabkeys,exit'
321
322
323 If you define any events/actions, there is no default behaviour,
324 i.e. you will have to specify _all_ events/actions you want to
325 use.
326
327
328
329 (3) Option '-m', Menu
330 ---------------------
331
332 Dzen provides two menu modes, vertical and horizontal menus. You can
333 access these modes by adding 'v'(ertical) or 'h'(horizontal) to the
334 '-m' option. If nothing is specified dzen defaults to vertical menus.
335
336 Vertical menu, both invocations are equivalent:
337 dzen2 -p -l 4 -m < file
338 dzen2 -p -l 4 -m v < file
339
340 Horizontal menu:
341 dzen2 -p -l 4 -m h < file
342
343
344 All actions beginning with "menu" work on the selected menu entry.
345
346 Note: Menu mode only makes sense if '-l <n>' is specified!
347
348 Horizontal menus have no title window, so all actions
349 affecting the title window will be silently discarded
350 in this mode.
351
352
353
354 (4) Option '-u', Simultaneous updates
355 -------------------------------------
356
357 ** DEPRECATED **
358
359 This option provides facilities to update the title and slave window at
360 the same time.
361
362 The way it works is best described by an example:
363
364 Motivation:
365
366 We want to display an updating clock in the title and some log
367 output in the slave window.
368
369 Solution:
370
371 while true; do
372 date # output goes to the title window
373 dmesg | tail -n 10 # output goes to the slave window
374 sleep 1
375 done | dzen2 -l 10 -u
376
377 For this to work correctly it is essential to provide exactly the number
378 of lines to the slave window as defined by the parameter to '-l'.
379
380
381
382 (5) In-text formating & control language:
383 -----------------------------------------
384
385 This feature allows to dynamically (at runtime) format the text dzen
386 displays and control its behaviour.
387
388 Currently the following commands are supported:
389
390
391 Note: Doubling the '^' character ('^^') will remove the special meaning from it.
392
393
394 Colors:
395 -------
396
397 ^fg(color) set foreground color
398 ^fg() without arguments, sets default fg color
399 ^bg(color) set background color
400 ^bg() without arguments, sets default bg color
401
402 Graphics:
403 ---------
404
405 ^i(path) draw icon specified by path
406 Supported formats: XBM and optionally XPM
407
408 ^r(WIDTHxHEIGHT) draw a rectangle with the dimensions
409 WIDTH and HEIGHT
410 ^ro(WIDTHxHEIGHT) rectangle outline
411
412 ^c(RADIUS) draw a circle with size RADIUS pixels
413 ^co(RADIUS) circle outline
414
415 Positioning:
416 ------------
417
418 ^p(ARGUMENT) position next input amount of PIXELs to the right
419 or left of the current position
420 a.k.a. relative positioning
421
422 ^pa(ARGUMENT) position next input at PIXEL
423 a.k.a. absolute positioning
424
425 ARGUMENT:
426
427 ^p(+-X) move X pixels to the right or left of the current position (on the X axis)
428
429 ^p(+-X;+-Y) move X pixels to the right or left and Y pixels up or down of the current
430 position (on the X and Y axis)
431
432 ^p(;+-Y) move Y pixels up or down of the current position (on the Y axis)
433
434 ^p() without parameters resets the Y position to its default
435
436 ^pa() takes the same parameters as described above but positions at
437 the absolute X and Y coordinates
438
439 Further ^p() also takes some symbolic names as argument:
440
441 _LOCK_X Lock the current X position, useful if you want to
442 align things vertically
443 _UNLOCK_X Unlock the X position
444 _LEFT Move current x-position to the left edge
445 _RIGHT Move current x-position to the right edge
446 _TOP Move current y-position to the top edge
447 _CENTER Move current x-position to center of the window
448 _BOTTOM Move current y-position to the bottom edge
449
450 Interaction:
451 ------------
452
453 ^ca(BTN, CMD) ... ^ca()
454
455 Used to define 'clickable areas' anywhere inside the
456 title window or slave window.
457 - 'BTN' denotes the mouse button (1=left, 2=right, 3=middle, etc.)
458 - 'CMD' denotes the command that should be spawned when the specific
459 area has been clicked with the defined button
460 - '...' denotes any text or formating commands dzen accepts
461 - '^ca()' without arguments denotes the end of this clickable area
462
463 Example:
464 foo ^ca(1, echo one)^fg(red)click me and i'll echo one^fg()^ca() bar
465
466 Actions as commands:
467 --------------------
468
469 ^togglecollapse()
470 ^collapse()
471 ^uncollapse()
472 ^togglestick()
473 ^stick() See section (2) 'Events and actions' for a detailed description
474 ^unstick() of each command.
475 ^togglehide()
476 ^hide()
477 ^unhide()
478 ^raise()
479 ^lower()
480 ^scrollhome()
481 ^scrollend()
482 ^exit()
483
484 Other:
485 ------
486
487 ^tw() draw to title window
488 This command has some annoyances, as only
489 the input after the command will be drawn
490 to the title window, so it is best used
491 only once and as first command per line.
492
493 ^cs() clear slave window
494 This command must be the first and only command
495 per line.
496
497 ^ib(VALUE) ignore background setting, VALUE can be either
498 1 to ignore or 0 to not ignore the bg color set
499 with ^bg(color).
500 This command is useful in combination with ^p()
501 and ^pa() in order to position the input inside
502 other already drawn input.
503
504 Example:
505 ^ib(1)^fg(red)^ro(100x15)^p(-98)^fg(blue)^r(20x10)^fg(orange)^p(3)^r(40x10)^p(4)^fg(darkgreen)^co(12)^p(2)^c(10)
506
507
508
509 These commands can appear anywhere and in any combination in dzen's
510 input.
511
512 The color can be specified either as symbolic name (e.g. red,
513 darkgreen, etc.) or as #rrggbb hex-value (e.g. #ffffaa).
514
515 Icons must be in the XBM or optionally XPM format, see the "bitmaps"
516 directory for some sample icons. With the standard "bitmap" application
517 you can easily draw your own icons.
518
519
520
521 Some examples:
522
523 Input:
524 ^fg(red)I'm red text ^fg(blue)I am blue
525
526
527 Input:
528 ^bg(#ffaaaa)The ^fg(yellow)text to ^bg(blue)^fg(orange)colorize
529
530
531 Input:
532 ^fg(grey70)Some text containing ^^ characters
533
534
535 Input for icons:
536 ^i(bitmaps/envelope.xbm) I am an envelope ^fg(yellow)and ^i(bitmaps/battery.xbm) I'm a baterry.
537
538
539 Input for rectangles:
540 6x4 rectangle ^r(6x4) ^fg(red)12x8 ^r(12x8) ^fg(yellow)and finally 100x15 ^r(100x15)
541
542
543 Input for relative positioning:
544 Some text^p(100)^fg(yellow)100 pixels to the right^p(50)^fg(red)50 more pixels to the right
545
546
547
548
549 Examples:
550 ---------
551
552 * Display message and timeout after 10 seconds:
553 (echo "This is a message"; sleep 10) | dzen2 -bg darkred -fg grey80 -fn fixed
554
555
556 * Display message and never timeout:
557 echo "This is a message"| dzen2 -p
558
559
560 * Display updating single line message:
561 for i in $(seq 1 20); do A=${A}'='; print $A; sleep 1; done | dzen2
562
563
564 * Display header and a message with multiple lines:
565 (echo Header; cal; sleep 20) | dzen2 -l 8
566
567 Displays "Header" in the title window and the output of cal in the 8
568 lines high slave window.
569
570
571 * Display updating messages:
572 (echo Header; while true; do echo test$((i++)); sleep 1; done) | dzen2 -l 12
573
574 The slave window will update contents if new input has arrived.
575
576
577 * Display log files:
578 (su -c "echo LOGFILENAME; tail -f /var/log/messages") | dzen2 -l 20 -x 100 -y 300 -w 500
579
580
581 * Monthly schedule with remind:
582 (echo Monthly Schedule; remind -c1 -m) | dzen2 -l 52 -w 410 -p -fn lime -bg '#e0e8ea' -fg black -x 635
583
584
585 * Simple menu:
586 echo "Applications" | dzen2 -l 4 -p -m < menufile
587
588
589 * Horizontal menu without any files:
590 {echo Menu; echo -e "xterm\nxclock\nxeyes\nxfontsel"} | dzen2 -l 4 -m h -p
591
592
593 * Extract PIDs from the process table:
594
595 {echo Procs; ps -a} | dzen2 -m -l 12 -p \
596 -e 'button1=menuprint;button3=exit;button4=scrollup:3;button5=scrolldown:3;entertitle=uncollapse;leaveslave=collapse' \
597 | awk '{print $1}'
598
599
600 * Dzen as xmonad (see http://xmonad.org) statusbar:
601
602 status.sh | dzen2 -ta r -fn '-*-profont-*-*-*-*-11-*-*-*-*-*-iso8859' -bg '#aecf96' -fg black \
603 -p -e 'sigusr1=raise;sigusr2=lower;onquit=exec:rm /tmp/dzen2-pid;button3=exit' & echo $! > /tmp/dzen2-pid
604
605
606
607
608 Have fun.