Data Structures | Macros | Typedefs | Enumerations | Functions
pugl.h File Reference
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Data Structures

struct  PuglRect
 
struct  PuglEventAny
 
struct  PuglEventButton
 
struct  PuglEventConfigure
 
struct  PuglEventExpose
 
struct  PuglEventClose
 
struct  PuglEventKey
 
struct  PuglEventText
 
struct  PuglEventCrossing
 
struct  PuglEventMotion
 
struct  PuglEventScroll
 
struct  PuglEventFocus
 
union  PuglEvent
 

Macros

#define PUGL_API
 
#define PUGL_BEGIN_DECLS
 
#define PUGL_END_DECLS
 

Typedefs

typedef uint32_t PuglMods
 
typedef uint32_t PuglEventFlags
 
typedef struct PuglWorldImpl PuglWorld
 
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  PuglMod
 
enum  PuglKey
 
enum  PuglEventType
 
enum  PuglEventFlag
 
enum  PuglCrossingMode
 
enum  PuglStatus
 
enum  PuglViewHint
 
enum  PuglViewHintValue
 

Functions

const char * puglStrerror (PuglStatus status)
 
PuglWorld * puglNewWorld (void)
 
void puglFreeWorld (PuglWorld *world)
 
void * puglGetNativeWorld (PuglWorld *world)
 
PuglStatus puglSetClassName (PuglWorld *world, const char *name)
 
double puglGetTime (const PuglWorld *world)
 
PuglStatus puglPollEvents (PuglWorld *world, double timeout)
 
PuglStatus puglDispatchEvents (PuglWorld *world)
 
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)
 

Detailed Description

Pugl C API.

Data Structure Documentation

◆ PuglRect

struct PuglRect

A rectangle.

This is used to describe things like view position and size. Pugl generally uses coordinates where the top left corner is 0,0.

Data Fields
double x
double y
double width
double height

◆ PuglEventAny

struct PuglEventAny

Common header for all event structs.

Data Fields
PuglEventType type Event type.
PuglEventFlags flags Bitwise OR of PuglEventFlag values.

◆ PuglEventButton

struct PuglEventButton

Button press or release event.

Data Fields
PuglEventType type PUGL_BUTTON_PRESS or PUGL_BUTTON_RELEASE
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
double time Time in seconds.
double x View-relative X coordinate.
double y View-relative Y coordinate.
double xRoot Root-relative X coordinate.
double yRoot Root-relative Y coordinate.
PuglMods state Bitwise OR of PuglMod flags.
uint32_t button Button number starting from 1.

◆ PuglEventConfigure

struct PuglEventConfigure

Window resize or move event.

A configure event is sent whenever the window is resized or moved. When a configure event is received, the graphics context is active but not set up for drawing. For example, it is valid to adjust the OpenGL viewport or otherwise configure the context, but not to draw anything.

Data Fields
PuglEventType type PUGL_CONFIGURE
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
double x New parent-relative X coordinate.
double y New parent-relative Y coordinate.
double width New width.
double height New height.

◆ PuglEventExpose

struct PuglEventExpose

Expose event for when a region must be redrawn.

When an expose event is received, the graphics context is active, and the view must draw the entire specified region. The contents of the region are undefined, there is no preservation of anything drawn previously.

Data Fields
PuglEventType type PUGL_EXPOSE
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
double x View-relative X coordinate.
double y View-relative Y coordinate.
double width Width of exposed region.
double height Height of exposed region.
int count Number of expose events to follow.

◆ PuglEventClose

struct PuglEventClose

Window close event.

This event is sent when the window is to be closed, for example when the user clicks the close button.

Data Fields
PuglEventType type PUGL_CLOSE
PuglEventFlags flags Bitwise OR of PuglEventFlag values.

◆ PuglEventKey

struct PuglEventKey

Key press or release event.

This event represents low-level key presses and releases. This can be used for "direct" keyboard handing like key bindings, but must not be interpreted as text input.

Keys are represented portably as Unicode code points, using the "natural" code point for the key where possible (see PuglKey for details). The key field is the code for the pressed key, without any modifiers applied. For example, a press or release of the 'A' key will have key 97 ('a') regardless of whether shift or control are being held.

Alternatively, the raw keycode can be used to work directly with physical keys, but note that this value is not portable and differs between platforms and hardware.

Data Fields
PuglEventType type PUGL_KEY_PRESS or PUGL_KEY_RELEASE
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
double time Time in seconds.
double x View-relative X coordinate.
double y View-relative Y coordinate.
double xRoot Root-relative X coordinate.
double yRoot Root-relative Y coordinate.
PuglMods state Bitwise OR of PuglMod flags.
uint32_t keycode Raw key code.
uint32_t key Unshifted Unicode character code, or 0.

◆ PuglEventText

struct PuglEventText

Character input event.

This event represents text input, usually as the result of a key press. The text is given both as a Unicode character code and a UTF-8 string.

Note that this event is generated by the platform's input system, so there is not necessarily a direct correspondence between text events and physical key presses. For example, with some input methods a sequence of several key presses will generate a single character.

Data Fields
PuglEventType type PUGL_TEXT
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
double time Time in seconds.
double x View-relative X coordinate.
double y View-relative Y coordinate.
double xRoot Root-relative X coordinate.
double yRoot Root-relative Y coordinate.
PuglMods state Bitwise OR of PuglMod flags.
uint32_t keycode Raw key code.
uint32_t character Unicode character code.
char string[8] UTF-8 string.

◆ PuglEventCrossing

struct PuglEventCrossing

Pointer enter or leave event.

This event is sent when the pointer enters or leaves the view. This can happen for several reasons (not just the user dragging the pointer over the window edge), as described by the mode field.

Data Fields
PuglEventType type PUGL_ENTER_NOTIFY or PUGL_LEAVE_NOTIFY
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
double time Time in seconds.
double x View-relative X coordinate.
double y View-relative Y coordinate.
double xRoot Root-relative X coordinate.
double yRoot Root-relative Y coordinate.
PuglMods state Bitwise OR of PuglMod flags.
PuglCrossingMode mode Reason for crossing.

◆ PuglEventMotion

struct PuglEventMotion

Pointer motion event.

Data Fields
PuglEventType type PUGL_MOTION_NOTIFY
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
double time Time in seconds.
double x View-relative X coordinate.
double y View-relative Y coordinate.
double xRoot Root-relative X coordinate.
double yRoot Root-relative Y coordinate.
PuglMods state Bitwise OR of PuglMod flags.
bool isHint True iff this event is a motion hint.
bool focus True iff this is the focused window.

◆ PuglEventScroll

struct PuglEventScroll

Scroll event.

The scroll distance is expressed in "lines", an arbitrary unit that corresponds to a single tick of a detented mouse wheel. For example, dy = 1.0 scrolls 1 line up. Some systems and devices support finer resolution and/or higher values for fast scrolls, so programs should handle any value gracefully.

Data Fields
PuglEventType type PUGL_SCROLL
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
double time Time in seconds.
double x View-relative X coordinate.
double y View-relative Y coordinate.
double xRoot Root-relative X coordinate.
double yRoot Root-relative Y coordinate.
PuglMods state Bitwise OR of PuglMod flags.
double dx Scroll X distance in lines.
double dy Scroll Y distance in lines.

◆ PuglEventFocus

struct PuglEventFocus

Keyboard focus event.

This event is sent whenever the view gains or loses the keyboard focus. The view with the keyboard focus will receive any key press or release events.

Data Fields
PuglEventType type PUGL_FOCUS_IN or PUGL_FOCUS_OUT
PuglEventFlags flags Bitwise OR of PuglEventFlag values.
bool grab True iff this is a grab/ungrab event.

◆ PuglEvent

union PuglEvent

View event.

This is a union of all event types. The type must be checked to determine which fields are safe to access. A pointer to PuglEvent can either be cast to the appropriate type, or the union members used.

Data Fields
PuglEventAny any Valid for all event types.
PuglEventType type Event type.
PuglEventButton button PUGL_BUTTON_PRESS, PUGL_BUTTON_RELEASE
PuglEventConfigure configure PUGL_CONFIGURE
PuglEventExpose expose PUGL_EXPOSE
PuglEventClose close PUGL_CLOSE
PuglEventKey key PUGL_KEY_PRESS, PUGL_KEY_RELEASE
PuglEventText text PUGL_TEXT
PuglEventCrossing crossing PUGL_ENTER_NOTIFY, PUGL_LEAVE_NOTIFY
PuglEventMotion motion PUGL_MOTION_NOTIFY
PuglEventScroll scroll PUGL_SCROLL
PuglEventFocus focus PUGL_FOCUS_IN, PUGL_FOCUS_OUT

Macro Definition Documentation

◆ PUGL_API

#define PUGL_API

◆ PUGL_BEGIN_DECLS

#define PUGL_BEGIN_DECLS

◆ PUGL_END_DECLS

#define PUGL_END_DECLS