diff options
Diffstat (limited to 'include/pugl/pugl.h')
| -rw-r--r-- | include/pugl/pugl.h | 118 |
1 files changed, 100 insertions, 18 deletions
diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h index 7b021b8..00dffba 100644 --- a/include/pugl/pugl.h +++ b/include/pugl/pugl.h @@ -132,6 +132,51 @@ typedef struct { */ /** + View style flags. + + Style flags reflect special modes and states supported by the window system. + Applications should ideally use a single main view, but can monitor or + manipulate style flags to better integrate with the window system. +*/ +typedef enum { + /// View is mapped to a real window and potentially visible + PUGL_VIEW_STYLE_MAPPED = 1U << 0U, + + /// View is modal, typically a dialog box of its transient parent + PUGL_VIEW_STYLE_MODAL = 1U << 1U, + + /// View should be above most others + PUGL_VIEW_STYLE_ABOVE = 1U << 2U, + + /// View should be below most others + PUGL_VIEW_STYLE_BELOW = 1U << 3U, + + /// View is minimized, shaded, or otherwise invisible + PUGL_VIEW_STYLE_HIDDEN = 1U << 4U, + + /// View is maximized to fill the screen vertically + PUGL_VIEW_STYLE_TALL = 1U << 5U, + + /// View is maximized to fill the screen horizontally + PUGL_VIEW_STYLE_WIDE = 1U << 6U, + + /// View is enlarged to fill the entire screen with no decorations + PUGL_VIEW_STYLE_FULLSCREEN = 1U << 7U, + + /// View is being resized + PUGL_VIEW_STYLE_RESIZING = 1U << 8U, + + /// View is ready for input or otherwise demanding attention + PUGL_VIEW_STYLE_DEMANDING = 1U << 9U, +} PuglViewStyleFlag; + +/// The maximum #PuglViewStyleFlag value +#define PUGL_MAX_VIEW_STYLE_FLAG PUGL_VIEW_STYLE_DEMANDING + +/// Bitwise OR of #PuglViewStyleFlag values +typedef uint32_t PuglViewStyleFlags; + +/** View realize event. This event is sent when a view is realized before it is first displayed, @@ -163,12 +208,13 @@ typedef PuglAnyEvent PuglUnrealizeEvent; otherwise configure the context, but not to draw anything. */ typedef struct { - PuglEventType type; ///< #PUGL_CONFIGURE - PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values - PuglCoord x; ///< Parent-relative X coordinate of view - PuglCoord y; ///< Parent-relative Y coordinate of view - PuglSpan width; ///< Width of view - PuglSpan height; ///< Height of view + PuglEventType type; ///< #PUGL_CONFIGURE + PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values + PuglCoord x; ///< Parent-relative X coordinate of view + PuglCoord y; ///< Parent-relative Y coordinate of view + PuglSpan width; ///< Width of view + PuglSpan height; ///< Height of view + PuglViewStyleFlags style; ///< Bitwise OR of #PuglViewStyleFlag flags } PuglConfigureEvent; /** @@ -863,10 +909,11 @@ typedef enum { PUGL_RESIZABLE, ///< True if view should be resizable PUGL_IGNORE_KEY_REPEAT, ///< True if key repeat events are ignored PUGL_REFRESH_RATE, ///< Refresh rate in Hz + PUGL_VIEW_TYPE, ///< View type (a #PuglViewType) } PuglViewHint; /// The number of #PuglViewHint values -#define PUGL_NUM_VIEW_HINTS ((unsigned)PUGL_REFRESH_RATE + 1U) +#define PUGL_NUM_VIEW_HINTS ((unsigned)PUGL_VIEW_TYPE + 1U) /// A special view hint value typedef enum { @@ -875,6 +922,13 @@ typedef enum { PUGL_TRUE = 1 ///< Explicitly true } PuglViewHintValue; +/// View type +typedef enum { + PUGL_VIEW_TYPE_NORMAL, ///< A normal top-level window + PUGL_VIEW_TYPE_UTILITY, ///< A utility window like a palette or toolbox + PUGL_VIEW_TYPE_DIALOG, ///< A dialog window +} PuglViewType; + /** A hint for configuring/constraining the size of a view. @@ -1198,6 +1252,30 @@ PUGL_API PuglStatus puglHide(PuglView* view); +/** + Set a view state, if supported by the system. + + This can be used to manipulate the window into various special states, but + note that not all states are supported on all systems. This function may + return failure or an error if the platform implementation doesn't + "understand" how to set the given style, but the return value here can't be + 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 +puglSetViewStyle(PuglView* view, PuglViewStyleFlags flags); + +/** + Return true if the view currently has a state flag set. + + The result is determined based on the state announced in the last configure + event. +*/ +PUGL_API +PuglViewStyleFlags +puglGetViewStyle(const PuglView* view); + /// Return true iff the view is currently visible PUGL_API bool @@ -1399,17 +1477,6 @@ PuglStatus puglSetCursor(PuglView* view, PuglCursor cursor); /** - 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. -*/ -PUGL_API -PuglStatus -puglRequestAttention(PuglView* view); - -/** Activate a repeating timer event. This starts a timer which will send a #PuglTimerEvent to `view` every @@ -1943,6 +2010,21 @@ 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); +} + #endif // PUGL_DISABLE_DEPRECATED /** |