Cocoa Internals/OS Versions: what changed
Revision 3 to 4. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | The page cover issues of (backwards) compatibility and API deprecation across different macOS versions. | |
| 2 | 2 | ||
| 3 | 3 | ## AppStore critical | |
| 4 | 4 | ||
| 5 | 5 | If you're building an application with LCL Cocoa, and having issues with uploading to AppStore, due to "Found private symbol usage", please bug report the issue if it is caused by a function or a method used in LCL Cocoa. | |
| 6 | 6 | ||
| 7 | 7 | The Cocoa Widgetset is expected to be AppStore friendly as AppStore is being made the core environment for the distribution of Apple apps. | |
| 8 | 8 | ||
| 9 | 9 | Please note that applications can still be distributed outside of the AppStore (unlike iOS). | |
| 10 | 10 | ||
| 11 | 11 | ## macOS API Deprecation | |
| 12 | 12 | ||
| 13 | 13 | It's quite common for Apple to introduce methods in one version of the system and deprecate them in another version. The chances are high that a deprecated method will be removed in a later macOS version completely. Thus, if method is not verified in run-time, the application could stop working (ie the App could fail to load). | |
| 14 | 14 | ||
| 15 | 15 | Suggestions: | |
| 16 | 16 | ||
| 17 | 17 | - Use non-deprecated methods (there are plenty of APIs that are in effect since macOS 10.0 and are not planned for deprecation). | |
| 18 | 18 | - If the deprecated method is in use and being replaced by some other newly introduced method - check the availability in runtime | |
| 19 | 19 | - if the latest method is available - use it first | |
| 20 | 20 | - if the latest method is not available - fallback to the original method. | |
| 21 | 21 | ||
| 22 | 22 | This would allow your application to execute the same code on earlier and later macOS versions. | |
| 23 | 23 | ||
| 24 | 24 | ## Objective-C methods | |
| 25 | 25 | ||
| 26 | 26 | Use ObjCSelector with respondsToSelector() check, prior to the explicit call. If an object gets a selector it's unable to handle, ObjectiveC would throw an exception and the application would crash. | |
| 27 | 27 | ||
| 28 | 28 | ``` pascal | |
| 29 | 29 | if Assigned(win) then | |
| 30 | 30 | begin | |
| 31 | 31 | if win.respondsToSelector( ObjCSelector('backingScaleFactor')) then | |
| 32 | 32 | Result := win.backingScaleFactor | |
| 33 | 33 | else if win.respondsToSelector( ObjCSelector('userSpaceScaleFactor')) then // for older macOS | |
| 34 | 34 | Result := win.userSpaceScaleFactor; | |
| 35 | 35 | end; | |
| 36 | 36 | ``` | |
| 37 | 37 | ||
| 38 | 38 | ## (Plain) Functions | |
| 39 | 39 | ||
| 40 | 40 | It's possible that a new feature requires a function that has been introduced in a later version of macOS. In this case a straight use of the function would cause a load-time failure on earlier versions of macOS. | |
| 41 | 41 | ||
| 42 | 42 | In order to prevent that, a dynamic loading of the function needs to be used. | |
| 43 | 43 | ||
| 44 | 44 | ``` pascal | |
| 45 | 45 | uses ... | |
| 46 | 46 | dl, dynlibs; | |
| 47 | 47 | ... | |
| 48 | 48 | p := GetProcedureAddress(TLibHandle(RTLD_DEFAULT), 'CGDisplayCreateImage'); | |
| 49 | 49 | ``` | |
| 50 | 50 | ||
| 51 | 51 | The following needs to be taken into consideration: | |
| 52 | 52 | ||
| 53 | 53 | - the use of RTLD_DEFAULT - searches for the function name across all loaded libraries. The system library would likely be loaded by that time. However, if not the actual library name needs to be loaded (unlike Linux, macOS doesn't require the full library path to be specified). | |
| 54 | 54 | ||
| 55 | 55 | - if the symbol is not present, then the code should handle it gracefully (instead of calling to unspecified function). | |
| 56 | 56 | ||
| 57 | 57 | ## AppKit Version | |
| 58 | 58 | ||
| 59 | 59 | In many cases you can call a certain functionality based on the AppKit version. **NSAppKitVersionNumber** is a shared global C-variable, thus the check of the value is performance friendly. | |
| 60 | 60 | ||
| 61 | 61 | Values to be compared to are constants (declared at cocoa_extra.pas): | |
| 62 | 62 | ||
| 63 | - | ||
| 63 | + | ```text | |
| 64 | 64 | NSAppKitVersionNumber10_4 = 824; | |
| 65 | 65 | NSAppKitVersionNumber10_5 = 949; | |
| 66 | 66 | NSAppKitVersionNumber10_6 = 1038; | |
| 67 | 67 | NSAppKitVersionNumber10_7 = 1138; | |
| 68 | 68 | NSAppKitVersionNumber10_8 = 1187; | |
| 69 | 69 | NSAppKitVersionNumber10_9 = 1265; | |
| 70 | 70 | NSAppKitVersionNumber10_10 = 1343; | |
| 71 | 71 | NSAppKitVersionNumber10_11 = 1404; | |
| 72 | 72 | NSAppKitVersionNumber10_12 = 1504; | |
| 73 | 73 | NSAppKitVersionNumber10_13 = 1561; | |
| 74 | 74 | NSAppKitVersionNumber10_14 = 1671; | |
| 75 | 75 | ``` | |
| 76 | 76 | ||
| 77 | 77 | Each version corresponds to a particular macOS release (or even sub-release in some cases). Major versions are denoted by an integer number, minor versions and release by the fractional part. To use macOS 10.13 and 10.14 as examples this is expressed as follows: | |
| 78 | 78 | ||
| 79 | 79 | | macOS version | Value of NSAppKitVersionNumber | | |
| 80 | 80 | |---------------|--------------------------------| | |
| 81 | 81 | | macOS 10.13 | 1561 | | |
| 82 | 82 | | macOS 10.13.1 | 1561.1 | | |
| 83 | 83 | | macOS 10.13.2 | 1561.2 | | |
| 84 | 84 | | macOS 10.13.3 | 1561.3 | | |
| 85 | 85 | | macOS 10.13.4 | 1561.4 | | |
| 86 | 86 | | macOS 10.14.1 | 1671.1 | | |
| 87 | 87 | | macOS 10.14.2 | 1671.2 | | |
| 88 | 88 | | macOS 10.14.3 | 1671.3 | | |
| 89 | 89 | | macOS 10.14.4 | 1671.4 | | |
| 90 | 90 | | macOS 10.14.5 | 1671.5 | | |
| 91 | 91 | ||
| 92 | 92 | The values are taken from macOS header files provided with Xcode (eg NSapplication.h). | |
| 93 | 93 | ||
| 94 | 94 | ## Version Specific | |
| 95 | 95 | ||
| 96 | 96 | ### Mojave (10.14) | |
| 97 | 97 | ||
| 98 | 98 | #### Drawing Issues | |
| 99 | 99 | ||
| 100 | 100 | According to [AppKit release notes](https://developer.apple.com/documentation/appkit/appkit_release_notes_for_macos_10_14?language=objc) for 10.14 there are views are drawn Layer-backed. | |
| 101 | 101 | ||
| 102 | - | ||
| 102 | + | ```text | |
| 103 | 103 | Windows in apps linked against the macOS 10.14 SDK are displayed using Core Animation when the app is running in macOS 10.14. | |
| 104 | 104 | This doesn’t mean that all views are layer-backed; rather, it means that all views are either layer-backed or draw into | |
| 105 | 105 | a shared layer with other layers. | |
| 106 | 106 | ||
| 107 | 107 | This change should be mostly invisible to most apps, but you might notice one or more subtle changes as a result. | |
| 108 | 108 | ||
| 109 | 109 | Views that depend on drawing in the same backing store as their ancestors or lower-ordered siblings may find | |
| 110 | 110 | that they are instead drawing in separate layers. Views shouldn’t rely on being able to draw into the same | |
| 111 | 111 | backing store as their ancestors; instead, those ancestors should change as required. For example, to affect | |
| 112 | 112 | the background of a window, use the NSWindow properties opaque and backgroundColor | |
| 113 | 113 | ``` | |
| 114 | 114 | ||
| 115 | 115 | The change seems to impact CocoaWS a lot, causing problem with area invalidation. A number of Mojave-specific issues ([1](https://bugs.freepascal.org/view.php?id=34335)[2](https://bugs.freepascal.org/view.php?id=34358)) were reported. | |
| 116 | 116 | ||
| 117 | 117 | ||
| 118 | 118 | **LCL solution** - make sure the code does the right thing. or force all LCL driven controsl to return wantsUpdateLayer as true. | |
| 119 | 119 | ||
| 120 | 120 | #### Dark Mode | |
| 121 | 121 | ||
| 122 | 122 | Dark mode is supported "out of the box", but only if an application was built using SDK for 10.14. For example, if an application was built with an earlier SDK (i.e. was compiled on macOS 10.13 High Sierra or earlier), then it would not pick up Dark Mode by default. | |
| 123 | 123 | ||
| 124 | - | ||
| 124 | + | ```text | |
| 125 | 125 | When an app links on the macOS 10.14 SDK, it’s automatically opted in to supporting the dark appearance, | |
| 126 | 126 | with its NSApp inheriting the NSAppearanceNameDarkAqua appearance from System Preferences. | |
| 127 | 127 | ``` | |
| 128 | 128 | ||
| 129 | 129 | ||
| 130 | 130 | **Enable dark mode on LCL level.** Cocoa WS needs to be updated, to check if NSApplication object supports "appearance" and if it does, then enable the currently selected system theme. That allows to support "Dark Mode" even for applications built on an earlier version of the system. | |
| 131 | 131 | ||
| 132 | 132 | **Enable dark mode in manifest.** Add a switch into Info.plist NSRequiresAquaSystemAppearance and set the value to "false". (The key must be specified explicitly, if an app is build for an earlier SDK.) | |
| 133 | 133 | ||
| 134 | 134 | **Disable dark mode in manifest.** In the Info.plist, the key NSRequiresAquaSystemAppearance should be set to "true". | |
| 135 | 135 | ||
| 136 | 136 | #### Font Quality | |
| 137 | 137 | ||
| 138 | 138 | Smooth font rendering is somewhat disabled in the OS by default. It is issue in 10.14 and 10.15 (Catalina). | |
| 139 | 139 | ||
| 140 | 140 | - <https://ahmadawais.com/fix-macos-mojave-font-rendering-issue/> | |
| 141 | 141 | - <https://discussions.apple.com/thread/250730319> | |
| 142 | 142 | ||
| 143 | 143 | Solution: open Terminal and enter the command: | |
| 144 | 144 | ||
| 145 | - | ||
| 145 | + | ```text | |
| 146 | 146 | defaults write -g CGFontRenderingFontSmoothingDisabled -bool NO | |
| 147 | 147 | ``` | |
| 148 | 148 | ||
| 149 | 149 | then log off or restart. | |
| 150 | 150 | ||
| 151 | 151 | ## See Also | |
| 152 | 152 | ||
| 153 | 153 | - [[Cocoa Internals]] | |
| 154 | 154 | - [Apple Release Notes for macOS 10.14](https://developer.apple.com/documentation/appkit/appkit_release_notes_for_macos_10_14?language=objc) | |
| 155 | 155 | - [Apple Release Notes for macOS 10.13](https://developer.apple.com/library/archive/releasenotes/AppKit/RN-AppKit/index.html) | |
| 156 | 156 | - [Apple Release Notes for macOS 10.12 and earlier](https://developer.apple.com/library/archive/releasenotes/AppKit/RN-AppKitOlderNotes/) | |
| 157 | 157 | ||
| 158 | 158 | - [Issue \#33672](https://bugs.freepascal.org/view.php?id=33672) - the bug covers some problems linking the app | |
| 159 | 159 | ||
| 160 | 160 | --- | |
| 161 | 161 | *From the Free Pascal wiki, page "Cocoa Internals/OS Versions", as it stood on 2020-09-19 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |