aboutsummaryrefslogtreecommitdiffstats
path: root/doc/mainpage.md
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2019-08-18 13:16:52 +0200
committerDavid Robillard <d@drobilla.net>2019-09-07 14:40:39 +0200
commit92937b14c733a344d7554d2edfd449a7b4ad63ff (patch)
tree735bec4884bf819e5d74e68f15cbe3f660fe1597 /doc/mainpage.md
parentdc9f1d852d3fba8ddcf7bb535810ad384900fe06 (diff)
downloadpugl-92937b14c733a344d7554d2edfd449a7b4ad63ff.tar.gz
pugl-92937b14c733a344d7554d2edfd449a7b4ad63ff.tar.bz2
pugl-92937b14c733a344d7554d2edfd449a7b4ad63ff.zip
Improve documentation and use LV2 documentation style
Diffstat (limited to 'doc/mainpage.md')
-rw-r--r--doc/mainpage.md43
1 files changed, 43 insertions, 0 deletions
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.