From 92937b14c733a344d7554d2edfd449a7b4ad63ff Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 18 Aug 2019 13:16:52 +0200 Subject: Improve documentation and use LV2 documentation style --- doc/mainpage.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 doc/mainpage.md (limited to 'doc/mainpage.md') diff --git a/doc/mainpage.md b/doc/mainpage.md new file mode 100644 index 0000000..b16551a --- /dev/null +++ b/doc/mainpage.md @@ -0,0 +1,43 @@ +This is the API documentation for Pugl. +The complete C API is documented in the [Pugl](@ref pugl) group, +and the C++ wrapper in the [Puglmm](@ref puglmm) group. + +The Pugl API revolves around two main objects: +the [World](@ref world) and the [View](@ref view). +An application creates a single world to manage system-level state, +then creates one or more views to display. + +## View creation + +Creating a visible view is a multi-step process. +A new view allocated with #puglNewView does not yet represent a "real" system window. +To display, it must first have a [backend set](@ref puglSetBackend), +and be configured by [setting hints](@ref puglSetViewHint) +and [configuring the frame](@ref frame). + +Once the view is configured, +the corresponding window can be [created](@ref puglCreateWindow) +and [shown](@ref puglShowWindow). + +Note that a view does not necessary correspond to a top-level system window. +To create a view within another window, +call #puglSetParentWindow before #puglCreateWindow. + +## Interaction + +Interaction with the user and system happens via [events](@ref interaction). +Before creating a window, +a view must have an [event handler](@ref PuglEventFunc) set with #puglSetEventFunc. +This handler 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 (drawing). + +## Event Loop + +Two functions are used to drive the event loop: + + * #puglPollEvents waits for events to become available. + * #puglDispatchEvents processes all pending events. + +Redrawing is accomplished by calling #puglPostRedisplay, +which posts an expose event to the queue. -- cgit v1.2.1