Re: Serious Questions
Re: Serious Questions
- Subject: Re: Serious Questions
- From: "Dennis C. De Mars" <email@hidden>
- Date: Sat, 26 May 2001 17:33:00 -0700
Several of the responses to this question seem to be predicated on the
belief that there is no serious hole in Cocoa documentation and that you
will be all right if you just change your approach.
The fact of the matter is, however, that there _are_ serious holes in the
Cocoa documentation because most of the existing documentation was derived
from the original NextStep/OpenStep documentation, and there are a couple of
major documents that haven't been updated to Cocoa yet, nor has Apple given
an indication of if and when they would be updated. (However, one of them
seems to be the basis for the "Learning Cocoa" book which was distributed at
WWDC and should be generally available soon).
Now, the NextStep framework which basically becomes Cocoa was the best
documented object-oriented framework I've ever seen. The two Macintosh
frameworks I've had experience with, MacApp and PowerPlant, both had a
similar deficiency in their documentation.
I think any object-oriented framework needs the following three levels of
documentation:
1) An overview of the framework explaining the architecture of the framework
and the way the main classes implementing that architecture are used and
interact with each other.
2) For all but the most trivial class, each class should have an overview
explaining the architecture of that class, the main methods you might be
interested in using or overriding, and the way the class interacts which
other classes.
3) A reference document defining the operation of every method.
Both MacApp and PowerPlant had good documentation at levels 1 and 3, but
basically none at level 2. Any class that was not mentioned at level one was
basically left undocumented. In each case I thought this was initially an
oversight to be remedied as the framework matured, and in each case I was
dismayed to finally realize that the missing documentation was not
forthcoming and the existing documentation was apparently felt to be
adequate by the vendor. The only way to fill the void left by the missing
documentation was to read the source code, and this is actually how these
guys managed to get away with not providing complete documentation. I
consider this a bad thing, though; you should _not_ have to read source code
to figure out how to use a framework.
Now, since the source for NextStep was never provided, they didn't have this
option and so they were forced to provide good documentation at level 2.
The interesting thing, though, is that the level 1 documentation was never
updated for Cocoa, so we have excellent level 2 and 3 documentation for
Cocoa but the level 1 seems to be missing.
Anyhow, take a look at the legacy documents which constitute the former
level 1 documentation for NexStep/OpenStep/Rhapsody. First of all, the book
"Tools and Techniques" contains a complete description of how the Interface
Builder worked, much of which still applies to the current Interface
Builder. It is included with the documentation installed from the "Developer
Tools" CD. Look in the path
Developer/Documentation/Cocoa/DevEngGuide/Book/Tools&Techniques.pdf
The other book is called "Discovering OpenStep" and it has a series of
increasingly complex tutorials (the first one is simply the Currency
Converter tutorial which has already been updated to Cocoa). You can find
this at:
http://developer.apple.com/techpubs/macosx/Legacy/DeveloperTutorial/Rhapsody
_DiscOS.pdf
An updated version of this appears to be a large part of the new book
"Learning Cocoa" which will probably answer a lot of your questions in
general. but it couldn't hurt to download the legacy document -- it's free.
I assure you that you are not alone in finding parts of the Interface
Builder unintuitive. It does things differently from other GUI builders and
is not consistent in itself, a lot of situations are special-cased. This is
probably not apparent to those who already know the interface, but it does
cause some consternation in learning.
To give a simple example, I had a document that consisted of an image I
synthesize and I wanted to make it scrollable. Well, a text view with scroll
bars is available in the IB palette, but I flailed around trying to figure
out how to give scroll bars to any other kind of view. In other GUI builders
there would usually be some kind of a scroll view in which you would imbed
your own view. You would drag the scroll view to the palette, then drag your
own view into the scroll view. But there was no such beast in the IB
palettes.
Now, Cocoa does have a scroll view and programmatically it is just as I
described. How to tell IB this is what I wanted was the problem. Reading the
legacy documents, I found all you need to do is put the view you want to be
scrollable into a window, select it and then select a menu command in IB to
give it scroll bars. This menu command creates the scroll view and imbeds
your view inside it.
Extremely simple, but not so simple to find when it is not the solution you
expected.
BTW, this question was asked and answered on a mailing list, but not this
one. You'd have to search the Omni mailing list archives to find it. Since
many beginners will probably end up joining this list and not knowing about
the older Omni lists, I would suggest that all beginners just ask away.
Maybe it will be an encouragement to Apple to get the rest of the
documentation out (Learning Cocoa will fill a big gap; I still think they
need to get the equivalent of an updated "Tools & Techniques" out. Maybe
they are on the verge of doing so. I hope so.) Developers really shouldn't
be expected to have to search mailing list archives just to figure out the
basic workings of the Interface Builder.
- Dennis D.
on 5/26/01 12:57 PM, email@hidden at email@hidden wrote:
>
I do not understand how a person is supposed to get started with Cocoa
>
when there is little, and very often NO documentation for even the
>
simplest things. I just dragged over a pop-up button to try and figure
>
out how that might work--not actually connecting it to anything, but
>
just to see if I could get it working on an interface level--but after
>
thirty minutes of looking everywhere I could think of I'm still at a
>
complete loss. The inspector window went away and I could not figure
>
out how to get it back. Searching Interface Builder's "Help" found ZERO
>
hits for "inspector"! Now that's scary. The only thing I got to work
>
was changing the names of the three choices offered. But how do I
>
reduce that to only 2 choices? Or increase it to 4 or 5 items? Every
>
time I turn around someone is touting Cocoa as an easy thing to learn.
>
For whom, I wonder?
>
>
If I'm the problem then it must be that I don't have sufficient
>
background because I just had a full battery of cognitive tests and I'm
>
still a pretty smart guy. Damn smart, in fact. So is a couple of
>
courses 25 years ago in Fortran and a little TeX macro writing in the
>
meantime way too little to start from? Do I need to sell my shack here
>
in the Northern woods and move someplace where there are a few Gurus I
>
can hang out with and maybe pick something up that way? Buy a few
>
rounds? Do I need a goat, or will a chicken be sufficient sacrifice?
>
If I go to the dark side will I find the same problem there?
>
>
Or is Apple giving the developer's tools disk to everyone who buys a
>
retail copy of OS X just a PR stunt? If I hang in there will this
>
dismal situation improve? Are the documentation floodgates soon to be
>
opened?
>
>
Finally, is it really okay to ask low-level questions in this forum?
>
Because I have a ton of them! Or should I just give this up and start a
>
Cocoa Cult list for the hoards of wannabes like me? Sorry for being so
>
flip, but it's the only way I know how to avoid screaming!
>
_______________________________________________
>
cocoa-dev mailing list
>
email@hidden
>
http://www.lists.apple.com/mailman/listinfo/cocoa-dev