{"id":18031753,"url":"https://github.com/dagronf/dsfsearchfield","last_synced_at":"2025-03-27T05:30:57.980Z","repository":{"id":63907298,"uuid":"307203939","full_name":"dagronf/DSFSearchField","owner":"dagronf","description":"A simple NSSearchField with a localizable, managed recent searches menu.","archived":false,"fork":false,"pushed_at":"2023-06-03T02:59:56.000Z","size":53,"stargazers_count":22,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-23T04:31:39.959Z","etag":null,"topics":["appkit","macos","nssearchfield","swift","swiftui","user-interface"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"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":null,"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-25T22:17:57.000Z","updated_at":"2024-09-30T23:26:56.000Z","dependencies_parsed_at":"2024-10-30T10:21:05.519Z","dependency_job_id":null,"html_url":"https://github.com/dagronf/DSFSearchField","commit_stats":{"total_commits":10,"total_committers":1,"mean_commits":10.0,"dds":0.0,"last_synced_commit":"d2dac5e143a8e5ce49f9f12412932684072089ba"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFSearchField","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFSearchField/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFSearchField/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagronf%2FDSFSearchField/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dagronf","download_url":"https://codeload.github.com/dagronf/DSFSearchField/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245791341,"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":["appkit","macos","nssearchfield","swift","swiftui","user-interface"],"created_at":"2024-10-30T10:10:39.839Z","updated_at":"2025-03-27T05:30:57.164Z","avatar_url":"https://github.com/dagronf.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DSFSearchField\n\n![](https://github.com/dagronf/dagronf.github.io/blob/master/art/projects/DSFSearchField/screenshot.png?raw=true)\n\nA simple NSSearchField with a localizable, managed recent searches menu and SwiftUI support.\n\n![](https://img.shields.io/github/v/tag/dagronf/DSFSearchField) ![](https://img.shields.io/badge/macOS-10.13+-red) ![](https://img.shields.io/badge/Swift-5.4-orange.svg)\n![](https://img.shields.io/badge/License-MIT-lightgrey) [![](https://img.shields.io/badge/spm-compatible-brightgreen.svg?style=flat)](https://swift.org/package-manager)\n\n## Why\n\n`NSSearchField` has a wonderful built-in mechanism for handling recents list which requires the developer to provide a menu to provide the recents list.  This class automatically provides a suitable localizable menu structure.\n\n`DSFSearchField` inherits from `NSSearchField` so search delegates, actions etc. all work as expected.\n\n## Installation\n\nNote that currently to support localization you'll need to use the 'Direct' method below until Swift tool version 5.3 becomes more pervasive (it supports embedding localizations within modules)\n\n### Swift Package Manager\n\nAdd `https://github.com/dagronf/DSFSearchField` to your project.\n\n### Direct\n\nCopy `DSFSearchField.swift` (and `DSFSearchField+SwiftUI.swift`) if you want SwiftUI support) to your project.\n\n## Usage\n\n### Via Interface Builder\n\n* Add a new `NSSearchField` using Interface Builder, then change the class type to `DSFSearchField`.\n* If you want to save the recent searches list, set `Autosave` in the Attributes Inspector of Interface Builder to a unique string for your project.\n\n### Programatically\n\n```swift\nlet searchField = DSFSearchField(frame: rect, recentsAutosaveName: \"primary-search\")\n```\n\n## Conveniences\n\n### Search text change callback\n\nThis is called whenever the text changes within the search field.\n\n```swift\n   searchField.searchTermChangeCallback = { [weak self] newSearchTerm in\n      // Do something with 'newSearchTerm'\n      ...\n   }\n```\n\n### Submit callback\n\nThis is called when the user presses 'return' in the search field.\n\n```swift\n   searchField.searchSubmitCallback = { [weak self] newSearchTerm in\n      // Do something with 'newSearchTerm'\n      ...\n   }\n```\n\n### Simple searchTerm interface\n\nYou can set the search text using `stringValue`, but I personally find this scans badly when I'm trying to read and understand code. This class provides an additional property `searchTerm` more descriptive property name. This property is bindable and settable.\n\nSimple setting of the search term\n\n```swift\nsearchField.searchTerm = \"cats\"\n```\n\nBindable observation of the search term.\n\n```swift\nsearchField.addObserver(\n   self, \n   forKeyPath: #keyPath(DSFSearchField.searchTerm), \n   options: [.new], \n   context: nil)\n```\n\n## SwiftUI\n\n`DSFSearchField` provides a basic SwiftUI interface to the search control.\n\n```swift\nDSFSearchField.SwiftUI(\n   text: $searchText, \n   placeholderText: \"Search for colors…\",\n   autosaveName: \"SystemColorsSearchField\"\n)\n```\n\n### Available view modifiers\n\n#### `.bezelStyle`\n\nThe style of bezel for the search bar.\n\n#### `.controlSize`\n\nThe size of the control\n\n**Note:** Unfortunately, I could not figure out how to hook into SwiftUI's `onSubmit` view modifier (and it appears that\nthe required `Environment` values have not been made visible to the public. So that means that the default `onSubmit`\nview modifier that SwiftUI provides will not be called.\n\n#### `onUpdateSearchText`\n\nProvide a block that gets called when the search text changes.\n\n```swift\nDSFSearchField.SwiftUI(...)\n   .onUpdateSearchText { newValue in\n      Swift.print(\"Update with new value -\u003e \\(newValue)\")\n   }\n```\n\n#### `onSubmitSearchText`\n\nProvide a block that gets called when the search text is submitted (the user presses the return key in the field)\n\n```swift\nDSFSearchField.SwiftUI(...)\n   .onSubmitSearchText { newValue in\n      Swift.print(\"Update with new value -\u003e \\(newValue)\")\n   }\n```\n\n### Example\n\n```swift\nvar body: some View {\n   DSFSearchField.SwiftUI(\n      text: $search1,\n      autosaveName: \"Search1\"\n   )\n   .onUpdateSearchText { newValue in\n      Swift.print(\"Update with new value -\u003e \\(newValue)\")\n   }\n   .onSubmitSearchText { newValue in\n      Swift.print(\"Submit with new value -\u003e \\(newValue)\")\n   }\n}\n```\n\n## License\n\nMIT. Use 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) 2023 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagronf%2Fdsfsearchfield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdagronf%2Fdsfsearchfield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagronf%2Fdsfsearchfield/lists"}