GObject 参考手册:概念:GLib 动态类型系统:约定

There are a number of conventions users are expected to follow when creating new types which are to be exported in a header file:
当用户在头文件中创建新类型时,有一些规范用户需要注意:

  • Use the object_method pattern for function names: to invoke the method named foo on an instance of object type bar, call bar_foo.
  • 使用 object_method 的形式来定义函数名称:例如在一个 bar 类中定义一个名为 foo 的函数,则用 bar_foo。
  • Use prefixing to avoid namespace conflicts with other projects. If your library (or application) is named Maman, prefix all your function names with maman_. For example: maman_object_method.
  • 使用前缀来避免与其他工程的命名空间冲突。如果你的库(或应用程序)名为 Marman,那么所有的函数名称前缀 为maman_。举例:maman_object_method。
  • Create a macro named PREFIX_TYPE_OBJECT which always returns the GType for the associated object type. For an object of type Bar in a libray prefixed by maman, use: MAMAN_TYPE_BAR. It is common although not a convention to implement this macro using either a global static variable or a function named prefix_object_get_type. We will follow the function pattern wherever possible in this document.
  • 创建一个宏命为 PREFIX_OBJECT_TYPE 用来返回 GType 关联的对象类型。比如,Bar 这个类在一个以 maman 前缀的库中,则使用 MANMAN_BAR_TYPE。另有一个不成文的规定是,定义一个使用全局静态变或一个名为 prefix_object_get_type 的函数来实现这个宏。我们将在后面的章节中讨论这个函数。
  • Create a macro named PREFIX_OBJECT (obj) which returns a pointer of type PrefixObject. This macro is used to enforce static type safety by doing explicit casts wherever needed. It also enforces dynamic type safety by doing runtime checks. It is possible to disable the dynamic type checks in production builds (see building glib). For example, we would create MAMAN_BAR (obj) to keep the previous example.
  • 创建一个宏命名为 PREFIX_OBJECT(obj) 来返回一个指向 PrefixObject 类型的指针。这个宏用于必要时安全地强制转换一个静态类型。运行环境检查时,同样也是安全地执行动态类型。在处理过程中禁用动态类型检查是可行的。例如,我们可以创建 MAMAN_BAR(obj) 来保持先前的例子。
  • If the type is classed, create a macro named PREFIX_OBJECT_CLASS (klass). This macro is strictly equivalent to the previous casting macro: it does static casting with dynamic type checking of class structures. It is expected to return a pointer to a class structure of type PrefixObjectClass. Again, an example is: MAMAN_BAR_CLASS.
  • 如果类型是类化的,那么创建一个命令为 PREFIX_OBJECT_CLASS(klass)的宏。这个宏与前面那个是非常相似的:它以类结构的动态类型检查来进行静态转换,并返回一个指向 PrefixObjectClass 这个类型的类结构的指针。同样,例子为:MAMAN_BAR_CLASS。
  • Create a macro named PREFIX_IS_BAR (obj): this macro is expected to return a gboolean which indicates whether or not the input object instance pointer of type BAR.
  • 创建一个宏命名为 PREFIX_IS_BAR (obj):这个宏用于判断输入的对象实例是否是 BAR类 型的。
  • If the type is classed, create a macro named PREFIX_IS_OBJECT_CLASS (klass) which, as above, returns a boolean if the input class pointer is a pointer to a class of type OBJECT.
  • 如果类型是类化的,创建一个名为 PREFIX_IS_OBJECT_CLASS (klass) 的宏,与上面的类似,返回输入的类型指针是否是 OBJECT 类型。
  • If the type is classed, create a macro named PREFIX_OBJECT_GET_CLASS (obj) which returns the class pointer associated to an instance of a given type. This macro is used for static and dynamic type safety purposes (just like the previous casting macros).
  • 如果类型是类化的,创建一个名为 PREFIX_OBJECT_GET_CLASS ,返回一个实例所属的类的类型指针。这个宏因为安全的原因,被静态和动态类型所使用,就像上面的转换宏一样。

The implementation of these macros is pretty straightforward: a number of simple-to-use macros are provided in gtype.h. For the example we used above, we would write the following trivial code to declare the macros:
至于这些宏的实现是非常直观的:一些数量的简单使用的宏由 gtype.h 提供。针对上面我们兴趣的例子,我们写了下面的代码来声明这些宏:

#define MAMAN_TYPE_BAR                  (maman_bar_get_type ())
#define MAMAN_BAR(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
#define MAMAN_BAR_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
#define MAMAN_IS_BAR(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
#define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
#define MAMAN_BAR_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))

The following code shows how to implement the maman_bar_get_type function:
下面的代码实现了 maman_bar_get_type 这个函数:

GType maman_bar_get_type (void)
{
  static GType type = 0;
  if (type == 0) {
    static const GTypeInfo info = {
      /* You fill this structure. */
    };
    type = g_type_register_static (G_TYPE_OBJECT,
                                   "MamanBarType",
                                   &info, 0);
  }
  return type;
}

When having no special requirements you also can use the G_DEFINE_TYPE macro:
如果没有特别需要,你也可以使用 G_DEFINE_TYPE 宏:

G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)

One thought on “GObject 参考手册:概念:GLib 动态类型系统:约定”

  1. Pingback: URL

Leave a Reply

Your email address will not be published. Required fields are marked *