Issues/133

docs/reference/endless/Makefile.am

@@ -52,7 +52,6 @@ EXTRA_HFILES=
 IGNORE_HFILES= eosinit-private.h \
                eostopbar-private.h \
                eosmainarea-private.h \
-               eosactionbutton-private.h \
                eosactionmenu-private.h \
                eospagemanager-private.h
 

docs/reference/endless/endless-docs.xml

@@ -20,8 +20,8 @@
         <xi:include href="xml/application.xml"/>
         <xi:include href="xml/window.xml"/>
         <xi:include href="xml/page-manager.xml"/>
-        <xi:include href="xml/enums.xml"/>
         <xi:include href="xml/splash-page-manager.xml"/>
+        <xi:include href="xml/action-button.xml"/>
         <!--<xi:include href="xml/hello.xml"/>-->
   </chapter>
 

docs/reference/endless/endless-sections.txt

@@ -88,11 +88,6 @@ eos_page_manager_transition_type_get_type
 EosPageManagerPrivate
 </SECTION>
 
-<SECTION>
-<FILE>enums</FILE>
-EosActionButtonSize
-</SECTION>
-
 <SECTION>
 <FILE>splash-page-manager</FILE>
 EosSplashPageManager
@@ -115,3 +110,27 @@ eos_splash_page_manager_get_type
 <SUBSECTION Private>
 EosSplashPageManagerPrivate
 </SECTION>
+
+<SECTION>
+<FILE>action-button</FILE>
+EosActionButton
+eos_action_button_new
+eos_action_button_get_icon_id
+eos_action_button_set_icon_id
+eos_action_button_get_label
+eos_action_button_set_label
+eos_action_button_get_size
+eos_action_button_set_size
+EosActionButtonSize
+<SUBSECTION Standard>
+EOS_ACTION_BUTTON
+EOS_ACTION_BUTTON_CLASS
+EOS_ACTION_BUTTON_GET_CLASS
+EOS_IS_ACTION_BUTTON
+EOS_IS_ACTION_BUTTON_CLASS
+EOS_TYPE_ACTION_BUTTON
+EosActionButtonClass
+eos_action_button_get_type
+<SUBSECTION Private>
+EosActionButtonPrivate
+</SECTION>

endless/Makefile.am

@@ -4,14 +4,14 @@ endless_public_installed_headers = endless/endless.h
 
 endless_private_installed_headers = \
 	endless/eosversion.h \
+	endless/eosactionbutton.h \
 	endless/eosapplication.h \
 	endless/eosenums.h \
 	endless/eosmacros.h \
 	endless/eospagemanager.h \
 	endless/eossplashpagemanager.h \
 	endless/eostypes.h \
 	endless/eoswindow.h \
-	endless/eosactionbutton-private.h \
 	endless/eosactionmenu-private.h
 
 endless_library_sources = \

endless/endless.h

@@ -12,6 +12,7 @@ G_BEGIN_DECLS
 
 /* Pull in other header files */
 #include "eostypes.h"
+#include "eosactionbutton.h"
 #include "eosapplication.h"
 #include "eospagemanager.h"
 #include "eossplashpagemanager.h"

endless/eosactionbutton.c

@@ -1,12 +1,37 @@
 /* Copyright 2013 Endless Mobile, Inc. */
 
 #include "config.h"
-#include "eosactionbutton-private.h"
+#include "eosactionbutton.h"
 
 #include <glib-object.h>
 #include <gtk/gtk.h>
 #include <math.h>
 
+/**
+ * SECTION:action-button
+ * @short_description: Buttons that the user recognizes as performing actions
+ * @title: Action buttons
+ *
+ * Any time you want to inform your user which actions are available, use an
+ * action button.
+ * For example, suppose you had a page in your application where the user could
+ * draw a picture.
+ * After finishing the picture, the user could save it or share it on Facebook.
+ * In that case, you would use two action buttons, labeled for example
+ * <quote>SAVE</quote> and <quote>SHARE</quote>, and containing icons
+ * representing saving and sharing.
+ *
+ * The buttons have a recognizable style and round border, so that it is
+ * instantly clear to the user that they represent actions.
+ *
+ * Generally, you should set the #EosPageManager:actions property on the page
+ * that you want to use action buttons on; this neatly arranges the actions
+ * in an action area on the right-hand side of the screen, placing the main
+ * action in a prominent place, and actions such as <quote>cancel</quote> on the
+ * bottom.
+ * However, you can also manually place action buttons anywhere on a page.
+ */
+
 #define _EOS_STYLE_CLASS_ACTION_BUTTON "action-button"
 
 G_DEFINE_TYPE (EosActionButton, eos_action_button, GTK_TYPE_BUTTON)
@@ -102,6 +127,14 @@ eos_action_button_class_init (EosActionButtonClass *klass)
   widget_class->get_preferred_width  = eos_action_button_get_preferred_width;
   widget_class->get_preferred_height = eos_action_button_get_preferred_height;
 
+  /**
+   * EosActionButton:size:
+   *
+   * Size for the action button; use #EosActionButtonSize to specify that the
+   * button represents a primary action, secondary, tertiary, or quaternary.
+   * #EOS_ACTION_BUTTON_SIZE_PRIMARY is the largest, and
+   * #EOS_ACTION_BUTTON_SIZE_QUATERNARY is the smallest (seldom used.)
+   */
   g_object_class_install_property (object_class,
                                    PROP_SIZE,
                                    g_param_spec_int ("size",
@@ -112,6 +145,11 @@ eos_action_button_class_init (EosActionButtonClass *klass)
                                                      EOS_ACTION_BUTTON_SIZE_SECONDARY,
                                                      G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
+  /**
+   * EosActionButton:label:
+   *
+   * Text for the label that is placed below or to the side of the button.
+   */
   g_object_class_install_property (object_class,
                                    PROP_LABEL,
                                    g_param_spec_string ("label",
@@ -120,6 +158,11 @@ eos_action_button_class_init (EosActionButtonClass *klass)
                                                         NULL,
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
+  /**
+   * EosActionButton:icon-id:
+   *
+   * Icon name for the icon that is drawn within the circular button.
+   */
   g_object_class_install_property (object_class,
                                    PROP_ICON_ID,
                                    g_param_spec_string ("icon-id",
@@ -195,6 +238,17 @@ eos_action_button_init (EosActionButton *self)
 
 /* ******* LIFECYCLE ******* */
 
+/**
+ * eos_action_button_new:
+ * @size: size for the button: primary, secondary, et cetera
+ * @label: text to place under or beside the action button
+ * @icon_id: icon name for the icon inside the action button
+ *
+ * Convenience function for creating an action button with the size, label, and
+ * icon already set.
+ *
+ * Returns: a pointer to the newly-created widget.
+ */
 GtkWidget *
 eos_action_button_new (EosActionButtonSize size,
                        const gchar *label,
@@ -277,6 +331,14 @@ eos_action_button_load_icon (EosActionButton *button)
   gtk_image_set_from_pixbuf (GTK_IMAGE (priv->icon_image), priv->icon_pixbuf);
 }
 
+/**
+ * eos_action_button_set_size:
+ * @button: the button
+ * @size: a value from #EosActionButtonSize
+ *
+ * Sets the size of the button (e.g. secondary).
+ * See #EosActionButton:size for more information.
+ */
 void
 eos_action_button_set_size  (EosActionButton *button,
                              EosActionButtonSize size)
@@ -305,6 +367,15 @@ eos_action_button_set_size  (EosActionButton *button,
     }
 }
 
+/**
+ * eos_action_button_get_size:
+ * @button: the button
+ *
+ * Gets the size of the button (e.g. secondary).
+ * See #EosActionButton:size for more information.
+ *
+ * Returns: the size as a value from #EosActionButtonSize
+ */
 EosActionButtonSize
 eos_action_button_get_size (EosActionButton *button)
 {
@@ -317,6 +388,14 @@ eos_action_button_get_size (EosActionButton *button)
   return priv->size;
 }
 
+/**
+ * eos_action_button_set_label:
+ * @button: the button
+ * @label: text for the label
+ *
+ * Sets the text showing below or beside the button.
+ * See #EosActionButton:label for more information.
+ */
 void
 eos_action_button_set_label (EosActionButton *button, const gchar *label)
 {
@@ -335,6 +414,15 @@ eos_action_button_set_label (EosActionButton *button, const gchar *label)
   g_object_notify (G_OBJECT (button), "label");
 }
 
+/**
+ * eos_action_button_get_label:
+ * @button: the button
+ *
+ * Gets the text showing below or beside the button.
+ * See #EosActionButton:label for more information.
+ *
+ * Returns: the label text
+ */
 const gchar *
 eos_action_button_get_label (EosActionButton *button)
 {
@@ -347,6 +435,14 @@ eos_action_button_get_label (EosActionButton *button)
   return priv->label;
 }
 
+/**
+ * eos_action_button_set_icon_id:
+ * @button: the button
+ * @icon_id: an icon name
+ *
+ * Sets a new icon showing in the button, specified by icon name.
+ * See #EosActionButton:icon-id for more information.
+ */
 void
 eos_action_button_set_icon_id (EosActionButton *button,
                                const gchar* icon_id)
@@ -366,6 +462,15 @@ eos_action_button_set_icon_id (EosActionButton *button,
     }
 }
 
+/**
+ * eos_action_button_get_icon_id:
+ * @button: the button
+ *
+ * Gets the icon name for the icon showing in the button.
+ * See #EosActionButton:icon-id for more information.
+ *
+ * Returns: an icon name
+ */
 const gchar *
 eos_action_button_get_icon_id (EosActionButton *button)
 {

endless/eosactionbutton-private.h → endless/eosactionbutton.h

@@ -35,6 +35,11 @@ typedef struct _EosActionButton EosActionButton;
 typedef struct _EosActionButtonClass EosActionButtonClass;
 typedef struct _EosActionButtonPrivate EosActionButtonPrivate;
 
+/**
+ * EosActionButton:
+ *
+ * This class structure contains no public members.
+ */
 struct _EosActionButton
 {
   GtkButton parent;
@@ -45,27 +50,38 @@ struct _EosActionButton
 struct _EosActionButtonClass
 {
   GtkButtonClass parent_class;
+
+  /* For further expansion */
+  gpointer _padding[8];
 };
 
+EOS_SDK_ALL_API_VERSIONS
 GType               eos_action_button_get_type    (void) G_GNUC_CONST;
 
+EOS_SDK_ALL_API_VERSIONS
 GtkWidget          *eos_action_button_new         (EosActionButtonSize size,
                                                    const gchar        *label,
                                                    const gchar        *icon_id);
 
+EOS_SDK_ALL_API_VERSIONS
 void                eos_action_button_set_size    (EosActionButton    *button,
                                                    EosActionButtonSize size);
 
+EOS_SDK_ALL_API_VERSIONS
 EosActionButtonSize eos_action_button_get_size    (EosActionButton    *button);
 
+EOS_SDK_ALL_API_VERSIONS
 void                eos_action_button_set_label   (EosActionButton    *button,
                                                    const gchar        *label);
 
+EOS_SDK_ALL_API_VERSIONS
 const gchar        *eos_action_button_get_label   (EosActionButton    *button);
 
+EOS_SDK_ALL_API_VERSIONS
 void                eos_action_button_set_icon_id (EosActionButton    *button,
-                                                   const gchar        *stock_id);
+                                                   const gchar        *icon_id);
 
+EOS_SDK_ALL_API_VERSIONS
 const gchar        *eos_action_button_get_icon_id (EosActionButton    *button);
 
 G_END_DECLS

endless/eosactionmenu.c

@@ -3,7 +3,7 @@
 #include "config.h"
 #include "eosactionmenu-private.h"
 
-#include "eosactionbutton-private.h"
+#include "eosactionbutton.h"
 #include <glib-object.h>
 #include <gtk/gtk.h>
 #include <math.h>

endless/eosenums.h

@@ -9,7 +9,7 @@
 
 /* Shared typedefs for enumerations */
 
-/**
+/*
  * SECTION:enums
  * @Short_description: Public enumerated types used throughout the Endless SDK
  * @Title: Standard Enumerations

test/Makefile.am

@@ -15,7 +15,9 @@ test_run_tests_SOURCES = \
 	test/test-page-manager.c \
 	test/test-splash-page-manager.c \
 	test/test-window.c \
-	test/test-action-menu.c
+	test/test-action-menu.c \
+	test/test-action-button.c \
+	$(NULL)
 test_run_tests_CPPFLAGS = $(TEST_FLAGS)
 test_run_tests_LDADD = $(TEST_LIBS)
 

test/run-tests.c

@@ -93,6 +93,7 @@ main (int    argc,
   add_page_manager_tests ();
   add_splash_page_manager_tests ();
   add_action_menu_tests ();
+  add_action_button_tests ();
 
   return g_test_run ();
 }

test/run-tests.h

@@ -38,5 +38,6 @@ void add_window_tests                        (void);
 void add_page_manager_tests                  (void);
 void add_splash_page_manager_tests           (void);
 void add_action_menu_tests                   (void);
+void add_action_button_tests                 (void);
 
 #endif /* RUN_TESTS_H */