View

Detailed Description

A drawable region that receives events.

A view can be thought of as a window, but does not necessarily correspond to a top-level window in a desktop environment. For example, a view can be embedded in some other window, or represent an embedded system where there is no concept of multiple windows at all.

Typedefs
typedef struct PuglViewImpl	PuglView
typedef struct PuglBackendImpl	PuglBackend
typedef uintptr_t	PuglNativeWindow
typedef void *	PuglHandle
typedef PuglStatus(*	PuglEventFunc) (PuglView *view, const PuglEvent *event)

Enumerations
enum	PuglViewHint
enum	PuglViewHintValue

Setup
Functions for creating and destroying a view.
PuglView *	puglNewView (PuglWorld *world)
void	puglFreeView (PuglView *view)
PuglWorld *	puglGetWorld (PuglView *view)
void	puglSetHandle (PuglView *view, PuglHandle handle)
PuglHandle	puglGetHandle (PuglView *view)
PuglStatus	puglSetBackend (PuglView *view, const PuglBackend *backend)
PuglStatus	puglSetEventFunc (PuglView *view, PuglEventFunc eventFunc)
PuglStatus	puglSetViewHint (PuglView *view, PuglViewHint hint, int value)

Frame
Functions for working with the position and size of a view.
PuglRect	puglGetFrame (const PuglView *view)
PuglStatus	puglSetFrame (PuglView *view, PuglRect frame)
PuglStatus	puglSetMinSize (PuglView *view, int width, int height)
PuglStatus	puglSetAspectRatio (PuglView *view, int minX, int minY, int maxX, int maxY)

Windows
Functions for working with top-level windows.
PuglStatus	puglSetWindowTitle (PuglView *view, const char *title)
PuglStatus	puglSetParentWindow (PuglView *view, PuglNativeWindow parent)
PuglStatus	puglSetTransientFor (PuglView *view, PuglNativeWindow parent)
PuglStatus	puglCreateWindow (PuglView *view, const char *title)
PuglStatus	puglShowWindow (PuglView *view)
PuglStatus	puglHideWindow (PuglView *view)
bool	puglGetVisible (PuglView *view)
PuglNativeWindow	puglGetNativeWindow (PuglView *view)

Graphics
Functions for working with the graphics context and scheduling redisplays.
void *	puglGetContext (PuglView *view)
PuglStatus	puglEnterContext (PuglView *view, bool drawing)
PuglStatus	puglLeaveContext (PuglView *view, bool drawing)
PuglStatus	puglPostRedisplay (PuglView *view)
PuglStatus	puglPostRedisplayRect (PuglView *view, PuglRect rect)

Interaction
Functions for interacting with the user.
PuglStatus	puglGrabFocus (PuglView *view)
bool	puglHasFocus (const PuglView *view)
PuglStatus	puglSetClipboard (PuglView *view, const char *type, const void *data, size_t len)
const void *	puglGetClipboard (PuglView *view, const char **type, size_t *len)
PuglStatus	puglRequestAttention (PuglView *view)

Typedef Documentation

PuglView

typedef struct PuglViewImpl PuglView

A drawable region that receives events.

PuglBackend

typedef struct PuglBackendImpl PuglBackend

A graphics backend.

The backend dictates how graphics are set up for a view, and how drawing is performed. A backend must be set by calling puglSetBackend() before realising a view.

If you are using a local copy of Pugl, it is possible to implement a custom backend. See the definition of PuglBackendImpl in the source code for details.

PuglNativeWindow

typedef uintptr_t PuglNativeWindow

A native window handle.

X11: This is a Window.

MacOS: This is a pointer to an NSView*.

Windows: This is a HWND.

PuglHandle

typedef void* PuglHandle

Handle for opaque user data.

PuglEventFunc

typedef PuglStatus(* PuglEventFunc) (PuglView *view, const PuglEvent *event)

A function called when an event occurs.

Enumeration Type Documentation

PuglViewHint

enum PuglViewHint

A hint for configuring a view.

Enumerator
PUGL_USE_COMPAT_PROFILE	Use compatible (not core) OpenGL profile.
PUGL_USE_DEBUG_CONTEXT	True to use a debug OpenGL context.
PUGL_CONTEXT_VERSION_MAJOR	OpenGL context major version.
PUGL_CONTEXT_VERSION_MINOR	OpenGL context minor version.
PUGL_RED_BITS	Number of bits for red channel.
PUGL_GREEN_BITS	Number of bits for green channel.
PUGL_BLUE_BITS	Number of bits for blue channel.
PUGL_ALPHA_BITS	Number of bits for alpha channel.
PUGL_DEPTH_BITS	Number of bits for depth buffer.
PUGL_STENCIL_BITS	Number of bits for stencil buffer.
PUGL_SAMPLES	Number of samples per pixel (AA)
PUGL_DOUBLE_BUFFER	True if double buffering should be used.
PUGL_SWAP_INTERVAL	Number of frames between buffer swaps.
PUGL_RESIZABLE	True if window should be resizable.
PUGL_IGNORE_KEY_REPEAT	True if key repeat events are ignored.
PUGL_NUM_WINDOW_HINTS

PuglViewHintValue

enum PuglViewHintValue

A special view hint value.

Enumerator
PUGL_DONT_CARE	Use best available value.
PUGL_FALSE	Explicitly false.
PUGL_TRUE	Explicitly true.

Function Documentation

puglNewView()

PuglView* puglNewView

(

PuglWorld *

world

)

Create a new view.

A newly created view does not correspond to a real system view or window. It must first be configured, then be realised by calling puglCreateWindow().

puglFreeView()

void puglFreeView

(

PuglView *

view

)

Free a view created with puglNewView().

puglGetWorld()

PuglWorld* puglGetWorld

(

PuglView *

view

)

Return the world that view is a part of.

puglSetHandle()

void puglSetHandle	(	PuglView *	view,
		PuglHandle	handle
	)

Set the user data for a view.

This is usually a pointer to a struct that contains all the state which must be accessed by a view. Everything needed to process events should be stored here, not in static variables.

The handle is opaque to Pugl and is not interpreted in any way.

puglGetHandle()

PuglHandle puglGetHandle

(

PuglView *

view

)

Get the user data for a view.

puglSetBackend()

PuglStatus puglSetBackend	(	PuglView *	view,
		const PuglBackend *	backend
	)

Set the graphics backend to use for a view.

This must be called once to set the graphics backend before calling puglCreateWindow().

Pugl includes the following backends:

• puglGlBackend(), declared in pugl_gl.h
• puglCairoBackend(), declared in pugl_cairo.h

Note that backends are modular and not compiled into the main Pugl library to avoid unnecessary dependencies. To use a particular backend, applications must link against the appropriate backend library, or be sure to compile in the appropriate code if using a local copy of Pugl.

puglSetEventFunc()

PuglStatus puglSetEventFunc	(	PuglView *	view,
		PuglEventFunc	eventFunc
	)

Set the function to call when an event occurs.

puglSetViewHint()

PuglStatus puglSetViewHint	(	PuglView *	view,
		PuglViewHint	hint,
		int	value
	)

Set a hint to configure window properties.

This only has an effect when called before puglCreateWindow().

puglGetFrame()

PuglRect puglGetFrame

(

const PuglView *

view

)

Get the current position and size of the view.

The position is in screen coordinates with an upper left origin.

puglSetFrame()

PuglStatus puglSetFrame	(	PuglView *	view,
		PuglRect	frame
	)

Set the current position and size of the view.

The position is in screen coordinates with an upper left origin.

puglSetMinSize()

PuglStatus puglSetMinSize	(	PuglView *	view,
		int	width,
		int	height
	)

Set the minimum size of the view.

If an initial minimum size is known, this should be called before puglCreateWindow() to avoid stutter, though it can be called afterwards as well.

puglSetAspectRatio()

PuglStatus puglSetAspectRatio	(	PuglView *	view,
		int	minX,
		int	minY,
		int	maxX,
		int	maxY
	)

Set the window aspect ratio range.

The x and y values here represent a ratio of width to height. To set a fixed aspect ratio, set the minimum and maximum values to the same ratio.

Note that setting different minimum and maximum constraints does not currenty work on MacOS (the minimum is used), so only setting a fixed aspect ratio works properly across all platforms.

If an initial aspect ratio is known, this should be called before puglCreateWindow() to avoid stutter, though it can be called afterwards as well.

puglSetWindowTitle()

PuglStatus puglSetWindowTitle	(	PuglView *	view,
		const char *	title
	)

Set the title of the window.

This only makes sense for non-embedded views that will have a corresponding top-level window, and sets the title, typically displayed in the title bar or in window switchers.

puglSetParentWindow()

PuglStatus puglSetParentWindow	(	PuglView *	view,
		PuglNativeWindow	parent
	)

Set the parent window for embedding a view in an existing window.

This must be called before puglCreateWindow(), reparenting is not supported.

puglSetTransientFor()

PuglStatus puglSetTransientFor	(	PuglView *	view,
		PuglNativeWindow	parent
	)

Set the transient parent of the window.

Set this for transient children like dialogs, to have them properly associated with their parent window. This should be called before puglCreateWindow().

puglCreateWindow()

PuglStatus puglCreateWindow	(	PuglView *	view,
		const char *	title
	)

Realise a view by creating a corresponding system view or window.

The view should be fully configured using the above functions before this is called. This function may only be called once per view.

puglShowWindow()

PuglStatus puglShowWindow

(

PuglView *

view

)

Show the current window.

If the window is currently hidden, it will be shown and possibly raised to the top depending on the platform.

puglHideWindow()

PuglStatus puglHideWindow

(

PuglView *

view

)

Hide the current window.

puglGetVisible()

bool puglGetVisible

(

PuglView *

view

)

Return true iff the view is currently visible.

puglGetNativeWindow()

PuglNativeWindow puglGetNativeWindow

(

PuglView *

view

)

Return the native window handle.

puglGetContext()

void* puglGetContext

(

PuglView *

view

)

Get the graphics context.

This is a backend-specific context used for drawing if the backend graphics API requires one. It is only available during an expose.

Returns

• OpenGL: NULL.
• Cairo: A pointer to a cairo_t.

puglEnterContext()

PuglStatus puglEnterContext	(	PuglView *	view,
		bool	drawing
	)

Enter the graphics context.

Note that, unlike some similar libraries, Pugl automatically enters and leaves the graphics context when required and application should not normally do this. Drawing in Pugl is only allowed during the processing of an expose event.

However, this can be used to enter the graphics context elsewhere, for example to call any GL functions during setup.

Parameters

view	The view being entered.
drawing	If true, prepare for drawing.

puglLeaveContext()

PuglStatus puglLeaveContext	(	PuglView *	view,
		bool	drawing
	)

Leave the graphics context.

This must be called after puglEnterContext() with a matching drawing parameter.

Parameters

view	The view being left.
drawing	If true, finish drawing, for example by swapping buffers.

puglPostRedisplay()

PuglStatus puglPostRedisplay

(

PuglView *

view

)

Request a redisplay for the entire view.

This will cause an expose event to be dispatched later. If called from within the event handler, the expose should arrive at the end of the current event loop iteration, though this is not strictly guaranteed on all platforms. If called elsewhere, an expose will be enqueued to be processed in the next event loop iteration.

puglPostRedisplayRect()

PuglStatus puglPostRedisplayRect	(	PuglView *	view,
		PuglRect	rect
	)

Request a redisplay of the given rectangle within the view.

This has the same semantics as puglPostRedisplay(), but allows giving a precise region for redrawing only a portion of the view.

puglGrabFocus()

PuglStatus puglGrabFocus

(

PuglView *

view

)

Grab the keyboard input focus.

puglHasFocus()

bool puglHasFocus

(

const PuglView *

view

)

Return whether view has the keyboard input focus.

puglSetClipboard()

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

puglGetClipboard()

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.
[out]	type	Set to the MIME type of the data.
[out]	len	Set to the length of the data in bytes.

Returns

The clipboard contents.

puglRequestAttention()

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.