From af90ac5cff9dbb5f44677cc4726eee60ab88bc5d Mon Sep 17 00:00:00 2001 From: Dmitry Kalyanov Date: Thu, 9 Jul 2009 00:44:28 +0400 Subject: [PATCH] Added some docstrings and changed exports --- glib/glib.lisp | 34 ++++++-- glib/gobject.foreign-closures.lisp | 11 +++ glib/gobject.foreign-gboxed.lisp | 105 ++++++++++++++++++++++++- glib/gobject.foreign-gobject-subclassing.lisp | 2 +- glib/gobject.foreign-gobject.lisp | 7 +- glib/gobject.foreign.lisp | 17 +++- glib/gobject.generating.lisp | 36 ++++++++- glib/gobject.gvalue-parser.lisp | 12 +++ glib/gobject.gvalue.lisp | 10 +++ glib/gobject.meta.lisp | 3 +- glib/gobject.object-defs.lisp | 6 +- glib/gobject.package.lisp | 40 +++++++--- glib/gobject.signals.lisp | 5 ++ glib/gobject.type.lisp | 19 +++++ gtk/gtk.objects.lisp | 4 +- 15 files changed, 285 insertions(+), 26 deletions(-) diff --git a/glib/glib.lisp b/glib/glib.lisp index a262e07..61f17a8 100644 --- a/glib/glib.lisp +++ b/glib/glib.lisp @@ -22,7 +22,9 @@ #:+g-priority-high-idle+ #:+g-priority-default-idle+ #:+g-priority-low+ - #:g-idle-add-full)) + #:g-idle-add-full) + (:documentation + "Cl-gtk2-glib is wrapper for @a[http://library.gnome.org/devel/glib/]{GLib}.")) (in-package :glib) @@ -36,6 +38,11 @@ (funcall fn))) (defmacro at-init (&body body) + "@arg[body]{the code} +Runs the code normally but also schedules the code to be run at image load time. +It is used to reinitialize the libraries when the dumped image is loaded. +(Works only on SBCL for now) +" `(progn (register-initializer (lambda () ,@body)) ,@body)) @@ -142,11 +149,11 @@ (defcfun (g-main-loop-get-context "g_main_loop_get_context" :library glib) (:pointer g-main-context) (loop (:pointer g-main-loop))) -(defconstant +g-priority-high+ -100) -(defconstant +g-priority-default+ 0) -(defconstant +g-priority-high-idle+ 100) -(defconstant +g-priority-default-idle+ 200) -(defconstant +g-priority-low+ 300) +(defconstant +g-priority-high+ -100 "Use this for high priority event sources. It is not used within GLib or GTK+.") +(defconstant +g-priority-default+ 0 "Use this for default priority event sources. In GLib this priority is used when adding timeout functions with g_timeout_add(). In GDK this priority is used for events from the X server.") +(defconstant +g-priority-high-idle+ 100 "Use this for high priority idle functions. GTK+ uses @variable{+g-priority-high-idle+} + 10 for resizing operations, and @variable{+g-priority-high-idle+} + 20 for redrawing operations. (This is done to ensure that any pending resizes are processed before any pending redraws, so that widgets are not redrawn twice unnecessarily.)") +(defconstant +g-priority-default-idle+ 200 "Use this for default priority idle functions. In GLib this priority is used when adding idle functions with g_idle_add().") +(defconstant +g-priority-low+ 300 "Use this for very low priority background tasks. It is not used within GLib or GTK+.") (defcfun (g-main-context-new "g_main_context_new" :library glib) (:pointer g-main-context)) @@ -272,6 +279,12 @@ (data :pointer)) (defcfun (g-idle-add-full "g_idle_add_full" :library glib) :uint + "A low-level function for adding callbacks to be called from main loop. Wrapper around g_idle_add_full. +Adds a function to be called whenever there are no higher priority events pending. If the function returns FALSE it is automatically removed from the list of event sources and will not be called again. +@arg[priority]{an integer specifying the priority. See @variable{+g-priority-default+}, @variable{+g-priority-default-idle+}, @variable{+g-priority-high+}, @variable{+g-priority-high-idle+}, @variable{+g-priority-low+}.} +@arg[function]{pointer to callback that will be called. Callback should accept a single pointer argument and return a boolean FALSE if it should be removed} +@arg[data]{pointer that will be passed to callback function} +@arg[notify]{function that will be called when callback is no more needed. It will receive the @code{data} argument}" (priority :uint) (function :pointer) (data :pointer) @@ -433,12 +446,21 @@ ; Memory Allocation, IO Channels, Error Reporting, Message Output and Debugging Functions, Message Logging (defcfun g-free :void + "@arg[ptr]{pointer previously obtained with @fun{g-malloc} or with g_malloc C function} +Frees the pointer by calling g_free on it." (ptr :pointer)) (defcfun (g-malloc "g_malloc0") :pointer + "@arg[n-bytes]{an integer} +@return{pointer to beginning of allocated memory} +Allocates the specified number of bytes in memory. Calls g_malloc. +@see{g-free}" (n-bytes gsize)) (defcfun g-strdup :pointer + "@arg[str]{a @class{string}} +@return{foreign pointer to new string} +Allocates a new string that is equal to @code{str}. Use @fun{g-free} to free it." (str (:string :free-to-foreign t))) ;omitted all GLib Utilites diff --git a/glib/gobject.foreign-closures.lisp b/glib/gobject.foreign-closures.lisp index 1f87c70..ee1ab44 100644 --- a/glib/gobject.foreign-closures.lisp +++ b/glib/gobject.foreign-closures.lisp @@ -46,6 +46,17 @@ closure)) (defun g-signal-connect (object signal handler &key after) + "Deprecated alias for @fun{connect-signal}" + (connect-signal object signal handler :after after)) + +(defun connect-signal (object signal handler &key after) + "Connects the function to a signal for a particular object. +If @code{after} is true, then the function will be called after the default handler of the signal. + +@arg[object]{an instance of @class{gobject}} +@arg[signal]{a string; names the signal} +@arg[handler]{a function; handles the signal. Number (and type) of arguments and return value type depends on the signal} +@arg[after]{a boolean}" (g-signal-connect-closure (ensure-object-pointer object) signal (create-closure handler) diff --git a/glib/gobject.foreign-gboxed.lisp b/glib/gobject.foreign-gboxed.lisp index ff6d9da..75f216b 100644 --- a/glib/gobject.foreign-gboxed.lisp +++ b/glib/gobject.foreign-gboxed.lisp @@ -185,6 +185,49 @@ (get-g-boxed-completed-c-definition (g-boxed-root name) (get name 'c-name)))) (defmacro define-g-boxed-class (g-name-and-c-name name (&optional superclass-and-dispatch (export t)) &body slots) + "Defines the class corresponding to GBoxed type. Used only for structures that are passed (semantically) by value. E.g., GdkEvent. +Single inheritance of classes is supported (and is used for definining different sub-types of GdkEvent). Decision of which class to use for a given C structure is made based on values of certain slots (see arguments @code{dispatch-slot} and @code{dispatch-values}). + +Example: + +@begin{pre} +\(define-g-boxed-class (\"GdkEvent\" event-struct) event () + (type event-type) + (window (g-object gdk-window)) + (send-event (:boolean :int8))) + +\(define-g-boxed-class nil event-button ((event type (:button-press :2button-press :3button-press :button-release))) + (time :uint32) + (x :double) + (y :double) + (axes (fixed-array :double 2)) + (state :uint) + (button :uint) + (device (g-object device)) + (x-root :double) + (y-root :double)) + +\(define-g-boxed-class \"GdkColor\" color () + (pixel :uint32 :initform 0) + (red :uint16 :initform 0) + (green :uint16 :initform 0) + (blue :uint16 :initform 0)) +@end{pre} +@arg[g-name-and-c-name]{@code{NIL} or list @code{(&optional g-name c-name)}; g-name is the GObject type name and c-name is the name of generated CFFI C structure.} +@arg[name]{a symbol; name of the structure (defstruct) that is defined} +@arg[superclass-and-dispatch]{@code{NIL} or list @code{(&optional superclass dispatch-slot dispatch-values)}} +@arg[superclass]{a symbol denoting the superclass of the class being defined} +@arg[dispatch-slot]{a symbol denoting the slot of the superclass that identifies the \"real\" class} +@arg[dispatch-values]{a value or a list of values of @code{dispatch-slot} of @code{superclass} that correspond to the class being defined} +@arg[export]{a boolean; defines whether all related symbols (@code{name} and generated slot accessors) should be exported from the current package} +@arg[slots]{a list of slots; each slot is defined by list @code{(name type &key initform parser unparser)}. +@begin{itemize} +@item{@code{name} is the name of a slot} +@item{@code{type} is a CFFI type of a slot} +@item{@code{initform} is an expression that is the iniform of a slot in generated @code{defstruct}; used when the lisp code creates the object.} +@item{@code{parser} is a function designator for a slot parser function (if a slot parsing depends on other slots of a structure; custom slot parsing is better implemented with CFFI foreign types). Slot parser function is a function that accepts two arguments: name of a slot and a pointer to C structure and returns the value of a slot} +@item{@code{unparser} is a function designator for a slot unparser function. Slot unparsing function is a function that accepts three arguments: name of a slot, pointer to a C structure and a value of a slot. It should assign the slot value to a C structure.} +@end{itemize}}" (destructuring-bind (&optional g-name c-name) (ensure-list g-name-and-c-name) (destructuring-bind (&optional superclass dispatch-slot dispatch-values) superclass-and-dispatch (let* ((superclass-slots (get superclass 'boxed-combined-slots)) @@ -213,7 +256,15 @@ (defun boxed-c-structure-name (name) (get (g-boxed-root name) 'c-name)) -(defclass g-boxed-ref () ((pointer :accessor pointer :initarg :pointer))) +(defclass g-boxed-ref () + ((pointer :accessor pointer :initarg :pointer)) + (:documentation "Class corresponding to GBoxed objects that are passed by reference to C structure rather than by value. + +Instances of this class are collected by garbage collector. Each object has an owner: lisp code or C code. If owner is the lisp code then the corresponding C structure will be freed when the object is collected. Is the owner is the C code, the C structure lifetime is not connected with the lifetime of the object: it may be freed before or after the object becomes collected. If the owner if C code, lisp code must be careful not to access slots of the object after the C code frees the object (it cannot be tracked automatically). + +When object is created by lisp code (using @fun{make-instance}), it is owned by lisp code unless explicitly disowned by @fun{disown-boxed-ref}. Disowning should be done when the object is passed to some function that becomes the owner of the reference. + +When object is returned from a function, it depends on a function whether lisp code is the owner of GBoxed object. Return values and arguments of foreign functions are marked with CFFI foreign-type called @class{g-boxed-ref-type} that specifies (by the value of its @code{owner} slot) which code owns the reference.")) (defvar *g-boxed-gc-lock* (make-recursive-lock "g-boxed-gc-lock")) (defvar *known-boxed-refs* (tg:make-weak-hash-table :test 'equal :weakness :value)) @@ -225,6 +276,9 @@ (error "g-boxed-ref class ~A has no free-function" name))) (defun disown-boxed-ref (object) + "Specify that the Lisp code no longer owns the reference to the @code{object}. Otherwise garbage collector would collect the @code{object} and corresponding C structure would be freed, causing dangling pointer (if C code does not free the structure) of double free (if C code frees the structure). + +@arg[object]{an instance of @class{g-boxed-ref}}" (setf (gethash (pointer-address (pointer object)) *boxed-ref-owner*) :foreign)) (defun dispose-boxed-ref (type pointer) @@ -321,6 +375,51 @@ `(,writer new-value object)))))))) (defmacro define-g-boxed-ref (gobject-name name &rest properties) + "Defines a class corresponding to GBoxed type that is passed by reference (e.g., GtkTextIter). Class is made a subclass of @code{g-boxed-ref}. + +Example: +@begin{pre} +\(defun tree-iter-alloc () (glib:g-malloc (foreign-type-size 'tree-iter))) +\(defun tree-iter-free (v) (glib:g-free v)) + +\(define-g-boxed-ref \"GtkTreeIter\" tree-iter + (:slots (stamp :reader tree-iter-get-stamp :writer tree-iter-set-stamp :accessor tree-iter-stamp) + (user-data :reader tree-iter-get-user-data :writer tree-iter-set-user-data :accessor tree-iter-user-data)) + (:alloc-function tree-iter-alloc) + (:free-function tree-iter-free)) +@end{pre} +@arg[gobject-name]{a string denoting the GObject type} +@arg[name]{a symbol denoting the class name for generated class} +@arg[properties]{p-list of options. +Each option is a list @code{(name value)} where @code{name} is name of an option and @code{value} is its value. +Following options are used: +@begin{itemize} +@item{@code{:free-function} (mandatory). Designator for a function that frees the allocated object. Accepts a single argument - pointer.} +@item{@code{:alloc-function} (mandator). Designator for a function that accepts zero arguments and returns the C pointer to newly allocated object.} +@item{@code{:slots} (optional). Slots specifications for GBoxed. +Each slot is specified as a list @code{(slot-name &key reader writer type (accessor slot-name))}. +@begin{itemize} +@item{@code{slot-name} is a symbol - the name of a slot} +@item{@code{type} is a CFFI type of a slot} +@item{@code{reader} is a @code{NIL} or a string or a function designator. + +If it is a @code{NIL} then the slot is not readable. + +If it is a string then it names the C function that accepts the pointer to C structure and returns the value of a slot (of specified CFFI type). + +If it is a function designator then it specifies a function that accepts the Lisp object and returns its slot value.} +@item{@code{writer} is a @code{NIL} or string or a function designator. + +If it is a @code{NIL} then the slot is not writable. + +If it is a string then it names the C function that accepts the pointer to C structure and a value (of specified CFFI type) and assigns it to the slot of a structure. and returns the value of a slot (of specified CFFI type). + +If it is a function designator then it specifies a function that accepts the new slot value and a Lisp object and assigns it to the slot.} +@item{@code{accessor} is a symbol that names accessor function for this slot. By default it equals to @code{slot-name}.} +@end{itemize} +} +@end{itemize} +}" (let ((free-fn (second (find :free-function properties :key 'first))) (alloc-fn (second (find :alloc-function properties :key 'first))) (slots (rest (find :slots properties :key 'first)))) @@ -341,7 +440,9 @@ (define-foreign-type fixed-array () ((element-type :reader fixed-array-element-type :initarg :element-type :initform (error "Element type must be specified")) (array-size :reader fixed-array-array-size :initarg :array-size :initform (error "Array size must be specified"))) - (:actual-type :pointer)) + (:actual-type :pointer) + (:documentation +"CFFI foreign type for an array of a fixed length. Slot @code{element-type}@see-slot{fixed-array-element-type} specifies the type of elements and slot @code{array-size}@see-slot{fixed-array-array-size} specifies the size of array (in elements).")) (define-parse-method fixed-array (element-type array-size) (make-instance 'fixed-array :element-type element-type :array-size array-size)) diff --git a/glib/gobject.foreign-gobject-subclassing.lisp b/glib/gobject.foreign-gobject-subclassing.lisp index cb9fc94..0e921e8 100644 --- a/glib/gobject.foreign-gobject-subclassing.lisp +++ b/glib/gobject.foreign-gobject-subclassing.lisp @@ -199,7 +199,7 @@ `(progn (setf (gethash ,name *registered-types*) (make-object-type :name ,name :class ',class :parent ,parent :interfaces ',interfaces :properties ',properties)) (at-init - (format t "Registering GObject type implementation ~A for type ~A~%" ',class ,name) + (debugf "Registering GObject type implementation ~A for type ~A~%" ',class ,name) (with-foreign-object (query 'g-type-query) (g-type-query (g-type-from-name ,parent) query) (with-foreign-slots ((class-size instance-size) query g-type-query) diff --git a/glib/gobject.foreign-gobject.lisp b/glib/gobject.foreign-gobject.lisp index c736aff..2e64dd1 100644 --- a/glib/gobject.foreign-gobject.lisp +++ b/glib/gobject.foreign-gobject.lisp @@ -9,7 +9,9 @@ (has-reference :type boolean :accessor g-object-has-reference - :initform nil))) + :initform nil)) + (:documentation + "Base class for GObject classes hierarchy.")) (defvar *foreign-gobjects* (make-weak-hash-table :test 'equal :weakness :value)) (defvar *foreign-gobjects-ref-count* (make-hash-table :test 'equal)) @@ -189,6 +191,9 @@ (register-object-type "GObject" 'g-object) (defun ensure-g-type (type) + "Returns the GType value for a given type. If type is an integer, it is returned. If type is a string, GType corresponding to this type name is looked up and returned. +@arg[type]{a string or and integer} +@return{integer equal to GType of @code{type}}" (etypecase type (integer type) (string (or (g-type-from-name type) diff --git a/glib/gobject.foreign.lisp b/glib/gobject.foreign.lisp index 0738cdc..051d700 100644 --- a/glib/gobject.foreign.lisp +++ b/glib/gobject.foreign.lisp @@ -1,10 +1,16 @@ (in-package :gobject) -(defgeneric release (object)) +(defgeneric release (object) + (:documentation "Manually frees the Lisp reference to the @code{object}. Probably should not be called. + +@arg[object]{an instance of @class{g-object}}")) (defmethod release ((object null))) (defun release* (&rest objects) + "Calls @fun{release} on all objects in @code{objects} + +@arg[objects]{a list of instances of @class{g-object}}" (declare (dynamic-extent objects)) (loop for object in objects @@ -31,14 +37,19 @@ (defvar *registered-stable-pointers* (make-array 0 :adjustable t :fill-pointer t)) (defun allocate-stable-pointer (thing) + "Allocates the stable pointer for @code{thing}. Stable pointer is an integer that can be dereferenced with @fun{get-stable-pointer-value} and freed with @fun{free-stable-pointer}. Stable pointers are used to pass references to lisp objects to foreign code. +@arg[thing]{any object} +@return{integer}" (let ((id (find-fresh-id))) (setf (aref *registered-stable-pointers* id) thing) (make-pointer id))) (defun free-stable-pointer (stable-pointer) + "Frees the stable pointer previously allocated by @fun{allocate-stable-pointer}" (setf (aref *registered-stable-pointers* (pointer-address stable-pointer)) nil)) (defun get-stable-pointer-value (stable-pointer) + "Returns the objects that is referenced by stable pointer previously allocated by @fun{allocate-stable-pointer}. May be called any number of times." (when (<= 0 (pointer-address stable-pointer) (length *registered-stable-pointers*)) (aref *registered-stable-pointers* (pointer-address stable-pointer)))) @@ -48,6 +59,10 @@ (1- (length *registered-stable-pointers*))))) (defmacro with-stable-pointer ((ptr expr) &body body) + "Executes @code{body} with @code{ptr} bound to the stable pointer to result of evaluating @code{expr}. + +@arg[ptr]{a symbol naming the variable which will hold the stable pointer value} +@arg[expr]{an expression}" `(let ((,ptr (allocate-stable-pointer ,expr))) (unwind-protect (progn ,@body) diff --git a/glib/gobject.generating.lisp b/glib/gobject.generating.lisp index 2be3e3c..0b7ebeb 100644 --- a/glib/gobject.generating.lisp +++ b/glib/gobject.generating.lisp @@ -1,6 +1,7 @@ (in-package :gobject) -(defvar *lisp-name-package* (find-package :gobject)) +(defvar *lisp-name-package* (find-package :gobject) + "For internal use (used by class definitions generator). Specifies the package in which symbols are interned.") (defvar *strip-prefix* "") (defvar *lisp-name-exceptions* nil) (defvar *generation-exclusions* nil) @@ -326,7 +327,22 @@ (equal (g-type-fundamental (ensure-g-type type)) fund-type)) types)) -(defmacro define-g-enum (g-name name (&key (export t) type-initializer) &body values) +(defmacro define-g-enum (g-name name (&key (export t) type-initializer) &body values) + "Defines a GEnum type for enumeration. Generates corresponding CFFI definition. + +Example: +@begin{pre} +\(define-g-enum \"GdkGrabStatus\" grab-status () :success :already-grabbed :invalid-time :not-viewable :frozen) +\(define-g-enum \"GdkExtensionMode\" gdk-extension-mode (:export t :type-initializer \"gdk_extension_mode_get_type\") + (:none 0) (:all 1) (:cursor 2)) +@end{pre} +@arg[g-name]{a string. Specifies the GEnum name} +@arg[name]{a symbol. Names the enumeration type.} +@arg[export]{a boolean. If true, @code{name} will be exported.} +@arg[type-initializer]{a @code{NIL} or a string or a function designator. + +If non-@code{NIL}, specifies the function that initializes the type: string specifies a C function that returns the GType value and function designator specifies the Lisp function.} +@arg[values]{values for enum. Each value is a keyword or a list @code{(keyword integer-value)}. @code{keyword} corresponds to Lisp value of enumeration, and @code{integer-value} is an C integer for enumeration item. If @code{integer-value} is not specified, it is generated automatically (see CFFI manual)}" `(progn (defcenum ,name ,@values) (register-enum-type ,g-name ',name) @@ -355,6 +371,22 @@ ,@(mapcar #'enum-value->definition items)))) (defmacro define-g-flags (g-name name (&key (export t) type-initializer) &body values) + "Defines a GFlags type for enumeration that can combine its values. Generates corresponding CFFI definition. Values of this type are lists of keywords that are combined. + +Example: +@begin{pre} +\(define-g-flags \"GdkWindowState\" window-state () + (:withdrawn 1) + (:iconified 2) (:maximized 4) (:sticky 8) (:fullscreen 16) + (:above 32) (:below 64)) +@end{pre} +@arg[g-name]{a string. Specifies the GEnum name} +@arg[name]{a symbol. Names the enumeration type.} +@arg[export]{a boolean. If true, @code{name} will be exported.} +@arg[type-initializer]{a @code{NIL} or a string or a function designator. + +If non-@code{NIL}, specifies the function that initializes the type: string specifies a C function that returns the GType value and function designator specifies the Lisp function.} +@arg[values]{values for flags. Each value is a keyword or a list @code{(keyword integer-value)}. @code{keyword} corresponds to Lisp value of a flag, and @code{integer-value} is an C integer for flag. If @code{integer-value} is not specified, it is generated automatically (see CFFI manual)}" `(progn (defbitfield ,name ,@values) (register-flags-type ,g-name ',name) diff --git a/glib/gobject.gvalue-parser.lisp b/glib/gobject.gvalue-parser.lisp index 7d1873f..212992f 100644 --- a/glib/gobject.gvalue-parser.lisp +++ b/glib/gobject.gvalue-parser.lisp @@ -16,6 +16,10 @@ `((equalp ,key ,value) ,@forms))))))) (defun parse-gvalue (gvalue) + "Parses the GValue structure and returns the corresponding Lisp object. + +@arg[value]{a C pointer to the GValue structure} +@return{value contained in the GValue structure. Type of value depends on GValue type}" (let* ((type (gvalue-type gvalue)) (fundamental-type (g-type-fundamental type))) (cond @@ -45,6 +49,14 @@ (t (error "Unknown type: ~A (~A)" type (g-type-name type)))))))) (defun set-g-value (gvalue value type &key zero-g-value unset-g-value (g-value-init t)) + "Assigns the GValue structure @code{gvalue} the value @code{value} of GType @code{type}. + +@arg[gvalue]{a C pointer to the GValue structure} +@arg[value]{a Lisp object that is to be assigned} +@arg[type]{a GType that is to be assigned} +@arg[zero-g-value]{a boolean specifying whether GValue should be zero-initialized before assigning. See @fun{g-value-zero}} +@arg[unset-g-value]{a boolean specifying whether GValue should be \"unset\" before assigning. See @fun{g-value-unset}. The \"true\" value should not be passed to both @code{zero-g-value} and @code{unset-g-value} arguments} +@arg[g-value-init]{a boolean specifying where GValue should be initialized}" (cond (zero-g-value (g-value-zero gvalue)) (unset-g-value (g-value-unset gvalue))) diff --git a/glib/gobject.gvalue.lisp b/glib/gobject.gvalue.lisp index 22b1b04..4162ee7 100644 --- a/glib/gobject.gvalue.lisp +++ b/glib/gobject.gvalue.lisp @@ -1,10 +1,17 @@ (in-package :gobject) (defcfun g-value-init (:pointer g-value) + "Initializes the GValue @code{value} with the default value of @code{type} + +@arg[value]{a C pointer to the GValue structure} +@arg[type]{an integer specifying the GType}" (value (:pointer g-value)) (type g-type)) (defun g-value-zero (g-value) + "Initializes the GValue in \"unset\" state. + +@arg[g-value]{a C pointer to the GValue structure}" (loop for i from 0 below (foreign-type-size 'g-value) do (setf (mem-ref g-value :uchar i) 0))) @@ -17,6 +24,9 @@ (value (:pointer g-value))) (defcfun g-value-unset (:pointer g-value) + "Clears the current value in @code{value} and \"unsets\" the type, releasing all resources associated with this GValue. An unset value is the same as an unitialized GValue. + +@arg[value]{a C pointer to the GValue structure}" (value (:pointer g-value))) (defcfun g-value-set-instance :void diff --git a/glib/gobject.meta.lisp b/glib/gobject.meta.lisp index c316dfb..b5d3f4c 100644 --- a/glib/gobject.meta.lisp +++ b/glib/gobject.meta.lisp @@ -9,7 +9,8 @@ :reader gobject-class-g-type-initializer) (interface-p :initform nil :initarg :g-interface-p - :reader gobject-class-interface-p))) + :reader gobject-class-interface-p)) + (:documentation "Metaclass for GObject-based classes.")) (defun initialize-gobject-class-g-type (class) (if (gobject-class-g-type-initializer class) diff --git a/glib/gobject.object-defs.lisp b/glib/gobject.object-defs.lisp index c147371..785e194 100644 --- a/glib/gobject.object-defs.lisp +++ b/glib/gobject.object-defs.lisp @@ -1,3 +1,7 @@ (in-package :gobject) -(define-g-object-class "GInitiallyUnowned" g-initially-unowned (:superclass g-object) ()) \ No newline at end of file +(defclass g-initially-unowned (g-object) + () + (:metaclass gobject-class) + (:g-type-name . "GInitiallyUnowned") + (:documentation "Base class that has initial \"floating\" reference.")) diff --git a/glib/gobject.package.lisp b/glib/gobject.package.lisp index 3227487..b02a772 100644 --- a/glib/gobject.package.lisp +++ b/glib/gobject.package.lisp @@ -1,10 +1,7 @@ (defpackage :gobject (:use :cl :glib :cffi :tg :bordeaux-threads :iter :closer-mop) (:export #:g-object - #:register-object-type - #:g-object-call-constructor - #:register-flags-type - #:register-enum-type + #:pointer #:g-type-from-object #:g-type-name #:g-type-from-name @@ -17,8 +14,7 @@ #:define-g-flags #:fixed-array #:g-boxed-inline - #:g-boxed-ptr - #:boxed-c-structure-name + #:g-boxed-ptr #:define-g-interface #:release #:using @@ -31,7 +27,6 @@ #:with-stable-pointer #:release* #:disown-boxed-ref - #:pointer #:g-type-interface #:g-value #:register-object-type-implementation @@ -43,7 +38,6 @@ #:emit-signal #:g-value-unset #:g-value-zero - #:g-value-take-boxed #:g-value-init #:g-class-property-definition #:g-class-property-definition-name @@ -62,7 +56,35 @@ #:g-type-class-unref #:registered-object-type-by-name #:g-type-children - #:g-signal-lookup)) + #:g-signal-lookup + #:g-type-parent + #:connect-signal + #:boxed-c-structure-name) + (:documentation +"This package contains bindings to GLib object system called GObject. + +It contains: +@begin{itemize} +@item{type system} +@item{object system} +@item{utilities for memory management} +@end{itemize} + +@begin[GObject type system querying]{section} +GObject type information can queried. Type is identified by GType — an integer. + +Function @fun{g-type-from-name} returns GType by its name, and function @fun{g-type-name} returns the name of a GType. Function @fun{ensure-g-type} is a convenience function that returns GType from either GType or its name. + +Functions @fun{g-type-parent} and @fun{g-type-children} inspect type hierarchy. +@end{section} + +@begin[GValue]{section} +GValue is a GObject's \"variant\"-like type. It can contain value of any type that GObject supports. The GValue is used for passing parameters to signal handlers, properties' getters and setters. Functions @fun{g-value-init}, @fun{g-value-unset}, @fun{g-value-zero}, @fun{parse-gvalue} and @fun{set-g-value} are used to init, reset, retrieve and assign GValue structures. +@end{section} + +@begin[Utilities]{section} +GObject contains implementation of stable pointers. Stable pointer is a reference that can be passed between FFI boundaries. Stable pointer is an integer that is allocated with @fun{allocate-stable-pointer}. This integer can be passed to other code and back. The value of this pointer (that is retrieved with @fun{get-stable-pointer-value}) is stable, staying the same until the pointer is freed with @fun{free-stable-pointer}. For convenience, @fun{with-stable-pointer} macro is provided. +@end{section}")) (in-package :gobject) diff --git a/glib/gobject.signals.lisp b/glib/gobject.signals.lisp index 83436fe..394280c 100644 --- a/glib/gobject.signals.lisp +++ b/glib/gobject.signals.lisp @@ -36,6 +36,11 @@ (logxor type (ldb (byte 1 0) type)));;subtract the G_SIGNAL_TYPE_STATIC_SCOPE (defun emit-signal (object signal-name &rest args) + "Emits the signal. +@arg[object]{an instance of @class{g-object}. Signal is emitted on this object} +@arg[signal-name]{a string specifying the signal} +@arg[args]{arguments for the signal} +@return{none}" (let ((signal-id (g-signal-lookup signal-name (g-type-from-object (pointer object))))) (when (= signal-id 0) (error "Signal ~A not found on object ~A" signal-name object)) diff --git a/glib/gobject.type.lisp b/glib/gobject.type.lisp index e863517..22eb2ec 100644 --- a/glib/gobject.type.lisp +++ b/glib/gobject.type.lisp @@ -8,12 +8,24 @@ (at-init (%g-type-init)) (defcfun (g-type-name "g_type_name") :string + "Returns the GType name + +@arg[type]{an integer specifying the GType} +@return{a string - name of type}" (type g-type)) (defcfun (g-type-from-name "g_type_from_name") g-type + "Looks up the GType by its name + +@arg[name]{a string naming the type} +@return{an integer specifying GType}" (name :string)) (defcfun g-type-parent g-type + "Returns the parent of a GType + +@arg[type]{an integer specifying the GType} +@return{an integer specifying the parent GType}" (type g-type)) (defcfun g-type-depth :uint @@ -48,6 +60,9 @@ (n-children (:pointer :uint))) (defun g-type-children (g-type) + "Returns the list of types inherited from @code{g-type}. + +@arg[g-type]{an integer or a string specifying type}" (setf g-type (ensure-g-type g-type)) (with-foreign-object (n-children :uint) (let ((g-types-ptr (%g-type-children g-type n-children))) @@ -109,6 +124,10 @@ (prerequisite-type g-type)) (defun g-type-from-object (object) + "Returns the GType of an @code{object} + +@arg[object]{C pointer to an object} +@return{an integer specifying the GType}" (g-type-from-instance object)) (defun g-type-from-class (g-class) diff --git a/gtk/gtk.objects.lisp b/gtk/gtk.objects.lisp index 6e095ac..e4f3521 100644 --- a/gtk/gtk.objects.lisp +++ b/gtk/gtk.objects.lisp @@ -17,8 +17,8 @@ (defun tree-iter-get-user-data (i) (pointer-address (foreign-slot-value (pointer i) 'tree-iter 'user-data))) (defun tree-iter-set-user-data (value i) (setf (foreign-slot-value (pointer i) 'tree-iter 'user-data) (make-pointer value))) -(defun tree-iter-alloc () (glib::g-malloc (foreign-type-size 'tree-iter))) -(defun tree-iter-free (v) (glib::g-free v)) +(defun tree-iter-alloc () (glib:g-malloc (foreign-type-size 'tree-iter))) +(defun tree-iter-free (v) (glib:g-free v)) (define-g-boxed-ref "GtkTreeIter" tree-iter (:slots (stamp :reader tree-iter-get-stamp :writer tree-iter-set-stamp :accessor tree-iter-stamp) -- 1.7.10.4