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 setClass CLASS
361 Set the resource name and class to CLASS, which should be a
362 resource name and a resource class connected by a dot. To preserve
363 either the existing name or class, use a percentage sign for that
364 part.
365 getClass
367 Print the resource name and class.
368 netState [STATE]
370 If STATE is omitted then it shows the EWMH window state. If STATE
371 starts with a "+" then flags in STATE are appended to the existing
372 EWMH window state. If STATE starts with a "-" then flags in STATE
373 are removed from the existing EWMH window state. If STATE starts
374 with a "^" then flags in STATE are toggled with respect to the
375 existing EWMH window state. If STATE starts with a "=" then the
376 EWMH window state is set to STATE. See EXPRESSIONS below. A list of
377 EWMH flags can be found in the output of "icesh symbols".
378 setLayer LAYER
380 Move the specified window to another window layer. See EXPRESSIONS
381 below for a list of LAYER symbols.
382 getLayer
384 Print the window layer for the specified window.
385 setWorkspace WORKSPACE
387 Move the specified window to another workspace. Select the root
388 window to change the current workspace. If WORKSPACE is "All" then
389 the specified window becomes visible on all workspaces. Specify
390 "this" for the current workspace, "next" for the subsequent
391 workspace or "prev" for the preceding workspace.
392 getWorkspace
394 Print the workspace for the specified window.
395 opacity [OPACITY]
397 Print the window opacity if OPACITY is not given, otherwise set the
398 window opacity to OPACITY.
399 setTrayOption TRAYOPTION
401 Set the IceWM tray option for the specified window to TRAYOPTION.
402 See IceWM tray options, below, for TRAYOPTION symbols.
403 getTrayOption
405 Print the IceWM tray option for the specified window.
406 setNormalGravity GRAVITY
408 Set the window gravity field in the WM_NORMAL_HINTS property for
409 the specified window to GRAVITY. See below for GRAVITY symbols.
410 getNormalGravity
412 Print the window gravity from the WM_NORMAL_HINTS property for the
413 specified window.
414 setWindowGravity GRAVITY
416 Set the window gravity for the specified window to GRAVITY. See
417 below for GRAVITY symbols.
418 getWindowGravity
420 Print the window gravity for the specified window.
421 setBitGravity GRAVITY
423 Set the bit gravity> for the specified window to GRAVITY. See
424 below for GRAVITY symbols.
425 getBitGravity
427 Print the bit gravity for the specified window.
428 motif [funcs FUNCTIONS | decor DECORATIONS | remove]
430 Query, set or modify the "_MOTIF_WM_HINTS" property for the
431 specified window. Without arguments motif will show the current
432 value, but only if the window has such a property. The property can
433 be removed or reset with the remove argument. With funcs and decor
434 individual fields of this property can be enabled or disabled. If
435 FUNCTIONS or DECORATIONS starts with a minus or plus sign then the
436 existing value is modified, otherwise it is set to the new value.
437 Note that if "All" is set, other set fields are disabled and
438 cleared fields are enabled.
439 borderless
441 Hide the frame borders and title.
442 bordered
444 Show the frame borders and title.
445 denormal
447 Remove the WM_NORMAL_HINTS property, if it exists. This lifts
448 font-size restrictions on resizing, especially for terminals.
449 prop PROPERTY
451 Print the value of property PROPERTY, if it is present.
452 properties
454 Print all properties and their values.
455 frame
457 Print the identifier of the window frame.
458 extents
460 Print the window identifier and the frame border sizes: left,
461 right, top and bottom.
462 focusmodel
464 Print the ICCCM focus model as advertised by the client window.
465 This is either Locally, Passive, Globally or NoInput.
466 override [0|1]
468 Print the override redirect status for the window, or if either 0
469 or 1 is given, then disable or enable the override redirect status.
470 tabto label
472 Move the windows as tabs to a frame which has "frame" label label.
473 Such a frame is created if needed.
474 untab
476 Move each window to its own frame, if it is currently tabbed.
477 loadicon image.pam
479 Load an icon from file, which must be in the PAM image format, with
480 dimensions at most 256, a depth of 4, and type RGB_ALPHA.
481 saveicon file000.pam
483 Save an icon to a new file in the PAM image format. Digits are
484 increased to generate a unique new filename for each window.
485 click window-x window-y button
487 Send a button press and release event at position (window-x,
488 window-y). A negative position is relative to the bottom right
489 corner. The mouse pointer is warped to the position before sending
490 the events. The button number should be between 1 and 5 inclusive.
491 monitors top bottom left right
493 This sets the monitors to use for fullscreen. Top, bottom, left,
494 and right are indices of the icesh xinerama command.
495 spy Observe the selected windows and report any changes. This includes
497 focus, visibility, position, size and all window properties. To
498 monitor all of the protocol request messages that client
499 applications may send to icewm, also spy on the root window.
500 stacking
502 Sort the list of windows from topmost to bottom-most.
503 reverse
505 Reverse the order of the list of windows.
506 MANAGER ACTIONS
508 The following actions control the IceWM window manager and therefore do
509 not require a window select or filter option:
510 listWorkspaces
512 List the names of all workspaces.
513 current
515 Show the number and name of the current workspace.
516 goto WORKSPACE
518 Change the current workspace to WORKSPACE. Specify "next" for the
519 subsequent workspace or "prev" for the preceding workspace.
520 workspaces [COUNT]
522 Print the number of workspaces if COUNT is not given, otherwise set
523 the number of workspaces to COUNT.
524 setWorkspaceName INDEX NAME
526 Change the name of the workspace INDEX to NAME, where INDEX is a
527 workspace number starting from zero.
528 setWorkspaceNames NAME [NAME]*
530 Change the workspace names to the list of NAMEs.
531 addWorkspace NAME
533 Create a new workspace with name NAME.
534 desktop [SHOWING]
536 If SHOWING is 1 then set "showing the desktop" mode. If SHOWING is
537 0 then turn off "showing the desktop". Print the current mode if
538 SHOWING is not given.
539 workarea
541 Print the dimensions of the work area for the current workspace.
542 This is the desktop, but minus space occupied by dock and panel
543 windows.
544 randr
546 Summarize the RandR configuration.
547 xinerama
549 Summarize the Xinerama configuration.
550 check
552 Print information about the current window manager, like name,
553 version, class, locale, command, host name and pid.
554 clients
556 List all managed client windows, their titles and geometries.
557 shown
559 List all mapped client windows for the current desktop, their
560 titles and geometries.
561 windows
563 List all toplevel windows, their titles and geometries.
564 systray
566 List applications which are managed by the IceWM system tray.
567 xembed
569 List application windows which are embedded using the XEMBED
570 protocol. This is another way to discover system tray
571 applications.
572 logout
574 Let icewm execute the "LogoutCommand".
575 reboot
577 Let icewm execute the "RebootCommand".
578 shutdown
580 Let icewm execute the "ShutdownCommand".
581 cancel
583 Let icewm cancel the logout/reboot/shutdown.
584 about
586 Let icewm show the about window.
587 windowlist
589 Let icewm show the window list window.
590 restart
592 Let icewm restart itself.
593 suspend
595 Let icewm execute the "SuspendCommand".
596 winoptions
598 Let icewm reload the "winoptions".
599 keys
601 Let icewm reload the "keys" file.
602 guievents
604 Monitor the ICEWM_GUI_EVENT property and report all changes.
605 delay [time]
607 Stop execution for time or 0.1 seconds.
608 runonce program [arguments...]
610 This action is meant to be used together with the -class option.
611 Only if no window is matched by WM_CLASS then program
612 [arguments...] is executed.
613 sync
615 Synchronize with the IceWM window manager. That is, wait for icewm
616 to process all previous actions.
617 symbols
619 List all named symbols.
620 CONDITIONALS
622 Icesh supports "if-then-else" expressions. The full syntax is:
623 if selection
625 then
626 actions
627 elif selection
628 then
629 actions
630 else
631 actions
632 end
633 Where "selection" is a sequence of selection and filtering options,
635 which evaluates to true when it is non-empty. That is, if one or more
636 windows fulfilled the condition. If it is empty, then its "actions"
637 clause is ignored and the subsequent "elif" or "else" clause is tried
638 or taken. Each clause is optional.
639 Whenever a selection condition evaluates to false, the window selection
641 that existed before the "if" clause is immediately restored. This also
642 happens after an "end" clause.
643 EXPRESSIONS
645 Some of the window actions require one or two EXPRESSION arguments.
646 EXPRESSION ::= SYMBOL | EXPRESSION { "+" | "|" } SYMBOL
648 Each SYMBOL may be from one of the following applicable domains:
650 Window layer
652 Named symbols of the domain Window layer (numeric range: 0-15):
653 Desktop (0)
655 Below (2)
656 Normal (4)
657 OnTop (6)
658 Dock (8)
659 AboveDock (10)
660 Menu (12)
661 These symbols are used with the LAYER argument to the "setLayer"
663 action.
664 IceWM tray option
666 Named symbols of the domain IceWM tray option (numeric range: 0-2):
667 Ignore (0)
669 Minimized (1)
670 Exclusive (2)
671 These symbols are used with the TRAYOPTION argument to the
673 "setTrayOption" action.
674 Gravity symbols
676 Named symbols for window and bit gravity (numeric range: 0-10):
677 ForgetGravity (0)
679 NorthWestGravity (1)
680 NorthGravity (2)
681 NorthEastGravity (3)
682 WestGravity (4)
683 CenterGravity (5)
684 EastGravity (6)
685 SouthWestGravity (7)
686 SouthGravity (8)
687 SouthEastGravity (9)
688 StaticGravity (10)
689 Motif functions
691 All (1)
692 Resize (2)
693 Move (4)
694 Minimize (8)
695 Maximize (16)
696 Close (32)
697 Motif decorations
699 All (1)
700 Border (2)
701 Resize (4)
702 Title (8)
703 Menu (16)
704 Minimize (32)
705 Maximize (64)
706 EWMH window state symbols
708 Named symbols of the domain EWMH state (numeric range: 0-8191):
709 ABOVE (1)
711 BELOW (2)
712 DEMANDS_ATTENTION (4)
713 FOCUSED (8)
714 FULLSCREEN (16)
715 HIDDEN (32)
716 MAXIMIZED_HORZ (64)
717 MAXIMIZED_VERT (128)
718 MODAL (256)
719 SHADED (512)
720 SKIP_PAGER (1024)
721 SKIP_TASKBAR (2048)
722 STICKY (4096)
723 EXAMPLES
725 List all workspace names:
726 icesh listWorkspaces
728 Example output:
730 workspace #0: `main'
732 workspace #1: `web'
733 workspace #2: `doc'
734 workspace #3: `dev'
735 Close terminal work and activate terminal fun.
737 icesh -c work.XTerm close -a -c fun.XTerm activate
739 Print opacity for all xterms.
741 icesh -c XTerm opacity
743 Change opacity for all xterms.
745 icesh -c XTerm opacity 84
747 Move all windows on workspace "Top" to the current workspace.
749 icesh -W "Top" setWorkspace "this"
751 Restore all hidden clients, minimize all clients on the current
753 workspace and activate Firefox.
754 icesh -N HIDDEN restore -a -W "this" minimize -a -c Firefox activate
756 Resize the focused window to occupy the right half of the desktop area.
758 icesh -f sizeto 49% 100% top right raise
760 Toggle the frame border of the focused window.
762 if icesh -f motif | grep -q 'decor:$'; then \
764 icesh -f motif decor All; else icesh -f motif decor ""; fi
765 Here is a different solution using conditionals.
767 icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless
769 Here is a conditional to either toggle the visibility of a roxterm,
771 which has a WM_ROLE value of "special", or start it with runonce.
772 icesh if -c roxterm.Roxterm -R special then \
774 if -v then hide \
775 elif -u then setWorkspace this activate end \
776 else runonce roxterm --role=special
777 Collect all urxvt terminals from the fourth workspace in a single frame
779 on the current workspace.
780 icesh -W 3 -c urxvt tabto myfunnyname
782 ENVIRONMENT
784 DISPLAY
785 The default display.
786 EXIT STATUS
788 0 The last action completed successfully.
789 1 The last action completed unsuccessfully, or no window met the
791 condition.
792 2 A conditional has invalid syntax.
794 3 The display could not be opened.
796 4 The X server reports an error while processing a request.
798 COMPLIANCE
800 icesh is largely compliant with the EWMH and ICCCM specifications.
801 Some commands, like manager actions, are specific to IceWM.
802 SEE ALSO
804 icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1),
805 XParseGeometry(3).
806 BUGS
808 Please report bugs at <https://github.com/bbidulock/icewm/issues>.
809 AUTHOR
811 Brian Bidulock <mailto:bidulock@openss7.org>.
812 See --copying for full copyright notice and copying permissions.
814 LICENSE
816 IceWM is licensed under the GNU Library General Public License. See
817 the COPYING file in the distribution or use the --copying flag to
818 display copying permissions.
819icewm 3.3.1 2023-01-24 ICESH(1)