{"id":13995144,"url":"https://github.com/dagronf/DSFDockTile","last_synced_at":"2025-07-22T21:32:12.717Z","repository":{"id":38248054,"uuid":"386870354","full_name":"dagronf/DSFDockTile","owner":"dagronf","description":"Easily display images, animations, badges and alerts to your macOS application's dock icon","archived":false,"fork":false,"pushed_at":"2024-04-06T06:50:49.000Z","size":3519,"stargazers_count":105,"open_issues_count":0,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-23T10:23:53.718Z","etag":null,"topics":["animation","badge","custom","dock","image","macos","nsdocktile","swiftui"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dagronf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-17T07:34:43.000Z","updated_at":"2024-10-30T19:11:58.000Z","dependencies_parsed_at":"2024-10-30T10:21:04.958Z","dependency_job_id":null,"html_url":"https://github.com/dagronf/DSFDockTile","commit_stats":{"total_commits":18,"total_committers":1,"mean_commits":18.0,"dds":0.0,"last_synced_commit":"5d34a5ef6941d7a11209564668ed335dfcec4df8"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFDockTile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFDockTile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFDockTile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFDockTile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dagronf","download_url":"https://codeload.github.com/dagronf/DSFDockTile/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227177789,"owners_count":17743167,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","badge","custom","dock","image","macos","nsdocktile","swiftui"],"created_at":"2024-08-09T14:03:16.186Z","updated_at":"2024-11-29T17:31:07.489Z","avatar_url":"https://github.com/dagronf.png","language":"Swift","readme":"# DSFDockTile\n\nEasily display images, animations, badges and alerts to your macOS application's dock icon.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/tag/dagronf/DSFDockTile\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/macOS-10.11+-red\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Swift-5.2-orange.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/SwiftUI-1.0+-yellow.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-lightgrey\" /\u003e\n    \u003ca href=\"https://swift.org/package-manager\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/spm-compatible-brightgreen.svg?style=flat\" alt=\"Swift Package Manager\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n![](https://github.com/dagronf/dagronf.github.io/blob/master/art/projects/DSFDockTile/stitch.gif?raw=true)\n\n## Why?\n\nI was inspired by [Neil Sardesai](https://twitter.com/neilsardesai) after he posted [this on Twitter](https://twitter.com/neilsardesai/status/1362179114204073984?s=20). And this marvellous follow-up tweet by [Norbert M. Doerner](https://twitter.com/cdfinder/status/1365201157854015488?s=20).\n\nWhile the NSDockTile API isn't overly complex, I wanted something that made it easy to change the dock image, and even add basic animations from GIF images etc.\n\n## Features\n\n* Set the badge label\n* Display an image\n* Display an animated image\n* Display the content of an NSView\n* Bounce the docktile \n\nBy default a `DSFDockTile` instance operates on the Application's docktile. You can provide your own `NSDockTile` for any window (by calling `window.dockTile`) via the `init` functions on the badge generators.\n\n## DockTile plugins\n\nDid you know that your application can show a custom DockTile image even when it's not running? Apple provides an `NSDockTilePlugin` prodocol that allows you to do exactly that. Want to provide different application icons for dark and light modes?  `NSDockTilePlugin` allows you to! Want to tweak the dock icon when your application isn't running, but needs attention? `NSDockTilePlugin`!\n\nThere is a demo application in the `Demos` folder called **'DSFDockTile Plugin Demo'** (macOS 11+) that demonstrates using `NSDockTilePlugin` and `DSFDockIcon` in SwiftUI.\n\n## Integration\n\n### Swift package manager\n\nAdd `https://github.com/dagronf/DSFDockTile` to your project.\n\nIf you don't want to include the `DSFImageFlipbook` package, copy all the files in the `Sources/` folder **EXCEPT** for `DSFDockTile+Animation.swift`.\n\n### Demo\n\nThere is a demo macOS application available in the `Demos` subfolder.\n\n## Badge Label\n\nIt's very easy to add a badge label to a docktile.\n\n```swift\n// Set the label on the docktile to 1234\nDSFDockTile.badgeLabel = \"1234\"\n\n// Remove the badge label from the docktile\nDSFDockTile.badgeLabel = nil\n```\n\n## DockTile Generators\n\n### AppIcon\n\nSet the docktile to the application's icon.\n\n```swift\n// Set the dock icon to the application icon\nDSFDockTile.AppIcon.display()\n```\n\n### Constant Image\n\nThis is a `DSFDockTile` object that displays a single image. Useful for if you have a set of images to display in the docktile that do not change and you want to the constantness.\n\n```swift\nstatic let LockedImage   = NSImage(named: NSImage.Name(\"padlock-locked\"))!\nstatic let UnlockedImage = NSImage(named: NSImage.Name(\"padlock-unlocked\"))!\n\nlet LockedDockTileImage = DSFDockTile.ConstantImage(LockedImage)\nlet UnlockedDockTileImage = DSFDockTile.ConstantImage(UnlockedImage)\n...\n\nif application.isEditable {\n   UnlockedDockTileImage.display()\n}\nelse {\n   LockedDockTileImage.display()\n}\n```\n\n### Image\n\nThis is a `DSFDockTile` object that can display images.\n\n```swift\nstatic let LockedImage   = NSImage(named: NSImage.Name(\"padlock-locked\"))!\nstatic let UnlockedImage = NSImage(named: NSImage.Name(\"padlock-unlocked\"))!\n\nlet stateDockTile = DSFDockTile.Image()\n\n...\n\nfunc viewDidLoad() {\n   let image = application.isEditable ? UnlockedImage : LockedImage\n   stateDockTile.display(image)\n}\n```\n\n### View\n\nThis is a `DSFDockTile` object that can display the content of a view managed by a view controller\n\nDue to NSDockTile restrictions, the view is not drawn live into the dock as the view is updated. You must call `display()` to update the dock tile with the view's current content whenever a change occurs in the view.\n\n```swift\n/// The view controller to display on the docktile\nlet dockViewController = DockViewController()\n\n/// The docktile instance handling the docktile\nlazy var updateDockTile: DSFDockTile.View = {\n   dockViewController.loadView()\n   return DSFDockTile.View(dockViewController)\n}()\n...\nfunc doUpdate() {\n   // Change the color of the item in the \n   self.dockViewController.foregroundColor = .systemYellow\n\n   // NSDockTile does not update automatically so need to tell it when changes are made\n   self.updateDockTile.display()\n}\n```\n\n### Animation\n\nThis is a docktile that can display an animation.  It uses `DSFImageFlipbook` under the seams to handle the animation itself.\n\n```swift\nlet animatedDockTile: DSFDockTile.Animated = {\n   let fb = DSFImageFlipbook()\n   let da = NSDataAsset(name: NSDataAsset.Name(\"animated-gif\"))!\n   _ = fb.loadFrames(from: da.data)\n   return DSFDockTile.Animated(fb)\n}()\n\n...\n\n@IBAction func startAnimating(_ sender: Any) {\n   animatedDockTile.startAnimating()\n}\n\n@IBAction func stopAnimating(_ sender: Any) {\n   animatedDockTile.stopAnimating()\n}\n```\n\n## SwiftUI \n\nThe `DockTile` view is used to manipulate the docktile for\n\n* The application (`.application`)\n* The window containing the `DockTile` View (`.window`)\n\nYou can set which docktile you want to update in the initializer of the `DockTile` View \n\n### Updating the badge\n\nTo set a badge using SwiftUI, use the `DockTile` view and provide a label for the badge\n\n```swift\n@State var badgeLabel: String = \"\"\nvar body: some Scene {\n   WindowGroup {\n      ZStack {\n         ContentView()\n         DockTile(label: badgeLabel)\n      }\n   }\n}\n```\n\n### Updating the content\n\nTo set the content of a dock tile, provide a view to the initializer. Set to `nil` to return the docktile to its default. \n\n```swift\n@State var dockText: String = \"\"\nvar body: some Scene {\n   WindowGroup {\n      ZStack {\n         ContentView()\n         DockTile(\n            .window,\n            label: \"3\",\n            content: ZStack {\n               Color.white\n               Text(dockText)\n            }\n         )\n      }\n   }\n}\n```\n\nRemember that the DockTile API does not provide live docktile updating, and will require you to update the view for each \nvisual change you want to make\n\n## Attention Concepts\n\nYou can request user information via the DockTile of an application if your application is not the front-most application.\n\nSee [Apple's Documentation](https://developer.apple.com/documentation/appkit/nsapplication/1428358-requestuserattention) for more details.\n\n### requestInformationalAttention()\n\nRequest that the docktile 'bounce' to inform the user of something informational. The function returns an object which you can use to cancel the attention request.\n\n```swift\nlet cancellable = DSFDockTile.requestInformationalAttention()\n```\n\nThe `cancellable` can be used to cancel the information request.\n\nSee [Apple's Documentation](https://developer.apple.com/documentation/appkit/nsapplication/requestuserattentiontype/criticalrequest)\n\n### requestCriticalAttention()\n\nRequest that the docktile 'bounce' to inform the user of something informational. The function returns an object which you can use to cancel the attention request.\n\n```swift\nlet cancellable = DSFDockTile.requestCriticalAttention()\n```\n\nThe `cancellable` can be used to cancel the critical request.\n\nSee [Apple's Documentation](https://developer.apple.com/documentation/appkit/nsapplication/requestuserattentiontype/informationalrequest)\n\n### Cancellation protocol (DSFDockTileUserAttentionCancellation)\n\nThe user attention methods return an object that conforms to `DSFDockTileUserAttentionCancellation` that can be used to cancel an attention request.\n\nSee [Apple's Documentation](https://developer.apple.com/documentation/appkit/nsapplication/1428683-canceluserattentionrequest)\n\n## Thanks\n\n* [Neil Sardesai](https://twitter.com/neilsardesai)\n* [Norbert M. Doerner](https://twitter.com/cdfinder)\n* The images (light/dark) in the demo application are thanks to [brgfx on freepix](https://www.freepik.com/free-vector/opposite-adjectives-light-dark_1172843.htm)\n  * Attribution - \u003ca href=\"https://www.freepik.com/vectors/background\"\u003eBackground vector created by brgfx - www.freepik.com\u003c/a\u003e\n\n* Here is the project I used to understand how to use `NSDockTilePlugin` for my own project. [https://github.com/rrroyal/AutomaticDockTile](https://github.com/rrroyal/AutomaticDockTile)\n\n## License\n\nMIT. Use it and abuse it for anything you want, just attribute my work. Let me know if you do use it somewhere, I'd love to hear about it!\n\n```\nMIT License\n\nCopyright (c) 2022 Darren Ford\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","funding_links":[],"categories":["Swift"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagronf%2FDSFDockTile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdagronf%2FDSFDockTile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagronf%2FDSFDockTile/lists"}