summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPhilip Chimento <philip@endlessm.com>2013-06-28 22:06:06 -0700
committerPhilip Chimento <philip@endlessm.com>2013-06-28 22:06:06 -0700
commitcf480c9de94a74fb705d00b4c6ac8390cbfdaf6a (patch)
tree690b5040957ca0863a05be47f0bb5f828ad8d89c
parentfe90102bc9ebd808a7abe7ce060d2182399e3899 (diff)
Make EosActionButton public and document it
Rename eosactionbutton-private.h to eosactionbutton.h, make sure it gets picked up in the documentation, include it in endless.h, make all the new public API documentation complete, and put the EosActionButtonSize enum documentation on the EosActionButton page. [endlessm/eos-sdk#133]
-rw-r--r--docs/reference/endless/Makefile.am1
-rw-r--r--docs/reference/endless/endless-docs.xml2
-rw-r--r--docs/reference/endless/endless-sections.txt29
-rw-r--r--endless/Makefile.am2
-rw-r--r--endless/endless.h1
-rw-r--r--endless/eosactionbutton.c107
-rw-r--r--endless/eosactionbutton.h (renamed from endless/eosactionbutton-private.h)18
-rw-r--r--endless/eosactionmenu.c2
-rw-r--r--endless/eosenums.h2
-rw-r--r--test/test-action-menu.c1
10 files changed, 152 insertions, 13 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/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"