placemaker

placemaker is a powerful wrapper for wmutils. It is designed to simplify the process of managing windows and allow users to easily create tiling/stacking patterns.

Requirements

• wmutils/core
• bash (also works with my zsh configuration, though your mileage may vary)

Usage

Commands follow the format placemaker [SETTINGS] [MODE]

Settings

Used to alter the default behavior of placemaker.

• --geometry X0 Y0 X1 Y1 : Set the geometry boundaries for window placement. X0, Y0, X1, and Y1 are all either an integer value or the character c. If they are set to c than the will use the currently stored value (which defaults to the bounds of the root window).
  • X0 = The left most x boundary to use.
  • Y0 = The top most y boundary to use.
  • X1 = The right most x boundary to use.
  • Y1 = The bottom most y boundary to use.
• --gap GAP : Set a gap that separates windows from the geometry. GAP is an
• --flip : Flip the y placement of windows.
• --mirror : Mirror the x placement of windows.
• --ignore-bor : Don't use the output of wattr b WID to adjust window placement.
• --autosave [ATOM] : When set windows will automatically have their geometry saved to the specified ATOM. If no ATOM is specified, PLACEMAKER_SAVE is used. If an ATOM is specified, it will override the default ATOM used by --save and --restore.
  • ATOM is a string representing the X atom that the geometry will be saved to. The only restrictions on an ATOM are that they can not begin with the characters 0x or be the string --erase as these are used for other functionality.
• --print : Don't move windows, only print adjustments to stdout.
• --quiet : Don't print window adjustments to stdout.
• -h, --help : Print help text to stdout.

Mode

Used to position windows based on their id value, WID.

• -P, --place X Y W H WID : Place a window at the specified X and Y coordinates, with a width of W and a height of H. X, Y, W, and H are all either an integer value or the character c. If they are set to c than the will use the windows current value.

• -V, --save [ATOM] WID : Save a windows current geometry to an ATOM. If no ATOM is specified, PLACEMAKER_SAVE is used. The definition of an ATOM can be found with the --autosave argument.

• -R, --restore [ATOM] [--erase] WID : Restore a window to a saved geometry. If no ATOM is specified, PLACEMAKER_SAVE is used. The definition of an ATOM can be found with the --autosave argument. If the --erase argument is passed, the atom will be set to an empty string after the window is positioned.

• -S, --slam S_DIR WID : Move the window to in a specified direction within the bounds of the geometry.

  • S_DIR is one of:
    • up or north : Move the window to the top bound of the geometry.
    • right or east : Move the window to the right bound of the geometry.
    • down or south : Move the window to the bottom bound of the geometry.
    • left or west : Move the window to the left bound of the geometry.
    • upperleft or northwest : Move the window to the top and left bounds of the geometry.
    • upperright or northeast : Move the window to the top and right bounds of the geometry.
    • lowerleft or southwest : Move the window to the bottom and left bounds of the geometry.
    • lowerright or southeast : Move the window to the bottom and right bounds of the geometry.
    • xcenter or hcenter : Centers the window horizontally within the bounds of the geometry. --gap 0 is automatically set.
    • ycenter or vcenter : Centers the window vertically within the bounds of the geometry. --gap 0 is automatically set.
    • center : Centers the window within the bounds of the geometry. --gap 0 is automatically set.

• -M, --max M_DIR WID : Maximize a window in a specified direction.

  • M_DIR is one of:
    • up or north : Move the top bound of the window to the top bound of the geometry, without changing the position of the windows bottom bound.
    • right or east : Move the right bound of the window to the right bound of the geometry, without changing the position of the windows left bound.
    • down or south : Move the bottom bound of the window to the bottom bound of the geometry, without changing the position of the windows top bound.
    • left or west : Move the left bound of the window to the left bound of the geometry, without changing the position of the windows right bound.
    • horizontal : Maximize the window to fill the full horizontal geometry.
    • vertical : Maximize the window to fill the full vertical geometry.
    • full : Maximize the window to fill the full geometry.

• -L, --scale PERCENT WID : Scale a windows size by a given percentage. --ignore-bor is automatically set when --scale is called.

• -G, --grid GRID [POSITION] WIDS : Places a windows in virtual grid cells, starting at a specified position. If no POSITION is passed, it defaults to 0,0.

  • GRID is two integers connected by the character x.

    • Example: 2x3 will create the following virtual grid.

      +----------------+----------------+
      |                |                |
      |                |                |
      |                |                |
      +----------------+----------------+
      |                |                |
      |                |                |
      |                |                |
      +----------------+----------------+
      |                |                |
      |                |                |
      |                |                |
      +----------------+----------------+
      

  • POSITION is two integers connected by the character ,.

    • Example: 1,2 will place a window in the middle leftmost cell in a 2x3 grid.

      +----------------+----------------+
      |                |                |
      |                |                |
      |                |                |
      +----------------+----------------+
      |                |                |
      |                |       wid      |
      |                |                |
      +----------------+----------------+
      |                |                |
      |                |                |
      |                |                |
      +----------------+----------------+
      

• -T, --tile RATIO PATTERN WIDS : Tile windows with a specified pattern, and master ratio. If only a single window is passed in, the monocle pattern will always be used.

  • RATIO is two integers connected by an / representing the size of the master window.

    • Example: 2/3 will produce the following master and sub placements with a hstack pattern.

      +---------------------------------+
      |                                 |
      |                                 |
      |                                 |
      |              master             |
      |                                 |
      |                                 |
      |                                 |
      +---------------------------------+
      |                                 |
      |               sub               |
      |                                 |
      +---------------------------------+
      

  • PATTERN is one of:

    • monocle or max or m : All tiled windows are the maximum geometry size. This ignores RATIO, though a variable must still be passed for it.
    • rstack or vstack or r : The master window is on the left of the screen, and sub windows stack vertically on the right of the screen.
    • lstack or l : The master window is on the right of the screen, and sub windows stack vertically on the left of the screen.
    • bstack or hstack or b : The master window is on the top of the screen, and sub windows stack horizontally on the bottom of the screen.
    • tstack or t : The master window is on the bottom of the screen, and sub windows stack horizontally on the top of the screen.

Advanced Usage

Direct Window Adjustments

By appending additional information to a WID you can adjust a window after it has been processed by placemakers other functions. Any number of adjustments can be appended in any order to a WID.

• Geometry Adjustment
  • By appending +X,Y,W,H to a WID you can adjust the windows position after placemaker has processed the window, but before it has been moved.
    • Example: 0x00000000+10,20,-10,-20 will move 0x00000000 10 pixels to the right and 20 pixels down, and decrease its width by 10 pixels and its height by 20 pixels. This will occur regardless of what function processes the window.
• Override Adjustment
  • By appending +[x|y|w|h]=INTEGER to a WID you can force the x, y, w, or h value to be overrode right before the window is placed.
    • Example: 0x00000000+w=200 will force 0x00000000 to have a width of 200 regardless of what other calculations placemaker has done.
• Position Adjustment
  • By appending +S_DIR (the parameter for the --slam function) to a WID you can position a window within its determined geometry. When this is done the windows width and height will be their current value. This can be used in conjunction with --tile to produce a psuedo tiled mode, where windows are positioned in their tiled locations, but are free to be any size.
    • Example: 0x00000000+upperright will position 0x00000000 in the upper right hand corner of its set geometry.
• Reflection Adjustment
  • By appending +mirror or +flip you can toggle the mirror or flip state for the window.
• WID Adjustment
  • By appending +WID you can change what window will actually be effected by the movement. This can be used to "steal" the position of a window and apply it to something else.
    • Example: 0x00000000+0x00000001 will use 0x00000000 for all of the window calculations, but move 0x00000001.

Grid Placement

--grid is the most complex function in placemaker, as it is designed to allow others to create there own tiling patterns to fit their own needs. Its true argument syntax is

--grid GRID [BEHAVIOR POSITION WIDS | BEHAVIOR WIDS | POSITION WIDS | WIDS]...

and it can take any number of these arguments, dynamically adjusting window placement on the way.

Behavior

By default --grid will automatically place all windows after the first WID one cell lower. This behavior can be altered by passing a BEHAVIOR.

BEHAVIOR is one of:

• --x-shift : WIDS after this one will be placed one cell to the right.
• --y-shift : WIDS after this one will be placed one cell lower. This the default.
• --no-auto : All WIDS will be placed in this location.

Position

In addition to the format specified in the Usage section, a position can also be two sets of integers connected by the character ,, connected by the character +. The first set of integers represents a standard POSITION. The second set is the number of cells that the WID will occupy.

Example: 0,0+1,2 will place a window in the top left cell, through the middle left cell of a 2x3 grid.

+----------------+----------------+
|                |                |
|                |                |
|                |                |
|      wid       +----------------+
|                |                |
|                |                |
|                |                |
+----------------+----------------+
|                |                |
|                |                |
|                |                |
+----------------+----------------+

Internal Functions

In addition to the Modes listed in the Usage section, there is also -I, --internal. This mode exposes the internal functions of placemaker to the user. This allows for the usage of things like the built in data parsers when creating new patterns. When calling an internal function fn_ is automatically prepended to the call.

Example: -I parseGrid x 3x4 will call the fn_parseGrid function, and return 3.

A complete list of functions and documentation can be found in the source code, but the key functions are:

• getAttribute : Get an internal window attribute, ignoring direct window adjustments if they are present.
• parseGrid : Return a requested value from a GRID.
• parsePosition : Return a requested value from a POSITION.
• checkPosition : If parsePosition returns the character o set an override value
• parseRatio : Return a requested value from a RATIO.

Todo

• Allow all functions to take in multiple WIDS.
• Add column and row patterns.
• Add dwindle pattern variants to lstack, rstack, bstack, and tstack.
• Add ability to read from stdin.
• Add inverted behaviors to Grid.
• Add example patterns to allow users to jumpstart their own patterns.
• Possibly rewrite in C++ (though there are pros and cons to this).