Merge pull request #142 from endlessm/issues/133

Issues/133

14 files changed, 350 insertions, 14 deletions

diff --git a/docs/reference/endless/Makefile.am b/docs/reference/endless/Makefile.am
index 00a813d..7131b0c 100644
--- a/docs/reference/endless/Makefile.am
+++ b/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
 
diff --git a/docs/reference/endless/endless-docs.xml b/docs/reference/endless/endless-docs.xml
index 1d63323..e11497c 100644
--- a/docs/reference/endless/endless-docs.xml
+++ b/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>
 
diff --git a/docs/reference/endless/endless-sections.txt b/docs/reference/endless/endless-sections.txt
index 88db2b2..a02e5c7 100644
--- a/docs/reference/endless/endless-sections.txt
+++ b/docs/reference/endless/endless-sections.txt
@@ -89,11 +89,6 @@ EosPageManagerPrivate
 </SECTION>
 
 <SECTION>
-<FILE>enums</FILE>
-EosActionButtonSize
-</SECTION>
-
-<SECTION>
 <FILE>splash-page-manager</FILE>
 EosSplashPageManager
 eos_splash_page_manager_new
@@ -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>
\ No newline at end of file
diff --git a/endless/Makefile.am b/endless/Makefile.am
index 77f8c95..db6022c 100644
--- a/endless/Makefile.am
+++ b/endless/Makefile.am
@@ -4,6 +4,7 @@ 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 \
@@ -11,7 +12,6 @@ endless_private_installed_headers = \
 	endless/eossplashpagemanager.h \
 	endless/eostypes.h \
 	endless/eoswindow.h \
-	endless/eosactionbutton-private.h \
 	endless/eosactionmenu-private.h
 
 endless_library_sources = \
diff --git a/endless/endless.h b/endless/endless.h
index 6e9d46e..afc30e7 100644
--- a/endless/endless.h
+++ b/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"
diff --git a/endless/eosactionbutton.c b/endless/eosactionbutton.c
index 14106d4..148cd2b 100644
--- a/endless/eosactionbutton.c
+++ b/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)
 {
diff --git a/endless/eosactionbutton-private.h b/endless/eosactionbutton.h
index 27dcb62..ad9c4cb 100644
--- a/endless/eosactionbutton-private.h
+++ b/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
diff --git a/endless/eosactionmenu.c b/endless/eosactionmenu.c
index 98ae77d..e3466e2 100644
--- a/endless/eosactionmenu.c
+++ b/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>
diff --git a/endless/eosenums.h b/endless/eosenums.h
index 873213d..824c99a 100644
--- a/endless/eosenums.h
+++ b/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
diff --git a/test/Makefile.am b/test/Makefile.am
index ee224e0..b4217c1 100644
--- a/test/Makefile.am
+++ b/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)
 
diff --git a/test/run-tests.c b/test/run-tests.c
index b9ce062..2e36212 100644
--- a/test/run-tests.c
+++ b/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 ();
 }
diff --git a/test/run-tests.h b/test/run-tests.h
index 39ee9b9..42cadf5 100644
--- a/test/run-tests.h
+++ b/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 */
diff --git a/test/test-action-button.c b/test/test-action-button.c
new file mode 100644
index 0000000..ba30be5
--- /dev/null
+++ b/test/test-action-button.c
@@ -0,0 +1,193 @@
+#include <gtk/gtk.h>
+#include <endless/endless.h>
+
+#include "run-tests.h"
+
+#define ADD_ACTION_BUTTON_TEST(path, test_func) \
+  g_test_add ((path), ActionButtonFixture, NULL, \
+              ab_fixture_setup, (test_func), ab_fixture_teardown)
+
+#define EXPECTED_DEFAULT_SIZE EOS_ACTION_BUTTON_SIZE_SECONDARY
+#define EXPECTED_DEFAULT_LABEL NULL
+#define EXPECTED_DEFAULT_ICON_NAME NULL
+
+#define INITIAL_SIZE EOS_ACTION_BUTTON_SIZE_PRIMARY
+#define INITIAL_LABEL "add"
+#define INITIAL_ICON_NAME "list-add-symbolic"
+
+/* When testing setters and getters, set values to these; should be different
+from INITIAL_x */
+#define EXPECTED_SIZE EOS_ACTION_BUTTON_SIZE_SECONDARY
+#define EXPECTED_LABEL "remove"
+#define EXPECTED_ICON_NAME "list-remove-symbolic"
+
+typedef struct
+{
+  GtkWidget *window;
+  EosActionButton *button;
+} ActionButtonFixture;
+
+static void
+ab_fixture_setup (ActionButtonFixture *fixture,
+                  gconstpointer        unused)
+{
+  fixture->button = EOS_ACTION_BUTTON (eos_action_button_new (INITIAL_SIZE,
+                                                              INITIAL_LABEL,
+                                                              INITIAL_ICON_NAME));
+
+  /* Place it in an offscreen window so that we can test the size */
+  fixture->window = gtk_offscreen_window_new ();
+  gtk_container_add (GTK_CONTAINER (fixture->window),
+                     GTK_WIDGET (fixture->button));
+
+  gtk_widget_show_all (GTK_WIDGET (fixture->window));
+}
+
+static void
+ab_fixture_teardown (ActionButtonFixture *fixture,
+                     gconstpointer        unused)
+{
+  gtk_widget_destroy (GTK_WIDGET (fixture->window));
+}
+
+/* TESTS */
+
+static void
+test_ab_default_properties (void)
+{
+  /* Create it using g_object_new() so that the properties are not explicitly
+  set */
+  EosActionButton *button = EOS_ACTION_BUTTON (g_object_new (EOS_TYPE_ACTION_BUTTON,
+                                                             NULL));
+  EosActionButtonSize size = eos_action_button_get_size (button);
+  const gchar *label = eos_action_button_get_label (button);
+  const gchar *icon_name = eos_action_button_get_icon_id (button);
+
+  g_assert_cmpint (size, ==, EXPECTED_DEFAULT_SIZE);
+  g_assert_cmpstr (label, ==, EXPECTED_DEFAULT_LABEL);
+  g_assert_cmpstr (icon_name, ==, EXPECTED_DEFAULT_ICON_NAME);
+}
+
+static void
+test_ab_get_set_size (ActionButtonFixture *fixture,
+                      gconstpointer        unused)
+{
+  EosActionButtonSize size;
+
+  size = eos_action_button_get_size (fixture->button);
+  g_assert_cmpint (size, ==, INITIAL_SIZE);
+
+  eos_action_button_set_size (fixture->button, EXPECTED_SIZE);
+  size = eos_action_button_get_size (fixture->button);
+  g_assert_cmpint (size, ==, EXPECTED_SIZE);
+}
+
+static void
+test_ab_prop_size (ActionButtonFixture *fixture,
+                   gconstpointer        unused)
+{
+  EosActionButtonSize size;
+
+  g_object_get (fixture->button, "size", &size, NULL);
+  g_assert_cmpint (size, ==, INITIAL_SIZE);
+
+  g_object_set (fixture->button, "size", EXPECTED_SIZE, NULL);
+  g_object_get (fixture->button, "size", &size, NULL);
+  g_assert_cmpint (size, ==, EXPECTED_SIZE);
+}
+
+static void
+test_ab_get_set_label (ActionButtonFixture *fixture,
+                       gconstpointer        unused)
+{
+  const gchar *label;
+
+  label = eos_action_button_get_label (fixture->button);
+  g_assert_cmpstr (label, ==, INITIAL_LABEL);
+
+  eos_action_button_set_label (fixture->button, EXPECTED_LABEL);
+  label = eos_action_button_get_label (fixture->button);
+  g_assert_cmpstr (label, ==, EXPECTED_LABEL);
+}
+
+static void
+test_ab_prop_label (ActionButtonFixture *fixture,
+                    gconstpointer        unused)
+{
+  gchar *label;
+
+  g_object_get (fixture->button, "label", &label, NULL);
+  g_assert_cmpstr (label, ==, INITIAL_LABEL);
+  g_free (label);
+
+  g_object_set (fixture->button, "label", EXPECTED_LABEL, NULL);
+  g_object_get (fixture->button, "label", &label, NULL);
+  g_assert_cmpstr (label, ==, EXPECTED_LABEL);
+  g_free (label);
+}
+
+static void
+test_ab_get_set_icon_name (ActionButtonFixture *fixture,
+                           gconstpointer        unused)
+{
+  const gchar *icon_name;
+
+  icon_name = eos_action_button_get_icon_id (fixture->button);
+  g_assert_cmpstr (icon_name, ==, INITIAL_ICON_NAME);
+
+  eos_action_button_set_icon_id (fixture->button, EXPECTED_ICON_NAME);
+  icon_name = eos_action_button_get_icon_id (fixture->button);
+  g_assert_cmpstr (icon_name, ==, EXPECTED_ICON_NAME);
+}
+
+static void
+test_ab_prop_icon_name (ActionButtonFixture *fixture,
+                        gconstpointer        unused)
+{
+  gchar *icon_name;
+
+  g_object_get (fixture->button, "icon-id", &icon_name, NULL);
+  g_assert_cmpstr (icon_name, ==, INITIAL_ICON_NAME);
+  g_free (icon_name);
+
+  g_object_set (fixture->button, "icon-id", EXPECTED_ICON_NAME, NULL);
+  g_object_get (fixture->button, "icon-id", &icon_name, NULL);
+  g_assert_cmpstr (icon_name, ==, EXPECTED_ICON_NAME);
+  g_free (icon_name);
+}
+
+static void
+test_ab_label_agrees (ActionButtonFixture *fixture,
+                      gconstpointer        unused)
+{
+  GtkWidget *inner_label;
+  const gchar *label_text;
+
+  inner_label = container_find_descendant_with_type (GTK_CONTAINER (fixture->button),
+                                                     GTK_TYPE_LABEL);
+  g_assert (inner_label);
+
+  label_text = gtk_label_get_text (GTK_LABEL (inner_label));
+  g_assert_cmpstr (label_text, ==, INITIAL_LABEL);
+
+  eos_action_button_set_label (fixture->button, EXPECTED_LABEL);
+  label_text = gtk_label_get_text (GTK_LABEL (inner_label));
+  g_assert_cmpstr (label_text, ==, EXPECTED_LABEL);
+}
+
+void
+add_action_button_tests (void)
+{
+  g_test_add_func ("/action-button/default-properties",
+                   test_ab_default_properties);
+  ADD_ACTION_BUTTON_TEST ("/action-button/get-set-size", test_ab_get_set_size);
+  ADD_ACTION_BUTTON_TEST ("/action-button/prop-size", test_ab_prop_size);
+  ADD_ACTION_BUTTON_TEST ("/action-button/get-set-label",
+                          test_ab_get_set_label);
+  ADD_ACTION_BUTTON_TEST ("/action-button/prop-label", test_ab_prop_label);
+  ADD_ACTION_BUTTON_TEST ("/action-button/get-set-icon-name",
+                          test_ab_get_set_icon_name);
+  ADD_ACTION_BUTTON_TEST ("/action-button/prop-icon-name",
+                          test_ab_prop_icon_name);
+  ADD_ACTION_BUTTON_TEST ("/action-button/label-agrees", test_ab_label_agrees);
+}
diff --git a/test/test-action-menu.c b/test/test-action-menu.c
index afd2397..b12ff8d 100644
--- a/test/test-action-menu.c
+++ b/test/test-action-menu.c
@@ -1,7 +1,6 @@
 #include <gtk/gtk.h>
 #include <endless/endless.h>
 
-#include <endless/eosactionbutton-private.h>
 #include <endless/eosactionmenu-private.h>
 
 #include "run-tests.h"