Re: Is NSDocument read outside init?
Re: Is NSDocument read outside init?
- Subject: Re: Is NSDocument read outside init?
- From: "Louis C. Sacha" <email@hidden>
- Date: Thu, 15 Apr 2004 03:09:47 -0700
Hello...
The documentation for NSDocument/NSDocumentController is
significantly out of sync with reality in several areas.
For example, the part below "If the file cannot be opened, displays
an attention panel informing the user and then returns nil." The
document does not display any type of alert panel, it simply returns
nil. The alert panel that _sometimes_ appears is part of the
openDocument: and (private) _openRecentDocument: methods of
NSDocumentController. <this is filed as Bug 3566930>
Among other problems, this leads to double alerts if the NSDocument
class raises an alert on failure in some situations (opening files
normally, from the menus) , and no alert at all if the NSDocument
class does not raise an alert in other situations (files dragged to
the app icon in the dock).
Also, the URL related methods are [basically useless] because there
are so many places in NSDocumentController and NSDocument where they
are hard-coded to fail if the URL is not a file URL (and if it is a
fileURL the file based methods are used instead). Implementing the
opening of non-file URLs in an NSDocument based application currently
requires overriding a significant number of methods in both
NSDocumentController and NSDocument.
The documentation for the NSDocumentController method
openDocumentWithContentsOfURL:display: claims that it invokes the
makeDocumentWithContentsOfURL:ofType:, but it doesn't. It does
isFileURL on the NSURL and then uses
makeDocumentWithContentsOfFile:ofType:, or fails returning nil if URL
is not a fileURL. This should probably work as it is documented, as
opposed to the documentation being updated to reflect the current
(MVC deficient) implementation.
Even if you call makeDocumentWithContentsOfURL:ofType: directly it
fails, returning nil, if a provided URL is not a fileURL. Instead it
should probably just call the document class's
initWithContentsOfURL:: method, and let the document class determine
if the URL is valid... Again, this should probably work as
documented, as opposed to the documentation being updated to reflect
the current implementation.
The fact that the recent documents list doesn't support non-file URLs
is understandable (although it would be nice if it was an option),
but it should at least be documented as working that way.
I haven't gotten around to filing a bug for the non-fileURL related
issues yet, since I've been busy writing my own versions of
NSDocument and NSDocumentController among other things :) I guess I
could just dump this verbatim into a bug report and see if anything
comes of it...
Louis
PS: Scott, if you have five minutes and want to fix two simple little
documentation bugs easily -- and help convince me that reporting
documentation bugs isn't an exercise in futility :) --, check out:
(3566931) Cocoa Foundation docs - NSClassDescription - attributeKeys
method desc....
The description for the instance method attributeKeys of the
NSClassDescription class, in the Foundation Objective-C reference
documentation, refers to using the NSObject instance method
inverseForRelationshipKey:, where it should refer to the NSObject
instance method attributeKeys.
(3566928) Cocoa Foundation docs- NSObject- classDescription method
description...
The description for the classDescription instance method of the
NSObject class, in the Foundation Objective-C reference
documentation, contains my favorite documentation bug so far. It
should probably read "NSObject's implementation simply calls
[NSClassDescription classDescriptionForClass:[self class]]." instead
of "NSObject's implementation simply calls [NSClassDescription
classDescriptionForClass:[self classDescription]."
Scott wrote:
The Reference docs say...
Initializes and returns an NSDocument object of document type
docType containing data stored in the file fileName. If the file
cannot be opened, displays an attention panel informing the user
and then returns nil. In opening the file, invokes the
readFromFile:ofType: method. If the document successfully opens the
file, it calls setFileName: and setFileType: with fileName and
docType, respectively, as arguments. This initializer is typically
invoked by NSDocumentControllers
makeDocumentWithContentsOfFile:ofType:.
...
I'm not sure that non-file URLs are supported here... I
suppose if you implement the URL read/write methods they could be
(my guess is that it falls back to the file versions if you don't)..
I've filed a request for clarifying the docs.
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.