Server
The Server class bridges the gap between the low-level library and the high-level library. It saves you from the micromanagement work of the ../PicoGUI protocol, but it isn't an object-oriented abstraction yet. However, some people may prefer to write applications using the Server class only, if they're not comfortable with object-oriented and event-driven programming. This is an acceptable use of the library.
Instantiation
You can instantiate a server with zero to two arguments. The first
argument, when present, is an internet address (anything that is
accepted by the standard python socket
module) and defaults to
"localhost"
. The second argument, when present, is a display
number, and defaults to zero. In the future (WishList), there will
also be support for Unix socket connections, but for now only TCP/IP
is supported.
String, font and bitmap handling
Server objects provide special methods, getString()
. getFont()
and getBitmap()
for handling objects that are stored in the
pgserver. It uses a string representation - the string or bitmap
data itself, for strings and bitmaps, and a font spec in the format
family:size:flags (where multiple flags are separated by
additional colons, and any field may be empty as soon as at least
two colons are present) - and keeps an internal dictionary of
handles. So, if your code uses the same string twice, you don't have
to know about it; just use getString("foo")
and the Server object
will transparently allocate it the first time, and reuse the same
handle the second time.
WishList: getBitmap()
is there but unimplemented, as it would require means of finding the image dimensions. This needs to be discussed.
Constants
The ../PicoGUI protocol uses a lot of special numerical values. When you use the C library, you use constants; but in python, names like PG_S_ALL are, well, not all right.
For most of these values, when dealing with Server objects, you can
instead use a mnemonic string, like "all"
. The Server module looks
up these strings in a hierarchically contextual way, so for example
in server.set(my_widget_id, "side", "all")
the "side" string will
evaluate to 2 and "all" will evaluate to 2048. In
server.set(my_widget_id, "align", "all")
, the "all" string would
however evaluate for 9, because that's the correct value in an
"align" context.
Requests
If you call a method of the Server object with the same name as a function in the RequestsModule (case-insensitive, so you can use CamelCase or betterCamelCase or even ALLCAPS if you wish), it will call this function (after processing all string constants), send the resulting request, wait for an answer, and return it.