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

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.

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)

getBlinking

public boolean getBlinking()

Reports if the StatusIcon is blinking.

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.

setBlinking

public void setBlinking(boolean setting)

Make the StatusIcon start [or stop] blinking.

Note that blinking user interface elements may be problematic for some users and may be turned off on a desktop wide level, in which case this setting would have no effect. Even ignoring the accessibility question, many people find blinking StatusIcons annoying in general. Use sparingly, if at all.

Parameters:

setting - true to start the StatusIcon blinking, false to stop it blinking.

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.

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD