From 28c758b032d97be0848447db8c6509d5ff16dbd1 Mon Sep 17 00:00:00 2001
From: Joel Holdsworth <joel@joel-desktop.(none)>
Date: Sat, 24 Jan 2009 15:54:19 +0000
Subject: [PATCH] Tidied and documented TimelineHeaderWidget

---
 .../timeline/timeline-header-widget.hpp       | 57 ++++++++++++++++++-
 1 file changed, 54 insertions(+), 3 deletions(-)

diff --git a/src/gui/widgets/timeline/timeline-header-widget.hpp b/src/gui/widgets/timeline/timeline-header-widget.hpp
index 93ae93b8d..62a33cb9d 100644
--- a/src/gui/widgets/timeline/timeline-header-widget.hpp
+++ b/src/gui/widgets/timeline/timeline-header-widget.hpp
@@ -35,16 +35,24 @@ namespace timeline {
 
 class Track;
 
+/**
+ * TimelineHeaderWidget is the base implementation of all header widgets
+ * and acts as a containers for the header controls.
+ **/
 class TimelineHeaderWidget : public Gtk::Container
 {
 public:
+  /**
+   * Constructor
+   * @param timeline_track The timeline track that owns this header
+   * widget
+   **/
   TimelineHeaderWidget(timeline::Track &timeline_track);
 
   void set_child_widget(Widget& child);
 
 private:
   /* ===== Overrides ===== */
-private:
 
   /**
    * An event handler for the window realized signal.
@@ -56,8 +64,18 @@ private:
    */
   void on_unrealize();
 
-  //Overrides:
+  /**
+   * An event handler that is called to offer an allocation to this
+   * widget.
+   * @param requisition The area offered for this widget.
+   */
   void on_size_request(Gtk::Requisition* requisition);
+  
+  /**
+   * An event handler that is called to notify this widget to allocate
+   * a given area for itself.
+   * @param allocation The area to allocate for this widget.
+   */
   void on_size_allocate(Gtk::Allocation& allocation);
   
   /**
@@ -83,10 +101,26 @@ private:
    */
   bool on_motion_notify_event (GdkEventMotion* event);
 
-  void forall_vfunc(gboolean include_internals, GtkCallback callback, gpointer callback_data);
+  /**
+   * Applies a given function to all the widgets in the container.
+   **/
+  void forall_vfunc(gboolean include_internals, GtkCallback callback,
+    gpointer callback_data);
 
+  /**
+   * A notification of when a widget is added to this container.
+   **/
   void on_add(Gtk::Widget* child);
+  
+  /**
+   * A notification of when a widget is removed to this container.
+   **/
   void on_remove(Gtk::Widget* child);
+  
+  /**
+   * An implementation of the a container function that specifies the
+   * types of child widget that this widget will accept.
+   **/
   GtkType child_type_vfunc() const;
 
   /**
@@ -101,12 +135,29 @@ private:
 
 private:
 
+  /**
+   * A reference to the timeline track that owns this widget.
+   **/
   timeline::Track &track;
 
+  /**
+   * The widget placed inside this container.
+   * @remarks This value is set to NULL if the container is empty
+   **/
   Gtk::Widget* widget;
   
+  /**
+   * This value is true if the mouse hovering over the expander.
+   * @remarks This value is updated by on_motion_notify_event
+   **/
   bool hoveringExpander;
   
+  /**
+   * This value is true if the mouse button is depressed over the
+   * expander.
+   * @remarks This value is updated by on_button_press_event and
+   * on_button_release_event
+   **/
   bool clickedExpander;
   
   /**