1ICESH(1)                         User Commands                        ICESH(1)
2
3
4
5   NAME
6        icesh - control window properties and the IceWM window manager
7
8   SYNOPSIS
9       icesh OPTIONS|ACTIONS+
10
11   DESCRIPTION
12       icesh provides two types of commands:
13
14       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
20       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
26           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
32           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
36           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
43       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
49   OPTIONS
50       icesh recognizes the following options:
51
52   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
58       The following options select one or more client windows.  If needed,
59       they can be repeated for successive actions.
60
61       -a, -all
62           Selects all client windows of the window manager.
63
64       -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
70       +g, +group
71           Extend the current selection with client windows which belong to
72           the same application window group.
73
74       -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
79       -s, -shown
80           Selects all client windows which are on the current workspace.
81
82       -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
87       -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
94       -x, -xembed
95           Selects all windows which are embedded using the XEMBED protocol.
96
97       +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
105       +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
109       -D, -Dockapps
110           Selects all Dockapp applications which are managed by icewm.
111
112       +P, +Pid
113           Extend the current selection with client windows that have the same
114           process identifier as one of the selected windows.
115
116       -T  Selects the IceWM taskbar.
117
118   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
123       -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
130       -l, -last
131           Filter clients and keep only the most recent client.
132
133       -m, -machine HOST
134           Filters clients by host name. Clients with a WM_CLIENT_MACHINE
135           property equal to HOST are selected.
136
137       -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
142       -p, -pid PID
143           Filters clients by process ID. Clients with a _NET_WM_PID property
144           equal to PID are selected.
145
146       -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
150       -v, -viewable
151           Filter clients and keep only those which are currently viewable.
152           These clients are mapped on the current workspace.
153
154       -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
160       -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
165       -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
172       -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
179       -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
184       -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
191       -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
198   GENERAL OPTIONS
199       The following options are identical for every IceWM command.
200
201       -d, -display DISPLAY
202           Specifies the X11 DISPLAY.  If unspecified, defaults to $DISPLAY.
203
204       -h, --help
205           Print a brief usage statement to stdout and exit.
206
207       -V, --version
208           Print the program version to stdout and exit.
209
210       -C, --copying
211           Print copying permissions to stdout for the program and exit.
212
213       -q, --quiet
214           Don't complain if no matching windows could be found.
215
216   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
222   WINDOW ACTIONS
223       The following actions affect the selected window or windows.
224
225       activate
226           Activate the window, aka. to focus.
227
228       close
229           Send a close request to the client that created the window.
230
231       kill
232           Force an immediate close down of the client that created the
233           window.
234
235       id  Print window identifiers for the selected windows.
236
237       pid Print process identifiers for the selected windows.
238
239       list
240           Show window details, like geometry and names.
241
242       lower
243           Lower the window.
244
245       raise
246           Raise the window.
247
248       above
249           Stack the window above others.
250
251       below
252           Stack the window below others.
253
254       rollup
255           Rollup the specified window.
256
257       fullscreen
258           Set the window to fullscreen.
259
260       maximize
261           Maximize the window.
262
263       horizontal
264           Maximize the window only horizontally.
265
266       vertical
267           Maximize the window only vertically.
268
269       minimize
270           Minimize the window.
271
272       restore
273           Restore the window to normal.
274
275       hide
276           Hide the window.
277
278       unhide
279           Reveal the window.
280
281       skip
282           Don't show the window on the taskbar.
283
284       unskip
285           Do show the window on the taskbar.
286
287       sticky
288           Show the window on all workspaces.
289
290       unsticky
291           Show the window on just one workspace.
292
293       urgent
294           Set the urgent flag to flash the task button.
295
296       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
301       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
308       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
314       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
320       moveby X Y
321           Displace window by X Y pixels.
322
323       center
324           Position the window in the center of the desktop work area.
325
326       left
327           Position the window against the left side of the desktop work area.
328
329       right
330           Position the window against the right side of the desktop work
331           area.
332
333       top Position the window against the top side of the desktop work area.
334
335       bottom
336           Position the window against the bottom side of the desktop work
337           area.
338
339       setIconTitle TITLE
340           Set the icon title to TITLE.
341
342       getIconTitle
343           Print the icon title.
344
345       setWindowTitle TITLE
346           Set the window title to TITLE.
347
348       getWindowTitle
349           Print the window title.
350
351       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
357       getGeometry
358           Print the window geometry.
359
360       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
370       setLayer LAYER
371           Move the specified window to another window layer.  See EXPRESSIONS
372           below for a list of LAYER symbols.
373
374       getLayer
375           Print the window layer for the specified window.
376
377       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
384       getWorkspace
385           Print the workspace for the specified window.
386
387       opacity [OPACITY]
388           Print the window opacity if OPACITY is not given, otherwise set the
389           window opacity to OPACITY.
390
391       setTrayOption TRAYOPTION
392           Set the IceWM tray option for the specified window to TRAYOPTION.
393           See IceWM tray options, below, for TRAYOPTION symbols.
394
395       getTrayOption
396           Print the IceWM tray option for the specified window.
397
398       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
402       getNormalGravity
403           Print the window gravity from the WM_NORMAL_HINTS property for the
404           specified window.
405
406       setWindowGravity GRAVITY
407           Set the window gravity for the specified window to GRAVITY.  See
408           below for GRAVITY symbols.
409
410       getWindowGravity
411           Print the window gravity for the specified window.
412
413       setBitGravity GRAVITY
414           Set the bit gravity> for the specified window to GRAVITY.  See
415           below for GRAVITY symbols.
416
417       getBitGravity
418           Print the bit gravity for the specified window.
419
420       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
431       borderless
432           Hide the frame borders and title.
433
434       bordered
435           Show the frame borders and title.
436
437       denormal
438           Remove the WM_NORMAL_HINTS property, if it exists.  This lifts
439           font-size restrictions on resizing, especially for terminals.
440
441       prop PROPERTY
442           Print the value of property PROPERTY, if it is present.
443
444       properties
445           Print all properties and their values.
446
447       frame
448           Print the identifier of the window frame.
449
450       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
456       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
460       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
465   MANAGER ACTIONS
466       The following actions control the IceWM window manager and therefore do
467       not require a window select or filter option:
468
469       listWorkspaces
470           List the names of all workspaces.
471
472       current
473           Show the number and name of the current workspace.
474
475       goto WORKSPACE
476           Change the current workspace to WORKSPACE. Specify "next" for the
477           subsequent workspace or "prev" for the preceding workspace.
478
479       workspaces [COUNT]
480           Print the number of workspaces if COUNT is not given, otherwise set
481           the number of workspaces to COUNT.
482
483       setWorkspaceName INDEX NAME
484           Change the name of the workspace INDEX to NAME, where INDEX is a
485           workspace number starting from zero.
486
487       setWorkspaceNames NAME [NAME]*
488           Change the workspace names to the list of NAMEs.
489
490       addWorkspace NAME
491           Create a new workspace with name NAME.
492
493       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
498       randr
499           Summarize the RandR configuration.
500
501       xinerama
502           Summarize the Xinerama configuration.
503
504       check
505           Print information about the current window manager, like name,
506           version, class, locale, command, host name and pid.
507
508       clients
509           List all managed client windows, their titles and geometries.
510
511       shown
512           List all mapped client windows for the current desktop, their
513           titles and geometries.
514
515       windows
516           List all toplevel windows, their titles and geometries.
517
518       systray
519           List applications which are managed by the IceWM system tray.
520
521       xembed
522           List application windows which are embedded using the XEMBED
523           protocol.  This is another way to discover system tray
524           applications.
525
526       logout
527           Let icewm execute the "LogoutCommand".
528
529       reboot
530           Let icewm execute the "RebootCommand".
531
532       shutdown
533           Let icewm execute the "ShutdownCommand".
534
535       cancel
536           Let icewm cancel the logout/reboot/shutdown.
537
538       about
539           Let icewm show the about window.
540
541       windowlist
542           Let icewm show the window list window.
543
544       restart
545           Let icewm restart itself.
546
547       suspend
548           Let icewm execute the "SuspendCommand".
549
550       winoptions
551           Let icewm reload the "winoptions".
552
553       keys
554           Let icewm reload the "keys" file.
555
556       guievents
557           Monitor the ICEWM_GUI_EVENT property and report all changes.
558
559       delay [time]
560           Stop execution for time or 0.1 seconds.
561
562       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
567       sync
568           Synchronize with the IceWM window manager. That is, wait for icewm
569           to process all previous actions.
570
571       symbols
572           List all named symbols.
573
574   CONDITIONALS
575       Icesh supports "if-then-else" expressions. The full syntax is:
576
577           if selection
578           then
579               actions
580           elif selection
581           then
582               actions
583           else
584               actions
585           end
586
587       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
593       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
597   EXPRESSIONS
598       Some of the window actions require one or two EXPRESSION arguments.
599
600       EXPRESSION ::= SYMBOL | EXPRESSION { "+" | "|" } SYMBOL
601
602       Each SYMBOL may be from one of the following applicable domains:
603
604       Window layer
605           Named symbols of the domain Window layer (numeric range: 0-15):
606
607               Desktop                (0)
608               Below                  (2)
609               Normal                 (4)
610               OnTop                  (6)
611               Dock                   (8)
612               AboveDock             (10)
613               Menu                  (12)
614
615           These symbols are used with the LAYER argument to the "setLayer"
616           action.
617
618       IceWM tray option
619           Named symbols of the domain IceWM tray option (numeric range: 0-2):
620
621               Ignore                 (0)
622               Minimized              (1)
623               Exclusive              (2)
624
625           These symbols are used with the TRAYOPTION argument to the
626           "setTrayOption" action.
627
628       Gravity symbols
629           Named symbols for window and bit gravity (numeric range: 0-10):
630
631               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
643       Motif functions
644               All                  (1)
645               Resize               (2)
646               Move                 (4)
647               Minimize             (8)
648               Maximize             (16)
649               Close                (32)
650
651       Motif decorations
652               All                  (1)
653               Border               (2)
654               Resize               (4)
655               Title                (8)
656               Menu                 (16)
657               Minimize             (32)
658               Maximize             (64)
659
660       EWMH window state symbols
661           Named symbols of the domain EWMH state (numeric range: 0-8191):
662
663               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
677   EXAMPLES
678       List all workspace names:
679
680           icesh listWorkspaces
681
682       Example output:
683
684           workspace #0: `main'
685           workspace #1: `web'
686           workspace #2: `doc'
687           workspace #3: `dev'
688
689       Close terminal work and activate terminal fun.
690
691           icesh -c work.XTerm close -a -c fun.XTerm activate
692
693       Print opacity for all xterms.
694
695           icesh -c XTerm opacity
696
697       Change opacity for all xterms.
698
699           icesh -c XTerm opacity 84
700
701       Move all windows on workspace "Top" to the current workspace.
702
703           icesh -W "Top" setWorkspace "this"
704
705       Restore all hidden clients, minimize all clients on the current
706       workspace and activate Firefox.
707
708           icesh -N HIDDEN restore -a -W "this" minimize -a -c Firefox activate
709
710       Resize the focused window to occupy the right half of the desktop area.
711
712           icesh -f sizeto 49% 100% sync top sync right sync raise activate
713
714       Toggle the frame border of the focused window.
715
716           if icesh -f motif | grep -q 'decor:$'; then \
717               icesh -f motif decor All; else icesh -f motif decor ""; fi
718
719       Here is a different solution using conditionals.
720
721           icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless
722
723       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
726           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
731   ENVIRONMENT
732       DISPLAY
733           The default display.
734
735   EXIT STATUS
736       0   The last action completed successfully.
737
738       1   The last action completed unsuccessfully, or no window met the
739           condition.
740
741       2   A conditional has invalid syntax.
742
743       3   The display could not be opened.
744
745       4   The X server reports an error while processing a request.
746
747   COMPLIANCE
748       icesh is largely compliant with the EWMH and ICCCM specifications.
749       Some commands, like manager actions, are specific to IceWM.
750
751   SEE ALSO
752       icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1),
753       XParseGeometry(3).
754
755   BUGS
756       Please report bugs at <https://github.com/bbidulock/icewm/issues>.
757
758   AUTHOR
759       Brian Bidulock <mailto:bidulock@openss7.org>.
760
761       See --copying for full copyright notice and copying permissions.
762
763   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.
767
768
769
770icewm 2.9.7                       2022-05-16                          ICESH(1)
Impressum