h1. Important 1/3/2011

The App Store branch has been merged into Master. Please be aware that existing projects that upgrade to the new version will need to toggle any Radio/Check buttons from the existing Bezel style to another and back again. (IE: A check will need to be toggled to radio and then back to check) This will setup the new code changes I had to implement for the App Store.

h2. About

BGHUDAppKit
Tim Davis @ BinaryMethod.com
“Homepage”:http://www.binarymethod.com/

The missing OS X Leopard/Snow Leopard HUD controls.

BGHUDAppKit is a small framework I designed to fill the gap left by Apple when they released the nifty HUD window but forgot to release their controls that match it. There are few really good frameworks out there that will provide you with the HUD style interface. This is where the big change in BGHUDAppKit becomes clear. I use absolutely NO resources or images to give these controls the HUD appearance. BGHUDAppKit uses 100% native Cocoa drawing functions like NSColor, NSGradient and NSBezierPath. Because of this the framework is much smaller, provides a cleaner interface and the biggie…it is already Resolution Independence ready. And of course it is free and open-source.

Project is hosted on “GitHub”:http://github.com/binarygod/BGHUDAppKit/tree/master
Public GIT Clone URL: git://github.com/binarygod/BGHUDAppKit.git

h2. Requirements

OS X Leopard 10.5^* or OS X Snow Leopard 10.6 (NOT compatible with any OS lower than 10.5) BGHUDAppKit is NOT compatible with OS X Tiger or lower.

^*See compiling notes for help compiling OS X Leopard 10.5

h2. Compiling

After cloning/downloading the repository open BGHUDAppKit.xcodeproj, follow the instructions for your particular OS version below.

• OS X Snow Leopard 10.6

Compile by clicking build.

Your finish.

• OS X Leopard 10.5

Expand the “Targets” group item.

Double-Click on “BGHUDAppKitPlugin” to open the ‘Target “BGHUDAppKitPlugin” Info’ window.

Select the Build tab

Select “All Configurations” from the “Configuration” drop down.

Change the “Architectures” setting to “32-Bit Universal”

The reason for this is that the Interface Builder frameworks on OS X Leopard 10.5 do not have 64-Bit capabilities.

h2. Installation

Installation is on a per project basis, BGHUDAppKit was designed to be embedded in your project and distributed.

Add BGHUDAppKit to your project

** Right-Click (Ctrl-Click) on your “Frameworks” group in XCode
** Select “Add > Existing Frameworks…”
** Navigate to BGHUDAppKit.framework and hit “Add”

In your active target add a new “Copy Files Build Phase”

** Right-Click (Ctrl-Click) on project Target under “Targets” group in XCode.
** Select “Add > New Build Phase › New Copy Files Build Phase”
** Double-Click new “Copy Files” build phase
** Select “Frameworks” from Destination drop down. (Close the window)

Add BGHUDAppKit.framework to newly created build phase

** Drag BGHUDAppKit.framework from “Frameworks” group in XCode to “Copy Files” build phase under “Targets” group in XCode.

Build and go. If you inspect your .APP you should now see BGHUDAppKit.framework sitting peacefully in your {APP}Contents/Frameworks directory.

h2. Usage

Using BGHUDAppKit is as simple as opening your project Nib/Xib and designing your interface. BGHUDAppKit comes with an IBPlugin, when your open the Nib/Xib the plugin will be loaded automatically. Just look for the Library item called “BGHUDAppKit”, now you can use it like any other control in Apple. Drag and Drop, setup your properties and run.

h2. Themeing

BGHUDAppKit is more powerful than it first appears to be. I have designed the classes with the mentality of reinvention. Why should everyone have to reinvent the NSScroller if they want to apply iTunes style colors to it? You shouldn’t have to. I’ve done the hard work and research for you. My purpose in life as a developer is to make life easier, programmers are lazy 😃 Every control in BGHUDAppKit uses a theme, you can have one theme for every control or you could have 10 different themes for 10 different controls.

Create a new Theme

Creating a theme does take a little bit of work. If you look inside the Headers directory of BGHUDAppKit.framework you will see a file name “BGTheme.h”. This is the master theme file. Inside of it will see every theme method available and a short description of each explaining where it is used at. Just create a subclass of BGTheme and start overriding whatever methods you need to change.

Adding to ThemeManager

BGHUDAppKit uses a singleton BGThemeManager obect. This makes it so that there is only ever one instance of the theme allocated, thus saving memory. In this example my subclassed theme is myTheme.m. This code is in my main AppController object.
Example Code

-(void)awakeFromNib {
	[[BGThemeManager keyedManager] setTheme: [[[myTheme alloc] init] autorelease] forKey: @"myTheme"];
}

 Whats happening?  We are telling BGThemeManagers keyedManager object that we want to add a new theme instance to its memory with a key of "myTheme".  You can add as many as you like.  Two default themes are provided for you.  The one you'll see when you Drag'n'Drop from the IB palette is "gradientTheme", this is also the theme you will always see	when you simulate the interface in IB.  This is because your custom theme object doesn't exist yet.  The second default theme is "flatTheme", this theme is just a slight dark gradient, giving the controls a less 'candy' look.

Using the new theme

Making the controls use this theme is even easier. In IB a new inspector panel will present itself when you are in the proper focus for that control. Some controls, like buttons, have this panel in the Cell focus. Click on a button once, and then again and it will get a halo around it. You will see a new section called “Theme” with a text box labeled “Theme Key”. Just type your theme key in there and when you build the app that control (and only that control) will use your custom theme.

Hint: Controls that are a combination of two controls, such as NSOutlineView, NSTableView, will have to have the theme set for the ScrollView and the underlying object, in the example above they would be OutlineView, and TableView respectively.

!http://www.binarymethod.com/images/AppKit-ThemeSample.png!

h2. Shrinking

BGHUDAppKit is appox 1.0 Mb in size. This is quite large for a framework this simple. The extra disk space is taken up by the BGHUDAppKitPlugin which is the IB Plugin. This really doesn’t need to be in your distributed app, the framework will function normally without it. Do NOT delete BGHUDAppKitPlugin from your source BGHUDAppKit.framework.

The reason the framework is build this way is because IB will automatically look in a linked framework for a plugin. This seemed, to me at least, the most logical and easiest way to distribute the plugin to you the developer.

A way to shrink your final APP size is really simple. Create a new “Run Script” build phase and copy the following line to it.

rm -fR "${CONFIGURATION_BUILD_DIR}/${WRAPPER_NAME}/Contents/Frameworks/BGHUDAppKit.framework/Versions/Current/Resources"

What happens is this: When you build XCode will look in your final .APP folder and remove the unneeded Resources directory that BGHUDAppKitPlugin resides in. This shrinks BGHUDAppKit.framework down to approx 400k. Quite a big difference.

h2. License

BGHUDAppKit - Copyright © 2008, Tim Davis (BinaryMethod.com, [email protected])

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of BinaryMethod.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

h2. History