menu tray icon commands

Author: spyoungtech

.github/workflows/release.yaml

@@ -19,7 +19,7 @@ jobs:
     - name: build
       shell: bash
       run: |
-        python -m pip install --upgrade wheel setuptools build
+        python -m pip install --upgrade wheel setuptools build unasync tokenize-rt
         python -m build
     - name: Release PyPI
       shell: bash

ahk/_async/engine.py

@@ -1379,6 +1379,31 @@ async def menu_tray_tooltip(self, value: str) -> None:
         await self._transport.function_call('AHKMenuTrayTip', args)
         return None
 
+    async def menu_tray_icon(self, filename: str = '*', icon_number: int = 1, freeze: Optional[bool] = None) -> None:
+        """
+        Change the tray icon menu.
+        Does not affect tray icon for AHK processes started with :py:meth:`run_script` or ``blocking=False``
+
+        Uses the `Icon subcommand <https://www.autohotkey.com/docs/v1/lib/Menu.htm#Icon>`_
+
+        If called with no parameters, the tray icon will be reset to the original default.
+        """
+        args = [filename, str(icon_number)]
+        if freeze is True:
+            args.append('1')
+        elif freeze is False:
+            args.append('0')
+        await self._transport.function_call('AHKMenuTrayIcon', args)
+        return None
+
+    async def menu_tray_icon_show(self) -> None:
+        """
+        Show ('unhide') the tray icon previously hidden by :py:class:`~ahk.directives.NoTrayIcon` directive.
+        Does not affect tray icon for AHK processes started with :py:meth:`run_script` or ``blocking=False``
+        """
+        await self._transport.function_call('AHKMenuTrayShow')
+        return None
+
     # fmt: off
     @overload
     async def sound_beep(self, frequency: int = 523, duration: int = 150) -> None: ...

ahk/_async/transport.py

@@ -95,6 +95,8 @@ def result(self, timeout: Optional[float] = None) -> T_SyncFuture:
     'AHKImageSearch',
     'AHKKeyState',
     'AHKKeyWait',
+    'AHKMenuTrayIcon',
+    'AHKMenuTrayShow',
     'AHKMenuTrayTip',
     'AHKMouseClickDrag',
     'AHKMouseGetPos',
@@ -568,6 +570,11 @@ async def function_call(self, function_name: Literal['AHKRegWrite'], args: Optio
     async def function_call(self, function_name: Literal['AHKRegDelete'], args: Optional[List[str]] = None, *, blocking: bool = True) -> Union[None, AsyncFutureResult[None]]: ...
     @overload
     async def function_call(self, function_name: Literal['AHKMenuTrayTip'], args: Optional[List[str]] = None, *, blocking: bool = True) -> Union[None, AsyncFutureResult[None]]: ...
+    @overload
+    async def function_call(self, function_name: Literal['AHKMenuTrayIcon'], args: Optional[List[str]] = None, *, blocking: bool = True) -> Union[None, AsyncFutureResult[None]]: ...
+    @overload
+    async def function_call(self, function_name: Literal['AHKMenuTrayShow'], args: Optional[List[str]] = None, *, blocking: bool = True) -> Union[None, AsyncFutureResult[None]]: ...
+
     # fmt: on
 
     async def function_call(

ahk/_constants.py

@@ -2609,6 +2609,19 @@
     return FormatNoValueResponse()
 }
 
+AHKMenuTrayShow(ByRef command) {
+    Menu, Tray, Icon
+    return FormatNoValueResponse()
+}
+
+AHKMenuTrayIcon(ByRef command) {
+    filename := command[2]
+    icon_number := command[3]
+    freeze := command[4]
+    Menu, Tray, Icon, %filename%, %icon_number%,%freeze%
+    return FormatNoValueResponse()
+}
+
 b64decode(ByRef pszString) {
     ; TODO load DLL globally for performance
     ; REF: https://docs.microsoft.com/en-us/windows/win32/api/wincrypt/nf-wincrypt-cryptstringtobinaryw

ahk/_sync/engine.py

@@ -1368,6 +1368,31 @@ def menu_tray_tooltip(self, value: str) -> None:
         self._transport.function_call('AHKMenuTrayTip', args)
         return None
 
+    def menu_tray_icon(self, filename: str = '*', icon_number: int = 1, freeze: Optional[bool] = None) -> None:
+        """
+        Change the tray icon menu.
+        Does not affect tray icon for AHK processes started with :py:meth:`run_script` or ``blocking=False``
+
+        Uses the `Icon subcommand <https://www.autohotkey.com/docs/v1/lib/Menu.htm#Icon>`_
+
+        If called with no parameters, the tray icon will be reset to the original default.
+        """
+        args = [filename, str(icon_number)]
+        if freeze is True:
+            args.append('1')
+        elif freeze is False:
+            args.append('0')
+        self._transport.function_call('AHKMenuTrayIcon', args)
+        return None
+
+    def menu_tray_icon_show(self) -> None:
+        """
+        Show ('unhide') the tray icon previously hidden by :py:class:`~ahk.directives.NoTrayIcon` directive.
+        Does not affect tray icon for AHK processes started with :py:meth:`run_script` or ``blocking=False``
+        """
+        self._transport.function_call('AHKMenuTrayShow')
+        return None
+
     # fmt: off
     @overload
     def sound_beep(self, frequency: int = 523, duration: int = 150) -> None: ...

ahk/_sync/transport.py

@@ -87,6 +87,8 @@ def result(self, timeout: Optional[float] = None) -> T_SyncFuture:
     'AHKImageSearch',
     'AHKKeyState',
     'AHKKeyWait',
+    'AHKMenuTrayIcon',
+    'AHKMenuTrayShow',
     'AHKMenuTrayTip',
     'AHKMouseClickDrag',
     'AHKMouseGetPos',
@@ -549,6 +551,11 @@ def function_call(self, function_name: Literal['AHKRegWrite'], args: Optional[Li
     def function_call(self, function_name: Literal['AHKRegDelete'], args: Optional[List[str]] = None, *, blocking: bool = True) -> Union[None, FutureResult[None]]: ...
     @overload
     def function_call(self, function_name: Literal['AHKMenuTrayTip'], args: Optional[List[str]] = None, *, blocking: bool = True) -> Union[None, FutureResult[None]]: ...
+    @overload
+    def function_call(self, function_name: Literal['AHKMenuTrayIcon'], args: Optional[List[str]] = None, *, blocking: bool = True) -> Union[None, FutureResult[None]]: ...
+    @overload
+    def function_call(self, function_name: Literal['AHKMenuTrayShow'], args: Optional[List[str]] = None, *, blocking: bool = True) -> Union[None, FutureResult[None]]: ...
+
     # fmt: on
 
     def function_call(

ahk/templates/daemon.ahk

@@ -2606,6 +2606,19 @@ AHKMenuTrayTip(ByRef command) {
     return FormatNoValueResponse()
 }
 
+AHKMenuTrayShow(ByRef command) {
+    Menu, Tray, Icon
+    return FormatNoValueResponse()
+}
+
+AHKMenuTrayIcon(ByRef command) {
+    filename := command[2]
+    icon_number := command[3]
+    freeze := command[4]
+    Menu, Tray, Icon, %filename%, %icon_number%,%freeze%
+    return FormatNoValueResponse()
+}
+
 b64decode(ByRef pszString) {
     ; TODO load DLL globally for performance
     ; REF: https://docs.microsoft.com/en-us/windows/win32/api/wincrypt/nf-wincrypt-cryptstringtobinaryw

docs/README.md

@@ -322,6 +322,28 @@ ahk = AHK(directives=[NoTrayIcon])
 
 By default, some directives are automatically added to ensure functionality and are merged with any user-provided directives.
 
+## Menu tray icon
+
+As discussed above, you can hide the tray icon if you wish. Additionally, there are some methods available for
+customizing the tray icon.
+
+
+```python
+from ahk import AHK
+ahk = AHK()
+
+# change the tray icon (in this case, using a builtin system icon)
+ahk.menu_tray_icon('Shell32.dll', 174)
+# revert it back to the original:
+ahk.menu_tray_icon()
+
+# change the tooltip that shows up when hovering the mouse over the tray icon
+ahk.menu_tray_tooltip('My Program Name')
+
+# Show the tray icon that was previously hidden by ``NoTrayIcon``
+ahk.menu_tray_icon_show()
+```
+
 ## Registry methods
 
 You can read/write/delete registry keys:

docs/conf.py

@@ -41,8 +41,6 @@
 }
 
 always_document_param_types = True
-typehints_use_signature = True
-typehints_use_signature_return = True
 html_css_files = [
     'css/custom.css',
 ]