home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / info-service / gopher / NeXT / Tree0.5 / treeobj / Making_Objects < prev    next >
Encoding:
Text File  |  1992-06-06  |  8.7 KB  |  200 lines
  1. Instructions for Making Your Own GOPHER IN A FOREST Objects
  2. ---------------------------------------------------------
  3. (ver 0.5)
  4.  
  5.  
  6. NOTE: I am maintaining an archive of GF objects on ion.rice.edu (as long
  7. as they don't take TOO much disk space). If you come up with something that's
  8. functional, I urge you to upload it to ion in /incoming. I will test them and
  9. move them to /pub/GFobjs. Feel free to download them from either location
  10. (at your own risk). Please try to limit your use of this server to nights
  11. and weekends.
  12.  
  13.  
  14. The new version of Gopher in a Forest has support for dynamically loading
  15. two types of objects. The first type of object is a subclass of Object and
  16. should (to be consistent) have a name ending with "Coord". This class allows
  17. you to put in your own algorithm for assigning node locations in 3d. TreeCoord
  18. is the default object used by Gopher in a Forest. It is already linked into
  19. the main program, and the source is present only as a programming example.
  20.  
  21. The other type of object must be a subclass of View and should have a name
  22. ending in "View". This type of object allows customization of the actual
  23. display. Again, TreeView is the default view for Gopher in a Tree and is
  24. already linked into the program. If you try to modify TreeView or TreeCoord,
  25. be SURE to give them a new name (filename must match class name).
  26.  
  27.  
  28. The "Coord" objects are designed to be simple and easy to implement. Each
  29. Coord object must implement all of the following methods :
  30.  
  31. -start:(Root *)top :(id)Pobject :(char *)path
  32.     This method passes the pointer to the top of the gopher web (top) and
  33.     the id of the GopherObj (discussed later) to your object. You should
  34.     store these variables (if you will need them) and return. This method
  35.     will be called once just after the object is created. The path
  36.     variable contains the path of Tree.app in case you need to load
  37.     your own .nib files, etc ...
  38.  
  39. -(char *)help:window :view
  40.     This method displays help and information about your object. There
  41.     are 3 methods you can use to actually display the information. First
  42.     and easiest is to ignore the passes variables and simply return a
  43.     pointer to a null terminated string containing your help message. This
  44.     message will be displayed for you. Second, you can use the window and
  45.     view ids to display the message yourself (if, for example, you
  46.     need to display an RTF file). You will need to makeKeyAndOrderFront 
  47.     the window, then display in the ScrollView. Be sure to return NULL
  48.     so your message doesn't get erased. Finally, you can open your
  49.     own window and do whatever you want. Just be sure to return NULL.
  50.  
  51. -setCoord:(Branch *)branch
  52.     This is the "meat" of the object. It receives a pointer to a branch
  53.     and is expected to fill the branch with x,y,z coordinates and return.
  54.     Several branch variables might be useful here : level contains the
  55.     level of the current branch (starting with 0 at the root), root points
  56.     to the Root structure where you can find the internet address, etc...
  57.     The file "gopher.h" contains all of the structure definitions and
  58.     explanations. This method is called whenever a new branch is created,
  59.     and once for each branch just after this object is created.
  60.  
  61. -preferences:sender
  62.     You will receive this event whenever the user wants to change the
  63.     preferences for this object. Feel free to ignore it if you don't
  64.     have any. If you want to support some options, you'll need to create
  65.     and load your own .nib file (more on this later).
  66.  
  67. You may, of course implement any other methods you'd like ...
  68.  
  69.  
  70. implementing a "View" object is somewhat more time consuming. All of the
  71. following methods must be implemented :
  72.  
  73. -initFrame:(NXRect *)myrect
  74.     You don't really HAVE to implement this object, but it is a good place
  75.     to do any initialization that needs to be done. Be sure to do a
  76.     [super initframe:myrect] as the first step in your routine.
  77.  
  78. -start:(Root *)Ptop :Pobject :(char *)path
  79.     Just like the -start method for the "Coord" objects. It gives you
  80.     access to the entire gopher web and to the main program object. In
  81.     this case you will definitely need the Ptop pointer for refreshing
  82.     the display, so be sure to save it.
  83.  
  84. -step:(Branch *)myloc
  85.     This method will be called several times each second (currently 
  86.     every .2 seconds). myloc points to the currently selected branch. You
  87.     will need to update the display if necessary. You can also use this
  88.     method for animation, etc ...
  89.  
  90. -drawSelf:(NXRect *)rects :(int)rectCount
  91.     This is the standard subview method which you must implement to
  92.     do the actual drawing. It is not called directly by the main program,
  93.     rather it is one of the methods that gets called when you call
  94.     display. If you intend to draw a lot of lines,etc ... you should 
  95.     probably learn how to use DPSDoUserPath or your View may become
  96.     unbearably slow. 
  97.  
  98. -refresh:(Branch *)myloc :(int)speed
  99.     This method is expected to make the display current. If the user
  100.     selects a new branch, this method must "move" the user to the
  101.     new location. It is wise, therefore to store myloc in a static
  102.     variable for the next time this method is called (so you can tell
  103.     if you've moved). Sometimes -refresh is called with a NULL pointer.
  104.     When this happens, you are expected to move (rapidly) to the top node
  105.     in the web and redisplay. speed contains an integer from 0 ("jump" to
  106.     the new location) to 100 (very slow flying to new location). Currently
  107.     you will receive only a few discrete values in this range. 80 should
  108.     be considered normal speed.
  109.  
  110. -preferences:sender
  111.     Just like the "Coord" method, you will receive this message when
  112.     the user wants to change some preferences for your view. If you want
  113.     to make use of this method, you'll probably need to make your
  114.     own .nib file (more later). If you don't support any preferences, it's
  115.     a good idea to say so in your "help" method, then have this method
  116.     call help.
  117.  
  118. -help:window :view
  119.     Just like the Coord -help method.
  120.     
  121.  
  122. The only "global" preference that's currently supported is flying speed. If you
  123. don't want to load your own .nib file, there are a few other ways you can still
  124. allow the user to make some changes (see TreeView). By implementing the
  125. -acceptsFirstResponder, -keyDown, -keyUp, etc ... methods, you can allow the
  126. user to move around and/or change the way the view is displayed.
  127.  
  128. For those of you who aren't big on data structures, the following fragment
  129. will climb the entire gopher web and call the DOIT routine exactly once for
  130. each Branch in the web :
  131.  
  132. {
  133. Root *curr;
  134.  
  135. for (curr=top; curr!=NULL; curr=curr->next) Climb(&curr->branch);
  136. }
  137.  
  138. void Climb(Branch *branch)
  139. {
  140. Branch *cur;
  141.  
  142. cur=branch;
  143.  
  144. for (cur=branch; cur!=NULL; cur=cur->next) {
  145.     DOIT(cur);
  146.     /* don't forget cur->link when drawing */
  147.     if (cur->sub!=NULL) Climb(cur->sub);
  148. return;
  149. }
  150.  
  151.  
  152. There are several useful methods supported by the main program's GopherObj
  153. which your objects should have access to :
  154.  
  155. -top:sender
  156.     Go to the top of the web and redisplay.
  157.  
  158. -goto:(Branch *)branch
  159.     Pretty obvious. This "moves" to the passed branch. It will send the
  160.     necessary refresh messages and update the browsers.
  161.  
  162. -(int)Read:(Branch *)branch
  163.     This causes the passed branch to be read. If it is a directory, it
  164.     is read in and added to the web. If it is a file it is read and 
  165.     displayed. Other types aren't supported yet.
  166.  
  167. (float) frand((float)lo,(float)hi)
  168.     This is actually a global subroutine you may use. It returns a floating
  169.     point random number between lo and hi.
  170.  
  171.  
  172. If you think of any other useful methods I should implement, please let me know.
  173.  
  174.  
  175. Once you've written your object(s), follow the following steps to add them
  176. to Gopher in a Forest :
  177.  
  178. 1. Compile and strip your object (see the included Makefile for 
  179.    necessary flags, etc...)
  180. 2. You can't add new objects to Gopher in a Forest while it's running yet 
  181.    (next release), so for now you'll have to do it manually. Move your .o
  182.    and any .nib files to the Tree.app directory. Next, edit the "Prefs" file
  183.    in the same directory and add the name of your object to the file. Coord
  184.    objects go before the #, and View objects go after. The first line of the
  185.    file is the default "root" host.
  186. 3. Run Tree from the command line.
  187. 4. Select your new object in one of the Forest browsers. If everything goes
  188.    well (very unlikely), your object will be loaded and the results will
  189.    be displayed. If something goes wrong with the dynamic loading, the
  190.    errors will be displayed on stderr. If you can't figure out what the problem
  191.    is, or if you think it's my fault (it very well may be at this point),
  192.    send me some mail (steve@ion.rice.edu). You may also want to upload the
  193.    problematical source to ion.rice.edu in the submissions directory.
  194.  
  195. NOTE: Ignore the initial "objc: class `classname' not linked into the
  196. application" message. It will go away in the next release, and is not a bug.
  197. If you receive this message twice for the same object, THEN there is a
  198. problem ...
  199.  
  200.