org.gnome.gtk

## Class StatusIcon

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.StatusIcon

-     public class StatusIcon
      extends Object

  An icon that is displayed in the notification area.

  A StatusIcon is an element that can be added to a notification area. It can be used to display information about user events that may occur (events in the sense of "something interesting", not as in GTK event signal). Examples of user events may be a new email notification, or an incoming instant message, or a completed file transfer. StatusIcons can be used to display information of an activity that is occurring in the background, such as a print job or a file copy activity. A third way of using the StatusIcon capability is to monitor an existing resource; two existing examples are laptop battery charge state from `gnome-power-manager` and the state of a wireless network connection from NetworkManager's `nm-applet` program.

  Using a StatusIcon in the notification area is generally less annoying than popping up a `Dialog`, but they are also less likely to catch user attention. Thus a StatusIcon can be used to inform the user of an important event, but not necessarily an urgent event.

  A StatusIcon can also have an associated tooltip, not to be confused with `Tooltip`. This tooltip appears in a balloon at the StatusIcon itself and can be used to convey additional information.

  Do not use as a substitute for writing an applet!. StatusIcons are frequently abused and/or over used. Only add one to your application if it conveys critical status information to the user. If it has a more utilitarian and full-time purpose, it should really be in an applet. In fact, the power and network examples above are both borderline. The battery state in particular should probably be an applet and may well move back to being one; the major argument to make it an applet is to give the user control over where the battery status is positioned on the panel; the counter argument is that in the new power management program, the battery charge state display is transitory and (by default) not shown when not charging. As you can see, it's a complex issue.

  It's essential to keep in mind that the Notification Area is itself a panel applet; if one isn't running the image displayed by the StatusIcon may not visible to the user. This is another reason to consider writing an applet... or just go all the way and write a proper daemon program. See the GNOME Human Interface Guidelines for more detailed information and policies.

  As it happens, StatusIcon does not derive from Widget for historical reasons related to the inability of some other platforms to adhere to the FreeDesktop standards properly.

  Since:
    4.0.4
  Author:
    Nat Pryce, Srichand Pendyala, Andrew Cowie

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `StatusIcon.Activate` The signal emitted when the user activates the StatusIcon.
    `static interface` | `StatusIcon.PopupMenu` The signal emitted when the user brings up the context menu of the StatusIcon.
    `static interface` | `StatusIcon.SizeChanged` Signal emitted when the size available for the StatusIcon's image changes.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StatusIcon()` Create an empty StatusIcon.
    `StatusIcon(Pixbuf pixbuf)` Create a StatusIcon that shows the specified Pixbuf.
    `StatusIcon(Stock stock)` Create a StatusIcon that shows as its image a given stock item.
    `StatusIcon(String filename)` Create a StatusIcon that displays an image file.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(StatusIcon.Activate handler)` Hook up a `StatusIcon.Activate` handler
    `void` | `connect(StatusIcon.PopupMenu handler)`
    `void` | `connect(StatusIcon.SizeChanged handler)`
    `Pixbuf` | `getPixbuf()` Returns the `Pixbuf` being displayed by the gtk.StatusIcon.
    `int` | `getSize()` Gets the size available for the image, in pixels.
    `Stock` | `getStock()` Returns the id of the stock icon being displayed by the StatusIcon.
    `ImageType` | `getStorageType()` Gets the type of representation being used by the StatusIcon to store image data.
    `boolean` | `getVisible()` Reports if the StatusIcon is visible.
    `boolean` | `isEmbedded()` Reports if the StatusIcon is embedded in a notification area.
    `void` | `setFromFile(String filename)` Make this StatusIcon display the image in file `filename`.
    `void` | `setFromIconName(String name)` Makes this StatusIcon display the named icon from the current icon theme.
    `void` | `setFromPixbuf(Pixbuf pixbuf)` Make this StatusIcon display the supplied Pixbuf.
    `void` | `setFromStock(Stock stock)` Makes this StatusIcon display a stock icon as its image.
    `void` | `setTooltipText(String text)` Set the text of the Tooltip for the StatusIcon.
    `void` | `setVisible(boolean visible)` Shows or hides the StatusIcon.

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### StatusIcon

          public StatusIcon()

      Create an empty StatusIcon.

    - #### StatusIcon

          public StatusIcon(Pixbuf pixbuf)

      Create a StatusIcon that shows the specified Pixbuf.

    - #### StatusIcon

          public StatusIcon(Stock stock)

      Create a StatusIcon that shows as its image a given stock item.

    - #### StatusIcon

          public StatusIcon(String filename)

      Create a StatusIcon that displays an image file.
      Parameters:
        `filename` - The path of an image file.

  - ### Method Detail

    - #### connect

          public void connect(StatusIcon.Activate handler)

      Hook up a `StatusIcon.Activate` handler
      Since:
        4.0.4

    - #### connect

          public void connect(StatusIcon.PopupMenu handler)

    - #### connect

          public void connect(StatusIcon.SizeChanged handler)

    - #### getPixbuf

          public Pixbuf getPixbuf()

      Returns the `Pixbuf` being displayed by the gtk.StatusIcon. The storage type of the StatusIcon must be `EMPTY` or `PIXBUF`.
      Returns:
        the `Pixbuf` being displayed by the StatusIcon or `null` if the StatusIcon is empty.
      See Also:
        `getStorageType()`

    - #### getSize

          public int getSize()

      Gets the size available for the image, in pixels. Stock icons adapt their size automatically if the size of the notification area changes. For other storage types, the `StatusIcon.SizeChanged` signal can be used to react to size changes.

    - #### getStock

          public Stock getStock()

      Returns the id of the stock icon being displayed by the StatusIcon. The StorageType of the StatusIcon must be `EMPTY` or `STOCK`; use `getStorageType()` to find out which it is.
      Returns:
        the Stock representing of the stock icon being displayed by the StatusIcon or `null` if the StatusIcon is empty.

    - #### getStorageType

          public ImageType getStorageType()

      Gets the type of representation being used by the StatusIcon to store image data. If the StatusIcon has no image data, the return value will be `EMPTY`.

    - #### getVisible

          public boolean getVisible()

      Reports if the StatusIcon is visible. Note that being visible does not guarantee that the user can actually see the Status, there must also be a Notification Area applet running to display it; see `isEmbedded()`
      Returns:
        `true` if the StatusIcon is visible, `false` otherwise.

    - #### isEmbedded

          public boolean isEmbedded()

      Reports if the StatusIcon is embedded in a notification area. This being `true` implies that the Notification Area applet is running and added to one of the user's panels on the desktop.

      Sometimes users forget to do that, or remove their Notification Area applet by accident and don't know how to get it back. On the panel, just Right Click > Add to Panel... and select Notification Area.

    - #### setFromFile

          public void setFromFile(String filename)

      Make this StatusIcon display the image in file `filename`.
      Parameters:
        `filename` - the name of an icon file.

    - #### setFromIconName

          public void setFromIconName(String name)

      Makes this StatusIcon display the named icon from the current icon theme.

    - #### setFromPixbuf

          public void setFromPixbuf(Pixbuf pixbuf)

      Make this StatusIcon display the supplied Pixbuf.

    - #### setFromStock

          public void setFromStock(Stock stock)

      Makes this StatusIcon display a stock icon as its image.

    - #### setTooltipText

          public void setTooltipText(String text)

      Set the text of the Tooltip for the StatusIcon.
      Parameters:
        `text` - a value of `null` will remove the tooltip if there is one presently set.
      Since:
        4.0.16

    - #### setVisible

          public void setVisible(boolean visible)

      Shows or hides the StatusIcon. This is equivalent to the more familiar `hide()` functionality you'll be used to with Widgets.
      Parameters:
        `visible` - `true` to show the StatusIcon, `false` to hide it.