https://github.com/kentzo/ikapplicationpreferences

Simple and beautiful way to add preferences to your Mac application. Mac OS X 10.6+, 64bit, ARC
https://github.com/kentzo/ikapplicationpreferences

Last synced: 8 months ago
JSON representation

Simple and beautiful way to add preferences to your Mac application. Mac OS X 10.6+, 64bit, ARC

• Host: GitHub
• URL: https://github.com/kentzo/ikapplicationpreferences
• Owner: Kentzo
• Created: 2012-11-02T10:53:53.000Z (over 13 years ago)
• Default Branch: master
• Last Pushed: 2013-11-22T19:18:39.000Z (over 12 years ago)
• Last Synced: 2025-04-14T08:09:29.097Z (about 1 year ago)
• Language: Objective-C
• Size: 223 KB
• Stars: 8
• Watchers: 2
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
Why

========================

Almost every Mac OS X application has a special preferences window,

but Apple do not provide any standard solution to build custom preferences.

We have to deal with NSWindowController/NSToolbar staff every time. Not good.

IKApplicationPreferences was developed to address this problem.

**Out of the box features:**

- Window is automatically resized to match size of the view

- Toolbar can be configured using **ASCII art**! Finally it's very easy to localize preferences

- Toggling views are animated. On pre 10.8 it uses hide/show approach (like in Mail.app or Safari.app)

On 10.8+ it uses Core Animation (like in About This Mac introduced in Lion)

- Default window title is localized in almost every language

- Provides methods to cyclically enumerate views. Very useful since order of preferences may depend on user's locale

- Automatic Reference Counting (a.k.a ARC)

- Support for windows restoration.

Requirements

========================

- Mac OS X 10.6+

- x86_64 (new runtime)

Tutorial

========================

`IKApplicationPreferences` consist of so-named Preferences Representations --- objects that adopts (formally or informally) `IKPreferencesRepresentation` protocol.

Each Preferences Representation consist of:

- view that represents preferences

- toolbar item

- *optionally* title

Therefore IKPreferencesRepresentation defines 2 required methods:

    - (NSView *)view

    - (void)configureToolbarItem:(NSToolbarItem *)anItem

and 1 optional method:

    - (NSString *)title

Most convenient (and widely used) way to create preferences representation is to subclass `NSViewController` and adopt `IKPreferencesRepresentation` for each representation.

Since NSViewController already implements both `-view` and `-title`, the only method you have to implement is `-configureToolbarItem:`.

This method receives an initialized instance of `NSToolbarItem` that it's supposed to configure. The only properties you cannot change are `target` and `action`.

It'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.

The designated initialized or IKApplicationPreferences is:

    - (instancetype)initWithWindowNibName:(NSString *)aNibName

                             visualFormat:(NSString *)aFormat

                          representations:(NSDictionary *)aRepresentations

                        usesCoreAnimation:(BOOL)aUsesCoreAnimation;

The 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.

- **aRepresentations** is a dictionary where keys are identifiers and objects are instances of classes that adopt `IKPreferencesRepresentation`

- **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"`

- **aUsesCoreAnimation** If set, Core Animation will be used therefore animation will be much smoother

You can also use `preferencesWithWindowNibName:visualFormat:representations:`. The only difference is that it lacks *aUsesCoreAnimation* parameter, because it

automaticaly uses Core Animation if target version of Mac OS X is 10.8+.

Already done with that? Great. To show the preferences window simply use standard method of NSWindowController: `-showWindow:`.

Notes

========================

- 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:

    1. File's Owner MUST be set to `IKApplicationPreferences` or its subclass.

    2. You MUST set Owner's window to nib's window.

    3. You MUST not bind title of the window.

    4. You MUST add an *empty* view and set Owner's _representationsRootView to it.

    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.

    6. You SHOULD set class of _representationsRootView to _IKRepresentationRootView. _IKRepresentationRootView is a flipped NSView.

    7. You MUST add Toolbar to the window and set its delegate to Owner.

- Default `-titlePlaceholder` uses standard CFBundleDisplayName to obtain localized name of you application. If it fails, it uses CFBundleName