molybden::Tray Class Reference

A system tray item. More...

#include <tray.hpp>

Inheritance diagram for molybden::Tray:

Public Member Functions
virtual std::shared_ptr< App >	app ()=0
	Returns the application instance for this tray.
virtual void	setImage (const std::string &file_path)=0
	Sets the tray image from the given absolute image file path.
virtual void	setMenu (std::shared_ptr< CustomMenu > menu)=0
	Sets the pull-down menu displayed when the user clicks the tray icon.
virtual void	setTitle (const std::string &title)=0
	Sets the tray title.
virtual std::string	title () const =0
	Returns the tray title.
virtual void	setTooltip (const std::string &text)=0
	Sets the tray tooltip text.
virtual std::string	tooltip () const =0
	Returns the tray tooltip text.
virtual void	destroy ()=0
	Destroys the tray.
virtual bool	isDestroyed () const =0
	Indicates whether the tray item is destroyed.

Static Public Member Functions
static std::shared_ptr< Tray >	create (std::shared_ptr< App > app)
	Creates a new tray item for the given application and displays it in the system tray on macOS or notification aray on Windows.

Additional Inherited Members
Public Attributes inherited from molybden::TrayEvents
Event< TrayClicked >	onClicked
	Invoked when the tray has been clicked using the left mouse button.

Detailed Description

A system tray item.

The tray item is a small widget shown in the system tray on macOS or notification area on Windows. Typically, it displays an icon, but on macOS it may display icon, title, or both.

The system tray is a platform-specific feature that currently works on macOS and Windows only.

Member Function Documentation

create()

static std::shared_ptr< Tray > molybden::Tray::create ( std::shared_ptr< App >  app )

static

Creates a new tray item for the given application and displays it in the system tray on macOS or notification aray on Windows.

Each application can create and display multiple tray items.

Parameters

app	the application instance associated with the tray.

Returns

a new tray instance or nullptr if the tray is not supported on the current platform.

destroy()

virtual void molybden::Tray::destroy ( )

pure virtual

Destroys the tray.

Once the tray is destroyed, it cannot be used anymore. The methods of the destroyed tray will do nothing and return the default values.

setImage()

virtual void molybden::Tray::setImage ( const std::string &  file_path )

pure virtual

Sets the tray image from the given absolute image file path.

The image file can be PNG or JPEG. PNG is preferred, because it supports transparency and doesn't lose quality.

Recommendation: put the image in the "src-app/resources" directory and get absolute path to the image using the following approach:

tray->setImage(app->getPath(PathKey::kAppResources) + "/image.png");

High-resolution image

To support high-DPI displays, you can provide images for different scale factors by adding a suffix corresponding to the scale factor to the file name before the extension. For example, "image@2x.png" will be treated as a high-resolution image with a scale factor of 2.0.

The following scale factors are supported:

• "@1x" or "" (default), matches 100% scale factor.
• "@1.25x", matches 125% scale factor.
• "@1.5x", matches 150% scale factor.
• "@1.75x", matches 175% scale factor.
• "@2x", matches 200% scale factor.

Here is an example of a directory structure with images for different scale factors:

images/ image.png image.nosp@m.@1.5.nosp@m.x.png image.nosp@m.@2x..nosp@m.png

You need to specify the absolute path to "image.png", and Molybden will automatically pick the most suitable image for the current environment.

Template image (macOS)

On macOS, you can mark the image file as a template image by adding the "Template" suffix to the file name before the extension. For example, "imageTemplate.png" or "imageTemplate@2x.png" will be treated as a template image. The template images consist of black and an alpha channel only, and mostly used for a menu bar icon, so it can adapt to both light and dark menu bars.

Parameters

file_path

the absolute path to a PNG or JPEG file. If the given path does not exist, the tray image will not be changed.

setMenu()

virtual void molybden::Tray::setMenu ( std::shared_ptr< CustomMenu >  menu )

pure virtual

Sets the pull-down menu displayed when the user clicks the tray icon.

On different platforms, the menu may be displayed in different ways:

• On Windows, the menu is displayed when the user clicks the tray icon using the right mouse button.
• On macOS, the menu is displayed when the user clicks the tray icon using the left or right mouse button.

On Windows, the menu can have the custom menu items only. The standard menus and menu items are not supported and won't be added to the tray menu.

Parameters

menu	the tray menu.

setTitle()

virtual void molybden::Tray::setTitle ( const std::string &  title )

pure virtual

Sets the tray title.

If the tray item has an image, the title is displayed next to the image.

The tray title is supported on macOS only.

Parameters

title

the tray title.

setTooltip()

virtual void molybden::Tray::setTooltip ( const std::string &  text )

pure virtual

Sets the tray tooltip text.

The tooltip is displayed when the user hovers the mouse over the tray item.

Parameters

text	the tray tooltip text.

title()

virtual std::string molybden::Tray::title ( ) const

pure virtual

Returns the tray title.

The tray title is supported on macOS only.

---

The documentation for this class was generated from the following file:

• include/molybden/tray/tray.hpp