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 that are managed by icewm.
19 2. Commands that 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 that 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 that 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 that 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 that belong to the
72 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 that are on the current workspace.
81 -t, -top
83 Selects all toplevel windows from the display unconditionally.
84 This includes windows that 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 that 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 that 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 that 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 that 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 that have at least an
167 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 that 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 that 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 that 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 that 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 that are managed by the IceWM system tray.
567 xembed
569 List application windows that 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 hibernate
598 Let icewm execute the "HibernateCommand".
599 winoptions
601 Let icewm reload the "winoptions".
602 keys
604 Let icewm reload the "keys" file.
605 refresh
607 Let icewm refresh the desktop background.
608 guievents
610 Monitor the ICEWM_GUI_EVENT property and report all changes. Hit
611 "Ctrl+C" to abort this and continue with the next command.
612 delay [time]
614 Stop execution for time or 0.1 seconds.
615 runonce program [arguments...]
617 This action is meant to be used together with the -class option.
618 Only if no window is matched by WM_CLASS then program
619 [arguments...] is executed.
620 loop [count]
622 Loop back to the beginning of the command and repeat. The optional
623 count limits the number of repetitions.
624 pick
626 Choose a window by a mouse button click.
627 sync
629 Synchronize with the IceWM window manager. That is, wait for icewm
630 to process all previous actions.
631 symbols
633 List all named symbols.
634 CONDITIONALS
636 Icesh supports "if-then-else" expressions. The full syntax is:
637 if selection
639 then
640 actions
641 elif selection
642 then
643 actions
644 else
645 actions
646 end
647 Where "selection" is a sequence of selection and filtering options,
649 which evaluates to true when it is non-empty. That is, if one or more
650 windows fulfilled the condition. If it is empty, then its "actions"
651 clause is ignored and the subsequent "elif" or "else" clause is tried
652 or taken. Each clause is optional.
653 Whenever a selection condition evaluates to false, the window selection
655 that existed before the "if" clause is immediately restored. This also
656 happens after an "end" clause.
657 EXPRESSIONS
659 Some of the window actions require one or two EXPRESSION arguments.
660 EXPRESSION ::= SYMBOL | EXPRESSION { "+" | "|" } SYMBOL
662 Each SYMBOL may be from one of the following applicable domains:
664 Window layer
666 Named symbols of the domain Window layer (numeric range: 0-15):
667 Desktop (0)
669 Below (2)
670 Normal (4)
671 OnTop (6)
672 Dock (8)
673 AboveDock (10)
674 Menu (12)
675 Fullscreen (14)
676 AboveAll (15)
677 These symbols are used with the LAYER argument to the "setLayer"
679 action.
680 IceWM tray option
682 Named symbols of the domain IceWM tray option (numeric range: 0-2):
683 Ignore (0)
685 Minimized (1)
686 Exclusive (2)
687 These symbols are used with the TRAYOPTION argument to the
689 "setTrayOption" action.
690 Gravity symbols
692 Named symbols for window and bit gravity (numeric range: 0-10):
693 ForgetGravity (0)
695 NorthWestGravity (1)
696 NorthGravity (2)
697 NorthEastGravity (3)
698 WestGravity (4)
699 CenterGravity (5)
700 EastGravity (6)
701 SouthWestGravity (7)
702 SouthGravity (8)
703 SouthEastGravity (9)
704 StaticGravity (10)
705 Motif functions
707 All (1)
708 Resize (2)
709 Move (4)
710 Minimize (8)
711 Maximize (16)
712 Close (32)
713 Motif decorations
715 All (1)
716 Border (2)
717 Resize (4)
718 Title (8)
719 Menu (16)
720 Minimize (32)
721 Maximize (64)
722 EWMH window state symbols
724 Named symbols of the domain EWMH state (numeric range: 0-8191):
725 ABOVE (1)
727 BELOW (2)
728 DEMANDS_ATTENTION (4)
729 FOCUSED (8)
730 FULLSCREEN (16)
731 HIDDEN (32)
732 MAXIMIZED_HORZ (64)
733 MAXIMIZED_VERT (128)
734 MODAL (256)
735 SHADED (512)
736 SKIP_PAGER (1024)
737 SKIP_TASKBAR (2048)
738 STICKY (4096)
739 EXAMPLES
741 List all workspace names:
742 icesh listWorkspaces
744 Example output:
746 workspace #0: `main'
748 workspace #1: `web'
749 workspace #2: `doc'
750 workspace #3: `dev'
751 Close terminal work and activate terminal fun.
753 icesh -c work.XTerm close -a -c fun.XTerm activate
755 Print opacity for all xterms.
757 icesh -c XTerm opacity
759 Change opacity for all xterms.
761 icesh -c XTerm opacity 84
763 Move all windows on workspace "Top" to the current workspace.
765 icesh -W "Top" setWorkspace "this"
767 Restore all hidden clients, minimize all clients on the current
769 workspace and activate Firefox.
770 icesh -N HIDDEN restore -a -W "this" minimize -a -c Firefox activate
772 Resize the focused window to occupy the right half of the desktop area.
774 icesh -f sizeto 49% 100% top right raise
776 Toggle the frame border of the focused window.
778 if icesh -f motif | grep -q 'decor:$'; then \
780 icesh -f motif decor All; else icesh -f motif decor ""; fi
781 Here is a different solution using conditionals.
783 icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless
785 Here is a conditional to either toggle the visibility of a roxterm that
787 has a WM_ROLE value of "special" or start it with runonce.
788 icesh if -c roxterm.Roxterm -R special then \
790 if -v then hide \
791 elif -u then setWorkspace this activate end \
792 else runonce roxterm --role=special
793 Collect all urxvt terminals from the fourth workspace in a single frame
795 on the current workspace.
796 icesh -W 3 -c urxvt tabto myfunnyname
798 Use the loop construct conditionally to wait for a certain window to
800 appear.
801 icesh -t if -n Tooltip then list else delay 0.05 loop end
803 ENVIRONMENT
805 DISPLAY
806 The default display.
807 EXIT STATUS
809 0 The last action completed successfully.
810 1 The last action completed unsuccessfully, or no window met the
812 condition.
813 2 A conditional has invalid syntax.
815 3 The display could not be opened.
817 4 The X server reports an error while processing a request.
819 COMPLIANCE
821 icesh is largely compliant with the EWMH and ICCCM specifications.
822 Some commands, like manager actions, are specific to IceWM.
823 SEE ALSO
825 icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1),
826 XParseGeometry(3).
827 BUGS
829 Please report bugs at <https://github.com/bbidulock/icewm/issues>.
830 AUTHOR
832 Brian Bidulock <mailto:bidulock@openss7.org>.
833 See --copying for full copyright notice and copying permissions.
835 LICENSE
837 IceWM is licensed under the GNU Library General Public License. See
838 the COPYING file in the distribution or use the --copying flag to
839 display copying permissions.
840icewm 3.4.4 2023-11-03 ICESH(1)