iOS Guides | Samples

MonoTouch.Foundation.NSObject Class

Base class for all bound objects that map to Objective-C objects.

See Also: NSObject

Syntax

[MonoTouch.Foundation.Register("NSObject", true)]
public class NSObject : INSObjectProtocol, IDisposable, IEquatable<NSObject>

Remarks

This is the base class that is used to bind Objective-C classes to C# classes. Merely subclassing from NSObject will produce a class that can be passed to Objective-C.

The C# NSObject class and their subclasses are managed representations of the underlying Objective-C instances. The pointer to the unmanaged code Objective-C object is stored in the NSObject.Handle property.

It is important to note that currently, the compiler does not support generic subclasses of NSObject.

Class Registration

When you create a subclass of NSObject this subclass is registered with the Objective-C runtime with a name based on the full .NET typename which is an implementation detail. If you need to ensure that a C# class is exposed with a specific name in the Objective-C runtime, you can apply the RegisterAttribute to the class and specify the name that you want your class to have.

The above is typically used in cases where either you want to reference the class by name on some Objective-C code, when using Interface Builder XIB and Storyboard files or when you are using an Objective-C serialization setup (for example when using NSCoder).

c# Example

//
// This exposes the C# class _MySampleView as the Objective-C MyView
//
[Export ("MyView")]
public class _MySampleView : UIView {

}

Objective-C Methods

In general, MonoTouch classes map one to one to the underlying Objective-C classes. For example, the C# class "MonoTouch.Foundation.NSObject" maps to the Objective-C "NSObject" class. But methods are different. The Objective-C methods do not translate well to C# methods, so they have been in general been altered to match both the C# language, the C# idioms and the .NET Framework Design Guidelines.

Objective-C methods are surfaced to C# as virtual methods that have the special ExportAttribute applied to them. This attribute is used by the compiler to map C# names to Objective-C names. These attributes are shown in the API documentation on top of each function, to help you identify which Objective-C method a particular C# method is calling.

To alter the behavior of a class you use the standard C# idioms: create a subclass and override the methods that you want to alter and use the "base." language feature to optionally call into your base class.

c# Example

public class MyView : UISlider {
	public override void Draw (RectangleF rect)
	{
		// Let the base class draw first
		base.Draw (rect);
	
		// Our custom code
		var ctx = UIGraphics.GetCurrentContext ();
		UIColor.Gray.SetColor ();
		ctx.StrokeEllipseInRect (rect);
	}
}

By default, only methods that have been overwritten will be exposed to the Objective-C world. If you want to expose an arbitrary C# method to the Objective-C world, you need to apply the ExportAttribute to your public method. And this can be done to both static and instance methods. Once the attribute is applied, the method will be exposed to Objective-C and the standard data type marshalling operations that are supported by the runtime are made available to those methods.

c# Example

//
// Exposes the class StringUtilities to Objective-C with the 
// method:
//    - (NSString *) joinArray:(NSArray *) stringArray withSeparator:(NSString *sep);
//
// Used like this:
//   id utilities = [[StringUtilities alloc] init];
//   NSLog (@"Joined: %@", [utilities joinArray:users withSeparator:@", "]);
//
public class StringUtilities : NSObject {
	[Export ("joinArray:withSeparator:")]
	public string Join (string [] array, string separator)
	{
		return string.Join (separator, array);
	}
}

Lifecycle

The C# NSObject and their subclasses are managed wrappers for the underlying Objective-C object. These are created either from C#, when you create a new instance by using the "new" operator or when an existing unmanaged object is surfaced to the C# world.

When you create an object from C# using the "new" operator, the object will initially be owned by C#, and C# will retain a reference to the object. This reference will only be dropped when the garbage collector determines that there are no pending managed references to it, or when you manually call the Dispose method on the object.

C# NSObjects are also created on demand when you invoke a method or a property that returns an NSObject. At this point, the runtime will look into an object cache and determine whether a given Objective-C NSObject has already been surfaced to the managed world or not. If the object has been surfaced, the existing object will be returned, otherwise a constructor that takes an IntPtr as a parameter is invoked to construct the object.

Pure "peers" to framework objects (those objects that are merely C# representations of an Objective-C object and have no extra managed associated state) can be recreated by the runtime on demand by using the constructor mentioned before.

User-subclasses of NSObjects often contain C# state so whenever the Objective-C runtime performs a "retain" operation on one of these objects, the runtime creates a GCHandle that keeps the managed object alive, even if there are no C# visible references to the object. This simplifies bookeeping a lot, since the state will be preserved automatically for you.

The Dispose operation on an NSObject will always drop the reference to the underlying Objective-C object, but will not destroy the managed state, this will only happen when both the managed code and the unmanaged code have both released the objects. This is slightly different from .NET, because on .NET once an object is disposed, it is not possible to invoke any methods on the object, as it is deemed to be useless. That is not the case with NSObjects.

Adopting Protocols

In MonoTouch, most Objective-C protocols are mapped to classes that have the ModelAttribute applied to them. And the way that you adopt a protocol is by subclassing and overwriting the methods that you want to adopt.

There are some rare cases, where you want to adopt an ad-hoc protocol on your own. If you need to adopt an Objective-C protocol, you should use the AdoptsAttribute on your class and provide the name of the protocol that you want to adopt. Typically, when adopting a protocol, you will also have to list all of the Objective-C selectors that you are adopting using the ExportAttribute.

c# Example

[Adopts ("NSLocking")]
public class MyLockeingObject : NSObject {
	[Export ("lock")]
	public void Lock ()
	{
		// ...
	}

	[Export ("unlock")]
	public void Unlock ()
	{
		// ...
	}
}

Key Value Coding

Key Value coding is a mechanism that allows you to access properties of an object by their name, as opposed to accessing them directly with a C# method.

To expose a C# property to the Key-Value coding system all you need to do is add the ExportAttribute to your property. The names must only contain ASCII characters, start with a lowercase letter, and must not contain any spaces.

c# Example

public class CircleLayer : CALayer {
	[Export ("radius")]
	public double Radius { get; set; }

	// ...
}

You use the MonoTouch.Foundation.ValueForKey(NSString) to lookup a property using a name, and you use the of functions MonoTouch.Foundation.SetValueForKey(NSObject, MonoTouch.Foundation.NSString) to set the value for the specified property. For example, you could call foo.ValueForKey ("user") to grab the value of the user property in an object.

In addition, you can use Key Paths to have the runtime repeatedly call the ValueForKey or SetValueForKey for you. You separate the keys by using a dot. For example the keypath "user.address.phone.mobile" would request the user property, and then request the address property on the user, then it would request the phone property on the address and finally request the mobile property on the phone and finally use the result as the value. You use the MonoTouch.Foundation.ValueForKeyPath(NSString) to lookup a property using a keypath, and you use the MonoTouch.Foundation.SetValueForKeyPath(NSObject, MonoTouch.Foundation.NSString) to set a value using a keypath.

When using keypaths, if a lookup fails, the NSObject.SetValueForUndefinedKey(NSObject,NSString) will be invoked when setting a value, and the NSObject.ValueForUndefinedKey(NSString) will be invoked when looking up a value. Both methods by default raise an Objective-C exception, you can alter that behavior by overriding the methods.

Key Value Observing

Key value observing is a mechanism implemented by NSObject that can be used to monitor changes being done to an NSObject through the Key Value Coding system.

For your class to observe a notification, you must override the Foundation.ObserveValue(NSString,NSObject,NSDictionary,IntPtr) method which will be invoked with the information about the value changes for a specific keypath. Then you use the Foundation.AddObserver(NSObject,NSString,NSKeyValueObservingOptions,IntPtr) to start observing changes and the Foundation.RemoveObserver(NSObject,NSString) method to stop receiving notifications.

Related content

Requirements

Namespace: MonoTouch.Foundation
Assembly: monotouch (in monotouch.dll)
Assembly Versions: 0.0.0.0

The members of MonoTouch.Foundation.NSObject are listed below.

See Also: Object

Public Constructors

Default constructor that initializes a new instance of this class with no parameters.
Constructor to call on derived classes to skip initialization and merely allocate the object.
A constructor used when creating managed representations of unmanaged objects; Called by the runtime.
A constructor used when creating managed representations of unmanaged objects; Called by the runtime.

Public Fields

static readonly
MonoTouchAssemblyAssembly. Points to the montoouch assembly.
static readonly
PlatformAssemblyAssembly.

Protected Fields

IsDirectBindingBoolean. Determines whether this class is a direct binding to an Objective-C class, or if this is a subclass of a direct binding.

Public Properties

[read-only]
static
ChangeIndexesKeyNSString. Represents the value associated with the constant NSKeyValueChangeIndexesKey
[read-only]
static
ChangeKindKeyNSString. Represents the value associated with the constant NSKeyValueChangeKindKey
[read-only]
static
ChangeNewKeyNSString. Represents the value associated with the constant NSKeyValueChangeNewKey
[read-only]
static
ChangeNotificationIsPriorKeyNSString. Notification constant for ChangeNotificati
[read-only]
static
ChangeOldKeyNSString. Represents the value associated with the constant NSKeyValueChangeOldKey
[read-only]
ClassClass.
[read-only]
ClassHandleIntPtr. The handle for this class.
[read-only]
DebugDescriptionString. A developer-meaningful description of this object.
[read-only]
DescriptionString. Description of the object, the Objective-C version of ToString.
HandleIntPtr. Handle (pointer) to the unmanaged object representation.
[read-only]
IsProxyBoolean.
[read-only]
RetainCountInt32. Returns the current Objective-C retain count for the object.
[read-only]
SelfNSObject.
[read-only]
SuperclassClass.
[read-only]
SuperHandleIntPtr. Handle used to represent the methods in the base class for this NSObject.
[read-only]
ZoneNSZone.

Public Methods

AccessibilityDecrement()
AccessibilityIncrement()
AccessibilityScroll(UIAccessibilityScrollDirection) : Boolean
AddObserver(NSString, NSKeyValueObservingOptions, Action<NSObservedChange>) : IDisposable
Registers an object for being observed externally using an arbitrary method.
AddObserver(String, NSKeyValueObservingOptions, Action<NSObservedChange>) : IDisposable
Registers an object for being observed externally using an arbitrary method.
AddObserver(NSObject, NSString, NSKeyValueObservingOptions, IntPtr)
Registers an object for being observed externally (using NSString keyPath).   Observed changes are dispatched to the observer’s object NSObject.ObserveValue method.
AddObserver(NSObject, String, NSKeyValueObservingOptions, IntPtr)
Registers an object for being observed externally (using string keyPath).   Observed changes are dispatched to the observer’s object NSObject.ObserveValue method.
static
Alloc(Class) : NSObject
static
AutomaticallyNotifiesObserversForKey(String) : Boolean
Whether this object is providing key-value notifications for the specified key.
Autorelease() : NSObject
[Dangerous] Invokes the low-level Objective-C autorelease method on the object.
AwakeFromNib()
Called after the object has been loaded from the nib file. Overriders must call base.AwakeFromNib().
BeginInvokeOnMainThread(NSAction)
Invokes asynchrously the specified code on the main UI thread.
BeginInvokeOnMainThread(Selector, NSObject)
Invokes asynchrously the specified code on the main UI thread.
static
CancelPreviousPerformRequest(NSObject)
Cancels a pending time-delayed Invoke or PerformSelector.
static
CancelPreviousPerformRequest(NSObject, Selector, NSObject)
Cancels a pending time-delayed PerformSelector.
ConformsToProtocol(IntPtr) : Boolean
Invoked to determine if this object implements the specified protocol.
Copy() : NSObject
Performs a copy of the underlying Objective-C object.
DangerousAutorelease() : NSObject
DangerousRelease()
DangerousRetain() : NSObject
DidChange(NSKeyValueChange, NSIndexSet, NSString)
Indicates a change occurred to the indexes for a to-many relationship.
DidChange(NSString, NSKeyValueSetMutationKind, NSSet)
DidChangeValue(String)
Indicates that a change occurred on the specified key.
Dispose()
Releases the resources used by the NSObject object.
DoesNotRecognizeSelector(Selector)
Indicates that this object does not recognize the specified selector.
EncodeTo(NSCoder)
Encodes the state of the object on the provided encoder
Finalize()
Finalizer for the NSObject object
static
FromObject(Object) : NSObject
Boxes an object into an NSObject.
GetDictionaryOfValuesFromKeys(NSString[]) : NSDictionary
Retrieves the values of the specified keys.
static
GetKeyPathsForValuesAffecting(NSString) : NSSet
The key paths whose values affect the value of the specified key.
GetMethodForSelector(Selector) : IntPtr
GetNativeField(String) : NSObject
GetNativeHash() : UInt32
Init()
Invoke(NSAction, Double)
Invoke(NSAction, TimeSpan)
static
InvokeInBackground(NSAction)
Invokes supplied code on a new background thread.
InvokeOnMainThread(NSAction)
Invokes synchronously the specified code on the main UI thread.
InvokeOnMainThread(Selector, NSObject)
Invokes synchrously the specified code on the main UI thread.
IsEqual(NSObject) : Boolean
IsKindOfClass(Class) : Boolean
IsMemberOfClass(Class) : Boolean
static
IsNewRefcountEnabled() : Boolean
Internal -- Determines whether MonoTouch is using the new toggle-reference system or not
MutableCopy() : NSObject
Creates a mutable copy of the specified NSObject.
ObserveValue(NSString, NSObject, NSDictionary, IntPtr)
Indicates that the value at the specified keyPath relative to this object has changed.
PerformSelector(Selector) : NSObject
PerformSelector(Selector, NSObject) : NSObject
PerformSelector(Selector, NSObject, NSObject) : NSObject
PerformSelector(Selector, NSObject, Double)
Invokes the selector on the current instance and if the obj is not null, it passes this as its single parameter.
PerformSelector(Selector, NSObject, Single)
Invokes the selector on the current instance and if the obj is not null, it passes this as its single parameter.
PerformSelector(Selector, NSObject, Double, NSString[])
PerformSelector(Selector, NSThread, NSObject, Boolean)
PerformSelector(Selector, NSThread, NSObject, Boolean, NSString[])
PrepareForInterfaceBuilder()
Release()
[Dangerous] Invokes the low-level Objective-C release method on the object.
RemoveObserver(NSObject, NSString)
Stops the specified observer from receiving further notifications of changed values for the specified keyPath.
RemoveObserver(NSObject, String)
Stops the specified observer from receiving further notifications of changed values for the specified keyPath.
RemoveObserver(NSObject, NSString, IntPtr)
Stops the specified observer from receiving further notifications of changed values for the specified keyPath and context.
RemoveObserver(NSObject, String, IntPtr)
Stops the specified observer from receiving further notifications of changed values for the specified keyPath and context.
RespondsToSelector(Selector) : Boolean
Whether this object recognizes the specified selector.
Retain() : NSObject
This will send the Objective-C 'retain' message to the object.
SetNativeField(String, NSObject)
SetNilValueForKey(NSString)
Sets the value of the specified key to null.
SetValueForKey(NSObject, NSString)
Sets the value of the property specified by the key to the specified value.
SetValueForKeyPath(NSObject, NSString)
Sets the value of a property that can be reached using a keypath.
SetValueForKeyPath(IntPtr, NSString)
A constructor used when creating managed representations of unmanaged objects; Called by the runtime.
SetValueForUndefinedKey(NSObject, NSString)
Indicates an attempt to write a value to an undefined key. If not overridden, raises an NSUndefinedKeyException.
SetValuesForKeysWithDictionary(NSDictionary)
Sets the values of this NSObject to those in the specified dictionary.
override
ToString() : String
Returns a string representation of the value of the current instance.
ValueForKey(NSString) : NSObject
Returns the value of the property associated with the specified key.
ValueForKeyPath(NSString) : NSObject
Returns the value of a property that can be reached using a keypath.
ValueForUndefinedKey(NSString) : NSObject
Indicates an attempt to read a value of an undefined key. If not overridden, raises an NSUndefinedKeyException.
WillChange(NSKeyValueChange, NSIndexSet, NSString)
Indicates that the values of the specified indices in the specified key are about to change.
WillChange(NSString, NSKeyValueSetMutationKind, NSSet)
WillChangeValue(String)
Indicates that the value of the specified key is about to change.

Protected Methods

Dispose(Boolean)
Releases the resources used by the NSObject object.
InitializeHandle(IntPtr)
InitializeHandle(IntPtr, String)
MarkDirty()
Promotes a regular peer object (IsDirectBinding is true) into a toggleref object.