Clean up a bit. Clarify several variable names. Add a lot of comments.

[inkscape.git] / src / ui / widget / page-sizer.h

diff --git a/src/ui/widget/page-sizer.h b/src/ui/widget/page-sizer.h
index d5934be0438ce09535f6788900c4031674a10952..b4b6145a808056419b2f8ee5f946172c7e6176f1 100644 (file)
--- a/src/ui/widget/page-sizer.h
+++ b/src/ui/widget/page-sizer.h
@@ -4,7 +4,7 @@
  * Author:
  *   Ralf Stephan <ralf@ark.in-berlin.de>
  *
- * Copyright (C) 2005 Authors
+ * Copyright (C) 2005-2006 Authors
  *
  * Released under GNU GPL.  Read the file 'COPYING' for more information.
  */
@@ -12,8 +12,8 @@
 #ifndef INKSCAPE_UI_WIDGET_PAGE_SIZER__H
 #define INKSCAPE_UI_WIDGET_PAGE_SIZER__H
 
-#include <sigc++/sigc++.h>
 #include <gtkmm.h>
+#include <sigc++/sigc++.h>
 #include "ui/widget/registry.h"
 #include "ui/widget/registered-widget.h"
 #include "helper/units.h"
@@ -24,13 +24,22 @@ namespace UI {
 namespace Widget {
 
 /**
- * Class used to store common paper dimensions
+ * Data class used to store common paper dimensions.  Used to make
+ * PageSizer's _paperSizeTable. 
  */ 
 class PaperSize
 {
 public:
+
+    /**
+     * Default constructor
+     */
     PaperSize()
         { init(); }
+
+    /**
+     * Main constructor.  Use this one.
+     */
     PaperSize(const Glib::ustring &nameArg,
                  double smallerArg,
                  double largerArg,
@@ -42,15 +51,46 @@ public:
            unit    = unitArg;
            }
 
+    /**
+     * Copy constructor
+     */
     PaperSize(const PaperSize &other)
         { assign(other); }
         
+    /**
+     * Assignment operator
+     */             
     PaperSize &operator=(const PaperSize &other)
         { assign(other); return *this; }
 
+    /**
+     * Destructor
+     */             
        virtual ~PaperSize()
            {}
            
+    /**
+     * Name of this paper specification
+     */             
+    Glib::ustring name;
+    
+    /**
+     * The lesser of the two dimensions
+     */             
+    double smaller;
+    
+    /**
+     * The greater of the two dimensions
+     */             
+    double larger;
+    
+    /**
+     * The units (px, pt, mm, etc) of this specification
+     */             
+    SPUnitId unit;
+
+private:
+
        void init()
            {
            name    = "";
@@ -67,10 +107,6 @@ public:
            unit    = other.unit;
         }
 
-    Glib::ustring name;
-    double smaller;
-    double larger;
-    SPUnitId unit;
 };
 
 
@@ -78,7 +114,8 @@ public:
 
 
 /**
- * Widget containing all widgets for specifying page size.
+ * A compound widget that allows the user to select the desired
+ * page size.  This widget is used in DocumentPreferences 
  */ 
 class PageSizer : public Gtk::VBox
 {
@@ -94,34 +131,63 @@ public:
      */
     virtual ~PageSizer();
 
+    /**
+     * Set up or reset this widget
+     */             
     void init (Registry& reg);
+    
+    /**
+     * Set the page size to the given dimensions.  If 'changeList' is
+     * true, then reset the paper size list to the closest match
+     */
     void setDim (double w, double h, bool changeList=true);
-    bool                 _landscape;
-
+ 
 protected:
 
+    /**
+     * Our handy table of all 'standard' paper sizes.
+     */             
+    std::map<Glib::ustring, PaperSize> paperSizeTable;
+
+    /**
+     * Find the closest standard paper size in the table, to the
+     */
     int find_paper_size (double w, double h) const;
+ 
     void fire_fit_canvas_to_selection_or_drawing();
-    void on_portrait();
-    void on_landscape();
-    void on_value_changed();
-    void on_paper_size_list_changed();
     
-    RegisteredUnitMenu   _rum;
-    RegisteredScalarUnit _rusw, _rush;
+    //### Dimension spinboxes
+    RegisteredUnitMenu   _dimensionUnits;
+    RegisteredScalarUnit _dimensionWidth;
+       RegisteredScalarUnit _dimensionHeight;
+    //callback
+    void on_value_changed();
+    sigc::connection    _changedw_connection;
+       sigc::connection    _changedh_connection;
     
-    //# Various things for a ComboBox
+    //### The Paper Size selection list
     Gtk::ComboBoxText _paperSizeList;
-    std::map<Glib::ustring, PaperSize> paperSizeTable;
+    //callback
+    void on_paper_size_list_changed();
+    sigc::connection    _paper_size_list_connection;
     
+    //### Button to select 'portrait' orientation
     Gtk::RadioButton    _portraitButton;
-       Gtk::RadioButton    _landscapeButton;
-    sigc::connection    _paper_size_list_connection;
+    //callback
+    void on_portrait();
     sigc::connection    _portrait_connection;
+
+    //### Button to select 'landscape' orientation
+       Gtk::RadioButton    _landscapeButton;
+       //callback
+    void on_landscape();
        sigc::connection    _landscape_connection;
-    sigc::connection    _changedw_connection;
-       sigc::connection    _changedh_connection;
-    Registry            *_wr;
+
+    Registry            *_widgetRegistry;
+
+    //### state - whether we are currently landscape or portrait
+    bool                 _landscape;
+
 };
 
 } // namespace Widget