PicoGUI Protocol

Version 20

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


Table of Contents
1. Introduction
2. Assumptions
3. Client/Server communication
3.1. Establishing a TCP/IP connection with PicoGUI
3.1.1. Recommendations for TCP/IP communication
3.2. Establishing a Unix socket connection with PicoGUI
3.3. Protocol Independant Initialization
3.3.1. pghello
4. PicoGUI packets
4.1. Requests and Responses
4.2. Client Requests
4.2.1. PGREQ_APPMSG - Send PG_WE_APPMSG to any widget
4.2.2. PGREQ_ATTACHWIDGET - Attach widget
4.2.3. PGREQ_BATCH - Batch multiple requests
4.2.4. PGREQ_CHCONTEXT - Change a handle's context
4.2.5. PGREQ_CHECKEVENT - Return number of queued events
4.2.6. PGREQ_CREATEWIDGET - Create a widget
4.2.7. PGREQ_DRIVERMSG - Send a message to all drivers
4.2.8. PGREQ_DUP - Duplicate an object
4.2.9. PGREQ_FINDTHOBJ - Find theme object by name
4.2.10. PGREQ_FINDWIDGET - Get widget handle by name
4.2.11. PGREQ_FOCUS - Forces focus to a specified widget
4.2.12. PGREQ_FREE - Free a handle
4.2.13. PGREQ_GET - Get a widget's property
4.2.14. PGREQ_GETCONTEXT - Get the app's current handle context
4.2.15. PGREQ_GETFSTYLE - Get information on a font
4.2.16. PGREQ_GETINACTIVE - Get miliseconds of inactivity
4.2.17. PGREQ_GETMODE - Get video mode information
4.2.18. PGREQ_GETPAYLOAD - Get the payload of an object
4.2.19. PGREQ_GETRESOURCE - Get a handle to a server-owned resource
4.2.20. PGREQ_GETSTRING - Return a string data
4.2.21. PGREQ_INFILTERSEND - Send a trigger to an input filter
4.2.22. PGREQ_LOADDRIVER - Load input/misc driver
4.2.23. PGREQ_MKARRAY - Make an array
4.2.24. PGREQ_MKBITMAP - Load a bitmap
4.2.25. PGREQ_MKCONTEXT - Enter a new context
4.2.26. PGREQ_MKCURSOR - Make a new cursor, return the handle
4.2.27. PGREQ_MKFILLSTYLE - Load a fill style
4.2.28. PGREQ_MKFONT - Make a font descriptor
4.2.29. PGREQ_MKINFILTER - Create a client-side input filter
4.2.30. PGREQ_MKSHMBITMAP - Convert a picogui bitmap to a shared memory segment
4.2.31. PGREQ_MKSTRING - Create a string
4.2.32. PGREQ_MKTHEME - Load a compiled theme
4.2.33. PGREQ_MKWIDGET - Make a new widget
4.2.34. PGREQ_NEWBITMAP - Create a blank bitmap
4.2.35. PGREQ_PING - Ping request
4.2.36. PGREQ_REGISTER - Register an application
4.2.37. PGREQ_REGOWNER - Get exclusive privileges
4.2.38. PGREQ_RENDER - Render a gropnode to a bitmap
4.2.39. PGREQ_RMCONTEXT - Clean up and kill a context
4.2.40. PGREQ_SET - Set a widget's properties
4.2.41. PGREQ_SETCONTEXT - Set the app's current handle context
4.2.42. PGREQ_SETINACTIVE - Set miliseconds of inactivity
4.2.43. PGREQ_SETMODE - Set video mode/depth/rotation
4.2.44. PGREQ_SETPAYLOAD - Set an object's payload
4.2.45. PGREQ_SIZEBITMAP - Find the size of a bitmap
4.2.46. PGREQ_SIZETEXT - Find the size of text
4.2.47. PGREQ_THLOOKUP - Perform a theme lookup
4.2.48. PGREQ_TRAVERSEWGT - Find widgets after this one
4.2.49. PGREQ_UNREGOWNER - Give up exclusive privileges
4.2.50. PGREQ_UPDATE - Update the screen
4.2.51. PGREQ_UPDATEPART - Update a subtree of widgets
4.2.52. PGREQ_WAIT - Wait for an event
4.2.53. PGREQ_WRITETO - Write data to a widget
4.3. Server Responses
4.3.1. PG_RESPONSE_ERR - Error Code
4.3.2. PG_RESPONSE_RET - 32bit Value
4.3.3. PG_RESPONSE_EVENT - Event
4.3.4. PG_RESPONSE_DATA - Variable Length Data
5. Event Parameters
5.1. PG_EVENTCODING_PARAM - 32bit Parameter
5.2. PG_EVENTCODING_XY - X,Y Coordinates
5.3. PG_EVENTCODING_PNTR - Pointer Parameters (x,y,btn,chbtn)
5.4. PG_EVENTCODING_DATA - Arbitrary data block
5.5. PG_EVENTCODING_KBD - Keyboard Parameters
A. Gropnode Types
B. Property Types
C. Request Types
D. Trigger Types
E. Widget Types
F. Font Constants
F.1. Font Styles
F.2. Font Representations
G. Keyboard Constants
H. Theme Constants
H.1. Theme Object Types
H.2. Theme Property Types
I. Driver Messages Constants
I.1. Generic Driver Message Types
J. Event Constants
J.1. Widget Events
J.2. Non-Widget Events
K. Server Resource Constants
K.1. Server Resources
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

charsigned 8bit value
s8signed 8bit value (same as char)
u8unsigned 8bit value
s16signed 16bit value
u16unsigned 16bit value
s32signed 32bit value
u32unsigned 32bit value

Table 2-2. special variables

dummyused 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_NORMAL1Normal application assigned a resizeable window
PG_APP_TOOLBAR2Toolbar 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_KEYBOARD1Exclusive access to the keyboard
PG_OWN_POINTER2Exclusive access to the pointer
PG_OWN_SYSEVENTS3Receive system events like app open/close, click on background, etc.
PG_OWN_DISPLAY4Exclusive 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_SET0Sets all flags to the specified value
PG_FM_ON1Turns on specified flags
PG_FM_OFF2Turns off specified flags
PG_FM_TOGGLE3Toggles specified flags

Table 4-4. PG_VID values

PG_VID_FULLSCREEN0x0001Deprecated
PG_VID_DOUBLEBUFFER0x0002Deprecated
PG_VID_ROTATE900x0004Rotate the display 90 degree clockwise
PG_VID_ROTATE1800x0008Rotate the display 180 degree clockwise
PG_VID_ROTATE2700x0010Rotate 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_CHILDREN1Starting with this widget's first child, traverse forward
PG_TRAVERSE_FORWARD2 
PG_TRAVERSE_BACKWARD3Going backwards is much slower than going forward right now
PG_TRAVERSE_CONTAINER4count 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.

IMPORTANT NOTE: The behaviour of this request will change in a future implementation of this protocol, the client should for now restrict itself from sending any other request after a PGREQ_MKWAIT is sent.


4.2.53. PGREQ_WRITETO - Write data to a widget

type                 : PGREQ_WRITETO (31)
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 terminal widget or commands to a canvas 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_ERR1response is a pgresponse_err struct
PG_RESPONSE_RET2response is a pgresponse_ret struct
PG_RESPONSE_EVENT3response is a pgresponse_event struct
PG_RESPONSE_DATA4response 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_NONE0x0000No error condition
PG_ERRT_MEMORY0x0101Error allocating memory
PG_ERRT_IO0x0200Filesystem, operating system, or other IO error
PG_ERRT_NETWORK0x0300Network (or IPC) communication error
PG_ERRT_BADPARAM0x0400Invalid parameters
PG_ERRT_HANDLE0x0500Invalid handle ID, type, or ownership
PG_ERRT_INTERNAL0x0600Shouldn't happen (tell a developer!)
PG_ERRT_BUSY0x0700Try again later?
PG_ERRT_FILEFMT0x0800Error in a loaded file format (theme files, bitmaps)
PG_ERRT_CLIENT0x8000An 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_PARAM0x000Just a 32-bit parameter
PG_EVENTCODING_XY0x100X,Y coordinates packed into param
PG_EVENTCODING_PNTR0x200Mouse parameters (x,y,btn,chbtn)
PG_EVENTCODING_DATA0x300Arbitrary data block
PG_EVENTCODING_KBD0x400Keyboard params
PG_EVENTCODING_MASK0xF00 

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_RECT0x00 
PG_GROP_FRAME0x10 
PG_GROP_SLAB0x20 
PG_GROP_BAR0x30 
PG_GROP_PIXEL0x40 
PG_GROP_LINE0x50 
PG_GROP_ELLIPSE0x60 
PG_GROP_FELLIPSE0x70 
PG_GROP_TEXT0x04Param: string
PG_GROP_BITMAP0x14Param: bitmap
PG_GROP_TILEBITMAP0x24Param: bitmap
PG_GROP_FPOLYGON0x34Param: array
PG_GROP_GRADIENT0x0CParam: angle, c1, c2
PG_GROP_TEXTGRID0x1CParam: string, bufferw, offset
PG_GROP_NOP0x03 
PG_GROP_RESETCLIP0x13Reset clip to whole divnode
PG_GROP_SETOFFSET0x01this grop's rect sets offset
PG_GROP_SETCLIP0x11this grop's rect sets clipping
PG_GROP_SETSRC0x21this grop's rect sets src_*
PG_GROP_SETMAPPING0x05Param: PG_MAP_* const
PG_GROP_SETCOLOR0x07Param: pgcolor
PG_GROP_SETFONT0x17Param: font
PG_GROP_SETLGOP0x27Param: lgop
PG_GROP_SETANGLE0x37Param: angle in degrees
PG_GROP_VIDUPDATE0x800Forces 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_SIZE1 
PG_WP_SIDE2 
PG_WP_ALIGN3 
PG_WP_BGCOLOR4 
PG_WP_COLOR5 
PG_WP_SIZEMODE6 
PG_WP_TEXT7 
PG_WP_FONT8 
PG_WP_TRANSPARENT9 
PG_WP_BORDERCOLOR10 
PG_WP_BITMAP12 
PG_WP_LGOP13 
PG_WP_VALUE14 
PG_WP_BITMASK15 
PG_WP_BIND16 
PG_WP_SCROLL_X17Horizontal and vertical scrolling amount
PG_WP_SCROLL_Y18 
PG_WP_HOTKEY19 
PG_WP_EXTDEVENTS20For buttons, a mask of extra events to send
PG_WP_DIRECTION21 
PG_WP_ABSOLUTEX22read-only, relative to screen
PG_WP_ABSOLUTEY23 
PG_WP_ON24on-off state of button/checkbox/etc
PG_WP_STATE25Deprecated! Use PG_WP_THOBJ instead
PG_WP_THOBJ25Set a widget's theme object
PG_WP_NAME26A widget's name (for named containers, etc)
PG_WP_PUBLICBOX27Set to 1 to allow other apps to make widgets in this container
PG_WP_DISABLED28For buttons, grays out text and prevents clicking
PG_WP_MARGIN29For boxes, overrides the default margin
PG_WP_TEXTFORMAT30For 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_TRIGGERMASK31Mask of extra triggers accepted (self->trigger_mask)
PG_WP_HILIGHTED32Widget property to hilight a widget and all it's children
PG_WP_SELECTED33List property to select a row.
PG_WP_SELECTED_HANDLE34List property to return a handle to the selected row
PG_WP_AUTOSCROLL35For the textbox or terminal, scroll to any new text that's inserted
PG_WP_LINES36Height, in lines
PG_WP_PREFERRED_W37Read only (for now) properties to get any widget's preferred size
PG_WP_PREFERRED_H38 
PG_WP_PANELBAR39Read-only property for panels returns a handle to its embedded panelbar widget
PG_WP_AUTO_ORIENTATION40Automatically reorient child widgets when PG_WP_SIDE changes
PG_WP_THOBJ_BUTTON41These four theme properties set the theme objects used for the
PG_WP_THOBJ_BUTTON_HILIGHT42three possible states of the button widget.
PG_WP_THOBJ_BUTTON_ON43 
PG_WP_THOBJ_BUTTON_ON_NOHILIGHT44 
PG_WP_PANELBAR_LABEL45More read-only panelbar properties to get the built-in panelbar widgets
PG_WP_PANELBAR_CLOSE46 
PG_WP_PANELBAR_ROTATE47 
PG_WP_PANELBAR_ZOOM48 
PG_WP_BITMAPSIDE49 
PG_WP_PASSWORD50 
PG_WP_HOTKEY_FLAGS51Keyboard event flags for the hotkey (PG_KF_*)
PG_WP_HOTKEY_CONSUME52Flag indicating whether to consume the key event when a hotkey comes in

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_PING0Simply return if server is ok
PGREQ_UPDATE1Call update()
PGREQ_MKWIDGET2Make a widget, return handle
PGREQ_MKBITMAP3Make a bitmap, return handle
PGREQ_MKFONT4Make a fontdesc, return handle
PGREQ_MKSTRING5Make a string, return handle
PGREQ_FREE6Free a handle
PGREQ_SET7Set a widget param
PGREQ_GET8Get a widget param, return it
PGREQ_MKTHEME9Load a compiled theme
PGREQ_MKCURSOR10Make a cursor, return handle
PGREQ_MKINFILTER11Make an input filter, return handle
PGREQ_GETRESOURCE12Get a handle to a server-owned resource
PGREQ_WAIT13Wait for an event
PGREQ_MKFILLSTYLE14Load a fill style, return handle
PGREQ_REGISTER15Register a new application
PGREQ_MKPOPUP16Create a popup root widget
PGREQ_SIZETEXT17Find the size of text
PGREQ_BATCH18Execute many requests
PGREQ_REGOWNER19Get exclusive privileges
PGREQ_UNREGOWNER20Give up exclusive privileges
PGREQ_SETMODE21Set video mode/depth/rotation
PGREQ_GETMODE22Return a modeinfo struct
PGREQ_MKCONTEXT23Enter a new context
PGREQ_RMCONTEXT24Clean up and kills the context
PGREQ_FOCUS25Force focus to specified widget
PGREQ_GETSTRING26Return a RESPONSE_DATA
PGREQ_DUP27Duplicate an object
PGREQ_SETPAYLOAD28Set an object's payload
PGREQ_GETPAYLOAD29Get an object's payload
PGREQ_CHCONTEXT30Change a handle's context
PGREQ_WRITETO31Stream data to a widget
PGREQ_UPDATEPART32Update subtree defined by wgt
PGREQ_MKARRAY33Make a array, return handle
PGREQ_RENDER34Render gropnode(s) to a bitmap
PGREQ_NEWBITMAP35Create a blank bitmap
PGREQ_THLOOKUP36Perform a theme lookup
PGREQ_GETINACTIVE37Get milliseconds of inactivity
PGREQ_SETINACTIVE38Set milliseconds of inactivity
PGREQ_DRIVERMSG39Send a message to all drivers
PGREQ_LOADDRIVER40Load input/misc (not video)
PGREQ_GETFSTYLE41Get info on a font style
PGREQ_FINDWIDGET42Get widget handle by name
PGREQ_CHECKEVENT43Return number of queued events
PGREQ_SIZEBITMAP44Find the size of a bitmap
PGREQ_APPMSG45Send PG_WE_APPMSG to any widget
PGREQ_CREATEWIDGET46Create widget
PGREQ_ATTACHWIDGET47Attach widget
PGREQ_FINDTHOBJ48Find theme object by name
PGREQ_TRAVERSEWGT49Find widgets relative to a specified widget
PGREQ_MKTEMPLATE50Load a widget template, return the handle
PGREQ_SETCONTEXT51Set the app's current handle context
PGREQ_GETCONTEXT52Get the app's current handle context
PGREQ_INFILTERSEND53Send a trigger to an input filter
PGREQ_MKSHMBITMAP54Convert a picogui bitmap to a shared memory segment

Appendix D. Trigger Types

(soon)


Appendix E. Widget Types

(soon)

Table E-1. PG_WIDGET values

PG_WIDGET_TOOLBAR0 
PG_WIDGET_LABEL1 
PG_WIDGET_SCROLL2 
PG_WIDGET_INDICATOR3 
PG_WIDGET_BUTTON5 
PG_WIDGET_PANEL6 
PG_WIDGET_POPUP7 
PG_WIDGET_BOX8 
PG_WIDGET_FIELD9 
PG_WIDGET_BACKGROUND10 
PG_WIDGET_MENUITEM11A variation on button
PG_WIDGET_TERMINAL12A full terminal emulator
PG_WIDGET_CANVAS13 
PG_WIDGET_CHECKBOX14Another variation of button
PG_WIDGET_FLATBUTTON15Yet another customized button
PG_WIDGET_LISTITEM16Still yet another...
PG_WIDGET_SUBMENUITEM17Menuitem with a submenu arrow
PG_WIDGET_RADIOBUTTON18Like a check box, but exclusive
PG_WIDGET_TEXTBOX19Client-side text layout
PG_WIDGET_PANELBAR20Draggable bar and container
PG_WIDGET_SIMPLEMENU21Popup-menu with only text items in it
PG_WIDGET_DIALOGBOX22Popup box with standard dialog titlebar
PG_WIDGET_MESSAGEDIALOG23Dialogbox that displays a message to the user
PG_WIDGET_SCROLLBOX24Container with built-in horizontal and vertical scrolling

Table E-2. PG_DERIVE values

PG_DERIVE_AFTER1 
PG_DERIVE_INSIDE2 
PG_DERIVE_BEFORE3 

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_BACKSPACE8 
PGKEY_TAB9 
PGKEY_CLEAR12 
PGKEY_RETURN13 
PGKEY_PAUSE19 
PGKEY_ESCAPE27 
PGKEY_SPACE32 
PGKEY_EXCLAIM33 
PGKEY_QUOTEDBL34 
PGKEY_HASH35 
PGKEY_DOLLAR36 
PGKEY_PERCENT37 
PGKEY_AMPERSAND38 
PGKEY_QUOTE39 
PGKEY_LEFTPAREN40 
PGKEY_RIGHTPAREN41 
PGKEY_ASTERISK42 
PGKEY_PLUS43 
PGKEY_COMMA44 
PGKEY_MINUS45 
PGKEY_PERIOD46 
PGKEY_SLASH47 
PGKEY_048 
PGKEY_149 
PGKEY_250 
PGKEY_351 
PGKEY_452 
PGKEY_553 
PGKEY_654 
PGKEY_755 
PGKEY_856 
PGKEY_957 
PGKEY_COLON58 
PGKEY_SEMICOLON59 
PGKEY_LESS60 
PGKEY_EQUALS61 
PGKEY_GREATER62 
PGKEY_QUESTION63 
PGKEY_AT64 
PGKEY_LEFTBRACKET91 
PGKEY_BACKSLASH92 
PGKEY_RIGHTBRACKET93 
PGKEY_CARET94 
PGKEY_UNDERSCORE95 
PGKEY_BACKQUOTE96 
PGKEY_a97 
PGKEY_b98 
PGKEY_c99 
PGKEY_d100 
PGKEY_e101 
PGKEY_f102 
PGKEY_g103 
PGKEY_h104 
PGKEY_i105 
PGKEY_j106 
PGKEY_k107 
PGKEY_l108 
PGKEY_m109 
PGKEY_n110 
PGKEY_o111 
PGKEY_p112 
PGKEY_q113 
PGKEY_r114 
PGKEY_s115 
PGKEY_t116 
PGKEY_u117 
PGKEY_v118 
PGKEY_w119 
PGKEY_x120 
PGKEY_y121 
PGKEY_z122 
PGKEY_LEFTBRACE123 
PGKEY_PIPE124 
PGKEY_RIGHTBRACE125 
PGKEY_TILDE126 
PGKEY_DELETE127 
PGKEY_WORLD_01600xA0
PGKEY_WORLD_1161 
PGKEY_WORLD_2162 
PGKEY_WORLD_3163 
PGKEY_WORLD_4164 
PGKEY_WORLD_5165 
PGKEY_WORLD_6166 
PGKEY_WORLD_7167 
PGKEY_WORLD_8168 
PGKEY_WORLD_9169 
PGKEY_WORLD_10170 
PGKEY_WORLD_11171 
PGKEY_WORLD_12172 
PGKEY_WORLD_13173 
PGKEY_WORLD_14174 
PGKEY_WORLD_15175 
PGKEY_WORLD_16176 
PGKEY_WORLD_17177 
PGKEY_WORLD_18178 
PGKEY_WORLD_19179 
PGKEY_WORLD_20180 
PGKEY_WORLD_21181 
PGKEY_WORLD_22182 
PGKEY_WORLD_23183 
PGKEY_WORLD_24184 
PGKEY_WORLD_25185 
PGKEY_WORLD_26186 
PGKEY_WORLD_27187 
PGKEY_WORLD_28188 
PGKEY_WORLD_29189 
PGKEY_WORLD_30190 
PGKEY_WORLD_31191 
PGKEY_WORLD_32192 
PGKEY_WORLD_33193 
PGKEY_WORLD_34194 
PGKEY_WORLD_35195 
PGKEY_WORLD_36196 
PGKEY_WORLD_37197 
PGKEY_WORLD_38198 
PGKEY_WORLD_39199 
PGKEY_WORLD_40200 
PGKEY_WORLD_41201 
PGKEY_WORLD_42202 
PGKEY_WORLD_43203 
PGKEY_WORLD_44204 
PGKEY_WORLD_45205 
PGKEY_WORLD_46206 
PGKEY_WORLD_47207 
PGKEY_WORLD_48208 
PGKEY_WORLD_49209 
PGKEY_WORLD_50210 
PGKEY_WORLD_51211 
PGKEY_WORLD_52212 
PGKEY_WORLD_53213 
PGKEY_WORLD_54214 
PGKEY_WORLD_55215 
PGKEY_WORLD_56216 
PGKEY_WORLD_57217 
PGKEY_WORLD_58218 
PGKEY_WORLD_59219 
PGKEY_WORLD_60220 
PGKEY_WORLD_61221 
PGKEY_WORLD_62222 
PGKEY_WORLD_63223 
PGKEY_WORLD_64224 
PGKEY_WORLD_65225 
PGKEY_WORLD_66226 
PGKEY_WORLD_67227 
PGKEY_WORLD_68228 
PGKEY_WORLD_69229 
PGKEY_WORLD_70230 
PGKEY_WORLD_71231 
PGKEY_WORLD_72232 
PGKEY_WORLD_73233 
PGKEY_WORLD_74234 
PGKEY_WORLD_75235 
PGKEY_WORLD_76236 
PGKEY_WORLD_77237 
PGKEY_WORLD_78238 
PGKEY_WORLD_79239 
PGKEY_WORLD_80240 
PGKEY_WORLD_81241 
PGKEY_WORLD_82242 
PGKEY_WORLD_83243 
PGKEY_WORLD_84244 
PGKEY_WORLD_85245 
PGKEY_WORLD_86246 
PGKEY_WORLD_87247 
PGKEY_WORLD_88248 
PGKEY_WORLD_89249 
PGKEY_WORLD_90250 
PGKEY_WORLD_91251 
PGKEY_WORLD_92252 
PGKEY_WORLD_93253 
PGKEY_WORLD_94254 
PGKEY_WORLD_952550xFF
PGKEY_KP0256 
PGKEY_KP1257 
PGKEY_KP2258 
PGKEY_KP3259 
PGKEY_KP4260 
PGKEY_KP5261 
PGKEY_KP6262 
PGKEY_KP7263 
PGKEY_KP8264 
PGKEY_KP9265 
PGKEY_KP_PERIOD266 
PGKEY_KP_DIVIDE267 
PGKEY_KP_MULTIPLY268 
PGKEY_KP_MINUS269 
PGKEY_KP_PLUS270 
PGKEY_KP_ENTER271 
PGKEY_KP_EQUALS272 
PGKEY_UP273 
PGKEY_DOWN274 
PGKEY_RIGHT275 
PGKEY_LEFT276 
PGKEY_INSERT277 
PGKEY_HOME278 
PGKEY_END279 
PGKEY_PAGEUP280 
PGKEY_PAGEDOWN281 
PGKEY_F1282 
PGKEY_F2283 
PGKEY_F3284 
PGKEY_F4285 
PGKEY_F5286 
PGKEY_F6287 
PGKEY_F7288 
PGKEY_F8289 
PGKEY_F9290 
PGKEY_F10291 
PGKEY_F11292 
PGKEY_F12293 
PGKEY_F13294 
PGKEY_F14295 
PGKEY_F15296 
PGKEY_NUMLOCK300 
PGKEY_CAPSLOCK301 
PGKEY_SCROLLOCK302 
PGKEY_RSHIFT303 
PGKEY_LSHIFT304 
PGKEY_RCTRL305 
PGKEY_LCTRL306 
PGKEY_RALT307 
PGKEY_LALT308 
PGKEY_RMETA309 
PGKEY_LMETA310 
PGKEY_LSUPER311Left "Windows" key
PGKEY_RSUPER312Right "Windows" key
PGKEY_MODE313"AltGr" key
PGKEY_HELP315 
PGKEY_PRINT316 
PGKEY_SYSREQ317 
PGKEY_BREAK318 
PGKEY_MENU319 
PGKEY_POWER320Power Macintosh powerkey
PGKEY_EURO321Some european keyboards
PGKEY_ALPHA322Selects letters on a numeric keypad (for celphones and similar devices)

Table G-2. PGMOD values

PGMOD_LSHIFT0001 
PGMOD_RSHIFT0002 
PGMOD_SHIFT0003 
PGMOD_LCTRL0040 
PGMOD_RCTRL0080 
PGMOD_CTRL00C0 
PGMOD_LALT0100 
PGMOD_RALT0200 
PGMOD_ALT0300 
PGMOD_LMETA0400 
PGMOD_RMETA0800 
PGMOD_META0C00 
PGMOD_NUM1000 
PGMOD_CAPS2000 
PGMOD_MODE4000 

Appendix H. Theme Constants

H.1. Theme Object Types

Table H-1. PGTH_O values

PGTH_O_DEFAULT0Every theme object inherits this
PGTH_O_BASE_INTERACTIVE1Base for interactive widgets
PGTH_O_BASE_CONTAINER2Base for containers like toolbars
PGTH_O_BUTTON3The button widget
PGTH_O_BUTTON_HILIGHT4Button, hilighted when mouse is over
PGTH_O_BUTTON_ON5Button, mouse is pressed
PGTH_O_TOOLBAR6The toolbar widget
PGTH_O_SCROLL7The scrollbar widget
PGTH_O_SCROLL_HILIGHT8Scroll, when mouse is over it
PGTH_O_INDICATOR9The indicator widget
PGTH_O_PANEL10The background portion of a panel
PGTH_O_PANELBAR11The draggable titlebar of a panel
PGTH_O_POPUP12Popup window
PGTH_O_BACKGROUND13Background widget bitmap
PGTH_O_BASE_DISPLAY14Base for widgets that mostly display stuff
PGTH_O_BASE_TLCONTAINER15Top-level containers like popups, panels
PGTH_O_THEMEINFO16Information about the theme that should be loaded into memory, like the name
PGTH_O_LABEL17The label widget
PGTH_O_FIELD18The field widget
PGTH_O_BITMAP19The bitmap widget
PGTH_O_SCROLL_ON20Scroll, when mouse is down
PGTH_O_LABEL_SCROLL21A label, when bound to a scrollbar
PGTH_O_PANELBAR_HILIGHT22A panelbar, when mouse is inside it
PGTH_O_PANELBAR_ON23A panelbar, when mouse is down
PGTH_O_BOX24The box widget
PGTH_O_LABEL_DLGTITLE25A label, used for a dialog box title
PGTH_O_LABEL_DLGTEXT26A label, used for the body of a dialog
PGTH_O_CLOSEBTN27A panelbar close button
PGTH_O_CLOSEBTN_ON28A panelbar close button, mouse down
PGTH_O_CLOSEBTN_HILIGHT29A panelbar close button, mouse over
PGTH_O_BASE_PANELBTN30Base for a panelbar button
PGTH_O_ROTATEBTN31A panelbar rotate button
PGTH_O_ROTATEBTN_ON32A panelbar rotate button, mouse down
PGTH_O_ROTATEBTN_HILIGHT33A panelbar rotate button, mouse over
PGTH_O_ZOOMBTN34A panelbar zoom button
PGTH_O_ZOOMBTN_ON35A panelbar zoom button, mouse down
PGTH_O_ZOOMBTN_HILIGHT36A panelbar zoom button, mouse over
PGTH_O_POPUP_MENU37A popup menu
PGTH_O_POPUP_MESSAGEDLG38A message dialog
PGTH_O_MENUITEM39Item in a popup menu (customized button)
PGTH_O_MENUITEM_HILIGHT40menuitem with the mouse over it
PGTH_O_CHECKBOX41Check box (customized button)
PGTH_O_CHECKBOX_HILIGHT42checkbox with mouse over it
PGTH_O_CHECKBOX_ON43checkbox when on
PGTH_O_FLATBUTTON44Flat button (customized button)
PGTH_O_FLATBUTTON_HILIGHT45flatbutton with mouse over it
PGTH_O_FLATBUTTON_ON46flatbutton with mouse down
PGTH_O_LISTITEM47Listitem (customized button)
PGTH_O_LISTITEM_HILIGHT48Listitem with mouse over it
PGTH_O_LISTITEM_ON49Selected listitem
PGTH_O_CHECKBOX_ON_NOHILIGHT50checkbox when on but not hilighted
PGTH_O_SUBMENUITEM51Submenuitem
PGTH_O_SUBMENUITEM_HILIGHT52Hilighted submenuitem
PGTH_O_RADIOBUTTON53Radio button (cust. button)
PGTH_O_RADIOBUTTON_HILIGHT54Radio button (cust. button)
PGTH_O_RADIOBUTTON_ON55Radio button (cust. button)
PGTH_O_RADIOBUTTON_ON_NOHILIGHT56Radio button (cust. button)
PGTH_O_TEXTBOX57Textbox widget
PGTH_O_TERMINAL58Terminal widget
PGTH_O_MENUBUTTON60DSPLinux Application Menu
PGTH_O_MENUBUTTON_ON61DSPLinux Application Menu
PGTH_O_MENUBUTTON_HILIGHT62DSPLinux Application Menu
PGTH_O_LABEL_HILIGHT63Label hilight or select - See PG_WP_HILIGHTED
PGTH_O_BOX_HILIGHT64Box hilight or select - See PG_WP_HILIGHTED
PGTH_O_INDICATOR_H65Horizontal indicator
PGTH_O_INDICATOR_V66Vertical indicator

H.2. Theme Property Types

Table H-2. PGTH_P values

PGTH_P_BGCOLOR1Default background color
PGTH_P_FGCOLOR2Default foreground color
PGTH_P_BGFILL3Background fillstyle
PGTH_P_OVERLAY4Fillstyle for scroll thumbs, the filled portion of an indicator
PGTH_P_FONT5A widget's main font
PGTH_P_NAME6Name of the theme object, themes can be searched by this
PGTH_P_WIDTH7Reccomended width
PGTH_P_HEIGHT8Reccomended height
PGTH_P_MARGIN9The border in some objects
PGTH_P_HILIGHTCOLOR10Color for hilighting an object
PGTH_P_SHADOWCOLOR11Color for shading an object
PGTH_P_OFFSET12An amount to displace something by
PGTH_P_ALIGN13How to position an object's contents
PGTH_P_BITMAPSIDE14Bitmap side relative to text (button)
PGTH_P_BITMAPMARGIN15Spacing between bitmap and text
PGTH_P_BITMAP116Generic bitmap property for theme use
PGTH_P_BITMAP217Generic bitmap property for theme use
PGTH_P_BITMAP318Generic bitmap property for theme use
PGTH_P_BITMAP419Generic bitmap property for theme use
PGTH_P_SPACING20Distance between similar widgets
PGTH_P_TEXT21Text caption for something like a button
PGTH_P_SIDE22Side for a widget or subwidget
PGTH_P_BACKDROP23Fillstyle on the screen behind a popup
PGTH_P_WIDGETBITMAP24Bitmap for something like a button
PGTH_P_WIDGETBITMASK25Bitmask for something like a button
PGTH_P_CURSORBITMAP26Bitmap for the (mouse) pointer
PGTH_P_CURSORBITMASK27Bitmask for the (mouse) pointer
PGTH_P_HIDEHOTKEYS28Set to a PG_HHK_* constant
PGTH_P_ATTR_DEFAULT29Default attribute for the terminal
PGTH_P_ATTR_CURSOR30Default attribute for the terminal
PGTH_P_TEXTCOLORS31Text color pallete for the terminal
PGTH_P_TIME_ON32Milliseconds on for flashing cursor
PGTH_P_TIME_OFF33Milliseconds off for flashing cursor
PGTH_P_TIME_DELAY34Milliseconds to wait before flashing
PGTH_P_PARENT35Overrides the default theme inheritance
PGTH_P_ICON_OK1000Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_OK_MASK1001Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_CANCEL1002Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_CANCEL_MASK1003Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_YES1004Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_YES_MASK1005Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_NO1006Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_NO_MASK1007Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_ERROR1008Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_ERROR_MASK1009Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_MESSAGE1010Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_MESSAGE_MASK1011Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_QUESTION1012Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_QUESTION_MASK1013Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_WARNING1014Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_ICON_WARNING_MASK1015Icon property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_OK1501Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_CANCEL1502Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_YES1503Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_NO1504Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_UP1505Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_DOWN1506Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_LEFT1507Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_RIGHT1508Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_ACTIVATE1509Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_HOTKEY_NEXT1510Hotkey property (usually in PGTH_O_DEFAULT)
PGTH_P_USER10000Application-defined theme property start range
PGTH_P_THEMEAUTO20000Automatically 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_BACKLIGHT2Turn the backlight on/off
PGDM_SOUNDFX3Parameter is a PG_SND_* constant
PGDM_POWER4Enter the power mode, PG_POWER_*
PGDM_SDC_CHAR5Send a character to the secondary display channel
PGDM_BRIGHTNESS6Set display brightness, 0x00-0xFF
PGDM_CONTRAST7Set display contrast, 0x00-0xFF
PGDM_SIGNAL13Internal message, sends SIGUSR1/2 to drivers (param is signal)
PGDM_READY14Notify the drivers that the server is completely up

Appendix J. Event Constants

J.1. Widget Events

Table J-1. PG_WE values

PG_WE_ACTIVATE0x001Button has been clicked/selected
PG_WE_DEACTIVATE0x002Sent when the user clicks outside the active popup
PG_WE_CLOSE0x003A top-level widget has closed
PG_WE_FOCUS0x004Sent when a button is focused, only if it has PG_EXEV_FOCUS. The field widget always sends this.
PG_WE_PNTR_DOWN0x204The "mouse" button is now down
PG_WE_PNTR_UP0x205The "mouse" button is now up
PG_WE_PNTR_RELEASE0x206The "mouse" button was released outside the widget
PG_WE_DATA0x306Widget is streaming data to the app
PG_WE_RESIZE0x107For terminal widgets
PG_WE_BUILD0x108Sent from a canvas, clients can rebuild groplist
PG_WE_PNTR_MOVE0x209The "mouse" moved
PG_WE_KBD_CHAR0x40AA focused keyboard character recieved
PG_WE_KBD_KEYUP0x40BA focused raw keyup event
PG_WE_KBD_KEYDOWN0x40CA focused raw keydown event
PG_WE_APPMSG0x301Messages from another application

J.2. Non-Widget Events

Table J-2. PG_NWE values

PG_NWE_THEME_INSERTED0x1001This 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_REMOVED0x1002This 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_INFILTER0x1302Carries 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_FONT0The server's default font handle
PGRES_STRING_OK1"Ok"
PGRES_STRING_CANCEL2"Cancel"
PGRES_STRING_YES3"Yes"
PGRES_STRING_NO4"No"
PGRES_STRING_SEGFAULT5"Segmentation Fault"
PGRES_STRING_MATHERR6"Floating Point Exception or Divide by Zero"
PGRES_STRING_PGUIERR7"PicoGUI Error"
PGRES_STRING_PGUIWARN8"PicoGUI Warning"
PGRES_STRING_PGUIERRDLG9"An error of type %s occurred in %s:\n\n%s\n\nTerminate the application?"
PGRES_STRING_PGUICOMPAT10"This PicoGUI application uses a newer protocol than the server.You may experience compatibility problems."
PGRES_DEFAULT_TEXTCOLORS11The server's default terminal palette
PGRES_INFILTER_TOUCHSCREEN12Input filter for touchscreen calibration and filtering
PGRES_INFILTER_KEY_PREPROCESS13Input filter for performing extra processing on keys before dispatching them
PGRES_INFILTER_PNTR_PREPROCESS14Input filter to do coordinate conversion on pointing events, and other processing if applicable
PGRES_INFILTER_MAGIC15Input filter for handling CTRL-ALT-* debug keys
PGRES_INFILTER_KEY_DISPATCH16Input filter for dispatching key events
PGRES_INFILTER_PNTR_DISPATCH17Input filter for dispatching pointing events
PGRES_DEFAULT_CURSORBITMAP18The bitmap for the default cursor
PGRES_DEFAULT_CURSORBITMASK19The bitmask for the default cursor
PGRES_BACKGROUND_WIDGET20The server-owned widget that takes up leftover space
PGRES_INFILTER_HOTSPOT21Input filter to manage global hotspot-navigation keys
PGRES_INFILTER_KEY_ALPHA22Input filter that manages PGKEY_ALPHA
PGRES_INFILTER_PNTR_NORMALIZE23Input 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.