First pass at Comment API

include/core/SkCanvas.h

 
 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 
 #ifndef SkCanvas_DEFINED
@@ skipping 834 matching lines @@
                               const SkColor colors[], SkXfermode* xmode,
                               const uint16_t indices[], int indexCount,
                               const SkPaint& paint);
 
     /** Send a blob of data to the canvas.
         For canvases that draw, this call is effectively a no-op, as the data
         is not parsed, but just ignored. However, this call exists for
         subclasses like SkPicture's recording canvas, that can store the data
         and then play it back later (via another call to drawData).
      */
-    virtual void drawData(const void* data, size_t length);
+    virtual void drawData(const void* data, size_t length) {
+        // do nothing. Subclasses may do something with the data
+    }
+
+    /** Add comments. beginCommentGroup/endCommentGroup open/close a new group. 
+        Each comment added via addComment is notionally attached to its 
+        enclosing group. Top-level comments simply belong to no group.
+     */
+    virtual void beginCommentGroup(const char* description) {
+        // do nothing. Subclasses may do something
+    }
+    virtual void addComment(const char* kywd, const char* value) {
+        // do nothing. Subclasses may do something
+    }
+    virtual void endCommentGroup() {
+        // do nothing. Subclasses may do something
+    }
+
 
     //////////////////////////////////////////////////////////////////////////
 
     /** Get the current bounder object.
         The bounder's reference count is unchaged.
         @return the canva's bounder (or NULL).
     */
     SkBounder*  getBounder() const { return fBounder; }
 
     /** Set a new bounder (or NULL).
@@ skipping 265 matching lines @@
             fCanvas->restoreToCount(fSaveCount);
             fCanvas = NULL;
         }
     }
 
 private:
     SkCanvas*   fCanvas;
     int         fSaveCount;
 };
 
+/** Stack helper class to automatically open and close a comment block
+ */
+class SkAutoCommentBlock : SkNoncopyable {
+public:
+    SkAutoCommentBlock(SkCanvas* canvas, const char* description) {
+        fCanvas = canvas;
+        if (NULL != fCanvas) {
+            fCanvas->beginCommentGroup(description);
+        }
+    }
+
+    ~SkAutoCommentBlock() {
+        if (NULL != fCanvas) {
+            fCanvas->endCommentGroup();
+        }
+    }
+
+private:
+    SkCanvas* fCanvas;
+};
+
 #endif