Skip to content

Latest commit

 

History

History
1042 lines (645 loc) · 28.3 KB

icesh.md

File metadata and controls

1042 lines (645 loc) · 28.3 KB
title
icesh(1)

NAME

icesh - control window properties and the IceWM window manager

SYNOPSIS

  • icesh OPTIONS|ACTIONS+

DESCRIPTION

icesh provides two types of commands:

  1. Commands to directly interact with icewm:

    These are listed in the section "MANAGER ACTIONS" below. They are easy to use, because they don't require to select one or more windows. For example, icesh restart will restart icewm and icesh clients lists the applications that are managed by icewm.

  2. Commands that operate on a selection of windows:

    See the section WINDOW ACTIONS below. For example, icesh close is a request to close a window, but which window? Now icesh will turn the mouse pointer into a crosshair. Click on a window and a close request will be sent to that application.

    The power of icesh lies in its ability to programmatically select one or more windows and operate on that selection. This can be used in scripts and in icewm-keys(5) to define your own window management hotkeys. For example, to immediately close all xterm windows do icesh -c xterm close.

    There are a dozen SELECT OPTIONS to select windows. They start with a '-' or a '+'. The '-' starts a new selection, while the '+' adds more windows to an existing selection.

    This selection of windows can be reduced by FILTER OPTIONS. These remove unwanted windows from the current selection. Multiple filter options can be given. For example, icesh -c xterm -W this close will close only those xterms that are shown on the current workspace. The xterms on other workspaces are filtered out by the -W this filter option.

There is no limit to the number of commands, selections, filters and actions that you can give to a single icesh command. They are processed and evaluated one by one from left to right. This makes icesh a small declarative programming language. Have a look at some examples near the end of this document.

OPTIONS

icesh recognizes the following options:

SELECT OPTIONS

Select options specify the window or windows to which subsequent actions apply. If none is given, but an action does require a window, then a selection crosshair is shown to select the desired window interactively. The manager actions do not require window options.

The following options select one or more client windows. If needed, they can be repeated for successive actions.

  • -a, -all

    Selects all client windows of the window manager.

  • -f, -focus, +f, +focus

    Selects the application window that is currently focused. The option with minus sign replaces the existing selection with the focused window. With a plus sign the focused window is added to an existing selection.

  • +g, +group

    Extend the current selection with client windows that belong to the same application window group.

  • -r, -root, +r, +root

    Selects the root window. The option with minus sign replaces the existing selection with the root window. With a plus sign the root window is added to an existing selection.

  • -s, -shown

    Selects all client windows that are on the current workspace.

  • -t, -top

    Selects all toplevel windows from the display unconditionally. This includes windows that have never been mapped and windows with the override redirect bit set to evade management.

  • -w, -window, +w, +window WINDOW_ID

    Specifies the identifier of the window, WINDOW_ID, for which the action applies. Special identifiers are root for the root window and focus for the currently focused window. The option with minus sign replaces the existing selection. With a plus sign the window is added to an existing selection.

  • -x, -xembed

    Selects all windows that are embedded using the XEMBED protocol.

  • +c, +class CLASS

    Extend the current selection with client windows that have a WM_CLASS property equal to CLASS. This is the resource instance and class name. If CLASS contains a period, only windows with exactly the same WM_CLASS property are matched. If there is no period, windows of the same class and windows of the same instance are selected.

  • +C, +Class

    Extend the current selection with client windows that have a WM_CLASS property similar to the already selected set of windows.

  • -D, -Dockapps

    Selects all Dockapp applications that are managed by icewm.

  • +P, +Pid

    Extend the current selection with client windows that have the same process identifier as one of the selected windows.

  • -T

    Selects the IceWM taskbar.

  • -A, -Await

    Wait for one or more new client windows to appear and make that the new selection.

FILTER OPTIONS

The following options filter the currently selected set of windows. If no previous select option was given then a -all option is implicitly assumed to filter all client windows.

  • -c, -class CLASS

    Filters the set of windows on their WM_CLASS property. This is the resource instance and class name. If CLASS contains a period, only windows with exactly the same WM_CLASS property are matched. If there is no period, windows of the same class and windows of the same instance (aka. -name) are selected.

  • -l, -last

    Filter clients and keep only the most recent client.

  • -m, -machine HOST

    Filters clients by host name. Clients with a WM_CLIENT_MACHINE property equal to HOST are selected.

  • -n, -name NAME

    Filters clients by _NET_WM_NAME or WM_NAME. NAME matches any part of the property value. To match at the beginning use a ^ prefix. To match at the end use a $ suffix.

  • -p, -pid PID

    Filters clients by process ID. Clients with a _NET_WM_PID property equal to PID are selected.

  • -u, -unmapped

    Filter clients and keep those that are currently not viewable. These are hidden, minimized, rolled-up, or on another workspace.

  • -v, -viewable

    Filter clients and keep only those that are currently viewable. These clients are mapped on the current workspace.

  • -G, -Gravity GRAVITY

    Filters clients by the window gravity field of the WM_NORMAL_HINTS property. Clients with a gravity equal to GRAVITY are selected. If GRAVITY starts with an exclamation mark then the filtering is inverted.

  • -L, -Layer LAYER

    Filters clients by GNOME window layer, which can either be a layer name or a layer number. See EXPRESSIONS below. If LAYER starts with an exclamation mark then the filtering is inverted.

  • -N, -Netstate STATE

    Filters clients by EWMH window state. Clients that have at least an EWMH window state of STATE are selected. This state refers to details like MINIZED or MAXIMIZED. See EXPRESSIONS below. If STATE starts with an exclamation mark then the filtering is inverted. A question mark ? filters clients with any bit set in STATE.

  • -P, -Property PROP[=value]

    Filters clients by property. Clients that have a property PROP are selected. If the optional value is given, the match succeeds only if PROP is a string, window, cardinal, or atom, with a value equal to value. The filtering is inverted if PROP starts with an exclamation mark.

  • -R, -Role ROLE

    Filters clients by WM_WINDOW_ROLE. Clients that have a WM_WINDOW_ROLE property value equal to ROLE are selected. The filtering is inverted if ROLE starts with an exclamation mark.

  • -W, -Workspace WORKSPACE

    Filter clients by workspace. Workspace WORKSPACE is either a workspace name, or a workspace number counting from zero, or the word this for the current workspace, or the word All for all workspaces. If WORKSPACE starts with an exclamation mark then the filtering is inverted.

  • -X, -Xinerama MONITOR

    Limit clients by RandR/Xinerama monitor. Only operate on clients that are displayed on MONITOR, where MONITOR can be All for all monitors, this for the monitor where the active window is displayed, or a monitor number starting from zero. See the output of randr or xinerama below.

GENERAL OPTIONS

The following options are identical for every IceWM command.

  • -d, -display DISPLAY

    Specifies the X11 DISPLAY. If unspecified, defaults to $DISPLAY.

  • -h, --help

    Print a brief usage statement to stdout and exit.

  • -V, --version

    Print the program version to stdout and exit.

  • -C, --copying

    Print copying permissions to stdout for the program and exit.

  • -q, --quiet

    Don't complain if no matching windows could be found.

ACTIONS

icesh expects one or more action arguments. There are two kinds of actions: window actions and manager actions. The first operates on the selected windows. The second directly interacts with the icewm window manager.

WINDOW ACTIONS

The following actions affect the selected window or windows.

  • activate

    Activate the window, aka. to focus.

  • close

    Send a close request to the client that created the window.

  • kill

    Force an immediate close down of the client that created the window.

  • id

    Print window identifiers for the selected windows.

  • pid

    Print process identifiers for the selected windows.

  • list

    Show window details, like geometry and names.

  • lower

    Lower the window.

  • raise

    Raise the window.

  • above

    Stack the window above others.

  • below

    Stack the window below others.

  • rollup

    Rollup the specified window.

  • fullscreen

    Set the window to fullscreen.

  • maximize

    Maximize the window.

  • horizontal

    Maximize the window only horizontally.

  • vertical

    Maximize the window only vertically.

  • minimize

    Minimize the window.

  • restore

    Restore the window to normal and clear urgency.

  • hide

    Hide the window.

  • unhide

    Reveal the window.

  • skip

    Don't show the window on the taskbar.

  • unskip

    Do show the window on the taskbar.

  • sticky

    Show the window on all workspaces.

  • unsticky

    Show the window on just one workspace.

  • urgent

    Set the urgency flag to flash the task button.

  • resize WIDTH HEIGHT

    Resize window to WIDTH by HEIGHT window units. For text based applications like terminals, a window unit is the size of a single character cell.

  • sizeto WIDTH HEIGHT

    Resize window to WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends with a percent sign %, then they refer to a percentage of the desktop work area. For instance, sizeto 50% 100% resizes to half the desktop width and whatever height is available above or below the taskbar.

  • sizeby WIDTH HEIGHT

    Resize window by WIDTH by HEIGHT pixels. If WIDTH or HEIGHT ends with a percent sign %, then they refer to a percentage of the current window size. For instance, sizeby 50% 200 increases the width by 50% and increases the height by 200 pixels.

  • move X Y

    Move the selected window or windows to the screen position X Y. To specify X or Y values relative to the right side or bottom side precede the value with an extra minus sign, like in move -+10 --20. When X or Y end with a percent sign %, they refer to a percentage of the desktop work area.

  • moveby X Y

    Displace window by X Y pixels.

  • center

    Position the window in the center of the desktop work area.

  • left

    Position the window against the left side of the desktop work area.

  • right

    Position the window against the right side of the desktop work area.

  • top

    Position the window against the top side of the desktop work area.

  • bottom

    Position the window against the bottom side of the desktop work area.

  • setIconTitle TITLE

    Set the icon title to TITLE.

  • getIconTitle

    Print the icon title.

  • setWindowTitle TITLE

    Set the window title to TITLE.

  • getWindowTitle

    Print the window title.

  • setGeometry GEOMETRY

    Set the window geometry to GEOMETRY. This geometry should be specified in a format that can be parsed by XParseGeometry(3). Negative offsets are with respect to the bottom or right side of the screen. Use +- for a truly negative position.

  • getGeometry

    Print the window geometry.

  • setClass CLASS

    Set the resource name and class to CLASS, which should be a resource name and a resource class connected by a dot. To preserve either the existing name or class, use a percentage sign for that part.

  • getClass

    Print the resource name and class.

  • netState [STATE]

    If STATE is omitted then it shows the EWMH window state. If STATE starts with a + then flags in STATE are appended to the existing EWMH window state. If STATE starts with a - then flags in STATE are removed from the existing EWMH window state. If STATE starts with a ^ then flags in STATE are toggled with respect to the existing EWMH window state. If STATE starts with a = then the EWMH window state is set to STATE. See EXPRESSIONS below. A list of EWMH flags can be found in the output of icesh symbols.

  • setLayer LAYER

    Move the specified window to another window layer. See EXPRESSIONS below for a list of LAYER symbols.

  • getLayer

    Print the window layer for the specified window.

  • setWorkspace WORKSPACE

    Move the specified window to another workspace. Select the root window to change the current workspace. If WORKSPACE is All then the specified window becomes visible on all workspaces. Specify this for the current workspace, next for the subsequent workspace or prev for the preceding workspace.

  • getWorkspace

    Print the workspace for the specified window.

  • opacity [OPACITY]

    Print the window opacity if OPACITY is not given, otherwise set the window opacity to OPACITY.

  • setTrayOption TRAYOPTION

    Set the IceWM tray option for the specified window to TRAYOPTION. See IceWM tray options, below, for TRAYOPTION symbols.

  • getTrayOption

    Print the IceWM tray option for the specified window.

  • setNormalGravity GRAVITY

    Set the window gravity field in the WM_NORMAL_HINTS property for the specified window to GRAVITY. See below for GRAVITY symbols.

  • getNormalGravity

    Print the window gravity from the WM_NORMAL_HINTS property for the specified window.

  • setWindowGravity GRAVITY

    Set the window gravity for the specified window to GRAVITY. See below for GRAVITY symbols.

  • getWindowGravity

    Print the window gravity for the specified window.

  • setBitGravity GRAVITY

    Set the bit gravity> for the specified window to GRAVITY. See below for GRAVITY symbols.

  • getBitGravity

    Print the bit gravity for the specified window.

  • motif [funcs FUNCTIONS | decor DECORATIONS | remove]

    Query, set or modify the _MOTIF_WM_HINTS property for the specified window. Without arguments motif will show the current value, but only if the window has such a property. The property can be removed or reset with the remove argument. With funcs and decor individual fields of this property can be enabled or disabled. If FUNCTIONS or DECORATIONS starts with a minus or plus sign then the existing value is modified, otherwise it is set to the new value. Note that if All is set, other set fields are disabled and cleared fields are enabled.

  • borderless

    Hide the frame borders and title.

  • bordered

    Show the frame borders and title.

  • denormal

    Remove the WM_NORMAL_HINTS property, if it exists. This lifts font-size restrictions on resizing, especially for terminals.

  • prop PROPERTY

    Print the value of property PROPERTY, if it is present.

  • properties

    Print all properties and their values.

  • frame

    Print the identifier of the window frame.

  • extents

    Print the window identifier and the frame border sizes: left, right, top and bottom.

  • focusmodel

    Print the ICCCM focus model as advertised by the client window. This is either Locally, Passive, Globally or NoInput.

  • override [0|1]

    Print the override redirect status for the window, or if either 0 or 1 is given, then disable or enable the override redirect status.

  • tabto label

    Move the windows as tabs to a frame that has frame label label. Such a frame is created if needed.

  • untab

    Move each window to its own frame, if it is currently tabbed.

  • loadicon image.pam

    Load an icon from file, which must be in the PAM image format, with dimensions at most 256, a depth of 4, and type RGB_ALPHA.

  • saveicon file000.pam

    Save an icon to a new file in the PAM image format. Digits are increased to generate a unique new filename for each window.

  • click window-x window-y button

    Send a button press and release event at position (window-x, window-y). A negative position is relative to the bottom right corner. The mouse pointer is warped to the position before sending the events. The button number should be between 1 and 5 inclusive.

  • monitors top bottom left right

    This sets the monitors to use for fullscreen. Top, bottom, left, and right are indices of the icesh xinerama command.

  • spy

    Observe the selected windows and report any changes. This includes focus, visibility, position, size and all window properties. To monitor all of the protocol request messages that client applications may send to icewm, also spy on the root window.

  • stacking

    Sort the list of windows from topmost to bottom-most.

  • reverse

    Reverse the order of the list of windows.

MANAGER ACTIONS

The following actions control the IceWM window manager and therefore do not require a window select or filter option:

  • listWorkspaces

    List the names of all workspaces.

  • current

    Show the number and name of the current workspace.

  • goto WORKSPACE

    Change the current workspace to WORKSPACE. Specify next for the subsequent workspace or prev for the preceding workspace.

  • workspaces [COUNT]

    Print the number of workspaces if COUNT is not given, otherwise set the number of workspaces to COUNT.

  • setWorkspaceName INDEX NAME

    Change the name of the workspace INDEX to NAME, where INDEX is a workspace number starting from zero.

  • setWorkspaceNames NAME [NAME]*

    Change the workspace names to the list of _NAME_s.

  • addWorkspace NAME

    Create a new workspace with name NAME.

  • desktop [SHOWING]

    If SHOWING is 1 then set showing the desktop mode. If SHOWING is 0 then turn off showing the desktop. Print the current mode if SHOWING is not given.

  • workarea

    Print the dimensions of the work area for the current workspace. This is the desktop, but minus space occupied by dock and panel windows.

  • randr

    Summarize the RandR configuration.

  • xinerama

    Summarize the Xinerama configuration.

  • check

    Print information about the current window manager, like name, version, class, locale, command, host name and pid.

  • clients

    List all managed client windows, their titles and geometries.

  • shown

    List all mapped client windows for the current desktop, their titles and geometries.

  • windows

    List all toplevel windows, their titles and geometries.

  • systray

    List applications that are managed by the IceWM system tray.

  • xembed

    List application windows that are embedded using the XEMBED protocol. This is another way to discover system tray applications.

  • logout

    Let icewm execute the LogoutCommand.

  • reboot

    Let icewm execute the RebootCommand.

  • shutdown

    Let icewm execute the ShutdownCommand.

  • cancel

    Let icewm cancel the logout/reboot/shutdown.

  • about

    Let icewm show the about window.

  • windowlist

    Let icewm show the window list window.

  • restart

    Let icewm restart itself.

  • suspend

    Let icewm execute the SuspendCommand.

  • hibernate

    Let icewm execute the HibernateCommand.

  • winoptions

    Let icewm reload the winoptions. This only affects new windows.

  • keys

    Let icewm reload the keys file.

  • refresh

    Let icewm refresh the desktop background.

  • guievents

    Monitor the ICEWM_GUI_EVENT property and report all changes. Hit Ctrl+C to abort this and continue with the next command.

  • delay [time]

    Stop execution for time or 0.1 seconds.

  • runonce program [arguments...]

    This action is meant to be used together with the -class option. Only if no window is matched by WM_CLASS then program [arguments...] is executed.

  • loop [count]

    Loop back to the beginning of the command and repeat. The optional count limits the number of repetitions.

  • pick

    Choose a window by a mouse button click.

  • sync

    Synchronize with the IceWM window manager. That is, wait for icewm to process all previous actions.

  • symbols

    List all named symbols.

CONDITIONALS

Icesh supports if-then-else expressions. The full syntax is:

if selection
then
    actions
elif selection
then
    actions
else
    actions
end

Where selection is a sequence of selection and filtering options, which evaluates to true when it is non-empty. That is, if one or more windows fulfilled the condition. If it is empty, then its actions clause is ignored and the subsequent elif or else clause is tried or taken. Each clause is optional.

Whenever a selection condition evaluates to false, the window selection that existed before the if clause is immediately restored. This also happens after an end clause.

EXPRESSIONS

Some of the window actions require one or two EXPRESSION arguments.

  • EXPRESSION ::= SYMBOL | EXPRESSION { + | \| | - } SYMBOL

This says that an expression is either a SYMBOL or an expression which is combined with an operator to a SYMBOL. In other words, an expression is a sequence of symbols, which are combined using operators, where an operator may be a plus, a vertical bar or a minus.

Each SYMBOL may be either a number or a named symbol from one of the following applicable domains, depending upon the context in which it is used:

  • Window layer

    Named symbols of the domain Window layer (numeric range: 0-15):

      Desktop                (0)
  Below                  (2)
  Normal                 (4)
  OnTop                  (6)
  Dock                   (8)
  AboveDock             (10)
  Menu                  (12)
  Fullscreen            (14)
  AboveAll              (15)

    These symbols are used with the LAYER argument to the setLayer action.

  • IceWM tray option

    Named symbols of the domain IceWM tray option (numeric range: 0-2):

      Ignore                 (0)
  Minimized              (1)
  Exclusive              (2)

    These symbols are used with the TRAYOPTION argument to the setTrayOption action.

  • Gravity symbols

    Named symbols for window and bit gravity (numeric range: 0-10):

      ForgetGravity         (0)
  NorthWestGravity      (1)
  NorthGravity          (2)
  NorthEastGravity      (3)
  WestGravity           (4)
  CenterGravity         (5)
  EastGravity           (6)
  SouthWestGravity      (7)
  SouthGravity          (8)
  SouthEastGravity      (9)
  StaticGravity         (10)

  • Motif functions

      All                  (1)
  Resize               (2)
  Move                 (4)
  Minimize             (8)
  Maximize             (16)
  Close                (32)

  • Motif decorations

      All                  (1)
  Border               (2)
  Resize               (4)
  Title                (8)
  Menu                 (16)
  Minimize             (32)
  Maximize             (64)

  • EWMH window state symbols

    Named symbols of the domain EWMH state (numeric range: 0-8191):

      ABOVE                 (1)
  BELOW                 (2)
  DEMANDS_ATTENTION     (4)
  FOCUSED               (8)
  FULLSCREEN            (16)
  HIDDEN                (32)
  MAXIMIZED_HORZ        (64)
  MAXIMIZED_VERT        (128)
  MODAL                 (256)
  SHADED                (512)
  SKIP_PAGER            (1024)
  SKIP_TASKBAR          (2048)
  STICKY                (4096)

EXAMPLES

List all workspace names:

icesh listWorkspaces

Example output:

workspace #0: `main'
workspace #1: `web'
workspace #2: `doc'
workspace #3: `dev'

Close terminal work and activate terminal fun.

icesh -c work.XTerm close -a -c fun.XTerm activate

Print opacity for all xterms.

icesh -c XTerm opacity

Change opacity for all xterms.

icesh -c XTerm opacity 84

Move all windows on workspace "Top" to the current workspace.

icesh -W "Top" setWorkspace "this"

Restore all hidden clients, minimize all clients on the current workspace and activate Firefox.

icesh -N HIDDEN restore -a -W "this" minimize -a -c Firefox activate

Resize the focused window to occupy the right half of the desktop area.

icesh -f sizeto 49% 100% top right raise

Toggle the frame border of the focused window.

if icesh -f motif | grep -q 'decor:$'; then \
    icesh -f motif decor All; else icesh -f motif decor ""; fi

Here is a different solution using conditionals.

icesh -f if -P _NET_FRAME_EXTENTS=0 then bordered else borderless

Here is a conditional to either toggle the visibility of a roxterm that has a WM_ROLE value of special or start it with runonce.

icesh if -c roxterm.Roxterm -R special then \
    if -v then hide \
    elif -u then setWorkspace this activate end \
    else runonce roxterm --role=special

Collect all urxvt terminals from the fourth workspace in a single frame on the current workspace.

icesh -W 3 -c urxvt tabto myfunnyname

Use the loop construct conditionally to wait for a certain window to appear.

icesh -t if -n Tooltip then list else delay 0.05 loop end

ENVIRONMENT

  • DISPLAY

    The default display.

EXIT STATUS

  • 0

    The last action completed successfully.

  • 1

    The last action completed unsuccessfully, or no window met the condition.

  • 2

    A conditional has invalid syntax.

  • 3

    The display could not be opened.

  • 4

    The X server reports an error while processing a request.

COMPLIANCE

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

SEE ALSO

icewm(1), wmctrl(1), xdotool(1), xprop(1), xwininfo(1), XParseGeometry(3).

BUGS

Please report bugs at Github.

AUTHOR

Brian Bidulock.

See --copying for full copyright notice and copying permissions.

LICENSE

IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution or use the --copying flag to display copying permissions.

| ------------: | :--------- | | Index | IceWM |