Set or get flags affecting operation of a visual

Name

ggiWmhSetFlags, ggiWmhGetFlags, ggiWmhAddFlags, ggiWmhRemoveFlags : Set or get flags affecting operation of a visual

Synopsis

#include <ggi/wmh.h>

int ggiWmhSetFlags(ggi_visual_t vis, uint32_t flags);

uint32_t ggiWmhGetFlags(ggi_visual_t vis);

#define ggiWmhAddFlags(vis,flags) \
             ggiWmhSetFlags((vis), ggiWmhGetFlags((vis) | (flags))
#define ggiWmhRemoveFlags(vis,flags) \
             ggiWmhSetFlags((vis), ggiWmhGetFlags((vis) & ~(flags))

Description

ggiWmhSetFlags sets the specified flags (bitwise OR'd together) on a visual.

ggiWmhGetFlags obtains the flags currently in effect.

ggiWmhAddFlags and ggiWmhRemoveFlags are macros that set or unset the specified flags.

Flags are used to alter a visual's underlying behaviour. All flags default to an unset value. Flags which are not supported by a given visual will remain unset even when an attempt is made to raise them. Thus, it is possible to tell by reading back the flags whether or not each of the flags is supported by the given visual.

Return Value

ggiWmhSetFlags, ggiAddFlags(3) and ggiRemoveFlags(3) return 0 on success, a gg-error(3) code on failure. This will only happen if the failure of a target to support the addition or removal of a flag will cause the target to behave in a way that the application is not expecting. As of this writing there are no such cases. On visuals where certain flags are unsupported but are inconsequential, these functions will return a successful return code, but will not actually set or clear the flag.

ggiGetFlags(3) returns the current flags. This can be used by the curious to check whether a flag is being silently ignored as per above.

Flags

GGIWMHFLAG_WITHDECORATION

When turned on, all coordinates used to alter window position and size include the window decoration. Visuals that only support altering the window position and size including window decoration, turn on this flag during initialization and don't allow to turn it off. Visuals that don't support window decoration at all, turn off this flag during initialization and don't allow to turn it on. Visuals that support both turn this flag off during initialization but allow the user to turn it on and off.

GGIWMHFLAG_GRAB_HOTKEYS

When turned on, the target will try to grab any hotkeys otherwise affecting the system, e.g. Alt-Tab to switch application. Hotkeys that are grabbed are passed on to the application. When turned off, hotkeys are not passed on to the application, they are instead handled by the system. It may not be possible for a target to grab all hotkeys.

GGIWMHFLAG_CATCH_CLOSE

When turned on, the target notifies when the user wants to exit the application with an event of type GII_SLI_CODE_WMH_CLOSEREQUEST.

GGIWMHFLAG_CLIPBOARD_CHANGE

When turned on, the target notifies when the clipboard contents change with an event of type GII_SLI_CODE_WMH_CLIPBOARD_CHANGE.

See Also