Systray implementation design

[proneon267]

I will implement systray support. But, I have not forgotten about #1890, which I will be implementing later on.

As the systray implementation is overlapping with notification implementation(especially on winforms), hence I think that a new class is needed. This will represent the app's icon in the System Tray(Windows) or status bar or notification area(for mobile).

I am not sure about the naming of the class, as calling it systray icon would be confusing for other platforms. Hence, I have came up with NotificationAreaIcon or StatusAreaIcon.

The App class will have an instance of the StatusAreaIcon that will be automatically instantiated(with default settings) on the first access of Toga.App.StatusAreaIcon.

The following will be the members and methods of StatusAreaIcon:

• icon - Gets and sets the icon of type Toga.Image().
• description - Gets and sets the string representing the current status of the app or the progress of the work that the app is doing currently. Or more specifically the tooltip of the StatusAreaIcon.
• show - boolean to show/hide the StatusAreaIcon
• add_to_menu("Name of the option", on_press=None) - Adds a single option to the StatusAreaIcon menu with a handler.
• add_to_menu(options=[("Name of the option1", on_press=None), ("Name of the option2", on_press=None),..]) - Adds multiple options to the StatusAreaIcon menu.
• remove_from_menu("Name of the option") - Remove an option from the menu.

What else do you think that needs to be in this API?
Related: #97 #1890 #907

[freakboy3742]

We're highly unlikely to add a "menu" API when we've managed to develop an entire App and Toolbar API that allows for app menus without once using the word "menu" in an API.

Another big gap in this API proposal is the "systray-only app". This proposal seems to be aimed at apps that have a main window and have a systray icon, but the much more pressing use case I can see is an app whose systray is the "main window".

[proneon267]

Well in that case, how does add_option() and remove_option() sound like?

As for "systray-only" app, I agree with you. I hadn't considered an app without any MainWindow. Is there any particular reason that the app can't just hide the MainWindow when it wants to be "systray-only"?

Generally, most systray apps( like apps that operate entirely in systray like a "cpu status" app that's in systray) provide an option in their context menu to bring up their MainWindow.

So, would showing and hiding the MainWindow would not be sufficient?

[freakboy3742]

Well in that case, how does add_option() and remove_option() sound like?

The issue isn't the name. It's the entire pattern you're proposing for constructing a menu.

3 questions for you that might be illuminating:

1. How do you add a menu to a Toga app?
2. How do you add a button to a Toga toolbar?
3. Why would the API for adding a menu to an app, or a button to a toolbar, be substantially different to the API for adding a menu to a systray?

As for "systray-only" app, I agree with you. I hadn't considered an app without any MainWindow. Is there any particular reason that the app can't just hide the MainWindow when it wants to be "systray-only"?

Yes, there's a very good reason. A macOS app isn't required to have a Main Window. I believe the same is true of GTK as well.

In terms of Toga's API - in the case of a DocumentApp, there literally isn't a main window. There's a window for each document; and when you start the app, there isn't necessarily a document open.

Generally, most systray apps( like apps that operate entirely in systray like a "cpu status" app that's in systray) provide an option in their context menu to bring up their MainWindow.

That's certainly a common pattern, but I wouldn't say it's universal. I've got several examples of apps in my system tray that don't have anything you could call their "main" window. The only element I'd say is universal is the preferences dialog - but that's not a main window.

[freakboy3742]

Just so we are clear, we are both talking about the context menu of the app when it is in systray, right?

Yes. Especially since the context menu of a "systray app" is the main UI of a systray app.

Are you proposing to use similar API that's used for adding commands to the toolbar?Like the API should use Toga.Command() and the user can do Toga.App.StatusAreaIcon.commands.add()?

That's a lot closer to the style of API that I'd expect (i.e., creating commands and adding them to a CommandSet). However I'd suggest the API is going to be closer to toga.App.systray.add() - if a separate API is needed at all.

To support the case of a "main window"-less app, we're likely going to need a standalone "toga.SystrayApp" - in which case, the commands on the App likely are the commands on the systray.

[proneon267]

I agree a standalone toga.SystrayApp is required.

Also, what about the naming? What should it be called? Systray?

[freakboy3742]

"System tray" is about as close as we're going to get to a shared name for this kind of feature. I'd lean towards system_tray/SystemTrayApp rather than abbreviating to systray.

[proneon267]

To support the case of a "main window"-less app, we're likely going to need a standalone "toga.SystrayApp" - in which case, the commands on the App likely are the commands on the systray.

That takes care of the API for adding options to the context menu, but what should be the behavior when the user wants the SystemTrayApp to behave like a Normal App and show a MainWindow?

There might be 3 situations:
        |->[Window Present] & [SystemTray icon Absent]
        |->[Window Present] & [SystemTray icon Present]
        |->[Window Absent] & [SystemTray icon Present]

Does that mean separate instances of Toga.App and Toga.SystemTrayApp will be needed to run in parallel, when both the Window and SystemTray will be present?

[mhsmith]

How about "StatusIcon" as a neutral name? I feel like "systray" is a bit Windows-centric, and the "area" in "StatusAreaIcon" is redundant.

To support the case of a "main window"-less app, we're likely going to need a standalone "toga.SystrayApp" - in which case, the commands on the App likely are the commands on the systray.

Why would this need a separate class? On macOS, the commands on the app appear in the menu bar at the top left when the app is focused, while the commands on the status icon appear when you click on the icon at the top right when any app is focused. They're two separate things.

Also, we should probably design the API to give the option of creating multiple icons.

[freakboy3742]

How about "StatusIcon" as a neutral name? I feel like "systray" is a bit Windows-centric, and the "area" in "StatusAreaIcon" is redundant.

I agree it's Windows specific; the only thing I'd say in the defence of that name is that the 3 or so times it's come up, the request has been for a "System tray icon". However, that may be because the people requesting it are Windows users.

I could live with StatusIcon though - a quick straw poll of some friends all hit on "Status bar" as the name of the place where these icons live; and Material Design guidelines apparently calls that area a Status Bar.

To support the case of a "main window"-less app, we're likely going to need a standalone "toga.SystrayApp" - in which case, the commands on the App likely are the commands on the systray.

Why would this need a separate class? On macOS, the commands on the app appear in the menu bar at the top left when the app is focused, while the commands on the status icon appear when you click on the icon at the top right when any app is focused. They're two separate things.

Yes - but a status bar app doesn't need to have a main window. Dropbox and Docker are good examples here - in both cases, you can interact with the app without any window being open, anything appearing in the Dock, or the app menu changing. In the case of Docker, you only get a change in the App menu when you open the Docker Desktop Dashboard.

So - we need to be able to create an app that doesn't have a main window - and toga.App requires a main window. In the case of Windows, the MainWindow is actually critical to event processing, so we need an entirely different app startup mechanism.

Also, we should probably design the API to give the option of creating multiple icons.

Can you give an example of a use case? I can't think of any apps that have multiple status bar icons.

[proneon267]

I agree :)

[proneon267]

If we can find a way to express this with a single App class, then I'm all in favor - but it isn't immediately obvious to me how we can do this without impacting on the usability of App for the "normal" use case.

I will research more and propose an API design that would comply with this idea.

[proneon267]

Proposal for the API design:
We should treat StatusIcons like Windows. This would allow us to not introduce a new App class and to have multiple StatusIcons. The app class would have a StatusIcon registry(toga.App.status_icons) similar to the Window registry(toga.App.windows). The options would be added by the existing toga.Command Resource.

To instantiate the class:

self.status_icon = toga.StatusIcon(icon: toga.Icon=None, tooltip: str=None)

To add an option to the context menu of the StatusIcon:

self.status_icon.options.add(*commands: toga.Command)

To remove an option from the context menu of the StatusIcon:

self.status_icon.options.remove(*commands: toga.Command)

To associate the StatusIcon with the app:

toga.App.status_icons += self.first_status_icon

toga.App.status_icons.add(*statusicons: toga.StatusIcon)

To show the StatusIcon:

self.status_icon.show()

To hide the StatusIcon:

self.status_icon.hide()

An example usage would be:

For apps having only StatusIcons:

def startup(self):

        self.first_status_icon = toga.StatusIcon(tooltip="First StatusIcon")
        self.status_icons += self.first_status_icon
        self.first_status_icon.options.add(cmd1, cmd2)
        self.first_status_icon.show()
        
        self.second_status_icon = toga.StatusIcon(tooltip="Second StatusIcon")
        self.status_icons += self.second_status_icon
        self.second_status_icon.options.add(cmd3, cmd4)
        self.second_status_icon.show()

Note here that there is no main_window. This is for creating "StatusIcon-only" apps.

For apps having both StatusIcons and windows:

 def startup(self):
        self.main_window = toga.MainWindow(title="Main Window")
        self.main_window.show()

        self.second_window = toga.Window(title="Second Window")
        self.windows += self.second_window
        self.second_window.show()

        self.first_status_icon = toga.StatusIcon(tooltip="First StatusIcon")
        self.status_icons += self.first_status_icon
        self.first_status_icon.options.add(cmd1, cmd2)
        self.first_status_icon.show()
        
        self.second_status_icon = toga.StatusIcon(tooltip="Second StatusIcon")
        self.status_icons += self.second_status_icon
        self.second_status_icon.options.add(cmd1, cmd2)
        self.second_status_icon.show()

For apps having only windows:

 def startup(self):
        self.main_window = toga.MainWindow(title="Main Window")
        self.main_window.show()

        self.second_window = toga.Window(title="Second Window")
        self.windows += self.second_window
        self.second_window.show()

Any changes and suggestions are welcome :)

[freakboy3742]

Once again, I'm again asking you to restrict yourself to one major new piece of work at a time. You have three major pieces in work in flight at present; and despite your statement that you understood and agreed that finishing the existing work was necessary before starting new things, you're continuing to develop designs here. Please focus on one of the major projects - preferably one that has already gotten through the design process - before continuing the design process on others.

For the sake of posterity - I have 2 critiques of this proposed design:

1. It's not clear to me why toga.StatusIcon is needed. We created an entire toolbar API without adding toga.ToobarButton or similar - why is toga.StatusIcon not just a toga.Group, and app.status_icons a normal toga.CommandSet?
2. You say we should "treat StatusIcon like a window" - but I can't see anything in this proposal where you... treat it like a window. It's a completely separate attribute. It's not added to app.windows. It doesn't take over the role of app.main_window. In what way is it being "treated like a window"? As I've indicated elsewhere, my fundamental concern here is that this API proposal requires changing the contract of toga.App so that you can no longer assume that main_window exists.

The second point is something we can change if we choose to do so - but we need to be careful that we've actually thought through the consequences. One big reason for having a different subclass: on macOS at least, the icon in the Dock is based on the app, not the windows of the app. In a "toolbar only" app, you don't want a Dock Icon, which requires changing the entire App execution mode - and the App is the first thing that is constructed, long before you've executed any code that creates a main_window.

[proneon267]

Once again, I'm again asking you to restrict yourself to one major new piece of work at a time. You have three major pieces in work in flight at present; and despite your statement that you understood and agreed that finishing the existing work was necessary before starting new things, you're continuing to develop designs here. Please focus on one of the major projects - preferably one that has already gotten through the design process - before continuing the design process on others.

Apologies, this will be my last reply on this thread, until I have completed all the existing opened PRs.

"treat StatusIcon like a window" - I did not meant that literally. toga.StatusIcon() will be a separate class. Its job will be to essentially take the role of a toga.Window() class. Like adding commands to the window, adds the commands to the toolbar. Similarly, adding commands to the toga.StatusIcon() would add the commands to the context menu of the StatusIcon. The construction of the StatusIcon's context menu would be similar to the way the commands are added to the app menu, meaning the existing patterns of toga.Group, toga.Command, etc will be used. Hence, creation of any new pattern of adding options would be avoided.

on macOS at least, the icon in the Dock is based on the app, not the windows of the app. In a "toolbar only" app, you don't want a Dock Icon, which requires changing the entire App execution mode - and the App is the first thing that is constructed, long before you've executed any code that creates a main_window.

I will research more and find a solution, but this feels like something we can solve by passing a flag parameter to the App class during its initialization to indicate, if the dock icon should be visible or not. In fact, this case is not specific to macOS only, other platforms would also need to not show app icon for a "toolbar only" app.

But, I will not continue to work on this, until I have completed the existing opened PRs.