1ETERM(1) X Tools ETERM(1)
2
6 Eterm - the Enlightened terminal emulator for the X Window System
7
9 Eterm [options]
10
13 Eterm — version 0.9.6 — is a color vt102 terminal emulator intended as
14 an xterm(1) replacement. It is designed with a Freedom of Choice phi‐
15 losophy, leaving as much power, flexibility, and freedom as possible in
16 the hands of the user. It is designed to look good and work well, but
17 takes a feature-rich approach rather than one of minimalism. Eterm
18 uses Imlib for advanced graphic abilities. See below for details.
19
21 The Eterm options are listed below. In keeping with the freedom-of-
22 choice philosophy, options may be eliminated or default values chosen
23 at compile-time, so options and defaults listed may not accurately re‐
24 flect the version installed on your system.
25 Options that do not take a parameter (besides -h and --help) are bool‐
27 ean. If you use the POSIX (short) option, you are forcing the parame‐
28 ter to "true". If you use the long option, you can use any of the ac‐
29 cepted boolean values, which are "yes", "on", "1", and "true" to turn
30 the option on, or "no", "off", "0", or "false" to turn the option off.
31 The same is true for boolean values in the configuration file.
32 -t theme, --theme theme
34 Load specified theme. Consult the FAQ for more details on what
35 constitutes an Eterm theme.
36 -X conffile, --config-file conffile
38 Use an alternative user config file name. Otherwise Eterm uses
39 the default, which is user.cfg. The theme config file is always
40 theme.cfg.
41 -d displayname, --display displayname
43 Attempt to open a window on the named X display displayname. In
44 the absence of this option, the display specified by the DISPLAY
45 environment variable is used.
46 --debug level
48 Show debugging output. level is an integer between 0 and 5
49 which determines how verbose the debugging output is.
50 --install
52 Tells Eterm to install its own colormap rather than using the
53 default one.
54 -h, --help
56 Print out a message describing available options.
57 --version
59 Print Eterm version and compile-time configuration.
60 -r, --reverse-video
62 Reverse video, swaps the foreground and background colors.
63 -b color, --background-color color
65 Set color as the background color. NOTE: this will actually be
66 the foreground color if reverse video is also selected.
67 -f color, --foreground-color color
69 Set color as the foreground (text) color. NOTE: this will actu‐
70 ally be the background color if reverse video is also selected.
71 --color0 color
73 ...
75 --color15 color
77 Use color as color X.
78 --colorBD color
80 Use color as the bold color.
81 --colorUL color
83 Use color as the underline color.
84 --pointer-color color
86 Use color as the pointer color.
87 -c color, --cursor-color color
89 Use color as the cursor color.
90 --cursor-text-color color
92 Use color as the cursor text color.
93 -g geom, --geometry geom
95 Window geometry as Width x Height+X coord+Y coord, i.e
96 100x200+0+100
97 -i,--iconic
99 Start in iconified state (only if the window manager supports
100 iconification).
101 -n name, --name name
103 Sets name of current instance to name. This will affect the
104 icon title and the window title string unless they are otherwise
105 explicitly set.
106 -T title, --title title
108 Sets window's title text to title.
109 --icon-name text
111 Sets the icon title text to text.
112 -B type, --scrollbar-type type
114 Specifies the type scrollbar style should be used. type can be
115 any of motif, xterm, or next.
116 --scrollbar-width width
118 Set the width of the scrollbar, in pixels, to width. Eterm does
119 not impose any restrictions on this value, but it should be rea‐
120 sonable.
121 -D desktop, --desktop desktop
123 Starts the Eterm on the specified desktop. desktop should be an
124 integer between 0 and your highest-numbered desktop. NOTE: You
125 must have a GNOME-compliant window manager for this feature to
126 work. Please see http://www.gnome.org/devel/gnomewm/ for more
127 information on the _WIN_WORKSPACE property and how to support
128 it.
129 --line-space num
131 Size of the extra gap, in pixels, to provide between lines in
132 the terminal window.
133 --bold-font font
135 Sets the bold text font to font.
136 -F font, --font font
138 Sets the normal text font to font.
139 --default-font-index num
141 Specifies the index of the default (normal) text font.
142 --font1 font
144 ...
146 --font4 font
148 Sets the font at the specified index (1-4) to font.
149 --proportional
151 Specifies that the font in use is proportional and requests
152 standard deviation-based character cell spacing. Terminals must
153 use fixed-width character cells to maintain proper columnal
154 alignment, even when proportionally-spaced fonts are in use.
155 Some proportionally-spaced fonts vary greatly between the mini‐
156 mum and maximum character widths. This option chooses a charac‐
157 ter cell size which is up to two standard deviations above the
158 average character width but will not exceed the maximum width of
159 the largest glyph. Note that characters larger than the chosen
160 cell width will overwrite (or be overwritten by) other charac‐
161 ters and may tend to leave pixel droppings. This behavior is an
162 expected side-effect of an imperfect scenario. If you object to
163 this behavior, do not use this option.
164 --font-fx effects
166 Specifies the effects to apply to the terminal window font. The
167 value of effects is a single string containing a series of cor‐
168 ner/color pairs. These pairs define toward which corner a drop
169 shadow of each character should be made, and what color that
170 shadow will be. The corner is specified first using the follow‐
171 ing keywords: top_left or tl, top_right or tr, bottom_left or
172 bl, and bottom_right or br. Each corner specifier is then fol‐
173 lowed by a color.
174 There are also several shortcuts for doing common effects. You
176 can get a single-color outline by using the keyword outline fol‐
177 lowed by a color. A single-color drop shadow is also available
178 using the keyword shadow followed by an optional corner speci‐
179 fier (bottom_right being the default) and a color. For a 3-D
180 embossed look, use emboss dark_color light_color. The opposite
181 effect, a carved-out look, can be obtained with carved
182 dark_color light_color. (Of course, with those last two, the
183 3-D look will only work if you choose the light and dark colors
184 wisely.)
185 Finally, for no font effects at all, simply specify the keyword
187 none.
188 The default value is bottom_right black which yields a black
190 drop shadow, greatly improving the visibility of lightly-colored
191 fonts on top of light spots in a background image. Note that
192 font effects are not active in solid color mode.
193 -P pic, --background-pixmap pic
195 Use pic as the background image. pic can be in any format that
196 Imlib understands. Currently this means just about anything,
197 including JPG, PNG, GIF, TIFF, PPM, etc. The image is tiled by
198 default. To specify alternate geometry, follow the filename
199 with an @ sign and the geometry string. Image geometry is spec‐
200 ified as @wxh+x+y:ops where w and h are the horizontal/vertical
201 scaling percentages, x and y are the horizontal/vertical align‐
202 ment percentages, and ops is a colon-delimited list of opera‐
203 tions: tiled (to tile the image), propscaled (for proportional
204 scaling). Note that these operations can be combined for vari‐
205 ous effects.
206 -I pic, --icon pic
208 Sets the icon pixmap file to pic. Works similarly to the -P op‐
209 tion above.
210 --up-arrow-pixmap pic
212 As above, except the scrollbar's up-arrow is set.
213 --down-arrow-pixmap pic
215 As above, except the scrollbar's down-arrow is set.
216 --trough-pixmap pic
218 As above, except the scrollbar's background (trough) is set.
219 --anchor-pixmap pic
221 As above, except the scrollbar's anchor image is set.
222 --menu-pixmap pic
224 As above, except the menu background image is set.
225 -O, --trans
227 This gives a pseudo-transparent Eterm. The image is taken di‐
228 rectly from the root window, so any requests for changing the
229 pixmap are ignored. If you do not use Enlightenment
230 (http://www.enlightenment.org/) as your window manager (or an‐
231 other compliant window manager...I have been told that Window‐
232 Maker works also), you will need to use the Esetroot program
233 (found in the utils/ directory) to set your root background im‐
234 age.
235 -0, --itrans
237 Activate the immotile transparency optimization for transparent
238 Eterm windows. Note that this does NOT activate transparency;
239 you must still include the -O or --trans option. This option
240 should be used on transparent windows which are shaded or tinted
241 and which do not move around on the desktop much. See the Mon
242 Mar 6 21:11:13 PST 2000 ChangeLog entry for a more detailed ex‐
243 planation.
244 --viewport-mode
246 This activates a special Eterm mode which is hard to describe in
247 words. Basically, imagine the effect you get with pseudo-trans‐
248 parency, where the desktop background moves through the Eterm
249 window as you move the window, so that it always aligns with the
250 desktop image. Now, imagine the same effect, but the image used
251 isn't the desktop image but any pixmap you choose. The image is
252 scaled or tiled up to the size of the desktop, and dragging the
253 Eterm around the screen reveals different portions of the image
254 as you move, much like a small viewport window in a ship or sub‐
255 marine does. The effect is especially keen if you open several
256 Eterms in this mode with the same image.
257 --shade percentage
259 Shade the background image/transparency by a specified percent‐
260 age.
261 --tint mask
263 --tint color
265 Tints the background pixmap (either an image file or the trans‐
266 parent portion can be shaded). The mask is an integer, usually
267 specified in hexadecimal in the form 0xRRGGBB, where RR, GG,
268 and BB are hexadecimal numbers between 00 and ff (0 and 255 dec‐
269 imal) which represent the brightness of the image's red, green,
270 and blue values, respectively. A value of 00 will mask that
271 color out entirely, while a value of ff will not change that
272 color at all.
273 You may also specify an X color such as grey75 or MidnightBlue
275 or #babb7f instead of a mask.
276 --cmod brightness [ contrast [ gamma ] ]
278 Specifies a color modifier to apply to the image overall. Each
279 of the three values is a number greater than or equal to 0. The
280 numbers can be specified as decimal, octal (if preceded by "0"),
281 or hexadecimal (if preceded by "0x"). A value of 256 (0x100)
282 represents 100%, or "leave that value unchanged." 0 represents
283 0%, 512 (0x200) is 200%, etc. However, be aware that overflow
284 can occur with excessively high values. Only the brightness
285 value is required for this option. Keep in mind, though, that
286 you must specify brightness with contrast, and both of these
287 with gamma.
288 --cmod-red brightness [ contrast [ gamma ] ]
290 Same as above, except that the modifier applies to the red val‐
291 ues of the image.
292 --cmod-green brightness [ contrast [ gamma ] ]
294 Same as above, except that the modifier applies to the green
295 values of the image.
296 --cmod-blue brightness [ contrast [ gamma ] ]
298 Same as above, except that the modifier applies to the blue val‐
299 ues of the image.
300 -p newpath, --path newpath
302 Sets the pic search path. When the --background-pixmap or other
303 pixmap options are used, this path will be used to find the im‐
304 age.
305 --cache size
307 Specify the size in bytes for the Imlib2 cache.
308 -N list, --anim list
310 Specifies an animation list to be use in cycling the background
311 pixmap. The list consists of two or more words. The first word
312 defines the delay, in seconds, between updates of the back‐
313 ground. This should be set to a reasonable value to insure that
314 Eterm doesn't spend all its time rendering backgrounds. All re‐
315 maining words specify background images and have the same syntax
316 as the -P option above, including the optional geometry string.
317 -M font, --mfont font
319 Sets the normal multibyte text font to font.
320 --mfont1 font
322 ...
324 --mfont4 font
326 Sets multibyte font X to font.
327 --mencoding encoding
329 Sets multichar encoding mode (eucj or sjis or euckr)
330 --input-method method
332 Sets XIM input method
333 --preedit-type type
335 Sets XIM preedit type
336 -l, --login-shell
338 Makes the new shell a login shell.
339 -s, --scrollbar
341 Enables the scrollbar. (Default)
342 -u, --utmp-logging
344 Tries to enable proper utmp logging. For this to work, Eterm
345 probably needs to run setuid or setgid, usually setuid root.
346 -v, --visual-bell
348 Enables the "visual bell". Means the window will flash or blink
349 rather than beep.
350 -H, --home-on-output
352 Jump to bottom on output.
353 --home-on-input
355 Jump to bottom on input.
356 -q, --no-input
358 Keeps Eterm from accepting keyboard input, and keeps the window
359 manager from focusing it. Useful for log tailers and such.
360 --scrollbar-right
362 Display scrollbar on the right hand side.
363 --scrollbar-floating
365 Display the scrollbar without a trough.
366 --scrollbar-popup
368 Display the scrollbar only when the Eterm window is focused.
369 -x, --borderless
371 This option forces Eterm to have no borders.
372 -S, --sticky
374 Start Eterm as a sticky window (shows on all desktops)
375 -m, --map-alert
377 Un-iconify on beep.
378 -8, --meta8
380 Causes the Meta key to set the 8th bit in the char.
381 --double-buffer
383 Rather than drawing text directly onto the window, this option
384 causes Eterm to allocate an additional pixmap the size of the
385 terminal window into which the background *and* the text are
386 rendered. This pixmap is then set as the window background.
387 Double-buffering uses additional memory in the X server, but it
388 allows Eterm to ignore expose events so redraws are faster.
389 --no-cursor
391 Disables the text cursor.
392 --pause
394 After the child process terminates, Eterm will wait for a key‐
395 press before exiting.
396 --xterm-select
398 Duplicate's xterm's treatment of cutchars. The only real dif‐
399 ference is what happens when you double click on a single
400 cutchar between two words. If this option is on, only that sin‐
401 gle character gets selected. If it is off, that character is
402 selected along with the two words. The latter behavior is use‐
403 ful for double-clicking on the space between someone's first and
404 last names, or the @ sign in an e-mail address, etc.
405 --select-line
407 If activated, this option causes a triple click to select the
408 entire line from beginning to end. If off, a triple-click se‐
409 lects just from the current word to the end of the line.
410 --select-trailing-spaces
412 Determines whether or not trailing spaces in a selection are
413 maintained (on) or discarded (off).
414 --report-as-keysyms
416 Reports certain keystrokes as keysyms and modifiers rather than
417 escape sequences. NOTE: This option is intended for use only
418 with programs that support this special Eterm mode. Do not en‐
419 able it unless you are executing a program which uses this mode.
420 --buttonbar
422 Toggle the display of all buttonbars.
423 --resize-gravity
425 If true, Eterm will automatically detect the nearest corner, and
426 font-change resizes will cause the Eterm window to gravitate to‐
427 ward that corner.
428 --overstrike-bold
430 If true (default), Eterm will simulate a bold font by printing
431 each character twice, offsetting the second pass by one pixel.
432 This makes the characters seem thicker without the need for a
433 special font. You may wish to disable this if you use a spe‐
434 cific color for bold.
435 --bold-brightens-foreground
437 If true (default), Eterm will use the "bold" ANSI color attri‐
438 bute to brighten the foreground color by using the high-inten‐
439 sity colors (8 through 15) rather than the low-intensity colors
440 (0 through 7). Note that having a specific color selected for
441 bold will override this.
442 --blink-brightens-background
444 If true (default), Eterm will use the "blink" ANSI color attri‐
445 bute to brighten the background color by using the high-inten‐
446 sity colors (8 through 15) rather than the low-intensity colors
447 (0 through 7).
448 --colors-suppress-bold
450 If true (default), any colored text (that is, any text not ren‐
451 dered using the default foreground color) will not be given any
452 other special treatment for bolding (e.g., bold font or bold
453 overstrike).
454 --big-font-key keysym
456 Specify a keysym to increase the font size. Default is Shift
457 and the + key on the keypad. Ctrl-> or Meta-> may also work (if
458 you #define one of the hotkeys in src/feature.h).
459 --small-font-key keysym
461 Specify a keysym to decrease the font size. Default is Shift
462 and the - key on the keypad. Ctrl-< or Meta-< may also work (if
463 you #define one of the hotkeys in src/feature.h).
464 --meta-mod num
466 Specify which X modifier (1-5) to treat as the Meta key. See
467 xmodmap(1) and the output of xmodmap -pm for more details.
468 --alt-mod num
470 Same as --meta-mod, but for the Alt key.
471 --numlock-mod num
473 Same as --meta-mod, but for the NumLock key.
474 --greek-keyboard mode
476 Use Greek keyboard mapping (iso or ibm).
477 --app-keypad
479 Start Eterm in application keypad mode (as opposed to normal
480 keypad mode).
481 --app-cursor
483 Start Eterm in application cursor key mode (as opposed to normal
484 cursor key mode).
485 -L num, --save-lines num
487 Set the number of lines in the scrollback buffer to num.
488 -a size, --min-anchor-size size
490 Specifies the minimum size, in pixels high, of the scrollbar an‐
491 chor. NOTE: This causes abnormal scrolling behavior when com‐
492 bined with large scrollback buffers!
493 -w width, --border-width width
495 Set the window's border width to width. The border this con‐
496 trols is the gap between the edge of the X window and the edge
497 of the terminal window; this has nothing to do with the window
498 border's your window manager supplies.
499 --print-pipe pipe
501 The pipe for the PrintScreen function.
502 --cut-chars separators
504 The seperators for double-click selection.
505 --finished-title title
507 Specifies the string Eterm should add to its title bar if
508 --pause is specified and the child process completes.
509 --finished-text text
511 Same as above, but displays text in the terminal window.
512 --term-name TERM
514 Use TERM for the value $TERM.
515 --pipe-name pipe
517 Specifies a named pipe from which to display output. This is
518 useful for systems where syslog output goes to a named pipe,
519 like /dev/xconsole on Debian.
520 -a line, --attribute line
522 This option is used to pass config file attributes on the com‐
523 mand line. line should be a single string, so you will almost
524 certainly have to quote it. The first word of line must be the
525 context (see config file section below) which should parse the
526 rest of the line. So, for example, you could specify the fore‐
527 ground color like so: -a 'color foreground blue'. Or you could
528 add a binding: -a 'actions bind anymod button1 to script exit'.
529 Note that this option may only be used with config file at‐
530 tributes that are not context-sensitive; i.e., menus and image‐
531 classes cannot be specified using this option.
532 -C, --console
534 Grab console messages. Depending on your system, Eterm may need
535 to be setuid root to do this.
536 -e command, --exec command
538 Execute command rather than a shell. Forces Eterm mode.
539 -U URL, --url URL
541 Pick up a "screen" session at URL rather than a local (-U "")
542 one. URLs look like so (screen://user@host.dom:port/screen_op‐
543 tions), with all parts optional, defaulting to "screen://cur‐
544 rent_user@localhost:22/-RDD". Forces Escreen mode, overrides
545 --exec. Note that only screen-options (see "man screen") are al‐
546 lowed; do not pass a command (with or without arguments) here:
547 to pass a command to the screen-session, use screen [<options>]
548 <command> [<args>] instead.
549 -Z lclport:fw:fwport,delay, --fw lclport:fw:fwport,delay
551 The URL given to -U is in an intranet behind firewall fw so
552 we'll build an SSH-tunnel to that firewall (to port 22/SSH, or
553 fwport if given) from our local machine (using any available
554 port-number, or lclport if given). Then, after delay seconds (or
555 a sensible default if not given), we will try to open a screen
556 session on the host behind the firewall using ssh -p localport
557 ... localhost screen cf. ssh -L
558
561 Eterm is built on the philosophy of Freedom of Choice. Each user
562 should be able to choose the environment in which he or she wishes to
563 exist, and the tools used should support that. In accordance with that
564 philosophy, Eterm is extremely configurable. Eterm supports a concept
565 called "themes," which should be familiar to users of Enlightenment,
566 icewm, or Microsoft Windows 95/98/NT. The general concept of a theme
567 is a collection of resources that change as many aspects of a programs
568 look and feel as possible. For example, an Enlightenment theme allows
569 you to customize menus, window borders, desktops, icons, iconbars, and
570 everything else about how E looks and feels.
571 An Eterm theme consists of a primary configuration file, always called
573 "theme.cfg", residing in a directory bearing the same name as the
574 theme. This directory must be a child of one of the directories speci‐
575 fied by CONFIG_SEARCH_PATH in src/feature.h. The theme may also contain
576 additional configuration files referenced by the primary theme.cfg
577 file, as well as pixmaps, menu files, documentation, etc., which are
578 allowable as extensions to the minimum requirement of an Eterm theme.
579 By convention and default, Eterm themes should be stored under
581 ~/.Eterm/themes/<theme_name>/ or /usr/share/Eterm/themes/<theme_name>.
582 Eterm now supports the existence of a user configuration file as a sup‐
584 pliment to the theme configuration file. The default name for this
585 file is user.cfg, and it follows the exact same syntax as any other
586 configuration file. It is searched for using the same algorithm used
587 for the theme.cfg file, and any settings in the user.cfg will override
588 any previous values for those settings defined by the theme. Thus, it
589 is recommended that any user.cfg files not be complete config files,
590 but rather only contain those values which the user wishes to explic‐
591 itly override.
592 NOTE: If you have a user.cfg file in the Eterm theme directory or in
594 ~/.Eterm/, it will override any previous settings, even if you are run‐
595 ning a different theme. For example, if you run the trans theme, but
596 ~/.Eterm/themes/Eterm/user.cfg has a mode line which sets the image
597 mode to "image" rather than "trans," you will not get transparency.
598 This is why user.cfg files should be kept small and only override set‐
599 tings that you know you want to enforce. If, on the other hand, you
600 were running the trans theme and had a user.cfg file in the trans theme
601 (or in ~/.Eterm/themes/trans/), that user.cfg would be found before the
602 one in the Eterm theme.
603 Almost all command line options can be enabled/disabled in the theme's
605 configuration file (the default is
606 /usr/share/Eterm/themes/Eterm/theme.cfg). The next section contains
607 details on the format and usage of the configuration file.
608
611 Since Eterm 0.9.6 is based on the concept of themes, it is vital that
612 you have a thorough understanding of the previous section before taking
613 on this one. The previous section and this one were written by the
614 same person who wrote the Eterm code which handles options, config
615 files, and themes, so it's probably the most authoritative documenta‐
616 tion on the subject you're going to find.
617 From here on out, I will assume you've read the above text and know how
619 to change the default value for the theme. It is highly recommended
620 that you have a copy of the Eterm theme config file that comes with
621 Eterm handy while you read this documentation.
622 Okay, first the general idea. The theme.cfg file is composed of com‐
624 ments and non-comments. Comments begin with a pound sign and continue
625 to the end of the line. Lines of whitespace are also ignored. The
626 rest of the file is the config stuff, which is divided into sections
627 (called "contexts") and variables (called "attributes"). There are
628 several contexts which are listed below in sections. Each attribute
629 must be inside a certain context to be valid. For instance, while the
630 "foreground" attribute is perfectly acceptable in the color context, it
631 would be rejected if found in, say, the toggles context. This allows
632 for better organization of the config file as well as for multiple con‐
633 texts to have attributes of the same name (like the scrollbar at‐
634 tributes in the color and toggles section).
635 Each context must be enclosed in a begin...end pair that specifies the
637 type of section. The statement "begin toggles" starts the toggles con‐
638 text, and the next "end" statement would terminate it. (You'll notice
639 that some "end" statements have the context name after them. This is
640 for readability only; any text after the word "end" is ignored.)
641 The rest of this section will contain a step-by-step analysis of the
643 config file, including what can go in each section. Note that some at‐
644 tributes (and even entire contexts) may not be available depending on
645 what support was compiled into Eterm by the person who built it.
646 MAGIC NUMBER
648 The first line of the config file must contain a "magic number"
650 type line that lets Eterm verify that it's reading an Eterm con‐
651 fig file and not something else (like an Enlightenment 0.13 and
652 earlier config file). The line should look like this:
653 <Eterm-VERSION>
655 where VERSION is the Eterm version for which the config file is
657 intended. For example, config files written for Eterm 0.9
658 should have "<Eterm-0.9>" as their first line, followed immedi‐
659 ately by a newline.
660 COLOR CONTEXT
662 This context contains color specifications. With the exception
664 of the terminal colors 0-15, all colors should be either a valid
665 color name or an RGB string as outlined in the X11(7) man page.
666 foreground color
668 Use color for the foreground (text) color.
669 background color
671 Use color for the background color.
672 cursor color
674 Use color for the cursor color.
675 cursor_text color
677 Use color for the cursor text color.
678 pointer color
680 Use color for the mouse pointer color.
681 video { normal | reverse }
683 normal will not reverse the foreground and background colors.
684 reverse (meaning reverse video) will.
685 color num color
687 Set terminal color num (0-15) to the color name, string, or
688 set of 3 decimal/hex/octal RGB values specified by color.
689 color { bd | ul } color
691 Set terminal bold (bd) or underline (ul) color to the color
692 name, string, or set of 3 decimal/hex/octal RGB values speci‐
693 fied by color.
694 ATTRIBUTES CONTEXT
697 This context contains X11 attributes. Most of these are depen‐
699 dent upon the cooperation of the window manager.
700 geometry geom
702 Use the geometry string geom to specify the startup geometry.
703 geom should be in the format WxH+X+Y where W is the width, H
704 is the height, and +X and +Y are the X and Y offsets. If the
705 signs on X and Y are positive, the coordinates are offsets
706 (in pixels) from the left and top, respectively, of the
707 screen. If the signs are negative, the offsets are relative
708 to the right and bottom of the screen, respectively.
709 title title
711 Use title as the text in the title bar of the Eterm window.
712 name name
714 Use name as the resource name of the Eterm window.
715 iconname name
717 Use name as the icon name of the Eterm window icon.
718 desktop num
720 Start Eterm on desktop num. NOTE: This requires a GNOME-com‐
721 pliant Window Manager. Please see http://www.gnome.org/de‐
722 vel/gnomewm/ for more information on the _WIN_WORKSPACE prop‐
723 erty and how to support it.
724 scrollbar_type type
726 Use a scrollbar with the type style. type can be any of mo‐
727 tif, xterm, or next.
728 scrollbar_width num
730 Use a scrollbar that is num pixels wide.
731 font num font
733 font bold font
734 Set the numth font, or the bold font, to font.
735 font default num
737 Specifies that the numth font should be considered the "de‐
738 fault" font.
739 font proportional boolean
741 Specifies that the font in use is proportional and requests
742 standard deviation-based character cell spacing. Terminals
743 must use fixed-width character cells to maintain proper
744 columnal alignment, even when proportionally-spaced fonts are
745 in use. Some proportionally-spaced fonts vary greatly be‐
746 tween the minimum and maximum character widths. This option
747 chooses a character cell size which is up to two standard de‐
748 viations above the average character width but will not ex‐
749 ceed the maximum width of the largest glyph. Note that char‐
750 acters larger than the chosen cell width will overwrite (or
751 be overwritten by) other characters and may tend to leave
752 pixel droppings. This behavior is an expected side-effect of
753 an imperfect scenario. If you object to this behavior, do
754 not use this option.
755 font fx effects
757 Specifies the effects to apply to the terminal window font.
758 The value of effects is a single string containing a series
759 of corner/color pairs. These pairs define toward which cor‐
760 ner a drop shadow of each character should be made, and what
761 color that shadow will be. The corner is specified first us‐
762 ing the following keywords: top_left or tl, top_right or tr,
763 bottom_left or bl, and bottom_right or br. Each corner spec‐
764 ifier is then followed by a color.
765 There are also several shortcuts for doing common effects.
767 You can get a single-color outline by using the keyword out‐
768 line followed by a color. A single-color drop shadow is also
769 available using the keyword shadow followed by an optional
770 corner specifier (bottom_right being the default) and a
771 color. For a 3-D embossed look, use emboss dark_color
772 light_color. The opposite effect, a carved-out look, can be
773 obtained with carved dark_color light_color. (Of course,
774 with those last two, the 3-D look will only work if you
775 choose the light and dark colors wisely.)
776 Finally, for no font effects at all, simply specify the key‐
778 word none.
779 The default value is bottom_right black which yields a black
781 drop shadow, greatly improving the visibility of lightly-col‐
782 ored fonts on top of light spots in a background image. Note
783 that font effects are not active in solid color mode.
784 IMAGECLASSES CONTEXT
787 This context contains global image attributes. It also provides
789 the parent context for defining images via the "image" context.
790 icon filename
792 Use filename as the icon image for the Eterm window. file‐
793 name can be an absolute path, relative to the current theme,
794 or relative to one of the directories in the path attribute
795 listed below.
796 cache num
798 Sets the Imlib2 cache size to num bytes. The default is 0.
799 path directory_list
801 Specifies a colon-delimited list of directories relative to
802 which Eterm should search for image and menu files. The syn‐
803 tax for directory_list is precisely the same as that of the
804 $PATH environment variable in UNIX shells.
805 anim interval images ...
807 Specifies an animation list to be use in cycling the back‐
808 ground pixmap. The interval defines the delay, in seconds,
809 between updates of the background. This should be set to a
810 reasonable value to insure that Eterm doesn't spend all its
811 time rendering backgrounds. All the images specify back‐
812 ground images and have the same syntax as the -P option
813 above, including the optional geometry string.
814 IMAGE CONTEXT
817 This context defines all the attributes of a particular image.
819 There can be (and usually are) several image contexts per theme,
820 one for each class of image.
821 type class
823 Specifies the type, or class, of the image that is going to
824 be defined in that context. This MUST be the first attribute
825 defined in the image context. Valid classes are: background,
826 trough, anchor, up_arrow, down_arrow, left_arrow, right_ar‐
827 row, menu, menuitem, submenu, button, and buttonbar. Note
828 that the left and right arrows, while valid, don't do any‐
829 thing just yet. All the subsequent attributes up to the next
830 type definition will be applied to that image class.
831 mode initial_mode [ allow allowed_modes ]
833 Specifies the initial mode for this image class as well as
834 the modes which the image class is allowed to use. ini‐
835 tial_mode is the mode that the image will have on startup
836 (unless overridden by command-line options. allowed_modes is
837 a list of one or more modes. The image will be prevented
838 from switching to any mode not listed in the allow section.
839 If the allow section is omitted entirely, the image will
840 never be permitted to change from the initial_mode. If no
841 mode line is specified for an image class, the default is
842 equivalent to mode solid allow solid. Valid mode names are
843 image (to use an image), trans (for transparency), viewport
844 (for viewport mode), auto (for auto mode, which requires En‐
845 lightenment 0.16 or better), and solid (which is a solid
846 color only).
847 state { normal | selected | clicked | disabled }
849 This sets the state of the image you are about to define. Up
850 until the next state attribute that is encountered (or until
851 you change types), all attributes will apply to that particu‐
852 lar state of the image. You should at minimum define the
853 normal state of the image. It will be used as the default if
854 the attributes for the other states are not specified. How‐
855 ever, each image state has self-contained options. There‐
856 fore, if you define multiple states for an image class, you
857 must define ALL attributes needed by that state. The sample
858 themes supplied with Eterm demonstrate how to define 1-, 2-,
859 3-, and 4-state images.
860 The above attributes affect the image class as a whole. All re‐
862 maining attributes in this context affect only the current state
863 of the image class.
864 color fg bg
866 Sets the foreground and background colors for this image‐
867 class. The foreground color is used for text, and the back‐
868 ground color is used for the object itself. If an invalid
869 color is specified, the default value for fg is white, and
870 the default for bg is black.
871 file filename
873 Sets the filename from which to load the image file. This is
874 used for the image mode. If you allow the image mode for
875 your image, don't forget to supply an image file! Note that
876 you can also supply an image geometry string here by adding
877 an @ symbol and the geometry string to the end of the file‐
878 name. See below for the syntax of the geometry string.
879 filename must be an absolute path or a path relative to one
880 of the directories in the path attribute. Note that the im‐
881 age is verified and loaded when this attribute is encountered
882 during parsing.
883 geom image_geometry
885 Specifies the geometry and geometry-related operations which
886 are to be applied to the image. This attribute only applies
887 to image classes using the image mode. Image geometry is
888 specified as wxh+x+y:ops where w and h are the horizon‐
889 tal/vertical scaling percentages, x and y are the horizon‐
890 tal/vertical alignment percentages, and ops is a colon-delim‐
891 ited list of operations: tiled (to tile the image), prop‐
892 scaled (for proportional scaling). Note that these opera‐
893 tions can be combined for various effects.
894 cmod { image | red | green | blue } brightness [ contrast [ gamma
896 ] ]
897 colormod { image | red | green | blue } brightness [ contrast [
898 gamma ] ]
899 Specifies a color modifier to apply to the image. The second
900 keyword determines whether the modifier will be applied to
901 the image overall, the red values, the green values, or the
902 blue values. Each of the three parameters is a number
903 greater than or equal to 0. The numbers can be specified as
904 decimal, octal (if preceded by "0"), or hexadecimal (if pre‐
905 ceded by "0x"). A value of 256 (0x100) represents 100%, or
906 "leave that value unchanged." 0 represents 0%, 512 (0x200)
907 is 200%, etc. However, be aware that overflow can occur with
908 excessively high values. Only the brightness value is re‐
909 quired for this option. Keep in mind, though, that you must
910 specify brightness with contrast, and both of these with
911 gamma.
912 border left right top bottom
914 Specifies that the image has borders which should not be
915 scaled with the rest of the image. This is primarily used
916 for images that have a beveled look, so that the bevel will
917 not end up getting scaled and lose the bevel effect. All
918 four parameter values are in pixels, just like the equivalent
919 options for E themes and Gtk+ pixmap themes.
920 bevel { up | down } left right top bottom
922 Adds a bevel to an image class. This can be done to any im‐
923 age class using the image or trans modes. The parameters are
924 pixel values which represent the width of each edge of the
925 bevel. This is especially useful if you want to use tiled
926 images or transparency for the arrow or anchor scrollbar wid‐
927 gets, or for menus.
928 padding left right top bottom
930 This is used only for the submenu image class. It defines
931 the amount of pixels on each side to reserve so that the text
932 will not overwrite part of the image. Works just like the
933 same option in Enlightenment themes.
934 MENU CONTEXT
938 This context is used to create a menu. There is one instance of
940 this context per menu, and the menus should be defined in sub‐
941 menu-menu order; i.e., any menu that refers to another menu (as
942 its submenu) should be defined after the submenu is defined.
943 Within the menu context, there should be a menuitem subcontext
944 for each menu item (with the exception of the shorthand for sep‐
945 arators).
946 title menu_title
948 This specifies the title for the menu to be defined. This
949 MUST be the first attribute given after the "begin menu".
950 The title must be unique amongst all the menus. It may con‐
951 tain spaces, but don't forget to enclose it in single or dou‐
952 ble quotes if it does. Any future references to the menu
953 will use the title.
954 font font_name
956 Tells Eterm to use font_name as the font for this menu. If
957 not given, the default terminal font is used.
958 sep or -
960 These symbols can be used as shorthand to insert a separator
961 into the menu.
962 MENUITEM CONTEXT
966 This is a subcontext of the menu context which creates a single
968 item for a menu. There can be (and usually are) several menu‐
969 item contexts per menu.
970 text label
972 This is the text that is displayed for this menuitem. It is
973 left-justified in the menu window. It can have spaces, but
974 enclose label in quotes if it does.
975 rtext label
977 This is text which is right-justified next to the menuitem
978 text. This is generally used to show what keystrokes corre‐
979 spond to a particular menu item, like "C-x C-c" for the
980 "Exit" menuitem in an Emacs menu.
981 action { string | echo | submenu | script } param
983 action separator
984 Specifies the action to occur when the menuitem is chosen.
985 If you specify separator, nothing else is needed. The other
986 action types require a parameter, param. string specifies a
987 string to be sent to Eterm for handling (escape codes, for
988 example). echo specifies a string to be sent to the client
989 program (for sending commands to a shell, or keystrokes to an
990 application like emacs or mutt). If you use either of these
991 action types, param will be parsed for escape codes (\a, C-,
992 and the like) before being sent. submenu specifies a submenu
993 which should be displayed when this item is selected, and
994 param is the title of the submenu to show. The submenu must
995 have already been defined. The script action type executes
996 the Eterm-builtin script contained in param. See the section
997 below for more details on the builtin Eterm functions allowed
998 for this action type.
999 ACTION CONTEXT
1003 Actions are key or mouse button bindings which activate certain
1005 behaviors. Any action that can be triggered through an escape
1006 code can be bound to a key or mouse button, with or without mod‐
1007 ifiers. You can also bind menus to keystrokes or mouse buttons.
1008 bind [ modifiers ] { keysym | button } to { string | echo | menu |
1010 script } param
1011 Binds a keysym or a mouse button to an action. The action
1012 syntax follows the keyword to and is identical to the syntax
1013 used for menus (see above). There can be any number of modi‐
1014 fiers (so long as the combination is reasonable) but only one
1015 keysym or button. Valid modifiers are ctrl, shift, lock,
1016 mod1 through mod5, alt, meta, and anymod (which allows any
1017 modifier). If none are given, the keypress must not have
1018 modifier keys in use or the action will not be triggered.
1019 Use anymod to allow any arbitrary modifier key to be used.
1020 The keysym can be given in text (case-sensitive) or as a hex
1021 number. buttons should be specified as button1 through but‐
1022 ton5. Also note that alt and meta will be equivalent to one
1023 or more of mod1 through mod5, as well as perhaps each other,
1024 based on your modifier settings. You can view these settings
1025 using xmodmap -pm. See also the alt_mod and meta_mod options
1026 below.
1027 BUTTON_BAR CONTEXT
1031 The buttonbar is an addition to Eterm 0.9.1 which allows users
1033 to have a fully-customizeable buttonbar at the top or bottom of
1034 each terminal window. Buttons on the buttonbar can be used just
1035 like menuitems; they can popup menus (like a menubar), or they
1036 can activate any other action a menuitem can.
1037 font font
1039 Specifies the font in which button labels will be displayed.
1040 dock { top | bottom | no }
1042 Specify whether or not to dock the buttonbar, and if so,
1043 whether to dock it at the top or the bottom of the Eterm win‐
1044 dow. Note that only top and bottom are currently enabled.
1045 visible boolean
1047 Toggle whether or not this particular buttonbar will be visi‐
1048 ble on startup.
1049 button [ text ] [ icon filename ] action { string | echo | menu |
1051 script } param
1052 Binds an action to a button. The usage of param and the ac‐
1053 tion types work the same here as they do for menuitems. Also
1054 note that you may specify some text or an icon or both, but
1055 you cannot omit both.
1056 MULTICHAR CONTEXT
1059 Behavior for multi-byte fonts and encodings are defined here.
1061 This context does not exist by default.
1062 encoding { eucj | sjis | euckr | big5 | gb | iso-10646 }
1064 Specifies the encoding method. Patches to support other en‐
1065 coding methods are encouraged.
1066 font num font
1068 Set the numth multichar font to font.
1069 XIM CONTEXT
1073 This context controls locale-based behavior.
1075 input_method input_method
1077 Specify your input method program of choice.
1078 preedit_type { OverTheSpot | OffTheSpot | Root }
1080 Specify your preedit type of choice.
1081 ESCREEN CONTEXT
1085 This context allows for customizations specific to Escreen mode.
1087 See the Escreen section below for more details.
1088 url protocol://user@host:port/params
1090 Connect to (or create) a particular screen session via a URL-
1091 type construct. Standard URL rules apply. The protocol
1092 should be either screen (the default) or twin. If user,
1093 host, and/or port are specified, an ssh connection is made to
1094 the remote server using the given login information. The de‐
1095 fault is to create/attach to a local session.
1096 Any params that are given are passed directly to the underly‐
1098 ing protocol and are separated from each other by a plus sign
1099 (+).
1100 firewall localport:firewall:remoteport
1102 Bounce the connection through a firewall via ssh.
1103 delay secs
1105 Specify the amount of time to wait before sending the
1106 screen/twin initialization sequence. This is required to in‐
1107 sure that the remote session has been established prior to
1108 sending the init sequence.
1109 bbar_font font
1111 Font to use for the Escreen buttonbar. The default is
1112 -*-helvetica-medium-r-normal--10-*-*-*-p-*-iso8859-1.
1113 bbar_dock { top | bottom | no }
1115 Dock the Escreen buttonbar as specified. Note that only top
1116 and bottom are currently enabled.
1117 TOGGLES CONTEXT
1121 This context contains boolean variables which can be toggled on
1123 or off. Valid values for the attributes in this section are
1124 "yes", "on", "1", and "true" to turn the option on, or "no",
1125 "off", "0", or "false" to turn the option off. These values are
1126 denoted by boolean. They all default to false unless otherwise
1127 noted.
1128 map_alert boolean
1130 If true, Eterm will un-iconify itself when it receives a beep
1131 (ASCII 0x07).
1132 visual_bell boolean
1134 If true, Eterm will flash rather than sending a beep.
1135 login_shell boolean
1137 If true, Eterm will prepend '-' to the shell name when call‐
1138 ing it. Depending on your shell, this may modify its startup
1139 behavior.
1140 scrollbar boolean
1142 This turns on and off the display of the scrollbar. Default
1143 is on.
1144 utmp_logging boolean
1146 If true, Eterm will attempt to make an entry in the utmp file
1147 to record the login information. Eterm may need to run priv‐
1148 ileged to do this.
1149 meta8 boolean
1151 Toggles the interpretation of the Meta key setting the 8th
1152 bit in a character.
1153 iconic boolean
1155 If true, Eterm will launch as an icon.
1156 home_on_output boolean
1158 Zoom to the bottom of the scrollback buffer on output.
1159 home_on_input boolean
1161 Zoom to the bottom of the scrollback buffer on input.
1162 no_input boolean
1164 If true, Eterm will not accept any keyboard input and will
1165 ask the window manager to not allow it to be focused.
1166 scrollbar_floating boolean
1168 If true, the scrollbar will have no trough.
1169 scrollbar_right boolean
1171 If true, Eterm will put the scrollbar on the right of the
1172 window (default is left).
1173 scrollbar_popup boolean
1175 If true, Eterm will hide the scrollbar when the Eterm window
1176 loses focus and restore it when focus is regained. Default
1177 is to not change the scrollbar state based on focus.
1178 borderless boolean
1180 If true, Eterm will run with no window borders. This also
1181 means that the window can not be moved or resized. You will
1182 want to specify a geometry with this attribute.
1183 double_buffer boolean
1185 Rather than drawing text directly onto the window, this
1186 causes Eterm to allocate an additional pixmap the size of the
1187 terminal window into which the background *and* the text are
1188 rendered. This pixmap is then set as the window background.
1189 Double-buffering uses additional memory in the X server, but
1190 it allows Eterm to ignore expose events so redraws are
1191 faster.
1192 no_cursor boolean
1194 If true, Eterm will not display a text cursor.
1195 pause boolean
1197 After the child process terminates, Eterm will wait for a
1198 keypress before exiting.
1199 xterm_select boolean
1201 Duplicate's xterm's treatment of cutchars. The only real
1202 difference is what happens when you double click on a single
1203 cutchar between two words. If this option is on, only that
1204 single character gets selected. If it is off, that character
1205 is selected along with the two words. The latter behavior is
1206 useful for double-clicking on the space between someone's
1207 first and last names, or the @ sign in an e-mail address,
1208 etc.
1209 select_line boolean
1211 If true, this attribute causes a triple click to select the
1212 entire line from beginning to end. If false (default), a
1213 triple-click selects from the current word to the end of the
1214 line.
1215 select_trailing_spaces boolean
1217 If true, this attribute causes spaces at the end of a line to
1218 be included as part of the selection text when selecting.
1219 The default is to strip these trailing spaces.
1220 report_as_keysyms boolean
1222 Reports certain keystrokes as keysyms and modifiers rather
1223 than escape sequences. NOTE: This option is intended for use
1224 only with programs that support this special Eterm mode. Do
1225 not enable it unless you are executing a program which uses
1226 this mode.
1227 itrans boolean
1229 immotile_trans boolean
1230 Toggles the immotile transparency optimization for transpar‐
1231 ent Eterm windows. Note that this does NOT activate trans‐
1232 parency; you must still activate "trans" mode for the back‐
1233 ground image. This option should be used on transparent win‐
1234 dows which are shaded or tinted and which do not move around
1235 on the desktop much. See the Mon Mar 6 21:11:13 PST 2000
1236 ChangeLog entry for a more detailed explanation.
1237 buttonbar boolean
1239 Toggle the display of all buttonbars.
1240 resize_gravity boolean
1242 If true, Eterm will automatically detect the nearest corner,
1243 and font-change resizes will cause the Eterm window to gravi‐
1244 tate toward that corner.
1245 overstrike_bold boolean
1247 If true (default), Eterm will simulate a bold font by print‐
1248 ing each character twice, offsetting the second pass by one
1249 pixel. This makes the characters seem thicker without the
1250 need for a special font. You may wish to disable this if you
1251 use a specific color for bold.
1252 bold_brightens_foreground boolean
1254 If true (default), Eterm will use the "bold" ANSI color at‐
1255 tribute to brighten the foreground color by using the high-
1256 intensity colors (8 through 15) rather than the low-intensity
1257 colors (0 through 7). Note that having a specific color se‐
1258 lected for bold will override this.
1259 blink_brightens_background boolean
1261 If true (default), Eterm will use the "blink" ANSI color at‐
1262 tribute to brighten the background color by using the high-
1263 intensity colors (8 through 15) rather than the low-intensity
1264 colors (0 through 7).
1265 colors_suppress_bold boolean
1267 If true (default), any colored text (that is, any text not
1268 rendered using the default foreground color) will not be
1269 given any other special treatment for bolding (e.g., bold
1270 font or bold overstrike).
1271 sticky boolean
1273 If true, Eterm will make its window sticky (shows on all
1274 desktops).
1275 KEYBOARD CONTEXT
1278 This context contains keyboard-related configuration options.
1280 smallfont_key keysym
1282 Specify a keysym to decrease the font size. Default is Shift
1283 and the - key on the keypad. Ctrl-< or Meta-< may also work
1284 (if you #define one of the hotkeys in src/feature.h).
1285 bigfont_key keysym
1287 Specify a keysym to increase the font size. Default is Shift
1288 and the + key on the keypad. Ctrl-> or Meta-> may also work
1289 (if you #define one of the hotkeys in src/feature.h).
1290 keysym keysym string
1292 Define keysym keysym to send string instead of its default.
1293 keysym must be between 0xff00 and 0xffff or Eterm will com‐
1294 plain.
1295 meta_mod num
1297 Specify which X modifier (1-5) to treat as the Meta key. See
1298 xmodmap(1) and the output of xmodmap -pm for more details.
1299 alt_mod num
1301 Same as meta_mod, but for the Alt key.
1302 numlock_mod num
1304 Same as meta_mod, but for the NumLock key.
1305 greek boolean { iso | ibm }
1307 Turn on/off greek keyboard support, and set which greek mode
1308 to use.
1309 app_keypad boolean
1311 Turn on/off application keypad mode on startup.
1312 app_cursor boolean
1314 Turn on/off application cursor key mode on startup.
1315 MISC CONTEXT
1318 This context contains miscellaneous attributes that really
1320 didn't belong anywhere else.
1321 print_pipe command
1323 Set the command to which to pipe print requests (printscreen)
1324 to command.
1325 save_lines num
1327 Set the number of lines in the scrollback buffer to num.
1328 cut_chars string
1330 Define the characters used as word delimiters to the charac‐
1331 ters contained in string.
1332 min_anchor_size num
1334 Sets the minimum size, in pixels, of the scrollbar anchor
1335 (the part your mouse grabs onto and moves around) to num.
1336 border_width num
1338 Sets the width of the border between the text window and the
1339 X window to num.
1340 line_space num
1342 Put num pixels' worth of space between each row of the termi‐
1343 nal window.
1344 finished_title title
1346 Specifies that title should be displayed in the title bar of
1347 a paused Eterm when the child process has completed.
1348 finished_text text
1350 Specifies that text should be displayed in the terminal win‐
1351 dow of a paused Eterm when the child process has completed.
1352 term_name name
1354 Use name as the $TERM environment variable, which controls
1355 which termcap/terminfo entry gets used. The default is
1356 Eterm.
1357 exec command
1359 Rather than executing a shell, this will cause Eterm to spawn
1360 command as its child process. You can only have one of
1361 these!
1362 BUILT-IN FUNCTIONS
1365 Eterm has a set of built-in functions which are available in
1367 config files. Each one accepts zero or more parameters and out‐
1368 puts a series of zero or more words. "Words" are defined in
1369 shell terms; i.e., words are separated by whitespace, and single
1370 or double quotes can be used to encapsulate words which contain
1371 whitespace themselves. You also employ backquotes to execute a
1372 command whose output can become part of the config file itself
1373 or can be passed to a built-in function as its parameter list.
1374 Built-in functions and backquotes may be used anywhere their
1375 output would be valid. Built-in functions are prefixed with the
1376 % character.
1377 %appname()
1379 Returns the application name, a hyphen, and the version num‐
1380 ber. Currently this is the string Eterm-0.9.6.
1381 %exec(command)
1383 Executes command and returns the result. Basically it's ex‐
1384 actly like using backquotes.
1385 %get(variable)
1387 Retrieve the value of a config file variable. Refer to the
1388 %put() function below.
1389 %put(variable value)
1391 Create a config variable named variable and assign it the
1392 value of value. The value can then subsequently be retrieved
1393 using %get(variable)
1394 %random(params)
1396 This function randomly chooses one of the words which compose
1397 params and returns that. The default themes that come with
1398 Eterm use this function to choose random backgrounds, but
1399 backgrounds aren't the only things that can be randomized
1400 with this function. You can randomize anything...colors,
1401 toggles, fonts, tinting, etc.
1402 %version()
1404 Returns the version number. Currently this is the string
1405 0.9.6.
1406 PREPROCESSING
1409 Eterm supports the %include file directive to allow for separa‐
1411 tion of the configuration information into multiple files.
1412 Eterm will load and parse file just like any other config file,
1413 but will treat its contents as if they replaced the directive
1414 itself.
1415 You may also request that the config file be run through an ex‐
1417 ternal preprocessor (such as m4 or cpp) before Eterm reads it.
1418 This is done via the %preproc command directive. You may spec‐
1419 ify anything you like for command so long as it accepts input on
1420 STDIN and sends output to STDOUT. See the menus.cfg file in the
1421 default chooser theme for an example.
1422 SCRIPT FUNCTIONS
1425 One of the action types which can be bound to keypresses, mouse
1427 buttons, menuitems, or buttonbar buttons is a script. The
1428 script must be a single word (i.e., containing no spaces or en‐
1429 closed in quotes) and consists of one or more calls to the
1430 script functions below. Each call is separated from the next by
1431 a semicolon (;). Function parameters are enclosed in parenthe‐
1432 ses; the parentheses are optional if no parameters are to be
1433 passed. Commas and/or whitespace separate parameters from each
1434 other.
1435 copy(buffer)
1437 Copies the current selection to the specified clipboard or
1438 cut buffer. buffer is either a number 0-7, in which case the
1439 selection is copied to the cut buffer specified, or one of
1440 the words clipboard, primary, or secondary (or any initial
1441 substring thereof), in which case the selection is copied to
1442 the specified clipboard. You may omit buffer, in which case
1443 the default buffer is primary (XA_PRIMARY in Xlib-speak).
1444 echo(string)
1446 Send the specified string to the subcommand. Exactly equiva‐
1447 lent to the echo action.
1448 es_display(cmd, params)
1450 Aliases: es_disp
1451 This is a master function which permits manipulation of Es‐
1452 creen displays through the use of a series of subcommands.
1453 The specified cmd determines what, if any, params are permit‐
1454 ted. Available subcommands are:
1455 goto - Switch to the specified display (0-9)
1456 prev - Switch to the previous display
1457 next - Switch to the next display
1458 toggle - Toggle display
1459 new - Create a new display. A name for the new display
1460 may be passed as a parameter, or ask to prompt the user
1461 for the name.
1462 rename - Change the name of the current display. A name
1463 for the new display may be passed as a parameter, or ask
1464 to prompt the user for the name.
1465 kill - Terminate the current (or specified) display.
1466 watch - Toggle monitoring of the current/specified dis‐
1467 play for activity.
1468 scrollback - View the scrollback for the current/speci‐
1469 fied display.
1470 es_region(cmd, params)
1472 Aliases: es_reg es_win es_window
1473 This is a master function which permits manipulation of Es‐
1474 creen display regions through the use of a series of subcom‐
1475 mands. The specified cmd determines what, if any, params are
1476 permitted. Available subcommands are:
1477 goto - Switch to the specified region (0-9)
1478 prev - Switch to the previous region
1479 next - Switch to the next region
1480 toggle - Toggle region
1481 new - Create a new region. A name for the new region
1482 may be passed as a parameter, or ask to prompt the user
1483 for the name.
1484 rename - Change the name of the current region. A name
1485 for the new region may be passed as a parameter, or ask
1486 to prompt the user for the name.
1487 kill - Terminate the current (or specified) region.
1488 only - Maximize the current/specified region to the full
1489 display.
1490 watch - Toggle monitoring of the current/specified re‐
1491 gion for activity.
1492 scrollback - View the scrollback for the current/speci‐
1493 fied region.
1494 es_statement(statement)
1496 Execute an Escreen (screen/twin) command directly.
1497 es_reset()
1499 Aliases: es_rst
1500 Reset the Escreen session
1501 exec_dialog(command)
1503 The same as exec/spawn, but this function presents the user
1504 with a dialog box in which she can edit/confirm the command
1505 to be run and specify additional parameters if needed.
1506 exit(message)
1508 exit(code)
1509 Aliases: die quit
1510 Exit Eterm with an optional message or an integer return
1511 code. Either parameter may be specified, but not both. If
1512 neither is specified, a code of 0 (zero) is the default.
1513 kill(signal)
1515 Sends the specified signal to Eterm's primary child process
1516 (either your shell, or whatever you specify for Eterm to exe‐
1517 cute). For the time being, signal must be numeric. SIGTERM
1518 is the default if signal is omitted.
1519 msgbox(message)
1521 Displays a small dialog box containing message and waits for
1522 a keypress before continuing.
1523 nop()
1525 Does absolutely nothing except waste time. :-)
1526 paste(buffer)
1528 Pastes the contents of the specified clipboard or cut buffer
1529 into the terminal window. buffer is either a number 0-7, in
1530 which case the selection is pasted from the cut buffer speci‐
1531 fied, or one of the words clipboard, primary, or secondary
1532 (or any initial substring thereof), in which case the con‐
1533 tents of the specified clipboard are pasted. You may omit
1534 buffer, in which case the default buffer is primary (XA_PRI‐
1535 MARY in Xlib-speak).
1536 save(type, filename)
1538 Save the current theme/user configuration. type can be ei‐
1539 ther user or theme; the default is user. filename is the
1540 file to which the settings should be saved. It may contain a
1541 path which is either absolute or relative to the theme direc‐
1542 tory. The default filename for user is user.cfg, and the de‐
1543 fault filename for theme is theme.cfg.
1544 save_buff(filename)
1546 Dumps the contents of the scrollback buffer to the specified
1547 file.
1548 scroll(n)
1550 Scrolls backward or forward in the scrollback buffer. n is a
1551 floating point number followed by an optional unit specifier.
1552 The unit specifier is one of: lines or l; pages or p; or buf‐
1553 fers or b. The floating point number may be separated from
1554 the unit specifier by whitespace or a comma, but it is not
1555 required. The floating point number should be positive to
1556 scroll down (forward) and negative to scroll up (backward).
1557 For example, the key sequence Shift-PgUp is equivalent to
1558 scroll(-1p). You may also specify fractional quantities,
1559 such as scroll(0.5p) to scroll down half a page. The default
1560 unit if not specified is lines.
1561 search(str)
1563 Presents a dialog box into which the user may enter a search
1564 term. The default value is set to str. All occurances of
1565 the specified search string are highlighted in the scrollback
1566 buffer, and Eterm jumps back to the most recent one. Search‐
1567 ing again with the same keyword will clear the previous high‐
1568 lighting.
1569 spawn(command)
1571 Aliases: exec
1572 Spawns a secondary child process to execute command, or Eterm
1573 if no value is passed.
1574 string(string)
1576 The specified string is parsed via Eterm. This is exactly
1577 identical to the string action.
1578
1582 Escreen is a screen/twin interface layer which allows Eterm to interop‐
1583 erate with GNU screen and with Massimiliano Ghilardi's twin software.
1584 This allows Eterm to support multiple subshell sessions within a single
1585 window. On the surface, this feature works similarly to the "tabbed"
1586 sessions offered by programs like konsole and multi-gnome-terminal.
1587 However, Escreen has the advantage of being an interface to existing
1588 software, thus providing additional capabilities like multiple regions
1589 per display, detach/reattach capability, seamless remote session sup‐
1590 port, firewall support, and more.
1591 Escreen support is still somewhat experimental and is thus not compiled
1593 into Eterm by default. To enable it, you must compile with --enable-
1594 escreen and/or --enable-etwin (depending on whether you have screen,
1595 twin, or both). If you installed from a package, you can use Eterm
1596 --version and check for either +ESCREEN (enabled) or -ESCREEN (dis‐
1597 abled).
1598 For best results, if you wish to use Escreen mode, do so by invoking
1600 Eterm with the Escreen theme (Eterm -t Escreen). This theme supplies
1601 default key bindings, the basic Escreen menu, color definitions, etc.
1602 for use by the Escreen engine. Most importantly, it supplies the re‐
1603 quired url parameter in order to invoke Escreen mode.
1604 Consult the README.Escreen file for more in-depth discussion of Escreen
1606 mode.
1607
1610 Michael Jennings (mej@eterm.org)
1611
1614 Eterm Home Page -- http://www.eterm.org/
1615 Author's Home Page -- http://www.kainx.org/
1616X Version 11 19 January 2023 ETERM(1)