Interaction

Functions for interacting with the user and window system.

PUGL_NUM_CURSORS

10U

The number of PuglCursor values.

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.

enumerator PUGL_CURSOR_UP_LEFT_DOWN_RIGHT

Diagonal arrow for down/right resize.

enumerator PUGL_CURSOR_UP_RIGHT_DOWN_LEFT

Diagonal arrow for down/left resize.

enumerator PUGL_CURSOR_ALL_SCROLL

Omnidirectional “arrow” for scrolling.

PuglStatus puglAcceptOffer(PuglView *view, const PuglDataOfferEvent *offer, uint32_t typeIndex, PuglDataAction action, int regionX, int regionY, unsigned regionWidth, unsigned regionHeight)

Accept data offered from a clipboard.

To accept data, 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().

The region parameters specify a region of the view that will accept the data, which may be used by the system to avoid sending redundant events.

Parameters:

  • view – The view.

  • offer – The data offer event.

  • typeIndex – Index of the type the view will accept, which can be identified with puglGetClipboardType().

  • action – The action to be performed on the data. This may be used to provide visual feedback to the user, for example by changing the cursor.

  • regionX – View-relative top-left X coordinate of the accepting region.

  • regionY – View-relative top-left Y coordinate of the accepting region.

  • regionWidth – Width of the accepting region.

  • regionHeight – Height of the accepting region.

const void *puglGetClipboard(PuglView *view, PuglClipboard clipboard, uint32_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.

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

Return the identifier of a type available in a clipboard.

This is usually a MIME type, but may also be another platform-specific type identifier. Applications must ignore any type they don’t recognize.

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

uint32_t puglGetNumClipboardTypes(const PuglView *view, PuglClipboard clipboard)

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

Returns zero if the clipboard is empty.

PuglStatus puglGrabFocus(PuglView *view)

Grab the keyboard input focus.

Note that this will fail if the view isn’t mapped and so shouldn’t, for example, be called immediately after puglShow().

Returns:

PuglStatus.PUGL_SUCCESS if the focus was successfully grabbed, or an error.

bool puglHasFocus(const PuglView *view)

Return whether view has the keyboard input focus.

Returns:

True if the view is realized and focused for keyboard input.

PuglStatus puglPaste(PuglView *view)

Request data from the general copy/paste clipboard.

A PuglEventType.PUGL_DATA_OFFER event will be sent if data is available.

PuglStatus puglRejectOffer(PuglView *view, const PuglDataOfferEvent *offer, int regionX, int regionY, unsigned regionWidth, unsigned regionHeight)

Reject data offered from a clipboard.

This can be called instead of puglAcceptOffer() to explicitly reject the offer. Note that drag-and-drop will still work if this isn’t called, but applications should always explicitly accept or reject each data offer for optimal behaviour.

The region parameters specify a region of the view that will refuse the data, which may be used by the system to avoid sending redundant events.

Parameters:

  • view – The view.

  • offer – The data offer event.

  • regionX – The top-left X coordinate of the rejecting region.

  • regionY – The top-left Y coordinate of the rejecting region.

  • regionWidth – The width of the rejecting region.

  • regionHeight – The height of the rejecting region.

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 any other. Only a few event types are currently supported.

Opaque PuglEventType.PUGL_CLIENT events are supported on all platforms.

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

Returns:

PuglStatus.PUGL_UNSUPPORTED if sending this type of event isn’t supported in general, PuglStatus.PUGL_FAILURE if the event can’t be sent now.

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

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 isn’t 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_UNSUPPORTED if setting the cursor isn’t supported on this system, or another error if the cursor is known but loading it fails.

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, usually a small positive integer enumerator. Only a limited number of timers is supported, and each adds overhead, so applications should create only a few timers, and perform several tasks in each if necessary.

  • timeout – The period, in seconds, of this timer. The maximum supported resolution is about 10 ms on Windows, and about 1 ms on X11 and MacOS.

Returns:

PuglStatus.PUGL_FAILURE if timers aren’t 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 aren’t supported by this system, PuglStatus.PUGL_UNKNOWN_ERROR if stopping the timer failed.