Some documentation

(bzr r10851)

4 files changed, 106 insertions, 131 deletions

diff --git a/src/ui/dialog/dialog.cpp b/src/ui/dialog/dialog.cpp
index 80ab49494..0a7359155 100644
--- a/src/ui/dialog/dialog.cpp
+++ b/src/ui/dialog/dialog.cpp
@@ -39,23 +39,20 @@ namespace Inkscape {
 namespace UI {
 namespace Dialog {
 
-void
-sp_retransientize(Inkscape::Application */*inkscape*/, SPDesktop *desktop, gpointer dlgPtr)
+void sp_retransientize(Inkscape::Application */*inkscape*/, SPDesktop *desktop, gpointer dlgPtr)
 {
     Dialog *dlg = (Dialog *)dlgPtr;
     dlg->onDesktopActivated (desktop);
 }
 
-gboolean
-sp_retransientize_again(gpointer dlgPtr)
+gboolean sp_retransientize_again(gpointer dlgPtr)
 {
     Dialog *dlg = (Dialog *)dlgPtr;
     dlg->retransientize_suppress = false;
     return FALSE; // so that it is only called once
 }
 
-void
-sp_dialog_shutdown(GtkObject */*object*/, gpointer dlgPtr)
+void sp_dialog_shutdown(GtkObject */*object*/, gpointer dlgPtr)
 {
     Dialog *dlg = (Dialog *)dlgPtr;
     dlg->onShutdown();
@@ -81,17 +78,6 @@ void unhideCallback(GtkObject */*object*/, gpointer dlgPtr)
 
 //=====================================================================
 
-/**
- * UI::Dialog::Dialog is a base class for all dialogs in Inkscape.  The
- * purpose of this class is to provide a unified place for ensuring
- * style and behavior.  Specifically, this class provides functionality
- * for saving and restoring the size and position of dialogs (through
- * the user's preferences file).
- *
- * It also provides some general purpose signal handlers for things like
- * showing and hiding all dialogs.
- */
-
 Dialog::Dialog(Behavior::BehaviorFactory behavior_factory, const char *prefs_path, int verb_num,
                Glib::ustring const &apply_label)
     : _user_hidden(false), 
@@ -136,29 +122,25 @@ Dialog::~Dialog()
 //---------------------------------------------------------------------
 
 
-void
-Dialog::onDesktopActivated(SPDesktop *desktop)
+void Dialog::onDesktopActivated(SPDesktop *desktop)
 {
     _behavior->onDesktopActivated(desktop);
 }
 
-void
-Dialog::onShutdown()
+void Dialog::onShutdown()
 {
     save_geometry();
     _user_hidden = true;
     _behavior->onShutdown();
 }
 
-void
-Dialog::onHideF12()
+void Dialog::onHideF12()
 {
     _hiddenF12 = true;
     _behavior->onHideF12();
 }
 
-void
-Dialog::onShowF12()
+void Dialog::onShowF12()
 {
     if (_user_hidden)
         return;
@@ -191,8 +173,7 @@ inline void Dialog::set_sensitive(bool sensitive)                { _behavior->se
 Glib::SignalProxy0<void> Dialog::signal_show() { return _behavior->signal_show(); }
 Glib::SignalProxy0<void> Dialog::signal_hide() { return _behavior->signal_hide(); }
 
-void
-Dialog::read_geometry()
+void Dialog::read_geometry()
 {
     _user_hidden = false;
 
@@ -223,8 +204,7 @@ Dialog::read_geometry()
 }
 
 
-void
-Dialog::save_geometry()
+void Dialog::save_geometry()
 {
     int y, x, w, h;
 
@@ -244,8 +224,7 @@ Dialog::save_geometry()
 
 }
 
-void
-Dialog::_handleResponse(int response_id)
+void Dialog::_handleResponse(int response_id)
 {
     switch (response_id) {
         case Gtk::RESPONSE_CLOSE: {
@@ -255,8 +234,7 @@ Dialog::_handleResponse(int response_id)
     }
 }
 
-bool
-Dialog::_onDeleteEvent(GdkEventAny */*event*/)
+bool Dialog::_onDeleteEvent(GdkEventAny */*event*/)
 {
     save_geometry();
     _user_hidden = true;
@@ -264,8 +242,7 @@ Dialog::_onDeleteEvent(GdkEventAny */*event*/)
     return false;
 }
 
-bool
-Dialog::_onEvent(GdkEvent *event)
+bool Dialog::_onEvent(GdkEvent *event)
 {
     bool ret = false;
 
@@ -298,8 +275,7 @@ Dialog::_onEvent(GdkEvent *event)
     return ret;
 }
 
-bool
-Dialog::_onKeyPress(GdkEventKey *event)
+bool Dialog::_onKeyPress(GdkEventKey *event)
 {
     unsigned int shortcut;
     shortcut = get_group0_keyval(event) |
@@ -312,23 +288,15 @@ Dialog::_onKeyPress(GdkEventKey *event)
     return sp_shortcut_invoke(shortcut, SP_ACTIVE_DESKTOP);
 }
 
-void
-Dialog::_apply()
+void Dialog::_apply()
 {
     g_warning("Apply button clicked for dialog [Dialog::_apply()]");
 }
 
-void
-Dialog::_close()
+void Dialog::_close()
 {
     GtkWidget *dlg = GTK_WIDGET(_behavior->gobj());
 
-    /* this code sends a delete_event to the dialog,
-     * instead of just destroying it, so that the
-     * dialog can do some housekeeping, such as remember
-     * its position.
-     */
-
     GdkEventAny event;
     event.type = GDK_DELETE;
     event.window = dlg->window;
@@ -343,8 +311,7 @@ Dialog::_close()
         g_object_unref(G_OBJECT(event.window));
 }
 
-void
-Dialog::_defocus()
+void Dialog::_defocus()
 {
     SPDesktop *desktop = SP_ACTIVE_DESKTOP;
 
diff --git a/src/ui/dialog/dialog.h b/src/ui/dialog/dialog.h
index 0afd5ee72..0248461d1 100644
--- a/src/ui/dialog/dialog.h
+++ b/src/ui/dialog/dialog.h
@@ -36,15 +36,33 @@ gboolean sp_retransientize_again(gpointer dlgPtr);
 void sp_dialog_shutdown(GtkObject *object, gpointer dlgPtr);
 
 /**
- * @brief Base class for Inkscape dialogs
- * This class provides certain common behaviors and styles wanted of all dialogs
- * in the application.  Fundamental parts of the dialog's behavior are controlled by
+ * Base class for Inkscape dialogs.
+ * 
+ * UI::Dialog::Dialog is a base class for all dialogs in Inkscape.  The
+ * purpose of this class is to provide a unified place for ensuring
+ * style and behavior. Specifically, this class provides functionality
+ * for saving and restoring the size and position of dialogs (through
+ * the user's preferences file).
+ *
+ * It also provides some general purpose signal handlers for things like
+ * showing and hiding all dialogs.
+ *
+ * Fundamental parts of the dialog's behavior are controlled by
  * a Dialog::Behavior subclass instance connected to the dialog.
+ *
+ * @see UI::Widget::Panel
  */
 class Dialog {
 
 public:
 
+    /**
+     * Constructor.
+     * 
+     * @param behavior_factory floating or docked
+     * @param prefs_path characteristic path to load/save 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 = "");
 
@@ -80,7 +98,14 @@ public:
     bool           _user_hidden; // when it is closed by the user, to prevent repopping on f12
     bool           _hiddenF12;
 
+    /**
+     * Load window position from preferences.
+     */
     void           read_geometry();
+    
+    /**
+     * Save window position to preferences.
+     */
     void           save_geometry();
 
     bool retransientize_suppress; // when true, do not retransientize (prevents races when switching new windows too fast)
@@ -98,6 +123,14 @@ protected:
     virtual bool   _onKeyPress(GdkEventKey *event);
 
     virtual void   _apply();
+    
+    /* Closes the dialog window.
+     *
+     * This code sends a delete_event to the dialog,
+     * instead of just destroying it, so that the
+     * dialog can do some housekeeping, such as remember
+     * its position.
+     */
     virtual void   _close();
     virtual void   _defocus();
 
diff --git a/src/ui/dialog/transformation.cpp b/src/ui/dialog/transformation.cpp
index 2b12806a6..996aaf19e 100644
--- a/src/ui/dialog/transformation.cpp
+++ b/src/ui/dialog/transformation.cpp
@@ -57,24 +57,6 @@ void on_selection_modified( Inkscape::Application */*inkscape*/,
 # C O N S T R U C T O R
 ########################################################################*/
 
-/**
- * Constructor for Transformation.  This does the initialization
- * and layout of the dialog used for transforming SVG objects.  It
- * consists of 5 pages for the 5 operations it handles:
- * 'Move' allows x,y translation of SVG objects
- * 'Scale' allows linear resizing of SVG objects
- * 'Rotate' allows rotating SVG objects by a degree
- * 'Skew' allows skewing SVG objects
- * 'Matrix' allows applying a generic affine transform on SVG objects,
- *     with the user specifying the 6 degrees of freedom manually.
- *
- * The dialog is implemented as a Gtk::Notebook with five pages.
- * The pages are implemented using Inkscape's NotebookPage which
- * is used to help make sure all of Inkscape's notebooks follow
- * the same style.  We then populate the pages with our widgets,
- * we use the ScalarUnit class for this.
- *
- */
 Transformation::Transformation()
     : UI::Widget::Panel ("", "/dialogs/transformation", SP_VERB_DIALOG_TRANSFORM),
       _page_move              (4, 2),
@@ -181,8 +163,7 @@ Transformation::~Transformation()
 # U T I L I T Y
 ########################################################################*/
 
-void
-Transformation::presentPage(Transformation::PageType page)
+void Transformation::presentPage(Transformation::PageType page)
 {
     _notebook.set_current_page(page);
     show();
@@ -197,8 +178,7 @@ Transformation::presentPage(Transformation::PageType page)
 ########################################################################*/
 
 
-void
-Transformation::layoutPageMove()
+void Transformation::layoutPageMove()
 {
     _units_move.setUnitType(UNIT_TYPE_LINEAR);
     
@@ -242,8 +222,7 @@ Transformation::layoutPageMove()
         .connect(sigc::mem_fun(*this, &Transformation::onMoveRelativeToggled));
 }
 
-void
-Transformation::layoutPageScale()
+void Transformation::layoutPageScale()
 {
     _units_scale.setUnitType(UNIT_TYPE_DIMENSIONLESS);
     _units_scale.setUnitType(UNIT_TYPE_LINEAR);
@@ -284,8 +263,7 @@ Transformation::layoutPageScale()
     //TODO: add a widget for selecting the fixed point in scaling, or honour rotation center?
 }
 
-void
-Transformation::layoutPageRotate()
+void Transformation::layoutPageRotate()
 {
     _units_rotate.setUnitType(UNIT_TYPE_RADIAL);
 
@@ -305,8 +283,7 @@ Transformation::layoutPageRotate()
     //TODO: honour rotation center?
 }
 
-void
-Transformation::layoutPageSkew()
+void Transformation::layoutPageSkew()
 {
     _units_skew.setUnitType(UNIT_TYPE_LINEAR);
     _units_skew.setUnitType(UNIT_TYPE_DIMENSIONLESS);
@@ -338,8 +315,7 @@ Transformation::layoutPageSkew()
 
 
 
-void
-Transformation::layoutPageTransform()
+void Transformation::layoutPageTransform()
 {
     _scalar_transform_a.setWidgetSizeRequest(65, -1);
     _scalar_transform_a.setRange(-1e10, 1e10);
@@ -419,8 +395,7 @@ Transformation::layoutPageTransform()
 # U P D A T E
 ########################################################################*/
 
-void
-Transformation::updateSelection(PageType page, Inkscape::Selection *selection)
+void Transformation::updateSelection(PageType page, Inkscape::Selection *selection)
 {
     if (!selection || selection->isEmpty())
         return;
@@ -455,16 +430,14 @@ Transformation::updateSelection(PageType page, Inkscape::Selection *selection)
                          selection && !selection->isEmpty());
 }
 
-void
-Transformation::onSwitchPage(GtkNotebookPage */*page*/,
+void Transformation::onSwitchPage(GtkNotebookPage */*page*/,
                                    guint pagenum)
 {
     updateSelection((PageType)pagenum, sp_desktop_selection(getDesktop()));
 }
 
 
-void
-Transformation::updatePageMove(Inkscape::Selection *selection)
+void Transformation::updatePageMove(Inkscape::Selection *selection)
 {
     if (selection && !selection->isEmpty()) {
         if (!_check_move_relative.get_active()) {
@@ -486,8 +459,7 @@ Transformation::updatePageMove(Inkscape::Selection *selection)
     }
 }
 
-void
-Transformation::updatePageScale(Inkscape::Selection *selection)
+void Transformation::updatePageScale(Inkscape::Selection *selection)
 {
     if (selection && !selection->isEmpty()) {
         Geom::OptRect bbox = selection->preferredBounds();
@@ -506,8 +478,7 @@ Transformation::updatePageScale(Inkscape::Selection *selection)
     }
 }
 
-void
-Transformation::updatePageRotate(Inkscape::Selection *selection)
+void Transformation::updatePageRotate(Inkscape::Selection *selection)
 {
     if (selection && !selection->isEmpty()) {
         _page_rotate.set_sensitive(true);
@@ -516,8 +487,7 @@ Transformation::updatePageRotate(Inkscape::Selection *selection)
     }
 }
 
-void
-Transformation::updatePageSkew(Inkscape::Selection *selection)
+void Transformation::updatePageSkew(Inkscape::Selection *selection)
 {
     if (selection && !selection->isEmpty()) {
         Geom::OptRect bbox = selection->preferredBounds();
@@ -535,8 +505,7 @@ Transformation::updatePageSkew(Inkscape::Selection *selection)
     }
 }
 
-void
-Transformation::updatePageTransform(Inkscape::Selection *selection)
+void Transformation::updatePageTransform(Inkscape::Selection *selection)
 {
     if (selection && !selection->isEmpty()) {
         if (_check_replace_matrix.get_active()) {
@@ -569,8 +538,7 @@ Transformation::updatePageTransform(Inkscape::Selection *selection)
 
 
 
-void
-Transformation::_apply()
+void Transformation::_apply()
 {
     Inkscape::Selection * const selection = _getSelection();
     if (!selection || selection->isEmpty())
@@ -605,8 +573,7 @@ Transformation::_apply()
     //setResponseSensitive(Gtk::RESPONSE_APPLY, false);
 }
 
-void
-Transformation::applyPageMove(Inkscape::Selection *selection)
+void Transformation::applyPageMove(Inkscape::Selection *selection)
 {
     double x = _scalar_move_horizontal.getValue("px");
     double y = _scalar_move_vertical.getValue("px");
@@ -693,8 +660,7 @@ Transformation::applyPageMove(Inkscape::Selection *selection)
                         _("Move"));
 }
 
-void
-Transformation::applyPageScale(Inkscape::Selection *selection)
+void Transformation::applyPageScale(Inkscape::Selection *selection)
 {
     double scaleX = _scalar_scale_horizontal.getValue("px");
     double scaleY = _scalar_scale_vertical.getValue("px");
@@ -755,8 +721,7 @@ Transformation::applyPageScale(Inkscape::Selection *selection)
                        _("Scale"));
 }
 
-void
-Transformation::applyPageRotate(Inkscape::Selection *selection)
+void Transformation::applyPageRotate(Inkscape::Selection *selection)
 {
     double angle = _scalar_rotate.getValue("deg");
 
@@ -777,8 +742,7 @@ Transformation::applyPageRotate(Inkscape::Selection *selection)
                        _("Rotate"));
 }
 
-void
-Transformation::applyPageSkew(Inkscape::Selection *selection)
+void Transformation::applyPageSkew(Inkscape::Selection *selection)
 {
     Inkscape::Preferences *prefs = Inkscape::Preferences::get();
     if (prefs->getBool("/dialogs/transformation/applyseparately")) {
@@ -837,8 +801,7 @@ Transformation::applyPageSkew(Inkscape::Selection *selection)
 }
 
 
-void
-Transformation::applyPageTransform(Inkscape::Selection *selection)
+void Transformation::applyPageTransform(Inkscape::Selection *selection)
 {
     double a = _scalar_transform_a.getValue();
     double b = _scalar_transform_b.getValue();
@@ -871,14 +834,12 @@ Transformation::applyPageTransform(Inkscape::Selection *selection)
 # V A L U E - C H A N G E D    C A L L B A C K S
 ########################################################################*/
 
-void
-Transformation::onMoveValueChanged()
+void Transformation::onMoveValueChanged()
 {
     setResponseSensitive(Gtk::RESPONSE_APPLY, true);
 }
 
-void
-Transformation::onMoveRelativeToggled()
+void Transformation::onMoveRelativeToggled()
 {
     Inkscape::Selection *selection = _getSelection();
 
@@ -909,8 +870,7 @@ Transformation::onMoveRelativeToggled()
     setResponseSensitive(Gtk::RESPONSE_APPLY, true);
 }
 
-void
-Transformation::onScaleXValueChanged()
+void Transformation::onScaleXValueChanged()
 {
     if (_scalar_scale_horizontal.setProgrammatically) {
         _scalar_scale_horizontal.setProgrammatically = false;
@@ -929,8 +889,7 @@ Transformation::onScaleXValueChanged()
     }
 }
 
-void
-Transformation::onScaleYValueChanged()
+void Transformation::onScaleYValueChanged()
 {
     if (_scalar_scale_vertical.setProgrammatically) {
         _scalar_scale_vertical.setProgrammatically = false;
@@ -949,20 +908,17 @@ Transformation::onScaleYValueChanged()
     }
 }
 
-void
-Transformation::onRotateValueChanged()
+void Transformation::onRotateValueChanged()
 {
     setResponseSensitive(Gtk::RESPONSE_APPLY, true);
 }
 
-void
-Transformation::onSkewValueChanged()
+void Transformation::onSkewValueChanged()
 {
     setResponseSensitive(Gtk::RESPONSE_APPLY, true);
 }
 
-void
-Transformation::onTransformValueChanged()
+void Transformation::onTransformValueChanged()
 {
 
     /*
@@ -980,8 +936,7 @@ Transformation::onTransformValueChanged()
     setResponseSensitive(Gtk::RESPONSE_APPLY, true);
 }
 
-void
-Transformation::onReplaceMatrixToggled()
+void Transformation::onReplaceMatrixToggled()
 {
     Inkscape::Selection *selection = _getSelection();
 
@@ -1013,15 +968,13 @@ Transformation::onReplaceMatrixToggled()
     _scalar_transform_f.setValue(new_displayed[5]);
 }
 
-void
-Transformation::onScaleProportionalToggled()
+void Transformation::onScaleProportionalToggled()
 {
     onScaleXValueChanged();
 }
 
 
-void
-Transformation::onClear()
+void Transformation::onClear()
 {
     int const page = _notebook.get_current_page();
 
@@ -1066,8 +1019,7 @@ Transformation::onClear()
     }
 }
 
-void
-Transformation::onApplySeparatelyToggled()
+void Transformation::onApplySeparatelyToggled()
 {
     Inkscape::Preferences *prefs = Inkscape::Preferences::get();
     prefs->setBool("/dialogs/transformation/applyseparately", _check_apply_separately.get_active());
diff --git a/src/ui/dialog/transformation.h b/src/ui/dialog/transformation.h
index cf6d72447..901a807a5 100644
--- a/src/ui/dialog/transformation.h
+++ b/src/ui/dialog/transformation.h
@@ -34,13 +34,36 @@ namespace Dialog {
 
 
 
+/**
+ * Transformation dialog.
+ * 
+ * The transformation dialog allows to modify Inkscape objects.
+ * 5 transformation operations are currently possible: move, scale,
+ * rotate, skew and matrix. 
+ */
 class Transformation : public UI::Widget::Panel
 {
 
 public:
 
     /**
-     * Create a new transform
+     * Constructor for Transformation.
+     * 
+     * This does the initialization
+     * and layout of the dialog used for transforming SVG objects.  It
+     * consists of 5 pages for the 5 operations it handles:
+     * 'Move' allows x,y translation of SVG objects
+     * 'Scale' allows linear resizing of SVG objects
+     * 'Rotate' allows rotating SVG objects by a degree
+     * 'Skew' allows skewing SVG objects
+     * 'Matrix' allows applying a generic affine transform on SVG objects,
+     *     with the user specifying the 6 degrees of freedom manually.
+     *
+     * The dialog is implemented as a Gtk::Notebook with five pages.
+     * The pages are implemented using Inkscape's NotebookPage which
+     * is used to help make sure all of Inkscape's notebooks follow
+     * the same style.  We then populate the pages with our widgets,
+     * we use the ScalarUnit class for this.
      */
     Transformation();