1ICESH(1) User Commands ICESH(1)
2 NAME
6 icesh - control window properties and the IceWM window manager
7 SYNOPSIS
9 icesh OPTIONS|ACTIONS+
10 DESCRIPTION
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 a dozen "SELECT OPTIONS" to select windows. They start
33 with a '-' or a '+'. The '-' starts a new selection, while the '+'
34 adds more windows to an existing selection.
35 This selection of windows can be reduced by "FILTER OPTIONS".
37 These remove unwanted windows from the current selection. Multiple
38 filter options can be given. For example, "icesh -c xterm -W this
39 close" will close only those xterms which are shown on the current
40 workspace. The xterms on other workspaces are filtered out by the
41 "-W this" filter option.
42 There is no limit to the number of commands, selections, filters and
44 actions which you can give to a single icesh command. They are
45 processed and evaluated one by one from left to right. This makes
46 icesh a small declarative programming language. Have a look at some
47 examples near the end of this document.
48 OPTIONS
50 icesh recognizes the following options:
51 SELECT OPTIONS
53 Select options specify the window or windows to which subsequent
54 actions apply. If none is given, but an action does require a window,
55 then a selection crosshair is shown to select the desired window
56 interactively. The manager actions do not require window options.
57 The following options select one or more client windows. If needed,
59 they can be repeated for successive actions.
60 -a, -all
62 Selects all client windows of the window manager.
63 -f, -focus, +f, +focus
65 Selects the application window which is currently focused. The
66 option with minus sign replaces the existing selection with the
67 focused window. With a plus sign the focused window is added to an
68 existing selection.
69 +g, +group
71 Extend the current selection with client windows which belong to
72 the same application window group.
73 -r, -root, +r, +root
75 Selects the root window. The option with minus sign replaces the
76 existing selection with the root window. With a plus sign the root
77 window is added to an existing selection.
78 -s, -shown
80 Selects all client windows which are on the current workspace.
81 -t, -top
83 Selects all toplevel windows from the display unconditionally.
84 This includes windows which have never been mapped and windows with
85 the override redirect bit set to evade management.
86 -w, -window, +w, +window WINDOW_ID
88 Specifies the identifier of the window, WINDOW_ID, for which the
89 action applies. Special identifiers are root for the root window
90 and focus for the currently focused window. The option with minus
91 sign replaces the existing selection. With a plus sign the window
92 is added to an existing selection.
93 -x, -xembed
95 Selects all windows which are embedded using the XEMBED protocol.
96 +c, +class CLASS
98 Extend the current selection with client windows that have a
99 WM_CLASS property equal to CLASS. This is the resource instance and
100 class name. If CLASS contains a period, only windows with exactly
101 the same WM_CLASS property are matched. If there is no period,
102 windows of the same class and windows of the same instance are
103 selected.
104 +C, +Class
106 Extend the current selection with client windows that have a
107 WM_CLASS property similar to the already selected set of windows.
108 -D, -Dockapps
110 Selects all Dockapp applications which are managed by icewm.
111 +P, +Pid
113 Extend the current selection with client windows that have the same
114 process identifier as one of the selected windows.
115 -T Selects the IceWM taskbar.
117 FILTER OPTIONS
119 The following options filter the currently selected set of windows. If
120 no previous select option was given then a -all option is implicitly
121 assumed to filter all client windows.
122 -c, -class CLASS
124 Filters the set of windows on their WM_CLASS property. This is the
125 resource instance and class name. If CLASS contains a period, only
126 windows with exactly the same WM_CLASS property are matched. If
127 there is no period, windows of the same class and windows of the
128 same instance (aka. -name) are selected.
129 -l, -last
131 Filter clients and keep only the most recent client.
132 -m, -machine HOST
134 Filters clients by host name. Clients with a WM_CLIENT_MACHINE
135 property equal to HOST are selected.
136 -n, -name NAME
138 Filters clients by _NET_WM_NAME or WM_NAME. NAME matches any part
139 of the property value. To match at the beginning use a "^" prefix.
140 To match at the end use a "$" suffix.
141 -p, -pid PID
143 Filters clients by process ID. Clients with a _NET_WM_PID property
144 equal to PID are selected.
145 -u, -unmapped
147 Filter clients and keep those which are currently not viewable.
148 These are hidden, minimized, rolled-up, or on another workspace.
149 -v, -viewable
151 Filter clients and keep only those which are currently viewable.
152 These clients are mapped on the current workspace.
153 -G, -Gravity GRAVITY
155 Filters clients by the window gravity field of the WM_NORMAL_HINTS
156 property. Clients with a gravity equal to GRAVITY are selected.
157 If GRAVITY starts with an exclamation mark then the filtering is
158 inverted.
159 -L, -Layer LAYER
161 Filters clients by GNOME window layer, which can either be a layer
162 name or a layer number. See EXPRESSIONS below. If LAYER starts with
163 an exclamation mark then the filtering is inverted.
164 -N, -Netstate STATE
166 Filters clients by EWMH window state. Clients which have at least
167 an EWMH window state of STATE are selected. This state refers to
168 details like MINIZED or MAXIMIZED. See EXPRESSIONS below. If STATE
169 starts with an exclamation mark then the filtering is inverted. A
170 question mark "?" filters clients with any bit set in STATE.
171 -P, -Property PROP[=value]
173 Filters clients by property. Clients which have a property PROP are
174 selected. If the optional value is given, the match succeeds only
175 if PROP is a string, window, cardinal, or atom, with a value equal
176 to value. The filtering is inverted if PROP starts with an
177 exclamation mark.
178 -R, -Role ROLE
180 Filters clients by WM_WINDOW_ROLE. Clients which have a
181 WM_WINDOW_ROLE property value equal to ROLE are selected. The
182 filtering is inverted if ROLE starts with an exclamation mark.
183 -W, -Workspace WORKSPACE
185 Filter clients by workspace. Workspace WORKSPACE is either a
186 workspace name, or a workspace number counting from zero, or the
187 word "this" for the current workspace, or the word "All" for all
188 workspaces. If WORKSPACE starts with an exclamation mark then the
189 filtering is inverted.
190 -X, -Xinerama MONITOR
192 Limit clients by RandR/Xinerama monitor. Only operate on clients
193 which are displayed on MONITOR, where MONITOR can be "All" for all
194 monitors, "this" for the monitor where the active window is
195 displayed, or a monitor number starting from zero. See the output
196 of "randr" or "xinerama" below.
197 GENERAL OPTIONS
199 The following options are identical for every IceWM command.
200 -d, -display DISPLAY
202 Specifies the X11 DISPLAY. If unspecified, defaults to $DISPLAY.
203 -h, --help
205 Print a brief usage statement to stdout and exit.
206 -V, --version
208 Print the program version to stdout and exit.
209 -C, --copying
211 Print copying permissions to stdout for the program and exit.
212 -q, --quiet
214 Don't complain if no matching windows could be found.
215 ACTIONS
217 icesh expects one or more action arguments. There are two kinds of
218 actions: window actions and manager actions. The first operates on the
219 selected windows. The second directly interacts with the icewm window
220 manager.
221 WINDOW ACTIONS
223 The following actions affect the selected window or windows.
224 activate
226 Activate the window, aka. to focus.
227 close
229 Send a close request to the client that created the window.
230 kill
232 Force an immediate close down of the client that created the
233 window.
234 id Print window identifiers for the selected windows.
236 pid Print process identifiers for the selected windows.
238 list
240 Show window details, like geometry and names.
241 lower
243 Lower the window.
244 raise
246 Raise the window.
247 above
249 Stack the window above others.
250 below
252 Stack the window below others.
253 rollup
255 Rollup the specified window.
256 fullscreen
258 Set the window to fullscreen.
259 maximize
261 Maximize the window.
262 horizontal
264 Maximize the window only horizontally.
265 vertical
267 Maximize the window only vertically.
268 minimize
270 Minimize the window.
271 restore
273 Restore the window to normal.
274 hide
276 Hide the window.
277 unhide
279 Reveal the window.
280 skip
282 Don't show the window on the taskbar.
283 unskip
285 Do show the window on the taskbar.
286 sticky
288 Show the window on all workspaces.
289 unsticky
291 Show the window on just one workspace.
292 urgent
294 Set the urgent flag to flash the task button.
295 resize WIDTH HEIGHT
297 Resize window to WIDTH by HEIGHT window units. For text based
298 applications like terminals, a window unit is the size of a single
299 character cell.
300 sizeto WIDTH HEIGHT
302 Resize window to WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends
303 with a percent sign "%", then they refer to a percentage of the
304 desktop work area. For instance, "sizeto 50% 100%" resizes to half
305 the desktop width and whatever height is available above or below
306 the taskbar.
307 sizeby WIDTH HEIGHT
309 Resize window by WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends
310 with a percent sign "%", then they refer to a percentage of the
311 current window size. For instance, "sizeby 50% 200" increases the
312 width by 50% and increases the height by 200 pixels.
313 move X Y
315 Move the selected window or windows to the screen position X Y. To
316 specify X or Y values relative to the right side or bottom side
317 precede the value with an extra minus sign, like in "move -+10
318 --20".
319 moveby X Y
321 Displace window by X Y pixels.
322 center
324 Position the window in the center of the desktop work area.
325 left
327 Position the window against the left side of the desktop work area.
328 right
330 Position the window against the right side of the desktop work
331 area.
332 top Position the window against the top side of the desktop work area.
334 bottom
336 Position the window against the bottom side of the desktop work
337 area.
338 setIconTitle TITLE
340 Set the icon title to TITLE.
341 getIconTitle
343 Print the icon title.
344 setWindowTitle TITLE
346 Set the window title to TITLE.
347 getWindowTitle
349 Print the window title.
350 setGeometry GEOMETRY
352 Set the window geometry to GEOMETRY. This geometry should be
353 specified in a format that can be parsed by XParseGeometry(3).
354 Negative offsets are with respect to the bottom or right side of
355 the screen. Use "+-" for a truly negative position.
356 getGeometry
358 Print the window geometry.
359 netState [STATE]
361 If STATE is omitted then it shows the EWMH window state. If STATE
362 starts with a "+" then flags in STATE are appended to the existing
363 EWMH window state. If STATE starts with a "-" then flags in STATE
364 are removed from the existing EWMH window state. If STATE starts
365 with a "^" then flags in STATE are toggled with respect to the
366 existing EWMH window state. If STATE starts with a "=" then the
367 EWMH window state is set to STATE. See EXPRESSIONS below. A list of
368 EWMH flags can be found in the output of "icesh symbols".
369 setLayer LAYER
371 Move the specified window to another window layer. See EXPRESSIONS
372 below for a list of LAYER symbols.
373 getLayer
375 Print the window layer for the specified window.
376 setWorkspace WORKSPACE
378 Move the specified window to another workspace. Select the root
379 window to change the current workspace. If WORKSPACE is "All" then
380 the specified window becomes visible on all workspaces. Specify
381 "this" for the current workspace, "next" for the subsequent
382 workspace or "prev" for the preceding workspace.
383 getWorkspace
385 Print the workspace for the specified window.
386 opacity [OPACITY]
388 Print the window opacity if OPACITY is not given, otherwise set the
389 window opacity to OPACITY.
390 setTrayOption TRAYOPTION
392 Set the IceWM tray option for the specified window to TRAYOPTION.
393 See IceWM tray options, below, for TRAYOPTION symbols.
394 getTrayOption
396 Print the IceWM tray option for the specified window.
397 setNormalGravity GRAVITY
399 Set the window gravity field in the WM_NORMAL_HINTS property for
400 the specified window to GRAVITY. See below for GRAVITY symbols.
401 getNormalGravity
403 Print the window gravity from the WM_NORMAL_HINTS property for the
404 specified window.
405 setWindowGravity GRAVITY
407 Set the window gravity for the specified window to GRAVITY. See
408 below for GRAVITY symbols.
409 getWindowGravity
411 Print the window gravity for the specified window.
412 setBitGravity GRAVITY
414 Set the bit gravity> for the specified window to GRAVITY. See
415 below for GRAVITY symbols.
416 getBitGravity
418 Print the bit gravity for the specified window.
419 motif [funcs FUNCTIONS | decor DECORATIONS | remove]
421 Query, set or modify the "_MOTIF_WM_HINTS" property for the
422 specified window. Without arguments motif will show the current
423 value, but only if the window has such a property. The property can
424 be removed or reset with the remove argument. With funcs and decor
425 individual fields of this property can be enabled or disabled. If
426 FUNCTIONS or DECORATIONS starts with a minus or plus sign then the
427 existing value is modified, otherwise it is set to the new value.
428 Note that if "All" is set, other set fields are disabled and
429 cleared fields are enabled.
430 borderless
432 Hide the frame borders and title.
433 bordered
435 Show the frame borders and title.
436 denormal
438 Remove the WM_NORMAL_HINTS property, if it exists. This lifts
439 font-size restrictions on resizing, especially for terminals.
440 prop PROPERTY
442 Print the value of property PROPERTY, if it is present.
443 properties
445 Print all properties and their values.
446 frame
448 Print the identifier of the window frame.
449 click window-x window-y button
451 Send a button press and release event at position (window-x,
452 window-y). A negative position is relative to the bottom right
453 corner. The mouse pointer is warped to the position before sending
454 the events. The button number should be between 1 and 5 inclusive.
455 monitors top bottom left right
457 This sets the monitors to use for fullscreen. Top, bottom, left,
458 and right are indices of the icesh xinerama command.
459 spy Observe the selected windows and report any changes. This includes
461 focus, visibility, position, size and all window properties. To
462 monitor all of the protocol request messages that client
463 applications may send to icewm, also spy on the root window.
464 MANAGER ACTIONS
466 The following actions control the IceWM window manager and therefore do
467 not require a window select or filter option:
468 listWorkspaces
470 List the names of all workspaces.
471 current
473 Show the number and name of the current workspace.
474 goto WORKSPACE
476 Change the current workspace to WORKSPACE. Specify "next" for the
477 subsequent workspace or "prev" for the preceding workspace.
478 workspaces [COUNT]
480 Print the number of workspaces if COUNT is not given, otherwise set
481 the number of workspaces to COUNT.
482 setWorkspaceName INDEX NAME
484 Change the name of the workspace INDEX to NAME, where INDEX is a
485 workspace number starting from zero.
486 setWorkspaceNames NAME [NAME]*
488 Change the workspace names to the list of NAMEs.
489 addWorkspace NAME
491 Create a new workspace with name NAME.
492 desktop [SHOWING]
494 If SHOWING is 1 then set "showing the desktop" mode. If SHOWING is
495 0 then turn off "showing the desktop". Print the current mode if
496 SHOWING is not given.
497 randr
499 Summarize the RandR configuration.
500 xinerama
502 Summarize the Xinerama configuration.
503 check
505 Print information about the current window manager, like name,
506 version, class, locale, command, host name and pid.
507 clients
509 List all managed client windows, their titles and geometries.
510 shown
512 List all mapped client windows for the current desktop, their
513 titles and geometries.
514 windows
516 List all toplevel windows, their titles and geometries.
517 systray
519 List applications which are managed by the IceWM system tray.
520 xembed
522 List application windows which are embedded using the XEMBED
523 protocol. This is another way to discover system tray
524 applications.
525 logout
527 Let icewm execute the "LogoutCommand".
528 reboot
530 Let icewm execute the "RebootCommand".
531 shutdown
533 Let icewm execute the "ShutdownCommand".
534 cancel
536 Let icewm cancel the logout/reboot/shutdown.
537 about
539 Let icewm show the about window.
540 windowlist
542 Let icewm show the window list window.
543 restart
545 Let icewm restart itself.
546 suspend
548 Let icewm execute the "SuspendCommand".
549 winoptions
551 Let icewm reload the "winoptions".
552 keys
554 Let icewm reload the "keys" file.
555 guievents
557 Monitor the ICEWM_GUI_EVENT property and report all changes.
558 delay [time]
560 Stop execution for time or 0.1 seconds.
561 runonce program [arguments...]
563 This action is meant to be used together with the -class option.
564 Only if no window is matched by WM_CLASS then program
565 [arguments...] is executed.
566 sync
568 Synchronize with the IceWM window manager. That is, wait for icewm
569 to process all previous actions.
570 symbols
572 List all named symbols.
573 CONDITIONALS
575 Icesh supports "if-then-else" expressions. The full syntax is:
576 if selection
578 then
579 actions
580 elif selection
581 then
582 actions
583 else
584 actions
585 end
586 Where "selection" is a sequence of selection and filtering options,
588 which evaluates to true when it is non-empty. That is, if one or more
589 windows fulfilled the condition. If it is empty, then its "actions"
590 clause is ignored and the subsequent "elif" or "else" clause is tried
591 or taken. Each clause is optional.
592 Whenever a selection condition evaluates to false, the window selection
594 that existed before the "if" clause is immediately restored. This also
595 happens after an "end" clause.
596 EXPRESSIONS
598 Some of the window actions require one or two EXPRESSION arguments.
599 EXPRESSION ::= SYMBOL | EXPRESSION { "+" | "|" } SYMBOL
601 Each SYMBOL may be from one of the following applicable domains:
603 Window layer
605 Named symbols of the domain Window layer (numeric range: 0-15):
606 Desktop (0)
608 Below (2)
609 Normal (4)
610 OnTop (6)
611 Dock (8)
612 AboveDock (10)
613 Menu (12)
614 These symbols are used with the LAYER argument to the "setLayer"
616 action.
617 IceWM tray option
619 Named symbols of the domain IceWM tray option (numeric range: 0-2):
620 Ignore (0)
622 Minimized (1)
623 Exclusive (2)
624 These symbols are used with the TRAYOPTION argument to the
626 "setTrayOption" action.
627 Gravity symbols
629 Named symbols for window and bit gravity (numeric range: 0-10):
630 ForgetGravity (0)
632 NorthWestGravity (1)
633 NorthGravity (2)
634 NorthEastGravity (3)
635 WestGravity (4)
636 CenterGravity (5)
637 EastGravity (6)
638 SouthWestGravity (7)
639 SouthGravity (8)
640 SouthEastGravity (9)
641 StaticGravity (10)
642 Motif functions
644 All (1)
645 Resize (2)
646 Move (4)
647 Minimize (8)
648 Maximize (16)
649 Close (32)
650 Motif decorations
652 All (1)
653 Border (2)
654 Resize (4)
655 Title (8)
656 Menu (16)
657 Minimize (32)
658 Maximize (64)
659 EWMH window state symbols
661 Named symbols of the domain EWMH state (numeric range: 0-8191):
662 ABOVE (1)
664 BELOW (2)
665 DEMANDS_ATTENTION (4)
666 FOCUSED (8)
667 FULLSCREEN (16)
668 HIDDEN (32)
669 MAXIMIZED_HORZ (64)
670 MAXIMIZED_VERT (128)
671 MODAL (256)
672 SHADED (512)
673 SKIP_PAGER (1024)
674 SKIP_TASKBAR (2048)
675 STICKY (4096)
676 EXAMPLES
678 List all workspace names:
679 icesh listWorkspaces
681 Example output:
683 workspace #0: `main'
685 workspace #1: `web'
686 workspace #2: `doc'
687 workspace #3: `dev'
688 Close terminal work and activate terminal fun.
690 icesh -c work.XTerm close -a -c fun.XTerm activate
692 Print opacity for all xterms.
694 icesh -c XTerm opacity
696 Change opacity for all xterms.
698 icesh -c XTerm opacity 84
700 Move all windows on workspace "Top" to the current workspace.
702 icesh -W "Top" setWorkspace "this"
704 Restore all hidden clients, minimize all clients on the current
706 workspace and activate Firefox.
707 icesh -N HIDDEN restore -a -W "this" minimize -a -c Firefox activate
709 Resize the focused window to occupy the right half of the desktop area.
711 icesh -f sizeto 49% 100% sync top sync right sync raise activate
713 Toggle the frame border of the focused window.
715 if icesh -f motif | grep -q 'decor:$'; then \
717 icesh -f motif decor All; else icesh -f motif decor ""; fi
718 Here is a different solution using conditionals.
720 icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless
722 Here is a conditional to either toggle the visibility of a roxterm,
724 which has a WM_ROLE value of "special", or start it with runonce.
725 icesh sync if -c roxterm.Roxterm -R special then \
727 if -v then hide \
728 elif -u then setWorkspace this sync activate end \
729 else runonce roxterm --role=special
730 ENVIRONMENT
732 DISPLAY
733 The default display.
734 EXIT STATUS
736 0 The last action completed successfully.
737 1 The last action completed unsuccessfully, or no window met the
739 condition.
740 2 A conditional has invalid syntax.
742 3 The display could not be opened.
744 4 The X server reports an error while processing a request.
746 COMPLIANCE
748 icesh is largely compliant with the EWMH and ICCCM specifications.
749 Some commands, like manager actions, are specific to IceWM.
750 SEE ALSO
752 icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1),
753 XParseGeometry(3).
754 BUGS
756 Please report bugs at <https://github.com/bbidulock/icewm/issues>.
757 AUTHOR
759 Brian Bidulock <mailto:bidulock@openss7.org>.
760 See --copying for full copyright notice and copying permissions.
762 LICENSE
764 IceWM is licensed under the GNU Library General Public License. See
765 the COPYING file in the distribution or use the --copying flag to
766 display copying permissions.
767icewm 2.9.7 2022-05-16 ICESH(1)