Enlightenment CVS committal
Author : mej
Project : eterm
Module : libast
Dir : eterm/libast/include/libast
Modified Files:
obj.h
Log Message:
Fri Jun 27 17:53:29 2003 Michael Jennings (mej)
Starting in on the docs for the object system. Yum.
===================================================================
RCS file: /cvsroot/enlightenment/eterm/libast/include/libast/obj.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -3 -r1.14 -r1.15
--- obj.h 19 Feb 2003 21:10:26 -0000 1.14
+++ obj.h 27 Jun 2003 21:53:49 -0000 1.15
@@ -25,21 +25,104 @@
#define _LIBAST_OBJ_H_
-/*
- * Generic macro goop
+/[EMAIL PROTECTED]/
+/**
+ * @name Object Definition and Declaration Macros
+ * Macros used to help declare and manipulate objects of any type.
+ *
+ * This set of macros is intended to abstract certain details about
+ * the internal workings of objects and greatly simplify their
+ * definition. The results have been known to cause non-cpp-compliant
+ * parsers to have the occasional fit, but they work. :-)
+ *
+ * @ingroup DOXGRP_OBJ
*/
-/* Convenience macros for declaring object structures and types. */
+/**
+ * Declare an object structure.
+ *
+ * This macro abstracts the actual name of the object structure to
+ * help prevent its direct use. Obviously the translation is plainly
+ * visible, so those sufficiently determined to do it the Wrong Way
+ * still can. This macro is not used directly, but rather as part of
+ * the SPIF_DEFINE_OBJ() macro (see below), which is in turn used to
+ * define object types.
+ *
+ * @param t The object type as a non-quoted string (e.g., obj).
+ * @return The @c struct keyword followed by the structure name for
+ * the specified object type.
+ *
+ * @see DOXGRP_OBJ, SPIF_DEFINE_OBJ(), SPIF_DEFINE_TYPE()
+ */
#define SPIF_DECL_OBJ_STRUCT(t) struct spif_ ## t ## _t_struct
+
+/**
+ * Define an object type based on the structure definition immediately
+ * following.
+ *
+ * This macro simplifies the creation of a new class by adding the
+ * appropriate @c typedef along with introducing the structure
+ * definition. Although use of this macro presents a bit of an
+ * unnatural parsing problem for non-cpp-aware tools (e.g., indent),
+ * its use is recommended for encapsulation purposes. Invocation of
+ * this macro should be immediately followed by an open brace ('{')
+ * and a normal C-style structure definition.
+ *
+ * @param t The object type as a non-quoted string (e.g., obj).
+ * @return An appropriate @c typedef and @c struct introducer.
+ *
+ * @see DOXGRP_OBJ
+ */
#define SPIF_DEFINE_OBJ(t) SPIF_DEFINE_TYPE(t,
SPIF_DECL_OBJ_STRUCT(t)); SPIF_DECL_OBJ_STRUCT(t)
+/**
+ * Declare the parent type of an object being defined.
+ *
+ * This macro is used to declare that a particular object type (e.g.,
+ * obj) is the parent type of an object which is being defined via
+ * SPIF_DEFINE_OBJ(). The call to this macro should @em immediately
+ * follow the opening brace (which, in turn, immediately follows the
+ * call to SPIF_DEFINE_OBJ()). Declaring the parent type allows for
+ * safe typecasting of any object of the current type to its parent
+ * type (or any parent type in its "family tree"). At minimum, any
+ * true object must at @em least be derived from the @c obj type so
+ * that it can be safely cast to a generic object.
+ *
+ * @param t The object type as a non-quoted string (e.g., obj).
+ *
+ * @see DOXGRP_OBJ
+ */
#define SPIF_DECL_PARENT_TYPE(t) SPIF_CONST_TYPE(t) parent
-/* Cast an arbitrary object pointer to a pointer to a nullobj. Coincidentally,
- a nullobj *is* an arbitrary object pointer. Even moreso than an obj. :-) */
-#define SPIF_NULLOBJ(obj) ((spif_nullobj_t) (obj))
-
-/* Typecase macros for classes */
+/**
+ * Cast an arbitrary class object to the generic class type.
+ *
+ * Most non-interface classes use the generic obj-style class
+ * variable, containing only the basic methods (create, delete,
+ * compare, etc.) that every object needs. However, interface classes
+ * require the use of more specific class objects with support for
+ * additional object methods. This macro allows an arbitrary class
+ * object, be it the generic class type or a decendent thereof, to be
+ * cast to the generic class type. This allows basic method calls to
+ * be performed on complex types by treating them as simple objects.
+ *
+ * @param cls An arbitrary class object.
+ * @return The class object cast to the generic type.
+ *
+ * @see DOXGRP_OBJ, SPIF_OBJ_CLASS()
+ */
#define SPIF_CLASS(cls) (SPIF_CAST(class) (cls))
+
+/**
+ * Cast an arbitrary class object to a const generic class type.
+ *
+ * This macro is equivalent to SPIF_CLASS(), except that the resulting
+ * object is a @c const object.
+ *
+ * @param cls An arbitrary class object.
+ * @return The class object cast to the generic type.
+ *
+ * @see DOXGRP_OBJ, SPIF_CLASS()
+ */
#define SPIF_CONST_CLASS(cls) (SPIF_CONST_CAST(class) (cls))
/* Assembles the name of the object class variable. */
@@ -57,6 +140,10 @@
# define SPIF_OBJ_CHECK_TYPE(o, type) SPIF_OBJ_IS_TYPE(o, type)
#endif
+/* Cast an arbitrary object pointer to a pointer to a nullobj. Coincidentally,
+ a nullobj *is* an arbitrary object pointer. Even moreso than an obj. :-) */
+#define SPIF_NULLOBJ(obj) ((spif_nullobj_t) (obj))
+
/* Cast an arbitrary object pointer to an obj. Any object of sufficient size
and/or complexity should be derived from this type. */
#define SPIF_OBJ(obj) ((spif_obj_t) (obj))
@@ -85,6 +172,7 @@
#define SPIF_OBJ_COMP(o1, o2) SPIF_CAST(cmp) (SPIF_OBJ_CALL_METHOD((o1),
comp)(o1, o2))
#define SPIF_OBJ_DUP(o) SPIF_CAST(obj) (SPIF_OBJ_CALL_METHOD((o),
dup)(o))
#define SPIF_OBJ_TYPE(o) SPIF_CAST(classname)
(SPIF_OBJ_CALL_METHOD((o), type)(o))
+/[EMAIL PROTECTED]/
/* Convenience macro */
#define SPIF_SHOW(o, fd) do { \
-------------------------------------------------------
This SF.Net email sponsored by: Free pre-built ASP.NET sites including
Data Reports, E-commerce, Portals, and Forums are available now.
Download today and enter to win an XBOX or Visual Studio .NET.
http://aspnet.click-url.com/go/psa00100006ave/direct;at.asp_061203_01/01
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
