Finds or creates an atom corresponding to a given string.
Parameters
atom_name: string
a string.
only_if_exists: boolean
if %TRUE, GDK is allowed to not create a new atom, but just return %GDK_NONE if the requested atom doesn’t already exists. Currently, the flag is ignored, since checking the existance of an atom is as expensive as creating it.
Finds or creates an atom corresponding to a given string.
Note that this function is identical to gdk_atom_intern() except
that if a new #GdkAtom is created the string itself is used rather
than a copy. This saves memory, but can only be used if the string
will always exist. It can be used with statically
allocated strings in the main program, but not with statically
allocated memory in dynamically loaded modules, if you expect to
ever unload the module again (e.g. do not use this function in
GTK+ theme engines).
Note that calling cairo_reset_clip() on the resulting #cairo_t will
produce undefined results, so avoid it at all costs.
Typically, this function is used to draw on a #GdkWindow out of the paint
cycle of the toolkit; this should be avoided, as it breaks various assumptions
and optimizations.
If you are drawing on a native #GdkWindow in response to a %GDK_EXPOSE event
you should use gdk_window_begin_draw_frame() and gdk_drawing_context_get_cairo_context()
instead. GTK will automatically do this for you when drawing a widget.
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 window 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 window 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.
This is a convenience function around cairo_clip_extents().
It rounds the clip extents to integer coordinates and returns
a boolean indicating if a clip area exists.
Sets the given window as the source pattern for cr.
The pattern has an extend mode of %CAIRO_EXTEND_NONE and is aligned
so that the origin of window is x,y. The window contains all its
subwindows when rendering.
Note that the contents of window are undefined outside of the
visible part of window, so use this function with care.
Parses a textual specification of a color and fill in the
red,green, and blue fields of a #GdkColor.
The string can either one of a large set of standard names
(taken from the X11 rgb.txt file), or it can be a hexadecimal
value in the form “#rgb” “#rrggbb”, “#rrrgggbbb” or
“#rrrrggggbbbb” where “r”, “g” and “b” are hex digits of
the red, green, and blue components of the color, respectively.
(White in the four forms is “#fff”, “#ffffff”, “#fffffffff”
and “#ffffffffffff”).
Disables multidevice support in GDK. This call must happen prior
to gdk_display_open(), gtk_init(), gtk_init_with_args() or
gtk_init_check() in order to take effect.
Most common GTK+ applications won’t ever need to call this. Only
applications that do mixed GDK/Xlib calls could want to disable
multidevice support if such Xlib code deals with input devices in
any way and doesn’t observe the presence of XInput 2.
Starts a drag and creates a new drag context for it.
This function assumes that the drag is controlled by the
client pointer device, use gdk_drag_begin_for_device() to
begin a drag with a different device.
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
context.
The #GdkDragContext 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.
Returns whether the dropped data has been successfully
transferred. This function is intended to be used while
handling a %GDK_DROP_FINISHED event, its return value is
meaningless at other times.
Removes an error trap pushed with gdk_error_trap_push().
May block until an error has been definitively received
or not received from the X server. gdk_error_trap_pop_ignored()
is preferred if you don’t need to know whether an error
occurred, because it never has to block. If you don't
need the return value of gdk_error_trap_pop(), use
gdk_error_trap_pop_ignored().
Prior to GDK 3.0, this function would not automatically
sync for you, so you had to gdk_flush() if your last
call to Xlib was not a blocking round trip.
Returns number
error_trap_pop_ignored
error_trap_pop_ignored(): void
Removes an error trap pushed with gdk_error_trap_push(), but
without bothering to wait and see whether an error occurred. If an
error arrives later asynchronously that was triggered while the
trap was pushed, that error will be ignored.
Returns void
error_trap_push
error_trap_push(): void
This function allows X errors to be trapped instead of the normal
behavior of exiting the application. It should only be used if it
is not possible to avoid the X error in any other way. Errors are
ignored on all #GdkDisplay currently known to the
#GdkDisplayManager. If you don’t care which error happens and just
want to ignore everything, pop with gdk_error_trap_pop_ignored().
If you need the error code, use gdk_error_trap_pop() which may have
to block and wait for the error to arrive from the X server.
This API exists on all platforms but only does anything on X.
You can use gdk_x11_display_error_trap_push() to ignore errors
on only a single display.
Checks all open displays for a #GdkEvent to process,to be processed
on, fetching events from the windowing system if necessary.
See gdk_display_get_event().
Sets the function to call to handle all events from GDK.
Note that GTK+ uses this to install its own event handler, so it is
usually not useful for GTK+ applications. (Although an application
can call this function then call gtk_main_do_event() to pass
events to GTK+.)
Request more motion notifies if event is a motion notify hint event.
This function should be used instead of gdk_window_get_pointer() to
request further motion notifies, because it also works for extension
events where motion notifies are provided for devices other than the
core pointer. Coordinate extraction, processing and requesting more
motion events from a %GDK_MOTION_NOTIFY event usually works like this:
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.
Gets the name of the display, which usually comes from the
DISPLAY environment variable or the
--display command line option.
Returns string
get_display_arg_name
get_display_arg_name(): string | null
Gets the display name specified in the command line arguments passed
to gdk_init() or gdk_parse_args(), if any.
Returns string | null
get_program_class
get_program_class(): string
Gets the program class. Unless the program class has explicitly
been set with gdk_set_program_class() or with the --class
commandline option, the default value is the program name (determined
with g_get_prgname()) with the first character converted to uppercase.
Initializes the GDK library and connects to the windowing system.
If initialization fails, a warning message is output and the application
terminates with a call to exit(1).
Any arguments used by GDK are removed from the array and argc and argv
are updated accordingly.
GTK+ initializes GDK in gtk_init() and so this function is not usually
needed by GTK+ applications.
Parameters
argv: string[]
the array of command line arguments.
Returns string[]
init_check
init_check(argv: string[]): [boolean, string[]]
Initializes the GDK library and connects to the windowing system,
returning %TRUE on success.
Any arguments used by GDK are removed from the array and argc and argv
are updated accordingly.
GTK+ initializes GDK in gtk_init() and so this function is not usually
needed by GTK+ applications.
Grabs the keyboard so that all events are passed to this
application until the keyboard is ungrabbed with gdk_keyboard_ungrab().
This overrides any previous keyboard grab by this client.
If you set up anything at the time you take the grab that needs to be cleaned
up when the grab ends, you should handle the #GdkEventGrabBroken events that
are emitted when the grab ends unvoluntarily.
the #GdkWindow which will own the grab (the grab window).
owner_events: boolean
if %FALSE then all keyboard events are reported with respect to window. If %TRUE then keyboard events for this application are reported as normal, but keyboard events outside this application are reported with respect to window. Both key press and key release events are always reported, independant of the event mask set by the application.
time_: number
a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is available.
Lists the available visuals for the default screen.
(See gdk_screen_list_visuals())
A visual describes a hardware image data format.
For example, a visual might support 24-bit color, or 8-bit color,
and might expect pixels to be in a certain format.
Call g_list_free() on the return value when you’re finished with it.
Indicates to the GUI environment that the application has finished
loading. If the applications opens windows, this function is
normally called after opening the application’s initial set of
windows.
GTK+ will call this function automatically after opening the first
#GtkWindow unless gtk_window_set_auto_startup_notification() is called
to disable that feature.
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.
Parameters
startup_id: string
a startup-notification identifier, for which notification process should be completed
Gets the offscreen surface that an offscreen window renders into.
If you need to keep this around over window resizes, you need to
add a reference to it.
To fully embed an offscreen window, in addition to calling this
function, it is also necessary to handle the #GdkWindow::pick-embedded-child
signal on the embedder and the #GdkWindow::to-embedder and
#GdkWindow::from-embedder signals on window.
Creates a #PangoContext for the default GDK screen.
The context must be freed when you’re finished with it.
When using GTK+, normally you should use gtk_widget_get_pango_context()
instead of this function, to get the appropriate context for
the widget you intend to render text onto.
The newly created context will have the default font options (see
#cairo_font_options_t) for the default screen; if these options
change it will not be updated. Using gtk_widget_get_pango_context()
is more convenient if you want to keep a context around and track
changes to the screen’s font rendering settings.
The context must be freed when you’re finished with it.
When using GTK+, normally you should use gtk_widget_get_pango_context()
instead of this function, to get the appropriate context for
the widget you intend to render text onto.
The newly created context will have the default font options
(see #cairo_font_options_t) for the display; if these options
change it will not be updated. Using gtk_widget_get_pango_context()
is more convenient if you want to keep a context around and track
changes to the font rendering settings.
The context must be freed when you’re finished with it.
When using GTK+, normally you should use gtk_widget_get_pango_context()
instead of this function, to get the appropriate context for
the widget you intend to render text onto.
The newly created context will have the default font options
(see #cairo_font_options_t) for the screen; if these options
change it will not be updated. Using gtk_widget_get_pango_context()
is more convenient if you want to keep a context around and track
changes to the screen’s font rendering settings.
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. For #GdkWindows, use
gdk_pixbuf_get_from_window() instead.
This function will create an RGB pixbuf with 8 bits per channel.
The pixbuf will contain an alpha channel if the surface contains one.
Transfers image data from a #GdkWindow and converts it to an RGB(A)
representation inside a #GdkPixbuf. In other words, copies
image data from a server-side drawable to a client-side RGB(A) buffer.
This allows you to efficiently read individual pixels on the client side.
This function will create an RGB pixbuf with 8 bits per channel with
the size specified by the width and height arguments scaled by the
scale factor of window. The pixbuf will contain an alpha channel if
the window contains one.
If the window is off the screen, then there is no image data in the
obscured/offscreen regions to be placed in the pixbuf. The contents of
portions of the pixbuf corresponding to the offscreen region are undefined.
If the window you’re obtaining data from is partially obscured by
other windows, then the contents of the pixbuf areas corresponding
to the obscured regions are undefined.
If the window is not mapped (typically because it’s iconified/minimized
or not on the current workspace), then %NULL will be returned.
If memory can’t be allocated for the return value, %NULL will be returned
instead.
(In short, there are several ways this function can fail, and if it fails
it returns %NULL; so check the return value.)
Grabs the pointer (usually a mouse) so that all events are passed to this
application until the pointer is ungrabbed with gdk_pointer_ungrab(), or
the grab window becomes unviewable.
This overrides any previous pointer grab by this client.
Pointer grabs are used for operations which need complete control over mouse
events, even if the mouse leaves the application.
For example in GTK+ it is used for Drag and Drop, for dragging the handle in
the #GtkHPaned and #GtkVPaned widgets.
Note that if the event mask of an X window has selected both button press and
button release events, then a button press event will cause an automatic
pointer grab until the button is released.
X does this automatically since most applications expect to receive button
press and release events in pairs.
It is equivalent to a pointer grab on the window with owner_events set to
%TRUE.
If you set up anything at the time you take the grab that needs to be cleaned
up when the grab ends, you should handle the #GdkEventGrabBroken events that
are emitted when the grab ends unvoluntarily.
the #GdkWindow which will own the grab (the grab window).
owner_events: boolean
if %FALSE then all pointer events are reported with respect to window and are only reported if selected by event_mask. If %TRUE then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to window and only if selected by event_mask. In either mode, unreported events are discarded.
specifies the event mask, which is used in accordance with owner_events. Note that only pointer events (i.e. button and motion events) may be selected.
If non-%NULL, the pointer will be confined to this window during the grab. If the pointer is outside confine_to, it will automatically be moved to the closest edge of confine_to and enter and leave events will be generated as necessary.
the cursor to display while the grab is active. If this is %NULL then the normal cursors are used for window and its descendants, and the cursor for window is used for all other windows.
time_: number
the timestamp of the event which led to this pointer grab. This usually comes from a #GdkEventButton struct, though %GDK_CURRENT_TIME can be used if the time isn’t known.
Retrieves a portion of the contents of a property. If the
property does not exist, then the function returns %FALSE,
and %GDK_NONE will be stored in actual_property_type.
The XGetWindowProperty() function that gdk_property_get()
uses has a very confusing and complicated set of semantics.
Unfortunately, gdk_property_get() makes the situation
worse instead of better (the semantics should be considered
undefined), and also prints warnings to stderr in cases where it
should return a useful error to the program. You are advised to use
XGetWindowProperty() directly until a replacement function for
gdk_property_get() is provided.
the desired property type, or %GDK_NONE, if any type of data is acceptable. If this does not match the actual type, then actual_format and actual_length will be filled in, a warning will be printed to stderr and no data will be returned.
offset: number
the offset into the property at which to begin retrieving data, in 4 byte units.
length: number
the length of the data to retrieve in bytes. Data is considered to be retrieved in 4 byte chunks, so length will be rounded up to the next highest 4 byte boundary (so be careful not to pass a value that might overflow when rounded up).
pdelete: number
if %TRUE, delete the property after retrieving the data.
This function returns the available bit depths for the default
screen. It’s equivalent to listing the visuals
(gdk_list_visuals()) and then looking at the depth field in each
visual, removing duplicates.
The array returned by this function should not be freed.
This function returns the available visual types for the default
screen. It’s equivalent to listing the visuals
(gdk_list_visuals()) and then looking at the type field in each
visual, removing duplicates.
The array returned by this function should not be freed.
the timestamp to use when retrieving the selection. The selection owner may refuse the request if it did not own the selection at the time indicated by the timestamp.
Note that the return value may be owned by a different
process if a foreign window was previously created for that
window, but a new foreign window will never be created by this call.
timestamp to use when setting the selection. If this is older than the timestamp given last time the owner was set for the given selection, the request will be ignored.
send_event: boolean
if %TRUE, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event.
timestamp to use when setting the selection If this is older than the timestamp given last time the owner was set for the given selection, the request will be ignored
send_event: boolean
if %TRUE, and the new owner is different from the current owner, the current owner will be sent a SelectionClear event
property in which the selection owner stored the data, or %GDK_NONE to indicate that the request was rejected
time_: number
timestamp
Returns void
set_allowed_backends
set_allowed_backends(backends: string): void
Sets a list of backends that GDK should try to use.
This can be be useful if your application does not
work with certain GDK backends.
By default, GDK tries all included backends.
For example,
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(), gtk_init_with_args() or gtk_init_check()
in order to take effect.
Parameters
backends: string
a comma-separated list of backends
Returns void
set_double_click_time
set_double_click_time(msec: number): void
Set the double click time for the default display. See
gdk_display_set_double_click_time().
See also gdk_display_set_double_click_distance().
Applications should not set this, it is a
global user-configured setting.
Parameters
msec: number
double click time in milliseconds (thousandths of a second)
Returns void
set_program_class
set_program_class(program_class: string): void
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.
The program class can still be overridden with the --class command
line option.
Parameters
program_class: string
a string.
Returns void
set_show_events
set_show_events(show_events: boolean): void
Sets whether a trace of received events is output.
Note that GTK+ must be compiled with debugging (that is,
configured using the --enable-debug option)
to use this option.
Parameters
show_events: boolean
%TRUE to output event debugging information.
Returns void
setting_get
setting_get(name: string, value: any): boolean
Obtains a desktop-wide setting, such as the double-click time,
for the default screen. See gdk_screen_get_setting().
This function is intended to be used in GTK+ test programs.
It will warp the mouse pointer to the given (x,``y) coordinates
within window and simulate a button press or release event.
Because the mouse pointer needs to be warped to the target
location, use of this function outside of test programs that
run in their own virtual windowing system (e.g. Xvfb) is not
recommended.
Also, gdk_test_simulate_button() is a fairly low level function,
for most testing purposes, gtk_test_widget_click() is the right
function to call which will generate a button press event followed
by its accompanying button release event.
This function is intended to be used in GTK+ test programs.
If (x,``y) are > (-1,-1), it will warp the mouse pointer to
the given (x,``y) coordinates within window and simulate a
key press or release event.
When the mouse pointer is warped to the target location, use
of this function outside of test programs that run in their
own virtual windowing system (e.g. Xvfb) is not recommended.
If (x,``y) are passed as (-1,-1), the mouse pointer will not
be warped and window origin will be used as mouse pointer
location for the event.
Also, gdk_test_simulate_key() is a fairly low level function,
for most testing purposes, gtk_test_widget_send_key() is the
right function to call which will generate a key press event
followed by its accompanying key release event.
threads_add_idle(priority: number, function_: SourceFunc): number
Adds a function to be called whenever there are no higher priority
events pending. If the function returns %FALSE it is automatically
removed from the list of event sources and will not be called again.
This variant of g_idle_add_full() calls function with the GDK lock
held. It can be thought of a MT-safe version for GTK+ widgets for the
following use case, where you have to worry about idle_callback()
running in thread A and accessing self after it has been finalized
in thread B:
static gboolean idle_callback (gpointer data) { // gdk_threads_enter(); would be needed for g_idle_add()
SomeWidget *self = data; // do stuff with self
self->idle_id = 0;
// gdk_threads_leave(); would be needed for g_idle_add() returnFALSE; }
staticvoid some_widget_do_stuff_later (SomeWidget *self) { self->idle_id = gdk_threads_add_idle (idle_callback, self) // using g_idle_add() here would require thread protection in the callback }
threads_add_timeout(priority: number, interval: number, function_: SourceFunc): number
Sets a function to be called at regular intervals holding the GDK lock,
with the given priority. The function is called repeatedly until it
returns %FALSE, at which point the timeout is automatically destroyed
and the function will not be called again. The notify function is
called when the timeout is destroyed. The first call to the
function will be at the end of the first interval.
Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to “catch up” time lost in delays).
This variant of g_timeout_add_full() can be thought of a MT-safe version
for GTK+ widgets for the following use case:
threads_add_timeout_seconds(priority: number, interval: number, function_: SourceFunc): number
A variant of gdk_threads_add_timeout_full() with second-granularity.
See g_timeout_add_seconds_full() for a discussion of why it is
a good idea to use this function if you don’t need finer granularity.
Parameters
priority: number
the priority of the timeout source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
interval: number
the time between calls to the function, in seconds
This function marks the beginning of a critical section in which
GDK and GTK+ functions can be called safely and without causing race
conditions. Only one thread at a time can be in such a critial
section.
Returns void
threads_init
threads_init(): void
Initializes GDK so that it can be used from multiple threads
in conjunction with gdk_threads_enter() and gdk_threads_leave().
This call must be made before any use of the main loop from
GTK+; to be safe, call it before gtk_init().
Returns void
threads_leave
threads_leave(): void
Leaves a critical region begun with gdk_threads_enter().
Returns void
unicode_to_keyval
unicode_to_keyval(wc: number): number
Convert from a ISO10646 character to a key symbol.
Parameters
wc: number
a ISO10646 encoded character
Returns number
utf8_to_string_target
utf8_to_string_target(str: string): string | null
Converts an UTF-8 string into the best possible representation
as a STRING. The representation of characters not in STRING
is not specified; it may be as pseudo-escape sequences
\x{ABCD}, or it may be in some other form of approximation.
The middle button.