【c/python】GtkGrid

一、GtkGrid

GtkGrid 是 GTK (GIMP Toolkit) 中的一个基础容器构件（widget），它可以用来安排其他构件在一个灵活的多行多列的网格中。每个加入网格的构件都可以占据一个或多个行和列。由于 GtkGrid 提供了在二维空间中安排构件的方式，它被广泛用于创建复杂的用户界面。

在 GTK 3 和 GTK 4 中，`GtkGrid` 的使用方法有所不同，下面将给出一个简单的例程，展示如何在 GTK 3 中使用 GtkGrid。如果 GTK 版本是 GTK 4，则代码中的某些部分可能需要做出调整。

首先，确保已经安装了 GTK 开发库。在大多数基于 Debian 的系统上（如 Ubuntu），可以使用以下命令安装：

sudo apt-get install libgtk-3-dev

以下是一个简单的 GTK 3 程序，该程序创建了一个包含几个按钮的窗口，并使用 GtkGrid 来组织这些按钮：

#include <gtk/gtk.h>

int main(int argc, char *argv[]) {
    gtk_init(&argc, &argv);

    GtkWidget *window;
    GtkWidget *grid;
    GtkWidget *button;

    // 创建一个新的窗口
    window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
    gtk_window_set_title(GTK_WINDOW(window), "GtkGrid Example");
    gtk_window_set_default_size(GTK_WINDOW(window), 300, 200);
    g_signal_connect(window, "destroy", G_CALLBACK(gtk_main_quit), NULL);

    // 创建一个 GtkGrid
    grid = gtk_grid_new();
    gtk_container_add(GTK_CONTAINER(window), grid);

    // 创建并添加第一个按钮
    button = gtk_button_new_with_label("Button 1");
    gtk_grid_attach(GTK_GRID(grid), button, 0, 0, 1, 1); // 放置在网格的 (0, 0)

    // 创建并添加第二个按钮
    button = gtk_button_new_with_label("Button 2");
    gtk_grid_attach(GTK_GRID(grid), button, 1, 0, 1, 1); // 放置在网格的 (1, 0)

    // 创建并添加第三个按钮
    button = gtk_button_new_with_label("Button 3");
    // 放置在网格的 (1, 1)，并跨越2列
    gtk_grid_attach(GTK_GRID(grid), button, 0, 1, 2, 1);

    // 显示所有的构件
    gtk_widget_show_all(window);

    // 进入 GTK 主循环
    gtk_main();

    return 0;
}

这段代码完成以下任务：

1. 初始化 GTK 库。
2. 创建一个新的 GTK 窗口，并为其设置标题和默认大小。
3. 连接窗口的 "destroy" 信号到 gtk_main_quit 函数，它将允许在关闭窗口时退出 GTK 主循环。
4. 创建 GtkGrid 并将其添加到窗口中。
5. 创建三个按钮构件，并使用 gtk_grid_attach() 函数将它们放置在合适的位置和跨度中。其中 gtk_grid_attach() 函数的参数分别代表网格、要放置的构件、构件的左上角列和行的坐标，以及构件横向和纵向上占据的列和行数。
6. 通过 gtk_widget_show_all() 展示窗口和其中的所有构件。

7. 进入 GTK 的主循环。

为了编译这个程序，可能需要使用 pkg-config 来获取正确的 GTK 编译和链接标志。一个典型的编译命令如下：

gcc `pkg-config --cflags gtk+-3.0` -o gtk_grid_example gtk_grid_example.c `pkg-config --libs gtk+-3.0`

这将产生一个可执行文件 gtk_grid_example。运行该文件将弹出一个带有布局按钮的窗口。请注意，上面的代码示例仅适用于 GTK 3；GTK 4 中的相应函数可能会有所不同。

二、GtkGrid和GtkBox有什么不同？

​​​​​​​GtkGrid 和 GtkBox 都是 GTK 中用于布局的容器构件，但它们各自有不同的特性和用途。

GtkBox

- GtkBox 是一个一维的布局容器，可以按照水平或垂直方向排列子构件。
- 子构件会按照它们被添加的顺序依次排列。
- 可以为子构件设置填充和扩展属性，但所有的子构件仅能在一个维度（水平或垂直）上进行布局。

- 适合用于简单的布局，如果需要在两个维度上进行布局，则可能需要嵌套使用多个 GtkBox 构件。

例如，一个垂直的 GtkBox 可能包含几个水平的 GtkBox 来实现一个网格布局，但这样会使结构变得更为复杂。

GtkGrid

- GtkGrid 是一个二维的布局容器，它提供了一种在多行多列网格中排列子构件的方式。
- 子构件可以占据多行或多列，为设计复杂的布局提供了更大的灵活性。
- GtkGrid 提供更精细的对齐和分布控制，这使得它更适合实现复杂的用户界面设计。

- 使用 GtkGrid 可以避免嵌套容器的需要，以更直接的方式创建布局。

简言之，`GtkGrid` 提供了比 GtkBox 更复杂和灵活的布局方案。对于需要在两个维度上对构件进行布局的情况，特别是当需要构件跨行或列展示时，`GtkGrid` 是更好的选择。然而，如果只需要在一维上对构件进行简单的排列，那么 GtkBox 是一个更简单和轻量级的选择。

从 GTK 3 开始，`GtkGrid` 通常被推荐用来替代 GtkBox 进行复杂布局的设计，因为它可以减少需要嵌套使用容器的情况，从而使界面的层次结构更加清晰。

三、GtkGrid的python例程

要在Python中使用`GtkGrid`，需要先确保有一个可用的Python GTK+ 3绑定，通常称为`PyGObject`。在大多数基于Debian的系统上，可以通过以下命令来安装：

sudo apt-get install python3-gi python3-gi-cairo gir1.2-gtk-3.0

下面是一个简单的Python例程，这个例程使用`GtkGrid`来创建一个窗口，其中包含一个按钮位于窗口的右下角：

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class GridWindow(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self, title="Grid Example")

        grid = Gtk.Grid()
        self.add(grid)

        # 创建一个按钮，并设置适当的边距
        button = Gtk.Button(label="Right Bottom Button")
        # 这里设置边距是为了让按钮远离窗口的边界
        button.set_margin_right(10)
        button.set_margin_bottom(10)
        
        # 将按钮添加至网格的右下角
        # Gtk.Grid.attach_next_to() 方法可以用于放置构件，
        # 但我们这里使用 Gtk.Grid.attach() 是因为我们希望按钮在右下角，占据一个单元格
        # 我们使用负的左边距和顶边距来确保按钮在右下角
        grid.attach(button, 0, 0, 1, 1)
        grid.set_halign(Gtk.Align.END)
        grid.set_valign(Gtk.Align.END)

        # 连接窗口的 "destroy" 事件到 Gtk.main_quit 函数
        self.connect("destroy", Gtk.main_quit)

# 创建一个 GridWindow 的实例，并显示它
window = GridWindow()
window.show_all()
Gtk.main()

以上脚本主要做了以下几件事情：

1. 导入 gi.repository 的 GTK+ 3 组件。
2. 定义一个`GridWindow`类，该类继承自 Gtk.Window 类，并在初始化方法中设置窗口和布局。
3. 创建一个 Gtk.Grid 容器和一个按钮构件。
4. 将按钮置于网格的右下角。借助 grid 的 set_halign 和 set_valign 方法，并设置为 Gtk.Align.END，可以保证网格本身对齐到窗口的右下角。

5. 最后，连接了窗口的 "destroy" 事件到 GTK 的主循环退出函数 Gtk.main_quit，并显示了所有构件。

请注意`set_margin_right`和`set_margin_bottom`可能在系统的PyGObject版本中不起作用（这取决于PyGObject的版本）。如果是这种情况，应当使用`set_margin_end`和`set_margin_bottom`方法替代。

要运行此脚本，请将其保存为一个 .py 文件，并使用Python 3运行它：

python3 your_script.py

执行脚本后，会出现一个窗口，窗口的右下角会有一个按钮。

这段代码，运行时可能提示：

gtk_grid_example.py:16: DeprecationWarning: Gtk.Widget.set_margin_right is deprecated
  button.set_margin_right(10)

GTK 所发出的 DeprecationWarning 表明，正在使用的方法已经被废弃，也就是说，在未来的 GTK 版本中，此方法可能会被移除。这种警告常常出现当库的开发者希望开发者迁移到新的方法或接口时。

对于遇到的具体情况，`Gtk.Widget.set_margin_right` 方法在 GTK 3.12 版本中被标记为废弃，并且在 GTK 3.14 版本中被移除。官方文档建议使用 set_margin_end 方法来替换 set_margin_right，因为后者不再是国际化的好选择。新的方法是基于文本方向敏感的边距设定，其中 "end" 表示在水平方向上的边距，当语言是从右到左的文字时，就变成了右边距，而对于从左到右的语言，则是左边距。

所有关于边距的方法都有四个替代选项：

- set_margin_start: 设置开始边（左边或右边，取决于文本方向）的边距。
- set_margin_end: 设置结束边（右边或左边，取决于文本方向）的边距。
- set_margin_top: 设置顶部的边距。

- set_margin_bottom: 设置底部的边距。

在代码中，可以这样更新来消除 DeprecationWarning 警告：

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class GridWindow(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self, title="Grid Example")

        grid = Gtk.Grid()
        self.add(grid)

        button = Gtk.Button(label="Right Bottom Button")
        button.set_margin_end(10)  # 使用 set_margin_end 替代 set_margin_right
        button.set_margin_bottom(10)

        grid.attach(button, 0, 0, 1, 1)
        grid.set_halign(Gtk.Align.END)
        grid.set_valign(Gtk.Align.END)

        self.connect("destroy", Gtk.main_quit)

window = GridWindow()
window.show_all()
Gtk.main()

请注意，更新代码后，对于 set_margin_end 方法，它设置的将是按钮的结束边的边距，而不是始终是右边的边距，它会根据应用内容的语言方向发生变化。如果应用面向国际用户，这是一个有利的修改，因为它将遵循用户的语言习惯（LTR或RTL）。如果确定只需要设置固定的边距（比如右边距），需要确保界面不会根据语言方向改变，或者使用其他方法来保证边距适用于界面设计。