Client to awesome communication

[Juul]

An X client can set arbitrary properties on itself which are communicated to the X server and intercepted by the window manager.

For custom properties it is necessary to create the property using the InternAtom function and then the property can be set by the client using ChangeProperty.

The awesome lua API can be used to subscribe to property changes:

To be notified when a property of a client changed:

client.connect_signal("property::name", function(c)
    -- do something
end)

To be notified when a property of a specific client c changed:

c:connect_signal("property::name", function()
    -- do something
end)

from the awesome lua api docs

The xprop utility can be used to inspect the current properties of a client.

Here is a node-x11 example of a client creating and setting a custom property:

// ChangeProperty/GetProperty / PropertyChange event example

var x11 = require('../../lib');
var PropertyChange = x11.eventMask.PropertyChange;

x11.createClient(function(err, display) {
    var X = display.client;
    var root = display.screen[0].root;
    var wid = X.AllocID();
    X.CreateWindow(wid, root, 0, 0, 400, 300, 0, 0, 0, 0, { eventMask: PropertyChange });
    X.MapWindow(wid);

  var foo = "DAMN";

  X.InternAtom(false, foo, function(err, fooAtom) {
    if(err) {
      console.error(err);
      process.exit(1);
    }
    
   
    // mode: 0 replace, 1 prepend, 2 append
    // mode, wid, name, type, format, data
    X.ChangeProperty(0, wid, fooAtom, X.atoms.STRING, 8, 'Hello, NodeJS');
    var interval = setInterval(function() {
           X.ChangeProperty(0, wid, fooAtom, X.atoms.STRING, 8, 'Hello, NodeJS ' + new Date());
    }, 1000);

    X.on('event', function(ev) {
        X.GetProperty(0, wid, fooAtom, X.atoms.STRING, 0, 10000000, function(err, prop) {
            if (prop.type == X.atoms.STRING)
               prop.data = prop.data.toString();
            console.log(prop.data);
        }); 
    });
    X.on('end', function() {
        clearInterval(interval);
    });
  });
});

References

• some info on X11 Properties and Atoms
• official X11 XChangeProperty documentation
• node-x11
• official X11 protocol documentation pdf

[Juul]

The plan is to let fread application change the update method for both their entire region but also for sub-regions and to completely turn off updates and trigger them manually, but there might be a better method than setting properties for triggering the manual updates.

[Juul]

There should be a way for awesome to set this properties on the behalf of applications. That way app developers can bundle a file with the preferred options for their app that are then picked up by awesome (in case they don't want the app to actually deal with the e-paper display in a more dynamic manner). Folks could also share these files for existing applications from the debian repository to make them work as well as possible without modification.