diff options
Diffstat (limited to 'include/pugl/pugl.h')
| -rw-r--r-- | include/pugl/pugl.h | 1033 |
1 files changed, 235 insertions, 798 deletions
diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h index 49e5fe5..5ba5a46 100644 --- a/include/pugl/pugl.h +++ b/include/pugl/pugl.h @@ -4,7 +4,7 @@ #ifndef PUGL_PUGL_H #define PUGL_PUGL_H -#include "pugl/attributes.h" +#include <pugl/attributes.h> #include <stddef.h> #include <stdint.h> @@ -46,22 +46,17 @@ typedef int16_t PuglCoord; */ typedef uint16_t PuglSpan; -/** - A rectangle in a view or on the screen. - - This type is used to describe two things: the position and size of a view - (for configuring), or a rectangle within a view (for exposing). - - The coordinate (0, 0) represents the top-left pixel of the parent window (or - display if there isn't one), or the top-left pixel of the view, - respectively. -*/ +/// A 2-dimensional position within/of a view typedef struct { PuglCoord x; PuglCoord y; - PuglSpan width; - PuglSpan height; -} PuglRect; +} PuglPoint; + +/// A 2-dimensional size within/of a view +typedef struct { + PuglSpan width; + PuglSpan height; +} PuglArea; /// A string property for configuration typedef enum { @@ -298,7 +293,7 @@ typedef PuglAnyEvent PuglCloseEvent; This event is sent to every view near the end of a main loop iteration when any pending exposures are about to be redrawn. It is typically used to mark - regions to expose with puglObscureView() or puglPostRedisplayRect(). For + regions to expose with puglObscureView() or puglObscureRegion(). For example, to continuously animate, obscure the view when an update event is received, and it will receive an expose event shortly afterwards. */ @@ -341,77 +336,77 @@ typedef struct { mapping used here is arbitrary and specific to Pugl. */ typedef enum { - PUGL_KEY_NONE = 0U, ///< Sentinel value for no key - PUGL_KEY_BACKSPACE = 0x00000008U, ///< Backspace - PUGL_KEY_TAB = 0x00000009U, ///< Tab - PUGL_KEY_ENTER = 0x0000000DU, ///< Enter - PUGL_KEY_ESCAPE = 0x0000001BU, ///< Escape - PUGL_KEY_DELETE = 0x0000007FU, ///< Delete - PUGL_KEY_SPACE = 0x00000020U, ///< Space - PUGL_KEY_F1 = 0x0000E000U, ///< F1 - PUGL_KEY_F2, ///< F2 - PUGL_KEY_F3, ///< F3 - PUGL_KEY_F4, ///< F4 - PUGL_KEY_F5, ///< F5 - PUGL_KEY_F6, ///< F6 - PUGL_KEY_F7, ///< F7 - PUGL_KEY_F8, ///< F8 - PUGL_KEY_F9, ///< F9 - PUGL_KEY_F10, ///< F10 - PUGL_KEY_F11, ///< F11 - PUGL_KEY_F12, ///< F12 - PUGL_KEY_PAGE_UP = 0xE031, ///< Page Up - PUGL_KEY_PAGE_DOWN, ///< Page Down - PUGL_KEY_END, ///< End - PUGL_KEY_HOME, ///< Home - PUGL_KEY_LEFT, ///< Left - PUGL_KEY_UP, ///< Up - PUGL_KEY_RIGHT, ///< Right - PUGL_KEY_DOWN, ///< Down - PUGL_KEY_PRINT_SCREEN = 0xE041U, ///< Print Screen - PUGL_KEY_INSERT, ///< Insert - PUGL_KEY_PAUSE, ///< Pause/Break - PUGL_KEY_MENU, ///< Menu - PUGL_KEY_NUM_LOCK, ///< Num Lock - PUGL_KEY_SCROLL_LOCK, ///< Scroll Lock - PUGL_KEY_CAPS_LOCK, ///< Caps Lock - PUGL_KEY_SHIFT_L = 0xE051U, ///< Left Shift - PUGL_KEY_SHIFT_R, ///< Right Shift - PUGL_KEY_CTRL_L, ///< Left Control - PUGL_KEY_CTRL_R, ///< Right Control - PUGL_KEY_ALT_L, ///< Left Alt - PUGL_KEY_ALT_R, ///< Right Alt / AltGr - PUGL_KEY_SUPER_L, ///< Left Super - PUGL_KEY_SUPER_R, ///< Right Super - PUGL_KEY_PAD_0 = 0xE060U, ///< Keypad 0 - PUGL_KEY_PAD_1, ///< Keypad 1 - PUGL_KEY_PAD_2, ///< Keypad 2 - PUGL_KEY_PAD_3, ///< Keypad 3 - PUGL_KEY_PAD_4, ///< Keypad 4 - PUGL_KEY_PAD_5, ///< Keypad 5 - PUGL_KEY_PAD_6, ///< Keypad 6 - PUGL_KEY_PAD_7, ///< Keypad 7 - PUGL_KEY_PAD_8, ///< Keypad 8 - PUGL_KEY_PAD_9, ///< Keypad 9 - PUGL_KEY_PAD_ENTER, ///< Keypad Enter - PUGL_KEY_PAD_PAGE_UP = 0xE071U, ///< Keypad Page Up - PUGL_KEY_PAD_PAGE_DOWN, ///< Keypad Page Down - PUGL_KEY_PAD_END, ///< Keypad End - PUGL_KEY_PAD_HOME, ///< Keypad Home - PUGL_KEY_PAD_LEFT, ///< Keypad Left - PUGL_KEY_PAD_UP, ///< Keypad Up - PUGL_KEY_PAD_RIGHT, ///< Keypad Right - PUGL_KEY_PAD_DOWN, ///< Keypad Down - PUGL_KEY_PAD_CLEAR = 0xE09DU, ///< Keypad Clear/Begin - PUGL_KEY_PAD_INSERT, ///< Keypad Insert - PUGL_KEY_PAD_DELETE, ///< Keypad Delete - PUGL_KEY_PAD_EQUAL, ///< Keypad Equal - PUGL_KEY_PAD_MULTIPLY = 0xE0AAU, ///< Keypad Multiply - PUGL_KEY_PAD_ADD, ///< Keypad Add - PUGL_KEY_PAD_SEPARATOR, ///< Keypad Separator - PUGL_KEY_PAD_SUBTRACT, ///< Keypad Subtract - PUGL_KEY_PAD_DECIMAL, ///< Keypad Decimal - PUGL_KEY_PAD_DIVIDE, ///< Keypad Divide + PUGL_KEY_NONE = 0U, ///< Sentinel value for no key + PUGL_KEY_BACKSPACE = 0x0008U, ///< Backspace + PUGL_KEY_TAB = 0x0009U, ///< Tab + PUGL_KEY_ENTER = 0x000DU, ///< Enter + PUGL_KEY_ESCAPE = 0x001BU, ///< Escape + PUGL_KEY_DELETE = 0x007FU, ///< Delete + PUGL_KEY_SPACE = 0x0020U, ///< Space + PUGL_KEY_F1 = 0xE000U, ///< F1 + PUGL_KEY_F2 = 0xE001U, ///< F2 + PUGL_KEY_F3 = 0xE002U, ///< F3 + PUGL_KEY_F4 = 0xE003U, ///< F4 + PUGL_KEY_F5 = 0xE004U, ///< F5 + PUGL_KEY_F6 = 0xE005U, ///< F6 + PUGL_KEY_F7 = 0xE006U, ///< F7 + PUGL_KEY_F8 = 0xE007U, ///< F8 + PUGL_KEY_F9 = 0xE008U, ///< F9 + PUGL_KEY_F10 = 0xE009U, ///< F10 + PUGL_KEY_F11 = 0xE010U, ///< F11 + PUGL_KEY_F12 = 0xE011U, ///< F12 + PUGL_KEY_PAGE_UP = 0xE031U, ///< Page Up + PUGL_KEY_PAGE_DOWN = 0xE032U, ///< Page Down + PUGL_KEY_END = 0xE033U, ///< End + PUGL_KEY_HOME = 0xE034U, ///< Home + PUGL_KEY_LEFT = 0xE035U, ///< Left + PUGL_KEY_UP = 0xE036U, ///< Up + PUGL_KEY_RIGHT = 0xE037U, ///< Right + PUGL_KEY_DOWN = 0xE038U, ///< Down + PUGL_KEY_PRINT_SCREEN = 0xE041U, ///< Print Screen + PUGL_KEY_INSERT = 0xE042U, ///< Insert + PUGL_KEY_PAUSE = 0xE043U, ///< Pause/Break + PUGL_KEY_MENU = 0xE044U, ///< Menu + PUGL_KEY_NUM_LOCK = 0xE045U, ///< Num Lock + PUGL_KEY_SCROLL_LOCK = 0xE046U, ///< Scroll Lock + PUGL_KEY_CAPS_LOCK = 0xE047U, ///< Caps Lock + PUGL_KEY_SHIFT_L = 0xE051U, ///< Left Shift + PUGL_KEY_SHIFT_R = 0xE052U, ///< Right Shift + PUGL_KEY_CTRL_L = 0xE053U, ///< Left Control + PUGL_KEY_CTRL_R = 0xE054U, ///< Right Control + PUGL_KEY_ALT_L = 0xE055U, ///< Left Alt + PUGL_KEY_ALT_R = 0xE056U, ///< Right Alt / AltGr + PUGL_KEY_SUPER_L = 0xE057U, ///< Left Super + PUGL_KEY_SUPER_R = 0xE058U, ///< Right Super + PUGL_KEY_PAD_0 = 0xE060U, ///< Keypad 0 + PUGL_KEY_PAD_1 = 0xE061U, ///< Keypad 1 + PUGL_KEY_PAD_2 = 0xE062U, ///< Keypad 2 + PUGL_KEY_PAD_3 = 0xE063U, ///< Keypad 3 + PUGL_KEY_PAD_4 = 0xE064U, ///< Keypad 4 + PUGL_KEY_PAD_5 = 0xE065U, ///< Keypad 5 + PUGL_KEY_PAD_6 = 0xE066U, ///< Keypad 6 + PUGL_KEY_PAD_7 = 0xE067U, ///< Keypad 7 + PUGL_KEY_PAD_8 = 0xE068U, ///< Keypad 8 + PUGL_KEY_PAD_9 = 0xE069U, ///< Keypad 9 + PUGL_KEY_PAD_ENTER = 0xE070U, ///< Keypad Enter + PUGL_KEY_PAD_PAGE_UP = 0xE071U, ///< Keypad Page Up + PUGL_KEY_PAD_PAGE_DOWN = 0xE072U, ///< Keypad Page Down + PUGL_KEY_PAD_END = 0xE073U, ///< Keypad End + PUGL_KEY_PAD_HOME = 0xE074U, ///< Keypad Home + PUGL_KEY_PAD_LEFT = 0xE075U, ///< Keypad Left + PUGL_KEY_PAD_UP = 0xE076U, ///< Keypad Up + PUGL_KEY_PAD_RIGHT = 0xE077U, ///< Keypad Right + PUGL_KEY_PAD_DOWN = 0xE078U, ///< Keypad Down + PUGL_KEY_PAD_CLEAR = 0xE09DU, ///< Keypad Clear/Begin + PUGL_KEY_PAD_INSERT = 0xE09EU, ///< Keypad Insert + PUGL_KEY_PAD_DELETE = 0xE09FU, ///< Keypad Delete + PUGL_KEY_PAD_EQUAL = 0xE0A0U, ///< Keypad Equal + PUGL_KEY_PAD_MULTIPLY = 0xE0AAU, ///< Keypad Multiply + PUGL_KEY_PAD_ADD = 0xE0ABU, ///< Keypad Add + PUGL_KEY_PAD_SEPARATOR = 0xE0ACU, ///< Keypad Separator + PUGL_KEY_PAD_SUBTRACT = 0xE0ADU, ///< Keypad Subtract + PUGL_KEY_PAD_DECIMAL = 0xE0AEU, ///< Keypad Decimal + PUGL_KEY_PAD_DIVIDE = 0xE0AFU, ///< Keypad Divide } PuglKey; /// Keyboard modifier flags @@ -444,8 +439,8 @@ typedef struct { Key press or release event. This event represents low-level key presses and releases. This can be used - for "direct" keyboard handing like key bindings, but must not be interpreted - as text input. + for "direct" keyboard handling like key bindings, but must not be + interpreted as text input. Keys are represented portably as Unicode code points, using the "natural" code point for the key where possible (see #PuglKey for details). The `key` @@ -734,8 +729,7 @@ typedef enum { } PuglStatus; /// Return a string describing a status code -PUGL_CONST_API -const char* +PUGL_CONST_API const char* puglStrerror(PuglStatus status); /** @@ -791,13 +785,11 @@ typedef uint32_t PuglWorldFlags; @param flags Flags to control world features. @return A new world, which must be later freed with puglFreeWorld(). */ -PUGL_MALLOC_API -PuglWorld* +PUGL_MALLOC_API PuglWorld* puglNewWorld(PuglWorldType type, PuglWorldFlags flags); /// Free a world allocated with puglNewWorld() -PUGL_API -void +PUGL_API void puglFreeWorld(PuglWorld* world); /** @@ -808,13 +800,11 @@ puglFreeWorld(PuglWorld* world); The handle is opaque to Pugl and is not interpreted in any way. */ -PUGL_API -void +PUGL_API void puglSetWorldHandle(PuglWorld* world, PuglWorldHandle handle); /// Get the user data for the world -PUGL_API -PuglWorldHandle +PUGL_API PuglWorldHandle puglGetWorldHandle(PuglWorld* world); /** @@ -826,8 +816,7 @@ puglGetWorldHandle(PuglWorld* world); Windows: Returns the `HMODULE` of the calling process. */ -PUGL_API -void* +PUGL_API void* puglGetNativeWorld(PuglWorld* world); /** @@ -836,8 +825,7 @@ puglGetNativeWorld(PuglWorld* world); The string value only needs to be valid for the duration of this call, it will be copied if necessary. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetWorldString(PuglWorld* world, PuglStringHint key, const char* value); /** @@ -846,8 +834,7 @@ puglSetWorldString(PuglWorld* world, PuglStringHint key, const char* value); The returned string should be accessed immediately, or copied. It may become invalid upon any call to any function that manipulates the same view. */ -PUGL_API -const char* +PUGL_API const char* puglGetWorldString(const PuglWorld* world, PuglStringHint key); /** @@ -857,8 +844,7 @@ puglGetWorldString(const PuglWorld* world, PuglStringHint key); time is only useful to compare against other times returned by this function, its absolute value has no meaning. */ -PUGL_API -double +PUGL_API double puglGetTime(const PuglWorld* world); /** @@ -883,8 +869,7 @@ puglGetTime(const PuglWorld* world); @return #PUGL_SUCCESS if events are read, #PUGL_FAILURE if no events are read, or an error. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglUpdate(PuglWorld* world, double timeout); /** @@ -960,9 +945,9 @@ typedef enum { /// A special view hint value typedef enum { - PUGL_DONT_CARE = -1, ///< Generic trinary: Use best default - PUGL_FALSE = 0, ///< Generic trinary: Explicitly false - PUGL_TRUE = 1, ///< Generic trinary: Explicitly true + PUGL_DONT_CARE = -1, ///< Generic trinary: unset + PUGL_FALSE = 0, ///< Generic trinary: false + PUGL_TRUE = 1, ///< Generic trinary: true PUGL_OPENGL_API = 2, ///< For #PUGL_CONTEXT_API PUGL_OPENGL_ES_API = 3, ///< For #PUGL_CONTEXT_API PUGL_OPENGL_CORE_PROFILE = 4, ///< For #PUGL_CONTEXT_PROFILE @@ -977,6 +962,49 @@ typedef enum { } PuglViewType; /** + A hint for configuring/constraining the position of a view. + + The system will attempt to make the view's window adhere to these, but they + are suggestions, not hard constraints. Applications should handle any view + position gracefully. + + An unset position has `INT16_MIN` (-32768) for both `x` and `y`. In + practice, set positions should be between -16000 and 16000 for portability. + Usually, the origin is the top left of the display, although negative + coordinates are possible, particularly on multi-display system. +*/ +typedef enum { + /** + Default position. + + This is used as the position during window creation as a default, if no + other position is specified. It isn't necessary to set a default position + (unlike the default size, which is required). If not even a default + position is set, then the window will be created at an arbitrary position. + This position is a best-effort attempt to do the most reasonable thing for + the initial display of the window, for example, by centering. Note that + it is implementation-defined, subject to change, platform-specific, and + for embedded views, may no longer make sense if the parent's size is + adjusted. Code that wants to make assumptions about the initial position + must set the default to a specific valid one, such as `{0, 0}`. + */ + PUGL_DEFAULT_POSITION, + + /** + Current position. + + This reflects the current position of the view, which may be different from + the default position if the view has been moved by the user, window + manager, or for any other reason. Typically, it overrides the + default position. + */ + PUGL_CURRENT_POSITION, +} PuglPositionHint; + +/// The number of #PuglPositionHint values +#define PUGL_NUM_POSITION_HINTS ((unsigned)PUGL_CURRENT_POSITION + 1U) + +/** A hint for configuring/constraining the size of a view. The system will attempt to make the view's window adhere to these, but they @@ -993,6 +1021,15 @@ typedef enum { PUGL_DEFAULT_SIZE, /** + Current size. + + This reflects the current size of the view, which may be different from + the default size if the view is resizable. Typically, it overrides the + default size. + */ + PUGL_CURRENT_SIZE, + + /** Minimum size. If set, the view's size should be constrained to be at least this large. @@ -1050,18 +1087,15 @@ typedef PuglStatus (*PuglEventFunc)(PuglView* view, const PuglEvent* event); It must first be configured, then the system view can be created with puglRealize(). */ -PUGL_MALLOC_API -PuglView* +PUGL_MALLOC_API PuglView* puglNewView(PuglWorld* world); /// Free a view created with puglNewView() -PUGL_API -void +PUGL_API void puglFreeView(PuglView* view); /// Return the world that `view` is a part of -PUGL_API -PuglWorld* +PUGL_API PuglWorld* puglGetWorld(PuglView* view); /** @@ -1073,13 +1107,11 @@ puglGetWorld(PuglView* view); The handle is opaque to Pugl and is not interpreted in any way. */ -PUGL_API -void +PUGL_API void puglSetHandle(PuglView* view, PuglHandle handle); /// Get the user data for a view -PUGL_API -PuglHandle +PUGL_API PuglHandle puglGetHandle(PuglView* view); /** @@ -1099,18 +1131,15 @@ puglGetHandle(PuglView* view); applications must link against the appropriate backend library, or be sure to compile in the appropriate code if using a local copy of Pugl. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetBackend(PuglView* view, const PuglBackend* backend); /// Return the graphics backend used by a view -PUGL_API -const PuglBackend* +PUGL_API const PuglBackend* puglGetBackend(const PuglView* view); /// Set the function to call when an event occurs -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetEventFunc(PuglView* view, PuglEventFunc eventFunc); /** @@ -1118,8 +1147,7 @@ puglSetEventFunc(PuglView* view, PuglEventFunc eventFunc); This only has an effect when called before puglRealize(). */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetViewHint(PuglView* view, PuglViewHint hint, int value); /** @@ -1129,8 +1157,7 @@ puglSetViewHint(PuglView* view, PuglViewHint hint, int value); hint which was initially set to PUGL_DONT_CARE, or has been adjusted from the suggested value. */ -PUGL_API -int +PUGL_API int puglGetViewHint(const PuglView* view, PuglViewHint hint); /** @@ -1140,8 +1167,7 @@ puglGetViewHint(const PuglView* view, PuglViewHint hint); string value only needs to be valid for the duration of this call, it will be copied if necessary. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetViewString(PuglView* view, PuglStringHint key, const char* value); /** @@ -1150,8 +1176,7 @@ puglSetViewString(PuglView* view, PuglStringHint key, const char* value); The returned string should be accessed immediately, or copied. It may become invalid upon any call to any function that manipulates the same view. */ -PUGL_API -const char* +PUGL_API const char* puglGetViewString(const PuglView* view, PuglStringHint key); /** @@ -1166,8 +1191,7 @@ puglGetViewString(const PuglView* view, PuglStringHint key); that is reasonably sized on a 96 DPI display, and the scale 2.0 should have text twice that large. */ -PUGL_API -double +PUGL_API double puglGetScaleFactor(const PuglView* view); /** @@ -1178,60 +1202,52 @@ puglGetScaleFactor(const PuglView* view); */ /** - Get the current position and size of the view. + Get a position hint for the view. - The position is in screen coordinates with an upper left origin. + This can be used to get the default or current position of a view, in screen + coordinates with an upper left origin. */ -PUGL_API -PuglRect -puglGetFrame(const PuglView* view); +PUGL_API PuglPoint +puglGetPositionHint(const PuglView* view, PuglPositionHint hint); /** - Set the current position and size of the view. + Set a position hint for the view. - The position is in screen coordinates with an upper left origin. + This can be used to set the default or current position of a view. - @return #PUGL_UNKNOWN_ERROR on failure, in which case the view frame is - unchanged. -*/ -PUGL_API -PuglStatus -puglSetFrame(PuglView* view, PuglRect frame); - -/** - Set the current position of the view. + This should be called before puglRealize() so the initial window for the + view can be configured correctly. It may also be used dynamically after the + window is realized, for some hints. - @return #PUGL_UNKNOWN_ERROR on failure, in which case the view frame is - unchanged. + @return An error code on failure, but always succeeds if the view is not yet + realized. */ -PUGL_API -PuglStatus -puglSetPosition(PuglView* view, int x, int y); +PUGL_API PuglStatus +puglSetPositionHint(PuglView* view, PuglPositionHint hint, int x, int y); /** - Set the current size of the view. + Get a size hint for the view. - @return #PUGL_UNKNOWN_ERROR on failure, in which case the view frame is - unchanged. + This can be used to get the default, current, minimum, and maximum size of a + view, as well as the supported range of aspect ratios. */ -PUGL_API -PuglStatus -puglSetSize(PuglView* view, unsigned width, unsigned height); +PUGL_API PuglArea +puglGetSizeHint(const PuglView* view, PuglSizeHint hint); /** Set a size hint for the view. - This can be used to set the default, minimum, and maximum size of a view, - as well as the supported range of aspect ratios. + This can be used to set the default, current, minimum, and maximum size of a + view, as well as the supported range of aspect ratios. This should be called before puglRealize() so the initial window for the - view can be configured correctly. + view can be configured correctly. It may also be used dynamically after the + window is realized, for some hints. - @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is - not yet realized. + @return An error code on failure, but always succeeds if the view is not yet + realized. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetSizeHint(PuglView* view, PuglSizeHint hint, unsigned width, @@ -1249,13 +1265,11 @@ puglSetSizeHint(PuglView* view, This must be called before puglRealize(), reparenting is not supported. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetParent(PuglView* view, PuglNativeView parent); /// Return the parent window this view is embedded in, or null -PUGL_API -PuglNativeView +PUGL_API PuglNativeView puglGetParent(const PuglView* view); /** @@ -1268,8 +1282,7 @@ puglGetParent(const PuglView* view); A view can either have a parent (for embedding) or a transient parent (for top-level windows like dialogs), but not both. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetTransientParent(PuglView* view, PuglNativeView parent); /** @@ -1278,8 +1291,7 @@ puglSetTransientParent(PuglView* view, PuglNativeView parent); @return The native handle to the window this view is a transient child of, or null. */ -PUGL_API -PuglNativeView +PUGL_API PuglNativeView puglGetTransientParent(const PuglView* view); /** @@ -1291,8 +1303,7 @@ puglGetTransientParent(const PuglView* view); The view should be fully configured using the above functions before this is called. This function may only be called once per view. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglRealize(PuglView* view); /** @@ -1301,8 +1312,7 @@ puglRealize(PuglView* view); This is the inverse of puglRealize(). After this call, the view no longer corresponds to a real system view, and can be realized again later. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglUnrealize(PuglView* view); /// A command to control the behaviour of puglShow() @@ -1346,13 +1356,11 @@ typedef enum { If the view is currently hidden, it will be shown and possibly raised to the top depending on the platform. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglShow(PuglView* view, PuglShowCommand command); /// Hide the current window -PUGL_API -PuglStatus +PUGL_API PuglStatus puglHide(PuglView* view); /** @@ -1365,8 +1373,7 @@ puglHide(PuglView* view); used to determine if the state has actually been set. Any changes to the actual state of the view will arrive in later configure events. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetViewStyle(PuglView* view, PuglViewStyleFlags flags); /** @@ -1375,18 +1382,15 @@ puglSetViewStyle(PuglView* view, PuglViewStyleFlags flags); The result is determined based on the state announced in the last configure event. */ -PUGL_API -PuglViewStyleFlags +PUGL_API PuglViewStyleFlags puglGetViewStyle(const PuglView* view); /// Return true iff the view is currently visible -PUGL_API -bool +PUGL_API bool puglGetVisible(const PuglView* view); /// Return the native window handle -PUGL_API -PuglNativeView +PUGL_API PuglNativeView puglGetNativeView(PuglView* view); /** @@ -1407,8 +1411,7 @@ puglGetNativeView(PuglView* view); All other backends: returns null. */ -PUGL_API -void* +PUGL_API void* puglGetContext(PuglView* view); /** @@ -1420,19 +1423,32 @@ puglGetContext(PuglView* view); platforms. If called elsewhere, an expose will be enqueued to be processed in the next event loop iteration. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglObscureView(PuglView* view); /** - Request a redisplay of the given rectangle within the view. + "Obscure" a region so it will be exposed in the next render. - This has the same semantics as puglObscureView(), but allows giving a precise - region for redrawing only a portion of the view. + This will cause an expose event to be dispatched later. If called from + within the event handler, the expose should arrive at the end of the current + event loop iteration, though this is not strictly guaranteed on all + platforms. If called elsewhere, an expose will be enqueued to be processed + in the next event loop iteration. + + The region is clamped to the size of the view if necessary. + + @param view The view to expose later. + @param x The top-left X coordinate of the rectangle to obscure. + @param y The top-left Y coordinate of the rectangle to obscure. + @param width The width of the rectangle to obscure. + @param height The height coordinate of the rectangle to obscure. */ -PUGL_API -PuglStatus -puglPostRedisplayRect(PuglView* view, PuglRect rect); +PUGL_API PuglStatus +puglObscureRegion(PuglView* view, + int x, + int y, + unsigned width, + unsigned height); /** @} @@ -1471,13 +1487,11 @@ typedef enum { @return #PUGL_SUCCESS if the focus was successfully grabbed, or an error. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglGrabFocus(PuglView* view); /// Return whether `view` has the keyboard input focus -PUGL_API -bool +PUGL_API bool puglHasFocus(const PuglView* view); /** @@ -1485,8 +1499,7 @@ puglHasFocus(const PuglView* view); A #PUGL_DATA_OFFER event will be sent if data is available. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglPaste(PuglView* view); /** @@ -1494,8 +1507,7 @@ puglPaste(PuglView* view); Returns zero if the clipboard is empty. */ -PUGL_API -uint32_t +PUGL_API uint32_t puglGetNumClipboardTypes(const PuglView* view); /** @@ -1507,8 +1519,7 @@ puglGetNumClipboardTypes(const PuglView* view); Returns null if `typeIndex` is out of bounds according to puglGetNumClipboardTypes(). */ -PUGL_API -const char* +PUGL_API const char* puglGetClipboardType(const PuglView* view, uint32_t typeIndex); /** @@ -1527,8 +1538,7 @@ puglGetClipboardType(const PuglView* view, uint32_t typeIndex); the `typeIndex` argument to the call of puglGetClipboardType() that returned the accepted type. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglAcceptOffer(PuglView* view, const PuglDataOfferEvent* offer, uint32_t typeIndex); @@ -1544,8 +1554,7 @@ puglAcceptOffer(PuglView* view, @param data The data to copy to the clipboard. @param len The length of data in bytes (including terminator if necessary). */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetClipboard(PuglView* view, const char* type, const void* data, @@ -1562,8 +1571,7 @@ puglSetClipboard(PuglView* view, @param[out] len Set to the length of the data in bytes. @return The clipboard contents, or null. */ -PUGL_API -const void* +PUGL_API const void* puglGetClipboard(PuglView* view, uint32_t typeIndex, size_t* len); /** @@ -1577,8 +1585,7 @@ puglGetClipboard(PuglView* view, uint32_t typeIndex, size_t* len); #PUGL_UNSUPPORTED if setting the cursor is not supported on this system, or another error if the cursor is known but loading it fails. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSetCursor(PuglView* view, PuglCursor cursor); /** @@ -1607,8 +1614,7 @@ puglSetCursor(PuglView* view, PuglCursor cursor); @return #PUGL_FAILURE if timers are not supported by the system, #PUGL_UNKNOWN_ERROR if setting the timer failed. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglStartTimer(PuglView* view, uintptr_t id, double timeout); /** @@ -1620,8 +1626,7 @@ puglStartTimer(PuglView* view, uintptr_t id, double timeout); @return #PUGL_FAILURE if timers are not supported by this system, #PUGL_UNKNOWN_ERROR if stopping the timer failed. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglStopTimer(PuglView* view, uintptr_t id); /** @@ -1634,585 +1639,17 @@ puglStopTimer(PuglView* view, uintptr_t id); Currently, only #PUGL_CLIENT events are supported on all platforms. X11: A #PUGL_EXPOSE event can be sent, which is similar to calling - puglPostRedisplayRect(), but will always send a message to the X server, - even when called in an event handler. + puglObscureRegion(), but will always send a message to the X server, even + when called in an event handler. @return #PUGL_UNSUPPORTED if sending events of this type is not supported, #PUGL_UNKNOWN_ERROR if sending the event failed. */ -PUGL_API -PuglStatus +PUGL_API PuglStatus puglSendEvent(PuglView* view, const PuglEvent* event); /** @} -*/ - -#ifndef PUGL_DISABLE_DEPRECATED - -/** - @} - @defgroup pugl_deprecated Deprecated API - @{ -*/ - -PUGL_DEPRECATED_BY("PuglRealizeEvent") -typedef PuglRealizeEvent PuglCreateEvent; - -PUGL_DEPRECATED_BY("PuglUnrealizeEvent") -typedef PuglUnrealizeEvent PuglDestroyEvent; - -PUGL_DEPRECATED_BY("PuglRealizeEvent") -typedef PuglRealizeEvent PuglEventCreate; - -PUGL_DEPRECATED_BY("PuglUnrealizeEvent") -typedef PuglUnrealizeEvent PuglEventDestroy; - -PUGL_DEPRECATED_BY("PuglConfigureEvent") -typedef PuglConfigureEvent PuglEventConfigure; - -PUGL_DEPRECATED_BY("PuglUpdateEvent") -typedef PuglUpdateEvent PuglEventUpdate; - -PUGL_DEPRECATED_BY("PuglExposeEvent") -typedef PuglExposeEvent PuglEventExpose; - -PUGL_DEPRECATED_BY("PuglCloseEvent") -typedef PuglCloseEvent PuglEventClose; - -PUGL_DEPRECATED_BY("PuglFocusEvent") -typedef PuglFocusEvent PuglEventFocus; - -PUGL_DEPRECATED_BY("PuglKeyEvent") -typedef PuglKeyEvent PuglEventKey; - -PUGL_DEPRECATED_BY("PuglTextEvent") -typedef PuglTextEvent PuglEventText; - -PUGL_DEPRECATED_BY("PuglCrossingEvent") -typedef PuglCrossingEvent PuglEventCrossing; - -PUGL_DEPRECATED_BY("PuglButtonEvent") -typedef PuglButtonEvent PuglEventButton; - -PUGL_DEPRECATED_BY("PuglMotionEvent") -typedef PuglMotionEvent PuglEventMotion; - -PUGL_DEPRECATED_BY("PuglScrollEvent") -typedef PuglScrollEvent PuglEventScroll; - -PUGL_DEPRECATED_BY("PuglClientEvent") -typedef PuglClientEvent PuglEventClient; - -PUGL_DEPRECATED_BY("PuglTimerEvent") -typedef PuglTimerEvent PuglEventTimer; - -PUGL_DEPRECATED_BY("PuglLoopEnterEvent") -typedef PuglLoopEnterEvent PuglEventLoopEnter; - -PUGL_DEPRECATED_BY("PuglLoopLeaveEvent") -typedef PuglLoopLeaveEvent PuglEventLoopLeave; - -/** - A native window handle. - - X11: This is a `Window`. - - MacOS: This is a pointer to an `NSView*`. - - Windows: This is a `HWND`. -*/ -PUGL_DEPRECATED_BY("PuglNativeView") -typedef uintptr_t PuglNativeWindow; - -/** - Create a Pugl application and view. - - To create a window, call the various puglInit* functions as necessary, then - call puglRealize(). - - @deprecated Use puglNewApp() and puglNewView(). - - @param pargc Pointer to argument count (currently unused). - @param argv Arguments (currently unused). - @return A newly created view. -*/ -static inline PUGL_DEPRECATED_BY("puglNewView") -PuglView* -puglInit(const int* pargc, char** argv) -{ - (void)pargc; - (void)argv; - - return puglNewView(puglNewWorld(PUGL_MODULE, 0)); -} - -/** - Destroy an app and view created with `puglInit()`. - - @deprecated Use puglFreeApp() and puglFreeView(). -*/ -static inline PUGL_DEPRECATED_BY("puglFreeView") -void -puglDestroy(PuglView* view) -{ - PuglWorld* const world = puglGetWorld(view); - - puglFreeView(view); - puglFreeWorld(world); -} - -/** - Set the class name of the application. - - This is a stable identifier for the application, used as the window - class/instance name on X11 and Windows. It is not displayed to the user, - but can be used in scripts and by window managers, so it should be the same - for every instance of the application, but different from other - applications. -*/ -static inline PUGL_DEPRECATED_BY("puglSetWorldString") -PuglStatus -puglSetClassName(PuglWorld* world, const char* name) -{ - return puglSetWorldString(world, PUGL_CLASS_NAME, name); -} - -/// Get the class name of the application, or null -static inline PUGL_DEPRECATED_BY("puglGetWorldString") -const char* -puglGetClassName(const PuglWorld* world) -{ - return puglGetWorldString(world, PUGL_CLASS_NAME); -} - -/** - Set the window class name before creating a window. -*/ -static inline PUGL_DEPRECATED_BY("puglSetWorldString") -void -puglInitWindowClass(PuglView* view, const char* name) -{ - puglSetWorldString(puglGetWorld(view), PUGL_CLASS_NAME, name); -} - -/** - Set the window size before creating a window. - - @deprecated Use puglSetFrame(). -*/ -static inline PUGL_DEPRECATED_BY("puglSetFrame") -void -puglInitWindowSize(PuglView* view, int width, int height) -{ - PuglRect frame = puglGetFrame(view); - - frame.width = (PuglSpan)width; - frame.height = (PuglSpan)height; - - puglSetFrame(view, frame); -} - -/** - Set the minimum window size before creating a window. -*/ -static inline PUGL_DEPRECATED_BY("puglSetSizeHint") -void -puglInitWindowMinSize(PuglView* view, int width, int height) -{ - puglSetSizeHint(view, PUGL_MIN_SIZE, (unsigned)width, (unsigned)height); -} - -/** - Set the window aspect ratio range before creating a window. - - 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 - currently work on MacOS (the minimum is used), so only setting a fixed - aspect ratio works properly across all platforms. -*/ -static inline PUGL_DEPRECATED_BY("puglSetSizeHint") -void -puglInitWindowAspectRatio(PuglView* view, - int minX, - int minY, - int maxX, - int maxY) -{ - puglSetSizeHint(view, PUGL_MIN_ASPECT, (unsigned)minX, (unsigned)minY); - puglSetSizeHint(view, PUGL_MAX_ASPECT, (unsigned)maxX, (unsigned)maxY); -} - -/** - Set transient parent before creating a window. - - On X11, parent must be a Window. - On OSX, parent must be an NSView*. -*/ -static inline PUGL_DEPRECATED_BY("puglSetTransientParent") -void -puglInitTransientFor(PuglView* view, uintptr_t parent) -{ - puglSetTransientParent(view, (PuglNativeView)parent); -} - -/** - Set transient parent before creating a window. - - @deprecated Use puglSetTransientParent(). -*/ -static inline PUGL_DEPRECATED_BY("puglSetTransientParent") -PuglStatus -puglSetTransientFor(PuglView* view, uintptr_t parent) -{ - return puglSetTransientParent(view, (PuglNativeView)parent); -} - -/** - Enable or disable resizing before creating a window. - - @deprecated Use puglSetViewHint() with #PUGL_RESIZABLE. -*/ -static inline PUGL_DEPRECATED_BY("puglSetViewHint") -void -puglInitResizable(PuglView* view, bool resizable) -{ - puglSetViewHint(view, PUGL_RESIZABLE, resizable); -} - -/** - Get the current size of the view. - - @deprecated Use puglGetFrame(). - -*/ -static inline PUGL_DEPRECATED_BY("puglGetFrame") -void -puglGetSize(PuglView* view, int* width, int* height) -{ - const PuglRect frame = puglGetFrame(view); - - *width = (int)frame.width; - *height = (int)frame.height; -} - -/** - Ignore synthetic repeated key events. - - @deprecated Use puglSetViewHint() with #PUGL_IGNORE_KEY_REPEAT. -*/ -static inline PUGL_DEPRECATED_BY("puglSetViewHint") -void -puglIgnoreKeyRepeat(PuglView* view, bool ignore) -{ - puglSetViewHint(view, PUGL_IGNORE_KEY_REPEAT, ignore); -} - -/** - Set a hint before creating a window. - - @deprecated Use puglSetWindowHint(). -*/ -static inline PUGL_DEPRECATED_BY("puglSetViewHint") -void -puglInitWindowHint(PuglView* view, PuglViewHint hint, int value) -{ - puglSetViewHint(view, hint, value); -} - -/** - Set the parent window before creating a window (for embedding). - - @deprecated Use puglSetWindowParent(). -*/ -static inline PUGL_DEPRECATED_BY("puglSetParent") -void -puglInitWindowParent(PuglView* view, PuglNativeView parent) -{ - puglSetParent(view, parent); -} - -/** - Set the graphics backend to use. - - @deprecated Use puglSetBackend(). -*/ -static inline PUGL_DEPRECATED_BY("puglSetBackend") -int -puglInitBackend(PuglView* view, const PuglBackend* backend) -{ - return (int)puglSetBackend(view, backend); -} - -/** - Set the title of the window. - - 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. -*/ -static inline PUGL_DEPRECATED_BY("puglSetViewString") -PuglStatus -puglSetWindowTitle(PuglView* view, const char* title) -{ - return puglSetViewString(view, PUGL_WINDOW_TITLE, title); -} - -/// Return the title of the window, or null -static inline PUGL_DEPRECATED_BY("puglGetViewString") -const char* -puglGetWindowTitle(const PuglView* view) -{ - return puglGetViewString(view, PUGL_WINDOW_TITLE); -} - -/** - Realize a view by creating a corresponding system view or window. - - The view should be fully configured using the above functions before this is - called. This function may only be called once per view. - - @deprecated Use puglRealize(), or just show the view. -*/ -static inline PUGL_DEPRECATED_BY("puglRealize") -PuglStatus -puglCreateWindow(PuglView* view, const char* title) -{ - puglSetViewString(view, PUGL_WINDOW_TITLE, title); - return puglRealize(view); -} - -/** - Block and wait for an event to be ready. - - This can be used in a loop to only process events via puglProcessEvents when - necessary. This function will block indefinitely if no events are - available, so is not appropriate for use in programs that need to perform - regular updates (e.g. animation). - - @deprecated Use puglPollEvents(). -*/ -PUGL_API -PUGL_DEPRECATED_BY("puglPollEvents") -PuglStatus -puglWaitForEvent(PuglView* view); - -/** - Process all pending window events. - - This handles input events as well as rendering, so it should be called - regularly and rapidly enough to keep the UI responsive. This function does - not block if no events are pending. - - @deprecated Use puglDispatchEvents(). -*/ -PUGL_API -PUGL_DEPRECATED_BY("puglDispatchEvents") -PuglStatus -puglProcessEvents(PuglView* view); - -/** - Poll for events that are ready to be processed. - - This polls for events that are ready for any view in the world, potentially - blocking depending on `timeout`. - - @param world The world to poll for events. - - @param timeout Maximum time to wait, in seconds. If zero, the call returns - immediately, if negative, the call blocks indefinitely. - - @return #PUGL_SUCCESS if events are read, #PUGL_FAILURE if not, or an error. - - @deprecated Use puglUpdate(). -*/ -static inline PUGL_DEPRECATED_BY("puglUpdate") -PuglStatus -puglPollEvents(PuglWorld* world, double timeout) -{ - return puglUpdate(world, timeout); -} - -/** - Dispatch any pending events to views. - - This processes all pending events, dispatching them to the appropriate - views. View event handlers will be called in the scope of this call. This - function does not block, if no events are pending then it will return - immediately. - - @deprecated Use puglUpdate(). -*/ -static inline PUGL_DEPRECATED_BY("puglUpdate") -PuglStatus -puglDispatchEvents(PuglWorld* world) -{ - return puglUpdate(world, 0.0); -} - -static inline PUGL_DEPRECATED_BY("puglShow") -PuglStatus -puglShowWindow(PuglView* view) -{ - return puglShow(view, PUGL_SHOW_RAISE); -} - -static inline PUGL_DEPRECATED_BY("puglHide") -PuglStatus -puglHideWindow(PuglView* view) -{ - return puglHide(view); -} - -/** - Set the default size of the view. - - This should be called before puglRealize() to set the default size of the - view, which will be the initial size of the window if this is a top level - view. - - @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is - not yet realized. -*/ -static inline PUGL_DEPRECATED_BY("puglSetSizeHint") -PuglStatus -puglSetDefaultSize(PuglView* view, int width, int height) -{ - return puglSetSizeHint( - view, PUGL_DEFAULT_SIZE, (unsigned)width, (unsigned)height); -} - -/** - Set the minimum size of the view. - - If an initial minimum size is known, this should be called before - puglRealize() to avoid stutter, though it can be called afterwards as well. - - @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is - not yet realized. -*/ -static inline PUGL_DEPRECATED_BY("puglSetSizeHint") -PuglStatus -puglSetMinSize(PuglView* view, int width, int height) -{ - return puglSetSizeHint( - view, PUGL_MIN_SIZE, (unsigned)width, (unsigned)height); -} - -/** - Set the maximum size of the view. - - If an initial maximum size is known, this should be called before - puglRealize() to avoid stutter, though it can be called afterwards as well. - - @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is - not yet realized. -*/ -static inline PUGL_DEPRECATED_BY("puglSetSizeHint") -PuglStatus -puglSetMaxSize(PuglView* view, int width, int height) -{ - return puglSetSizeHint( - view, PUGL_MAX_SIZE, (unsigned)width, (unsigned)height); -} - -/** - Set the view 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 - currently work on MacOS (the minimum is used), so only setting a fixed - aspect ratio works properly across all platforms. - - If an initial aspect ratio is known, this should be called before - puglRealize() to avoid stutter, though it can be called afterwards as well. - - @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is - not yet realized. -*/ -static inline PUGL_DEPRECATED_BY("puglSetSizeHint") -PuglStatus -puglSetAspectRatio(PuglView* view, int minX, int minY, int maxX, int maxY) -{ - const PuglStatus st0 = - puglSetSizeHint(view, PUGL_MIN_ASPECT, (unsigned)minX, (unsigned)minY); - - const PuglStatus st1 = - puglSetSizeHint(view, PUGL_MAX_ASPECT, (unsigned)maxX, (unsigned)maxY); - - return st0 ? st0 : st1; -} - -/// Return the native window handle -static inline PUGL_DEPRECATED_BY("puglGetNativeView") -PuglNativeView -puglGetNativeWindow(PuglView* view) -{ - return puglGetNativeView(view); -} - -/** - Request user attention. - - This hints to the system that the window or application requires attention - from the user. The exact effect depends on the platform, but is usually - something like a flashing task bar entry or bouncing application icon. -*/ -static inline PUGL_DEPRECATED_BY("puglSetViewStyle") -PuglStatus -puglRequestAttention(PuglView* view) -{ - return puglSetViewStyle(view, - puglGetViewStyle(view) | PUGL_VIEW_STYLE_DEMANDING); -} - -# define PUGL_KEY_SHIFT PUGL_KEY_SHIFT_L - -# define PUGL_KEY_CTRL PUGL_KEY_CTRL_L - -# define PUGL_KEY_ALT PUGL_KEY_ALT_L - -# define PUGL_KEY_SUPER PUGL_KEY_SUPER_L - -/// Set the parent window for embedding a view in an existing window -static inline PUGL_DEPRECATED_BY("puglSetParent") -PuglStatus -puglSetParentWindow(PuglView* view, PuglNativeView parent) -{ - return puglSetParent(view, parent); -} - -/// Return the parent window this view is embedded in, or null -static inline PUGL_DEPRECATED_BY("puglGetParent") -PuglNativeView -puglGetParentWindow(PuglView* view) -{ - return puglGetParent(view); -} - -/** - Request a redisplay for the entire view. - - This will cause an expose event to be dispatched later. If called from - within the event handler, the expose should arrive at the end of the current - event loop iteration, though this is not strictly guaranteed on all - platforms. If called elsewhere, an expose will be enqueued to be processed - in the next event loop iteration. -*/ -static inline PUGL_DEPRECATED_BY("puglObscureView") -PuglStatus -puglPostRedisplay(PuglView* view) -{ - return puglObscureView(view); -} - -#endif // PUGL_DISABLE_DEPRECATED - -/** @} @} */ |