Fit Page to Drawing or Selection With Margins
===============================================================================
Alex Leone (acleone ~AT~ gmail.com), 2009-12-24


Goals:
===============================================================================
- Pass margin information to fit page by selection


Implementation:
===============================================================================
- We need a way to pass margins to src/document.cpp: SPDocument::fitToRect(...)
  The problem is that the current verb API doesn't allow for passing of extra
  parameters to verb listeners.
- Solution: We have to use a registered widget
  (see ui/widget/registered-widget.cpp), which stores it's value in the XML,
  under <sodipodi:namedview id="base">.
  
  This patch uses the attributes:
  "fit-margin-units", "fit-margin-top", "fit-margin-left", "fit-margin-right",
  "fit-margin-bottom".

- To read these values in fitToRect, we use
  SPNamedView *nv = sp_document_namedview(this, 0);
  Inkscape::XML::Node *nv_repr = SP_OBJECT_REPR (nv);
  gchar const * const units_abbr = nv_repr->attribute("fit-margin-units");
  // etc...
  
- We also need only the events fired by the "Fit page to selection" button to
  add margins when calling fitToRect, so we have to add another parameter to
  fitToRect, with_margins = false.
- This means we also need to pass this paramter in selection-chemistry.cpp:
  fit_canvas_to_selection_or_drawing.


Bugs:
===============================================================================
- One pre-existing bug: if you press "Fit page to selection" while editing
  nodes, then the node handles move.
  Steps to reproduce:
  1. Open the document properties dialog (Shift-Ctrl-D)
  2. Draw a rectangle
  3. Without de-selecting the rectangle (there still should be node boxes at
     the corners), press the "Fit page to selection" in the document properties
     dialog.
  4. The node boxes should move off the corners of the rectangle.
  
  
Future:
===============================================================================
- This patch supports percentage margins but there's no way to select % with
  the units dropdown created by RegisteredUnitMenu.
- Add support for export dialog.
- Don't use the namedview registry to pass the margin information; pass data
  through the verb.cpp api (which doesn't support this currently).
- Add a "Fit page to selection on save" checkbox in the document properties.


Development Notes:
===============================================================================
- There's no function that parses a RegisteredScalarUnit string, e.g. "12px".
  One does exist in svg/svg.h but it doesn't use the new unit api.  This
  function should probably be in xml/repr.h
- There is a way to pass data to listeners with sp_action_perform(action, NULL)
  where the second parameter is a void pointer, but src/helper/action.cpp needs
  to free this void pointer after all the handlers are serviced.


Call Chain:
===============================================================================
- The dialog is in src/ui/dialog/document-properties.cpp
- The "Fit page to selection" button is in src/ui/widget/page-sizer.cpp
- The button fires "fire_fit_canvas_to_selection_or_drawing" on line 487
- Which calls sp_action_perform(action, NULL) (src/helper/action.cpp:161)
- Which calls avector->perform(action, listener->data, data) line 181, where
  avector = (SPActionEventVector *) listener->vector;
- void (* perform)(SPAction *action, void *ldata, void *pdata);
- src/verbs.cpp:2149 FitCanvasVerb::perform(SPAction *action, void *data,
                                            void */*pdata*/)
- 2164:fit_canvas_to_selection_or_drawing(dt)
- src/selection-chemistry.cpp:2973
  fit_canvas_to_selection_or_drawing(SPDesktop *desktop)
- fit_canvas_to_drawing(SPDocument *doc) 2957:doc->fitToRect(*bbox);
- src/document.cpp:601 void SPDocument::fitToRect(Geom::Rect const &rect)