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