Interaction

Macros
#define	PUGL_NUM_CURSORS   ((unsigned)PUGL_CURSOR_ANTI_DIAGONAL + 1u)
	The number of PuglCursor values.

Enumerations
enum	PuglCursor {   PUGL_CURSOR_ARROW , PUGL_CURSOR_CARET , PUGL_CURSOR_CROSSHAIR , PUGL_CURSOR_HAND ,   PUGL_CURSOR_NO , PUGL_CURSOR_LEFT_RIGHT , PUGL_CURSOR_UP_DOWN , PUGL_CURSOR_DIAGONAL ,   PUGL_CURSOR_ANTI_DIAGONAL }

Functions
PUGL_API PuglStatus	puglGrabFocus (PuglView *view)
PUGL_API bool	puglHasFocus (const PuglView *view)
	Return whether View has the keyboard input focus.
PUGL_API PuglStatus	puglPaste (PuglView *view)
PUGL_API uint32_t	puglGetNumClipboardTypes (const PuglView *view)
PUGL_API const char *	puglGetClipboardType (const PuglView *view, uint32_t typeIndex)
PUGL_API PuglStatus	puglAcceptOffer (PuglView *view, const PuglDataOfferEvent *offer, uint32_t typeIndex)
PUGL_API PuglStatus	puglSetClipboard (PuglView *view, const char *type, const void *data, size_t len)
PUGL_API const void *	puglGetClipboard (PuglView *view, uint32_t typeIndex, size_t *len)
PUGL_API PuglStatus	puglSetCursor (PuglView *view, PuglCursor cursor)
PUGL_API PuglStatus	puglRequestAttention (PuglView *view)
PUGL_API PuglStatus	puglStartTimer (PuglView *view, uintptr_t id, double timeout)
PUGL_API PuglStatus	puglStopTimer (PuglView *view, uintptr_t id)
PUGL_API PuglStatus	puglSendEvent (PuglView *view, const PuglEvent *event)

Detailed Description

Functions for interacting with the user and window system.

Macro Definition Documentation

PUGL_NUM_CURSORS

#define PUGL_NUM_CURSORS   ((unsigned)PUGL_CURSOR_ANTI_DIAGONAL + 1u)

The number of PuglCursor values.

Enumeration Type Documentation

PuglCursor

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.
PUGL_CURSOR_CARET	Caret (I-Beam) for text entry.
PUGL_CURSOR_CROSSHAIR	Cross-hair.
PUGL_CURSOR_HAND	Hand with a pointing finger.
PUGL_CURSOR_NO	Operation not allowed.
PUGL_CURSOR_LEFT_RIGHT	Left/right arrow for horizontal resize.
PUGL_CURSOR_UP_DOWN	Up/down arrow for vertical resize.
PUGL_CURSOR_DIAGONAL	Top-left to bottom-right arrow for diagonal resize.
PUGL_CURSOR_ANTI_DIAGONAL	Bottom-left to top-right arrow for diagonal resize.

Function Documentation

puglAcceptOffer()

PUGL_API PuglStatus puglAcceptOffer	(	PuglView *	view,
		const PuglDataOfferEvent *	offer,
		uint32_t	typeIndex )

Accept data offered from a clipboard.

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

Parameters

View	The view.
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.

puglGetClipboard()

PUGL_API const void * puglGetClipboard	(	PuglView *	view,
		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.
	typeIndex	Index of the data type to get the item as.
[out]	len	Set to the length of the data in bytes.

Returns

The clipboard contents, or null.

puglGetClipboardType()

PUGL_API const char * puglGetClipboardType	(	const PuglView *	view,
		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 do not recognize.

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

puglGetNumClipboardTypes()

PUGL_API uint32_t puglGetNumClipboardTypes

(

const PuglView *

view

)

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

Returns zero if the clipboard is empty.

puglGrabFocus()

PUGL_API PuglStatus puglGrabFocus

(

PuglView *

view

)

Grab the keyboard input focus.

Note that this will fail if the view is not mapped and so should not, for example, be called immediately after puglShow().

Returns

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

puglHasFocus()

PUGL_API bool puglHasFocus

(

const PuglView *

view

)

Return whether View has the keyboard input focus.

puglPaste()

PUGL_API PuglStatus puglPaste

(

PuglView *

view

)

Request data from the general copy/paste clipboard.

A PUGL_DATA_OFFER event will be sent if data is available.

puglRequestAttention()

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

puglSendEvent()

PUGL_API 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 PUGL_CLIENT events are supported on all platforms.

X11: A 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

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

puglSetClipboard()

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

puglSetCursor()

PUGL_API 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

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

puglStartTimer()

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

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

puglStopTimer()

PUGL_API 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

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