Preprocessor Macros

Macros
#define	__NI_DEPRECATED_METHOD   __attribute__((deprecated))
#define	NI_FIX_CATEGORY_BUG(name)
#define	RGBCOLOR(r, g, b)   [UIColor colorWithRed:(r)/255.0f green:(g)/255.0f blue:(b)/255.0f alpha:1]
#define	RGBACOLOR(r, g, b, a)   [UIColor colorWithRed:(r)/255.0f green:(g)/255.0f blue:(b)/255.0f alpha:(a)]

Overview

Preprocessor macros are added to Nimbus with care.

Macros hide functionality and are difficult to debug, so most macros found in Nimbus are one-liners or compiler utilities.

Creating Byte- and Hex-based Colors

Nimbus provides the RGBCOLOR and RGBACOLOR macros for easily creating UIColor objects with byte and hex values.

Examples

UIColor* color = RGBCOLOR(255, 128, 64); // Fully opaque orange
UIColor* color = RGBACOLOR(255, 128, 64, 0.5); // Orange with 50% transparency
UIColor* color = RGBCOLOR(0xFF, 0x7A, 0x64); // Hexadecimal color

Why it exists

There is no easy way to create UIColor objects using 0 - 255 range values or hexadecimal. This leads to code like this being written:

UIColor* color = [UIColor colorWithRed:128.f/255.0f green:64.f/255.0f blue:32.f/255.0f alpha:1]

Avoid requiring the -all_load and -force_load flags

Categories can introduce the need for the -all_load and -force_load because of the fact that the application will not load these categories on startup without them. This is due to the way Xcode deals with .m files that only contain categories: it doesn't load them without the -all_load or -force_load flag specified.

There is, however, a way to force Xcode into loading the category .m file. If you provide an empty class implementation in the .m file then your app will pick up the category implementation.

Example in plain UIKit:

@interface BogusClass
@end
@implementation BogusClass
@end

@implementation UIViewController (MyCustomCategory)
...
@end

NI_FIX_CATEGORY_BUG is a Nimbus macro that you include in your category .m file to save you the trouble of having to write a bogus class for every category. Just be sure that the name you provide to the macro is unique across your project or you will encounter duplicate symbol errors when linking.

NI_FIX_CATEGORY_BUG(UIViewController_MyCustomCategory);

@implementation UIViewController (MyCustomCategory)
...
@end

Macro Definition Documentation

__NI_DEPRECATED_METHOD   __attribute__((deprecated))

Mark a method or property as deprecated to the compiler.

#define __NI_DEPRECATED_METHOD;

Discussion

Any use of a deprecated method or property will flag a warning when compiling.

Borrowed from Apple's AvailabiltyInternal.h header.

  __AVAILABILITY_INTERNAL_DEPRECATED         __attribute__((deprecated))

NI_FIX_CATEGORY_BUG

Value:

@interface NI_FIX_CATEGORY_BUG_##name : NSObject @end \
@implementation NI_FIX_CATEGORY_BUG_##name @end

Force a category to be loaded when an app starts up.

#define NI_FIX_CATEGORY_BUG:;

Discussion

Add this macro before each category implementation, so we don't have to use -all_load or -force_load to load object files from static libraries that only contain categories and no classes. See http://developer.apple.com/library/mac/#qa/qa2006/qa1490.html for more info.

RGBCOLOR   [UIColor colorWithRed:(r)/255.0f green:(g)/255.0f blue:(b)/255.0f alpha:1]

Creates an opaque UIColor object from a byte-value color definition.

#define RGBCOLOR;

RGBACOLOR   [UIColor colorWithRed:(r)/255.0f green:(g)/255.0f blue:(b)/255.0f alpha:(a)]

Creates a UIColor object from a byte-value color definition and alpha transparency.

#define RGBACOLOR;