| Top |  |
 |
 |
 |
Functions
| gint64 | gdk_frame_clock_get_frame_time () |
| void | gdk_frame_clock_request_phase () |
| void | gdk_frame_clock_begin_updating () |
| void | gdk_frame_clock_end_updating () |
| gint64 | gdk_frame_clock_get_frame_counter () |
| gint64 | gdk_frame_clock_get_history_start () |
| GdkFrameTimings * | gdk_frame_clock_get_timings () |
| GdkFrameTimings * | gdk_frame_clock_get_current_timings () |
| void | gdk_frame_clock_get_refresh_info () |
Signals
| void | after-paint | Run Last |
| void | before-paint | Run Last |
| void | flush-events | Run Last |
| void | layout | Run Last |
| void | paint | Run Last |
| void | resume-events | Run Last |
| void | update | Run Last |
Description
A GdkFrameClock tells the application when to update and repaint a window. This may be synced to the vertical refresh rate of the monitor, for example. Even when the frame clock uses a simple timer rather than a hardware-based vertical sync, the frame clock helps because it ensures everything paints at the same time (reducing the total number of frames). The frame clock can also automatically stop painting when it knows the frames will not be visible, or scale back animation framerates.
GdkFrameClock is designed to be compatible with an OpenGL-based implementation or with mozRequestAnimationFrame in Firefox, for example.
A frame clock is idle until someone requests a frame with
gdk_frame_clock_request_phase(). At some later point that makes
sense for the synchronization being implemented, the clock will
process a frame and emit signals for each phase that has been
requested. (See the signals of the GdkFrameClock class for
documentation of the phases. GDK_FRAME_CLOCK_PHASE_UPDATE and the
“update” signal are most interesting for application
writers, and are used to update the animations, using the frame time
given by gdk_frame_clock_get_frame_time().
The frame time is reported in microseconds and generally in the same
timescale as g_get_monotonic_time(), however, it is not the same
as g_get_monotonic_time(). The frame time does not advance during
the time a frame is being painted, and outside of a frame, an attempt
is made so that all calls to gdk_frame_clock_get_frame_time() that
are called at a “similar” time get the same value. This means that
if different animations are timed by looking at the difference in
time between an initial value from gdk_frame_clock_get_frame_time()
and the value inside the “update” signal of the clock,
they will stay exactly synchronized.
Functions
gdk_frame_clock_get_frame_time ()
gint64
gdk_frame_clock_get_frame_time (GdkFrameClock *frame_clock);
Gets the time that should currently be used for animations. Inside the processing of a frame, it’s the time used to compute the animation position of everything in a frame. Outside of a frame, it's the time of the conceptual “previous frame,” which may be either the actual previous frame time, or if that’s too old, an updated time.
gdk_frame_clock_request_phase ()
void gdk_frame_clock_request_phase (GdkFrameClock *frame_clock,GdkFrameClockPhase phase);
Asks the frame clock to run a particular phase. The signal
corresponding the requested phase will be emitted the next
time the frame clock processes. Multiple calls to
gdk_frame_clock_request_phase() will be combined together
and only one frame processed. If you are displaying animated
content and want to continually request the
GDK_FRAME_CLOCK_PHASE_UPDATE phase for a period of time,
you should use gdk_frame_clock_begin_updating() instead, since
this allows GTK to adjust system parameters to get maximally
smooth animations.
gdk_frame_clock_begin_updating ()
void
gdk_frame_clock_begin_updating (GdkFrameClock *frame_clock);
Starts updates for an animation. Until a matching call to
gdk_frame_clock_end_updating() is made, the frame clock will continually
request a new frame with the GDK_FRAME_CLOCK_PHASE_UPDATE phase.
This function may be called multiple times and frames will be
requested until gdk_frame_clock_end_updating() is called the same
number of times.
gdk_frame_clock_end_updating ()
void
gdk_frame_clock_end_updating (GdkFrameClock *frame_clock);
Stops updates for an animation. See the documentation for
gdk_frame_clock_begin_updating().
gdk_frame_clock_get_frame_counter ()
gint64
gdk_frame_clock_get_frame_counter (GdkFrameClock *frame_clock);
A GdkFrameClock maintains a 64-bit counter that increments for each frame drawn.
gdk_frame_clock_get_history_start ()
gint64
gdk_frame_clock_get_history_start (GdkFrameClock *frame_clock);
GdkFrameClock internally keeps a history of GdkFrameTimings
objects for recent frames that can be retrieved with
gdk_frame_clock_get_timings(). The set of stored frames
is the set from the counter values given by
gdk_frame_clock_get_history_start() and
gdk_frame_clock_get_frame_counter(), inclusive.
Returns
the frame counter value for the oldest frame that is available in the internal frame history of the GdkFrameClock.
gdk_frame_clock_get_timings ()
GdkFrameTimings * gdk_frame_clock_get_timings (GdkFrameClock *frame_clock,gint64 frame_counter);
Retrieves a GdkFrameTimings object holding timing information
for the current frame or a recent frame. The GdkFrameTimings
object may not yet be complete: see gdk_frame_timings_get_complete().
Returns
the GdkFrameTimings object for
the specified frame, or NULL if it is not available. See
gdk_frame_clock_get_history_start().
[nullable][transfer none]
gdk_frame_clock_get_current_timings ()
GdkFrameTimings *
gdk_frame_clock_get_current_timings (GdkFrameClock *frame_clock);
Gets the frame timings for the current frame.
Returns
the GdkFrameTimings for the
frame currently being processed, or even no frame is being
processed, for the previous frame. Before any frames have been
processed, returns NULL.
[nullable][transfer none]
gdk_frame_clock_get_refresh_info ()
void gdk_frame_clock_get_refresh_info (GdkFrameClock *frame_clock,gint64 base_time,gint64 *refresh_interval_return,gint64 *presentation_time_return);
Using the frame history stored in the frame clock, finds the last
known presentation time and refresh interval, and assuming that
presentation times are separated by the refresh interval,
predicts a presentation time that is a multiple of the refresh
interval after the last presentation time, and later than base_time
.
Parameters
frame_clock |
||
base_time |
base time for determining a presentaton time |
|
refresh_interval_return |
a location to store the
determined refresh interval, or |
[out][optional] |
presentation_time_return |
a location to store the next candidate presentation time after the given base time. 0 will be will be stored if no history is present. |
[out] |
Types and Values
enum GdkFrameClockPhase
GdkFrameClockPhase is used to represent the different paint clock phases that can be requested. The elements of the enumeration correspond to the signals of GdkFrameClock.
Members
|
no phase |
||
|
corresponds to GdkFrameClock::flush-events. Should not be handled by applications. |
||
|
corresponds to GdkFrameClock::before-paint. Should not be handled by applications. |
||
|
corresponds to GdkFrameClock::update. |
||
|
corresponds to GdkFrameClock::layout. |
||
|
corresponds to GdkFrameClock::paint. |
||
|
corresponds to GdkFrameClock::resume-events. Should not be handled by applications. |
||
|
corresponds to GdkFrameClock::after-paint. Should not be handled by applications. |
Signal Details
The “after-paint” signal
void user_function (GdkFrameClock *clock, gpointer user_data)
This signal ends processing of the frame. Applications should generally not handle this signal.
Parameters
clock |
the frame clock emitting the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “before-paint” signal
void user_function (GdkFrameClock *clock, gpointer user_data)
This signal begins processing of the frame. Applications should generally not handle this signal.
Parameters
clock |
the frame clock emitting the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “flush-events” signal
void user_function (GdkFrameClock *clock, gpointer user_data)
This signal is used to flush pending motion events that are being batched up and compressed together. Applications should not handle this signal.
Parameters
clock |
the frame clock emitting the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “layout” signal
void user_function (GdkFrameClock *clock, gpointer user_data)
This signal is emitted as the second step of toolkit and application processing of the frame. Any work to update sizes and positions of application elements should be performed. GTK normally handles this internally.
Parameters
clock |
the frame clock emitting the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “paint” signal
void user_function (GdkFrameClock *clock, gpointer user_data)
This signal is emitted as the third step of toolkit and application processing of the frame. The frame is repainted. GDK normally handles this internally and produces expose events, which are turned into GTK “draw” signals.
Parameters
clock |
the frame clock emitting the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “resume-events” signal
void user_function (GdkFrameClock *clock, gpointer user_data)
This signal is emitted after processing of the frame is finished, and is handled internally by GTK to resume normal event processing. Applications should not handle this signal.
Parameters
clock |
the frame clock emitting the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “update” signal
void user_function (GdkFrameClock *clock, gpointer user_data)
This signal is emitted as the first step of toolkit and
application processing of the frame. Animations should
be updated using gdk_frame_clock_get_frame_time().
Applications can connect directly to this signal, or
use gtk_widget_add_tick_callback() as a more convenient
interface.
Parameters
clock |
the frame clock emitting the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
| Top | |
|
|
|
Functions
Description
The functions in this section are specific to the GDK X11 backend.
To use them, you need to include the <gdk/gdkx.h> header and use
the X11-specific pkg-config file gtk4-x11 to build your application.
To make your code compile with other GDK backends, guard backend-specific
calls by an ifdef as follows. Since GDK may be built with multiple
backends, you should also check for the backend that is in use (e.g. by
using the GDK_IS_X11_DISPLAY() macro).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
#ifdef GDK_WINDOWING_X11 if (GDK_IS_X11_DISPLAY (display)) { // make X11-specific calls here } else #endif #ifdef GDK_WINDOWING_QUARTZ if (GDK_IS_QUARTZ_DISPLAY (display)) { // make Quartz-specific calls here } else #endif g_error ("Unsupported GDK backend"); |
Functions
GDK_SURFACE_XID()
#define GDK_SURFACE_XID(win) (gdk_x11_surface_get_xid (win))
Returns the X window belonging to a GdkSurface.
GDK_DISPLAY_XDISPLAY()
#define GDK_DISPLAY_XDISPLAY(display) (gdk_x11_display_get_xdisplay (display))
Returns the display of a GdkDisplay.
GDK_POINTER_TO_XID()
#define GDK_POINTER_TO_XID(pointer) GPOINTER_TO_UINT(pointer)
Converts a gpointer
back to an XID that was previously converted
using GDK_XID_TO_POINTER().
GDK_XID_TO_POINTER()
#define GDK_XID_TO_POINTER(xid) GUINT_TO_POINTER(xid)
Converts an XID into a gpointer
. This is useful with data structures
that use pointer arguments such as GHashTable. Use GDK_POINTER_TO_XID()
to convert the argument back to an XID.
gdk_x11_lookup_xdisplay ()
GdkDisplay *
gdk_x11_lookup_xdisplay (Display *xdisplay);
Find the GdkDisplay corresponding to xdisplay
, if any exists.
gdk_x11_get_server_time ()
guint32
gdk_x11_get_server_time (GdkSurface *surface);
Routine to get the current X server time stamp.
Parameters
surface |
a GdkSurface, used for communication with the server. The surface must have GDK_PROPERTY_CHANGE_MASK in its events mask or a hang will result. |
[type GdkX11Surface] |
gdk_x11_device_get_id ()
gint
gdk_x11_device_get_id (GdkDevice *device);
Returns the device ID as seen by XInput2.
If
gdk_disable_multidevice()has been called, this function will respectively return 2/3 for the core pointer and keyboard, (matching the IDs for the Virtual Core Pointer and Keyboard in XInput 2), but calling this function on any slave devices (i.e. those managed via XInput 1.x), will return 0.
gdk_x11_device_manager_lookup ()
GdkDevice * gdk_x11_device_manager_lookup (GdkX11DeviceManagerCore *device_manager,gint device_id);
Returns the GdkDevice that wraps the given device ID.
Parameters
device_manager |
a GdkDeviceManager. |
[type GdkX11DeviceManagerCore] |
device_id |
a device ID, as understood by the XInput2 protocol |
Returns
The GdkDevice wrapping the device ID,
or NULL if the given ID doesn’t currently represent a device.
[transfer none][allow-none][type GdkX11DeviceCore]
gdk_disable_multidevice ()
void
gdk_disable_multidevice (void);
Disables multidevice support in GDKs X11 backend. This call must happen prior
to gdk_display_open(), gtk_init() or gtk_init_check() in order to
take effect.
Most common GTK+ applications won’t ever need to call this. Only applications that do mixed GDK/Xlib calls could want to disable multidevice support if such Xlib code deals with input devices in any way and doesn’t observe the presence of XInput 2.
gdk_x11_display_open ()
GdkDisplay *
gdk_x11_display_open (const char *display_name);
Tries to open a new display to the X server given by
display_name
. If opening the display fails, NULL is
returned.
gdk_x11_display_set_program_class ()
void gdk_x11_display_set_program_class (GdkDisplay *display,const char *program_class);
Sets the program class.
The X11 backend uses the program class to set the class name part
of the WM_CLASS property on toplevel windows; see the ICCCM.
gdk_x11_display_get_user_time ()
guint32
gdk_x11_display_get_user_time (GdkDisplay *display);
Returns the timestamp of the last user interaction on
display
. The timestamp is taken from events caused
by user interaction such as key presses or pointer
movements. See gdk_x11_surface_set_user_time().
gdk_x11_display_broadcast_startup_message ()
void gdk_x11_display_broadcast_startup_message (GdkDisplay *display,const char *message_type,...);
Sends a startup notification message of type message_type
to
display
.
This is a convenience function for use by code that implements the freedesktop startup notification specification. Applications should not normally need to call it directly. See the Startup Notification Protocol specification for definitions of the message types and keys that can be used.
Parameters
display |
a GdkDisplay. |
[type GdkX11Display] |
message_type |
startup notification message type ("new", "change", or "remove") |
|
... |
a list of key/value pairs (as strings), terminated by a
|
gdk_x11_display_get_startup_notification_id ()
const gchar *
gdk_x11_display_get_startup_notification_id
(GdkDisplay *display);
Gets the startup notification ID for a display.
gdk_x11_display_set_startup_notification_id ()
void gdk_x11_display_set_startup_notification_id (GdkDisplay *display,const gchar *startup_id);
Sets the startup notification ID for a display.
This is usually taken from the value of the DESKTOP_STARTUP_ID
environment variable, but in some cases (such as the application not
being launched using exec()) it can come from other sources.
If the ID contains the string "_TIME" then the portion following that string is taken to be the X11 timestamp of the event that triggered the application to be launched and the GDK current event time is set accordingly.
The startup ID is also what is used to signal that the startup is
complete (for example, when opening a window or when calling
gdk_notify_startup_complete()).
Parameters
display |
a GdkDisplay. |
[type GdkX11Display] |
startup_id |
the startup notification ID (must be valid utf8) |
gdk_x11_display_get_xdisplay ()
Display *
gdk_x11_display_get_xdisplay (GdkDisplay *display);
Returns the X display of a GdkDisplay.
gdk_x11_display_get_xscreen ()
Screen *
gdk_x11_display_get_xscreen (GdkDisplay *display);
Returns the X Screen used by GdkDisplay.
gdk_x11_display_get_xrootwindow ()
Window
gdk_x11_display_get_xrootwindow (GdkDisplay *display);
Returns the root X window used by GdkDisplay.
gdk_x11_display_get_xcursor ()
Cursor gdk_x11_display_get_xcursor (GdkDisplay *display,GdkCursor *cursor);
Returns the X cursor belonging to a GdkCursor, potentially creating the cursor.
Be aware that the returned cursor may not be unique to cursor
.
It may for example be shared with its fallback cursor. On old
X servers that don't support the XCursor extension, all cursors
may even fall back to a few default cursors.
gdk_x11_display_grab ()
void
gdk_x11_display_grab (GdkDisplay *display);
Call XGrabServer() on display
.
To ungrab the display again, use gdk_x11_display_ungrab().
gdk_x11_display_grab()/gdk_x11_display_ungrab() calls can be nested.
gdk_x11_display_ungrab ()
void
gdk_x11_display_ungrab (GdkDisplay *display);
Ungrab display
after it has been grabbed with
gdk_x11_display_grab().
gdk_x11_display_error_trap_push ()
void
gdk_x11_display_error_trap_push (GdkDisplay *display);
Begins a range of X requests on display
for which X error events
will be ignored. Unignored errors (when no trap is pushed) will abort
the application. Use gdk_x11_display_error_trap_pop() or
gdk_x11_display_error_trap_pop_ignored()to lift a trap pushed
with this function.
See also gdk_error_trap_push() to push a trap on all displays.
gdk_x11_display_error_trap_pop ()
gint
gdk_x11_display_error_trap_pop (GdkDisplay *display);
Pops the error trap pushed by gdk_x11_display_error_trap_push().
Will XSync() if necessary and will always block until
the error is known to have occurred or not occurred,
so the error code can be returned.
If you don’t need to use the return value,
gdk_x11_display_error_trap_pop_ignored() would be more efficient.
See gdk_error_trap_pop() for the all-displays-at-once
equivalent.
gdk_x11_display_error_trap_pop_ignored ()
void
gdk_x11_display_error_trap_pop_ignored
(GdkDisplay *display);
Pops the error trap pushed by gdk_x11_display_error_trap_push().
Does not block to see if an error occurred; merely records the
range of requests to ignore errors for, and ignores those errors
if they arrive asynchronously.
See gdk_error_trap_pop_ignored() for the all-displays-at-once
equivalent.
gdk_x11_display_set_cursor_theme ()
void gdk_x11_display_set_cursor_theme (GdkDisplay *display,const gchar *theme,const gint size);
Sets the cursor theme from which the images for cursor should be taken.
If the windowing system supports it, existing cursors created
with gdk_cursor_new(), gdk_cursor_new_for_display() and
gdk_cursor_new_from_name() are updated to reflect the theme
change. Custom cursors constructed with
gdk_cursor_new_from_texture() will have to be handled
by the application (GTK+ applications can learn about
cursor theme changes by listening for change notification
for the corresponding GtkSetting).
Parameters
display |
a GdkDisplay. |
[type GdkX11Display] |
theme |
the name of the cursor theme to use, or |
[nullable] |
size |
the cursor size to use, or 0 to keep the previous size |
gdk_x11_display_set_surface_scale ()
void gdk_x11_display_set_surface_scale (GdkDisplay *display,gint scale);
Forces a specific window scale for all windows on this display,
instead of using the default or user configured scale. This
is can be used to disable scaling support by setting scale
to
1, or to programmatically set the window scale.
Once the scale is set by this call it will not change in response to later user configuration changes.
gdk_x11_display_get_glx_version ()
gboolean gdk_x11_display_get_glx_version (GdkDisplay *display,gint *major,gint *minor);
Retrieves the version of the GLX implementation.
gdk_x11_register_standard_event_type ()
void gdk_x11_register_standard_event_type (GdkDisplay *display,gint event_base,gint n_events);
Registers interest in receiving extension events with type codes
between event_base
and event_base + n_events - 1.
The registered events must have the window field in the same place
as core X events (this is not the case for e.g. XKB extension events).
GDK may register the events of some X extensions on its own.
This function should only be needed in unusual circumstances, e.g. when filtering XInput extension events on the root window.
Parameters
display |
a GdkDisplay. |
[type GdkX11Display] |
event_base |
first event type code to register |
|
n_events |
number of event type codes to register |
gdk_x11_screen_get_screen_number ()
int
gdk_x11_screen_get_screen_number (GdkX11Screen *screen);
Returns the index of a GdkX11Screen.
gdk_x11_screen_get_xscreen ()
Screen *
gdk_x11_screen_get_xscreen (GdkX11Screen *screen);
Returns the screen of a GdkX11Screen.
gdk_x11_screen_get_window_manager_name ()
const char *
gdk_x11_screen_get_window_manager_name
(GdkX11Screen *screen);
Returns the name of the window manager for screen
.
gdk_x11_screen_get_monitor_output ()
XID gdk_x11_screen_get_monitor_output (GdkX11Screen *screen,gint monitor_num);
Gets the XID of the specified output/monitor. If the X server does not support version 1.2 of the RANDR extension, 0 is returned.
gdk_x11_screen_lookup_visual ()
GdkX11Visual * gdk_x11_screen_lookup_visual (GdkX11Screen *screen,VisualID xvisualid);
Looks up the GdkVisual for a particular screen and X Visual ID.
gdk_x11_screen_supports_net_wm_hint ()
gboolean gdk_x11_screen_supports_net_wm_hint (GdkX11Screen *screen,GdkAtom property);
This function is specific to the X11 backend of GDK, and indicates whether the window manager supports a certain hint from the Extended Window Manager Hints specification.
When using this function, keep in mind that the window manager
can change over time; so you shouldn’t use this function in
a way that impacts persistent application state. A common bug
is that your application can start up before the window manager
does when the user logs in, and before the window manager starts
gdk_x11_screen_supports_net_wm_hint() will return FALSE for every property.
You can monitor the window_manager_changed signal on GdkX11Screen to detect
a window manager change.
gdk_x11_screen_get_number_of_desktops ()
guint32
gdk_x11_screen_get_number_of_desktops (GdkX11Screen *screen);
Returns the number of workspaces for screen
when running under a
window manager that supports multiple workspaces, as described
in the
Extended Window Manager Hints specification.
gdk_x11_screen_get_current_desktop ()
guint32
gdk_x11_screen_get_current_desktop (GdkX11Screen *screen);
Returns the current workspace for screen
when running under a
window manager that supports multiple workspaces, as described
in the
Extended Window Manager Hints specification.
gdk_x11_surface_lookup_for_display ()
GdkSurface * gdk_x11_surface_lookup_for_display (GdkDisplay *display,Window window);
Looks up the GdkSurface that wraps the given native window handle.
Parameters
display |
the GdkDisplay corresponding to the window handle. |
[type GdkX11Display] |
window |
an Xlib Window |
Returns
the GdkSurface wrapper for the native
window, or NULL if there is none.
[transfer none][type GdkX11Surface]
gdk_x11_surface_get_xid ()
Window
gdk_x11_surface_get_xid (GdkSurface *surface);
Returns the X resource (surface) belonging to a GdkSurface.
gdk_x11_surface_set_theme_variant ()
void gdk_x11_surface_set_theme_variant (GdkSurface *surface,const char *variant);
GTK+ applications can request a dark theme variant. In order to make other applications - namely window managers using GTK+ for themeing - aware of this choice, GTK+ uses this function to export the requested theme variant as _GTK_THEME_VARIANT property on toplevel surfaces.
Note that this property is automatically updated by GTK+, so this function should only be used by applications which do not use GTK+ to create toplevel surfaces.
gdk_x11_surface_set_user_time ()
void gdk_x11_surface_set_user_time (GdkSurface *surface,guint32 timestamp);
The application can use this call to update the _NET_WM_USER_TIME property on a toplevel surface. This property stores an Xserver time which represents the time of the last user input event received for this surface. This property may be used by the window manager to alter the focus, stacking, and/or placement behavior of surfaces when they are mapped depending on whether the new surface was created by a user action or is a "pop-up" surface activated by a timer or some other event.
Note that this property is automatically updated by GDK, so this function should only be used by applications which handle input events bypassing GDK.
Parameters
surface |
A toplevel GdkSurface. |
[type GdkX11Surface] |
timestamp |
An XServer timestamp to which the property should be set |
gdk_x11_surface_move_to_current_desktop ()
void
gdk_x11_surface_move_to_current_desktop
(GdkSurface *surface);
Moves the surface to the correct workspace when running under a window manager that supports multiple workspaces, as described in the Extended Window Manager Hints specification. Will not do anything if the surface is already on all workspaces.
gdk_x11_surface_move_to_desktop ()
void gdk_x11_surface_move_to_desktop (GdkSurface *surface,guint32 desktop);
Moves the surface to the given workspace when running unde a window manager that supports multiple workspaces, as described in the Extended Window Manager Hints specification.
Parameters
surface |
a GdkSurface. |
[type GdkX11Surface] |
desktop |
the number of the workspace to move the surface to |
gdk_x11_surface_get_desktop ()
guint32
gdk_x11_surface_get_desktop (GdkSurface *surface);
Gets the number of the workspace surface
is on.
gdk_x11_surface_set_utf8_property ()
void gdk_x11_surface_set_utf8_property (GdkSurface *surface,const gchar *name,const gchar *value);
This function modifies or removes an arbitrary X11 window
property of type UTF8_STRING. If the given surface
is
not a toplevel surface, it is ignored.
Parameters
surface |
a GdkSurface. |
[type GdkX11Surface] |
name |
Property name, will be interned as an X atom |
|
value |
Property value, or |
[allow-none] |
gdk_x11_surface_set_frame_sync_enabled ()
void gdk_x11_surface_set_frame_sync_enabled (GdkSurface *surface,gboolean frame_sync_enabled);
This function can be used to disable frame synchronization for a surface. Normally frame synchronziation will be enabled or disabled based on whether the system has a compositor that supports frame synchronization, but if the surface is not directly managed by the window manager, then frame synchronziation may need to be disabled. This is the case for a surface embedded via the XEMBED protocol.
Parameters
surface |
a native GdkSurface. |
[type GdkX11Surface] |
frame_sync_enabled |
whether frame-synchronization should be enabled |
gdk_x11_keymap_get_group_for_state ()
gint gdk_x11_keymap_get_group_for_state (GdkKeymap *keymap,guint state);
Extracts the group from the state field sent in an X Key event. This is only needed for code processing raw X events, since GdkEventKey directly includes an is_modifier field.
gdk_x11_keymap_key_is_modifier ()
gboolean gdk_x11_keymap_key_is_modifier (GdkKeymap *keymap,guint keycode);
Determines whether a particular key code represents a key that is a modifier. That is, it’s a key that normally just affects the keyboard state and the behavior of other keys rather than producing a direct effect itself. This is only needed for code processing raw X events, since GdkEventKey directly includes an is_modifier field.
gdk_x11_visual_get_xvisual ()
Visual *
gdk_x11_visual_get_xvisual (GdkX11Visual *visual);
Returns the X visual belonging to a GdkVisual.
gdk_x11_atom_to_xatom_for_display ()
Atom gdk_x11_atom_to_xatom_for_display (GdkDisplay *display,GdkAtom atom);
Converts from a GdkAtom to the X atom for a GdkDisplay
with the same string value. The special value NULL
is converted to None.
gdk_x11_xatom_to_atom_for_display ()
GdkAtom gdk_x11_xatom_to_atom_for_display (GdkDisplay *display,Atom xatom);
Convert from an X atom for a GdkDisplay to the corresponding GdkAtom.
gdk_x11_get_xatom_by_name_for_display ()
Atom gdk_x11_get_xatom_by_name_for_display (GdkDisplay *display,const gchar *atom_name);
Returns the X atom for a GdkDisplay corresponding to atom_name
.
This function caches the result, so if called repeatedly it is much
faster than XInternAtom(), which is a round trip to the server each time.
gdk_x11_get_xatom_name_for_display ()
const gchar * gdk_x11_get_xatom_name_for_display (GdkDisplay *display,Atom xatom);
Returns the name of an X atom for its display. This
function is meant mainly for debugging, so for convenience, unlike
XAtomName() and the result doesn’t need to
be freed.
gdk_x11_set_sm_client_id ()
void
gdk_x11_set_sm_client_id (const gchar *sm_client_id);
Sets the SM_CLIENT_ID property on the application’s leader window so that
the window manager can save the application’s state using the X11R6 ICCCM
session management protocol.
See the X Session Management Library documentation for more information on session management and the Inter-Client Communication Conventions Manual
gdk_x11_display_text_property_to_text_list ()
gint gdk_x11_display_text_property_to_text_list (GdkDisplay *display,GdkAtom encoding,gint format,const guchar *text,gint length,gchar ***list);
Convert a text string from the encoding as it is stored in a property into an array of strings in the encoding of the current locale. (The elements of the array represent the nul-separated elements of the original text string.)
Parameters
display |
The GdkDisplay where the encoding is defined. |
[type GdkX11Display] |
encoding |
an atom representing the encoding. The most common values for this are STRING, or COMPOUND_TEXT. This is value used as the type for the property |
|
format |
the format of the property |
|
text |
The text data |
|
length |
The number of items to transform |
|
list |
location to store an array of strings in
the encoding of the current locale. This array should be
freed using |
gdk_x11_free_text_list ()
void
gdk_x11_free_text_list (gchar **list);
Frees the array of strings created by
gdk_x11_display_text_property_to_text_list().
Parameters
list |
the value stored in the |
gdk_x11_display_string_to_compound_text ()
gint gdk_x11_display_string_to_compound_text (GdkDisplay *display,const gchar *str,GdkAtom *encoding,gint *format,guchar **ctext,gint *length);
Convert a string from the encoding of the current locale into a form suitable for storing in a window property.
Parameters
display |
the GdkDisplay where the encoding is defined. |
[type GdkX11Display] |
str |
a nul-terminated string |
|
encoding |
location to store the encoding atom (to be used as the type for the property). |
[out][transfer none] |
format |
location to store the format of the property. |
[out] |
ctext |
location to store newly allocated data for the property. |
[out][array length=length] |
length |
the length of |
gdk_x11_display_utf8_to_compound_text ()
gboolean gdk_x11_display_utf8_to_compound_text (GdkDisplay *display,const gchar *str,GdkAtom *encoding,gint *format,guchar **ctext,gint *length);
Converts from UTF-8 to compound text.
Parameters
display |
a GdkDisplay. |
[type GdkX11Display] |
str |
a UTF-8 string |
|
encoding |
location to store resulting encoding. |
[out] |
format |
location to store format of the result. |
[out] |
ctext |
location to store the data of the result. |
[out][array length=length] |
length |
location to store the length of the data
stored in |
gdk_x11_free_compound_text ()
void
gdk_x11_free_compound_text (guchar *ctext);
Frees the data returned from gdk_x11_display_string_to_compound_text().
Parameters
ctext |
The pointer stored in |
|
 |
|
 |
A
NULL is OK, both for passing and for returning.
Parameter points to an array of items.
C
This parameter is a 'user_data', for callbacks; many bindings can pass NULL here.
This symbol is a constructor, not a static method.
E
Generics and defining elements of containers and arrays.
I
Parameter for input and for returning results. Default is transfer full.
N
NULL must not be passed as the value in, out, in-out; or as a return value.
NULL may be passed as the value in, out, in-out; or as a return value.
O
NULL may be passed instead of a pointer to a location.
Parameter for returning results. Default is transfer full.
Out parameter, where caller must allocate storage.
P
An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways.
R
Rename the original symbol's name to SYMBOL.
S
The callback is valid until first called.
The callback is valid only during the call to the method.
Exposed in C code, not necessarily available in other languages.
T
Free data container after the code is done.
Free data after the code is done.
Don't free data after the code is done.
Override the parsed C type with given type.
| Top | |
|
|
|
Functions
| void | (*GdkContentSerializeFunc) () |
| const char * | gdk_content_serializer_get_mime_type () |
| GType | gdk_content_serializer_get_gtype () |
| const GValue * | gdk_content_serializer_get_value () |
| GOutputStream * | gdk_content_serializer_get_output_stream () |
| int | gdk_content_serializer_get_priority () |
| GCancellable * | gdk_content_serializer_get_cancellable () |
| gpointer | gdk_content_serializer_get_user_data () |
| void | gdk_content_serializer_set_task_data () |
| gpointer | gdk_content_serializer_get_task_data () |
| void | gdk_content_serializer_return_success () |
| void | gdk_content_serializer_return_error () |
| void | gdk_content_register_serializer () |
| void | gdk_content_serialize_async () |
| gboolean | gdk_content_serialize_finish () |
Description
A GdkContentSerializer is used to serialize content for inter-application data transfers.
Functions
GdkContentSerializeFunc ()
void
(*GdkContentSerializeFunc) (GdkContentSerializer *serializer);
The type of a function that can be registered with gdk_content_register_serializer().
When the function gets called to operate on content, it can call functions on the
serializer
object to obtain the mime type, output stream, user data, etc. for its
operation.
gdk_content_serializer_get_mime_type ()
const char *
gdk_content_serializer_get_mime_type (GdkContentSerializer *serializer);
Gets the mime type to serialize to.
gdk_content_serializer_get_gtype ()
GType
gdk_content_serializer_get_gtype (GdkContentSerializer *serializer);
Gets the GType to of the object to serialize.
gdk_content_serializer_get_value ()
const GValue *
gdk_content_serializer_get_value (GdkContentSerializer *serializer);
Gets the GValue to read the object to serialize from.
gdk_content_serializer_get_output_stream ()
GOutputStream *
gdk_content_serializer_get_output_stream
(GdkContentSerializer *serializer);
Gets the output stream that was passed to gdk_content_serialize_async().
gdk_content_serializer_get_priority ()
int
gdk_content_serializer_get_priority (GdkContentSerializer *serializer);
Gets the io priority that was passed to gdk_content_serialize_async().
gdk_content_serializer_get_cancellable ()
GCancellable *
gdk_content_serializer_get_cancellable
(GdkContentSerializer *serializer);
Gets the cancellable that was passed to gdk_content_serialize_async().
gdk_content_serializer_get_user_data ()
gpointer
gdk_content_serializer_get_user_data (GdkContentSerializer *serializer);
Gets the user data that was passed when the serializer was registered.
gdk_content_serializer_set_task_data ()
void gdk_content_serializer_set_task_data (GdkContentSerializer *serializer,gpointer data,GDestroyNotify notify);
Associate data with the current serialization operation.
gdk_content_serializer_get_task_data ()
gpointer
gdk_content_serializer_get_task_data (GdkContentSerializer *serializer);
Gets the data that was associated with serializer
via gdk_content_serializer_set_task_data().
gdk_content_serializer_return_success ()
void
gdk_content_serializer_return_success (GdkContentSerializer *serializer);
Indicate that the serialization has been successfully completed.
gdk_content_serializer_return_error ()
void gdk_content_serializer_return_error (GdkContentSerializer *serializer,GError *error);
Indicate that the serialization has ended with an error.
This function consumes error
.
gdk_content_register_serializer ()
void gdk_content_register_serializer (GType type,const char *mime_type,GdkContentSerializeFunc serialize,gpointer data,GDestroyNotify notify);
Registers a function to convert objects of the given type
to
a serialized representation with the given mime type.
gdk_content_serialize_async ()
void gdk_content_serialize_async (GOutputStream *stream,const char *mime_type,const GValue *value,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Serialize content and write it to the given output stream, asynchronously.
When the operation is finished, callback
will be called. You can then
call gdk_content_serialize_finish() to get the result of the operation.
Parameters
stream |
a GOutputStream to write the serialized content to |
|
mime_type |
the mime type to serialize to |
|
value |
the content to serialize |
|
io_priority |
the io priority of the operation |
|
cancellable |
optional GCancellable object. |
[nullable] |
callback |
callback to call when the operation is done. |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
| Top | |
|
|
|
Functions
| GdkDisplay * | gdk_monitor_get_display () |
| void | gdk_monitor_get_geometry () |
| void | gdk_monitor_get_workarea () |
| int | gdk_monitor_get_width_mm () |
| int | gdk_monitor_get_height_mm () |
| const char * | gdk_monitor_get_manufacturer () |
| const char * | gdk_monitor_get_model () |
| int | gdk_monitor_get_scale_factor () |
| int | gdk_monitor_get_refresh_rate () |
| GdkSubpixelLayout | gdk_monitor_get_subpixel_layout () |
| gboolean | gdk_monitor_is_primary () |
| gboolean | gdk_monitor_is_valid () |
Properties
| GdkDisplay * | display | Read / Write / Construct Only |
| GdkRectangle * | geometry | Read |
| gint | height-mm | Read |
| gchar * | manufacturer | Read |
| gchar * | model | Read |
| gint | refresh-rate | Read |
| gint | scale-factor | Read |
| GdkSubpixelLayout | subpixel-layout | Read |
| gboolean | valid | Read |
| gint | width-mm | Read |
| GdkRectangle * | workarea | Read |
Description
GdkMonitor objects represent the individual outputs that are
associated with a GdkDisplay. GdkDisplay has APIs to enumerate
monitors with gdk_display_get_n_monitors() and gdk_display_get_monitor(), and
to find particular monitors with gdk_display_get_primary_monitor() or
gdk_display_get_monitor_at_surface().
Functions
gdk_monitor_get_display ()
GdkDisplay *
gdk_monitor_get_display (GdkMonitor *monitor);
Gets the display that this monitor belongs to.
gdk_monitor_get_geometry ()
void gdk_monitor_get_geometry (GdkMonitor *monitor,GdkRectangle *geometry);
Retrieves the size and position of an individual monitor within the
display coordinate space. The returned geometry is in ”application pixels”,
not in ”device pixels” (see gdk_monitor_get_scale_factor()).
gdk_monitor_get_workarea ()
void gdk_monitor_get_workarea (GdkMonitor *monitor,GdkRectangle *workarea);
Retrieves the size and position of the “work area” on a monitor
within the display coordinate space. The returned geometry is in
”application pixels”, not in ”device pixels” (see
gdk_monitor_get_scale_factor()).
The work area should be considered when positioning menus and similar popups, to avoid placing them below panels, docks or other desktop components.
Note that not all backends may have a concept of workarea. This function will return the monitor geometry if a workarea is not available, or does not apply.
gdk_monitor_get_width_mm ()
int
gdk_monitor_get_width_mm (GdkMonitor *monitor);
Gets the width in millimeters of the monitor.
gdk_monitor_get_height_mm ()
int
gdk_monitor_get_height_mm (GdkMonitor *monitor);
Gets the height in millimeters of the monitor.
gdk_monitor_get_manufacturer ()
const char *
gdk_monitor_get_manufacturer (GdkMonitor *monitor);
Gets the name of the monitor's manufacturer, if available.
gdk_monitor_get_model ()
const char *
gdk_monitor_get_model (GdkMonitor *monitor);
Gets the a string identifying the monitor model, if available.
gdk_monitor_get_scale_factor ()
int
gdk_monitor_get_scale_factor (GdkMonitor *monitor);
Gets the internal scale factor that maps from monitor coordinates to the actual device pixels. On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2).
This can be used if you want to create pixel based data for a
particular monitor, but most of the time you’re drawing to a surface
where it is better to use gdk_surface_get_scale_factor() instead.
gdk_monitor_get_refresh_rate ()
int
gdk_monitor_get_refresh_rate (GdkMonitor *monitor);
Gets the refresh rate of the monitor, if available.
The value is in milli-Hertz, so a refresh rate of 60Hz is returned as 60000.
gdk_monitor_get_subpixel_layout ()
GdkSubpixelLayout
gdk_monitor_get_subpixel_layout (GdkMonitor *monitor);
Gets information about the layout of red, green and blue primaries for each pixel in this monitor, if available.
gdk_monitor_is_primary ()
gboolean
gdk_monitor_is_primary (GdkMonitor *monitor);
Gets whether this monitor should be considered primary
(see gdk_display_get_primary_monitor()).
gdk_monitor_is_valid ()
gboolean
gdk_monitor_is_valid (GdkMonitor *monitor);
Returns TRUE if the monitor
object corresponds to a
physical monitor. The monitor
becomes invalid when the
physical monitor is unplugged or removed.
Types and Values
GdkMonitor
typedef struct _GdkMonitor GdkMonitor;
The GdkMonitor struct contains only private fields and should not be accessed directly.
enum GdkSubpixelLayout
This enumeration describes how the red, green and blue components of physical pixels on an output device are laid out.
Property Details
The “display” property
“display” GdkDisplay *
The display of the monitor.
Flags: Read / Write / Construct Only
The “height-mm” property
“height-mm” gint
The height of the monitor, in millimeters.
Flags: Read
Allowed values: >= 0
Default value: 0
The “manufacturer” property
“manufacturer” gchar *
The manufacturer name.
Flags: Read
Default value: NULL
The “refresh-rate” property
“refresh-rate” gint
The refresh rate, in millihertz.
Flags: Read
Allowed values: >= 0
Default value: 0
The “scale-factor” property
“scale-factor” gint
The scale factor.
Flags: Read
Allowed values: >= 0
Default value: 1
The “subpixel-layout” property
“subpixel-layout” GdkSubpixelLayout
The subpixel layout.
Flags: Read
Default value: GDK_SUBPIXEL_LAYOUT_UNKNOWN
The “valid” property
“valid” gboolean
Whether the monitor is still valid.
Flags: Read
Default value: TRUE
The “width-mm” property
“width-mm” gint
The width of the monitor, in millimeters.
Flags: Read
Allowed values: >= 0
Default value: 0
Signal Details
The “invalidate” signal
void user_function (GdkMonitor *monitor, gpointer user_data)
The ::invalidate signal gets emitted when the output represented
by monitor
gets disconnected.
Parameters
monitor |
the object on which this signal was emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
| Top | |
|
|
|
Functions
| VkDevice | gdk_vulkan_context_get_device () |
| uint32_t | gdk_vulkan_context_get_draw_index () |
| VkSemaphore | gdk_vulkan_context_get_draw_semaphore () |
| VkImage | gdk_vulkan_context_get_image () |
| VkFormat | gdk_vulkan_context_get_image_format () |
| VkInstance | gdk_vulkan_context_get_instance () |
| uint32_t | gdk_vulkan_context_get_n_images () |
| VkPhysicalDevice | gdk_vulkan_context_get_physical_device () |
| VkQueue | gdk_vulkan_context_get_queue () |
| uint32_t | gdk_vulkan_context_get_queue_family_index () |
Description
GdkVulkanContext is an object representing the platform-specific Vulkan draw context.
GdkVulkanContexts are created for a GdkSurface using
gdk_surface_create_vulkan_context(), and the context will match the
the characteristics of the surface.
Support for GdkVulkanContext is platform-specific, context creation
can fail, returning NULL context.
Functions
gdk_vulkan_context_get_device ()
VkDevice
gdk_vulkan_context_get_device (GdkVulkanContext *context);
Gets the Vulkan device that this context is using.
gdk_vulkan_context_get_draw_index ()
uint32_t
gdk_vulkan_context_get_draw_index (GdkVulkanContext *context);
Gets the index of the image that is currently being drawn.
This function can only be used between gdk_draw_context_begin_frame() and
gdk_draw_context_end_frame() calls.
gdk_vulkan_context_get_draw_semaphore ()
VkSemaphore
gdk_vulkan_context_get_draw_semaphore (GdkVulkanContext *context);
Gets the Vulkan semaphore that protects access to the image that is currently being drawn.
This function can only be used between gdk_draw_context_begin_frame() and
gdk_draw_context_end_frame() calls.
gdk_vulkan_context_get_image ()
VkImage gdk_vulkan_context_get_image (GdkVulkanContext *context,guint id);
Gets the image with index id
that this context is using.
gdk_vulkan_context_get_image_format ()
VkFormat
gdk_vulkan_context_get_image_format (GdkVulkanContext *context);
Gets the image format that this context is using.
gdk_vulkan_context_get_instance ()
VkInstance
gdk_vulkan_context_get_instance (GdkVulkanContext *context);
Gets the Vulkan instance that is associated with context
.
gdk_vulkan_context_get_n_images ()
uint32_t
gdk_vulkan_context_get_n_images (GdkVulkanContext *context);
Gets the number of images that this context is using in its swap chain.
gdk_vulkan_context_get_physical_device ()
VkPhysicalDevice
gdk_vulkan_context_get_physical_device
(GdkVulkanContext *context);
Gets the Vulkan physical device that this context is using.
gdk_vulkan_context_get_queue ()
VkQueue
gdk_vulkan_context_get_queue (GdkVulkanContext *context);
Gets the Vulkan queue that this context is using.
gdk_vulkan_context_get_queue_family_index ()
uint32_t
gdk_vulkan_context_get_queue_family_index
(GdkVulkanContext *context);
Gets the family index for the queue that this context is using.
See vkGetPhysicalDeviceQueueFamilyProperties().
Types and Values
GdkVulkanContext
typedef struct _GdkVulkanContext GdkVulkanContext;
The GdkVulkanContext struct contains only private fields and should not be accessed directly.
Signal Details
The “images-updated” signal
void user_function (GdkVulkanContext *context, gpointer user_data)
This signal is emitted when the images managed by this context have changed. Usually this means that the swapchain had to be recreated, for example in response to a change of the surface size.
Parameters
context |
the object on which the signal is emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
| Top | |
|
|
|
Functions
| GdkRGBA * | gdk_rgba_copy () |
| void | gdk_rgba_free () |
| gboolean | gdk_rgba_is_clear () |
| gboolean | gdk_rgba_is_opaque () |
| gboolean | gdk_rgba_parse () |
| gboolean | gdk_rgba_equal () |
| guint | gdk_rgba_hash () |
| gchar * | gdk_rgba_to_string () |
Description
GdkRGBA is a convenient way to pass rgba colors around. It’s based on cairo’s way to deal with colors and mirrors its behavior. All values are in the range from 0.0 to 1.0 inclusive. So the color (0.0, 0.0, 0.0, 0.0) represents transparent black and (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped to this range when drawing.
Functions
gdk_rgba_copy ()
GdkRGBA *
gdk_rgba_copy (const GdkRGBA *rgba);
Makes a copy of a GdkRGBA.
The result must be freed through gdk_rgba_free().
gdk_rgba_is_clear ()
gboolean
gdk_rgba_is_clear (const GdkRGBA *rgba);
Checks if an rgba
value is transparent. That is, drawing with the value
would not produce any change.
gdk_rgba_is_opaque ()
gboolean
gdk_rgba_is_opaque (const GdkRGBA *rgba);
Checks if an rgba
value is opaque. That is, drawing with the value
will not retain any results from previous contents.
gdk_rgba_parse ()
gboolean gdk_rgba_parse (GdkRGBA *rgba,const gchar *spec);
Parses a textual representation of a color, filling in
the red
, green
, blue
and alpha
fields of the rgba
GdkRGBA.
The string can be either one of:
A standard name (Taken from the X11 rgb.txt file).
A hexadecimal value in the form “#rgb”, “#rrggbb”, “#rrrgggbbb” or ”#rrrrggggbbbb”
A RGB color in the form “rgb(r,g,b)” (In this case the color will have full opacity)
A RGBA color in the form “rgba(r,g,b,a)”
Where “r”, “g”, “b” and “a” are respectively the red, green, blue and alpha color values. In the last two cases, “r”, “g”, and “b” are either integers in the range 0 to 255 or percentage values in the range 0% to 100%, and a is a floating point value in the range 0 to 1.
gdk_rgba_equal ()
gboolean gdk_rgba_equal (gconstpointer p1,gconstpointer p2);
Compares two RGBA colors.
gdk_rgba_hash ()
guint
gdk_rgba_hash (gconstpointer p);
A hash function suitable for using for a hash table that stores GdkRGBAs.
gdk_rgba_to_string ()
gchar *
gdk_rgba_to_string (const GdkRGBA *rgba);
Returns a textual specification of rgba
in the form
rgb(r,g,b) or
rgba(r g,b,a),
where “r”, “g”, “b” and “a” represent the red, green,
blue and alpha values respectively. “r”, “g”, and “b” are
represented as integers in the range 0 to 255, and “a”
is represented as a floating point value in the range 0 to 1.
These string forms are string forms that are supported by
the CSS3 colors module, and can be parsed by gdk_rgba_parse().
Note that this string representation may lose some precision, since “r”, “g” and “b” are represented as 8-bit integers. If this is a concern, you should use a different representation.
Types and Values
GdkRGBA
typedef struct {
gdouble red;
gdouble green;
gdouble blue;
gdouble alpha;
} GdkRGBA;
A GdkRGBA is used to represent a (possibly translucent) color, in a way that is compatible with cairo’s notion of color.
| Top | |
|
|
|
Description
The purpose of the GdkDisplayManager singleton object is to offer notification when displays appear or disappear or the default display changes.
You can use gdk_display_manager_get() to obtain the GdkDisplayManager
singleton, but that should be rarely necessary. Typically, initializing
GTK opens a display that you can work with without ever accessing the
GdkDisplayManager.
The GDK library can be built with support for multiple backends. The GdkDisplayManager object determines which backend is used at runtime.
When writing backend-specific code that is supposed to work with
multiple GDK backends, you have to consider both compile time and
runtime. At compile time, use the GDK_WINDOWING_X11, GDK_WINDOWING_WIN32
macros, etc. to find out which backends are present in the GDK library
you are building your application against. At runtime, use type-check
macros like GDK_IS_X11_DISPLAY() to find out which backend is in use:
Backend-specific code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
#ifdef GDK_WINDOWING_X11 if (GDK_IS_X11_DISPLAY (display)) { // make X11-specific calls here } else #endif #ifdef GDK_WINDOWING_QUARTZ if (GDK_IS_QUARTZ_DISPLAY (display)) { // make Quartz-specific calls here } else #endif g_error ("Unsupported GDK backend"); |
Functions
gdk_display_manager_get ()
GdkDisplayManager *
gdk_display_manager_get (void);
Gets the singleton GdkDisplayManager object.
When called for the first time, this function consults the
GDK_BACKEND environment variable to find out which
of the supported GDK backends to use (in case GDK has been compiled
with multiple backends). Applications can use gdk_set_allowed_backends()
to limit what backends can be used.
Returns
The global GdkDisplayManager singleton;
gdk_parse_args(), gdk_init(), or gdk_init_check() must have
been called first.
[transfer none]
gdk_display_manager_get_default_display ()
GdkDisplay *
gdk_display_manager_get_default_display
(GdkDisplayManager *manager);
Gets the default GdkDisplay.
gdk_display_manager_set_default_display ()
void gdk_display_manager_set_default_display (GdkDisplayManager *manager,GdkDisplay *display);
Sets display
as the default display.
gdk_display_manager_list_displays ()
GSList *
gdk_display_manager_list_displays (GdkDisplayManager *manager);
List all currently open displays.
Returns
a newly
allocated GSList of GdkDisplay objects. Free with g_slist_free()
when you are done with it.
[transfer container][element-type GdkDisplay]
gdk_display_manager_open_display ()
GdkDisplay * gdk_display_manager_open_display (GdkDisplayManager *manager,const gchar *name);
Opens a display.
gdk_set_allowed_backends ()
void
gdk_set_allowed_backends (const gchar *backends);
Sets a list of backends that GDK should try to use.
This can be be useful if your application does not work with certain GDK backends.
By default, GDK tries all included backends.
For example,
1 |
gdk_set_allowed_backends ("wayland,quartz,*"); |
instructs GDK to try the Wayland backend first, followed by the Quartz backend, and then all others.
If the GDK_BACKEND environment variable
is set, it determines what backends are tried in what
order, while still respecting the set of allowed backends
that are specified by this function.
The possible backend names are x11, win32, quartz, broadway, wayland. You can also include a * in the list to try all remaining backends.
This call must happen prior to gdk_display_open(),
gtk_init(), or gtk_init_check()
in order to take effect.
Property Details
The “default-display” property
“default-display” GdkDisplay *
The default display for GDK.
Flags: Read / Write
Signal Details
The “display-opened” signal
void user_function (GdkDisplayManager *manager, GdkDisplay *display, gpointer user_data)
The ::display-opened signal is emitted when a display is opened.
Parameters
manager |
the object on which the signal is emitted |
|
display |
the opened display |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
| Top | |
|
|
|
Functions
Description
This section describes the GdkContentFormats structure that is used to advertise and negotiate the format of content passed between different widgets, windows or applications using for example the clipboard or drag'n'drop.
GDK supports content in 2 forms: GType and mime type. Using GTypes is meant only for in-process content transfers. Mime types are meant to be used for data passing both in-process and out-of-process. The details of how data is passed is described in the documentation of the actual implementations.
A GdkContentFormats describes a set of possible formats content can be
exchanged in. It is assumed that this set is ordered. GTypes are more
important than mime types. Order between different Gtypes or mime types
is the order they were added in, most important first. Functions that
care about order, such as gdk_content_formats_union() will describe in
their documentation how they interpret that order, though in general the
order of the first argument is considered the primary order of the result,
followed by the order of further arguments.
For debugging purposes, the function gdk_content_formats_to_string() exists.
It will print a comma-seperated formats of formats from most important to least
important.
GdkContentFormats is an immutable struct. After creation, you cannot change the types it represents. Instead, new GdkContentFormats have to be created. The GdkContentFormatsBuilder structure is meant to help in this endeavor.
Functions
gdk_intern_mime_type ()
const char *
gdk_intern_mime_type (const char *string);
Canonicalizes the given mime type and interns the result.
If string
is not a valid mime type, NULL is returned instead.
See RFC 2048 for the syntax if mime types.
gdk_content_formats_new ()
GdkContentFormats * gdk_content_formats_new (const char **mime_types,guint n_mime_types);
Creates a new GdkContentFormats from an array of mime types.
The mime types must be valid and different from each other or the behavior of the return value is undefined. If you cannot guarantee this, use GdkContentFormatsBuilder instead.
gdk_content_formats_new_for_gtype ()
GdkContentFormats *
gdk_content_formats_new_for_gtype (GType type);
Creates a new GdkContentFormats for a given GType.
gdk_content_formats_ref ()
GdkContentFormats *
gdk_content_formats_ref (GdkContentFormats *formats);
Increases the reference count of a GdkContentFormats by one.
gdk_content_formats_unref ()
void
gdk_content_formats_unref (GdkContentFormats *formats);
Decreases the reference count of a GdkContentFormats by one. If the resulting reference count is zero, frees the formats.
gdk_content_formats_print ()
void gdk_content_formats_print (GdkContentFormats *formats,GString *string);
Prints the given formats
into a string for human consumption.
This is meant for debugging and logging.
The form of the representation may change at any time and is not guranteed to stay identical.
gdk_content_formats_to_string ()
char *
gdk_content_formats_to_string (GdkContentFormats *formats);
Prints the given formats
into a human-readable string.
This is a small wrapper around gdk_content_formats_print() to help
when debugging.
gdk_content_formats_get_gtypes ()
const GType * gdk_content_formats_get_gtypes (GdkContentFormats *formats,gsize *n_gtypes);
Gets the GTypes included in formats
. Note that formats
may not
contain any GTypes, in particular when they are empty. In that
case NULL will be returned.
gdk_content_formats_get_mime_types ()
const char * const * gdk_content_formats_get_mime_types (GdkContentFormats *formats,gsize *n_mime_types);
Gets the mime types included in formats
. Note that formats
may not
contain any mime types, in particular when they are empty. In that
case NULL will be returned.
gdk_content_formats_union ()
GdkContentFormats * gdk_content_formats_union (GdkContentFormats *first,const GdkContentFormats *second);
Append all missing types from second
to first
, in the order
they had in second
.
Parameters
first |
the GdkContentFormats to merge into. |
[transfer full] |
second |
the GdkContentFormats to merge from. |
[transfer none] |
gdk_content_formats_match ()
gboolean gdk_content_formats_match (const GdkContentFormats *first,const GdkContentFormats *second);
Checks if first
and second
have any matching formats.
Parameters
first |
the primary GdkContentFormats to intersect |
|
second |
the GdkContentFormats to intersect with |
gdk_content_formats_match_gtype ()
GType gdk_content_formats_match_gtype (const GdkContentFormats *first,const GdkContentFormats *second);
Finds the first GType from first
that is also contained
in second
. If no matching GType is found, G_TYPE_INVALID
is returned.
Parameters
first |
the primary GdkContentFormats to intersect |
|
second |
the GdkContentFormats to intersect with |
gdk_content_formats_match_mime_type ()
const char * gdk_content_formats_match_mime_type (const GdkContentFormats *first,const GdkContentFormats *second);
Finds the first mime type from first
that is also contained
in second
. If no matching mime type is found, NULL is
returned.
Parameters
first |
the primary GdkContentFormats to intersect |
|
second |
the GdkContentFormats to intersect with |
gdk_content_formats_contain_gtype ()
gboolean gdk_content_formats_contain_gtype (const GdkContentFormats *formats,GType type);
Checks if a given GType is part of the given formats
.
gdk_content_formats_contain_mime_type ()
gboolean gdk_content_formats_contain_mime_type (const GdkContentFormats *formats,const char *mime_type);
Checks if a given mime type is part of the given formats
.
gdk_content_formats_union_serialize_gtypes ()
GdkContentFormats *
gdk_content_formats_union_serialize_gtypes
(GdkContentFormats *formats);
Add GTypes for the mime types in formats
for which serializers are
registered.
Return: a new GdkContentFormats
gdk_content_formats_union_deserialize_gtypes ()
GdkContentFormats *
gdk_content_formats_union_deserialize_gtypes
(GdkContentFormats *formats);
Add GTypes for mime types in formats
for which deserializers are
registered.
Return: a new GdkContentFormats
gdk_content_formats_union_serialize_mime_types ()
GdkContentFormats *
gdk_content_formats_union_serialize_mime_types
(GdkContentFormats *formats);
Add mime types for GTypes in formats
for which serializers are
registered.
Return: a new GdkContentFormats
gdk_content_formats_union_deserialize_mime_types ()
GdkContentFormats *
gdk_content_formats_union_deserialize_mime_types
(GdkContentFormats *formats);
Add mime types for GTypes in formats
for which deserializers are
registered.
Return: a new GdkContentFormats
gdk_content_formats_builder_new ()
GdkContentFormatsBuilder *
gdk_content_formats_builder_new (void);
Create a new GdkContentFormatsBuilder object. The resulting builder would create an empty GdkContentFormats. Use addition functions to add types to it.
gdk_content_formats_builder_free_to_formats ()
GdkContentFormats *
gdk_content_formats_builder_free_to_formats
(GdkContentFormatsBuilder *builder);
Creates a new GdkContentFormats from the current state of the
given builder
, and frees the builder
instance.
[skip]
gdk_content_formats_builder_add_formats ()
void gdk_content_formats_builder_add_formats (GdkContentFormatsBuilder *builder,const GdkContentFormats *formats);
Appends all formats from formats
to builder
, skipping those that
already exist.
gdk_content_formats_builder_add_gtype ()
void gdk_content_formats_builder_add_gtype (GdkContentFormatsBuilder *builder,GType type);
Appends gtype
to builder
if it has not already been added.
gdk_content_formats_builder_add_mime_type ()
void gdk_content_formats_builder_add_mime_type (GdkContentFormatsBuilder *builder,const char *mime_type);
Appends mime_type
to builder
if it has not already been added.
gdk_content_formats_builder_ref ()
GdkContentFormatsBuilder *
gdk_content_formats_builder_ref (GdkContentFormatsBuilder *builder);
Acquires a reference on the given builder
.
This function is intended primarily for bindings. GdkContentFormatsBuilder objects should not be kept around.
gdk_content_formats_builder_unref ()
void
gdk_content_formats_builder_unref (GdkContentFormatsBuilder *builder);
Releases a reference on the given builder
.
gdk_content_formats_builder_to_formats ()
GdkContentFormats *
gdk_content_formats_builder_to_formats
(GdkContentFormatsBuilder *builder);
Creates a new GdkContentFormats from the given builder
.
The given GdkContentFormatsBuilder is reset once this function returns;
you cannot call this function multiple times on the same builder
instance.
This function is intended primarily for bindings. C code should use
gdk_content_formats_builder_free_to_formats().
Types and Values
GdkContentFormats
typedef struct _GdkContentFormats GdkContentFormats;
A GdkContentFormats struct is a reference counted struct and should be treated as opaque.
GdkContentFormatsBuilder
typedef struct _GdkContentFormatsBuilder GdkContentFormatsBuilder;
A GdkContentFormatsBuilder struct is an opaque struct. It is meant to not be kept around and only be used to create new GdkContentFormats objects.
| Top | |
|
|
|
Functions
| GdkTexture * | gdk_texture_new_for_pixbuf () |
| GdkTexture * | gdk_texture_new_from_resource () |
| GdkTexture * | gdk_texture_new_from_file () |
| int | gdk_texture_get_width () |
| int | gdk_texture_get_height () |
| void | gdk_texture_download () |
| gboolean | gdk_texture_save_to_png () |
| GdkTexture * | gdk_memory_texture_new () |
| GdkTexture * | gdk_gl_texture_new () |
| void | gdk_gl_texture_release () |
Description
GdkTexture is the basic element used to refer to pixel data. It is primarily mean for pixel data that will not change over multiple frames, and will be used for a long time.
You cannot get your pixel data back once you've uploaded it.
GdkTexture is an immutable object: That means you cannot change
anything about it other than increasing the reference count via
g_object_ref().
Functions
gdk_texture_new_for_pixbuf ()
GdkTexture *
gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf);
Creates a new texture object representing the GdkPixbuf.
gdk_texture_new_from_resource ()
GdkTexture *
gdk_texture_new_from_resource (const char *resource_path);
Creates a new texture by loading an image from a resource. The file format is detected automatically.
It is a fatal error if resource_path
does not specify a valid
image resource and the program will abort if that happens.
If you are unsure about the validity of a resource, use
gdk_texture_new_from_file() to load it.
gdk_texture_new_from_file ()
GdkTexture * gdk_texture_new_from_file (GFile *file,GError **error);
Creates a new texture by loading an image from a file. The file format is
detected automatically. If NULL is returned, then error
will be set.
gdk_texture_get_width ()
int
gdk_texture_get_width (GdkTexture *texture);
Returns the width of texture
.
gdk_texture_get_height ()
int
gdk_texture_get_height (GdkTexture *texture);
Returns the height of the texture
.
gdk_texture_download ()
void gdk_texture_download (GdkTexture *texture,guchar *data,gsize stride);
Downloads the texture
into local memory. This may be
an expensive operation, as the actual texture data may
reside on a GPU or on a remote display server.
The data format of the downloaded data is equivalent to
CAIRO_FORMAT_ARGB32, so every downloaded pixel requires
4 bytes of memory.
Downloading a texture into a Cairo image surface:
1 2 3 4 5 6 7 |
surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, gdk_texture_get_width (texture), gdk_texture_get_height (texture)); gdk_texture_download (texture, cairo_image_surface_get_data (surface), cairo_image_surface_get_stride (surface)); cairo_surface_mark_dirty (surface); |
gdk_texture_save_to_png ()
gboolean gdk_texture_save_to_png (GdkTexture *texture,const char *filename);
Store the given texture
to the filename
as a PNG file.
This is a utility function intended for debugging and testing. If you want more control over formats, proper error handling or want to store to a GFile or other location, you might want to look into using the gdk-pixbuf library.
gdk_memory_texture_new ()
GdkTexture * gdk_memory_texture_new (int width,int height,GdkMemoryFormat format,GBytes *bytes,gsize stride);
Creates a new texture for a blob of image data.
The GBytes must contain stride
x height
pixels
in the given format.
gdk_gl_texture_new ()
GdkTexture * gdk_gl_texture_new (GdkGLContext *context,guint id,int width,int height,GDestroyNotify destroy,gpointer data);
Creates a new texture for an existing GL texture.
Note that the GL texture must not be modified until destroy
is called,
which will happen when the GdkTexture object is finalized, or due to
an explicit call of gdk_gl_texture_release().
gdk_gl_texture_release ()
void
gdk_gl_texture_release (GdkGLTexture *self);
Releases the GL resources held by a GdkGLTexture that
was created with gdk_gl_texture_new().
The texture contents are still available via the
gdk_texture_download() function, after this function
has been called.
Types and Values
GdkTexture
typedef struct _GdkTexture GdkTexture;
The GdkTexture structure contains only private data.
enum GdkMemoryFormat
GdkMemoryFormat describes a format that bytes can have in memory.
It describes formats by listing the contents of the memory passed to it. So GDK_MEMORY_A8R8G8B8 will be 1 byte (8 bits) of alpha, followed by a byte each of red, green and blue. It is not endian-dependent, so CAIRO_FORMAT_ARGB32 is represented by different GdkMemoryFormats on architectures with different endiannesses.
Its naming is modelled after VkFormat (see https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.htmlVkFormat for details).
Members
|
4 bytes; for blue, green, red, alpha. The color values are premultiplied with the alpha value. |
||
|
4 bytes; for alpha, red, green, blue. The color values are premultiplied with the alpha value. |
||
|
4 bytes; for blue, green, red, alpha. |
||
|
4 bytes; for alpha, red, green, blue. |
||
|
4 bytes; for red, green, blue, alpha. |
||
|
4 bytes; for alpha, blue, green, red. |
||
|
3 bytes; for red, green, blue. The data is opaque. |
||
|
3 bytes; for blue, green, red. The data is opaque. |
||
|
The number of formats. This value will change as more formats get added, so do not rely on its concrete integer. |
GDK_MEMORY_DEFAULT
#define GDK_MEMORY_DEFAULT GDK_MEMORY_B8G8R8A8_PREMULTIPLIED
This is the default memory format used by GTK and is the format
provided by gdk_texture_download(). It is equal to
CAIRO_FORMAT_ARGB32.
Be aware that unlike the GdkMemoryFormat values, this format is different for different endianness.
| Top | |
|
|
|
Functions
Properties
| GdkCursor * | cursor | Read / Write |
| GdkDisplay * | display | Read / Write / Construct Only |
| GdkFrameClock * | frame-clock | Read / Write / Construct Only |
| gboolean | mapped | Read |
| GdkSurfaceState | state | Read |
Signals
| gboolean | event | Run Last |
| void | moved-to-rect | Run First |
| gboolean | render | Run Last |
| void | size-changed | Run First |
Types and Values
| GdkSurface | |
| enum | GdkSurfaceType |
| enum | GdkSurfaceHints |
| struct | GdkGeometry |
| enum | GdkGravity |
| enum | GdkAnchorHints |
| enum | GdkSurfaceEdge |
| enum | GdkSurfaceTypeHint |
| enum | GdkSurfaceState |
| enum | GdkFullscreenMode |
| #define | GDK_PARENT_RELATIVE |
| enum | GdkModifierType |
| enum | GdkModifierIntent |
| enum | GdkWMDecoration |
| enum | GdkWMFunction |
Description
A GdkSurface is a (usually) rectangular region on the screen. It’s a low-level object, used to implement high-level objects such as GtkWidget and GtkWindow on the GTK level. A GtkWindow is a toplevel surface, the thing a user might think of as a “window” with a titlebar and so on; a GtkWindow may contain many sub-GdkSurfaces.
Functions
gdk_surface_new_toplevel ()
GdkSurface * gdk_surface_new_toplevel (GdkDisplay *display,int width,int height);
Creates a new toplevel surface. The surface will be managed by the surface manager.
[constructor]
gdk_surface_new_popup ()
GdkSurface * gdk_surface_new_popup (GdkDisplay *display,const GdkRectangle *position);
Creates a new toplevel popup surface. The surface will bypass surface management.
[constructor]
gdk_surface_new_temp ()
GdkSurface *
gdk_surface_new_temp (GdkDisplay *display);
Creates a new toplevel temporary surface. The surface will be situated off-screen and not handle output.
You most likely do not want to use this function.
[constructor]
gdk_surface_new_child ()
GdkSurface * gdk_surface_new_child (GdkSurface *parent,const GdkRectangle *position);
Creates a new client-side child surface.
[constructor]
gdk_surface_destroy ()
void
gdk_surface_destroy (GdkSurface *surface);
Destroys the window system resources associated with surface
and decrements surface
's
reference count. The window system resources for all children of surface
are also
destroyed, but the children’s reference counts are not decremented.
Note that a surface will not be destroyed automatically when its reference count reaches zero. You must call this function yourself before that happens.
gdk_surface_get_surface_type ()
GdkSurfaceType
gdk_surface_get_surface_type (GdkSurface *surface);
Gets the type of the surface. See GdkSurfaceType.
gdk_surface_get_display ()
GdkDisplay *
gdk_surface_get_display (GdkSurface *surface);
Gets the GdkDisplay associated with a GdkSurface.
gdk_surface_show ()
void
gdk_surface_show (GdkSurface *surface);
Like gdk_surface_show_unraised(), but also raises the surface to the
top of the surface stack (moves the surface to the front of the
Z-order).
This function maps a surface so it’s visible onscreen. Its opposite
is gdk_surface_hide().
When implementing a GtkWidget, you should call this function on the widget's GdkSurface as part of the “map” method.
gdk_surface_show_unraised ()
void
gdk_surface_show_unraised (GdkSurface *surface);
Shows a GdkSurface onscreen, but does not modify its stacking
order. In contrast, gdk_surface_show() will raise the surface
to the top of the surface stack.
On the X11 platform, in Xlib terms, this function calls
XMapWindow() (it also updates some internal GDK state, which means
that you can’t really use XMapWindow() directly on a GDK surface).
gdk_surface_hide ()
void
gdk_surface_hide (GdkSurface *surface);
For toplevel surfaces, withdraws them, so they will no longer be
known to the window manager; for all surfaces, unmaps them, so
they won’t be displayed. Normally done automatically as
part of gtk_widget_hide().
gdk_surface_is_destroyed ()
gboolean
gdk_surface_is_destroyed (GdkSurface *surface);
Check to see if a surface is destroyed..
gdk_surface_is_visible ()
gboolean
gdk_surface_is_visible (GdkSurface *surface);
Checks whether the surface has been mapped (with gdk_surface_show() or
gdk_surface_show_unraised()).
gdk_surface_is_viewable ()
gboolean
gdk_surface_is_viewable (GdkSurface *surface);
Check if the surface and all ancestors of the surface are mapped. (This is not necessarily "viewable" in the X sense, since we only check as far as we have GDK surface parents, not to the root surface.)
gdk_surface_is_input_only ()
gboolean
gdk_surface_is_input_only (GdkSurface *surface);
Determines whether or not the surface is an input only surface.
gdk_surface_get_state ()
GdkSurfaceState
gdk_surface_get_state (GdkSurface *surface);
Gets the bitwise OR of the currently active surface state flags, from the GdkSurfaceState enumeration.
gdk_surface_iconify ()
void
gdk_surface_iconify (GdkSurface *surface);
Asks to iconify (minimize) surface
. The window manager may choose
to ignore the request, but normally will honor it. Using
gtk_window_iconify() is preferred, if you have a GtkWindow widget.
This function only makes sense when surface
is a toplevel surface.
gdk_surface_deiconify ()
void
gdk_surface_deiconify (GdkSurface *surface);
Attempt to deiconify (unminimize) surface
. On X11 the window manager may
choose to ignore the request to deiconify. When using GTK,
use gtk_window_deiconify() instead of the GdkSurface variant. Or better yet,
you probably want to use gtk_window_present_with_time(), which raises the surface, focuses it,
unminimizes it, and puts it on the current desktop.
gdk_surface_stick ()
void
gdk_surface_stick (GdkSurface *surface);
“Pins” a surface such that it’s on all workspaces and does not scroll
with viewports, for window managers that have scrollable viewports.
(When using GtkWindow, gtk_window_stick() may be more useful.)
On the X11 platform, this function depends on window manager support, so may have no effect with many window managers. However, GDK will do the best it can to convince the window manager to stick the surface. For window managers that don’t support this operation, there’s nothing you can do to force it to happen.
gdk_surface_unstick ()
void
gdk_surface_unstick (GdkSurface *surface);
Reverse operation for gdk_surface_stick(); see gdk_surface_stick(),
and gtk_window_unstick().
gdk_surface_maximize ()
void
gdk_surface_maximize (GdkSurface *surface);
Maximizes the surface. If the surface was already maximized, then this function does nothing.
On X11, asks the window manager to maximize surface
, if the window
manager supports this operation. Not all window managers support
this, and some deliberately ignore it or don’t have a concept of
“maximized”; so you can’t rely on the maximization actually
happening. But it will happen with most standard window managers,
and GDK makes a best effort to get it to happen.
On Windows, reliably maximizes the surface.
gdk_surface_unmaximize ()
void
gdk_surface_unmaximize (GdkSurface *surface);
Unmaximizes the surface. If the surface wasn’t maximized, then this function does nothing.
On X11, asks the window manager to unmaximize surface
, if the
window manager supports this operation. Not all window managers
support this, and some deliberately ignore it or don’t have a
concept of “maximized”; so you can’t rely on the unmaximization
actually happening. But it will happen with most standard window
managers, and GDK makes a best effort to get it to happen.
On Windows, reliably unmaximizes the surface.
gdk_surface_fullscreen ()
void
gdk_surface_fullscreen (GdkSurface *surface);
Moves the surface into fullscreen mode. This means the surface covers the entire screen and is above any panels or task bars.
If the surface was already fullscreen, then this function does nothing.
On X11, asks the window manager to put surface
in a fullscreen
state, if the window manager supports this operation. Not all
window managers support this, and some deliberately ignore it or
don’t have a concept of “fullscreen”; so you can’t rely on the
fullscreenification actually happening. But it will happen with
most standard window managers, and GDK makes a best effort to get
it to happen.
gdk_surface_fullscreen_on_monitor ()
void gdk_surface_fullscreen_on_monitor (GdkSurface *surface,GdkMonitor *monitor);
Moves the surface into fullscreen mode on the given monitor. This means the surface covers the entire screen and is above any panels or task bars.
If the surface was already fullscreen, then this function does nothing.
gdk_surface_unfullscreen ()
void
gdk_surface_unfullscreen (GdkSurface *surface);
Moves the surface out of fullscreen mode. If the surface was not fullscreen, does nothing.
On X11, asks the window manager to move surface
out of the fullscreen
state, if the window manager supports this operation. Not all
window managers support this, and some deliberately ignore it or
don’t have a concept of “fullscreen”; so you can’t rely on the
unfullscreenification actually happening. But it will happen with
most standard window managers, and GDK makes a best effort to get
it to happen.
gdk_surface_get_fullscreen_mode ()
GdkFullscreenMode
gdk_surface_get_fullscreen_mode (GdkSurface *surface);
Obtains the GdkFullscreenMode of the surface
.
gdk_surface_set_fullscreen_mode ()
void gdk_surface_set_fullscreen_mode (GdkSurface *surface,GdkFullscreenMode mode);
Specifies whether the surface
should span over all monitors (in a multi-head
setup) or only the current monitor when in fullscreen mode.
The mode
argument is from the GdkFullscreenMode enumeration.
If GDK_FULLSCREEN_ON_ALL_MONITORS is specified, the fullscreen surface
will
span over all monitors of the display.
On X11, searches through the list of monitors display the ones
which delimit the 4 edges of the entire display and will ask the window
manager to span the surface
over these monitors.
If the XINERAMA extension is not available or not usable, this function has no effect.
Not all window managers support this, so you can’t rely on the fullscreen surface to span over the multiple monitors when GDK_FULLSCREEN_ON_ALL_MONITORS is specified.
gdk_surface_set_keep_above ()
void gdk_surface_set_keep_above (GdkSurface *surface,gboolean setting);
Set if surface
must be kept above other surfaces. If the
surface was already above, then this function does nothing.
On X11, asks the window manager to keep surface
above, if the window
manager supports this operation. Not all window managers support
this, and some deliberately ignore it or don’t have a concept of
“keep above”; so you can’t rely on the surface being kept above.
But it will happen with most standard window managers,
and GDK makes a best effort to get it to happen.
gdk_surface_set_keep_below ()
void gdk_surface_set_keep_below (GdkSurface *surface,gboolean setting);
Set if surface
must be kept below other surfaces. If the
surface was already below, then this function does nothing.
On X11, asks the window manager to keep surface
below, if the window
manager supports this operation. Not all window managers support
this, and some deliberately ignore it or don’t have a concept of
“keep below”; so you can’t rely on the surface being kept below.
But it will happen with most standard window managers,
and GDK makes a best effort to get it to happen.
gdk_surface_set_opacity ()
void gdk_surface_set_opacity (GdkSurface *surface,gdouble opacity);
Set surface
to render as partially transparent,
with opacity 0 being fully transparent and 1 fully opaque. (Values
of the opacity parameter are clamped to the [0,1] range.)
For toplevel surfaces this depends on support from the windowing system
that may not always be there. For instance, On X11, this works only on
X screens with a compositing manager running. On Wayland, there is no
per-surface opacity value that the compositor would apply. Instead, use
gdk_surface_set_opaque_region (surface, NULL) to tell the compositor
that the entire surface is (potentially) non-opaque, and draw your content
with alpha, or use gtk_widget_set_opacity() to set an overall opacity
for your widgets.
Support for non-toplevel surfaces was added in 3.8.
gdk_surface_set_pass_through ()
void gdk_surface_set_pass_through (GdkSurface *surface,gboolean pass_through);
Sets whether input to the surface is passed through to the surface below.
The default value of this is FALSE, which means that pointer
events that happen inside the surface are send first to the surface,
but if the event is not selected by the event mask then the event
is sent to the parent surface, and so on up the hierarchy.
If pass_through
is TRUE then such pointer events happen as if the
surface wasn't there at all, and thus will be sent first to any
surfaces below surface
. This is useful if the surface is used in a
transparent fashion. In the terminology of the web this would be called
"pointer-events: none".
Note that a surface with pass_through
TRUE can still have a subsurface
without pass through, so you can get events on a subset of a surface. And in
that cases you would get the in-between related events such as the pointer
enter/leave events on its way to the destination surface.
gdk_surface_get_pass_through ()
gboolean
gdk_surface_get_pass_through (GdkSurface *surface);
Returns whether input to the surface is passed through to the surface below.
See gdk_surface_set_pass_through() for details
gdk_surface_move ()
void gdk_surface_move (GdkSurface *surface,gint x,gint y);
Repositions a surface relative to its parent surface.
For toplevel surfaces, window managers may ignore or modify the move;
you should probably use gtk_window_move() on a GtkWindow widget
anyway, instead of using GDK functions. For child surfaces,
the move will reliably succeed.
If you’re also planning to resize the surface, use gdk_surface_move_resize()
to both move and resize simultaneously, for a nicer visual effect.
gdk_surface_resize ()
void gdk_surface_resize (GdkSurface *surface,gint width,gint height);
Resizes surface
; for toplevel surfaces, asks the window manager to resize
the surface. The window manager may not allow the resize. When using GTK,
use gtk_window_resize() instead of this low-level GDK function.
Surfaces may not be resized below 1x1.
If you’re also planning to move the surface, use gdk_surface_move_resize()
to both move and resize simultaneously, for a nicer visual effect.
gdk_surface_move_resize ()
void gdk_surface_move_resize (GdkSurface *surface,gint x,gint y,gint width,gint height);
Equivalent to calling gdk_surface_move() and gdk_surface_resize(),
except that both operations are performed at once, avoiding strange
visual effects. (i.e. the user may be able to see the surface first
move, then resize, if you don’t use gdk_surface_move_resize().)
gdk_surface_move_to_rect ()
void gdk_surface_move_to_rect (GdkSurface *surface,const GdkRectangle *rect,GdkGravity rect_anchor,GdkGravity surface_anchor,GdkAnchorHints anchor_hints,gint rect_anchor_dx,gint rect_anchor_dy);
Moves surface
to rect
, aligning their anchor points.
rect
is relative to the top-left corner of the surface that surface
is
transient for. rect_anchor
and surface_anchor
determine anchor points on
rect
and surface
to pin together. rect
's anchor point can optionally be
offset by rect_anchor_dx
and rect_anchor_dy
, which is equivalent to
offsetting the position of surface
.
anchor_hints
determines how surface
will be moved if the anchor points cause
it to move off-screen. For example, GDK_ANCHOR_FLIP_X will replace
GDK_GRAVITY_NORTH_WEST with GDK_GRAVITY_NORTH_EAST and vice versa if
surface
extends beyond the left or right edges of the monitor.
Connect to the “moved-to-rect” signal to find out how it was actually positioned.
Parameters
surface |
the GdkSurface to move |
|
rect |
the destination GdkRectangle to align |
[not nullable] |
rect_anchor |
the point on |
|
surface_anchor |
the point on |
|
anchor_hints |
positioning hints to use when limited on space |
|
rect_anchor_dx |
horizontal offset to shift |
|
rect_anchor_dy |
vertical offset to shift |
gdk_surface_has_native ()
gboolean
gdk_surface_has_native (GdkSurface *surface);
Checks whether the surface has a native surface or not.
gdk_surface_raise ()
void
gdk_surface_raise (GdkSurface *surface);
Raises surface
to the top of the Z-order (stacking order), so that
other surfaces with the same parent surface appear below surface
.
This is true whether or not the surfaces are visible.
If surface
is a toplevel, the window manager may choose to deny the
request to move the surface in the Z-order, gdk_surface_raise() only
requests the restack, does not guarantee it.
gdk_surface_lower ()
void
gdk_surface_lower (GdkSurface *surface);
Lowers surface
to the bottom of the Z-order (stacking order), so that
other surfaces with the same parent surface appear above surface
.
This is true whether or not the other surfaces are visible.
If surface
is a toplevel, the window manager may choose to deny the
request to move the surface in the Z-order, gdk_surface_lower() only
requests the restack, does not guarantee it.
Note that gdk_surface_show() raises the surface again, so don’t call this
function before gdk_surface_show(). (Try gdk_surface_show_unraised().)
gdk_surface_restack ()
void gdk_surface_restack (GdkSurface *surface,GdkSurface *sibling,gboolean above);
Changes the position of surface
in the Z-order (stacking order), so that
it is above sibling
(if above
is TRUE) or below sibling
(if above
is
FALSE).
If sibling
is NULL, then this either raises (if above
is TRUE) or
lowers the surface.
If surface
is a toplevel, the window manager may choose to deny the
request to move the surface in the Z-order, gdk_surface_restack() only
requests the restack, does not guarantee it.
Parameters
surface |
||
sibling |
a GdkSurface that is a sibling of |
[allow-none] |
above |
a boolean |
gdk_surface_focus ()
void gdk_surface_focus (GdkSurface *surface,guint32 timestamp);
Sets keyboard focus to surface
. In most cases, gtk_window_present_with_time()
should be used on a GtkWindow, rather than calling this function.
gdk_surface_register_dnd ()
void
gdk_surface_register_dnd (GdkSurface *surface);
Registers a surface as a potential drop destination.
gdk_surface_begin_resize_drag ()
void gdk_surface_begin_resize_drag (GdkSurface *surface,GdkSurfaceEdge edge,gint button,gint x,gint y,guint32 timestamp);
Begins a surface resize operation (for a toplevel surface).
This function assumes that the drag is controlled by the
client pointer device, use gdk_surface_begin_resize_drag_for_device()
to begin a drag with a different device.
Parameters
surface |
a toplevel GdkSurface |
|
edge |
the edge or corner from which the drag is started |
|
button |
the button being used to drag, or 0 for a keyboard-initiated drag |
|
x |
surface X coordinate of mouse click that began the drag |
|
y |
surface Y coordinate of mouse click that began the drag |
|
timestamp |
timestamp of mouse click that began the drag (use |
gdk_surface_begin_resize_drag_for_device ()
void gdk_surface_begin_resize_drag_for_device (GdkSurface *surface,GdkSurfaceEdge edge,GdkDevice *device,gint button,gint x,gint y,guint32 timestamp);
Begins a surface resize operation (for a toplevel surface). You might use this function to implement a “window resize grip,”
Parameters
surface |
a toplevel GdkSurface |
|
edge |
the edge or corner from which the drag is started |
|
device |
the device used for the operation |
|
button |
the button being used to drag, or 0 for a keyboard-initiated drag |
|
x |
surface X coordinate of mouse click that began the drag |
|
y |
surface Y coordinate of mouse click that began the drag |
|
timestamp |
timestamp of mouse click that began the drag (use |
gdk_surface_begin_move_drag ()
void gdk_surface_begin_move_drag (GdkSurface *surface,gint button,gint x,gint y,guint32 timestamp);
Begins a surface move operation (for a toplevel surface).
This function assumes that the drag is controlled by the
client pointer device, use gdk_surface_begin_move_drag_for_device()
to begin a drag with a different device.
Parameters
surface |
a toplevel GdkSurface |
|
button |
the button being used to drag, or 0 for a keyboard-initiated drag |
|
x |
surface X coordinate of mouse click that began the drag |
|
y |
surface Y coordinate of mouse click that began the drag |
|
timestamp |
timestamp of mouse click that began the drag |
gdk_surface_begin_move_drag_for_device ()
void gdk_surface_begin_move_drag_for_device (GdkSurface *surface,GdkDevice *device,gint button,gint x,gint y,guint32 timestamp);
Begins a surface move operation (for a toplevel surface).
Parameters
surface |
a toplevel GdkSurface |
|
device |
the device used for the operation |
|
button |
the button being used to drag, or 0 for a keyboard-initiated drag |
|
x |
surface X coordinate of mouse click that began the drag |
|
y |
surface Y coordinate of mouse click that began the drag |
|
timestamp |
timestamp of mouse click that began the drag |
gdk_surface_show_window_menu ()
gboolean gdk_surface_show_window_menu (GdkSurface *surface,GdkEvent *event);
Asks the windowing system to show the window menu. The window menu is the menu shown when right-clicking the titlebar on traditional windows managed by the window manager. This is useful for windows using client-side decorations, activating it with a right-click on the window decorations.
gdk_surface_constrain_size ()
void gdk_surface_constrain_size (GdkGeometry *geometry,GdkSurfaceHints flags,gint width,gint height,gint *new_width,gint *new_height);
Constrains a desired width and height according to a set of geometry hints (such as minimum and maximum size).
Parameters
geometry |
a GdkGeometry structure |
|
flags |
a mask indicating what portions of |
|
width |
desired width of surface |
|
height |
desired height of the surface |
|
new_width |
location to store resulting width. |
[out] |
new_height |
location to store resulting height. |
[out] |
gdk_surface_beep ()
void
gdk_surface_beep (GdkSurface *surface);
Emits a short beep associated to surface
in the appropriate
display, if supported. Otherwise, emits a short beep on
the display just as gdk_display_beep().
gdk_surface_get_scale_factor ()
gint
gdk_surface_get_scale_factor (GdkSurface *surface);
Returns the internal scale factor that maps from surface coordiantes to the actual device pixels. On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2).
A higher value means that drawing is automatically scaled up to a higher resolution, so any code doing drawing will automatically look nicer. However, if you are supplying pixel-based data the scale value can be used to determine whether to use a pixel resource with higher resolution data.
The scale of a surface may change during runtime, if this happens a configure event will be sent to the toplevel surface.
gdk_surface_set_opaque_region ()
void gdk_surface_set_opaque_region (GdkSurface *surface,cairo_region_t *region);
For optimisation purposes, compositing window managers may like to not draw obscured regions of surfaces, or turn off blending during for these regions. With RGB windows with no transparency, this is just the shape of the window, but with ARGB32 windows, the compositor does not know what regions of the window are transparent or not.
This function only works for toplevel surfaces.
GTK will update this property automatically if
the surface
background is opaque, as we know where the opaque regions
are. If your surface background is not opaque, please update this
property in your “style-updated” handler.
gdk_surface_create_gl_context ()
GdkGLContext * gdk_surface_create_gl_context (GdkSurface *surface,GError **error);
Creates a new GdkGLContext matching the framebuffer format to the visual of the GdkSurface. The context is disconnected from any particular surface or surface.
If the creation of the GdkGLContext failed, error
will be set.
Before using the returned GdkGLContext, you will need to
call gdk_gl_context_make_current() or gdk_gl_context_realize().
gdk_surface_create_vulkan_context ()
GdkVulkanContext * gdk_surface_create_vulkan_context (GdkSurface *surface,GError **error);
Creates a new GdkVulkanContext for rendering on surface
.
If the creation of the GdkVulkanContext failed, error
will be set.
gdk_surface_create_cairo_context ()
GdkCairoContext *
gdk_surface_create_cairo_context (GdkSurface *surface);
Creates a new GdkCairoContext for rendering on surface
.
gdk_surface_queue_expose ()
void
gdk_surface_queue_expose (GdkSurface *surface);
Forces an expose event for surface
to be scheduled.
If the invalid area of surface
is empty, an expose event will
still be emitted. Its invalid region will be empty.
This function is useful for implementations that track invalid regions on their own.
gdk_surface_freeze_updates ()
void
gdk_surface_freeze_updates (GdkSurface *surface);
Temporarily freezes a surface such that it won’t receive expose
events. The surface will begin receiving expose events again when
gdk_surface_thaw_updates() is called. If gdk_surface_freeze_updates()
has been called more than once, gdk_surface_thaw_updates() must be called
an equal number of times to begin processing exposes.
gdk_surface_thaw_updates ()
void
gdk_surface_thaw_updates (GdkSurface *surface);
Thaws a surface frozen with gdk_surface_freeze_updates().
gdk_surface_get_frame_clock ()
GdkFrameClock *
gdk_surface_get_frame_clock (GdkSurface *surface);
Gets the frame clock for the surface. The frame clock for a surface never changes unless the surface is reparented to a new toplevel surface.
gdk_surface_set_accept_focus ()
void gdk_surface_set_accept_focus (GdkSurface *surface,gboolean accept_focus);
Setting accept_focus
to FALSE hints the desktop environment that the
surface doesn’t want to receive input focus.
On X, it is the responsibility of the window manager to interpret this hint. ICCCM-compliant window manager usually respect it.
Parameters
surface |
a toplevel GdkSurface |
|
accept_focus |
|
gdk_surface_get_accept_focus ()
gboolean
gdk_surface_get_accept_focus (GdkSurface *surface);
Determines whether or not the desktop environment shuld be hinted that the surface does not want to receive input focus.
gdk_surface_set_focus_on_map ()
void gdk_surface_set_focus_on_map (GdkSurface *surface,gboolean focus_on_map);
Setting focus_on_map
to FALSE hints the desktop environment that the
surface doesn’t want to receive input focus when it is mapped.
focus_on_map should be turned off for surfaces that aren’t triggered
interactively (such as popups from network activity).
On X, it is the responsibility of the window manager to interpret this hint. Window managers following the freedesktop.org window manager extension specification should respect it.
Parameters
surface |
a toplevel GdkSurface |
|
focus_on_map |
|
gdk_surface_get_focus_on_map ()
gboolean
gdk_surface_get_focus_on_map (GdkSurface *surface);
Determines whether or not the desktop environment should be hinted that the surface does not want to receive input focus when it is mapped.
gdk_surface_input_shape_combine_region ()
void gdk_surface_input_shape_combine_region (GdkSurface *surface,const cairo_region_t *shape_region,gint offset_x,gint offset_y);
Like gdk_surface_shape_combine_region(), but the shape applies
only to event handling. Mouse events which happen while
the pointer position corresponds to an unset bit in the
mask will be passed on the surface below surface
.
An input shape is typically used with RGBA surfaces. The alpha channel of the surface defines which pixels are invisible and allows for nicely antialiased borders, and the input shape controls where the surface is “clickable”.
On the X11 platform, this requires version 1.1 of the shape extension.
On the Win32 platform, this functionality is not present and the function does nothing.
gdk_surface_set_child_input_shapes ()
void
gdk_surface_set_child_input_shapes (GdkSurface *surface);
Sets the input shape mask of surface
to the union of input shape masks
for all children of surface
, ignoring the input shape mask of surface
itself. Contrast with gdk_surface_merge_child_input_shapes() which includes
the input shape mask of surface
in the masks to be merged.
gdk_surface_merge_child_input_shapes ()
void
gdk_surface_merge_child_input_shapes (GdkSurface *surface);
Merges the input shape masks for any child surfaces into the
input shape mask for surface
. i.e. the union of all input masks
for surface
and its children will become the new input mask
for surface
. See gdk_surface_input_shape_combine_region().
This function is distinct from gdk_surface_set_child_input_shapes()
because it includes surface
’s input shape mask in the set of
shapes to be merged.
gdk_surface_set_title ()
void gdk_surface_set_title (GdkSurface *surface,const gchar *title);
Sets the title of a toplevel surface, to be displayed in the titlebar.
If you haven’t explicitly set the icon name for the surface
(using gdk_surface_set_icon_name()), the icon name will be set to
title
as well. title
must be in UTF-8 encoding (as with all
user-readable strings in GDK and GTK). title
may not be NULL.
gdk_surface_set_cursor ()
void gdk_surface_set_cursor (GdkSurface *surface,GdkCursor *cursor);
Sets the default mouse pointer for a GdkSurface.
Note that cursor
must be for the same display as surface
.
Use gdk_cursor_new_from_name() or gdk_cursor_new_from_texture() to
create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR.
Passing NULL for the cursor
argument to gdk_surface_set_cursor() means
that surface
will use the cursor of its parent surface. Most surfaces
should use this default.
gdk_surface_get_cursor ()
GdkCursor *
gdk_surface_get_cursor (GdkSurface *surface);
Retrieves a GdkCursor pointer for the cursor currently set on the
specified GdkSurface, or NULL. If the return value is NULL then
there is no custom cursor set on the specified surface, and it is
using the cursor for its parent surface.
Returns
a GdkCursor, or NULL. The
returned object is owned by the GdkSurface and should not be
unreferenced directly. Use gdk_surface_set_cursor() to unset the
cursor of the surface.
[nullable][transfer none]
gdk_surface_get_geometry ()
void gdk_surface_get_geometry (GdkSurface *surface,gint *x,gint *y,gint *width,gint *height);
Any of the return location arguments to this function may be NULL,
if you aren’t interested in getting the value of that field.
The X and Y coordinates returned are relative to the parent surface
of surface
, which for toplevels usually means relative to the
surface decorations (titlebar, etc.) rather than relative to the
root window (screen-size background window).
On the X11 platform, the geometry is obtained from the X server,
so reflects the latest position of surface
; this may be out-of-sync
with the position of surface
delivered in the most-recently-processed
GdkEventConfigure. gdk_surface_get_position() in contrast gets the
position from the most recent configure event.
Note: If surface
is not a toplevel, it is much better
to call gdk_surface_get_position(), gdk_surface_get_width() and
gdk_surface_get_height() instead, because it avoids the roundtrip to
the X server and because these functions support the full 32-bit
coordinate space, whereas gdk_surface_get_geometry() is restricted to
the 16-bit coordinates of X11.
Parameters
surface |
||
x |
return location for X coordinate of surface (relative to its parent). |
[out][allow-none] |
y |
return location for Y coordinate of surface (relative to its parent). |
[out][allow-none] |
width |
return location for width of surface. |
[out][allow-none] |
height |
return location for height of surface. |
[out][allow-none] |
gdk_surface_set_geometry_hints ()
void gdk_surface_set_geometry_hints (GdkSurface *surface,const GdkGeometry *geometry,GdkSurfaceHints geom_mask);
Sets the geometry hints for surface
. Hints flagged in geom_mask
are set, hints not flagged in geom_mask
are unset.
To unset all hints, use a geom_mask
of 0 and a geometry
of NULL.
This function provides hints to the surfaceing system about
acceptable sizes for a toplevel surface. The purpose of
this is to constrain user resizing, but the windowing system
will typically (but is not required to) also constrain the
current size of the surface to the provided values and
constrain programatic resizing via gdk_surface_resize() or
gdk_surface_move_resize().
Note that on X11, this effect has no effect on surfaces
of type GDK_SURFACE_TEMP since these surfaces are not resizable
by the user.
Since you can’t count on the windowing system doing the
constraints for programmatic resizes, you should generally
call gdk_surface_constrain_size() yourself to determine
appropriate sizes.
Parameters
surface |
a toplevel GdkSurface |
|
geometry |
geometry hints |
|
geom_mask |
bitmask indicating fields of |
gdk_surface_get_width ()
int
gdk_surface_get_width (GdkSurface *surface);
Returns the width of the given surface
.
On the X11 platform the returned size is the size reported in the most-recently-processed configure event, rather than the current size on the X server.
gdk_surface_get_height ()
int
gdk_surface_get_height (GdkSurface *surface);
Returns the height of the given surface
.
On the X11 platform the returned size is the size reported in the most-recently-processed configure event, rather than the current size on the X server.
gdk_surface_set_icon_list ()
void gdk_surface_set_icon_list (GdkSurface *surface,GList *surfaces);
Sets a list of icons for the surface. One of these will be used to represent the surface when it has been iconified. The icon is usually shown in an icon box or some sort of task bar. Which icon size is shown depends on the window manager. The window manager can scale the icon but setting several size icons can give better image quality since the window manager may only need to scale the icon by a small amount or not at all.
Note that some platforms don't support surface icons.
Parameters
surface |
The GdkSurface toplevel surface to set the icon of. |
|
surfaces |
A list of image surfaces, of different sizes. |
[transfer none][element-type GdkTexture] |
gdk_surface_set_modal_hint ()
void gdk_surface_set_modal_hint (GdkSurface *surface,gboolean modal);
The application can use this hint to tell the window manager that a certain surface has modal behaviour. The window manager can use this information to handle modal surfaces in a special way.
You should only use this on surfaces for which you have
previously called gdk_surface_set_transient_for()
gdk_surface_get_modal_hint ()
gboolean
gdk_surface_get_modal_hint (GdkSurface *surface);
Determines whether or not the window manager is hinted that surface
has modal behaviour.
gdk_surface_set_type_hint ()
void gdk_surface_set_type_hint (GdkSurface *surface,GdkSurfaceTypeHint hint);
The application can use this call to provide a hint to the surface manager about the functionality of a surface. The window manager can use this information when determining the decoration and behaviour of the surface.
The hint must be set before the surface is mapped.
gdk_surface_get_type_hint ()
GdkSurfaceTypeHint
gdk_surface_get_type_hint (GdkSurface *surface);
This function returns the type hint set for a surface.
gdk_surface_set_shadow_width ()
void gdk_surface_set_shadow_width (GdkSurface *surface,gint left,gint right,gint top,gint bottom);
Newer GTK windows using client-side decorations use extra geometry around their frames for effects like shadows and invisible borders. Window managers that want to maximize windows or snap to edges need to know where the extents of the actual frame lie, so that users don’t feel like windows are snapping against random invisible edges.
Note that this property is automatically updated by GTK, so this function should only be used by applications which do not use GTK to create toplevel surfaces.
gdk_surface_get_position ()
void gdk_surface_get_position (GdkSurface *surface,gint *x,gint *y);
Obtains the position of the surface as reported in the
most-recently-processed GdkEventConfigure. Contrast with
gdk_surface_get_geometry() which queries the X server for the
current surface position, regardless of which events have been
received or processed.
The position coordinates are relative to the surface’s parent surface.
gdk_surface_get_root_origin ()
void gdk_surface_get_root_origin (GdkSurface *surface,gint *x,gint *y);
Obtains the top-left corner of the window manager frame in root surface coordinates.
Parameters
surface |
a toplevel GdkSurface |
|
x |
return location for X position of surface frame. |
[out] |
y |
return location for Y position of surface frame. |
[out] |
gdk_surface_get_frame_extents ()
void gdk_surface_get_frame_extents (GdkSurface *surface,GdkRectangle *rect);
Obtains the bounding box of the surface, including window manager
titlebar/borders if any. The frame position is given in root window
coordinates. To get the position of the surface itself (rather than
the frame) in root window coordinates, use gdk_surface_get_origin().
Parameters
surface |
a toplevel GdkSurface |
|
rect |
rectangle to fill with bounding box of the surface frame. |
[out] |
gdk_surface_get_origin ()
gint gdk_surface_get_origin (GdkSurface *surface,gint *x,gint *y);
Obtains the position of a surface in root window coordinates.
(Compare with gdk_surface_get_position() and
gdk_surface_get_geometry() which return the position of a surface
relative to its parent surface.)
gdk_surface_get_root_coords ()
void gdk_surface_get_root_coords (GdkSurface *surface,gint x,gint y,gint *root_x,gint *root_y);
Obtains the position of a surface position in root
window coordinates. This is similar to
gdk_surface_get_origin() but allows you to pass
in any position in the surface, not just the origin.
gdk_surface_get_device_position ()
GdkSurface * gdk_surface_get_device_position (GdkSurface *surface,GdkDevice *device,double *x,double *y,GdkModifierType *mask);
Obtains the current device position in doubles and modifier state.
The position is given in coordinates relative to the upper left
corner of surface
.
Parameters
surface |
a GdkSurface. |
|
device |
pointer GdkDevice to query to. |
|
x |
return location for the X coordinate of |
[out][allow-none] |
y |
return location for the Y coordinate of |
[out][allow-none] |
mask |
return location for the modifier mask, or |
[out][allow-none] |
Returns
The surface underneath device
(as with gdk_device_get_surface_at_position()), or NULL if the
surface is not known to GDK.
[nullable][transfer none]
gdk_surface_get_parent ()
GdkSurface *
gdk_surface_get_parent (GdkSurface *surface);
Obtains the parent of surface
, as known to GDK. Does not query the
X server; thus this returns the parent as passed to gdk_surface_new(),
not the actual parent. This should never matter unless you’re using
Xlib calls mixed with GDK calls on the X11 platform. It may also
matter for toplevel windows, because the window manager may choose
to reparent them.
gdk_surface_get_toplevel ()
GdkSurface *
gdk_surface_get_toplevel (GdkSurface *surface);
Gets the toplevel surface that’s an ancestor of surface
.
Any surface type but GDK_SURFACE_CHILD is considered a
toplevel surface, as is a GDK_SURFACE_CHILD surface that
has a root surface as parent.
gdk_surface_get_children ()
GList *
gdk_surface_get_children (GdkSurface *surface);
Gets the list of children of surface
known to GDK.
This function only returns children created via GDK,
so for example it’s useless when used with the root window;
it only returns surfaces an application created itself.
The returned list must be freed, but the elements in the list need not be.
gdk_surface_peek_children ()
GList *
gdk_surface_peek_children (GdkSurface *surface);
Like gdk_surface_get_children(), but does not copy the list of
children, so the list does not need to be freed.
gdk_surface_set_icon_name ()
void gdk_surface_set_icon_name (GdkSurface *surface,const gchar *name);
Surfaces may have a name used while minimized, distinct from the name they display in their titlebar. Most of the time this is a bad idea from a user interface standpoint. But you can set such a name with this function, if you like.
After calling this with a non-NULL name
, calls to gdk_surface_set_title()
will not update the icon title.
Using NULL for name
unsets the icon title; further calls to
gdk_surface_set_title() will again update the icon title as well.
Note that some platforms don't support surface icons.
Parameters
surface |
a toplevel GdkSurface |
|
name |
name of surface while iconified (minimized). |
[allow-none] |
gdk_surface_set_transient_for ()
void gdk_surface_set_transient_for (GdkSurface *surface,GdkSurface *parent);
Indicates to the window manager that surface
is a transient dialog
associated with the application surface parent
. This allows the
window manager to do things like center surface
on parent
and
keep surface
above parent
.
See gtk_window_set_transient_for() if you’re using GtkWindow or
GtkDialog.
gdk_surface_set_startup_id ()
void gdk_surface_set_startup_id (GdkSurface *surface,const gchar *startup_id);
When using GTK, typically you should use gtk_window_set_startup_id()
instead of this low-level function.
gdk_surface_set_decorations ()
void gdk_surface_set_decorations (GdkSurface *surface,GdkWMDecoration decorations);
“Decorations” are the features the window manager adds to a toplevel GdkSurface.
This function sets the traditional Motif window manager hints that tell the
window manager which decorations you would like your surface to have.
Usually you should use gtk_window_set_decorated() on a GtkWindow instead of
using the GDK function directly.
The decorations
argument is the logical OR of the fields in
the GdkWMDecoration enumeration. If GDK_DECOR_ALL is included in the
mask, the other bits indicate which decorations should be turned off.
If GDK_DECOR_ALL is not included, then the other bits indicate
which decorations should be turned on.
Most window managers honor a decorations hint of 0 to disable all decorations, but very few honor all possible combinations of bits.
gdk_surface_get_decorations ()
gboolean gdk_surface_get_decorations (GdkSurface *surface,GdkWMDecoration *decorations);
Returns the decorations set on the GdkSurface with
gdk_surface_set_decorations().
Parameters
surface |
The toplevel GdkSurface to get the decorations from |
|
decorations |
The surface decorations will be written here. |
[out] |
gdk_surface_set_functions ()
void gdk_surface_set_functions (GdkSurface *surface,GdkWMFunction functions);
Sets hints about the window management functions to make available via buttons on the window frame.
On the X backend, this function sets the traditional Motif window manager hint for this purpose. However, few window managers do anything reliable or interesting with this hint. Many ignore it entirely.
The functions
argument is the logical OR of values from the
GdkWMFunction enumeration. If the bitmask includes GDK_FUNC_ALL,
then the other bits indicate which functions to disable; if
it doesn’t include GDK_FUNC_ALL, it indicates which functions to
enable.
gdk_surface_get_support_multidevice ()
gboolean
gdk_surface_get_support_multidevice (GdkSurface *surface);
Returns TRUE if the surface is aware of the existence of multiple
devices.
gdk_surface_set_support_multidevice ()
void gdk_surface_set_support_multidevice (GdkSurface *surface,gboolean support_multidevice);
This function will enable multidevice features in surface
.
Multidevice aware surfaces will need to handle properly multiple, per device enter/leave events, device grabs and grab ownerships.
Parameters
surface |
a GdkSurface. |
|
support_multidevice |
|
gdk_surface_get_device_cursor ()
GdkCursor * gdk_surface_get_device_cursor (GdkSurface *surface,GdkDevice *device);
Retrieves a GdkCursor pointer for the device
currently set on the
specified GdkSurface, or NULL. If the return value is NULL then
there is no custom cursor set on the specified surface, and it is
using the cursor for its parent surface.
Returns
a GdkCursor, or NULL. The
returned object is owned by the GdkSurface and should not be
unreferenced directly. Use gdk_surface_set_cursor() to unset the
cursor of the surface.
[nullable][transfer none]
gdk_surface_set_device_cursor ()
void gdk_surface_set_device_cursor (GdkSurface *surface,GdkDevice *device,GdkCursor *cursor);
Sets a specific GdkCursor for a given device when it gets inside surface
.
Use gdk_cursor_new_fromm_name() or gdk_cursor_new_from_texture() to create
the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR. Passing
NULL for the cursor
argument to gdk_surface_set_cursor() means that
surface
will use the cursor of its parent surface. Most surfaces should
use this default.
gdk_surface_coords_from_parent ()
void gdk_surface_coords_from_parent (GdkSurface *surface,gdouble parent_x,gdouble parent_y,gdouble *x,gdouble *y);
Transforms surface coordinates from a parent surface to a child surface.
Calling this function is equivalent to subtracting the return
values of gdk_surface_get_position() from the parent coordinates.
See also: gdk_surface_coords_to_parent()
Parameters
surface |
a child surface |
|
parent_x |
X coordinate in parent’s coordinate system |
|
parent_y |
Y coordinate in parent’s coordinate system |
|
x |
return location for X coordinate in child’s coordinate system. |
[out][allow-none] |
y |
return location for Y coordinate in child’s coordinate system. |
[out][allow-none] |
gdk_surface_coords_to_parent ()
void gdk_surface_coords_to_parent (GdkSurface *surface,gdouble x,gdouble y,gdouble *parent_x,gdouble *parent_y);
Transforms surface coordinates from a child surface to its parent
surface. Calling this function is equivalent to adding the return
values of gdk_surface_get_position() to the child coordinates.
See also: gdk_surface_coords_from_parent()
Parameters
surface |
a child surface |
|
x |
X coordinate in child’s coordinate system |
|
y |
Y coordinate in child’s coordinate system |
|
parent_x |
return location for X coordinate
in parent’s coordinate system, or |
[out][allow-none] |
parent_y |
return location for Y coordinate
in parent’s coordinate system, or |
[out][allow-none] |
Types and Values
GdkSurface
typedef struct _GdkSurface GdkSurface;
The GdkSurface struct contains only private fields and should not be accessed directly.
enum GdkSurfaceHints
Used to indicate which fields of a GdkGeometry struct should be paid
attention to. Also, the presence/absence of GDK_HINT_POS
,
GDK_HINT_USER_POS
, and GDK_HINT_USER_SIZE
is significant, though they don't
directly refer to GdkGeometry fields. GDK_HINT_USER_POS
will be set
automatically by GtkWindow if you call gtk_window_move().
GDK_HINT_USER_POS
and GDK_HINT_USER_SIZE
should be set if the user
specified a size/position using a --geometry command-line argument;
gtk_window_parse_geometry() automatically sets these flags.
Members
|
indicates that the program has positioned the surface |
||
|
min size fields are set |
||
|
max size fields are set |
||
|
base size fields are set |
||
|
aspect ratio fields are set |
||
|
resize increment fields are set |
||
|
surface gravity field is set |
||
|
indicates that the surface’s position was explicitly set by the user |
||
|
indicates that the surface’s size was explicitly set by the user |
struct GdkGeometry
struct GdkGeometry {
gint min_width;
gint min_height;
gint max_width;
gint max_height;
gint base_width;
gint base_height;
gint width_inc;
gint height_inc;
gdouble min_aspect;
gdouble max_aspect;
GdkGravity win_gravity;
};
The GdkGeometry struct gives the window manager information about
a surface’s geometry constraints. Normally you would set these on
the GTK+ level using gtk_window_set_geometry_hints(). GtkWindow
then sets the hints on the GdkSurface it creates.
gdk_surface_set_geometry_hints() expects the hints to be fully valid already
and simply passes them to the window manager; in contrast,
gtk_window_set_geometry_hints() performs some interpretation. For example,
GtkWindow will apply the hints to the geometry widget instead of the
toplevel window, if you set a geometry widget. Also, the
min_width
/min_height
/max_width
/max_height
fields may be set to -1, and
GtkWindow will substitute the size request of the surface or geometry widget.
If the minimum size hint is not provided, GtkWindow will use its requisition
as the minimum size. If the minimum size is provided and a geometry widget is
set, GtkWindow will take the minimum size as the minimum size of the
geometry widget rather than the entire surface. The base size is treated
similarly.
The canonical use-case for gtk_window_set_geometry_hints() is to get a
terminal widget to resize properly. Here, the terminal text area should be
the geometry widget; GtkWindow will then automatically set the base size to
the size of other widgets in the terminal window, such as the menubar and
scrollbar. Then, the width_inc
and height_inc
fields should be set to the
size of one character in the terminal. Finally, the base size should be set
to the size of one character. The net effect is that the minimum size of the
terminal will have a 1x1 character terminal area, and only terminal sizes on
the “character grid” will be allowed.
Here’s an example of how the terminal example would be implemented, assuming a terminal area widget called “terminal” and a toplevel window “toplevel”:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
GdkGeometry hints; hints.base_width = terminal->char_width; hints.base_height = terminal->char_height; hints.min_width = terminal->char_width; hints.min_height = terminal->char_height; hints.width_inc = terminal->char_width; hints.height_inc = terminal->char_height; gtk_window_set_geometry_hints (GTK_WINDOW (toplevel), GTK_WIDGET (terminal), &hints, GDK_HINT_RESIZE_INC | GDK_HINT_MIN_SIZE | GDK_HINT_BASE_SIZE); |
The other useful fields are the min_aspect
and max_aspect
fields; these
contain a width/height ratio as a floating point number. If a geometry widget
is set, the aspect applies to the geometry widget rather than the entire
window. The most common use of these hints is probably to set min_aspect
and
max_aspect
to the same value, thus forcing the window to keep a constant
aspect ratio.
Members
minimum width of surface (or -1 to use requisition, with GtkWindow only) |
||
minimum height of surface (or -1 to use requisition, with GtkWindow only) |
||
maximum width of surface (or -1 to use requisition, with GtkWindow only) |
||
maximum height of surface (or -1 to use requisition, with GtkWindow only) |
||
allowed surface widths are |
||
allowed surface widths are |
||
width resize increment |
||
height resize increment |
||
minimum width/height ratio |
||
maximum width/height ratio |
||
GdkGravity |
surface gravity, see |
enum GdkGravity
Defines the reference point of a surface and the meaning of coordinates
passed to gtk_window_move(). See gtk_window_move() and the "implementation
notes" section of the
Extended Window Manager Hints
specification for more details.
Members
|
the reference point is at the top left corner. |
||
|
the reference point is in the middle of the top edge. |
||
|
the reference point is at the top right corner. |
||
|
the reference point is at the middle of the left edge. |
||
|
the reference point is at the center of the surface. |
||
|
the reference point is at the middle of the right edge. |
||
|
the reference point is at the lower left corner. |
||
|
the reference point is at the middle of the lower edge. |
||
|
the reference point is at the lower right corner. |
||
|
the reference point is at the top left corner of the surface itself, ignoring window manager decorations. |
enum GdkAnchorHints
Positioning hints for aligning a surface relative to a rectangle.
These hints determine how the surface should be positioned in the case that the surface would fall off-screen if placed in its ideal position.
For example, GDK_ANCHOR_FLIP_X will replace GDK_GRAVITY_NORTH_WEST with
GDK_GRAVITY_NORTH_EAST and vice versa if the surface extends beyond the left
or right edges of the monitor.
If GDK_ANCHOR_SLIDE_X is set, the surface can be shifted horizontally to fit
on-screen. If GDK_ANCHOR_RESIZE_X is set, the surface can be shrunken
horizontally to fit.
In general, when multiple flags are set, flipping should take precedence over sliding, which should take precedence over resizing.
Members
|
allow flipping anchors horizontally |
||
|
allow flipping anchors vertically |
||
|
allow sliding surface horizontally |
||
|
allow sliding surface vertically |
||
|
allow resizing surface horizontally |
||
|
allow resizing surface vertically |
||
|
allow flipping anchors on both axes |
||
|
allow sliding surface on both axes |
||
|
allow resizing surface on both axes |
enum GdkSurfaceEdge
Determines a surface edge or corner.
enum GdkSurfaceTypeHint
These are hints for the window manager that indicate what type of function the window has. The window manager can use this when determining decoration and behaviour of the window. The hint must be set before mapping the window.
See the Extended Window Manager Hints specification for more details about window types.
Members
|
Normal toplevel window. |
||
|
Dialog window. |
||
|
Window used to implement a menu; GTK uses this hint only for torn-off menus, see GtkTearoffMenuItem. |
||
|
Window used to implement toolbars. |
||
|
Window used to display a splash screen during application startup. |
||
|
Utility windows which are not detached toolbars or dialogs. |
||
|
Used for creating dock or panel windows. |
||
|
Used for creating the desktop background window. |
||
|
A menu that belongs to a menubar. |
||
|
A menu that does not belong to a menubar, e.g. a context menu. |
||
|
A tooltip. |
||
|
A notification - typically a “bubble” that belongs to a status icon. |
||
|
A popup from a combo box. |
||
|
A window that is used to implement a DND cursor. |
enum GdkSurfaceState
Specifies the state of a toplevel surface.
On platforms that support information about individual edges, the GDK_SURFACE_STATE_TILED
state will be set whenever any of the individual tiled states is set. On platforms
that lack that support, the tiled state will give an indication of tiledness without
any of the per-edge states being set.
Members
|
the surface is not shown |
||
|
the surface is minimized |
||
|
the surface is maximized |
||
|
the surface is sticky |
||
|
the surface is maximized without decorations |
||
|
the surface is kept above other surfaces |
||
|
the surface is kept below other surfaces |
||
|
the surface is presented as focused (with active decorations) |
||
|
the surface is in a tiled state |
||
|
whether the top edge is tiled |
||
|
whether the top edge is resizable |
||
|
whether the right edge is tiled |
||
|
whether the right edge is resizable |
||
|
whether the bottom edge is tiled |
||
|
whether the bottom edge is resizable |
||
|
whether the left edge is tiled |
||
|
whether the left edge is resizable |
enum GdkFullscreenMode
Indicates which monitor (in a multi-head setup) a surface should span over when in fullscreen mode.
GDK_PARENT_RELATIVE
#define GDK_PARENT_RELATIVE 1L
A special value, indicating that the background for a surface should be inherited from the parent surface.
enum GdkModifierType
A set of bit-flags to indicate the state of modifier keys and mouse buttons in various event types. Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock.
Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons.
GDK recognizes which of the Meta, Super or Hyper keys are mapped
to Mod2 - Mod5, and indicates this by setting GDK_SUPER_MASK,
GDK_HYPER_MASK or GDK_META_MASK in the state field of key events.
Note that GDK may add internal values to events which include
reserved values such as GDK_MODIFIER_RESERVED_13_MASK. Your code
should preserve and ignore them. You can use GDK_MODIFIER_MASK to
remove all reserved values.
Also note that the GDK X backend interprets button press events for button
4-7 as scroll events, so GDK_BUTTON4_MASK and GDK_BUTTON5_MASK will never
be set.
Members
|
the Shift key. |
||
|
a Lock key (depending on the modifier mapping of the X server this may either be CapsLock or ShiftLock). |
||
|
the Control key. |
||
|
the fourth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier, but normally it is the Alt key). |
||
|
the fifth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier). |
||
|
the sixth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier). |
||
|
the seventh modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier). |
||
|
the eighth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier). |
||
|
the first mouse button. |
||
|
the second mouse button. |
||
|
the third mouse button. |
||
|
the fourth mouse button. |
||
|
the fifth mouse button. |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
A reserved bit flag; do not use in your own code |
||
|
the Super modifier |
||
|
the Hyper modifier |
||
|
the Meta modifier |
||
|
A reserved bit flag; do not use in your own code |
||
|
not used in GDK itself. GTK uses it to differentiate between (keyval, modifiers) pairs from key press and release events. |
||
|
a mask covering all modifier types. |
enum GdkModifierIntent
This enum is used with gdk_keymap_get_modifier_mask()
in order to determine what modifiers the
currently used windowing system backend uses for particular
purposes. For example, on X11/Windows, the Control key is used for
invoking menu shortcuts (accelerators), whereas on Apple computers
it’s the Command key (which correspond to GDK_CONTROL_MASK and
GDK_MOD2_MASK, respectively).
Members
|
the primary modifier used to invoke menu accelerators. |
||
|
the modifier used to invoke context menus. Note that mouse button 3 always triggers context menus. When this modifier is not 0, it additionally triggers context menus when used with mouse button 1. |
||
|
the modifier used to extend selections
using |
||
|
the modifier used to modify selections, which in most cases means toggling the clicked item into or out of the selection. |
||
|
when any of these modifiers is pressed, the key event cannot produce a symbol directly. This is meant to be used for input methods, and for use cases like typeahead search. |
||
|
the modifier that switches between keyboard groups (AltGr on X11/Windows and Option/Alt on OS X). |
||
|
The set of modifier masks accepted as modifiers in accelerators. Needed because Command is mapped to MOD2 on OSX, which is widely used, but on X11 MOD2 is NumLock and using that for a mod key is problematic at best. Ref: https://bugzilla.gnome.org/show_bug.cgi?id=736125. |
enum GdkWMDecoration
These are hints originally defined by the Motif toolkit. The window manager can use them when determining how to decorate the surface. The hint must be set before mapping the surface.
Property Details
The “cursor” property
“cursor” GdkCursor *
The mouse pointer for a GdkSurface. See gdk_surface_set_cursor() and
gdk_surface_get_cursor() for details.
Flags: Read / Write
The “display” property
“display” GdkDisplay *
The GdkDisplay connection of the surface. See gdk_surface_get_display()
for details.
Flags: Read / Write / Construct Only
The “frame-clock” property
“frame-clock” GdkFrameClock *
Frame Clock.
Flags: Read / Write / Construct Only
The “state” property
“state” GdkSurfaceState
State.
Flags: Read
Default value: GDK_SURFACE_STATE_WITHDRAWN
Signal Details
The “event” signal
gboolean user_function (GdkSurface *surface, GdkEvent *event, gpointer user_data)
Emitted when GDK receives an input event for surface
.
Parameters
surface |
the GdkSurface |
|
event |
an input event |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “moved-to-rect” signal
void user_function (GdkSurface *surface, gpointer flipped_rect, gpointer final_rect, gboolean flipped_x, gboolean flipped_y, gpointer user_data)
Emitted when the position of surface
is finalized after being moved to a
destination rectangle.
surface
might be flipped over the destination rectangle in order to keep
it on-screen, in which case flipped_x
and flipped_y
will be set to TRUE
accordingly.
flipped_rect
is the ideal position of surface
after any possible
flipping, but before any possible sliding. final_rect
is flipped_rect
,
but possibly translated in the case that flipping is still ineffective in
keeping surface
on-screen.
Parameters
surface |
the GdkSurface that moved |
|
flipped_rect |
the position of |
[nullable] |
final_rect |
the final position of |
[nullable] |
flipped_x |
|
|
flipped_y |
|
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
Stability Level: Private
The “render” signal
gboolean user_function (GdkSurface *surface, CairoRegion *region, gpointer user_data)
Emitted when part of the surface needs to be redrawn.
Parameters
surface |
the GdkSurface |
|
region |
the region that needs to be redrawn |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “size-changed” signal
void user_function (GdkSurface *surface, gint width, gint height, gpointer user_data)
Emitted when the size of surface
is changed.
Parameters
surface |
the GdkSurface |
|
width |
the new width |
|
height |
the new height |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
| Top | |
|
|
|
Functions
| GdkDisplay * | gdk_gl_context_get_display () |
| GdkSurface * | gdk_gl_context_get_surface () |
| GdkGLContext * | gdk_gl_context_get_shared_context () |
| void | gdk_gl_context_get_version () |
| void | gdk_gl_context_set_required_version () |
| void | gdk_gl_context_get_required_version () |
| void | gdk_gl_context_set_debug_enabled () |
| gboolean | gdk_gl_context_get_debug_enabled () |
| void | gdk_gl_context_set_forward_compatible () |
| gboolean | gdk_gl_context_get_forward_compatible () |
| void | gdk_gl_context_set_use_es () |
| gboolean | gdk_gl_context_get_use_es () |
| gboolean | gdk_gl_context_is_legacy () |
| gboolean | gdk_gl_context_realize () |
| void | gdk_gl_context_make_current () |
| GdkGLContext * | gdk_gl_context_get_current () |
| void | gdk_gl_context_clear_current () |
Description
GdkGLContext is an object representing the platform-specific OpenGL draw context.
GdkGLContexts are created for a GdkSurface using
gdk_surface_create_gl_context(), and the context will match the
the characteristics of the surface.
A GdkGLContext is not tied to any particular normal framebuffer.
For instance, it cannot draw to the GdkSurface back buffer. The GDK
repaint system is in full control of the painting to that. Instead,
you can create render buffers or textures and use gdk_cairo_draw_from_gl()
in the draw function of your widget to draw them. Then GDK will handle
the integration of your rendering with that of other widgets.
Support for GdkGLContext is platform-specific, context creation
can fail, returning NULL context.
A GdkGLContext has to be made "current" in order to start using it, otherwise any OpenGL call will be ignored.
Creating a new OpenGL context
In order to create a new GdkGLContext instance you need a GdkSurface, which you typically get during the realize call of a widget.
A GdkGLContext is not realized until either gdk_gl_context_make_current(),
or until it is realized using gdk_gl_context_realize(). It is possible to
specify details of the GL context like the OpenGL version to be used, or
whether the GL context should have extra state validation enabled after
calling gdk_surface_create_gl_context() by calling gdk_gl_context_realize().
If the realization fails you have the option to change the settings of the
GdkGLContext and try again.
Using a GdkGLContext
You will need to make the GdkGLContext the current context before issuing OpenGL calls; the system sends OpenGL commands to whichever context is current. It is possible to have multiple contexts, so you always need to ensure that the one which you want to draw with is the current one before issuing commands:
1 |
gdk_gl_context_make_current (context); |
You can now perform your drawing using OpenGL commands.
You can check which GdkGLContext is the current one by using
gdk_gl_context_get_current(); you can also unset any GdkGLContext
that is currently set by calling gdk_gl_context_clear_current().
Functions
gdk_gl_context_get_display ()
GdkDisplay *
gdk_gl_context_get_display (GdkGLContext *context);
Retrieves the GdkDisplay the context
is created for
gdk_gl_context_get_surface ()
GdkSurface *
gdk_gl_context_get_surface (GdkGLContext *context);
Retrieves the GdkSurface used by the context
.
gdk_gl_context_get_shared_context ()
GdkGLContext *
gdk_gl_context_get_shared_context (GdkGLContext *context);
Retrieves the GdkGLContext that this context
share data with.
gdk_gl_context_get_version ()
void gdk_gl_context_get_version (GdkGLContext *context,int *major,int *minor);
Retrieves the OpenGL version of the context
.
The context
must be realized prior to calling this function.
gdk_gl_context_set_required_version ()
void gdk_gl_context_set_required_version (GdkGLContext *context,int major,int minor);
Sets the major and minor version of OpenGL to request.
Setting major
and minor
to zero will use the default values.
The GdkGLContext must not be realized or made current prior to calling this function.
gdk_gl_context_get_required_version ()
void gdk_gl_context_get_required_version (GdkGLContext *context,int *major,int *minor);
Retrieves the major and minor version requested by calling
gdk_gl_context_set_required_version().
gdk_gl_context_set_debug_enabled ()
void gdk_gl_context_set_debug_enabled (GdkGLContext *context,gboolean enabled);
Sets whether the GdkGLContext should perform extra validations and run time checking. This is useful during development, but has additional overhead.
The GdkGLContext must not be realized or made current prior to calling this function.
gdk_gl_context_get_debug_enabled ()
gboolean
gdk_gl_context_get_debug_enabled (GdkGLContext *context);
Retrieves the value set using gdk_gl_context_set_debug_enabled().
gdk_gl_context_set_forward_compatible ()
void gdk_gl_context_set_forward_compatible (GdkGLContext *context,gboolean compatible);
Sets whether the GdkGLContext should be forward compatible.
Forward compatibile contexts must not support OpenGL functionality that has been marked as deprecated in the requested version; non-forward compatible contexts, on the other hand, must support both deprecated and non deprecated functionality.
The GdkGLContext must not be realized or made current prior to calling this function.
gdk_gl_context_get_forward_compatible ()
gboolean
gdk_gl_context_get_forward_compatible (GdkGLContext *context);
Retrieves the value set using gdk_gl_context_set_forward_compatible().
gdk_gl_context_set_use_es ()
void gdk_gl_context_set_use_es (GdkGLContext *context,int use_es);
Requests that GDK create a OpenGL ES context instead of an OpenGL one, if the platform and windowing system allows it.
The context
must not have been realized.
By default, GDK will attempt to automatically detect whether the
underlying GL implementation is OpenGL or OpenGL ES once the context
is realized.
You should check the return value of gdk_gl_context_get_use_es() after
calling gdk_gl_context_realize() to decide whether to use the OpenGL or
OpenGL ES API, extensions, or shaders.
Parameters
context |
a GdkGLContext: |
|
use_es |
whether the context should use OpenGL ES instead of OpenGL, or -1 to allow auto-detection |
gdk_gl_context_get_use_es ()
gboolean
gdk_gl_context_get_use_es (GdkGLContext *context);
Checks whether the context
is using an OpenGL or OpenGL ES profile.
gdk_gl_context_is_legacy ()
gboolean
gdk_gl_context_is_legacy (GdkGLContext *context);
Whether the GdkGLContext is in legacy mode or not.
The GdkGLContext must be realized before calling this function.
When realizing a GL context, GDK will try to use the OpenGL 3.2 core
profile; this profile removes all the OpenGL API that was deprecated
prior to the 3.2 version of the specification. If the realization is
successful, this function will return FALSE.
If the underlying OpenGL implementation does not support core profiles,
GDK will fall back to a pre-3.2 compatibility profile, and this function
will return TRUE.
You can use the value returned by this function to decide which kind of OpenGL API to use, or whether to do extension discovery, or what kind of shader programs to load.
gdk_gl_context_realize ()
gboolean gdk_gl_context_realize (GdkGLContext *context,GError **error);
Realizes the given GdkGLContext.
It is safe to call this function on a realized GdkGLContext.
gdk_gl_context_make_current ()
void
gdk_gl_context_make_current (GdkGLContext *context);
Makes the context
the current one.
gdk_gl_context_get_current ()
GdkGLContext *
gdk_gl_context_get_current (void);
Retrieves the current GdkGLContext.
gdk_gl_context_clear_current ()
void
gdk_gl_context_clear_current (void);
Clears the current GdkGLContext.
Any OpenGL call after this function returns will be ignored
until gdk_gl_context_make_current() is called.
Types and Values
GdkGLContext
typedef struct _GdkGLContext GdkGLContext;
The GdkGLContext struct contains only private fields and should not be accessed directly.
enum GdkGLError
Error enumeration for GdkGLContext.
Property Details
The “shared-context” property
“shared-context” GdkGLContext *
The GdkGLContext that this context is sharing data with, or NULL
Flags: Read / Write / Construct Only
| Top | |
|
|
|
Description
Pango is the text layout system used by GDK and GTK+. The functions and types in this section are used to obtain clip regions for PangoLayouts, and to get PangoContexts that can be used with GDK.
Creating a PangoLayout object is the first step in rendering text,
and requires getting a handle to a PangoContext. For GTK+ programs,
you’ll usually want to use gtk_widget_get_pango_context(), or
gtk_widget_create_pango_layout(). Once you have a PangoLayout,
you can set the text and attributes of it with Pango functions like
pango_layout_set_text() and get its size with pango_layout_get_size().
(Note that Pango uses a fixed point system internally, so converting
between Pango units and pixels using PANGO_SCALE
or the PANGO_PIXELS() macro.)
Rendering a Pango layout is done most simply with pango_cairo_show_layout();
you can also draw pieces of the layout with pango_cairo_show_layout_line().
Draw transformed text with Pango and cairo
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 |
#define RADIUS 100 #define N_WORDS 10 #define FONT "Sans Bold 18" PangoContext *context; PangoLayout *layout; PangoFontDescription *desc; double radius; int width, height; int i; // Set up a transformation matrix so that the user space coordinates for // where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS] // We first center, then change the scale width = gdk_surface_get_width (surface); height = gdk_surface_get_height (surface); radius = MIN (width, height) / 2.; cairo_translate (cr, radius + (width - 2 * radius) / 2, radius + (height - 2 * radius) / 2); cairo_scale (cr, radius / RADIUS, radius / RADIUS); // Create a PangoLayout, set the font and text context = gdk_pango_context_get_for_display (display); layout = pango_layout_new (context); pango_layout_set_text (layout, "Text", -1); desc = pango_font_description_from_string (FONT); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); // Draw the layout N_WORDS times in a circle for (i = 0; i < N_WORDS; i++) { double red, green, blue; double angle = 2 * G_PI * i / n_words; cairo_save (cr); // Gradient from red at angle == 60 to blue at angle == 300 red = (1 + cos (angle - 60)) / 2; green = 0; blue = 1 - red; cairo_set_source_rgb (cr, red, green, blue); cairo_rotate (cr, angle); // Inform Pango to re-layout the text with the new transformation matrix pango_cairo_update_layout (cr, layout); pango_layout_get_size (layout, &width, &height); cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS); pango_cairo_show_layout (cr, layout); cairo_restore (cr); } g_object_unref (layout); g_object_unref (context); |
Functions
gdk_pango_layout_get_clip_region ()
cairo_region_t * gdk_pango_layout_get_clip_region (PangoLayout *layout,gint x_origin,gint y_origin,const gint *index_ranges,gint n_ranges);
Obtains a clip region which contains the areas where the given ranges
of text would be drawn. x_origin
and y_origin
are the top left point
to center the layout. index_ranges
should contain
ranges of bytes in the layout’s text.
Note that the regions returned correspond to logical extents of the text ranges, not ink extents. So the drawn layout may in fact touch areas out of the clip region. The clip region is mainly useful for highlightling parts of text, such as when text is selected.
[skip]
Parameters
layout |
||
x_origin |
X pixel where you intend to draw the layout with this clip |
|
y_origin |
Y pixel where you intend to draw the layout with this clip |
|
index_ranges |
array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes |
|
n_ranges |
number of ranges in |
gdk_pango_layout_line_get_clip_region ()
cairo_region_t * gdk_pango_layout_line_get_clip_region (PangoLayoutLine *line,gint x_origin,gint y_origin,const gint *index_ranges,gint n_ranges);
Obtains a clip region which contains the areas where the given
ranges of text would be drawn. x_origin
and y_origin
are the top left
position of the layout. index_ranges
should contain ranges of bytes in the layout’s text. The clip
region will include space to the left or right of the line (to the
layout bounding box) if you have indexes above or below the indexes
contained inside the line. This is to draw the selection all the way
to the side of the layout. However, the clip region is in line coordinates,
not layout coordinates.
Note that the regions returned correspond to logical extents of the text ranges, not ink extents. So the drawn line may in fact touch areas out of the clip region. The clip region is mainly useful for highlightling parts of text, such as when text is selected.
[skip]
Parameters
line |
||
x_origin |
X pixel where you intend to draw the layout line with this clip |
|
y_origin |
baseline pixel where you intend to draw the layout line with this clip |
|
index_ranges |
array of byte indexes into the layout, where even members of array are start indexes and odd elements are end indexes. |
[array] |
n_ranges |
number of ranges in |
| Top | |
|
|
|
Functions
| GdkDisplay * | gdk_draw_context_get_display () |
| GdkSurface * | gdk_draw_context_get_surface () |
| void | gdk_draw_context_begin_frame () |
| void | gdk_draw_context_end_frame () |
| gboolean | gdk_draw_context_is_in_frame () |
| const cairo_region_t * | gdk_draw_context_get_frame_region () |
Description
GdkDrawContext is the base object used by contexts implementing different rendering methods, such as GdkGLContext or GdkVulkanContext. It provides shared functionality between those contexts.
You will always interact with one of those s.ubclasses.
A GdkDrawContext is always associated with a single toplevel surface.
Functions
gdk_draw_context_get_display ()
GdkDisplay *
gdk_draw_context_get_display (GdkDrawContext *context);
Retrieves the GdkDisplay the context
is created for
gdk_draw_context_get_surface ()
GdkSurface *
gdk_draw_context_get_surface (GdkDrawContext *context);
Retrieves the GdkSurface used by the context
.
gdk_draw_context_begin_frame ()
void gdk_draw_context_begin_frame (GdkDrawContext *context,const cairo_region_t *region);
Indicates that you are beginning the process of redrawing region
on the context
's surface.
Calling this function begins a drawing operation using context
on the
surface that context
was created from. The actual requirements and
guarantees for the drawing operation vary for different implementations
of drawing, so a GdkCairoContext and a GdkGLContext need to be treated
differently.
A call to this function is a requirement for drawing and must be followed
by a call to gdk_draw_context_end_frame(), which will complete the
drawing operation and ensure the contents become visible on screen.
Note that the region
passed to this function is the minimum region that
needs to be drawn and depending on implementation, windowing system and
hardware in use, it might be necessary to draw a larger region. Drawing
implementation must use gdk_draw_context_get_frame_region() to query the
region that must be drawn.
When using GTK+, the widget system automatically places calls to
gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the
use of GskRenderers, so application code does not need to call these
functions explicitly.
gdk_draw_context_end_frame ()
void
gdk_draw_context_end_frame (GdkDrawContext *context);
Ends a drawing operation started with gdk_draw_context_begin_frame()
and makes the drawing available on screen. See that function for more
details about drawing.
When using a GdkGLContext, this function may call glFlush()glFlush()
gdk_draw_context_is_in_frame ()
gboolean
gdk_draw_context_is_in_frame (GdkDrawContext *context);
Returns TRUE if context
is in the process of drawing to its surface
after a call to gdk_draw_context_begin_frame() and not yet having called
gdk_draw_context_end_frame().
In this situation, drawing commands may be effecting the contents of a
context
's surface.
gdk_draw_context_get_frame_region ()
const cairo_region_t *
gdk_draw_context_get_frame_region (GdkDrawContext *context);
Retrieves the region that is currently in the process of being repainted.
After a call to gdk_draw_context_begin_frame() this function will return
a union of the region passed to that function and the area of the surface
that the context
determined needs to be repainted.
If context
is not inbetween calls to gdk_draw_context_begin_frame() and
gdk_draw_context_end_frame(), NULL will be returned.
| Top | |
|
|
|
Functions
| guint | gdk_keymap_lookup_key () |
| gboolean | gdk_keymap_translate_keyboard_state () |
| gboolean | gdk_keymap_get_entries_for_keyval () |
| gboolean | gdk_keymap_get_entries_for_keycode () |
| PangoDirection | gdk_keymap_get_direction () |
| gboolean | gdk_keymap_have_bidi_layouts () |
| gboolean | gdk_keymap_get_caps_lock_state () |
| gboolean | gdk_keymap_get_num_lock_state () |
| gboolean | gdk_keymap_get_scroll_lock_state () |
| guint | gdk_keymap_get_modifier_state () |
| void | gdk_keymap_add_virtual_modifiers () |
| gboolean | gdk_keymap_map_virtual_modifiers () |
| GdkModifierType | gdk_keymap_get_modifier_mask () |
| GdkDisplay * | gdk_keymap_get_display () |
| gchar * | gdk_keyval_name () |
| guint | gdk_keyval_from_name () |
| void | gdk_keyval_convert_case () |
| guint | gdk_keyval_to_upper () |
| guint | gdk_keyval_to_lower () |
| gboolean | gdk_keyval_is_upper () |
| gboolean | gdk_keyval_is_lower () |
| guint32 | gdk_keyval_to_unicode () |
| guint | gdk_unicode_to_keyval () |
Description
Key values are the codes which are sent whenever a key is pressed or released.
They appear in the GdkEventKey.keyval field of the GdkEventKey structure.
The complete list of key values can be found in the gdk/gdkkeysyms.h header file.
Key values are regularly updated from the upstream X.org X11 implementation, so new values are added regularly. They will be prefixed with GDK_KEY_ rather than XF86XK_ or XK_ (for older symbols).
Key values can be converted into a string representation using
gdk_keyval_name(). The reverse function, converting a string to a key value,
is provided by gdk_keyval_from_name().
The case of key values can be determined using gdk_keyval_is_upper() and
gdk_keyval_is_lower(). Key values can be converted to upper or lower case
using gdk_keyval_to_upper() and gdk_keyval_to_lower().
When it makes sense, key values can be converted to and from
Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
Groups
One GdkKeymap object exists for each user display. To obtain keymaps for
a display, use gdk_display_get_keymap(). A keymap is a mapping from
GdkKeymapKey to key values. You can think of a GdkKeymapKey as a
representation of a symbol printed on a physical keyboard key. That is, it
contains three pieces of information. First, it contains the hardware keycode;
this is an identifying number for a physical key. Second, it contains the
“level” of the key. The level indicates which symbol on the
key will be used, in a vertical direction. So on a standard US keyboard, the key
with the number “1“ on it also has the exclamation point (”!”) character on
it. The level indicates whether to use the “1” or the “!” symbol. The letter
keys are considered to have a lowercase letter at level 0, and an uppercase
letter at level 1, though only the uppercase letter is printed. Third, the
GdkKeymapKey contains a group; groups are not used on standard US keyboards,
but are used in many other countries. On a keyboard with groups, there can be 3
or 4 symbols printed on a single key. The group indicates movement in a
horizontal direction. Usually groups are used for two different languages. In
group 0, a key might have two English characters, and in group 1 it might have
two Hebrew characters. The Hebrew characters will be printed on the key next to
the English characters.
In order to use a keymap to interpret a key event, it’s necessary to first
convert the keyboard state into an effective group and level. This is done via a
set of rules that varies widely according to type of keyboard and user
configuration. The function gdk_keymap_translate_keyboard_state() accepts a
keyboard state -- consisting of hardware keycode pressed, active modifiers, and
active group -- applies the appropriate rules, and returns the group/level to be
used to index the keymap, along with the modifiers which did not affect the
group and level. i.e. it returns “unconsumed modifiers.” The keyboard group may
differ from the effective group used for keymap lookups because some keys don't
have multiple groups - e.g. the Enter key is always in group 0 regardless of
keyboard state.
Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it
goes ahead and performs the keymap lookup in addition to telling you which
effective group/level values were used for the lookup. GdkEventKey already
contains this keyval, however, so you don’t normally need to call
gdk_keymap_translate_keyboard_state() just to get the keyval.
Functions
gdk_keymap_lookup_key ()
guint gdk_keymap_lookup_key (GdkKeymap *keymap,const GdkKeymapKey *key);
Looks up the keyval mapped to a keycode/group/level triplet.
If no keyval is bound to key
, returns 0. For normal user input,
you want to use gdk_keymap_translate_keyboard_state() instead of
this function, since the effective group/level may not be
the same as the current keyboard state.
gdk_keymap_translate_keyboard_state ()
gboolean gdk_keymap_translate_keyboard_state (GdkKeymap *keymap,guint hardware_keycode,GdkModifierType state,gint group,guint *keyval,gint *effective_group,gint *level,GdkModifierType *consumed_modifiers);
Translates the contents of a GdkEventKey into a keyval, effective
group, and level. Modifiers that affected the translation and
are thus unavailable for application use are returned in
consumed_modifiers
.
See Groups for an explanation of
groups and levels. The effective_group
is the group that was
actually used for the translation; some keys such as Enter are not
affected by the active keyboard group. The level
is derived from
state
. For convenience, GdkEventKey already contains the translated
keyval, so this function isn’t as useful as you might think.
consumed_modifiers
gives modifiers that should be masked outfrom state
when comparing this key press to a hot key. For instance, on a US keyboard,
the plus symbol is shifted, so when comparing a key press to a
<Control>plus accelerator <Shift> should be masked out.
1 2 3 4 5 6 7 8 |
// We want to ignore irrelevant modifiers like ScrollLock #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK) gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode, event->state, event->group, &keyval, NULL, NULL, &consumed); if (keyval == GDK_PLUS && (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK) // Control was pressed |
An older interpretation consumed_modifiers
was that it contained
all modifiers that might affect the translation of the key;
this allowed accelerators to be stored with irrelevant consumed
modifiers, by doing:
1 2 3 4 |
// XXX Don’t do this XXX if (keyval == accel_keyval && (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed)) // Accelerator was pressed |
However, this did not work if multi-modifier combinations were
used in the keymap, since, for instance, <Control> would be
masked out even if only <Control><Alt> was used in the keymap.
To support this usage as well as well as possible, all single
modifier combinations that could affect the key for any combination
of modifiers will be returned in consumed_modifiers
; multi-modifier
combinations are returned only when actually found in state
. When
you store accelerators, you should always store them with consumed
modifiers removed. Store <Control>plus, not <Control><Shift>plus,
Parameters
keymap |
||
hardware_keycode |
a keycode |
|
state |
a modifier state |
|
group |
active keyboard group |
|
keyval |
return location for keyval, or |
[out][allow-none] |
effective_group |
return location for effective
group, or |
[out][allow-none] |
level |
return location for level, or |
[out][allow-none] |
consumed_modifiers |
return location for modifiers
that were used to determine the group or level, or |
[out][allow-none] |
gdk_keymap_get_entries_for_keyval ()
gboolean gdk_keymap_get_entries_for_keyval (GdkKeymap *keymap,guint keyval,GdkKeymapKey **keys,gint *n_keys);
Obtains a list of keycode/group/level combinations that will
generate keyval
. Groups and levels are two kinds of keyboard mode;
in general, the level determines whether the top or bottom symbol
on a key is used, and the group determines whether the left or
right symbol is used. On US keyboards, the shift key changes the
keyboard level, and there are no groups. A group switch key might
convert a keyboard between Hebrew to English modes, for example.
GdkEventKey contains a group field that indicates the active
keyboard group. The level is computed from the modifier mask.
The returned array should be freed
with g_free().
Parameters
keymap |
||
keyval |
a keyval, such as |
|
keys |
return location for an array of GdkKeymapKey. |
[out][array length=n_keys][transfer full] |
n_keys |
return location for number of elements in returned array |
gdk_keymap_get_entries_for_keycode ()
gboolean gdk_keymap_get_entries_for_keycode (GdkKeymap *keymap,guint hardware_keycode,GdkKeymapKey **keys,guint **keyvals,gint *n_entries);
Returns the keyvals bound to hardware_keycode
.
The Nth GdkKeymapKey in keys
is bound to the Nth
keyval in keyvals
. Free the returned arrays with g_free().
When a keycode is pressed by the user, the keyval from
this list of entries is selected by considering the effective
keyboard group and level. See gdk_keymap_translate_keyboard_state().
Parameters
keymap |
||
hardware_keycode |
a keycode |
|
keys |
return
location for array of GdkKeymapKey, or |
[out][array length=n_entries][transfer full][optional] |
keyvals |
return
location for array of keyvals, or |
[out][array length=n_entries][transfer full][optional] |
n_entries |
length of |
gdk_keymap_get_direction ()
PangoDirection
gdk_keymap_get_direction (GdkKeymap *keymap);
Returns the direction of effective layout of the keymap.
The direction of a layout is the direction of the majority of its
symbols. See pango_unichar_direction().
Returns
PANGO_DIRECTION_LTR or PANGO_DIRECTION_RTL
if it can determine the direction. PANGO_DIRECTION_NEUTRAL
otherwise.
gdk_keymap_have_bidi_layouts ()
gboolean
gdk_keymap_have_bidi_layouts (GdkKeymap *keymap);
Determines if keyboard layouts for both right-to-left and left-to-right languages are in use.
gdk_keymap_get_caps_lock_state ()
gboolean
gdk_keymap_get_caps_lock_state (GdkKeymap *keymap);
Returns whether the Caps Lock modifer is locked.
gdk_keymap_get_num_lock_state ()
gboolean
gdk_keymap_get_num_lock_state (GdkKeymap *keymap);
Returns whether the Num Lock modifer is locked.
gdk_keymap_get_scroll_lock_state ()
gboolean
gdk_keymap_get_scroll_lock_state (GdkKeymap *keymap);
Returns whether the Scroll Lock modifer is locked.
gdk_keymap_get_modifier_state ()
guint
gdk_keymap_get_modifier_state (GdkKeymap *keymap);
Returns the current modifier state.
gdk_keymap_add_virtual_modifiers ()
void gdk_keymap_add_virtual_modifiers (GdkKeymap *keymap,GdkModifierType *state);
Maps the non-virtual modifiers (i.e Mod2, Mod3, ...) which are set
in state
to the virtual modifiers (i.e. Super, Hyper and Meta) and
set the corresponding bits in state
.
GDK already does this before delivering key events, but for compatibility reasons, it only sets the first virtual modifier it finds, whereas this function sets all matching virtual modifiers.
This function is useful when matching key events against accelerators.
gdk_keymap_map_virtual_modifiers ()
gboolean gdk_keymap_map_virtual_modifiers (GdkKeymap *keymap,GdkModifierType *state);
Maps the virtual modifiers (i.e. Super, Hyper and Meta) which
are set in state
to their non-virtual counterparts (i.e. Mod2,
Mod3,...) and set the corresponding bits in state
.
This function is useful when matching key events against accelerators.
gdk_keymap_get_modifier_mask ()
GdkModifierType gdk_keymap_get_modifier_mask (GdkKeymap *keymap,GdkModifierIntent intent);
Returns the modifier mask the keymap
’s windowing system backend
uses for a particular purpose.
Note that this function always returns real hardware modifiers, not
virtual ones (e.g. it will return GDK_MOD1_MASK rather than
GDK_META_MASK if the backend maps MOD1 to META), so there are use
cases where the return value of this function has to be transformed
by gdk_keymap_add_virtual_modifiers() in order to contain the
expected result.
gdk_keymap_get_display ()
GdkDisplay *
gdk_keymap_get_display (GdkKeymap *keymap);
Retrieves the GdkDisplay associated to the keymap
.
gdk_keyval_name ()
gchar *
gdk_keyval_name (guint keyval);
Converts a key value into a symbolic name.
The names are the same as those in the
gdk/gdkkeysyms.h header file
but without the leading “GDK_KEY_”.
gdk_keyval_from_name ()
guint
gdk_keyval_from_name (const gchar *keyval_name);
Converts a key name to a key value.
The names are the same as those in the
gdk/gdkkeysyms.h header file
but without the leading “GDK_KEY_”.
gdk_keyval_convert_case ()
void gdk_keyval_convert_case (guint symbol,guint *lower,guint *upper);
Obtains the upper- and lower-case versions of the keyval symbol
.
Examples of keyvals are GDK_KEY_a, GDK_KEY_Enter, GDK_KEY_F1, etc.
gdk_keyval_to_upper ()
guint
gdk_keyval_to_upper (guint keyval);
Converts a key value to upper case, if applicable.
gdk_keyval_to_lower ()
guint
gdk_keyval_to_lower (guint keyval);
Converts a key value to lower case, if applicable.
gdk_keyval_is_upper ()
gboolean
gdk_keyval_is_upper (guint keyval);
Returns TRUE if the given key value is in upper case.
gdk_keyval_is_lower ()
gboolean
gdk_keyval_is_lower (guint keyval);
Returns TRUE if the given key value is in lower case.
gdk_keyval_to_unicode ()
guint32
gdk_keyval_to_unicode (guint keyval);
Convert from a GDK key symbol to the corresponding ISO10646 (Unicode) character.
Types and Values
GdkKeymap
typedef struct _GdkKeymap GdkKeymap;
A GdkKeymap defines the translation from keyboard state (including a hardware key, a modifier mask, and active keyboard group) to a keyval. This translation has two phases. The first phase is to determine the effective keyboard group and level for the keyboard state; the second phase is to look up the keycode/group/level triplet in the keymap and see what keyval it corresponds to.
struct GdkKeymapKey
struct GdkKeymapKey {
guint keycode;
gint group;
gint level;
};
A GdkKeymapKey is a hardware key that can be mapped to a keyval.
Members
the hardware keycode. This is an identifying number for a physical key. |
||
indicates movement in a horizontal direction. Usually groups are used for two different languages. In group 0, a key might have two English characters, and in group 1 it might have two Hebrew characters. The Hebrew characters will be printed on the key next to the English characters. |
||
indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key with the number “1” on it also has the exclamation point ("!") character on it. The level indicates whether to use the “1” or the “!” symbol. The letter keys are considered to have a lowercase letter at level 0, and an uppercase letter at level 1, though only the uppercase letter is printed. |
Property Details
The “display” property
“display” GdkDisplay *
The display of the keymap.
Flags: Read / Write / Construct Only
Signal Details
The “direction-changed” signal
void user_function (GdkKeymap *keymap, gpointer user_data)
The ::direction-changed signal gets emitted when the direction
of the keymap changes. See gdk_keymap_get_direction().
Parameters
keymap |
the object on which the signal is emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “keys-changed” signal
void user_function (GdkKeymap *keymap, gpointer user_data)
The ::keys-changed signal is emitted when the mapping represented by
keymap
changes.
Parameters
keymap |
the object on which the signal is emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “state-changed” signal
void user_function (GdkKeymap *keymap, gpointer user_data)
The ::state-changed signal is emitted when the state of the
keyboard changes, e.g when Caps Lock is turned on or off.
See gdk_keymap_get_caps_lock_state().
Parameters
keymap |
the object on which the signal is emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
| Top | |
|
|
|
Types and Values
| #define | GDK_WINDOWING_X11 |
| #define | GDK_WINDOWING_WIN32 |
| #define | GDK_WINDOWING_QUARTZ |
| #define | GDK_WINDOWING_WAYLAND |
| #define | GDK_VERSION_4_0 |
| #define | GDK_VERSION_MIN_REQUIRED |
| #define | GDK_VERSION_MAX_ALLOWED |
| #define | GDK_DISABLE_DEPRECATION_WARNINGS |
Description
This section describes the GDK initialization functions and miscellaneous utility functions, as well as deprecation facilities.
The GDK and GTK headers annotate deprecated APIs in a way that produces
compiler warnings if these deprecated APIs are used. The warnings
can be turned off by defining the macro GDK_DISABLE_DEPRECATION_WARNINGS
before including the glib.h header.
GDK and GTK also provide support for building applications against
defined subsets of deprecated or new APIs. Define the macro
GDK_VERSION_MIN_REQUIRED to specify up to what version
you want to receive warnings about deprecated APIs. Define the
macro GDK_VERSION_MAX_ALLOWED to specify the newest version
whose API you want to use.
Types and Values
GDK_WINDOWING_X11
#define GDK_WINDOWING_X11
The GDK_WINDOWING_X11 macro is defined if the X11 backend is supported.
Use this macro to guard code that is specific to the X11 backend.
GDK_WINDOWING_WIN32
#define GDK_WINDOWING_WIN32
The GDK_WINDOWING_WIN32 macro is defined if the Win32 backend is supported.
Use this macro to guard code that is specific to the Win32 backend.
GDK_WINDOWING_QUARTZ
#define GDK_WINDOWING_QUARTZ
The GDK_WINDOWING_QUARTZ macro is defined if the Quartz backend is supported.
Use this macro to guard code that is specific to the Quartz backend.
GDK_WINDOWING_WAYLAND
#define GDK_WINDOWING_WAYLAND
The GDK_WINDOWING_WAYLAND macro is defined if the Wayland backend is supported.
Use this macro to guard code that is specific to the Wayland backend.
GDK_VERSION_4_0
#define GDK_VERSION_4_0 (G_ENCODE_VERSION (4, 0))
A macro that evaluates to the 4.0 version of GDK, in a format that can be used by the C pre-processor.
GDK_VERSION_MIN_REQUIRED
# define GDK_VERSION_MIN_REQUIRED (GDK_VERSION_CUR_STABLE)
A macro that should be defined by the user prior to including
the gdk.h header.
The definition should be one of the predefined GDK version
macros: GDK_VERSION_4_0, GDK_VERSION_4_2,...
This macro defines the lower bound for the GDK API to use.
If a function has been deprecated in a newer version of GDK, it is possible to use this symbol to avoid the compiler warnings without disabling warning for every deprecated function.
GDK_VERSION_MAX_ALLOWED
# define GDK_VERSION_MAX_ALLOWED GDK_VERSION_MIN_REQUIRED
A macro that should be defined by the user prior to including
the gdk.h header.
The definition should be one of the predefined GDK version
macros: GDK_VERSION_4_0, GDK_VERSION_4_2,...
This macro defines the upper bound for the GDK API to use.
If a function has been introduced in a newer version of GDK, it is possible to use this symbol to get compiler warnings when trying to use that function.
GDK 4 Reference Manual |
|---|
This document is for the GDK 4 library, version 3.96.0 . The latest versions can be found online at https://developer.gnome.org/gdk4/. If you are looking for the older GDK 3 series of libraries, see https://developer.gnome.org/gdk3/.
- I. API Reference
- General — Library initialization and miscellaneous functions
- GdkDisplayManager — Maintains a list of all open GdkDisplays
- GdkDisplay — Controls a set of monitors and their associated input devices
- GdkSeat — Object representing an user seat
- GdkDevice — Object representing an input device
- GtkDevicePad — Pad device interface
- GdkMonitor — Object representing an output
- Points and Rectangles — Simple graphical data types
- GdkTexture — Pixel data
- GdkPaintable — An interface for a paintable region
- RGBA Colors — RGBA colors
- Cursors — Named and texture cursors
- Surfaces — Onscreen display areas in the target window system
- Frame clock — Frame clock syncs painting to a window or display
- Frame timings — Object holding timing information for a single frame
- GdkDrawContext — Base class for draw contexts
- GdkGLContext — OpenGL draw context
- GdkVulkanContext — Vulkan draw context
- Events — Functions for handling events from the window system
- Key Values — Functions for manipulating keyboard codes
- Clipboards — Share data between applications for Copy-and-Paste
- Drag And Drop — Functions for controlling drag and drop handling
- Content Formats — Advertising and negotiating of content exchange formats
- GdkContentProvider — Provides content for data transfer between applications
- GdkContentSerializer — Serialize content for transfer
- GdkContentDeserializer — Deserialize content for transfer
- Properties and Atoms — Functions to manipulate properties on windows
- Application launching — Startup notification for applications
- GdkPixbuf Interaction — Functions for obtaining pixbufs
- Pango Interaction — Using Pango in GDK
- Cairo Interaction — Functions to support using cairo
- X Window System Interaction — X backend-specific functions
- Wayland Interaction — Wayland backend-specific functions
- Index of all symbols
- Annotation Glossary
| Top | |
|
|
|
Functions
Description
GdkPaintable is a simple interface used by GDK and GDK to represent objects that can be painted anywhere at any size without requiring any sort of layout. The interface is inspired by similar concepts elsewhere, such as ClutterContent, HTML/CSS Paint Sources, or SVG Paint Servers.
A GdkPaintable can be snapshot at any time and size using
gdk_paintable_snapshot(). How the paintable interprets that size and if it
scales or centers itself into the given rectangle is implementation defined,
though if you are implementing a GdkPaintable and don't know what to do, it
is suggested that you scale your paintable ignoring any potential aspect ratio.
The contents that a GdkPaintable produces may depend on the GdkSnapshot passed to it. For example, paintables may decide to use more detailed images on higher resolution screens or when OpenGL is available. A GdkPaintable will however always produce the same output for the same snapshot.
A GdkPaintable may change its contents, meaning that it will now produce a
different output with the same snpashot. Once that happens, it will call
gdk_paintable_invalidate_contents() which will emit the
“invalidate-contents” signal.
If a paintable is known to never change its contents, it will set the
GDK_PAINTABLE_STATIC_CONTENT flag. If a consumer cannot deal with changing
contents, it may call gdk_paintable_get_static_image() which will return a
static paintable and use that.
A paintable can report an intrinsic (or preferred) size or aspect ratio it
wishes to be rendered at, though it doesn't have to. Consumers of the interface
can use this information to layout thepaintable appropriately.
Just like the contents, the size of a paintable can change. A paintable will
indicate this by calling gdk_paintable_invalidate_size() which will emit the
“invalidate-size” signal.
And just like for contents, if a paintable is known to never change its size,
it will set the GDK_PAINTABLE_STATIC_SIZE flag.
Besides API for applications, there are some functions that are only
useful for implementing subclasses and should not be used by applications:
gdk_paintable_invalidate_contents(),
gdk_paintable_invalidate_size(),
gdk_paintable_new_empty().
Functions
gdk_paintable_get_current_image ()
GdkPaintable *
gdk_paintable_get_current_image (GdkPaintable *paintable);
Gets an immutable paintable for the current contents displayed by paintable
.
This is useful when you want to retain the current state of an animation, for example to take a screenshot of a running animation.
If the paintable
is already immutable, it will return itself.
gdk_paintable_snapshot ()
void gdk_paintable_snapshot (GdkPaintable *paintable,GdkSnapshot *snapshot,double width,double height);
Snapshots the given paintable with the given width
and height
at the
current (0,0) offset of the snapshot
. If width
and height
are not larger
than zero, this function will do nothing.
gdk_paintable_get_flags ()
GdkPaintableFlags
gdk_paintable_get_flags (GdkPaintable *paintable);
Get flags for the paintable. This is oftentimes useful for optimizations.
See GdkPaintableFlags for the flags and what they mean.
gdk_paintable_get_intrinsic_width ()
int
gdk_paintable_get_intrinsic_width (GdkPaintable *paintable);
Gets the preferred width the paintable
would like to be displayed at.
Consumers of this interface can use this to reserve enough space to draw
the paintable.
This is a purely informational value and does not in any way limit the values
that may be passed to gdk_paintable_snapshot().
If the paintable
does not have a preferred width, it returns 0. Negative
values are never returned.
gdk_paintable_get_intrinsic_height ()
int
gdk_paintable_get_intrinsic_height (GdkPaintable *paintable);
Gets the preferred height the paintable
would like to be displayed at.
Consumers of this interface can use this to reserve enough space to draw
the paintable.
This is a purely informational value and does not in any way limit the values
that may be passed to gdk_paintable_snapshot().
If the paintable
does not have a preferred height, it returns 0. Negative
values are never returned.
gdk_paintable_get_intrinsic_aspect_ratio ()
double
gdk_paintable_get_intrinsic_aspect_ratio
(GdkPaintable *paintable);
Gets the preferred aspect ratio the paintable
would like to be displayed at.
The aspect ration is the width divided by the height, so a value of 0.5 means
that the paintable
prefers to be displayed twice as high as it is wide.
Consumers of this interface can use this to preserve aspect ratio when displaying
this paintable.
This is a purely informational value and does not in any way limit the values
that may be passed to gdk_paintable_snapshot().
Usually when a paintable
returns non-0 values from
gdk_paintable_get_intrinsic_width() and gdk_paintable_get_intrinsic_height()
the aspect ratio should conform to those values, though that is not required.
If the paintable
does not have a preferred aspect ratio, it returns 0.0.
Negative values are never returned.
gdk_paintable_compute_concrete_size ()
void gdk_paintable_compute_concrete_size (GdkPaintable *paintable,double specified_width,double specified_height,double default_width,double default_height,double *concrete_width,double *concrete_height);
Applies the sizing algorithm outlined in
https://drafts.csswg.org/css-images-3/default-sizing
to the given paintable
. See that link for more details.
It is not necessary to call this function when both specified_width
and specified_height
are known, but it is useful to call this
function in GtkWidget:measure implementations to compute the
other dimension when only one dimension is given.
Parameters
paintable |
||
specified_width |
the width |
|
specified_height |
the height |
|
default_width |
the width |
|
default_height |
the height |
|
concrete_width |
will be set to the concrete width computed. |
[out] |
concrete_height |
will be set to the concrete height computed. |
[out] |
gdk_paintable_invalidate_contents ()
void
gdk_paintable_invalidate_contents (GdkPaintable *paintable);
Called by implementations of GdkPaintable to invalidate their contents. Unless the contents are invalidated, implementations must guarantee that multiple calls to GdkPaintable::snapshot produce the same output.
This function will emit the GdkPaintable::invalidate-contents signal.
If a paintable
reports the GDK_PAINTABLE_STATIC_CONTENTS flag,
it must not call this function.
gdk_paintable_invalidate_size ()
void
gdk_paintable_invalidate_size (GdkPaintable *paintable);
Called by implementations of GdkPaintable to invalidate their size.
As long as the size is not invalidated, paintable
must return the same values
for its width, height and intrinsic height.
This function will emit the GdkPaintable::invalidate-size signal.
If a paintable
reports the GDK_PAINTABLE_STATIC_SIZE flag,
it must not call this function.
gdk_paintable_new_empty ()
GdkPaintable * gdk_paintable_new_empty (int intrinsic_width,int intrinsic_height);
Returns a paintable that has the given intrinsic size and draws nothing.
This is often useful for implementing the GdkPaintableClass:get_current_image()
virtual function when the paintable is in an incomplete state (like a
GtkMediaStream before receiving the first frame).
Types and Values
Signal Details
The “invalidate-contents” signal
void user_function (GdkPaintable *paintable, gpointer user_data)
Emitted when the contents of the paintable
change.
Examples for such an event would be videos changing to the next frame or the icon theme for an icon changing.
Flags: Run Last
The “invalidate-size” signal
void user_function (GdkPaintable *paintable, gpointer user_data)
Emitted when the intrinsic size of the paintable
changes. This means the values
reported by at least one of gdk_paintable_get_intrinsic_width(),
gdk_paintable_get_intrinsic_height() or gdk_paintable_get_intrinsic_aspect_ratio()
has changed.
Examples for such an event would be a paintable displaying the contents of a toplevel surface being resized.
Flags: Run Last
| Top | |
|
|
|
Description
Pixbufs are client-side images. For details on how to create and manipulate pixbufs, see the GdkPixbuf API documentation.
The functions described here allow to obtain pixbufs from GdkSurfaces and cairo surfaces.
Functions
gdk_pixbuf_get_from_surface ()
GdkPixbuf * gdk_pixbuf_get_from_surface (cairo_surface_t *surface,gint src_x,gint src_y,gint width,gint height);
Transfers image data from a cairo_surface_t and converts it to an RGB(A) representation inside a GdkPixbuf. This allows you to efficiently read individual pixels from cairo surfaces.
This function will create an RGB pixbuf with 8 bits per channel.
The pixbuf will contain an alpha channel if the surface
contains one.
| Top | |
|
|
|
Functions
Properties
| GdkDevice * | associated-device | Read |
| GdkAxisFlags | axes | Read |
| GdkDisplay * | display | Read / Write / Construct Only |
| gboolean | has-cursor | Read / Write / Construct Only |
| GdkInputMode | input-mode | Read / Write |
| GdkInputSource | input-source | Read / Write / Construct Only |
| guint | n-axes | Read |
| gchar * | name | Read / Write / Construct Only |
| guint | num-touches | Read / Write / Construct Only |
| gchar * | product-id | Read / Write / Construct Only |
| GdkSeat * | seat | Read / Write |
| GdkDeviceTool * | tool | Read |
| GdkDeviceType | type | Read / Write / Construct Only |
| gchar * | vendor-id | Read / Write / Construct Only |
Types and Values
| GdkDevice | |
| enum | GdkInputSource |
| enum | GdkInputMode |
| enum | GdkAxisUse |
| enum | GdkAxisFlags |
| enum | GdkDeviceToolType |
| enum | GdkDeviceType |
| enum | GdkGrabOwnership |
| struct | GdkTimeCoord |
Description
The GdkDevice object represents a single input device, such as a keyboard, a mouse, a touchpad, etc.
See the GdkSeat documentation for more information about the various kinds of master and slave devices, and their relationships.
Functions
gdk_device_get_name ()
const gchar *
gdk_device_get_name (GdkDevice *device);
Determines the name of the device.
gdk_device_get_vendor_id ()
const gchar *
gdk_device_get_vendor_id (GdkDevice *device);
Returns the vendor ID of this device, or NULL if this information couldn't
be obtained. This ID is retrieved from the device, and is thus constant for
it.
This function, together with gdk_device_get_product_id(), can be used to eg.
compose GSettings paths to store settings for this device.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
static GSettings * get_device_settings (GdkDevice *device) { const gchar *vendor, *product; GSettings *settings; GdkDevice *device; gchar *path; vendor = gdk_device_get_vendor_id (device); product = gdk_device_get_product_id (device); path = g_strdup_printf ("/org/example/app/devices/%s:%s/", vendor, product); settings = g_settings_new_with_path (DEVICE_SCHEMA, path); g_free (path); return settings; } |
gdk_device_get_product_id ()
const gchar *
gdk_device_get_product_id (GdkDevice *device);
Returns the product ID of this device, or NULL if this information couldn't
be obtained. This ID is retrieved from the device, and is thus constant for
it. See gdk_device_get_vendor_id() for more information.
gdk_device_get_source ()
GdkInputSource
gdk_device_get_source (GdkDevice *device);
Determines the type of the device.
gdk_device_set_mode ()
gboolean gdk_device_set_mode (GdkDevice *device,GdkInputMode mode);
Sets a the mode of an input device. The mode controls if the device is active and whether the device’s range is mapped to the entire screen or to a single surface.
Note: This is only meaningful for floating devices, master devices (and slaves connected to these) drive the pointer cursor, which is not limited by the input mode.
gdk_device_get_mode ()
GdkInputMode
gdk_device_get_mode (GdkDevice *device);
Determines the mode of the device.
gdk_device_set_key ()
void gdk_device_set_key (GdkDevice *device,guint index_,guint keyval,GdkModifierType modifiers);
Specifies the X key event to generate when a macro button of a device is pressed.
gdk_device_get_key ()
gboolean gdk_device_get_key (GdkDevice *device,guint index_,guint *keyval,GdkModifierType *modifiers);
If index_
has a valid keyval, this function will return TRUE
and fill in keyval
and modifiers
with the keyval settings.
Parameters
device |
a GdkDevice. |
|
index_ |
the index of the macro button to get. |
|
keyval |
return value for the keyval. |
[out] |
modifiers |
return value for modifiers. |
[out] |
gdk_device_set_axis_use ()
void gdk_device_set_axis_use (GdkDevice *device,guint index_,GdkAxisUse use);
Specifies how an axis of a device is used.
Parameters
device |
a pointer GdkDevice |
|
index_ |
the index of the axis |
|
use |
specifies how the axis is used |
gdk_device_get_axis_use ()
GdkAxisUse gdk_device_get_axis_use (GdkDevice *device,guint index_);
Returns the axis use for index_
.
gdk_device_get_associated_device ()
GdkDevice *
gdk_device_get_associated_device (GdkDevice *device);
Returns the associated device to device
, if device
is of type
GDK_DEVICE_TYPE_MASTER, it will return the paired pointer or
keyboard.
If device
is of type GDK_DEVICE_TYPE_SLAVE, it will return
the master device to which device
is attached to.
If device
is of type GDK_DEVICE_TYPE_FLOATING, NULL will be
returned, as there is no associated device.
gdk_device_list_slave_devices ()
GList *
gdk_device_list_slave_devices (GdkDevice *device);
If the device if of type GDK_DEVICE_TYPE_MASTER, it will return
the list of slave devices attached to it, otherwise it will return
NULL
gdk_device_get_device_type ()
GdkDeviceType
gdk_device_get_device_type (GdkDevice *device);
Returns the device type for device
.
gdk_device_get_display ()
GdkDisplay *
gdk_device_get_display (GdkDevice *device);
Returns the GdkDisplay to which device
pertains.
Returns
a GdkDisplay. This memory is owned by GTK+, and must not be freed or unreffed.
[transfer none]
gdk_device_get_has_cursor ()
gboolean
gdk_device_get_has_cursor (GdkDevice *device);
Determines whether the pointer follows device motion. This is not meaningful for keyboard devices, which don't have a pointer.
gdk_device_get_n_axes ()
gint
gdk_device_get_n_axes (GdkDevice *device);
Returns the number of axes the device currently has.
gdk_device_get_n_keys ()
gint
gdk_device_get_n_keys (GdkDevice *device);
Returns the number of keys the device currently has.
gdk_device_get_axes ()
GdkAxisFlags
gdk_device_get_axes (GdkDevice *device);
Returns the axes currently available on the device.
gdk_device_get_seat ()
GdkSeat *
gdk_device_get_seat (GdkDevice *device);
Returns the GdkSeat the device belongs to.
gdk_device_get_state ()
void gdk_device_get_state (GdkDevice *device,GdkSurface *surface,gdouble *axes,GdkModifierType *mask);
Gets the current state of a pointer device relative to surface
. As a slave
device’s coordinates are those of its master pointer, this
function may not be called on devices of type GDK_DEVICE_TYPE_SLAVE,
unless there is an ongoing grab on them. See gdk_device_grab().
[skip]
Parameters
device |
a GdkDevice. |
|
surface |
a GdkSurface. |
|
axes |
an array of doubles to store the values of
the axes of |
[nullable][array] |
mask |
location to store the modifiers, or |
[optional][out] |
gdk_device_get_position ()
void gdk_device_get_position (GdkDevice *device,double *x,double *y);
Gets the current location of device
in double precision. As a slave device's
coordinates are those of its master pointer, this function
may not be called on devices of type GDK_DEVICE_TYPE_SLAVE,
unless there is an ongoing grab on them. See gdk_device_grab().
gdk_device_get_surface_at_position ()
GdkSurface * gdk_device_get_surface_at_position (GdkDevice *device,double *win_x,double *win_y);
Obtains the surface underneath device
, returning the location of the device in win_x
and win_y
in
double precision. Returns NULL if the surface tree under device
is not known to GDK (for example,
belongs to another application).
As a slave device coordinates are those of its master pointer, This
function may not be called on devices of type GDK_DEVICE_TYPE_SLAVE,
unless there is an ongoing grab on them, see gdk_device_grab().
Parameters
device |
pointer GdkDevice to query info to. |
|
win_x |
return location for the X coordinate of the device location,
relative to the surface origin, or |
[out][allow-none] |
win_y |
return location for the Y coordinate of the device location,
relative to the surface origin, or |
[out][allow-none] |
gdk_device_get_history ()
gboolean gdk_device_get_history (GdkDevice *device,GdkSurface *surface,guint32 start,guint32 stop,GdkTimeCoord ***events,gint *n_events);
Obtains the motion history for a pointer device; given a starting and
ending timestamp, return all events in the motion history for
the device in the given range of time. Some windowing systems
do not support motion history, in which case, FALSE will
be returned. (This is not distinguishable from the case where
motion history is supported and no events were found.)
Note that there is also gdk_surface_set_event_compression() to get
more motion events delivered directly, independent of the windowing
system.
[skip]
Parameters
device |
||
surface |
the surface with respect to which which the event coordinates will be reported |
|
start |
starting timestamp for range of events to return |
|
stop |
ending timestamp for the range of events to return |
|
events |
location to store a newly-allocated array of GdkTimeCoord, or
|
[array length=n_events][out][transfer full][optional] |
n_events |
location to store the length of
|
[out][optional] |
gdk_device_free_history ()
void gdk_device_free_history (GdkTimeCoord **events,gint n_events);
Frees an array of GdkTimeCoord that was returned by gdk_device_get_history().
[skip]
Parameters
events |
an array of GdkTimeCoord. |
[array length=n_events] |
n_events |
the length of the array. |
gdk_device_get_axis ()
gboolean gdk_device_get_axis (GdkDevice *device,gdouble *axes,GdkAxisUse use,gdouble *value);
Interprets an array of double as axis values for a given device, and locates the value in the array for a given axis use.
[skip]
gdk_device_list_axes ()
GList *
gdk_device_list_axes (GdkDevice *device);
Returns a GList of GdkAtoms, containing the labels for
the axes that device
currently has.
gdk_device_get_axis_value ()
gboolean gdk_device_get_axis_value (GdkDevice *device,gdouble *axes,GdkAtom axis_label,gdouble *value);
Interprets an array of double as axis values for a given device,
and locates the value in the array for a given axis label, as returned
by gdk_device_list_axes()
[skip]
Parameters
device |
a pointer GdkDevice. |
|
axes |
pointer to an array of axes. |
[array] |
axis_label |
name of the label |
|
value |
location to store the found value. |
[out] |
gdk_device_get_last_event_surface ()
GdkSurface *
gdk_device_get_last_event_surface (GdkDevice *device);
Gets information about which surface the given pointer device is in, based on events
that have been received so far from the display server. If another application
has a pointer grab, or this application has a grab with owner_events = FALSE,
NULL may be returned even if the pointer is physically over one of this
application's surfaces.
gdk_device_tool_get_serial ()
guint64
gdk_device_tool_get_serial (GdkDeviceTool *tool);
Gets the serial of this tool, this value can be used to identify a physical tool (eg. a tablet pen) across program executions.
gdk_device_tool_get_tool_type ()
GdkDeviceToolType
gdk_device_tool_get_tool_type (GdkDeviceTool *tool);
Gets the GdkDeviceToolType of the tool.
gdk_device_tool_get_hardware_id ()
guint64
gdk_device_tool_get_hardware_id (GdkDeviceTool *tool);
Gets the hardware ID of this tool, or 0 if it's not known. When
non-zero, the identificator is unique for the given tool model,
meaning that two identical tools will share the same hardware_id
,
but will have different serial numbers (see gdk_device_tool_get_serial()).
This is a more concrete (and device specific) method to identify
a GdkDeviceTool than gdk_device_tool_get_tool_type(), as a tablet
may support multiple devices with the same GdkDeviceToolType,
but having different hardware identificators.
Types and Values
GdkDevice
typedef struct _GdkDevice GdkDevice;
The GdkDevice struct contains only private fields and should not be accessed directly.
enum GdkInputSource
An enumeration describing the type of an input device in general terms.
Members
|
the device is a mouse. (This will be reported for the core pointer, even if it is something else, such as a trackball.) |
||
|
the device is a stylus of a graphics tablet or similar device. |
||
|
the device is an eraser. Typically, this would be the other end of a stylus on a graphics tablet. |
||
|
the device is a graphics tablet “puck” or similar device. |
||
|
the device is a keyboard. |
||
|
the device is a direct-input touch device, such as a touchscreen or tablet. This device type has been added in 3.4. |
||
|
the device is an indirect touch device, such as a touchpad. This device type has been added in 3.4. |
||
|
the device is a trackpoint. This device type has been added in 3.22 |
||
|
the device is a "pad", a collection of buttons, rings and strips found in drawing tablets. This device type has been added in 3.22. |
enum GdkInputMode
An enumeration that describes the mode of an input device.
Members
|
the device is disabled and will not report any events. |
||
|
the device is enabled. The device’s coordinate space maps to the entire screen. |
||
|
the device is enabled. The device’s coordinate space is mapped to a single surface. The manner in which this surface is chosen is undefined, but it will typically be the same way in which the focus surface for key events is determined. |
enum GdkAxisUse
An enumeration describing the way in which a device axis (valuator) maps onto the predefined valuator types that GTK understands.
Note that the X and Y axes are not really needed; pointer devices report their location via the x/y members of events regardless. Whether X and Y are present as axes depends on the GDK backend.
Members
|
the axis is ignored. |
||
|
the axis is used as the x axis. |
||
|
the axis is used as the y axis. |
||
|
the axis is used for pressure information. |
||
|
the axis is used for x tilt information. |
||
|
the axis is used for y tilt information. |
||
|
the axis is used for wheel information. |
||
|
the axis is used for pen/tablet distance information |
||
|
the axis is used for pen rotation information |
||
|
the axis is used for pen slider information |
||
|
a constant equal to the numerically highest axis value. |
enum GdkAxisFlags
Flags describing the current capabilities of a device/tool.
enum GdkDeviceToolType
Indicates the specific type of tool being used being a tablet. Such as an airbrush, pencil, etc.
struct GdkTimeCoord
struct GdkTimeCoord {
guint32 time;
gdouble axes[GDK_MAX_TIMECOORD_AXES];
};
A GdkTimeCoord stores a single event in a motion history.
Property Details
The “associated-device” property
“associated-device” GdkDevice *
Associated pointer or keyboard with this device, if any. Devices of type GDK_DEVICE_TYPE_MASTER
always come in keyboard/pointer pairs. Other device types will have a NULL associated device.
Flags: Read
The “display” property
“display” GdkDisplay *
The GdkDisplay the GdkDevice pertains to.
Flags: Read / Write / Construct Only
The “has-cursor” property
“has-cursor” gboolean
Whether the device is represented by a cursor on the screen. Devices of type
GDK_DEVICE_TYPE_MASTER will have TRUE here.
Flags: Read / Write / Construct Only
Default value: FALSE
The “input-mode” property
“input-mode” GdkInputMode
Input mode for the device.
Flags: Read / Write
Default value: GDK_MODE_DISABLED
The “input-source” property
“input-source” GdkInputSource
Source type for the device.
Flags: Read / Write / Construct Only
Default value: GDK_SOURCE_MOUSE
The “name” property
“name” gchar *
The device name.
Flags: Read / Write / Construct Only
Default value: NULL
The “num-touches” property
“num-touches” guint
The maximal number of concurrent touches on a touch device. Will be 0 if the device is not a touch device or if the number of touches is unknown.
Flags: Read / Write / Construct Only
Default value: 0
The “product-id” property
“product-id” gchar *
Product ID of this device, see gdk_device_get_product_id().
Flags: Read / Write / Construct Only
Default value: NULL
The “tool” property
“tool” GdkDeviceTool *
The tool that is currently used with this device.
Flags: Read
The “type” property
“type” GdkDeviceType
Device role in the device manager.
Flags: Read / Write / Construct Only
Default value: GDK_DEVICE_TYPE_MASTER
The “vendor-id” property
“vendor-id” gchar *
Vendor ID of this device, see gdk_device_get_vendor_id().
Flags: Read / Write / Construct Only
Default value: NULL
Signal Details
The “changed” signal
void user_function (GdkDevice *device, gpointer user_data)
The ::changed signal is emitted either when the GdkDevice has changed the number of either axes or keys. For example In X this will normally happen when the slave device routing events through the master device changes (for example, user switches from the USB mouse to a tablet), in that case the master device will change to reflect the new slave device axes and keys.
Parameters
device |
the GdkDevice that changed. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “tool-changed” signal
void user_function (GdkDevice *device, GdkDeviceTool *tool, gpointer user_data)
The ::tool-changed signal is emitted on pen/eraser GdkDevices whenever tools enter or leave proximity.
Parameters
device |
the GdkDevice that changed. |
|
tool |
The new current tool |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
|
|
|
|
A
B
C
D
E
F
G
I
K
M
N
P
R
S
T
U
V
W
X
| Top | |
|
|
|
Functions
| void | (*GdkSeatGrabPrepareFunc) () |
| GdkDisplay * | gdk_seat_get_display () |
| GdkGrabStatus | gdk_seat_grab () |
| void | gdk_seat_ungrab () |
| GdkSeatCapabilities | gdk_seat_get_capabilities () |
| GdkDevice * | gdk_seat_get_pointer () |
| GdkDevice * | gdk_seat_get_keyboard () |
| GList * | gdk_seat_get_slaves () |
| GList * | gdk_seat_get_master_pointers () |
Signals
| void | device-added | Run Last |
| void | device-removed | Run Last |
| void | tool-added | Run Last |
| void | tool-removed | Run Last |
Functions
GdkSeatGrabPrepareFunc ()
void (*GdkSeatGrabPrepareFunc) (GdkSeat *seat,GdkSurface *surface,gpointer user_data);
Type of the callback used to set up surface
so it can be
grabbed. A typical action would be ensuring the surface is
visible, although there's room for other initialization
actions.
Parameters
seat |
the GdkSeat being grabbed |
|
surface |
the GdkSurface being grabbed |
|
user_data |
user data passed in |
gdk_seat_get_display ()
GdkDisplay *
gdk_seat_get_display (GdkSeat *seat);
Returns the GdkDisplay this seat belongs to.
gdk_seat_grab ()
GdkGrabStatus gdk_seat_grab (GdkSeat *seat,GdkSurface *surface,GdkSeatCapabilities capabilities,gboolean owner_events,GdkCursor *cursor,const GdkEvent *event,GdkSeatGrabPrepareFunc prepare_func,gpointer prepare_func_data);
Grabs the seat so that all events corresponding to the given capabilities
are passed to this application until the seat is ungrabbed with gdk_seat_ungrab(),
or the surface becomes hidden. This overrides any previous grab on the
seat by this client.
As a rule of thumb, if a grab is desired over GDK_SEAT_CAPABILITY_POINTER,
all other "pointing" capabilities (eg. GDK_SEAT_CAPABILITY_TOUCH) should
be grabbed too, so the user is able to interact with all of those while
the grab holds, you should thus use GDK_SEAT_CAPABILITY_ALL_POINTING most
commonly.
Grabs are used for operations which need complete control over the events corresponding to the given capabilities. For example in GTK this is used for Drag and Drop operations, popup menus and such.
Note that if the event mask of a GdkSurface has selected both button press
and button release events, or touch begin and touch end, then a press event
will cause an automatic grab until the button is released, equivalent to a
grab on the surface with owner_events
set to TRUE. This is done because most
applications expect to receive paired press and release events.
If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the GdkEventGrabBroken events that are emitted when the grab ends unvoluntarily.
Parameters
seat |
a GdkSeat |
|
surface |
the GdkSurface which will own the grab |
|
capabilities |
capabilities that will be grabbed |
|
owner_events |
if |
|
cursor |
the cursor to display while the grab is active. If
this is |
[nullable] |
event |
the event that is triggering the grab, or |
[nullable] |
prepare_func |
function to
prepare the surface to be grabbed, it can be |
[nullable][scope call][closure prepare_func_data] |
prepare_func_data |
user data to pass to |
gdk_seat_ungrab ()
void
gdk_seat_ungrab (GdkSeat *seat);
Releases a grab added through gdk_seat_grab().
gdk_seat_get_capabilities ()
GdkSeatCapabilities
gdk_seat_get_capabilities (GdkSeat *seat);
Returns the capabilities this GdkSeat currently has.
gdk_seat_get_pointer ()
GdkDevice *
gdk_seat_get_pointer (GdkSeat *seat);
Returns the master device that routes pointer events.
Returns
a master GdkDevice with pointer capabilities. This object is owned by GTK and must not be freed.
[transfer none][nullable]
gdk_seat_get_keyboard ()
GdkDevice *
gdk_seat_get_keyboard (GdkSeat *seat);
Returns the master device that routes keyboard events.
Returns
a master GdkDevice with keyboard capabilities. This object is owned by GTK and must not be freed.
[transfer none][nullable]
gdk_seat_get_slaves ()
GList * gdk_seat_get_slaves (GdkSeat *seat,GdkSeatCapabilities capabilities);
Returns the slave devices that match the given capabilities.
Returns
A list of GdkDevices.
The list must be freed with g_list_free(), the elements are owned
by GDK and must not be freed.
[transfer container][element-type GdkDevice]
gdk_seat_get_master_pointers ()
GList * gdk_seat_get_master_pointers (GdkSeat *seat,GdkSeatCapabilities capabilities);
Returns all master pointers with the given capabilities driven by this seat
.
On most backends this function will return a list with a single element (meaning
that all input devices drive the same onscreen cursor).
In other backends where there can possibly be multiple foci (eg. wayland), this function will return all master GdkDevices that represent these.
Types and Values
GdkSeat
typedef struct _GdkSeat GdkSeat;
The GdkSeat struct contains only private fields and should not be accessed directly.
enum GdkSeatCapabilities
Flags describing the seat capabilities.
enum GdkGrabStatus
Returned by gdk_device_grab() to indicate success or the reason for the
failure of the grab attempt.
Members
|
the resource was successfully grabbed. |
||
|
the resource is actively grabbed by another client. |
||
|
the resource was grabbed more recently than the specified time. |
||
|
the grab surface or the |
||
|
the resource is frozen by an active grab of another client. |
||
|
the grab failed for some other reason |
Property Details
The “display” property
“display” GdkDisplay *
GdkDisplay of this seat.
Flags: Read / Write / Construct Only
Signal Details
The “device-added” signal
void user_function (GdkSeat *seat, GdkDevice *device, gpointer user_data)
The ::device-added signal is emitted when a new input device is related to this seat.
Parameters
seat |
the object on which the signal is emitted |
|
device |
the newly added GdkDevice. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “device-removed” signal
void user_function (GdkSeat *seat, GdkDevice *device, gpointer user_data)
The ::device-removed signal is emitted when an input device is removed (e.g. unplugged).
Parameters
seat |
the object on which the signal is emitted |
|
device |
the just removed GdkDevice. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “tool-added” signal
void user_function (GdkSeat *seat, GdkDeviceTool *tool, gpointer user_data)
The ::tool-added signal is emitted whenever a new tool is made known to the seat. The tool may later be assigned to a device (i.e. on proximity with a tablet). The device will emit the “tool-changed” signal accordingly.
A same tool may be used by several devices.
Parameters
seat |
the object on which the signal is emitted |
|
tool |
the new GdkDeviceTool known to the seat |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “tool-removed” signal
void user_function (GdkSeat *seat, GdkDeviceTool *tool, gpointer user_data)
This signal is emitted whenever a tool is no longer known
to this seat
.
Parameters
seat |
the object on which the signal is emitted |
|
tool |
the just removed GdkDeviceTool |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
| Top | |
|
|
|
Functions
| gint | gdk_device_pad_get_n_groups () |
| gint | gdk_device_pad_get_group_n_modes () |
| gint | gdk_device_pad_get_n_features () |
| gint | gdk_device_pad_get_feature_group () |
Description
GdkDevicePad is an interface implemented by devices of type
GDK_SOURCE_TABLET_PAD, it allows querying the features provided
by the pad device.
Tablet pads may contain one or more groups, each containing a subset
of the buttons/rings/strips available. gdk_device_pad_get_n_groups()
can be used to obtain the number of groups, gdk_device_pad_get_n_features()
and gdk_device_pad_get_feature_group() can be combined to find out the
number of buttons/rings/strips the device has, and how are they grouped.
Each of those groups have different modes, which may be used to map
each individual pad feature to multiple actions. Only one mode is
effective (current) for each given group, different groups may have
different current modes. The number of available modes in a group can
be found out through gdk_device_pad_get_group_n_modes(), and the current
mode for a given group will be notified through the GdkEventPadGroupMode
event.
Functions
gdk_device_pad_get_n_groups ()
gint
gdk_device_pad_get_n_groups (GdkDevicePad *pad);
Returns the number of groups this pad device has. Pads have at least one group. A pad group is a subcollection of buttons/strip/rings that is affected collectively by a same current mode.
gdk_device_pad_get_group_n_modes ()
gint gdk_device_pad_get_group_n_modes (GdkDevicePad *pad,gint group_idx);
Returns the number of modes that group
may have.
gdk_device_pad_get_n_features ()
gint gdk_device_pad_get_n_features (GdkDevicePad *pad,GdkDevicePadFeature feature);
Returns the number of features a tablet pad has.
gdk_device_pad_get_feature_group ()
gint gdk_device_pad_get_feature_group (GdkDevicePad *pad,GdkDevicePadFeature feature,gint feature_idx);
Returns the group the given feature
and idx
belong to,
or -1 if feature/index do not exist in pad
.
| Top | |
|
|
|
Functions
| GdkDisplay * | gdk_clipboard_get_display () |
| GdkContentFormats * | gdk_clipboard_get_formats () |
| gboolean | gdk_clipboard_is_local () |
| GdkContentProvider * | gdk_clipboard_get_content () |
| void | gdk_clipboard_store_async () |
| gboolean | gdk_clipboard_store_finish () |
| void | gdk_clipboard_read_async () |
| GInputStream * | gdk_clipboard_read_finish () |
| void | gdk_clipboard_read_value_async () |
| const GValue * | gdk_clipboard_read_value_finish () |
| void | gdk_clipboard_read_texture_async () |
| GdkTexture * | gdk_clipboard_read_texture_finish () |
| void | gdk_clipboard_read_text_async () |
| char * | gdk_clipboard_read_text_finish () |
| gboolean | gdk_clipboard_set_content () |
| void | gdk_clipboard_set () |
| void | gdk_clipboard_set_valist () |
| void | gdk_clipboard_set_value () |
| void | gdk_clipboard_set_text () |
| void | gdk_clipboard_set_texture () |
Properties
| GdkContentProvider * | content | Read |
| GdkDisplay * | display | Read / Write / Construct Only |
| GdkContentFormats * | formats | Read |
| gboolean | local | Read |
Description
The GdkClipboard object represents a clipboard of data shared between different applications or between different parts of the same application.
To get a GdkClipboard object, use gdk_display_get_clipboard() or
gdk_display_get_primary_clipboard(). You can find out about the data that
is currently available in a clipboard using gdk_clipboard_get_formats().
To make text or image data available in a clipboard, use gdk_clipboard_set_text() or
gdk_clipboard_set_texture(). For other data, you can use gdk_clipboard_set_content(),
which takes a GdkContentProvider object.
To read textual or image data from a clipboard, use gdk_clipboard_read_text_async() or
gdk_clipboard_read_texture_async(). For other data, use gdk_clipboard_read_async(),
which provides a GInputStream object.
Functions
gdk_clipboard_get_display ()
GdkDisplay *
gdk_clipboard_get_display (GdkClipboard *clipboard);
Gets the GdkDisplay that the clipboard was created for.
gdk_clipboard_get_formats ()
GdkContentFormats *
gdk_clipboard_get_formats (GdkClipboard *clipboard);
Gets the formats that the clipboard can provide its current contents in.
gdk_clipboard_is_local ()
gboolean
gdk_clipboard_is_local (GdkClipboard *clipboard);
Returns if the clipboard is local. A clipboard is considered local if it was last claimed by the running application.
Note that gdk_clipboard_get_content() may return NULL even on a local
clipboard. In this case the clipboard is empty.
gdk_clipboard_get_content ()
GdkContentProvider *
gdk_clipboard_get_content (GdkClipboard *clipboard);
Returns the GdkContentProvider currently set on clipboard
. If the
clipboard
is empty or its contents are not owned by the current process,
NULL will be returned.
gdk_clipboard_store_async ()
void gdk_clipboard_store_async (GdkClipboard *clipboard,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously instructs the clipboard
to store its contents remotely to
preserve them for later usage. If the clipboard is not local, this function
does nothing but report success.
This function is called automatically when gtk_main() or GtkApplication
exit, so you likely don't need to call it.
gdk_clipboard_store_finish ()
gboolean gdk_clipboard_store_finish (GdkClipboard *clipboard,GAsyncResult *result,GError **error);
Finishes an asynchronous clipboard store started with gdk_clipboard_store_async().
gdk_clipboard_read_async ()
void gdk_clipboard_read_async (GdkClipboard *clipboard,const char **mime_types,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously requests an input stream to read the clipboard
's
contents from. When the operation is finished callback
will be called.
You can then call gdk_clipboard_read_finish() to get the result of the
operation.
The clipboard will choose the most suitable mime type from the given list to fulfill the request, preferring the ones listed first.
Parameters
clipboard |
||
mime_types |
a |
|
io_priority |
the I/O priority of the request. |
|
cancellable |
optional GCancellable object, |
[nullable] |
callback |
callback to call when the request is satisfied. |
[scope async] |
user_data |
the data to pass to callback function. |
[closure] |
gdk_clipboard_read_finish ()
GInputStream * gdk_clipboard_read_finish (GdkClipboard *clipboard,GAsyncResult *result,const char **out_mime_type,GError **error);
Finishes an asynchronous clipboard read started with gdk_clipboard_read_async().
gdk_clipboard_read_value_async ()
void gdk_clipboard_read_value_async (GdkClipboard *clipboard,GType type,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously request the clipboard
contents converted to the given
type
. When the operation is finished callback
will be called.
You can then call gdk_clipboard_read_value_finish() to get the resulting
GValue.
For local clipboard contents that are available in the given GType, the
value will be copied directly. Otherwise, GDK will try to use
gdk_content_deserialize_async() to convert the clipboard's data.
gdk_clipboard_read_value_finish ()
const GValue * gdk_clipboard_read_value_finish (GdkClipboard *clipboard,GAsyncResult *result,GError **error);
Finishes an asynchronous clipboard read started with
gdk_clipboard_read_value_async().
gdk_clipboard_read_texture_async ()
void gdk_clipboard_read_texture_async (GdkClipboard *clipboard,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously request the clipboard
contents converted to a GdkPixbuf.
When the operation is finished callback
will be called. You can then
call gdk_clipboard_read_texture_finish() to get the result.
This is a simple wrapper around gdk_clipboard_read_value_async(). Use
that function or gdk_clipboard_read_async() directly if you need more
control over the operation.
gdk_clipboard_read_texture_finish ()
GdkTexture * gdk_clipboard_read_texture_finish (GdkClipboard *clipboard,GAsyncResult *result,GError **error);
Finishes an asynchronous clipboard read started with
gdk_clipboard_read_texture_async().
gdk_clipboard_read_text_async ()
void gdk_clipboard_read_text_async (GdkClipboard *clipboard,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously request the clipboard
contents converted to a string.
When the operation is finished callback
will be called. You can then
call gdk_clipboard_read_text_finish() to get the result.
This is a simple wrapper around gdk_clipboard_read_value_async(). Use
that function or gdk_clipboard_read_async() directly if you need more
control over the operation.
gdk_clipboard_read_text_finish ()
char * gdk_clipboard_read_text_finish (GdkClipboard *clipboard,GAsyncResult *result,GError **error);
Finishes an asynchronous clipboard read started with
gdk_clipboard_read_text_async().
gdk_clipboard_set_content ()
gboolean gdk_clipboard_set_content (GdkClipboard *clipboard,GdkContentProvider *provider);
Sets a new content provider on clipboard
. The clipboard will claim the
GdkDisplay's resources and advertise these new contents to other
applications.
In the rare case of a failure, this function will return FALSE. The
clipboard will then continue reporting its old contents and ignore
provider
.
If the contents are read by either an external application or the
clipboard
's read functions, clipboard
will select the best format to
transfer the contents and then request that format from provider
.
gdk_clipboard_set ()
void gdk_clipboard_set (GdkClipboard *clipboard,GType type,...);
Sets the clipboard to contain the value collected from the given varargs.
gdk_clipboard_set_valist ()
void gdk_clipboard_set_valist (GdkClipboard *clipboard,GType type,va_list args);
Sets the clipboard to contain the value collected from the given
args
.
[skip]
gdk_clipboard_set_value ()
void gdk_clipboard_set_value (GdkClipboard *clipboard,const GValue *value);
Sets the clipboard
to contain the given value
.
[rename-to gdk_clipboard_set]
gdk_clipboard_set_text ()
void gdk_clipboard_set_text (GdkClipboard *clipboard,const char *text);
Puts the given text
into the clipboard.
[skip]
gdk_clipboard_set_texture ()
void gdk_clipboard_set_texture (GdkClipboard *clipboard,GdkTexture *texture);
Puts the given texture
into the clipboard.
[skip]
Property Details
The “content” property
“content” GdkContentProvider *
The GdkContentProvider or NULL if the clipboard is empty or contents are
provided otherwise.
Flags: Read
The “display” property
“display” GdkDisplay *
The GdkDisplay that the clipboard belongs to.
Flags: Read / Write / Construct Only
The “formats” property
“formats” GdkContentFormats *
The possible formats that the clipboard can provide its data in.
Flags: Read
Signal Details
The “changed” signal
void user_function (GdkClipboard *clipboard, gpointer user_data)
The ::changed signal is emitted when the clipboard changes ownership.
Parameters
clipboard |
the object on which the signal was emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
| Top | |
|
|
|
Functions
| GdkFrameTimings * | gdk_frame_timings_ref () |
| void | gdk_frame_timings_unref () |
| gint64 | gdk_frame_timings_get_frame_counter () |
| gboolean | gdk_frame_timings_get_complete () |
| gint64 | gdk_frame_timings_get_frame_time () |
| gint64 | gdk_frame_timings_get_presentation_time () |
| gint64 | gdk_frame_timings_get_refresh_interval () |
| gint64 | gdk_frame_timings_get_predicted_presentation_time () |
Description
A GdkFrameTimings object holds timing information for a single frame
of the application’s displays. To retrieve GdkFrameTimings objects,
use gdk_frame_clock_get_timings() or gdk_frame_clock_get_current_timings().
The information in GdkFrameTimings is useful for precise synchronization
of video with the event or audio streams, and for measuring
quality metrics for the application’s display, such as latency and jitter.
Functions
gdk_frame_timings_ref ()
GdkFrameTimings *
gdk_frame_timings_ref (GdkFrameTimings *timings);
Increases the reference count of timings
.
gdk_frame_timings_unref ()
void
gdk_frame_timings_unref (GdkFrameTimings *timings);
Decreases the reference count of timings
. If timings
is no longer referenced, it will be freed.
gdk_frame_timings_get_frame_counter ()
gint64
gdk_frame_timings_get_frame_counter (GdkFrameTimings *timings);
Gets the frame counter value of the GdkFrameClock when this this frame was drawn.
gdk_frame_timings_get_complete ()
gboolean
gdk_frame_timings_get_complete (GdkFrameTimings *timings);
The timing information in a GdkFrameTimings is filled in
incrementally as the frame as drawn and passed off to the
window system for processing and display to the user. The
accessor functions for GdkFrameTimings can return 0 to
indicate an unavailable value for two reasons: either because
the information is not yet available, or because it isn't
available at all. Once gdk_frame_timings_get_complete() returns
TRUE for a frame, you can be certain that no further values
will become available and be stored in the GdkFrameTimings.
gdk_frame_timings_get_frame_time ()
gint64
gdk_frame_timings_get_frame_time (GdkFrameTimings *timings);
Returns the frame time for the frame. This is the time value
that is typically used to time animations for the frame. See
gdk_frame_clock_get_frame_time().
gdk_frame_timings_get_presentation_time ()
gint64
gdk_frame_timings_get_presentation_time
(GdkFrameTimings *timings);
Reurns the presentation time. This is the time at which the frame became visible to the user.
Returns
the time the frame was displayed to the user, in the
timescale of g_get_monotonic_time(), or 0 if no presentation
time is available. See gdk_frame_timings_get_complete()
gdk_frame_timings_get_refresh_interval ()
gint64
gdk_frame_timings_get_refresh_interval
(GdkFrameTimings *timings);
Gets the natural interval between presentation times for the display that this frame was displayed on. Frame presentation usually happens during the “vertical blanking interval”.
Returns
the refresh interval of the display, in microseconds,
or 0 if the refresh interval is not available.
See gdk_frame_timings_get_complete().
gdk_frame_timings_get_predicted_presentation_time ()
gint64
gdk_frame_timings_get_predicted_presentation_time
(GdkFrameTimings *timings);
Gets the predicted time at which this frame will be displayed. Although
no predicted time may be available, if one is available, it will
be available while the frame is being generated, in contrast to
gdk_frame_timings_get_presentation_time(), which is only available
after the frame has been presented. In general, if you are simply
animating, you should use gdk_frame_clock_get_frame_time() rather
than this function, but this function is useful for applications
that want exact control over latency. For example, a movie player
may want this information for Audio/Video synchronization.
|
|
|
|
Table of Contents
- General — Library initialization and miscellaneous functions
- GdkDisplayManager — Maintains a list of all open GdkDisplays
- GdkDisplay — Controls a set of monitors and their associated input devices
- GdkSeat — Object representing an user seat
- GdkDevice — Object representing an input device
- GtkDevicePad — Pad device interface
- GdkMonitor — Object representing an output
- Points and Rectangles — Simple graphical data types
- GdkTexture — Pixel data
- GdkPaintable — An interface for a paintable region
- RGBA Colors — RGBA colors
- Cursors — Named and texture cursors
- Surfaces — Onscreen display areas in the target window system
- Frame clock — Frame clock syncs painting to a window or display
- Frame timings — Object holding timing information for a single frame
- GdkDrawContext — Base class for draw contexts
- GdkGLContext — OpenGL draw context
- GdkVulkanContext — Vulkan draw context
- Events — Functions for handling events from the window system
- Key Values — Functions for manipulating keyboard codes
- Clipboards — Share data between applications for Copy-and-Paste
- Drag And Drop — Functions for controlling drag and drop handling
- Content Formats — Advertising and negotiating of content exchange formats
- GdkContentProvider — Provides content for data transfer between applications
- GdkContentSerializer — Serialize content for transfer
- GdkContentDeserializer — Deserialize content for transfer
- Properties and Atoms — Functions to manipulate properties on windows
- Application launching — Startup notification for applications
- GdkPixbuf Interaction — Functions for obtaining pixbufs
- Pango Interaction — Using Pango in GDK
- Cairo Interaction — Functions to support using cairo
- X Window System Interaction — X backend-specific functions
- Wayland Interaction — Wayland backend-specific functions
| Top | |
|
|
|
Functions
| void | (*GdkContentDeserializeFunc) () |
| const char * | gdk_content_deserializer_get_mime_type () |
| GType | gdk_content_deserializer_get_gtype () |
| GValue * | gdk_content_deserializer_get_value () |
| GInputStream * | gdk_content_deserializer_get_input_stream () |
| int | gdk_content_deserializer_get_priority () |
| GCancellable * | gdk_content_deserializer_get_cancellable () |
| gpointer | gdk_content_deserializer_get_user_data () |
| void | gdk_content_deserializer_set_task_data () |
| gpointer | gdk_content_deserializer_get_task_data () |
| void | gdk_content_deserializer_return_success () |
| void | gdk_content_deserializer_return_error () |
| void | gdk_content_register_deserializer () |
| void | gdk_content_deserialize_async () |
| gboolean | gdk_content_deserialize_finish () |
Description
A GdkContentDeserializer is used to deserialize content received via inter-application data transfers.
Functions
GdkContentDeserializeFunc ()
void
(*GdkContentDeserializeFunc) (GdkContentDeserializer *deserializer);
The type of a function that can be registered with gdk_content_register_deserializer().
When the function gets called to operate on content, it can call functions on the
deserializer
object to obtain the mime type, input stream, user data, etc. for its
operation.
gdk_content_deserializer_get_mime_type ()
const char *
gdk_content_deserializer_get_mime_type
(GdkContentDeserializer *deserializer);
Gets the mime type to deserialize from.
gdk_content_deserializer_get_gtype ()
GType
gdk_content_deserializer_get_gtype (GdkContentDeserializer *deserializer);
Gets the GType to create an instance of.
gdk_content_deserializer_get_value ()
GValue *
gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer);
Gets the GValue to store the deserialized object in.
gdk_content_deserializer_get_input_stream ()
GInputStream *
gdk_content_deserializer_get_input_stream
(GdkContentDeserializer *deserializer);
Gets the input stream that was passed to gdk_content_deserialize_async().
gdk_content_deserializer_get_priority ()
int
gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer);
Gets the io priority that was passed to gdk_content_deserialize_async().
gdk_content_deserializer_get_cancellable ()
GCancellable *
gdk_content_deserializer_get_cancellable
(GdkContentDeserializer *deserializer);
Gets the cancellable that was passed to gdk_content_deserialize_async().
gdk_content_deserializer_get_user_data ()
gpointer
gdk_content_deserializer_get_user_data
(GdkContentDeserializer *deserializer);
Gets the user data that was passed when the deserializer was registered.
gdk_content_deserializer_set_task_data ()
void gdk_content_deserializer_set_task_data (GdkContentDeserializer *deserializer,gpointer data,GDestroyNotify notify);
Associate data with the current deserialization operation.
gdk_content_deserializer_get_task_data ()
gpointer
gdk_content_deserializer_get_task_data
(GdkContentDeserializer *deserializer);
Gets the data that was associated with deserializer
via gdk_content_deserializer_set_task_data().
gdk_content_deserializer_return_success ()
void
gdk_content_deserializer_return_success
(GdkContentDeserializer *deserializer);
Indicate that the deserialization has been successfully completed.
gdk_content_deserializer_return_error ()
void gdk_content_deserializer_return_error (GdkContentDeserializer *deserializer,GError *error);
Indicate that the deserialization has ended with an error.
This function consumes error
.
gdk_content_register_deserializer ()
void gdk_content_register_deserializer (const char *mime_type,GType type,GdkContentDeserializeFunc deserialize,gpointer data,GDestroyNotify notify);
Registers a function to create objects of a given type
from
a serialized representation with the given mime type.
gdk_content_deserialize_async ()
void gdk_content_deserialize_async (GInputStream *stream,const char *mime_type,GType type,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Read content from the given input stream and deserialize it, asynchronously.
When the operation is finished, callback
will be called. You can then
call gdk_content_deserialize_finish() to get the result of the operation.
Parameters
stream |
a GInputStream to read the serialized content from |
|
mime_type |
the mime type to deserialize from |
|
type |
the GType to deserialize from |
|
io_priority |
the io priority of the operation |
|
cancellable |
optional GCancellable object. |
[nullable] |
callback |
callback to call when the operation is done. |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
| Top | |
|
|
|
Description
Each window under X can have any number of associated “properties” attached to it. Properties are arbitrary chunks of data identified by “atom”s. (An “atom” is a numeric index into a string table on the X server. They are used to transfer strings efficiently between clients without having to transfer the entire string.) A property has an associated type, which is also identified using an atom.
A property has an associated “format”, an integer describing how many bits are in each unit of data inside the property. It must be 8, 16, or 32. When data is transferred between the server and client, if they are of different endianesses it will be byteswapped as necessary according to the format of the property. Note that on the client side, properties of format 32 will be stored with one unit per long, even if a long integer has more than 32 bits on the platform. (This decision was apparently made for Xlib to maintain compatibility with programs that assumed longs were 32 bits, at the expense of programs that knew better.)
The functions in this section are used to add, remove and change properties on windows, to convert atoms to and from strings and to manipulate some types of data commonly stored in X window properties.
Functions
gdk_text_property_to_utf8_list_for_display ()
gint gdk_text_property_to_utf8_list_for_display (GdkDisplay *display,GdkAtom encoding,gint format,const guchar *text,gint length,gchar ***list);
Converts a text property in the given encoding to a list of UTF-8 strings.
Parameters
display |
||
encoding |
an atom representing the encoding of the text |
|
format |
the format of the property |
|
text |
the text to convert. |
[array length=length] |
length |
the length of |
|
list |
location to store the list
of strings or |
[out][array zero-terminated=1] |
gdk_utf8_to_string_target ()
gchar *
gdk_utf8_to_string_target (const gchar *str);
Converts an UTF-8 string into the best possible representation as a STRING. The representation of characters not in STRING is not specified; it may be as pseudo-escape sequences \x{ABCD}, or it may be in some other form of approximation.
| Top | |
|
|
|
Functions
Types and Values
| GdkEvent | |
| enum | GdkEventType |
| enum | GdkEventMask |
| enum | GdkScrollDirection |
| enum | GdkCrossingMode |
| enum | GdkNotifyType |
| #define | GDK_CURRENT_TIME |
| #define | GDK_PRIORITY_EVENTS |
| #define | GDK_PRIORITY_REDRAW |
| #define | GDK_EVENT_PROPAGATE |
| #define | GDK_EVENT_STOP |
| #define | GDK_BUTTON_PRIMARY |
| #define | GDK_BUTTON_MIDDLE |
| #define | GDK_BUTTON_SECONDARY |
| GdkEventSequence |
Description
This section describes functions dealing with events from the window system.
In GTK+ applications the events are handled automatically in
gtk_main_do_event() and passed on to the appropriate widgets,
so these functions are rarely needed.
Functions
gdk_event_new ()
GdkEvent *
gdk_event_new (GdkEventType type);
Creates a new event of the given type. All fields are set to 0.
gdk_event_copy ()
GdkEvent *
gdk_event_copy (const GdkEvent *event);
Copies a GdkEvent, copying or incrementing the reference count of the resources associated with it (e.g. GdkSurface’s and strings).
gdk_event_get_axes ()
gboolean gdk_event_get_axes (GdkEvent *event,gdouble **axes,guint *n_axes);
Extracts all axis values from an event.
Parameters
event |
a GdkEvent |
|
axes |
the array of values for all axes. |
[transfer none][out][array length=n_axes] |
n_axes |
the length of array. |
[out] |
gdk_event_get_axis ()
gboolean gdk_event_get_axis (const GdkEvent *event,GdkAxisUse axis_use,gdouble *value);
Extract the axis value for a particular axis use from an event structure.
Parameters
event |
a GdkEvent |
|
axis_use |
the axis use to look for |
|
value |
location to store the value found. |
[out] |
gdk_event_get_button ()
gboolean gdk_event_get_button (const GdkEvent *event,guint *button);
Extract the button number from an event.
gdk_event_get_click_count ()
gboolean gdk_event_get_click_count (const GdkEvent *event,guint *click_count);
Extracts the click count from an event.
gdk_event_get_coords ()
gboolean gdk_event_get_coords (const GdkEvent *event,gdouble *x_win,gdouble *y_win);
Extract the event surface relative x/y coordinates from an event.
Parameters
event |
a GdkEvent |
|
x_win |
location to put event surface x coordinate. |
[out][optional] |
y_win |
location to put event surface y coordinate. |
[out][optional] |
gdk_event_get_keycode ()
gboolean gdk_event_get_keycode (const GdkEvent *event,guint16 *keycode);
Extracts the hardware keycode from an event.
Also see gdk_event_get_scancode().
gdk_event_get_keyval ()
gboolean gdk_event_get_keyval (const GdkEvent *event,guint *keyval);
Extracts the keyval from an event.
gdk_event_get_root_coords ()
gboolean gdk_event_get_root_coords (const GdkEvent *event,gdouble *x_root,gdouble *y_root);
Extract the root window relative x/y coordinates from an event.
Parameters
event |
a GdkEvent |
|
x_root |
location to put root window x coordinate. |
[out][optional] |
y_root |
location to put root window y coordinate. |
[out][optional] |
gdk_event_get_scroll_direction ()
gboolean gdk_event_get_scroll_direction (const GdkEvent *event,GdkScrollDirection *direction);
Extracts the scroll direction from an event.
gdk_event_get_scroll_deltas ()
gboolean gdk_event_get_scroll_deltas (const GdkEvent *event,gdouble *delta_x,gdouble *delta_y);
Retrieves the scroll deltas from a GdkEvent
Parameters
event |
a GdkEvent |
|
delta_x |
return location for X delta. |
[out] |
delta_y |
return location for Y delta. |
[out] |
gdk_event_is_scroll_stop_event ()
gboolean
gdk_event_is_scroll_stop_event (const GdkEvent *event);
Check whether a scroll event is a stop scroll event. Scroll sequences with smooth scroll information may provide a stop scroll event once the interaction with the device finishes, e.g. by lifting a finger. This stop scroll event is the signal that a widget may trigger kinetic scrolling based on the current velocity.
Stop scroll events always have a a delta of 0/0.
gdk_event_get_state ()
gboolean gdk_event_get_state (const GdkEvent *event,GdkModifierType *state);
If the event contains a “state” field, puts that field in state
.
Otherwise stores an empty state (0).
event
may be NULL, in which case it’s treated
as if the event had no state field.
gdk_event_get_time ()
guint32
gdk_event_get_time (const GdkEvent *event);
Returns the time stamp from event
, if there is one; otherwise
returns GDK_CURRENT_TIME. If event
is NULL, returns GDK_CURRENT_TIME.
gdk_event_get_surface ()
GdkSurface *
gdk_event_get_surface (const GdkEvent *event);
Extracts the GdkSurface associated with an event.
gdk_event_get_event_type ()
GdkEventType
gdk_event_get_event_type (const GdkEvent *event);
Retrieves the type of the event.
gdk_event_get_event_sequence ()
GdkEventSequence *
gdk_event_get_event_sequence (const GdkEvent *event);
If event
if of type GDK_TOUCH_BEGIN, GDK_TOUCH_UPDATE,
GDK_TOUCH_END or GDK_TOUCH_CANCEL, returns the GdkEventSequence
to which the event belongs. Otherwise, return NULL.
gdk_events_get_angle ()
gboolean gdk_events_get_angle (GdkEvent *event1,GdkEvent *event2,gdouble *angle);
If both events contain X/Y information, this function will return TRUE
and return in angle
the relative angle from event1
to event2
. The rotation
direction for positive angles is from the positive X axis towards the positive
Y axis.
gdk_events_get_center ()
gboolean gdk_events_get_center (GdkEvent *event1,GdkEvent *event2,gdouble *x,gdouble *y);
If both events contain X/Y information, the center of both coordinates
will be returned in x
and y
.
gdk_events_get_distance ()
gboolean gdk_events_get_distance (GdkEvent *event1,GdkEvent *event2,gdouble *distance);
If both events have X/Y information, the distance between both coordinates
(as in a straight line going from event1
to event2
) will be returned.
gdk_event_triggers_context_menu ()
gboolean
gdk_event_triggers_context_menu (const GdkEvent *event);
This function returns whether a GdkEventButton should trigger a
context menu, according to platform conventions. The right mouse
button always triggers context menus. Additionally, if
gdk_keymap_get_modifier_mask() returns a non-0 mask for
GDK_MODIFIER_INTENT_CONTEXT_MENU, then the left mouse button will
also trigger a context menu if this modifier is pressed.
This function should always be used instead of simply checking for
event->button == GDK_BUTTON_SECONDARY.
gdk_event_get_seat ()
GdkSeat *
gdk_event_get_seat (const GdkEvent *event);
Returns the GdkSeat this event was generated for.
gdk_event_get_scancode ()
int
gdk_event_get_scancode (GdkEvent *event);
Gets the keyboard low-level scancode of a key event.
This is usually hardware_keycode. On Windows this is the high word of WM_KEY{DOWN,UP} lParam which contains the scancode and some extended flags.
gdk_event_get_pointer_emulated ()
gboolean
gdk_event_get_pointer_emulated (GdkEvent *event);
Returns whether this event is an 'emulated' pointer event (typically from a touch event), as opposed to a real one.
gdk_event_get_crossing_detail ()
gboolean gdk_event_get_crossing_detail (const GdkEvent *event,GdkNotifyType *detail);
Extracts the crossing detail from an event.
gdk_event_get_crossing_mode ()
gboolean gdk_event_get_crossing_mode (const GdkEvent *event,GdkCrossingMode *mode);
Extracts the crossing mode from an event.
gdk_event_get_drop ()
GdkDrop *
gdk_event_get_drop (const GdkEvent *event);
Gets the GdkDrop from a DND event.
gdk_event_get_focus_in ()
gboolean gdk_event_get_focus_in (const GdkEvent *event,gboolean *focus_in);
Extracts whether this is a focus-in or focus-out event.
gdk_event_get_grab_surface ()
gboolean gdk_event_get_grab_surface (const GdkEvent *event,GdkSurface **surface);
Extracts the grab surface from a grab broken event.
gdk_event_get_motion_history ()
GList *
gdk_event_get_motion_history (const GdkEvent *event);
Retrieves the history of the event
motion, as a list of time and
coordinates.
gdk_event_get_key_group ()
gboolean gdk_event_get_key_group (const GdkEvent *event,guint *group);
Extracts the key group from an event.
gdk_event_get_key_is_modifier ()
gboolean gdk_event_get_key_is_modifier (const GdkEvent *event,gboolean *is_modifier);
Extracts whether the event is a key event for a modifier key.
gdk_event_get_pad_axis_value ()
gboolean gdk_event_get_pad_axis_value (const GdkEvent *event,guint *index,gdouble *value);
Extracts the information from a pad event.
Parameters
event |
a GdkEvent |
|
index |
Return location for the axis index. |
[out] |
value |
Return location for the axis value. |
[out] |
gdk_event_get_pad_button ()
gboolean gdk_event_get_pad_button (const GdkEvent *event,guint *button);
Extracts information about the pressed button from a pad event.
gdk_event_get_pad_group_mode ()
gboolean gdk_event_get_pad_group_mode (const GdkEvent *event,guint *group,guint *mode);
Extracts group and mode information from a pad event.
Parameters
event |
a GdkEvent |
|
group |
return location for the group. |
[out] |
mode |
return location for the mode. |
[out] |
gdk_event_get_touch_emulating_pointer ()
gboolean gdk_event_get_touch_emulating_pointer (const GdkEvent *event,gboolean *emulating);
Extracts whether a touch event is emulating a pointer event.
gdk_event_get_touchpad_angle_delta ()
gboolean gdk_event_get_touchpad_angle_delta (const GdkEvent *event,double *delta);
Extracts the angle from a touchpad event.
gdk_event_get_touchpad_deltas ()
gboolean gdk_event_get_touchpad_deltas (const GdkEvent *event,double *dx,double *dy);
Extracts delta information from a touchpad event.
gdk_event_get_touchpad_gesture_n_fingers ()
gboolean gdk_event_get_touchpad_gesture_n_fingers (const GdkEvent *event,guint *n_fingers);
Extracts the number of fingers from a touchpad event.
gdk_event_get_touchpad_gesture_phase ()
gboolean gdk_event_get_touchpad_gesture_phase (const GdkEvent *event,GdkTouchpadGesturePhase *phase);
Extracts the touchpad gesture phase from a touchpad event.
gdk_event_get_touchpad_scale ()
gboolean gdk_event_get_touchpad_scale (const GdkEvent *event,double *scale);
Extracts the scale from a touchpad event.
gdk_event_is_sent ()
gboolean
gdk_event_is_sent (const GdkEvent *event);
Returns whether the event was sent explicitly.
gdk_get_show_events ()
gboolean
gdk_get_show_events (void);
Gets whether event debugging output is enabled.
gdk_set_show_events ()
void
gdk_set_show_events (gboolean show_events);
Sets whether a trace of received events is output.
Note that GTK+ must be compiled with debugging (that is,
configured using the --enable-debug option)
to use this option.
gdk_event_set_display ()
void gdk_event_set_display (GdkEvent *event,GdkDisplay *display);
Sets the display that an event is associated with.
gdk_event_get_display ()
GdkDisplay *
gdk_event_get_display (const GdkEvent *event);
Retrieves the GdkDisplay associated to the event
.
gdk_event_get_device ()
GdkDevice *
gdk_event_get_device (const GdkEvent *event);
If the event contains a “device” field, this function will return
it, else it will return NULL.
gdk_event_set_device ()
void gdk_event_set_device (GdkEvent *event,GdkDevice *device);
Sets the device for event
to device
. The event must
have been allocated by GTK+, for instance, by
gdk_event_copy().
gdk_event_get_source_device ()
GdkDevice *
gdk_event_get_source_device (const GdkEvent *event);
This function returns the hardware (slave) GdkDevice that has
triggered the event, falling back to the virtual (master) device
(as in gdk_event_get_device()) if the event wasn’t caused by
interaction with a hardware device. This may happen for example
in synthesized crossing events after a GdkSurface updates its
geometry or a grab is acquired/released.
If the event does not contain a device field, this function will
return NULL.
gdk_event_set_source_device ()
void gdk_event_set_source_device (GdkEvent *event,GdkDevice *device);
Sets the slave device for event
to device
.
The event must have been allocated by GTK+,
for instance by gdk_event_copy().
gdk_event_get_device_tool ()
GdkDeviceTool *
gdk_event_get_device_tool (const GdkEvent *event);
If the event was generated by a device that supports
different tools (eg. a tablet), this function will
return a GdkDeviceTool representing the tool that
caused the event. Otherwise, NULL will be returned.
Note: the GdkDeviceTool<!-- -->s will be constant during
the application lifetime, if settings must be stored
persistently across runs, see gdk_device_tool_get_serial()
Types and Values
enum GdkEventType
Specifies the type of the event.
Do not confuse these events with the signals that GTK+ widgets emit. Although many of these events result in corresponding signals being emitted, the events are often transformed or filtered along the way.
Members
|
a special code to indicate a null event. |
||
|
the window manager has requested that the toplevel surface be hidden or destroyed, usually when the user clicks on a special icon in the title bar. |
||
|
the surface has been destroyed. |
||
|
the pointer (usually a mouse) has moved. |
||
|
a mouse button has been pressed. |
||
|
a mouse button has been released. |
||
|
a key has been pressed. |
||
|
a key has been released. |
||
|
the pointer has entered the surface. |
||
|
the pointer has left the surface. |
||
|
the keyboard focus has entered or left the surface. |
||
|
the size, position or stacking order of the surface has changed.
Note that GTK+ discards these events for |
||
|
an input device has moved into contact with a sensing surface (e.g. a touchscreen or graphics tablet). |
||
|
an input device has moved out of contact with a sensing surface. |
||
|
the mouse has entered the surface while a drag is in progress. |
||
|
the mouse has left the surface while a drag is in progress. |
||
|
the mouse has moved in the surface while a drag is in progress. |
||
|
a drop operation onto the surface has started. |
||
|
the scroll wheel was turned |
||
|
a pointer or keyboard grab was broken. This event type was added in 2.8. |
||
|
A new touch event sequence has just started. This event type was added in 3.4. |
||
|
A touch event sequence has been updated. This event type was added in 3.4. |
||
|
A touch event sequence has finished. This event type was added in 3.4. |
||
|
A touch event sequence has been canceled. This event type was added in 3.4. |
||
|
A touchpad swipe gesture event, the current state is determined by its phase field. This event type was added in 3.18. |
||
|
A touchpad pinch gesture event, the current state is determined by its phase field. This event type was added in 3.18. |
||
|
A tablet pad button press event. This event type was added in 3.22. |
||
|
A tablet pad button release event. This event type was added in 3.22. |
||
|
A tablet pad axis event from a "ring". This event type was added in 3.22. |
||
|
A tablet pad axis event from a "strip". This event type was added in 3.22. |
||
|
A tablet pad group mode change. This event type was added in 3.22. |
||
|
marks the end of the GdkEventType enumeration. Added in 2.18 |
enum GdkEventMask
A set of bit-flags to indicate which events a surface is to receive. Most of these masks map onto one or more of the GdkEventType event types above.
See the input handling overview for details of event masks and event propagation.
If GDK_TOUCH_MASK is enabled, the surface will receive touch events
from touch-enabled devices. Those will come as sequences of GdkEventTouch
with type GDK_TOUCH_UPDATE, enclosed by two events with
type GDK_TOUCH_BEGIN and GDK_TOUCH_END (or GDK_TOUCH_CANCEL).
gdk_event_get_event_sequence() returns the event sequence for these
events, so different sequences may be distinguished.
Members
|
receive expose events |
||
|
receive all pointer motion events |
||
|
receive pointer motion events while any button is pressed |
||
|
receive pointer motion events while 1 button is pressed |
||
|
receive pointer motion events while 2 button is pressed |
||
|
receive pointer motion events while 3 button is pressed |
||
|
receive button press events |
||
|
receive button release events |
||
|
receive key press events |
||
|
receive key release events |
||
|
receive surface enter events |
||
|
receive surface leave events |
||
|
receive focus change events |
||
|
receive events about surface configuration change |
||
|
receive property change events |
||
|
receive proximity in events |
||
|
receive proximity out events |
||
|
receive events about surface configuration changes of child surfaces |
||
|
receive scroll events |
||
|
receive touch events |
||
|
receive smooth scrolling events |
||
|
receive touchpad gesture events |
||
|
receive tablet pad events |
||
|
the combination of all the above event masks. |
enum GdkScrollDirection
Specifies the direction for scroll events.
Members
|
the surface is scrolled up. |
||
|
the surface is scrolled down. |
||
|
the surface is scrolled to the left. |
||
|
the surface is scrolled to the right. |
||
|
the scrolling is determined by the delta values
in scroll events. See |
enum GdkCrossingMode
Specifies the crossing mode for enter and leave events.
Members
|
crossing because of pointer motion. |
||
|
crossing because a grab is activated. |
||
|
crossing because a grab is deactivated. |
||
|
crossing because a GTK+ grab is activated. |
||
|
crossing because a GTK+ grab is deactivated. |
||
|
crossing because a GTK+ widget changed state (e.g. sensitivity). |
||
|
crossing because a touch sequence has begun, this event is synthetic as the pointer might have not left the surface. |
||
|
crossing because a touch sequence has ended, this event is synthetic as the pointer might have not left the surface. |
||
|
crossing because of a device switch (i.e. a mouse taking control of the pointer after a touch device), this event is synthetic as the pointer didn’t leave the surface. |
enum GdkNotifyType
Specifies the kind of crossing for enter and leave events.
See the X11 protocol specification of LeaveNotify for full details of crossing event generation.
Members
|
the surface is entered from an ancestor or left towards an ancestor. |
||
|
the pointer moves between an ancestor and an inferior of the surface. |
||
|
the surface is entered from an inferior or left towards an inferior. |
||
|
the surface is entered from or left towards a surface which is neither an ancestor nor an inferior. |
||
|
the pointer moves between two surfaces which are not ancestors of each other and the surface is part of the ancestor chain between one of these surfaces and their least common ancestor. |
||
|
an unknown type of enter/leave event occurred. |
GDK_CURRENT_TIME
#define GDK_CURRENT_TIME 0L
Represents the current time, and can be used anywhere a time is expected.
GDK_PRIORITY_EVENTS
#define GDK_PRIORITY_EVENTS (G_PRIORITY_DEFAULT)
This is the priority that events from the X server are given in the GLib Main Loop.
GDK_PRIORITY_REDRAW
#define GDK_PRIORITY_REDRAW (G_PRIORITY_HIGH_IDLE + 20)
This is the priority that the idle handler processing surface updates is given in the GLib Main Loop.
GDK_EVENT_PROPAGATE
#define GDK_EVENT_PROPAGATE (FALSE)
Use this macro as the return value for continuing the propagation of an event handler.
GDK_EVENT_STOP
#define GDK_EVENT_STOP (TRUE)
Use this macro as the return value for stopping the propagation of an event handler.
GDK_BUTTON_PRIMARY
#define GDK_BUTTON_PRIMARY (1)
The primary button. This is typically the left mouse button, or the right button in a left-handed setup.
GDK_BUTTON_SECONDARY
#define GDK_BUTTON_SECONDARY (3)
The secondary button. This is typically the right mouse button, or the left button in a left-handed setup.
Property Details
The “event-type” property
“event-type” GdkEventType
Event type.
Flags: Read / Write / Construct Only
Default value: GDK_NOTHING
| Top | |
|
|
|
Functions
| struct wl_seat * | gdk_wayland_seat_get_wl_seat () |
| struct wl_keyboard * | gdk_wayland_device_get_wl_keyboard () |
| struct wl_pointer * | gdk_wayland_device_get_wl_pointer () |
| struct wl_seat * | gdk_wayland_device_get_wl_seat () |
| struct wl_compositor * | gdk_wayland_display_get_wl_compositor () |
| struct wl_display * | gdk_wayland_display_get_wl_display () |
| gboolean | gdk_wayland_display_query_registry () |
| struct wl_surface * | gdk_wayland_surface_get_wl_surface () |
| void | (*GdkWaylandSurfaceExported) () |
| gboolean | gdk_wayland_surface_export_handle () |
| void | gdk_wayland_surface_unexport_handle () |
| gboolean | gdk_wayland_surface_set_transient_for_exported () |
Description
The functions in this section are specific to the GDK Wayland backend.
To use them, you need to include the <gdk/gdkwayland.h> header and use
the Wayland-specific pkg-config gtk4-wayland file to build your application.
To make your code compile with other GDK backends, guard backend-specific
calls by an ifdef as follows. Since GDK may be built with multiple
backends, you should also check for the backend that is in use (e.g. by
using the GDK_IS_WAYLAND_DISPLAY() macro).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
#ifdef GDK_WINDOWING_WAYLAND if (GDK_IS_WAYLAND_DISPLAY (display)) { // make Wayland-specific calls here } else #endif #ifdef GDK_WINDOWING_X11 if (GDK_IS_X11_DISPLAY (display)) { // make X11-specific calls here } else #endif g_error ("Unsupported GDK backend"); |
Functions
gdk_wayland_seat_get_wl_seat ()
struct wl_seat *
gdk_wayland_seat_get_wl_seat (GdkSeat *seat);
Returns the Wayland wl_seat of a GdkSeat.
gdk_wayland_device_get_wl_keyboard ()
struct wl_keyboard *
gdk_wayland_device_get_wl_keyboard (GdkDevice *device);
Returns the Wayland wl_keyboard of a GdkDevice.
gdk_wayland_device_get_wl_pointer ()
struct wl_pointer *
gdk_wayland_device_get_wl_pointer (GdkDevice *device);
Returns the Wayland wl_pointer of a GdkDevice.
gdk_wayland_device_get_wl_seat ()
struct wl_seat *
gdk_wayland_device_get_wl_seat (GdkDevice *device);
Returns the Wayland wl_seat of a GdkDevice.
gdk_wayland_display_get_wl_compositor ()
struct wl_compositor *
gdk_wayland_display_get_wl_compositor (GdkDisplay *display);
Returns the Wayland global singleton compositor of a GdkDisplay.
gdk_wayland_display_get_wl_display ()
struct wl_display *
gdk_wayland_display_get_wl_display (GdkDisplay *display);
Returns the Wayland wl_display of a GdkDisplay.
gdk_wayland_display_query_registry ()
gboolean gdk_wayland_display_query_registry (GdkDisplay *display,const gchar *global);
Returns TRUE if the the interface was found in the display
wl_registry.global handler.
gdk_wayland_surface_get_wl_surface ()
struct wl_surface *
gdk_wayland_surface_get_wl_surface (GdkSurface *surface);
Returns the Wayland surface of a GdkSurface.
GdkWaylandSurfaceExported ()
void (*GdkWaylandSurfaceExported) (GdkSurface *surface,const char *handle,gpointer user_data);
Callback that gets called when the handle for a surface has been obtained from the Wayland compositor. The handle can be passed to other processes, for the purpose of marking surfaces as transient for out-of-process surfaces.
Parameters
surface |
the GdkSurface that is exported |
|
handle |
the handle |
|
user_data |
user data that was passed to |
gdk_wayland_surface_export_handle ()
gboolean gdk_wayland_surface_export_handle (GdkSurface *surface,GdkWaylandSurfaceExported callback,gpointer user_data,GDestroyNotify destroy_func);
Asynchronously obtains a handle for a surface that can be passed
to other processes. When the handle has been obtained, callback
will be called.
It is an error to call this function on a surface that is already exported.
When the handle is no longer needed, gdk_wayland_surface_unexport_handle()
should be called to clean up resources.
The main purpose for obtaining a handle is to mark a surface
from another surface as transient for this one, see
gdk_wayland_surface_set_transient_for_exported().
Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future.
Parameters
surface |
the GdkSurface to obtain a handle for |
|
callback |
callback to call with the handle |
|
user_data |
user data for |
|
destroy_func |
destroy notify for |
gdk_wayland_surface_unexport_handle ()
void
gdk_wayland_surface_unexport_handle (GdkSurface *surface);
Destroys the handle that was obtained with
gdk_wayland_surface_export_handle().
It is an error to call this function on a surface that does not have a handle.
Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future.
gdk_wayland_surface_set_transient_for_exported ()
gboolean gdk_wayland_surface_set_transient_for_exported (GdkSurface *surface,char *parent_handle_str);
Marks surface
as transient for the surface to which the given
parent_handle_str
refers. Typically, the handle will originate
from a gdk_wayland_surface_export_handle() call in another process.
Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future.
Parameters
surface |
the GdkSurface to make as transient |
|
parent_handle_str |
an exported handle for a surface |
| Top | |
|
|
|
Functions
Signals
| void | closed | Run Last |
| void | monitor-added | Run Last |
| void | monitor-removed | Run Last |
| void | opened | Run Last |
| void | seat-added | Run Last |
| void | seat-removed | Run Last |
| void | setting-changed | Run Last |
Description
GdkDisplay objects are the GDK representation of a workstation.
Their purpose are two-fold:
To manage and provide information about input devices (pointers, keyboards, etc)
To manage and provide information about output devices (monitors, projectors, etc)
Most of the input device handling has been factored out into separate GdkSeat
objects. Every display has a one or more seats, which can be accessed with
gdk_display_get_default_seat() and gdk_display_list_seats().
Output devices are represented by GdkMonitor objects, which can be accessed
with gdk_display_get_monitor() and similar APIs.
Functions
gdk_display_get_default ()
GdkDisplay *
gdk_display_get_default (void);
Gets the default GdkDisplay. This is a convenience
function for:
gdk_display_manager_get_default_display (.gdk_display_manager_get())
gdk_display_get_name ()
const gchar *
gdk_display_get_name (GdkDisplay *display);
Gets the name of the display.
gdk_display_device_is_grabbed ()
gboolean gdk_display_device_is_grabbed (GdkDisplay *display,GdkDevice *device);
Returns TRUE if there is an ongoing grab on device
for display
.
gdk_display_sync ()
void
gdk_display_sync (GdkDisplay *display);
Flushes any requests queued for the windowing system and waits until all
requests have been handled. This is often used for making sure that the
display is synchronized with the current state of the program. Calling
gdk_display_sync() before gdk_error_trap_pop() makes sure that any errors
generated from earlier requests are handled before the error trap is
removed.
This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing.
gdk_display_flush ()
void
gdk_display_flush (GdkDisplay *display);
Flushes any requests queued for the windowing system; this happens automatically when the main loop blocks waiting for new events, but if your application is drawing without returning control to the main loop, you may need to call this function explicitly. A common case where this function needs to be called is when an application is executing drawing commands from a thread other than the thread where the main loop is running.
This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing.
gdk_display_close ()
void
gdk_display_close (GdkDisplay *display);
Closes the connection to the windowing system for the given display, and cleans up associated resources.
gdk_display_is_closed ()
gboolean
gdk_display_is_closed (GdkDisplay *display);
Finds out if the display has been closed.
gdk_display_get_event ()
GdkEvent *
gdk_display_get_event (GdkDisplay *display);
Gets the next GdkEvent to be processed for display
, fetching events from the
windowing system if necessary.
Returns
the next GdkEvent to be processed,
or NULL if no events are pending.
[nullable][transfer full]
gdk_display_peek_event ()
GdkEvent *
gdk_display_peek_event (GdkDisplay *display);
Gets a copy of the first GdkEvent in the display
’s event queue, without
removing the event from the queue. (Note that this function will
not get more events from the windowing system. It only checks the events
that have already been moved to the GDK event queue.)
gdk_display_put_event ()
void gdk_display_put_event (GdkDisplay *display,const GdkEvent *event);
Appends a copy of the given event onto the front of the event
queue for display
.
gdk_display_has_pending ()
gboolean
gdk_display_has_pending (GdkDisplay *display);
Returns whether the display has events that are waiting to be processed.
gdk_display_is_rgba ()
gboolean
gdk_display_is_rgba (GdkDisplay *display);
Returns wether surfaces on this display
are created with an
alpha channel.
Even if a TRUE is returned, it is possible that the
surface’s alpha channel won’t be honored when displaying the
surface on the screen: in particular, for X an appropriate
windowing manager and compositing manager must be running to
provide appropriate display. Use gdk_display_is_composited()
to check if that is the case.
For setting an overall opacity for a top-level surface, see
gdk_surface_set_opacity().
On modern displays, this value is always TRUE.
gdk_display_is_composited ()
gboolean
gdk_display_is_composited (GdkDisplay *display);
Returns whether surfaces can reasonably be expected to have
their alpha channel drawn correctly on the screen. Check
gdk_display_is_rgba() for wether the display supports an
alpha channel.
On X11 this function returns whether a compositing manager is
compositing on display
.
On modern displays, this value is always TRUE.
gdk_display_get_default_group ()
GdkSurface *
gdk_display_get_default_group (GdkDisplay *display);
Returns the default group leader surface for all toplevel surfaces
on display
. This surface is implicitly created by GDK.
See gdk_surface_set_group().
gdk_display_supports_shapes ()
gboolean
gdk_display_supports_shapes (GdkDisplay *display);
Returns TRUE if gdk_surface_shape_combine_mask() can
be used to create shaped windows on display
.
gdk_display_supports_input_shapes ()
gboolean
gdk_display_supports_input_shapes (GdkDisplay *display);
Returns TRUE if gdk_surface_input_shape_combine_mask() can
be used to modify the input shape of surfaces on display
.
gdk_display_get_app_launch_context ()
GdkAppLaunchContext *
gdk_display_get_app_launch_context (GdkDisplay *display);
Returns a GdkAppLaunchContext suitable for launching applications on the given display.
Returns
a new GdkAppLaunchContext for display
.
Free with g_object_unref() when done.
[transfer full]
gdk_display_notify_startup_complete ()
void gdk_display_notify_startup_complete (GdkDisplay *display,const gchar *startup_id);
Indicates to the GUI environment that the application has finished loading, using a given identifier.
GTK+ will call this function automatically for GtkWindow
with custom startup-notification identifier unless
gtk_window_set_auto_startup_notification() is called to
disable that feature.
gdk_display_get_default_seat ()
GdkSeat *
gdk_display_get_default_seat (GdkDisplay *display);
Returns the default GdkSeat for this display.
gdk_display_list_seats ()
GList *
gdk_display_list_seats (GdkDisplay *display);
Returns the list of seats known to display
.
gdk_display_get_n_monitors ()
int
gdk_display_get_n_monitors (GdkDisplay *display);
Gets the number of monitors that belong to display
.
The returned number is valid until the next emission of the “monitor-added” or “monitor-removed” signal.
gdk_display_get_monitor ()
GdkMonitor * gdk_display_get_monitor (GdkDisplay *display,int monitor_num);
Gets a monitor associated with this display.
Returns
the GdkMonitor, or NULL if
monitor_num
is not a valid monitor number.
[nullable][transfer none]
gdk_display_get_primary_monitor ()
GdkMonitor *
gdk_display_get_primary_monitor (GdkDisplay *display);
Gets the primary monitor for the display.
The primary monitor is considered the monitor where the “main desktop” lives. While normal application surfaces typically allow the window manager to place the surfaces, specialized desktop applications such as panels should place themselves on the primary monitor.
If no monitor is the designated primary monitor, any monitor
(usually the first) may be returned. To make sure there is a dedicated
primary monitor, use gdk_monitor_is_primary() on the returned monitor.
gdk_display_get_monitor_at_point ()
GdkMonitor * gdk_display_get_monitor_at_point (GdkDisplay *display,int x,int y);
Gets the monitor in which the point (x
, y
) is located,
or a nearby monitor if the point is not in any monitor.
gdk_display_get_monitor_at_surface ()
GdkMonitor * gdk_display_get_monitor_at_surface (GdkDisplay *display,GdkSurface *surface);
Gets the monitor in which the largest area of surface
resides, or a monitor close to surface
if it is outside
of all monitors.
gdk_display_get_clipboard ()
GdkClipboard *
gdk_display_get_clipboard (GdkDisplay *display);
Gets the clipboard used for copy/paste operations.
gdk_display_get_primary_clipboard ()
GdkClipboard *
gdk_display_get_primary_clipboard (GdkDisplay *display);
Gets the clipboard used for the primary selection. On backends where the primary clipboard is not supported natively, GDK emulates this clipboard locally.
gdk_display_get_setting ()
gboolean gdk_display_get_setting (GdkDisplay *display,const char *name,GValue *value);
Retrieves a desktop-wide setting such as double-click time
for the display
.
gdk_display_get_keymap ()
GdkKeymap *
gdk_display_get_keymap (GdkDisplay *display);
Returns the GdkKeymap attached to display
.
Property Details
The “composited” property
“composited” gboolean
TRUE if the display properly composits the alpha channel.
See gdk_display_is_composited() for details.
Flags: Read
Default value: TRUE
The “rgba” property
“rgba” gboolean
TRUE if the display supports an alpha channel. See gdk_display_is_rgba()
for details.
Flags: Read
Default value: TRUE
Signal Details
The “closed” signal
void user_function (GdkDisplay *display, gboolean is_error, gpointer user_data)
The ::closed signal is emitted when the connection to the windowing
system for display
is closed.
Parameters
display |
the object on which the signal is emitted |
|
is_error |
|
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “monitor-added” signal
void user_function (GdkDisplay *display, GdkMonitor *monitor, gpointer user_data)
The ::monitor-added signal is emitted whenever a monitor is added.
Parameters
display |
the objedct on which the signal is emitted |
|
monitor |
the monitor that was just added |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “monitor-removed” signal
void user_function (GdkDisplay *display, GdkMonitor *monitor, gpointer user_data)
The ::monitor-removed signal is emitted whenever a monitor is removed.
Parameters
display |
the object on which the signal is emitted |
|
monitor |
the monitor that was just removed |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “opened” signal
void user_function (GdkDisplay *display, gpointer user_data)
The ::opened signal is emitted when the connection to the windowing
system for display
is opened.
Parameters
display |
the object on which the signal is emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “seat-added” signal
void user_function (GdkDisplay *display, GdkSeat *seat, gpointer user_data)
The ::seat-added signal is emitted whenever a new seat is made known to the windowing system.
Parameters
display |
the object on which the signal is emitted |
|
seat |
the seat that was just added |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “seat-removed” signal
void user_function (GdkDisplay *display, GdkSeat *seat, gpointer user_data)
The ::seat-removed signal is emitted whenever a seat is removed by the windowing system.
Parameters
display |
the object on which the signal is emitted |
|
seat |
the seat that was just removed |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “setting-changed” signal
void user_function (GdkDisplay *display, gchar *setting, gpointer user_data)
The ::setting-changed signal is emitted whenever a setting changes its value.
Parameters
display |
the object on which the signal is emitted |
|
setting |
the name of the setting that changed |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
| Top | |
|
|
|
Functions
| void | gdk_app_launch_context_set_desktop () |
| void | gdk_app_launch_context_set_timestamp () |
| void | gdk_app_launch_context_set_icon () |
| void | gdk_app_launch_context_set_icon_name () |
Description
GdkAppLaunchContext is an implementation of GAppLaunchContext that handles launching an application in a graphical context. It provides startup notification and allows to launch applications on a specific screen or workspace.
Launching an application
1 2 3 4 5 6 7 8 9 10 11 |
GdkAppLaunchContext *context; context = gdk_display_get_app_launch_context (display); gdk_app_launch_context_set_display (display); gdk_app_launch_context_set_timestamp (event->time); if (!g_app_info_launch_default_for_uri ("http://www.gtk.org", context, &error)) g_warning ("Launching failed: %s\n", error->message); g_object_unref (context); |
Functions
gdk_app_launch_context_set_desktop ()
void gdk_app_launch_context_set_desktop (GdkAppLaunchContext *context,gint desktop);
Sets the workspace on which applications will be launched when using this context when running under a window manager that supports multiple workspaces, as described in the Extended Window Manager Hints.
When the workspace is not specified or desktop
is set to -1,
it is up to the window manager to pick one, typically it will
be the current workspace.
gdk_app_launch_context_set_timestamp ()
void gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context,guint32 timestamp);
Sets the timestamp of context
. The timestamp should ideally
be taken from the event that triggered the launch.
Window managers can use this information to avoid moving the focus to the newly launched application when the user is busy typing in another window. This is also known as 'focus stealing prevention'.
gdk_app_launch_context_set_icon ()
void gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,GIcon *icon);
Sets the icon for applications that are launched with this context.
Window Managers can use this information when displaying startup notification.
See also gdk_app_launch_context_set_icon_name().
gdk_app_launch_context_set_icon_name ()
void gdk_app_launch_context_set_icon_name (GdkAppLaunchContext *context,const char *icon_name);
Sets the icon for applications that are launched with this context.
The icon_name
will be interpreted in the same way as the Icon field
in desktop files. See also gdk_app_launch_context_set_icon().
If both icon
and icon_name
are set, the icon_name
takes priority.
If neither icon
or icon_name
is set, the icon is taken from either
the file that is passed to launched application or from the GAppInfo
for the launched application itself.
| Top | |
|
|
|
Functions
| cairo_surface_t * | gdk_surface_create_similar_surface () |
| gboolean | gdk_cairo_get_clip_rectangle () |
| void | gdk_cairo_set_source_rgba () |
| void | gdk_cairo_set_source_pixbuf () |
| void | gdk_cairo_rectangle () |
| void | gdk_cairo_region () |
| cairo_region_t * | gdk_cairo_region_create_from_surface () |
| void | gdk_cairo_draw_from_gl () |
| void | gdk_cairo_surface_upload_to_gl () |
Description
Cairo is a graphics library that supports vector graphics and image compositing that can be used with GDK and GTK.
GDK does not wrap the cairo API, instead it allows to create cairo contexts which can be used to draw on GdkSurfaces. Additional functions allow use GdkRectangles with cairo and to use GdkRGBAs, GdkPixbufs and GdkSurfaces as sources for drawing operations.
Functions
gdk_surface_create_similar_surface ()
cairo_surface_t * gdk_surface_create_similar_surface (GdkSurface *surface,cairo_content_t content,int width,int height);
Create a new surface that is as compatible as possible with the
given surface
. For example the new surface will have the same
fallback resolution and font options as surface
. Generally, the new
surface will also use the same backend as surface
, unless that is
not possible for some reason. The type of the returned surface may
be examined with cairo_surface_get_type().
Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.)
Parameters
surface |
surface to make new surface similar to |
|
content |
the content for the new surface |
|
width |
width of the new surface |
|
height |
height of the new surface |
Returns
a pointer to the newly allocated surface. The caller
owns the surface and should call cairo_surface_destroy() when done
with it.
This function always returns a valid pointer, but it will return a
pointer to a “nil” surface if other
is already in an error state
or any other error occurs.
gdk_cairo_get_clip_rectangle ()
gboolean gdk_cairo_get_clip_rectangle (cairo_t *cr,GdkRectangle *rect);
This is a convenience function around cairo_clip_extents().
It rounds the clip extents to integer coordinates and returns
a boolean indicating if a clip area exists.
gdk_cairo_set_source_rgba ()
void gdk_cairo_set_source_rgba (cairo_t *cr,const GdkRGBA *rgba);
Sets the specified GdkRGBA as the source color of cr
.
gdk_cairo_set_source_pixbuf ()
void gdk_cairo_set_source_pixbuf (cairo_t *cr,const GdkPixbuf *pixbuf,gdouble pixbuf_x,gdouble pixbuf_y);
Sets the given pixbuf as the source pattern for cr
.
The pattern has an extend mode of CAIRO_EXTEND_NONE and is aligned
so that the origin of pixbuf
is pixbuf_x
, pixbuf_y
.
gdk_cairo_rectangle ()
void gdk_cairo_rectangle (cairo_t *cr,const GdkRectangle *rectangle);
Adds the given rectangle to the current path of cr
.
gdk_cairo_region ()
void gdk_cairo_region (cairo_t *cr,const cairo_region_t *region);
Adds the given region to the current path of cr
.
gdk_cairo_region_create_from_surface ()
cairo_region_t *
gdk_cairo_region_create_from_surface (cairo_surface_t *surface);
Creates region that describes covers the area where the given
surface
is more than 50% opaque.
This function takes into account device offsets that might be
set with cairo_surface_set_device_offset().
gdk_cairo_draw_from_gl ()
void gdk_cairo_draw_from_gl (cairo_t *cr,GdkSurface *surface,int source,int source_type,int buffer_scale,int x,int y,int width,int height);
This is the main way to draw GL content in GTK. It takes a render buffer ID
(source_type
== GL_RENDERBUFFER) or a texture id (source_type
== GL_TEXTURE)
and draws it onto cr
with an OVER operation, respecting the current clip.
The top left corner of the rectangle specified by x
, y
, width
and height
will be drawn at the current (0,0) position of the cairo_t.
This will work for *all* cairo_t, as long as surface
is realized, but the
fallback implementation that reads back the pixels from the buffer may be
used in the general case. In the case of direct drawing to a surface with
no special effects applied to cr
it will however use a more efficient
approach.
For GL_RENDERBUFFER the code will always fall back to software for buffers with alpha components, so make sure you use GL_TEXTURE if using alpha.
Calling this may change the current GL context.
Parameters
cr |
a cairo context |
|
surface |
The surface we're rendering for (not necessarily into) |
|
source |
The GL ID of the source buffer |
|
source_type |
The type of the |
|
buffer_scale |
The scale-factor that the |
|
x |
The source x position in |
|
y |
The source y position in |
|
width |
The width of the region to draw |
|
height |
The height of the region to draw |
gdk_cairo_surface_upload_to_gl ()
void gdk_cairo_surface_upload_to_gl (cairo_surface_t *surface,int target,int width,int height,GdkGLContext *context);
Uploads the contents of a Cairo surface
to a GL texture target
.
Parameters
surface |
a Cairo surface |
|
target |
a GL texture target |
|
width |
the width of the texture |
|
height |
the height of the texture |
|
context |
a GdkGLContext, or |
[nullable] |
| Top | |
|
|
|
Functions
| GdkCursor * | gdk_cursor_new_from_texture () |
| GdkCursor * | gdk_cursor_new_from_name () |
| GdkCursor * | gdk_cursor_get_fallback () |
| const char * | gdk_cursor_get_name () |
| GdkTexture * | gdk_cursor_get_texture () |
| int | gdk_cursor_get_hotspot_x () |
| int | gdk_cursor_get_hotspot_y () |
Description
These functions are used to create and destroy cursors. Cursors are immutable objects, so once you created them, there is no way to modify them later. Create a new cursor, when you want to change something about it.
Cursors by themselves are not very interesting, they must be
bound to a window for users to see them. This is done with
gdk_surface_set_cursor() or gdk_surface_set_device_cursor().
Applications will typically use higher-level GTK+ functions such
as gtk_widget_set_cursor() instead.
Cursors are not bound to a given GdkDisplay, so they can be shared. However, the appearance of cursors may vary when used on different platforms.
There are multiple ways to create cursors. The platform's own cursors
can be created with gdk_cursor_new_from_name(). That function lists
the commonly available names that are shared with the CSS specification.
Other names may be available, depending on the platform in use.
Another option to create a cursor is to use gdk_cursor_new_from_texture()
and provide an image to use for the cursor.
To ease work with unsupported cursors, a fallback cursor can be provided. If a GdkSurface cannot use a cursor because of the reasons mentioned above, it will try the fallback cursor. Of course, fallback cursors can themselves have fallback cursors again, so it is possible to provide a chain of progressively easier to support cursors. If none of the provided cursors can be supported, the default cursor will be the ultimate fallback.
Functions
gdk_cursor_new_from_texture ()
GdkCursor * gdk_cursor_new_from_texture (GdkTexture *texture,int hotspot_x,int hotspot_y,GdkCursor *fallback);
Creates a new cursor from a GdkTexture.
Parameters
texture |
the texture providing the pixel data |
|
hotspot_x |
the horizontal offset of the “hotspot” of the cursor |
|
hotspot_y |
the vertical offset of the “hotspot” of the cursor |
|
fallback |
|
[allow-none] |
gdk_cursor_new_from_name ()
GdkCursor * gdk_cursor_new_from_name (const gchar *name,GdkCursor *fallback);
Creates a new cursor by looking up name
in the current cursor
theme.
A recommended set of cursor names that will work across different platforms can be found in the CSS specification:
"none"
"default"
"help"
"pointer"
"context-menu"
"progress"
"wait"
"cell"
"crosshair"
"text"
"vertical-text"
"alias"
"copy"
"no-drop"
"move"
"not-allowed"
"grab"
"grabbing"
"all-scroll"
"col-resize"
"row-resize"
"n-resize"
"e-resize"
"s-resize"
"w-resize"
"ne-resize"
"nw-resize"
"sw-resize"
"se-resize"
"ew-resize"
"ns-resize"
"nesw-resize"
"nwse-resize"
"zoom-in"
"zoom-out"
Parameters
fallback |
|
[allow-none] |
name |
the name of the cursor |
gdk_cursor_get_fallback ()
GdkCursor *
gdk_cursor_get_fallback (GdkCursor *cursor);
Returns the fallback for this cursor
. The fallback will be used if this
cursor is not available on a given GdkDisplay.
For named cursors, this can happen when using nonstandard names or when using an incomplete cursor theme. For textured cursors, this can happen when the texture is too large or when the GdkDisplay it is used on does not support textured cursors.
gdk_cursor_get_name ()
const char *
gdk_cursor_get_name (GdkCursor *cursor);
Returns the name of the cursor. If the cursor is not a named cursor, NULL
will be returned and the GdkCursor::texture property will be set.
gdk_cursor_get_texture ()
GdkTexture *
gdk_cursor_get_texture (GdkCursor *cursor);
Returns the texture for the cursor. If the cursor is a named cursor, NULL
will be returned and the GdkCursor::name property will be set.
gdk_cursor_get_hotspot_x ()
int
gdk_cursor_get_hotspot_x (GdkCursor *cursor);
Returns the horizontal offset of the hotspot. The hotspot indicates the pixel that will be directly above the cursor.
Types and Values
GdkCursor
typedef struct _GdkCursor GdkCursor;
A GdkCursor represents a cursor. Its contents are private.
Cursors are immutable objects, so they can not change after they have been constructed.
Property Details
The “fallback” property
“fallback” GdkCursor *
Cursor image to fall back to if this cursor cannot be displayed.
Flags: Read / Write / Construct Only
The “hotspot-x” property
“hotspot-x” gint
Horizontal offset of the cursor hotspot.
Flags: Read / Write / Construct Only
Allowed values: >= 0
Default value: 0
The “hotspot-y” property
“hotspot-y” gint
Vertical offset of the cursor hotspot.
Flags: Read / Write / Construct Only
Allowed values: >= 0
Default value: 0
The “name” property
“name” gchar *
Name of this cursor.
Flags: Read / Write / Construct Only
Default value: NULL
The “texture” property
“texture” GdkTexture *
The texture displayed by this cursor.
Flags: Read / Write / Construct Only
| Top | |
|
|
|
Functions
| gboolean | gdk_rectangle_intersect () |
| void | gdk_rectangle_union () |
| gboolean | gdk_rectangle_equal () |
| gboolean | gdk_rectangle_contains_point () |
Description
GDK provides the GdkPoint and GdkRectangle data types for representing pixels and sets of pixels on the screen. Together with Cairo’s cairo_region_t data type, they make up the central types for representing graphical data.
A GdkPoint represents an x and y coordinate of a point.
A GdkRectangle represents the position and size of a rectangle.
The intersection of two rectangles can be computed with
gdk_rectangle_intersect(). To find the union of two rectangles use
gdk_rectangle_union().
cairo_region_t is usually used for managing clipping of graphical operations.
Functions
gdk_rectangle_intersect ()
gboolean gdk_rectangle_intersect (const GdkRectangle *src1,const GdkRectangle *src2,GdkRectangle *dest);
Calculates the intersection of two rectangles. It is allowed for
dest
to be the same as either src1
or src2
. If the rectangles
do not intersect, dest
’s width and height is set to 0 and its x
and y values are undefined. If you are only interested in whether
the rectangles intersect, but not in the intersecting area itself,
pass NULL for dest
.
gdk_rectangle_union ()
void gdk_rectangle_union (const GdkRectangle *src1,const GdkRectangle *src2,GdkRectangle *dest);
Calculates the union of two rectangles.
The union of rectangles src1
and src2
is the smallest rectangle which
includes both src1
and src2
within it.
It is allowed for dest
to be the same as either src1
or src2
.
Note that this function does not ignore 'empty' rectangles (ie. with zero width or height).
gdk_rectangle_equal ()
gboolean gdk_rectangle_equal (const GdkRectangle *rect1,const GdkRectangle *rect2);
Checks if the two given rectangles are equal.
gdk_rectangle_contains_point ()
gboolean gdk_rectangle_contains_point (const GdkRectangle *rect,int x,int y);
Returns TRUE if rect
contains the point described by x
and y
.
Types and Values
GdkRectangle
typedef struct {
int x, y;
int width, height;
} GdkRectangle;
Defines the position and size of a rectangle. It is identical to cairo_rectangle_int_t.
| Top | |
|
|
|
Functions
Description
A GdkContentProvider is used to provide content for the clipboard in a number of formats.
To create a GdkContentProvider, use gdk_content_provider_new_for_value() or
gdk_content_provider_new_for_bytes().
GDK knows how to handle common text and image formats out-of-the-box. See GdkContentSerializer and GdkContentDeserializer if you want to add support for application-specific data formats.
Functions
gdk_content_provider_new_for_value ()
GdkContentProvider *
gdk_content_provider_new_for_value (const GValue *value);
Create a content provider that provides the given value
.
gdk_content_provider_new_for_bytes ()
GdkContentProvider * gdk_content_provider_new_for_bytes (const char *mime_type,GBytes *bytes);
Create a content provider that provides the given bytes
as data for
the given mime_type
.
gdk_content_provider_ref_formats ()
GdkContentFormats *
gdk_content_provider_ref_formats (GdkContentProvider *provider);
Gets the formats that the provider can provide its current contents in.
gdk_content_provider_ref_storable_formats ()
GdkContentFormats *
gdk_content_provider_ref_storable_formats
(GdkContentProvider *provider);
Gets the formats that the provider suggests other applications to store the data in. An example of such an application would be a clipboard manager.
This can be assumed to be a subset of gdk_content_provider_ref_formats().
gdk_content_provider_content_changed ()
void
gdk_content_provider_content_changed (GdkContentProvider *provider);
Emits the “contents-changed” signal.
gdk_content_provider_write_mime_type_async ()
void gdk_content_provider_write_mime_type_async (GdkContentProvider *provider,const char *mime_type,GOutputStream *stream,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously writes the contents of provider
to stream
in the given
mime_type
. When the operation is finished callback
will be called. You
can then call gdk_content_provider_write_mime_type_finish() to get the
result of the operation.
The given mime type does not need to be listed in the formats returned by
gdk_content_provider_ref_formats(). However, if the given GType is not
supported, G_IO_ERROR_NOT_SUPPORTED will be reported.
The given stream
will not be closed.
Parameters
provider |
||
mime_type |
the mime type to provide the data in |
|
stream |
the GOutputStream to write to |
|
io_priority |
the I/O priority of the request. |
|
cancellable |
optional GCancellable object, |
[nullable] |
callback |
callback to call when the request is satisfied. |
[scope async] |
user_data |
the data to pass to callback function. |
[closure] |
gdk_content_provider_write_mime_type_finish ()
gboolean gdk_content_provider_write_mime_type_finish (GdkContentProvider *provider,GAsyncResult *result,GError **error);
Finishes an asynchronous write operation started with
gdk_content_provider_write_mime_type_async().
gdk_content_provider_get_value ()
gboolean gdk_content_provider_get_value (GdkContentProvider *provider,GValue *value,GError **error);
Gets the convtents of provider
stored in value
.
The value
will have been initialized to the GType the value should be
provided in. This given GType does not need to be listed in the formats
returned by gdk_content_provider_ref_formats(). However, if the given
GType is not supported, this operation can fail and
G_IO_ERROR_NOT_SUPPORTED will be reported.
Types and Values
GdkContentProvider
typedef struct _GdkContentProvider GdkContentProvider;
Should not be directly accessed.
struct GdkContentProviderClass
struct GdkContentProviderClass {
GObjectClass parent_class;
/* signals */
void (* content_changed) (GdkContentProvider *provider);
/* vfuncs */
void (* attach_clipboard) (GdkContentProvider *provider,
GdkClipboard *clipboard);
void (* detach_clipboard) (GdkContentProvider *provider,
GdkClipboard *clipboard);
GdkContentFormats * (* ref_formats) (GdkContentProvider *provider);
GdkContentFormats * (* ref_storable_formats) (GdkContentProvider *provider);
void (* write_mime_type_async) (GdkContentProvider *provider,
const char *mime_type,
GOutputStream *stream,
int io_priority,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean (* write_mime_type_finish) (GdkContentProvider *provider,
GAsyncResult *result,
GError **error);
gboolean (* get_value) (GdkContentProvider *provider,
GValue *value,
GError **error);
};
Property Details
The “formats” property
“formats” GdkContentFormats *
The possible formats that the provider can provide its data in.
Flags: Read
The “storable-formats” property
“storable-formats” GdkContentFormats *
The subset of formats that clipboard managers should store this provider's data in.
Flags: Read
Signal Details
The “content-changed” signal
void user_function (GdkContentProvider *gdkcontentprovider, gpointer user_data)
Flags: Run Last
| Top | |
|
|
|
Functions
| void | gdk_drag_drop_done () |
| GdkDrag * | gdk_drag_begin () |
| GdkDisplay * | gdk_drag_get_display () |
| GdkDragAction | gdk_drag_get_actions () |
| GdkDragAction | gdk_drag_get_selected_action () |
| GdkContentFormats * | gdk_drag_get_formats () |
| GdkDevice * | gdk_drag_get_device () |
| GdkSurface * | gdk_drag_get_drag_surface () |
| void | gdk_drag_set_hotspot () |
| gboolean | gdk_drag_action_is_unique () |
| GdkDisplay * | gdk_drop_get_display () |
| GdkDevice * | gdk_drop_get_device () |
| GdkSurface * | gdk_drop_get_surface () |
| GdkContentFormats * | gdk_drop_get_formats () |
| GdkDragAction | gdk_drop_get_actions () |
| GdkDrag * | gdk_drop_get_drag () |
| void | gdk_drop_status () |
| void | gdk_drop_finish () |
| void | gdk_drop_read_async () |
| GInputStream * | gdk_drop_read_finish () |
| void | gdk_drop_read_value_async () |
| const GValue * | gdk_drop_read_value_finish () |
| void | gdk_drop_read_text_async () |
| char * | gdk_drop_read_text_finish () |
Properties
| GdkDragAction | actions | Read / Write |
| GdkContentProvider * | content | Read / Write / Construct Only |
| GdkDevice * | device | Read / Write / Construct Only |
| GdkDisplay * | display | Read |
| GdkContentFormats * | formats | Read / Write / Construct Only |
| GdkDragAction | selected-action | Read / Write |
| GdkSurface * | surface | Read / Write / Construct Only |
| GdkDragAction | actions | Read / Write / Construct Only |
| GdkDevice * | device | Read / Write / Construct Only |
| GdkDisplay * | display | Read |
| GdkDrag * | drag | Read / Write / Construct Only |
| GdkContentFormats * | formats | Read / Write / Construct Only |
| GdkSurface * | surface | Read / Write / Construct Only |
Description
These functions provide a low level interface for drag and drop.
The GdkDrag object represents the source side of an ongoing DND operation. It is created when a drag is started, and stays alive for duration of the DND operation.
The GdkDrop object represents the target side of an ongoing DND operation.
GTK+ provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK+ applications. See the Drag and Drop section of the GTK+ documentation for more information.
Functions
gdk_drag_drop_done ()
void gdk_drag_drop_done (GdkDrag *drag,gboolean success);
Inform GDK if the drop ended successfully. Passing FALSE
for success
may trigger a drag cancellation animation.
This function is called by the drag source, and should
be the last call before dropping the reference to the
drag
.
The GdkDrag will only take the first gdk_drag_drop_done()
call as effective, if this function is called multiple times,
all subsequent calls will be ignored.
gdk_drag_begin ()
GdkDrag * gdk_drag_begin (GdkSurface *surface,GdkDevice *device,GdkContentProvider *content,GdkDragAction actions,gint dx,gint dy);
Starts a drag and creates a new drag context for it.
This function is called by the drag source.
Parameters
surface |
the source surface for this drag |
|
device |
the device that controls this drag |
|
content |
the offered content. |
[transfer none] |
actions |
the actions supported by this drag |
|
dx |
the x offset to |
|
dy |
the y offset to |
gdk_drag_get_display ()
GdkDisplay *
gdk_drag_get_display (GdkDrag *drag);
Gets the GdkDisplay that the drag object was created for.
gdk_drag_get_actions ()
GdkDragAction
gdk_drag_get_actions (GdkDrag *drag);
Determines the bitmask of possible actions proposed by the source.
gdk_drag_get_selected_action ()
GdkDragAction
gdk_drag_get_selected_action (GdkDrag *drag);
Determines the action chosen by the drag destination.
gdk_drag_get_formats ()
GdkContentFormats *
gdk_drag_get_formats (GdkDrag *drag);
Retrieves the formats supported by this GdkDrag object.
gdk_drag_get_device ()
GdkDevice *
gdk_drag_get_device (GdkDrag *drag);
Returns the GdkDevice associated to the GdkDrag object.
gdk_drag_get_drag_surface ()
GdkSurface *
gdk_drag_get_drag_surface (GdkDrag *drag);
Returns the surface on which the drag icon should be rendered
during the drag operation. Note that the surface may not be
available until the drag operation has begun. GDK will move
the surface in accordance with the ongoing drag operation.
The surface is owned by drag
and will be destroyed when
the drag operation is over.
gdk_drag_set_hotspot ()
void gdk_drag_set_hotspot (GdkDrag *drag,gint hot_x,gint hot_y);
Sets the position of the drag surface that will be kept under the cursor hotspot. Initially, the hotspot is at the top left corner of the drag surface.
Parameters
drag |
a GdkDrag |
|
hot_x |
x coordinate of the drag surface hotspot |
|
hot_y |
y coordinate of the drag surface hotspot |
gdk_drag_action_is_unique ()
gboolean
gdk_drag_action_is_unique (GdkDragAction action);
Checks if action
represents a single action or if it
includes multiple flags that can be selected from.
When action
is 0 - ie no action was given, TRUE
is returned.
gdk_drop_get_display ()
GdkDisplay *
gdk_drop_get_display (GdkDrop *self);
Gets the GdkDisplay that self
was created for.
gdk_drop_get_device ()
GdkDevice *
gdk_drop_get_device (GdkDrop *self);
Returns the GdkDevice performing the drop.
gdk_drop_get_surface ()
GdkSurface *
gdk_drop_get_surface (GdkDrop *self);
Returns the GdkSurface performing the drop.
gdk_drop_get_formats ()
GdkContentFormats *
gdk_drop_get_formats (GdkDrop *self);
Returns the GdkContentFormats that the drop offers the data to be read in.
gdk_drop_get_actions ()
GdkDragAction
gdk_drop_get_actions (GdkDrop *self);
Returns the possible actions for this GdkDrop. If this value
contains multiple actions - ie gdk_drag_action_is_unique()
returns FALSE for the result - gdk_drag_finish() must choose
the action to use when accepting the drop.
This value may change over the lifetime of the GdkDrop both
as a response to source side actions as well as to calls to
gdk_drop_status() or gdk_drag_finish(). The source side will
not change this value anymore once a drop has started.
gdk_drop_get_drag ()
GdkDrag *
gdk_drop_get_drag (GdkDrop *self);
If this is an in-app drag-and-drop operation, returns the GdkDrag that corresponds to this drop.
If it is not, NULL is returned.
gdk_drop_status ()
void gdk_drop_status (GdkDrop *self,GdkDragAction actions);
Selects all actions that are potentially supported by the destination.
When calling this function, do not restrict the passed in actions to
the ones provided by gdk_drop_get_actions(). Those actions may
change in the future, even depending on the actions you provide here.
This function should be called by drag destinations in response to
GDK_DRAG_ENTER or GDK_DRAG_MOTION events. If the destination does
not yet know the exact actions it supports, it should set any possible
actions first and then later call this function again.
Parameters
self |
a GdkDrop |
|
actions |
Supported actions of the destination, or 0 to indicate that a drop will not be accepted |
gdk_drop_finish ()
void gdk_drop_finish (GdkDrop *self,GdkDragAction action);
Ends the drag operation after a drop.
The action
must be a single action selected from the actions
available via gdk_drop_get_actions().
gdk_drop_read_async ()
void gdk_drop_read_async (GdkDrop *self,const char **mime_types,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously read the dropped data from a GdkDrop in a format that complies with one of the mime types.
Parameters
self |
a GdkDrop |
|
mime_types |
pointer to an array of mime types. |
[array zero-terminated=1][element-type utf8] |
io_priority |
the io priority for the read operation |
|
cancellable |
optional GCancellable object,
|
[allow-none] |
callback |
a GAsyncReadyCallback to call when the request is satisfied. |
[scope async] |
user_data |
the data to pass to |
[closure] |
gdk_drop_read_finish ()
GInputStream * gdk_drop_read_finish (GdkDrop *self,GAsyncResult *result,const char **out_mime_type,GError **error);
Finishes an async drop read operation, see gdk_drop_read_async().
Parameters
self |
a GdkDrop |
|
result |
a GAsyncResult |
|
out_mime_type |
return location for the used mime type. |
[out][type utf8] |
error |
location to store error information on failure, or |
[allow-none] |
gdk_drop_read_value_async ()
void gdk_drop_read_value_async (GdkDrop *self,GType type,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously request the drag operation's contents converted to the given
type
. When the operation is finished callback
will be called.
You can then call gdk_drop_read_value_finish() to get the resulting
GValue.
For local drag'n'drop operations that are available in the given GType, the
value will be copied directly. Otherwise, GDK will try to use
gdk_content_deserialize_async() to convert the data.
Parameters
self |
a GdkDrop |
|
type |
a GType to read |
|
io_priority |
the I/O priority of the request. |
|
cancellable |
optional GCancellable object, |
[nullable] |
callback |
callback to call when the request is satisfied. |
[scope async] |
user_data |
the data to pass to callback function. |
[closure] |
gdk_drop_read_value_finish ()
const GValue * gdk_drop_read_value_finish (GdkDrop *self,GAsyncResult *result,GError **error);
Finishes an async drop read started with
gdk_drop_read_value_async().
Parameters
self |
a GdkDrop |
|
result |
a GAsyncResult |
|
error |
a GError location to store the error occurring, or |
gdk_drop_read_text_async ()
void gdk_drop_read_text_async (GdkDrop *self,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously request the drag operation's contents converted to a string.
When the operation is finished callback
will be called. You can then
call gdk_drop_read_text_finish() to get the result.
This is a simple wrapper around gdk_drop_read_value_async(). Use
that function or gdk_drop_read_async() directly if you need more
control over the operation.
Parameters
self |
a GdkDrop |
|
cancellable |
optional GCancellable object, |
[nullable] |
callback |
callback to call when the request is satisfied. |
[scope async] |
user_data |
the data to pass to callback function. |
[closure] |
gdk_drop_read_text_finish ()
char * gdk_drop_read_text_finish (GdkDrop *self,GAsyncResult *result,GError **error);
Finishes an asynchronous read started with
gdk_drop_read_text_async().
Parameters
self |
a GdkDrop |
|
result |
a GAsyncResult |
|
error |
a GError location to store the error occurring, or |
Types and Values
GdkDrag
typedef struct _GdkDrag GdkDrag;
The GdkDrag struct contains only private fields and should not be accessed directly.
GdkDrop
typedef struct _GdkDrop GdkDrop;
The GdkDrop struct contains only private fields and should not be accessed directly.
enum GdkDragAction
Used in GdkDrag to indicate what the destination should do with the dropped data.
GDK_ACTION_ALL
#define GDK_ACTION_ALL (GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK)
Defines all possible DND actions. This can be used in gdk_drop_status()
messages when any drop can be accepted or a more specific drop method
is not yet known.
Property Details
The “content” property
“content” GdkContentProvider *
The GdkContentProvider.
Flags: Read / Write / Construct Only
The “device” property
“device” GdkDevice *
The GdkDevice that is performing the drag.
Flags: Read / Write / Construct Only
The “formats” property
“formats” GdkContentFormats *
The possible formats that the drag can provide its data in.
Flags: Read / Write / Construct Only
The “selected-action” property
“selected-action” GdkDragAction
The currently selected action.
Flags: Read / Write
The “surface” property
“surface” GdkSurface *
The surface where the drag originates.
Flags: Read / Write / Construct Only
The “actions” property
“actions” GdkDragAction
The possible actions for this drop
Flags: Read / Write / Construct Only
Default value: GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK
The “device” property
“device” GdkDevice *
The GdkDevice performing the drop
Flags: Read / Write / Construct Only
The “drag” property
“drag” GdkDrag *
The GdkDrag that initiated this drop
Flags: Read / Write / Construct Only
The “formats” property
“formats” GdkContentFormats *
The possible formats that the drop can provide its data in.
Flags: Read / Write / Construct Only
The “surface” property
“surface” GdkSurface *
The GdkSurface the drop happens on
Flags: Read / Write / Construct Only
Signal Details
The “cancel” signal
void user_function (GdkDrag *drag, GdkDragCancelReason reason, gpointer user_data)
The drag operation was cancelled.
Parameters
drag |
The object on which the signal is emitted |
|
reason |
The reason the drag was cancelled |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “dnd-finished” signal
void user_function (GdkDrag *drag, gpointer user_data)
The drag operation was finished, the destination finished reading all data. The drag object can now free all miscellaneous data.
Parameters
drag |
The object on which the signal is emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “drop-performed” signal
void user_function (GdkDrag *drag, gpointer user_data)
The drag operation was performed on an accepting client.
Parameters
drag |
The object on which the signal is emitted |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
If gdk_disable_multidevice() has been called, this function will respectively return 2/3 for the core pointer and keyboard, (matching the IDs for the Virtual Core Pointer and Keyboard in XInput 2), but calling this function on any slave devices (i.e. those managed via XInput 1.x), will return 0.