{"id":18031740,"url":"https://github.com/dagronf/dsftoolbar","last_synced_at":"2025-10-10T18:11:52.229Z","repository":{"id":45623733,"uuid":"300201610","full_name":"dagronf/DSFToolbar","owner":"dagronf","description":"A SwiftUI-style declarative NSToolbar wrapper for macOS.","archived":false,"fork":false,"pushed_at":"2024-08-06T06:55:16.000Z","size":765,"stargazers_count":26,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-23T04:31:39.120Z","etag":null,"topics":["declarative-programming","dsl","maccatalyst","macos","nstoolbar","toolbar"],"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":"2020-10-01T08:18:14.000Z","updated_at":"2025-03-06T07:37:04.000Z","dependencies_parsed_at":"2024-08-06T08:55:03.308Z","dependency_job_id":null,"html_url":"https://github.com/dagronf/DSFToolbar","commit_stats":{"total_commits":56,"total_committers":1,"mean_commits":56.0,"dds":0.0,"last_synced_commit":"124102478525079c24cd22ab6ec44d80c3174154"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFToolbar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFToolbar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFToolbar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFToolbar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dagronf","download_url":"https://codeload.github.com/dagronf/DSFToolbar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245791335,"owners_count":20672665,"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":["declarative-programming","dsl","maccatalyst","macos","nstoolbar","toolbar"],"created_at":"2024-10-30T10:10:37.167Z","updated_at":"2025-10-10T18:11:47.191Z","avatar_url":"https://github.com/dagronf.png","language":"Swift","readme":"# DSFToolbar\n\n![tag](https://img.shields.io/github/v/tag/dagronf/DSFToolbar)\n![Swift](https://img.shields.io/badge/Swift-5.4-orange.svg)\n[![License MIT](https://img.shields.io/badge/license-MIT-magenta.svg)](https://github.com/dagronf/ColorPaletteCodable/blob/master/LICENSE) \n![SPM](https://img.shields.io/badge/spm-compatible-maroon.svg)\n\n![macOS](https://img.shields.io/badge/macOS-10.13+-darkblue)\n![macCatalyst](https://img.shields.io/badge/macCatalyst-2+-orangered)\n\nA SwiftUI-style declarative `NSToolbar` for macOS and Mac Catalyst.\n\n## Why?\n\nNSToolbar has an amazing API with incredible flexibility, but I find that it can be too verbose and spread throughout your code with the use of delegates and callbacks for simpler projects and I have trouble keeping tabs on all the individual components. Even moreso if you want to use actions and bindings on the toolbar objects which just increases the amount code required for each toolbar.\n\nBecause of this, I tended to find that I wasn't putting toolbars into my (admittedly basic) apps.\n\nI was keen to see if I could produce an API that can :-\n\n* use a SwiftUI- style declarative style for defining the toolbar.\n* provide a block-based or bindings based interaction model.\n* provide basic functionality for all of the toolbar item types.  For example, segmented controls, search controls.\n* provide fallback for newer toolbar functionality. For example, if you want to use the new macOS 11 splitview-tracking toolbar items you'd have to litter your code with `if #available(macOS 11, *)` if you want/need to support 10.15 (for example).\n* legacy support for minSize/maxSize toolbar items on older macOS versions (before 10.13) if needed.\n\nThis module doesn't contain the full functionality of the `NSToolbar`/`NSToolbarDelegate`, but provides a decent chunk of the core functionality.\n\n## TL;DR - Show me something!\n\nIf you're familiar with SwiftUI syntax you'll feel comfortable with the declaration style.\n\n```swift\nclass MyViewController: NSViewController {\n   // A binder to enable/disable the search field\n   let searchEnabled = ValueBinder(true)\n   // The search text binding to the content of the search toolbar item\n   let searchText = ValueBinder(\"\") { newValue in\n      Swift.print(\"Search text is now \\(newValue)\")\n   }\n   ...\n   lazy var customToolbar: DSFToolbar = {\n      DSFToolbar(\n         toolbarIdentifier: NSToolbar.Identifier(\"Core\"),\n         allowsUserCustomization: true\n      ) {\n         DSFToolbar.Item(\"item-new\")\n            .label(\"New\")\n            .isSelectable(true)\n            .image(ProjectAssets.ImageSet.toolbar_new_document.template)\n            .willEnable { [weak self] in\n               self?.canAddDocument() ?? false\n            }\n            .action { [weak self] _ in\n               self?.addDocument()\n            }\n\n         DSFToolbar.Item(\"item-edit\")\n            .label(\"Edit\")\n            .isSelectable(true)\n            .image(ProjectAssets.ImageSet.toolbar_edit_document.template)\n            .willEnable { [weak self] in\n               self?.canEditDocument() ?? false\n            }\n            .action { [weak self] _ in\n               self?.editDocument()\n            }\n\n         DSFToolbar.FlexibleSpace()\n\n         DSFToolbar.Search(\"search-field\")\n            .label(\"Search\")\n            .isSelectable(true)\n            .bindIsEnabled(searchEnabled)\n            .bindText(self.searchText)\n      }\n   }()\n   ...\n   // Attaching the window to the toolbar will make the toolbar appear\n   self.customToolbar.attachedWindow = self.view.window\n}\n```\n![](https://github.com/dagronf/dagronf.github.io/blob/master/art/projects/DSFToolbar/sample.png?raw=true)\n\nAnd thats it!\n\n## Usage\n\nFor the most part, you'll only really need to use [`DSFToolbar.Item`](Markdown/item.md), [`DSFToolbar.Group`](Markdown/group.md) and [`DSFToolbar.Search`](Markdown/search.md) to get 90+% of the toolbar functionality you'll need.\n\nEven moreso if you target 10.15 or later, you can use `DSFToolbar.Group` as a segmented-style control by settings \n`isBordered(true)`.\n\n# Concepts\n\n## Toolbar\n\n### Customization\n\nA toolbar can be marked as customisable by settings `allowsUserCustomization: true` in the constructor of the toolbar.\n\nAdditionally you can set or bind to the toolbar's display mode (eg. `.iconAndLabel`, `.labelOnly`) by calling\n`displayMode()` or binding using `bindDisplayMode()` on your `DSFToolbar` instance.\n\n## Items\n\n### Default items\n\nA toolbar item can be marked with `isDefault` to indicate that the item should appear on the default toolbar.\nAn item marked as `isDefault(false)` will not appear initially in the toolbar, but will appear in the customization\npalette to allow to be added.\n\n### Selectable items\n\nA toolbar item marked as `isSelectable` will show a selection marker when pressed. You can detect the toolbar selection\nchange by providing a block for the `onSelectionChange` property.\n\n```swift\nself.customToolbar = DSFToolbar(NSToolbar.Identifier(\"My Toolbar\")) {\n      ...\n   }\n   .onSelectionChange { newToolbarSelection in\n      // Do something when the selection changes\n   }\n```\n\n## Items and Interaction\n\n### Actions\n\nItems which provide callbacks (for example, responses to clicks) can provide a block action to respond with as part of\nthe declaration.\n\n```swift\nself.customToolbar = DSFToolbar(NSToolbar.Identifier(\"Buttons\")) {\n   DSFToolbar.Image(NSToolbarItem.Identifier(\"toolbar-image-bordered\"))\n      .label(\"Burger\")\n      .action { _ in\n         Swift.print(\"Clicked burger!\")\n      }\n   }\n```\n\nCapturing `self` in any block can create retain cycles, so make sure you `[weak self]` if you need to capture self\nwithin a block\n\n### Block requests\n\nSome toolbar items can request information. For example, you can pass a block that provides the enabled status of an \n`Image` item during the declaration.\n\nCapturing `self` in any block can create retain cycles, so make sure you `[weak self]` if you need to capture self\nwithin a block\n\n```swift\nself.customToolbar = DSFToolbar(NSToolbar.Identifier(\"Enabled-buttons\")) {\n   DSFToolbar.Image(NSToolbarItem.Identifier(\"toolbar-image-bordered\"))\n      .label(\"Burger\")\n      .willEnable { [weak self] in\n         return self?.IsBurgerMenuEnabled() ?? false\n      }\n      .action { _ in\n         Swift.print(\"Clicked burger!\")\n      }\n   }\n```\n\n### Bindings\n\nA lot of functionality can be hooked up via bindings in order to pass information to and from a toolbar item. \nFor example, you can hook the content of the Search item to a class variable to observe when the content of the \nsearch field changes.\n\nThis library uses [DSFValueBinders](https://github.com/dagronf/DSFValueBinders) to provide two-way bindings between \nlocal properties and toolbar items.\n\n```swift\nlet searchText = ValueBinder(\"\") {\n   // Update the search with the new string\n}\n   ...\nself.customToolbar = DSFToolbar(\"Search\") {\n   DSFToolbar.Search(\"toolbar-search-field\")\n      .label(\"Search\")\n      .bindSearchText(self.searchText)\n   }\n```\n\n### Cleanup\n\nWhen you are finished with a toolbar, you need to call `close()` on the toolbar object. This will remove any bindings or observers or custom controls that were set up during the creation of the toolbar.\n\n```swift\nself.customToolbar.close()\n```\n\n## Available toolbar item types\n\n### Common\n\n| Type | Description |\n|------|-------------|\n| [Core](Markdown/core.md) | Core elements available to all toolbar item types |\n\n### Controls\n\n| Type | Available | Description |\n|------|:--------:|-------------|\n| [Item](Markdown/item.md) | macOS\u003cbr/\u003emacCatalyst | Basic toolbar 'image' type. Provides basic image, label, action etc.  Most of the time you'll want this. |\n| [Group](Markdown/group.md) | macOS\u003cbr/\u003emacCatalyst | Group multiple items together to represent a common unit.\u003cbr/\u003e This can also be used as a segmented control style (in catalyst and 10.15) by setting `isBordered(true)` on the group. |\n| [Search](Markdown/search.md) | macOS\u003cbr/\u003emacCatalyst | Provides a search text field |\n| [Segmented](Markdown/segmented.md) | macOS\u003cbr/\u003emacCatalyst | A simple segmented control |\n| [Separator](Markdown/separator.md) | macOS11+\u003cbr/\u003emacCatalyst | Hooks into an NSSplitView to track a toolbar separator to a split view separator | \n| [Button](Markdown/button.md) | macOS | A toolbar item containing an `NSButton` |\n| [PopupButton](Markdown/popup-button.md) | macOS | A toolbar item that displays a menu when activated |\n| [PopoverButton](Markdown/popover-button.md) | macOS | A toolbar item that displays a popover when activated |\n| PopupMenu | macOS | A toolbar item that displays a selectable menu item |\n| [View](Markdown/view.md) | macOS | A toolbar item containing a custom view |\n\n# Demos\n\nYou can find pre-made demos under the `Demos` folder\n\n* `DSFToolbar Demo`: Project for Xcode 12 containing targets for macOS and macCatalyst\n\n# License\n\nMIT. Use it for anything you want! Let me know if you do use it somewhere, I'd love to hear about it.\n\n```\nMIT License\n\nCopyright (c) 2024 Darren Ford\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and\nassociated documentation files (the \"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to \nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial\nportions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT\nLIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. \nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, \nWHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagronf%2Fdsftoolbar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdagronf%2Fdsftoolbar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagronf%2Fdsftoolbar/lists"}