Apple-specific UI elements: what changed
Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 1 | + | *(macOS only)* | |
| 2 | 2 | ||
| 3 | - | ||
| 3 | + | ## Apple main menu item | |
| 4 | 4 | ||
| 5 | - | ||
| 5 | + | In each Mac application there is a main menu item with the name of the application. Lazarus will automatically add the "Services", "Hide" and "Quit" menu items to this menu. In order to add more items to this menu, create a menu item with the apple character as its Caption "" (without quotes, it is Unicode 0xF8FF). You can use ifdefs {\$IFDEF DARWIN} to hide it in non-macOS. | |
| 6 | 6 | ||
| 7 | - | ||
| 7 | + | For example: | |
| 8 | 8 | ||
| 9 | - | ||
| 9 | + | ``` pascal | |
| 10 | + | {$IFDEF DARWIN} | |
| 11 | + | AppMenu := TMenuItem.Create(Self); {Application menu} | |
| 12 | + | AppMenu.Caption := #$EF#$A3#$BF; {Unicode Apple logo char} | |
| 13 | + | MainMenu.Items.Insert(0, AppMenu); | |
| 10 | 14 | ||
| 11 | - | ||
| 12 | - | ||
| 13 | - | ||
| 14 | - | ||
| 15 | - | ||
| 16 | - | ||
| 17 | - | ||
| 18 | - | ||
| 19 | - | ||
| 20 | - | ||
| 21 | - | ||
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 29 | - | ||
| 30 | - | ||
| 31 | - | ||
| 32 | - | ||
| 33 | - | ||
| 34 | - | ||
| 35 | - | ||
| 15 | + | AppAboutCmd := TMenuItem.Create(Self); | |
| 16 | + | AppAboutCmd.Action:= ActionList1.Actions[1]; | |
| 17 | + | AppMenu.Add(AppAboutCmd); {Add About as item in application menu} | |
| 36 | 18 | ||
| 37 | - | ||
| 19 | + | AppSep1Cmd := TMenuItem.Create(Self); | |
| 20 | + | AppSep1Cmd.Caption := '-'; | |
| 21 | + | AppMenu.Add(AppSep1Cmd); | |
| 38 | 22 | ||
| 39 | - | ||
| 23 | + | AppCheckCmd := TMenuItem.Create(Self); | |
| 24 | + | AppCheckCmd.Action:= ActionList1.Actions[2]; | |
| 25 | + | AppMenu.Add(AppCheckCmd); {Add Check as item in application menu} | |
| 40 | 26 | ||
| 41 | - | ||
| 42 | - | ||
| 43 | - | ||
| 44 | - | ||
| 45 | - | ||
| 46 | - | ||
| 47 | - | ||
| 48 | - | ||
| 49 | - | ||
| 50 | - | ||
| 51 | - | ||
| 52 | - | ||
| 53 | - | ||
| 54 | - | ||
| 55 | - | ||
| 56 | - | ||
| 57 | - | ||
| 58 | - | ||
| 59 | - | ||
| 60 | - | ||
| 61 | - | ||
| 62 | - | ||
| 63 | - | ||
| 27 | + | AppSep2Cmd := TMenuItem.Create(Self); | |
| 28 | + | AppSep2Cmd.Caption := '-'; | |
| 29 | + | AppMenu.Add(AppSep2Cmd); | |
| 30 | + | {$ENDIF} | |
| 64 | 31 | ``` | |
| 65 | 32 | ||
| 66 | 33 | ## About Box | |
| 67 | 34 | ||
| 68 | - | ||
| 35 | + | See the [[Mac Show Application Title, Version, and Company|Simple Way]] to have the system automatically create a Cocoa Framework About Box for you that is appropriately decorated with just a single line of code, a single unit added to your Uses clause and an HTML (credits) file. | |
| 69 | 36 | ||
| 70 | 37 | ## Fixing your application name | |
| 71 | 38 | ||
| 72 | - | ||
| 73 | - | ||
| 74 | - | ||
| 75 | - | ||
| 39 | + | By default your application's name will be the name of your project. You can rename your project, but you cannot add a space to the project name. So, "My App" will show up in the AppName/Apple Menu as "MyApp". Your application dock icon will also display "MyApp". Fear not, this can be fixed by editing the application Info.plist file and changing the Bundle Name key value from "MyApp" to "My App". For example: | |
| 40 | + | ||
| 41 | + | ``` xml | |
| 42 | + | <key>CFBundleName</key> | |
| 43 | + | <string>My App</string> | |
| 76 | 44 | ``` | |
| 77 | 45 | ||
| 78 | - | ||
| 46 | + | The two keys to consider when renaming your application: | |
| 79 | 47 | ||
| 80 | - | ||
| 81 | - | ||
| 82 | - | ||
| 83 | - | ||
| 84 | - | ||
| 48 | + | | Key name | Description | | |
| 49 | + | |----|----| | |
| 50 | + | | CFBundleName (Bundle name) | The short name for the bundle. The value for this key is usually the name of your application. Xcode sets the value of this key by default when you create a new project. | | |
| 51 | + | | CFBundleDisplayName (Bundle display name) | The localized version of your application name. You typically include a localized value for this key in an InfoPlist.strings file in each of your language-specific resource directories. | | |
| 52 | + | | | | | |
| 53 | + | ||
| 85 | 54 | ## How to make Apple main menu multilingual | |
| 86 | 55 | ||
| 87 | - | ||
| 88 | - | ||
| 89 | - | ||
| 90 | - | ||
| 91 | - | ||
| 92 | - | ||
| 93 | - | ||
| 94 | - | ||
| 95 | - | ||
| 96 | - | ||
| 97 | - | ||
| 98 | - | ||
| 99 | - | ||
| 100 | - | ||
| 101 | - | ||
| 102 | - | ||
| 103 | - | ||
| 104 | - | ||
| 56 | + | To translate the Apple main menu from the default English to, for example, German, see the procedure below: | |
| 57 | + | ||
| 58 | + | ``` pascal | |
| 59 | + | unit... | |
| 60 | + | {$ifdef LCLCocoa} {$modeswitch objectivec2} {$endif} | |
| 61 | + | ||
| 62 | + | uses ... | |
| 63 | + | {$ifdef LCLCocoa} CocoaAll, {$endif} | |
| 64 | + | ||
| 65 | + | procedure TranslateApplicationMenu; | |
| 66 | + | var mnMain: NSMenu; | |
| 67 | + | mnApp : NSMenu; | |
| 68 | + | mnItem: NSMenuItem; | |
| 69 | + | i : integer; | |
| 70 | + | begin | |
| 71 | + | mnMain := NSApplication (NSApp).mainmenu; | |
| 72 | + | mnItem := NSMenuItem (mnMain.itemArray.objectAtIndex(0)); | |
| 73 | + | ||
| 74 | + | if (mnItem.hasSubmenu) then | |
| 75 | + | begin | |
| 76 | + | mnApp := mnItem.submenu; | |
| 77 | + | ||
| 78 | + | for i:=0 to mnApp.itemArray.count-1 do | |
| 105 | 79 | begin | |
| 106 | - | ||
| 107 | - | ||
| 108 | - | ||
| 80 | + | mnItem := NSMenuItem(mnApp.itemArray.objectAtIndex(i)); | |
| 81 | + | ||
| 82 | + | if (NOT mnItem.isSeparatorItem) then | |
| 109 | 83 | begin | |
| 110 | - | ||
| 111 | - | ||
| 112 | - | ||
| 113 | - | ||
| 114 | - | ||
| 115 | - | ||
| 116 | - | ||
| 117 | - | ||
| 118 | - | ||
| 119 | - | ||
| 120 | - | ||
| 121 | - | ||
| 122 | - | ||
| 123 | - | ||
| 124 | - | ||
| 84 | + | if (mnItem.title.UTF8String = 'Services') then | |
| 85 | + | mnItem.setTitle (NSString.stringWithUTF8string('Dienste')); | |
| 86 | + | if (mnItem.title.UTF8String = 'Hide Others') then | |
| 87 | + | mnItem.setTitle (NSString.stringWithUTF8string('Andere ausblenden')); | |
| 88 | + | if (mnItem.title.UTF8String = 'Show All') then | |
| 89 | + | mnItem.setTitle (NSString.stringWithUTF8string('Alle einblenden')); | |
| 90 | + | if (mnItem.title.UTF8String = 'Hide ' + Application.Title) then | |
| 91 | + | mnItem.setTitle (NSString.stringWithUTF8string(PChar(Application.Title + ' ausblenden'))); | |
| 92 | + | if (mnItem.title.UTF8String = 'Quit ' + Application.Title) then | |
| 93 | + | mnItem.setTitle (NSString.stringWithUTF8string(PChar(Application.Title + ' beenden'))); | |
| 125 | 94 | end | |
| 126 | 95 | end | |
| 127 | - | ||
| 96 | + | end | |
| 97 | + | end; | |
| 128 | 98 | ``` | |
| 129 | 99 | ||
| 130 | 100 | ## Adding an icon to your app bundle | |
| 131 | 101 | ||
| 132 | - | ||
| 102 | + | 1\. Use /usr/bin/iconutil or a similar program to create your app's icon file (.icns extension). | |
| 133 | 103 | ||
| 134 | - | ||
| 135 | - | ||
| 104 | + | 2\. Copy the .icns file to your app bundle's Resources folder. For example, from the command line: | |
| 105 | + | ||
| 106 | + | ``` bash | |
| 136 | 107 | cp -p myapp.icns myapp.app/Contents/Resources | |
| 137 | 108 | ``` | |
| 138 | 109 | ||
| 139 | - | ||
| 140 | - | ||
| 110 | + | 3\. Add the following key to your app bundle's Info.plist file: | |
| 111 | + | ||
| 112 | + | ``` xml | |
| 141 | 113 | <key>CFBundleIconFile</key> | |
| 142 | - | ||
| 114 | + | <string>myapp.icns</string> | |
| 143 | 115 | ``` | |
| 144 | 116 | ||
| 145 | - | ||
| 117 | + | Sometimes Finder doesn't "refresh" an app to use the new icon, continuing instead to show the default icon. You can try these things to force Finder to use the new icon: | |
| 146 | 118 | ||
| 147 | - | ||
| 148 | - | ||
| 149 | - | ||
| 150 | - | ||
| 119 | + | - In a Terminal, use the UNIX command "touch" to touch the app bundle (eg touch MyApp.app) - this should work instantly. | |
| 120 | + | - Log out and back in again. | |
| 121 | + | - Drag (move) your application to a different folder, then back again. | |
| 122 | + | - Restart Finder (Esc-Option-Apple keys). | |
| 151 | 123 | ||
| 152 | - | ||
| 124 | + | You shouldn't have this problem with Finder when you install your app on other computers. The issue is a result of Finder caching the icon. | |
| 153 | 125 | ||
| 154 | 126 | ## Removing the app icon from title bars | |
| 155 | 127 | ||
| 156 | - | ||
| 128 | + | The Apple convention is that a window title bar has an icon only when the window represents a file. However, in the LCL the icon typically defines the application itself. | |
| 157 | 129 | ||
| 158 | - | ||
| 130 | + | The expected Apple behaviour can be achieved by setting the global variable **CocoaIconUse** to true and including the **CocoaInt** unit. See [[Cocoa Internals/Forms|Cocoa Form Icons]] for the full details. | |
| 159 | 131 | ||
| 160 | - | ||
| 132 | + | See also the Apple [*Human Interface Guidelines*](https://developer.apple.com/design/human-interface-guidelines/macos/windows-and-views/window-anatomy/) document on window anatomy. | |
| 161 | 133 | ||
| 162 | 134 | ## Removing the title bar and border from a form | |
| 163 | 135 | ||
| 164 | - | ||
| 165 | - | ||
| 136 | + | To remove the title bar and border from a form, use the following code in your Form OnCreate method: | |
| 137 | + | ||
| 138 | + | ``` pascal | |
| 166 | 139 | procedure TForm1.FormCreate(Sender: TObject); | |
| 167 | - | ||
| 168 | - | ||
| 169 | - | ||
| 170 | - | ||
| 171 | - | ||
| 172 | - | ||
| 173 | - | ||
| 140 | + | begin | |
| 141 | + | BorderIcons := []; | |
| 142 | + | BorderStyle := bsNone; | |
| 143 | + | FormStyle := fsStayOnTop; | |
| 144 | + | ShowInTaskBar := stNever; | |
| 145 | + | ControlStyle := ControlStyle - [csSetCaption]; | |
| 146 | + | end; | |
| 174 | 147 | ``` | |
| 175 | 148 | ||
| 176 | 149 | ## Add an Apple help book to your app | |
| 177 | 150 | ||
| 178 | - | ||
| 151 | + | No professional macOS application should be without a functioning Apple Help Book. Unfortunately Apple make it harder than it should be for developers to create an Apple Help Book because their documentation is significantly out of date (2013 anyone?) and the Apple Help Viewer has undergone significant change in recent versions of the operating system. For the full details on how to add an Apple Help Book to your application, along with sample code, refer to the article [[Add an Apple Help Book to your macOS app]]. | |
| 179 | 152 | ||
| 180 | 153 | ## Using preferences in your application | |
| 181 | 154 | ||
| 182 | - | ||
| 155 | + | For details on how to use Preferences in your application, refer to the articles: [[Mac Preferences Read and Write|Reading and Writing Preferences]] and [[Mac Preferences and About Menu|Preferences Menu]]. | |
| 183 | 156 | ||
| 184 | 157 | ## Menu bar | |
| 185 | 158 | ||
| 186 | - | ||
| 159 | + | Only one status bar, the system status bar, is available in macOS. It resides in the system-wide menu bar at the top of the screen. Status items appear on the right side of the menu bar, just to the left of the menu bar clock and Menu Extras, such as the Displays and Sound menus. The items remain in the menu bar even when your application is not in the foreground. | |
| 187 | 160 | ||
| 188 | - | ||
| 161 | + | For details of adding your own status items to the menu bar, refer to the [[macOS NSStatusBar]] article. | |
| 189 | 162 | ||
| 190 | 163 | ## Mac Buttons | |
| 191 | 164 | ||
| 192 | - | ||
| 165 | + | By default, the button placed onto a form by Lazarus is 75 (width) by 25 (height), which is not the standard for Mac Applications. See [[Mac Buttons]] for how to create the expected Mac button appearance. | |
| 193 | 166 | ||
| 194 | 167 | ## The Dock | |
| 195 | 168 | ||
| 196 | - | ||
| 169 | + | The Dock is a prominent feature of the macOS GUI which is used to launch applications and to switch between running applications. A user's frequently applications, or indeed any file or folder, may also be placed in the Dock for quick access. Applications that do not normally keep icons in the Dock will still appear there when running and remain until they are quit. By default, the Dock appears at the bottom of the screen, but the user can optionally locate it on the left or right side of the screen. | |
| 197 | 170 | ||
| 198 | - | ||
| 171 | + | Apple applied for a US patent for the Dock design in 1999 and the patent was ultimately granted in 2008. | |
| 199 | 172 | ||
| 200 | 173 | ### Hiding an application from the Dock | |
| 201 | 174 | ||
| 202 | - | ||
| 175 | + | For information on how to hide your application from the Dock, refer to the article [[Hiding a macOS app from the Dock]]. | |
| 203 | 176 | ||
| 204 | 177 | ### Show Badge on application icon in Dock | |
| 205 | 178 | ||
| 206 | - | ||
| 179 | + | Badges are used to notify a user of something new in an application. The badge is a counter that appears on the application's dock tile (icon) as a white number on a red circular or oval, depending on the number of digits, background. For how to implement this, see the article [[Show Badge on Application Icon in Dock]]. | |
| 207 | 180 | ||
| 208 | 181 | ### Bouncing an application icon in the Dock | |
| 209 | 182 | ||
| 210 | - | ||
| 183 | + | Bouncing your application's icon in the dock can be useful to attract a user's attention when, for example, a long-running task has finished. For how to do this, refer to the [[Bounce Application Icon in Dock]] article. | |
| 211 | 184 | ||
| 212 | 185 | ### Adding menu items to an application Dock Menu | |
| 213 | 186 | ||
| 214 | - | ||
| 187 | + | By adding menu items to your application's dock icon, you can provide the user with quick access to commonly used features. For how to do this, referent to the [[macOS Application Dock Menu]] article. | |
| 215 | 188 | ||
| 216 | 189 | ## Dialogs / Windows | |
| 217 | 190 | ||
| 218 | 191 | ### How to use a Drawer | |
| 219 | 192 | ||
| 220 | - | ||
| 193 | + | A drawer is a child window that slides out from a parent window and that the user can open or close (show or hide) while the parent window is open. A drawer should contain frequently accessed controls that do not need to be visible at all times. For how to do this, refer to the [[macOS Drawers]] article. | |
| 221 | 194 | ||
| 222 | 195 | ### How to use a Sheet | |
| 223 | 196 | ||
| 224 | - | ||
| 197 | + | A sheet is the Apple recommended way to request user input before proceeding with a document-specific action or to present information to the user before the next step. For information on how to create and use a sheet, see: [[Using macOS Sheets]]. | |
| 225 | 198 | ||
| 226 | 199 | ### How to use Alert Panels | |
| 227 | 200 | ||
| 228 | - | ||
| 201 | + | A panel is a special kind of window, typically serving an auxiliary function in an application. An alert panel is a type of built-in dialog for alerting the user to something and retrieving any choice the user made (eg clicking an OK or Cancel button). For information on how to create and use an alert panel in your application, see the article [[Using macOS Alert Panels]]. | |
| 229 | 202 | ||
| 230 | 203 | ### About windows / About Boxes | |
| 231 | 204 | ||
| 232 | - | ||
| 205 | + | An About window, also called an About Box, is an optional window that contains your application’s version and copyright information and may also optionally include credits acknowledging people and code you did not write. For several different ways to implement About windows. see the [[Mac Show Application Title, Version, and Company|About windows]] article. | |
| 233 | 206 | ||
| 234 | 207 | ## How to deliver user notifications | |
| 235 | 208 | ||
| 236 | - | ||
| 209 | + | Notifications are a great way for your applications to keep your users informed. They appear in the upper-right corner of the screen and/or in the Notification Center. To use this feature in your application, see the article [[macOS User Notifications]]. | |
| 237 | 210 | ||
| 238 | 211 | ## Detecting Light or Dark mode | |
| 239 | 212 | ||
| 240 | - | ||
| 213 | + | Dark mode was introduced with macOS Mojave (10.14). Macs using older versions of macOS like High Sierra and Sierra are unfortunately not able to use dark mode but can enable a dark menu bar and dock. Users can enable or disable dark mode via System Preferences. An Auto mode was introduced with macOS Catalina (10.15). This mode switches between light (during the day) and dark (during the night) modes automatically. | |
| 241 | 214 | ||
| 242 | - | ||
| 215 | + | For details of how to detect the mode, see [[Dark theme|Dark mode]]. | |
| 243 | 216 | ||
| 244 | 217 | ## See also | |
| 245 | 218 | ||
| 246 | - | ||
| 247 | - | ||
| 248 | - | ||
| 249 | - | ||
| 250 | - | ||
| 219 | + | - [[Portal:Mac|Lazarus/FPC macOS Portal]]. | |
| 220 | + | - [[macOS Programming Tips]]. | |
| 221 | + | - [[macOS Big Sur changes for developers]]. | |
| 222 | + | - [[Multiplatform Programming Guide]]. | |
| 223 | + | - [[Introduction to platform-sensitive development]]. | |
| 251 | 224 | ||
| 252 | 225 | ## External links | |
| 253 | 226 | ||
| 254 | - | ||
| 227 | + | - Apple [*Human Interface Guidelines*](https://developer.apple.com/design/human-interface-guidelines/macos/) | |
| 255 | 228 | ||
| 256 | 229 | --- | |
| 257 | - | ||
| 230 | + | *From the Free Pascal wiki, page "Apple-specific UI elements", as it stood on 2021-12-13 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).* | |
| 231 | + | Category: Code Snippets | |
| 232 | + | Category: Platform-sensitive development | |
| 233 | + | Category: macOS |