gtk3 3.0.5 → 3.0.6

data/sample/tutorial/README.md

@@ -521,3 +521,418 @@ In this line, given that `self` is `ExampleAppWindow` the usage of `stack` is a
 https://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.8
 
 *    exampleapp4/exampleapp.rb
+
+An application menu is shown by GNOME shell at the top of the screen. It is meant to collect infrequently used actions that affect the whole application.
+Just like the window template, we specify our application menu in a ui file, and add it as a resource to our binary.
+
+#### Adding the menu interface
+
+*    app-menu.ui
+```xml
+<?xml version="1.0"?>
+<interface>
+  <!-- interface-requires gtk+ 3.0 -->
+  <menu id="appmenu">
+    <section>
+      <item>
+        <attribute name="label" translatable="yes">_Preferences</attribute>
+        <attribute name="action">app.preferences</attribute>
+      </item>
+    </section>
+    <section>
+      <item>
+        <attribute name="label" translatable="yes">_Quit</attribute>
+        <attribute name="action">app.quit</attribute>
+      </item>
+    </section>
+  </menu>
+</interface>
+```
+
+This menu interface is loaded and added to our application with :
+
+```ruby
+builder = Gtk::Builder.new(:resource => "/org/gtk/exampleapp/app-menu.ui")
+app_menu = builder.get_object("appmenu")
+application.set_app_menu(app_menu)
+```
+
+With this, our application has a menu with two items that we can show when clicking on the application icon in the Gnome shell.
+
+#### Linking menu items to actions.
+
+All the actions initialization should be done during the "startup" step, which is guaranteed to be called once for each primary application instance.
+
+The "quit" item in the menu is implemented with this:
+
+```xml
+<section>
+  <item>
+    <attribute name="label" translatable="yes">_Quit</attribute>
+    <attribute name="action">app.quit</attribute>
+  </item>
+</section>
+```
+
+Then we just have to create an `Gio::SimpleAction` named "quit" and configure it in order to quit the application when this action is triggered.
+
+```ruby
+action = Gio::SimpleAction.new("quit")
+action.signal_connect("activate") do |_action, parameter|
+  application.quit
+end
+application.add_action(action)
+
+```
+
+#### Add accelerators for action.
+
+An accelerator is just a keys combination that acts as a shortcut for an action. 
+
+```ruby
+quit_accels = ["<Ctrl>Q"]
+action = Gio::SimpleAction.new("quit")
+action.signal_connect("activate") do |_action, parameter|
+  application.quit
+end
+application.add_action(action)
+application.set_accels_for_action("app.quit", quit_accels)
+```
+
+### A preferences dialog
+https://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.9
+
+### Define and store settings for an application with gschemas
+*    exampleapp5/exampleapp.rb
+
+A typical application will have a some preferences that should be remembered from one run to the next. Even for our simple example application, we may want to change the font that is used for the content.
+We are going to use `Gio::Settings` to store our preferences. `Gio::Settings` requires a schema that describes our settings:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<schemalist>
+  <schema path="/org/gtk/exampleapp/" id="org.gtk.exampleapp">
+    <key name="font" type="s">
+      <default>'Monospace 12'</default>
+      <summary>Font</summary>
+      <description>The font to be used for content.</description>
+    </key>
+    <key name="transition" type="s">
+      <choices>
+        <choice value='none'/>
+        <choice value='crossfade'/>
+        <choice value='slide-left-right'/>
+      </choices>
+      <default>'none'</default>
+      <summary>Transition</summary>
+      <description>The transition to use when switching tabs.</description>
+    </key>
+  </schema>
+</schemalist>
+```
+
+Before we can make use of this schema in our application, we need to compile it into the binary form that `Gio::Settings` expects. 
+
+```ruby
+system("glib-compile-schemas", data_path)
+```
+In this command, the tool *glib-compile-schemas* searches all files with a name that ends with *.gschema.xml* and compiles it into a binary file called *gschemas.compiled*.
+
+This binary file can be loaded and our custom schema installed  at the begining of our script with:
+
+```ruby
+Gio::SettingsSchemaSource.new(data_path,
+                              Gio::SettingsSchemaSource.default,
+                              false)
+
+```
+This is the corresponding method to the function [g_settings_schema_source_new_from_directory](https://developer.gnome.org/gio/stable/gio-GSettingsSchema-GSettingsSchemaSource.html#g-settings-schema-source-new-from-directory). 
+
+As an alternative, our schema  can just be loaded by using the `GSETTINGS_SCHEMA_DIR` environment variable.
+
+```ruby
+ENV["GSETTINGS_SCHEMA_DIR"] = data_path 
+```
+More informations on the use of gschemas can be found [here](https://developer.gnome.org/gio/stable/gio-GSettingsSchema-GSettingsSchemaSource.html)
+
+Next, we need to connect our settings to the widgets that they are supposed to control. One convenient way to do this is to use `Gio::Settings` bind functionality to bind settings keys to object properties, as we do here for the transition setting. The `Gio::Settings#bind` is the ruby method for the [g_settings_bind](https://developer.gnome.org/gio/stable/GSettings.html#g-settings-bind) fonction of `gio`
+
+```ruby
+class ExampleAppWindow < Gtk::ApplicationWindow
+  type_register
+  class << self
+    def init
+      set_template(:resource => "/org/gtk/exampleapp/window.ui")
+      bind_template_child("stack")
+    end
+  end
+
+  def initialize(application)
+    super(:application => application)
+    settings = Gio::Settings.new("org.gtk.exampleapp")
+    settings.bind("transition",
+                  stack,
+                  "transition-type",
+                  Gio::SettingsBindFlags::DEFAULT)
+  end
+...
+```
+
+#### Configure the settings with a dialog window
+
+*    exampleapp6/exampleapp.rb
+
+The code to connect the font setting is a little more involved, since there is no simple object property that it corresponds to, so we are not going to go into that here.
+At this point, the application will already react if you change one of the settings, e.g. using the gsettings commandline tool. Of course, we expect the application to provide a preference dialog for these. So lets do that now. Our preference dialog will be a subclass of `Gtk::Dialog`, and we'll use the same techniques that we've already seen: templates, bind child widget name to method, settings bindings.
+
+Lets start with the template.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+  <!-- interface-requires gtk+ 3.8 -->
+  <template class="ExampleAppPrefs" parent="GtkDialog">
+    <property name="title" translatable="yes">Preferences</property>
+    <property name="resizable">False</property>
+    <property name="modal">True</property>
+    <child internal-child="vbox">
+      <object class="GtkBox" id="vbox">
+        <child>
+          <object class="GtkGrid" id="grid">
+            <property name="visible">True</property>
+            <property name="margin">6</property>
+            <property name="row-spacing">12</property>
+            <property name="column-spacing">6</property>
+            <child>
+              <object class="GtkLabel" id="fontlabel">
+                <property name="visible">True</property>
+                <property name="label">_Font:</property>
+                <property name="use-underline">True</property>
+                <property name="mnemonic-widget">font</property>
+                <property name="xalign">1</property>
+              </object>
+              <packing>
+                <property name="left-attach">0</property>
+                <property name="top-attach">0</property>
+              </packing>
+            </child>
+            <child>
+              <object class="GtkFontButton" id="font">
+                <property name="visible">True</property>
+              </object>
+              <packing>
+                <property name="left-attach">1</property>
+                <property name="top-attach">0</property>
+              </packing>
+            </child>
+            <child>
+              <object class="GtkLabel" id="transitionlabel">
+                <property name="visible">True</property>
+                <property name="label">_Transition:</property>
+                <property name="use-underline">True</property>
+                <property name="mnemonic-widget">transition</property>
+                <property name="xalign">1</property>
+              </object>
+              <packing>
+                <property name="left-attach">0</property>
+                <property name="top-attach">1</property>
+              </packing>
+            </child>
+            <child>
+              <object class="GtkComboBoxText" id="transition">
+                <property name="visible">True</property>
+                <items>
+                  <item translatable="yes" id="none">None</item>
+                  <item translatable="yes" id="crossfade">Fade</item>
+                  <item translatable="yes" id="slide-left-right">Slide</item>
+                </items>
+              </object>
+              <packing>
+                <property name="left-attach">1</property>
+                <property name="top-attach">1</property>
+              </packing>
+            </child>
+          </object>
+        </child>
+      </object>
+    </child>
+  </template>
+</interface>
+```
+Next comes the dialog subclass.
+
+```ruby
+class ExampleAppPrefs < Gtk::Dialog
+  type_register
+  class << self
+    def init
+      set_template(:resource => "/org/gtk/exampleapp/prefs.ui")
+      bind_template_child("font")
+      bind_template_child("transition")
+    end
+  end
+  def initialize(args)
+    parent = args[:transient_for]
+    bar = args[:use_header_bar]
+    super(:transient_for => parent, :use_header_bar => 1)
+    settings = Gio::Settings.new("org.gtk.exampleapp")
+    settings.bind("font",
+                  font,
+                  "font",
+                  Gio::SettingsBindFlags::DEFAULT)
+    settings.bind("transition",
+                  transition,
+                  "active-id",
+                  Gio::SettingsBindFlags::DEFAULT)
+  end
+end
+```
+
+Nothing new here, it works like previously. The main difference in our application now is that we define what must be done when the *preferences* menu item is clicked.
+
+```ruby
+action = Gio::SimpleAction.new("preferences")
+action.signal_connect("activate") do |_action, _parameter|
+  win = application.windows.first
+
+  prefs = ExampleAppPrefs.new(:transient_for => win,
+                              :use_header_bar => true)
+  prefs.present
+end
+```
+Here we just says that when the user activate the *preferences* item, we create an `ExampleAppPrefs` instance and display it. The user can then specify the *font* and *transition* settings for the application. Those settings are used in the `ExampleAppWindow#open` method for example:
+
+```ruby
+def open(file)
+  basename = file.basename
+  scrolled = Gtk::ScrolledWindow.new
+  scrolled.show
+  scrolled.set_hexpand(true)
+  scrolled.set_vexpand(true)
+  view = Gtk::TextView.new
+  view.set_editable(false)
+  view.set_cursor_visible(false)
+  view.show
+  scrolled.add(view)
+  stack.add_titled(scrolled, basename, basename)
+  stream = file.read
+  buffer = view.buffer
+  buffer.text = stream.read
+  tag = buffer.create_tag() 
+  @settings.bind("font", tag, "font", Gio::SettingsBindFlags::DEFAULT)
+  buffer.apply_tag(tag, buffer.start_iter, buffer.end_iter)
+end
+``` 
+
+## Adding a search bar
+https://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.10
+
+*    exampleapp7/exampleapp.rb
+
+We continue to flesh out the functionality of our application. For now, we add search. GTK+ supports this with `Gtk::SearchEntry` and `Gtk::SearchBar`. The search bar is a widget that can slide in from the top to present a search entry.
+We add a toggle button to the header bar, which can be used to slide out the search bar below the header bar.
+
+The new window.ui file:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+  <!-- interface-requires gtk+ 3.8 -->
+  <template class="ExampleAppWindow" parent="GtkApplicationWindow">
+    <property name="title" translatable="yes">Example Application</property>
+    <property name="default-width">600</property>
+    <property name="default-height">400</property>
+    <child>
+      <object class="GtkBox" id="content_box">
+        <property name="visible">True</property>
+        <property name="orientation">vertical</property>
+        <child>
+          <object class="GtkHeaderBar" id="header">
+            <property name="visible">True</property>
+            <child type="title">
+              <object class="GtkStackSwitcher" id="tabs">
+                <property name="visible">True</property>
+                <property name="margin">6</property>
+                <property name="stack">stack</property>
+              </object>
+            </child>
+            <child>
+              <object class="GtkToggleButton" id="search">
+                <property name="visible">True</property>
+                <property name="sensitive">False</property>
+                <style>
+                  <class name="image-button"/>
+                </style>
+                <child>
+                  <object class="GtkImage" id="search-icon">
+                    <property name="visible">True</property>
+                    <property name="icon-name">edit-find-symbolic</property>
+                    <property name="icon-size">1</property>
+                  </object>
+                </child>
+              </object>
+              <packing>
+                <property name="pack-type">end</property>
+              </packing>
+            </child>
+          </object>
+        </child>
+        <child>
+          <object class="GtkSearchBar" id="searchbar">
+            <property name="visible">True</property>
+            <child>
+              <object class="GtkSearchEntry" id="searchentry">
+                <signal name="search-changed" handler="search_text_changed"/>
+                <property name="visible">True</property>
+              </object>
+            </child>
+          </object>
+        </child>
+        <child>
+          <object class="GtkStack" id="stack">
+            <signal name="notify::visible-child" handler="visible_child_changed"/>
+            <property name="visible">True</property>
+          </object>
+        </child>
+      </object>
+    </child>
+  </template>
+</interface>
+```
+Implementing the search needs quite a few code changes that we are not going to completely go over here. The central piece of the search implementation is a signal handler that listens for text changes in the search entry.
+
+```ruby
+
+def init
+  set_template(:resource => "/org/gtk/exampleapp/window.ui")
+  bind_template_child("stack")
+  bind_template_child("search")
+  bind_template_child("searchbar")
+  set_connect_func do |name|
+    method(name)
+  end
+end
+
+private
+
+def search_text_changed(search_entry)
+  text = search_entry.text
+  return if text.empty?
+
+  win = search_entry.toplevel
+  tab = win.stack.visible_child
+  view = tab.child
+  buffer = view.buffer
+  range = buffer.start_iter.forward_search(text, Gtk::TextSearchFlags::CASE_INSENSITIVE)
+  return unless range
+  buffer.select_range(range[0], range[1])
+  view.scroll_to_iter(range[0], 0.0, false, 0.0, 0.0)
+end
+```
+
+In this part of code, the use of the method `set_connect_func` will allow us to define private methods as callback that have been set in the handler attributs of the XML ui file. In the code above, we can see that we have defined a private method name `search_text_changed`. In the XML file, there is this line :
+
+    <signal name="search-changed" handler="search_text_changed"/>
+
+Those pieces together mean that for the signal *search-changed* of the `Gtk::SearchEntry`, trigger the private method of `ExampleAppWindow` that is called `search_text_changed`.
+

data/test/run-test.rb

@@ -63,4 +63,4 @@ require 'gtk3'
 
 Gtk.init
 
-exit Test::Unit::AutoRunner.run(true)
+exit Test::Unit::AutoRunner.run(true, File.join(gtk3_base, "test"))

data/test/test-gtk-builder.rb

@@ -19,16 +19,18 @@ class TestGtkBuilder < Test::Unit::TestCase
       assert_kind_of(Gtk::Dialog, builder["dialog1"])
     end
 
+    test "path" do
+      only_gtk_version(3, 10, 0)
+      builder = Gtk::Builder.new(:path => ui_definition_file.path)
+      assert_kind_of(Gtk::Dialog, builder["dialog1"])
+    end
+
     test "resource" do
       only_gtk_version(3, 10, 0)
-      resource = Gio::Resource.load(fixture_path("simple_window.gresource"))
-      Gio::Resources.register(resource)
-      begin
+      register_resource(fixture_path("simple_window.gresource")) do
         resource_path = "/simple_window/simple_window.ui"
         builder = Gtk::Builder.new(:resource => resource_path)
         assert_kind_of(Gtk::Window, builder["window"])
-      ensure
-        Gio::Resources.unregister(resource)
       end
     end
 
@@ -39,43 +41,109 @@ class TestGtkBuilder < Test::Unit::TestCase
     end
   end
 
-  def test_add_from_file
-    builder = Gtk::Builder.new
-    assert_nothing_raised do
-      builder.add_from_file(ui_definition_file.path)
+  sub_test_case "#add" do
+    sub_test_case ":file" do
+      test "all" do
+        builder = Gtk::Builder.new
+        builder.add(:file => ui_definition_file.path)
+        assert_kind_of(Gtk::Dialog, builder["dialog1"])
+      end
+
+      test ":object_ids" do
+        builder = Gtk::Builder.new
+        builder.add(:file => ui_definition_file.path,
+                    :object_ids => ["ok_button"])
+        assert_equal(["ok_button"],
+                     builder.objects.collect(&:builder_name).sort)
+      end
+    end
+
+    sub_test_case ":path" do
+      test "all" do
+        builder = Gtk::Builder.new
+        builder.add(:path => ui_definition_file.path)
+        assert_kind_of(Gtk::Dialog, builder["dialog1"])
+      end
+
+      test ":object_ids" do
+        builder = Gtk::Builder.new
+        builder.add(:path => ui_definition_file.path,
+                    :object_ids => ["ok_button"])
+        assert_equal(["ok_button"],
+                     builder.objects.collect(&:builder_name).sort)
+      end
     end
-    assert_kind_of(Gtk::Dialog, builder["dialog1"])
-  end
 
-  sub_test_case "#add_from_string" do
-    def test_ascii_only
+    test "path" do
       builder = Gtk::Builder.new
-      builder.add_from_string(ui_definition_simple)
-      assert_kind_of(Gtk::Window, builder["main-window"])
+      builder.add(ui_definition_file.path)
+      assert_kind_of(Gtk::ButtonBox, builder["hbuttonbox1"])
     end
 
-    def test_multibyte_characters
+    sub_test_case ":resource" do
+      setup do
+        only_gtk_version(3, 12, 0)
+      end
+
+      test "all" do
+        builder = Gtk::Builder.new
+        register_resource(fixture_path("simple_window.gresource")) do
+          resource_path = "/simple_window/simple_window.ui"
+          builder.add(:resource => resource_path)
+          assert_kind_of(Gtk::Window, builder["window"])
+        end
+      end
+
+      test ":object_ids" do
+        builder = Gtk::Builder.new
+        register_resource(fixture_path("simple_window.gresource")) do
+          resource_path = "/simple_window/simple_window.ui"
+          builder.add(:resource => resource_path,
+                      :object_ids => ["label"])
+          assert_equal(["label"],
+                       builder.objects.collect(&:builder_name).sort)
+        end
+      end
+    end
+
+    test "resource" do
+      only_gtk_version(3, 12, 0)
       builder = Gtk::Builder.new
-      comment = "<!-- 日本語 -->\n" * 100
-      builder.add_from_string("#{comment}#{ui_definition_simple}")
-      assert_kind_of(Gtk::Window, builder["main-window"])
+      register_resource(fixture_path("simple_window.gresource")) do
+        resource_path = "/simple_window/simple_window.ui"
+        builder.add(resource_path)
+        assert_kind_of(Gtk::Window, builder["window"])
+      end
     end
-  end
 
-  def test_add_with_file
-    builder = Gtk::Builder.new
-    assert_nothing_raised do
-      builder.add(ui_definition_file.path)
+    sub_test_case ":string" do
+      test "ascii only" do
+        builder = Gtk::Builder.new
+        builder.add(:string => ui_definition_simple)
+        assert_kind_of(Gtk::Window, builder["main-window"])
+      end
+
+      test "multibyte characters" do
+        builder = Gtk::Builder.new
+        comment = "<!-- 日本語 -->\n" * 100
+        builder.add(:string => "#{comment}#{ui_definition_simple}")
+        assert_kind_of(Gtk::Window, builder["main-window"])
+      end
+
+      test ":object_ids" do
+        builder = Gtk::Builder.new
+        builder.add(:string => ui_definition,
+                    :object_ids => ["ok_button"])
+        assert_equal(["ok_button"],
+                     builder.objects.collect(&:builder_name).sort)
+      end
     end
-    assert_kind_of(Gtk::ButtonBox, builder["hbuttonbox1"])
-  end
 
-  def test_add_with_string
-    builder = Gtk::Builder.new
-    assert_nothing_raised do
+    test "string" do
+      builder = Gtk::Builder.new
       builder.add(ui_definition)
+      assert_kind_of(Gtk::Button, builder["ok_button"])
     end
-    assert_kind_of(Gtk::Button, builder["ok_button"])
   end
 
   def test_add_chain
@@ -197,4 +265,14 @@ EOX
     xml.close
     xml
   end
+
+  def register_resource(path)
+    resource = Gio::Resource.load(path)
+    Gio::Resources.register(resource)
+    begin
+      yield
+    ensure
+      Gio::Resources.unregister(resource)
+    end
+  end
 end