glib/gobject.type-info.lisp

   1 (defpackage :gobject.type-info
   2   (:use :cl :iter :cffi :glib)
   3   (:export #:+g-type-invalid+
   4            #:+g-type-void+
   5            #:+g-type-interface+
   6            #:+g-type-char+
   7            #:+g-type-uchar+
   8            #:+g-type-boolean+
   9            #:+g-type-int+
  10            #:+g-type-uint+
  11            #:+g-type-long+
  12            #:+g-type-ulong+
  13            #:+g-type-int64+
  14            #:+g-type-uint64+
  15            #:+g-type-enum+
  16            #:+g-type-flags+
  17            #:+g-type-float+
  18            #:+g-type-double+
  19            #:+g-type-string+
  20            #:+g-type-pointer+
  21            #:+g-type-boxed+
  22            #:+g-type-param+
  23            #:+g-type-object+
  24            #:g-type-name
  25            #:g-type-from-name
  26            #:g-type
  27            #:g-type-children
  28            #:g-type-parent
  29            #:g-type-designator
  30            #:g-type-fundamental
  31            #:g-type-depth
  32            #:g-type-next-base
  33            #:g-type-is-a
  34            #:g-type-interfaces
  35            #:g-type-interface-prerequisites
  36            #:g-strv-get-type
  37            #:g-closure-get-type)
  38   (:documentation
  39 "This package contains functions for querying the basic type information from GObject type system. For an overview of GObject type system, see @a[http://library.gnome.org/devel/gobject/stable/index.html]{GObject documentation}
  40
  41 Types are identified by GType designators that are specified in @class{g-type-designator}. Functions of this package provide means to query basic information about type.
  42
  43 @begin{itemize}
  44 @item{@fun{g-type-name} and @fun{g-type-from-name} convert between numeric and string representation of GType.}
  45 @item{@fun{g-type-parent}, @fun{g-type-children} and @fun{g-type-interfaces} traverse across the type hierarchy.}
  46 @item{@fun{g-type-depth}, @fun{g-type-fundamental}, @fun{g-type-is-a}, @fun{g-type-next-base} are convenience functions that provide useful information from type hierarchy}
  47 @end{itemize}
  48
  49 This is a list of variables and functions that correspond to basic types:
  50 @begin{itemize}
  51 @item{@fun{g-closure-get-type}}
  52 @item{@fun{g-strv-get-type}}
  53 @item{@variable{+g-type-invalid+}}
  54 @item{@variable{+g-type-void+}}
  55 @item{@variable{+g-type-interface+}}
  56 @item{@variable{+g-type-char+}}
  57 @item{@variable{+g-type-uchar+}}
  58 @item{@variable{+g-type-boolean+}}
  59 @item{@variable{+g-type-int+}}
  60 @item{@variable{+g-type-uint+}}
  61 @item{@variable{+g-type-long+}}
  62 @item{@variable{+g-type-ulong+}}
  63 @item{@variable{+g-type-int64+}}
  64 @item{@variable{+g-type-uint64+}}
  65 @item{@variable{+g-type-enum+}}
  66 @item{@variable{+g-type-flags+}}
  67 @item{@variable{+g-type-float+}}
  68 @item{@variable{+g-type-double+}}
  69 @item{@variable{+g-type-string+}}
  70 @item{@variable{+g-type-pointer+}}
  71 @item{@variable{+g-type-boxed+}}
  72 @item{@variable{+g-type-param+}}
  73 @item{@variable{+g-type-object+}}
  74 @end{itemize}
  75 "))
  76
  77 (in-package :gobject.type-info)
  78
  79 (defctype g-type gsize)
  80
  81 (eval-when (:load-toplevel :compile-toplevel)
  82   (defun gtype-make-fundamental-type (x)
  83     (ash x 2)))
  84
  85 (defconstant +g-type-invalid+ (gtype-make-fundamental-type 0) "An invalid GType used as error return value in some functions which return a GType.")
  86 (defconstant +g-type-void+ (gtype-make-fundamental-type 1) "A fundamental type which is used as a replacement for the C @code{void} return type.")
  87 (defconstant +g-type-interface+ (gtype-make-fundamental-type 2) "The fundamental type from which all interfaces are derived.")
  88 (defconstant +g-type-char+ (gtype-make-fundamental-type 3) "The fundamental type corresponding to gchar. The type designated by @variable{+g-type-char+} is unconditionally an 8-bit signed integer. This may or may not be the same type a the C type @code{gchar}.")
  89 (defconstant +g-type-uchar+ (gtype-make-fundamental-type 4) "The fundamental type corresponding to @code{guchar}.")
  90 (defconstant +g-type-boolean+ (gtype-make-fundamental-type 5) "The fundamental type corresponding to @code{gboolean}.")
  91 (defconstant +g-type-int+ (gtype-make-fundamental-type 6) "The fundamental type corresponding to @code{gint}.")
  92 (defconstant +g-type-uint+ (gtype-make-fundamental-type 7) "The fundamental type corresponding to @code{guint}.")
  93 (defconstant +g-type-long+ (gtype-make-fundamental-type 8) "The fundamental type corresponding to @code{glong}.")
  94 (defconstant +g-type-ulong+ (gtype-make-fundamental-type 9) "The fundamental type corresponding to @code{gulong}.")
  95 (defconstant +g-type-int64+ (gtype-make-fundamental-type 10) "The fundamental type corresponding to @code{gint64}.")
  96 (defconstant +g-type-uint64+ (gtype-make-fundamental-type 11) "The fundamental type corresponding to @code{guint64}.")
  97 (defconstant +g-type-enum+ (gtype-make-fundamental-type 12) "The fundamental type from which all enumeration types are derived.")
  98 (defconstant +g-type-flags+ (gtype-make-fundamental-type 13) "The fundamental type from which all flags types are derived.")
  99 (defconstant +g-type-float+ (gtype-make-fundamental-type 14) "The fundamental type corresponding to @code{gfloat}.")
 100 (defconstant +g-type-double+ (gtype-make-fundamental-type 15) "The fundamental type corresponding to @code{gdouble}.")
 101 (defconstant +g-type-string+ (gtype-make-fundamental-type 16) "The fundamental type corresponding to null-terminated C strings.")
 102 (defconstant +g-type-pointer+ (gtype-make-fundamental-type 17) "The fundamental type corresponding to @code{gpointer}.")
 103 (defconstant +g-type-boxed+ (gtype-make-fundamental-type 18) "The fundamental type from which all boxed types are derived.")
 104 (defconstant +g-type-param+ (gtype-make-fundamental-type 19) "The fundamental type from which all GParamSpec types are derived.")
 105 (defconstant +g-type-object+ (gtype-make-fundamental-type 20) "The fundamental type for GObject.")
 106
 107 (define-foreign-type g-type-designator ()
 108   ()
 109   (:documentation "Values of this CFFI foreign type identify the GType. GType is designated by a its name (a string) or a numeric identifier. Functions accept GType designators as a string or integer and return them as a string. Functions @fun{g-type-name} and @fun{g-type-from-name} are used to convert between name and numeric identifier.
 110
 111 Numeric identifier of GType may be different between different program runs. But string identifier of GType does not change.")
 112   (:actual-type g-type)
 113   (:simple-parser g-type-designator))
 114
 115 (defmethod translate-from-foreign (value (type g-type-designator))
 116   (g-type-name value))
 117
 118 (defmethod translate-to-foreign (value (type g-type-designator))
 119   (etypecase value
 120     (string (g-type-from-name value))
 121     (integer value)
 122     (null +g-type-invalid+)))
 123
 124 (defcfun (g-type-fundamental "g_type_fundamental") g-type-designator
 125   "Returns the fundamental type which is the ancestor of @code{type}.
 126
 127 Example:
 128 @pre{
 129 \(g-type-fundamental \"GtkWindowType\")
 130 => \"GEnum\"
 131 \(g-type-fundamental \"GtkLabel\")
 132 => \"GObject\"
 133 }
 134 @arg[type]{GType designator (see @class{g-type-designator})}
 135 @return{GType designator}"
 136   (type g-type-designator))
 137
 138 (defcfun (%g-type-init "g_type_init") :void)
 139
 140 (at-init () (%g-type-init))
 141
 142 (defcfun (g-type-name "g_type_name") :string
 143   "Returns the name of a GType.@see{g-type-from-name}
 144
 145 Example:
 146 @pre{
 147 \(g-type-from-name \"GtkLabel\")
 148 => 7151952
 149 \(g-type-name 7151952)
 150 => \"GtkLabel\"
 151 }
 152 @arg[type]{GType designator (see @class{g-type-designator})}
 153 @return{a string}"
 154   (type g-type-designator))
 155
 156 (defcfun (g-type-from-name "g_type_from_name") g-type
 157   "Returns the numeric identifier of a GType by its name. @see{g-type-name}
 158
 159 Example:
 160 @pre{
 161 \(g-type-from-name \"GtkLabel\")
 162 => 7151952
 163 \(g-type-name 7151952)
 164 => \"GtkLabel\"
 165 }
 166 @arg[name]{a string - name of GType}
 167 @return{an integer}"
 168   (name :string))
 169
 170 (defcfun g-type-parent g-type-designator
 171   "Returns the parent of a GType. @see{g-type-chilren}
 172
 173 Example:
 174 @pre{
 175 \(g-type-parent \"GtkLabel\")
 176 => \"GtkMisc\"
 177 }
 178 @arg[type]{GType designator (see @class{g-type-designator})}
 179 @return{GType designator}"
 180   (type g-type-designator))
 181
 182 (defcfun g-type-depth :uint
 183   "Returns the length of the ancestry of @code{type}. This includes the @code{type} itself, so that e.g. a fundamental type has depth 1.
 184
 185 Example:
 186 @pre{
 187 \(g-type-depth \"GtkLabel\")
 188 => 6
 189 }
 190 @arg[type]{GType designator (see @class{g-type-designator})}
 191 @return{an integer}"
 192   (type g-type-designator))
 193
 194 (defcfun g-type-next-base g-type-designator
 195   "Determines the type that is derived directly from @code{root-type} which is also a base class of @code{leaf-type}.
 196
 197 Example:
 198 @pre{
 199 \(g-type-next-base \"GtkButton\" \"GtkWidget\")
 200 => \"GtkContainer\"
 201 }
 202 @arg[leaf-type]{GType designator (see @class{g-type-designator})}
 203 @arg[root-type]{GType designator}
 204 @return{GType designator}"
 205   (leaf-type g-type-designator)
 206   (root-type g-type-designator))
 207
 208 (defcfun g-type-is-a :boolean
 209   "If @code{is-a-type} is a derivable type, check whether type is a descendant of @code{is-a-type}. If @code{is-a-type} is an interface, check whether type conforms to it.
 210
 211 Example:
 212 @pre{
 213 \(g-type-is-a \"GtkButton\" \"GtkWidget\")
 214 => T
 215 \(g-type-is-a \"GtkButton\" \"AtkImplementorIface\")
 216 => T
 217 \(g-type-is-a \"GtkButton\" \"GtkLabel\")
 218 => NIL
 219 }
 220 @arg[type]{GType designator (see @class{g-type-designator})}
 221 @arg[is-a-type]{GType designator}
 222 @return{boolean}"
 223   (type g-type-designator)
 224   (is-a-type g-type-designator))
 225
 226 (defcfun (%g-type-children "g_type_children") (:pointer g-type)
 227   (type g-type-designator)
 228   (n-children (:pointer :uint)))
 229
 230 (defun g-type-children (g-type)
 231   "Returns the list of types inherited from @code{g-type}.@see{g-type-parent}
 232
 233 Example:
 234 @pre{
 235 \(g-type-children \"GtkObject\")
 236 => (\"GtkWidget\" \"GtkAdjustment\" \"GtkTreeViewColumn\" \"GtkCellRenderer\"
 237     \"GtkFileFilter\" \"GtkRecentFilter\" \"GtkTooltips\")
 238 }
 239 @arg[g-type]{GType designator (see @class{g-type-designator})}
 240 @return{list of GType designators}"
 241   (with-foreign-object (n-children :uint)
 242     (let ((g-types-ptr (%g-type-children g-type n-children)))
 243       (prog1
 244           (loop
 245              for i from 0 below (mem-ref n-children :uint)
 246              collect (mem-aref g-types-ptr 'g-type-designator i))
 247         (g-free g-types-ptr)))))
 248
 249 (defcfun (%g-type-interfaces "g_type_interfaces") (:pointer g-type)
 250   (type g-type-designator)
 251   (n-interfaces (:pointer :uint)))
 252
 253 (defun g-type-interfaces (g-type)
 254   "Returns the list of interfaces the @code{g-type} conforms to.
 255
 256 Example:
 257 @pre{
 258 \(g-type-interfaces \"GtkButton\")
 259 => (\"AtkImplementorIface\" \"GtkBuildable\" \"GtkActivatable\")
 260 }
 261 @arg[g-type]{GType designator (see @class{g-type-designator})}
 262 @return{list of GType designators}"
 263   (with-foreign-object (n-interfaces :uint)
 264     (let ((g-types-ptr (%g-type-interfaces g-type n-interfaces)))
 265       (prog1
 266           (loop
 267              for i from 0 below (mem-ref n-interfaces :uint)
 268              collect (mem-aref g-types-ptr 'g-type-designator i))
 269         (g-free g-types-ptr)))))
 270
 271 (defcfun (%g-type-interface-prerequisites "g_type_interface_prerequisites") (:pointer g-type)
 272   (type g-type-designator)
 273   (n-interface-prerequisites (:pointer :uint)))
 274
 275 (defun g-type-interface-prerequisites (g-type)
 276   "Returns the prerequisites of an interface type. Prerequisite is a type that must be a superclass of an implementing class or an interface that the object must also implement.
 277
 278 Example:
 279 @pre{
 280 \(g-type-interface-prerequisites \"GtkTreeModel\")
 281 => (\"GObject\")
 282 }
 283 @arg[g-type]{GType designator (see @class{g-type-designator})}
 284 @return{list of GType designators}"
 285   (with-foreign-object (n-interface-prerequisites :uint)
 286     (let ((g-types-ptr (%g-type-interface-prerequisites g-type n-interface-prerequisites)))
 287       (prog1
 288           (loop
 289              for i from 0 below (mem-ref n-interface-prerequisites :uint)
 290              collect (mem-aref g-types-ptr 'g-type-designator i))
 291         (g-free g-types-ptr)))))
 292
 293 (defcfun g-strv-get-type g-type-designator
 294   "Returns the type designator (see @class{g-type-designator}) for GStrv type. As a side effect, ensures that the type is registered.")
 295
 296 (at-init nil (g-strv-get-type))
 297
 298 (defcfun g-closure-get-type g-type-designator
 299   "Returns the type designator (see @class{g-type-designator}) for GClosure type. As a side effect, ensure that the type is registered.")
 300
 301 (at-init nil (g-closure-get-type))