| 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 char *name);
Opens a display.
gdk_set_allowed_backends ()
void
gdk_set_allowed_backends (const char *backends);
Sets a list of backends that GDK should try to use.
This can 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.
Owner: GdkDisplayManager
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
| GdkDisplay * | gdk_seat_get_display () |
| GdkSeatCapabilities | gdk_seat_get_capabilities () |
| GdkDevice * | gdk_seat_get_pointer () |
| GdkDevice * | gdk_seat_get_keyboard () |
| GList * | gdk_seat_get_devices () |
| GList * | gdk_seat_get_tools () |
Signals
| void | device-added | Run Last |
| void | device-removed | Run Last |
| void | tool-added | Run Last |
| void | tool-removed | Run Last |
Functions
gdk_seat_get_display ()
GdkDisplay *
gdk_seat_get_display (GdkSeat *seat);
Returns the GdkDisplay this seat belongs to.
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 logical device that routes pointer events.
Returns
a logical 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 logical device that routes keyboard events.
Returns
a logical GdkDevice with keyboard capabilities. This object is owned by GTK and must not be freed.
[transfer none][nullable]
gdk_seat_get_devices ()
GList * gdk_seat_get_devices (GdkSeat *seat,GdkSeatCapabilities capabilities);
Returns the devices that match the given capabilities.
gdk_seat_get_tools ()
GList *
gdk_seat_get_tools (GdkSeat *seat);
Returns all GdkDeviceTools that are known to the application.
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.
Property Details
The “display” property
“display” GdkDisplay *
GdkDisplay of this seat.
Owner: GdkSeat
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
Types and Values
| GdkEvent | |
| enum | GdkEventType |
| enum | GdkKeyMatch |
| enum | GdkTouchpadGesturePhase |
| 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 by toplevel widgets and passed on to the event controllers of appropriate widgets, so these functions are rarely needed.
Functions
gdk_event_unref ()
void
gdk_event_unref (GdkEvent *event);
Decrease the ref count of event
, and free it
if the last reference is dropped.
gdk_event_get_event_type ()
GdkEventType
gdk_event_get_event_type (GdkEvent *event);
Retrieves the type of the event.
gdk_event_get_surface ()
GdkSurface *
gdk_event_get_surface (GdkEvent *event);
Extracts the GdkSurface associated with an event.
gdk_event_get_device ()
GdkDevice *
gdk_event_get_device (GdkEvent *event);
Returns the device of an event.
gdk_event_get_device_tool ()
GdkDeviceTool *
gdk_event_get_device_tool (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 GdkDeviceTools will be constant during
the application lifetime, if settings must be stored
persistently across runs, see gdk_device_tool_get_serial()
gdk_event_get_time ()
guint32
gdk_event_get_time (GdkEvent *event);
Returns the time stamp from event
, if there is one; otherwise
returns GDK_CURRENT_TIME.
gdk_event_get_display ()
GdkDisplay *
gdk_event_get_display (GdkEvent *event);
Retrieves the GdkDisplay associated to the event
.
gdk_event_get_seat ()
GdkSeat *
gdk_event_get_seat (GdkEvent *event);
Returns the seat that originated the event.
gdk_event_get_event_sequence ()
GdkEventSequence *
gdk_event_get_event_sequence (GdkEvent *event);
If event
is a touch event, returns the GdkEventSequence
to which the event belongs. Otherwise, return NULL.
gdk_event_get_modifier_state ()
GdkModifierType
gdk_event_get_modifier_state (GdkEvent *event);
Returns the modifier state field of an event.
gdk_event_get_position ()
gboolean gdk_event_get_position (GdkEvent *event,double *x,double *y);
Extract the event surface relative x/y coordinates from an event.
Parameters
event |
a GdkEvent |
|
x |
location to put event surface x coordinate. |
[out] |
y |
location to put event surface y coordinate. |
[out] |
gdk_event_get_axes ()
gboolean gdk_event_get_axes (GdkEvent *event,double **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 (GdkEvent *event,GdkAxisUse axis_use,double *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_history ()
GdkTimeCoord * gdk_event_get_history (GdkEvent *event,guint *out_n_coords);
Retrieves the history of the event
, as a list of time and coordinates.
The history includes events that are not delivered to the application
because they occurred in the same frame as event
.
Note that only motion and scroll events record history, and motion events only if one of the mouse buttons is down.
Parameters
event |
a motion or scroll GdkEvent |
|
out_n_coords |
Return location for the length of the returned array. |
[out] |
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_triggers_context_menu ()
gboolean
gdk_event_triggers_context_menu (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.
This function should always be used instead of simply checking for
event->button == GDK_BUTTON_SECONDARY.
gdk_button_event_get_button ()
guint
gdk_button_event_get_button (GdkEvent *event);
Extract the button number from a button event.
gdk_scroll_event_get_direction ()
GdkScrollDirection
gdk_scroll_event_get_direction (GdkEvent *event);
Extracts the direction of a scroll event.
gdk_scroll_event_get_deltas ()
void gdk_scroll_event_get_deltas (GdkEvent *event,double *delta_x,double *delta_y);
Extracts the scroll deltas of a scroll event.
The deltas will be zero unless the scroll direction
is GDK_SCROLL_SMOOTH.
gdk_scroll_event_is_stop ()
gboolean
gdk_scroll_event_is_stop (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 delta of 0/0.
gdk_key_event_get_keyval ()
guint
gdk_key_event_get_keyval (GdkEvent *event);
Extracts the keyval from a key event.
gdk_key_event_get_keycode ()
guint
gdk_key_event_get_keycode (GdkEvent *event);
Extracts the keycode from a key event.
gdk_key_event_get_consumed_modifiers ()
GdkModifierType
gdk_key_event_get_consumed_modifiers (GdkEvent *event);
Extracts the consumed modifiers from a key event.
gdk_key_event_get_layout ()
guint
gdk_key_event_get_layout (GdkEvent *event);
Extracts the layout from a key event.
gdk_key_event_get_level ()
guint
gdk_key_event_get_level (GdkEvent *event);
Extracts the shift level from a key event.
gdk_key_event_is_modifier ()
gboolean
gdk_key_event_is_modifier (GdkEvent *event);
Extracts whether the key event is for a modifier key.
gdk_key_event_matches ()
GdkKeyMatch gdk_key_event_matches (GdkEvent *event,guint keyval,GdkModifierType modifiers);
Matches a key event against a keyboard shortcut that is specified as a keyval and modifiers. Partial matches are possible where the combination matches if the currently active group is ignored.
Note that we ignore Caps Lock for matching.
Parameters
event |
a key GdkEvent. |
[type GdkKeyEvent] |
keyval |
the keyval to match |
|
modifiers |
the modifiers to match |
gdk_key_event_get_match ()
gboolean gdk_key_event_get_match (GdkEvent *event,guint *keyval,GdkModifierType *modifiers);
Gets a keyval and modifier combination that will cause
gdk_key_event_matches() to successfully match the given event.
Parameters
event |
a key GdkEvent. |
[type GdkKeyEvent] |
keyval |
return location for a keyval. |
[out] |
modifiers |
return location for modifiers. |
[out] |
gdk_focus_event_get_in ()
gboolean
gdk_focus_event_get_in (GdkEvent *event);
Extracts whether this event is about focus entering or leaving the surface.
gdk_touch_event_get_emulating_pointer ()
gboolean
gdk_touch_event_get_emulating_pointer (GdkEvent *event);
Extracts whether a touch event is emulating a pointer event.
gdk_crossing_event_get_mode ()
GdkCrossingMode
gdk_crossing_event_get_mode (GdkEvent *event);
Extracts the crossing mode from a crossing event.
gdk_crossing_event_get_detail ()
GdkNotifyType
gdk_crossing_event_get_detail (GdkEvent *event);
Extracts the notify detail from a crossing event.
gdk_crossing_event_get_focus ()
gboolean
gdk_crossing_event_get_focus (GdkEvent *event);
Checks if the event
surface is the focus surface.
gdk_grab_broken_event_get_grab_surface ()
GdkSurface *
gdk_grab_broken_event_get_grab_surface
(GdkEvent *event);
Extracts the grab surface from a grab broken event.
gdk_grab_broken_event_get_implicit ()
gboolean
gdk_grab_broken_event_get_implicit (GdkEvent *event);
Checks whether the grab broken event is for an implicit grab.
gdk_dnd_event_get_drop ()
GdkDrop *
gdk_dnd_event_get_drop (GdkEvent *event);
Gets the GdkDrop from a DND event.
gdk_configure_event_get_size ()
void gdk_configure_event_get_size (GdkEvent *event,int *width,int *height);
Extracts the surface size from a configure event.
gdk_touchpad_event_get_gesture_phase ()
GdkTouchpadGesturePhase
gdk_touchpad_event_get_gesture_phase (GdkEvent *event);
Extracts the touchpad gesture phase from a touchpad event.
gdk_touchpad_event_get_n_fingers ()
guint
gdk_touchpad_event_get_n_fingers (GdkEvent *event);
Extracts the number of fingers from a touchpad event.
gdk_touchpad_event_get_deltas ()
void gdk_touchpad_event_get_deltas (GdkEvent *event,double *dx,double *dy);
Extracts delta information from a touchpad event.
gdk_touchpad_event_get_pinch_angle_delta ()
double
gdk_touchpad_event_get_pinch_angle_delta
(GdkEvent *event);
Extracts the angle delta from a touchpad pinch event.
gdk_touchpad_event_get_pinch_scale ()
double
gdk_touchpad_event_get_pinch_scale (GdkEvent *event);
Extracts the scale from a touchpad pinch event.
gdk_pad_event_get_axis_value ()
void gdk_pad_event_get_axis_value (GdkEvent *event,guint *index,double *value);
Extracts the information from a pad strip or ring event.
gdk_pad_event_get_button ()
guint
gdk_pad_event_get_button (GdkEvent *event);
Extracts information about the pressed button from a pad event.
gdk_pad_event_get_group_mode ()
void gdk_pad_event_get_group_mode (GdkEvent *event,guint *group,guint *mode);
Extracts group and mode information from a pad event.
gdk_events_get_angle ()
gboolean gdk_events_get_angle (GdkEvent *event1,GdkEvent *event2,double *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,double *x,double *y);
If both events contain X/Y information, the center of both coordinates
will be returned in x
and y
.
Types and Values
GdkEvent
typedef struct _GdkEvent GdkEvent;
The GdkEvent struct contains only private fields and should not be accessed directly.
enum GdkEventType
Specifies the type of the event.
Members
|
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 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 of the surface has changed. |
||
|
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. |
||
|
A new touch event sequence has just started. |
||
|
A touch event sequence has been updated. |
||
|
A touch event sequence has finished. |
||
|
A touch event sequence has been canceled. |
||
|
A touchpad swipe gesture event, the current state is determined by its phase field. |
||
|
A touchpad pinch gesture event, the current state is determined by its phase field. |
||
|
A tablet pad button press event. |
||
|
A tablet pad button release event. |
||
|
A tablet pad axis event from a "ring". |
||
|
A tablet pad axis event from a "strip". |
||
|
A tablet pad group mode change. |
||
|
marks the end of the GdkEventType enumeration. |
enum GdkKeyMatch
The possible return values from gdk_key_event_matches()
describe how well an event matches a given keyval and modifiers.
enum GdkTouchpadGesturePhase
Specifies the current state of a touchpad gesture. All gestures are
guaranteed to begin with an event with phase GDK_TOUCHPAD_GESTURE_PHASE_BEGIN,
followed by 0 or several events with phase GDK_TOUCHPAD_GESTURE_PHASE_UPDATE.
A finished gesture may have 2 possible outcomes, an event with phase
GDK_TOUCHPAD_GESTURE_PHASE_END will be emitted when the gesture is
considered successful, this should be used as the hint to perform any
permanent changes.
Cancelled gestures may be so for a variety of reasons, due to hardware
or the compositor, or due to the gesture recognition layers hinting the
gesture did not finish resolutely (eg. a 3rd finger being added during
a pinch gesture). In these cases, the last event will report the phase
GDK_TOUCHPAD_GESTURE_PHASE_CANCEL, this should be used as a hint
to undo any visible/permanent changes that were done throughout the
progress of the gesture.
enum GdkScrollDirection
Specifies the direction for scroll events.
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.
| Top | |
|
|
|
Functions
| GdkDisplay * | gdk_monitor_get_display () |
| void | gdk_monitor_get_geometry () |
| int | gdk_monitor_get_width_mm () |
| int | gdk_monitor_get_height_mm () |
| const char * | gdk_monitor_get_manufacturer () |
| const char * | gdk_monitor_get_model () |
| const char * | gdk_monitor_get_connector () |
| int | gdk_monitor_get_scale_factor () |
| int | gdk_monitor_get_refresh_rate () |
| GdkSubpixelLayout | gdk_monitor_get_subpixel_layout () |
| gboolean | gdk_monitor_is_valid () |
Properties
| gchar * | connector | Read |
| 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 |
Description
GdkMonitor objects represent the individual outputs that are
associated with a GdkDisplay. GdkDisplay keeps a GListModel to enumerate
and monitor monitors with gdk_display_get_monitors().
You can use gdk_display_get_monitor_at_surface() to find a particular monitor.
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_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 or PNP ID of the monitor's manufacturer, if available.
Note that this value might also vary depending on actual display backend.
PNP ID registry is located at https://uefi.org/pnp_id_list
gdk_monitor_get_model ()
const char *
gdk_monitor_get_model (GdkMonitor *monitor);
Gets the string identifying the monitor model, if available.
gdk_monitor_get_connector ()
const char *
gdk_monitor_get_connector (GdkMonitor *monitor);
Gets the name of the monitor's connector, 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_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 “connector” property
“connector” gchar *
The connector name.
Owner: GdkMonitor
Flags: Read
Default value: NULL
The “display” property
“display” GdkDisplay *
The display of the monitor.
Owner: GdkMonitor
Flags: Read / Write / Construct Only
The “geometry” property
“geometry” GdkRectangle *
The geometry of the monitor.
Owner: GdkMonitor
Flags: Read
The “height-mm” property
“height-mm” gint
The height of the monitor, in millimeters.
Owner: GdkMonitor
Flags: Read
Allowed values: >= 0
Default value: 0
The “manufacturer” property
“manufacturer” gchar *
The manufacturer name.
Owner: GdkMonitor
Flags: Read
Default value: NULL
The “model” property
“model” gchar *
The model name.
Owner: GdkMonitor
Flags: Read
Default value: NULL
The “refresh-rate” property
“refresh-rate” gint
The refresh rate, in millihertz.
Owner: GdkMonitor
Flags: Read
Allowed values: >= 0
Default value: 0
The “scale-factor” property
“scale-factor” gint
The scale factor.
Owner: GdkMonitor
Flags: Read
Allowed values: >= 0
Default value: 1
The “subpixel-layout” property
“subpixel-layout” GdkSubpixelLayout
The subpixel layout.
Owner: GdkMonitor
Flags: Read
Default value: GDK_SUBPIXEL_LAYOUT_UNKNOWN
The “valid” property
“valid” gboolean
Whether the monitor is still valid.
Owner: GdkMonitor
Flags: Read
Default value: TRUE
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
| 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 char *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.
Owner: GdkCursor
Flags: Read / Write / Construct Only
The “hotspot-x” property
“hotspot-x” gint
Horizontal offset of the cursor hotspot.
Owner: GdkCursor
Flags: Read / Write / Construct Only
Allowed values: >= 0
Default value: 0
The “hotspot-y” property
“hotspot-y” gint
Vertical offset of the cursor hotspot.
Owner: GdkCursor
Flags: Read / Write / Construct Only
Allowed values: >= 0
Default value: 0
The “name” property
“name” gchar *
Name of this cursor.
Owner: GdkCursor
Flags: Read / Write / Construct Only
Default value: NULL
The “texture” property
“texture” GdkTexture *
The texture displayed by this cursor.
Owner: GdkCursor
Flags: Read / Write / Construct Only
| 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.
There are various ways to create GdkTexture objects from a GdkPixbuf, or a Cairo surface, or other pixel data.
The ownership of the pixel data is transferred to the GdkTexture
instance; you can only make a copy of it, via gdk_texture_download().
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.
GDK 4 Reference Manual |
|---|
This document is for the GDK 4 library, version 3.99.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 a 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
- Toplevels — Interface for toplevel surfaces
- GdkToplevelLayout — Information for presenting toplevels
- Popups — Interface for popup surfaces
- GdkPopupLayout — Information for presenting popups
- 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
- GdkCairoContext — Cairo 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
- 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
| gboolean | gdk_toplevel_present () |
| gboolean | gdk_toplevel_minimize () |
| gboolean | gdk_toplevel_lower () |
| void | gdk_toplevel_focus () |
| GdkSurfaceState | gdk_toplevel_get_state () |
| void | gdk_toplevel_set_title () |
| void | gdk_toplevel_set_startup_id () |
| void | gdk_toplevel_set_transient_for () |
| void | gdk_toplevel_set_modal () |
| void | gdk_toplevel_set_icon_list () |
| gboolean | gdk_toplevel_show_window_menu () |
| void | gdk_toplevel_set_decorated () |
| void | gdk_toplevel_set_deletable () |
| gboolean | gdk_toplevel_supports_edge_constraints () |
| void | gdk_toplevel_inhibit_system_shortcuts () |
| void | gdk_toplevel_restore_system_shortcuts () |
| void | gdk_toplevel_begin_resize () |
| void | gdk_toplevel_begin_move () |
Properties
| gboolean | decorated | Read / Write |
| gboolean | deletable | Read / Write |
| GdkFullscreenMode | fullscreen-mode | Read / Write |
| gpointer | icon-list | Read / Write |
| gboolean | modal | Read / Write |
| gboolean | shortcuts-inhibited | Read |
| gchar * | startup-id | Read / Write |
| GdkSurfaceState | state | Read |
| gchar * | title | Read / Write |
| GdkSurface * | transient-for | Read / Write |
Functions
gdk_toplevel_present ()
gboolean gdk_toplevel_present (GdkToplevel *toplevel,int width,int height,GdkToplevelLayout *layout);
Present toplevel
after having processed the GdkToplevelLayout rules.
If the toplevel was previously now showing, it will be showed,
otherwise it will change layout according to layout
.
Presenting may fail.
Parameters
toplevel |
the GdkToplevel to show |
|
width |
the unconstrained toplevel width to layout |
|
height |
the unconstrained toplevel height to layout |
|
layout |
the GdkToplevelLayout object used to layout |
gdk_toplevel_minimize ()
gboolean
gdk_toplevel_minimize (GdkToplevel *toplevel);
Asks to minimize the toplevel
.
The windowing system may choose to ignore the request.
gdk_toplevel_lower ()
gboolean
gdk_toplevel_lower (GdkToplevel *toplevel);
Asks to lower the toplevel
below other windows.
The windowing system may choose to ignore the request.
gdk_toplevel_focus ()
void gdk_toplevel_focus (GdkToplevel *toplevel,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_toplevel_get_state ()
GdkSurfaceState
gdk_toplevel_get_state (GdkToplevel *toplevel);
Gets the bitwise OR of the currently active surface state flags, from the GdkSurfaceState enumeration.
gdk_toplevel_set_title ()
void gdk_toplevel_set_title (GdkToplevel *toplevel,const char *title);
Sets the title of a toplevel surface, to be displayed in the titlebar, in lists of windows, etc.
gdk_toplevel_set_startup_id ()
void gdk_toplevel_set_startup_id (GdkToplevel *toplevel,const char *startup_id);
When using GTK, typically you should use gtk_window_set_startup_id()
instead of this low-level function.
gdk_toplevel_set_transient_for ()
void gdk_toplevel_set_transient_for (GdkToplevel *toplevel,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_toplevel_set_modal ()
void gdk_toplevel_set_modal (GdkToplevel *toplevel,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_toplevel_set_transient_for().
gdk_toplevel_set_icon_list ()
void gdk_toplevel_set_icon_list (GdkToplevel *toplevel,GList *surfaces);
Sets a list of icons for the surface.
One of these will be used to represent the surface in iconic form. The icon may be shown in window lists or task bars. 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.
Note that some platforms don't support surface icons.
gdk_toplevel_show_window_menu ()
gboolean gdk_toplevel_show_window_menu (GdkToplevel *toplevel,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_toplevel_set_decorated ()
void gdk_toplevel_set_decorated (GdkToplevel *toplevel,gboolean decorated);
Setting decorated
to FALSE hints the desktop environment
that the surface has its own, client-side decorations and
does not need to have window decorations added.
gdk_toplevel_set_deletable ()
void gdk_toplevel_set_deletable (GdkToplevel *toplevel,gboolean deletable);
Setting deletable
to TRUE hints the desktop environment
that it should offer the user a way to close the surface.
gdk_toplevel_supports_edge_constraints ()
gboolean
gdk_toplevel_supports_edge_constraints
(GdkToplevel *toplevel);
Returns whether the desktop environment supports tiled window states.
gdk_toplevel_inhibit_system_shortcuts ()
void gdk_toplevel_inhibit_system_shortcuts (GdkToplevel *toplevel,GdkEvent *event);
Requests that the toplevel
inhibit the system shortcuts, asking the
desktop environment/windowing system to let all keyboard events reach
the surface, as long as it is focused, instead of triggering system
actions.
If granted, the rerouting remains active until the default shortcuts
processing is restored with gdk_toplevel_restore_system_shortcuts(),
or the request is revoked by the desktop environment, windowing system
or the user.
A typical use case for this API is remote desktop or virtual machine viewers which need to inhibit the default system keyboard shortcuts so that the remote session or virtual host gets those instead of the local environment.
The windowing system or desktop environment may ask the user to grant or deny the request or even choose to ignore the request entirely.
The caller can be notified whenever the request is granted or revoked by listening to the GdkToplevel::shortcuts-inhibited property.
Parameters
toplevel |
the GdkToplevel requesting system keyboard shortcuts |
|
event |
the GdkEvent that is triggering the inhibit
request, or |
[nullable] |
gdk_toplevel_restore_system_shortcuts ()
void
gdk_toplevel_restore_system_shortcuts (GdkToplevel *toplevel);
Restore default system keyboard shortcuts which were previously
requested to be inhibited by gdk_toplevel_inhibit_system_shortcuts().
gdk_toplevel_begin_resize ()
void gdk_toplevel_begin_resize (GdkToplevel *toplevel,GdkSurfaceEdge edge,GdkDevice *device,int button,double x,double y,guint32 timestamp);
Begins an interactive resize operation (for a toplevel surface). You might use this function to implement a “window resize grip.”
Parameters
toplevel |
||
edge |
the edge or corner from which the drag is started |
|
device |
the device used for the operation. |
[nullable] |
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_toplevel_begin_move ()
void gdk_toplevel_begin_move (GdkToplevel *toplevel,GdkDevice *device,int button,double x,double y,guint32 timestamp);
Begins an interactive move operation (for a toplevel surface). You might use this function to implement draggable titlebars.
Parameters
toplevel |
||
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 |
Property Details
The “decorated” property
“decorated” gboolean
Decorated.
Owner: GdkToplevel
Flags: Read / Write
Default value: FALSE
The “deletable” property
“deletable” gboolean
Deletable.
Owner: GdkToplevel
Flags: Read / Write
Default value: FALSE
The “fullscreen-mode” property
“fullscreen-mode” GdkFullscreenMode
Fullscreen mode.
Owner: GdkToplevel
Flags: Read / Write
Default value: GDK_FULLSCREEN_ON_CURRENT_MONITOR
The “icon-list” property
“icon-list” gpointer
The list of icon textures.
Owner: GdkToplevel
Flags: Read / Write
The “modal” property
“modal” gboolean
Whether the surface is modal.
Owner: GdkToplevel
Flags: Read / Write
Default value: FALSE
The “shortcuts-inhibited” property
“shortcuts-inhibited” gboolean
Whether keyboard shortcuts are inhibited.
Owner: GdkToplevel
Flags: Read
Default value: FALSE
The “startup-id” property
“startup-id” gchar *
The startup ID of the surface.
Owner: GdkToplevel
Flags: Read / Write
Default value: NULL
The “state” property
“state” GdkSurfaceState
State.
Owner: GdkToplevel
Flags: Read
Default value: GDK_SURFACE_STATE_WITHDRAWN
The “title” property
“title” gchar *
The title of the surface.
Owner: GdkToplevel
Flags: Read / Write
Default value: NULL
The “transient-for” property
“transient-for” GdkSurface *
The transient parent of the surface.
Owner: GdkToplevel
Flags: Read / Write
| Top | |
|
|
|
Functions
| GdkToplevelLayout * | gdk_toplevel_layout_new () |
| GdkToplevelLayout * | gdk_toplevel_layout_ref () |
| void | gdk_toplevel_layout_unref () |
| GdkToplevelLayout * | gdk_toplevel_layout_copy () |
| gboolean | gdk_toplevel_layout_equal () |
| void | gdk_toplevel_layout_set_maximized () |
| gboolean | gdk_toplevel_layout_get_maximized () |
| void | gdk_toplevel_layout_set_fullscreen () |
| gboolean | gdk_toplevel_layout_get_fullscreen () |
| GdkMonitor * | gdk_toplevel_layout_get_fullscreen_monitor () |
| int | gdk_toplevel_layout_get_min_width () |
| int | gdk_toplevel_layout_get_min_height () |
| void | gdk_toplevel_layout_set_resizable () |
| gboolean | gdk_toplevel_layout_get_resizable () |
Description
Toplevel surfaces are sovereign windows that can be presented to the user in various states (maximized, on all workspaces, etc).
The GdkToplevelLayout struct contains information that
is necessary to do so, and is passed to gdk_toplevel_present().
Functions
gdk_toplevel_layout_new ()
GdkToplevelLayout * gdk_toplevel_layout_new (int min_width,int min_height);
Create a toplevel layout description.
Used together with gdk_toplevel_present() to describe
how a toplevel surface should be placed and behave on-screen.
The size is in ”application pixels”, not
”device pixels” (see gdk_surface_get_scale_factor()).
[constructor]
gdk_toplevel_layout_ref ()
GdkToplevelLayout *
gdk_toplevel_layout_ref (GdkToplevelLayout *layout);
Increases the reference count of layout
.
gdk_toplevel_layout_unref ()
void
gdk_toplevel_layout_unref (GdkToplevelLayout *layout);
Decreases the reference count of layout
.
gdk_toplevel_layout_copy ()
GdkToplevelLayout *
gdk_toplevel_layout_copy (GdkToplevelLayout *layout);
Create a new GdkToplevelLayout and copy the contents of layout
into it.
gdk_toplevel_layout_equal ()
gboolean gdk_toplevel_layout_equal (GdkToplevelLayout *layout,GdkToplevelLayout *other);
Check whether layout
and other
has identical layout properties.
gdk_toplevel_layout_set_maximized ()
void gdk_toplevel_layout_set_maximized (GdkToplevelLayout *layout,gboolean maximized);
Sets whether the layout should cause the surface to be maximized when presented.
gdk_toplevel_layout_get_maximized ()
gboolean
gdk_toplevel_layout_get_maximized (GdkToplevelLayout *layout);
Returns whether the layout should present the surface as maximized.
gdk_toplevel_layout_set_fullscreen ()
void gdk_toplevel_layout_set_fullscreen (GdkToplevelLayout *layout,gboolean fullscreen,GdkMonitor *monitor);
Sets whether the layout should cause the surface to be fullscreen when presented.
gdk_toplevel_layout_get_fullscreen ()
gboolean
gdk_toplevel_layout_get_fullscreen (GdkToplevelLayout *layout);
Returns whether the layout should cause the surface to be fullscreen when presented.
gdk_toplevel_layout_get_fullscreen_monitor ()
GdkMonitor *
gdk_toplevel_layout_get_fullscreen_monitor
(GdkToplevelLayout *layout);
Returns the monitor that the layout is fullscreening the surface on.
gdk_toplevel_layout_get_min_width ()
int
gdk_toplevel_layout_get_min_width (GdkToplevelLayout *layout);
Returns the minimum width of the given layout.
gdk_toplevel_layout_get_min_height ()
int
gdk_toplevel_layout_get_min_height (GdkToplevelLayout *layout);
Returns the minimum height of the given layout.
gdk_toplevel_layout_set_resizable ()
void gdk_toplevel_layout_set_resizable (GdkToplevelLayout *layout,gboolean resizable);
Sets whether the layout should allow the user to resize the surface after it has been presented.
gdk_toplevel_layout_get_resizable ()
gboolean
gdk_toplevel_layout_get_resizable (GdkToplevelLayout *layout);
Returns whether the layout should allow the user to resize the surface.
| Top | |
|
|
|
Functions
Description
Popups are positioned relative to their parent surface. The GdkPopupLayout struct contains information that is necessary to do so.
Functions
gdk_popup_layout_new ()
GdkPopupLayout * gdk_popup_layout_new (const GdkRectangle *anchor_rect,GdkGravity rect_anchor,GdkGravity surface_anchor);
Create a popup layout description. Used together with
gdk_surface_present_popup() to describe how a popup surface should be placed
and behave on-screen.
anchor_rect
is relative to the top-left corner of the surface's parent.
rect_anchor
and surface_anchor
determine anchor points on anchor_rect
and
surface to pin together.
The position of anchor_rect
's anchor point can optionally be offset using
gdk_popup_layout_set_offset(), which is equivalent to offsetting the
position of surface.
[constructor]
Parameters
anchor_rect |
the anchor GdkRectangle to align |
[not nullable] |
rect_anchor |
the point on |
|
surface_anchor |
the point on |
gdk_popup_layout_ref ()
GdkPopupLayout *
gdk_popup_layout_ref (GdkPopupLayout *layout);
Increases the reference count of value
.
gdk_popup_layout_unref ()
void
gdk_popup_layout_unref (GdkPopupLayout *layout);
Decreases the reference count of value
.
gdk_popup_layout_copy ()
GdkPopupLayout *
gdk_popup_layout_copy (GdkPopupLayout *layout);
Create a new GdkPopupLayout and copy the contents of layout
into it.
gdk_popup_layout_equal ()
gboolean gdk_popup_layout_equal (GdkPopupLayout *layout,GdkPopupLayout *other);
Check whether layout
and other
has identical layout properties.
gdk_popup_layout_set_anchor_rect ()
void gdk_popup_layout_set_anchor_rect (GdkPopupLayout *layout,const GdkRectangle *anchor_rect);
Set the anchor rectangle.
gdk_popup_layout_get_anchor_rect ()
const GdkRectangle *
gdk_popup_layout_get_anchor_rect (GdkPopupLayout *layout);
Get the anchor rectangle.
gdk_popup_layout_set_rect_anchor ()
void gdk_popup_layout_set_rect_anchor (GdkPopupLayout *layout,GdkGravity anchor);
Set the anchor on the anchor rectangle.
gdk_popup_layout_get_rect_anchor ()
GdkGravity
gdk_popup_layout_get_rect_anchor (GdkPopupLayout *layout);
Returns the anchor position on the anchor rectangle.
gdk_popup_layout_set_surface_anchor ()
void gdk_popup_layout_set_surface_anchor (GdkPopupLayout *layout,GdkGravity anchor);
Set the anchor on the popup surface.
gdk_popup_layout_get_surface_anchor ()
GdkGravity
gdk_popup_layout_get_surface_anchor (GdkPopupLayout *layout);
Returns the anchor position on the popup surface.
gdk_popup_layout_set_anchor_hints ()
void gdk_popup_layout_set_anchor_hints (GdkPopupLayout *layout,GdkAnchorHints anchor_hints);
Set new anchor hints.
The set 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.
gdk_popup_layout_get_anchor_hints ()
GdkAnchorHints
gdk_popup_layout_get_anchor_hints (GdkPopupLayout *layout);
Get the GdkAnchorHints.
gdk_popup_layout_set_offset ()
void gdk_popup_layout_set_offset (GdkPopupLayout *layout,int dx,int dy);
Offset the position of the anchor rectangle with the given delta.
gdk_popup_layout_get_offset ()
void gdk_popup_layout_get_offset (GdkPopupLayout *layout,int *dx,int *dy);
Get the delta the anchor rectangle is offset with
Types and Values
GdkPopupLayout
typedef struct _GdkPopupLayout GdkPopupLayout;
Struct containing information for gdk_popup_present()
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 |
| Top | |
|
|
|
Functions
| GdkSurface * | gdk_surface_new_toplevel () |
| GdkSurface * | gdk_surface_new_popup () |
| void | gdk_surface_destroy () |
| gboolean | gdk_surface_is_destroyed () |
| GdkDisplay * | gdk_surface_get_display () |
| void | gdk_surface_hide () |
| gboolean | gdk_surface_get_mapped () |
| gboolean | gdk_surface_translate_coordinates () |
| void | gdk_surface_beep () |
| int | gdk_surface_get_scale_factor () |
| void | gdk_surface_set_opaque_region () |
| GdkGLContext * | gdk_surface_create_gl_context () |
| GdkVulkanContext * | gdk_surface_create_vulkan_context () |
| GdkCairoContext * | gdk_surface_create_cairo_context () |
| void | gdk_surface_queue_render () |
| GdkFrameClock * | gdk_surface_get_frame_clock () |
| void | gdk_surface_set_cursor () |
| GdkCursor * | gdk_surface_get_cursor () |
| void | gdk_surface_set_input_region () |
| int | gdk_surface_get_width () |
| int | gdk_surface_get_height () |
| void | gdk_surface_set_shadow_width () |
| void | gdk_surface_get_device_position () |
| GdkCursor * | gdk_surface_get_device_cursor () |
| void | gdk_surface_set_device_cursor () |
Properties
| GdkCursor * | cursor | Read / Write |
| GdkDisplay * | display | Read / Write / Construct Only |
| GdkFrameClock * | frame-clock | Read / Write / Construct Only |
| gboolean | mapped | Read |
Signals
| void | enter-monitor | Run First |
| gboolean | event | Run Last |
| void | leave-monitor | Run First |
| void | popup-layout-changed | Run First |
| gboolean | render | Run Last |
| void | size-changed | Run First |
Types and Values
| GdkSurface | |
| enum | GdkGravity |
| enum | GdkSurfaceEdge |
| enum | GdkSurfaceState |
| enum | GdkModifierType |
| #define | GDK_MODIFIER_MASK |
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 GtkWindow on the GTK level.
Functions
gdk_surface_new_toplevel ()
GdkSurface * gdk_surface_new_toplevel (GdkDisplay *display,int width,int height);
Creates a new toplevel surface.
[constructor]
gdk_surface_new_popup ()
GdkSurface * gdk_surface_new_popup (GdkSurface *parent,gboolean autohide);
Create a new popup surface.
The surface will be attached to parent
and can be positioned relative to it
using gdk_surface_show_popup() or later using gdk_surface_layout_popup().
[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_is_destroyed ()
gboolean
gdk_surface_is_destroyed (GdkSurface *surface);
Check to see if a surface is destroyed..
gdk_surface_get_display ()
GdkDisplay *
gdk_surface_get_display (GdkSurface *surface);
Gets the GdkDisplay associated with a GdkSurface.
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_get_mapped ()
gboolean
gdk_surface_get_mapped (GdkSurface *surface);
Checks whether the surface has been mapped (with gdk_surface_show() or
gdk_surface_show_unraised()).
gdk_surface_translate_coordinates ()
gboolean gdk_surface_translate_coordinates (GdkSurface *from,GdkSurface *to,double *x,double *y);
Translates the given coordinates from being
relative to the from
surface to being relative
to the to
surface.
Note that this only works if to
and from
are
popups or transient-for to the same toplevel
(directly or indirectly).
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 ()
int
gdk_surface_get_scale_factor (GdkSurface *surface);
Returns the internal scale factor that maps from surface 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).
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 GtkWidgetClass.css_changed() 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_render ()
void
gdk_surface_queue_render (GdkSurface *surface);
Forces a “render” signal emission for surface
to be scheduled.
This function is useful for implementations that track invalid regions on their own.
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_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_set_input_region ()
void gdk_surface_set_input_region (GdkSurface *surface,cairo_region_t *region);
Apply the region to the surface for the purpose of 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 region 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 region controls where the surface is “clickable”.
Use gdk_display_support_input_shapes() to find out if
a particular backend supports input regions.
gdk_surface_get_width ()
int
gdk_surface_get_width (GdkSurface *surface);
Returns the width of the given surface
.
Surface size is reported in ”application pixels”, not
”device pixels” (see gdk_surface_get_scale_factor()).
gdk_surface_get_height ()
int
gdk_surface_get_height (GdkSurface *surface);
Returns the height of the given surface
.
Surface size is reported in ”application pixels”, not
”device pixels” (see gdk_surface_get_scale_factor()).
gdk_surface_set_shadow_width ()
void gdk_surface_set_shadow_width (GdkSurface *surface,int left,int right,int top,int 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_device_position ()
void 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] |
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_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.
Types and Values
GdkSurface
typedef struct _GdkSurface GdkSurface;
The GdkSurface struct contains only private fields and should not be accessed directly.
enum GdkGravity
Defines the reference point of a surface and is used in GdkPopupLayout.
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 GdkSurfaceEdge
Determines a surface edge or corner.
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 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.
Note that GDK may add internal values to events which include values outside
of this enumeration. Your code should preserve and ignore them. You can use
GDK_MODIFIER_MASK to remove all private values.
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 first mouse button. |
||
|
the second mouse button. |
||
|
the third mouse button. |
||
|
the fourth mouse button. |
||
|
the fifth mouse button. |
||
|
the Super modifier |
||
|
the Hyper modifier |
||
|
the Meta modifier |
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.
Owner: GdkSurface
Flags: Read / Write
The “display” property
“display” GdkDisplay *
The GdkDisplay connection of the surface. See gdk_surface_get_display()
for details.
Owner: GdkSurface
Flags: Read / Write / Construct Only
The “frame-clock” property
“frame-clock” GdkFrameClock *
Frame Clock.
Owner: GdkSurface
Flags: Read / Write / Construct Only
Signal Details
The “enter-monitor” signal
void user_function (GdkSurface *surface, GdkMonitor *monitor, gpointer user_data)
Emitted when surface
starts being present on the monitor.
Parameters
surface |
the GdkSurface |
|
monitor |
the monitor |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “event” signal
gboolean user_function (GdkSurface *surface, gpointer event, gpointer user_data)
Emitted when GDK receives an input event for surface
.
Parameters
surface |
the GdkSurface |
|
event |
an input event. |
[type Gdk.Event] |
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “leave-monitor” signal
void user_function (GdkSurface *surface, GdkMonitor *monitor, gpointer user_data)
Emitted when surface
stops being present on the monitor.
Parameters
surface |
the GdkSurface |
|
monitor |
the monitor |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “popup-layout-changed” signal
void user_function (GdkSurface *surface, gpointer user_data)
Emitted when the layout of a popup surface
has changed, e.g. if the popup
layout was reactive and after the parent moved causing the popover to end
up partially off-screen.
Parameters
surface |
the GdkSurface that was laid out |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
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.
Surface size is reported in ”application pixels”, not
”device pixels” (see gdk_surface_get_scale_factor()).
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 an 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
Owner: GdkGLContext
Flags: Read / Write / Construct Only
| 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
| 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/wayland/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 char *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 |
[closure] |
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 |
|
 |
|
|
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 a 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
- Toplevels — Interface for toplevel surfaces
- GdkToplevelLayout — Information for presenting toplevels
- Popups — Interface for popup surfaces
- GdkPopupLayout — Information for presenting popups
- 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
- GdkCairoContext — Cairo 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
- 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 | gdk_drag_drop_done () |
| GdkDrag * | gdk_drag_begin () |
| GdkDisplay * | gdk_drag_get_display () |
| GdkContentProvider * | gdk_drag_get_content () |
| 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_surface () |
| GdkSurface * | gdk_drag_get_drag_surface () |
| void | gdk_drag_set_hotspot () |
| gboolean | gdk_drag_action_is_unique () |
| gboolean | gdk_drag_surface_present () |
| 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 () |
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. After a drag has been started with gdk_drag_begin(),
the caller gets informed about the status of the ongoing drag operation
with signals on the GdkDrag object.
The GdkDrop object represents the target side of an ongoing DND operation.
Possible drop sites get informed about the status of the ongoing drag operation
with events of type GDK_DRAG_ENTER, GDK_DRAG_LEAVE, GDK_DRAG_MOTION and
GDK_DROP_START. The GdkDrop object can be obtained from these GdkEvents
using gdk_event_get_drop().
The actual data transfer is initiated from the target side via an async
read, using one of the GdkDrop functions for this purpose: gdk_drop_read_async()
or gdk_drop_read_value_async().
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,double dx,double dy);
Starts a drag and creates a new drag context for it.
This function is called by the drag source. After this call, you
probably want to set up the drag icon using the surface returned
by gdk_drag_get_drag_surface().
This function returns a reference to the GdkDrag object, but GTK keeps its own reference as well, as long as the DND operation is going on.
Note: if actions
include GDK_ACTION_MOVE, you need to listen for
the “dnd-finished” signal and delete the data at the source
if gdk_drag_get_selected_action() returns GDK_ACTION_MOVE.
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_content ()
GdkContentProvider *
gdk_drag_get_content (GdkDrag *drag);
Returns the GdkContentProvider associated to the GdkDrag object.
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_surface ()
GdkSurface *
gdk_drag_get_surface (GdkDrag *drag);
Returns the GdkSurface where the drag originates.
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,int hot_x,int 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_drag_surface_present ()
gboolean gdk_drag_surface_present (GdkDragSurface *drag_surface,int width,int height);
Present drag_surface
.
Parameters
drag_surface |
the GdkDragSurface to show |
|
width |
the unconstrained drag_surface width to layout |
|
height |
the unconstrained drag_surface height to layout |
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_drop_finish() must choose
the action to use when accepting the drop. This will only
happen if you passed GDK_ACTION_ASK as one of the possible
actions in gdk_drag_status(). GDK_ACTION_ASK itself will not
be included in the actions returned by this function.
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_drop_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,GdkDragAction preferred);
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.
The preferred
action is a hint to the drag'n'drop mechanism about which
action to use when multiple actions are possible.
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 |
|
preferred |
A unique action that's a member of |
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 |
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 GdkDrop and GdkDrag to indicate the actions that the destination can and should do with the dropped data.
Members
|
Copy the data. |
||
|
Move the data, i.e. first copy it, then delete it from the source using the DELETE target of the X selection protocol. |
||
|
Add a link to the data. Note that this is only useful if source and destination agree on what it means, and is not supported on all platforms. |
||
|
Ask the user what to do with the 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.
GdkDragSurface
typedef struct _GdkDragSurface GdkDragSurface;
A GdkDragSurface is an interface implemented by GdkSurfaces used during a DND operation.
Property Details
The “actions” property
“actions” GdkDragAction
The possible actions.
Owner: GdkDrag
Flags: Read / Write
The “content” property
“content” GdkContentProvider *
The GdkContentProvider.
Owner: GdkDrag
Flags: Read / Write / Construct Only
The “device” property
“device” GdkDevice *
The GdkDevice that is performing the drag.
Owner: GdkDrag
Flags: Read / Write / Construct Only
The “display” property
“display” GdkDisplay *
The GdkDisplay that the drag belongs to.
Owner: GdkDrag
Flags: Read
The “formats” property
“formats” GdkContentFormats *
The possible formats that the drag can provide its data in.
Owner: GdkDrag
Flags: Read / Write / Construct Only
The “selected-action” property
“selected-action” GdkDragAction
The currently selected action.
Owner: GdkDrag
Flags: Read / Write
The “surface” property
“surface” GdkSurface *
The surface where the drag originates.
Owner: GdkDrag
Flags: Read / Write / Construct Only
The “actions” property
“actions” GdkDragAction
The possible actions for this drop
Owner: GdkDrop
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
Owner: GdkDrop
Flags: Read / Write / Construct Only
The “display” property
“display” GdkDisplay *
The GdkDisplay that the drop belongs to.
Owner: GdkDrop
Flags: Read
The “drag” property
“drag” GdkDrag *
The GdkDrag that initiated this drop
Owner: GdkDrop
Flags: Read / Write / Construct Only
The “formats” property
“formats” GdkContentFormats *
The possible formats that the drop can provide its data in.
Owner: GdkDrop
Flags: Read / Write / Construct Only
The “surface” property
“surface” GdkSurface *
The GdkSurface the drop happens on
Owner: GdkDrop
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
| 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 guaranteed 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 (const 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 (const 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
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_CONTENTS 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.
Parameters
paintable |
||
snapshot |
a GdkSnapshot to snapshot to |
|
width |
width to snapshot in |
|
height |
height to snapshot in |
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 “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 “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 GdkPaintableInterface.get_current_image()
virtual function when the paintable is in an incomplete state (like a
GtkMediaStream before receiving the first frame).
Types and Values
struct GdkPaintableInterface
struct GdkPaintableInterface {
/* draw to 0,0 with the given width and height */
void (* snapshot) (GdkPaintable *paintable,
GdkSnapshot *snapshot,
double width,
double height);
/* get the current contents in an immutable form (optional) */
GdkPaintable * (* get_current_image) (GdkPaintable *paintable);
/* get flags for potential optimizations (optional) */
GdkPaintableFlags (* get_flags) (GdkPaintable *paintable);
/* preferred width of paintable or 0 if it has no width (optional) */
int (* get_intrinsic_width) (GdkPaintable *paintable);
/* preferred height of paintable or 0 if it has no height (optional) */
int (* get_intrinsic_height) (GdkPaintable *paintable);
/* aspect ratio (width / height) of paintable or 0 if it has no aspect ratio (optional) */
double (* get_intrinsic_aspect_ratio) (GdkPaintable *paintable);
};
The list of functions that can be implemented for the GdkPaintable interface.
Note that apart from the first function, no function is mandatory to implement,
though it is a good idea to implement GdkPaintableInterface.get_current_image()
for non-static paintables and GdkPaintableInterface.get_flags() if the image
is not dynamic as the default implementation returns no flags and that will
make the implementation likely quite slow.
Members
Snapshot the paintable. The given |
||
return a GdkPaintable that does not change over
time. This means the GDK_PAINTABLE_STATIC_SIZE and
|
||
Get the flags for this instance. See GdkPaintableFlags for details. |
||
The preferred width for this object to be snapshot at or 0 if none. This is purely a hint. The object must still be able to render at any size. |
||
The preferred height for this object to be snapshot at or 0 if none. This is purely a hint. The object must still be able to render at any size. |
||
The preferred aspect ratio for this object
or 0 if none. If both |
enum GdkPaintableFlags
Flags about this object. Implementations use these for optimizations such as caching.
Members
|
The size is immutable. The “invalidate-size” signal will never be emitted. |
||
|
The content is immutable. The “invalidate-contents” signal will never be emitted. |
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 | |
|
|
|
Functions
| int | gdk_device_pad_get_n_groups () |
| int | gdk_device_pad_get_group_n_modes () |
| int | gdk_device_pad_get_n_features () |
| int | 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 ()
int
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 ()
int gdk_device_pad_get_group_n_modes (GdkDevicePad *pad,int group_idx);
Returns the number of modes that group
may have.
gdk_device_pad_get_n_features ()
int 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 ()
int gdk_device_pad_get_feature_group (GdkDevicePad *pad,GdkDevicePadFeature feature,int 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_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.
Returns
TRUE if the context is between gdk_draw_context_begin_frame()
and gdk_draw_context_end_frame() calls.
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 | |
|
|
|
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 (gdk_event_get_time (event)); 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_get_display ()
GdkDisplay *
gdk_app_launch_context_get_display (GdkAppLaunchContext *context);
Gets the GdkDisplay that context
is for.
gdk_app_launch_context_set_desktop ()
void gdk_app_launch_context_set_desktop (GdkAppLaunchContext *context,int 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.
Property Details
The “display” property
“display” GdkDisplay *
Display.
Owner: GdkAppLaunchContext
Flags: Read / Write / Construct Only
| 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.
Owner: GdkClipboard
Flags: Read
The “display” property
“display” GdkDisplay *
The GdkDisplay that the clipboard belongs to.
Owner: GdkClipboard
Flags: Read / Write / Construct Only
The “formats” property
“formats” GdkContentFormats *
The possible formats that the clipboard can provide its data in.
Owner: GdkClipboard
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
Description
The functions in this section are specific to the GDK X11 backend.
To use them, you need to include the <gdk/x11/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_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 ()
int
gdk_x11_device_get_id (GdkDevice *device);
Returns the device ID as seen by XInput2.
gdk_x11_device_manager_lookup ()
GdkDevice * gdk_x11_device_manager_lookup (GdkX11DeviceManagerXI2 *device_manager,int device_id);
Returns the GdkDevice that wraps the given device ID.
Parameters
device_manager |
a GdkDeviceManager. |
[type GdkX11DeviceManagerXI2] |
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 GdkX11DeviceXI2]
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 char *
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 char *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_get_default_group ()
GdkSurface *
gdk_x11_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_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 ()
int
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 char *theme,const int 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,int 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,int *major,int *minor);
Retrieves the version of the GLX implementation.
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,int 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,const char *property_name);
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 char *name,const char *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 ()
int 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_get_xatom_by_name_for_display ()
Atom gdk_x11_get_xatom_by_name_for_display (GdkDisplay *display,const char *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 char * 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 char *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 ()
int gdk_x11_display_text_property_to_text_list (GdkDisplay *display,const char *encoding,int format,const guchar *text,int length,char ***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 |
a string 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 (char **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 ()
int gdk_x11_display_string_to_compound_text (GdkDisplay *display,const char *str,const char **encoding,int *format,guchar **ctext,int *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 (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 char *str,const char **encoding,int *format,guchar **ctext,int *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][transfer none] |
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
B
C
D
E
F
G
I
K
M
N
P
R
S
T
U
V
W
X
| Top | |
|
|
|
Functions
| cairo_surface_t * | gdk_surface_create_similar_surface () |
| 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_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,double pixbuf_x,double 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
| 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
| 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 | |
|
|
|
Functions
| gboolean | gdk_popup_present () |
| GdkGravity | gdk_popup_get_surface_anchor () |
| GdkGravity | gdk_popup_get_rect_anchor () |
| GdkSurface * | gdk_popup_get_parent () |
| int | gdk_popup_get_position_x () |
| int | gdk_popup_get_position_y () |
| gboolean | gdk_popup_get_autohide () |
Properties
| gboolean | autohide | Read / Write / Construct Only |
| GdkSurface * | parent | Read / Write / Construct Only |
Description
A GdkPopup is a surface that is attached to another surface, and is positioned relative to it.
Functions
gdk_popup_present ()
gboolean gdk_popup_present (GdkPopup *popup,int width,int height,GdkPopupLayout *layout);
Present popup
after having processed the GdkPopupLayout rules.
If the popup was previously now showing, it will be showed,
otherwise it will change position according to layout
.
After calling this function, the result of the layout can be queried
using gdk_popup_get_position_x(), gdk_popup_get_position_y(),
gdk_surface_get_width(), gdk_surface_get_height(),
gdk_popup_get_rect_anchor() and gdk_popup_get_surface_anchor().
Presenting may have fail, for example if it was immediately
hidden if the popup
was set to autohide.
Parameters
popup |
the GdkPopup to show |
|
width |
the unconstrained popup width to layout |
|
height |
the unconstrained popup height to layout |
|
layout |
the GdkPopupLayout object used to layout |
gdk_popup_get_surface_anchor ()
GdkGravity
gdk_popup_get_surface_anchor (GdkPopup *popup);
Gets the current popup surface anchor.
The value returned may change after calling gdk_popup_present(),
or after the "popup-layout-changed" is emitted.
gdk_popup_get_rect_anchor ()
GdkGravity
gdk_popup_get_rect_anchor (GdkPopup *popup);
Gets the current popup rectangle anchor.
The value returned may change after calling gdk_popup_present(),
or after the "popup-layout-changed" is emitted.
gdk_popup_get_parent ()
GdkSurface *
gdk_popup_get_parent (GdkPopup *popup);
Returns the parent surface of a popup.
gdk_popup_get_position_x ()
int
gdk_popup_get_position_x (GdkPopup *popup);
Obtains the position of the popup relative to its parent.
gdk_popup_get_position_y ()
int
gdk_popup_get_position_y (GdkPopup *popup);
Obtains the position of the popup relative to its parent.
Property Details
The “autohide” property
“autohide” gboolean
The parent surface.
Owner: GdkPopup
Flags: Read / Write / Construct Only
Default value: FALSE
The “parent” property
“parent” GdkSurface *
The parent surface.
Owner: GdkPopup
Flags: Read / Write / Construct Only
| 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_typed ()
GdkContentProvider * gdk_content_provider_new_typed (GType type,...);
Create a content provider that provides the value of the given
type
.
The value is provided using G_VALUE_COLLECT(), so the same rules
apply as when calling g_object_new() or g_object_set().
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_new_union ()
GdkContentProvider * gdk_content_provider_new_union (GdkContentProvider **providers,gsize n_providers);
Creates a content provider that represents all the given providers
.
Whenever data needs to be written, the union provider will try the given
providers
in the given order and the first one supporting a format will
be chosen to provide it.
This allows an easy way to support providing data in different formats. For example, an image may be provided by its file and by the iamge contents with a call such as
1 2 3 4 |
gdk_content_provider_new_union ((GdkContentProvider *[2]) { gdk_content_provider_new_typed (G_TYPE_FILE, file), gdk_content_provider_new_typed (G_TYPE_TEXTURE, texture) }, 2); |
Parameters
providers |
The GdkContentProviders to present the union of. |
[nullable][array length=n_providers][transfer full] |
n_providers |
the number of providers |
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 “content-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 contents 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.
Owner: GdkContentProvider
Flags: Read
The “storable-formats” property
“storable-formats” GdkContentFormats *
The subset of formats that clipboard managers should store this provider's data in.
Owner: GdkContentProvider
Flags: Read
Signal Details
The “content-changed” signal
void user_function (GdkContentProvider *gdkcontentprovider, gpointer user_data)
Emitted whenever the content provided by this provider has changed.
Flags: Run Last
|
|
|
 |
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.
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.
R
Rename the original symbol's name to SYMBOL.
S
The callback is valid until first called.
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
| const char * | gdk_device_get_name () |
| const char * | gdk_device_get_vendor_id () |
| const char * | gdk_device_get_product_id () |
| GdkInputSource | gdk_device_get_source () |
| GdkDisplay * | gdk_device_get_display () |
| gboolean | gdk_device_get_has_cursor () |
| GdkSeat * | gdk_device_get_seat () |
| guint | gdk_device_get_num_touches () |
| GdkDeviceTool * | gdk_device_get_device_tool () |
| gboolean | gdk_device_get_caps_lock_state () |
| PangoDirection | gdk_device_get_direction () |
| GdkModifierType | gdk_device_get_modifier_state () |
| gboolean | gdk_device_get_num_lock_state () |
| gboolean | gdk_device_get_scroll_lock_state () |
| gboolean | gdk_device_has_bidi_layouts () |
| GdkSurface * | gdk_device_get_surface_at_position () |
| guint64 | gdk_device_tool_get_serial () |
| GdkDeviceToolType | gdk_device_tool_get_tool_type () |
| guint64 | gdk_device_tool_get_hardware_id () |
| GdkAxisFlags | gdk_device_tool_get_axes () |
Properties
| gboolean | caps-lock-state | Read |
| PangoDirection | direction | Read |
| GdkDisplay * | display | Read / Write / Construct Only |
| gboolean | has-bidi-layouts | Read |
| gboolean | has-cursor | Read / Write / Construct Only |
| GdkModifierType | modifier-state | Read |
| guint | n-axes | Read |
| gchar * | name | Read / Write / Construct Only |
| gboolean | num-lock-state | Read |
| guint | num-touches | Read / Write / Construct Only |
| gchar * | product-id | Read / Write / Construct Only |
| gboolean | scroll-lock-state | Read |
| GdkSeat * | seat | Read / Write |
| GdkInputSource | source | Read / Write / Construct Only |
| GdkDeviceTool * | tool | Read |
| gchar * | vendor-id | Read / Write / Construct Only |
| GdkAxisFlags | axes | Read / Write / Construct Only |
| guint64 | hardware-id | Read / Write / Construct Only |
| guint64 | serial | Read / Write / Construct Only |
| GdkDeviceToolType | tool-type | Read / Write / Construct Only |
Types and Values
| GdkDevice | |
| enum | GdkInputSource |
| enum | GdkAxisUse |
| enum | GdkAxisFlags |
| GdkDeviceTool | |
| enum | GdkDeviceToolType |
| 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 logical and physical devices, and their relationships.
Functions
gdk_device_get_name ()
const char *
gdk_device_get_name (GdkDevice *device);
Determines the name of the device.
gdk_device_get_vendor_id ()
const char *
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 char *vendor, *product; GSettings *settings; GdkDevice *device; char *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 char *
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_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_seat ()
GdkSeat *
gdk_device_get_seat (GdkDevice *device);
Returns the GdkSeat the device belongs to.
gdk_device_get_num_touches ()
guint
gdk_device_get_num_touches (GdkDevice *device);
Retrieves the number of touch points associated to device
.
gdk_device_get_device_tool ()
GdkDeviceTool *
gdk_device_get_device_tool (GdkDevice *device);
Retrieves the GdkDeviceTool associated to device
.
gdk_device_get_caps_lock_state ()
gboolean
gdk_device_get_caps_lock_state (GdkDevice *device);
Retrieves whether the Caps Lock modifier of the
keyboard is locked, if device
is a keyboard device.
gdk_device_get_direction ()
PangoDirection
gdk_device_get_direction (GdkDevice *device);
Returns the direction of effective layout of the keyboard,
if device
is a keyboard device.
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_device_get_modifier_state ()
GdkModifierType
gdk_device_get_modifier_state (GdkDevice *device);
Retrieves the current modifier state of the keyboard,
if device
is a keyboard device.
gdk_device_get_num_lock_state ()
gboolean
gdk_device_get_num_lock_state (GdkDevice *device);
Retrieves whether the Num Lock modifier of the
keyboard is locked, if device
is a keyboard device.
gdk_device_get_scroll_lock_state ()
gboolean
gdk_device_get_scroll_lock_state (GdkDevice *device);
Retrieves whether the Scroll Lock modifier of the
keyboard is locked, if device
is a keyboard device.
gdk_device_has_bidi_layouts ()
gboolean
gdk_device_has_bidi_layouts (GdkDevice *device);
Determines if keyboard layouts for both right-to-left and
left-to-right languages are in use on the keyboard, if
device
is a keyboard device.
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).
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_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.
gdk_device_tool_get_axes ()
GdkAxisFlags
gdk_device_tool_get_axes (GdkDeviceTool *tool);
Gets the axes of the tool.
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 a keyboard. |
||
|
the device is a direct-input touch device, such as a touchscreen or tablet |
||
|
the device is an indirect touch device, such as a touchpad |
||
|
the device is a trackpoint |
||
|
the device is a "pad", a collection of buttons, rings and strips found in drawing tablets |
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 as the scroll x delta |
||
|
the axis is used as the scroll y delta |
||
|
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;
GdkAxisFlags flags;
double axes[GDK_AXIS_LAST];
};
A GdkTimeCoord stores a single event in a motion history.
Members
The timestamp for this event. |
||
GdkAxisFlags |
Flags indicating what axes are present |
|
axis values |
Property Details
The “caps-lock-state” property
“caps-lock-state” gboolean
Whether the keyboard caps lock is on.
Owner: GdkDevice
Flags: Read
Default value: FALSE
The “direction” property
“direction” PangoDirection
The direction of the current layout of the keyboard.
Owner: GdkDevice
Flags: Read
Default value: PANGO_DIRECTION_NEUTRAL
The “display” property
“display” GdkDisplay *
The GdkDisplay the GdkDevice pertains to.
Owner: GdkDevice
Flags: Read / Write / Construct Only
The “has-bidi-layouts” property
“has-bidi-layouts” gboolean
Whether the keyboard has bidi layouts.
Owner: GdkDevice
Flags: Read
Default value: FALSE
The “has-cursor” property
“has-cursor” gboolean
Whether the device is represented by a cursor on the screen.
Owner: GdkDevice
Flags: Read / Write / Construct Only
Default value: FALSE
The “modifier-state” property
“modifier-state” GdkModifierType
The modifier state of the keyboard.
Owner: GdkDevice
Flags: Read
The “n-axes” property
“n-axes” guint
Number of axes in the device.
Owner: GdkDevice
Flags: Read
Default value: 0
The “name” property
“name” gchar *
The device name.
Owner: GdkDevice
Flags: Read / Write / Construct Only
Default value: NULL
The “num-lock-state” property
“num-lock-state” gboolean
Whether the keyboard num lock is on.
Owner: GdkDevice
Flags: Read
Default value: FALSE
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.
Owner: GdkDevice
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().
Owner: GdkDevice
Flags: Read / Write / Construct Only
Default value: NULL
The “scroll-lock-state” property
“scroll-lock-state” gboolean
Whether the keyboard scroll lock is on.
Owner: GdkDevice
Flags: Read
Default value: FALSE
The “source” property
“source” GdkInputSource
Source type for the device.
Owner: GdkDevice
Flags: Read / Write / Construct Only
Default value: GDK_SOURCE_MOUSE
The “tool” property
“tool” GdkDeviceTool *
The tool that is currently used with this device.
Owner: GdkDevice
Flags: Read
The “vendor-id” property
“vendor-id” gchar *
Vendor ID of this device, see gdk_device_get_vendor_id().
Owner: GdkDevice
Flags: Read / Write / Construct Only
Default value: NULL
The “axes” property
“axes” GdkAxisFlags
Tool axes.
Owner: GdkDeviceTool
Flags: Read / Write / Construct Only
The “hardware-id” property
“hardware-id” guint64
Hardware ID.
Owner: GdkDeviceTool
Flags: Read / Write / Construct Only
Default value: 0
The “serial” property
“serial” guint64
Serial number.
Owner: GdkDeviceTool
Flags: Read / Write / Construct Only
Default value: 0
The “tool-type” property
“tool-type” GdkDeviceToolType
Tool type.
Owner: GdkDeviceTool
Flags: Read / Write / Construct Only
Default value: GDK_DEVICE_TOOL_TYPE_UNKNOWN
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 on X11 this will normally happen when the physical device routing events through the logical device changes (for example, user switches from the USB mouse to a tablet); in that case the logical device will change to reflect the axes and keys on the new physical device.
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
| Top | |
|
|
|
Functions
Signals
| void | closed | 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 char *
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_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_supports_input_shapes ()
gboolean
gdk_display_supports_input_shapes (GdkDisplay *display);
Returns TRUE if gdk_surface_set_input_region() can
be used to modify the input shape of surfaces on display
.
On modern displays, this value is always TRUE.
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 char *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.
Note that a display may not have a seat. In this case,
this function will return NULL.
gdk_display_list_seats ()
GList *
gdk_display_list_seats (GdkDisplay *display);
Returns the list of seats known to display
.
gdk_display_get_monitors ()
GListModel *
gdk_display_get_monitors (GdkDisplay *self);
Gets the list of monitors associated with this display.
Subsequent calls to this function will always return the same list for the same display.
You can listen to the GListModel::items-changed signal on this list to monitor changes to the monitor of this display.
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_startup_notification_id ()
const char *
gdk_display_get_startup_notification_id
(GdkDisplay *display);
Gets the startup notification ID for a Wayland display, or NULL
if no ID has been defined.
gdk_display_put_event ()
void gdk_display_put_event (GdkDisplay *display,GdkEvent *event);
Appends the given event onto the front of the event
queue for display
.
This function is only useful in very special situations and should not be used by applications.
gdk_display_map_keyval ()
gboolean gdk_display_map_keyval (GdkDisplay *display,guint keyval,GdkKeymapKey **keys,int *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().
gdk_display_map_keycode ()
gboolean gdk_display_map_keycode (GdkDisplay *display,guint keycode,GdkKeymapKey **keys,guint **keyvals,int *n_entries);
Returns the keyvals bound to keycode
. The Nth GdkKeymapKey
in keys
is bound to the Nth keyval in keyvals
.
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.
Free the returned arrays with g_free().
gdk_display_translate_key ()
gboolean gdk_display_translate_key (GdkDisplay *display,guint keycode,GdkModifierType state,int group,guint *keyval,int *effective_group,int *level,GdkModifierType *consumed);
Translates the contents of a GdkEventKey (ie keycode
, state
, and group
)
into a keyval, effective group, and level. Modifiers that affected the
translation and are thus unavailable for application use are returned in
consumed_modifiers
.
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
.
consumed_modifiers
gives modifiers that should be masked outfrom state
when comparing this key press to a keyboard shortcut. 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.
This function should rarely be needed, since GdkEventKey already contains the translated keyval. It is exported for the benefit of virtualized test environments.
Parameters
display |
||
keycode |
a keycode |
|
state |
a modifier state |
|
group |
active keyboard group |
|
keyval |
return location for keyval, or |
[out][optional] |
effective_group |
return location for effective
group, or |
[out][optional] |
level |
return location for level, or |
[out][optional] |
consumed |
return location for modifiers
that were used to determine the group or level, or |
[out][optional] |
Property Details
The “composited” property
“composited” gboolean
TRUE if the display properly composites the alpha channel.
See gdk_display_is_composited() for details.
Owner: GdkDisplay
Flags: Read
Default value: TRUE
The “input-shapes” property
“input-shapes” gboolean
TRUE if the display supports input shapes. See
gdk_display_supports_input_shapes() for details.
Owner: GdkDisplay
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.
Owner: GdkDisplay
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 “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 | |
|
|
|
Description
GdkCairoContext is an object representing the platform-specific draw context.
GdkCairoContexts are created for a GdkDisplay using
gdk_surface_create_cairo_context(), and the context can then be used
to draw on that GdkSurface.
Functions
gdk_cairo_context_cairo_create ()
cairo_t *
gdk_cairo_context_cairo_create (GdkCairoContext *self);
Retrieves a Cairo context to be used to draw on the GdkSurface
of context
. A call to gdk_draw_context_begin_frame() with this
context
must have been done or this function will return NULL.
The returned context is guaranteed to be valid until
gdk_draw_context_end_frame() is called.
Returns
a Cairo context to be used
to draw the contents of the GdkSurface. NULL is returned
when contet
is not drawing.
[transfer full][nullable]
| 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.
| 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.
| Top | |
|
|
|
Functions
| const char * | 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 are included in the data contained in a key press or release GdkEvent.
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
At the lowest level, physical keys on the keyboard are represented by
numeric keycodes, and GDK knows how to translate these keycodes into
key values according to the configured keyboard layout and the current
state of the keyboard. In the GDK api, the mapping from keycodes to key
values is available via gdk_display_map_keycode(), and the reverse mapping
is available via gdk_display_map_keyval(). The results of these functions
are returned in GdkKeymapKey structs.
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 normally only the uppercase letter is printed on the key. 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.
When GDK creates a key event in order to deliver a key press or release, it first converts the current 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 input to this translation consists of the hardware keycode pressed, the active modifiers, and the active group. It then 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 lookups because some keys don't have multiple groups - e.g. the Enter key is always in group 0 regardless of keyboard state.
The results of the translation, including the keyval, are all included in the key event and can be obtained via GdkEvent getters.
Consumed modifiers
The consumed_modifiers
in a key event are modifiers that should be masked
out from 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 9 10 11 |
// We want to ignore irrelevant modifiers like ScrollLock #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_ALT_MASK) state = gdk_event_get_modifier_state (event); gdk_keymap_translate_keyboard_state (keymap, gdk_key_event_get_keycode (event), state, gdk_key_event_get_group (event), &keyval, NULL, NULL, &consumed); if (keyval == GDK_PLUS && (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 && (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.
Functions
gdk_keyval_name ()
const char *
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 char *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.
Note that the conversion does not take the current locale
into consideration, which might be expected for particular
keyvals, such as GDK_KEY_KP_Decimal.
| 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,int x_origin,int y_origin,const int *index_ranges,int 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,int x_origin,int y_origin,const int *index_ranges,int 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 | |
|
|
|
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,int src_x,int src_y,int width,int 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.
gdk_pixbuf_get_from_texture ()
GdkPixbuf *
gdk_pixbuf_get_from_texture (GdkTexture *texture);
Creates a new pixbuf from texture
. This should generally not be used
in newly written code as later stages will almost certainly convert
the pixbuf back into a texture to draw it on screen.
| 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
| 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 () |
| char * | 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 char *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 ()
char *
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 {
float red;
float green;
float blue;
float alpha;
} GdkRGBA;
A GdkRGBA is used to represent a (possibly translucent) color, in a way that is compatible with cairo’s notion of color.