diff options
| -rw-r--r-- | docs/reference/endless/Makefile.am | 1 | ||||
| -rw-r--r-- | docs/reference/endless/endless-docs.xml | 2 | ||||
| -rw-r--r-- | docs/reference/endless/endless-sections.txt | 29 | ||||
| -rw-r--r-- | endless/Makefile.am | 2 | ||||
| -rw-r--r-- | endless/endless.h | 1 | ||||
| -rw-r--r-- | endless/eosactionbutton.c | 107 | ||||
| -rw-r--r-- | endless/eosactionbutton.h (renamed from endless/eosactionbutton-private.h) | 18 | ||||
| -rw-r--r-- | endless/eosactionmenu.c | 2 | ||||
| -rw-r--r-- | endless/eosenums.h | 2 | ||||
| -rw-r--r-- | test/Makefile.am | 4 | ||||
| -rw-r--r-- | test/run-tests.c | 1 | ||||
| -rw-r--r-- | test/run-tests.h | 1 | ||||
| -rw-r--r-- | test/test-action-button.c | 193 | ||||
| -rw-r--r-- | test/test-action-menu.c | 1 |
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 9b0eb4f..1a7f56f 100644 --- a/endless/Makefile.am +++ b/endless/Makefile.am @@ -26,6 +26,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 \ @@ -33,7 +34,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" |