Functions ========= .. currentmodule:: gi.repository.Gdk .. function:: cairo_draw_from_gl(cr: ~gi.repository.cairo.Context, surface: ~gi.repository.Gdk.Surface, source: int, source_type: int, buffer_scale: int, x: int, y: int, width: int, height: int) -> None The main way to not 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. .. deprecated:: 4.6 The function is overly complex and produces broken output in various combinations of arguments. If you want to draw with GL textures in GTK, use :obj:`~gi.repository.Gdk.GLTexture.new`\; if you want to use that texture in Cairo, use :obj:`~gi.repository.Gdk.Texture.download` to download the data into a Cairo image surface. :param cr: a cairo context :param surface: The surface we're rendering for (not necessarily into) :param source: The GL ID of the source buffer :param source_type: The type of the ``source`` :param buffer_scale: The scale-factor that the ``source`` buffer is allocated for :param x: The source x position in ``source`` to start copying from in GL coordinates :param y: The source y position in ``source`` to start copying from in GL coordinates :param width: The width of the region to draw :param height: The height of the region to draw .. function:: cairo_rectangle(cr: ~gi.repository.cairo.Context, rectangle: ~gi.repository.Gdk.Rectangle) -> None Adds the given rectangle to the current path of ``cr``\. :param cr: a cairo context :param rectangle: a ``GdkRectangle`` .. function:: cairo_region(cr: ~gi.repository.cairo.Context, region: ~gi.repository.cairo.Region) -> None Adds the given region to the current path of ``cr``\. :param cr: a cairo context :param region: a ``cairo_region_t`` .. function:: cairo_region_create_from_surface(surface: ~gi.repository.cairo.Surface) -> ~gi.repository.cairo.Region Creates region that 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(). :param surface: a cairo surface :return: A ``cairo_region_t`` .. function:: cairo_set_source_pixbuf(cr: ~gi.repository.cairo.Context, pixbuf: ~gi.repository.GdkPixbuf.Pixbuf, pixbuf_x: float, pixbuf_y: float) -> None 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``\. :param cr: a cairo context :param pixbuf: a ``GdkPixbuf`` :param pixbuf_x: X coordinate of location to place upper left corner of ``pixbuf`` :param pixbuf_y: Y coordinate of location to place upper left corner of ``pixbuf`` .. function:: cairo_set_source_rgba(cr: ~gi.repository.cairo.Context, rgba: ~gi.repository.Gdk.RGBA) -> None Sets the specified ``GdkRGBA`` as the source color of ``cr``\. :param cr: a cairo context :param rgba: a ``GdkRGBA`` .. function:: color_state_get_rec2100_linear() -> ~gi.repository.Gdk.ColorState .. function:: color_state_get_rec2100_pq() -> ~gi.repository.Gdk.ColorState .. function:: color_state_get_srgb() -> ~gi.repository.Gdk.ColorState .. function:: color_state_get_srgb_linear() -> ~gi.repository.Gdk.ColorState .. function:: content_deserialize_async(stream: ~gi.repository.Gio.InputStream, mime_type: str, type: ~gobject.GType, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Read content from the given input stream and deserialize it, asynchronously. The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers indicate a higher priority. :param stream: a ``GInputStream`` to read the serialized content from :param mime_type: the mime type to deserialize from :param type: the GType to deserialize from :param io_priority: the I/O priority of the operation :param cancellable: optional ``GCancellable`` object :param callback: callback to call when the operation is done :param user_data: data to pass to the callback function .. function:: content_deserialize_finish(result: ~gi.repository.Gio.AsyncResult) -> ~typing.Tuple[bool, ~gi.repository.GObject.Value] Finishes a content deserialization operation. :param result: the ``GAsyncResult`` :return: :const:`True` if the operation was successful. In this case, ``value`` is set. :const:`False` if an error occurred. In this case, ``error`` is set .. function:: content_formats_parse(string: str) -> ~gi.repository.Gdk.ContentFormats | None :param string: .. function:: content_register_deserializer(mime_type: str, type: ~gobject.GType, deserialize: ~typing.Callable[[~gi.repository.Gdk.ContentDeserializer], None], data: ~typing.Any = None) -> None Registers a function to deserialize object of a given type. :param mime_type: the mime type which the function can deserialize from :param type: the type of objects that the function creates :param deserialize: the callback :param data: data that ``deserialize`` can access .. function:: content_register_serializer(type: ~gobject.GType, mime_type: str, serialize: ~typing.Callable[[~gi.repository.Gdk.ContentSerializer], None], data: ~typing.Any = None) -> None Registers a function to serialize objects of a given type. :param type: the type of objects that the function can serialize :param mime_type: the mime type to serialize to :param serialize: the callback :param data: data that ``serialize`` can access .. function:: content_serialize_async(stream: ~gi.repository.Gio.OutputStream, mime_type: str, value: ~gi.repository.GObject.Value, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Serialize content and write it to the given output stream, asynchronously. The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers indicate a higher priority. :param stream: a ``GOutputStream`` to write the serialized content to :param mime_type: the mime type to serialize to :param value: the content to serialize :param io_priority: the I/O priority of the operation :param cancellable: optional ``GCancellable`` object :param callback: callback to call when the operation is done :param user_data: data to pass to the callback function .. function:: content_serialize_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes a content serialization operation. :param result: the ``GAsyncResult`` :return: :const:`True` if the operation was successful, :const:`False` if an error occurred. In this case, ``error`` is set .. function:: dmabuf_error_quark() -> int .. function:: drag_action_is_unique(action: ~gi.repository.Gdk.DragAction) -> bool :param action: .. function:: events_get_angle(event1: ~gi.repository.Gdk.Event, event2: ~gi.repository.Gdk.Event) -> ~typing.Tuple[bool, float] Returns the relative angle from ``event1`` to ``event2``\. The relative angle is the angle between the X axis and the line through both events' positions. The rotation direction for positive angles is from the positive X axis towards the positive Y axis. This assumes that both events have X/Y information. If not, this function returns :const:`False`. :param event1: first ``GdkEvent`` :param event2: second ``GdkEvent`` :return: :const:`True` if the angle could be calculated. .. function:: events_get_center(event1: ~gi.repository.Gdk.Event, event2: ~gi.repository.Gdk.Event) -> ~typing.Tuple[bool, float, float] Returns the point halfway between the events' positions. This assumes that both events have X/Y information. If not, this function returns :const:`False`. :param event1: first ``GdkEvent`` :param event2: second ``GdkEvent`` :return: :const:`True` if the center could be calculated. .. function:: events_get_distance(event1: ~gi.repository.Gdk.Event, event2: ~gi.repository.Gdk.Event) -> ~typing.Tuple[bool, float] Returns the distance between the event locations. This assumes that both events have X/Y information. If not, this function returns :const:`False`. :param event1: first ``GdkEvent`` :param event2: second ``GdkEvent`` :return: :const:`True` if the distance could be calculated. .. function:: gl_error_quark() -> int .. function:: intern_mime_type(string: str) -> str | None Canonicalizes the given mime type and interns the result. If ``string`` is not a valid mime type, :const:`None` is returned instead. See RFC 2048 for the syntax if mime types. :param string: string of a potential mime type :return: An interned string for the canonicalized mime type or :const:`None` if the string wasn't a valid mime type .. function:: keyval_convert_case(symbol: int) -> ~typing.Tuple[int, int] 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. :param symbol: a keyval .. function:: keyval_from_name(keyval_name: str) -> int 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_``\”. :param keyval_name: a key name :return: the corresponding key value, or :const:`~gi.repository.Gdk.KEY_VOIDSYMBOL` if the key name is not a valid key .. function:: keyval_is_lower(keyval: int) -> bool Returns :const:`True` if the given key value is in lower case. :param keyval: a key value. :return: :const:`True` if ``keyval`` is in lower case, or if ``keyval`` is not subject to case conversion. .. function:: keyval_is_upper(keyval: int) -> bool Returns :const:`True` if the given key value is in upper case. :param keyval: a key value. :return: :const:`True` if ``keyval`` is in upper case, or if ``keyval`` is not subject to case conversion. .. function:: keyval_name(keyval: int) -> str | None 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_``\”. :param keyval: a key value :return: a string containing the name of the key .. function:: keyval_to_lower(keyval: int) -> int Converts a key value to lower case, if applicable. :param keyval: a key value. :return: the lower case form of ``keyval``\, or ``keyval`` itself if it is already in lower case or it is not subject to case conversion. .. function:: keyval_to_unicode(keyval: int) -> int Convert from a GDK key symbol to the corresponding Unicode character. Note that the conversion does not take the current locale into consideration, which might be expected for particular keyvals, such as :const:`~gi.repository.Gdk.KEY_KP_DECIMAL`. :param keyval: a GDK key symbol :return: the corresponding unicode character, or 0 if there is no corresponding character. .. function:: keyval_to_upper(keyval: int) -> int Converts a key value to upper case, if applicable. :param keyval: a key value. :return: the upper case form of ``keyval``\, or ``keyval`` itself if it is already in upper case or it is not subject to case conversion. .. function:: paintable_new_empty(intrinsic_width: int, intrinsic_height: int) -> ~gi.repository.Gdk.Paintable :param intrinsic_width: :param intrinsic_height: .. function:: pixbuf_get_from_surface(surface: ~gi.repository.cairo.Surface, src_x: int, src_y: int, width: int, height: int) -> ~gi.repository.GdkPixbuf.Pixbuf | None Transfers image data from a ``cairo_surface_t`` and converts it to 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. .. deprecated:: 4.12 Use :obj:`~gi.repository.Gdk.Texture` and subclasses instead cairo surfaces and pixbufs :param surface: surface to copy from :param src_x: Source X coordinate within ``surface`` :param src_y: Source Y coordinate within ``surface`` :param width: Width in pixels of region to get :param height: Height in pixels of region to get :return: A newly-created pixbuf with a reference count of 1 .. function:: pixbuf_get_from_texture(texture: ~gi.repository.Gdk.Texture) -> ~gi.repository.GdkPixbuf.Pixbuf | None 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. .. deprecated:: 4.12 Use :obj:`~gi.repository.Gdk.Texture` and subclasses instead cairo surfaces and pixbufs :param texture: a ``GdkTexture`` :return: a new ``GdkPixbuf`` .. function:: set_allowed_backends(backends: str) -> None 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: .. code-block:: c :dedent: gdk_set_allowed_backends ("wayland,macos,*"); instructs GDK to try the Wayland backend first, followed by the MacOs 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: - ``broadway`` - ``macos`` - ``wayland``\. - ``win32`` - ``x11`` You can also include a ``*`` in the list to try all remaining backends. This call must happen prior to functions that open a display, such as :obj:`~gi.repository.Gdk.Display.open`\, ``gtk_init()``\, or ``gtk_init_check()`` in order to take effect. :param backends: a comma-separated list of backends .. function:: texture_error_quark() -> int .. function:: unicode_to_keyval(wc: int) -> int Convert from a Unicode character to a key symbol. :param wc: a Unicode character :return: the corresponding GDK key symbol, if one exists. or, if there is no corresponding symbol, wc | 0x01000000 .. function:: vulkan_error_quark() -> int