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 commands to directly interact with the icewm(1) window
13 manager. There are two types of commands:
14 1. Commands to directly interact with icewm:
16 These are listed in the section "MANAGER ACTIONS" below. They are
17 easy to use, because they don't require to select one or more
18 windows. For example, "icesh restart" will restart icewm and "icesh
19 clients" lists the applications which are managed by icewm.
20 2. Commands which operate on a selection of windows:
22 See the section "WINDOW ACTIONS" below. For example, "icesh close"
23 is a request to close a window, but which window? Now icesh will
24 turn the mouse pointer into a crosshair. Click on a window and a
25 close request will be sent to that application.
26 The power of icesh lies in its ability to programmatically select
28 one or more windows and operate on that selection. This can be
29 used in scripts and in icewm-keys(5) to define your own window
30 management hotkeys. For example, to immediately close all xterm
31 windows do "icesh -c xterm close".
32 There are about seven "SELECT OPTIONS" to select windows. They
34 start with a minus sign '-' or with a plus sign '+'. The first
35 starts a new selection. The second adds more windows to an existing
36 selection.
37 This selection of windows can be reduced by "FILTER OPTIONS".
39 These remove unwanted windows from the current selection. Multiple
40 filter options can be given. For example, "icesh -c xterm -W this
41 close" will close only those xterms which are shown on the current
42 workspace. The xterms on other workspaces are filtered out by the
43 "-W this" filter option.
44 There is no limit to the number of commands, selections, filters and
46 actions which you can give to a single icesh command. They are
47 processed and evaluated one by one from left to right. This makes
48 icesh a small declarative programming language. Have a look at some
49 examples near the end of this document.
50
52 icesh recognizes the following options:
53 SELECT OPTIONS
55 Select options specify the window or windows to which subsequent
56 actions apply. If none is given, but an action does require a window,
57 then a selection crossbar is invoked to select the desired window
58 interactively. The manager actions do not require window options.
59 The following five options select one or more client windows. If
61 needed, they can be repeated for successive actions.
62 -w, -window, +w, +window WINDOW_ID
64 Specifies the identifier of the window, WINDOW_ID, for which the
65 action applies. Special identifiers are root for the root window
66 and focus for the currently focused window. The option with minus
67 sign replaces the existing selection. With a plus sign the window
68 is added to an existing selection.
69 -r, -root, +r, +root
71 Is equivalent to -window root and selects the root window. The
72 option with minus sign replaces the existing selection with the
73 root window. With a plus sign the root window is added to an
74 existing selection.
75 -f, -focus, +f, +focus
77 Is equivalent to -window focus and selects the focused window. The
78 option with minus sign replaces the existing selection with the
79 focused window. With a plus sign the focused window is added to an
80 existing selection.
81 -a, -all
83 Selects all client windows of the window manager.
84 -s, -shown
86 Selects all clients which are on the current workspace.
87 -t, -top
89 Selects all toplevel windows from the display unconditionally.
90 This includes windows which have never been mapped and windows with
91 the override redirect bit set to evade management.
92 -x, -xembed
94 Selects all windows which are embedded using the XEMBED protocol.
95 FILTER OPTIONS
97 The following options filter the currently selected set of windows. If
98 no previous select option was given then a -all option is implicitly
99 assumed to filter all client windows.
100 -c, -class WM_CLASS
102 Filters the set of windows on window manager class, WM_CLASS. If
103 WM_CLASS contains a period, only windows with exactly the same
104 WM_CLASS property are matched. If there is no period, windows of
105 the same class and windows of the same instance (aka. -name) are
106 selected.
107 -l, -last
109 Filter clients and keep only the most recent client.
110 -m, -machine HOST
112 Filters clients by host name. Clients with a WM_CLIENT_MACHINE
113 property equal to HOST are selected.
114 -n, -name NAME
116 Filters clients by _NET_WM_NAME or WM_NAME. NAME matches any part
117 of the property value. To match at the beginning use a "^" prefix.
118 To match at the end use a "$" suffix.
119 -p, -pid PID
121 Filters clients by process ID. Clients with a _NET_WM_PID property
122 equal to PID are selected.
123 -G, -Gravity GRAVITY
125 Filters clients by the window gravity field of the WM_NORMAL_HINTS
126 property. Clients with a gravity equal to GRAVITY are selected.
127 If GRAVITY starts with an exclamation mark then the filtering is
128 inverted.
129 -L, -Layer LAYER
131 Filters clients by GNOME window layer, which can either be a layer
132 name or a layer number. See EXPRESSIONS below. If LAYER starts with
133 an exclamation mark then the filtering is inverted.
134 -N, -Netstate STATE
136 Filters clients by EWMH window state. Clients which have at least
137 an EWMH window state of STATE are selected. This state refers to
138 details like minized or maximized. See EXPRESSIONS below. If STATE
139 starts with an exclamation mark then the filtering is inverted. A
140 question mark "?" filters clients with any bit set in STATE.
141 -P, -Property PROP[=value]
143 Filters clients by property. Clients which have a property PROP are
144 selected. If the optional value is given, the match succeeds only
145 if PROP is a string, window, cardinal, or atom, with a value equal
146 to value. The filtering is inverted if PROP starts with an
147 exclamation mark.
148 -R, -Role ROLE
150 Filters clients by WM_WINDOW_ROLE. Clients which have a
151 WM_WINDOW_ROLE property value equal to ROLE are selected. The
152 filtering is inverted if ROLE starts with an exclamation mark.
153 -W, -Workspace WORKSPACE
155 Filter clients by workspace. Workspace WORKSPACE is either a
156 workspace name, or a workspace number counting from zero, or the
157 word "this" for the current workspace, or the word "All" for all
158 workspaces. If WORKSPACE starts with an exclamation mark then the
159 filtering is inverted.
160 -X, -Xinerama MONITOR
162 Limit clients by RandR/Xinerama monitor. Only operate on clients
163 which are displayed on MONITOR, where MONITOR can be "All" for all
164 monitors, "this" for the monitor where the active window is
165 displayed, or a monitor number starting from zero. See the output
166 of "randr" or "xinerama" below.
167 GENERAL OPTIONS
169 The following options are identical for every IceWM command.
170 -d, -display DISPLAY
172 Specifies the X11 DISPLAY. If unspecified, defaults to $DISPLAY.
173 -h, --help
175 Print a brief usage statement to stdout and exit.
176 -V, --version
178 Print the program version to stdout and exit.
179 -C, --copying
181 Print copying permissions to stdout for the program and exit.
182 -q, --quiet
184 Don't complain if no matching windows could be found.
185
187 icesh expects one or more action arguments. There are two kinds of
188 actions: window actions and manager actions. The first operates on the
189 selected windows. The second directly interacts with the icewm window
190 manager.
191 WINDOW ACTIONS
193 The following actions affect the selected window or windows.
194 activate
196 Activate the window, aka. to focus.
197 close
199 Send a close request to the client that created the window.
200 kill
202 Force an immediate close down of the client that created the
203 window.
204 id Print window identifiers for the selected windows.
206 pid Print process identifiers for the selected windows.
208 list
210 Show window details, like geometry and names.
211 lower
213 Lower the window.
214 raise
216 Raise the window.
217 above
219 Stack the window above others.
220 below
222 Stack the window below others.
223 rollup
225 Rollup the specified window.
226 fullscreen
228 Set the window to fullscreen.
229 maximize
231 Maximize the window.
232 horizontal
234 Maximize the window only horizontally.
235 vertical
237 Maximize the window only vertically.
238 minimize
240 Minimize the window.
241 restore
243 Restore the window to normal.
244 hide
246 Hide the window.
247 unhide
249 Reveal the window.
250 skip
252 Don't show the window on the taskbar.
253 unskip
255 Do show the window on the taskbar.
256 sticky
258 Show the window on all workspaces.
259 unsticky
261 Show the window on only one workspace.
262 urgent
264 Set the urgent flag.
265 resize WIDTH HEIGHT
267 Resize window to WIDTH by HEIGHT window units.
268 sizeto WIDTH HEIGHT
270 Resize window to WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends
271 with a percent sign "%", then they refer to a percentage of the
272 desktop work area. For instance, "sizeto 50% 100%" resizes to half
273 the desktop width and whatever height is available above or below
274 the taskbar.
275 sizeby WIDTH HEIGHT
277 Resize window by WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends
278 with a percent sign "%", then they refer to a percentage of the
279 current window size. For instance, "sizeto 50% 200" increases the
280 width by 50% and increases the height by 200 pixels.
281 move X Y
283 Move the selected window or windows to the screen position X Y. To
284 specify X or Y values relative to the right side or bottom side
285 precede the value with an extra minus sign, like in "move -+10
286 --20".
287 moveby X Y
289 Displace window by X Y pixels.
290 center
292 Position the window in the center of the desktop work area.
293 left
295 Position the window against the left side of the desktop work area.
296 right
298 Position the window against the right side of the desktop work
299 area.
300 top Position the window against the top side of the desktop work area.
302 bottom
304 Position the window against the bottom side of the desktop work
305 area.
306 setIconTitle TITLE
308 Set the icon title to TITLE.
309 getIconTitle
311 Print the icon title.
312 setWindowTitle TITLE
314 Set the window title to TITLE.
315 getWindowTitle
317 Print the window title.
318 setGeometry GEOMETRY
320 Set the window geometry to GEOMETRY.
321 getGeometry
323 Print the window geometry.
324 netState [STATE]
326 If STATE is omitted then it shows the EWMH window state. If STATE
327 starts with a "+" then flags in STATE are appended to the existing
328 EWMH window state. If STATE starts with a "-" then flags in STATE
329 are removed from the existing EWMH window state. If STATE starts
330 with a "^" then flags in STATE are toggled with respect to the
331 existing EWMH window state. If STATE starts with a "=" then the
332 EWMH window state is set to STATE. See EXPRESSIONS below. A list of
333 EWMH flags can be found in the output of "icesh symbols".
334 setLayer LAYER
336 Move the specified window to another GNOME window layer. See below
337 for LAYER symbols.
338 getLayer
340 Print the GNOME window layer for the specified window.
341 setWorkspace WORKSPACE
343 Move the specified window to another workspace. Select the root
344 window to change the current workspace. If WORKSPACE is "All" then
345 the specified window becomes visible on all workspaces. Specify
346 "this" for the current workspace.
347 getWorkspace
349 Print the workspace for the specified window.
350 opacity [OPACITY]
352 Print the window opacity if OPACITY is not given, otherwise set the
353 window opacity to OPACITY.
354 setTrayOption TRAYOPTION
356 Set the IceWM tray option for the specified window to TRAYOPTION.
357 See IceWM tray options, below, for TRAYOPTION symbols.
358 getTrayOption
360 Print the IceWM tray option for the specified window.
361 setNormalGravity GRAVITY
363 Set the window gravity field in the WM_NORMAL_HINTS property for
364 the specified window to GRAVITY. See below for GRAVITY symbols.
365 getNormalGravity
367 Print the window gravity from the WM_NORMAL_HINTS property for the
368 specified window.
369 setWindowGravity GRAVITY
371 Set the window gravity for the specified window to GRAVITY. See
372 below for GRAVITY symbols.
373 getWindowGravity
375 Print the window gravity for the specified window.
376 setBitGravity GRAVITY
378 Set the bit gravity> for the specified window to GRAVITY. See
379 below for GRAVITY symbols.
380 getBitGravity
382 Print the bit gravity for the specified window.
383 motif [funcs FUNCTIONS | decor DECORATIONS | remove]
385 Query, set or modify the "_MOTIF_WM_HINTS" property for the
386 specified window. Without arguments motif will show the current
387 value, but only if the window has such a property. The property can
388 be removed or reset with the remove argument. With funcs and decor
389 individual fields of this property can be enabled or disabled. If
390 FUNCTIONS or DECORATIONS starts with a minus or plus sign then the
391 existing value is modified, otherwise it is set to the new value.
392 Note that if "All" is set, then other set fields will be disabled
393 and cleared fields will be enabled.
394 borderless
396 Hide the frame borders and title.
397 bordered
399 Show the frame borders and title.
400 denormal
402 Remove the WM_NORMAL_HINTS property, if it exists. This lifts
403 font-size restrictions on resizing, especially for terminals.
404 prop PROPERTY
406 Print the value of property PROPERTY if it is present.
407 properties
409 Print all properties.
410 frame
412 Print the identifier of the window frame.
413 click window-x window-y button
415 Send a button press and release event at position (window-x,
416 window-y). A negative position is relative to the bottom right
417 corner. The mouse pointer is warped to the position before sending
418 the events. The button number should be between 1 and 5 inclusive.
419 monitors top bottom left right
421 This sets the monitors to use for fullscreen. Top, bottom, left,
422 and right are indices of the icesh xinerama command.
423 spy Observe the selected windows and report any changes. This includes
425 focus, visibility, position, size and all window properties.
426 MANAGER ACTIONS
428 The following actions control the IceWM window manager and therefore do
429 not require a window select or filter option:
430 listWorkspaces
432 List the names of all workspaces.
433 current
435 Show the number and name of the current workspace.
436 goto WORKSPACE
438 Change the current workspace to WORKSPACE.
439 workspaces [COUNT]
441 Print the number of workspaces if COUNT is not given, otherwise set
442 the number of workspaces to COUNT.
443 setWorkspaceName INDEX NAME
445 Change the name of the workspace INDEX to NAME, where INDEX is a
446 workspace number starting from zero.
447 setWorkspaceNames NAME [NAME]*
449 Change the workspace names to the list of NAMEs.
450 addWorkspace NAME
452 Create a new workspace with name NAME.
453 desktop [SHOWING]
455 If SHOWING is 1 then set "showing the desktop" mode. If SHOWING is
456 0 then turn off "showing the desktop". Print the current mode if
457 SHOWING is not given.
458 randr
460 Summarize the RandR configuration.
461 xinerama
463 Summarize the Xinerama configuration.
464 check
466 Print information about the current window manager, like name,
467 version, class, locale, command, host name and pid.
468 clients
470 List all managed client windows, their titles and geometries.
471 shown
473 List all mapped client windows for the current desktop, their
474 titles and geometries.
475 windows
477 List all toplevel windows, their titles and geometries.
478 systray
480 List applications which are managed by the IceWM system tray.
481 xembed
483 List application windows which are embedded using the XEMBED
484 protocol. This is another way to discover system tray
485 applications.
486 logout
488 Let icewm execute the "LogoutCommand".
489 reboot
491 Let icewm execute the "RebootCommand".
492 shutdown
494 Let icewm execute the "ShutdownCommand".
495 cancel
497 Let icewm cancel the logout/reboot/shutdown.
498 about
500 Let icewm show the about window.
501 windowlist
503 Let icewm show the window list window.
504 restart
506 Let icewm restart itself.
507 suspend
509 Let icewm execute the "SuspendCommand".
510 winoptions
512 Let icewm reload the "winoptions".
513 keys
515 Let icewm reload the "keys" file.
516 guievents
518 Monitor the ICEWM_GUI_EVENT property and report all changes.
519 delay [time]
521 Stop execution for time or 0.1 seconds.
522 runonce program [arguments...]
524 This action is meant to be used together with the -class option.
525 Only if no window is matched by WM_CLASS then program
526 [arguments...] is executed.
527 sync
529 Synchronize with the IceWM window manager. That is, wait for icewm
530 to process all previous actions.
531 symbols
533 List all named symbols.
534 CONDITIONALS
536 Icesh supports "if-then-else" expressions. The full syntax is:
537 if selection
539 then
540 actions
541 elif selection
542 then
543 actions
544 else
545 actions
546 end
547 Where "selection" is a sequence of selection and filtering options,
549 which evaluates to true when it is non-empty. That is, if one or more
550 windows fulfilled the condition. If it is empty, then its "actions"
551 clause is ignored and the subsequent "elif" or "else" clause is tried
552 or taken. Each clause is optional. Even the "then" clause may be
553 omitted. Whenever a selection condition evaluates to false, the window
554 selection that existed before the "if" clause is immediately restored.
555 Note that the use of conditionals is seldom needed.
556 EXPRESSIONS
558 Some of the window actions require one or two EXPRESSION arguments.
559 EXPRESSION ::= SYMBOL | EXPRESSION { "+" | "|" } SYMBOL
561 Each SYMBOL may be from one of the following applicable domains:
563 Window layer
565 Named symbols of the domain Window layer (numeric range: 0-15):
566 Desktop (0)
568 Below (2)
569 Normal (4)
570 OnTop (6)
571 Dock (8)
572 AboveDock (10)
573 Menu (12)
574 These symbols are used with the LAYER argument to the "setLayer"
576 action.
577 IceWM tray option
579 Named symbols of the domain IceWM tray option (numeric range: 0-2):
580 Ignore (0)
582 Minimized (1)
583 Exclusive (2)
584 These symbols are used with the TRAYOPTION argument to the
586 "setTrayOption" action.
587 Gravity symbols
589 Named symbols for window and bit gravity (numeric range: 0-10):
590 ForgetGravity (0)
592 NorthWestGravity (1)
593 NorthGravity (2)
594 NorthEastGravity (3)
595 WestGravity (4)
596 CenterGravity (5)
597 EastGravity (6)
598 SouthWestGravity (7)
599 SouthGravity (8)
600 SouthEastGravity (9)
601 StaticGravity (10)
602 Motif functions
604 All (1)
605 Resize (2)
606 Move (4)
607 Minimize (8)
608 Maximize (16)
609 Close (32)
610 Motif decorations
612 All (1)
613 Border (2)
614 Resize (4)
615 Title (8)
616 Menu (16)
617 Minimize (32)
618 Maximize (64)
619 EWMH window state symbols
621 Named symbols of the domain EWMH state (numeric range: 0-8191):
622 ABOVE (1)
624 BELOW (2)
625 DEMANDS_ATTENTION (4)
626 FOCUSED (8)
627 FULLSCREEN (16)
628 HIDDEN (32)
629 MAXIMIZED_HORZ (64)
630 MAXIMIZED_VERT (128)
631 MODAL (256)
632 SHADED (512)
633 SKIP_PAGER (1024)
634 SKIP_TASKBAR (2048)
635 STICKY (4096)
636
638 List all workspace names:
639 icesh listWorkspaces
641 Example output:
643 workspace #0: `main'
645 workspace #1: `web'
646 workspace #2: `doc'
647 workspace #3: `dev'
648 Close terminal work and activate terminal fun.
650 icesh -c work.XTerm close -a -c fun.XTerm activate
652 Print opacity for all xterms.
654 icesh -c XTerm opacity
656 Change opacity for all xterms.
658 icesh -c XTerm opacity 84
660 Move all windows on workspace "Top" to the current workspace.
662 icesh -W "Top" setWorkspace "this"
664 Restore all hidden clients, minimize all clients on the current
666 workspace and activate Firefox.
667 icesh -S hidden restore -a -W "this" minimize -a -c Firefox activate
669 Resize the focused window to occupy the right half of the desktop area.
671 icesh -f sizeto 49% 100% sync top sync right sync raise activate
673 Toggle the frame border of the focused window.
675 if icesh -f motif | grep -q 'decor:$'; then \
677 icesh -f motif decor All; else icesh -f motif decor ""; fi
678 Here is a different solution using conditionals.
680 icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless
682
684 DISPLAY
685 The default display.
686
688 0 The last action completed successfully.
689 1 The last action completed unsuccessfully, or no window met the
691 condition.
692 2 A conditional has invalid syntax.
694 3 The display could not be opened.
696 4 The X server reports an error while processing a request.
698
700 icesh is largely compliant with the EWMH and ICCCM specifications.
701 Some commands, like manager actions, are specific to IceWM.
702
704 icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1).
705
707 icesh had no known bugs at the time of release. Please report bugs for
708 current versions to the source code repository at
709 <https://github.com/bbidulock/icewm/issues>.
710
712 Brian Bidulock <mailto:bidulock@openss7.org>.
713 See --copying for full copyright notice and copying permissions.
715
717 IceWM is licensed under the GNU Library General Public License. See
718 the COPYING file in the distribution or use the --copying flag to
719 display copying permissions.
720icewm 2.3.4 2021-05-10 ICESH(1)