mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-25 01:31:08 +00:00
fa6f34e403
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@11402 72102866-910b-0410-8b05-ffd578937521
624 lines
23 KiB
XML
624 lines
23 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
|
|
<gsdoc base="NSObject" prev="NSNumberFormatter" next="NSPipe" up="Base">
|
|
<head>
|
|
<title>NSObject</title>
|
|
<author name="Richard Frith-Macdonald">
|
|
<email address="rfm@gnu.org"/>
|
|
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
|
|
</author>
|
|
<author name="Nicola Pero">
|
|
<email address="n.pero@mi.flashnet.it"/>
|
|
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
|
|
</author>
|
|
<version>$Revision$</version>
|
|
<date>$Date$</date>
|
|
</head>
|
|
<body>
|
|
<chapter>
|
|
<heading>NSObject</heading>
|
|
<class name="NSObject">
|
|
<declared>Foundation/NSObject.h</declared>
|
|
<conform>NSObject</conform>
|
|
<desc>
|
|
<p>
|
|
<code>NSObject</code> is the root class (a root class is
|
|
a class with no superclass) of the gnustep base library
|
|
class hierarchy, so all classes normally inherit from
|
|
<code>NSObject</code>. There is an exception though:
|
|
<code>NSProxy</code> (which is used for remote messaging)
|
|
does not inherit from <code>NSObject</code>.
|
|
</p>
|
|
<p>
|
|
Unless you are really sure of what you are doing, all
|
|
your own classes should inherit (directly or indirectly)
|
|
from <code>NSObject</code> (or in special cases from
|
|
<code>NSProxy</code>). <code>NSObject</code> provides
|
|
the basic common functionality shared by all gnustep
|
|
classes and objects.
|
|
</p>
|
|
<p>
|
|
The essential methods which must be implemented by all
|
|
classes for their instances to be usable within gnustep
|
|
are declared in a separate protocol, which is the
|
|
<code>NSObject</code> protocol. Both
|
|
<code>NSObject</code> and <code>NSProxy</code> conform to
|
|
this protocol, which means all objects in a gnustep
|
|
application will conform to this protocol (btw, if you
|
|
don't find a method of <code>NSObject</code> you are
|
|
looking for in this documentation, make sure you also
|
|
look into the documentation for the <code>NSObject</code>
|
|
protocol).
|
|
</p>
|
|
<p>
|
|
Theoretically, in special cases you might need to
|
|
implement a new root class. If you do, you need to make
|
|
sure that your root class conforms (at least) to the
|
|
<code>NSObject</code> protocol, otherwise it will not
|
|
interact correctly with the gnustep framework. Said
|
|
that, I must note that I have never seen a case in which
|
|
a new root class is needed.
|
|
</p>
|
|
<p>
|
|
<code>NSObject</code> is a root class, which implies that
|
|
instance methods of <code>NSObject</code> are treated in
|
|
a special way by the Objective-C runtime. This is an
|
|
exception to the normal way messaging works with class
|
|
and instance methods: if the Objective-C runtime can't
|
|
find a class method for a class object, as a last resort
|
|
it looks for an instance method of the root class with
|
|
the same name, and executes it if it finds it. This
|
|
means that instance methods of the root class (such as
|
|
<code>NSObject</code>) can be performed by class objects
|
|
which inherit from that root class ! This can only
|
|
happen if the class doesn't have a class method with the
|
|
same name, otherwise that method - of course - takes the
|
|
precedence. Because of this exception,
|
|
<code>NSObject</code>'s instance methods are written in
|
|
such a way that they work both on <code>NSObject</code>'s
|
|
instances and on class objects.
|
|
</p>
|
|
</desc>
|
|
<method type="id" factory="yes">
|
|
<sel>alloc</sel>
|
|
<desc>
|
|
Allocates a new instance of the receiver from the default
|
|
zone, by invoking <code>allocWithZone:</code> with
|
|
<code>NSDefaultMallocZone()</code> as the zone argument.
|
|
Returns the created instance.
|
|
</desc>
|
|
</method>
|
|
<method type="id" factory="yes">
|
|
<sel>allocWithZone:</sel>
|
|
<arg type="NSZone*">zone</arg>
|
|
<desc>
|
|
This is the basic method to create a new instance. It
|
|
allocates a new instance of the receiver from the specified
|
|
memory zone.
|
|
<p>
|
|
Memory for an instance of the receiver is allocated; a
|
|
pointer to this newly created instance is returned. All
|
|
instance variables are set to 0 except the
|
|
<code>isa</code> pointer which is set to point to the
|
|
object class. No initialization of the instance is
|
|
performed: it is your responsibility to initialize the
|
|
instance by calling an appropriate <code>init</code>
|
|
method. If you are not using the garbage collector, it is
|
|
also your responsibility to make sure the returned
|
|
instance is destroyed when you finish using it, by calling
|
|
the <code>release</code> method to destroy the instance
|
|
directly, or by using <code>autorelease</code> and
|
|
autorelease pools.
|
|
</p>
|
|
<p>
|
|
You do not normally need to override this method in
|
|
subclasses, unless you are implementing a class which for
|
|
some reasons silently allocates instances of another class
|
|
(this is typically needed to implement class clusters and
|
|
similar design schemes).
|
|
</p>
|
|
<p>
|
|
If you have turned on debugging of object allocation (by
|
|
calling the <code>GSDebugAllocationActive</code>
|
|
function), this method will also update the various
|
|
debugging counts and monitors of allocated objects, which
|
|
you can access using the <code>GSDebugAllocation...</code>
|
|
functions.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="void" factory="yes">
|
|
<sel>cancelPreviousPerformRequestsWithTarget:</sel>
|
|
<arg type="id">aTarget</arg>
|
|
<sel>selector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="Class" factory="yes">
|
|
<sel>class</sel>
|
|
<desc>
|
|
Returns the receiver.
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL" factory="yes">
|
|
<sel>conformsToProtocol:</sel>
|
|
<arg type="Protocol*">aProtocol</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id" factory="yes">
|
|
<sel>copyWithZone:</sel>
|
|
<arg type="NSZone*">zone</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="NSString*" factory="yes">
|
|
<sel>description</sel>
|
|
<desc>
|
|
The <code>description</code> factory method describes the class
|
|
of the receiver. In the default GNUstep implementation, this
|
|
simply returns the name of the class as an NSString object.
|
|
</desc>
|
|
</method>
|
|
<method type="NSString*" factory="yes">
|
|
<sel>descriptionWithLocale:</sel>
|
|
<arg type="NSDictionary*">aLocale</arg>
|
|
<desc>
|
|
The default (NSOBject) implementation of this method simply calls
|
|
the <code>description</code> method and discards the locale
|
|
information.
|
|
</desc>
|
|
<standards><GNUstep/></standards>
|
|
</method>
|
|
<method type="NSString*" factory="yes">
|
|
<sel>descriptionWithLocale:</sel>
|
|
<arg type="NSDictionary*">aLocale</arg>
|
|
<sel>indent:</sel>
|
|
<arg type="unsigned int">level</arg>
|
|
<desc>
|
|
The default (NSObject) implementation of this method simply calls
|
|
the <code>descriptionWithLocale:</code> method and discards the
|
|
level information.
|
|
</desc>
|
|
<standards><GNUstep/></standards>
|
|
</method>
|
|
<method type="NSString*" factory="yes">
|
|
<sel>descriptionWithLocale:</sel>
|
|
<arg type="NSDictionary*">aLocale</arg>
|
|
<sel>indent:</sel>
|
|
<arg type="unsigned int">level</arg>
|
|
<sel>to:</sel>
|
|
<arg type="id<GNUDescriptionDestination>">output</arg>
|
|
<desc>
|
|
The default (NSObject) implementation of this method simply calls
|
|
the <code>descriptionWithLocale:indent:</code> method and appends
|
|
the value returned by that method to the output object.
|
|
</desc>
|
|
<standards><GNUstep/></standards>
|
|
</method>
|
|
<method type="void" factory="yes">
|
|
<sel>initialize</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="IMP" factory="yes">
|
|
<sel>instanceMethodForSelector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="NSMethodSignature*" factory="yes">
|
|
<sel>instanceMethodSignatureForSelector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<desc>
|
|
Returns a method signature object representing the
|
|
method implemented for instsances of this class which
|
|
corresponds to the supplied selector.
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL" factory="yes">
|
|
<sel>instancesRespondToSelector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="void" factory="yes">
|
|
<sel>load</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id" factory="yes">
|
|
<sel>mutableCopyWithZone:</sel>
|
|
<arg type="NSZone*">zone</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id" factory="yes">
|
|
<sel>new</sel>
|
|
<desc>
|
|
This method is a short-hand for alloc followed by init, that is,
|
|
<p><code>
|
|
NSObject *object = [NSObject new];
|
|
</code></p>
|
|
is exactly the same as
|
|
<p><code>
|
|
NSObject *object = [[NSObject alloc] init];
|
|
</code></p>
|
|
<p>
|
|
This is a general convention: all <code>new...</code>
|
|
methods are supposed to return a newly allocated and
|
|
initialized instance, as would be generated by an
|
|
<code>alloc</code> method followed by a corresponding
|
|
<code>init...</code> method. Please note that if you are
|
|
not using a garbage collector, this means that instances
|
|
generated by the <code>new...</code> methods are not
|
|
autoreleased, that is, you are responsible for releasing
|
|
(autoreleasing) the instances yourself. So when you use
|
|
<code>new</code> you typically do something like:
|
|
</p>
|
|
<p>
|
|
<code>
|
|
NSMutableArray *array = AUTORELEASE ([NSMutableArray new]);
|
|
</code>
|
|
</p>
|
|
<p>
|
|
You do no normally need to override <code>new</code> in
|
|
subclasses, because if you override <code>init</code> (and
|
|
optionally <code>allocWithZone:</code> if you really
|
|
need), <code>new</code> will automatically use your
|
|
subclass methods.
|
|
</p>
|
|
<p>
|
|
You might need instead to define new <code>new...</code>
|
|
methods specific to your subclass to match any
|
|
<code>init...</code> specific to your subclass. For
|
|
example, if your subclass defines
|
|
</p>
|
|
<p>
|
|
<code>-initWithName:</code>
|
|
</p>
|
|
<p>
|
|
it might be handy for you to have a
|
|
</p>
|
|
<p>
|
|
<code>+newWithName:</code>
|
|
</p>
|
|
<p>
|
|
which combines <code>alloc</code> and
|
|
<code>initWithName:</code>. You would implement it as follows:
|
|
</p>
|
|
<p>
|
|
<code>
|
|
+ (id) newWithName: (NSString *)aName
|
|
{
|
|
return [[self alloc] initWithName: aName];
|
|
}
|
|
</code>
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="void" factory="yes">
|
|
<sel>poseAsClass:</sel>
|
|
<arg type="Class">aClass</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="void" factory="yes">
|
|
<sel>setVersion:</sel>
|
|
<arg type="int">aVersion</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="Class" factory="yes">
|
|
<sel>superclass</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="int" factory="yes">
|
|
<sel>version</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>awakeAfterUsingCoder:</sel>
|
|
<arg type="NSCoder*">aDecoder</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="Class">
|
|
<sel>classForArchiver</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="Class">
|
|
<sel>classForCoder</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="Class">
|
|
<sel>classForPortCoder</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>connection:</sel>
|
|
<arg type="NSConnection*">connection</arg>
|
|
<sel>handleRequest:</sel>
|
|
<arg type="NSDistantObjectRequest*">doreq</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>copy</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>dealloc</sel>
|
|
<desc>
|
|
<p>
|
|
<code>NSObject</code>'s implementation of this method
|
|
destroys the receiver, by returning the memory allocated
|
|
to the receiver to the system. After this method has been
|
|
called on an instance, you must not refer the instance in
|
|
any way, because it does not exist any longer. If you do,
|
|
it is a bug and your program might even crash with a
|
|
segmentation fault.
|
|
</p>
|
|
<p>
|
|
If you have turned on the debugging facilities for
|
|
instance allocation, <code>NSObject</code>'s
|
|
implementation of this method will also update the various
|
|
counts and monitors of allocated instances (see the
|
|
<code>GSDebugAllocation...</code> functions for more
|
|
info).
|
|
</p>
|
|
<p>
|
|
Normally you are supposed to manage the memory taken by
|
|
objects by using the high level interface provided by the
|
|
<code>retain</code>, <code>release</code> and
|
|
<code>autorelease</code> methods (or better by the
|
|
corresponding macros <code>RETAIN</code>,
|
|
<code>RELEASE</code> and <code>AUTORELEASE</code>), and by
|
|
autorelease pools and such; whenever the
|
|
release/autorelease mechanism determines that an object is
|
|
no longer needed (which happens when its retain count
|
|
reaches 0), it will call the <code>dealloc</code> method
|
|
to actually deallocate the object. This means that normally,
|
|
you should not need to call <code>dealloc</code> directly as
|
|
the gnustep base library automatically calls it for you when
|
|
the retain count of an object reaches 0.
|
|
</p>
|
|
<p>
|
|
Because the <code>dealloc</code> method will be called
|
|
when an instance is being destroyed, if instances of your
|
|
subclass use objects or resources (as it happens for most
|
|
useful classes), you must override <code>dealloc</code> in
|
|
subclasses to release all objects and resources which are
|
|
used by the instance, otherwise these objects and
|
|
resources would be leaked. In the subclass
|
|
implementation, you should first release all your subclass
|
|
specific objects and resources, and then invoke super's
|
|
implementation (which will do the same, and so on up in
|
|
the class hierarchy to <code>NSObject</code>'s
|
|
implementation, which finally destroys the object). Here
|
|
is an example of the implementation of
|
|
<code>dealloc</code> for a subclass whose instances have a
|
|
single instance variable <code>name</code> which needs to
|
|
be released when an instance is deallocated:
|
|
</p>
|
|
<p>
|
|
<code>
|
|
- (void) dealloc
|
|
{
|
|
RELEASE (name);
|
|
[super dealloc];
|
|
}
|
|
</code>
|
|
</p>
|
|
<p>
|
|
<code>dealloc</code> might contain code to release not
|
|
only objects, but also other resources, such as open
|
|
files, network connections, raw memory allocated in other
|
|
ways, etc.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="NSString*">
|
|
<sel>description</sel>
|
|
<desc>
|
|
<p>
|
|
The <code>description</code> method describes the reciever.
|
|
In the default GNUstep implementation, this returns an NSString
|
|
object giving the name of the class of the receiver and the
|
|
hexadecimal representation of the recievers address enclosed
|
|
in angle brackets.
|
|
</p>
|
|
<p>
|
|
Generally, classes other than NSObject will override this method
|
|
to provide a more informative description of their instances.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="NSString*">
|
|
<sel>descriptionWithLocale:</sel>
|
|
<arg type="NSDictionary*">aLocale</arg>
|
|
<desc>
|
|
The default (NSOBject) implementation of this method simply calls
|
|
the <code>description</code> method and discards the locale
|
|
information.
|
|
</desc>
|
|
<standards><GNUstep/></standards>
|
|
</method>
|
|
<method type="NSString*">
|
|
<sel>descriptionWithLocale:</sel>
|
|
<arg type="NSDictionary*">aLocale</arg>
|
|
<sel>indent:</sel>
|
|
<arg type="unsigned int">level</arg>
|
|
<desc>
|
|
The default (NSObject) implementation of this method simply calls
|
|
the <code>descriptionWithLocale:</code> method and discards the
|
|
level information.
|
|
</desc>
|
|
<standards><GNUstep/></standards>
|
|
</method>
|
|
<method type="NSString*">
|
|
<sel>descriptionWithLocale:</sel>
|
|
<arg type="NSDictionary*">aLocale</arg>
|
|
<sel>indent:</sel>
|
|
<arg type="unsigned int">level</arg>
|
|
<sel>to:</sel>
|
|
<arg type="id<GNUDescriptionDestination>">output</arg>
|
|
<desc>
|
|
The default (NSObject) implementation of this method simply calls
|
|
the <code>descriptionWithLocale:indent:</code> method and appends
|
|
the value returned by that method to the output object.
|
|
<p>
|
|
Property-list classes (NSString, NSArray, NSDictionary and
|
|
NSData) will override this method in order to efficiently
|
|
write descriptions of themselves into property lists.
|
|
</p>
|
|
</desc>
|
|
<standards><GNUstep/></standards>
|
|
</method>
|
|
<method type="void">
|
|
<sel>doesNotRecognizeSelector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>forwardInvocation:</sel>
|
|
<arg type="NSInvocation*">anInvocation</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="unsigned int">
|
|
<sel>hash</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>init</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>isEqual:</sel>
|
|
<arg type="id">anObject</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="IMP">
|
|
<sel>methodForSelector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="NSMethodSignature*">
|
|
<sel>methodSignatureForSelector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<desc>
|
|
Returns a method signature object representing the
|
|
method implemented in this object which corresponds to
|
|
the supplied selector.
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>mutableCopy</sel>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>performSelector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<sel>withObject:</sel>
|
|
<arg type="id">anArgument</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>performSelector:</sel>
|
|
<arg type="SEL">aSelector</arg>
|
|
<sel>withObject:</sel>
|
|
<arg type="id">anArgument</arg>
|
|
<sel>afterDelay:</sel>
|
|
<arg type="NSTimeInterval">delay</arg>
|
|
<sel>inModes:</sel>
|
|
<arg type="NSArray*">modes</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>replacementObjectForArchiver:</sel>
|
|
<arg type="NSArchiver*">anArchiver</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>replacementObjectForCoder:</sel>
|
|
<arg type="NSCoder*">aCoder</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>replacementObjectForPortCoder:</sel>
|
|
<arg type="NSPortCoder*">aCoder</arg>
|
|
<desc>
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>deallocNotificationsActive</sel>
|
|
<desc>
|
|
<p>
|
|
Returns a boolean indicating whether deallocation notification
|
|
has been turned on.
|
|
</p>
|
|
<p>
|
|
If deallocation notification is turned on, whenever an objects
|
|
retain count reaches zero (and it would normally be deallocated)
|
|
the <em>_dealloc</em> methiod is called and the object is only
|
|
deallocated if that method returns YES.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>setDeallocNotificationsActive:</sel>
|
|
<arg type="BOOL">flag</arg>
|
|
<desc>
|
|
<p>
|
|
Turns on (or off) deallocation notification.
|
|
</p>
|
|
<p>
|
|
If deallocation notification is turned on, whenever an objects
|
|
retain count reaches zero (and it would normally be deallocated)
|
|
the <em>_dealloc</em> methiod is called and the object is only
|
|
deallocated if that method returns YES.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>_dealloc</sel>
|
|
<desc>
|
|
<p>
|
|
Returns a boolean indicating whether the receiver should be
|
|
deallocated or not. The default implementation returns YES.
|
|
</p>
|
|
<p>
|
|
This method is called when an objects retain count reaches
|
|
zero (if deallocation notifications are active).
|
|
</p>
|
|
<p>
|
|
This method is provided so that you can take some sort of
|
|
action when objects are deallocated ... normally you would
|
|
override this method in your classes, but you could also
|
|
override it in a category of NSObject - and perform some
|
|
action whenever <em>any</em> object is deallocated.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
</class>
|
|
</chapter>
|
|
</body>
|
|
</gsdoc>
|