gi-gtk-3.0.17: Gtk bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Gtk.Objects.StatusIcon

Contents

Description

The “system tray” or notification area is normally used for transient icons that indicate some special state. For example, a system tray icon might appear to tell the user that they have new mail, or have an incoming instant message, or something along those lines. The basic idea is that creating an icon in the notification area is less annoying than popping up a dialog.

A StatusIcon 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 StatusIcon, 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 statusIconIsEmbedded.

On X11, the implementation follows the FreeDesktop System Tray Specification. 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 Object. Making it a widget would be impractical, since the system tray on Win32 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 Notification API which works well with Application. Also see this HowDoI.

Synopsis

Exported types

Methods

getGeometry

statusIconGetGeometry Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m (Bool, Screen, Rectangle, Orientation)

Returns: True if the location information has been filled in

Deprecated: (Since version 3.14)Use notifications

Obtains information about the location of the status icon on screen. This information can be used to e.g. position popups like notification bubbles.

See statusIconPositionMenu for a more convenient alternative for positioning menus.

Note that some platforms do not allow GTK+ to provide this information, and even on platforms that do allow it, the information is not reliable unless the status icon is embedded in a notification area, see statusIconIsEmbedded.

Since: 2.10

getGicon

statusIconGetGicon Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m (Maybe Icon)

Returns: the displayed icon, or Nothing if the image is empty

Deprecated: (Since version 3.14)Use notifications

Retrieves the Icon being displayed by the StatusIcon. The storage type of the status icon must be ImageTypeEmpty or ImageTypeGicon (see statusIconGetStorageType). The caller of this function does not own a reference to the returned Icon.

If this function fails, icon is left unchanged;

Since: 2.14

getHasTooltip

statusIconGetHasTooltip Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m Bool

Returns: current value of has-tooltip on statusIcon.

Deprecated: (Since version 3.14)Use notifications

Returns the current value of the has-tooltip property. See StatusIcon:has-tooltip for more information.

Since: 2.16

getIconName

statusIconGetIconName Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m (Maybe Text)

Returns: name of the displayed icon, or Nothing if the image is empty.

Deprecated: (Since version 3.14)Use notifications

Gets the name of the icon being displayed by the StatusIcon. The storage type of the status icon must be ImageTypeEmpty or ImageTypeIconName (see statusIconGetStorageType). The returned string is owned by the StatusIcon and should not be freed or modified.

Since: 2.10

getPixbuf

statusIconGetPixbuf Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m (Maybe Pixbuf)

Returns: the displayed pixbuf, or Nothing if the image is empty.

Deprecated: (Since version 3.14)Use notifications

Gets the Pixbuf being displayed by the StatusIcon. The storage type of the status icon must be ImageTypeEmpty or ImageTypePixbuf (see statusIconGetStorageType). The caller of this function does not own a reference to the returned pixbuf.

Since: 2.10

getScreen

statusIconGetScreen Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m Screen

Returns: a Screen.

Deprecated: (Since version 3.14)Use notifications

Returns the Screen associated with statusIcon.

Since: 2.12

getSize

statusIconGetSize Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m Int32

Returns: the size that is available for the image

Deprecated: (Since version 3.14)Use notifications

Gets the size in pixels that is available for the image. Stock icons and named icons adapt their size automatically if the size of the notification area changes. For other storage types, the size-changed signal can be used to react to size changes.

Note that the returned size is only meaningful while the status icon is embedded (see statusIconIsEmbedded).

Since: 2.10

getStock

statusIconGetStock Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m (Maybe Text)

Returns: stock id of the displayed stock icon, or Nothing if the image is empty.

Deprecated: (Since version 3.10)Use statusIconGetIconName instead.

Gets the id of the stock icon being displayed by the StatusIcon. The storage type of the status icon must be ImageTypeEmpty or ImageTypeStock (see statusIconGetStorageType). The returned string is owned by the StatusIcon and should not be freed or modified.

Since: 2.10

getStorageType

statusIconGetStorageType Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m ImageType

Returns: the image representation being used

Deprecated: (Since version 3.14)Use notifications

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 ImageTypeEmpty.

Since: 2.10

getTitle

statusIconGetTitle Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m Text

Returns: the title of the status icon

Deprecated: (Since version 3.14)Use notifications

Gets the title of this tray icon. See statusIconSetTitle.

Since: 2.18

getTooltipMarkup

statusIconGetTooltipMarkup Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m (Maybe Text)

Returns: the tooltip text, or Nothing. You should free the returned string with free when done.

Deprecated: (Since version 3.14)Use notifications

Gets the contents of the tooltip for statusIcon.

Since: 2.16

getTooltipText

statusIconGetTooltipText Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m (Maybe Text)

Returns: the tooltip text, or Nothing. You should free the returned string with free when done.

Deprecated: (Since version 3.14)Use notifications

Gets the contents of the tooltip for statusIcon.

Since: 2.16

getVisible

statusIconGetVisible Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m Bool

Returns: True if the status icon is visible

Deprecated: (Since version 3.14)Use notifications

Returns whether the status icon is visible or not. Note that being visible does not guarantee that the user can actually see the icon, see also statusIconIsEmbedded.

Since: 2.10

getX11WindowId

statusIconGetX11WindowId Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m Word32

Returns: An 32 bit unsigned integer identifier for the underlying X11 Window

Deprecated: (Since version 3.14)Use notifications

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 in order for the server to position notification windows pointing to a status icon reliably.

This function is not intended for other use cases which are more likely to be met by one of the non-X11 specific methods, such as statusIconPositionMenu.

Since: 2.14

isEmbedded

statusIconIsEmbedded Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> m Bool

Returns: True if the status icon is embedded in a notification area.

Deprecated: (Since version 3.14)Use notifications

Returns whether the status icon is embedded in a notification area.

Since: 2.10

new

statusIconNew Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> m StatusIcon

Returns: a new StatusIcon

Deprecated: (Since version 3.14)Use notifications

Creates an empty status icon object.

Since: 2.10

newFromFile

statusIconNewFromFile Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> [Char]

filename: a filename

-> m StatusIcon

Returns: a new StatusIcon

Deprecated: (Since version 3.14)Use notifications

Creates a status icon displaying the file filename.

The image will be scaled down to fit in the available space in the notification area, if necessary.

Since: 2.10

newFromGicon

statusIconNewFromGicon Source #

Arguments

:: (HasCallStack, MonadIO m, IsIcon a) 
=> a

icon: a Icon

-> m StatusIcon

Returns: a new StatusIcon

Deprecated: (Since version 3.14)Use notifications

Creates a status icon displaying a Icon. If the icon is a themed icon, it will be updated when the theme changes.

Since: 2.14

newFromIconName

statusIconNewFromIconName Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Text

iconName: an icon name

-> m StatusIcon

Returns: a new StatusIcon

Deprecated: (Since version 3.14)Use notifications

Creates a status icon displaying an icon from the current icon theme. If the current icon theme is changed, the icon will be updated appropriately.

Since: 2.10

newFromPixbuf

statusIconNewFromPixbuf Source #

Arguments

:: (HasCallStack, MonadIO m, IsPixbuf a) 
=> a

pixbuf: a Pixbuf

-> m StatusIcon

Returns: a new StatusIcon

Deprecated: (Since version 3.14)Use notifications

Creates a status icon displaying pixbuf.

The image will be scaled down to fit in the available space in the notification area, if necessary.

Since: 2.10

newFromStock

statusIconNewFromStock Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Text

stockId: a stock icon id

-> m StatusIcon

Returns: a new StatusIcon

Deprecated: (Since version 3.10)Use statusIconNewFromIconName instead.

Creates a status icon displaying a stock icon. Sample stock icon names are STOCK_OPEN, STOCK_QUIT. You can register your own stock icon names, see iconFactoryAddDefault and iconFactoryAdd.

Since: 2.10

positionMenu

statusIconPositionMenu Source #

Arguments

:: (HasCallStack, MonadIO m, IsMenu a, IsStatusIcon b) 
=> a

menu: the Menu

-> Int32

x: return location for the x position

-> Int32

y: return location for the y position

-> b

userData: the status icon to position the menu on

-> m (Int32, Int32, Bool) 

Deprecated: (Since version 3.14)Use notifications

Menu positioning function to use with menuPopup to position menu aligned to the status icon userData.

Since: 2.10

setFromFile

statusIconSetFromFile Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> [Char]

filename: a filename

-> m () 

Deprecated: (Since version 3.14)Use notifications

Makes statusIcon display the file filename. See statusIconNewFromFile for details.

Since: 2.10

setFromGicon

statusIconSetFromGicon Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a, IsIcon b) 
=> a

statusIcon: a StatusIcon

-> b

icon: a GIcon

-> m () 

Deprecated: (Since version 3.14)Use notifications

Makes statusIcon display the Icon. See statusIconNewFromGicon for details.

Since: 2.14

setFromIconName

statusIconSetFromIconName Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> Text

iconName: an icon name

-> m () 

Deprecated: (Since version 3.14)Use notifications

Makes statusIcon display the icon named iconName from the current icon theme. See statusIconNewFromIconName for details.

Since: 2.10

setFromPixbuf

statusIconSetFromPixbuf Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a, IsPixbuf b) 
=> a

statusIcon: a StatusIcon

-> Maybe b

pixbuf: a Pixbuf or Nothing

-> m () 

Deprecated: (Since version 3.14)Use notifications

Makes statusIcon display pixbuf. See statusIconNewFromPixbuf for details.

Since: 2.10

setFromStock

statusIconSetFromStock Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> Text

stockId: a stock icon id

-> m () 

Deprecated: (Since version 3.10)Use statusIconSetFromIconName instead.

Makes statusIcon display the stock icon with the id stockId. See statusIconNewFromStock for details.

Since: 2.10

setHasTooltip

statusIconSetHasTooltip Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> Bool

hasTooltip: whether or not statusIcon has a tooltip

-> m () 

Deprecated: (Since version 3.14)Use notifications

Sets the has-tooltip property on statusIcon to hasTooltip. See StatusIcon:has-tooltip for more information.

Since: 2.16

setName

statusIconSetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> Text

name: the name

-> m () 

Deprecated: (Since version 3.14)Use notifications

Sets the name of this tray icon. This should be a string identifying this icon. It is may be used for sorting the icons in the tray and will not be shown to the user.

Since: 2.20

setScreen

statusIconSetScreen Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a, IsScreen b) 
=> a

statusIcon: a StatusIcon

-> b

screen: a Screen

-> m () 

Deprecated: (Since version 3.14)Use notifications

Sets the Screen where statusIcon is displayed; if the icon is already mapped, it will be unmapped, and then remapped on the new screen.

Since: 2.12

setTitle

statusIconSetTitle Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> Text

title: the title

-> m () 

Deprecated: (Since version 3.14)Use notifications

Sets the title of this tray icon. This should be a short, human-readable, localized string describing the tray icon. It may be used by tools like screen readers to render the tray icon.

Since: 2.18

setTooltipMarkup

statusIconSetTooltipMarkup Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> Maybe Text

markup: the contents of the tooltip for statusIcon, or Nothing

-> m () 

Deprecated: (Since version 3.14)Use notifications

Sets markup as the contents of the tooltip, which is marked up with the [Pango text markup language][PangoMarkupFormat].

This function will take care of setting StatusIcon:has-tooltip to True and of the default handler for the StatusIcon::query-tooltip signal.

See also the StatusIcon:tooltip-markup property and tooltipSetMarkup.

Since: 2.16

setTooltipText

statusIconSetTooltipText Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> Text

text: the contents of the tooltip for statusIcon

-> m () 

Deprecated: (Since version 3.14)Use notifications

Sets text as the contents of the tooltip.

This function will take care of setting StatusIcon:has-tooltip to True and of the default handler for the StatusIcon::query-tooltip signal.

See also the StatusIcon:tooltip-text property and tooltipSetText.

Since: 2.16

setVisible

statusIconSetVisible Source #

Arguments

:: (HasCallStack, MonadIO m, IsStatusIcon a) 
=> a

statusIcon: a StatusIcon

-> Bool

visible: True to show the status icon, False to hide it

-> m () 

Deprecated: (Since version 3.14)Use notifications

Shows or hides a status icon.

Since: 2.10

Properties

embedded

file

gicon

setStatusIconGicon :: (MonadIO m, IsStatusIcon o, IsIcon a) => o -> a -> m () Source #

hasTooltip

iconName

orientation

pixbuf

setStatusIconPixbuf :: (MonadIO m, IsStatusIcon o, IsPixbuf a) => o -> a -> m () Source #

screen

setStatusIconScreen :: (MonadIO m, IsStatusIcon o, IsScreen a) => o -> a -> m () Source #

size

stock

storageType

title

tooltipMarkup

tooltipText

visible

Signals

activate

buttonPressEvent

buttonReleaseEvent

popupMenu

queryTooltip

scrollEvent

sizeChanged