From 36f9c9dd7bc2f3d986b90477238c24e121936a25 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Sun, 4 Aug 2019 21:15:19 +0200
Subject: Reorganize header and documentation into coherent sections
---
pugl/pugl.h | 194 ++++++++++++++++++++++++++++++------------------------------
1 file changed, 98 insertions(+), 96 deletions(-)
diff --git a/pugl/pugl.h b/pugl/pugl.h
index 1488b61..4cf4d7f 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -502,8 +502,9 @@ puglDispatchEvents(PuglWorld* world);
/**
@}
- @name Initialization
- Configuration functions which must be called before creating a window.
+ @name View
+ A view is a drawing region that receives events, which may correspond to a
+ top-level window or be embedded in some other window.
@{
*/
@@ -529,14 +530,19 @@ PUGL_API PuglWorld*
puglGetWorld(PuglView* view);
/**
- Set the title of the window.
+ Set the handle to be passed to all callbacks.
- 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.
+ This is generally a pointer to a struct which contains all necessary state.
+ Everything needed in callbacks should be here, not in static variables.
*/
-PUGL_API PuglStatus
-puglSetWindowTitle(PuglView* view, const char* title);
+PUGL_API void
+puglSetHandle(PuglView* view, PuglHandle handle);
+
+/**
+ Get the handle to be passed to all callbacks.
+*/
+PUGL_API PuglHandle
+puglGetHandle(PuglView* view);
/**
Set a hint to configure window properties.
@@ -547,130 +553,146 @@ PUGL_API PuglStatus
puglSetViewHint(PuglView* view, PuglViewHint hint, int value);
/**
- Set the parent window before creating a window (for embedding).
-
- This only works when called before creating the window with
- puglCreateWindow(), reparenting is not supported.
+ Return true iff the view is currently visible.
*/
-PUGL_API PuglStatus
-puglSetParentWindow(PuglView* view, PuglNativeWindow parent);
+PUGL_API bool
+puglGetVisible(PuglView* view);
/**
- Set the graphics backend to use.
-
- This needs to be called once before creating the window to set the graphics
- backend. There are two backend accessors included with pugl:
- puglGlBackend() and puglCairoBackend(), declared in pugl_gl_backend.h and
- pugl_cairo_backend.h, respectively.
+ Request a redisplay on the next call to puglDispatchEvents().
*/
-PUGL_API PuglStatus
-puglSetBackend(PuglView* view, const PuglBackend* backend);
+PUGL_API void
+puglPostRedisplay(PuglView* view);
/**
@}
- @name Windows
- Functions for creating and managing a visible window for a view.
+ @name Frame
+ Functions for working with the position and size of a view.
@{
*/
/**
- Create a window with the settings given by the various puglInit functions.
-
- @return 1 (pugl does not currently support multiple windows).
+ Get the current position and size of the view.
*/
-PUGL_API int
-puglCreateWindow(PuglView* view, const char* title);
+PUGL_API PuglRect
+puglGetFrame(const PuglView* view);
/**
- Show the current window.
+ Set the current position and size of the view.
*/
-PUGL_API void
-puglShowWindow(PuglView* view);
+PUGL_API PuglStatus
+puglSetFrame(PuglView* view, PuglRect frame);
/**
- Hide the current window.
+ Set the minimum size of the view.
+
+ To avoid stutter, this should be called before creating the window.
*/
-PUGL_API void
-puglHideWindow(PuglView* view);
+PUGL_API PuglStatus
+puglSetMinSize(PuglView* view, int width, int height);
/**
- Return the native window handle.
+ 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.
*/
-PUGL_API PuglNativeWindow
-puglGetNativeWindow(PuglView* view);
+PUGL_API PuglStatus
+puglSetAspectRatio(PuglView* view, int minX, int minY, int maxX, int maxY);
/**
@}
+ @name Windows
+ Functions for working with top-level windows.
+ @{
*/
/**
- Set the handle to be passed to all callbacks.
+ Set the title of the window.
- This is generally a pointer to a struct which contains all necessary state.
- Everything needed in callbacks should be here, not in static variables.
+ 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.
*/
-PUGL_API void
-puglSetHandle(PuglView* view, PuglHandle handle);
+PUGL_API PuglStatus
+puglSetWindowTitle(PuglView* view, const char* title);
/**
- Get the handle to be passed to all callbacks.
+ Set the parent window before creating a window (for embedding).
+
+ This only works when called before creating the window with
+ puglCreateWindow(), reparenting is not supported.
*/
-PUGL_API PuglHandle
-puglGetHandle(PuglView* view);
+PUGL_API PuglStatus
+puglSetParentWindow(PuglView* view, PuglNativeWindow parent);
/**
- Return true iff the view is currently visible.
+ Set the transient parent of the window.
+
+ This is used for things like dialogs, to have them associated with the
+ window they are a transient child of properly.
*/
-PUGL_API bool
-puglGetVisible(PuglView* view);
+PUGL_API void
+puglSetTransientFor(PuglView* view, PuglNativeWindow parent);
/**
- Get the current position and size of the view.
+ Create a window with the settings given by the various puglInit functions.
+
+ @return 1 (pugl does not currently support multiple windows).
*/
-PUGL_API PuglRect
-puglGetFrame(const PuglView* view);
+PUGL_API int
+puglCreateWindow(PuglView* view, const char* title);
/**
- Set the current position and size of the view.
+ Show the current window.
*/
-PUGL_API PuglStatus
-puglSetFrame(PuglView* view, PuglRect frame);
+PUGL_API void
+puglShowWindow(PuglView* view);
/**
- Set the minimum size of the view.
-
- To avoid stutter, this should be called before creating the window.
+ Hide the current window.
*/
-PUGL_API PuglStatus
-puglSetMinSize(PuglView* view, int width, int height);
+PUGL_API void
+puglHideWindow(PuglView* view);
/**
- Set the window aspect ratio range.
+ Return the native window handle.
+*/
+PUGL_API PuglNativeWindow
+puglGetNativeWindow(PuglView* view);
- 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.
+/**
+ @}
+ @name Graphics Context
+ Functions for working with the drawing context.
+ @{
+*/
- 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.
+/**
+ OpenGL extension function.
*/
-PUGL_API PuglStatus
-puglSetAspectRatio(PuglView* view, int minX, int minY, int maxX, int maxY);
+typedef void (*PuglGlFunc)(void);
/**
- Set the transient parent of the window.
+ Set the graphics backend to use.
- This is used for things like dialogs, to have them associated with the
- window they are a transient child of properly.
+ This needs to be called once before creating the window to set the graphics
+ backend. There are two backend accessors included with pugl:
+ puglGlBackend() and puglCairoBackend(), declared in pugl_gl_backend.h and
+ pugl_cairo_backend.h, respectively.
*/
-PUGL_API void
-puglSetTransientFor(PuglView* view, PuglNativeWindow parent);
+PUGL_API PuglStatus
+puglSetBackend(PuglView* view, const PuglBackend* backend);
/**
- @name Context
- Functions for accessing the drawing context.
- @{
+ Return the address of an OpenGL extension function.
*/
+PUGL_API PuglGlFunc
+puglGetProcAddress(const char* name);
/**
Get the drawing context.
@@ -750,26 +772,6 @@ puglRequestAttention(PuglView* view);
/**
@}
-*/
-
-/**
- OpenGL extension function.
-*/
-typedef void (*PuglGlFunc)(void);
-
-/**
- Return the address of an OpenGL extension function.
-*/
-PUGL_API PuglGlFunc
-puglGetProcAddress(const char* name);
-
-/**
- Request a redisplay on the next call to puglProcessEvents().
-*/
-PUGL_API void
-puglPostRedisplay(PuglView* view);
-
-/**
@name Deprecated API
@{
*/
--
cgit v1.2.1