macOS¶
The Toga backend for macOS is toga-cocoa.
Prerequisites¶
toga-cocoa requires macOS 11 (Big Sur) or newer.
Installation¶
toga-cocoa is installed automatically on macOS machines (machines that report sys.platform == 'darwin'), or can be manually installed by running invoking:
$ python -m pip install toga-cocoa
Implementation details¶
The toga-cocoa backend uses the AppKit Objective-C API, also known as Cocoa.
The native APIs are accessed using Rubicon Objective-C.
Platform-specific APIs¶
App lifecycle hooks¶
macOS notifies an app of lifecycle events (app launch, activation, hiding, termination, etc.) by calling methods on an NSApplicationDelegate instance. Toga's implementation of this delegate hands off every lifecycle notification it receives to a same-named method on the Cocoa App implementation class, prefixed with cocoa_. For example, the applicationDidBecomeActive: notification is handled by cocoa_applicationDidBecomeActive() on the Cocoa App class.
An app can hook into a lifecycle event by defining a custom subclass of a platform's App implementation class:
import sys
if sys.platform == "darwin":
from toga_cocoa.app import App as CocoaApp
class MyCocoaApp(CocoaApp):
def cocoa_applicationDidBecomeActive(self, notification):
# ... custom logic before default Toga implementation ...
super().cocoa_applicationDidBecomeActive(notification)
# ... custom logic after default Toga implementation ...
You can then direct your app to use this custom class by overriding the create() method on your app to construct and return an instance of your custom App class when running on macOS:
class MyApp(toga.App):
def create(self):
if sys.platform == "darwin":
return MyCocoaApp(interface=self)
else:
return super().create()
def startup(self): ...
Each hook receives the same arguments as the underlying NSApplicationDelegate method (usually an NSNotification instance). cocoa_applicationWillHide(), cocoa_applicationDidUnhide() and cocoa_applicationDidFinishLaunching() already implement behavior required by Toga's cross-platform API (e.g. triggering on_hide/on_show on windows); if you override one of these, call the base implementation to preserve that behavior, as shown in the example above.
The following lifecycle hooks are available:
cocoa_applicationWillFinishLaunching(notification)
Invoked when applicationWillFinishLaunching: is called on the app
delegate, before the app has finished launching.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationDidFinishLaunching(notification)
Invoked when applicationDidFinishLaunching: is called on the app
delegate, once the app has finished launching.
By default, this brings the app to the foreground.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationWillBecomeActive(notification)
Invoked when applicationWillBecomeActive: is called on the app
delegate, before the app becomes the active app.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationDidBecomeActive(notification)
Invoked when applicationDidBecomeActive: is called on the app
delegate, once the app has become the active app.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationWillResignActive(notification)
Invoked when applicationWillResignActive: is called on the app
delegate, before the app stops being the active app.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationDidResignActive(notification)
Invoked when applicationDidResignActive: is called on the app
delegate, once the app has stopped being the active app.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationWillHide(notification)
Invoked when applicationWillHide: is called on the app delegate,
before the app is hidden.
By default, this triggers on_hide on every window that is
currently visible to the user.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationDidHide(notification)
Invoked when applicationDidHide: is called on the app delegate,
once the app has been hidden.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationWillUnhide(notification)
Invoked when applicationWillUnhide: is called on the app delegate,
before the app is unhidden.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationDidUnhide(notification)
Invoked when applicationDidUnhide: is called on the app delegate,
once the app has been unhidden.
By default, this triggers on_show on every window that is
currently visible to the user.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationDidChangeScreenParameters(notification)
Invoked when applicationDidChangeScreenParameters: is called on
the app delegate, when the screen configuration (e.g. resolution, or
the set of connected screens) changes.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|
cocoa_applicationShouldTerminate(sender) -> int
Invoked when applicationShouldTerminate: is called on the app
delegate, to determine whether the app is allowed to terminate.
By default, this allows termination to proceed immediately.
| PARAMETER | DESCRIPTION |
|---|---|
sender
|
The
|
| RETURNS | DESCRIPTION |
|---|---|
int
|
An |
cocoa_applicationWillTerminate(notification)
Invoked when applicationWillTerminate: is called on the app
delegate, immediately before the app terminates.
This is a no-op by default.
| PARAMETER | DESCRIPTION |
|---|---|
notification
|
The
|