Reorganize header and documentation into coherent sections

1 files 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
    @{
 */