tsocket_format.txt - ltk - Socket-based GUI for X11 (WIP)
HTML git clone git://lumidify.org/ltk.git (fast, but not encrypted)
HTML git clone https://lumidify.org/git/ltk.git (encrypted, but very slow)
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
tsocket_format.txt (5381B)
---
1 General:
2
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.
18
19 Requests:
20
21 <widget type> <widget id> <command> <args>
22 > grid grd1 create 2 2
23
24 If the command takes a string, the string may contain newlines:
25 > button btn1 create "I'm a
26 > button!"
27
28 The command line is read until the first newline that is not
29 within a string.
30
31 Double quotes must be escaped in strings, like so:
32 > button btn1 create "Bla\"bla"
33
34 Essentially, the individual messages are separated by line
35 breaks (\n), but line breaks within strings don't break the
36 message.
37
38 Responses:
39
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).
44
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.
47
48 Errors:
49
50 err <error number> <number of bad argument or -1> <string description of error>
51
52 Events:
53
54 event[l] <widget id> <widget type or "widget" for generic events> <event name> [further data]
55
56 By default, no events are reported. An event mask has to be set first:
57
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]
61
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).
68
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.
78
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.
89
90 Miscellaneous:
91
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.
97
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.