documentation

(bzr r10899)

3 files changed, 47 insertions, 33 deletions

diff --git a/src/ui/dialog/dialog.h b/src/ui/dialog/dialog.h
index 0248461d1..225484709 100644
--- a/src/ui/dialog/dialog.h
+++ b/src/ui/dialog/dialog.h
@@ -48,9 +48,10 @@ void sp_dialog_shutdown(GtkObject *object, gpointer dlgPtr);
  * showing and hiding all dialogs.
  *
  * Fundamental parts of the dialog's behavior are controlled by
- * a Dialog::Behavior subclass instance connected to the dialog.
+ * a UI::Dialog::Behavior subclass instance connected to the dialog.
  *
- * @see UI::Widget::Panel
+ * @see UI::Widget::Panel panel class from which the dialogs are actually derived from.
+ * @see UI::Dialog::DialogManager manages the dialogs within inkscape.
  */
 class Dialog {
 
@@ -59,9 +60,9 @@ public:
     /**
      * Constructor.
      * 
-     * @param behavior_factory floating or docked
-     * @param prefs_path characteristic path to load/save dialog position
-     * @param verb_num the dialog verb
+     * @param behavior_factory floating or docked.
+     * @param prefs_path characteristic path for loading/saving dialog position.
+     * @param verb_num the dialog verb.
      */
     Dialog(Behavior::BehaviorFactory behavior_factory, const char *prefs_path = NULL,
            int verb_num = 0, Glib::ustring const &apply_label = "");
@@ -71,7 +72,7 @@ public:
     virtual void onDesktopActivated(SPDesktop*);
     virtual void onShutdown();
 
-    /** Hide and show dialogs */
+    /* Hide and show dialogs */
     virtual void onHideF12();
     virtual void onShowF12();
 
@@ -99,7 +100,7 @@ public:
     bool           _hiddenF12;
 
     /**
-     * Load window position from preferences.
+     * Read window position from preferences.
      */
     void           read_geometry();
     
diff --git a/src/ui/widget/panel.cpp b/src/ui/widget/panel.cpp
index 8c8603640..4942d4bde 100644
--- a/src/ui/widget/panel.cpp
+++ b/src/ui/widget/panel.cpp
@@ -333,14 +333,12 @@ void Panel::restorePanelPrefs()
     _bounceCall(PANEL_SETTING_WRAP, panel_wrap);
 }
 
-sigc::signal<void, int> &
-Panel::signalResponse()
+sigc::signal<void, int> &Panel::signalResponse()
 {
     return _signal_response;
 }
 
-sigc::signal<void> &
-Panel::signalPresent()
+sigc::signal<void> &Panel::signalPresent()
 {
     return _signal_present;
 }
@@ -487,30 +485,26 @@ void Panel::_handleAction(int /*set_id*/, int /*item_id*/)
 // for subclasses to override
 }
 
-void
-Panel::_apply()
+void Panel::_apply()
 {
     g_warning("Apply button clicked for panel [Panel::_apply()]");
 }
 
-Gtk::Button *
-Panel::addResponseButton(const Glib::ustring &button_text, int response_id)
+Gtk::Button *Panel::addResponseButton(const Glib::ustring &button_text, int response_id)
 {
     Gtk::Button *button = new Gtk::Button(button_text);
     _addResponseButton(button, response_id);
     return button;
 }
 
-Gtk::Button *
-Panel::addResponseButton(const Gtk::StockID &stock_id, int response_id)
+Gtk::Button *Panel::addResponseButton(const Gtk::StockID &stock_id, int response_id)
 {
     Gtk::Button *button = new Gtk::Button(stock_id);
     _addResponseButton(button, response_id);
     return button;
 }
 
-void
-Panel::_addResponseButton(Gtk::Button *button, int response_id)
+void Panel::_addResponseButton(Gtk::Button *button, int response_id)
 {
     // Create a button box for the response buttons if it's the first button to be added
     if (!_action_area) {
@@ -528,8 +522,7 @@ Panel::_addResponseButton(Gtk::Button *button, int response_id)
     }
 }
 
-void
-Panel::setDefaultResponse(int response_id)
+void Panel::setDefaultResponse(int response_id)
 {
     ResponseMap::iterator widget_found;
     widget_found = _response_map.find(response_id);
@@ -541,8 +534,7 @@ Panel::setDefaultResponse(int response_id)
     }
 }
 
-void
-Panel::setResponseSensitive(int response_id, bool setting)
+void Panel::setResponseSensitive(int response_id, bool setting)
 {
     if (_response_map[response_id])
         _response_map[response_id]->set_sensitive(setting);
@@ -566,8 +558,7 @@ Panel::signalDeactiveDesktop()
     return _signal_deactive_desktop;
 }
 
-void
-Panel::_handleResponse(int response_id)
+void Panel::_handleResponse(int response_id)
 {
     switch (response_id) {
         case Gtk::RESPONSE_APPLY: {
diff --git a/src/ui/widget/panel.h b/src/ui/widget/panel.h
index 7f0f7ff3d..c8006dc1d 100644
--- a/src/ui/widget/panel.h
+++ b/src/ui/widget/panel.h
@@ -5,6 +5,7 @@
  *
  * Copyright (C) 2004 Bryce Harrington
  * Copyright (C) 2005 Jon A. Cruz
+ * Copyright (C) 2012 Kris De Gussem
  *
  * Released under GNU GPL.  Read the file 'COPYING' for more information.
  */
@@ -16,8 +17,8 @@
 #include <gtkmm.h>
 
 #include "inkscape.h"
-#include "ui/previewfillable.h"
 #include "selection.h"
+#include "ui/previewfillable.h"
 
 namespace Inkscape {
 namespace UI {
@@ -25,6 +26,14 @@ namespace Widget {
 
 /**
  * A generic dockable container.
+ *
+ * Inkscape::UI::Widget::Panel is a base class from which dockable dialogs
+ * are created. A new dockable dialog is created by deriving a class from panel.
+ * Child widgets are private data members of Panel (no need to use pointers and
+ * new).
+ *
+ * @see UI::Dialog::DesktopTracker to handle desktop change, selection change and selected object modifications.
+ * @see UI::Dialog::DialogManager manages the dialogs within inkscape.
  */
 class Panel : public Gtk::VBox {
 
@@ -33,6 +42,10 @@ public:
 
     /**
      * Construct a Panel.
+     *
+     * @param label label for the panel of a dialog, shown at the top.
+     * @param prefs_path characteristic path to load/save dialog position.
+     * @param verb_num the dialog verb.
      */
     Panel(Glib::ustring const &label = "", gchar const *prefs_path = 0,
           int verb_num = 0, Glib::ustring const &apply_label = "",
@@ -41,6 +54,10 @@ public:
     virtual ~Panel();
 
     gchar const *getPrefsPath() const;
+    
+    /**
+     * Sets a label for the panel and displays it in the panel at the top (is not the title bar of a floating dialog).
+     */
     void setLabel(Glib::ustring const &label);
     Glib::ustring const &getLabel() const;
     int const &getVerb() const;
@@ -55,12 +72,12 @@ public:
     virtual void setDesktop(SPDesktop *desktop);
     SPDesktop *getDesktop() { return _desktop; }
 
-    /** Signal accessors */
+    /* Signal accessors */
     virtual sigc::signal<void, int> &signalResponse();
     virtual sigc::signal<void> &signalPresent();
 
-    /** Methods providing a Gtk::Dialog like interface for adding buttons that emit Gtk::RESPONSE
-     *  signals on click. */
+    /* Methods providing a Gtk::Dialog like interface for adding buttons that emit Gtk::RESPONSE
+     * signals on click. */
     Gtk::Button* addResponseButton (const Glib::ustring &button_text, int response_id);
     Gtk::Button* addResponseButton (const Gtk::StockID &stock_id, int response_id);
     void setDefaultResponse(int response_id);
@@ -71,6 +88,9 @@ public:
     virtual sigc::signal<void, Inkscape::Application *, SPDesktop *> &signalDeactiveDesktop();
 
 protected:
+    /**
+     * Returns a pointer to a Gtk::Box containing the child widgets.
+     */
     Gtk::Box *_getContents() { return &_contents; }
     void _setTargetFillable(PreviewFillable *target);
     void _regItem(Gtk::MenuItem* item, int group, int id);
@@ -80,16 +100,18 @@ protected:
 
     virtual void _handleResponse(int response_id);
 
-    /** Helper methods */
+    /* Helper methods */
     void _addResponseButton(Gtk::Button *button, int response_id);
     Inkscape::Selection *_getSelection();
 
+    /**
+     * Stores characteristic path for loading/saving the dialog position.
+     */
     Glib::ustring const _prefs_path;
-
     bool _menu_desired;
     Gtk::AnchorType _anchor;
 
-    /** Signals */
+    /* Signals */
     sigc::signal<void, int> _signal_response;
     sigc::signal<void>      _signal_present;
     sigc::signal<void, SPDesktop *, SPDocument *> _signal_document_replaced;
@@ -122,7 +144,7 @@ private:
     std::vector<Gtk::Widget *> _non_vertical;
     PreviewFillable *_fillable;
 
-    /** A map to store which widget that emits a certain response signal */
+    /* A map to store which widget that emits a certain response signal */
     typedef std::map<int, Gtk::Widget *> ResponseMap;
     ResponseMap _response_map;
 };