# PicoGUI Protocol

## Version 21

### Dave Poirier

`<instinc@users.sf.net>`

Copyright © 2002, 2003 Dave Poirier

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license can be acquired electronically from http://www.fsf.org/licenses/fdl.html or by writing to 59 Temple Place, Suite 330,Boston, MA 02111-1307 USA

List of Tables
2-1. data types
2-2. special variables
4-1. PG_APP values
4-2. PG_OWN values
4-3. PG_FM values
4-4. PG_VID values
4-5. PG_TRAVERSE values
4-6. PG_RESPONSE values
4-7. PG_ERRT values
5-1. PG_EVENTCODING values
A-1. PG_GROP values
B-1. PG_WP values
C-1. PGREQ values
E-1. PG_WIDGET values
E-2. PG_DERIVE values
F-1. PG_FSTYLE values
F-2. PG_FR values
G-1. PGKEY values
G-2. PGMOD values
H-1. PGTH_O values
H-2. PGTH_P values
I-1. PGDM values
J-1. PG_WE values
J-2. PG_NWE values
K-1. PGRES values

List of Figures
3-1. struct pghello
4-1. struct pgrequest
4-2. struct pgreqd_attachwidget
4-3. struct pgreqd_chcontext
4-4. struct pgreqd_createwidget
4-5. struct pgreqd_drivermsg
4-6. struct pgreqd_handlestruct
4-7. struct pgreqd_get
4-8. struct pgreqd_getfstyle
4-9. struct pgdata_getfstyle
4-10. struct pgmodeinfo
4-11. struct pgreqd_getresource
4-12. struct pgreqd_infiltersend
4-13. union pg_client_trigger
4-14. struct pgreqd_mkfont
4-15. struct pgreqd_mkinfilter
4-16. struct pgreqd_mkshmbitmap
4-17. struct pgshmbitmap
4-18. struct pgreqd_mkwidget
4-19. struct pgreqd_newbitmap
4-20. struct pgreqd_register
4-21. struct pgreqd_regowner
4-22. struct pgreqd_render
4-23. struct pgreqd_rmcontext
4-24. struct pgreqd_set
4-25. struct pgreqd_setcontext
4-26. struct pgreqd_setinactive
4-27. struct pgreqd_setmode
4-28. struct pgreqd_setpayload
4-29. struct pgreqd_sizetext
4-30. struct pgreqd_thlookup
4-31. struct pgreqd_traversewgt
4-32. struct pgresponse_err
4-33. struct pgresponse_ret
4-34. struct pgresponse_event
4-35. struct pgresponse_data

# Chapter 1. Introduction

This book aims to describe the protocol used to communicate between a PicoGUI server and client; the client part is normally implemented in the cli_c library.

This book is not aimed to be a tutorial to PicoGUI but a rather crude technical manual of its communication protocol.

# Chapter 2. Assumptions

It is assumed that the reader have a good general programming background, good knowledge of data structures and basic network principles.

Unless otherwise stated, every value is stored in network byte order.

The following types are used throughout the document:

Table 2-1. data types

char | signed 8bit value
s8 | signed 8bit value (same as char)
u8 | unsigned 8bit value
s16 | signed 16bit value
u16 | unsigned 16bit value
s32 | signed 32bit value
u32 | unsigned 32bit value

Table 2-2. special variables

dummy | used in various structures to denote bytes of padding

# Chapter 3. Client/Server communication

PicoGUI is a client/server based graphical user interface aimed at embedded devices, where the executable size does matter but a minimum of flexibility is required.

The client application sends requests using "packets" which are sent via sockets. Currently supported protocols include tcp/ip and unix sockets, each described in its own chapter.

A packet is a simple data structure and each request has its own format and packet length. The various packet structures and allowed values are defined in the next chapter (see Chapter 4).

Establishing a connection with the PicoGUI server is conceived of protocol dependant and independant parts.

## 3.1. Establishing a TCP/IP connection with PicoGUI

A TCP/IP connection is established by connecting to the tcp port PicoGUI is listening to, by default this should be 30450+display. A connection to pgserver on display 0 would then be established by connecting to port 30450 while a connection to display 1 would be done on port 30451.

The server may be running on a different host as long as the client is able to determine the IP address on which the server is running.

### 3.1.1. Recommendations for TCP/IP communication

When possible, respect the $PGSERVER environment variable. It uses the X-like syntax of hostname:display, but both halves are optional. For example, on a computer named "menchi", the following are all equal: menchi:0, menchi, :0, localhost, localhost:0, or an empty $PGSERVER.

To decrease latency to pgserver, disable the operating system's TCP delays if they exist. On Linux, there is a TCP_NODELAY option for setsockopt() that can be used to disable its "tinygram prevention". This sacrifices throughput for latency, but in cases where the client is waiting for a server response this increases the client's throughput.

To increase throughput to pgserver by decreasing network overhead, groups of requests can be combined in batch requests. Since the server only sends one return packet for the entire group of requests, it's good for processing large numbers of requests that don't have a useful return value.

## 3.2. Establishing a Unix socket connection with PicoGUI

A Unix socket connection is established by opening the "/var/tmp/.pgui.X" where X is the display number. As an example, if pgserver is running on display 0, the socket name would be "/var/tmp/.pgui.0" while a connection for display 1 would be done using "/var/tmp/.pgui.1"[1]

## 3.3. Protocol Independant Initialization

As soon as the connection is established the server will send to the client a "pghello" packet. The client is then able to enter the cycle of request->response and may do so by sending its first request immediately following the reception of the pghello packet.

### 3.3.1. pghello

Whenever a connection is established, the server immediately sends a `pghello` packet which can be used by the client to determine if the server is compatible or not.

Figure 3-1. struct pghello

    struct pghello {
      u32 magic;
      u16 protover;
      u16 dummy;
    };

The `magic` id is a value of `0x31415926` identifying a PicoGUI server.

The `protover` identifies the protocol version in use. The version number is incremented every time a change is made to the protocol specifications. At the time of writing this document the latest value was `20`.

# Chapter 4. PicoGUI packets

Packets are the basic communication units with a PicoGUI server. They can be used to send requests, receive responses and perform various actions.

You can find the original definitions in `picogui/network.h`, or on their cvs in `pgserver/include/picogui/network.h`.

## 4.1. Requests and Responses

The client performs action by sending "requests" for which the server sends "responses". Note that the server will always send a response packet whether the request was valid or not. The client will be able to determine the outcome of a specific request by looking at the response packets values.[2]

## 4.2. Client Requests

Requests are the only packet type allowed from the client. Each request is composed of a common header and optionally by as many bytes of data as required.

The client proceeds with a request by allocating the required memory for the `pgrequest` structure, filling in the `id`, `size` and `type` fields, then sending it and the associated data (if any) to the server via the network connection.

Figure 4-1. struct pgrequest

    struct pgrequest {
      u32 id;
      u32 size;
      u16 type;
      u16 dummy;
    };

The `id` field is a value used by the client to match the answers returned for a specific request. This value does not have any particular significance for the server and can be set to any value at the discretion of the client.

The `size` field is used to indicate how many bytes of data are attached to the request, excluding the size of the common header.

The `type` is the numerical value identifying the request made (see Appendix C for a complete listing of valid values).

### 4.2.1. PGREQ_APPMSG - Send PG_WE_APPMSG to any widget

    type                 : PGREQ_APPMSG (45)
    client lib equivalent: pgAppMessage()
    additional data      : struct pgreqd_handlestruct
                           data
    server response type : PG_RESPONSE_RET
    server returned data : none

Send a message to a widget owned by any application.

See Figure 4-6 for the format of the `pgreqd_handlestruct` structure.

### 4.2.2. PGREQ_ATTACHWIDGET - Attach widget

    type                 : PGREQ_ATTACHWIDGET (47)
    client lib equivalent: pgAttachWidget()
    additional data      : struct pgreqd_attachwidget
    server response type : PG_RESPONSE_RET
    server returned data : none

Attach a widget to a new parent.

Figure 4-2. struct pgreqd_attachwidget

    struct pgreqd_attachwidget {
      u32 parent;
      u32 widget;
      u16 rship;
      u16 dummy;
    };

The `parent` is the handle of the new parent to set, or zero to detach the widget.

The `widget` is the handle of the widget that needs to be attached.

The `rship` is a `PG_DERIVE_*` constant indicating the new widget's relationship to it's parent (see Table E-2 for a complete listing). This is ignored if there is no parent.

### 4.2.3. PGREQ_BATCH - Batch multiple requests

    type                 : PGREQ_BATCH (18)
    client lib equivalent: none
    additional data      : requests
    server response type : set to response type of the last request
    server returned data : set to returned data of the last request

This request allows to send a batch of multiple requests that will be executed in sequence. If any command fails, its error code is returned and the other commands are ignored. Only the return value from the last command is saved.

The `size` of this request must be set to the sum of all the requests combined.

### 4.2.4. PGREQ_CHCONTEXT - Change a handle's context

    type                 : PGREQ_CHCONTEXT (30)
    client lib equivalent: pgChangeContext()
    additional data      : struct pgreqd_chcontext
    server response type : PG_RESPONSE_RET
    server returned data : none

Change the handle context of an object.

Figure 4-3. struct pgreqd_chcontext

    struct pgreqd_chcontext {
      u32 handle;
      s16 delta;
      u16 dummy;
    };

The `handle` is the handle of the object for which the context must be changed.

The `delta` is a signed value that will modify the current context. A positive delta value increases the object's context, equivalent to adding extra `PGREQ_MKCONTEXT` layers. The delta value may be negative, to 'send' the handle to a higher-level context.

### 4.2.5. PGREQ_CHECKEVENT - Return number of queued events

    type                 : PGREQ_CHECKEVENT (43)
    client lib equivalent: pgCheckEvent()
    additional data      : none
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Check the number of pending events and returns the quantity queued as an integer in `pgresponse_ret.data`.

The PicoGUI server keeps a ring buffer of waiting events for each client connected to it. This request returns the number of events waiting in this buffer. Note that this buffer is usually relatively small. At the time of writing this, it is set to hold 16 events. If the buffer is full, old events will be discarded.

You can use this request if, for some reason, you need to poll PicoGUI events instead of waiting for them. In the middle of a long operation, for example, you may wish to periodically check if the user clicks a cancel button. If this request indicates that there are events waiting, a `PGREQ_WAIT` request will immediately return the oldest queued event.

### 4.2.6. PGREQ_CREATEWIDGET - Create a widget

    type                 : PGREQ_CREATEWIDGET (46)
    client lib equivalent: pgCreateWidget()
    additional data      : struct pgreqd_createwidget
    server response type : PG_RESPONSE_RET
    server returned data : presponse_ret.data

Create a widget, but does not attach it to the parent widget. You can still set the widget's properties and attach child widgets to this one, but the widget cannot be drawn until a `PGREQ_ATTACHWIDGET` request successfully completed.

Then handle of the widget created is returned in `pgresponse_ret.data`.

Figure 4-4. struct pgreqd_createwidget

    struct pgreqd_createwidget {
       u16 type;
       u16 dummy;
    };

Where `type` is a type defined in Table E-1.

### 4.2.7. PGREQ_DRIVERMSG - Send a message to all drivers

    type                 : PGREQ_DRIVERMSG (39)
    client lib equivalent: pgDriverMessage()
    additional data      : struct pgreqd_drivermsg
    server response type : PG_RESPONSE_RET
    server returned data : none

This command can send 'extra' commands that may be hardware-specific, like beeps, cursor blanking, and backlight control.

Figure 4-5. struct pgreqd_drivermsg

    struct pgreqd_drivermsg {
      u32 message;
      u32 param;
    };

Where `message` is a `PGDM_*` constant specying the message type and `param` is the associated data for the specific message type sent (see Section I.1 for a complete listing).

### 4.2.8. PGREQ_DUP - Duplicate an object

    type                 : PGREQ_DUP (27)
    client lib equivalent: pgDup()
    additional data      : struct pgreqd_handlestruct
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Duplicate an object that has a handle. The handle of the new created object is returned in `pgresponse_ret.data`.

Some objects simply can't be duplicated: For example, it would not make sense to duplicate a widget, driver, or theme. [3]

### 4.2.9. PGREQ_FINDTHOBJ - Find theme object by name

    type                 : PGREQ_FINDTHOBJ (48)
    client lib equivalent: pgFindThemeObject()
    additional data      : data (name)
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Find a theme object's ID given its name. Theme objects defined as custom are assigned an ID automatically at load time. These objects can be found with this request as long as each is assigned a unique name property.

The `data` is the name of the property to search for. The theme ID is returned as an integer in `pgresponse_ret.data`.

### 4.2.10. PGREQ_FINDWIDGET - Get widget handle by name

    type                 : PGREQ_FINDWIDGET (42)
    client lib equivalent: pgFindWidget()
    additional data      : data (name)
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Search for a widget by its PG_WP_NAME property. The handle of the found widget is returned in `pgresponse_ret.data`.

Every widget can be given a name by setting it's PG_WP_NAME property to a string handle. This request can search for a widget's handle based on this name. Note that this request will search all widgets, even those not owned by the client.

### 4.2.11. PGREQ_FOCUS - Forces focus to a specified widget

    type                 : PGREQ_FOCUS (25)
    client lib equivalent: pgFocus()
    additional data      : struct pgreqd_handlestruct
    server response type : PG_RESPONSE_RET
    server returned data : none

Give a widget the keyboard focus.

See Figure 4-6 for more info about `pgreqd_handlestruct`.

### 4.2.12. PGREQ_FREE - Free a handle

    type                 : PGREQ_FREE (6)
    client lib equivalent: pgDelete()
    additional data      : struct pgreqd_handlestruct
    server response type : PG_RESPONSE_RET
    server returned data : none

Free the handle specified and delete its associated object.

Figure 4-6. struct pgreqd_handlestruct

    struct pgreqd_handlestruct {
      u32 h;
    };

Where `h` is the handle to free.

### 4.2.13. PGREQ_GET - Get a widget's property

    type                 : PGREQ_GET (8)
    client lib equivalent: pgGetWidget()
    additional data      : struct pgreqd_get
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Get a widget property. The value of the wdiget is returned as a long in `pgresponse_ret.data`.

Figure 4-7. struct pgreqd_get

    struct pgreqd_get {
      u32 widget;
      u16 property;
      u16 dummy;
    };

The `widget` is the handle of the widget to get the property from.

The `property` is a property identifier (see Appendix B for a complete listing).

### 4.2.14. PGREQ_GETCONTEXT - Get the app's current handle context

    type                 : PGREQ_GETCONTEXT (52)
    client lib equivalent: pgGetContext()
    additional data      : none
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Every handle created by a PicoGUI is given a numerical "context" ID, that usually works much like variable scopes in C. This function lets you get the ID that new handles in an app are created at.

### 4.2.15. PGREQ_GETFSTYLE - Get information on a font

    type                 : PGREQ_GETFSTYLE (41)
    client lib equivalent: pgGetFontStyle()
    additional data      : struct pgreqd_getfstyle
    server response type : PG_RESPONSE_DATA
    server returned data : struct pgdata_getfstyle

Get information about a font style

Figure 4-8. struct pgreqd_getfstyle

    struct pgreqd_getfstyle {
      u16 index;
      u16 dummy;
    };

The `index` is a zero-based index to select a font style in the order that the were compiled or loaded into pgserver.

Figure 4-9. struct pgdata_getfstyle

    struct pgdata_getfstyle {
      char name[40];
      unsigned short size;
      unsigned short fontrep;
      unsigned long  flags;
    };

The `name` is the name of the font family. If the first char of the name (Name[0]) is 0, the index requested was invalid. [4]

If the font is bitmapped, the `size` is the height in pixels, otherwise the value is undetermined.

The `fontrep` is a bitmask of `PG_FR_*` constants for the font representation (see Section F.2 for a complete listing).

The `flags` is a bitmask of `PG_FSTYLE_*` constants for the font style itself (see Section F.1 for a complete listing).

### 4.2.16. PGREQ_GETINACTIVE - Get miliseconds of inactivity

    type                 : PGREQ_GETINACTIVE (37)
    client lib equivalent: pgGetInactivity()
    additional data      : none
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Get the number of miliseconds of inactivity. The value is returned as a unsigned long in `pgresponse_ret.data`.

### 4.2.17. PGREQ_GETMODE - Get video mode information

    type                 : PGREQ_GETMODE (22)
    client lib equivalent: pgGetVideoMode()
    additional data      : none
    server response type : PG_RESPONSE_DATA
    server returned data : struct pgmodeinfo

Get information about the current video mode.

Figure 4-10. struct pgmodeinfo

    struct pgmodeinfo {
       u32 flags;
       u16 xres;
       u16 yres;
       u16 lxres;
       u16 lyres;
       u16 bpp;
       u16 dummy;
    };

The `flags` is a bitmask of `PG_VID_*` (see Table 4-4 for a complete listing).

The `xres` and `yres` are the width and height in pixels of the set video mode before any rotation is applied. They should normally not be used by anything else than input/video drivers.

The `lxres` and `lyres` are the logical width and height in pixels of the video mode after the rotation is applied. They represent the actual width and height of the display the user is presented with.

The `bpp` is the bits per pixel value of the currently set video mode.

### 4.2.18. PGREQ_GETPAYLOAD - Get the payload of an object

    type                 : PGREQ_GETPAYLOAD (29)
    client lib equivalent: pgGetPayload()
    additional data      : struct pgreqd_handlestruct
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Get an object's payload. The payload value is returned as an unsigned long in `pgresponse_ret.data`. See Section 4.2.44 for more information.

### 4.2.19. PGREQ_GETRESOURCE - Get a handle to a server-owned resource

    type                 : PGREQ_GETRESOURCE (12)
    client lib equivalent: pgGetServerRes()
    additional data      : struct pgreqd_getresource
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Get the handle associated with a particular server-side resource ID. See

Figure 4-11. struct pgreqd_getresource

    struct pgreqd_getresource {
      u32 id;
    };

The `id` is a PGRES_* constant identifying the resource to retrieve. The value returned should not change over the duration of the client's connection, so it is safe for the client libarary to cache the server resources.

### 4.2.20. PGREQ_GETSTRING - Return a string data

    type                 : PGREQ_GETSTRING (26)
    client lib equivalent: pgGetString()
    additional data      : struct pgreqd_handlestruct
    server response type : PG_RESPONSE_DATA
    server returned data : string

Get the contents of a string handle. See Figure 4-6 for `pgreqd_handlestruct` format.

The string is returned in Unicode UTF-8 encoding, which is compatible with 7-bit ASCII. The string is returned without zero-termination.

### 4.2.21. PGREQ_INFILTERSEND - Send a trigger to an input filter

    type                 : PGREQ_INFILTERSEND (53)
    client lib equivalent: pgInFilterSend()
    additional data      : struct pgreqd_infiltersend
    server response type : PG_RESPONSE_RET
    server returned data : none

Send a trigger to an input filter. This may be used to resend a trigger after it's processed by a client-side input filter, or you could use to create a new trigger to write client-side input drivers.

Figure 4-12. struct pgreqd_infiltersend

    struct pgreqd_infiltersend {
      union pg_client_trigger trig;
    };

The pg_client_trigger union is the same one passed from server to client when a client-side input filter recieves a trigger. For forward compatibility with changes in the server, the client must preserve the entire structure when passing it forward in the input filter chain, even if it doesn't know about all the members. This is the reason for the `array` field in the union. When the client is creating a new trigger, all unused fields should be set to zero. If `infilter_from` is zero, it will be sent to the first filter in the chain, as if it came from a driver.

Figure 4-13. union pg_client_trigger

    /* A client-side representation of triggers, used for client-side input filters
     * and event handling. The whole structure can be viewed as a 64-byte packet of
     * 16 u32 variables, so that more trigger types can be added without disrupting
     * the client libraries or the protocol.
     */
    union pg_client_trigger {
      u32 array[16];
      struct {
        u32 infilter_from;           /* Handle of input filter this is generated by */
        u32 type;                    /* PG_TRIGGER_* constant                       */
        union {                      /* Type-dependent data (must be 14 or less vars each) */

          struct {
    	u32 x,y,btn,pressure;    /* Current status */
    	u32 chbtn;               /* Changed buttons */
    	u32 cursor_handle;
    	u32 is_logical;          /* Nonzero if events are in logical coordinates */
    	u32 ts_calibration;      /* Handle of a calibration string for the touchscreen */
          } mouse;

          struct {
    	u32 key;                 /* PGKEY_* constant */
    	u32 mods;                /* PGMOD_* constant */
    	u32 flags;               /* PG_KF_* constants */
    	u32 consume;             /* Consume event during widget propagation */
          } kbd;

        } u;
      } content;
    };

### 4.2.22. PGREQ_LOADDRIVER - Load input/misc driver

    type                 : PGREQ_LOADDRIVER (40)
    client lib equivalent: pgLoadDriver()
    additional data      : data
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Load a named driver. The name is specified as the `data` argument and the handle to the driver is returned in `pgresponse_ret.data`

### 4.2.23. PGREQ_MKARRAY - Make an array

    type                 : PGREQ_MKARRAY (33)
    client lib equivalent: pgNewArray()
    additional data      : data
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Create a new array object. Each array entry is 32bit and must be sent to the server in the network byte order. The `size` of the request will set the size of the array.

Arrays can be used for various things, like setting the palettes for the terminal widget or giving the polygon gropnode a list of points.

### 4.2.24. PGREQ_MKBITMAP - Load a bitmap

    type                 : PGREQ_MKBITMAP (3)
    client lib equivalent: pgLoadBitmap()
    additional data      : image data
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Load a bitmap in any format supported by pgserver. The contents of the PNG, PNM, JPEG, BMP, etc. is just dumped into the packet and sent to pgserver. The format and size is autodetected, the bitmap converted to the video driver's format, and a handle to the bitmap returned in the `pgresponse_ret.data`. If the format is one not supported by pgserver, an error will be returned.

### 4.2.25. PGREQ_MKCONTEXT - Enter a new context

    type                 : PGREQ_MKCONTEXT (23)
    client lib equivalent: pgEnterContext()
    additional data      : none
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Enter a new context.

PicoGUI uses a context system, similar to a variable's scope in C. Whenever the program leaves a context, all objects created while in that context are deleted. No memory is used by creating a context, and they can be nested a very large number of times. An ID number for the newly entered context is returned.

### 4.2.26. PGREQ_MKCURSOR - Make a new cursor, return the handle

    type                 : PGREQ_MKCURSOR (10)
    client lib equivalent: pgNewCursor()
    additional data      : none
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Create a new cursor object.

PicoGUI drivers or input filters that need a visual representation of the pointing device position should create a cursor object, and pass it along with triggers they send. This cursor creates a sprite independent of any other cursors that may be active.

### 4.2.27. PGREQ_MKFILLSTYLE - Load a fill style

    type                 : PGREQ_MKFILLSTYLE
    client lib equivalent: none
    additional data      : raw fillstyle bytecode
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

This request is used by the compiled theme and should not be used by the client. More information about raw fillstyle bytecode can be found in `pgserver/include/picogui/theme.h`

The handle to the fill style is returned in `pgresponse_ret.data`

### 4.2.28. PGREQ_MKFONT - Make a font descriptor

    type                 : PGREQ_MKFONT (4)
    client lib equivalent: pgNewFont()
    additional data      : struct pgreqd_mkfont
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Create a new font object using the specified font name and properties. The font handle will be returned in `pgresponse_ret.data`

Figure 4-14. struct pgreqd_mkfont

    struct pgreqd_mkfont {
      char name[40];
      u32 style;
      u16 size;
      u16 dummy;
    };

Where `name` is the name of the font to search for. It is possible to specify no specific font name by using name[0]=0.

The `style` value is zero or more PG_FSTYLE_* flags or'ed together (see Section F.1 for a complete listing).

The `size` or height in pixels of the font to search for, or zero for any.

### 4.2.29. PGREQ_MKINFILTER - Create a client-side input filter

    type                 : PGREQ_MKINFILTER (11)
    client lib equivalent: pgNewInFilter()
    additional data      : struct pgreqd_mkinfilter
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Create a client-side input filter, that can intercept and/or modify the server's "triggers" used to send events from drivers to widgets.

Figure 4-15. struct pgreqd_mkinfilter

    struct pgreqd_mkinfilter {
      u32 insert_after;        /* Handle of the filter to insert this one after, or 0
    			    * for this filter to be the first in the chain.
    			    */
      u32 accept_trigs;        /* Mask of triggers that this filter should accept */
      u32 absorb_trigs;        /* Mask of triggers not to automatically pass on   */
    };

The `insert_after` field is the handle of the input filter to insert this one after. If you want it to be the first filter in the chain, this should be zero. You can get handles to the server's built-in filters using PGREQ_GETRESOURCE.

The `accept_trigs` and `absorb_trigs` are, respectively, masks of which triggers to process in this filter and which triggers to prevent from passing on to the next trigger. Note that these two masks are independent of each other, and you can still manually pass on triggers using PGREQ_INFILTERSEND regardless of the setting in `absorb_trigs`.

### 4.2.30. PGREQ_MKSHMBITMAP - Convert a picogui bitmap to a shared memory segment

    type                 : PGREQ_MKSHMBITMAP (54)
    client lib equivalent: pgMakeSHMBitmap()
    additional data      : struct pgreqd_mkshmbitmap
    server response type : PG_RESPONSE_DATA
    server returned data : struct pgshmbitmap

Convert a PicoGUI bitmap to a shared memory segment. This allows very low-level access to the contents of a picogui bitmaps, suitable for 2D games and media players. The application must write data in the video driver's native format and this only works on systems that support shared memory and where the client and server are on the same machine, so this request should be avoided when possible.

Figure 4-16. struct pgreqd_mkshmbitmap

    struct pgreqd_mkshmbitmap {
      u32 bitmap;    /* Bitmap handle to memory map */
      u32 uid;       /* UID of the client process   */
    };

The bitmap handle supplied is converted to a shared memory segment. The supplied UID is used for setting permissions on that memory segment so that the client may access it. After this call, the bitmap can be used as normal in PicoGUI requests, as well as by the client using the information returned:

Figure 4-17. struct pgshmbitmap

    /* Returned by rqh_mkshmbitmap, represents a picogui bitmap
     * that has been exported as shared memory. The returned SHM key
     * will be valid as long as the bitmap it was created from exists.
     * This structure supplies as much information about the bitmap's
     * internal representation as possible, as the client must manipulate
     * the bitmap in our video driver's native format, whatever that
     *  might be. All values here are in network byte order.
     */
    struct pgshmbitmap {
      u32 shm_key;             /* System V shared memory key          */
      u32 shm_length;          /* Length in bytes of shared segment   */

      u32 format;              /* PG_BITFORMAT_* flags                */
      u32 palette;             /* A handle to the associated palette  */

      u16 width;               /* Physical resolution of bitmap       */
      u16 height;              /*   (doesn't account for rotation)    */
      u16 bpp;
      u16 pitch;

      u32 red_mask;            /* For true color modes, masks of bits */
      u32 green_mask;          /*   occupied by all the color fields  */
      u32 blue_mask;
      u32 alpha_mask;

      u16 red_shift;           /* For true color modes, number of     */
      u16 green_shift;         /*   bits each color field is shifted  */
      u16 blue_shift;          /*   left.                             */
      u16 alpha_shift;

      u16 red_length;          /* For true color modes, length        */
      u16 green_length;        /*   in bits of each color field       */
      u16 blue_length;
      u16 alpha_length;
    };

### 4.2.31. PGREQ_MKSTRING - Create a string

    type                 : PGREQ_MKSTRING (5)
    client lib equivalent: pgNewString()
    additional data      : string
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Create a new string object. The string handle will be returned in `pgresponse_ret.data`

The string is submitted in Unicode UTF-8 encoding, which is compatible with 7-bit ASCII. A zero-termination on the end of the string is optional.

### 4.2.32. PGREQ_MKTHEME - Load a compiled theme

    type                 : PGREQ_MKTHEME (9)
    client lib equivalent: pgLoadTheme()
    additional data      : compiled theme data
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Load a compiled theme. The theme ID (or handle) will be returned in `pgresponse_ret.data`

### 4.2.33. PGREQ_MKWIDGET - Make a new widget

    type                 : PGREQ_MKWIDGET (2)
    client lib equivalent: pgNewWidget()
    additional data      : struct pgreqd_mkwidget
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Create a new widget, derived from a parent widget. The handle to the new widget will be returned in `pgresponse_ret.data`

Figure 4-18. struct pgreqd_mkwidget

    struct pgreqd_mkwidget {
      u16 rship;
      u16 type;
      u32 parent;
    };

The `rship` is a `PG_DERIVE_*` constant indicating the new widget's relationship to it's parent (see Table E-2 for a complete listing).

The `type` is a `PG_WIDGET_*` constant for the widget type (see Table E-1 for a complete listing).

The `parent` is the handle of the parent widget.

### 4.2.34. PGREQ_NEWBITMAP - Create a blank bitmap

    type                 : PGREQ_NEWBITMAP (35)
    client lib equivalent: pgCreateBitmap()
    additional data      : struct pgreqd_newbitmap
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Create a blank bitmap object of the specified size. The handle to the new bitmap will be returned in `pgresponse_ret.data`

Figure 4-19. struct pgreqd_newbitmap

    struct pgreqd_newbitmap {
      u16 width;
      u16 height;
    };

Where `width` and `height` for the new image are specified in pixels.

### 4.2.35. PGREQ_PING - Ping request

    type                 : PGREQ_PING (0)
    client lib equivalent: none
    additional data      : none
    server response type : PG_RESPONSE_RET
    server returned data : none

return `success` if the server connection is ok.

### 4.2.36. PGREQ_REGISTER - Register an application

    type                 : PGREQ_REGISTER (15)
    client lib equivalent: pgRegisterApp()
    additional data      : struct pgreqd_register
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Create a root widget of an application, and registers the application in the server's list of running apps. The handle to the root widget created will be returned in the `pgresponse_ret.data`

Figure 4-20. struct pgreqd_register

    struct pgreqd_register {
      u32 name;
      u16 type;
      u16 dummy;
    };

The `name` is the handle of the string to use as the application name. If applicable, it will be displayed in its panelbar.

The `type` is a `PG_APP_*` constant.

Table 4-1. PG_APP values

PG_APP_NORMAL | 1 | Normal application assigned a resizeable window
PG_APP_TOOLBAR | 2 | Toolbar application using a fixed width window without panelbar

### 4.2.37. PGREQ_REGOWNER - Get exclusive privileges

    type                 : PGREQ_REGOWNER (19)
    client lib equivalent: pgRegisterOwner()
    additional data      : struct pgreqd_regowner
    server response type : PG_RESPONSE_RET
    server returned data : none

Register exclusive access to a resource.

Figure 4-21. struct pgreqd_regowner

    struct pgreqd_regowner {
      u16 res;
    };

Where `res` is the `PG_OWN_*` constant value of the resource to get exclusive privileges of.

Table 4-2. PG_OWN values

PG_OWN_KEYBOARD | 1 | Exclusive access to the keyboard
PG_OWN_POINTER | 2 | Exclusive access to the pointer
PG_OWN_SYSEVENTS | 3 | Receive system events like app open/close, click on background, etc.
PG_OWN_DISPLAY | 4 | Exclusive access to the display via `PGREQ_RENDER` requests

NOTE: In the next protocol version the `pgreqd_regowner` structure will be padded to 32bits.

### 4.2.38. PGREQ_RENDER - Render a gropnode to a bitmap

    type                 : PGREQ_RENDER (34)
    client lib equivalent: pgRender()
    additional data      : struct pgreqd_render
                           gropnode data
    server response type : PG_RESPONSE_RET
    server returned data : none

Render a gropnode to a bitmap

Figure 4-22. struct pgreqd_render

    struct pgreqd_render {
      u32 dest;
      u32 groptype;
    };

The `dest` is a bitmap handle to render to. Alternatively, if the app has registered exclusive display access this can be zero to draw directly to the display.

The `groptype` is a `PG_GROP_*` constant indicating the type of gropnode (see below for a list of valid values).

Immediately following the `groptype` the gropnode parameters should follow.

### 4.2.39. PGREQ_RMCONTEXT - Clean up and kill a context

    type                 : PGREQ_RMCONTEXT (24)
    client lib equivalent: pgLeaveContext()
    additional data      : optional struct pgreqd_rmcontext
    server response type : PG_RESPONSE_RET
    server returned data : none

Leave a context. This takes one optional parameter, specifying the context ID. Without that parameter, the context system is treated like a stack. The current context number (the last one returned by PGREQ_MKCONTEXT) is deleted, and the current context number is decremented.

Figure 4-23. struct pgreqd_rmcontext

    struct pgreqd_rmcontext {
      u32 context;
    };

With the optional pgreqd_rmcontext structure, the context specified therein in deleted without effecting the current context number used by PGREQ_MKCONTEXT.

When leaving a context, all objects created within it are deleted.

### 4.2.40. PGREQ_SET - Set a widget's properties

    type                 : PGREQ_SET (7)
    client lib equivalent: pgSetWidget()
    additional data      : struct pgreqd_set
    server response type : PG_RESPONSE_RET
    server returned data : none

Set the properties of a widget.

Figure 4-24. struct pgreqd_set

    struct pgreqd_set {
      u32 widget;
      u32 glob;
      u16 property;
      u16 dummy;
    };

The `widget` is the handle of the widget for which the propertie needs to be set.

The `glob` is the new value to assign to this property.

The `property` is a property identifier (see Appendix B for a complete listing).

### 4.2.41. PGREQ_SETCONTEXT - Set the app's current handle context

    type                 : PGREQ_SETCONTEXT (51)
    client lib equivalent: pgSetContext()
    additional data      : struct pgreqd_setcontext
    server response type : PG_RESPONSE_RET
    server returned data : none

Every handle created by a PicoGUI is given a numerical "context" ID, that usually works much like variable scopes in C. This function lets you manipulate the ID that new handles in an app are created at.

Figure 4-25. struct pgreqd_setcontext

    struct pgreqd_setcontext {
      u32 context;
    };

Where `context` is the new initial handle context ID for this client.

### 4.2.42. PGREQ_SETINACTIVE - Set miliseconds of inactivity

    type                 : PGREQ_SETINACTIVE (38)
    client lib equivalent: pgSetInactivity()
    additional data      : struct pgreqd_setinactive
    server response type : PG_RESPONSE_RET
    server returned data : none

Set the number of milisecond of inactivity.

Figure 4-26. struct pgreqd_setinactive

    struct pgreqd_setinactive {
      u32 time;
    };

Where `time` is the number of miliseconds to use as timer delta.

### 4.2.43. PGREQ_SETMODE - Set video mode/depth/rotation

    type                 : PGREQ_SETMODE (21)
    client lib equivalent: pgSetVideoMode()
    additional data      : struct pgreqd_setmode
    server response type : PG_RESPONSE_RET
    server returned data : none

Change video mode/depth/rotation at runtime.

Figure 4-27. struct pgreqd_setmode

    struct pgreqd_setmode {
      u16 xres;
      u16 yres;
      u16 bpp;
      u16 flagmode;
      u32 flags;
    };

The `xres` and `yres` indicate the width and height, respectively, of the video mode to use. A value of 0 for either of them means to not change the current value.

The `bpp` indicates the depth to use (bits per pixel). A value of 0 indicates to the server to keep the current video mode depth.

The `flagmode` is a `PG_FM_*` constant specifying how to combine flags with the current video flags (see Table 4-3 below).

The `flags` specifies extra optional features that may be present in the video driver. Unsupported flags are ignored. It can be zero or more `PG_VID_*` values or'ed together (see Table 4-4 below).

Table 4-3. PG_FM values

PG_FM_SET | 0 | Sets all flags to the specified value
PG_FM_ON | 1 | Turns on specified flags
PG_FM_OFF | 2 | Turns off specified flags
PG_FM_TOGGLE | 3 | Toggles specified flags

Table 4-4. PG_VID values

PG_VID_FULLSCREEN | 0x0001 | Deprecated
PG_VID_DOUBLEBUFFER | 0x0002 | Deprecated
PG_VID_ROTATE90 | 0x0004 | Rotate the display 90 degree clockwise
PG_VID_ROTATE180 | 0x0008 | Rotate the display 180 degree clockwise
PG_VID_ROTATE270 | 0x0010 | Rotate the display 270 degree clockwise

note: the `PG_VID_ROTATE*` flags are mutually exclusive.

### 4.2.44. PGREQ_SETPAYLOAD - Set an object's payload

    type                 : PGREQ_SETPAYLOAD (28)
    client lib equivalent: pgSetPayload()
    additional data      : struct pgreqd_setpayload
    server response type : PG_RESPONSE_RET
    server returned data : none

Set an object's payload. The "payload" is a client-defined chunk of data attatched to any object that has a handle. Some good uses for this are assigning numerical values to buttons, or even creating a linked list of objects by storing a handle in the payload. It is usually possible for the client to store pointers in the payload, but this is not recommended, for two reasons:

- If the pgserver is buggy or compromised, the client is vulnerable to crashes or data corruption.

- If the client-side architecture uses pointers of more than 32 bits, it will not work.

Figure 4-28. struct pgreqd_setpayload

    struct pgreqd_setpayload {
      u32 h;
      u32 payload;
    };

Where `payload` is the 32bit value to assign as payload and `h` is the handle of the object to assign the payload to.

### 4.2.45. PGREQ_SIZEBITMAP - Find the size of a bitmap

    type                 : PGREQ_SIZEBITMAP (44)
    client lib equivalent: pgSizeBitmap()
    additional data      : struct pgreqd_handlestruct
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Find the width and height of a bitmap matching the provided handle of a valid PicoGUI bitmap object.

The `width` is located in the high 16bits of `pgresponse_ret.data` while the `height` is located in the lowest 16bits of it.

See Figure 4-6 for the `pgreqd_handlestruct` structure format.

### 4.2.46. PGREQ_SIZETEXT - Find the size of text

    type                 : PGREQ_SIZETEXT (17)
    client lib equivalent: pgSizeText()
    additional data      : struct pgreqd_sizetext
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Measure the length and height of a string of text. The `width` is located in the high 16bits of `pgresponse_ret.data` while the `height` is located in the lowest 16bits of it.

Figure 4-29. struct pgreqd_sizetext

    struct pgreqd_sizetext {
      u32 text;
      u32 font;
    };

Where `text` and `font` are handles of the string and font to use respectively.

### 4.2.47. PGREQ_THLOOKUP - Perform a theme lookup

    type                 : PGREQ_THLOOKUP (36)
    client lib equivalent: pgThemeLookup()
    additional data      : struct pgreqd_thlookup
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Retrieve a theme property. The property is returned as an unsigned long in `pgresponse_ret.data`

Figure 4-30. struct pgreqd_thlookup

    truct pgreqd_thlookup {
      u16 object;
      u16 property;
    };

The `object` is a `PGTH_O_*` theme object constant (see Section H.1 for a complete listing).

The `property` is a `PGTH_P_*` theme property constant (see Section H.2 for a complete listing).

### 4.2.48. PGREQ_TRAVERSEWGT - Find widgets after this one

    type                 : PGREQ_TRAVERSEWGT (49)
    client lib equivalent: pgTraverseWidget()
    additional data      : struct pgreqd_traversewgt
    server response type : PG_RESPONSE_RET
    server returned data : pgresponse_ret.data

Finds a widget in relation to another widget. The handle of the widget found will be returned in `pgresponse_ret.data`

Figure 4-31. struct pgreqd_traversewgt

    struct pgreqd_traversewgt {
      u32 widget;
      u16 direction;
      u16 count;
    };

The `widget` is the handle of the widget referenced.

The `direction` is the direction to traverse specified with a `PG_TRAVERSE_*` constant (see Table 4-5 for a complete listing).

The `count` is the number of steps to take in that direction.

Table 4-5. PG_TRAVERSE values

PG_TRAVERSE_CHILDREN | 1 | Starting with this widget's first child, traverse forward
PG_TRAVERSE_FORWARD | 2 |
PG_TRAVERSE_BACKWARD | 3 | Going backwards is much slower than going forward right now
PG_TRAVERSE_CONTAINER | 4 | `count` is the number of container levels to traverse up

### 4.2.49. PGREQ_UNREGOWNER - Give up exclusive privileges

    type                 : PGREQ_UNREGOWNER (20)
    client lib equivalent: pgUnregisterOwner()
    additional data      : struct pgreqd_regowner
    server response type : PG_RESPONSE_RET
    server returned data : none

Unregister exclusive access to a resouce. An error will be returned if the client does not already own the specified resource.

See also Section 4.2.37 and Table 4-2.

### 4.2.50. PGREQ_UPDATE - Update the screen

    type                 : PGREQ_UPDATE (1)
    client lib equivalent: pgUpdate()
    additional data      : none
    server response type : PG_RESPONSE_RET
    server returned data : none

Redraw portions of the screen if necessary. This forces all unsent packets to be flushed to the server, and instructs the server to draw changed areas of the screen.

### 4.2.51. PGREQ_UPDATEPART - Update a subtree of widgets

    type                 : PGREQ_UPDATEPART (32)
    client lib equivalent: pgSubUpdate()
    additional data      : struct pgreqd_handlestruct
    server response type : PG_RESPONSE_RET
    server returned data : none

Update a subsection of the screen.

The given widget and all other widgets contained within it are redrawn if necessary. The request buffer is flushed and the section is redrawn independantly and immediately.

This function is recommended for animation. Areas of the screen other than the specified widget and its children are never updated, and SubUpdates can occur in toolbars even while a popup dialog is onscreen.

### 4.2.52. PGREQ_WAIT - Wait for an event

    type                 : PGREQ_WAIT (13)
    client lib equivalent: pgEvent()
    additional data      : none
    server response type : PG_RESPONSE_EVENT
    server returned data : depends of the event type

Indicate to the server that the client is waiting for an event, if any event is available it will be sent as a response immediately, otherwise the client is placed in a waiting queue.

If any request is received by the server after a `PGREQ_MKWAIT`, the client will be removed from the wait queue and the new request wil be processed. In the event where the new request would be a `PGREQ_MKWAIT`, the client is sent back in the waiting queue after discarding the previous request.

### 4.2.53. PGREQ_WRITECMD - Send a command to a widget

    type                 : PGREQ_WRITECMD (31)
    client lib equivalent: pgWriteCmd()
    additional data      : struct pgreqd_handlestruct
                           data
    server response type : PG_RESPONSE_RET
    server returned data : none

Write a widget-defined command to a widget. For example, this can be used to send commands to a terminal, textbox or canvas widget.

The first 32 bits of the data are the command code; after that, follows a number of 16-bit arguments to that command. The meaning of the command and arguments is defined by the widget.

See Figure 4-6 for the `pgreqd_handlestruct` format.

### 4.2.54. PGREQ_WRITETO - Write data to a widget

    type                 : PGREQ_WRITEDATA (55)
    client lib equivalent: pgWriteData()
    additional data      : struct pgreqd_handlestruct
                           data
    server response type : PG_RESPONSE_RET
    server returned data : none

Write a chunk of widget-defined data to a widget. For example, this can be used to send text to a textbox widget.

See Figure 4-6 for the `pgreqd_handlestruct` format.

## 4.3. Server Responses

After each request, or once after a requests batch, the PicoGUI server sends a response. All responses are at least 32bits long from which the first 16bits can be used to identify the type of response received. The following table list the various types:

Table 4-6. PG_RESPONSE values

PG_RESPONSE_ERR | 1 | response is a pgresponse_err struct
PG_RESPONSE_RET | 2 | response is a pgresponse_ret struct
PG_RESPONSE_EVENT | 3 | response is a pgresponse_event struct
PG_RESPONSE_DATA | 4 | response is a pgresponse_data struct

### 4.3.1. PG_RESPONSE_ERR - Error Code

Sent only if an error occured, the request could not be completed for some reason. The response include a general error type, the id of the requests for which this packet is sent, as well as a text message. [5]

Figure 4-32. struct pgresponse_err

    struct pgresponse_err {
      u16 type;
      u16 errt;
      u16 msglen;
      u16 dummy;
      u32 id;
    };

The `type` is the `PG_RESPONSE_ERR`(1) constant identifying the packet as a `pgresponse_err`.

The `errt` is a broad error category which value is a `PG_ERRT_*` constant (see Table 4-7 for a complete listing).

The `msglen` is the length in bytes of the associated text error message following immediately the `pgresponse_err`.

The `id` is the client provided id that was located in the `pgrequest` causing the error.

Table 4-7. PG_ERRT values

PG_ERRT_NONE | 0x0000 | No error condition
PG_ERRT_MEMORY | 0x0101 | Error allocating memory
PG_ERRT_IO | 0x0200 | Filesystem, operating system, or other IO error
PG_ERRT_NETWORK | 0x0300 | Network (or IPC) communication error
PG_ERRT_BADPARAM | 0x0400 | Invalid parameters
PG_ERRT_HANDLE | 0x0500 | Invalid handle ID, type, or ownership
PG_ERRT_INTERNAL | 0x0600 | Shouldn't happen (tell a developer!)
PG_ERRT_BUSY | 0x0700 | Try again later?
PG_ERRT_FILEFMT | 0x0800 | Error in a loaded file format (theme files, bitmaps)
PG_ERRT_CLIENT | 0x8000 | An error caused by the client lib, not the server

### 4.3.2. PG_RESPONSE_RET - 32bit Value

Sent by the server after most requests where a single 32bit value is returned, such as a widget/string handle.

Figure 4-33. struct pgresponse_ret

    struct pgresponse_ret {
      u16 type;
      u16 dummy;
      u32 id;
      u32 data;
    };

The `type` is the `PG_RESPONSE_RET`(2) constant identifying the response as a `pgresponse_ret`.

The `id` is the client provided id that was located in the `pgrequest` for which the value is returned.

The `data` is a 32bit value specific to the type of request made. More often than note a widget/string handle.

### 4.3.3. PG_RESPONSE_EVENT - Event

This response is returned after a `PGREQ_WAIT` request.

Figure 4-34. struct pgresponse_event

    struct pgresponse_event {
      u16 type;
      u16 event;
      u32 from;
      u32 param;
    };

The `type` is the `PG_RESPONSE_EVENT`(3) constant identifying the response as a `pgresponse_event`.

The `event` is a `PG_WE_*` or `PG_NWE_*` constant identyfing the type of event received (see Section J.1 and Section J.2 respectively for complete listings).

The `from` is a a widget handle if the event is a `PG_WE_*` or 0 if it's one of the `PG_NWE_*`.

The `param` contains the packed data for the event, which varies with the event type. It is explained in more detail in Chapter 5

### 4.3.4. PG_RESPONSE_DATA - Variable Length Data

Sent by the server whenever more than 32bit of data needs to be returned, such as after a `PGREQ_GETSTRING` (see Section 4.2.20).

Figure 4-35. struct pgresponse_data

    struct pgresponse_data {
      u16 type;
      u16 dummy;
      u32 id;
      u32 size;
    };

The `type` is the `PG_RESPONSE_DATA`(4) constant identifying the response as a `pgresponse_data`.

The `id` is the client provided id that was located in the `pgrequest` for which the data is returned.

The `size` is the number of bytes of data following the `pgresponse_data` structure.

# Chapter 5. Event Parameters

Events can return various types of data that the client library will separate out for the app. To indicate a type of encoding, the `PG_WE_` constant is logically or'ed with one of these:

Table 5-1. PG_EVENTCODING values

PG_EVENTCODING_PARAM | 0x000 | Just a 32-bit parameter
PG_EVENTCODING_XY | 0x100 | X,Y coordinates packed into param
PG_EVENTCODING_PNTR | 0x200 | Mouse parameters (x,y,btn,chbtn)
PG_EVENTCODING_DATA | 0x300 | Arbitrary data block
PG_EVENTCODING_KBD | 0x400 | Keyboard params
PG_EVENTCODING_MASK | 0xF00 |

Determining the parameter encoding can thus be resumed in the following operations:

      1.) Do a bitwise AND between pgresponse_event.event and PG_EVENTCODING_MASK
      2.) Compare the result with the PG_EVENTCODING_* values

## 5.1. PG_EVENTCODING_PARAM - 32bit Parameter

The `pgresponse_event.param` is a 32bit value, no special decoding required.

## 5.2. PG_EVENTCODING_XY - X,Y Coordinates

Mostly returned with width/size of bitmaps and/or string size. The X coordinate (or width) is located in the highest 16bits while the Y coordinate (or height) is located in the lowest 16bits.

    x = pgresponse_event.param >> 16;
    y = pgresponse_event.param & 0xFFFF;

## 5.3. PG_EVENTCODING_PNTR - Pointer Parameters (x,y,btn,chbtn)

Used to return the x,y absolute coordinates as well as the pressed buttons bitmask (btn) and changed buttons bitmask since last event (chbtn). This will be generated whenever the pointing device is moved or one of its button is pressed or released.

The `x` is located in bits 11-0 of `pgresponse_event.param` and represents the absolute x coordinate of the new pointer location.

The `y` is located in bits 23-12 of `pgresponse_event.param` and represents the absolute y coordinate of the new pointer location.

The `btn` is the bitmask of the currently pressed buttons and is located in bits 27-24 of `pgresponse_event.param`.

The `chbtn` is the bitmaks of the buttons which changed status since the last event and is located in bits 31-28 of `pgresponse_event.param`.

    x = pgresponse_event.param & 0xFFF;
    y = (pgresponse_event.param >> 12) & 0xFFF;
    btn = (pgresponse_event.param >> 24) & 0xF;
    chbtn = (pgresponse_event.param >> 28) & 0xF;

## 5.4. PG_EVENTCODING_DATA - Arbitrary data block

Used to return data of variable length. The `pgresponse_event.param` represents the number of bytes of data located after the `pgresponse_event` structure.

## 5.5. PG_EVENTCODING_KBD - Keyboard Parameters

Used to return pressed/released keys and the current status of the keyboard modifiers.

The `keys` is located in the lowest 16bits of `pgresponse_event.param`. For `PG_WE_KBD_CHAR`, the value is an ASCII/Unicode character. For `PG_WE_KBD_KEYUP` and `PG_WE_KBD_KEYDOWN`, it is a `PGKEY_*` constant

# Appendix A. Gropnode Types

Table A-1. PG_GROP values

PG_GROP_RECT | 0x00 |
PG_GROP_FRAME | 0x10 |
PG_GROP_SLAB | 0x20 |
PG_GROP_BAR | 0x30 |
PG_GROP_PIXEL | 0x40 |
PG_GROP_LINE | 0x50 |
PG_GROP_ELLIPSE | 0x60 |
PG_GROP_FELLIPSE | 0x70 |
PG_GROP_TEXT | 0x04 | Param: string
PG_GROP_BITMAP | 0x14 | Param: bitmap
PG_GROP_TILEBITMAP | 0x24 | Param: bitmap
PG_GROP_FPOLYGON | 0x34 | Param: array
PG_GROP_GRADIENT | 0x0C | Param: angle, c1, c2
PG_GROP_TEXTGRID | 0x1C | Param: string, bufferw, offset
PG_GROP_NOP | 0x03 |
PG_GROP_RESETCLIP | 0x13 | Reset clip to whole divnode
PG_GROP_SETOFFSET | 0x01 | this grop's rect sets offset
PG_GROP_SETCLIP | 0x11 | this grop's rect sets clipping
PG_GROP_SETSRC | 0x21 | this grop's rect sets src_*
PG_GROP_SETMAPPING | 0x05 | Param: PG_MAP_* const
PG_GROP_SETCOLOR | 0x07 | Param: pgcolor
PG_GROP_SETFONT | 0x17 | Param: font
PG_GROP_SETLGOP | 0x27 | Param: lgop
PG_GROP_SETANGLE | 0x37 | Param: angle in degrees
PG_GROP_VIDUPDATE | 0x800 | Forces a video update

# Appendix B. Property Types

Latest values may be found in `picogui/constants.h` or on cvs in `pgserver/include/picogui/constants.h`

Table B-1. PG_WP values

PG_WP_SIZE | 1 |
PG_WP_SIDE | 2 |
PG_WP_ALIGN | 3 |
PG_WP_BGCOLOR | 4 |
PG_WP_COLOR | 5 |
PG_WP_SIZEMODE | 6 |
PG_WP_TEXT | 7 |
PG_WP_FONT | 8 |
PG_WP_TRANSPARENT | 9 |
PG_WP_BORDERCOLOR | 10 |
PG_WP_BITMAP | 12 |
PG_WP_LGOP | 13 |
PG_WP_VALUE | 14 |
PG_WP_BITMASK | 15 |
PG_WP_BIND | 16 |
PG_WP_SCROLL_X | 17 | Horizontal and vertical scrolling amount
PG_WP_SCROLL_Y | 18 |
PG_WP_HOTKEY | 19 |
PG_WP_EXTDEVENTS | 20 | For buttons, a mask of extra events to send
PG_WP_DIRECTION | 21 |
PG_WP_ABSOLUTEX | 22 | read-only, relative to screen
PG_WP_ABSOLUTEY | 23 |
PG_WP_ON | 24 | on-off state of button/checkbox/etc
PG_WP_STATE | 25 | Deprecated! Use PG_WP_THOBJ instead
PG_WP_THOBJ | 25 | Set a widget's theme object
PG_WP_NAME | 26 | A widget's name (for named containers, etc)
PG_WP_PUBLICBOX | 27 | Set to 1 to allow other apps to make widgets in this container
PG_WP_DISABLED | 28 | For buttons, grays out text and prevents clicking
PG_WP_MARGIN | 29 | For boxes, overrides the default margin
PG_WP_TEXTFORMAT | 30 | For the textbox, defines a format for PG_WP_TEXT. fourCC format, with optional preceeding '+' to prevent erasing existing data, just append at the cursor position
PG_WP_TRIGGERMASK | 31 | Mask of extra triggers accepted (self->trigger_mask)
PG_WP_HILIGHTED | 32 | Widget property to hilight a widget and all it's children
PG_WP_SELECTED | 33 | List property to select a row.
PG_WP_SELECTED_HANDLE | 34 | List property to return a handle to the selected row
PG_WP_AUTOSCROLL | 35 | For the textbox or terminal, scroll to any new text that's inserted
PG_WP_LINES | 36 | Height, in lines
PG_WP_PREFERRED_W | 37 | Read only (for now) properties to get any widget's preferred size
PG_WP_PREFERRED_H | 38 |
PG_WP_PANELBAR | 39 | Read-only property for panels returns a handle to its embedded panelbar widget
PG_WP_AUTO_ORIENTATION | 40 | Automatically reorient child widgets when PG_WP_SIDE changes
PG_WP_THOBJ_BUTTON | 41 | These four theme properties set the theme objects used for the
PG_WP_THOBJ_BUTTON_HILIGHT | 42 | three possible states of the button widget.
PG_WP_THOBJ_BUTTON_ON | 43 |
PG_WP_THOBJ_BUTTON_ON_NOHILIGHT | 44 |
PG_WP_PANELBAR_LABEL | 45 | More read-only panelbar properties to get the built-in panelbar widgets
PG_WP_PANELBAR_CLOSE | 46 |
PG_WP_PANELBAR_ROTATE | 47 |
PG_WP_PANELBAR_ZOOM | 48 |
PG_WP_BITMAPSIDE | 49 |
PG_WP_PASSWORD | 50 |
PG_WP_HOTKEY_FLAGS | 51 | Keyboard event flags for the hotkey (PG_KF_*)
PG_WP_HOTKEY_CONSUME | 52 | Flag indicating whether to consume the key event when a hotkey comes in
PG_WP_WIDTH | 53 | A read only property for all widgets (use PG_WP_SIZE to change the size). Always in pixels
PG_WP_HEIGHT | 54 | A read only property for all widgets (use PG_WP_SIZE to change the size). Always in pixels
PG_WP_SPACING | 55 | Override the normal spacing between buttons
PG_WP_MINIMUM | 56 | Used by the panelbar widget to set minimum size
PG_WP_MULTILINE | 57 | Turn this off on the textbox widget to get a single line textbox
PG_WP_SELECTION | 58 | Selected text in the textedit widget
PG_WP_READONLY | 59 |
PG_WP_INSERTMODE | 60 | Set to a PG_INSERT_* constant, for textbox widget
PG_WP_TYPE | 61 | Return the type of the widget (PG_WIDGET_*)
PG_WP_TAB | 62 | The tab associated with a tabpage widget
PG_WP_TAB_BAR | 63 | The tab bar associated with a tabpage widget
PG_WP_POPUP_IS_MENU | 64 | Popup is menu flag
PG_WP_POPUP_IS_SUBMENU | 65 | Popup is submenu flag
PG_WP_CURSOR_POSITION | 66 | Textbox cursor position

# Appendix C. Request Types

Request types are used by the client to ask the server to perform an action, and used by the server to determine which action to perform.

Latest values may be found in `picogui/network.h` or on cvs in `pgserver/include/picogui/network.h`

Table C-1. PGREQ values

PGREQ_PING | 0 | Simply return if server is ok
PGREQ_UPDATE | 1 | Call update()
PGREQ_MKWIDGET | 2 | Make a widget, return handle
PGREQ_MKBITMAP | 3 | Make a bitmap, return handle
PGREQ_MKFONT | 4 | Make a fontdesc, return handle
PGREQ_MKSTRING | 5 | Make a string, return handle
PGREQ_FREE | 6 | Free a handle
PGREQ_SET | 7 | Set a widget param
PGREQ_GET | 8 | Get a widget param, return it
PGREQ_MKTHEME | 9 | Load a compiled theme
PGREQ_MKCURSOR | 10 | Make a cursor, return handle
PGREQ_MKINFILTER | 11 | Make an input filter, return handle
PGREQ_GETRESOURCE | 12 | Get a handle to a server-owned resource
PGREQ_WAIT | 13 | Wait for an event
PGREQ_MKFILLSTYLE | 14 | Load a fill style, return handle
PGREQ_REGISTER | 15 | Register a new application
PGREQ_MKPOPUP | 16 | Create a popup root widget
PGREQ_SIZETEXT | 17 | Find the size of text
PGREQ_BATCH | 18 | Execute many requests
PGREQ_REGOWNER | 19 | Get exclusive privileges
PGREQ_UNREGOWNER | 20 | Give up exclusive privileges
PGREQ_SETMODE | 21 | Set video mode/depth/rotation
PGREQ_GETMODE | 22 | Return a modeinfo struct
PGREQ_MKCONTEXT | 23 | Enter a new context
PGREQ_RMCONTEXT | 24 | Clean up and kills the context
PGREQ_FOCUS | 25 | Force focus to specified widget
PGREQ_GETSTRING | 26 | Return a RESPONSE_DATA
PGREQ_DUP | 27 | Duplicate an object
PGREQ_SETPAYLOAD | 28 | Set an object's payload
PGREQ_GETPAYLOAD | 29 | Get an object's payload
PGREQ_CHCONTEXT | 30 | Change a handle's context
PGREQ_WRITECMD | 31 | Send a command to a widget
PGREQ_UPDATEPART | 32 | Update subtree defined by wgt
PGREQ_MKARRAY | 33 | Make a array, return handle
PGREQ_RENDER | 34 | Render gropnode(s) to a bitmap
PGREQ_NEWBITMAP | 35 | Create a blank bitmap
PGREQ_THLOOKUP | 36 | Perform a theme lookup
PGREQ_GETINACTIVE | 37 | Get milliseconds of inactivity
PGREQ_SETINACTIVE | 38 | Set milliseconds of inactivity
PGREQ_DRIVERMSG | 39 | Send a message to all drivers
PGREQ_LOADDRIVER | 40 | Load input/misc (not video)
PGREQ_GETFSTYLE | 41 | Get info on a font style
PGREQ_FINDWIDGET | 42 | Get widget handle by name
PGREQ_CHECKEVENT | 43 | Return number of queued events
PGREQ_SIZEBITMAP | 44 | Find the size of a bitmap
PGREQ_APPMSG | 45 | Send PG_WE_APPMSG to any widget
PGREQ_CREATEWIDGET | 46 | Create widget
PGREQ_ATTACHWIDGET | 47 | Attach widget
PGREQ_FINDTHOBJ | 48 | Find theme object by name
PGREQ_TRAVERSEWGT | 49 | Find widgets relative to a specified widget
PGREQ_MKTEMPLATE | 50 | Load a widget template, return the handle
PGREQ_SETCONTEXT | 51 | Set the app's current handle context
PGREQ_GETCONTEXT | 52 | Get the app's current handle context
PGREQ_INFILTERSEND | 53 | Send a trigger to an input filter
PGREQ_MKSHMBITMAP | 54 | Convert a picogui bitmap to a shared memory segment
PGREQ_WRITEDATA | 55 | Stream data to a widget

# Appendix D. Trigger Types

(soon)

# Appendix E. Widget Types

(soon)

Table E-1. PG_WIDGET values

PG_WIDGET_TOOLBAR | 0 |
PG_WIDGET_LABEL | 1 |
PG_WIDGET_SCROLL | 2 |
PG_WIDGET_INDICATOR | 3 |
PG_WIDGET_BUTTON | 5 |
PG_WIDGET_PANEL | 6 |
PG_WIDGET_POPUP | 7 |
PG_WIDGET_BOX | 8 |
PG_WIDGET_FIELD | 9 |
PG_WIDGET_BACKGROUND | 10 |
PG_WIDGET_MENUITEM | 11 | A variation on button
PG_WIDGET_TERMINAL | 12 | A full terminal emulator
PG_WIDGET_CANVAS | 13 |
PG_WIDGET_CHECKBOX | 14 | Another variation of button
PG_WIDGET_FLATBUTTON | 15 | Yet another customized button
PG_WIDGET_LISTITEM | 16 | Still yet another...
PG_WIDGET_SUBMENUITEM | 17 | Menuitem with a submenu arrow
PG_WIDGET_RADIOBUTTON | 18 | Like a check box, but exclusive
PG_WIDGET_TEXTBOX | 19 | Client-side text layout
PG_WIDGET_PANELBAR | 20 | Draggable bar and container
PG_WIDGET_SIMPLEMENU | 21 | Popup-menu with only text items in it
PG_WIDGET_DIALOGBOX | 22 | Popup box with standard dialog titlebar
PG_WIDGET_MESSAGEDIALOG | 23 | Dialogbox that displays a message to the user
PG_WIDGET_SCROLLBOX | 24 | Container with built-in horizontal and vertical scrolling

Table E-2. PG_DERIVE values

PG_DERIVE_AFTER | 1 |
PG_DERIVE_INSIDE | 2 |
PG_DERIVE_BEFORE | 3 |

# Appendix F. Font Constants

## F.1. Font Styles

These font style constants can be used as the property flags parameter of a PGREQ_FINDFONT and PGREQ_MKFONT request

Table F-1. PG_FSTYLE values

PG_FSTYLE_FIXED | (1<<0) | Fixed width
PG_FSTYLE_DEFAULT | (1<<1) | The default font in its category, fixed or proportional.
PG_FSTYLE_SYMBOL | (1<<2) | Font contains nonstandard chars and will not be chosen unless specifically requested
PG_FSTYLE_SUBSET | (1<<3) | Font does not contain all the ASCII chars before 127, and shouldn't be used unless requested
PG_FSTYLE_EXTENDED | (1<<4) | (deprecated) Contains international characters above 127
PG_FSTYLE_IBMEXTEND | (1<<5) | (deprecated) Has IBM-PC extended characters
PG_FSTYLE_DOUBLESPACE | (1<<7) | Add extra space between lines
PG_FSTYLE_BOLD | (1<<8) | Use or simulate a bold version of the font
PG_FSTYLE_ITALIC | (1<<9) | Use or simulate an italic version of the font
PG_FSTYLE_UNDERLINE | (1<<10) | Underlined text
PG_FSTYLE_STRIKEOUT | (1<<11) | Strikeout, a line through the middle of the text
PG_FSTYLE_GRAYLINE | (1<<12) | deprecated
PG_FSTYLE_FLUSH | (1<<14) | Disable the margin that PicoGUI puts around text
PG_FSTYLE_DOUBLEWIDTH | (1<<15) | Add extra space between characters
PG_FSTYLE_ITALIC2 | (1<<16) | Twice the slant of the default italic
PG_FSTYLE_ENCODING_ISOLATIN1 | (1<<4) | ISO Latin-1 encoding
PG_FSTYLE_ENCODING_IBM | (1<<5) | IBM-PC extended characters
PG_FSTYLE_ENCODING_UNICODE | (1<<17) | Unicode encoding

## F.2. Font Representations

These flags can be returned in a response to a PGREQ_GETFSTYLE, indicating supported methods of graphically representing a font.

Currently this can only indicate whether a font has built-in bold, italic, or bolditalic bitmaps, but in the future could be used to indicate whether a style is bitmapped or scalable.

Table F-2. PG_FR values

PG_FR_BITMAP_NORMAL | (1<<0) | Normal bitmapped font
PG_FR_BITMAP_BOLD | (1<<1) | Bitmapped font with bold
PG_FR_BITMAP_ITALIC | (1<<2) | Bitmapped font with italic
PG_FR_BITMAP_BOLDITALIC | (1<<3) | Bitmapped font with bold and italic
PG_FR_SCALABLE | (1<<4) | Wishful thinking :)

# Appendix G. Keyboard Constants

Table G-1. PGKEY values

PGKEY_BACKSPACE | 8 |
PGKEY_TAB | 9 |
PGKEY_CLEAR | 12 |
PGKEY_RETURN | 13 |
PGKEY_PAUSE | 19 |
PGKEY_ESCAPE | 27 |
PGKEY_SPACE | 32 |
PGKEY_EXCLAIM | 33 |
PGKEY_QUOTEDBL | 34 |
PGKEY_HASH | 35 |
PGKEY_DOLLAR | 36 |
PGKEY_PERCENT | 37 |
PGKEY_AMPERSAND | 38 |
PGKEY_QUOTE | 39 |
PGKEY_LEFTPAREN | 40 |
PGKEY_RIGHTPAREN | 41 |
PGKEY_ASTERISK | 42 |
PGKEY_PLUS | 43 |
PGKEY_COMMA | 44 |
PGKEY_MINUS | 45 |
PGKEY_PERIOD | 46 |
PGKEY_SLASH | 47 |
PGKEY_0 | 48 |
PGKEY_1 | 49 |
PGKEY_2 | 50 |
PGKEY_3 | 51 |
PGKEY_4 | 52 |
PGKEY_5 | 53 |
PGKEY_6 | 54 |
PGKEY_7 | 55 |
PGKEY_8 | 56 |
PGKEY_9 | 57 |
PGKEY_COLON | 58 |
PGKEY_SEMICOLON | 59 |
PGKEY_LESS | 60 |
PGKEY_EQUALS | 61 |
PGKEY_GREATER | 62 |
PGKEY_QUESTION | 63 |
PGKEY_AT | 64 |
PGKEY_LEFTBRACKET | 91 |
PGKEY_BACKSLASH | 92 |
PGKEY_RIGHTBRACKET | 93 |
PGKEY_CARET | 94 |
PGKEY_UNDERSCORE | 95 |
PGKEY_BACKQUOTE | 96 |
PGKEY_a | 97 |
PGKEY_b | 98 |
PGKEY_c | 99 |
PGKEY_d | 100 |
PGKEY_e | 101 |
PGKEY_f | 102 |
PGKEY_g | 103 |
PGKEY_h | 104 |
PGKEY_i | 105 |
PGKEY_j | 106 |
PGKEY_k | 107 |
PGKEY_l | 108 |
PGKEY_m | 109 |
PGKEY_n | 110 |
PGKEY_o | 111 |
PGKEY_p | 112 |
PGKEY_q | 113 |
PGKEY_r | 114 |
PGKEY_s | 115 |
PGKEY_t | 116 |
PGKEY_u | 117 |
PGKEY_v | 118 |
PGKEY_w | 119 |
PGKEY_x | 120 |
PGKEY_y | 121 |
PGKEY_z | 122 |
PGKEY_LEFTBRACE | 123 |
PGKEY_PIPE | 124 |
PGKEY_RIGHTBRACE | 125 |
PGKEY_TILDE | 126 |
PGKEY_DELETE | 127 |
PGKEY_WORLD_0 | 160 | 0xA0
PGKEY_WORLD_1 | 161 |
PGKEY_WORLD_2 | 162 |
PGKEY_WORLD_3 | 163 |
PGKEY_WORLD_4 | 164 |
PGKEY_WORLD_5 | 165 |
PGKEY_WORLD_6 | 166 |
PGKEY_WORLD_7 | 167 |
PGKEY_WORLD_8 | 168 |
PGKEY_WORLD_9 | 169 |
PGKEY_WORLD_10 | 170 |
PGKEY_WORLD_11 | 171 |
PGKEY_WORLD_12 | 172 |
PGKEY_WORLD_13 | 173 |
PGKEY_WORLD_14 | 174 |
PGKEY_WORLD_15 | 175 |
PGKEY_WORLD_16 | 176 |
PGKEY_WORLD_17 | 177 |
PGKEY_WORLD_18 | 178 |
PGKEY_WORLD_19 | 179 |
PGKEY_WORLD_20 | 180 |
PGKEY_WORLD_21 | 181 |
PGKEY_WORLD_22 | 182 |
PGKEY_WORLD_23 | 183 |
PGKEY_WORLD_24 | 184 |
PGKEY_WORLD_25 | 185 |
PGKEY_WORLD_26 | 186 |
PGKEY_WORLD_27 | 187 |
PGKEY_WORLD_28 | 188 |
PGKEY_WORLD_29 | 189 |
PGKEY_WORLD_30 | 190 |
PGKEY_WORLD_31 | 191 |
PGKEY_WORLD_32 | 192 |
PGKEY_WORLD_33 | 193 |
PGKEY_WORLD_34 | 194 |
PGKEY_WORLD_35 | 195 |
PGKEY_WORLD_36 | 196 |
PGKEY_WORLD_37 | 197 |
PGKEY_WORLD_38 | 198 |
PGKEY_WORLD_39 | 199 |
PGKEY_WORLD_40 | 200 |
PGKEY_WORLD_41 | 201 |
PGKEY_WORLD_42 | 202 |
PGKEY_WORLD_43 | 203 |
PGKEY_WORLD_44 | 204 |
PGKEY_WORLD_45 | 205 |
PGKEY_WORLD_46 | 206 |
PGKEY_WORLD_47 | 207 |
PGKEY_WORLD_48 | 208 |
PGKEY_WORLD_49 | 209 |
PGKEY_WORLD_50 | 210 |
PGKEY_WORLD_51 | 211 |
PGKEY_WORLD_52 | 212 |
PGKEY_WORLD_53 | 213 |
PGKEY_WORLD_54 | 214 |
PGKEY_WORLD_55 | 215 |
PGKEY_WORLD_56 | 216 |
PGKEY_WORLD_57 | 217 |
PGKEY_WORLD_58 | 218 |
PGKEY_WORLD_59 | 219 |
PGKEY_WORLD_60 | 220 |
PGKEY_WORLD_61 | 221 |
PGKEY_WORLD_62 | 222 |
PGKEY_WORLD_63 | 223 |
PGKEY_WORLD_64 | 224 |
PGKEY_WORLD_65 | 225 |
PGKEY_WORLD_66 | 226 |
PGKEY_WORLD_67 | 227 |
PGKEY_WORLD_68 | 228 |
PGKEY_WORLD_69 | 229 |
PGKEY_WORLD_70 | 230 |
PGKEY_WORLD_71 | 231 |
PGKEY_WORLD_72 | 232 |
PGKEY_WORLD_73 | 233 |
PGKEY_WORLD_74 | 234 |
PGKEY_WORLD_75 | 235 |
PGKEY_WORLD_76 | 236 |
PGKEY_WORLD_77 | 237 |
PGKEY_WORLD_78 | 238 |
PGKEY_WORLD_79 | 239 |
PGKEY_WORLD_80 | 240 |
PGKEY_WORLD_81 | 241 |
PGKEY_WORLD_82 | 242 |
PGKEY_WORLD_83 | 243 |
PGKEY_WORLD_84 | 244 |
PGKEY_WORLD_85 | 245 |
PGKEY_WORLD_86 | 246 |
PGKEY_WORLD_87 | 247 |
PGKEY_WORLD_88 | 248 |
PGKEY_WORLD_89 | 249 |
PGKEY_WORLD_90 | 250 |
PGKEY_WORLD_91 | 251 |
PGKEY_WORLD_92 | 252 |
PGKEY_WORLD_93 | 253 |
PGKEY_WORLD_94 | 254 |
PGKEY_WORLD_95 | 255 | 0xFF
PGKEY_KP0 | 256 |
PGKEY_KP1 | 257 |
PGKEY_KP2 | 258 |
PGKEY_KP3 | 259 |
PGKEY_KP4 | 260 |
PGKEY_KP5 | 261 |
PGKEY_KP6 | 262 |
PGKEY_KP7 | 263 |
PGKEY_KP8 | 264 |
PGKEY_KP9 | 265 |
PGKEY_KP_PERIOD | 266 |
PGKEY_KP_DIVIDE | 267 |
PGKEY_KP_MULTIPLY | 268 |
PGKEY_KP_MINUS | 269 |
PGKEY_KP_PLUS | 270 |
PGKEY_KP_ENTER | 271 |
PGKEY_KP_EQUALS | 272 |
PGKEY_UP | 273 |
PGKEY_DOWN | 274 |
PGKEY_RIGHT | 275 |
PGKEY_LEFT | 276 |
PGKEY_INSERT | 277 |
PGKEY_HOME | 278 |
PGKEY_END | 279 |
PGKEY_PAGEUP | 280 |
PGKEY_PAGEDOWN | 281 |
PGKEY_F1 | 282 |
PGKEY_F2 | 283 |
PGKEY_F3 | 284 |
PGKEY_F4 | 285 |
PGKEY_F5 | 286 |
PGKEY_F6 | 287 |
PGKEY_F7 | 288 |
PGKEY_F8 | 289 |
PGKEY_F9 | 290 |
PGKEY_F10 | 291 |
PGKEY_F11 | 292 |
PGKEY_F12 | 293 |
PGKEY_F13 | 294 |
PGKEY_F14 | 295 |
PGKEY_F15 | 296 |
PGKEY_NUMLOCK | 300 |
PGKEY_CAPSLOCK | 301 |
PGKEY_SCROLLOCK | 302 |
PGKEY_RSHIFT | 303 |
PGKEY_LSHIFT | 304 |
PGKEY_RCTRL | 305 |
PGKEY_LCTRL | 306 |
PGKEY_RALT | 307 |
PGKEY_LALT | 308 |
PGKEY_RMETA | 309 |
PGKEY_LMETA | 310 |
PGKEY_LSUPER | 311 | Left "Windows" key
PGKEY_RSUPER | 312 | Right "Windows" key
PGKEY_MODE | 313 | "AltGr" key
PGKEY_HELP | 315 |
PGKEY_PRINT | 316 |
PGKEY_SYSREQ | 317 |
PGKEY_BREAK | 318 |
PGKEY_MENU | 319 |
PGKEY_POWER | 320 | Power Macintosh powerkey
PGKEY_EURO | 321 | Some european keyboards
PGKEY_ALPHA | 322 | Selects letters on a numeric keypad (for celphones and similar devices)

Table G-2. PGMOD values

PGMOD_LSHIFT | 0001 |
PGMOD_RSHIFT | 0002 |
PGMOD_SHIFT | 0003 |
PGMOD_LCTRL | 0040 |
PGMOD_RCTRL | 0080 |
PGMOD_CTRL | 00C0 |
PGMOD_LALT | 0100 |
PGMOD_RALT | 0200 |
PGMOD_ALT | 0300 |
PGMOD_LMETA | 0400 |
PGMOD_RMETA | 0800 |
PGMOD_META | 0C00 |
PGMOD_NUM | 1000 |
PGMOD_CAPS | 2000 |
PGMOD_MODE | 4000 |

# Appendix H. Theme Constants

## H.1. Theme Object Types

Table H-1. PGTH_O values

PGTH_O_DEFAULT | 0 | Every theme object inherits this
PGTH_O_BASE_INTERACTIVE | 1 | Base for interactive widgets
PGTH_O_BASE_CONTAINER | 2 | Base for containers like toolbars
PGTH_O_BUTTON | 3 | The button widget
PGTH_O_BUTTON_HILIGHT | 4 | Button, hilighted when mouse is over
PGTH_O_BUTTON_ON | 5 | Button, mouse is pressed
PGTH_O_TOOLBAR | 6 | The toolbar widget
PGTH_O_SCROLL | 7 | The scrollbar widget
PGTH_O_SCROLL_HILIGHT | 8 | Scroll, when mouse is over it
PGTH_O_INDICATOR | 9 | The indicator widget
PGTH_O_PANEL | 10 | The background portion of a panel
PGTH_O_PANELBAR | 11 | The draggable titlebar of a panel
PGTH_O_POPUP | 12 | Popup window
PGTH_O_BACKGROUND | 13 | Background widget bitmap
PGTH_O_BASE_DISPLAY | 14 | Base for widgets that mostly display stuff
PGTH_O_BASE_TLCONTAINER | 15 | Top-level containers like popups, panels
PGTH_O_THEMEINFO | 16 | Information about the theme that should be loaded into memory, like the name
PGTH_O_LABEL | 17 | The label widget
PGTH_O_FIELD | 18 | The field widget
PGTH_O_BITMAP | 19 | The bitmap widget
PGTH_O_SCROLL_ON | 20 | Scroll, when mouse is down
PGTH_O_LABEL_SCROLL | 21 | A label, when bound to a scrollbar
PGTH_O_PANELBAR_HILIGHT | 22 | A panelbar, when mouse is inside it
PGTH_O_PANELBAR_ON | 23 | A panelbar, when mouse is down
PGTH_O_BOX | 24 | The box widget
PGTH_O_LABEL_DLGTITLE | 25 | A label, used for a dialog box title
PGTH_O_LABEL_DLGTEXT | 26 | A label, used for the body of a dialog
PGTH_O_CLOSEBTN | 27 | A panelbar close button
PGTH_O_CLOSEBTN_ON | 28 | A panelbar close button, mouse down
PGTH_O_CLOSEBTN_HILIGHT | 29 | A panelbar close button, mouse over
PGTH_O_BASE_PANELBTN | 30 | Base for a panelbar button
PGTH_O_ROTATEBTN | 31 | A panelbar rotate button
PGTH_O_ROTATEBTN_ON | 32 | A panelbar rotate button, mouse down
PGTH_O_ROTATEBTN_HILIGHT | 33 | A panelbar rotate button, mouse over
PGTH_O_ZOOMBTN | 34 | A panelbar zoom button
PGTH_O_ZOOMBTN_ON | 35 | A panelbar zoom button, mouse down
PGTH_O_ZOOMBTN_HILIGHT | 36 | A panelbar zoom button, mouse over
PGTH_O_POPUP_MENU | 37 | A popup menu
PGTH_O_POPUP_MESSAGEDLG | 38 | A message dialog
PGTH_O_MENUITEM | 39 | Item in a popup menu (customized button)
PGTH_O_MENUITEM_HILIGHT | 40 | menuitem with the mouse over it
PGTH_O_CHECKBOX | 41 | Check box (customized button)
PGTH_O_CHECKBOX_HILIGHT | 42 | checkbox with mouse over it
PGTH_O_CHECKBOX_ON | 43 | checkbox when on
PGTH_O_FLATBUTTON | 44 | Flat button (customized button)
PGTH_O_FLATBUTTON_HILIGHT | 45 | flatbutton with mouse over it
PGTH_O_FLATBUTTON_ON | 46 | flatbutton with mouse down
PGTH_O_LISTITEM | 47 | Listitem (customized button)
PGTH_O_LISTITEM_HILIGHT | 48 | Listitem with mouse over it
PGTH_O_LISTITEM_ON | 49 | Selected listitem
PGTH_O_CHECKBOX_ON_NOHILIGHT | 50 | checkbox when on but not hilighted
PGTH_O_SUBMENUITEM | 51 | Submenuitem
PGTH_O_SUBMENUITEM_HILIGHT | 52 | Hilighted submenuitem
PGTH_O_RADIOBUTTON | 53 | Radio button (cust. button)
PGTH_O_RADIOBUTTON_HILIGHT | 54 | Radio button (cust. button)
PGTH_O_RADIOBUTTON_ON | 55 | Radio button (cust. button)
PGTH_O_RADIOBUTTON_ON_NOHILIGHT | 56 | Radio button (cust. button)
PGTH_O_TEXTBOX | 57 | Textbox widget
PGTH_O_TERMINAL | 58 | Terminal widget
PGTH_O_MENUBUTTON | 60 | DSPLinux Application Menu
PGTH_O_MENUBUTTON_ON | 61 | DSPLinux Application Menu
PGTH_O_MENUBUTTON_HILIGHT | 62 | DSPLinux Application Menu
PGTH_O_LABEL_HILIGHT | 63 | Label hilight or select - See PG_WP_HILIGHTED
PGTH_O_BOX_HILIGHT | 64 | Box hilight or select - See PG_WP_HILIGHTED
PGTH_O_INDICATOR_H | 65 | Horizontal indicator
PGTH_O_INDICATOR_V | 66 | Vertical indicator

## H.2. Theme Property Types

Table H-2. PGTH_P values

PGTH_P_BGCOLOR | 1 | Default background color
PGTH_P_FGCOLOR | 2 | Default foreground color
PGTH_P_BGFILL | 3 | Background fillstyle
PGTH_P_OVERLAY | 4 | Fillstyle for scroll thumbs, the filled portion of an indicator
PGTH_P_FONT | 5 | A widget's main font
PGTH_P_NAME | 6 | Name of the theme object, themes can be searched by this
PGTH_P_WIDTH | 7 | Reccomended width
PGTH_P_HEIGHT | 8 | Reccomended height
PGTH_P_MARGIN | 9 | The border in some objects
PGTH_P_HILIGHTCOLOR | 10 | Color for hilighting an object
PGTH_P_SHADOWCOLOR | 11 | Color for shading an object
PGTH_P_OFFSET | 12 | An amount to displace something by
PGTH_P_ALIGN | 13 | How to position an object's contents
PGTH_P_BITMAPSIDE | 14 | Bitmap side relative to text (button)
PGTH_P_BITMAPMARGIN | 15 | Spacing between bitmap and text
PGTH_P_BITMAP1 | 16 | Generic bitmap property for theme use
PGTH_P_BITMAP2 | 17 | Generic bitmap property for theme use
PGTH_P_BITMAP3 | 18 | Generic bitmap property for theme use
PGTH_P_BITMAP4 | 19 | Generic bitmap property for theme use
PGTH_P_SPACING | 20 | Distance between similar widgets
PGTH_P_TEXT | 21 | Text caption for something like a button
PGTH_P_SIDE | 22 | Side for a widget or subwidget
PGTH_P_BACKDROP | 23 | Fillstyle on the screen behind a popup
PGTH_P_WIDGETBITMAP | 24 | Bitmap for something like a button
PGTH_P_WIDGETBITMASK | 25 | Bitmask for something like a button
PGTH_P_CURSORBITMAP | 26 | Bitmap for the (mouse) pointer
PGTH_P_CURSORBITMASK | 27 | Bitmask for the (mouse) pointer
PGTH_P_HIDEHOTKEYS | 28 | Set to a PG_HHK_* constant
PGTH_P_ATTR_DEFAULT | 29 | Default attribute for the terminal
PGTH_P_ATTR_CURSOR | 30 | Default attribute for the terminal
PGTH_P_TEXTCOLORS | 31 | Text color pallete for the terminal
PGTH_P_TIME_ON | 32 | Milliseconds on for flashing cursor
PGTH_P_TIME_OFF | 33 | Milliseconds off for flashing cursor
PGTH_P_TIME_DELAY | 34 | Milliseconds to wait before flashing
PGTH_P_PARENT | 35 | Overrides the default theme inheritance
PGTH_P_ICON_OK | 1000 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_OK_MASK | 1001 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_CANCEL | 1002 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_CANCEL_MASK | 1003 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_YES | 1004 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_YES_MASK | 1005 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_NO | 1006 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_NO_MASK | 1007 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_ERROR | 1008 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_ERROR_MASK | 1009 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_MESSAGE | 1010 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_MESSAGE_MASK | 1011 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_QUESTION | 1012 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_QUESTION_MASK | 1013 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_WARNING | 1014 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_WARNING_MASK | 1015 | Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_OK | 1501 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_CANCEL | 1502 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_YES | 1503 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_NO | 1504 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_UP | 1505 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_DOWN | 1506 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_LEFT | 1507 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_RIGHT | 1508 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_ACTIVATE | 1509 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_NEXT | 1510 | Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_USER | 10000 | Application-defined theme property start range
PGTH_P_THEMEAUTO | 20000 | Automatically allocated properties used only by the theme start range

# Appendix I. Driver Messages Constants

## I.1. Generic Driver Message Types

Table I-1. PGDM values

PGDM_BACKLIGHT | 2 | Turn the backlight on/off
PGDM_SOUNDFX | 3 | Parameter is a PG_SND_* constant
PGDM_POWER | 4 | Enter the power mode, PG_POWER_*
PGDM_SDC_CHAR | 5 | Send a character to the secondary display channel
PGDM_BRIGHTNESS | 6 | Set display brightness, 0x00-0xFF
PGDM_CONTRAST | 7 | Set display contrast, 0x00-0xFF
PGDM_SIGNAL | 13 | Internal message, sends SIGUSR1/2 to drivers (param is signal)
PGDM_READY | 14 | Notify the drivers that the server is completely up

# Appendix J. Event Constants

## J.1. Widget Events

Table J-1. PG_WE values

PG_WE_ACTIVATE | 0x001 | Button has been clicked/selected
PG_WE_DEACTIVATE | 0x002 | Sent when the user clicks outside the active popup
PG_WE_CLOSE | 0x003 | A top-level widget has closed
PG_WE_FOCUS | 0x004 | Sent when a button is focused, only if it has PG_EXEV_FOCUS. The field widget always sends this.
PG_WE_CHANGED | 0x005 | Sent by the textbox when its contents change (but only after a delay)
PG_WE_PNTR_DOWN | 0x204 | The "mouse" button is now down
PG_WE_PNTR_UP | 0x205 | The "mouse" button is now up
PG_WE_PNTR_RELEASE | 0x206 | The "mouse" button was released outside the widget
PG_WE_DATA | 0x306 | Widget is streaming data to the app
PG_WE_RESIZE | 0x107 | For terminal widgets
PG_WE_BUILD | 0x108 | Sent from a canvas, clients can rebuild groplist
PG_WE_PNTR_MOVE | 0x209 | The "mouse" moved
PG_WE_KBD_CHAR | 0x40A | A focused keyboard character recieved
PG_WE_KBD_KEYUP | 0x40B | A focused raw keyup event
PG_WE_KBD_KEYDOWN | 0x40C | A focused raw keydown event
PG_WE_APPMSG | 0x301 | Messages from another application

## J.2. Non-Widget Events

Table J-2. PG_NWE values

PG_NWE_THEME_INSERTED | 0x1001 | This notifies all clients when a theme is inserted, so they can reevaluate theme properties they're using. The parameter passed with this event is a handle to the theme.
PG_NWE_THEME_REMOVED | 0x1002 | This notifies all clients when a theme is removed, so they can reevaluate theme properties they're using. The parameter passed with this event is a handle to the theme. Note that at the time this event is sent, the handle will be invalid, but it is provided for comparison purposes if needed.
PG_NWE_INFILTER | 0x1302 | Carries an event from pgserver to a client-side input filter. The data along with this event is a union pg_client_trigger

# Appendix K. Server Resource Constants

## K.1. Server Resources

Table K-1. PGRES values

PGRES_DEFAULT_FONT | 0 | The server's default font handle
PGRES_STRING_OK | 1 | "Ok"
PGRES_STRING_CANCEL | 2 | "Cancel"
PGRES_STRING_YES | 3 | "Yes"
PGRES_STRING_NO | 4 | "No"
PGRES_STRING_SEGFAULT | 5 | "Segmentation Fault"
PGRES_STRING_MATHERR | 6 | "Floating Point Exception or Divide by Zero"
PGRES_STRING_PGUIERR | 7 | "PicoGUI Error"
PGRES_STRING_PGUIWARN | 8 | "PicoGUI Warning"
PGRES_STRING_PGUIERRDLG | 9 | "An error of type %s occurred in %s:\n\n%s\n\nTerminate the application?"
PGRES_STRING_PGUICOMPAT | 10 | "This PicoGUI application uses a newer protocol than the server.You may experience compatibility problems."
PGRES_DEFAULT_TEXTCOLORS | 11 | The server's default terminal palette
PGRES_INFILTER_TOUCHSCREEN | 12 | Input filter for touchscreen calibration and filtering
PGRES_INFILTER_KEY_PREPROCESS | 13 | Input filter for performing extra processing on keys before dispatching them
PGRES_INFILTER_PNTR_PREPROCESS | 14 | Input filter to do coordinate conversion on pointing events, and other processing if applicable
PGRES_INFILTER_MAGIC | 15 | Input filter for handling CTRL-ALT-* debug keys
PGRES_INFILTER_KEY_DISPATCH | 16 | Input filter for dispatching key events
PGRES_INFILTER_PNTR_DISPATCH | 17 | Input filter for dispatching pointing events
PGRES_DEFAULT_CURSORBITMAP | 18 | The bitmap for the default cursor
PGRES_DEFAULT_CURSORBITMASK | 19 | The bitmask for the default cursor
PGRES_BACKGROUND_WIDGET | 20 | The server-owned widget that takes up leftover space
PGRES_INFILTER_HOTSPOT | 21 | Input filter to manage global hotspot-navigation keys
PGRES_INFILTER_KEY_ALPHA | 22 | Input filter that manages PGKEY_ALPHA
PGRES_INFILTER_PNTR_NORMALIZE | 23 | Input filter to convert all pointing events to a standard form

### Notes

[1] | At the time of writing this document, the unix socket layer of PicoGUI does not support multiple displays without modifying the source code and building separate binaries. This should be fixed pretty soon though, so the chances are that while you are reading this it is already available. By default at this time the socket name is "/var/tmp/.pgui".
[2] | At the time of writing this document, the server does not send individual replies if multiple requests were sent as a single packet.
[3] | At the time of writing this, the only object type for which duplication is implemented is the string object.
[4] | It is expected in the future protocol version that a `PG_RESPONSE_ERR` will be returned if the index is invalid rather than returning a NULL name.
[5] | In the future protocol versions it is expected that the text message will be replaced by a string handle and an error code be returned.