Class: Gtk::Builder

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

Class Method Summary collapse

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



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/gtk3/builder.rb', line 65

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

  if path
    path = path.to_path if path.respond_to?(:to_path)
    initialize_new_from_file(path)
  elsif resource
    initialize_new_from_resource(resource)
  elsif string
    initialize_new_from_string(string, string.bytesize)
  else
    initialize_raw
  end
end

Class Method Details

.connect_signal(builder, object, signal_name, handler_name, connect_object, flags, &block) ⇒ Object 



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
 
# File 'lib/gtk3/builder.rb', line 20

def connect_signal(builder,
                   object,
                   signal_name,
                   handler_name,
                   connect_object,
                   flags,
                   &block)
  handler_name = normalize_handler_name(handler_name)
  if connect_object
    handler = connect_object.method(handler_name)
  else
    handler = block.call(handler_name)
  end

  unless handler
    $stderr.puts("Undefined handler: #{handler_name}") if $DEBUG
    return
  end

  if flags.is_a?(Integer)
    flags = GLib::ConnectFlags.new(flags)
  end

  if flags.after?
    signal_connect_method = :signal_connect_after
  else
    signal_connect_method = :signal_connect
  end

  if handler.arity.zero?
    object.__send__(signal_connect_method, signal_name) do
      handler.call
    end
  else
    object.__send__(signal_connect_method, signal_name, &handler)
  end
end

Instance Method Details

#<<(target) ⇒ Object 



143
144
145
146
 
# File 'lib/gtk3/builder.rb', line 143

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

#add(target_or_options = {}) ⇒ Object 



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/gtk3/builder.rb', line 94

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



85
86
87
 
# File 'lib/gtk3/builder.rb', line 85

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/gtk3/builder.rb', line 84

#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



90
91
92
 
# File 'lib/gtk3/builder.rb', line 90

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/gtk3/builder.rb', line 89

#connect_signals(&block) ⇒ Object 



149
150
151
152
153
 
# File 'lib/gtk3/builder.rb', line 149

def connect_signals(&block)
  connect_signals_raw do |*args|
    self.class.connect_signal(*args, &block)
  end
end

#connect_signals_raw ⇒ Object 



148
 
# File 'lib/gtk3/builder.rb', line 148

alias_method :connect_signals_raw, :connect_signals

#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/gtk3/builder.rb', line 64

#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