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 & context2all contexts must match

logical OR:

context1 | context2one or more of the contexts must match

logical NOT:

~context1inversion 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.