{"id":23143107,"url":"https://github.com/cleancocoa/appguideoverlay","last_synced_at":"2025-08-21T02:05:25.154Z","repository":{"id":66740536,"uuid":"119167148","full_name":"CleanCocoa/AppGuideOverlay","owner":"CleanCocoa","description":"macOS user interface guide to display an overlay with descriptions of NSViews in your app","archived":false,"fork":false,"pushed_at":"2023-12-28T18:04:37.000Z","size":1781,"stargazers_count":22,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-17T14:43:32.012Z","etag":null,"topics":["guide","macos","overlay","swift","tutorial"],"latest_commit_sha":null,"homepage":null,"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/CleanCocoa.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}},"created_at":"2018-01-27T13:33:40.000Z","updated_at":"2025-07-30T04:10:17.000Z","dependencies_parsed_at":"2023-12-28T19:24:20.923Z","dependency_job_id":"0a35d1a9-3783-4e4d-8f1c-d6f1075548e7","html_url":"https://github.com/CleanCocoa/AppGuideOverlay","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/CleanCocoa/AppGuideOverlay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanCocoa%2FAppGuideOverlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanCocoa%2FAppGuideOverlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanCocoa%2FAppGuideOverlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanCocoa%2FAppGuideOverlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CleanCocoa","download_url":"https://codeload.github.com/CleanCocoa/AppGuideOverlay/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanCocoa%2FAppGuideOverlay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271415496,"owners_count":24755639,"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","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["guide","macos","overlay","swift","tutorial"],"created_at":"2024-12-17T15:12:10.520Z","updated_at":"2025-08-21T02:05:25.136Z","avatar_url":"https://github.com/CleanCocoa.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AppGuideOverlay\n\n![Swift 5.0](https://img.shields.io/badge/Swift-5.0-blue.svg?style=flat)\n![Version](https://img.shields.io/github/tag/CleanCocoa/AppGuideOverlay.svg?style=flat)\n![License](https://img.shields.io/github/license/CleanCocoa/AppGuideOverlay.svg?style=flat)\n![Platform](https://img.shields.io/badge/platform-macOS-lightgrey.svg?style=flat)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n\nmacOS user interface guide to display an overlay with descriptions of NSViews in your app.\n\n## Usage\n\n### Example\n\nHave a look at the example app that is part of this repository. The basic setup looks like this:\n\n```swift\n// Given access to interesting view components ...\nlet window: NSWindow = ...\nlet textField: NSTextField = ...\nlet button: NSButton = ...\n\n// ... and an AppGuide with steps attached to them ...\nlet appGuide = AppGuide(steps: [\n    AppGuide.Step(title: \"A Text Field\",\n          detail: \"Use this to type something.\",\n          position: .below,\n          cutoutView: textField),\n    AppGuide.Step(title: \"A Button\",\n          detail: \"Press this to make something happen.\",\n          position: .right,\n          cutoutView: button)\n    ])\n\n// ... keep the AppGuideOverlay around and start it:\nlet appGuideOverlay = AppGuideOverlay(\n    appGuide: appGuide,\n    appGuideSuperview: window.contentView!)\nappGuideOverlay.start()\n```\n\n### Types of Interest\n\n- `AppGuide` is the model. It contains an array of `AppGuide.Step`s that represents the steps in your guide.\n- `AppGuideOverlay` is a convenient service object to set up the app guide and control it. (You don't have to use it and can use `AppGuidePresenter` and a `HandlesOverlayEvents` conforming delegate. But `AppGuideOverlay` really is the most useful façade to get started.)\n- `AppGuideOverlayDelegate` is used to react to progress and completion events.\n\n## Features\n\n- **Uses Auto Layout** to position the `AppGuide.Step` contents next to the view the steps explain. This ensures the window size fits the labels at all times. It also ensures the step's description is displayed correctly when the window is resized. \n    \u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"img/auto-layout.gif\" /\u003e\n    \u003c/div\u003e\n- **Tasteful** pulsation of the cutout frame's size in the overlay. This also indicates that the app doesn't just hang.\n    \u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"img/breathing.gif\" /\u003e\n    \u003c/div\u003e\n- **Good citizen:** No custom `NSRunLoop` or anything. It's just a view on top of other views that captures the first responder status and doesn't give it back to underlying controls. This means you can remote-control your user interface to change display content and animate as usual while the overlay is visible.\n\n## Code License\n\nCopyright (c) 2018-2019 Christian Tietze. Distributed under the MIT License.\n\n- Uses [LoopingAnimation](https://github.com/CleanCocoa/LoopingAnimation) code directly, also distributed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcleancocoa%2Fappguideoverlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcleancocoa%2Fappguideoverlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcleancocoa%2Fappguideoverlay/lists"}