| Version | 0.2.0 |
|---|
This is the API documentation for Pugl. This documentation is based around the C API, there is also a C++ API in the pugl namespace.
The Pugl API revolves around two main objects: the World and the View. An application creates a single world to manage top-level state, then creates one or more views to display.
The World contains all top-level state, and manages views and the event loop.
A world must be created before any views, and it must outlive all views.
A View is a drawable region that receives events.
Creating a visible view is a multi-step process. When a new view is created, it does not yet represent a real system view or window. To display, it must first have a backend and event handler set, and be configured by setting hints and optionally adjusting the frame.
The Backend controls drawing for a view. Pugl includes Cairo and OpenGL backends, as well as a stub backend that creates a native window with no drawing context.
Once the view is configured, it can be created and shown. By default a view will correspond to a top-level system window. To create a view within another window, it must have a parent window set before being created.
Events are sent to a view when it has received user input or must be drawn.
Events are handled by the event handler set during initialisation. This function is called whenever something happens that the view must respond to. This includes user interaction like mouse and keyboard input, and system events like window resizing and exposure.
Two functions are used to drive the event loop:
Redrawing is accomplished by calling puglPostRedisplay or puglPostRedisplayRect, which post expose events to the queue.
Most functions return a Status which should be checked to detect failure.