Class: Gtk::Image

Inherits:
Widget
  • Object
show all
Extended by:
GLib::Deprecatable
Defined in:
lib/gtk4/image.rb,
lib/gtk4/deprecated.rb

Overview

The GtkImage widget displays an image.

An example GtkImage

Various kinds of object can be displayed as an image; most typically, you would load a GdkTexture from a file, using the convenience function [ctorGtk.Image.new_from_file], for instance:

GtkWidget *image = gtk_image_new_from_file ("myfile.png");

If the file isn’t loaded successfully, the image will contain a “broken image” icon similar to that used in many web browsers.

If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with [ctorGdk.Texture.new_from_file], then create the GtkImage with [ctorGtk.Image.new_from_paintable].

Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of GResource inside GIO, for details. In this case, [propertyGtk.Image:resource], [ctorGtk.Image.new_from_resource], and [methodGtk.Image.set_from_resource] should be used.

GtkImage displays its image as an icon, with a size that is determined by the application. See [classGtk.Picture] if you want to show an image at is actual size.

CSS nodes

GtkImage has a single CSS node with the name image. The style classes .normal-icons or .large-icons may appear, depending on the [propertyGtk.Image:icon-size] property.

Accessibility

GtkImage uses the GTK_ACCESSIBLE_ROLE_IMG role.

Instance Method Summary collapse

Methods inherited from Widget

#accessible_role, #accessible_role=, #action_set_enabled, #activate, #activate_action, #activate_action_variant, #activate_default, #activate_signal, #activate_signal=, #activate_signal_from_name=, #add_binding, #add_binding_action, #add_binding_signal, #add_controller, #add_css_class, #add_mnemonic_label, #add_shortcut, #add_tick_callback, #allocate, #allocated_baseline, #allocated_height, #allocated_width, #baseline, #bind_template_callback_full, #bind_template_child, #bind_template_child_full, #can_focus, #can_focus=, #can_focus?, #can_target, #can_target=, #can_target?, #child_focus, #child_visible, #child_visible=, #children, #clipboard, #compute_bounds, #compute_expand, #compute_point, #compute_transform, #contains, #create_pango_context, #create_pango_layout, #css_classes, #css_classes=, #css_name, #css_name=, #cursor, #cursor=, #cursor_from_name=, default_direction, default_direction=, #direction, #direction=, #display, #dispose_template, #drag_check_threshold, #error_bell, #first_child, #focus_child, #focus_child=, #focus_on_click, #focus_on_click=, #focus_on_click?, #focusable, #focusable=, #focusable?, #font_map, #font_map=, #font_options, #font_options=, #frame_clock, #get_allocation, #get_ancestor, #get_color, #get_preferred_size, #get_size, #get_size_request, #get_template_child, #grab_focus, #halign, #halign=, #has_css_class, #has_default, #has_default=, #has_default?, #has_focus, #has_focus=, #has_focus?, #has_tooltip, #has_tooltip=, #has_tooltip?, #has_visible_focus, have_template?, #height, #height_request, #height_request=, #hexpand, #hexpand=, #hexpand?, #hexpand_set, #hexpand_set=, #hexpand_set?, #hide, #in_destruction, #init_template, #insert_action_group, #insert_action_group_raw, #insert_after, #insert_before, #install_action, #install_property_action, #is_ancestor, #is_drawable, #is_focus, #is_sensitive, #is_visible, #keynav_failed, #last_child, #layout_manager, #layout_manager=, #layout_manager_type, #layout_manager_type=, #list_mnemonic_labels, #map, #mapped, #margin_bottom, #margin_bottom=, #margin_end, #margin_end=, #margin_start, #margin_start=, #margin_top, #margin_top=, #measure, #mnemonic_activate, #name, #name=, #native, #next_sibling, #observe_children, #observe_controllers, #opacity, #opacity=, #overflow, #overflow=, #pango_context, #parent, #parent=, #pick, #prev_sibling, #primary_clipboard, #query_action, #queue_allocate, #queue_draw, #queue_resize, #realize, #realized, #receives_default, #receives_default=, #receives_default?, #remove_controller, #remove_css_class, #remove_mnemonic_label, #remove_tick_callback, #request_mode, #root, #root=, #scale_factor, #scale_factor=, #sensitive, #sensitive=, #sensitive?, #set_size_request, #set_size_request_raw, #set_state_flags, #set_template, #set_template_raw, #settings, #should_layout, #show, #size_allocate, #snapshot_child, #state_flags, #style_context, #style_context_raw, #template=, template_children, #template_from_resource=, #template_scope=, #tooltip_markup, #tooltip_markup=, #tooltip_text, #tooltip_text=, #translate_coordinates, #translate_coordinates_raw, #trigger_tooltip_query, #unmap, #unparent, #unrealize, #unset_state_flags, #valign, #valign=, #vexpand, #vexpand=, #vexpand?, #vexpand_set, #vexpand_set=, #vexpand_set?, #visible, #visible=, #visible?, #width, #width_request, #width_request=

Constructor Details

#initialize(options = {}) ⇒ Image

Creates a Gtk::Image. The source of the image depends on the options given.

icon = Gio::Icon.new_for_string 'path/to/the/image.png' image = Gtk::Image.new(icon: icon)

Examples:

Create an empty image.

image = Gtk::Image.new

Create an image from a file.

image = Gtk::Image.new(file: 'path/to/the/image.png')

Create an image from icon name.

image = Gtk::Image.new(icon_name: 'gtk-open')

Create an image from a Gio::Icon, that itself is loaded from a

file.

Create an image from from a Gio::Icon that is an Gio::ThemedIcon.

icon = Gio::ThemedIcon.new 'gtk-open'
image = Gtk::Image.new(icon: icon)

Create an image from a GdkPixbuf::Pixbuf.

pixbuf = GdkPixbuf::Pixbuf.new(:file => 'path/to/the/image.png')
image = Gtk::Image.new(pixbuf: pixbuf)

Create an image from a file in a resource file

resource = Gio::Resource.load(a_resource_file)
Gio::Resources.register(resource)
resource_path = "/path/to/image.png"
image = Gtk::Image.new(resource: resource_path)

Create an image from a paintable

Gio::File.open(path: "my.png") do |file|
  texture = Gdk::Texture.new(file)
  image = Gtk::Image.new(paintable: texture)
end

Parameters:

  • Hash (Symbol => String, Gio::Icon, GdkPixbuf::Pixbuf, Gdk::Paintable) 


58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/gtk4/image.rb', line 58

def initialize(options={})
  icon_name = options[:icon_name] || nil
  icon      = options[:icon] || options[:gicon] || nil
  file      = options[:file] || nil
  pixbuf    = options[:pixbuf] || nil
  resource  = options[:resource] || nil
  paintable = options[:paintable] || nil

  if icon_name
    initialize_new_from_icon_name(icon_name)
  elsif icon
    initialize_new_from_gicon(icon)
  elsif file
    initialize_new_from_file(file)
  elsif pixbuf
    initialize_new_from_pixbuf(pixbuf)
  elsif resource
    initialize_new_from_resource(resource)
  elsif paintable
    initialize_new_from_paintable(paintable)
  else
    initialize_raw
  end
end

Instance Method Details

#clear ⇒ nil

Resets the image to be empty.

Returns:

  • (nil)

#file ⇒ String

A path to the file to display.

Returns:

  • (String) —

    file

#file=(file) ⇒ String

A path to the file to display.

Parameters:

  • file (String)

Returns:

  • (String) —

    file

  • (String) —

    file

#from_file=(filename) ⇒ nil

Sets a GtkImage to show a file.

See [ctorGtk.Image.new_from_file] for details.

Parameters:

  • filename (Gtk::filename) —

    a filename

Returns:

  • (nil)

#from_gicon=(icon) ⇒ nil

Sets a GtkImage to show a GIcon.

See [ctorGtk.Image.new_from_gicon] for details.

Parameters:

  • icon (Gio::Icon) —

    an icon

Returns:

  • (nil)

#from_icon_name=(icon_name) ⇒ nil

Sets a GtkImage to show a named icon.

See [ctorGtk.Image.new_from_icon_name] for details.

Parameters:

  • icon_name (String) —

    an icon name

Returns:

  • (nil)

#from_paintable=(paintable) ⇒ nil

Sets a GtkImage to show a GdkPaintable.

See [ctorGtk.Image.new_from_paintable] for details.

Parameters:

Returns:

  • (nil)

#from_pixbuf=(pixbuf) ⇒ nil

Sets a GtkImage to show a GdkPixbuf.

See [ctorGtk.Image.new_from_pixbuf] for details.

Note: This is a helper for [methodGtk.Image.set_from_paintable], and you can't get back the exact pixbuf once this is called, only a paintable.

Parameters:

  • pixbuf (GdkPixbuf::Pixbuf) —

    a GdkPixbuf or NULL

Returns:

  • (nil)

#from_resource=(resource_path) ⇒ nil

Sets a GtkImage to show a resource.

See [ctorGtk.Image.new_from_resource] for details.

Parameters:

  • resource_path (String) —

    a resource path

Returns:

  • (nil)

#gicon ⇒ Gio::Icon

The GIcon displayed in the GtkImage.

For themed icons, If the icon theme is changed, the image will be updated automatically.

Returns:

  • (Gio::Icon) —

    gicon

#gicon=(gicon) ⇒ Gio::Icon

The GIcon displayed in the GtkImage.

For themed icons, If the icon theme is changed, the image will be updated automatically.

Parameters:

  • gicon (Gio::Icon)

Returns:

  • (Gio::Icon) —

    gicon

  • (Gio::Icon) —

    gicon

#icon_name ⇒ String

The name of the icon in the icon theme.

If the icon theme is changed, the image will be updated automatically.

Returns:

  • (String) —

    icon-name

#icon_name=(icon_name) ⇒ String

The name of the icon in the icon theme.

If the icon theme is changed, the image will be updated automatically.

Parameters:

  • icon_name (String)

Returns:

  • (String) —

    icon-name

  • (String) —

    icon-name

#icon_size ⇒ Gtk::IconSize

The symbolic size to display icons at.

Returns:

#icon_size=(icon_size) ⇒ Gtk::IconSize

The symbolic size to display icons at.

Parameters:

Returns:

#initialize_raw ⇒ Gtk::Widget

Creates a new GtkImage displaying the resource file resource_path.

If the file isn’t found or can’t be loaded, the resulting GtkImage will display a “broken image” icon. This function never returns nil, it always returns a valid GtkImage widget.

If you need to detect failures to load the file, use [ctorGdkPixbuf.Pixbuf.new_from_file] to load the file yourself, then create the GtkImage from the pixbuf.

The storage type (see [methodGtk.Image.get_storage_type]) of the returned image is not defined, it will be whatever is appropriate for displaying the file.

Parameters:

  • resource_path (String) —

    a resource path

Returns:




# File 'lib/gtk4/image.rb', line 19

#paintable ⇒ Gdk::Paintable

The GdkPaintable to display.

Returns:

#paintable=(paintable) ⇒ Gdk::Paintable

The GdkPaintable to display.

Parameters:

Returns:

#pixel_size ⇒ Integer

The size in pixels to display icons at.

If set to a value != -1, this property overrides the [propertyGtk.Image:icon-size] property for images of type GTK_IMAGE_ICON_NAME.

Returns:

  • (Integer) —

    pixel-size

#pixel_size=(pixel_size) ⇒ Integer

The size in pixels to display icons at.

If set to a value != -1, this property overrides the [propertyGtk.Image:icon-size] property for images of type GTK_IMAGE_ICON_NAME.

Parameters:

  • pixel_size (Integer)

Returns:

  • (Integer) —

    pixel-size

  • (Integer) —

    pixel-size

#resource ⇒ String

A path to a resource file to display.

Returns:

  • (String) —

    resource

#resource=(resource) ⇒ String

A path to a resource file to display.

Parameters:

  • resource (String)

Returns:

  • (String) —

    resource

  • (String) —

    resource

#storage_type ⇒ Gtk::ImageType

The representation being used for image data.

Returns:

#storage_type=(storage_type) ⇒ Gtk::ImageType

The representation being used for image data.

Parameters:

Returns:

#use_fallback=(use_fallback) ⇒ Boolean

Whether the icon displayed in the GtkImage will use standard icon names fallback.

The value of this property is only relevant for images of type %GTK_IMAGE_ICON_NAME and %GTK_IMAGE_GICON.

Parameters:

  • use_fallback (Boolean)

Returns:

  • (Boolean) —

    use-fallback

  • (Boolean) —

    use-fallback

#use_fallback? ⇒ Boolean

Whether the icon displayed in the GtkImage will use standard icon names fallback.

The value of this property is only relevant for images of type %GTK_IMAGE_ICON_NAME and %GTK_IMAGE_GICON.

Returns:

  • (Boolean) —

    use-fallback