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 based on the application context, i.e. foreground window executable, title, and handle

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

Class reference

class AppContext(executable=None, title=None, exclude=False)

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.

Constructor arguments:

• executable (str) – (part of) the path name of the foreground application’s executable; case insensitive
• title (str) – (part of) the title of the foreground window; case insensitive

class Context

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)

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.