使用 Ruby 创建 Linux 桌面应用程序

最近，在尝试 GTK 及其 Ruby 绑定时，我决定编写一个教程来介绍此功能。在这篇文章中，我们将使用 gtk3 gem（又名 GTK+ Ruby 绑定）创建一个简单的 ToDo 应用程序（类似于我们使用 Ruby on Rails 创建的应用程序）。

您可以在 GitHub 上找到本教程的代码。

什么是 GTK+？

根据 GTK+ 网站

GTK+，即 GIMP 工具包，是一个用于创建图形用户界面的多平台工具包。GTK+ 提供了一整套完整的组件，适用于从小型一次性工具到完整应用程序套件的各种项目。

该网站还解释了创建 GTK+ 的原因

GTK+ 最初是为 GIMP（GNU 图像处理程序）开发和使用的。它被称为“The GIMP ToolKit”，以便记住该项目的起源。如今，它更常被称为 GTK+，并被大量应用程序使用，包括 GNU 项目的 GNOME 桌面。

先决条件

GTK+

请确保您已安装 GTK+。我是在 Ubuntu 16.04 中开发本教程的应用程序的，该系统默认安装了 GTK+（版本 3.18）。

您可以使用以下命令检查您的版本： dpkg -l libgtk-3-0。

Ruby

您的系统应该安装了 Ruby。我使用 RVM 来管理系统上安装的多个 Ruby 版本。如果您也想这样做，可以在 RVM 的主页上找到 RVM 安装说明，并在 相关文档页面上找到安装 Ruby 版本（又名 Rubies）的说明。

本教程使用 Ruby 2.4.2。您可以使用 ruby --version 或通过 RVM 使用 rvm list 检查您的版本。

图片来源：

opensource.com

Glade

根据 Glade 的网站，“Glade 是一个 RAD 工具，可以快速轻松地为 GTK+ 工具包和 GNOME 桌面环境开发用户界面。”

我们将使用 Glade 来设计我们应用程序的用户界面。如果您使用的是 Ubuntu，请使用 sudo apt install glade 安装 glade。

GTK3 gem

这个 gem 提供了 GTK+ 工具包的 Ruby 绑定。换句话说，它允许我们使用 Ruby 语言与 GTK+ API 通信。

使用 gem install gtk3 安装 gem。

定义应用程序规范

我们将在本教程中构建的应用程序将

• 具有用户界面（即桌面应用程序）
• 允许用户为每个项目设置各种属性（例如，优先级）
• 允许用户创建和编辑 ToDo 项目
  • 所有项目都将以文件形式保存在用户主目录中名为 .gtk-todo-tutorial 的文件夹中
• 允许用户存档 ToDo 项目
  • 存档的项目应放在名为 archived 的单独文件夹中

应用程序结构

gtk-todo-tutorial # root directory
  |-- application
    |-- ui # everything related to the ui of the application
    |-- models # our models
    |-- lib # the directory to host any utilities we might need
  |-- resources # directory to host the resources of our application
  gtk-todo # the executable that will start our application

构建 ToDo 应用程序

初始化应用程序

创建一个目录来保存应用程序所需的所有文件。正如您在上面的结构中看到的，我将其命名为 gtk-todo-tutorial。

创建一个名为 gtk-todo 的文件（没错，没有扩展名）并添加以下内容

#!/usr/bin/env ruby

require 'gtk3'

app = Gtk::Application.new 'com.iridakos.gtk-todo', :flags_none

app.signal_connect :activate do |application|
  window = Gtk::ApplicationWindow.new(application)
  window.set_title 'Hello GTK+Ruby!'
  window.present
end

puts app.run

这将是启动应用程序的脚本。

注意第一行的 shebang (#!)。这就是我们定义哪个解释器将在 Unix/Linux 操作系统下执行脚本的方式。这样，我们不必使用 ruby gtk-todo；我们可以直接使用脚本的名称：gtk-todo。

不过，现在还不要尝试，因为我们还没有将文件的模式更改为可执行。要做到这一点，请在导航到应用程序的根目录后，在终端中键入以下命令

chmod +x ./gtk-todo # make the script executable

从控制台执行

./gtk-todo # execute the script

图片来源：

opensource.com

注释

• 我们上面定义的应用程序对象（以及所有的 GTK+ 组件）会发出信号来触发事件。例如，一旦应用程序开始运行，它就会发出一个信号来触发 activate 事件。我们所要做的就是定义当发出此信号时我们希望发生什么。我们通过使用 signal_connect 实例方法并传递一个代码块来实现这一点，该代码块将在给定事件发生时执行。在整个教程中，我们将经常这样做。
• 当我们初始化 Gtk::Application 对象时，我们传递了两个参数
  • com.iridakos.gtk-todo：这是我们应用程序的 ID，一般来说，它应该是一个反向 DNS 风格的标识符。您可以在 GNOME 的 wiki 上了解更多关于其用法和最佳实践的信息。
  • :flags_none：此标志定义了应用程序的行为。我们使用了默认行为。查看所有 标志以及它们定义的应用程序类型。我们可以使用 Ruby 等效标志，如 Gio::ApplicationFlags.constants 中定义的那样。例如，我们可以使用 Gio::ApplicationFlags::FLAGS_NONE 而不是 :flags_none。

假设我们之前创建的应用程序对象 (Gtk::Application) 在发出 activate 信号时有很多事情要做，或者我们想要连接到更多信号。我们最终会创建一个巨大的 gtk-todo 脚本文件，使其难以阅读/维护。现在是时候重构了。

如上面的应用程序结构中所述，我们将创建一个名为 application 的文件夹和子文件夹 ui、models 和 lib。

• 在 ui 文件夹中，我们将放置所有与用户界面相关的文件。
• 在 models 文件夹中，我们将放置所有与模型相关的文件。
• 在 lib 文件夹中，我们将放置所有不属于上述任何类别的文件。

我们将为我们的应用程序定义 Gtk::Application 类的新子类。我们将在 application/ui/todo 下创建一个名为 application.rb 的文件，内容如下

module ToDo
  class Application < Gtk::Application
    def initialize
      super 'com.iridakos.gtk-todo', Gio::ApplicationFlags::FLAGS_NONE

      signal_connect :activate do |application|
        window = Gtk::ApplicationWindow.new(application)
        window.set_title 'Hello GTK+Ruby!'
        window.present
      end
    end
  end
end

我们将相应地更改 gtk-todo 脚本

#!/usr/bin/env ruby

require 'gtk3'

app = ToDo::Application.new

puts app.run

更简洁了，不是吗？是的，但是它不起作用。我们得到类似这样的结果

./gtk-todo:5:in `<main>': uninitialized constant ToDo (NameError)

问题是我们没有 require 任何放置在 application 文件夹中的 Ruby 文件。我们需要按如下方式更改脚本文件并再次执行它。

#!/usr/bin/env ruby

require 'gtk3'

# Require all ruby files in the application folder recursively
application_root_path = File.expand_path(__dir__)
Dir[File.join(application_root_path, '**', '*.rb')].each { |file| require file }

app = ToDo::Application.new

puts app.run

现在应该可以了。

资源

在本教程的开头，我们说过我们将使用 Glade 来设计应用程序的用户界面。Glade 生成 xml 文件，其中包含适当的元素和属性，以反映我们通过其用户界面设计的内容。我们需要使用这些文件来让我们的应用程序获得我们设计的 UI。

这些文件是应用程序的资源，GResource API 提供了一种将它们全部打包到一个二进制文件中的方法，该二进制文件稍后可以从应用程序内部访问，具有优势——而不是手动处理已加载的资源、它们在文件系统上的位置等等。阅读更多关于 GResource API 的信息。

描述资源

首先，我们需要创建一个文件来描述应用程序的资源。创建一个名为 gresources.xml 的文件，并将其直接放在 resources 文件夹下。

<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/com/iridakos/gtk-todo">
    <file preprocess="xml-stripblanks">ui/application_window.ui</file>
  </gresource>
</gresources>

此描述基本上是说：“我们有一个资源，它位于 ui 目录（相对于此 xml 文件）下，名称为 application_window.ui。在加载此资源之前，请删除空白。” 当然，这还不行，因为我们还没有通过 Glade 创建资源。不过别担心，一次做一件事。

注意：xml-stripblanks 指令将使用 xmllint 命令来删除空白。在 Ubuntu 中，您必须安装 libxml2-utils 包。

构建资源二进制文件

为了生成二进制资源文件，我们将使用另一个名为 glib-compile-resources 的 GLib 库实用程序。检查您是否已安装它，使用 dpkg -l libglib2.0-bin。您应该看到类似这样的结果

ii  libglib2.0-bin     2.48.2-0ubuntu amd64          Programs for the GLib library

如果没有，请安装该软件包（在 Ubuntu 中为 sudo apt install libglib2.0-bin）。

让我们构建文件。我们将在我们的脚本中添加代码，以便每次执行它时都会构建资源。按如下方式更改 gtk-todo 脚本

#!/usr/bin/env ruby

require 'gtk3'
require 'fileutils'

# Require all ruby files in the application folder recursively
application_root_path = File.expand_path(__dir__)
Dir[File.join(application_root_path, '**', '*.rb')].each { |file| require file }

# Define the source & target files of the glib-compile-resources command
resource_xml = File.join(application_root_path, 'resources', 'gresources.xml')
resource_bin = File.join(application_root_path, 'gresource.bin')

# Build the binary
system("glib-compile-resources",
       "--target", resource_bin,
       "--sourcedir", File.dirname(resource_xml),
       resource_xml)

at_exit do
  # Before existing, please remove the binary we produced, thanks.
  FileUtils.rm_f(resource_bin)
end

app = ToDo::Application.new
puts app.run

当我们执行它时，控制台中会发生以下情况；我们稍后会修复它

/.../gtk-todo-tutorial/resources/gresources.xml: Failed to locate 'ui/application_window.ui' in any source directory.

这是我们所做的

• 为 fileutils 库添加了一个 require 语句，以便我们可以在 at_exit 调用中使用它
• 定义了 glib-compile-resources 命令的源文件和目标文件
• 执行了 glib-compile-resources 命令
• 设置了一个钩子，以便在退出脚本之前（即在应用程序退出之前）删除二进制文件，以便下次再次构建它

加载资源二进制文件

我们已经描述了资源并将它们打包到一个二进制文件中。现在我们必须在应用程序中加载和注册它们，以便我们可以使用它们。这就像在 at_exit 钩子之前添加以下两行一样简单

resource = Gio::Resource.load(resource_bin)
Gio::Resources.register(resource)

就是这样。从现在开始，我们可以从应用程序内部的任何地方使用资源。（我们稍后会看到如何使用。）目前，脚本失败，因为它无法加载未生成的二进制文件。请耐心等待；我们很快就会进入有趣的部分。实际上就是现在。

设计主应用程序窗口

介绍 Glade

首先，打开 Glade。

图片来源：

opensource.com

这是我们看到的

• 左侧是组件列表，可以将其拖放到中间部分。（您不能在标签组件内添加顶级窗口。）我将其称为**组件部分**。
• 中间部分包含我们的组件，它们将（大多数时候）在应用程序中显示。我将其称为**设计部分**。
• 右侧是两个子部分
  • 顶部部分包含添加到资源的组件的层次结构。我将其称为**层次结构部分**。
  • 底部部分包含可以通过 Glade 为上面选择的组件配置的所有属性。我将其称为**属性部分**。

我将描述使用 Glade 构建本教程 UI 的步骤，但如果您有兴趣构建 GTK+ 应用程序，您应该查看该工具的官方 资源和 教程。

创建应用程序窗口设计

让我们通过简单地将**应用程序窗口**组件从**组件部分**拖到**设计部分**来创建应用程序窗口。

图片来源：

opensource.com

Gtk::Builder 是 GTK+ 应用程序中使用的对象，用于读取用户界面的文本描述（例如我们将通过 Glade 构建的那个）并构建描述的对象组件。

**属性部分**中的第一件事是 ID，它具有默认值 applicationWindow1。如果我们保持此属性不变，我们稍后将通过我们的代码创建一个 Gtk::Builder，它将加载 Glade 生成的文件。为了获得应用程序窗口，我们将不得不使用类似这样的代码

application_window = builder.get_object('applicationWindow1')

application_window.signal_connect 'whatever' do |a,b|
...

application_window 对象将是 Gtk::ApplicationWindow 类；因此，我们必须添加到其行为中的任何内容（例如设置其标题）都将在原始类之外发生。此外，如上面的代码片段所示，连接到窗口信号的代码将放在实例化它的文件中。

好消息是 GTK+ 在 2013 年引入了一项 功能，允许创建复合组件模板，该模板（除其他优点外）允许我们为组件定义自定义类（通常最终从现有的 GTK::Widget 类派生）。如果您感到困惑，请不要担心。在编写一些代码并查看结果后，您将了解发生了什么。

要将我们的设计定义为模板，请选中属性组件中的 **Composite** 复选框。请注意，ID 属性已更改为 **Class Name**。填写 TodoApplicationWindow。这是我们将在代码中创建以表示此组件的类。

图片来源：

opensource.com

将文件以名称 application_window.ui 保存在 resources 内部名为 ui 的新文件夹中。如果我们从编辑器中打开该文件，就会看到以下内容

<?xml version="1.0" encoding="UTF-8"?>
<!-- Generated with glade 3.18.3 -->
<interface>
  <requires lib="gtk+" version="3.12"/>
  <template class="TodoApplicationWindow" parent="GtkApplicationWindow">
    <property name="can_focus">False</property>
    <child>
      <placeholder/>
    </child>
  </template>
</interface>

我们的组件具有类和父属性。按照父类属性约定，我们的类必须在名为 Todo 的模块内定义。在开始之前，让我们尝试通过执行脚本 (./gtk-todo) 来启动应用程序。

耶！它启动了！

创建应用程序窗口类

如果我们检查应用程序运行时应用程序根目录的内容，我们可以看到 gresource.bin 文件在那里。即使应用程序成功启动，因为资源 bin 存在并且可以注册，我们现在还不会使用它。我们仍然会在我们的 application.rb 文件中初始化一个普通的 Gtk::ApplicationWindow。现在是时候创建我们的自定义应用程序窗口类了。

在 application/ui/todo 文件夹中创建一个名为 application_window.rb 的文件，并添加以下内容

module Todo
  class ApplicationWindow < Gtk::ApplicationWindow
    # Register the class in the GLib world
    type_register

    class << self
      def init
        # Set the template from the resources binary
        set_template resource: '/com/iridakos/gtk-todo/ui/application_window.ui'
      end
    end

    def initialize(application)
      super application: application

      set_title 'GTK+ Simple ToDo'
    end
  end
end

我们在打开 *eigenclass* 后将 init 方法定义为类上的单例方法，以便将此组件的模板绑定到先前注册的资源文件。

在此之前，我们调用了 type_register 类方法，该方法注册并将我们的自定义组件类提供给 GLib 世界。

最后，每次我们创建此窗口的实例时，我们都会将其标题设置为 GTK+ Simple ToDo。

现在，让我们回到 application.rb 文件并使用我们刚刚实现的内容

module ToDo
  class Application < Gtk::Application
    def initialize
      super 'com.iridakos.gtk-todo', Gio::ApplicationFlags::FLAGS_NONE

      signal_connect :activate do |application|
        window = Todo::ApplicationWindow.new(application)
        window.present
      end
    end
  end
end

执行脚本。

图片来源：

opensource.com

定义模型

为了简单起见，我们将 ToDo 项目以 JSON 格式的文件保存在用户主目录中的专用隐藏文件夹中。在实际应用程序中，我们将使用数据库，但这超出了本教程的范围。

我们的 Todo::Item 模型将具有以下属性

• id：项目的 id
• title：标题
• notes：任何备注
• priority：其优先级
• creation_datetime：项目创建的日期和时间
• filename：项目保存到的文件名

我们将在 application/models 目录下创建一个名为 item.rb 的文件，内容如下

require 'securerandom'
require 'json'

module Todo
  class Item
    PROPERTIES = [:id, :title, :notes, :priority, :filename, :creation_datetime].freeze

    PRIORITIES = ['high', 'medium', 'normal', 'low'].freeze

    attr_accessor *PROPERTIES

    def initialize(options = {})
      if user_data_path = options[:user_data_path]
        # New item. When saved, it will be placed under the :user_data_path value
        @id = SecureRandom.uuid
        @creation_datetime = Time.now.to_s
        @filename = "#{user_data_path}/#{id}.json"
      elsif filename = options[:filename]
        # Load an existing item
        load_from_file filename
      else
        raise ArgumentError, 'Please specify the :user_data_path for new item or the :filename to load existing'
      end
    end

    # Loads an item from a file
    def load_from_file(filename)
      properties = JSON.parse(File.read(filename))

      # Assign the properties
      PROPERTIES.each do |property|
        self.send "#{property}=", properties[property.to_s]
      end
    rescue => e
      raise ArgumentError, "Failed to load existing item: #{e.message}"
    end

    # Resolves if an item is new
    def is_new?
      !File.exists? @filename
    end

    # Saves an item to its `filename` location
    def save!
      File.open(@filename, 'w') do |file|
        file.write self.to_json
      end
    end

    # Deletes an item
    def delete!
      raise 'Item is not saved!' if is_new?

      File.delete(@filename)
    end

    # Produces a json string for the item
    def to_json
      result = {}
      PROPERTIES.each do |prop|
        result[prop] = self.send prop
      end

      result.to_json
    end
  end
end

在这里我们定义了以下方法

• 初始化项目
  • 作为“新”项目，通过定义稍后将保存它的 :user_data_path
  • 作为“现有”项目，通过定义要从中加载的 :filename。文件名必须是先前由项目生成的 JSON 文件
• 从文件加载项目
• 确定项目是新的还是旧的（即，是否至少在 :user_data_path 中保存过）
• 通过将其 JSON 字符串写入文件来保存项目
• 删除项目
• 生成项目的 JSON 字符串作为其属性的哈希值

添加新项目

创建按钮

让我们在我们的应用程序窗口中添加一个按钮，用于添加新项目。在 Glade 中打开 resources/ui/application_window.ui 文件。

• 将 Button 从 **组件部分** 拖到 **设计部分**。
• 在 **属性部分** 中，将其 ID 值设置为 add_new_item_button。
• 在 **属性部分** 中 *General* 选项卡的底部附近，在 *Label with optional image* 选项的正下方有一个文本区域。将其值从 *Button* 更改为 *Add new item*。
• 保存文件并执行脚本。

图片来源：

opensource.com

别担心；我们稍后会改进设计。现在，让我们看看如何将功能 *连接* 到我们按钮的 *clicked* 事件。

首先，我们必须更新我们的应用程序窗口类，以便它了解它的新子项，即 id 为 add_new_item_button 的按钮。然后我们可以访问子项以更改其行为。

按如下方式更改 init 方法

def init
  # Set the template from the resources binary
  set_template resource: '/com/iridakos/gtk-todo/ui/application_window.ui'

  bind_template_child 'add_new_item_button'
end

很简单，对吧？bind_template_child 方法完全按照它所说的做，从现在开始，我们的 Todo::ApplicationWindow 类的每个实例都将有一个 add_new_item_button 方法来访问相关的按钮。因此，让我们按如下方式更改 initialize 方法

def initialize(application)
  super application: application

  set_title 'GTK+ Simple ToDo'

  add_new_item_button.signal_connect 'clicked' do |button, application|
    puts "OMG! I AM CLICKED"
  end
end

正如您所看到的，我们将通过 add_new_item_button 方法访问按钮，并且我们定义了当它被单击时我们希望发生的事情。重新启动应用程序并尝试单击按钮。在控制台中，当您单击按钮时，您应该看到消息 OMG! I AM CLICKED。

但是，当我们单击此按钮时，我们希望发生的事情是显示一个新窗口来保存 ToDo 项目。您猜对了：现在是 Glade 时间。

创建新项目窗口

• 通过按顶部栏中最左侧的图标或从应用程序菜单中选择 *文件 > 新建*，在 Glade 中创建一个新项目。
• 将 Window 从 **组件部分** 拖到 **设计区域**。
• 选中其 **Composite** 属性并将类命名为 TodoNewItemWindow。

图片来源：

opensource.com

• 将 Grid 从 **组件部分** 拖到我们之前添加的窗口中。
• 在弹出的窗口中设置 **5** 行和 **2** 列。
• 在 **属性部分** 的 *General* 选项卡中，将行和列间距设置为 **10**（像素）。
• 在 **属性部分** 的 *Common* 选项卡中，将 Widget Spacing > Margins > Top, Bottom, Left, Right 全部设置为 **10**，以便内容不会粘在网格的边框上。

图片来源：

opensource.com

• 将四个 Label 组件从 **组件部分** 拖到网格的每一行中。
• 从上到下，按如下方式更改它们的 Label 属性
  • Id
  • 标题
  • 注释
  • 优先级
• 在 **属性部分** 的 *General* 选项卡中，将每个属性的 *Alignment and Padding > Alignment > Horizontal* 属性从 0.50 更改为 **1**，以便右对齐标签文本。
• 此步骤是可选的，但建议执行。我们不会在我们的窗口中绑定这些标签，因为我们不需要更改它们的状态或行为。在这种情况下，我们不需要像我们在应用程序窗口中为 add_new_item_button 按钮所做的那样为它们设置描述性 ID。但是 我们将在我们的设计中添加更多元素，如果它们说 label1、label2 等，Glade 中组件的层次结构将很难阅读。设置描述性 ID（如 id_label、title_label、notes_label、priority_label）将使我们的生活更轻松。我甚至将网格的 ID 设置为 main_grid，因为我不喜欢在 ID 中看到数字或变量名。

图片来源：

opensource.com

• 将 Label 从 **组件部分** 拖到网格第一行的第二列。ID 将由我们的模型自动生成；我们不允许编辑，因此一个标签来显示它就足够了。
• 将 ID 属性设置为 id_value_label。
• 将 *Alignment and Padding > Alignment > Horizontal* 属性设置为 **0**，以便文本在左侧对齐。
• 我们将此组件绑定到我们的 Window 类，以便我们每次加载窗口时都可以更改其文本。因此，不需要通过 Glade 设置标签，但它使设计更接近于使用实际数据渲染时的外观。您可以将标签设置为最适合您的任何内容；我将我的设置为 id-of-the-todo-item-here。

图片来源：

opensource.com

• 将 Text Entry 从 **组件部分** 拖到网格第二行第二列。
• 将其 ID 属性设置为 title_text_entry。正如您可能已经注意到的，我更喜欢在 ID 中获取组件类型，以使类中的代码更具可读性。
• 在 **属性部分** 的 *Common* 选项卡中，选中 Widget Spacing > Expand > Horizontal 复选框，然后打开旁边的开关。这样，组件将在每次调整其父组件（又名网格）大小时水平扩展。

图片来源：

opensource.com

• 将 Text View 从 **组件部分** 拖到网格第三行第二列。
• 将其 ID 设置为 notes。不，只是在测试您。将其 ID 属性设置为 notes_text_view。
• 在 **属性部分** 的 *Common* 选项卡中，选中 Widget Spacing > Expand > Horizontal, Vertical 复选框，然后打开旁边的开关。这样，组件将在每次调整其父组件（网格）大小时水平和垂直扩展。

图片来源：

opensource.com

• 将 Combo Box 从 **组件部分** 拖到网格第四行第二列。
• 将其 ID 设置为 priority_combo_box。
• 在 **属性部分** 的 *Common* 选项卡中，选中 Widget Spacing > Expand > Horizontal 复选框，然后打开右侧的开关。这允许组件在每次调整其父组件（网格）大小时水平扩展。
• 此组件是一个下拉元素。我们将在我们的窗口类中显示它时填充用户可以选择的值。

图片来源：

opensource.com

• 将 Button Box 从 **组件部分** 拖到网格最后一行的第二列。
• 在弹出窗口中，选择 **2** 个项目。
• 在 **属性部分** 的 *General* 选项卡中，将 *Box Attributes > Orientation* 属性设置为 **Horizontal**。
• 在 **属性部分** 的 *General* 选项卡中，将 *Box Attributes > Spacing* 属性设置为 **10**。
• 在 **属性部分** 的 *Common* 选项卡中，将 *Widget Spacing > Alignment > Horizontal* 设置为 **Center**。
• 同样，我们的代码不会更改此组件，但您可以为其提供描述性 ID 以提高可读性。我将其命名为 actions_box。

图片来源：

opensource.com

• 拖动两个 Button 组件，并将一个放在我们在上一步中添加的按钮框组件的每个框中。
• 分别将其 ID 属性设置为 cancel_button 和 save_button。
• 在 **属性窗口** 的 *General* 选项卡中，分别将其 *Button Content > Label with option image* 属性设置为 **Cancel** 和 **Save**。

图片来源：

opensource.com

窗口已准备就绪。将文件保存在 resources/ui/new_item_window.ui 下。

现在是时候将其移植到我们的应用程序中了。

实现新项目窗口类

在实现新类之前，我们必须更新我们的 GResource 描述文件 (resources/gresources.xml) 以获取新资源

<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/com/iridakos/gtk-todo">
    <file preprocess="xml-stripblanks">ui/application_window.ui</file>
    <file preprocess="xml-stripblanks">ui/new_item_window.ui</file>
  </gresource>
</gresources>

现在我们可以创建新的窗口类了。在 application/ui/todo 下创建一个名为 new_item_window.rb 的文件，并将其内容设置为如下

module Todo
  class NewItemWindow < Gtk::Window
    # Register the class in the GLib world
    type_register

    class << self
      def init
        # Set the template from the resources binary
        set_template resource: '/com/iridakos/gtk-todo/ui/new_item_window.ui'
      end
    end

    def initialize(application)
      super application: application
    end
  end
end

这里没有什么特别的。我们只是更改了模板资源以指向我们资源的正确文件。

我们必须更改在 clicked 信号上执行的 add_new_item_button 代码，以显示新项目窗口。我们将继续在 application_window.rb 中将该代码更改为如下所示

add_new_item_button.signal_connect 'clicked' do |button|
  new_item_window = NewItemWindow.new(application)
  new_item_window.present
end

让我们看看我们做了什么。启动应用程序并单击 **添加新项目** 按钮。哒哒！

图片来源：

opensource.com

但是当我们按下按钮时，什么也没有发生。让我们修复它。

首先，我们将绑定 Todo::NewItemWindow 类中的 UI 组件。

将 init 方法更改为此

def init
  # Set the template from the resources binary
  set_template resource: '/com/iridakos/gtk-todo/ui/new_item_window.ui'

  # Bind the window's widgets
  bind_template_child 'id_value_label'
  bind_template_child 'title_text_entry'
  bind_template_child 'notes_text_view'
  bind_template_child 'priority_combo_box'
  bind_template_child 'cancel_button'
  bind_template_child 'save_button'
end

此窗口将在创建或编辑 ToDo 项目时显示，因此 new_item_window 命名不是很有效。我们稍后会重构它。

现在，我们将更新窗口的 initialize 方法，以要求一个额外的参数，用于要创建或编辑的 Todo::Item。然后我们可以设置更有意义的窗口标题并更改子组件以反映当前项目。

我们将 initialize 方法更改为此

def initialize(application, item)
  super application: application
  set_title "ToDo item #{item.id} - #{item.is_new? ? 'Create' : 'Edit' } Mode"

  id_value_label.text = item.id
  title_text_entry.text = item.title if item.title
  notes_text_view.buffer.text = item.notes if item.notes

  # Configure the combo box
  model = Gtk::ListStore.new(String)
  Todo::Item::PRIORITIES.each do |priority|
    iterator = model.append
    iterator[0] = priority
  end

  priority_combo_box.model = model
  renderer = Gtk::CellRendererText.new
  priority_combo_box.pack_start(renderer, true)
  priority_combo_box.set_attributes(renderer, "text" => 0)

  priority_combo_box.set_active(Todo::Item::PRIORITIES.index(item.priority)) if item.priority
end

然后我们将在 application/models/item.rb 文件中的 PROPERTIES 常量下方添加常量 PRIORITIES

PRIORITIES = ['high', 'medium', 'normal', 'low'].freeze

我们在这里做了什么？

• 我们将窗口的标题设置为一个字符串，其中包含当前项目的 ID 和模式（取决于项目是正在创建还是正在编辑）。
• 我们将 id_value_label 文本设置为显示当前项目的 ID。
• 我们将 title_text_entry 文本设置为显示当前项目的标题。
• 我们将 notes_text_view 文本设置为显示当前项目的备注。
• 我们为 priority_combo_box 创建了一个模型，其条目将只有一个 String 值。乍一看，Gtk::ListStore 模型可能看起来有点令人困惑。它是这样工作的。
  • 假设我们想在组合框中显示国家代码及其各自国家名称的列表。
  • 我们将创建一个 Gtk::ListStore，定义其条目将包含两个字符串值：一个用于国家代码，一个用于国家名称。因此，我们将 ListStore 初始化为： 
    

    model = Gtk::ListStore.new(String, String)

  • 要使用数据填充模型，我们将执行以下操作（确保您不要错过代码片段中的注释）： 
    

    [['gr', 'Greece'], ['jp','Japan'], ['nl', 'Netherlands']].each do |country_pair|
      entry = model.append
      # Each entry has two string positions since that's how we initialized the Gtk::ListStore
      # Store the country code in position 0
      entry[0] = country_pair[0]
      # Store the country name in position 1
      entry[1] = country_pair[1]
    end

  • 我们还配置了组合框以渲染两个文本列/单元格（再次，请确保您不要错过代码片段中的注释）： 
    

    country_code_renderer = Gtk::CellRendererText.new
    # Add the first renderer
    combo.pack_start(country_code_renderer, true)
    # Use the value in index 0 of each model entry a.k.a. the country code
    combo.set_attributes(country_code_renderer, 'text' => 0)
    
    country_name_renderer = Gtk::CellRendererText.new
    # Add the second renderer
    combo.pack_start(country_name_renderer, true)
    # Use the value in index 1 of each model entry a.k.a. the country name
    combo.set_attributes(country_name_renderer, 'text' => 1)

  • 我希望这让它更清楚一点。
• 我们在组合框中添加了一个简单的文本渲染器，并指示它显示每个模型条目的唯一值（又名位置 0）。想象一下，我们的模型类似于 [['high'],['medium'],['normal'],['low']]，而 0 是每个子数组的第一个元素。我现在将停止模型-组合框-文本渲染器说明……

配置用户数据路径

请记住，在初始化新的 Todo::Item（而不是现有的）时，我们必须定义一个 :user_data_path，它将在其中保存。我们将在应用程序启动时解析此路径，并使其可从所有组件访问。

我们所要做的就是检查 .gtk-todo-tutorial 路径是否存在于用户的主目录 ~ 中。如果不存在，我们将创建它。然后我们将其设置为应用程序的实例变量。所有组件都可以访问应用程序实例。因此，所有组件都可以访问此用户路径变量。

将 application/application.rb 文件更改为此

module ToDo
  class Application < Gtk::Application
    attr_reader :user_data_path

    def initialize
      super 'com.iridakos.gtk-todo', Gio::ApplicationFlags::FLAGS_NONE

      @user_data_path = File.expand_path('~/.gtk-todo-tutorial')
      unless File.directory?(@user_data_path)
        puts "First run. Creating user's application path: #{@user_data_path}"
        FileUtils.mkdir_p(@user_data_path)
      end

      signal_connect :activate do |application|
        window = Todo::ApplicationWindow.new(application)
        window.present
      end
    end
  end
end

在我们测试到目前为止所做的工作之前，我们需要做的最后一件事是在单击 add_new_item_button 时实例化 Todo::NewItemWindow，以符合我们所做的更改。换句话说，将 application_window.rb 中的代码更改为此

add_new_item_button.signal_connect 'clicked' do |button|
  new_item_window = NewItemWindow.new(application, Todo::Item.new(user_data_path: application.user_data_path))
  new_item_window.present
end

启动应用程序并单击 **添加新项目** 按钮。哒哒！（请注意标题中的 *- 创建模式* 部分）。

图片来源：

opensource.com

取消项目创建/更新

要在用户单击 cancel_button 时关闭 Todo::NewItemWindow 窗口，我们只需将其添加到窗口的 initialize 方法中

cancel_button.signal_connect 'clicked' do |button|
  close
end

close 是 Gtk::Window 类的一个实例方法，用于关闭窗口。

保存项目

保存项目涉及两个步骤

• 根据组件的值更新项目的属性。
• 在 Todo::Item 实例上调用 save! 方法。

同样，我们的代码将放在 Todo::NewItemWindow 的 initialize 方法中

save_button.signal_connect 'clicked' do |button|
  item.title = title_text_entry.text
  item.notes = notes_text_view.buffer.text
  item.priority = priority_combo_box.active_iter.get_value(0) if priority_combo_box.active_iter
  item.save!
  close
end

再次，在保存项目后窗口关闭。

让我们试一试。

图片来源：

opensource.com

现在，通过按“保存”并导航到我们的 ~/.gtk-todo-tutorial 文件夹，我们应该看到一个文件。我的文件包含以下内容

{
	"id": "3d635839-66d0-4ce6-af31-e81b47b3e585",
	"title": "Optimize the priorities model creation",
	"notes": "It doesn't have to be initialized upon each window creation.",
	"priority": "high",
	"filename": "/home/iridakos/.gtk-todo-tutorial/3d635839-66d0-4ce6-af31-e81b47b3e585.json",
	"creation_datetime": "2018-01-25 18:09:51 +0200"
}

别忘了也试试“取消”按钮。

查看 ToDo 项目

Todo::ApplicationWindow 仅包含一个按钮。是时候改变一下了。

我们希望窗口顶部有添加新项目，下方有一个列表，其中包含我们所有的待办事项。我们将在设计中添加一个 Gtk::ListBox，它可以包含任意数量的行。

更新应用程序窗口

• 在 Glade 中打开 resources/ui/application_window.ui 文件。
• 如果我们直接从“Widget（控件）”部分将 List Box（列表框） 控件拖到窗口上，则不会发生任何事情。 这是正常的。首先，我们必须将窗口分成两部分：一部分用于按钮，一部分用于列表框。请耐心跟随。
• 在“Hierarchy（层级）”部分右键单击 new_item_window，然后选择 Add parent > Box（添加父项 > Box）。
• 在弹出的窗口中，将项目数设置为 2。
• box 的方向已经是垂直的，所以我们保持这样即可。

图片来源：

opensource.com

• 现在，拖动一个 List Box（列表框） 并将其放置在先前添加的 box 的空白区域。
• 将其 ID 属性设置为 todo_items_list_box。
• 将其 Selection mode（选择模式） 设置为 None（无），因为我们不提供此功能。

图片来源：

opensource.com

设计待办事项列表框行

我们在上一步中创建的列表框的每一行都将比文本行更复杂。每一行都将包含允许用户展开项目注释以及删除或编辑项目的控件。

• 在 Glade 中创建一个新项目，就像我们为 new_item_window.ui 所做的那样。将其保存在 resources/ui/todo_item_list_box_row.ui 下。
• 不幸的是（至少在我的 Glade 版本中），“Widget（控件）”部分中没有 List Box Row（列表框行）控件。因此，我们将以一种有点 hack 的方式将其作为项目的顶层控件添加。
• 从“Widget（控件）”部分将 List Box（列表框） 拖到“Design area（设计区域）”。
• 在“Hierarchy（层级）”部分中，右键单击 List Box（列表框） 并选择 Add Row（添加行）。

图片来源：

opensource.com

• 在“Hierarchy（层级）”部分中，右键单击新添加的嵌套在 List Box（列表框） 下的 List Box Row（列表框行），然后选择 Remove parent（移除父项）。 就在那里！List Box Row（列表框行） 现在是项目的顶层控件。

图片来源：

opensource.com

• 检查控件的 Composite（复合） 属性，并将其名称设置为 TodoItemListBoxRow。
• 从“Widget（控件）”部分将 Box 拖到 List Box Row（列表框行） 内的“Design area（设计区域）”。
• 在弹出的窗口中将其项目数设置为 2。
• 将其 ID 属性设置为 main_box。

图片来源：

opensource.com

• 从“Widget（控件）”部分将另一个 Box 拖到先前添加的 box 的第一行。
• 在弹出的窗口中将其项目数设置为 2。
• 将其 ID 属性设置为 todo_item_top_box。
• 将其 Orientation（方向） 属性设置为 Horizontal（水平）。
• 将其 Spacing（间距）（General（常规） 选项卡）属性设置为 10。

图片来源：

opensource.com

• 从“Widget（控件）”部分将 Label（标签） 拖到 todo_item_top_box 的第一列。
• 将其 ID 属性设置为 todo_item_title_label。
• 将其 Alignment and Padding > Alignment > Horizontal（对齐和填充 > 对齐 > 水平） 属性设置为 0.00。
• 在“Properties（属性）”部分的 Common（通用） 选项卡中，选中 Widget Spacing > Expand > Horizontal（控件间距 > 展开 > 水平） 复选框，并打开旁边的开关，以便标签将扩展到可用空间。

图片来源：

opensource.com

• 从“Widget（控件）”部分将 Button（按钮） 拖到 todo_item_top_box 的第二列。
• 将其 ID 属性设置为 details_button。
• 选中 Button Content > Label with optional image（按钮内容 > 带可选图像的标签） 单选按钮，然后输入 ... （三个点）。

图片来源：

opensource.com

• 从“Widget（控件）”部分将 Revealer（显示器） 控件拖到 main_box 的第二行。
• 在 General（常规） 选项卡中关闭 Reveal Child（显示子项） 开关。
• 将其 ID 属性设置为 todo_item_details_revealer。
• 将其 Transition type（过渡类型） 属性设置为 Slide Down（向下滑动）。

图片来源：

opensource.com

• 从“Widget（控件）”部分将 Box 拖到显示空间。
• 在弹出的窗口中将其项目数设置为 2。
• 将其 ID 属性设置为 details_box。
• 在 Common（通用） 选项卡中，将其 Widget Spacing > Margins > Top（控件间距 > 边距 > 顶部） 属性设置为 10。

图片来源：

opensource.com

• 从“Widget（控件）”部分将 Button Box（按钮框） 拖到 details_box 的第一行。
• 将其 ID 属性设置为 todo_item_action_box。
• 将其 Layout style（布局样式） 属性设置为 expand（展开）。

图片来源：

opensource.com

• 将 Button（按钮） 控件拖到 todo_item_action_box 的第一列和第二列。
• 分别将其 ID 属性设置为 delete_button 和 edit_button。
• 分别将其 Button Content > Label with optional image（按钮内容 > 带可选图像的标签） 属性设置为 Delete（删除） 和 Edit（编辑）。

图片来源：

opensource.com

• 从“Widget（控件）”部分将 Viewport（视口） 控件拖到 details_box 的第二行。
• 将其 ID 属性设置为 todo_action_notes_viewport。
• 从“Widget（控件）”部分将 Text View（文本视图） 控件拖到我们刚刚添加的 todo_action_notes_viewport 中。
• 将其 ID 设置为 todo_item_notes_text_view。
• 在“Properties（属性）”部分的 General（常规） 选项卡中，取消选中其 Editable（可编辑） 属性。

图片来源：

opensource.com

创建待办事项列表框行类

现在我们将创建类来反映我们刚刚创建的列表框行的 UI。

首先，我们必须更新我们的 GResource 描述文件，以包含新创建的设计。按如下方式更改 resources/gresources.xml 文件

<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/com/iridakos/gtk-todo">
    <file preprocess="xml-stripblanks">ui/application_window.ui</file>
    <file preprocess="xml-stripblanks">ui/new_item_window.ui</file>
    <file preprocess="xml-stripblanks">ui/todo_item_list_box_row.ui</file>
  </gresource>
</gresources>

在 application/ui 文件夹中创建一个名为 item_list_box_row.rb 的文件，并添加以下内容

module Todo
  class ItemListBoxRow < Gtk::ListBoxRow
    type_register

    class << self
      def init
        set_template resource: '/com/iridakos/gtk-todo/ui/todo_item_list_box_row.ui'
      end
    end

    def initialize(item)
      super()
    end
  end
end

目前我们不会绑定任何子项。

启动应用程序时，我们必须在 :user_data_path 中搜索文件，并且我们必须为每个文件创建一个 Todo::Item 实例。对于每个实例，我们还必须向 Todo::ApplicationWindow 的 todo_items_list_box 列表框添加一个新的 Todo::ItemListBoxRow。一次做一件事。

首先，让我们在 Todo::ApplicationWindow 类中绑定 todo_items_list_box。按如下方式更改 init 方法

def init
  # Set the template from the resources binary
  set_template resource: '/com/iridakos/gtk-todo/ui/application_window.ui'

  bind_template_child 'add_new_item_button'
  bind_template_child 'todo_items_list_box'
end

接下来，我们将在同一个类中添加一个实例方法，该方法将负责在相关的列表框中加载待办事项列表项。在 Todo::ApplicationWindow 中添加以下代码

def load_todo_items
  todo_items_list_box.children.each { |child| todo_items_list_box.remove child }

  json_files = Dir[File.join(File.expand_path(application.user_data_path), '*.json')]
  items = json_files.map{ |filename| Todo::Item.new(filename: filename) }

  items.each do |item|
    todo_items_list_box.add Todo::ItemListBoxRow.new(item)
  end
end

然后，我们将在 initialize 方法的末尾调用此方法

def initialize(application)
  super application: application

  set_title 'GTK+ Simple ToDo'

  add_new_item_button.signal_connect 'clicked' do |button|
    new_item_window = NewItemWindow.new(application, Todo::Item.new(user_data_path: application.user_data_path))
    new_item_window.present
  end

  load_todo_items
end

注意： 我们必须首先清空列表框当前的子行，然后再重新填充它。这样，我们将在通过 Todo::NewItemWindow 的 save_button 的 signal_connect 保存 Todo::Item 后调用此方法，并且父应用程序窗口将被重新加载！这是更新后的代码（在 application/ui/new_item_window.rb 中）

save_button.signal_connect 'clicked' do |button|
  item.title = title_text_entry.text
  item.notes = notes_text_view.buffer.text
  item.priority = priority_combo_box.active_iter.get_value(0) if priority_combo_box.active_iter
  item.save!

  close

  # Locate the application window
  application_window = application.windows.find { |w| w.is_a? Todo::ApplicationWindow }
  application_window.load_todo_items
end

之前，我们使用此代码

json_files = Dir[File.join(File.expand_path(application.user_data_path), '*.json')]

在应用程序用户数据路径中查找带有 JSON 扩展名的所有文件的名称。

让我们看看我们创建了什么。启动应用程序并尝试添加一个新的待办事项。按下 Save（保存） 按钮后，您应该看到父 Todo::ApplicationWindow 自动更新了新项目！

图片来源：

opensource.com

剩下要做的是完成 Todo::ItemListBoxRow 的功能。

首先，我们将绑定控件。按如下方式更改 Todo::ItemListBoxRow 类的 init 方法

def init
  set_template resource: '/com/iridakos/gtk-todo/ui/todo_item_list_box_row.ui'

  bind_template_child 'details_button'
  bind_template_child 'todo_item_title_label'
  bind_template_child 'todo_item_details_revealer'
  bind_template_child 'todo_item_notes_text_view'
  bind_template_child 'delete_button'
  bind_template_child 'edit_button'
end

然后，我们将根据每一项的项目设置控件。

def initialize(item)
  super()

  todo_item_title_label.text = item.title || ''

  todo_item_notes_text_view.buffer.text = item.notes

  details_button.signal_connect 'clicked' do
    todo_item_details_revealer.set_reveal_child !todo_item_details_revealer.reveal_child?
  end

  delete_button.signal_connect 'clicked' do
    item.delete!

    # Locate the application window
    application_window = application.windows.find { |w| w.is_a? Todo::ApplicationWindow }
    application_window.load_todo_items
  end

  edit_button.signal_connect 'clicked' do
    new_item_window = NewItemWindow.new(application, item)
    new_item_window.present
  end
end

def application
  parent = self.parent
  parent = parent.parent while !parent.is_a? Gtk::Window
  parent.application
end

• 如您所见，当单击 details_button 时，我们指示 todo_item_details_revealer 切换其内容的可见性。
• 删除项目后，我们找到应用程序的 Todo::ApplicationWindow 以调用其 load_todo_items，就像我们在保存项目后所做的那样。
• 当单击编辑按钮时，我们创建一个新的 Todo::NewItemWindow 实例，并将项目作为当前项目传递。效果很好！
• 最后，为了到达列表框行的应用程序父项，我们定义了一个简单的实例方法 application，该方法遍历控件的父项，直到它到达可以从中获取应用程序对象的窗口。

保存并运行应用程序。就在那里！

图片来源：

opensource.com

这是一个非常长的教程，即使有很多我们尚未涵盖的项目，我认为我们最好在此处结束。

长文，猫咪照片。

图片来源：

opensource.com

实用链接

• 本教程的代码
• 一组用于从 Ruby 使用 GNOME-2.x 库的绑定
• 基于官方 C 版本的 Ruby Gtk3 教程
• GTK+ 3 参考手册

这最初发布在 Lazarus Lazaridis 的博客 iridakos.com 上，并经许可重新发布。