Socket-based GUI for X11 (WIP)
git clone git:// (fast, but not encrypted)
git clone (encrypted, but very slow)
Log | Files | Refs | README | LICENSE

socket_format.txt (5381B)

      1 General:
      3 All requests, responses, errors, and events start with a sequence number.
      4 This number starts at 0 and is incremented by the client with each request.
      5 When the server sends a response, error, or event, it starts with the last
      6 sequence number that the client sent. The client 'ltkc' adds sequence
      7 numbers automatically (perhaps it should hide them in its output as well,
      8 but I'm too lazy to implement that right now). A more advanced client could
      9 use the numbers to properly check that requests really were received.
     10 It isn't clear yet what should happen in the pathological case that the
     11 uint32_t used to store the sequence number overflows before any of the
     12 requests have been handled (i.e. it isn't clear anymore which request a
     13 reply is for). I guess this could technically happen when running over a
     14 broken connection or something, but I don't have a solution right now.
     15 It doesn't seem like a very realistic scenario, though, considering that
     16 all the requests/responses would need to be buffered somewhere, which
     17 would be somewhat unrealistic considering the size of uint32_t.
     19 Requests:
     21 <widget type> <widget id> <command> <args>
     22 > grid grd1 create 2 2
     24 If the command takes a string, the string may contain newlines:
     25 > button btn1 create "I'm a
     26 > button!"
     28 The command line is read until the first newline that is not
     29 within a string.
     31 Double quotes must be escaped in strings, like so:
     32 > button btn1 create "Bla\"bla"
     34 Essentially, the individual messages are separated by line
     35 breaks (\n), but line breaks within strings don't break the
     36 message.
     38 Responses:
     40 Not properly implemented yet.
     41 Currently, all requests that don't generate errors just get the response
     42 "<sequence> res ok". Of course, this will be changed once other response
     43 types are available (e.g. get-text and others).
     45 It might be good to allow ignoring responses to avoid lots of useless traffic.
     46 On the client side, the usage could be similar to XCB's checked/unchecked.
     48 Errors:
     50 err <error number> <number of bad argument or -1> <string description of error>
     52 Events:
     54 event[l] <widget id> <widget type or "widget" for generic events> <event name> [further data]
     56 By default, no events are reported. An event mask has to be set first:
     58 mask-add <widget id> <type> <event name> [lock]
     59 mask-remove <widget id> <type> <event name> [lock]
     60 mask-set <widget id> <type> <event name> [lock]
     62 <type> is either "widget" for generic events (mousepress, mouserelease,
     63 mousemotion, configure, statechange) or the widget type for specific events.
     64 The only specific event currently supported is "press" for both "button"
     65 and "menuentry". Note that currently, only a single mask type can be
     66 added/removed at once instead of combining multiple in one request
     67 (i.e. it isn't possible to do something like "mousepress|mouserelease" yet).
     69 If "lock" is set, the "lock mask" is manipulated instead of the normal one.
     70 If an event occurs that is included in the lock mask, the event will start
     71 with "eventl" instead of "event", and the ltk server blocks until it gets the
     72 request "event-unlock [true/false]" from the client that received the event.
     73 Note that if multiple clients have an event in their lock mask, all of them will
     74 receive the event, but only one of them is chosen to listen for the event-unlock
     75 (basically, this is unspecified behavior that should be avoided). If event-unlock
     76 includes "true", the event is not processed further by the ltk server. If "false"
     77 is given instead, the event is processed as usual by the ltk server.
     79 This was added to allow functionality like in regular GUI toolkits where it is
     80 possible to override events completely. The problem is that it currently isn't
     81 really clear where exactly the command should be emitted and whether it really
     82 makes sense to block all further processing (some processing has to be done
     83 even now for it to make any sense at all). That could possibly lead to very
     84 weird bugs. It also currently isn't possible to do much after locking because
     85 no useful low-level functions for widgets exist (yet?). All in all, I'm not
     86 entirely sure how to make this work nicely so it is actually useful.
     87 Since all of this is pushed over a socket and will probably be able to run
     88 over a network connection eventually, it will also cause problems with latency.
     90 Miscellaneous:
     92 It probably isn't too great for security when anyone can do anything with the
     93 window. Maybe it would be better to allow different clients to have different
     94 permissions? For instance, maybe only the main client could change things, but
     95 other clients could have readonly permissions for things like screenreaders.
     96 That would probably get very over-complicated, though.
     98 I'm also seriously considering switching to a binary socket format. It's nice
     99 to have a text format, but it's an absolute pain to process, because everything
    100 has to be converted from/to text. It also isn't nearly as efficient, especially
    101 if more complicated things are done, such as listening for all mousemotion events.
    102 Of course, it could be made much more efficient with various lookup tables
    103 (it isn't implemented very efficiently currently), but still not nearly as good
    104 as a binary protocol. The idea would be to have a binary protocol, but to still
    105 have something like ltkc that converts the protocol to a text format so simple
    106 shell clients can still exist, but more complicated programs aren't hindered by it.