1ICESH(1)                         User Commands                        ICESH(1)
2
3
4

NAME

6        icesh - control window properties and the IceWM window manager
7

SYNOPSIS

9       icesh OPTIONS|ACTIONS+
10

DESCRIPTION

12       icesh provides commands to directly interact with the icewm(1) window
13       manager.  There are two types of commands:
14
15       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
21       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
27           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
33           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
38           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
45       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

OPTIONS

52       icesh recognizes the following options:
53
54   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
60       The following five options select one or more client windows.  If
61       needed, they can be repeated for successive actions.
62
63       -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
70       -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
76       -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
82       -a, -all
83           Selects all client windows of the window manager.
84
85       -s, -shown
86           Selects all clients which are on the current workspace.
87
88       -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
93       -x, -xembed
94           Selects all windows which are embedded using the XEMBED protocol.
95
96   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
101       -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
108       -l, -last
109           Filter clients and keep only the most recent client.
110
111       -m, -machine HOST
112           Filters clients by host name. Clients with a WM_CLIENT_MACHINE
113           property equal to HOST are selected.
114
115       -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
120       -p, -pid PID
121           Filters clients by process ID. Clients with a _NET_WM_PID property
122           equal to PID are selected.
123
124       -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
130       -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
135       -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
142       -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
149       -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
154       -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
161       -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
168   GENERAL OPTIONS
169       The following options are identical for every IceWM command.
170
171       -d, -display DISPLAY
172           Specifies the X11 DISPLAY.  If unspecified, defaults to $DISPLAY.
173
174       -h, --help
175           Print a brief usage statement to stdout and exit.
176
177       -V, --version
178           Print the program version to stdout and exit.
179
180       -C, --copying
181           Print copying permissions to stdout for the program and exit.
182
183       -q, --quiet
184           Don't complain if no matching windows could be found.
185

ACTIONS

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
192   WINDOW ACTIONS
193       The following actions affect the selected window or windows.
194
195       activate
196           Activate the window, aka. to focus.
197
198       close
199           Send a close request to the client that created the window.
200
201       kill
202           Force an immediate close down of the client that created the
203           window.
204
205       id  Print window identifiers for the selected windows.
206
207       pid Print process identifiers for the selected windows.
208
209       list
210           Show window details, like geometry and names.
211
212       lower
213           Lower the window.
214
215       raise
216           Raise the window.
217
218       above
219           Stack the window above others.
220
221       below
222           Stack the window below others.
223
224       rollup
225           Rollup the specified window.
226
227       fullscreen
228           Set the window to fullscreen.
229
230       maximize
231           Maximize the window.
232
233       horizontal
234           Maximize the window only horizontally.
235
236       vertical
237           Maximize the window only vertically.
238
239       minimize
240           Minimize the window.
241
242       restore
243           Restore the window to normal.
244
245       hide
246           Hide the window.
247
248       unhide
249           Reveal the window.
250
251       skip
252           Don't show the window on the taskbar.
253
254       unskip
255           Do show the window on the taskbar.
256
257       sticky
258           Show the window on all workspaces.
259
260       unsticky
261           Show the window on only one workspace.
262
263       urgent
264           Set the urgent flag.
265
266       resize WIDTH HEIGHT
267           Resize window to WIDTH by HEIGHT window units.
268
269       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
276       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
282       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
288       moveby X Y
289           Displace window by X Y pixels.
290
291       center
292           Position the window in the center of the desktop work area.
293
294       left
295           Position the window against the left side of the desktop work area.
296
297       right
298           Position the window against the right side of the desktop work
299           area.
300
301       top Position the window against the top side of the desktop work area.
302
303       bottom
304           Position the window against the bottom side of the desktop work
305           area.
306
307       setIconTitle TITLE
308           Set the icon title to TITLE.
309
310       getIconTitle
311           Print the icon title.
312
313       setWindowTitle TITLE
314           Set the window title to TITLE.
315
316       getWindowTitle
317           Print the window title.
318
319       setGeometry GEOMETRY
320           Set the window geometry to GEOMETRY.
321
322       getGeometry
323           Print the window geometry.
324
325       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
335       setLayer LAYER
336           Move the specified window to another GNOME window layer.  See below
337           for LAYER symbols.
338
339       getLayer
340           Print the GNOME window layer for the specified window.
341
342       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
348       getWorkspace
349           Print the workspace for the specified window.
350
351       opacity [OPACITY]
352           Print the window opacity if OPACITY is not given, otherwise set the
353           window opacity to OPACITY.
354
355       setTrayOption TRAYOPTION
356           Set the IceWM tray option for the specified window to TRAYOPTION.
357           See IceWM tray options, below, for TRAYOPTION symbols.
358
359       getTrayOption
360           Print the IceWM tray option for the specified window.
361
362       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
366       getNormalGravity
367           Print the window gravity from the WM_NORMAL_HINTS property for the
368           specified window.
369
370       setWindowGravity GRAVITY
371           Set the window gravity for the specified window to GRAVITY.  See
372           below for GRAVITY symbols.
373
374       getWindowGravity
375           Print the window gravity for the specified window.
376
377       setBitGravity GRAVITY
378           Set the bit gravity> for the specified window to GRAVITY.  See
379           below for GRAVITY symbols.
380
381       getBitGravity
382           Print the bit gravity for the specified window.
383
384       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
395       borderless
396           Hide the frame borders and title.
397
398       bordered
399           Show the frame borders and title.
400
401       denormal
402           Remove the WM_NORMAL_HINTS property, if it exists.  This lifts
403           font-size restrictions on resizing, especially for terminals.
404
405       prop PROPERTY
406           Print the value of property PROPERTY if it is present.
407
408       properties
409           Print all properties.
410
411       frame
412           Print the identifier of the window frame.
413
414       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
420       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
424       spy Observe the selected windows and report any changes. This includes
425           focus, visibility, position, size and all window properties.
426
427   MANAGER ACTIONS
428       The following actions control the IceWM window manager and therefore do
429       not require a window select or filter option:
430
431       listWorkspaces
432           List the names of all workspaces.
433
434       current
435           Show the number and name of the current workspace.
436
437       goto WORKSPACE
438           Change the current workspace to WORKSPACE.
439
440       workspaces [COUNT]
441           Print the number of workspaces if COUNT is not given, otherwise set
442           the number of workspaces to COUNT.
443
444       setWorkspaceName INDEX NAME
445           Change the name of the workspace INDEX to NAME, where INDEX is a
446           workspace number starting from zero.
447
448       setWorkspaceNames NAME [NAME]*
449           Change the workspace names to the list of NAMEs.
450
451       addWorkspace NAME
452           Create a new workspace with name NAME.
453
454       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
459       randr
460           Summarize the RandR configuration.
461
462       xinerama
463           Summarize the Xinerama configuration.
464
465       check
466           Print information about the current window manager, like name,
467           version, class, locale, command, host name and pid.
468
469       clients
470           List all managed client windows, their titles and geometries.
471
472       shown
473           List all mapped client windows for the current desktop, their
474           titles and geometries.
475
476       windows
477           List all toplevel windows, their titles and geometries.
478
479       systray
480           List applications which are managed by the IceWM system tray.
481
482       xembed
483           List application windows which are embedded using the XEMBED
484           protocol.  This is another way to discover system tray
485           applications.
486
487       logout
488           Let icewm execute the "LogoutCommand".
489
490       reboot
491           Let icewm execute the "RebootCommand".
492
493       shutdown
494           Let icewm execute the "ShutdownCommand".
495
496       cancel
497           Let icewm cancel the logout/reboot/shutdown.
498
499       about
500           Let icewm show the about window.
501
502       windowlist
503           Let icewm show the window list window.
504
505       restart
506           Let icewm restart itself.
507
508       suspend
509           Let icewm execute the "SuspendCommand".
510
511       winoptions
512           Let icewm reload the "winoptions".
513
514       keys
515           Let icewm reload the "keys" file.
516
517       guievents
518           Monitor the ICEWM_GUI_EVENT property and report all changes.
519
520       delay [time]
521           Stop execution for time or 0.1 seconds.
522
523       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
528       sync
529           Synchronize with the IceWM window manager. That is, wait for icewm
530           to process all previous actions.
531
532       symbols
533           List all named symbols.
534
535   CONDITIONALS
536       Icesh supports "if-then-else" expressions. The full syntax is:
537
538           if selection
539           then
540               actions
541           elif selection
542           then
543               actions
544           else
545               actions
546           end
547
548       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
557   EXPRESSIONS
558       Some of the window actions require one or two EXPRESSION arguments.
559
560       EXPRESSION ::= SYMBOL | EXPRESSION { "+" | "|" } SYMBOL
561
562       Each SYMBOL may be from one of the following applicable domains:
563
564       Window layer
565           Named symbols of the domain Window layer (numeric range: 0-15):
566
567               Desktop                (0)
568               Below                  (2)
569               Normal                 (4)
570               OnTop                  (6)
571               Dock                   (8)
572               AboveDock             (10)
573               Menu                  (12)
574
575           These symbols are used with the LAYER argument to the "setLayer"
576           action.
577
578       IceWM tray option
579           Named symbols of the domain IceWM tray option (numeric range: 0-2):
580
581               Ignore                 (0)
582               Minimized              (1)
583               Exclusive              (2)
584
585           These symbols are used with the TRAYOPTION argument to the
586           "setTrayOption" action.
587
588       Gravity symbols
589           Named symbols for window and bit gravity (numeric range: 0-10):
590
591               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
603       Motif functions
604               All                  (1)
605               Resize               (2)
606               Move                 (4)
607               Minimize             (8)
608               Maximize             (16)
609               Close                (32)
610
611       Motif decorations
612               All                  (1)
613               Border               (2)
614               Resize               (4)
615               Title                (8)
616               Menu                 (16)
617               Minimize             (32)
618               Maximize             (64)
619
620       EWMH window state symbols
621           Named symbols of the domain EWMH state (numeric range: 0-8191):
622
623               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

EXAMPLES

638       List all workspace names:
639
640           icesh listWorkspaces
641
642       Example output:
643
644           workspace #0: `main'
645           workspace #1: `web'
646           workspace #2: `doc'
647           workspace #3: `dev'
648
649       Close terminal work and activate terminal fun.
650
651           icesh -c work.XTerm close -a -c fun.XTerm activate
652
653       Print opacity for all xterms.
654
655           icesh -c XTerm opacity
656
657       Change opacity for all xterms.
658
659           icesh -c XTerm opacity 84
660
661       Move all windows on workspace "Top" to the current workspace.
662
663           icesh -W "Top" setWorkspace "this"
664
665       Restore all hidden clients, minimize all clients on the current
666       workspace and activate Firefox.
667
668           icesh -S hidden restore -a -W "this" minimize -a -c Firefox activate
669
670       Resize the focused window to occupy the right half of the desktop area.
671
672           icesh -f sizeto 49% 100% sync top sync right sync raise activate
673
674       Toggle the frame border of the focused window.
675
676           if icesh -f motif | grep -q 'decor:$'; then \
677               icesh -f motif decor All; else icesh -f motif decor ""; fi
678
679       Here is a different solution using conditionals.
680
681           icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless
682

ENVIRONMENT

684       DISPLAY
685           The default display.
686

EXIT STATUS

688       0   The last action completed successfully.
689
690       1   The last action completed unsuccessfully, or no window met the
691           condition.
692
693       2   A conditional has invalid syntax.
694
695       3   The display could not be opened.
696
697       4   The X server reports an error while processing a request.
698

COMPLIANCE

700       icesh is largely compliant with the EWMH and ICCCM specifications.
701       Some commands, like manager actions, are specific to IceWM.
702

SEE ALSO

704       icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1).
705

BUGS

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

AUTHOR

712       Brian Bidulock <mailto:bidulock@openss7.org>.
713
714       See --copying for full copyright notice and copying permissions.
715

LICENSE

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.
720
721
722
723icewm 2.3.4                       2021-05-10                          ICESH(1)
Impressum