Changes between Version 12 and Version 13 of code/doc/ClassTreeMask

Timestamp:

Sep 29, 2008, 3:45:18 AM (16 years ago)

Author:

landauf

Comment:

—

code/doc/ClassTreeMask

@@ -5 +5 @@
 == Description ==
 
-The !ClassTreeMask defines a mask that includes or excludes branches and single classes in the [wiki:Identifier class-tree]. You can think of the !ClassTreeMask like a mask in computer graphics: A mask is a black/white picture where black means invisible and white means fully visible. That way you can show some parts of an image and hide others. The !ClassTreeMask does the same with the class-tree, but ''show'' means ''include'' and ''hide'' means ''exclude''. An unmodified mask shows everything / is white / includes the [wiki:BaseObject] (those statements are equivalent). '''Notation: Including or excluding a class is denoted as "adding a new rule".'''
+The !ClassTreeMask defines a mask that includes or excludes branches and single classes in the [wiki:Identifier class-tree]. You can think of the !ClassTreeMask like a mask in computer graphics: A mask is a black/white picture where black means invisible and white means fully visible. That way you can show some parts of an image and hide others. The !ClassTreeMask does the same with the class-tree, but ''show'' means ''include'' and ''hide'' means ''exclude''. An unmodified mask shows everything / is white / includes the [wiki:BaseObject] (those statements are equivalent).
+
+== Creating the mask ==
+=== Include and exclude ===
+You can include and exclude classes in the mask by calling the corresponding functions. Including/Excluding a class usually applies not only to the specified class but to all subclasses too.
+
+'''Notation: Including or excluding a class is denoted as "adding a new rule".'''
 
 The [wiki:Identifier class-tree] starts with the [wiki:BaseObject] but has some additional Interfaces that are parents of some subclasses (or "nodes" in the speak of tree-structure). Because we can't include or exclude classes directly, we use the corresponding [wiki:Identifier Identifiers] instead. '''In the following we'll speak about "classes" but implicitly mean "the [wiki:Identifier Identifiers] of those classes".'''
 
+=== The ''overwrite'' flag ===
 Including a class means: "The whole branch starting with this class gets included", unless you didn't set the ''overwrite'' flag to false. Including a class without overwriting means: "Include the whole branch starting with this class but don't include previously excluded classes". The same aplies for excluding.
 
-After including/excluding a class, the !ClassTreeMask is scanned for useless rules. If you include the [wiki:BaseObject] and include a subclass of [wiki:BaseObject] too, this brings no new information, so the inclusion-rule of the subclass can be discarded. Only rules that change the state are saved. You can turn of this cleanup by setting the ''clean'' flag to false. '''Warning''': This could change the meaning of your mask when you add further rules with ''overwrite'' set to false. If, in our example, the subclass of [wiki:BaseObject] was included without ''clean'' and afterward you exclude the [wiki:BaseObject] without ''overwrite'', the subclass stays included. You'll find some examples for this in the corresponding section of this page.
-
+=== The ''clean'' flag ===
+After including/excluding a class, the !ClassTreeMask is scanned for useless rules. If you include the [wiki:BaseObject] and include a subclass of [wiki:BaseObject] too, this brings no new information, so the inclusion-rule of the subclass can be discarded. Only rules that change the state are saved. You can turn this cleanup off by setting the ''clean'' flag to false. '''Warning''': This could change the meaning of your mask when you add further rules with ''overwrite'' set to false. If, in our example, the subclass of [wiki:BaseObject] was included without ''clean'' and afterward you exclude the [wiki:BaseObject] without ''overwrite'', the subclass stays included. You'll find some examples for this in the corresponding section of this page.
+
+=== Rules for single classes ===
 It's also possible to include/exclude only a single class wihtout changing the rule for following classes. This is achieved with the includeSingle/excludeSingle functions.
 
+=== Interfaces ===
 Including/excluding interfaces is a bit different, because interfaces aren't directly in the class-tree. Instead the !ClassTreeMask will apply the rule for all direct parents of the interfaces. If you set ''overwrite'' to false, only direct parents without an explicit rule apply the new rule. This may sound difficult, but it's really intutive. Just look at the examples.
 
@@ -20 +30 @@
 
 === Branches ===
- * '''include('''''class''''', '''''overwrite''''', '''''clean''''')''': Includes ''class'' and all following classes. If ''overwrite'' is false, only classes that weren't explicitly excluded previously are included (default is true). If ''clean'' is true, only relevant rules stay in the branch (default is true).
- * '''exclude('''''class''''', '''''overwrite''''', '''''clean''''')''': Excludes ''class'' and all following classes. If ''overwrite'' is false, only classes that weren't explicitly included previously are excluded (default is true). If ''clean'' is true, only relevant rules stay in the branch (default is true).
+ * '''include('''''class'' [''', '''''overwrite''''', '''''clean'']''')''': Includes ''class'' and all following classes. If ''overwrite'' is false, only classes that weren't explicitly excluded previously are included (default is true). If ''clean'' is true, only relevant rules stay in the branch (default is true).
+ * '''exclude('''''class'' [''', '''''overwrite''''', '''''clean'']''')''': Excludes ''class'' and all following classes. If ''overwrite'' is false, only classes that weren't explicitly included previously are excluded (default is true). If ''clean'' is true, only relevant rules stay in the branch (default is true).
 
 === Single classes ===
- * '''includeSingle('''''class''''', '''''clean''''')''': Includes ''class'' without changing the rule for following classes. If ''clean'' is true, only relevant rules stay in the branch (default is true).
- * '''excludeSingle('''''class''''', '''''clean''''')''': Excludes ''class'' without changing the rule for following classes. If ''clean'' is true, only relevant rules stay in the branch (default is true).
+ * '''includeSingle('''''class'' [''', '''''clean'']''')''': Includes ''class'' without changing the rule for following classes. If ''clean'' is true, only relevant rules stay in the branch (default is true).
+ * '''excludeSingle('''''class'' [''', '''''clean'']''')''': Excludes ''class'' without changing the rule for following classes. If ''clean'' is true, only relevant rules stay in the branch (default is true).
 
 === Tree ===
@@ -46 +56 @@
    * operator{{{^}}}, operator{{{^}}}=
 
+== Iterator ==
+Sometimes you want to iterate through all existing objects which are instances of classes included in a !ClassTreeMask. This can be achieved by using an !ClassTreeMaskObjectIterator.
+
+This is done the following way:
+{{{
+for (ClassTreeMaskObjectIterator it = mask.begin(); it != mask.end(); ++it)
+    it->doSomething();
+}}}
+
+'''Note''': The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If you want to use another class, you should use a dynamic_cast:
+{{{
+for (ClassTreeMaskObjectIterator it = mask.begin(); it != mask.end(); ++it)
+    (dynamic_cast<SomeClass*>(*it))->doSomethingAdvanced();
+}}}
+
+Performance of ClassTreeMaskObjectIterator is good as long as you don't exclude subclasses of included classes. Of course you can still exlucde subclasses, but if this is done more often, we need a new implementation using a second ObjectList in the Identifier, containing all objects of exactly one class. Including subclasses of excluded classes however is really fast.
+
 == Examples ==