[GType] Conventions

from https://developer.gnome.org

원본 문서를 header/source 파일로 나누어서 보기 쉽게 정리해 보았습니다.

Header 파일

Header 파일을 작성해서 외부로 노출되는 새로운 type을 생성하고자 할 때, 아래의 간단한 코드가 사용됩니다.

#define VIEWER_TYPE_FILE viewer_file_get_type ()
G_DECLARE_FINAL_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)

이는 쉬운 코드 작성을 위해 제공되는 macro들을 이용한 것으로, 내부적인 구현은 다음의 표준을 따릅니다.

이름 표준

• Type 이름(object 이름 포함)은 ‘a–z’, ‘A–Z’ 또는 ‘_’로 시작하는 적어도 세개 이상의 문자를 사용.
• 함수 이름은 object_method 패턴을 사용: file이라는 이름의 object type의 객체가 제공하는 save라는 이름의 method를 호출하려면, file_save를 호출.
• 다른 프로젝트와의 namespace 충돌을 피하기 위해 prefix 사용: 라이브러리(또는 어플리케이션)의 이름이 Viewer인 경우, 모든 함수 이름을 viewer_로 prefixing. 예를 들어, viewer_object_method.

실제 header에 작성되는 code 표준

• PREFIX_TYPE_OBJECT macro를 해당 object type의 GType을 리턴해 주도록 작성: Viewer namespace의 File object type을 위해서는 VIEWER_TYPE_FILE 매크로를 작성. 이 매크로는 prefix_object_get_type 이름의 함수를 호출하도록 구성됨(e.g. viewer_file_get_type).
• G_DECLARE_FINAL_TYPE 또는 G_DECLARE_DERIVABLE_TYPE를 사용하여 아래의 다양한 표준 매크로들을 선언.
  • PREFIX_OBJECT (obj)
    • PrefixObject type의 pointer(instance structure pointer)를 리턴.
    • 이 매크로를 사용함으로써 필요한 곳에서의 명시적 캐스팅이 이루어지므로 static type safety가 보장되고, runtime check를 통해 dynamic type safety도 보장된다.
    • 배포(Production) 빌드에서는 dynamic type checks를 비활성화 할 수 있다(building GLib 참조).
    • e.g. VIEWER_FILE (obj)
  • PREFIX_OBJECT_CLASS (klass)
    • PrefixObjectClass type의 pointer(class structure pointer)를 리턴.
    • 위 macro와 동일하게 static/dynamic type safety를 보장.
    • e.g. VIEWER_FILE_CLASS.
  • PREFIX_IS_OBJECT (obj)
    • 입력으로 받은 instance pointer가 NULL이 아니고 OBJECT type인지 여부를 gboolean으로 리턴.
    • e.g. VIEWER_IS_FILE.
  • PREFIX_IS_OBJECT_CLASS (klass), which returns a boolean if the input class pointer is a pointer to a class of type OBJECT. For example,
    • 입력으로 받은 class pointer가 NULL이 아니고 OBJECT type의 class인지 여부를 gboolean으로 리턴.
    • e.g. VIEWER_IS_FILE_CLASS.
  • PREFIX_OBJECT_GET_CLASS (obj)
    • 입력으로 전달받은 instance의 class pointer를 리턴.
    • 역시 static/dynamic type safety를 보장.
    • e.g. VIEWER_FILE_GET_CLASS.

이들 매크로들의 구현은 꽤 직관적입니다: 많은 수의 쉬운 사용을 위한 매크로들이 gtype.h에 의해 제공됩니다.

Source 파일

코드에 특별한 요구사항이 없는 한, class를 정의(define)하기 위해 아래와 같이 G_DEFINE_TYPE 매크로를 사용할 수 있습니다.

G_DEFINE_TYPE (ViewerFile, viewer_file, G_TYPE_OBJECT)

그렇지 않은 경우 viewer_file_get_type 함수를 아래와 같이 직접 구현해야 합니다:

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