*
* 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.
*/
*
* 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)
{
*
* 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)
{
*
* 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)
{
*
* 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)
{
*
* 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)
{
*
* 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)
{
*
* 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)
*
* 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)
*
* 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)
*
* 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)
*
* 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)
{
*
* 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)
{
*
* 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)
{
*
* 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)
{
*
* 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)
{
*
* 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,
*
* 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)
*
* 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)
*
* 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)
{
*
* 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)
{
*
* 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,
*
* 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,
*
* 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,
*
* 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)
*
* 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,
*
* 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)
*
* 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,
*
* 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)
* @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
*
* 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)
*
* 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,
*
* 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)
*
* 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,
projects / gtk+3.0.git / commitdiff