java-gnome
public class StatusIcon extends Object
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.
| 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 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.
|
| 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.
|
public StatusIcon()
public StatusIcon(Pixbuf pixbuf)
public StatusIcon(Stock stock)
public StatusIcon(String filename)
filename - The path of an image file.public void connect(StatusIcon.Activate handler)
StatusIcon.Activate handlerpublic void connect(StatusIcon.PopupMenu handler)
public void connect(StatusIcon.SizeChanged handler)
public Pixbuf getPixbuf()
Pixbuf being displayed by the gtk.StatusIcon. The
storage type of the StatusIcon must be EMPTY or
PIXBUF.Pixbuf being displayed by the StatusIcon or
null if the StatusIcon is empty.getStorageType()public int getSize()
StatusIcon.SizeChanged signal can
be used to react to size changes.public Stock getStock()
EMPTY or
STOCK; use getStorageType() to find out which it is.null if the StatusIcon is empty.public ImageType getStorageType()
EMPTY.public boolean getVisible()
isEmbedded()true if the StatusIcon is visible,
false otherwise.public boolean isEmbedded()
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.
public void setFromFile(String filename)
filename.filename - the name of an icon file.public void setFromIconName(String name)
public void setFromPixbuf(Pixbuf pixbuf)
public void setFromStock(Stock stock)
public void setTooltipText(String text)
text - a value of null will remove the tooltip if
there is one presently set.public void setVisible(boolean visible)
hide() functionality you'll be used to with
Widgets.visible - true to show the StatusIcon, false
to hide it.