diff options
| -rw-r--r-- | pugl/pugl.h | 194 |
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 @{ */ |