Interaction

Functions for interacting with the user and window system.

enum PuglCursor

A mouse cursor type.

This is a portable subset of mouse cursors that exist on X11, MacOS, and Windows.

enumerator PUGL_CURSOR_ARROW

Default pointing arrow.

enumerator PUGL_CURSOR_CARET

Caret (I-Beam) for text entry.

enumerator PUGL_CURSOR_CROSSHAIR

Cross-hair.

enumerator PUGL_CURSOR_HAND

Hand with a pointing finger.

enumerator PUGL_CURSOR_NO

Operation not allowed.

enumerator PUGL_CURSOR_LEFT_RIGHT

Left/right arrow for horizontal resize.

enumerator PUGL_CURSOR_UP_DOWN

Up/down arrow for vertical resize.

PuglStatus puglGrabFocus(PuglView *view)

Grab the keyboard input focus.

bool puglHasFocus(const PuglView *view)

Return whether view has the keyboard input focus.

PuglStatus puglPaste(PuglView *view)

Request data from the general copy/paste clipboard.

PuglStatus puglRegisterDragType(PuglView *view, const char *type)

Register a type as supported for drag and drop.

Before realizing the view, this function should be called for every type the view may accept as a drop target.

size_t puglGetNumClipboardTypes(PuglView *view, PuglClipboard clipboard)

Return the number of types available for the value in a clipboard.

Returns zero if the clipboard is empty.

const char *puglGetClipboardType(PuglView *view, PuglClipboard clipboard, size_t typeIndex)

Return the identifier of a type available in a clipboard.

Returns null if typeIndex is out of bounds according to puglGetNumClipboardTypes().

PuglStatus puglAcceptOffer(PuglView *view, const PuglDataOfferEvent *offer, size_t typeIndex, PuglAction action, PuglRect region)

Accept data offered from a clipboard.

To accept a drop, this must be called while handling a PuglEventType.PUGL_DATA_OFFER event. Doing so will request the data from the source as the specified type. When the data is available, a PuglEventType.PUGL_DATA event will be sent to the view which can then retrieve the data with puglGetClipboard().

Parameters

  • view – The view that received the data offer.

  • offer – The data offer event.

  • typeIndex – The index of the type that the view will accept. This is the typeIndex argument to the call of puglGetClipboardType() that returned the accepted type.

  • action – The action that will be performed when the data is dropped. This may be used to provide visual feedback to the user, for example by having the drag source change the cursor.

  • region – The region of the view that will accept this drop. This may be used by the system to avoid sending redundant events when the item is dragged within the region. This is only an optimization, an all-zero region can safely be passed.

PuglStatus puglRejectOffer(PuglView *view, const PuglDataOfferEvent *offer, PuglRect region)

Reject data offered from a clipboard.

FIXME: remove?

PuglStatus puglSetClipboard(PuglView *view, PuglClipboard clipboard, const char *type, const void *data, size_t len)

Set the clipboard contents.

This sets the system clipboard contents, which can be retrieved with puglGetClipboard() or pasted into other applications.

Parameters

  • view – The view.

  • clipboard – Clipboard to set data for.

  • type – The MIME type of the data, “text/plain” is assumed if NULL.

  • data – The data to copy to the clipboard.

  • len – The length of data in bytes (including terminator if necessary).

const void *puglGetClipboard(PuglView *view, PuglClipboard clipboard, size_t typeIndex, size_t *len)

Get the clipboard contents.

This gets the system clipboard contents, which may have been set with puglSetClipboard() or copied from another application.

Parameters

  • view – The view.

  • clipboard – Clipboard to get data from.

  • typeIndex – Index of the data type to get the item as.

  • len – Set to the length of the data in bytes.

Returns

The clipboard contents, or null.

PuglStatus puglSetCursor(PuglView *view, PuglCursor cursor)

Set the mouse cursor.

This changes the system cursor that is displayed when the pointer is inside the view. May fail if setting the cursor is not supported on this system, for example if compiled on X11 without Xcursor support.

Returns

PuglStatus.PUGL_BAD_PARAMETER if the given cursor is invalid, PuglStatus.PUGL_FAILURE if the cursor is known but loading it system fails.

PuglStatus puglRequestAttention(PuglView *view)

Request user attention.

This hints to the system that the window or application requires attention from the user. The exact effect depends on the platform, but is usually something like a flashing task bar entry or bouncing application icon.

PuglStatus puglStartTimer(PuglView *view, uintptr_t id, double timeout)

Activate a repeating timer event.

This starts a timer which will send a PuglTimerEvent to view every timeout seconds. This can be used to perform some action in a view at a regular interval with relatively low frequency. Note that the frequency of timer events may be limited by how often puglUpdate() is called.

If the given timer already exists, it is replaced.

Parameters

  • view – The view to begin sending PuglEventType.PUGL_TIMER events to.

  • id – The identifier for this timer. This is an application-specific ID that should be a low number, typically the value of a constant or enum that starts from 0. There is a platform-specific limit to the number of supported timers, and overhead associated with each, so applications should create only a few timers and perform several tasks in one if necessary.

  • timeout – The period, in seconds, of this timer. This is not guaranteed to have a resolution better than 10ms (the maximum timer resolution on Windows) and may be rounded up if it is too short. On X11 and MacOS, a resolution of about 1ms can usually be relied on.

Returns

PuglStatus.PUGL_FAILURE if timers are not supported by the system, PuglStatus.PUGL_UNKNOWN_ERROR if setting the timer failed.

PuglStatus puglStopTimer(PuglView *view, uintptr_t id)

Stop an active timer.

Parameters

  • view – The view that the timer is set for.

  • id – The ID previously passed to puglStartTimer().

Returns

PuglStatus.PUGL_FAILURE if timers are not supported by this system, PuglStatus.PUGL_UNKNOWN_ERROR if stopping the timer failed.

PuglStatus puglSendEvent(PuglView *view, const PuglEvent *event)

Send an event to a view via the window system.

If supported, the event will be delivered to the view via the event loop like other events. Note that this function only works for certain event types.

Currently, only PuglEventType.PUGL_CLIENT events are supported on all platforms.

X11: A PuglEventType.PUGL_EXPOSE event can be sent, which is similar to calling puglPostRedisplayRect(), but will always send a message to the X server, even when called in an event handler.

Returns

PuglStatus.PUGL_UNSUPPORTED_TYPE if sending events of this type is not supported, PuglStatus.PUGL_UNKNOWN_ERROR if sending the event failed.