【GTK】常用库函数

1、创建GtkApplication实例

GtkApplication*
gtk_application_new (
  const char* application_id,
  GApplicationFlags flags
)

创建GtkApplication实例。
调用该函数创建GtkApplication实例，无需手动调用gtk_init()函数进行初始化。
gtk_init函数会在GApplication::startup信号的回调函数中调用。命令行参数不会传递给gtk_init函数。
如果application_id不为NULL，那么应用id必需是合法的，参阅g_application_id_is_valid函数。
如果application_id是NULL，那么有些特性将会被禁用（如应用唯一特性）。

参数：

• application_id：应用id，可以为NULL；
• flags：定义应用行为。

Name	Description
G_APPLICATION_DEFAULT_FLAGS	默认行为
G_APPLICATION_IS_SERVICE	以Service的方式运行应用，如果已有相同的service正在运行，那么将会注册失败，并且应用程序最多等待初始激活消息10秒
G_APPLICATION_IS_LAUNCHER	主实例不要使用该flag
G_APPLICATION_HANDLES_OPEN	应用处理打开文件操作（在主实例中）。这个flag只会影响local_command_line的默认实现，不会影响G_APPLICATION_HANDLES_COMMAND_LINE
G_APPLICATION_HANDLES_COMMAND_LINE	应用处理命令行参数（在主实例中）。注意该flag只会影响local_command_line的默认实现
G_APPLICATION_SEND_ENVIRONMENT	将启动进程的环境发送到主实例。如果你的应用想要根据不同的环境变量进行不同的操作，就需要设置这个标志。例如，编辑器在编辑git提交消息时可能期望使用GIT_COMMITTER_NAME环境变量。该环境可通过g_application_command_line_getenv()提供给GApplication::command-line信号处理程序。
G_APPLICATION_NON_UNIQUE	即使给出了应用程序ID，也不要尝试进行任何典型的单实例应用程序协商。应用程序既不尝试成为应用程序ID的所有者，也不检查现有所有者是否已经存在。一切都发生在本地进程中。
G_APPLICATION_CAN_OVERRIDE_APP_ID	允许用户通过命令行重写application id，命令行使用--gapplication-app-id参数设置app id
G_APPLICATION_ALLOW_REPLACEMENT	允许另一个实例接管总线名称。
G_APPLICATION_REPLACE	使用当前实例替换指定实例，命令行通过--gapplication-replace进行替换

2、信号回调函数

#define g_signal_connect (
  instance,
  detailed_signal,
  c_handler,
  data
)

为instance对象的detailed_signal信号关联回调函数c_hanlder，data是需要传入回调函数的用户数据。c_handler会在该信号的默认回调函数之前调用，当该信号的所有回调函数都被调用之后，g_signal_emit函数才会返回。

参数：

• instance：关联信号的实例
• detailed_signal："signal-name::detail"格式的字符串
• c_handler：信号回调函数
• data：传入回调函数的用户数据

3、运行应用实例

int
g_application_run (
  GApplication* application,
  int argc,
  char** argv
)

该函数应该在main函数中调用，同时它的返回值应该作为main函数的返回值。如果不想处理命令行，可以将argv置为NULL，同时argc置为0.

GApplication将尝试解析命令行参数。您可以通过g_application_add_main_option_entries()将命令行标志添加到可识别选项列表中。在此之后，发出GApplication::handle-local-options信号，应用程序可以从中检查其GOptionEntrys的值。

GApplication::handle-local-options是处理选项的好地方，比如--version，在这里需要本地进程的立即回复(而不是与已经运行的实例通信)。GApplication::handle-local-options处理程序可以通过返回一个非负值来停止进一步的处理，该值随后成为进程的退出状态。

接下来发生的事情取决于标志:如果指定了G_APPLICATION_HANDLES_COMMAND_LINE，则其余的命令行参数被发送到主实例，并激活GApplication::command-line信号。否则，将假定其余命令行参数为文件列表。如果没有列出文件，则通过GApplication::activate信号激活应用程序。如果有一个或多个文件，并且指定了G_APPLICATION_HANDLES_OPEN，那么这些文件将通过GApplication::open信号打开。

如果在完成上述操作后，应用程序的使用计数为零，则立即返回退出状态。如果使用计数不为零，则迭代默认的主上下文，直到使用计数降为零，此时返回0。

如果设置了G_APPLICATION_IS_SERVICE标志，那么在等待激活消息到达时，服务将运行最多10秒，使用计数为零。在此之后，如果使用计数降为零，则应用程序将立即退出，除非g_application_set_inactivity_timeout()正在使用。

这个函数将prgname(g_set_prgname())设置为argv[0]的basename。

与g_main_loop_run()非常相似，该函数将在应用程序运行期间获取主上下文。

从2.40开始，没有显式标记为服务或启动程序的应用程序(即:G_APPLICATION_IS_SERVICE或G_APPLICATION_IS_LAUNCHER都没有作为标志给出)将检查(从local_command_line的默认处理程序)是否在命令行中给出了“-gapplication-service”。如果出现此标志，则中断正常的命令行处理，并设置G_APPLICATION_IS_SERVICE标志。这提供了一个“折衷”的解决方案，即直接从命令行运行应用程序将以正常方式调用它(这对调试很有用)，同时仍然允许应用程序在服务模式下被D-Bus激活。D-Bus服务文件应该以“-gapplication-service”作为唯一的命令行参数来调用可执行文件。这种方法适合大多数图形化应用程序使用，但不应该用于像编辑器这样需要精确控制通过命令行调用的进程何时退出以及退出状态的应用程序。

4、转换GCallback

#define G_CALLBACK (
  f
)

将函数指针转为GCallback.

5、转换GApplication

#define G_APPLICATION(inst)

检查inst是不是GApplication的实例，如果不是则返回告警，如果是则将inst转换为GApplication。

6、减少对象引用计数

void
g_object_unref (
  GObject* object
)

减少object的引用计数，如果引用计数降为0，则对象会被释放。如果这个GObject*指针还会被使用，建议指针置为NULL，防止访问野指针，导致程序崩溃，建议使用g_clear_object代替。

7、创建窗口

GtkWidget*
gtk_application_window_new (
  GtkApplication* application
)

创建GtkApplicationWindow实例。

8、转换GtkWindow

#define GTK_WINDOW(obj)

如果obj是GtkWindow的实例，则将obj转为GtkWindow，否则返回告警。

9、设置窗口标题

void
gtk_window_set_title (
  GtkWindow* window,
  const char* title
)

设置窗口标题，可以设置为NULL，表示为空字符串。

10、设置窗口默认大小

void
gtk_window_set_default_size (
  GtkWindow* window,
  int width,
  int height
)

窗口的默认大小是在没有其他约束的情况下使用的大小。如果窗口没有被强制设置大小，那么就可以重新调整窗口大小。
窗口的尺寸存在最小值，如果默认尺寸小于最小值，那么默认值将被忽略。
将默认大小设置为<= 0将导致它被忽略，而使用自然大小。当窗口显示“重置”到其初始大小时，可以这样做。
与gtk_widget_set_size_request()不同，gtk_widget_set_size_request()为widget设置大小，从而阻止用户缩小窗口，而gtk_window_set_default_size只设置初始大小，就像用户自己调整了窗口大小一样。用户仍然可以像往常一样再次缩小窗口。将默认大小设置为-1意味着使用“自然”默认大小。
如果想要回复窗口默认大小，需要使用gtk_window_get_default_size函数返回的大小，如果直接设置，可能会导致窗口增大或缩小。

参数：

• width：宽度，单位像素
• height：高度，单位像素

11、创建按钮

GtkWidget*
gtk_button_new_with_label (
  const char* label
)

创建GtkButton，同时带一个标签GtkLabel。

12、为窗口设置子部件

void
gtk_window_set_child (
  GtkWindow* window,
  GtkWidget* child
)

为窗口设置子部件。

13、显示窗口

void
gtk_window_present (
  GtkWindow* window
)

显示窗口。
这可能意味着提高窗口的堆叠顺序，将其最小化，将其移动到当前桌面和/或给它键盘焦点(可能取决于用户的平台，窗口管理器和首选项)。
如果窗口是隐藏的，该函数也会让窗口显示出来。

14、显示部件

已被启用，使用gtk_widget_set_visible或者gtk_window_present代替

void
gtk_widget_show (
  GtkWidget* widget
)

标记需要显示的部件，没有被标记的部件不会显示。如果想要显示所有部件，使用gtk_widget_show_all函数。如果想要显示部件，它的父容器必须是可见的。

15、创建GtkBox

GtkWidget*
gtk_box_new (
  GtkOrientation orientation,
  gint spacing
)

创建GtkBox。

参数：

• orientation：GtkBox中部件放置的方向
• spacing： GtkBox中子部件之间的间隔（单位：像素）

16、设置横向布局

void
gtk_widget_set_halign (
  GtkWidget* widget,
  GtkAlign align
)

设置widget的水平对齐方式。
align取值如下：

Name	Description
GTK_ALIGN_FILL	拉伸填满横向空间，如果无法拉伸则居中
GTK_ALIGN_START	从左到右或从上到下放置组件
GTK_ALIGN_END	从右到左或从下到上放置组件
GTK_ALIGN_CENTER	居中放置组件
GTK_ALIGN_BASELINE	根据基线对齐部件

17、设置纵向布局

void
gtk_widget_set_valign (
  GtkWidget* widget,
  GtkAlign align
)

align取值参考上一个函数说明。

18、关联信号的回调函数（调换instance和data的位置）

#define g_signal_connect_swapped (
  instance,
  detailed_signal,
  c_handler,
  data
)

这个宏和g_signal_connect的区别在于：调用c_handler回调函数时，会调换instance和data的位置。当只想操作data，而不操作instance时，就可以使用这个宏，可以减少多余代码。
例如：

g_signal_connect_swapped (button, "clicked",
                          (GCallback) gtk_widget_hide, other_widget);

如果使用g_signal_connect宏：

static void
button_clicked_cb (GtkButton *button, GtkWidget *other_widget)
{
    gtk_widget_hide (other_widget);
}

...

g_signal_connect (button, "clicked",
                  (GCallback) button_clicked_cb, other_widget);

19、向GtkBox中添加子部件

void
gtk_box_append (
  GtkBox* box,
  GtkWidget* child
)

向GtkBox中添加子组件。