gedit r6468 - in trunk: . gedit

[icq svn gnome org]

Author: icq
Date: Thu Aug 28 08:23:00 2008
New Revision: 6468
URL: http://svn.gnome.org/viewvc/gedit?rev=6468&view=rev

Log:
2008-08-28  Ignacio Casal Quinteiro  <nacho resa gmail com>

        * gedit/gedit-message-area.c:
        Added documentation.



Modified:
   trunk/ChangeLog
   trunk/gedit/gedit-message-area.c

Modified: trunk/gedit/gedit-message-area.c
==============================================================================
--- trunk/gedit/gedit-message-area.c	(original)
+++ trunk/gedit/gedit-message-area.c	Thu Aug 28 08:23:00 2008
@@ -335,6 +335,13 @@
 				    0);
 }
 
+/**
+ * gedit_message_area_set_contents:
+ * @message_area: a #GeditMessageArea
+ * @contents: widget you want to add to the contents area
+ *
+ * Adds the @contents widget to the contents area of #GeditMessageArea.
+ */
 void
 gedit_message_area_set_contents	(GeditMessageArea *message_area,
 				 GtkWidget        *contents)
@@ -350,6 +357,19 @@
 			    0);
 }
 
+/**
+ * gedit_message_area_add_button:
+ * @message_area: a #GeditMessageArea
+ * @button_text: text of button, or stock ID
+ * @response_id: response ID for the button
+ * 
+ * Adds a button with the given text (or a stock button, if button_text is a stock ID)
+ * and sets things up so that clicking the button will emit the "response" signal
+ * with the given response_id. The button is appended to the end of the message area's
+ * action area. The button widget is returned, but usually you don't need it.
+ *
+ * Returns: the button widget that was added
+ */
 GtkWidget*
 gedit_message_area_add_button (GeditMessageArea *message_area,
 			       const gchar      *button_text,
@@ -403,6 +423,16 @@
 	}
 }
 
+/**
+ * gedit_message_area_add_buttons:
+ * @message_area: a #GeditMessageArea
+ * @first_button_text: button text or stock ID
+ * @...: response ID for first button, then more text-response_id pairs
+ *
+ * Adds more buttons, same as calling gedit_message_area_add_button() repeatedly.
+ * The variable argument list should be NULL-terminated as with
+ * gedit_message_area_new_with_buttons(). Each button must have both text and response ID.
+ */
 void
 gedit_message_area_add_buttons (GeditMessageArea *message_area,
 				const gchar      *first_button_text,
@@ -419,12 +449,33 @@
 	va_end (args);
 }
 
+/**
+ * gedit_message_area_new:
+ * 
+ * Creates a new #GeditMessageArea object.
+ * 
+ * Returns: a new #GeditMessageArea object
+ */
 GtkWidget *
 gedit_message_area_new (void)
 {
 	return g_object_new (GEDIT_TYPE_MESSAGE_AREA, NULL);
 }
 
+/**
+ * gedit_message_area_new_with_buttons:
+ * @first_button_text: stock ID or text to go in first button, or NULL
+ * @...: response ID for first button, then additional buttons, ending with NULL
+ * 
+ * Creates a new #GeditMessageArea with buttons. Button text/response ID pairs 
+ * should be listed, with a NULL pointer ending the list. Button text can be either
+ * a stock ID such as GTK_STOCK_OK, or some arbitrary text. A response ID can be any
+ * positive number, or one of the values in the GtkResponseType enumeration. If 
+ * the user clicks one of these dialog buttons, GeditMessageArea will emit the "response"
+ * signal with the corresponding response ID.
+ *
+ * Returns: a new #GeditMessageArea
+ */
 GtkWidget *
 gedit_message_area_new_with_buttons (const gchar *first_button_text,
                                      ...)
@@ -445,6 +496,16 @@
 	return GTK_WIDGET (message_area);
 }
 
+/**
+ * gedit_message_area_set_response_sensitive:
+ * @message_area: a #GeditMessageArea
+ * @response_id: a response ID
+ * @setting: TRUE for sensitive
+ *
+ * Calls gtk_widget_set_sensitive (widget, setting) for each widget in the dialog's
+ * action area with the given response_id. A convenient way to sensitize/desensitize
+ * dialog buttons.
+ */
 void
 gedit_message_area_set_response_sensitive (GeditMessageArea *message_area,
 					   gint              response_id,
@@ -472,6 +533,15 @@
 	g_list_free (children);
 }
 
+/**
+ * gedit_message_area_set_default_response:
+ * @message_area: a #GeditMessageArea
+ * @response_id: a response ID
+ *
+ * Sets the last widget in the message area's action area with the given response_id
+ * as the default widget for the dialog. Pressing "Enter" normally activates the
+ * default widget.
+ */
 void
 gedit_message_area_set_default_response (GeditMessageArea *message_area,
 					 gint              response_id)
@@ -498,6 +568,13 @@
 	g_list_free (children);
 }
 
+/**
+ * gedit_message_area_set_default_response:
+ * @message_area: a #GeditMessageArea
+ * @response_id: a response ID
+ *
+ * Emits the 'response' signal with the given @response_id.
+ */
 void
 gedit_message_area_response (GeditMessageArea *message_area,
 			     gint              response_id)
@@ -510,6 +587,15 @@
 		       response_id);
 }
 
+/**
+ * gedit_message_area_add_stock_button_with_text:
+ * @message_area: a #GeditMessageArea
+ * @text: the text to visualize in the button
+ * @stock_id: the stock ID of the button
+ * @response_id: a response ID
+ *
+ * Same as gedit_message_area_add_button() but with a specific text.
+ */
 GtkWidget *
 gedit_message_area_add_stock_button_with_text (GeditMessageArea *message_area,
 				    	       const gchar      *text,