Changes between Initial Version and Version 1 of code/doc/Super

Timestamp:

Oct 1, 2008, 2:52:45 AM (16 years ago)

Author:

landauf

Comment:

—

code/doc/Super

@@ +1 @@
+= Super =
+[[TracNav(TracNav/TOC_Development)]]
+
+== Description ==
+Super.h defines all macros needed to add a new "super-function". If you add a super-function, you can call SUPER(myclass, functionname, arguments) inside your code and the function of the parentclass gets called. This is comparable with
+super.functionname() in Java or other languages.
+
+This works only with virtual functions that return nothing (void) and belong to classes that have an Identifier. Arguments however are supported.
+
+
+== Add a new super-function ==
+To add a new super-function, you have process 4 steps:
+
+ 1. '''Add a new SUPER macro''':[[br]]
+    This allows you to call the super-function in your code.[[br]]
+    Location: core/Super.h, marked with --> HERE <-- comments (1/3)[[br]][[br]]
+ 1. '''Call the SUPER_FUNCTION_GLOBAL_DECLARATION_PART1/2 macros.'''[[br]]
+    This defines some global classes and templates, needed to create and call the super-functions.[[br]]
+    Location: core/Super.h, marked with --> HERE <-- comments (2/3)[[br]][[br]]
+ 1. '''Call the SUPER_INTRUSIVE_DECLARATION macro.'''[[br]]
+    This will be included into the declaration of !ClassIdentifier<T>.[[br]]
+    Location: core/Super.h, marked with --> HERE <-- comments (3/3)[[br]][[br]]
+ 1. '''Call the SUPER_FUNCTION macro.'''[[br]]
+    This defines a partially specialized template that will decide if a class is "super" to another class. If the check returns true, a SuperFunctionCaller gets created, which will be used by the SUPER macro. You have to add this into the header-file of the baseclass of the super-function (the class that first implements the function), below the class declaration. You can't call it directly in this file, because otherwise you had to include the headerfile right here, which would cause some ugly backdependencies, include loops and slower compilation.[[br]]
+    Dont forget to include core/Super.h in the header-file.[[br]]
+    Location: The header-file of the baseclass (core/Baseclass.h), below the class declaration[[br]]
+
+== Call a super-function ==
+Example: mySuperFunction(int value) was declared as a super-function by following the previous steps. This is how you use SUPER:
+
+*.h File:
+{{{
+class BaseClass
+{
+    virtual void mySuperFunction(int value);
+};
+
+class DerivedClass : public BaseClass
+{
+    virtual void mySuperFunction(int value);
+};
+}}}
+
+*.cc File:
+{{{
+void BaseClass::mySuperFunction(int value)
+{
+   ...
+}
+
+void DerivedClass::mySuperFunction(int value)
+{
+    SUPER(DerivedClass, mySuperFunction, value);
+
+    // This is equivalent to:
+    // BaseClass::mySuperFunction(value);
+}
+}}}
+
+The advantage is that you don't have to write "BaseClass" to call the super-function but "DerivedClass". This means you don't have to rely on the class hierarchy.