Code examples

This page contains few examples of usage.

Basic notification

Following example show basic usage of zroya. First, zroya.TrayIcon instance is created. It is the main center for all notification manipulation. As long as this object exists, you may create notifications, receive events and run callbacks.

Second line creates simple notification with title and text. Since icon and callback parameters are omnited, info icon will be used with no events attached to this notification.

from zroya import TrayIcon

nc = TrayIcon() # 1
nc.create("Info", "This is informative notification.\nClick me!") # 2

Notification

Because of Windows limitations, you can create only one notification at the time. If you have one notification running, creating another one will result in TrayIcon.create method returning False.

# Zroya is imported, nc contains TrayIcon instance

nc.create("Info", "This is informative notification.\nClick me!")

Events

Zroya supports three event types. Each one corresponds with some notification action.

First of them is on_click. This event is fired when user clicks on notification. It does not depend whether it is during timeout (notification is shown over the tray bar) or after it (notification is in Windows notification center).

on_show is event fired right after notification is created.

on_hide is the last of supported notification event. It is fired when notification is closed by user.

You may register one or all of above mentioned events for each notification. When calling zroya.TrayIcon.create(), pass function name as value to one of on_* parameters.

# zroya is imported, nc contains TrayIcon instance

nc.create("Info", "Text does not matter now",
    on_click = on_click_callback,
    on_hide = on_hide_callback,
    on_show = on_show_callback
)

Callbacks

Each callback should be function or method of following form:

def callback(data):
    """
    This is general callback for zroya.
    :param dict data:   All data used when creating corresponding notification.
    """

    # Your code here
    pass

Data parameter consist of following keys:

data = {
    "title": "Notification title",
    "message": "Original notification text",
    "icon": "Path to notification icon, or one of TrayIcon.ICON_*",
    "sound": "True/False value. Should sound be played when notification appears?"
}

Event loop

This may be the most important part of events example. Because zroya depends on win32 library, it shares bit of its mechanics. On of them is application event loop. This loop takes care of running corresponding actions for each event.

Zroya uses method zroya.TrayIcon.update(). It polls all waiting events, runs user defined callbacks and then pass the execution to default Windows event handler.

You should call it periodically in your application main loop. Without is, event callbacks won’t work.

Icons

For most cases, using system default info icon is enought. This icon will be used as default.

In other cases, you may specify, which icon should be displayed next to notification text. Zroya offers three basic types:

zroya.TrayIcon.ICON_INFO is default icon.

zroya.TrayIcon.ICON_ERROR shows red cross:

zroya.TrayIcon.ICON_WARNING shows yellow warning sign:

Following code generates warning notification:

# zroya is imported, nc contains TrayIcon instance

nc.create("Test", "Test", icon=TrayIcon.ICON_WARNING) #1

In additional to those icons, zroya supports user defined icons. Just pass absolute path to icon file (.ico, .bmp) as icon parameter of zroya.TrayIcon.create() method.

# zroya is imported, nc contains TrayIcon instance

nc.create("Test", "Test", icon="C:\\Path\To\\My\\Image.ico") #1

Sound effects

Last feature of zroya is probably muting sound for notification. When creating a new one, passing False to zroya.TrayIcon.create() parameter sound will mute its sound.

# zroya is imported, nc contains TrayIcon instance

nc.create("No Sound", "No sound for this notification", sound=False) #1