Objective-C Language

Properties

Syntax#

  • @property (optional_attributes, …) type identifier;
  • @synthesize identifier = optional_backing_ivar;
  • @dynamic identifier;

Parameters#

Attribute Description
atomic Implicit. Enables synchronization in synthesized accessor methods.
nonatomic Disables synchronization in the synthesized accessor methods.
readwrite Implicit. Synthesizes getter, setter and backing ivar.
readonly Synthesizes only the getter method and backing ivar, which can be assigned directly.
getter=name Specifies the name of getter method, implicit is propertyName.
setter=name Specifies the name of setter method, implicity is setPropertyName:. Colon : must be a part of the name.
strong Implicit for objects under ARC. The backing ivar is synthesized using __strong, which prevents deallocation of referenced object.
retain Synonym for strong.
copy Same as strong, but the synthesized setter also calls -copy on the new value.
unsafe_unretained Implicit, except for objects under ARC. The backing ivar is synthesized using __unsafe_unretained, which (for obejcts) results in dangling pointer once the referenced object deallocates.
assign Synonym for unsafe_unretained. Suitable for non-object types.
weak Backing ivar is synthesized using __weak, so the value will be nullified once the referenced object is deallocated.
class Property accessors are synthesized as class methods, instead of instance methods. No backing storage is synthesized.
nullable The property accepts nil values. Mainly used for Swift bridging.
nonnull The property doesn’t accept nil values. Mainly used for Swift bridging.
null_resettable The property accepts nil values in setter, but never returns nil values from getter. Your custom implementation of getter or setter must ensure this behavior. Mainly used for Swift bridging.
null_unspecified Implicit. The property doesn’t specify handling of nil values. Mainly used for Swift bridging.
## What are properties?
Here is an example class which has a couple of instance variables, without using properties:
@interface TestClass : NSObject {
    NSString *_someString;
    int _someInt;
}

-(NSString *)someString;
-(void)setSomeString:(NSString *)newString;

-(int)someInt;
-(void)setSomeInt:(NSString *)newInt;

@end


@implementation TestClass

-(NSString *)someString {
    return _someString;
}

-(void)setSomeString:(NSString *)newString {
    _someString = newString;
}

-(int)someInt {
    return _someInt;
}

-(void)setSomeInt:(int)newInt {
    _someInt = newInt;
}

@end

This is quite a lot of boilerplate code to create a simple instance variable. You have to create the instance variable & create accessor methods which do nothing except set or return the instance variable. So with Objective-C 2.0, Apple introduced properties, which auto-generate some or all of the boilerplate code.

Here is the above class rewritten with properties:

@interface TestClass

@property NSString *someString;
@property int someInt;

@end


@implementation testClass

@end

A property is an instance variable paired with auto-generated getters and setters. For a property called someString, the getter and setter are called someString and setSomeString: respectively. The name of the instance variable is, by default, the name of the property prefixed with an underscore (so the instance variable for someString is called _someString, but this can be overridden with an @synthesize directive in the @implementation section:

@synthesize someString=foo;    //names the instance variable "foo"
@synthesize someString;    //names it "someString"
@synthesize someString=_someString;        //names it "_someString"; the default if 
                                           //there is no @synthesize directive

Properties can be accessed by calling the getters and setters:

[testObject setSomeString:@"Foo"];
NSLog(@"someInt is %d", [testObject someInt]);

They can also be accessed using dot notation:

testObject.someString = @"Foo";
NSLog(@"someInt is %d", testObject.someInt);

Custom getters and setters

The default property getters and setters can be overridden:

@interface TestClass

@property NSString *someString;

@end

@implementation TestClass

// override the setter to print a message
- (void)setSomeString:(NSString *)newString {
    NSLog(@"Setting someString to %@", newString);
    // Make sure to access the ivar (default is the property name with a _ 
    // at the beginning) because calling self.someString would call the same
    // method again leading to an infinite recursion
    _someString = newString;
}

- (void)doSomething {
    // The next line will call the setSomeString: method
    self.someString = @"Test";
}

@end

This can be useful to provide, for example, lazy initialization (by overriding the getter to set the initial value if it has not yet been set):

- (NSString *)someString {
    if (_someString == nil) {
        _someString = [self getInitialValueForSomeString];
    }
    return _someString;
}

You can also make a property that computes its value in the getter:

@interface Circle : NSObject

@property CGPoint origin;
@property CGFloat radius;
@property (readonly) CGFloat area;

@end

@implementation Circle

- (CGFloat)area {
    return M_PI * pow(self.radius, 2);
}

@end

Properties that cause updates

This object, Shape has a property image that depends on numberOfSides and sideWidth. If either one of them is set, than the image has to be recalculated. But recalculation is presumably long, and only needs to be done once if both properties are set, so the Shape provides a way to set both properties and only recalculate once. This is done by setting the property ivars directly.

In Shape.h

@interface Shape {
    NSUInteger numberOfSides;
    CGFloat sideWidth;

    UIImage * image;
}

// Initializer that takes initial values for the properties.
- (instancetype)initWithNumberOfSides:(NSUInteger)numberOfSides withWidth:(CGFloat)width;

// Method that allows to set both properties in once call.
// This is useful if setting these properties has expensive side-effects.
// Using a method to set both values at once allows you to have the side-
// effect executed only once.
- (void)setNumberOfSides:(NSUInteger)numberOfSides andWidth:(CGFloat)width;

// Properties using default attributes.
@property NSUInteger numberOfSides;
@property CGFloat sideWidth;

// Property using explicit attributes.
@property(strong, readonly) UIImage * image;

@end

In Shape.m

@implementation AnObject

// The variable name of a property that is auto-generated by the compiler
// defaults to being the property name prefixed with an underscore, for
// example "_propertyName". You can change this default variable name using
// the following statement:
// @synthesize propertyName = customVariableName;

- (id)initWithNumberOfSides:(NSUInteger)numberOfSides withWidth:(CGFloat)width {
    if ((self = [self init])) {
       [self setNumberOfSides:numberOfSides andWidth:width];
    }

    return self;
}

- (void)setNumberOfSides:(NSUInteger)numberOfSides {
    _numberOfSides = numberOfSides;

    [self updateImage];
}

- (void)setSideWidth:(CGFloat)sideWidth {
    _sideWidth = sideWidth;

    [self updateImage];
}

- (void)setNumberOfSides:(NSUInteger)numberOfSides andWidth:(CGFloat)sideWidth {
    _numberOfSides = numberOfSides;
    _sideWidth = sideWidth;

    [self updateImage];
}

// Method that does some post-processing once either of the properties has
// been updated.
- (void)updateImage {
    ...
}

@end

When properties are assigned to (using object.property = value), the setter method setProperty: is called. This setter, even if provided by @synthesize, can be overridden, as it is in this case for numberOfSides and sideWidth. However, if you set an property’s ivar directly (through property if the object is self, or object->property), it doesn’t call the getter or setter, allowing you to do things like multiple property sets that only call one update or bypass side-effects caused by the setter.


This modified text is an extract of the original Stack Overflow Documentation created by the contributors and released under CC BY-SA 3.0 This website is not affiliated with Stack Overflow