• Immutable Page
  • Info
  • Attachments

Class Definition

static const CompOption::Vector nilValues;

class PropertyWriter
{
    public:

        PropertyWriter ();
        PropertyWriter (CompString propName,
                        CompOption::Vector &readTemplate);
        PropertyWriter (Atom       atom,
                        CompOption::Vector &readTemplate);

        bool updateProperty (Window, CompOption::Vector &, int);
        void deleteProperty (Window);
        const CompOption::Vector & readProperty (Window);
        void setReadTemplate (const CompOption::Vector &);
        const CompOption::Vector & getReadTemplate ();

    private:

        CompOption::Vector mPropertyValues;
        Atom               mAtom;
};

Description

PropertyWriter provides a wrapper to the setting and retrieval of X11 window properties, an otherwise complicated process. It does this through setting a "readback template" to read property data in order and to write it in order specified. Plugins can used this class to easily attach information to an X11 window property, visible to other applications and plugins.

Setting the template

One of the current limitations of the PropertyWriter class is that creating a template involves creating a CompOption::Vector and limiting yourself to the data types allowed within that.

To create the template, simply create a CompOption::Vector of a specific size, and then change the types of each CompOption in the vector to the appropriate type for your template. For example:

    CompOption::Vector atomTemplate;
    
    atomTemplate.resize (4);

    for (int i = 0; i < 4; i++)
    {
        char buf[4];
        snprintf (buf, 4, "%i", i);
        CompString tmpName (buf);

        atomTemplate.at (i).setName (tmpName, CompOption::TypeInt);
    }

    resizeInformationAtom = PropertyWriter ("_COMPIZ_RESIZE_INFORMATION",
                                            atomTemplate);

In this case atomTemplate has 4 integers. Then a new PropertyWriter for the property name "_COMPIZ_RESIZE_INFORMATION_ATOM"" is initialized with the readback template for 4 ints.

Writing to a window property

The updateProperty (Window, CompOption::Vector &, int); function allows you to apply property data according to the template to a window, so you can retrieve it later. For example:

    CompOption::Vector data = resizeInformationAtom.getReadTemplate ();;
    CompOption::Value v;

    if (data.size () != 4)
        return;

    v = geometry.x;
    data.at (0).set (v);

    v = geometry.y;
    data.at (1).set (v);

    v = geometry.width;
    data.at (2).set (v);

    v = geometry.height;
    data.at (3).set (v);

    resizeInformationAtom.updateProperty (w->id (), data, XA_CARDINAL);
}

In this example, the readback template has already been set, and is fetched with ::getReadTemplate. Then the data in the template holders is manipulated and then the property is applied to the CompWindow::id (X11 Handle) with the XA_CARDINAL data type.

Reading from the window property

If you wish to read from the window property, you can call ::readProperty (Window id), which will return the same CompOption::Vector & structure that you set as the read and write template for the property. This template will have the appropriate values from the window property set in each CompOption member.

Deleting the window property

If you decide that you no longer need the data stored in the window property, you can free it by calling ::deleteProperty (Window id). This will remove all property data from that window. Note that window properties are stored in X Server Memory which means that the memory is persistent across compiz instances. If other applications do not need the property data when compiz is not running, you should remove the property data in your window destructor.

/!\ Data stored in window properties is automatically free'd by the X Server when the X Server resource is free\'d

Development/zero-nine/CoreClasses/PropertyWriter (last edited 2010-07-26 02:45:24 by bright-snat)