PtClient

Client widget

Class hierarchy:

PtWidgetPtBasicPtContainerPtClient

Immediate subclasses:

For more information, see the diagram of the widget hierarchy.

PhAB icon:

None — not normally instantiated.

Public header:

<photon/PtClient.h>

Description:

PtClient and PtServer let one process (the “server”) display widgets in a window that belongs to another process (the “client”).

PtClient and PtServer use a Photon connection to communicate (see Connections in the Interprocess Communications chapter of the Photon Programmer's Guide), but they have a few resources that in most cases let applications avoid dealing with connection objects directly.

A PtClient widget creates a parent region for a PtServer widget and handles the process of connecting to a PtServer. Then, the client controls the server's size and notifies it of certain events in order to make the server look and feel as if it were just another container in the client's window. Additionally, PtClient lets your application send arbitrary messages to the server process.

New resources:

Resource C type Pt type Default
Pt_ARG_CLIENT_FLAGS unsigned Flags 0
Pt_ARG_CLIENT_NAME char * String NULL
Pt_ARG_CLIENT_REPLY_LEN unsigned Scalar 0
Pt_ARG_CLIENT_SEND char, unsigned Array NULL, 0
Pt_ARG_CLIENT_SERVER PtConnectionClient_t * Pointer NULL
Pt_CB_CLIENT_CONNECTED PtCallback_t * Link NULL
Pt_CB_CLIENT_ERROR PtCallback_t * Link NULL
Pt_CB_CLIENT_EVENT PtCallback_t * Link NULL
Pt_CB_CLIENT_NOT_FOUND PtCallback_t * Link NULL

Pt_ARG_CLIENT_FLAGS

C type Pt type Default
unsigned Flags 0

Flags that control the behavior of the widget:

Pt_CLIENT_NOEVENTS
Setting this flag tells the widget that the server doesn't use the Pt_ARG_SERVER_SEND resource.
Pt_CLIENT_NONBLOCK
If this flag is clear, the call to PtSetResources() that sets Pt_ARG_CLIENT_NAME doesn't return until the connecting has either succeeded or been aborted.

If the flag is set, setting the Pt_ARG_CLIENT_NAME is nonblocking, and the connecting is performed in background, after PtSetResources() has returned.

Pt_ARG_CLIENT_NAME

C type Pt type Default
char * String NULL

The connector name to which to connect. Setting this resource initiates the process of connecting to a server.

If the connection isn't successful, the widget's Pt_CB_CLIENT_NOT_FOUND callbacks are invoked.

Pt_ARG_CLIENT_REPLY_LEN

C type Pt type Default
unsigned Scalar 0

The maximum length of a reply from the server, in bytes. See Pt_ARG_CLIENT_SEND.

Pt_ARG_CLIENT_SEND

C type Pt type Default
char, unsigned Array NULL, 0

When you set this resource, the widget sends a message to its PtServer. The message invokes a Pt_CB_SERVER_RECEIVE callback in the server that lets the server specify a reply. The reply is then available in the client by getting the Pt_ARG_CLIENT_SEND resource (the length gives you the actual length of the reply, not the size of the buffer).

Pt_ARG_CLIENT_SERVER (read only)

C type Pt type Default
PtConnectionClient_t * Pointer NULL

A pointer to the connection object used for communicating to the PtServer. Don't use this pointer for anything other than checking to see if it's NULL.

Pt_CB_CLIENT_CONNECTED

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that are invoked when the client connects to the server. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason
Pt_CB_CLIENT_CONNECTED
reason_subtype
0 (not used).
event
NULL.
cbdata
NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_CLIENT_ERROR

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that are invoked when an error occurs.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason
Pt_CB_CLIENT_ERROR
reason_subtype
0 (not used).
event
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
cbdata
A pointer to a PtClientErrorCallback_t structure that contains at least:

These callbacks should return Pt_CONTINUE.

Pt_CB_CLIENT_EVENT

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that are invoked for each message sent by the server's Pt_ARG_SERVER_SEND resource.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason
Pt_CB_CLIENT_EVENT
reason_subtype
0 (not used).
event
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
cbdata
A pointer to a PtClientCallback_t structure that contains at least:

These callbacks should return Pt_CONTINUE.

Pt_CB_CLIENT_NOT_FOUND

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that are invoked if the widget fails to find the server specified when you set Pt_ARG_CLIENT_NAME.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason
Pt_CB_CLIENT_NOT_FOUND
reason_subtype
0 (not used).
event
NULL.
cbdata
A pointer to an int initialized to Pt_END. Set it to Pt_CONTINUE if you want the widget to retry after a little while. Typically, the first Pt_CB_CLIENT_NOT_FOUND callback spawns the server, and any subsequent Pt_CB_CLIENT_NOT_FOUND callback checks whether or not the server is still running, and abort the connecting if the server has terminated.

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget 0
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_OVERRIDE PtContainer
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_STYLE PtBasic
Pt_ARG_TITLE PtContainer
Pt_ARG_TITLE_FONT PtContainer
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer
Pt_CB_BLOCKED PtWidget
Pt_CB_CHILD_ADDED_REMOVED PtContainer
Pt_CB_CHILD_GETTING_FOCUS PtContainer
Pt_CB_CHILD_LOSING_FOCUS PtContainer
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_RESIZE PtContainer
Pt_CB_UNREALIZED PtWidget