• Development
• zero-nine
• CoreClasses
• CompMatch

CompMatch

A CompMatch is an object representation of a regex used to match windows based on properties. See [WindowMatching] for more details about what kind of things can be matched on the base matching interface.

Evaluating a window

The method evaluate (CompWindow *) will take a CompWindow * and check if it matches the properties set in the CompMatch regex. This returns true if there is a match, or false if not.

Exporting

The method toString () will return a CompString object which represents a string version of the regex. The method isEmpty () will return true if the match is empty, false if there is content in the regex.

Adding criteria

There are a few operator overloads which you can use to extend the regex.

operator &= allows you to add an existing CompMatch object to the CompMatch as a boolean AND criteria, such that the match will now only match windows which fufill the criteria set out in both matches. operator |= allows you to add an existing CompMatch object to the CompMatch as a boolean OR criteria, such that the match will match windows which fufill either one of the two criteria.

operator& returns a CompMatch which is the boolean AND of the CompMatch on the left and right hand sides. operator| returns a CompMatch which is the boolean OR of the CompMatch on the left and right hand sides. operator! returns a CompMatch which is the boolean inverse of the current CompMatch.

Comparing Matches

The operators operator== and operator!= can be used to compare CompMatch objects entirely

Extending the matching interface

You can also create a CompMatch::Expression which can be used to represent a new expression to match windows which your plugin will handle the actual evaluation of that expression. Such a class definition should include a constructor which takes a const CompString & and overloads the bool evaluate (CompWindow *); in CompMatch::Expression. For example:

class StrangeExp :
    public CompMatch::Expression
{
    public:
        StrangeExp (const CompString &str);

        bool evaluate (CompWindow *w);

        bool value;
};

In order to use this expression, you'll need to register to handle a few functions in ScreenInterface

class PluginScreen :
    public PluginClassHandler <PluginScreen, CompScreen>,
    public PluginOptions,
    public ScreenInterface
{
    public:

        PluginScreen (CompScreen *);
        ~PluginScreen ();

        CompMatch::Expression *
        matchInitExp (CompString &value);

        void
        matchExpHandlerChanged ();

        void
        matchPropertyChanged ();
}

The interface function ScreenInterface::matchInitExp (CompString &); allows you to search a CompMatch's internal string for any expression that you might be interested in, and then create a new expression evaluation object based on that string. For example:

CompMatch::Expression *
PluginScreen::matchInitExp (CompString &str)
{
    /* Create a new match object */

    if (str.find ("strange=") == 0)
        return new StrangeExp (str.substr (8));

    return screen->matchInitExp (str);
}

This will look for the criteria "strange=" in the match string and if found creates a new expression StrangeExp for that match, which will later be used to evaluate that bit of the match. So when ::evaluate (CompWindow *); is called on the CompMatch object, your expressions' ::evaulate (CompWindow *) function will also be called.

You'll also need to tell core that your plugin provides a new expression handler. To do this, you need to interface the ::matchExpHandlerChanged () function and call it whenever there are new windows that could be matched (screen->matchExpHandlerChanged ()}.

In your plugin's interface to the ::matchExpHandlerChanged () function, you need to check all the windows and do any other administrative things to ensure your windows can be matched properly. For example:

void
PluginScreen::matchExpHandlerChanged ()
{
    screen->matchExpHandlerChanged ();

    /* match options are up to date after the call to matchExpHandlerChanged */

    foreach (CompWindow *w, screen->windows ())
    {
        if (PluginWindow::get (w)->ok ())
        {
            PluginWindow::get (w)->updateAnythingElse ();

            screen->matchPropertyChanged (w);
        }
    }
}

A call to ::matchPropertyChanged (CompWindow *); another function which you interfaced is made here. This interfaced function allows you to further update windows and other plugin's match properties.