{"id":18847000,"url":"https://github.com/kentzo/ikapplicationpreferences","last_synced_at":"2025-11-09T11:02:54.017Z","repository":{"id":5321959,"uuid":"6504882","full_name":"Kentzo/IKApplicationPreferences","owner":"Kentzo","description":"Simple and beautiful way to add preferences to your Mac application. Mac OS X 10.6+, 64bit, ARC","archived":false,"fork":false,"pushed_at":"2013-11-22T19:18:39.000Z","size":228,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T08:09:29.097Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Objective-C","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/Kentzo.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}},"created_at":"2012-11-02T10:53:53.000Z","updated_at":"2024-11-13T00:30:39.000Z","dependencies_parsed_at":"2022-07-05T15:00:29.775Z","dependency_job_id":null,"html_url":"https://github.com/Kentzo/IKApplicationPreferences","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Kentzo/IKApplicationPreferences","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentzo%2FIKApplicationPreferences","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentzo%2FIKApplicationPreferences/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentzo%2FIKApplicationPreferences/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentzo%2FIKApplicationPreferences/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kentzo","download_url":"https://codeload.github.com/Kentzo/IKApplicationPreferences/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kentzo%2FIKApplicationPreferences/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283496071,"owners_count":26845317,"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-11-09T02:00:05.828Z","response_time":62,"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":[],"created_at":"2024-11-08T03:04:58.014Z","updated_at":"2025-11-09T11:02:53.974Z","avatar_url":"https://github.com/Kentzo.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"Why\n========================\nAlmost every Mac OS X application has a special preferences window,\nbut Apple do not provide any standard solution to build custom preferences.\nWe have to deal with NSWindowController/NSToolbar staff every time. Not good.\n\nIKApplicationPreferences was developed to address this problem.\n\n**Out of the box features:**\n\n- Window is automatically resized to match size of the view\n- Toolbar can be configured using **ASCII art**! Finally it's very easy to localize preferences\n- Toggling views are animated. On pre 10.8 it uses hide/show approach (like in Mail.app or Safari.app)\nOn 10.8+ it uses Core Animation (like in About This Mac introduced in Lion)\n- Default window title is localized in almost every language\n- Provides methods to cyclically enumerate views. Very useful since order of preferences may depend on user's locale\n- Automatic Reference Counting (a.k.a ARC)\n- Support for windows restoration.\n\nRequirements\n========================\n\n- Mac OS X 10.6+\n- x86_64 (new runtime)\n\nTutorial\n========================\n`IKApplicationPreferences` consist of so-named Preferences Representations --- objects that adopts (formally or informally) `IKPreferencesRepresentation` protocol.\n\nEach Preferences Representation consist of:\n\n- view that represents preferences\n\n- toolbar item\n\n- *optionally* title\n\nTherefore IKPreferencesRepresentation defines 2 required methods:\n\n    - (NSView *)view\n    - (void)configureToolbarItem:(NSToolbarItem *)anItem\n\nand 1 optional method:\n\n    - (NSString *)title\n\nMost convenient (and widely used) way to create preferences representation is to subclass `NSViewController` and adopt `IKPreferencesRepresentation` for each representation.\nSince NSViewController already implements both `-view` and `-title`, the only method you have to implement is `-configureToolbarItem:`.\n\nThis method receives an initialized instance of `NSToolbarItem` that it's supposed to configure. The only properties you cannot change are `target` and `action`.\n\nIt's time to create an instance of IKApplicationPreferences. As you may already noticed IKApplicationPreferences is a subclass of `NSWindowController` and it requires a nib to load the window. You may use stock *IKApplicationPreferencesWindow.xib* or you may create custom nib. See notes how to do this properly.\n\nThe designated initialized or IKApplicationPreferences is:\n\n    - (instancetype)initWithWindowNibName:(NSString *)aNibName\n                             visualFormat:(NSString *)aFormat\n                          representations:(NSDictionary *)aRepresentations\n                        usesCoreAnimation:(BOOL)aUsesCoreAnimation;\n\nThe first parameter is a name of nib we discussed above. The second and third parameters should be familiar to you if you ever worked with NSLayoutConstraint.\n\n- **aRepresentations** is a dictionary where keys are identifiers and objects are instances of classes that adopt `IKPreferencesRepresentation`\n\n- **aFormat** is a string which represents configuration of `NSToolbar` using ASCII art. It's essentially a comma-separated list of identifiers specified in **aRepresentations** or standard NSToolbarItem identifiers. It also supports 2 shortcuts: `' '`(NSToolbarSpaceItemIdentifier) and `'-'`(NSToolbarFlexibleSpaceItemIdentifier). E.g. `@\"general,accounts, ,audio,video,-,about\"`\n\n- **aUsesCoreAnimation** If set, Core Animation will be used therefore animation will be much smoother\n\nYou can also use `preferencesWithWindowNibName:visualFormat:representations:`. The only difference is that it lacks *aUsesCoreAnimation* parameter, because it\nautomaticaly uses Core Animation if target version of Mac OS X is 10.8+.\n\nAlready done with that? Great. To show the preferences window simply use standard method of NSWindowController: `-showWindow:`.\n\nNotes\n========================\n\n- The main reason to create custom nib is add views that will be common to any preferences. E.g. custom background or Lock/Unlock view (line in System Preferences.app). Your nib must match the following requirements:\n\n    1. File's Owner MUST be set to `IKApplicationPreferences` or its subclass.\n    2. You MUST set Owner's window to nib's window.\n    3. You MUST not bind title of the window.\n    4. You MUST add an *empty* view and set Owner's _representationsRootView to it.\n    5. You SHOULD set _representationsRootView's autoresizing mask or constraints so it will be resized with window proportionally. It's not a requirement because you can provide custom layout in your subclass of IKApplicationPreferences.\n    6. You SHOULD set class of _representationsRootView to _IKRepresentationRootView. _IKRepresentationRootView is a flipped NSView.\n    7. You MUST add Toolbar to the window and set its delegate to Owner.\n\n- Default `-titlePlaceholder` uses standard CFBundleDisplayName to obtain localized name of you application. If it fails, it uses CFBundleName\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentzo%2Fikapplicationpreferences","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkentzo%2Fikapplicationpreferences","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentzo%2Fikapplicationpreferences/lists"}