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.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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

/* 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

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.

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.

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:

/* 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

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

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

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.

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.

struct pgreqd_regowner {
  u16 res;
};
   

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

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

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.

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.

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.

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.

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.

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).

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.

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.

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

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

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.

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.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]

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.

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.

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.

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).

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.