Some more documentation fixes

[~andy/gtk] / gtk / gtkcheckmenuitem.c

diff --git a/gtk/gtkcheckmenuitem.c b/gtk/gtkcheckmenuitem.c
index 850a811518ad14cfbe87b678755f420c66aacbb1..343565d2d8d4e34d4a193fbf95c65dab6b7e613f 100644 (file)
--- a/gtk/gtkcheckmenuitem.c
+++ b/gtk/gtkcheckmenuitem.c
@@ -12,9 +12,7 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
 /*
@@ -33,9 +31,25 @@
 #include "gtkmarshalers.h"
 #include "gtkprivate.h"
 #include "gtkintl.h"
+#include "a11y/gtkcheckmenuitemaccessible.h"
 
+/**
+ * SECTION:gtkcheckmenuitem
+ * @Short_description: A menu item with a check box
+ * @Title: GtkCheckMenuItem
+ *
+ * A #GtkCheckMenuItem is a menu item that maintains the state of a boolean
+ * value in addition to a #GtkMenuItem usual role in activating application
+ * code.
+ *
+ * A check box indicating the state of the boolean value is displayed
+ * at the left side of the #GtkMenuItem.  Activating the #GtkMenuItem
+ * toggles the value.
+ */
 
 
+#define INDICATOR_SIZE 16
+
 struct _GtkCheckMenuItemPrivate
 {
   guint active             : 1;
@@ -130,11 +144,13 @@ gtk_check_menu_item_class_init (GtkCheckMenuItemClass *klass)
                                                              P_("Size of check or radio indicator"),
                                                              0,
                                                              G_MAXINT,
-                                                             13,
+                                                             INDICATOR_SIZE,
                                                              GTK_PARAM_READABLE));
 
   widget_class->draw = gtk_check_menu_item_draw;
-  
+
+  gtk_widget_class_set_accessible_type (widget_class, GTK_TYPE_CHECK_MENU_ITEM_ACCESSIBLE);
+
   menu_item_class->activate = gtk_check_menu_item_activate;
   menu_item_class->hide_on_activate = FALSE;
   menu_item_class->toggle_size_request = gtk_check_menu_item_toggle_size_request;
@@ -142,6 +158,15 @@ gtk_check_menu_item_class_init (GtkCheckMenuItemClass *klass)
   klass->toggled = NULL;
   klass->draw_indicator = gtk_real_check_menu_item_draw_indicator;
 
+  /**
+   * GtkCheckMenuItem::toggled:
+   * @checkmenuitem: the object which received the signal.
+   *
+   * This signal is emitted when the state of the check box is changed.
+   *
+   * A signal handler can use gtk_check_menu_item_get_active()
+   * to discover the new state.
+   */
   check_menu_item_signals[TOGGLED] =
     g_signal_new (I_("toggled"),
                   G_OBJECT_CLASS_TYPE (gobject_class),
@@ -212,12 +237,27 @@ gtk_check_menu_item_sync_action_properties (GtkActivatable *activatable,
                                          gtk_toggle_action_get_draw_as_radio (GTK_TOGGLE_ACTION (action)));
 }
 
+/**
+ * gtk_check_menu_item_new:
+ *
+ * Creates a new #GtkCheckMenuItem.
+ *
+ * Returns: a new #GtkCheckMenuItem.
+ */
 GtkWidget*
 gtk_check_menu_item_new (void)
 {
   return g_object_new (GTK_TYPE_CHECK_MENU_ITEM, NULL);
 }
 
+/**
+ * gtk_check_menu_item_new_with_label:
+ * @label: the string to use for the label.
+ *
+ * Creates a new #GtkCheckMenuItem with a label.
+ *
+ * Returns: a new #GtkCheckMenuItem.
+ */
 GtkWidget*
 gtk_check_menu_item_new_with_label (const gchar *label)
 {
@@ -230,13 +270,14 @@ gtk_check_menu_item_new_with_label (const gchar *label)
 /**
  * gtk_check_menu_item_new_with_mnemonic:
  * @label: The text of the button, with an underscore in front of the
- *         mnemonic character
- * @returns: a new #GtkCheckMenuItem
+ *     character
  *
  * Creates a new #GtkCheckMenuItem containing a label. The label
  * will be created using gtk_label_new_with_mnemonic(), so underscores
  * in @label indicate the mnemonic for the menu item.
- **/
+ *
+ * Returns: a new #GtkCheckMenuItem
+ */
 GtkWidget*
 gtk_check_menu_item_new_with_mnemonic (const gchar *label)
 {
@@ -246,6 +287,13 @@ gtk_check_menu_item_new_with_mnemonic (const gchar *label)
                        NULL);
 }
 
+/**
+ * gtk_check_menu_item_set_active:
+ * @check_menu_item: a #GtkCheckMenuItem.
+ * @is_active: boolean value indicating whether the check box is active.
+ *
+ * Sets the active state of the menu item's check box.
+ */
 void
 gtk_check_menu_item_set_active (GtkCheckMenuItem *check_menu_item,
                                 gboolean          is_active)
@@ -296,6 +344,12 @@ gtk_check_menu_item_toggle_size_request (GtkMenuItem *menu_item,
   *requisition = indicator_size + toggle_spacing;
 }
 
+/**
+ * gtk_check_menu_item_toggled:
+ * @check_menu_item: a #GtkCheckMenuItem.
+ *
+ * Emits the #GtkCheckMenuItem::toggled signal.
+ */
 void
 gtk_check_menu_item_toggled (GtkCheckMenuItem *check_menu_item)
 {
@@ -504,7 +558,7 @@ gtk_real_check_menu_item_draw_indicator (GtkCheckMenuItem *check_menu_item,
 
       if (priv->active ||
           priv->always_show_toggle ||
-          (gtk_widget_get_state_flags (widget) & GTK_STATE_FLAG_PRELIGHT))
+          (state & GTK_STATE_FLAG_PRELIGHT))
         {
           gtk_style_context_save (context);
 
@@ -513,9 +567,6 @@ gtk_real_check_menu_item_draw_indicator (GtkCheckMenuItem *check_menu_item,
           else if (priv->active)
             state |= GTK_STATE_FLAG_ACTIVE;
 
-          if (!gtk_widget_is_sensitive (widget))
-            state |= GTK_STATE_FLAG_INSENSITIVE;
-
           gtk_style_context_set_state (context, state);
 
           if (priv->draw_as_radio)