1ICESH(1) User Commands ICESH(1)
2
6 icesh - control window properties and the IceWM window manager
7
9 icesh OPTIONS|ACTIONS+
10
12 icesh provides two types of commands:
13 1. Commands to directly interact with icewm:
15 These are listed in the section "MANAGER ACTIONS" below. They are
16 easy to use, because they don't require to select one or more
17 windows. For example, "icesh restart" will restart icewm and "icesh
18 clients" lists the applications which are managed by icewm.
19 2. Commands which operate on a selection of windows:
21 See the section "WINDOW ACTIONS" below. For example, "icesh close"
22 is a request to close a window, but which window? Now icesh will
23 turn the mouse pointer into a crosshair. Click on a window and a
24 close request will be sent to that application.
25 The power of icesh lies in its ability to programmatically select
27 one or more windows and operate on that selection. This can be
28 used in scripts and in icewm-keys(5) to define your own window
29 management hotkeys. For example, to immediately close all xterm
30 windows do "icesh -c xterm close".
31 There are about ten "SELECT OPTIONS" to select windows. They start
33 with a minus sign '-' or with a plus sign '+'. The first starts a
34 new selection. The second adds more windows to an existing
35 selection.
36 This selection of windows can be reduced by "FILTER OPTIONS".
38 These remove unwanted windows from the current selection. Multiple
39 filter options can be given. For example, "icesh -c xterm -W this
40 close" will close only those xterms which are shown on the current
41 workspace. The xterms on other workspaces are filtered out by the
42 "-W this" filter option.
43 There is no limit to the number of commands, selections, filters and
45 actions which you can give to a single icesh command. They are
46 processed and evaluated one by one from left to right. This makes
47 icesh a small declarative programming language. Have a look at some
48 examples near the end of this document.
49
51 icesh recognizes the following options:
52 SELECT OPTIONS
54 Select options specify the window or windows to which subsequent
55 actions apply. If none is given, but an action does require a window,
56 then a selection crossbar is invoked to select the desired window
57 interactively. The manager actions do not require window options.
58 The following options select one or more client windows. If needed,
60 they can be repeated for successive actions.
61 -a, -all
63 Selects all client windows of the window manager.
64 -f, -focus, +f, +focus
66 Selects the application window which is currently focused. The
67 option with minus sign replaces the existing selection with the
68 focused window. With a plus sign the focused window is added to an
69 existing selection.
70 +g, +group
72 Extend the current selection with client windows which belong to
73 the same application window group.
74 -r, -root, +r, +root
76 Selects the root window. The option with minus sign replaces the
77 existing selection with the root window. With a plus sign the root
78 window is added to an existing selection.
79 -s, -shown
81 Selects all client windows which are on the current workspace.
82 -t, -top
84 Selects all toplevel windows from the display unconditionally.
85 This includes windows which have never been mapped and windows with
86 the override redirect bit set to evade management.
87 -w, -window, +w, +window WINDOW_ID
89 Specifies the identifier of the window, WINDOW_ID, for which the
90 action applies. Special identifiers are root for the root window
91 and focus for the currently focused window. The option with minus
92 sign replaces the existing selection. With a plus sign the window
93 is added to an existing selection.
94 -x, -xembed
96 Selects all windows which are embedded using the XEMBED protocol.
97 +C, +Class
99 Extend the current selection with client windows that have a
100 similar WM_CLASS property, which specifies the resource instance
101 and the class name.
102 -D, -Dockapps
104 Selects all Dockapp applications which are managed by icewm.
105 -T Selects the IceWM taskbar.
107 FILTER OPTIONS
109 The following options filter the currently selected set of windows. If
110 no previous select option was given then a -all option is implicitly
111 assumed to filter all client windows.
112 -c, -class WM_CLASS
114 Filters the set of windows on window manager class, WM_CLASS. If
115 WM_CLASS contains a period, only windows with exactly the same
116 WM_CLASS property are matched. If there is no period, windows of
117 the same class and windows of the same instance (aka. -name) are
118 selected.
119 -l, -last
121 Filter clients and keep only the most recent client.
122 -m, -machine HOST
124 Filters clients by host name. Clients with a WM_CLIENT_MACHINE
125 property equal to HOST are selected.
126 -n, -name NAME
128 Filters clients by _NET_WM_NAME or WM_NAME. NAME matches any part
129 of the property value. To match at the beginning use a "^" prefix.
130 To match at the end use a "$" suffix.
131 -p, -pid PID
133 Filters clients by process ID. Clients with a _NET_WM_PID property
134 equal to PID are selected.
135 -u, -unmapped
137 Filter clients and keep those which are currently not viewable.
138 These are hidden, minimized, rolled-up, or on another workspace.
139 -v, -viewable
141 Filter clients and keep only those which are currently viewable.
142 These clients are mapped on the current workspace.
143 -G, -Gravity GRAVITY
145 Filters clients by the window gravity field of the WM_NORMAL_HINTS
146 property. Clients with a gravity equal to GRAVITY are selected.
147 If GRAVITY starts with an exclamation mark then the filtering is
148 inverted.
149 -L, -Layer LAYER
151 Filters clients by GNOME window layer, which can either be a layer
152 name or a layer number. See EXPRESSIONS below. If LAYER starts with
153 an exclamation mark then the filtering is inverted.
154 -N, -Netstate STATE
156 Filters clients by EWMH window state. Clients which have at least
157 an EWMH window state of STATE are selected. This state refers to
158 details like MINIZED or MAXIMIZED. See EXPRESSIONS below. If STATE
159 starts with an exclamation mark then the filtering is inverted. A
160 question mark "?" filters clients with any bit set in STATE.
161 -P, -Property PROP[=value]
163 Filters clients by property. Clients which have a property PROP are
164 selected. If the optional value is given, the match succeeds only
165 if PROP is a string, window, cardinal, or atom, with a value equal
166 to value. The filtering is inverted if PROP starts with an
167 exclamation mark.
168 -R, -Role ROLE
170 Filters clients by WM_WINDOW_ROLE. Clients which have a
171 WM_WINDOW_ROLE property value equal to ROLE are selected. The
172 filtering is inverted if ROLE starts with an exclamation mark.
173 -W, -Workspace WORKSPACE
175 Filter clients by workspace. Workspace WORKSPACE is either a
176 workspace name, or a workspace number counting from zero, or the
177 word "this" for the current workspace, or the word "All" for all
178 workspaces. If WORKSPACE starts with an exclamation mark then the
179 filtering is inverted.
180 -X, -Xinerama MONITOR
182 Limit clients by RandR/Xinerama monitor. Only operate on clients
183 which are displayed on MONITOR, where MONITOR can be "All" for all
184 monitors, "this" for the monitor where the active window is
185 displayed, or a monitor number starting from zero. See the output
186 of "randr" or "xinerama" below.
187 GENERAL OPTIONS
189 The following options are identical for every IceWM command.
190 -d, -display DISPLAY
192 Specifies the X11 DISPLAY. If unspecified, defaults to $DISPLAY.
193 -h, --help
195 Print a brief usage statement to stdout and exit.
196 -V, --version
198 Print the program version to stdout and exit.
199 -C, --copying
201 Print copying permissions to stdout for the program and exit.
202 -q, --quiet
204 Don't complain if no matching windows could be found.
205
207 icesh expects one or more action arguments. There are two kinds of
208 actions: window actions and manager actions. The first operates on the
209 selected windows. The second directly interacts with the icewm window
210 manager.
211 WINDOW ACTIONS
213 The following actions affect the selected window or windows.
214 activate
216 Activate the window, aka. to focus.
217 close
219 Send a close request to the client that created the window.
220 kill
222 Force an immediate close down of the client that created the
223 window.
224 id Print window identifiers for the selected windows.
226 pid Print process identifiers for the selected windows.
228 list
230 Show window details, like geometry and names.
231 lower
233 Lower the window.
234 raise
236 Raise the window.
237 above
239 Stack the window above others.
240 below
242 Stack the window below others.
243 rollup
245 Rollup the specified window.
246 fullscreen
248 Set the window to fullscreen.
249 maximize
251 Maximize the window.
252 horizontal
254 Maximize the window only horizontally.
255 vertical
257 Maximize the window only vertically.
258 minimize
260 Minimize the window.
261 restore
263 Restore the window to normal.
264 hide
266 Hide the window.
267 unhide
269 Reveal the window.
270 skip
272 Don't show the window on the taskbar.
273 unskip
275 Do show the window on the taskbar.
276 sticky
278 Show the window on all workspaces.
279 unsticky
281 Show the window on only one workspace.
282 urgent
284 Set the urgent flag.
285 resize WIDTH HEIGHT
287 Resize window to WIDTH by HEIGHT window units.
288 sizeto WIDTH HEIGHT
290 Resize window to WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends
291 with a percent sign "%", then they refer to a percentage of the
292 desktop work area. For instance, "sizeto 50% 100%" resizes to half
293 the desktop width and whatever height is available above or below
294 the taskbar.
295 sizeby WIDTH HEIGHT
297 Resize window by WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends
298 with a percent sign "%", then they refer to a percentage of the
299 current window size. For instance, "sizeby 50% 200" increases the
300 width by 50% and increases the height by 200 pixels.
301 move X Y
303 Move the selected window or windows to the screen position X Y. To
304 specify X or Y values relative to the right side or bottom side
305 precede the value with an extra minus sign, like in "move -+10
306 --20".
307 moveby X Y
309 Displace window by X Y pixels.
310 center
312 Position the window in the center of the desktop work area.
313 left
315 Position the window against the left side of the desktop work area.
316 right
318 Position the window against the right side of the desktop work
319 area.
320 top Position the window against the top side of the desktop work area.
322 bottom
324 Position the window against the bottom side of the desktop work
325 area.
326 setIconTitle TITLE
328 Set the icon title to TITLE.
329 getIconTitle
331 Print the icon title.
332 setWindowTitle TITLE
334 Set the window title to TITLE.
335 getWindowTitle
337 Print the window title.
338 setGeometry GEOMETRY
340 Set the window geometry to GEOMETRY. This geometry should be
341 specified in a format that can be parsed by XParseGeometry(3).
342 Negative offsets are with respect to the bottom or right side of
343 the screen. Use "+-" for a truly negative position.
344 getGeometry
346 Print the window geometry.
347 netState [STATE]
349 If STATE is omitted then it shows the EWMH window state. If STATE
350 starts with a "+" then flags in STATE are appended to the existing
351 EWMH window state. If STATE starts with a "-" then flags in STATE
352 are removed from the existing EWMH window state. If STATE starts
353 with a "^" then flags in STATE are toggled with respect to the
354 existing EWMH window state. If STATE starts with a "=" then the
355 EWMH window state is set to STATE. See EXPRESSIONS below. A list of
356 EWMH flags can be found in the output of "icesh symbols".
357 setLayer LAYER
359 Move the specified window to another GNOME window layer. See below
360 for LAYER symbols.
361 getLayer
363 Print the GNOME window layer for the specified window.
364 setWorkspace WORKSPACE
366 Move the specified window to another workspace. Select the root
367 window to change the current workspace. If WORKSPACE is "All" then
368 the specified window becomes visible on all workspaces. Specify
369 "this" for the current workspace.
370 getWorkspace
372 Print the workspace for the specified window.
373 opacity [OPACITY]
375 Print the window opacity if OPACITY is not given, otherwise set the
376 window opacity to OPACITY.
377 setTrayOption TRAYOPTION
379 Set the IceWM tray option for the specified window to TRAYOPTION.
380 See IceWM tray options, below, for TRAYOPTION symbols.
381 getTrayOption
383 Print the IceWM tray option for the specified window.
384 setNormalGravity GRAVITY
386 Set the window gravity field in the WM_NORMAL_HINTS property for
387 the specified window to GRAVITY. See below for GRAVITY symbols.
388 getNormalGravity
390 Print the window gravity from the WM_NORMAL_HINTS property for the
391 specified window.
392 setWindowGravity GRAVITY
394 Set the window gravity for the specified window to GRAVITY. See
395 below for GRAVITY symbols.
396 getWindowGravity
398 Print the window gravity for the specified window.
399 setBitGravity GRAVITY
401 Set the bit gravity> for the specified window to GRAVITY. See
402 below for GRAVITY symbols.
403 getBitGravity
405 Print the bit gravity for the specified window.
406 motif [funcs FUNCTIONS | decor DECORATIONS | remove]
408 Query, set or modify the "_MOTIF_WM_HINTS" property for the
409 specified window. Without arguments motif will show the current
410 value, but only if the window has such a property. The property can
411 be removed or reset with the remove argument. With funcs and decor
412 individual fields of this property can be enabled or disabled. If
413 FUNCTIONS or DECORATIONS starts with a minus or plus sign then the
414 existing value is modified, otherwise it is set to the new value.
415 Note that if "All" is set, then other set fields will be disabled
416 and cleared fields will be enabled.
417 borderless
419 Hide the frame borders and title.
420 bordered
422 Show the frame borders and title.
423 denormal
425 Remove the WM_NORMAL_HINTS property, if it exists. This lifts
426 font-size restrictions on resizing, especially for terminals.
427 prop PROPERTY
429 Print the value of property PROPERTY if it is present.
430 properties
432 Print all properties.
433 frame
435 Print the identifier of the window frame.
436 click window-x window-y button
438 Send a button press and release event at position (window-x,
439 window-y). A negative position is relative to the bottom right
440 corner. The mouse pointer is warped to the position before sending
441 the events. The button number should be between 1 and 5 inclusive.
442 monitors top bottom left right
444 This sets the monitors to use for fullscreen. Top, bottom, left,
445 and right are indices of the icesh xinerama command.
446 spy Observe the selected windows and report any changes. This includes
448 focus, visibility, position, size and all window properties. To
449 monitor all of the protocol request messages that client
450 applications may send to icewm, also spy on the root window.
451 MANAGER ACTIONS
453 The following actions control the IceWM window manager and therefore do
454 not require a window select or filter option:
455 listWorkspaces
457 List the names of all workspaces.
458 current
460 Show the number and name of the current workspace.
461 goto WORKSPACE
463 Change the current workspace to WORKSPACE.
464 workspaces [COUNT]
466 Print the number of workspaces if COUNT is not given, otherwise set
467 the number of workspaces to COUNT.
468 setWorkspaceName INDEX NAME
470 Change the name of the workspace INDEX to NAME, where INDEX is a
471 workspace number starting from zero.
472 setWorkspaceNames NAME [NAME]*
474 Change the workspace names to the list of NAMEs.
475 addWorkspace NAME
477 Create a new workspace with name NAME.
478 desktop [SHOWING]
480 If SHOWING is 1 then set "showing the desktop" mode. If SHOWING is
481 0 then turn off "showing the desktop". Print the current mode if
482 SHOWING is not given.
483 randr
485 Summarize the RandR configuration.
486 xinerama
488 Summarize the Xinerama configuration.
489 check
491 Print information about the current window manager, like name,
492 version, class, locale, command, host name and pid.
493 clients
495 List all managed client windows, their titles and geometries.
496 shown
498 List all mapped client windows for the current desktop, their
499 titles and geometries.
500 windows
502 List all toplevel windows, their titles and geometries.
503 systray
505 List applications which are managed by the IceWM system tray.
506 xembed
508 List application windows which are embedded using the XEMBED
509 protocol. This is another way to discover system tray
510 applications.
511 logout
513 Let icewm execute the "LogoutCommand".
514 reboot
516 Let icewm execute the "RebootCommand".
517 shutdown
519 Let icewm execute the "ShutdownCommand".
520 cancel
522 Let icewm cancel the logout/reboot/shutdown.
523 about
525 Let icewm show the about window.
526 windowlist
528 Let icewm show the window list window.
529 restart
531 Let icewm restart itself.
532 suspend
534 Let icewm execute the "SuspendCommand".
535 winoptions
537 Let icewm reload the "winoptions".
538 keys
540 Let icewm reload the "keys" file.
541 guievents
543 Monitor the ICEWM_GUI_EVENT property and report all changes.
544 delay [time]
546 Stop execution for time or 0.1 seconds.
547 runonce program [arguments...]
549 This action is meant to be used together with the -class option.
550 Only if no window is matched by WM_CLASS then program
551 [arguments...] is executed.
552 sync
554 Synchronize with the IceWM window manager. That is, wait for icewm
555 to process all previous actions.
556 symbols
558 List all named symbols.
559 CONDITIONALS
561 Icesh supports "if-then-else" expressions. The full syntax is:
562 if selection
564 then
565 actions
566 elif selection
567 then
568 actions
569 else
570 actions
571 end
572 Where "selection" is a sequence of selection and filtering options,
574 which evaluates to true when it is non-empty. That is, if one or more
575 windows fulfilled the condition. If it is empty, then its "actions"
576 clause is ignored and the subsequent "elif" or "else" clause is tried
577 or taken. Each clause is optional.
578 Whenever a selection condition evaluates to false, the window selection
580 that existed before the "if" clause is immediately restored. This also
581 happens after an "end" clause.
582 EXPRESSIONS
584 Some of the window actions require one or two EXPRESSION arguments.
585 EXPRESSION ::= SYMBOL | EXPRESSION { "+" | "|" } SYMBOL
587 Each SYMBOL may be from one of the following applicable domains:
589 Window layer
591 Named symbols of the domain Window layer (numeric range: 0-15):
592 Desktop (0)
594 Below (2)
595 Normal (4)
596 OnTop (6)
597 Dock (8)
598 AboveDock (10)
599 Menu (12)
600 These symbols are used with the LAYER argument to the "setLayer"
602 action.
603 IceWM tray option
605 Named symbols of the domain IceWM tray option (numeric range: 0-2):
606 Ignore (0)
608 Minimized (1)
609 Exclusive (2)
610 These symbols are used with the TRAYOPTION argument to the
612 "setTrayOption" action.
613 Gravity symbols
615 Named symbols for window and bit gravity (numeric range: 0-10):
616 ForgetGravity (0)
618 NorthWestGravity (1)
619 NorthGravity (2)
620 NorthEastGravity (3)
621 WestGravity (4)
622 CenterGravity (5)
623 EastGravity (6)
624 SouthWestGravity (7)
625 SouthGravity (8)
626 SouthEastGravity (9)
627 StaticGravity (10)
628 Motif functions
630 All (1)
631 Resize (2)
632 Move (4)
633 Minimize (8)
634 Maximize (16)
635 Close (32)
636 Motif decorations
638 All (1)
639 Border (2)
640 Resize (4)
641 Title (8)
642 Menu (16)
643 Minimize (32)
644 Maximize (64)
645 EWMH window state symbols
647 Named symbols of the domain EWMH state (numeric range: 0-8191):
648 ABOVE (1)
650 BELOW (2)
651 DEMANDS_ATTENTION (4)
652 FOCUSED (8)
653 FULLSCREEN (16)
654 HIDDEN (32)
655 MAXIMIZED_HORZ (64)
656 MAXIMIZED_VERT (128)
657 MODAL (256)
658 SHADED (512)
659 SKIP_PAGER (1024)
660 SKIP_TASKBAR (2048)
661 STICKY (4096)
662
664 List all workspace names:
665 icesh listWorkspaces
667 Example output:
669 workspace #0: `main'
671 workspace #1: `web'
672 workspace #2: `doc'
673 workspace #3: `dev'
674 Close terminal work and activate terminal fun.
676 icesh -c work.XTerm close -a -c fun.XTerm activate
678 Print opacity for all xterms.
680 icesh -c XTerm opacity
682 Change opacity for all xterms.
684 icesh -c XTerm opacity 84
686 Move all windows on workspace "Top" to the current workspace.
688 icesh -W "Top" setWorkspace "this"
690 Restore all hidden clients, minimize all clients on the current
692 workspace and activate Firefox.
693 icesh -S hidden restore -a -W "this" minimize -a -c Firefox activate
695 Resize the focused window to occupy the right half of the desktop area.
697 icesh -f sizeto 49% 100% sync top sync right sync raise activate
699 Toggle the frame border of the focused window.
701 if icesh -f motif | grep -q 'decor:$'; then \
703 icesh -f motif decor All; else icesh -f motif decor ""; fi
704 Here is a different solution using conditionals.
706 icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless
708 Here is a conditional to either toggle the visibility of a roxterm,
710 which has a WM_ROLE value of "special", or start it with runonce.
711 icesh sync if -c roxterm.Roxterm -R special then \
713 if -v then hide \
714 elif -u then setWorkspace this sync activate end \
715 else runonce roxterm --role=special
716
718 DISPLAY
719 The default display.
720
722 0 The last action completed successfully.
723 1 The last action completed unsuccessfully, or no window met the
725 condition.
726 2 A conditional has invalid syntax.
728 3 The display could not be opened.
730 4 The X server reports an error while processing a request.
732
734 icesh is largely compliant with the EWMH and ICCCM specifications.
735 Some commands, like manager actions, are specific to IceWM.
736
738 icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1),
739 XParseGeometry(3).
740
742 Please report bugs at <https://github.com/bbidulock/icewm/issues>.
743
745 Brian Bidulock <mailto:bidulock@openss7.org>.
746 See --copying for full copyright notice and copying permissions.
748
750 IceWM is licensed under the GNU Library General Public License. See
751 the COPYING file in the distribution or use the --copying flag to
752 display copying permissions.
753icewm 2.9.0 2021-11-24 ICESH(1)