Additional tray icon features
Ideas on how to implement new features requested by @C0rn3j and me.
Scroll event callbacks
Support for scroll events that get generated while user scrolls over a tray icon, both Windows and *nix (SNI and XEmbed) support this, unsure about OS X.
Here is how the API could look like:
typedef enum SDL_TrayScrollDirection
{
SDL_TRAYSCROLLDIRECTION_VERTICAL,
SDL_TRAYSCROLLDIRECTION_HORIZONTAL
} SDL_TrayScrollDirection;
typedef void (SDLCALL *SDL_TrayScrollCallback)(void *userdata, SDL_Tray *tray, SDL_TrayScrollDirection direction, Sint32 delta);
SDL_PROP_TRAY_CREATE_SCROLL_CALLBACK_POINTERThis is basically a direct mapping of the SNI verison of scroll events, Should normal int be used instead of Sint32? I chose Sint32 because that is what the SNI protocol uses for scroll deltas.
Hiding/showing icons
The ability to hide and show tray icons, all platforms support this.
I propose two API ideas:
typedef enum SDL_TrayStatus
{
SDL_TRAYSTATUS_PASSIVE,
SDL_TRAYSTATUS_ACTIVE,
SDL_TRAYSTATUS_IMPORTANT
} SDL_TrayStatus;
bool SDL_SetTrayStatus(SDL_Tray *tray, SDL_TrayStatus status) /* true if set sucessfully, false if status is unsupported */
SDL_TrayStatus SDL_GetTrayStatus(SDL_Tray *tray)void SDL_SetTrayVisibility(SDL_Tray *tray, bool visibility)
bool SDL_GetTrayVisibility(SDL_Tray *tray)All platforms and *nix tray protocols support basic hiding and showing.
Which one to use? It is important to note that the SNI specs use the term status instead of visibility and SNI tray hosts can choose to not hide "hidden" (passive) items. The SNI spec also has a "NeedsAttention" status, where tray icons are brought front and center, is a similar thing supported in other platforms? Even if we use an enum with this option instead of a bool, how do we handle platforms where it is not supported? Do we just treat it as active/visible or return a bool in SetStatus indicating the state was supported or not?
Textual descriptions of tray icons for accessibility
Seems to be only supported by SNI, requested by @C0rn3j.
Possible API:
void SDL_SetTrayIconDescription(SDL_Tray *tray, const char *desc)Do we return a bool to indicate if the platform/tray driver supports this? Is using a property better?
Tray icon coordinates in mouse button callbacks.
This is for programs that would like to render their own custom menus instead of relying on native menus, SNI, XEmbed and Windows support this.
We can just add two integers to the existing callback type, since they arent in any stable SDL release, or do we create a new "MenuRequested" callback (SNI specs say that multiple actions, not just right clicking can trigger context menus)?
Or do we rename the callbacks in acccordance with the SNI spec and add the position integers?
@slouken
Source: libsdl-org/SDL