Context classes
Dragonfly uses context classes to define when grammars and
rules should be active. A context is an object with a
Context.matches()
method which returns True if the
system is currently within that context, and False if it
is not.
The following context classes are available:
Context
– the base class from which all other context classes are derived
AppContext
– class which is based on the application context, i.e. foreground window executable, title, and handle
FuncContext
– class that evaluates a given function/lambda/callable, whose return value is interpreted as a bool, determining whether the context is active
Logical operations
It is possible to modify and combine the behavior of contexts using the Python’s standard logical operators:
- logical AND:
context1 & context2
– all contexts must match- logical OR:
context1 | context2
– one or more of the contexts must match- logical NOT:
~context1
– inversion of when the context matches
For example, to create a context which will match when Firefox is in the foreground, but only if Google Reader is not being viewed:
firefox_context = AppContext(executable="firefox")
reader_context = AppContext(executable="firefox", title="Google Reader")
firefox_but_not_reader_context = firefox_context & ~reader_context
Matching other window attributes
The AppContext
class can be used to match window attributes and
properties other than the title and executable. To do this, pass extra
keyword arguments to the constructor:
# Context for a maximized Firefox window.
maximized_firefox = AppContext(executable="firefox", is_maximized=True)
# Context for a browser in fullscreen mode.
# 'role' and 'is_fullscreen' are X11 only.
fullscreen_browser = AppContext(role="browser", is_fullscreen=True)
# Context for Android Studio or PyCharm using the X11 'cls' property.
AppContext(cls=["jetbrains-studio", "jetbrains-pycharm-ce"])
Class reference
- class AppContext(executable=None, title=None, exclude=False, **kwargs)[source]
Context class using foreground application details.
This class determines whether the foreground window meets certain requirements. Which requirements must be met for this context to match are determined by the constructor arguments.
If multiple strings are passed in a list, True will be returned if the foreground window matches one or more of them. This applies to the executable and title arguments and key word arguments for most window attributes.
- Constructor arguments:
executable (str or list) – (part of) the path name of the foreground application’s executable; case insensitive
title (str or list) – (part of) the title of the foreground window; case insensitive
key word arguments – optional window attributes/properties and expected values; case insensitive
- matches(executable, title, handle)[source]
Indicate whether the system is currently within this context.
- Arguments:
executable (str) – path name to the executable of the foreground application
title (str) – title of the foreground window
handle (int) – window handle to the foreground window
The default implementation of this method simply returns True.
Note
This is generally the method which developers should overload to give derived context classes custom functionality.
- class Context[source]
Base class for other context classes.
This base class implements some basic infrastructure, including what’s required for logical operations on context objects. Derived classes should at least do the following things:
During initialization, set self._str to some descriptive, human readable value. This attribute is used by the
__str__()
method.Overload the
Context.matches()
method to implement the logic to determine when to be active.
The self._log logger objects should be used in methods of derived classes for logging purposes. It is a standard logger object from the logger module in the Python standard library.
- matches(executable, title, handle)[source]
Indicate whether the system is currently within this context.
- Arguments:
executable (str) – path name to the executable of the foreground application
title (str) – title of the foreground window
handle (int) – window handle to the foreground window
The default implementation of this method simply returns True.
Note
This is generally the method which developers should overload to give derived context classes custom functionality.
- class FuncContext(function, **defaults)[source]
Context class that evaluates a given function, whose return value is interpreted as a bool, determining whether the context is active.
The foreground application details are optionally passed to the function as arguments named executable, title, and/or handle, if any/each matches a so-named keyword argument of the function. Default arguments may also be passed to the function, through this class’s constructor.
- Constructor arguments:
function (callable) – the function to call when this context is evaluated
defaults – optional default keyword-values for the arguments with which the function will be called
- matches(executable, title, handle)[source]
Indicate whether the system is currently within this context.
- Arguments:
executable (str) – path name to the executable of the foreground application
title (str) – title of the foreground window
handle (int) – window handle to the foreground window
The default implementation of this method simply returns True.
Note
This is generally the method which developers should overload to give derived context classes custom functionality.
- class LogicAndContext(*children)[source]
- matches(executable, title, handle)[source]
Indicate whether the system is currently within this context.
- Arguments:
executable (str) – path name to the executable of the foreground application
title (str) – title of the foreground window
handle (int) – window handle to the foreground window
The default implementation of this method simply returns True.
Note
This is generally the method which developers should overload to give derived context classes custom functionality.
- class LogicNotContext(child)[source]
- matches(executable, title, handle)[source]
Indicate whether the system is currently within this context.
- Arguments:
executable (str) – path name to the executable of the foreground application
title (str) – title of the foreground window
handle (int) – window handle to the foreground window
The default implementation of this method simply returns True.
Note
This is generally the method which developers should overload to give derived context classes custom functionality.
- class LogicOrContext(*children)[source]
- matches(executable, title, handle)[source]
Indicate whether the system is currently within this context.
- Arguments:
executable (str) – path name to the executable of the foreground application
title (str) – title of the foreground window
handle (int) – window handle to the foreground window
The default implementation of this method simply returns True.
Note
This is generally the method which developers should overload to give derived context classes custom functionality.