{"id":15724290,"url":"https://github.com/cedlemo/ruby-gtk3-tutorial","last_synced_at":"2025-07-15T10:39:23.878Z","repository":{"id":36251058,"uuid":"40555463","full_name":"cedlemo/ruby-gtk3-tutorial","owner":"cedlemo","description":"Gtk3 tutorial for ruby based on the official C version","archived":false,"fork":false,"pushed_at":"2016-06-09T07:54:11.000Z","size":59,"stargazers_count":109,"open_issues_count":2,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-31T01:14:12.535Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cedlemo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-11T17:24:45.000Z","updated_at":"2024-11-27T03:12:34.000Z","dependencies_parsed_at":"2022-08-29T19:50:35.539Z","dependency_job_id":null,"html_url":"https://github.com/cedlemo/ruby-gtk3-tutorial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedlemo%2Fruby-gtk3-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedlemo%2Fruby-gtk3-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedlemo%2Fruby-gtk3-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedlemo%2Fruby-gtk3-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cedlemo","download_url":"https://codeload.github.com/cedlemo/ruby-gtk3-tutorial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252612452,"owners_count":21776253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T22:16:00.914Z","updated_at":"2025-05-06T02:51:16.550Z","avatar_url":"https://github.com/cedlemo.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Getting started with GTK+ with the ruby-gnome2 Gtk3 module.\n\nThis is a ruby adaptation of the official tutorial for the C language that you can find at https://developer.gnome.org/gtk3/stable/gtk-getting-started.html.\n\nGTK+ is a widget toolkit. Each user interface created by GTK+ consists of widgets. The Gtk3 module of the ruby-gnome2 project is an implementation of the ruby bindings for GTK+.\n\nWith Gtk3, Widgets are organized in a hierachy. The Gtk::Window widget is the main container. The user interface is then built by adding buttons, drop-down menus, input fields, and other widgets to the window.\n\nIf you are creating complex user interfaces it is recommended to use Gtk::Builder and its GTK-specific markup description language, instead of assembling the interface manually. You can also use a visual user interface editor, like Glade.\n\nGTK+ is event-driven. The toolkit listens for events such as a click on a button, and passes the event to your application.\n\nHere is the most basic example that illustrate the principles of widget hierarchy and events management:\n\n```ruby\nrequire \"gtk3\"\n\nwindow = Gtk::Window.new(\"First example\")\nwindow.set_size_request(400, 400)\nwindow.set_border_width(10)\n\nbutton = Gtk::Button.new(:label =\u003e \"Say hello\")\nbutton.signal_connect \"clicked\" do |_widget|\n  puts \"Hello World!!\"\nend\n\nwindow.add(button)\nwindow.signal_connect(\"delete-event\") { |_widget| Gtk.main_quit }\nwindow.show_all\n\nGtk.main\n```\nThis tutorial will mainly be focused on the use of Gtk::Application, which is the best way to create an application.\n\n## Table of Contents\n*  [Basics](#basics)\n*  [Packing](#packing)\n*  [Building user interfaces](#building-user-interfaces)\n*  [Building Applications](#building-applications)\n  *  [A trivial application](#a-trivial-application)\n  *  [Populating the window](#populating-the-window)\n    *  [Link a template to a custom class widget](#link-a-template-to-a-custom-class-widget)\n    *  [Load a resource file](#load-a-resource-file)\n  *  [Opening files](#opening-file)\n  *  [An application menu](#an-application-menu)\n    *  [Adding the menu interface](#adding-the-menu-interface)\n    *  [Linking menu items to actions](#linking-menu-items-to-actions)\n    *  [Add accelerators for an action](#add-accelerators-for-an-action)\n  *  [A preference dialog](#a-preference-dialog)\n    *  [Define and store settings for an application with gschemas](#define-and-store-settings-for-an-application-with-gschemas)\n    *  [Configure the settings with a dialog window](#configure-the-settings-with-a-dialog-window)\n  *  [Adding a search bar](#adding-a-search-bar)\n  *  [Adding a sidebar](#adding-a-sidebar)\n  *  [Properties](#properties)\n  *  [Header Bar](#header-bar)\n\n## Basics\nhttps://developer.gnome.org/gtk3/stable/gtk-getting-started.html#id-1.2.3.5\n\nTo begin our introduction to GTK, we'll start with a simple signal-based Gtk application. This program will create an empty 200 × 200 pixel window.\n\n*    example-0.rb\n```ruby\nrequire \"gtk3\"\n\napp = Gtk::Application.new(\"org.gtk.example\", :flags_none)\n\napp.signal_connect \"activate\" do |application|\n  window = Gtk::ApplicationWindow.new(application)\n  window.set_title(\"Window\")\n  window.set_default_size(200, 200)\n  window.show_all\nend\n\nputs app.run\n\n```\nWhen creating a Gtk::Application you need to pick an application identifier (a name) and input to `Gtk::Application#new` as parameter. For this example *org.gtk.example* is used but for choosing an identifier for your application see this [guide](https://wiki.gnome.org/HowDoI/ChooseApplicationID).\nLastly `Gtk::Application#new` takes a `Gio::ApplicationFlags` constants as input for your application, if your application would have special needs (those constants can be replaced by theirs respective symbol ie. `Gio::ApplicationFlags::NONE` == `:flags_none`).\n\nNext we add instructions for the \"activate\" event of the `Gtk::Application` instance we created. The activate signal will be sent when your application is launched with the method `Gtk::Application#run` without argument on the line below (this is a specific case, see the part **A trivial application**). This method also takes as arguments a ruby array of string. This allows GTK+ to parse specific command line arguments that control the behavior of GTK+ itself. The parsed arguments will be removed from the array, leaving the unrecognized ones for your application to parse.\n\nInside the \"activate\" event block, we want to construct our GTK window, so that a window is shown when the application is launched. The call to `Gtk::ApplicationWindow#new` will create a new `Gtk::Window`. The window will have a frame, a title bar, and window controls depending on the platform.\n\nA window title is set using `Gtk::Window#set_title`. This function takes a string as input. Finally the window size is set using `Gtk::Window#set_default_size` and the window is then shown by GTK via `Gtk::Widget#show_all`.\n\nWhen you exit the window, by for example pressing the X, the `Gtk::Application#run` in the main loop returns with a number which is the exit status.\n\nWhile the program is running, GTK+ is receiving *events*. These are typically input events caused by the user interacting with your program, but also things like messages from the window manager or other applications. GTK+ processes these and as a result, signals may be emitted on your widgets. Connecting handlers for these signals is how you normally make your program do something in response to user input.\nThe following example is slightly more complex, and tries to showcase some of the capabilities of GTK+.\n\nIn the long tradition of programming languages and libraries, it is called *Hello, World*.\n*    example-1.rb\n```ruby\nrequire \"gtk3\"\napp = Gtk::Application.new(\"org.gtk.example\", :flags_none)\n\napp.signal_connect \"activate\" do |application|\n  window = Gtk::ApplicationWindow.new(application)\n  window.set_title(\"Window\")\n  window.set_default_size(200, 200)\n\n  button_box = Gtk::ButtonBox.new(:horizontal)\n  window.add(button_box)\n\n  button = Gtk::Button.new(label: \"Hello World\")\n  button.signal_connect \"clicked\" do |widget|\n    puts \"Hello World\"\n    window.destroy\n  end\n\n  button_box.add(button)\n\n  window.show_all\nend\n\n# Gtk::Application#run need C style argv ([prog, arg1, arg2, ...,argn]).\n# The ARGV ruby variable only contains the arguments ([arg1, arg2, ...,argb])\n# and not the program name. We have to add it explicitly.\n\nputs app.run([$0] + ARGV)\n```\nAs seen above, example-1.rb builds further upon example-0.rb by adding a button to our window, with the label \"Hello World\". Two new variables are created to accomplish this, button and button_box.\n\nThe button_box variable stores a `Gtk::ButtonBox` object, which is GTK+'s way of controlling the size and layout of buttons. The `Gtk::ButtonBox` is created with the method `Gtk::ButtonBox#new` which takes a `Gtk::Orientation `constant as parameter or the related symbols (`:vertical` or `:horizontal`).\n\nThe buttons which this box will contain can either be stored horizontally or vertically but this does not matter in this particular case as we are dealing with only one button. After initializing button_box with horizontal orientation, the code adds the button_box widget to the window widget using `Gtk::ButtonBox#add`.\n\nNext the button variable is initialized in similar manner. The method `Gtk::Button#new` is called which returns a GtkButton to be stored inside button. A label is set using a ruby hash as argument :`:label =\u003e \"Hello World\"`.\n\nAfterwards button is added to our button_box. Using the method \"Gtk::Button#signal_connect\" we add instructions, so that when the button is clicked, a message will be displayed in the terminal if the GTK application was started from one.\n\nAfter that, `Gtk::Window#destroy` is called. This method is herited from `Gtk::Widget`. This has the effect that when the button is clicked, the whole GTK window is destroyed. More information about creating buttons can be found [here](https://wiki.gnome.org/HowDoI/Buttons).\nThe rest of the code in example-1.rb is identical to example-0.rb. Next section will elaborate further on how to add several GtkWidgets to your GTK application.\n\n## Packing\nhttps://developer.gnome.org/gtk3/stable/ch01s02.html\n\nWhen creating an application, you'll want to put more than one widget inside a window. When you want to put more than one widget into a window, it it becomes important to control how each widget is positioned and sized. This is where packing comes in.\n\nGTK+ comes with a large variety of layout containers whose purpose it is to control the layout of the child widgets that are added to them. See [Layout Containers](https://developer.gnome.org/gtk3/stable/LayoutContainers.html) for an overview.\n\nThe following example shows how the `Gtk::Grid` container lets you arrange several buttons:\n*    example-2.rb\n\n```ruby\nrequire \"gtk3\"\n\napp = Gtk::Application.new(\"org.gtk.example\", :flags_none)\n\napp.signal_connect \"activate\" do |application|\n  # create a new window, and set its title\n  window = Gtk::ApplicationWindow.new(application)\n  window.set_title(\"Window\")\n  window.set_border_width(10)\n\n  # Here we construct the container that is going pack our buttons \n  grid = Gtk::Grid.new\n\n  # Pack the container in the window\n  window.add(grid)\n\n  button = Gtk::Button.new(:label =\u003e \"Button 1\")\n  button.signal_connect(\"clicked\") { puts \"Hello World\" }\n  # Place the first button in the grid cell (0, 0), and make it fill\n  # just 1 cell horizontally and vertically (ie no spanning)\n  grid.attach(button, 0, 0, 1, 1)\n\n  button = Gtk::Button.new(:label =\u003e \"Button 2\")\n  button.signal_connect(\"clicked\") { puts \"Hello World\" }\n  # Place the second button in the grid cell (1, 0), and make it fill\n  # just 1 cell horizontally and vertically (ie no spanning)\n  grid.attach(button, 1, 0, 1, 1)\n\n  button = Gtk::Button.new(:label =\u003e \"Quit\")\n  button.signal_connect(\"clicked\") { window.destroy }\n  # Place the Quit button in the grid cell (0, 1), and make it\n  # span 2 columns.\n  grid.attach(button, 0, 1, 2, 1)\n\n  # Now that we are done packing our widgets, we show them all\n  # in one go, by calling Gtk::Widget#show_all on the window.\n  # This call recursively calls Gtk::Widget#show on all widgets\n  # that are contained in the window, directly or indirectly\n  window.show_all\nend\n\n# Gtk::Application#run need C style argv ([prog, arg1, arg2, ...,argn]).\n# The ARGV ruby variable only contains the arguments ([arg1, arg2, ...,argb])\n# and not the program name. We have to add it explicitly.\n\nstatus = app.run([$0] + ARGV)\n\nputs status\n```\n\n## Building user interfaces\nhttps://developer.gnome.org/gtk3/stable/ch01s03.html\n\nWhen construcing a more complicated user interface, with dozens or hundreds of widgets, doing all the setup work in code is cumbersome, and making changes becomes next to impossible.\nThankfully, GTK+ supports the separation of user interface layout from your business logic, by using UI descriptions in an XML format that can be parsed by the GtkBuilder class.\n\n*    example-4.rb : Packing buttons with GtkBuilder\n\n```ruby\nrequire \"gtk3\"\n\nbuilder_file = \"#{File.expand_path(File.dirname(__FILE__))}/builder.ui\"\n\n# Construct a Gtk::Builder instance and load our UI description\nbuilder = Gtk::Builder.new(:file =\u003e builder_file)\n\n# Connect signal handlers to the constructed widgets\nwindow = builder.get_object(\"window\")\nwindow.signal_connect(\"destroy\") { Gtk.main_quit }\n\nbutton = builder.get_object(\"button1\")\nbutton.signal_connect(\"clicked\") { puts \"Hello World\" }\n\nbutton = builder.get_object(\"button2\")\nbutton.signal_connect(\"clicked\") { puts \"Hello World\" }\n\nbutton = builder.get_object(\"quit\")\nbutton.signal_connect(\"clicked\") { Gtk.main_quit }\n\nGtk.main\n```\n\nHere is the \"builder.ui\" file that describes the interface:\n\n```xml\n\u003cinterface\u003e\n  \u003cobject id=\"window\" class=\"GtkWindow\"\u003e\n    \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n    \u003cproperty name=\"title\"\u003eGrid\u003c/property\u003e\n    \u003cproperty name=\"border-width\"\u003e10\u003c/property\u003e\n    \u003cchild\u003e\n      \u003cobject id=\"grid\" class=\"GtkGrid\"\u003e\n        \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n        \u003cchild\u003e\n          \u003cobject id=\"button1\" class=\"GtkButton\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cproperty name=\"label\"\u003eButton 1\u003c/property\u003e\n          \u003c/object\u003e\n          \u003cpacking\u003e\n            \u003cproperty name=\"left-attach\"\u003e0\u003c/property\u003e\n            \u003cproperty name=\"top-attach\"\u003e0\u003c/property\u003e\n          \u003c/packing\u003e\n        \u003c/child\u003e\n        \u003cchild\u003e\n          \u003cobject id=\"button2\" class=\"GtkButton\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cproperty name=\"label\"\u003eButton 2\u003c/property\u003e\n          \u003c/object\u003e\n          \u003cpacking\u003e\n            \u003cproperty name=\"left-attach\"\u003e1\u003c/property\u003e\n            \u003cproperty name=\"top-attach\"\u003e0\u003c/property\u003e\n          \u003c/packing\u003e\n        \u003c/child\u003e\n        \u003cchild\u003e\n          \u003cobject id=\"quit\" class=\"GtkButton\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cproperty name=\"label\"\u003eQuit\u003c/property\u003e\n          \u003c/object\u003e\n          \u003cpacking\u003e\n            \u003cproperty name=\"left-attach\"\u003e0\u003c/property\u003e\n            \u003cproperty name=\"top-attach\"\u003e1\u003c/property\u003e\n            \u003cproperty name=\"width\"\u003e2\u003c/property\u003e\n          \u003c/packing\u003e\n        \u003c/child\u003e\n      \u003c/object\u003e\n      \u003cpacking\u003e\n      \u003c/packing\u003e\n    \u003c/child\u003e\n  \u003c/object\u003e\n\u003c/interface\u003e\n```\n\nThe usage of the `Gtk::Builder` is really easy, we just create an instance from the\nfile \"builder.ui\" with `Gtk::Builder.new(:file =\u003e builder_file)`. Then you can access every widget or part of the interface thanks to its name: `window = builder.get_object(\"window\")`. Note that `Gtk::Builder` can also be used to construct objects that are not widgets, such as tree models, adjustments, etc.\n\nThe XML definition of the interface can be loaded from a file, a string or a path in a gresource binary. More informations related to this XML definition can be found [here](https://developer.gnome.org/gtk3/stable/GtkBuilder.html#BUILDER-UI). Those files are generally built with [glade](https://glade.gnome.org/). \n\n\n## Building applications\n\n### A trivial application\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.5\n\n*    exampleapp1.rb\n```ruby\nrequire \"gtk3\"\n\nclass ExampleAppWindow \u003c Gtk::ApplicationWindow\n\n  def open(file)\n    \n  end\nend\n\nclass ExampleApp \u003c Gtk::Application\n  def initialize\n    super(\"org.gtk.exampleapp\", :handles_open)\n\n    signal_connect \"activate\" do |application|\n      window = ExampleAppWindow.new(application)\n      window.present\n    end\n    signal_connect \"open\" do |application, files, hin|\n      windows = application.windows\n      win = nil\n      unless windows.empty?\n        win = windows.first\n      else\n        win = ExampleAppWindow.new(application)\n      end\n\n      files.each { |file| win.open(file) }\n        \n      win.present\n    end\n  end\nend\n\napp = ExampleApp.new\n\nputs app.run([$0]+ARGV)\n```\n\nIn this example we create a subclass of `Gtk::Application` called ExampleApp. In the `ExampleApp#initialize` method, we add instructions for two signals *activate* and *open*. Every `Gtk::Application` object or its subclass object can react to 4 signals:\n\n*    startup : sets up the application when it first start\n*    shutdown : preforms shutdown tasks\n*    activate : shows the default first window of the application\n*    open : opens files and shows them in a new window\n\nFor more informations, see [here](https://wiki.gnome.org/HowDoI/GtkApplication).\nIn this case, the signal \"*activate*\" will be triggered if no arguments are given to the `ExampleApp#run` method. And a default window will be created and will be presented to the user ( [see](https://developer.gnome.org/gtk3/stable/GtkWindow.html#gtk-window-present).\n\nIf file names are given to the `ExampleApp#run` method, then it is the \"*open*\" signal that is called.\nTrought this event, you can manage the files that are stored in an array of `Gio::File` objects.\n\nIn this example, each files are used by an `ExampleAppWindow#open` method. The `ExampleAppWindow` class is derived from the `Gtk::ApplicationWindow`.\n\nThis does not look very impressive yet, but our application is already presenting itself on the session bus, and it accepts files as commandline arguments.\n\n### Populating the window\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.6\n\nIn this step, we use a [`Gtk::Builder`](https://developer.gnome.org/gtk3/stable/GtkBuilder.html) template to associate a [`Gtk::Builder`](https://developer.gnome.org/gtk3/stable/GtkBuilder.html) ui file with our application window class.\nOur simple ui file puts a [`Gtk::HeaderBar`](https://developer.gnome.org/gtk3/stable/GtkHeaderBar.html) on top of a [`Gtk::Stack`](https://developer.gnome.org/gtk3/stable/GtkStack.html) widget. The header bar contains a [`Gtk::StackSwitcher`](https://developer.gnome.org/gtk3/stable/GtkStackSwitcher.html), which is a standalone widget to show a row of 'tabs' for the pages of a [`Gtk::Stack`](https://developer.gnome.org/gtk3/stable/GtkStack.html) .\n\nHere is the \"window.ui\" file that contains the template of the window:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cinterface\u003e\n  \u003c!-- interface-requires gtk+ 3.8 --\u003e\n  \u003ctemplate class=\"ExampleAppWindow\" parent=\"GtkApplicationWindow\"\u003e\n    \u003cproperty name=\"title\" translatable=\"yes\"\u003eExample Application\u003c/property\u003e\n    \u003cproperty name=\"default-width\"\u003e600\u003c/property\u003e\n    \u003cproperty name=\"default-height\"\u003e400\u003c/property\u003e\n    \u003cchild\u003e\n      \u003cobject class=\"GtkBox\" id=\"content_box\"\u003e\n        \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n        \u003cproperty name=\"orientation\"\u003evertical\u003c/property\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkHeaderBar\" id=\"header\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cchild type=\"title\"\u003e\n              \u003cobject class=\"GtkStackSwitcher\" id=\"tabs\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"margin\"\u003e6\u003c/property\u003e\n                \u003cproperty name=\"stack\"\u003estack\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkStack\" id=\"stack\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n      \u003c/object\u003e\n    \u003c/child\u003e\n  \u003c/template\u003e\n\u003c/interface\u003e\n```\nUnlike regular interface descriptions, in template XML descriptions, a`\u003ctemplate\u003e` tag is expected as a direct child of the toplevel `\u003cinterface\u003e` tag. Yhe `\u003ctemplate\u003e` tag must specify the \"*class*\" attribute which must be the class name of the widget. Optionally, the \"*parent*\" attribute may be specified to indicate the direct parent class (superclass).\n\nMore informations can be found in the part [building composite widgets from template XML](https://developer.gnome.org/gtk3/stable/GtkWidget.html#GtkWidget.description) of the `Gtk::Widget` documentation. \n\n#### Link a template to a custom class widget.\n\nexampleapp2.rb : \n```ruby\nclass ExampleAppWindow \u003c Gtk::ApplicationWindow\n  type_register\n  class \u003c\u003c self\n    def init\n      set_template(:resource =\u003e \"/org/gtk/exampleapp/window.ui\")\n    end\n  end\n\n  def initialize(application)\n    super(:application =\u003e application)\n  end\n\n  def open(file)\n    \n  end\nend\n```\n\nWe create a subclass of Gtk::ApplicationWindow. Then we call the method `type_register` inherited from `GLib::Object` in order to register this class as a new [GType](https://developer.gnome.org/gobject/stable/chapter-gtype.html). See the file *ruby-gnome2/glib2/ext/glib2/rbgobj_object.c* for the C implementation. More informations on the gobject manipulation can be found [here](https://blogs.gnome.org/desrt/2012/02/26/a-gentle-introduction-to-gobject-construction/)\n\nThe template of the interface is bound to the class using the `init` singleton method. We just open the *eigenclass*  with `class \u003c\u003c self` and define the method `init` in which we call the `Gtk::Widget#set_template` method.\n\nAfter that, the `ExampleAppWindow#initialize` method must be overwritten. When `type_register` is used, *super* is equivalent to `GLib::Object#initialize` so you need to use properties style constructor (hash argument, see [here](https://github.com/ruby-gnome2/ruby-gnome2/issues/503))\n\n#### Load a resource file.\n\nYou may have noticed that we used the `:resource =\u003e ` key as the argument of the method that sets a template. Now we need to use GLib's resource functionality to include the ui file in the binary. This is commonly done by listing all resources in a .gresource.xml file, such as this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cgresources\u003e\n  \u003cgresource prefix=\"/org/gtk/exampleapp\"\u003e\n    \u003cfile preprocess=\"xml-stripblanks\"\u003ewindow.ui\u003c/file\u003e\n  \u003c/gresource\u003e\n\u003c/gresources\u003e\n```\nIn our script, we built the resource binary file with\n```ruby\nsystem(\"glib-compile-resources\",\n       \"--target\", gresource_bin,\n       \"--sourcedir\", File.dirname(gresource_xml),\n       gresource_xml)\n```\nThen we make sure that this file is deleted when the script is done :\n\n```ruby\nat_exit do\n  FileUtils.rm_f(gresource_bin)\nend\n```\nThe resource binary file is loaded so that each resources in it can be accessed via theirs respective paths.\n\n```ruby\nresource = Gio::Resource.load(gresource_bin)\nGio::Resources.register(resource)\n```\n\n### Opening files\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.7\n\n*    exampleapp3.rb\n\nIn this step, we make our application show the content of all the files that it is given on the commandline.\nTo this end, we need to easily access widgets from the template. So we use the method `Gtk::Widget#bind_template_child` like in the code below:\n\n```ruby\nclass ExampleAppWindow \u003c Gtk::ApplicationWindow\n  type_register\n  class \u003c\u003c self\n    def init\n      set_template(:resource =\u003e \"/org/gtk/exampleapp/window.ui\")\n      bind_template_child(\"stack\")\n    end\n  end\n```\nMost of this piece of code have been seen previously, a window widget interface is defined with a template. But the usage of `bind_template_child(\"stack\")` will add a method, to each ExampleAppWindow instance, which name will be `ExampleAppWindow#stack` and that will return the corresponding child widget in the template.\n\nThe initial implementation of `Gtk::Widget#bind_template_child` have been done in this [pull request](https://github.com/ruby-gnome2/ruby-gnome2/pull/445)\n\nThis new way to access the stack widget is used in the following code. We have previously handled the *open* signal in our application like this:\n\n```ruby\n\nclass ExampleAppWindow \u003c Gtk::ApplicationWindow\n  def open(file)\n    \n  end\nend\n\nclass ExampleApp \u003c Gtk::Application\n  def initialize\n    # ...\n\n    signal_connect \"open\" do |application, files, hin|\n      windows = application.windows\n      win = nil\n      unless windows.empty?\n        win = windows.first\n      else\n        win = ExampleAppWindow.new(application)\n      end\n\n      files.each { |file| win.open(file) }\n        \n      win.present\n    end\n  end\nend\n```\n\nThe `open` method of the main window is called with for each file. Now we manage those files like this:\n\n```ruby\ndef open(file)\n  basename = file.basename\n  scrolled = Gtk::ScrolledWindow.new\n  scrolled.show\n  scrolled.set_hexpand(true)\n  scrolled.set_vexpand(true)\n  view = Gtk::TextView.new\n  view.set_editable(false)\n  view.set_cursor_visible(false)\n  view.show\n  scrolled.add(view)\n  stack.add_titled(scrolled, basename, basename)\n  stream = file.read\n  view.buffer.text = stream.read\nend\n```\nEach file is opened and loaded in a `Gtk::TextView` with \n\n```ruby\n  stream = file.read\n  view.buffer.text = stream.read\n```\n\nWe get the basename, of the file in argument, that will be used as title for each tab of the stack widget: \n\n```\nstack.add_titled(scrolled, basename, basename)\n```\n\nIn this line, given that `self` is `ExampleAppWindow` the usage of `stack` is a call to the method we have created previously. So here we add a tab with a `Gtk::ScrolledWindow` in the `Gtk::Stack` widget of our template and we display the file content.\n\n### An application menu\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.8\n\n*    exampleapp4.rb\n\nAn 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.\nJust like the window template, we specify our application menu in a ui file, and add it as a resource to our binary.\n\n#### Adding the menu interface\n\n*    app-menu.ui\n```xml\n\u003c?xml version=\"1.0\"?\u003e\n\u003cinterface\u003e\n  \u003c!-- interface-requires gtk+ 3.0 --\u003e\n  \u003cmenu id=\"appmenu\"\u003e\n    \u003csection\u003e\n      \u003citem\u003e\n        \u003cattribute name=\"label\" translatable=\"yes\"\u003e_Preferences\u003c/attribute\u003e\n        \u003cattribute name=\"action\"\u003eapp.preferences\u003c/attribute\u003e\n      \u003c/item\u003e\n    \u003c/section\u003e\n    \u003csection\u003e\n      \u003citem\u003e\n        \u003cattribute name=\"label\" translatable=\"yes\"\u003e_Quit\u003c/attribute\u003e\n        \u003cattribute name=\"action\"\u003eapp.quit\u003c/attribute\u003e\n      \u003c/item\u003e\n    \u003c/section\u003e\n  \u003c/menu\u003e\n\u003c/interface\u003e\n```\n\nThis menu interface is loaded and added to our application with :\n\n```ruby\nbuilder = Gtk::Builder.new(:resource =\u003e \"/org/gtk/exampleapp/app-menu.ui\")\napp_menu = builder.get_object(\"appmenu\")\napplication.set_app_menu(app_menu)\n```\n\nWith this, our application has a menu with two items that we can show when clicking on the application icon\nin the Gnome shell.\n\n#### Linking menu items to actions.\n\nAll the actions initialization should be done during the \"startup\" step, which is guaranteed to be called once for each primary application instance.\n\nThe \"quit\" item in the menu is implemented with this:\n\n```xml\n\u003csection\u003e\n  \u003citem\u003e\n    \u003cattribute name=\"label\" translatable=\"yes\"\u003e_Quit\u003c/attribute\u003e\n    \u003cattribute name=\"action\"\u003eapp.quit\u003c/attribute\u003e\n  \u003c/item\u003e\n\u003c/section\u003e\n```\n\nThen we just have to create an `Gio::SimpleAction` named \"quit\" and configure it in order to quit the application when this action is triggered.\n\n```ruby\naction = Gio::SimpleAction.new(\"quit\")\naction.signal_connect(\"activate\") do |_action, parameter|\n  application.quit\nend\napplication.add_action(action)\n\n```\n\n#### Add accelerators for action.\n\nAn accelerator is just a keys combination that acts as a shortcut for an action. \n\n```ruby\nquit_accels = [\"\u003cCtrl\u003eQ\"]\naction = Gio::SimpleAction.new(\"quit\")\naction.signal_connect(\"activate\") do |_action, parameter|\n  application.quit\nend\napplication.add_action(action)\napplication.set_accels_for_action(\"app.quit\", quit_accels)\n```\n\n### A preference dialog\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.9\n\n#### Define and store settings for an application with gschemas\n*    exampleapp5.rb\n\nA 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.\nWe are going to use `Gio::Settings` to store our preferences. `Gio::Settings` requires a schema that describes our settings:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cschemalist\u003e\n  \u003cschema path=\"/org/gtk/exampleapp/\" id=\"org.gtk.exampleapp\"\u003e\n    \u003ckey name=\"font\" type=\"s\"\u003e\n      \u003cdefault\u003e'Monospace 12'\u003c/default\u003e\n      \u003csummary\u003eFont\u003c/summary\u003e\n      \u003cdescription\u003eThe font to be used for content.\u003c/description\u003e\n    \u003c/key\u003e\n    \u003ckey name=\"transition\" type=\"s\"\u003e\n      \u003cchoices\u003e\n        \u003cchoice value='none'/\u003e\n        \u003cchoice value='crossfade'/\u003e\n        \u003cchoice value='slide-left-right'/\u003e\n      \u003c/choices\u003e\n      \u003cdefault\u003e'none'\u003c/default\u003e\n      \u003csummary\u003eTransition\u003c/summary\u003e\n      \u003cdescription\u003eThe transition to use when switching tabs.\u003c/description\u003e\n    \u003c/key\u003e\n  \u003c/schema\u003e\n\u003c/schemalist\u003e\n```\n\nBefore we can make use of this schema in our application, we need to compile it into the binary form that `Gio::Settings` expects. \n\n```ruby\nsystem(\"glib-compile-schemas\", data_path)\n```\nIn 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*.\n\nThis binary file can be loaded and our custom schema installed  at the begining of our script with:\n\n```ruby\nGio::SettingsSchemaSource.new(data_path,\n                              Gio::SettingsSchemaSource.default,\n                              false)\n\n```\nThis 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). \n\nAs an alternative, our schema  can just be loaded by using the `GSETTINGS_SCHEMA_DIR` environment variable.\n\n```ruby\nENV[\"GSETTINGS_SCHEMA_DIR\"] = data_path \n```\nMore informations on the use of gschemas can be found [here](https://developer.gnome.org/gio/stable/gio-GSettingsSchema-GSettingsSchemaSource.html)\n\nNext, 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`\n\n```ruby\nclass ExampleAppWindow \u003c Gtk::ApplicationWindow\n  type_register\n  class \u003c\u003c self\n    def init\n      set_template(:resource =\u003e \"/org/gtk/exampleapp/window.ui\")\n      bind_template_child(\"stack\")\n    end\n  end\n\n  def initialize(application)\n    super(:application =\u003e application)\n    settings = Gio::Settings.new(\"org.gtk.exampleapp\")\n    settings.bind(\"transition\",\n                  stack,\n                  \"transition-type\",\n                  Gio::SettingsBindFlags::DEFAULT)\n  end\n...\n```\n\n#### Configure the settings with a dialog window\n\n*    exampleapp6.rb\n\nThe 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.\nAt 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.\n\nLets start with the template.\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cinterface\u003e\n  \u003c!-- interface-requires gtk+ 3.8 --\u003e\n  \u003ctemplate class=\"ExampleAppPrefs\" parent=\"GtkDialog\"\u003e\n    \u003cproperty name=\"title\" translatable=\"yes\"\u003ePreferences\u003c/property\u003e\n    \u003cproperty name=\"resizable\"\u003eFalse\u003c/property\u003e\n    \u003cproperty name=\"modal\"\u003eTrue\u003c/property\u003e\n    \u003cchild internal-child=\"vbox\"\u003e\n      \u003cobject class=\"GtkBox\" id=\"vbox\"\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkGrid\" id=\"grid\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cproperty name=\"margin\"\u003e6\u003c/property\u003e\n            \u003cproperty name=\"row-spacing\"\u003e12\u003c/property\u003e\n            \u003cproperty name=\"column-spacing\"\u003e6\u003c/property\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkLabel\" id=\"fontlabel\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"label\"\u003e_Font:\u003c/property\u003e\n                \u003cproperty name=\"use-underline\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"mnemonic-widget\"\u003efont\u003c/property\u003e\n                \u003cproperty name=\"xalign\"\u003e1\u003c/property\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"left-attach\"\u003e0\u003c/property\u003e\n                \u003cproperty name=\"top-attach\"\u003e0\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkFontButton\" id=\"font\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"left-attach\"\u003e1\u003c/property\u003e\n                \u003cproperty name=\"top-attach\"\u003e0\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkLabel\" id=\"transitionlabel\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"label\"\u003e_Transition:\u003c/property\u003e\n                \u003cproperty name=\"use-underline\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"mnemonic-widget\"\u003etransition\u003c/property\u003e\n                \u003cproperty name=\"xalign\"\u003e1\u003c/property\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"left-attach\"\u003e0\u003c/property\u003e\n                \u003cproperty name=\"top-attach\"\u003e1\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkComboBoxText\" id=\"transition\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003citems\u003e\n                  \u003citem translatable=\"yes\" id=\"none\"\u003eNone\u003c/item\u003e\n                  \u003citem translatable=\"yes\" id=\"crossfade\"\u003eFade\u003c/item\u003e\n                  \u003citem translatable=\"yes\" id=\"slide-left-right\"\u003eSlide\u003c/item\u003e\n                \u003c/items\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"left-attach\"\u003e1\u003c/property\u003e\n                \u003cproperty name=\"top-attach\"\u003e1\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n      \u003c/object\u003e\n    \u003c/child\u003e\n  \u003c/template\u003e\n\u003c/interface\u003e\n```\nNext comes the dialog subclass.\n\n```ruby\nclass ExampleAppPrefs \u003c Gtk::Dialog\n  type_register\n  class \u003c\u003c self\n    def init\n      set_template(:resource =\u003e \"/org/gtk/exampleapp/prefs.ui\")\n      bind_template_child(\"font\")\n      bind_template_child(\"transition\")\n    end\n  end\n  def initialize(args)\n    parent = args[:transient_for]\n    bar = args[:use_header_bar]\n    super(:transient_for =\u003e parent, :use_header_bar =\u003e 1)\n    settings = Gio::Settings.new(\"org.gtk.exampleapp\")\n    settings.bind(\"font\",\n                  font,\n                  \"font\",\n                  Gio::SettingsBindFlags::DEFAULT)\n    settings.bind(\"transition\",\n                  transition,\n                  \"active-id\",\n                  Gio::SettingsBindFlags::DEFAULT)\n  end\nend\n```\n\nNothing 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.\n\n```ruby\naction = Gio::SimpleAction.new(\"preferences\")\naction.signal_connect(\"activate\") do |_action, _parameter|\n  win = application.windows.first\n\n  prefs = ExampleAppPrefs.new(:transient_for =\u003e win,\n                              :use_header_bar =\u003e true)\n  prefs.present\nend\n```\nHere 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:\n\n```ruby\ndef open(file)\n  basename = file.basename\n  scrolled = Gtk::ScrolledWindow.new\n  scrolled.show\n  scrolled.set_hexpand(true)\n  scrolled.set_vexpand(true)\n  view = Gtk::TextView.new\n  view.set_editable(false)\n  view.set_cursor_visible(false)\n  view.show\n  scrolled.add(view)\n  stack.add_titled(scrolled, basename, basename)\n  stream = file.read\n  buffer = view.buffer\n  buffer.text = stream.read\n  tag = buffer.create_tag() \n  @settings.bind(\"font\", tag, \"font\", Gio::SettingsBindFlags::DEFAULT)\n  buffer.apply_tag(tag, buffer.start_iter, buffer.end_iter)\nend\n``` \n\n\n\n### Adding a search bar\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.10\n\n*    exampleapp7.rb\n\nWe 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.\nWe add a toggle button to the header bar, which can be used to slide out the search bar below the header bar.\n\nThe new window.ui file:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cinterface\u003e\n  \u003c!-- interface-requires gtk+ 3.8 --\u003e\n  \u003ctemplate class=\"ExampleAppWindow\" parent=\"GtkApplicationWindow\"\u003e\n    \u003cproperty name=\"title\" translatable=\"yes\"\u003eExample Application\u003c/property\u003e\n    \u003cproperty name=\"default-width\"\u003e600\u003c/property\u003e\n    \u003cproperty name=\"default-height\"\u003e400\u003c/property\u003e\n    \u003cchild\u003e\n      \u003cobject class=\"GtkBox\" id=\"content_box\"\u003e\n        \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n        \u003cproperty name=\"orientation\"\u003evertical\u003c/property\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkHeaderBar\" id=\"header\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cchild type=\"title\"\u003e\n              \u003cobject class=\"GtkStackSwitcher\" id=\"tabs\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"margin\"\u003e6\u003c/property\u003e\n                \u003cproperty name=\"stack\"\u003estack\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkToggleButton\" id=\"search\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"sensitive\"\u003eFalse\u003c/property\u003e\n                \u003cstyle\u003e\n                  \u003cclass name=\"image-button\"/\u003e\n                \u003c/style\u003e\n                \u003cchild\u003e\n                  \u003cobject class=\"GtkImage\" id=\"search-icon\"\u003e\n                    \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                    \u003cproperty name=\"icon-name\"\u003eedit-find-symbolic\u003c/property\u003e\n                    \u003cproperty name=\"icon-size\"\u003e1\u003c/property\u003e\n                  \u003c/object\u003e\n                \u003c/child\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"pack-type\"\u003eend\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkSearchBar\" id=\"searchbar\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkSearchEntry\" id=\"searchentry\"\u003e\n                \u003csignal name=\"search-changed\" handler=\"search_text_changed\"/\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkStack\" id=\"stack\"\u003e\n            \u003csignal name=\"notify::visible-child\" handler=\"visible_child_changed\"/\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n      \u003c/object\u003e\n    \u003c/child\u003e\n  \u003c/template\u003e\n\u003c/interface\u003e\n```\nImplementing 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.\n\n```ruby\n\ndef init\n  set_template(:resource =\u003e \"/org/gtk/exampleapp/window.ui\")\n  bind_template_child(\"stack\")\n  bind_template_child(\"search\")\n  bind_template_child(\"searchbar\")\n  set_connect_func do |name|\n    method(name)\n  end\nend\n\nprivate\n\ndef search_text_changed(search_entry)\n  text = search_entry.text\n  return if text.empty?\n\n  win = search_entry.toplevel\n  tab = win.stack.visible_child\n  view = tab.child\n  buffer = view.buffer\n  range = buffer.start_iter.forward_search(text, Gtk::TextSearchFlags::CASE_INSENSITIVE)\n  return unless range\n  buffer.select_range(range[0], range[1])\n  view.scroll_to_iter(range[0], 0.0, false, 0.0, 0.0)\nend\n```\n\nIn this part of code, the use of the method `set_connect_func` will allow us to define private methodsas 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 :\n\n    \u003csignal name=\"search-changed\" handler=\"search_text_changed\"/\u003e\n\nThose pieces together mean that the signal *search-changed* of the `Gtk::SearchEntry`, trigger the private method of `ExampleAppWindow` that is called `search_text_changed`.\n\n### Adding a sidebar\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.11\n\n*    exampleapp8.rb\n\nAs another piece of functionality, we are adding a sidebar, which demonstrates `Gtk::MenuButton`, `Gtk::Revealer` and Gtk::ListBox`.\n\nwindow.ui :\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cinterface\u003e\n  \u003c!-- interface-requires gtk+ 3.8 --\u003e\n  \u003ctemplate class=\"ExampleAppWindow\" parent=\"GtkApplicationWindow\"\u003e\n    \u003cproperty name=\"title\" translatable=\"yes\"\u003eExample Application\u003c/property\u003e\n    \u003cproperty name=\"default-width\"\u003e600\u003c/property\u003e\n    \u003cproperty name=\"default-height\"\u003e400\u003c/property\u003e\n    \u003cchild\u003e\n      \u003cobject class=\"GtkBox\" id=\"content_box\"\u003e\n        \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n        \u003cproperty name=\"orientation\"\u003evertical\u003c/property\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkHeaderBar\" id=\"header\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cchild type=\"title\"\u003e\n              \u003cobject class=\"GtkStackSwitcher\" id=\"tabs\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"margin\"\u003e6\u003c/property\u003e\n                \u003cproperty name=\"stack\"\u003estack\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkToggleButton\" id=\"search\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"sensitive\"\u003eFalse\u003c/property\u003e\n                \u003cstyle\u003e\n                  \u003cclass name=\"image-button\"/\u003e\n                \u003c/style\u003e\n                \u003cchild\u003e\n                  \u003cobject class=\"GtkImage\" id=\"search-icon\"\u003e\n                    \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                    \u003cproperty name=\"icon-name\"\u003eedit-find-symbolic\u003c/property\u003e\n                    \u003cproperty name=\"icon-size\"\u003e1\u003c/property\u003e\n                  \u003c/object\u003e\n                \u003c/child\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"pack-type\"\u003eend\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkMenuButton\" id=\"gears\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"direction\"\u003enone\u003c/property\u003e\n                \u003cproperty name=\"use-popover\"\u003eTrue\u003c/property\u003e\n                \u003cstyle\u003e\n                  \u003cclass name=\"image-button\"/\u003e\n                \u003c/style\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"pack-type\"\u003eend\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkSearchBar\" id=\"searchbar\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkSearchEntry\" id=\"searchentry\"\u003e\n                \u003csignal name=\"search-changed\" handler=\"search_text_changed\"/\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkBox\" id=\"hbox\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkRevealer\" id=\"sidebar\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"transition-type\"\u003eslide-right\u003c/property\u003e\n                \u003cchild\u003e\n                 \u003cobject class=\"GtkScrolledWindow\" id=\"sidebar-sw\"\u003e\n                   \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                   \u003cproperty name=\"hscrollbar-policy\"\u003enever\u003c/property\u003e\n                   \u003cproperty name=\"vscrollbar-policy\"\u003eautomatic\u003c/property\u003e\n                   \u003cchild\u003e\n                     \u003cobject class=\"GtkListBox\" id=\"words\"\u003e\n                       \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                       \u003cproperty name=\"selection-mode\"\u003enone\u003c/property\u003e\n                     \u003c/object\u003e\n                   \u003c/child\u003e\n                 \u003c/object\u003e\n                \u003c/child\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkStack\" id=\"stack\"\u003e\n                \u003csignal name=\"notify::visible-child\" handler=\"visible_child_changed\"/\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n      \u003c/object\u003e\n    \u003c/child\u003e\n  \u003c/template\u003e\n\u003c/interface\u003e\n```\n\nThe code to populate the sidebar with buttons for the words found in each file is a little too involved to go into here. But we'll look at the code to add the gears menu.\nAs expected by now, the gears menu is specified in a GtkBuilder ui file.\n\ngears-menu.ui\n\n```xml\n\u003c?xml version=\"1.0\"?\u003e\n\u003cinterface\u003e\n  \u003c!-- interface-requires gtk+ 3.0 --\u003e\n  \u003cmenu id=\"menu\"\u003e\n    \u003csection\u003e\n      \u003citem\u003e\n        \u003cattribute name=\"label\" translatable=\"yes\"\u003e_Words\u003c/attribute\u003e\n        \u003cattribute name=\"action\"\u003ewin.show-words\u003c/attribute\u003e\n      \u003c/item\u003e\n    \u003c/section\u003e\n  \u003c/menu\u003e\n\u003c/interface\u003e\n```\nTo connect the menuitem to the show-words setting, we use a `Gio::SimpleAction` corresponding to the given `Gio::Settings` key.\n\n```ruby\nclass ExampleAppWindow \u003c Gtk::ApplicationWindow\n  # some code\n  def initialize(application)\n    super(:application =\u003e application)\n    @settings = Gio::Settings.new(\"org.gtk.exampleapp\")\n    @settings.bind(\"transition\",\n                   stack,\n                   \"transition-type\",\n                   Gio::SettingsBindFlags::DEFAULT)\n    search.bind_property(\"active\", searchbar, \"search-mode-enabled\", :bidirectional)\n    @settings.bind(\"show-words\",\n                   sidebar,\n                   \"reveal-child\",\n                   Gio::SettingsBindFlags::DEFAULT)\n    sidebar.signal_connect \"notify::reveal-child\" do |_sidebar, _gparamspec|\n      update_words(self)\n    end\n    builder = Gtk::Builder.new(:resource =\u003e \"/org/gtk/exampleapp/gears-menu.ui\")\n    menu = builder.get_object(\"menu\")\n    gears.set_menu_model(menu)\n    action = @settings.create_action(\"show-words\")\n    add_action(action)\n  end\n\n  # some code\nend\n```\n\n### Properties\n\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.12\n\nWidgets and other objects have many useful properties.\n\nHere we show some ways to use them in new and flexible ways, by wrapping them in actions with `Gio::PropertyAction` or by binding them with `Gio::Binding`.\nTo set this up, we add two labels to the header bar in our window template, named *lines_label* and *lines*, and bind them to struct members in the private struct, as we've seen a couple of times by now.\nWe add a new \"Lines\" menu item to the gears menu, which triggers the show-lines action:\n\n```xml\n\u003c?xml version=\"1.0\"?\u003e\n\u003cinterface\u003e\n  \u003c!-- interface-requires gtk+ 3.0 --\u003e\n  \u003cmenu id=\"menu\"\u003e\n    \u003csection\u003e\n      \u003citem\u003e\n        \u003cattribute name=\"label\" translatable=\"yes\"\u003e_Words\u003c/attribute\u003e\n        \u003cattribute name=\"action\"\u003ewin.show-words\u003c/attribute\u003e\n      \u003c/item\u003e\n      \u003citem\u003e\n        \u003cattribute name=\"label\" translatable=\"yes\"\u003e_Lines\u003c/attribute\u003e\n        \u003cattribute name=\"action\"\u003ewin.show-lines\u003c/attribute\u003e\n      \u003c/item\u003e\n    \u003c/section\u003e\n  \u003c/menu\u003e\n\u003c/interface\u003e\n```\n\nTo make this menu item do something, we create a property action for the visible property of the lines label, and add it to the actions of the window. The effect of this is that the visibility of the label gets toggled every time the action is activated.\nSince we want both labels to appear and disappear together, we bind the visible property of the lines_label widget to the same property of the lines widget.\n\n*    exampleapp9.rb\n\n```ruby\n# ...\nclass ExampleAppWindow \u003c Gtk::ApplicationWindow\n# ...\n  def initialize(application)\n    super(:application =\u003e application)\n# ...\n    action = Gio::PropertyAction.new(\"show-lines\", lines, \"visible\")\n    add_action(action)\n    lines.bind_property(\"visible\", lines_label, \"visible\", :default)\n  end\n```\nWe also need a function that counts the lines of the currently active tab, and updates the lines label. See the full source if you are interested in the details.\n\n### Header Bar\n\nhttps://developer.gnome.org/gtk3/stable/ch01s04.html#id-1.2.3.12.13\n\nOur application already uses a `Gtk::HeaderBar`, but so far it still gets a 'normal' window titlebar on top of that. This is a bit redundant, and we will now tell GTK+ to use the header bar as replacement for the titlebar. To do so, we move it around to be a direct child of the window, and set its type to be titlebar.\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cinterface\u003e\n  \u003c!-- interface-requires gtk+ 3.8 --\u003e\n  \u003ctemplate class=\"ExampleAppWindow\" parent=\"GtkApplicationWindow\"\u003e\n    \u003cproperty name=\"title\" translatable=\"yes\"\u003eExample Application\u003c/property\u003e\n    \u003cproperty name=\"default-width\"\u003e600\u003c/property\u003e\n    \u003cproperty name=\"default-height\"\u003e400\u003c/property\u003e\n        \u003cchild type=\"titlebar\"\u003e\n          \u003cobject class=\"GtkHeaderBar\" id=\"header\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cproperty name=\"show-close-button\"\u003eTrue\u003c/property\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkLabel\" id=\"lines_label\"\u003e\n                \u003cproperty name=\"visible\"\u003eFalse\u003c/property\u003e\n                \u003cproperty name=\"label\" translatable=\"yes\"\u003eLines:\u003c/property\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"pack-type\"\u003estart\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkLabel\" id=\"lines\"\u003e\n                \u003cproperty name=\"visible\"\u003eFalse\u003c/property\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"pack-type\"\u003estart\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n            \u003cchild type=\"title\"\u003e\n              \u003cobject class=\"GtkStackSwitcher\" id=\"tabs\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"margin\"\u003e6\u003c/property\u003e\n                \u003cproperty name=\"stack\"\u003estack\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkToggleButton\" id=\"search\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"sensitive\"\u003eFalse\u003c/property\u003e\n                \u003cstyle\u003e\n                  \u003cclass name=\"image-button\"/\u003e\n                \u003c/style\u003e\n                \u003cchild\u003e\n                  \u003cobject class=\"GtkImage\" id=\"search-icon\"\u003e\n                    \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                    \u003cproperty name=\"icon-name\"\u003eedit-find-symbolic\u003c/property\u003e\n                    \u003cproperty name=\"icon-size\"\u003e1\u003c/property\u003e\n                  \u003c/object\u003e\n                \u003c/child\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"pack-type\"\u003eend\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkMenuButton\" id=\"gears\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"direction\"\u003enone\u003c/property\u003e\n                \u003cproperty name=\"use-popover\"\u003eTrue\u003c/property\u003e\n                \u003cstyle\u003e\n                  \u003cclass name=\"image-button\"/\u003e\n                \u003c/style\u003e\n              \u003c/object\u003e\n              \u003cpacking\u003e\n                \u003cproperty name=\"pack-type\"\u003eend\u003c/property\u003e\n              \u003c/packing\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n    \u003cchild\u003e\n      \u003cobject class=\"GtkBox\" id=\"content_box\"\u003e\n        \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n        \u003cproperty name=\"orientation\"\u003evertical\u003c/property\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkSearchBar\" id=\"searchbar\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkSearchEntry\" id=\"searchentry\"\u003e\n                \u003csignal name=\"search-changed\" handler=\"search_text_changed\"/\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n        \u003cchild\u003e\n          \u003cobject class=\"GtkBox\" id=\"hbox\"\u003e\n            \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkRevealer\" id=\"sidebar\"\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                \u003cproperty name=\"transition-type\"\u003eslide-right\u003c/property\u003e\n                \u003cchild\u003e\n                 \u003cobject class=\"GtkScrolledWindow\" id=\"sidebar-sw\"\u003e\n                   \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                   \u003cproperty name=\"hscrollbar-policy\"\u003enever\u003c/property\u003e\n                   \u003cproperty name=\"vscrollbar-policy\"\u003eautomatic\u003c/property\u003e\n                   \u003cchild\u003e\n                     \u003cobject class=\"GtkListBox\" id=\"words\"\u003e\n                       \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n                       \u003cproperty name=\"selection-mode\"\u003enone\u003c/property\u003e\n                     \u003c/object\u003e\n                   \u003c/child\u003e\n                 \u003c/object\u003e\n                \u003c/child\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n            \u003cchild\u003e\n              \u003cobject class=\"GtkStack\" id=\"stack\"\u003e\n                \u003csignal name=\"notify::visible-child\" handler=\"visible_child_changed\"/\u003e\n                \u003cproperty name=\"visible\"\u003eTrue\u003c/property\u003e\n              \u003c/object\u003e\n            \u003c/child\u003e\n          \u003c/object\u003e\n        \u003c/child\u003e\n      \u003c/object\u003e\n    \u003c/child\u003e\n  \u003c/template\u003e\n\u003c/interface\u003e\n```\n\nA small extra bonus of using a header bar is that we get a fallback application menu for free. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedlemo%2Fruby-gtk3-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcedlemo%2Fruby-gtk3-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedlemo%2Fruby-gtk3-tutorial/lists"}