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 puglSetClipboard(PuglView *view, 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.

  • 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, const char **type, 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.

  • type – Set to the MIME type of the data.

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