Improved documentation.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/apps/gorm/trunk@20800 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,8 @@
+2005-02-26 22:14 Gregory John Casamento <greg_casamento@yahoo.com>
+
+	* Documentation/Gorm.texi: Updating documentation to contain
+	information answering recent questions about encoding.
+
 2005-02-20 12:48 Gregory John Casamento <greg_casamento@yahoo.com>
 
 	* GModelDecoder.m: Mapped NSCStringText to NSText.

Documentation/Gorm.texi

@@ -692,6 +692,24 @@ This is only used when the user has associated a custom class with an existing i
 
 This array is used to form the connections after the .gorm file is loaded.  The method @samp{[... establishConnection]} is never called on either NSNibControlConnector or NSNibOutletConnector objects while in Gorm.   This prevents the connections from having any effect while they are being edited in Gorm itself.   Once they are loaded, the establishConnection method is called and the connections are made.
 
+@section Custom Class Encoding
+
+Custom objects are an interesting challenge in Gorm.  By definition, custom classes are not known to Gorm, unless they are in a palette (covered elsewhere).   For classes which are not in a palette instances of these classes in Gorm are encoding in one of three ways:
+
+@itemize bullet
+@item A Proxy - This is a standin object which takes the place of the custom object.   This is usually used when the superclass of the object is a non-graphical object, such as a controller.  The init message is called on this object when it's unarchived.
+@item A Custom View - This is a standin view object similar to the one descrribed above, but it is a subclass of NSView.  When this is used the initWithFrame: message is called on the view instance which is created (based on what view subclass the user selects)
+@item A Template Class - Probably the most interesting of the three.  This is a standin class which uses an existing instance created in Gorm to build a custom subclass from.   For instance when a window subclass is created, call it MyWindow, a template class called GSWindowTemplate is used to hold the NSWindow created in Gorm as well as the name of the subclass to be created when the class is unarchived outside of Gorm as well as some additional information.   When the classes are unarchived in the running app, the designated initializer for that class will be invoked, except in the case of NSControl subclasses.  See the Apple documentation for more information.
+@end itemize
+
+All custom instances have awakeFromNib invoked on them when they are unarchived from the .gorm file.   This allows the user to do whatever additional setup that needs to be done, such as setting attribute.
+
+@subsection Restrictions On Your Custom Subclasses
+
+The restrictions here are the same as those in Apple's InterfaceBuilder.   In general, you cannot have additional information which is expected to be decoded in an initWithCoder: method from a custom class which uses one of the methods in the previous section.   This is because, by definition, Gorm doesn't know anything about these classes and allowing you to use them in Gorm in this way is a convenience to make it simpler for the developer.  Gorm therefore, must use one of the proxies to encode the class since it cannot encode the class directly.
+
+How can you get your classes into Gorm, you say?   I'm pleased that you asked me that question.  The best way to make your class known to Gorm so that you don't need to worry about the above restriction is to add a palette which contains your class.  In this way, because you're literally linking the class into Gorm, you're making the class and it's structure known to Gorm so that it can encode the class directly.   With the new palette loaded you can load and save classes containing real instances, not proxies, of your class encoded directly in the .gorm file.
+
 @chapter Frequently Asked Questions
 
 @subsection Should I modify the data.classes of file in the .gorm package?