GNOME.org
 

[gtk/gtk-3-22] docs: Add proper deprecation text for GtkStatusIcon

commit bd13a5a5ce004496648f3d3463b8b71e2fd9a10c
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Feb 13 11:12:26 2018 +0000

    docs: Add proper deprecation text for GtkStatusIcon
    
    We link to the HowDoI for GNotification in the class description, but we
    should be more verbose in the deprecation notices for each function of
    the GtkStatusIcon class.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=743975

 gtk/deprecated/gtkstatusicon.c | 192 ++++++++++++++++++++++++++++-------------
 1 file changed, 132 insertions(+), 60 deletions(-)
---
diff --git a/gtk/deprecated/gtkstatusicon.c b/gtk/deprecated/gtkstatusicon.c
index b33a296751..28535df491 100644
--- a/gtk/deprecated/gtkstatusicon.c
+++ b/gtk/deprecated/gtkstatusicon.c
@@ -70,24 +70,31 @@
  *
  * A #GtkStatusIcon object can be used to display an icon in a “system tray”.
  * The icon can have a tooltip, and the user can interact with it by
- * activating it or popping up a context menu. Critical information should
- * not solely be displayed in a #GtkStatusIcon, since it may not be
- * visible (e.g. when the user doesn’t have a notification area on his panel).
- * This can be checked with gtk_status_icon_is_embedded().
+ * activating it or popping up a context menu.
+ *
+ * It is very important to notice that status icons depend on the existence
+ * of a notification area being available to the user; you should not use status
+ * icons as the only way to convey critical information regarding your application,
+ * as the notification area may not exist on the user's environment, or may have
+ * been removed. You should always check that a status icon has been embedded into
+ * a notification area by using gtk_status_icon_is_embedded(), and gracefully
+ * recover if the function returns %FALSE.
  *
  * On X11, the implementation follows the
  * [FreeDesktop System Tray Specification](http://www.freedesktop.org/wiki/Specifications/systemtray-spec).
  * Implementations of the “tray” side of this specification can
  * be found e.g. in the GNOME 2 and KDE panel applications.
  *
- * Note that a GtkStatusIcon is not a widget, but just
- * a #GObject. Making it a widget would be impractical, since the system tray
- * on Win32 doesn’t allow to embed arbitrary widgets.
+ * Note that a GtkStatusIcon is not a widget, but just a #GObject. Making it a
+ * widget would be impractical, since the system tray on Windows doesn’t allow
+ * to embed arbitrary widgets.
  *
  * GtkStatusIcon has been deprecated in 3.14. You should consider using
  * notifications or more modern platform-specific APIs instead. GLib provides
- * the #GNotification API which works well with #GtkApplication. Also see this
- * [HowDoI](https://wiki.gnome.org/HowDoI/GNotification).
+ * the #GNotification API which works well with #GtkApplication on multiple
+ * platforms and environments, and should be the preferred mechanism to notify
+ * the users of transient status updates. See this [HowDoI](https://wiki.gnome.org/HowDoI/GNotification)
+ * for code examples.
  */
 
 
@@ -1192,8 +1199,9 @@ gtk_status_icon_get_property (GObject    *object,
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications
+ */
 GtkStatusIcon *
 gtk_status_icon_new (void)
 {
@@ -1213,8 +1221,9 @@ gtk_status_icon_new (void)
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications
+ */
 GtkStatusIcon *
 gtk_status_icon_new_from_pixbuf (GdkPixbuf *pixbuf)
 {
@@ -1236,8 +1245,9 @@ gtk_status_icon_new_from_pixbuf (GdkPixbuf *pixbuf)
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications
+ */
 GtkStatusIcon *
 gtk_status_icon_new_from_file (const gchar *filename)
 {
@@ -1259,8 +1269,9 @@ gtk_status_icon_new_from_file (const gchar *filename)
  *
  * Since: 2.10
  *
- * Deprecated: 3.10: Use gtk_status_icon_new_from_icon_name() instead.
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications
+ */
 GtkStatusIcon *
 gtk_status_icon_new_from_stock (const gchar *stock_id)
 {
@@ -1281,8 +1292,9 @@ gtk_status_icon_new_from_stock (const gchar *stock_id)
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications
+ */
 GtkStatusIcon *
 gtk_status_icon_new_from_icon_name (const gchar *icon_name)
 {
@@ -1302,8 +1314,9 @@ gtk_status_icon_new_from_icon_name (const gchar *icon_name)
  *
  * Since: 2.14
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications
+ */
 GtkStatusIcon *
 gtk_status_icon_new_from_gicon (GIcon *icon)
 {
@@ -1776,8 +1789,10 @@ gtk_status_icon_take_image (GtkStatusIcon      *status_icon,
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; you can use g_notification_set_icon()
+ *   to associate a #GIcon with a notification
+ */
 void
 gtk_status_icon_set_from_pixbuf (GtkStatusIcon *status_icon,
                                 GdkPixbuf     *pixbuf)
@@ -1799,8 +1814,10 @@ gtk_status_icon_set_from_pixbuf (GtkStatusIcon *status_icon,
  *
  * Since: 2.10 
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; you can use g_notification_set_icon()
+ *   to associate a #GIcon with a notification
+ */
 void
 gtk_status_icon_set_from_file (GtkStatusIcon *status_icon,
                               const gchar   *filename)
@@ -1852,8 +1869,10 @@ gtk_status_icon_set_from_stock (GtkStatusIcon *status_icon,
  *
  * Since: 2.10 
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; you can use g_notification_set_icon()
+ *   to associate a #GIcon with a notification
+ */
 void
 gtk_status_icon_set_from_icon_name (GtkStatusIcon *status_icon,
                                    const gchar   *icon_name)
@@ -1875,8 +1894,10 @@ gtk_status_icon_set_from_icon_name (GtkStatusIcon *status_icon,
  *
  * Since: 2.14
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; you can use g_notification_set_icon()
+ *   to associate a #GIcon with a notification
+ */
 void
 gtk_status_icon_set_from_gicon (GtkStatusIcon *status_icon,
                                 GIcon         *icon)
@@ -1900,8 +1921,11 @@ gtk_status_icon_set_from_gicon (GtkStatusIcon *status_icon,
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function, and #GNotification only supports #GIcon
+ *   instances
+ */
 GtkImageType
 gtk_status_icon_get_storage_type (GtkStatusIcon *status_icon)
 {
@@ -1924,8 +1948,10 @@ gtk_status_icon_get_storage_type (GtkStatusIcon *status_icon)
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
+ */
 GdkPixbuf *
 gtk_status_icon_get_pixbuf (GtkStatusIcon *status_icon)
 {
@@ -1981,8 +2007,10 @@ gtk_status_icon_get_stock (GtkStatusIcon *status_icon)
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
+ */
 const gchar *
 gtk_status_icon_get_icon_name (GtkStatusIcon *status_icon)
 {
@@ -2011,8 +2039,10 @@ gtk_status_icon_get_icon_name (GtkStatusIcon *status_icon)
  *
  * Since: 2.14
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
+ */
 GIcon *
 gtk_status_icon_get_gicon (GtkStatusIcon *status_icon)
 {
@@ -2042,8 +2072,11 @@ gtk_status_icon_get_gicon (GtkStatusIcon *status_icon)
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function, as the representation of a notification
+ *   is left to the platform
+ */
 gint
 gtk_status_icon_get_size (GtkStatusIcon *status_icon)
 {
@@ -2063,7 +2096,10 @@ gtk_status_icon_get_size (GtkStatusIcon *status_icon)
  *
  * Since: 2.12
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function, as GTK typically only has one #GdkScreen
+ *   and notifications are managed by the platform
  */
 void
 gtk_status_icon_set_screen (GtkStatusIcon *status_icon,
@@ -2087,7 +2123,9 @@ gtk_status_icon_set_screen (GtkStatusIcon *status_icon,
  *
  * Since: 2.12
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function, as notifications are managed by the platform
  */
 GdkScreen *
 gtk_status_icon_get_screen (GtkStatusIcon *status_icon)
@@ -2111,8 +2149,10 @@ gtk_status_icon_get_screen (GtkStatusIcon *status_icon)
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function, as notifications are managed by the platform
+ */
 void
 gtk_status_icon_set_visible (GtkStatusIcon *status_icon,
                             gboolean       visible)
@@ -2172,8 +2212,10 @@ gtk_status_icon_set_visible (GtkStatusIcon *status_icon,
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
+ */
 gboolean
 gtk_status_icon_get_visible (GtkStatusIcon *status_icon)
 {
@@ -2194,8 +2236,10 @@ gtk_status_icon_get_visible (GtkStatusIcon *status_icon)
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
+ */
 gboolean
 gtk_status_icon_is_embedded (GtkStatusIcon *status_icon)
 {
@@ -2231,8 +2275,10 @@ gtk_status_icon_is_embedded (GtkStatusIcon *status_icon)
  * 
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
- **/
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; notifications do not have menus,
+ *   but can have buttons, and actions associated with each button
+ */
 void
 gtk_status_icon_position_menu (GtkMenu  *menu,
                               gint     *x,
@@ -2385,7 +2431,10 @@ gtk_status_icon_position_menu (GtkMenu  *menu,
  *
  * Since: 2.10
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function, as the platform is responsible for the
+ *   presentation of notifications
  */
 gboolean
 gtk_status_icon_get_geometry (GtkStatusIcon    *status_icon,
@@ -2440,7 +2489,10 @@ gtk_status_icon_get_geometry (GtkStatusIcon    *status_icon,
  *
  * Since: 2.16
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function, but notifications can display an arbitrary
+ *   amount of text using g_notification_set_body()
  */
 void
 gtk_status_icon_set_has_tooltip (GtkStatusIcon *status_icon,
@@ -2489,7 +2541,9 @@ gtk_status_icon_set_has_tooltip (GtkStatusIcon *status_icon,
  *
  * Since: 2.16
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
  */
 gboolean
 gtk_status_icon_get_has_tooltip (GtkStatusIcon *status_icon)
@@ -2531,7 +2585,9 @@ gtk_status_icon_get_has_tooltip (GtkStatusIcon *status_icon)
  *
  * Since: 2.16
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
  */
 void
 gtk_status_icon_set_tooltip_text (GtkStatusIcon *status_icon,
@@ -2587,7 +2643,9 @@ gtk_status_icon_set_tooltip_text (GtkStatusIcon *status_icon,
  *
  * Since: 2.16
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
  */
 gchar *
 gtk_status_icon_get_tooltip_text (GtkStatusIcon *status_icon)
@@ -2631,7 +2689,9 @@ gtk_status_icon_get_tooltip_text (GtkStatusIcon *status_icon)
  *
  * Since: 2.16
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
  */
 void
 gtk_status_icon_set_tooltip_markup (GtkStatusIcon *status_icon,
@@ -2677,7 +2737,9 @@ gtk_status_icon_set_tooltip_markup (GtkStatusIcon *status_icon,
  *
  * Since: 2.16
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
  */
 gchar *
 gtk_status_icon_get_tooltip_markup (GtkStatusIcon *status_icon)
@@ -2710,6 +2772,7 @@ gtk_status_icon_get_tooltip_markup (GtkStatusIcon *status_icon)
  * @status_icon: a #GtkStatusIcon
  *
  * This function is only useful on the X11/freedesktop.org platform.
+ *
  * It returns a window ID for the widget in the underlying
  * status icon implementation.  This is useful for the Galago 
  * notification service, which can send a window ID in the protocol 
@@ -2725,7 +2788,9 @@ gtk_status_icon_get_tooltip_markup (GtkStatusIcon *status_icon)
  *
  * Since: 2.14
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
  */
 guint32
 gtk_status_icon_get_x11_window_id (GtkStatusIcon *status_icon)
@@ -2753,7 +2818,9 @@ gtk_status_icon_get_x11_window_id (GtkStatusIcon *status_icon)
  *
  * Since: 2.18
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; you should use g_notification_set_title()
+ *   and g_notification_set_body() to present text inside your notification
  */
 void
 gtk_status_icon_set_title (GtkStatusIcon *status_icon,
@@ -2791,7 +2858,9 @@ gtk_status_icon_set_title (GtkStatusIcon *status_icon,
  *
  * Since: 2.18
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function
  */
 const gchar *
 gtk_status_icon_get_title (GtkStatusIcon *status_icon)
@@ -2830,7 +2899,10 @@ gtk_status_icon_get_title (GtkStatusIcon *status_icon)
  *
  * Since: 2.20
  *
- * Deprecated: 3.14: Use notifications
+ * Deprecated: 3.14: Use #GNotification and #GtkApplication to
+ *   provide status notifications; there is no direct replacement
+ *   for this function, as notifications are associated with a
+ *   unique application identifier by #GApplication
  */
 void
 gtk_status_icon_set_name (GtkStatusIcon *status_icon,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]