Configuration
From PyTyle Wiki
New configuration options?
If there are new configuration options, there are two ways to use them. The first way is to simply delete (or move) your current configuration file, and PyTyle will put a fresh and up to date on in its place. The other way is to look at the most up to date version of the configuration file, and add in the changes manually.
Where?
After PyTyle runs for the first time, it will create a directory in your XDG_CONFIG_HOME path (usually ~/.config/) named pytyle. Inside the directory, there should be a pytylerc file for you to edit.
Remember, the pytylerc file is a Python script, meaning that if there is a syntax error, PyTyle will not load properly.
This wiki page describes the options available to you. For information on precisely how to change them, see the configuration file. It is well documented with explanations and examples.
Dynamic loading
The pytylerc file can be dynamically loaded while PyTyle is running. This allows you to change your configuration options and layouts on the fly. By default the configuration file can be reloaded while PyTyle is running by pressing the Alt-Q key combination.
Currently, the only option that you cannot change on the fly is "global_tiling." I'm open to thoughts on if this should be enabled.
Terminology
There are a few words that you need to be familiar with as they relate to PyTyle:
Screen - A physical screen. Using Xinerama, PyTyle will detect all screens on the current desktop. (PyTyle has not been tested with separate X sessions yet.)
Workspace - A designated area of space for you to work with, provided by your window manager. More than likely, you will have more than one of these. Additionally, "workspace" on this page can be interchangeable with "viewport" or "desktop" (depending on which one that your window manager supports).
Master - Any window in the "master" pane of your tiling layout. (Depending on the layout, sometimes there can be only one master window, but usually you can have more than one.)
Slave - Any window in the "slave" pane of your tiling layout.
Miscellaneous Options
Tilers
A listing of all available tilers that PyTyle can use. If a tiling layout is not in this list, it cannot be used. This list also provides the order through which you can cycle tiling layouts. (By default, you can cycle layouts using the Alt-Z key combination.)
Global Tiling
When this option is enabled, PyTyle will automatically tile all workspaces and screens when it starts up.
When this option is disabled, PyTyle will not tile any workspaces or screens unless you tell it to.
In either case, you can still disable tiling on a per screen/workspace basis by issuing the untile command. (By default, this is the Alt-U key combination.)
Timeout
Sometimes PyTyle needs to wait a small amount of time between when the X server sends an event to PyTyle and when PyTyle checks for the effects of that event. This setting enables you to change that time (in seconds).
By default it is set to 0.1 seconds. This probably won't need to be changed. (I've tested this setting on a P3 1.0 GHz with 128 MB of memory and it works fine.)
Decorations
Experimental in Openbox only.
When this setting is disabled, PyTyle will attempt to remove the window decorations around the windows its tiling. Windows will get their decorations back only when the untile command is issued.
The problem with this setting is that window managers usually use the window decoration to indicate which window is "active." Without the decorations, it becomes difficult to tell exactly which window is "active." I'm still experimenting with the possibility of drawing borders around the windows, XMonad style.
Original Decorations
This should reflect whether or not you have disabled decorations via your window manager. This is to make sure that PyTyle isn't adding or removing decorations when you issue an untile command when it shouldn't be adding or removing decorations.
Key Bindings
Key bindings are a dictionary of mappings. PyTyle maps key combinations to commands that PyTyle understands and executes. In general, the format for key combinations is as follows:
[Alt-][Shift-][Ctrl-][Super-]KEY
Where "KEY" can be anything from the key listing.
What follows is a listing of all possible commands.
Tile
Default binding: Alt-A
Default command: tile.default
Tile will do just as its name suggests- tile your windows. This will also enable tiling for your screen/workspace if it was disabled before. Additionally, while PyTyle is enabled on your current screen/workspace, you can drag windows around and PyTyle won't complain. If you want to put that window back in its proper place, issue the tile command. If you drag/move a window to another screen or workspace, PyTyle will automatically adjust and re-tile itself. Issuing the tile command keeps your current window size proportions.
You may also bind specific tiling layouts to keys as well. For instance, you may want an additional key binding, say, "Alt-Ctrl-C" to always use the Cascade tiling layout. Simply bind it to the tile.Cascade command. (Remember, the layout must be listed in the tilers list.)
Untile
Default binding: Alt-U
Default command: untile
Attempts to move and resize your windows back to their original position and size before they were tiled. This will also disable tiling for the screen/workspace that you are on. When tiling is disabled, the only command that will work is the tile command.
Cycle Tiler
Default binding: Alt-Z
Default command: cycle_tiler
Changes to the next tiling layout listed in tilers.
Reload
Default binding: Alt-Q
Default command: reload
Dynamically reloads your configuration file. This includes key bindings, workarea, layout options, available layouts, etc.
Reset
Default binding: Alt-Shift-space
Default command: reset
Does a hard reset of your current tiling layout. This command is probably only useful in two contexts:
- To reset your window proportion sizes back to their defaults
- A last ditch effort (before restarting PyTyle) to recover from a bug that's preventing you from using your tiling layout.
Cycle
Default binding: Alt-C
Default command: cycle
Cycles all slave windows into the position of the current master window. If there is more than one master window, only the first master window will be cycled. If there are no master windows or no slaves, this command has no effect.
Screen Focus
Default bindings: Alt-W Alt-E Alt-R
Default commands: screen0_focus screen1_focus screen2_focus (respectively)
Moves focus to the last active window on the specified screen. If there are no windows on the screen you are trying to focus to, or that screen isn't currently being tiled, then this command will have no effect. Also, if you try to move focus to the current screen, this command will have no effect.
Note the number in each of the above three commands. This is not currently arbitrary, and also means that PyTyle has built-in support for three screens. However, PyTyle was built such that it should be able to support any arbitrary number of screens (except for these commands). If you have three or more screens, I would love to hear from you. (Everything except for screen focus and screen put should work.)
Screen Put
Default bindings: Alt-Shift-W Alt-Shift-E Alt-Shift-R
Default commands: screen0_put screen1_put screen2_put (respectively)
Moves the currently active window to the specified screen. This will always work, even if the specified screen does not have tiling enabled (but the current screen must have tiling enabled).
Note the number in each of the above three commands. This is not currently arbitrary, and also means that PyTyle has built-in support for three screens. However, PyTyle was built such that it should be able to support any arbitrary number of screens (except for these commands). If you have three or more screens, I would love to hear from you. (Everything except for screen focus and screen put should work.)
Master Decrease
Default binding: Alt-H
Default command: master_decrease
Decreases the master pane by a certain amount. (This "amount" cannot currently be specified in the configuration file, although that option will probably appear at some point.)
Remember, this command may not have relevancy to some layouts and thus have no effect.
Master Increase
Default binding: Alt-L
Default command: master_increase
Increases the master pane by a certain amount. (This "amount" cannot currently be specified in the configuration file, although that option will probably appear at some point.)
Remember, this command may not have relevancy to some layouts and thus have no effect.
Add Master
Default binding: Alt-period
Default command: add_master
Adds an additional master window to the master area. If you issue this command while focused on a slave, then it will add that window to the master pane. Otherwise it will pick the first slave.
This command actually increases a counter for the number of allowed master windows. That means the layout will always readjust itself to make sure it satisfies the number of masters before it appoints windows as slaves.
Remember, this command may not have relevancy to some layouts and thus have no effect.
Remove Master
Default binding: Alt-comma
Default command: remove_master
Removes a master window from the master area. If you issue this command while focused on a master, then it will remove that window from the master pane. Otherwise it will pick the first master.
This command actually decreases a counter for the number of allowed master windows. That means the layout will always readjust itself to make sure it satisfies the number of masters before it appoints windows as slaves.
There can be zero masters if the tiling layout allows for it.
Remember, this command may not have relevancy to some layouts and thus have no effect.
Make Active Master
Default binding: Alt-Return
Default command: make_active_master
Replaces the currently active window with the master window. If there is more than one master, then it will replace the first master (which includes other masters). If you are currently focused on the first master, this command has no effect.
Master Focus
Default binding: Alt-M
Default command: win_master
Simply moves focus to the master. If there is more than one master, it will focus on the first master.
Close Window
Default binding: Alt-Shift-C
Default command: win_close
Closes the currently focused window. You do not need to use this command. You may close windows using normal methods provided by your window manager- PyTyle will detect it and adjust itself. This command is only included in PyTyle for completeness.
In fact, due to PyTyle's youth, it is quite possible that the active window is not currently what PyTyle thinks is the active window (out-of-sync). Therefore, issuing a close command could very well close a window you don't want to close.
Tip: You could comment out this key binding in the configuration file and assign your own key combination for closing windows using your window manager.
Focus Previous
Default binding: Alt-J
Default command: win_previous
Moves focus to the previous window.
Focus Next
Default binding: Alt-K
Default command: win_next
Moves focus to the next window.
Switch Previous
Default binding: Alt-Shift-J
Default command: switch_previous
Switches the currently active window with the previous window. The focus does not change.
Switch Next
Default binding: Alt-Shift-K
Default command: switch_next
Switches the currently active window with the next window. The focus does not change.
DEBUG: Query
Default binding: Alt-D
Default command: query
Query is commented out by default.
When this command is issued, it will spit out some useful debugging information about the current environment to the standard out.
Callbacks
PyTyle is now capable of accepting commands over the command line thanks to a patch from Johannes Pirkl. This can be done using the following command:
pytyle-client callback_number
Where callback number is an integer that is bound to a command specified in the Callbacks portion of the configuration file.
Work area
The "work area" is defined as the rectangular box on any screen with which PyTyle should operate within. You can view it as a way to specify margins on a per screen basis.
If you are using one screen, then you should not have to use this configuration option. Window managers will usually provide an accurate description of the work area in this case. However, you can still use this feature by using screen 0 to specify your margins.
If you are using multiple screens and have docks/panels, then you must use this configuration option. With multiple screens, window managers are terrible about reporting available work area, thus, PyTyle will ignore it and use the margins you specify here.
The work area is automatically updated while PyTyle is running if you add/remove panels and/or docks. This will only work if you're using one screen and if you have not specified a work area in the configuration file.
Ignore Windows From Tiling
While PyTyle will ignore as many windows and popups as it makes sense to ignore, there are still sometimes when you need to force PyTyle to ignore windows. For instance, gmrun and gimp are good candidates for this scenario.
Quite simply, PyTyle will search (case insensitive) each window's class, and if there's a match with the specified filter, PyTyle will not tile that window.
You can use xprop to find a window's class.
Layout Specific Options
Sometimes layouts need only to be tweaked slightly to suit your needs. This is where layout specific options come in handy. Below is a description of the default settings for each layout.
Vertical
- width_factor
- The default width factor of the master pane. It is defined relative to the respective screen's width. It can be any value greater than 0 and less than or equal to 1.
Horizontal
- height_factor
- The default height factor of the master pane. It is defined relative to the respective screen's height. It can be any value greater than 0 and less than or equal to 1.
Maximal
There are no options for the Maximal layout. Can anyone think of any?
Cascade
- decoration_height
- Sometimes PyTyle cannot accurately pick up on a window's decoration height. Since this is required for a proper cascading effect, it may be necessary to configure this. (Although, you probably shouldn't have to.)
- width_factor
- The default width factor of all windows. It is defined relative to the respective screen's width. It can be any value greater than 0 and less than or equal to 1.
- height_factor
- The default height factor of all windows. It is defined relative to the respective screen's height. It can be any value greater than 0 and less than or equal to 1.
- push_over
- This can be used to provide a more traditional cascading effect. When set to 0, all windows are aligned on the same y-axis. When set to something above 0, each subsequent window is indented more by that amount. (So if it's set to 25, then the first window will be indented by 0 pixels, the second by 25 pixels, the third by 50 pixels, and so on.)
- horz_align
- This can either be "left" or "right." This allows you to have a cascading effect on either side of the screen. (Should there be a vert_align? How would it work?
Horizontal Rows
- height_factor
- The default height factor of the master pane. It is defined relative to the respective screen's height. It can be any value greater than 0 and less than or equal to 1.
- row_size
- The default number of columns for the horizontal rows of windows.
Tiling Per Workspace Or Screen
Sometimes you have screens that support different resolutions (for instance, I have 1280x1024 and 1280x720 monitors), and thus are better suited for different layouts. Also, you might have a workspace named "browsers" where you prefer a full screen layout and another named "terminals" where you prefer a grid-like layout.
This option will allow you to set default tiling layouts on a per screen per workspace basis. (That is, screen first and then workspace. So if you need a default tiling layout for an entire workspace for both screens, you would need to specify it twice.) You can still cycle through tiling layouts at any time.
Note that workspaces and screens start at the number 0, and count across before going down. For instance, if you have three rows and three columns of workspaces, the number scheme would look like this:
0 1 2 3 4 5 6 7 8
