Main window manager object. More...
Public Member Functions | |
| def | __init__ |
| Create the main window manager object. More... | |
| def | start |
| Start the window manager. More... | |
| def | connect_x |
| Connect to the X server. More... | |
| def | configure_x |
| Configure X server to send Minx events it needs to manage windows. More... | |
| def | manage_existing |
| Manage existing top-level windows. More... | |
| def | event_loop |
| Retrieve and process X events. More... | |
| def | focus_next |
| Focus next window. More... | |
| def | focus_prev |
| Focus previous window. More... | |
| def | kill |
| Kill window. More... | |
| def | nuke |
| Kill window using brute force. More... | |
| def | spawn |
| Run specified command. More... | |
| def | add_to_focus_list |
| Add a newly created top-level window to the focus list. More... | |
| def | manage |
| Check if given window should be managed or not. More... | |
| def | quit |
| Quit the window manager. More... | |
Main window manager object.
This class encapsulates all the internal state required by the window manager. Typically, you will create an instance of this class in order to start the window manager. For example, the simplest Minx configuration would be a file with the following contents:
#!/usr/bin/env python
import minx
minx.core.wm().start()Of course, the above code requires the minx package to be in your Python path. But, assuming that is the case, it would start Minx with the default key bindings, hooks, and other settings.
To make simple customizations, create an instance of the config class and pass that to the wm constructor:
#!/usr/bin/env python
import minx
conf = minx.core.config()
conf.active_border_color = 0x00FF00 # green
minx.core.wm(conf).start()In addition to customizing window border attributes, the config class enables logging to be configured. Here is an example:
#!/usr/bin/env python
import logging
import minx
conf = minx.core.config()
conf.log_to_file('minx.log')
conf.log_level(logging.DEBUG)
minx.core.wm(conf).start()The Logging HOWTO provides more details on logging configuration.
Apart from the simple attribute customizations shown above, if you would also like to change the way Minx responds to various events, you will have to define hook functions and pass those to Minx. Here is a simple example:
#!/usr/bin/env python
import minx
def my_manage_hook(w):
prop = w.properties()
if prop['class'].lower() == 'gkrellm':
return False
return True
wm = minx.core.wm()
wm.hooks.add('manage_hook', my_manage_hook)
wm.start()The above configuration will setup a manage hook that instructs Minx to ignore the GKrellM window. Have a look at the Hooks HOWTO for lots more info about configuring Minx using hooks. Additionally, the Hooks List documents all the hooks that Minx currently supports.
One important use of hooks is for defining custom key bindings. The Key Bindings HOWTO has the details.
To customize how Minx arranges windows, you can:
Here is an example that illustrates the first two of the above possibilities:
#!/usr/bin/env python
import minx
def my_init_hook(m):
scr = m.root_windows
m.layouts.add(minx.layout.tall(m, scr[0]))
m.layouts.add(minx.layout.rows(m, scr[1]))
def my_receptive_layout_hook(w):
prop = w.properties()
if 'gimp' in prop['class'].lower():
global wm
try:
L = wm.layouts.find('gimp')
return L
except minx.core.layman.unknown_layout:
parent = wm.root_windows[w.screen()]
return minx.layout.gimp(wm, parent)
return None
wm = minx.core.wm()
wm.hooks.add('init_hook', my_init_hook)
wm.hooks.add('receptive_layout_hook', my_receptive_layout_hook)
wm.start()The init hook allows you to setup the layouts you want to use. If you don't supply an init hook, Minx will use a default layout for each screen. At this time, the default layout is the full layout, which shows one window at a time by resizing windows to occupy the entire screen. In the above example, we use the tall layout for the first screen and the rows layout for the second screen. Of course, this would only work if you actually have two screens. Please also note that the tall and rows layout classes have not yet been implemented; we use these nonexistent layouts just to illustrate the intended spirit of layouts specification.
The receptive layout hook allows you to either create or find a layout for each new window that Minx manages. In the above example, we created an instance of the gimp layout when Gimp starts up and use that for subsequent windows. For all other window types, we fall back to either the tall or rows layouts setup in the init hook. If, for some reason, the tall and rows layouts refuse to manage the new window, Minx will fall back its default, viz., the full layout. Again, like tall and rows, the gimp layout does not exist yet; it was used merely to illustrate how the receptive layout hook is intended to work.
Documentation for implementing layouts will come later.
| def minx.core.wm.wm.__init__ | ( | self, | |
conf = None |
|||
| ) |
Create the main window manager object.
| conf | Config object containing simple customizations. |
The wm class implements the main interface to the Minx window manager. You will have to first create an instance of this class and then call its start() method to run the window manager. This constructor simply sets up some internal attributes, the most important of which are:
The config object specifies various settings such as the border colors, sizes, etc. To customize these settings, you will (typically) create a config object, change its various attributes, and pass that object into this constructor. (Alternatively, you could first create a wm object and then access its config attribute.) If you don't supply a config object, the window manager will use default settings.
The wm object's hooks attribute maps names of hook functions (i.e., strings) to prioritized lists of callables. Minx will trigger these hooks at appropriate points in its event processing workflow. Minx uses hooks both internally (to handle various events) and "externally" (to allow end-users to customize its behaviour).
To supply your own hooks, after creating a wm instance, use its hooks attribute to add hook functions for various events. Take a look at the Hooks HOWTO for more on customizing Minx with hook functions. The Hooks List documents all the hooks currently supported by Minx.
As mentioned earlier, Minx leverages its hooks mechanism to allow end-users to define custom key bindings. The Key Bindings HOWTO explains this feature.
One thing to keep in mind about hooks is that, since Minx uses them internally, it is easy to override its internal hooks and even disable them. Usually, this will cause Bad Things (TM) to happen. Thus, you should exercise care when dealing with "dangerous" hooks. As long as you stick to "external" hooks used by Minx specifically to effect customization, you should be okay.
Finally, the layouts object provides an interface for dealing with window layouts. By default, Minx uses the full layout, which shows one window at a time, resizing windows so that they occupy the entire screen. You can use the init hook to add your preferred layouts to the layout manager.
Another way to customize layout selection is to use the receptive layout hook, which provides a mechanism for deciding a layout for each new window.
| def minx.core.wm.wm.add_to_focus_list | ( | self, | |
| w | |||
| ) |
Add a newly created top-level window to the focus list.
| w | The minxlib.window to be added. |
This function is meant to be used internally by Minx. Specifically, the wm constructor calls it to take over management of any top-level windows that might have been created before Minx was started. Also, the MapNotify handler in the xevents class uses it to add a newly mapped top-level window to the focus list and to focus it.
End-users should not use this function.
| def minx.core.wm.wm.configure_x | ( | self) |
Configure X server to send Minx events it needs to manage windows.
This method sets up the event mask for all the root windows so that Minx gets the notifications it needs to be able to manage windows. It also sets up passive keyboard grabs to make the keybindings mechanism work.
| def minx.core.wm.wm.connect_x | ( | self) |
Connect to the X server.
This method connects to the X server. If we are unable to do so, it will raise a minxlib.connection_error.
| def minx.core.wm.wm.event_loop | ( | self) |
Retrieve and process X events.
This method implements Minx's event loop. Once we enter this function, Minx will initiate an infinite loop, wherein it blocks, waiting for the X server to send it events. When it receives an event notification, it will trigger its internal event processing hooks to respond appropriately.
| def minx.core.wm.wm.focus_next | ( | self) |
Focus next window.
This function passes input focus to the next window in the window manager's list of top-level windows that can accept input focus. It is meant to be invoked via a key binding's hook. Here is an example of intended usage:
#!/usr/bin/env python
import minx
wm = minx.core.wm()
wm.hooks.add( 'F1', wm.focus_next)
wm.hooks.add('S-F1', wm.focus_prev)
wm.start()With that in your Minx start-up script, you will be able to cycle input focus with F1 and SHIFT + F1 (in addition to the default key bindings for focus cycling, viz., ALT + Tab and ALT + SHIFT + Tab).
| def minx.core.wm.wm.focus_prev | ( | self) |
Focus previous window.
This function passes input focus to the previous window in the window manager's list of top-level windows that can accept input focus. It is meant to be invoked via a key binding's hook. Here is an example of intended usage:
#!/usr/bin/env python
import minx
wm = minx.core.wm()
wm.hooks.add( 'F1', wm.focus_next)
wm.hooks.add('S-F1', wm.focus_prev)
wm.start()With that in your Minx start-up script, you will be able to cycle input focus with F1 and SHIFT + F1 (in addition to the default key bindings for focus cycling, viz., ALT + Tab and ALT + SHIFT + Tab).
| def minx.core.wm.wm.kill | ( | self, | |
w = None |
|||
| ) |
Kill window.
| w | The minxlib.window to be killed. |
This function kills the X client application that created the window w and all of its other windows and X resources. If w is not supplied by the caller, this function will kill the currently focused window.
| def minx.core.wm.wm.manage | ( | self, | |
| w | |||
| ) |
Check if given window should be managed or not.
| w | The minxlib.window to be checked. |
This function triggers the manage hooks setup by end-users and checks all their return values. If all the manage hooks return True, then this function will return True. If any of the manage hooks returns False, this function will return False. Thus, Minx will only manage a top-level window if all the manage hooks return True.
| def minx.core.wm.wm.manage_existing | ( | self) |
Manage existing top-level windows.
Minx uses this function to get the list of existing top-level windows and add them to its internal data structures so it can manage them. This is necessary, for example, when an end-user's ~/.xinitrc starts X programs before starting the window manager. It is also required when the window manager is restarted or when a user switches from another running window manager to Minx.
| def minx.core.wm.wm.nuke | ( | self, | |
w = None |
|||
| ) |
Kill window using brute force.
| w | The minxlib.window to be nuked. |
This function kills the X client application that created the window w and all of its other windows and X resources. If w is not supplied by the caller, this function will kill the currently focused window.
| def minx.core.wm.wm.quit | ( | self) |
Quit the window manager.
This function sets a flag that will eventually result in Minx exiting its event loop. It is meant to be invoked via a key binding or other similar action.
| def minx.core.wm.wm.spawn | ( | self, | |
| cmd | |||
| ) |
Run specified command.
| cmd | A string containing the command and command-line arguments. |
This function can be used to run arbitrary commands. Minx does not wait for the command to complete or communicate with it any further after starting it. The intent of this function is to facilitate launching GUI applications via window manager key bindings.
If the command fails, Minx will write details to its log (if logging has been enabled).
| def minx.core.wm.wm.start | ( | self) |
Start the window manager.
Call this method after creating a wm instance to get Minx up and running. Here is an example showing how to start Minx with its default settings, key bindings, etc.:
#!/usr/bin/env python
import minx
minx.core.wm().start()If you would like to customize Minx by specifying your own hooks to be able to deal with various events, the initialization and start-up sequence will be a three step procedure as shown below:
#!/usr/bin/env python
import minx
# Define your hook functions
def my_manage_hook(w):
return True # actually, you would do something more useful
# Step one: create window manager object
wm = minx.core.wm()
# Step two: customize using hooks
wm.hooks.add('manage_hook', my_manage_hook)
wm.hooks.add( 'F1', wm.focus_next) # custom key binding
wm.hooks.add('S-F1', wm.focus_prev) # custom key binding
# Step three: start the window manager
wm.start()