Documentation of the Text and Font dialog

(bzr r10991)

2 files changed, 49 insertions, 18 deletions

diff --git a/src/ui/dialog/text-edit.cpp b/src/ui/dialog/text-edit.cpp
index 046d0e513..4e2003d07 100644
--- a/src/ui/dialog/text-edit.cpp
+++ b/src/ui/dialog/text-edit.cpp
@@ -7,8 +7,9 @@
  *   bulia byak <buliabyak@users.sf.net>
  *   Johan Engelen <goejendaagh@zonnet.nl>
  *   Abhishek Sharma
+ *   John Smith
  *
- * Copyright (C) 1999-2007 Authors
+ * Copyright (C) 1999-2012 Authors
  * Copyright (C) 2000-2001 Ximian, Inc.
  *
  * Released under GNU GPL, read the file 'COPYING' for more information
@@ -102,7 +103,7 @@ TextEdit::TextEdit()
     GtkWidget *px = sp_icon_new( Inkscape::ICON_SIZE_SMALL_TOOLBAR, INKSCAPE_ICON("text_line_spacing") );
     layout_hbox.pack_start(*Gtk::manage(Glib::wrap(px)), false, false);
 
-/**
+/*
 This would introduce dependency on gtk version 2.24 which is currently not available in
 Trisquel GNU/Linux 4.5.1 (released on May 25th, 2011)
 This conditional and its #else block can be deleted in the future.
@@ -116,7 +117,7 @@ This conditional and its #else block can be deleted in the future.
 
     const gchar *spacings[] = {"50%", "80%", "90%", "100%", "110%", "120%", "130%", "140%", "150%", "200%", "300%", NULL};
     for (int i = 0; spacings[i]; i++) {
-/**
+/*
 This would introduce dependency on gtk version 2.24 which is currently not available in
 Trisquel GNU/Linux 4.5.1 (released on May 25th, 2011)
 This conditional and its #else block can be deleted in the future.
@@ -209,9 +210,6 @@ TextEdit::~TextEdit()
     deskTrack.disconnect();
 }
 
-/*
- * Function to style the radio buttons with tooltips and icons
- */
 void TextEdit::styleButton(Gtk::RadioButton *button, gchar const *tooltip, gchar const *icon_name, Gtk::RadioButton *group_button )
 {
     GtkWidget *icon = sp_icon_new( Inkscape::ICON_SIZE_SMALL_TOOLBAR, icon_name );
@@ -245,10 +243,7 @@ void TextEdit::onSelectionModified(guint flags )
 
     onReadSelection (style, content);
 }
-/**
- * Called whenever something 'changes' on canvas
- * Gets the currently selected item from the canvas and sets all the controls in this dialog to the correct state
- */
+
 void TextEdit::onReadSelection ( gboolean dostyle, gboolean docontent )
 {
     if (blocked)
@@ -496,7 +491,7 @@ SPCSSAttr *TextEdit::getTextStyle ()
         // Note that CSS 1.1 does not support line-height; we set it for consistency, but also set
         // sodipodi:linespacing for backwards compatibility; in 1.2 we use line-height for flowtext
 
-/**
+/*
 This would introduce dependency on gtk version 2.24 which is currently not available in
 Trisquel GNU/Linux 4.5.1 (released on May 25th, 2011)
 This conditional and its #else block can be deleted in the future.
diff --git a/src/ui/dialog/text-edit.h b/src/ui/dialog/text-edit.h
index 7d599a32c..84b032eb8 100644
--- a/src/ui/dialog/text-edit.h
+++ b/src/ui/dialog/text-edit.h
@@ -5,8 +5,10 @@
  *   Lauris Kaplinski <lauris@ximian.com>
  *   bulia byak <buliabyak@users.sf.net>
  *   Johan Engelen <goejendaagh@zonnet.nl>
+ *   John Smith
+ *   Kris De Gussem <Kris.DeGussem@gmail.com>
  *
- * Copyright (C) 1999-2007 Authors
+ * Copyright (C) 1999-2012 Authors
  * Copyright (C) 2000-2001 Ximian, Inc.
  *
  * Released under GNU GPL, read the file 'COPYING' for more information
@@ -37,23 +39,46 @@ namespace UI {
 namespace Dialog {
 
 #define VB_MARGIN 4
-
+/**
+ * The TextEdit class defines the Text and font dialog.
+ * 
+ * The Text and font dialog allows you to set the font family, style and size
+ * and shows a preview of the result. The dialogs layout settings include
+ * horizontal and vertical alignment and inter line distance.
+ */
 class TextEdit : public UI::Widget::Panel {
 public:
     TextEdit();
     virtual ~TextEdit();
 
+    /**
+     * Helper function which returns a new instance of the dialog.
+     * getInstance is needed by the dialog manager (Inkscape::UI::Dialog::DialogManager).
+     */
     static TextEdit &getInstance() { return *new TextEdit(); }
 
 protected:
 
     /**
-     * Callbacks for button presses and change handlers
+     * Callback for pressing the default button.
      */
     void onSetDefault ();
+
+    /**
+     * Callback for pressing the apply button.
+     */
     void onApply ();
     void onSelectionChange ();
     void onSelectionModified (guint flags);
+    
+    /**
+     * Called whenever something 'changes' on canvas.
+     * 
+     * onReadSelection gets the currently selected item from the canvas and sets all the controls in this dialog to the correct state.
+     * 
+     * @param dostyle Indicates whether the modification of the user includes a style change.
+     * @param content Indicates whether the modification of the user includes a style change. Actually refers to the question if we do want to show the content? (Parameter currently not used)
+     */
     void onReadSelection (gboolean style, gboolean content);
     void onToggle ();
     static void onLineSpacingChange (GtkComboBox* widget, gpointer data);
@@ -61,13 +86,17 @@ protected:
     static void onFontChange (SPFontSelector *fontsel, font_instance *font, TextEdit *self);
 
     /**
-     * Functions to get the selected text off the main canvas
+     * Get the selected text off the main canvas.
      */
     SPItem *getSelectedTextItem (void);
+
+    /**
+     * Count the number of text objects in the selection on the canvas.
+     */
     unsigned getSelectedTextCount (void);
 
     /**
-     * Helper function to create markup from a font definition and display in the preview label
+     * Helper function to create markup from a font definition and display in the preview label.
      */
     void setPreviewText (font_instance *font, Glib::ustring phrase);
 
@@ -75,7 +104,14 @@ protected:
     SPCSSAttr *getTextStyle ();
 
     /**
-     * Helper function to style radio buttons with icons, tooltips
+     * Helper function to style radio buttons with icons, tooltips.
+     * 
+     * styleButton is used when creating the dialog.
+     * 
+     * @param button pointer to the button which is created
+     * @param tooltip pointer to its tooltip string
+     * @param iconname string identifying the icon to be shown
+     * @param group_button group to which the radio button belongs to
      */
     void styleButton(Gtk::RadioButton *button, gchar const *tooltip, gchar const *iconname, Gtk::RadioButton *group_button  );
 
@@ -93,7 +129,7 @@ protected:
 
 private:
 
-    /**
+    /*
      * All the dialogs widgets
      */
     Gtk::Notebook notebook;