XLogo Source Documentation Documentation Version: Draft 2 - 11/23/2003 Copyright 2003 Jeff Skrysak Table of Contents I. Introduction to the software II. Explanation of the software design A. Introduction to the MVC Paradigm B. Design of XLogo III. Turtle Class IV. LogoParser Class V. Controller Class VI. TurtleView Class I. Introduction to the software XLogo was created to give Mac OS X a free version of a Logo program, for younger learners, so that they can learn LOGO like their counterparts did in the 1970's and 1980's. A side effect, or added bonus, is the source code itself. It should also be written in a manner that teaches programming making both the software and its source code a learning tool. II. Explanation of the software design (MVC) A. Introduction to the MVC Paradigm The true progenitors and perhaps sole originators of object oriented programming are the languages Simula 67 and SmallTalk. These programming language, developed in the 1960's and 1970's commonly used a software design paradigm called MVC, or Model-View-Controller. That is the one we will focus on in this document. [Note: There are many object-oriented design paradigms, and a good number of them are now well-documented and named. For examples of this, see the book "Design Patterns" written by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides. (ISBN 0-201-63361-2)] The MVC design separates the view (V), from the data model (M) and control (C). This just means that the code used to show the user information, including a GUI, is separate from the management of the data itself as well as the interaction between the GUI and data. A better explanation follows: The View. This only houses GUI elements such as buttons, sliders, text fields and drawing areas. It has *some* intelligence to it, as needed, but is mostly a way to get user data and also return data to the user. The Controller. This class/object is the middle-man, the messenger. It can have as much intelligence or functionality as you like, but not enough to make the model objects useless. It's job is to accept actions or new user input from the View and send them to the Model object(s). It also accepts actions or new information from the Model object(s) and sends them to the View. The Model. This is where the information is managed, stored, massaged, computed, etc.. It can be composed of multiple objects if necessary. Generally speaking, there should only be one main View, one Controller, and any number of Model objects. Some programs, depending on the speed needed, size of the program, or simplicity can merge any of the objects above or modify the interactions. For example, in a computer game where speed of drawing is ideal, the view can talk directly to the model. Also, if a program is quite simple, the controller and model can be combined into one. B. Design of XLogo XLogo was designed using the MVC paradigm explained above. The TurtleView object is the View of MVC and it subclasses NSView. Basically, it's just a drawing area. The rest of the GUI is housed in the NIB file and is managed accordingly. The Controller object is the Controller portion of MVC and in this case, has some functionality to it making it more of the "brain". The Turtle and CommandMaster objects model the data as well as manage it. However, most of the actual heavy lifting is done in the LogoParser object, and other smaller objects such as Controller, LogoParserExpression, and Utilities are helper objects to the main ones. III. Turtle Class The Turtle class holds the turtle's location, heading, and speed. It also provides accessor methods to manage and retrieve those values. It subclasses NSObject. Below is the header information (as of XLogo version 0.3): @interface Turtle : NSObject { IBOutlet id errorView; IBOutlet id outputView; NSString *turtleName; // Name of the turtle NSColor *turtleColor; // Color of the turtle float turtleSize; // Size of the turtle (normally 1.0) const float *turtleShape; // Shape of the turtle (polygon points) NSBezierPath *path; NSPoint location; // Location of the turtle float direction; // Direction they are facing float penColor; // Drawing color int pen; // Pen up or pen down BOOL visible; // Show the turtle to the user or not } // Creation and destruction - (id)initWithName:(NSString *)aName andColor:(NSColor *)aColor; - (void)dealloc; // Accessor methods - (void)setTurtleName:(NSString *)aName; - (NSString *)turtleName; - (void)setTurtleColor:(NSColor *)aColor; - (NSColor *)turtleColor; - (void)setTurtleSize:(float)aTurtleSize; - (float)turtleSize; - (void)setTurtleShape:(const float *)aShape; - (void)setOutputView:(id)aOutputView; - outputView; - (void)setErrorView:(id)aErrorView; - errorView; - (NSPoint)location; - (BOOL)setLocation:(NSPoint)aLocation; - (float)direction; - (BOOL)setDirection:(float)aDirection; - (BOOL)visible; - (BOOL)setVisible:(BOOL)aVisible; - (float)penColor; - (BOOL)setPenColor:(float)aPenColor; // Draw Commands - (void)drawTriangleAt:(NSPoint)aPoint heading:(float)aDirection withColor:(NSColor *)aColor; - (void)drawSquareAt:(NSPoint)aPoint heading:(float)aDirection withColor:(NSColor *)aColor length:(float)sideLength; - (void)drawTurtleAt:(NSPoint)aPoint heading:(float)aDirection withColor:(NSColor *)aColor; - (void)drawAtOffset:(NSPoint)aPoint; // Movement commands - (BOOL)moveTo:(NSPoint)aPoint; - (BOOL)move:(float)aSteps stepsInDirection:(float)aDirection; - (BOOL)clearGraphics; - (BOOL)home; - (BOOL)north; - (BOOL)northWest; - (BOOL)west; - (BOOL)southWest; - (BOOL)south; - (BOOL)southEast; - (BOOL)east; - (BOOL)northEast; - (BOOL)back:(float)aSteps; - (BOOL)forward:(float)aSteps; - (BOOL)turnLeft:(float)aDegrees; - (BOOL)turnRight:(float)aDegrees; - (BOOL)penUp; - (BOOL)penErase; - (BOOL)penDown; - (BOOL)hide; - (BOOL)show; IV. LogoParser Class The LogoParser class manages the LOGO commands entered in by the user. It is responsible for storing them, verifying their validity, and perhaps interpreting them. It subclasses NSObject. Below is the header information (as of XLogo version 0.3): @interface LogoParser : NSObject { IBOutlet id outputView; IBOutlet id errorView; NSMutableArray *turtles; NSMutableArray *listeningTurtles; // the active turtles const unichar *listing; const unichar *programCounter; NSMutableArray *stack; unsigned stackIndex; NSMutableArray *variables; } // Creation and destruction - (id)initWithOutputView:(id)aOutputView errorView:(id)aErrorView; - (void)dealloc; // Turtle management - (void)addTurtle:(Turtle *)aTurtle; - (void)removeTurtle:(Turtle *)aTurtle; - (void)activateTurtle:(Turtle *)aTurtle; - (void)deactivateTurtle:(Turtle *)aTurtle; - (void)deactivateAllTurtles; - (NSArray *)turtles; - (void)setOutputView:(id)aOutputView; - outputView; - (void)setErrorView:(id)aErrorView; - errorView; - (void)setListing:(NSString *)aListing; //- (void)setLines:(NSArray *)aLines; //- (NSArray *)lines; - (long)doCommand; IV. Controller Class The Controller class is a data middle-man, and in this case is used for preferences. Below is the header information (as of XLogo version 0.3): @interface Controller : NSObject { IBOutlet id preferencesPanel; IBOutlet id maximumTurtles; IBOutlet id lineWidth; IBOutlet id saveSpeed; } // Preferences methods - (IBAction)preferences:(id)sender; - (IBAction)cancelPreferences:(id)sender; - (IBAction)savePreferences:(id)sender; IV. TurtleView Class The TurtleView class is just a subclass of NSView and is used as the drawing area of the turtle. Below is the header information (as of XLogo version 0.3): @interface TurtleView : NSView { IBOutlet id parser; NSMutableArray *drawCommands; NSBezierPath *path; float paperColor; BOOL initializeFlag; float lineWidth; NSString *lineWidthString; NSUserDefaults *defaults; } // Creation and destruction - (id)init; - (void)dealloc; // Drawing - (void)drawRect:(NSRect)rect; - (void)addCommand:(DrawCommand *)drawCommand; - (BOOL)clear; // Accessor methods - (BOOL)setPaperColor:(float)aPaperColor; - (float)paperColor; - (BOOL)setPenSize:(float)newLineWidth; - (float)penSize;