Window

Functions to control the top-level window of a view.

enum PuglShowCommand

A command to control the behaviour of puglShow()

enumerator PUGL_SHOW_PASSIVE

Realize and show the window without intentionally raising it.

This will weakly “show” the window but without making any effort to raise it. Depending on the platform or system configuration, the window may be raised above some others regardless.

enumerator PUGL_SHOW_RAISE

Raise the window to the top of the application’s stack.

This is the normal “well-behaved” way to show and raise the window, which should be used in most cases.

enumerator PUGL_SHOW_FORCE_RAISE

Aggressively force the window to be raised to the top.

This will attempt to raise the window to the top, even if this isn’t the active application, or if doing so would otherwise go against the platform’s guidelines. This generally shouldn’t be used, and isn’t guaranteed to work. On modern Windows systems, the active application must explicitly grant permission for others to steal the foreground from it.

PuglNativeView puglGetNativeView(const PuglView *view)

Return the native window handle.

PuglNativeView puglGetParent(const PuglView *view)

Return the native view that the view is embedded in.

Returns:

The native view handle of the parent that view is embedded in, or zero (if view is top-level or unrealized).

PuglNativeView puglGetTransientParent(const PuglView *view)

Return the transient parent of the window.

Returns:

The native handle to the window this view is a transient child of, or null.

PuglViewStyleFlags puglGetViewStyle(const PuglView *view)

Return the style flags currently set for a view.

bool puglGetVisible(const PuglView *view)

Return true iff the view is currently visible.

PuglStatus puglHide(PuglView *view)

Hide the view.

This is the counterpart to puglShow(). If the view is currently visible, it will be hidden, otherwise, this does nothing.

PuglStatus puglRealize(PuglView *view)

Realize a view by creating a corresponding system view or window.

After this call, the (initially invisible) underlying system view exists and can be accessed with puglGetNativeView().

The view should be fully configured using the above functions before this is called. This function may only be called once per view.

PuglStatus puglSetParent(PuglView *view, PuglNativeView parent)

Set the native view the view will be embedded in.

This must be called before puglRealize(), reparenting isn’t supported.

PuglStatus puglSetTransientParent(PuglView *view, PuglNativeView parent)

Set the transient parent of the window.

Set this for transient children like dialogs, to have them properly associated with their parent window. This should be called before puglRealize().

A view can either have a parent (for embedding) or a transient parent (for top-level windows like dialogs), but not both.

PuglStatus puglSetViewStyle(PuglView *view, PuglViewStyleFlags flags)

Set a view style, 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.

PuglStatus puglShow(PuglView *view, PuglShowCommand command)

Show the view.

If the view has not yet been realized, the first call to this function will do so automatically. If the view is currently hidden, it will be shown and possibly raised to the top depending on the platform.

Returns:

PuglStatus.PUGL_SUCCESS, an error from realization, or PuglStatus.PUGL_FAILURE if the window was shown but not raised.

PuglStatus puglUnrealize(PuglView *view)

Unrealize a view by destroying the corresponding system view or window.

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.