Class: Gtk::Builder

Inherits:
Object
  • Object
show all
Defined in:
lib/gtk4/builder.rb

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Gtk::Builder

Parses the UI definition in string.

If string is nil-terminated, then length should be -1. If length is not -1, then it is the length of string.

If there is an error parsing string then the program will be aborted. You should not attempt to parse user interface description from untrusted sources.

Parameters:

  • string (String) —

    a user interface (XML) description

  • length (Gtk::gssize) —

    the length of string, or -1



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/gtk4/builder.rb', line 22

def initialize(options={})
  object = options[:object]
  path = options[:path] || options[:file]
  resource = options[:resource]
  string = options[:string]

  initialize_new
  set_current_object(object) if object
  set_scope(RubyBuilderScope.new)

  if path
    path = path.to_path if path.respond_to?(:to_path)
    add_from_file(path)
  elsif resource
    add_from_resource(resource)
  elsif string
    add_from_string(string)
  end
end

Instance Method Details

#<<(target) ⇒ Object 



103
104
105
106
 
# File 'lib/gtk4/builder.rb', line 103

def <<(target)
  add(target)
  self
end

#add(target_or_options = {}) ⇒ Object 



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/gtk4/builder.rb', line 54

def add(target_or_options={})
  if target_or_options.is_a?(Hash)
    options = target_or_options
  else
    target = target_or_options
    options = {}
    if target.respond_to?(:to_path)
      options[:path] = target.to_path
    elsif target.start_with?("<") or target.start_with?(" ")
      options[:string] = target
    elsif File.exist?(target)
      options[:path] = target
    else
      options[:resource] = target
    end
  end

  string   = options[:string]
  path     = options[:path] || options[:file]
  resource = options[:resource]

  object_ids = options[:object_ids]

  if path
    path = path.to_path if path.respond_to?(:to_path)
    if object_ids
      add_objects_from_file(path, object_ids)
    else
      add_from_file(path)
    end
  elsif resource
    if object_ids
      add_objects_from_resource(resource, object_ids)
    else
      add_from_resource(resource)
    end
  elsif string
    if object_ids
      add_objects_from_string(string, object_ids)
    else
      add_from_string(string)
    end
  else
    message = ":path (:file), :resource or :string " +
      "must be specified: #{options.inspect}"
    raise InvalidArgument, message
  end
end

#add_from_file(filename) ⇒ Boolean

Parses a file containing a UI definition and merges it with the current contents of builder.

This function is useful if you need to call [methodGtk.Builder.set_current_object]) to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctorGtk.Builder.new_from_file] instead.

If an error occurs, 0 will be returned and error will be assigned a GError from the GTK_BUILDER_ERROR, G_MARKUP_ERROR or G_FILE_ERROR domains.

It’s not really reasonable to attempt to handle failures of this call. You should not use this function with untrusted files (ie: files that are not part of your application). Broken GtkBuilder files can easily crash your program, and it’s possible that memory was leaked leading up to the reported failure. The only reasonable thing to do when an error is detected is to call g_error().

Parameters:

  • filename (Gtk::filename) —

    the name of the file to parse

Returns:

  • (Boolean) —

    true on success, false if an error occurred

#add_from_resource(resource_path) ⇒ Boolean

Parses a resource file containing a UI definition and merges it with the current contents of builder.

This function is useful if you need to call [methodGtk.Builder.set_current_object] to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctorGtk.Builder.new_from_resource] instead.

If an error occurs, 0 will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_RESOURCE_ERROR domain.

It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error().

Parameters:

  • resource_path (String) —

    the path of the resource file to parse

Returns:

  • (Boolean) —

    true on success, false if an error occurred

#add_from_string(string) ⇒ Boolean

Parses a string containing a UI definition and merges it with the current contents of builder.

This function is useful if you need to call [methodGtk.Builder.set_current_object] to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctorGtk.Builder.new_from_string] instead.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_VARIANT_PARSE_ERROR domain.

It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error().

Parameters:

  • buffer (String) —

    the string to parse

  • length (Gtk::gssize) —

    the length of buffer (may be -1 if buffer is nul-terminated)

Returns:

  • (Boolean) —

    true on success, false if an error occurred



45
46
47
 
# File 'lib/gtk4/builder.rb', line 45

def add_from_string(string)
  add_from_string_raw(string, string.bytesize)
end

#add_from_string_raw ⇒ Boolean

Parses a string containing a UI definition and merges it with the current contents of builder.

This function is useful if you need to call [methodGtk.Builder.set_current_object] to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctorGtk.Builder.new_from_string] instead.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_VARIANT_PARSE_ERROR domain.

It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error().

Parameters:

  • buffer (String) —

    the string to parse

  • length (Gtk::gssize) —

    the length of buffer (may be -1 if buffer is nul-terminated)

Returns:

  • (Boolean) —

    true on success, false if an error occurred




# File 'lib/gtk4/builder.rb', line 44

#add_objects_from_file(filename, object_ids) ⇒ Boolean

Parses a file containing a UI definition building only the requested objects and merges them with the current contents of builder.

Upon errors, 0 will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_FILE_ERROR domain.

If you are adding an object that depends on an object that is not its child (for instance a GtkTreeView that depends on its GtkTreeModel), you have to explicitly list all of them in object_ids.

Parameters:

  • filename (Gtk::filename) —

    the name of the file to parse

  • object_ids (Array<String>) —

    nul-terminated array of objects to build

Returns:

  • (Boolean) —

    true on success, false if an error occurred

#add_objects_from_resource(resource_path, object_ids) ⇒ Boolean

Parses a resource file containing a UI definition, building only the requested objects and merges them with the current contents of builder.

Upon errors, 0 will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_RESOURCE_ERROR domain.

If you are adding an object that depends on an object that is not its child (for instance a GtkTreeView that depends on its GtkTreeModel), you have to explicitly list all of them in object_ids.

Parameters:

  • resource_path (String) —

    the path of the resource file to parse

  • object_ids (Array<String>) —

    nul-terminated array of objects to build

Returns:

  • (Boolean) —

    true on success, false if an error occurred

#add_objects_from_string(string, object_ids) ⇒ Boolean

Parses a string containing a UI definition, building only the requested objects and merges them with the current contents of builder.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR or %G_MARKUP_ERROR domain.

If you are adding an object that depends on an object that is not its child (for instance a GtkTreeView that depends on its GtkTreeModel), you have to explicitly list all of them in object_ids.

Parameters:

  • buffer (String) —

    the string to parse

  • length (Gtk::gssize) —

    the length of buffer (may be -1 if buffer is nul-terminated)

  • object_ids (Array<String>) —

    nul-terminated array of objects to build

Returns:

  • (Boolean) —

    true on success, false if an error occurred



50
51
52
 
# File 'lib/gtk4/builder.rb', line 50

def add_objects_from_string(string, object_ids)
  add_objects_from_string_raw(string, string.bytesize, object_ids)
end

#add_objects_from_string_raw ⇒ Boolean

Parses a string containing a UI definition, building only the requested objects and merges them with the current contents of builder.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR or %G_MARKUP_ERROR domain.

If you are adding an object that depends on an object that is not its child (for instance a GtkTreeView that depends on its GtkTreeModel), you have to explicitly list all of them in object_ids.

Parameters:

  • buffer (String) —

    the string to parse

  • length (Gtk::gssize) —

    the length of buffer (may be -1 if buffer is nul-terminated)

  • object_ids (Array<String>) —

    nul-terminated array of objects to build

Returns:

  • (Boolean) —

    true on success, false if an error occurred




# File 'lib/gtk4/builder.rb', line 49

#create_closure(function_name, flags, object) ⇒ GObject::Closure

Creates a closure to invoke the function called function_name.

This is using the create_closure() implementation of builder's [ifaceGtk.BuilderScope].

If no closure could be created, nil will be returned and error will be set.

Parameters:

  • function_name (String) —

    name of the function to look up

  • flags (Gtk::BuilderClosureFlags) —

    closure creation flags

  • object (GObject::Object) —

    Object to create the closure with

Returns:

  • (GObject::Closure) —

    A new closure for invoking function_name

#current_object ⇒ GObject::Object

The object the builder is evaluating for.

Returns:

  • (GObject::Object) —

    current-object

#current_object=(current_object) ⇒ GObject::Object

The object the builder is evaluating for.

Parameters:

  • current_object (GObject::Object)

Returns:

  • (GObject::Object) —

    current-object

  • (GObject::Object) —

    current-object

#expose_object(name, object) ⇒ nil

Add object to the builder object pool so it can be referenced just like any other object built by builder.

Only a single object may be added using name. However, it is not an error to expose the same object under multiple names. gtk_builder_get_object() may be used to determine if an object has already been added with name.

Parameters:

  • name (String) —

    the name of the object exposed to the builder

  • object (GObject::Object) —

    the object to expose

Returns:

  • (nil)

#extend_with_template(object, template_type, buffer, length) ⇒ Boolean

Main private entry point for building composite components from template XML.

Most likely you do not need to call this function in applications as templates are handled by GtkWidget.

Parameters:

  • object (GObject::Object) —

    the object that is being extended

  • template_type (GLib::Type) —

    the type that the template is for

  • buffer (String) —

    the string to parse

  • length (Gtk::gssize) —

    the length of buffer (may be -1 if buffer is nul-terminated)

Returns:

  • (Boolean) —

    A positive value on success, 0 if an error occurred

#get_object(name) ⇒ GObject::Object Also known as: []

Gets the object named name.

Note that this function does not increment the reference count of the returned object.

Parameters:

  • name (String) —

    name of object to get

Returns:

  • (GObject::Object) —

    the object named name

#get_type_from_name(type_name) ⇒ GLib::Type

Looks up a type by name.

This is using the virtual function that GtkBuilder has for that purpose. This is mainly used when implementing the GtkBuildable interface on a type.

Parameters:

  • type_name (String) —

    type name to lookup

Returns:

  • (GLib::Type) —

    the GType found for type_name or %G_TYPE_INVALID if no type was found

#initialize_raw ⇒ Gtk::Builder

Parses the UI definition in string.

If string is nil-terminated, then length should be -1. If length is not -1, then it is the length of string.

If there is an error parsing string then the program will be aborted. You should not attempt to parse user interface description from untrusted sources.

Parameters:

  • string (String) —

    a user interface (XML) description

  • length (Gtk::gssize) —

    the length of string, or -1

Returns:

  • (Gtk::Builder) —

    a GtkBuilder containing the interface described by string




# File 'lib/gtk4/builder.rb', line 21

#objects ⇒ GLib::SList<GObject::Object>

Gets all objects that have been constructed by builder.

Note that this function does not increment the reference counts of the returned objects.

Returns:

  • (GLib::SList<GObject::Object>) —

    a newly-allocated GSList containing all the objects constructed by the GtkBuilder instance. It should be freed by g_slist_free()

#scope ⇒ Gtk::BuilderScope

The scope the builder is operating in

Returns:

#scope=(scope) ⇒ Gtk::BuilderScope

The scope the builder is operating in

Parameters:

Returns:

#translation_domain ⇒ String

The translation domain used when translating property values that have been marked as translatable.

If the translation domain is nil, GtkBuilder uses gettext(), otherwise g_dgettext().

Returns:

  • (String) —

    translation-domain

#translation_domain=(translation_domain) ⇒ String

The translation domain used when translating property values that have been marked as translatable.

If the translation domain is nil, GtkBuilder uses gettext(), otherwise g_dgettext().

Parameters:

  • translation_domain (String)

Returns:

  • (String) —

    translation-domain

  • (String) —

    translation-domain

#value_from_string(pspec, string, value) ⇒ Boolean

Demarshals a value from a string.

This function calls g_value_init() on the value argument, so it need not be initialised beforehand.

Can handle char, uchar, boolean, int, uint, long, ulong, enum, flags, float, double, string, GdkRGBA and GtkAdjustment type values.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR domain.

Parameters:

  • pspec (GObject::ParamSpec) —

    the GParamSpec for the property

  • string (String) —

    the string representation of the value

  • value (GObject::Value) —

    the GValue to store the result in

Returns:

  • (Boolean) —

    true on success

#value_from_string_type(type, string, value) ⇒ Boolean

Demarshals a value from a string.

Unlike [methodGtk.Builder.value_from_string], this function takes a GType instead of GParamSpec.

Calls g_value_init() on the value argument, so it need not be initialised beforehand.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR domain.

Parameters:

  • type (GLib::Type) —

    the GType of the value

  • string (String) —

    the string representation of the value

  • value (GObject::Value) —

    the GValue to store the result in

Returns:

  • (Boolean) —

    true on success