From a40fbd79618d04b97a9362e4102ad08af9581f57 Mon Sep 17 00:00:00 2001 From: Ross Boucher Date: Wed, 10 Sep 2008 15:11:37 -0700 Subject: [PATCH] Add the first draft of documentation inline. --- AppKit/CPAnimation.j | 135 ++++++- AppKit/CPApplication.j | 180 ++++++++- AppKit/CPButton.j | 293 +++++++++++++- AppKit/CPClipView.j | 32 +- AppKit/CPCollectionView.j | 166 +++++++- AppKit/CPColor.j | 168 +++++++- AppKit/CPColorPanel.j | 79 +++- AppKit/CPColorPicker.j | 32 +- AppKit/CPColorWell.j | 31 +- AppKit/CPControl.j | 116 +++++- AppKit/CPCookie.j | 23 ++ AppKit/CPDocument.j | 230 ++++++++++- AppKit/CPDocumentController.j | 92 ++++- AppKit/CPDragServer.j | 43 +- AppKit/CPEvent.j | 210 +++++++++- AppKit/CPFont.j | 56 ++- AppKit/CPFontManager.j | 19 +- AppKit/CPGeometry.j | 235 +++++++++++ AppKit/CPGraphicsContext.j | 29 +- AppKit/CPImage.j | 81 +++- AppKit/CPImageView.j | 63 +++ AppKit/CPKulerColorPicker.j | 5 + AppKit/CPMenu.j | 204 +++++++++- AppKit/CPMenuItem.j | 250 +++++++++++- AppKit/CPOutlineView.j | 35 +- AppKit/CPPanel.j | 37 ++ AppKit/CPPasteboard.j | 76 +++- AppKit/CPPopUpButton.j | 189 ++++++++- AppKit/CPProgressIndicator.j | 105 ++++- AppKit/CPResponder.j | 108 ++++- AppKit/CPScrollView.j | 144 ++++++- AppKit/CPScroller.j | 89 ++++- AppKit/CPSegmentedControl.j | 161 +++++++- AppKit/CPShadow.j | 27 +- AppKit/CPSlider.j | 94 ++++- AppKit/CPSliderColorPicker.j | 3 + AppKit/CPStringDrawing.j | 3 + AppKit/CPTabView.j | 120 +++++- AppKit/CPTabViewItem.j | 65 ++- AppKit/CPTableColumn.j | 120 +++++- AppKit/CPTableView.j | 106 ++++- AppKit/CPTextField.j | 124 +++++- AppKit/CPToolbar.j | 84 +++- AppKit/CPToolbarItem.j | 141 ++++++- AppKit/CPView.j | 448 +++++++++++++++++++-- AppKit/CPWindow.j | 505 +++++++++++++++++++++++- AppKit/CPWindowController.j | 68 +++- AppKit/Cib/CPCustomView.j | 1 + AppKit/CoreAnimation/CAAnimation.j | 65 ++- AppKit/CoreAnimation/CALayer.j | 260 +++++++++++- AppKit/CoreGraphics/CGAffineTransform.j | 41 +- AppKit/CoreGraphics/CGColor.j | 99 +++++ AppKit/CoreGraphics/CGColorSpace.j | 28 ++ AppKit/CoreGraphics/CGContext.j | 210 +++++++++- AppKit/CoreGraphics/CGGeometry.j | 32 ++ AppKit/Platform/DOM/CPDOMWindowBridge.j | 36 ++ AppKit/_CPImageAndTitleView.j | 2 +- Foundation/CPArray.j | 363 ++++++++++++++++- Foundation/CPCoder.j | 67 +++- Foundation/CPDictionary.j | 102 ++++- Foundation/CPEnumerator.j | 14 + Foundation/CPException.j | 67 +++- Foundation/CPIndexSet.j | 155 +++++++- Foundation/CPInvocation.j | 65 ++- Foundation/CPKeyValueCoding.j | 4 + Foundation/CPKeyedArchiver.j | 154 +++++++- Foundation/CPKeyedUnarchiver.j | 129 +++++- Foundation/CPNotification.j | 46 +++ Foundation/CPNotificationCenter.j | 49 ++- Foundation/CPNull.j | 10 +- Foundation/CPNumber.j | 17 +- Foundation/CPObject.j | 186 ++++++++- Foundation/CPRange.j | 71 ++++ Foundation/CPRunLoop.j | 36 ++ Foundation/CPSortDescriptor.j | 63 ++- Foundation/CPString.j | 202 +++++++++- Foundation/CPURLConnection.j | 74 +++- Foundation/CPURLRequest.j | 47 +++ Foundation/CPURLResponse.j | 10 + Foundation/CPUndoManager.j | 140 ++++++- Foundation/CPValue.j | 25 ++ Objective-J/Object.j | 2 +- 82 files changed, 8113 insertions(+), 383 deletions(-) diff --git a/AppKit/CPAnimation.j b/AppKit/CPAnimation.j index b3a10f93fb..11eed88a5a 100644 --- a/AppKit/CPAnimation.j +++ b/AppKit/CPAnimation.j @@ -24,14 +24,53 @@ import import "CAMediaTimingFunction.j" - -CPAnimationEaseInOut = 0, -CPAnimationEaseIn = 1, -CPAnimationEaseOut = 2, +/* + @global + @group CPAnimationCurve +*/ +CPAnimationEaseInOut = 0; +/* + @global + @group CPAnimationCurve +*/ +CPAnimationEaseIn = 1; +/* + @global + @group CPAnimationCurve +*/ +CPAnimationEaseOut = 2; +/* + @global + @group CPAnimationCurve +*/ CPAnimationLinear = 3; ACTUAL_FRAME_RATE = 0; +/* + Manages an animation. Contains timing and progress information. + + @delegate -(BOOL)animationShouldStart:(CPAnimation)animation; + Called at the beginning of startAnimation. + @param animation the animation that will start + @return YES allows the animation to start. + NO stops the animation. + + @delegate -(void)animationDidEnd:(CPAnimation)animation; + Called when an animation has completed. + @param animation the animation that completed + + @delegate -(void)animationDidStop:(CPAnimation)animation; + Called when the animation was stopped (before completing). + @param animation the animation that was stopped + + @delegate - (float)animation:(CPAnimation)animation valueForProgress:(float)progress; + The value from this method will be returned when CPAnimation's + currentValue method is called. + @param animation the animation to obtain the curve value for + @param progress the current animation progress + @return the curve value +*/ @implementation CPAnimation : CPObject { CPTimeInterval _startTime; @@ -41,19 +80,25 @@ ACTUAL_FRAME_RATE = 0; CAMediaTimingFunction _timingFunction; float _frameRate; - CPAnimationProgress _progress; + float _progress; id _delegate; CPTimer _timer; } +/* + Initializes the animation with a duration and animation curve. + @param aDuration the length of the animation + @param anAnimationCurve defines the animation's pace + @throws CPInvalidArgumentException if an invalid animation curve is specified +*/ - (id)initWithDuration:(float)aDuration animationCurve:(CPAnimationCurve)anAnimationCurve { self = [super init]; if (self) { - _duration = aDuration; + _duration = MAX(0.0, aDuration); _animationCurve = anAnimationCurve; _frameRate = 60.0; } @@ -61,6 +106,11 @@ ACTUAL_FRAME_RATE = 0; return self; } +/* + Sets the animation's pace. + @param anAnimationCurve the animation's pace + @throws CPInvalidArgumentException if an invalid animation curve is specified +*/ - (void)setAnimationCurve:(CPAnimationCurve)anAnimationCurve { _animationCurve = anAnimationCurve; @@ -77,46 +127,87 @@ ACTUAL_FRAME_RATE = 0; case CPAnimationEaseOut: timingFunctionName = kCAMediaTimingFunctionEaseOut; break; + + default: [CPException raise:CPInvalidArgumentException + reason:"Invalid value provided for animation curve"]; + break; } _timingFunction = [CAMediaTimingFunction functionWithName:timingFunctionName]; } +/* + Returns the animation's pace +*/ - (CPAnimationCurve)animationCurve { return _animationCurve; } +/* + Sets the animation's length. + @param aDuration the new animation length + @throws CPInvalidArgumentException if aDuration is negative +*/ - (void)setDuration:(CPTimeInterval)aDuration { + if (aDuration < 0) + [CPException raise:CPInvalidArgumentException reason:"aDuration can't be negative"]; + _duration = aDuration; } +/* + Returns the length of the animation. +*/ - (CPTimeInterval)duration { return _duration; } -- (void)setFramesPerSecond:(float)framesPerSecond +/* + Sets the animation frame rate. This is not a guaranteed frame rate. 0 means to go as fast as possible. + @param frameRate the new desired frame rate + @throws CPInvalidArgumentException if frameRate is negative +*/ +- (void)setFrameRate:(float)frameRate { - _frameRate = framesPerSecond; + if (frameRate < 0) + [CPException raise:CPInvalidArgumentException reason:"frameRate can't be negative"]; + + _frameRate = frameRate; } +/* + Returns the desired frame rate. +*/ - (float)frameRate { return _frameRate; } +/* + Returns the animation's delegate +*/ - (id)delegate { return _delegate; } +/* + Sets the animation's delegate. + @param aDelegate the new delegate +*/ - (void)setDelegate:(id)aDelegate { _delegate = aDelegate; } +/* + Starts the animation. The method calls animationShouldStart: + on the delegate (if it implements it) to see if the animation + should begin. +*/ - (void)startAnimation { // If we're already animating, or our delegate stops us, animate. @@ -133,11 +224,16 @@ ACTUAL_FRAME_RATE = 0; }, 1); // must be 1ms not 0 for IE. //_duration * 1000 / _frameRate); } +/* + @ignore +*/ - (void)animationTimerDidFire:(CPTimer)aTimer { var elapsed = new Date() - _startTime, progress = MIN(1.0, 1.0 - (_duration - elapsed / 1000.0) / _duration); -++ACTUAL_FRAME_RATE; + + ++ACTUAL_FRAME_RATE; + [self setCurrentProgress:progress]; if (progress == 1.0) @@ -151,6 +247,9 @@ ACTUAL_FRAME_RATE = 0; } +/* + Stops the animation before it has completed. +*/ - (void)stopAnimation { if (!_timer) @@ -162,21 +261,35 @@ ACTUAL_FRAME_RATE = 0; [_delegate animationDidStop:self]; } +/* + Returns YES if the animation + is running. +*/ - (BOOL)isAnimating { return _timer; } -- (void)setCurrentProgress:(CPAnimationProgress)aProgress +/* + Sets the animation's progress. + @param aProgress the animation's progress +*/ +- (void)setCurrentProgress:(float)aProgress { _progress = aProgress; } -- (CPAnimationProgress)currentProgress +/* + Returns the animation's progress +*/ +- (float)currentProgress { return _progress; } +/* + Returns the animation's timing progress. +*/ - (float)currentValue { if ([_delegate respondsToSelector:@selector(animation:valueForProgress:)]) diff --git a/AppKit/CPApplication.j b/AppKit/CPApplication.j index 290581fb1c..f2c81c12a2 100644 --- a/AppKit/CPApplication.j +++ b/AppKit/CPApplication.j @@ -37,6 +37,28 @@ CPRunStoppedResponse = -1000; CPRunAbortedResponse = -1001; CPRunContinuesResponse = -1002; +/* + CPApplication is THE way to start up the Cappucino framework for your application to use. + Every GUI application has exactly one instance of CPApplication (or of a custom subclass of + CPApplication). Your program's main() function can create that instance by calling the + CPApplicationMain function. A simple example looks like this: + + 
+    function main(args, namedArgs)
+    {
+        CPApplicationMain(args, namedArgs);
+    }
+
+ + @delegate -(void)applicationDidFinishLaunching:(CPNotification)aNotification; + Sent from the notification center after the app initializes, but before + receiving events. + @param aNotification contains information about the event + + @delegate -(void)applicationWillFinishLaunching:(CPNotification)aNotification; + Sent from the notification center before the app is initialized. + @param aNotification contains information about the event +*/ @implementation CPApplication : CPResponder { CPArray _eventListeners; @@ -59,6 +81,11 @@ CPRunContinuesResponse = -1002; CPArray _args; } +/* + Returns the singleton instance of the running application. If it + doesn't exist, it will be created, and then returned. + @return the application singleton +*/ + (CPApplication)sharedApplication { if (!CPApp) @@ -67,6 +94,11 @@ CPRunContinuesResponse = -1002; return CPApp; } +/* + Initializes the Document based application with basic menu functions. + Functions are New, Open, Undo, Redo, Save, Cut, Copy, Paste. + @return the initialized application +*/ - (id)init { self = [super init]; @@ -142,6 +174,12 @@ CPRunContinuesResponse = -1002; // Configuring Applications +/* + Sets the delegate for this application. The delegate will receive various notifications + caused by user interactions during the application's run. The delegate can choose to + react to these events. + @param aDelegate the delegate object +*/ - (void)setDelegate:(id)aDelegate { if (_delegate == aDelegate) @@ -179,11 +217,20 @@ CPRunContinuesResponse = -1002; object:self]; } +/* + Returns the application's delegate. The app can only have one delegate at a time. +*/ - (id)delegate { return _delegate; } +/* + This method is called by run before the event loop begins. + When it successfully completes, it posts the notification + CPApplicationDidFinishLaunchingNotification. If you override + finishLaunching, the subclass method should invoke the superclass method. +*/ - (void)finishLaunching { var bundle = [CPBundle mainBundle], @@ -221,18 +268,30 @@ CPRunContinuesResponse = -1002; [[CPRunLoop currentRunLoop] performSelectors]; } +/* + Calls finishLaunching method which results in starting + the main event loop. +*/ - (void)run { [self finishLaunching]; } // Managing the Event Loop - +/* + Starts a modal event loop for aWindow + @param aWindow the window to start the event loop for +*/ - (void)runModalForWindow:(CPWindow)aWindow { [self runModalSession:[self beginModalSessionForWindow:aWindow]]; } +/* + Stops the event loop started by runModalForWindow: and + sets the code that runModalForWindow: will return. + @param aCode the return code for the modal event +*/ - (void)stopModalWithCode:(int)aCode { if (!_currentSession) @@ -248,6 +307,7 @@ CPRunContinuesResponse = -1002; [self _removeRunModalLoop]; } +/* @ignore */ - (void)_removeRunModalLoop { var count = _eventListeners.length; @@ -261,21 +321,35 @@ CPRunContinuesResponse = -1002; } } +/* + Stops the modal event loop +*/ - (void)stopModal { [self stopModalWithCode:CPRunStoppedResponse] } +/* + Aborts the event loop started by runModalForWindow: +*/ - (void)abortModal { [self stopModalWithCode:CPRunAbortedResponse]; } +/* + Sets up a modal session with theWindow. + @param aWindow the window to set up the modal session for +*/ - (CPModalSession)beginModalSessionForWindow:(CPWindow)aWindow { return _CPModalSessionMake(aWindow, 0); } +/* + Runs a modal session + @param CPModalSession the session to run +*/ - (void)runModalSession:(CPModalSession)aModalSession { aModalSession._previous = _currentSession; @@ -291,6 +365,10 @@ CPRunContinuesResponse = -1002; [CPApp setCallback:_CPRunModalLoop forNextEventMatchingMask:CPAnyEventMask untilDate:nil inMode:0 dequeue:NO]; } +/* + Returns the window for the current modal session. If there is no + modal session, it returns nil. +*/ - (CPWindow)modalWindow { if (!_currentSession) @@ -299,6 +377,7 @@ CPRunContinuesResponse = -1002; return _currentSession._window; } +/* @ignore */ - (BOOL)_handleKeyEquivalent:(CPEvent)anEvent { if ([_mainMenu performKeyEquivalent:anEvent]) @@ -307,6 +386,10 @@ CPRunContinuesResponse = -1002; return NO; } +/* + Dispatches events to other objects. + @param anEvent the event to dispatch +*/ - (void)sendEvent:(CPEvent)anEvent { // Check if this is a candidate for key equivalent... @@ -335,40 +418,66 @@ CPRunContinuesResponse = -1002; [super doCommandBySelector:aSelector]; } +/* + Returns the key window. +*/ - (CPWindow)keyWindow { return _keyWindow; } +/* + Returns the main window. +*/ - (CPWindow)mainWindow { return _mainWindow; } +/* + Returns the CPWindow object corresponding to aWindowNumber. +*/ - (CPWindow)windowWithWindowNumber:(int)aWindowNumber { return _windows[aWindowNumber]; } +/* + Returns an array of the application's CPWindows +*/ - (CPArray)windows { return _windows; } // Accessing the Main Menu - +/* + Returns the application's main menu +*/ - (CPMenu)mainMenu { return _mainMenu; } +/* + Sets the main menu for the application + @param aMenu the menu to set for the application +*/ - (void)setMainMenu:(CPMenu)aMenu { _mainMenu = aMenu; } // Posting Actions - +/* + Tries to perform the action with an argument. Performs + the action on itself (if it responds to it), then + tries to perform the action on the delegate. + @param anAction the action to perform. + @param anObject the argument for the action + method + @return YES if the action was performed +*/ - (BOOL)tryToPerform:(SEL)anAction with:(id)anObject { if (!anAction) @@ -387,6 +496,13 @@ CPRunContinuesResponse = -1002; return NO; } +/* + Sends an action to a target. + @param anAction the action to send + @param aTarget the target for the action + @param aSender the action sender + @return YES +*/ - (BOOL)sendAction:(SEL)anAction to:(id)aTarget from:(id)aSender { var target = [self targetForAction:anAction to:aTarget from:aSender]; @@ -399,6 +515,17 @@ CPRunContinuesResponse = -1002; return YES; } +/* + Finds a target for the specified action. If the + action is nil, returns nil. + If the target is not nil, aTarget is + returned. Otherwise, it calls targetForAction: + to search for a target. + @param anAction the action to find a target for + @param aTarget if not nil, this will be returned + @aSender not used + @return a target for the action +*/ - (id)targetForAction:(SEL)anAction to:(id)aTarget from:(id)aSender { if (!anAction) @@ -410,6 +537,23 @@ CPRunContinuesResponse = -1002; return [self targetForAction:anAction]; } +/* + Finds an action-target for a specified window. + It finds a matching target in the following order: +
    +
  1. the window's first responder
    2. +
  2. all the next responders after first responder
    3. +
  3. the window
    4. +
  4. the window's delegate
    5. +
  5. the window's controller
    6. +
  6. the window's associated document
    7. +
+ @param aWindow the window to search for a target + @param anAction the action to find a responder to + @return the object that responds to the action, or nil + if no matching target was found + @ignore +*/ - (id)_targetForWindow:(CPWindow)aWindow action:(SEL)anAction { var responder = [aWindow firstResponder], @@ -431,7 +575,7 @@ CPRunContinuesResponse = -1002; var delegate = [aWindow delegate]; - if ([aWindow respondsToSelector:anAction]) + if ([delegate respondsToSelector:anAction]) return delegate; var windowController = [aWindow windowController]; @@ -447,6 +591,20 @@ CPRunContinuesResponse = -1002; return nil; } +/* + Looks for a target that can handle the specified action. + Checks for a target in the following order: +
    +
  1. a responder from the key window
    2. +
  2. a responder frmo the main window
    3. +
  3. the CPApplication instance
    4. +
  4. the application delegate
    5. +
  5. the document controller
    6. +
+ @param anAction the action to handle + @return a target that can respond, or nil + if no match could be found +*/ - (id)targetForAction:(SEL)anAction { if (!anAction) @@ -488,6 +646,14 @@ CPRunContinuesResponse = -1002; // Managing Sheets +/* + Displays a window as a sheet. + @param aSheet the window to display as a sheet + @param aWindow the window that will hold the sheet as a child + @param aModalDelegate + @param aDidEndSelector + @param aContextInfo +*/ - (void)beginSheet:(CPWindow)aSheet modalForWindow:(CPWindow)aWindow modalDelegate:(id)aModalDelegate didEndSelector:(SEL)aDidEndSelector contextInfo:(id)aContextInfo { [aWindow _attachSheet:aSheet modalDelegate:aModalDelegate didEndSelector:aDidEndSelector contextInfo:aContextInfo]; @@ -532,6 +698,12 @@ var _CPRunModalLoop = function(anEvent) [CPApp _removeRunModalLoop]; } +/* + Starts the GUI and Cappuccino frameworks. This function should be + called from the main() function of your program. + @class CPApplication + @return void +*/ function CPApplicationMain(args, namedArgs) { var mainBundle = [CPBundle mainBundle], diff --git a/AppKit/CPButton.j b/AppKit/CPButton.j index 5a4f1ed911..dcaeac5376 100644 --- a/AppKit/CPButton.j +++ b/AppKit/CPButton.j @@ -27,48 +27,188 @@ import "CPControl.j" #include "CoreGraphics/CGGeometry.h" - CPScaleProportionally = 0; CPScaleToFit = 1; CPScaleNone = 2; +/* + @global + @group CPCellImagePosition +*/ CPNoImage = 0; +/* + @global + @group CPCellImagePosition +*/ CPImageOnly = 1; +/* + @global + @group CPCellImagePosition +*/ CPImageLeft = 2; +/* + @global + @group CPCellImagePosition +*/ CPImageRight = 3; +/* + @global + @group CPCellImagePosition +*/ CPImageBelow = 4; +/* + @global + @group CPCellImagePosition +*/ CPImageAbove = 5; +/* + @global + @group CPCellImagePosition +*/ CPImageOverlaps = 6; +/* + @global + @class CPButton +*/ CPOnState = 1; +/* + @global + @class CPButton +*/ CPOffState = 0; +/* + @global + @class CPButton +*/ CPMixedState = -1; +/* + @global + @group CPBezelStyle +*/ CPRoundedBezelStyle = 1; +/* + @global + @group CPBezelStyle +*/ CPRegularSquareBezelStyle = 2; +/* + @global + @group CPBezelStyle +*/ CPThickSquareBezelStyle = 3; +/* + @global + @group CPBezelStyle +*/ CPThickerSquareBezelStyle = 4; +/* + @global + @group CPBezelStyle +*/ CPDisclosureBezelStyle = 5; +/* + @global + @group CPBezelStyle +*/ CPShadowlessSquareBezelStyle = 6; +/* + @global + @group CPBezelStyle +*/ CPCircularBezelStyle = 7; +/* + @global + @group CPBezelStyle +*/ CPTexturedSquareBezelStyle = 8; +/* + @global + @group CPBezelStyle +*/ CPHelpButtonBezelStyle = 9; +/* + @global + @group CPBezelStyle +*/ CPSmallSquareBezelStyle = 10; +/* + @global + @group CPBezelStyle +*/ CPTexturedRoundedBezelStyle = 11; +/* + @global + @group CPBezelStyle +*/ CPRoundRectBezelStyle = 12; +/* + @global + @group CPBezelStyle +*/ CPRecessedBezelStyle = 13; +/* + @global + @group CPBezelStyle +*/ CPRoundedDisclosureBezelStyle = 14; +/* + @global + @group CPBezelStyle +*/ CPHUDBezelStyle = -1; + +/* + @global + @group CPButtonType +*/ CPMomentaryLightButton = 0; +/* + @global + @group CPButtonType +*/ CPPushOnPushOffButton = 1; +/* + @global + @group CPButtonType +*/ CPToggleButton = 2; +/* + @global + @group CPButtonType +*/ CPSwitchButton = 3; +/* + @global + @group CPButtonType +*/ CPRadioButton = 4; +/* + @global + @group CPButtonType +*/ CPMomentaryChangeButton = 5; +/* + @global + @group CPButtonType +*/ CPOnOffButton = 6; +/* + @global + @group CPButtonType +*/ CPMomentaryPushInButton = 7; +/* + @global + @group CPButtonType +*/ CPMomentaryPushButton = 0; +/* + @global + @group CPButtonType +*/ CPMomentaryLight = 7; @@ -79,6 +219,11 @@ var _CPButtonClassName = nil, _CPButtonBezelStyleIdentifiers = {}, _CPButtonBezelStyleHighlightedIdentifier = @"Highlighted"; +/* + CPButton is a subclass of CPControl that + intercepts mouse-down events and sends an action message to a + target object when it's clicked or pressed. +*/ @implementation CPButton : CPControl { int _tag; @@ -104,6 +249,10 @@ var _CPButtonClassName = nil, _CPImageAndTitleView _imageAndTitleView; } +/* + Initializes the CPButton class. + @ignore +*/ + (void)initialize { if (self != [CPButton class]) @@ -154,7 +303,10 @@ var _CPButtonClassName = nil, } // Configuring Buttons - +/* + Sets how the button highlights and shows its state. + @param aButtonType Defines the behavior of the button. +*/ - (void)setButtonType:(CPButtonType)aButtonType { if (aButtonType == CPSwitchButton) @@ -166,7 +318,7 @@ var _CPButtonClassName = nil, } } -- (id)initWithFrame:(CPRect)aFrame +- (id)initWithFrame:(CGRect)aFrame { self = [super initWithFrame:aFrame]; @@ -186,6 +338,10 @@ var _CPButtonClassName = nil, return self; } +/* + Sets the position of the button's image to anImagePosition. + @param anImagePosition the position for the button's image +*/ - (void)setImagePosition:(CPCellImagePosition)anImagePosition { if (_imagePosition == anImagePosition) @@ -196,11 +352,18 @@ var _CPButtonClassName = nil, [self drawContentsWithHighlight:_isHighlighted]; } +/* + Returns the buton's image position +*/ - (CPCellImagePosition)imagePosition { return _imagePosition; } +/* + Sets the button's images scaling method + @param anImageScaling the image scaling method +*/ - (void)setImageScaling:(CPImageScaling)anImageScaling { if (_imageScaling == anImageScaling) @@ -211,11 +374,18 @@ var _CPButtonClassName = nil, [self drawContentsWithHighlight:_isHighlighted]; } +/* + Returns the button's image scaling method +*/ - (CPImageScaling)imageScaling { return _imageScaling; } +/* + Sets the color of the button's text + @param aColor the color to use for drawing the button text +*/ - (void)setTextColor:(CPColor)aColor { [super setTextColor:aColor]; @@ -223,6 +393,10 @@ var _CPButtonClassName = nil, [self drawContentsWithHighlight:_isHighlighted]; } +/* + Sets the font that will be used to draw the button text + @param aFont the font used to draw the button text +*/ - (void)setFont:(CPFont)aFont { [super setFont:aFont]; @@ -231,17 +405,26 @@ var _CPButtonClassName = nil, } // Setting the state - +/* + Returns YES if the button has a 'mixed' state in addition to on and off. +*/ - (BOOL)allowsMixedState { return _allowsMixedState; } +/* + Sets whether the button can have a 'mixed' state. + @param aFlag specifies whether a 'mixed' state is allowed or not +*/ - (void)setAllowsMixedState:(BOOL)aFlag { _allowsMixedState = aFlag; } +/* + Sets the button to its next state. +*/ - (void)setNextState { if (_state == CPOffState) @@ -250,16 +433,28 @@ var _CPButtonClassName = nil, _state = (_state >= CPOnState && _allowsMixedState) ? CPMixedState : CPOffState; } +/* + Sets the button's state to aState. + @param aState Possible states are any of the CPButton globals: + CPOffState, CPOnState, CPMixedState +*/ - (void)setState:(int)aState { _state = aState; } +/* + Returns the button's current state +*/ - (int)state { return _state; } +/* + Sets the alignment of the text on the button. + @param anAlignment an alignment object +*/ - (void)setAlignment:(CPTextAlignment)anAlignment { [super setAlignment:anAlignment]; @@ -267,6 +462,10 @@ var _CPButtonClassName = nil, [self drawContentsWithHighlight:_isHighlighted]; } +/* + Sets the image that will be drawn on the button. + @param anImage the image that will be drawn +*/ - (void)setImage:(CPImage)anImage { if (_image == anImage) @@ -277,21 +476,35 @@ var _CPButtonClassName = nil, [self drawContentsWithHighlight:_isHighlighted]; } +/* + Returns the image that will be drawn on the button +*/ - (CPImage)image { return _image; } +/* + Sets the button's image which is used in its alternate state. + @param anImage the image to be used while the button is in an alternate state +*/ - (void)setAlternateImage:(CPImage)anImage { _alternateImage = anImage; } +/* + Returns the image used when the button is in an alternate state. +*/ - (CPImage)alternateImage { return _alternateImage; } +/* + Sets the button's title. + @param aTitle the new title for the button +*/ - (void)setTitle:(CPString)aTitle { if (_title == aTitle) @@ -302,11 +515,17 @@ var _CPButtonClassName = nil, [self drawContentsWithHighlight:_isHighlighted]; } +/* + Returns the button's title string +*/ - (CPString)title { return _title; } +/* + Lays out the button. +*/ - (void)tile { var size = [self bounds].size; @@ -328,6 +547,9 @@ var _CPButtonClassName = nil, [_imageAndTitleView setFrameSize:size]; } +/* + Compacts the button's frame to fit its contents. +*/ - (void)sizeToFit { [_imageAndTitleView sizeToFit]; @@ -346,29 +568,48 @@ var _CPButtonClassName = nil, [self setFrameSize:CGSizeMake(CGRectGetWidth(frame), height)]; } -- (void)setFrameSize:(CPSize)aSize +/* + Sets the frame size for the button. + @param the new frame size +*/ +- (void)setFrameSize:(CGSize)aSize { [super setFrameSize:aSize]; [self tile]; } +/* + Highlights the receiver based on aFlag. + @param If YES the button will highlight, NO the button will unhighlight. +*/ - (void)highlight:(BOOL)aFlag { [self drawBezelWithHighlight:aFlag]; [self drawContentsWithHighlight:aFlag]; } +/* + Sets button's tag. + @param aTag the button's new tag +*/ - (void)setTag:(int)aTag { _tag = aTag; } +/* + Returns the button's tag. +*/ - (int)tag { return _tag; } +/* + Called when the user clicks on this button. + @param anEvent the event with information about the click +*/ - (void)mouseDown:(CPEvent)anEvent { _isHighlighted = YES; @@ -376,6 +617,10 @@ var _CPButtonClassName = nil, [self highlight:_isHighlighted]; } +/* + Called when the user drags on the button. + @param anEvent the event with information about the drag +*/ - (void)mouseDragged:(CPEvent)anEvent { _isHighlighted = CGRectContainsPoint([self bounds], [self convertPoint:[anEvent locationInWindow] fromView:nil]); @@ -383,6 +628,10 @@ var _CPButtonClassName = nil, [self highlight:_isHighlighted]; } +/* + Called when the user releases the mouse button + @param anEvent the event with information about the mouse release +*/ - (void)mouseUp:(CPEvent)anEvent { _isHighlighted = NO; @@ -392,7 +641,10 @@ var _CPButtonClassName = nil, [super mouseUp:anEvent]; } -// FIXME: This probably belongs in CPControl. +/* + Sets the button's control size. + @param aControlSize the button's new control size +*/ - (void)setControlSize:(CPControlSize)aControlSize { if (_controlSize == aControlSize) @@ -404,11 +656,18 @@ var _CPButtonClassName = nil, [self _updateTextAttributes]; } +/* + Returns the button's control size. +*/ - (CPControlSize)controlSize { return _controlSize; } +/* + Sets whether the button has a bezeled border. + @param If YES, the the button will have a bezeled border. +*/ - (void)setBordered:(BOOL)isBordered { if (_isBordered == isBordered) @@ -422,11 +681,18 @@ var _CPButtonClassName = nil, [self tile]; } +/* + Returns YES if the border is bezeled. +*/ - (BOOL)isBordered { return _isBordered; } +/* + Sets the button's bezel style. + @param aBezelStye one of the predefined bezel styles +*/ - (void)setBezelStyle:(CPBezelStyle)aBezelStyle { // FIXME: We need real support for these: @@ -457,11 +723,15 @@ var _CPButtonClassName = nil, [self tile]; } +/* + Returns the current bezel style +*/ - (int)bezelStyle { return _bezelStyle; } +/* @ignore */ - (void)updateBackgroundColors { if (_isBordered) @@ -488,6 +758,7 @@ var _CPButtonClassName = nil, } } +/* @ignore */ - (void)drawBezelWithHighlight:(BOOL)shouldHighlight { _bezelBorderNeedsUpdate = ![self window]; @@ -498,6 +769,7 @@ var _CPButtonClassName = nil, [self setBackgroundColorWithName:shouldHighlight ? CPControlHighlightedBackgroundColor : CPControlNormalBackgroundColor]; } +/* @ignore */ - (void)drawContentsWithHighlight:(BOOL)isHighlighted { if (!_title && !_image && !_alternateTitle && !_alternateImage && !_imageAndTitleView) @@ -528,6 +800,7 @@ var _CPButtonClassName = nil, [self drawBezelWithHighlight:_isHighlighted]; } +/* @ignore */ - (void)_updateTextAttributes { if (_bezelStyle == CPHUDBezelStyle) @@ -553,6 +826,10 @@ var CPButtonImageKey = @"CPButtonImageKey", @implementation CPButton (CPCoding) +/* + Initializes the button by unarchiving data from aCoder. + @param aCoder the coder containing the archived CPButton. +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super initWithCoder:aCoder]; @@ -576,6 +853,10 @@ var CPButtonImageKey = @"CPButtonImageKey", return self; } +/* + Archives this button into the provided coder. + @param aCoder the coder to which the button's instance data will be written. +*/ - (void)encodeWithCoder:(CPCoder)aCoder { // We do this in order to avoid encoding the _imageAndTitleView, which diff --git a/AppKit/CPClipView.j b/AppKit/CPClipView.j index f32acecd8b..979dd6b4f6 100644 --- a/AppKit/CPClipView.j +++ b/AppKit/CPClipView.j @@ -24,12 +24,19 @@ import "CPView.j" #include "CoreGraphics/CGGeometry.h" - +/* + CPClipView allows you to define a clip rect and display only that portion of its containing view. + It is used to hold the document view in a CPScrollView. +*/ @implementation CPClipView : CPView { CPView _documentView; } +/* + Sets the document view to be aView. + @param aView the new document view. It's frame origin will be changed to (0,0) after calling this method. +*/ - (void)setDocumentView:(CPView)aView { if (_documentView == aView) @@ -78,11 +85,20 @@ import "CPView.j" } } +/* + Returns the document view. +*/ - (id)documentView { return _documentView; } +/* + Returns a new point that may be adjusted from aPoint + to make sure it lies within the document view. + @param aPoint + @return the adjusted point +*/ - (CGPoint)constrainScrollPoint:(CGPoint)aPoint { var documentFrame = [_documentView frame]; @@ -106,11 +122,19 @@ import "CPView.j" [superview reflectScrolledClipView:self]; } -- (void)scrollToPoint:(CPPoint)aPoint +/* + Scrolls the clip view to the specified point. The method + sets its bounds origin to aPoint. +*/ +- (void)scrollToPoint:(CGPoint)aPoint { [self setBoundsOrigin:[self constrainScrollPoint:aPoint]]; } +/* + Handles a CPViewBoundsDidChangeNotification. + @param aNotification the notification event +*/ - (void)viewBoundsChanged:(CPNotification)aNotification { var superview = [self superview]; @@ -119,6 +143,10 @@ import "CPView.j" [superview reflectScrolledClipView:self]; } +/* + Handles a CPViewFrameDidChangeNotification. + @param aNotification the notification event +*/ - (void)viewFrameChanged:(CPNotification)aNotification { var superview = [self superview]; diff --git a/AppKit/CPCollectionView.j b/AppKit/CPCollectionView.j index 111369a754..dbc631d8c3 100644 --- a/AppKit/CPCollectionView.j +++ b/AppKit/CPCollectionView.j @@ -28,7 +28,31 @@ import import - +/* + This class presents an array of content as a grid of views. + + @delegate -(void)collectionViewDidChangeSelection:(CPCollectionView)collectionView; + Called when the selection in the collection view has changed. + @param collectionView the collection view who's selection changed + + @delegate -(void)collectionView:(CPCollectionView)collectionView didDoubleClickOnItemAtIndex:(int)index; + Called when the user double-clicks on an item in the collection view. + @param collectionView the collection view that received the double-click + @param index the index of the item that received the double-click + + @delegate -(CPData)collectionView:(CPCollectionView)collectionView dataForItemsAtIndexes:(CPIndexSet)indices forType:(CPString)aType; + Invoked to obtain data for a set of indices. + @param collectionView the collection view to obtain data for + @param indices the indices to return data for + @param aType the data type + @return a data object containing the index items + + @delegate -(CPArray)collectionView:(CPCollectionView)collectionView dragTypesForItemsAtIndexes:(CPIndexSet)indices; + Invoked to obtain the data types supported by the specified indices for placement on the pasteboard. + @param collectionView the collection view the items reside in + @param indices the indices to obtain drag types + @return an array of drag types (CPString) +*/ @implementation CPCollectionView : CPView { CPArray _content; @@ -86,6 +110,10 @@ import return self; } +/* + Sets the item prototype to anItem + @param anItem the new item prototype +*/ - (void)setItemPrototype:(CPCollectionViewItem)anItem { _itemData = [CPKeyedArchiver archivedDataWithRootObject:anItem]; @@ -94,11 +122,18 @@ import [self reloadContent]; } +/* + Returns the current item prototype +*/ - (CPCollectionViewItem)itemPrototype { return _itemPrototype; } +/* + Returns a collection view item for anObject. + @param anObject the object to be represented. +*/ - (CPCollectionViewItem)newItemForRepresentedObject:(id)anObject { var item = nil; @@ -115,19 +150,29 @@ import } // Working with the Responder Chain - +/* + Returns YES by default. +*/ - (BOOL)acceptsFirstResponder { return YES; } +/* + Returns whether the receiver is currently the first responder. +*/ - (BOOL)isFirstResponder { return [[self window] firstResponder] == self; } // Setting the Content - +/* + Sets the content of the collection view to the content in anArray. + This array can be of any type, and each element will be passed to the setRepresentedObject: method. + It's the responsibility of your custom collection view item to interpret the object. + @param anArray the content array +*/ - (void)setContent:(CPArray)anArray { if (_content == anArray) @@ -138,18 +183,27 @@ import [self reloadContent]; } +/* + Returns the collection view content array +*/ - (CPArray)content { return _content; } +/* + Returns the collection view items. +*/ - (CPArray)items { return _items; } // Setting the Selection Mode - +/* + Sets whether the user is allowed to select items + @param isSelectable YES allows the user to select items. +*/ - (void)setSelectable:(BOOL)isSelectable { if (_isSelectable == isSelectable) @@ -166,21 +220,36 @@ import } } +/* + Returns YES if the collection view is + selected, and NO otherwise. +*/ - (BOOL)isSelected { return _isSelected; } +/* + Sets whether the user can select multiple items. + @param shouldAllowMultipleSelection YES allows the user to select multiple items +*/ - (void)setAllowsMultipleSelection:(BOOL)shouldAllowMultipleSelection { _allowsMultipleSelection = shouldAllowsMultipleSelection; } +/* + Returns YES if the user can select multiple items, NO otherwise. +*/ - (BOOL)allowsMultipleSelection { return _allowsMultipleSelection; } +/* + Sets the selected items based on the provided indices. + @param anIndexSet the set of items to be selected +*/ - (void)setSelectionIndexes:(CPIndexSet)anIndexSet { if (_selectionIndexes == anIndexSet) @@ -202,11 +271,15 @@ import [_delegate collectionViewDidChangeSelection:self] } +/* + Returns a set of the selected indices. +*/ - (CPIndexSet)selectionIndexes { return _selectionIndexes; } +/* @ignore */ - (void)reloadContent { // Remove current views @@ -237,6 +310,7 @@ import [self tile]; } +/* @ignore */ - (void)tile { var width = CGRectGetWidth([self bounds]); @@ -308,7 +382,10 @@ import } // Laying Out the Collection View - +/* + Sets the maximum number of rows. + @param aMaxNumberOfRows the new maximum number of rows +*/ - (void)setMaxNumberOfRows:(unsigned)aMaxNumberOfRows { if (_maxNumberOfRows == aMaxNumberOfRows) @@ -319,11 +396,18 @@ import [self tile]; } +/* + Returns the maximum number of rows. +*/ - (unsigned)maxNumberOfRows { return _maxNumberOfRows; } +/* + Sets the maximum number of columns. + @param aMaxNumberOfColumns the new maximum number of columns +*/ - (void)setMaxNumberOfColumns:(unsigned)aMaxNumberOfColumns { if (_maxNumberOfColumns == aMaxNumberOfColumns) @@ -334,11 +418,18 @@ import [self tile]; } +/* + Returns the maximum number of columns +*/ - (unsigned)maxNumberOfColumns { return _maxNumberOfColumns; } +/* + Sets the minimum size for an item + @param aSize the new minimum item size +*/ - (void)setMinItemSize:(CGSize)aSize { if (CGSizeEqualToSize(_minItemSize, aSize)) @@ -349,11 +440,18 @@ import [self tile]; } +/* + Returns the current minimum item size +*/ - (CGSize)minItemSize { return _minItemSize; } +/* + Sets the maximum item size. + @param aSize the new maximum item size +*/ - (void)setMaxItemSize:(CGSize)aSize { if (CGSizeEqualToSize(_maxItemSize, aSize)) @@ -364,6 +462,9 @@ import [self tile]; } +/* + Returns the current maximum item size. +*/ - (CGSize)maxItemSize { return _maxItemSize; @@ -418,6 +519,11 @@ import slideBack:YES]; } +/* + Places the selected items on the specified pasteboard. The items are requested from the collection's delegate. + @param aPasteboard the pasteboard to put the items on + @param aType the format the pasteboard data +*/ - (void)pasteboard:(CPPasteboard)aPasteboard provideDataForType:(CPString)aType { [aPasteboard setData:[_delegate collectionView:self dataForItemsAtIndexes:_selectionIndexes forType:aType] forType:aType]; @@ -435,11 +541,18 @@ import [self tile]; } +/* + Sets the collection view's delegate + @param aDelegate the new delegate +*/ - (void)setDelegate:(id)aDelegate { _delegate = aDelegate; } +/* + Returns the collection view's delegate +*/ - (id)delegate { return _delegate; @@ -447,6 +560,9 @@ import @end +/* + Represents an object inside a CPCollectionView. +*/ @implementation CPCollectionViewItem : CPObject { id _representedObject; @@ -457,7 +573,10 @@ import } // Setting the Represented Object - +/* + Sets the object to be represented by this item. + @param anObject the object to be represented +*/ - (void)setRepresentedObject:(id)anObject { if (_representedObject == anObject) @@ -469,25 +588,37 @@ import [_view setRepresentedObject:anObject]; } +/* + Returns the object represented by this view item +*/ - (id)representedObject { return _representedObject; } // Modifying the View - +/* + Sets the view that is used represent this object. + @param aView the view used to represent this object +*/ - (void)setView:(CPView)aView { _view = aView; } +/* + Returns the view that represents this object. +*/ - (CPView)view { return _view; } // Modifying the Selection - +/* + Sets whether this view item should be selected. + @param shouldBeSelected YES makes the item selected. NO deselects it. +*/ - (void)setSelected:(BOOL)shouldBeSelected { if (_isSelected == shouldBeSelected) @@ -499,13 +630,18 @@ import [_view setSelected:_isSelected]; } +/* + Returns YES if the item is currently selected. NO if the item is not selected. +*/ - (BOOL)isSelected { return _isSelected; } // Parent Collection View - +/* + Returns the collection view of which this item is a part. +*/ - (CPCollectionView)collectionView { return [_view superview]; @@ -517,6 +653,9 @@ var CPCollectionViewItemViewKey = @"CPCollectionViewItemViewKey"; @implementation CPCollectionViewItem (CPCoding) +/* + FIXME Not yet implemented +*/ - (id)copy { @@ -528,6 +667,11 @@ var CPCollectionViewItemViewKey = @"CPCollectionViewItemViewKey"; @implementation CPCollectionViewItem (CPCoding) +/* + Initializes the view item by unarchiving data from a coder. + @param aCoder the coder from which the data will be unarchived + @return the initialized collection view item +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super init]; @@ -538,6 +682,10 @@ var CPCollectionViewItemViewKey = @"CPCollectionViewItemViewKey"; return self; } +/* + Archives the colletion view item to the provided coder. + @param aCoder the coder to which the view item should be archived +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeObject:_view forKey:CPCollectionViewItemViewKey]; diff --git a/AppKit/CPColor.j b/AppKit/CPColor.j index dd88941924..fccc667332 100644 --- a/AppKit/CPColor.j +++ b/AppKit/CPColor.j @@ -35,7 +35,19 @@ var _redComponent = 0, var _hueComponent = 0, _saturationComponent = 1, _brightnessComponent = 2; - + +/* + CPColor can be used to represent color + in an RGB or HSB model with an optional transparency value.

+ +

It also provides some class helper methods that + returns instances of commonly used colors.

+ +

The class does not have a set: method + like NextStep based frameworks to change the color of + the current context. To change the color of the current + context, use CGContextSetFillColor(). +*/ @implementation CPColor : CPObject { CPArray _components; @@ -44,16 +56,47 @@ var _hueComponent = 0, CPString _cssString; } +/* + Creates a color in the RGB color space, with an alpha value. + Each component should be between the range of 0.0 to 1.0. For + the alpha component, a value of 1.0 is opaque, and 0.0 means + completely transparent. + + @param red the red component of the color + @param green the green component of the color + @param blue the blue component of the color + @param alpha the alpha component + + @return a color initialized to the values specified +*/ + (CPColor)colorWithCalibratedRed:(float)red green:(float)green blue:(float)blue alpha:(float)alpha { return [[CPColor alloc] _initWithRGBA:[red, green, blue, alpha]]; } +/* + Creates a new color object with white for the RGB components. + For the alpha component, a value of 1.0 is opaque, and 0.0 means completely transparent. + + @param white a float between 0.0 and 1.0 + @param alpha the alpha component between 0.0 and 1.0 + + @return a color initialized to the values specified +*/ + (CPColor)colorWithCalibratedWhite:(float)white alpha:(float)alpha { return [[CPColor alloc] _initWithRGBA:[white, white, white, alpha]]; } +/* + Creates a new color in HSB space. + + @param hue the hue value + @param saturation the saturation value + @param brightness the brightness value + + @return the initialized color +*/ + (CPColor)colorWithHue:(float)hue saturation:(float)saturation brightness:(float)brightness { if(saturation == 0.0) @@ -76,71 +119,123 @@ var _hueComponent = 0, } } +/* + Creates an RGB color from a hexadecimal string. For example, + the a string of "FFFFFF" would return a white CPColor. + "FF0000" would return a pure red, "00FF00" would return a + pure blue, and "0000FF" would return a pure green. + + @param hex a 6 character long string of hex + + @return an initialized RGB color +*/ + (CPColor)colorWithHexString:(string)hex { return [[CPColor alloc] _initWithRGBA: hexToRGB(hex)]; } +/* + Returns a black color object. (RGBA=[0.0, 0.0, 0.0, 1.0]) +*/ + (CPColor)blackColor { return [[CPColor alloc] _initWithRGBA:[0.0, 0.0, 0.0, 1.0]]; } +/* + Returns a blue color object. (RGBA=[0.0, 0.0, 1.0, 1.0]) +*/ + (CPColor)blueColor { return [[CPColor alloc] _initWithRGBA:[0.0, 0.0, 1.0, 1.0]]; } +/* + Returns a dark gray color object. (RGBA=[0.33 ,0.33, 0.33, 1.0]) +*/ + (CPColor)darkGrayColor { return [CPColor colorWithCalibratedWhite:1.0 / 3.0 alpha:1.0]; } +/* + Returns a gray color object. (RGBA=[0.5, 0.5, 0.5, 1.0]) +*/ + (CPColor)grayColor { return [CPColor colorWithCalibratedWhite:0.5 alpha: 1.0]; } +/* + Returns a green color object. (RGBA=[0.0, 1.0, 0.0, 1.0]) +*/ + (CPColor)greenColor { return [[CPColor alloc] _initWithRGBA:[0.0, 1.0, 0.0, 1.0]]; } +/* + Returns a light gray color object (RGBA=[0.66, 0.66, 0.66, 1.0]) +*/ + (CPColor)lightGrayColor { return [CPColor colorWithCalibratedWhite:2.0 / 3.0 alpha:1.0]; } +/* + Returns a red color object (RGBA=[1.0, 0.0, 0.0, 1.0]) +*/ + (CPColor)redColor { return [[CPColor alloc] _initWithRGBA:[1.0, 0.0, 0.0, 1.0]]; } +/* + Returns a white color object (RGBA=[1.0, 1.0, 1.0, 1.0]) +*/ + (CPColor)whiteColor { return [[CPColor alloc] _initWithRGBA:[1.0, 1.0, 1.0, 1.0]]; } +/* + Returns a yellow color object (RGBA=[1.0, 1.0, 0.0, 1.0]) +*/ + (CPColor)yellowColor { return [[CPColor alloc] _initWithRGBA:[1.0, 1.0, 0.0, 1.0]]; } +/* + Returns a shadow looking color (RGBA=[0.0, 0.0, 0.0, 0.33]) +*/ + (CPColor)shadowColor { return [[CPColor alloc] _initWithRGBA:[0.0, 0.0, 0.0, 1.0 / 3.0]]; } +/* + Creates a color using a tile pattern with anImage + @param the image to tile + @return a tiled image color object +*/ + (CPColor)colorWithPatternImage:(CPImage)anImage { return [[CPColor alloc] _initWithPatternImage:anImage]; } +/* + Creates a CPColor from a valid CSS RGB string. Example, "rgb(32,64,129)". + + @param aString a CSS color string + @return a color initialized to the value in the css string +*/ + (CPColor)colorWithCSSString:(CPString)aString { return [[CPColor alloc] _initWithCSSString: aString]; } +/* @ignore */ - (id)_initWithCSSString:(CPString)aString { if(aString.indexOf("rgb") == CPNotFound) @@ -163,6 +258,7 @@ var _hueComponent = 0, return self; } +/* @ignore */ - (id)_initWithRGBA:(CPArray)components { self = [super init]; @@ -218,6 +314,7 @@ var _hueComponent = 0, return self; } +/* @ignore */ - (id)_initWithPatternImage:(CPImage)anImage { self = [super init]; @@ -231,36 +328,69 @@ var _hueComponent = 0, return self; } +/* + Returns the image being used as the pattern for the tile in this color. +*/ - (CPImage)patternImage { return _patternImage; } +/* + Returns the alpha component of this color. +*/ - (float)alphaComponent { return _components[3]; } +/* + Returns the blue component of this color. +*/ - (float)blueComponent { return _components[2]; } +/* + Returns the green component of this color. +*/ - (float)greenComponent { return _components[1]; } +/* + Return the red component of this color. +*/ - (float)redComponent { return _components[0]; } +/* + Returns the RGBA components of this color in an array. + The index values are ordered as: +

+Index   Component
+0       Red
+1       Green
+2       Blue
+3       Alpha
+
+*/ - (CPArray)components { return _components; } +/* + Returns a new color with the same RGB as the receiver but a new alpha component. + + @param anAlphaComponent the alpha component for the new color + + @return a new color object +*/ - (CPColor)colorWithAlphaComponent:(float)anAlphaComponent { var components = _components.slice(); @@ -270,6 +400,16 @@ var _hueComponent = 0, return [[[self class] alloc] _initWithRGBA:components]; } +/* + Returns an array with the HSB values for this color. + The index values are ordered as: +
+Index   Component
+0       Hue
+1       Saturation
+2       Brightness
+
+*/ - (CPArray)hsbComponents { var red = ROUND(_components[_redComponent] * 255.0), @@ -311,11 +451,23 @@ var _hueComponent = 0, ]; } +/* + Returns the CSS representation of this color. The color will + be in one of the following forms: +
+rgb(22,44,88)
+rgba(22,44,88,0.5)  // if there is an alpha
+url("data:image/png;base64,BASE64ENCODEDDATA")  // if there is a pattern image
+
+*/ - (CPString)cssString { return _cssString; } +/* + Returns a 6 character long hex string of this color. +*/ - (CPString)hexString { return rgbToHex([self redComponent], [self greenComponent], [self blueComponent]) @@ -328,6 +480,10 @@ var CPColorComponentsKey = @"CPColorComponentsKey", @implementation CPColor (CPCoding) +/* + Initializes this color from the data archived in a coder. + @param aCoder the coder from which the color will be loaded +*/ - (id)initWithCoder:(CPCoder)aCoder { if ([aCoder containsValueForKey:CPColorPatternImageKey]) @@ -336,6 +492,10 @@ var CPColorComponentsKey = @"CPColorComponentsKey", return [self _initWithRGBA:[aCoder decodeObjectForKey:CPColorComponentsKey]]; } +/* + Archives this color into a coder. + @param aCoder the coder into which the color will be archived. +*/ - (void)encodeWithCoder:(CPCoder)aCoder { if (_patternImage) @@ -348,6 +508,12 @@ var CPColorComponentsKey = @"CPColorComponentsKey", var hexCharacters = "0123456789ABCDEF"; +/* + Used for the CPColor colorWithHexString: implementation + @ignore + @class CPColor + @return an array of rgb components +*/ function hexToRGB(hex) { if(hex.length != 6) diff --git a/AppKit/CPColorPanel.j b/AppKit/CPColorPanel.j index 7d088aa959..ba02ce05b5 100644 --- a/AppKit/CPColorPanel.j +++ b/AppKit/CPColorPanel.j @@ -37,13 +37,33 @@ var PREVIEW_HEIGHT = 20.0, var SharedColorPanel = nil; -CPWheelColorPickerMode = 1, -CPKulerColorPickerMode = 2, +/* + A color wheel + @global + @group CPColorPanelMode +*/ +CPWheelColorPickerMode = 1; +/* + Kuler color picker + @global + @group CPColorPanelMode +*/ +CPKulerColorPickerMode = 2; +/* + Slider based picker + @global + @group CPColorPanelMode +*/ CPSliderColorPickerMode = 3; CPColorPickerViewWidth = 265, CPColorPickerViewHeight = 370; +/* + CPColorPanel provides a reusable panel that can be used + displayed on screen to prompt the user for a color selection. To + obtain the panel, call the sharedColorPanel method. +*/ @implementation CPColorPanel : CPPanel { _CPColorPanelToolbar _toolbar; @@ -68,6 +88,9 @@ CPColorPickerViewHeight = 370; int _mode; } +/* + Returns (and if necessary, creates) the shared color panel. +*/ + (CPColorPanel)sharedColorPanel { if (!SharedColorPanel) @@ -76,12 +99,20 @@ CPColorPickerViewHeight = 370; return SharedColorPanel; } -+ (void)setPickerMode:(int)mode +/* + Returns the shared color panel set to display in mode. + @param mode the mode to which the color panel will be set before returning +*/ ++ (void)setPickerMode:(CPColorPanelMode)mode { var panel = [CPColorPanel sharedColorPanel]; [panel setMode: mode]; } +/* + To obtain the color panel, use sharedColorPanel. + @ignore +*/ - (id)init { self = [super initWithContentRect:CGRectMake(500.0, 50.0, 218.0, 360.0) @@ -101,6 +132,9 @@ CPColorPickerViewHeight = 370; return self; } +/* + Sets the color of the panel, and updates the picker. Also posts a CPColorPanelDidChangeNotification. +*/ - (void)setColor:(CPColor)aColor { _color = aColor; @@ -116,6 +150,11 @@ CPColorPickerViewHeight = 370; object:self]; } +/* + Sets the selected color of the panel and optionally updates the picker. + @param bool whether or not to update the picker + @ignore +*/ -(void)setColor:(CPColor)aColor updatePicker:(BOOL)bool { [self setColor: aColor]; @@ -125,32 +164,55 @@ CPColorPickerViewHeight = 370; } +/* + Returns the panel's currently selected color. +*/ - (CPColor)color { return _color; } +/* + Sets the target for the color panel. Messages are sent + to the target when colors are selected in the panel. +*/ - (void)setTarget:(id)aTarget { _target = aTarget; } +/* + Returns the current target. The target receives messages + when colors are selected in the panel. +*/ - (id)target { return _target; } +/* + Sets the action that gets sent to the target. + This action is sent whenever a color is selected in the panel. + @param anAction the action that will be sent +*/ - (void)setAction:(selector)anAction { _action = anAction; } +/* + Returns the current target action. +*/ - (selector)action { return _action; } -- (void)setMode:(int)mode +/* + Sets the mode (look) of the color panel. + @param mode the mode in which to display the color panel +*/ +- (void)setMode:(CPColorPanelMode)mode { if(mode == _mode) return; @@ -175,7 +237,10 @@ CPColorPickerViewHeight = 370; [[self contentView] addSubview: _currentView]; } -- (int)mode +/* + Returns the color panel's current display mode. +*/ +- (CPColorPanelMode)mode { return _mode; } @@ -187,6 +252,7 @@ CPColorPickerViewHeight = 370; [super orderFront:aSender]; } +/* @ignore */ - (void)_loadContentsIfNecessary { if (_toolbar) @@ -269,6 +335,7 @@ CPColorPickerViewHeight = 370; var iconSize = 32, totalIcons = 3; +/* @ignore */ @implementation _CPColorPanelToolbar : CPView { CPImage _wheelImage; @@ -366,6 +433,7 @@ var iconSize = 32, CPColorDragType = "CPColorDragType"; var CPColorPanelSwatchesCookie = "CPColorPanelSwatchesCookie"; +/* @ignore */ @implementation _CPColorPanelSwatches : CPView { CPView[] _swatches; @@ -539,6 +607,7 @@ var CPColorPanelSwatchesCookie = "CPColorPanelSwatchesCookie"; @end +/* @ignore */ @implementation _CPColorPanelPreview : CPView { CPColorPanel _colorPanel; diff --git a/AppKit/CPColorPicker.j b/AppKit/CPColorPicker.j index 343df45c9e..fdfcba7919 100644 --- a/AppKit/CPColorPicker.j +++ b/AppKit/CPColorPicker.j @@ -25,13 +25,20 @@ import import import - +/* + CPColorPicker is an abstract superclass for all color picker subclasses. If you want a particular color picker, use CPColorPanel's setPickerMode: method. The simplest way to implement your own color picker is to create a subclass of CPColorPicker. +*/ @implementation CPColorPicker : CPObject { CPColorPanel _panel; int _mask; } +/* + Initializes the color picker. + @param aMask a unique unsigned int identifying your color picker + @param aPanel the color panel that owns this picker +*/ - (id)initWithPickerMask:(int)aMask colorPanel:(CPColorPanel)aPanel { self = [super init]; @@ -42,21 +49,37 @@ import return self; } +/* + Returns the color panel that owns this picker +*/ - (CPColorPanel)colorPanel { return _panel; } +/* + FIXME Not implemented. + @return nil + @ignore +*/ - (CPImage)provideNewButtonImage { return nil; } -- (void)setMode:(int)mode +/* + Sets the color picker's mode. + @param mode the color panel mode +*/ +- (void)setMode:(CPColorPanelMode)mode { return; } +/* + Sets the picker's color. + @param aColor the new color for the picker +*/ - (void)setColor:(CPColor)aColor { return; @@ -64,6 +87,10 @@ import @end +/* + The wheel mode color picker. + @ignore +*/ @implementation CPColorWheelColorPicker : CPColorPicker { CPView _pickerView; @@ -167,6 +194,7 @@ import @end +/* @ignore */ @implementation __CPColorWheel : CPView { DOMElement _wheelImage; diff --git a/AppKit/CPColorWell.j b/AppKit/CPColorWell.j index bcca91233b..ef55d9fe77 100644 --- a/AppKit/CPColorWell.j +++ b/AppKit/CPColorWell.j @@ -29,6 +29,11 @@ import "CPColorPanel.j" var _CPColorWellDidBecomeExclusiveNotification = @"_CPColorWellDidBecomeExclusiveNotification"; +/* + CPColorWell is a CPControl for selecting and displaying a single color value. An example of a CPColorWell object (or simply color well) is found in CPColorPanel, which uses a color well to display the current color selection.

+ +

An application can have one or more active CPColorWells. You can activate multiple CPColorWells by invoking the activate: method with NO as its argument. When a mouse-down event occurs on an CPColorWell's border, it becomes the only active color well. When a color well becomes active, it brings up the color panel also. +*/ @implementation CPColorWell : CPControl { BOOL _active; @@ -70,11 +75,17 @@ var _CPColorWellDidBecomeExclusiveNotification = @"_CPColorWellDidBecomeExclusiv // Managing Color From Color Wells +/* + Returns the color well's current color. +*/ - (CPColor)color { return _color; } +/* + Sets the color well's current color. +*/ - (void)setColor:(CPColor)aColor { if (_color == aColor) @@ -85,13 +96,21 @@ var _CPColorWellDidBecomeExclusiveNotification = @"_CPColorWellDidBecomeExclusiv [self drawWellInside:CGRectInset([self bounds], 3.0, 3.0)]; } +/* + Changes the color of the well to that of aSender. + @param aSender the object from which to retrieve the color +*/ - (void)takeColorFrom:(id)aSender { [self setColor:[aSender color]]; } // Activating and Deactivating Color Wells - +/* + Activates the color well, displays the color panel, and makes the panel's current color the same as its own. + If exclusive is YES, deactivates any other CPColorWells. NO, keeps them active. + @param shouldBeExclusive whether other color wells should be deactivated. +*/ - (void)activate:(BOOL)shouldBeExclusive { if (shouldBeExclusive) @@ -113,6 +132,9 @@ var _CPColorWellDidBecomeExclusiveNotification = @"_CPColorWellDidBecomeExclusiv object:[CPColorPanel sharedColorPanel]]; } +/* + Deactivates the color well. +*/ - (void)deactivate { if (![self isActive]) @@ -126,6 +148,9 @@ var _CPColorWellDidBecomeExclusiveNotification = @"_CPColorWellDidBecomeExclusiv object:[CPColorPanel sharedColorPanel]]; } +/* + Returns YES if the color well is active. +*/ - (BOOL)isActive { return _active; @@ -137,6 +162,10 @@ var _CPColorWellDidBecomeExclusiveNotification = @"_CPColorWellDidBecomeExclusiv { } +/* + Draws the colored area inside the color well without borders. + @param aRect the location at which to draw +*/ - (void)drawWellInside:(CGRect)aRect { if (!_wellView) diff --git a/AppKit/CPControl.j b/AppKit/CPControl.j index 29b87774ac..d76594e3bc 100644 --- a/AppKit/CPControl.j +++ b/AppKit/CPControl.j @@ -26,15 +26,46 @@ import "CPView.j" #include "Platform/Platform.h" - +/* + @global + @group CPTextAlignment +*/ CPLeftTextAlignment = 0; +/* + @global + @group CPTextAlignment +*/ CPRightTextAlignment = 1; +/* + @global + @group CPTextAlignment +*/ CPCenterTextAlignment = 2; +/* + @global + @group CPTextAlignment +*/ CPJustifiedTextAlignment = 3; +/* + @global + @group CPTextAlignment +*/ CPNaturalTextAlignment = 4; +/* + @global + @group CPControlSize +*/ CPRegularControlSize = 0; +/* + @global + @group CPControlSize +*/ CPSmallControlSize = 1; +/* + @global + @group CPControlSize +*/ CPMiniControlSize = 2; CPControlNormalBackgroundColor = @"CPControlNormalBackgroundColor"; @@ -44,6 +75,9 @@ CPControlDisabledBackgroundColor = @"CPControlDisabledBackgroundColor"; var CPControlBlackColor = [CPColor blackColor]; +/* + CPControl is an abstract superclass used to implement user interface elements. As a subclass of CPView and CPResponder it has the ability to handle screen drawing and handling user input. +*/ @implementation CPControl : CPView { id _value; @@ -66,7 +100,7 @@ var CPControlBlackColor = [CPColor blackColor]; CPString _currentBackgroundColorName; } -- (id)initWithFrame:(CPRect)aFrame +- (id)initWithFrame:(CGRect)aFrame { self = [super initWithFrame:aFrame]; @@ -84,16 +118,27 @@ var CPControlBlackColor = [CPColor blackColor]; return self; } +/* + Sets whether the receiver responds to mouse events. + @param isEnabled whether the receiver will respond to mouse events +*/ - (void)setEnabled:(BOOL)isEnabled { [self setAlphaValue:(_isEnabled = isEnabled) ? 1.0 : 0.3]; } +/* + Returns YES if the receiver responds to mouse events. +*/ - (BOOL)isEnabled { return _isEnabled; } + +/* + Sets the color of the receiver's text. +*/ - (void)setTextColor:(CPColor)aColor { if (_textColor == aColor) @@ -106,21 +151,35 @@ var CPControlBlackColor = [CPColor blackColor]; #endif } +/* + Returns the color of the receiver's text +*/ - (CPColor)textColor { return _textColor; } -- (int)alignment +/* + Returns the receiver's alignment +*/ +- (CPTextAlignment)alignment { return _alignment; } -- (void)setAlignment:(int)anAlignment +/* + Sets the receiver's alignment + @param anAlignment the receiver's alignment +*/ +- (void)setAlignment:(CPTextAlignment)anAlignment { _alignment = anAlignment; } +/* + Sets the receiver's font + @param aFont the font for the receiver +*/ - (void)setFont:(CPFont)aFont { if (_font == aFont) @@ -133,36 +192,60 @@ var CPControlBlackColor = [CPColor blackColor]; #endif } +/* + Returns the receiver's font +*/ - (CPFont)font { return _font; } +/* + Sets the shadow for the receiver's text. + @param aTextShadow the text shadow +*/ - (void)setTextShadow:(CPShadow)aTextShadow { _DOMElement.style.textShadow = [_textShadow = aTextShadow cssString]; } +/* + Returns the receiver's text shadow +*/ - (CPShadow)textShadow { return _textShadow; } +/* + Returns the receiver's target action +*/ - (SEL)action { return _action; } +/* + Sets the receiver's target action + @param anAction Sets the action message that gets sent to the target. +*/ - (void)setAction:(SEL)anAction { _action = anAction; } +/* + Returns the receiver's target. The target receives action messages from the receiver. +*/ - (id)target { return _target; } +/* + Sets the receiver's target. The target receives action messages from the receiver. + @param aTarget the object that will receive the message specified by action +*/ - (void)setTarget:(id)aTarget { _target = aTarget; @@ -176,16 +259,27 @@ var CPControlBlackColor = [CPColor blackColor]; [super mouseUp:anEvent]; } +/* + Causes anAction to be sent to anObject. + @param anAction the action to send + @param anObject the object to which the action will be sent +*/ - (void)sendAction:(SEL)anAction to:(id)anObject { [CPApp sendAction:anAction to:anObject from:self]; } +/* + Returns the receiver's float value +*/ - (float)floatValue { - return _value ? parseFloat(_value) : 0.0; + return _value ? parseFloat(_value, 10) : 0.0; } +/* + Sets the receiver's float value +*/ - (void)setFloatValue:(float)aValue { _value = aValue; @@ -239,7 +333,8 @@ var CPControlBlackColor = [CPColor blackColor]; Ð setStringValue: Ð setNeedsDisplay Ð attributedStringValue -Ð setAttributedStringValue: */ +Ð setAttributedStringValue: +*/ @end @@ -253,6 +348,11 @@ var CPControlIsEnabledKey = @"CPControlIsEnabledKey", @implementation CPControl (CPCoding) +/* + Initializes the control by unarchiving it from a coder. + @param aCoder the coder from which to unarchive the control + @return the initialized control +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super initWithCoder:aCoder]; @@ -274,6 +374,10 @@ var CPControlIsEnabledKey = @"CPControlIsEnabledKey", return self; } +/* + Archives the control to the provided coder. + @param aCoder the coder to which the control will be archived. +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [super encodeWithCoder:aCoder]; diff --git a/AppKit/CPCookie.j b/AppKit/CPCookie.j index 33adb1fcf4..7479d711e3 100644 --- a/AppKit/CPCookie.j +++ b/AppKit/CPCookie.j @@ -24,6 +24,9 @@ import import +/* + CPCookie is the Cappuccino interface to a web browser cookie. You can set the name +*/ @implementation CPCookie : CPObject { CPString _cookieName; @@ -32,6 +35,10 @@ import CPString _expires; } +/* + Initializes a cookie with a given name aName. + @param the name for the cookie +*/ - (id)initWithName:(CPString)aName { self = [super init]; @@ -42,21 +49,36 @@ import return self; } +/* + Returns the cookie's data value +*/ - (CPString)value { return _cookieValue; } +/* + Returns the cookie's name +*/ - (CPString)name { return _cookieName; } +/* + Returns the cookie's expiration date +*/ - (CPString)expires { return _expires; } +/* + Sets a value, expiration date, and domain for the cookie + @param value the cookie's value + @param date the cookie's expiration date + @param domain the cookie's domain +*/ - (void)setValue:(CPString)value expires:(CPDate)date domain:(CPString)domain { if(date) @@ -72,6 +94,7 @@ import document.cookie = _cookieName+"="+value+expires+"; path=/"+domain; } +/* @ignore */ - (CPString)_readCookieValue { var nameEQ = _cookieName + "="; diff --git a/AppKit/CPDocument.j b/AppKit/CPDocument.j index ccb52e8789..2e53ce40ac 100644 --- a/AppKit/CPDocument.j +++ b/AppKit/CPDocument.j @@ -26,16 +26,51 @@ import import "CPResponder.j" import "CPWindowController.j" - +/* + @global + @group CPSaveOperationType +*/ CPSaveOperation = 0; +/* + @global + @group CPSaveOperationType +*/ CPSaveAsOperation = 1; +/* + @global + @group CPSaveOperationType +*/ CPSaveToOperation = 2; +/* + @global + @group CPSaveOperationType +*/ CPAutosaveOperation = 3; +/* + @global + @group CPDocumentChangeType +*/ CPChangeDone = 0; +/* + @global + @group CPDocumentChangeType +*/ CPChangeUndone = 1; +/* + @global + @group CPDocumentChangeType +*/ CPChangeCleared = 2; +/* + @global + @group CPDocumentChangeType +*/ CPChangeReadOtherContents = 3; +/* + @global + @group CPDocumentChangeType +*/ CPChangeAutosaved = 4; CPDocumentWillSaveNotification = @"CPDocumentWillSaveNotification"; @@ -44,6 +79,12 @@ CPDocumentDidFailToSaveNotification = @"CPDocumentDidFailToSaveNotification"; var CPDocumentUntitledCount = 0; +/* + CPDocument is used to represent a document/file in a Cappuccino application. + In a document-based application, generally multiple documents are open simutaneously + (multiple text documents, slide presentations, spreadsheets, etc.), and multiple + CPDocuments should be used to represent this. +*/ @implementation CPDocument : CPResponder { CPURL _fileURL; @@ -60,6 +101,10 @@ var CPDocumentUntitledCount = 0; CPURLRequest _writeRequest; } +/* + Initializes an empty document. + @return the initialized document +*/ - (id)init { self = [super init]; @@ -77,6 +122,12 @@ var CPDocumentUntitledCount = 0; return self; } +/* + Initializes the document with a specific data type. + @param aType the type of document to initialize + @param anError not used + @return the initialized document +*/ - (id)initWithType:(CPString)aType error:({CPError})anError { self = [self init]; @@ -87,6 +138,17 @@ var CPDocumentUntitledCount = 0; return self; } +/* + Initializes a document of a specific type located at a URL. Notifies + the provided delegate after initialization. + @param anAbsoluteURL the url of the document content + @param aType the type of document located at the URL + @param aDelegate the delegate to notify + @param aDidReadSelector the selector used to notify the delegate + @param aContextInfo context information passed to the delegate + after initialization + @return the initialized document +*/ - (id)initWithContentsOfURL:(CPURL)anAbsoluteURL ofType:(CPString)aType delegate:(id)aDelegate didReadSelector:(SEL)aDidReadSelector contextInfo:(id)aContextInfo { self = [self init]; @@ -102,6 +164,16 @@ var CPDocumentUntitledCount = 0; return self; } +/* + Initializes the document from a URL. + @param anAbsoluteURL the document location + @param absoluteContentsURL the location of the document's contents + @param aType the type of the contents + @param aDelegate this object will receive a callback after the document's contents are loaded + @param aDidReadSelector the message selector that will be sent to aDelegate + @param aContextInfo passed as the argument to the message sent to the aDelegate + @return the initialized document +*/ - (id)initForURL:(CPURL)anAbsoluteURL withContentsOfURL:(CPURL)absoluteContentsURL ofType:(CPString)aType delegate:(id)aDelegate didReadSelector:(SEL)aDidReadSelector contextInfo:(id)aContextInfo { self = [self init]; @@ -117,18 +189,39 @@ var CPDocumentUntitledCount = 0; return self; } +/* + Returns the receiver's data in a specified type. The default implementation just + throws an exception. + @param aType the format of the data + @param anError not used + @throws CPUnsupportedMethodException if this method hasn't been overriden by the subclass + @return the document data +*/ - (CPData)dataOfType:(CPString)aType error:({CPError})anError { - // FIXME: Throw Exception. - return nil; + [CPException raise:CPUnsupportedMethodException + reason:"This method must be overridden by the document"]; } +/* + Sets the content of the document by reading the provided + data. The default implementation just throws an exception. + @param aData the document's data + @param aType the document type + @param anError not used + @throws CPUnsupportedMethodException if this method hasn't been + overridden by the subclass +*/ - (void)readFromData:(CPData)aData ofType:(CPString)aType error:(CPError)anError { + [CPException raise:CPUnsupportedMethodException + reason:"This method must be overridden by the document"]; } // Creating and managing window controllers - +/* + Creates the window controller for this document. +*/ - (void)makeWindowControllers { var controller = [[CPWindowController alloc] initWithWindowCibName:nil]; @@ -136,11 +229,19 @@ var CPDocumentUntitledCount = 0; [self addWindowController:controller]; } +/* + Returns the document's window controllers +*/ - (CPArray)windowControllers { return _windowControllers; } +/* + Add a controller to the document's list of controllers. This should + be called after making a new window controller. + @param aWindowController the controller to add +*/ - (void)addWindowController:(CPWindowController)aWindowController { [_windowControllers addObject:aWindowController]; @@ -153,12 +254,17 @@ var CPDocumentUntitledCount = 0; } // Managing Document Windows - +/* + Shows all the document's windows. +*/ - (void)showWindows { [_windowControllers makeObjectsPerformSelector:@selector(showWindow:) withObject:self]; } +/* + Returns the name of the document as displayed in the title bar. +*/ - (CPString)displayName { // FIXME: By default, return last path component of fileURL @@ -171,21 +277,39 @@ var CPDocumentUntitledCount = 0; return @"Untitled " + _untitledDocumentIndex; } +/* + Returns the document's Cib name +*/ - (CPString)windowCibName { return nil; } +/* + Called after aWindowController loads the document's Nib file. + @param aWindowController the controller that loaded the Nib file +*/ - (void)windowControllerDidLoadNib:(CPWindowController)aWindowController { } +/* + Called before aWindowController will load the document's Nib file. + @param aWindowController the controller that will load the Nib file +*/ - (void)windowControllerWillLoadNib:(CPWindowController)aWindowController { } // Reading from and Writing to URLs - +/* + Set the document's data from a URL. Notifies the provided delegate afterwards. + @param anAbsoluteURL the URL to the document's content + @param aType the document type + @param aDelegate delegate to notify after reading the data + @param aDidReadSelector message that will be sent to the delegate + @param aContextInfo context information that gets sent to the delegate +*/ - (void)readFromURL:(CPURL)anAbsoluteURL ofType:(CPString)aType delegate:(id)aDelegate didReadSelector:(SEL)aDidReadSelector contextInfo:(id)aContextInfo { [_readConnection cancel]; @@ -196,11 +320,18 @@ var CPDocumentUntitledCount = 0; _readConnection.session = _CPReadSessionMake(aType, aDelegate, aDidReadSelector, aContextInfo); } +/* + Returns the path to the document's file. +*/ - (CPURL)fileURL { return _fileURL; } +/* + Sets the path to the document's file. + @param aFileURL the path to the document's file +*/ - (void)setFileURL:(CPURL)aFileURL { if (_fileURL == aFileURL) @@ -211,6 +342,16 @@ var CPDocumentUntitledCount = 0; [_windowControllers makeObjectsPerformSelector:@selector(synchronizeWindowTitleWithDocumentName)]; } +/* + Saves the document to the specified URL. Notifies the provided delegate + with the provided selector and context info afterwards. + @param anAbsoluteURL the url to write the document data to + @param aTypeName the document type + @param aSaveOperation the type of save operation + @param aDelegate the delegate to notify after saving + @param aDidSaveSelector the selector to send the delegate + @param aContextInfo context info that gets passed to the delegate +*/ - (void)saveToURL:(CPURL)anAbsoluteURL ofType:(CPString)aTypeName forSaveOperation:(CPSaveOperationType)aSaveOperation delegate:(id)aDelegate didSaveSelector:(SEL)aDidSaveSelector contextInfo:(id)aContextInfo { var data = [self dataOfType:[self fileType] error:nil], @@ -235,6 +376,10 @@ var CPDocumentUntitledCount = 0; connection.session = _CPSaveSessionMake(anAbsoluteURL, aSaveOperation, oldChangeCount, aDelegate, aDidSaveSelector, aContextInfo, connection); } +/* + Implemented as a delegate method for CPURLConnection + @ignore +*/ - (void)connection:(CPURLConnection)aConnection didReceiveResponse:(CPURLResponse)aResponse { var statusCode = [aResponse statusCode]; @@ -282,6 +427,10 @@ var CPDocumentUntitledCount = 0; } } +/* + Implemented as a delegate method for CPURLConnection + @ignore +*/ - (void)connection:(CPURLConnection)aConnection didReceiveData:(CPString)aData { var session = aConnection.session; @@ -304,6 +453,10 @@ var CPDocumentUntitledCount = 0; } } +/* + Implemented as a delegate method for CPURLConnection + @ignore +*/ - (void)connection:(CPURLConnection)aConnection didFailWithError:(CPError)anError { var session = aConnection.session; @@ -327,6 +480,10 @@ var CPDocumentUntitledCount = 0; } } +/* + Implemented as a delegate method for CPURLConnection + @ignore +*/ - (void)connectionDidFinishLoading:(CPURLConnection)aConnection { if (_readConnection == aConnection) @@ -334,12 +491,18 @@ var CPDocumentUntitledCount = 0; } // Managing Document Status - +/* + Returns YES if there are any unsaved changes. +*/ - (BOOL)isDocumentEdited { return _changeCount != 0; } +/* + Updates the number of unsaved changes to the document. + @param aChangeType a new document change to apply +*/ - (void)updateChangeCount:(CPDocumentChangeType)aChangeType { if (aChangeType == CPChangeDone) @@ -356,25 +519,38 @@ var CPDocumentUntitledCount = 0; } // Managing File Types - +/* + Sets the document's file type + @param aType the document's type +*/ - (void)setFileType:(CPString)aType { _fileType = aType; } +/* + Returns the document's file type +*/ - (CPString)fileType { return _fileType; } // Working with Undo Manager - +/* + Returns YES if the document has a + CPUndoManager. +*/ - (BOOL)hasUndoManager { return _hasUndoManager; } -- (void)setHashUndoManager:(BOOL)aFlag +/* + Sets whether the document should have a CPUndoManager. + @param aFlag YES makes the document have an undo manager +*/ +- (void)setHasUndoManager:(BOOL)aFlag { if (_hasUndoManager == aFlag) return; @@ -385,6 +561,7 @@ var CPDocumentUntitledCount = 0; [self setUndoManager:nil]; } +/* @ignore */ - (void)_undoManagerWillCloseGroup:(CPNotification)aNotification { var undoManager = [aNotification object]; @@ -395,16 +572,23 @@ var CPDocumentUntitledCount = 0; [self updateChangeCount:CPChangeDone]; } +/* @ignore */ - (void)_undoManagerDidUndoChange:(CPNotification)aNotification { [self updateChangeCount:CPChangeUndone]; } +/* @ignore */ - (void)_undoManagerDidRedoChange:(CPNotification)aNotification { [self updateChangeCount:CPChangeDone]; } +/* + Sets the document's undo manager. This method will add the + undo manager as an observer to the notification center. + @param anUndoManager the new undo manager for the document +*/ - (void)setUndoManager:(CPUndoManager)anUndoManager { var defaultCenter = [CPNotificationCenter defaultCenter]; @@ -446,6 +630,12 @@ var CPDocumentUntitledCount = 0; } } +/* + Returns the document's undo manager. If the document + should have one, but the manager is nil, it + will be created and then returned. + @return the document's undo manager +*/ - (CPUndoManager)undoManager { if (_hasUndoManager && !_undoManager) @@ -453,14 +643,23 @@ var CPDocumentUntitledCount = 0; return _undoManager; } - + +/* + Implemented as a delegate of a CPWindow + @ignore +*/ - (CPUndoManager)windowWillReturnUndoManager:(CPWindow)aWindow { return [self undoManager]; } // Handling User Actions - +/* + Saves the document. If the document does not + have a file path to save to (fileURL) + then saveDocumentAs: will be called. + @param aSender the object requesting the save +*/ - (void)saveDocument:(id)aSender { if (_fileURL) @@ -475,6 +674,10 @@ var CPDocumentUntitledCount = 0; [self saveDocumentAs:self]; } +/* + Saves the document to a user specified path. + @param aSender the object requesting the operation +*/ - (void)saveDocumentAs:(id)aSender { _documentName = window.prompt("Document Name:"); @@ -489,6 +692,9 @@ var CPDocumentUntitledCount = 0; [self saveToURL:[self proposedFileURL] ofType:[self fileType] forSaveOperation:CPSaveAsOperation delegate:self didSaveSelector:@selector(document:didSave:contextInfo:) contextInfo:NULL]; } +/* + @ignore +*/ - (void)document:(id)aDocument didSave:(BOOL)didSave contextInfo:(id)aContextInfo { if (didSave) diff --git a/AppKit/CPDocumentController.j b/AppKit/CPDocumentController.j index 0445f96ca6..84fbd9d7a9 100644 --- a/AppKit/CPDocumentController.j +++ b/AppKit/CPDocumentController.j @@ -27,12 +27,20 @@ import "CPDocument.j" var CPSharedDocumentController = nil; +/* + This class is responsible for managing an application's open documents. +*/ @implementation CPDocumentController : CPObject { CPArray _documents; CPArray _documentTypes; } +/* + Returns the singleton instance of the application's document controller. If it has not + been created yet, it will be created then returned. + @return a CPDocumentController +*/ + (id)sharedDocumentController { if (!CPSharedDocumentController) @@ -41,6 +49,9 @@ var CPSharedDocumentController = nil; return CPSharedDocumentController; } +/* + @ignore +*/ - (id)init { self = [super init]; @@ -59,6 +70,13 @@ var CPSharedDocumentController = nil; // Creating and Opening Documents +/* + Returns the document matching the specified URL. This + method searches documents already open. It does not + open the document at the URL if it is not already open. + @param aURL the url of the document + @return the document, or nil if such a document is not open +*/ - (CPDocument)documentForURL:(CPURL)aURL { var index = 0, @@ -75,6 +93,11 @@ var CPSharedDocumentController = nil; return nil; } +/* + Creates a new document of the specified type. + @param aType the type of the new document + @param shouldDisplay whether to display the document on screen +*/ - (void)openUntitledDocumentOfType:(CPString)aType display:(BOOL)shouldDisplay { var document = [self makeUntitledDocumentOfType:aType error:nil]; @@ -91,11 +114,24 @@ var CPSharedDocumentController = nil; return document; } +/* + Creates a document of the specified type. + @param aType the document type + @param anError not used + @return the created document +*/ - (CPDocument)makeUntitledDocumentOfType:(CPString)aType error:({CPError})anError { return [[[self documentClassForType:aType] alloc] initWithType:aType error:anError]; } +/* + Opens the document at the specified URL. + @param anAbsoluteURL the path to the document's file + @param shouldDisplay whether to display the document on screen + @param anError not used + @return the opened document +*/ - (CPDocument)openDocumentWithContentsOfURL:(CPURL)anAbsoluteURL display:(BOOL)shouldDisplay error:(CPError)anError { var result = [self documentForURL:anAbsoluteURL]; @@ -110,21 +146,53 @@ var CPSharedDocumentController = nil; return result; } +/* + Loads a document for a specified URL with it's content + retrieved from another URL. + @param anAbsoluteURL the document URL + @param absoluteContentsURL the location of the document's contents + @param anError not used + @return the loaded document or nil if there was an error +*/ - (CPDocument)reopenDocumentForURL:(CPURL)anAbsoluteURL withContentsOfURL:(CPURL)absoluteContentsURL error:(CPError)anError { return [self makeDocumentForURL:anAbsoluteURL withContentsOfURL:absoluteContentsURL ofType:[[_documentTypes objectAtIndex:0] objectForKey:@"CPBundleTypeName"] delegate:self didReadSelector:@selector(document:didRead:contextInfo:) contextInfo:nil]; } +/* + Creates a document from the contents at the specified URL. + Notifies the provided delegate with the provided selector afterwards. + @param anAbsoluteURL the location of the document data + @param aType the document type + @param aDelegate the delegate to notify + @param aSelector the selector to notify with + @param aContextInfo the context infomration passed to the delegate +*/ - (CPDocument)makeDocumentWithContentsOfURL:(CPURL)anAbsoluteURL ofType:(CPString)aType delegate:(id)aDelegate didReadSelector:(SEL)aSelector contextInfo:(id)aContextInfo { return [[[self documentClassForType:aType] alloc] initWithContentsOfURL:anAbsoluteURL ofType:aType delegate:aDelegate didReadSelector:aSelector contextInfo:aContextInfo]; } +/* + Creates a document from the contents of a URL, and sets + the document's URL location as another URL. + @param anAbsoluteURL the document's location + @param absoluteContentsURL the location of the document's contents + @param aType the document's data type + @param aDelegate receives a callback after the load has completed + @param aSelector the selector to invoke for the callback + @param aContextInfo an object passed as an argument for the callback + @return a new document or nil if there was an error +*/ - (CPDocument)makeDocumentForURL:(CPURL)anAbsoluteURL withContentsOfURL:(CPURL)absoluteContentsURL ofType:(CPString)aType delegate:(id)aDelegate didReadSelector:(SEL)aSelector contextInfo:(id)aContextInfo { return [[[self documentClassForType:aType] alloc] initForURL:anAbsoluteURL withContentsOfURL:absoluteContentsURL ofType:aType delegate:aDelegate didReadSelector:aSelector contextInfo:aContextInfo]; } +/* + Implemented delegate method + @ignore +*/ - (void)document:(CPDocument)aDocument didRead:(BOOL)didRead contextInfo:(id)aContextInfo { if (!didRead) @@ -134,6 +202,10 @@ var CPSharedDocumentController = nil; [aDocument makeWindowControllers]; } +/* + Opens a new document in the application. + @param aSender the requesting object +*/ - (CFAction)newDocument:(id)aSender { [self openUntitledDocumentOfType:[[_documentTypes objectAtIndex:0] objectForKey:@"CPBundleTypeName"] display:YES]; @@ -141,16 +213,28 @@ var CPSharedDocumentController = nil; // Managing Documents +/* + Returns the array of all documents being managed. This is + the same as all open documents in the application. +*/ - (CPArray)documents { return _documents; } +/* + Adds aDocument under the control of the receiver. + @param aDocument the document to add +*/ - (void)addDocument:(CPDocument)aDocument { [_documents addObject:aDocument]; } +/* + Removes aDocument from the control of the receiver. + @param aDocument the document to remove +*/ - (void)removeDocument:(CPDocument)aDocument { [_documents removeObjectIdenticalTo:aDocument]; @@ -158,6 +242,7 @@ var CPSharedDocumentController = nil; // Managing Document Types +/* @ignore */ - (CPDictionary)_infoForType:(CPString)aType { var i = 0, @@ -174,11 +259,16 @@ var CPSharedDocumentController = nil; return nil; } +/* + Returns the CPDocument subclass associated with aType. + @param aType the type of document + @return a Cappuccino Class object, or nil if no match was found +*/ - (Class)documentClassForType:(CPString)aType { var className = [[self _infoForType:aType] objectForKey:@"CPDocumentClass"]; - return className ? CPClassFromString(className) : Nil; + return className ? CPClassFromString(className) : nil; } @end diff --git a/AppKit/CPDragServer.j b/AppKit/CPDragServer.j index f9a0ca12b8..e1ce104542 100644 --- a/AppKit/CPDragServer.j +++ b/AppKit/CPDragServer.j @@ -114,11 +114,18 @@ var CPDragServerUpdateDragging = function(anEvent) [CPDragServerSource draggedView:CPDragServerView movedTo:location]; } +/* + CPDraggingInfo is a container of information about a specific dragging session. + @ignore +*/ @implementation CPDraggingInfo : CPObject { CPWindow _window; } +/* + Initializes the receiver with the window +*/ - (id)initWithWindow:(CPWindow)aWindow { self = [super init]; @@ -152,6 +159,10 @@ var CPDragServerUpdateDragging = function(anEvent) CPImageView _imageView; } +/* + Private Objective-J/Cappuccino method + @ignore +*/ + (void)initialize { if (self != [CPDragServer class]) @@ -168,6 +179,9 @@ var CPDragServerUpdateDragging = function(anEvent) return CPSharedDragServer; } +/* + @ignore +*/ - (id)init { self = [super init]; @@ -181,7 +195,19 @@ var CPDragServerUpdateDragging = function(anEvent) return self; } -- (void)dragView:(CPView)aView fromWindow:(CPWindow)aWindow at:(CPPoint)viewLocation offset:(CPSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack +/* + Initiates a drag session. + @param aView the view being dragged + @param aWindow the window where the drag source is + @param viewLocation + @param mouseOffset + @param anEvent + @param aPasteboard the pasteboard that contains the drag data + @param aSourceObject the object where the drag started + @param slideBack if YES, aView slides back to + its origin on a failed drop +*/ +- (void)dragView:(CPView)aView fromWindow:(CPWindow)aWindow at:(CGPoint)viewLocation offset:(CGSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack { var eventLocation = [anEvent locationInWindow]; @@ -224,7 +250,19 @@ var CPDragServerUpdateDragging = function(anEvent) CPDragServerStartDragging(anEvent); } -- (void)dragImage:(CPImage)anImage fromWindow:(CPWindow)aWindow at:(CPPoint)imageLocation offset:(CPSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack +/* + Initiates a drag session. + @param anImage the image to be dragged + @param aWindow the source window of the drag session + @param imageLocation + @param mouseOffset + @param anEvent + @param aPasteboard the pasteboard where the drag data is located + @param aSourceObject the object where the drag started + @param slideBack if YES, aView slides back to + its origin on a failed drop +*/ +- (void)dragImage:(CPImage)anImage fromWindow:(CPWindow)aWindow at:(CGPoint)imageLocation offset:(CGSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack { CPDragServerIsDraggingImage = YES; @@ -241,6 +279,7 @@ var CPDragServerUpdateDragging = function(anEvent) @implementation CPView (CPDraggingAdditions) +/* @ignore */ - (CPView)_dragHitTest:(CPPoint)aPoint pasteboard:(CPPasteboard)aPasteboard { if(!CPRectContainsPoint(_frame, aPoint) || self == CPDragServerView) diff --git a/AppKit/CPEvent.j b/AppKit/CPEvent.j index 56d5469cc3..8786c9fc0d 100644 --- a/AppKit/CPEvent.j +++ b/AppKit/CPEvent.j @@ -24,27 +24,110 @@ import #include "CoreGraphics/CGGeometry.h" - +/* + @global + @group CPEventType +*/ CPLeftMouseDown = 1; +/* + @global + @group CPEventType +*/ CPLeftMouseUp = 2; +/* + @global + @group CPEventType +*/ CPRightMouseDown = 3; +/* + @global + @group CPEventType +*/ CPRightMouseUp = 4; +/* + @global + @group CPEventType +*/ CPMouseMoved = 5; +/* + @global + @group CPEventType +*/ CPLeftMouseDragged = 6; +/* + @global + @group CPEventType +*/ CPRightMouseDragged = 7; +/* + @global + @group CPEventType +*/ CPMouseEntered = 8; +/* + @global + @group CPEventType +*/ CPMouseExited = 9; +/* + @global + @group CPEventType +*/ CPKeyDown = 10; +/* + @global + @group CPEventType +*/ CPKeyUp = 11; +/* + @global + @group CPEventType +*/ CPFlagsChanged = 12; +/* + @global + @group CPEventType +*/ CPAppKitDefined = 13; +/* + @global + @group CPEventType +*/ CPSystemDefined = 14; +/* + @global + @group CPEventType +*/ CPApplicationDefined = 15; +/* + @global + @group CPEventType +*/ CPPeriodic = 16; +/* + @global + @group CPEventType +*/ CPCursorUpdate = 17; +/* + @global + @group CPEventType +*/ CPScrollWheel = 22; +/* + @global + @group CPEventType +*/ CPOtherMouseDown = 25; +/* + @global + @group CPEventType +*/ CPOtherMouseUp = 26; +/* + @global + @group CPEventType +*/ CPOtherMouseDragged = 27; CPAlphaShiftKeyMask = 1 << 16; @@ -95,6 +178,9 @@ CPDOMEventScrollWheel = "mousewheel"; var _CPEventPeriodicEventPeriod = 0, _CPEventPeriodicEventTimer = nil; +/* + CPEvent encapsulates the details of a Cappuccino keyboard or mouse event. +*/ @implementation CPEvent : CPObject { CPEventType _type; @@ -116,8 +202,24 @@ var _CPEventPeriodicEventPeriod = 0, float _deltaY; float _deltaZ; } - -+ (CPEvent)keyEventWithType:(CPEventType)anEventType location:(CPPoint)aPoint modifierFlags:(unsigned int)modifierFlags + +/* + Creates a new keyboard event. + @param anEventType the event type. Must be one of CPKeyDown, CPKeyUp or CPFlagsChanged + @param aPoint the location of the cursor in the window specified by aWindowNumber + @param modifierFlags a bitwise combination of the modifiers specified in the CPEvent globals + @param aTimestamp the time the event occurred + @param aWindowNumber the number of the CPWindow where the event occurred + @param aGraphicsContext the graphics context where the event occurred + @param characters the characters associated with the event + @param unmodCharacters the string of keys pressed without the presence of any modifiers other than Shift + @param repeatKey YES if this is caused by the system repeat as opposed to the user pressing the key again + @param code a number associated with the keyboard key of this event + @throws CPInternalInconsistencyException if anEventType is not a CPKeyDown, + CPKeyUp or CPFlagsChanged + @return the keyboard event +*/ ++ (CPEvent)keyEventWithType:(CPEventType)anEventType location:(CGPoint)aPoint modifierFlags:(unsigned int)modifierFlags timestamp:(CPTimeInterval)aTimestamp windowNumber:(int)aWindowNumber context:(CPGraphicsContext)aGraphicsContext characters:(CPString)characters charactersIgnoringModifiers:(CPString)unmodCharacters isARepeat:(BOOL)repeatKey keyCode:(unsigned short)code { @@ -126,7 +228,21 @@ var _CPEventPeriodicEventPeriod = 0, characters:characters charactersIgnoringModifiers:unmodCharacters isARepeat:repeatKey keyCode:code]; } -+ (id)mouseEventWithType:(CPEventType)anEventType location:(CPPoint)aPoint modifierFlags:(unsigned)modifierFlags +/* + Creates a new mouse event + @param anEventType the event type + @param aPoint the location of the cursor in the window specified by aWindowNumber + @param modifierFlags a bitwise combination of the modifiers specified in the CPEvent globals + @param aTimestamp the time the event occurred + @param aWindowNumber the number of the CPWindow where the event occurred + @param aGraphicsContext the graphics context where the event occurred + @param anEventNumber a number for this event + @param aClickCount the number of clicks that caused this event + @param aPressure the amount of pressure applied to the input device (ranges from 0.0 to 1.0) + @throws CPInternalInconsistencyException if an invalid event type is provided + @return the new mouse event +*/ ++ (id)mouseEventWithType:(CPEventType)anEventType location:(CGPoint)aPoint modifierFlags:(unsigned)modifierFlags timestamp:(CPTimeInterval)aTimestamp windowNumber:(int)aWindowNumber context:(CPGraphicsContext)aGraphicsContext eventNumber:(int)anEventNumber clickCount:(int)aClickCount pressure:(float)aPressure { @@ -134,6 +250,20 @@ var _CPEventPeriodicEventPeriod = 0, timestamp:aTimestamp windowNumber:aWindowNumber context:aGraphicsContext eventNumber:anEventNumber clickCount:aClickCount pressure:aPressure]; } +/* + Creates a new custom event + @param anEventType the event type. Must be one of CPAppKitDefined, CPSystemDefined, CPApplicationDefined or CPPeriodic + @param aLocation the location of the cursor in the window specified by aWindowNumber + @param modifierFlags a bitwise combination of the modifiers specified in the CPEvent globals + @param aTimestamp the time the event occurred + @param aWindowNumber the number of the CPWindow where the event occurred + @param aGraphicsContext the graphics context where the event occurred + @param aSubtype a numeric identifier to differentiate this event from other custom events + @param aData1 more data that describes the event + @param aData2 even more data that describes the event + @throws CPInternalInconsistencyException if an invalid event type is provided + @return the new custom event +*/ + (CPEvent)otherEventWithType:(CPEventType)anEventType location:(CGPoint)aLocation modifierFlags:(unsigned)modifierFlags timestamp:(CPTimeInterval)aTimestamp windowNumber:(int)aWindowNumber context:(CPGraphicsContext)aGraphicsContext subtype:(short)aSubtype data1:(int)aData1 data2:(int)aData2 @@ -142,6 +272,7 @@ var _CPEventPeriodicEventPeriod = 0, timestamp:aTimestamp windowNumber:aWindowNumber context:aGraphicsContext subtype:aSubtype data1:aData1 data2:aData2]; } +/* @ignore */ - (id)_initMouseEventWithType:(CPEventType)anEventType location:(CPPoint)aPoint modifierFlags:(unsigned)modifierFlags timestamp:(CPTimeInterval)aTimestamp windowNumber:(int)aWindowNumber context:(CPGraphicsContext)aGraphicsContext eventNumber:(int)anEventNumber clickCount:(int)aClickCount pressure:(float)aPressure @@ -164,6 +295,7 @@ var _CPEventPeriodicEventPeriod = 0, return self; } +/* @ignore */ - (id)_initKeyEventWithType:(CPEventType)anEventType location:(CPPoint)aPoint modifierFlags:(unsigned int)modifierFlags timestamp:(CPTimeInterval)aTimestamp windowNumber:(int)aWindowNumber context:(CPGraphicsContext)aGraphicsContext characters:(CPString)characters charactersIgnoringModifiers:(CPString)unmodCharacters isARepeat:(BOOL)isARepeat keyCode:(unsigned short)code @@ -187,6 +319,7 @@ var _CPEventPeriodicEventPeriod = 0, return self; } +/* @ignore */ - (id)_initOtherEventWithType:(CPEventType)anEventType location:(CGPoint)aPoint modifierFlags:(unsigned)modifierFlags timestamp:(CPTimeInterval)aTimestamp windowNumber:(int)aWindowNumber context:(CPGraphicsContext)aGraphicsContext subtype:(short)aSubtype data1:(int)aData1 data2:(int)aData2 @@ -208,63 +341,107 @@ var _CPEventPeriodicEventPeriod = 0, return self; } -- (CPPoint)locationInWindow +/* + Returns the location of the mouse (for mouse events). + If this is not a mouse event, it returns nil. + If window returns nil, then + the mouse coordinates will be based on the screen coordinates. + Otherwise, the coordinates are relative to the window's coordinates. + @return the location of the mouse, or nil for non-mouse events. +*/ +- (CGPoint)locationInWindow { return _location; } +/* + Returns event information as a bit mask +*/ - (unsigned)modifierFlags { return _modifierFlags; } +/* + Returns the time the event occurred +*/ - (CPTimeInterval)timestamp { return _timestamp; } +/* + Returns the type of event. +*/ - (CPEventType)type { return _type; } +/* + Returns the event's associated window +*/ - (CPWindow)window { return _window; } +/* + The number of the window associated with the event. +*/ - (int)windowNumber { return _windowNumber; } // Mouse Event Information - +/* + Returns the button number for the mouse that generated the event. +*/ - (int)buttonNumber { return _buttonNumber; } +/* + Returns the number of clicks that caused this event. (mouse only) +*/ - (int)clickCount { return _clickCount; } +/* + Returns the characters associated with this event (keyboard only) + @throws CPInternalInconsistencyException if this method is called on a non-key event +*/ - (CPString)characters { return _characters; } +/* + Returns the character ignoring any modifiers (except shift). + @throws CPInternalInconsistencyException if this method is called on a non-key event +*/ - (CPString)charactersIgnoringModifiers { return _charactersIgnoringModifiers; } +/* + Returns YES if the keyboard event was caused by the key being held down. + @throws CPInternalInconsistencyException if this method is called on a non-key event +*/ - (BOOL)isARepeat { return _isARepeat; } +/* + Returns the key's key code. + @throws CPInternalInconsistencyException if this method is called on a non-key event +*/ - (unsigned short)keyCode { return _keyCode; @@ -275,28 +452,44 @@ var _CPEventPeriodicEventPeriod = 0, return _pressure; } +/* + @ignore +*/ - (DOMEvent)_DOMEvent { return _DOMEvent; } // Getting Scroll Wheel Event Infomration - +/* + Returns the change in the x-axis for a mouse event. +*/ - (float)deltaX { return _deltaX; } +/* + Returns the change in the y-axis for a mouse event. +*/ - (float)deltaY { return _deltaY; } +/* + Returns the change in the x-axis for a mouse event. +*/ - (float)deltaZ { return _deltaZ; } +/* + Generates periodic events every aPeriod seconds. + @param aDelay the number of seconds before the first event + @param aPeriod the length of time in seconds between successive events +*/ + (void)startPeriodicEventsAfterDelay:(CPTimeInterval)aDelay withPeriod:(CPTimeInterval)aPeriod { _CPEventPeriodicEventPeriod = aPeriod; @@ -305,6 +498,9 @@ var _CPEventPeriodicEventPeriod = 0, _CPEventPeriodicEventTimer = window.setTimeout(function() { _CPEventPeriodicEventTimer = window.setInterval(_CPEventFirePeriodEvent, aPeriod * 1000.0); }, aDelay * 1000.0); } +/* + Stops the periodic events from being generated +*/ + (void)stopPeriodicEvents { if (_CPEventPeriodicEventTimer === nil) diff --git a/AppKit/CPFont.j b/AppKit/CPFont.j index fa247d67cb..f5379ee73a 100644 --- a/AppKit/CPFont.j +++ b/AppKit/CPFont.j @@ -25,6 +25,9 @@ var _CPFonts = {}; #define _CPCachedFont(aName, aSize, isBold) _CPFonts[(isBold ? @"bold " : @"") + ROUND(aSize) + @"px '" + aName + @"'"] +/* + The CPFont class allows control of the fonts used for displaying text anywhere on the screen. The primary method for getting a particular font is through one of the class methods that take a name and/or size as arguments, and return the appropriate CPFont. +*/ @implementation CPFont : CPObject { CPString _name; @@ -34,26 +37,51 @@ var _CPFonts = {}; CPString _cssString; } -+ (id)fontWithName:(CPString)aName size:(float)aSize +/* + Returns a font with the specified name and size. + @param aName the name of the font + @param aSize the size of the font (in points) + @return the requested font +*/ ++ (CPFont)fontWithName:(CPString)aName size:(float)aSize { return _CPCachedFont(aName, aSize, NO) || [[CPFont alloc] _initWithName:aName size:aSize bold:NO]; } -+ (id)boldFontWithName:(CPString)aName size:(float)aSize +/* + Returns a bold font with the specified name and size. + @param aName the name of the font + @param aSize the size of the font (in points) + @return the requested bold font +*/ ++ (CPFont)boldFontWithName:(CPString)aName size:(float)aSize { return _CPCachedFont(aName, aSize, YES) || [[CPFont alloc] _initWithName:aName size:aSize bold:YES]; } -+ (id)systemFontOfSize:(CPSize)aSize +/* + Returns the system font scaled to the specified size + @param aSize the size of the font (in points) + @return the requested system font +*/ ++ (CPFont)systemFontOfSize:(CPSize)aSize { return _CPCachedFont(_CPFontSystemFontFace, aSize, NO) || [[CPFont alloc] _initWithName:_CPFontSystemFontFace size:aSize bold:NO]; } -+ (id)boldSystemFontOfSize:(CPSize)aSize +/* + Returns the bold system font scaled to the specified size + @param aSize the size of the font (in points) + @return the requested bold system font +*/ ++ (CPFont)boldSystemFontOfSize:(CPSize)aSize { return _CPCachedFont(_CPFontSystemFontFace, aSize, YES) || [[CPFont alloc] _initWithName:_CPFontSystemFontFace size:aSize bold:YES]; } -// FIXME Font Descriptor + +/** FIXME Font Descriptor + @ignore +*/ - (id)_initWithName:(CPString)aName size:(float)aSize bold:(BOOL)isBold { self = [super init]; @@ -72,16 +100,25 @@ var _CPFonts = {}; return self; } +/* + Returns the font size (in points) +*/ - (float)size { return _size; } +/* + Returns the font as a CSS string +*/ - (CPString)cssString { return _cssString; } +/* + Returns the font's family name +*/ - (CPString)familyName { return _name; @@ -95,6 +132,11 @@ var CPFontNameKey = @"CPFontNameKey", @implementation CPFont (CPCoding) +/* + Initializes the font from a coder. + @param aCoder the coder from which to read the font data + @return the initialized font +*/ - (id)initWithCoder:(CPCoder)aCoder { return [self _initWithName:[aCoder decodeObjectForKey:CPFontNameKey] @@ -102,6 +144,10 @@ var CPFontNameKey = @"CPFontNameKey", bold:[aCoder decodeBoolForKey:CPFontIsBoldKey]]; } +/* + Writes the font information out to a coder. + @param aCoder the coder to which the data will be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeObject:_name forKey:CPFontNameKey]; diff --git a/AppKit/CPFontManager.j b/AppKit/CPFontManager.j index 0601129f51..3e074c49fd 100644 --- a/AppKit/CPFontManager.j +++ b/AppKit/CPFontManager.j @@ -34,8 +34,11 @@ var CPSharedFontManager = nil, } // Getting the Shared Font Manager - -+ (id)sharedFontManager +/* + Returns the application's font manager. If the font + manager does not exist yet, it will be created. +*/ ++ (CPFontManager)sharedFontManager { if (!CPSharedFontManager) CPSharedFontManager = [[CPFontManagerFactory alloc] init]; @@ -44,12 +47,18 @@ var CPSharedFontManager = nil, } // Changing the Default Font Conversion Classes - +/* + Sets the class that will be used to create the applcation's + font manager. +*/ + (void)setFontManagerFactory:(Class)aClass { CPFontManagerFactory = aClass; } +/* + Returns an array of the available fonts +*/ - (CPArray)availableFonts { if (!_availableFonts) @@ -75,6 +84,10 @@ var CPSharedFontManager = nil, return _availableFonts; } +/* + Returns the available fonts matching the provided name. + @param aFontName the name of the font +*/ - (CPArray)fontWithNameIsAvailable:(CPString)aFontName { return _CPFontDetectFontAvailable(aFontName); diff --git a/AppKit/CPGeometry.j b/AppKit/CPGeometry.j index 74a6e8834c..738bdd894d 100644 --- a/AppKit/CPGeometry.j +++ b/AppKit/CPGeometry.j @@ -32,28 +32,61 @@ CPMakePoint = CGPointMake; CPMakeSize = CGSizeMake; CPMakeRect = CGRectMake; +/** + Creates a copy of a specified point and returns the copy + @group CGPoint + @param the point to be copied + @return CGPoint the copy of the provided CGPoint + */ function CPPointCreateCopy(aPoint) { return { x: aPoint.x, y: aPoint.y }; } +/** + Makes a CGPoint object out of two numbers provided as arguments + @group CGPoint + @param x the x-coordinate of the CGPoint + @param y the y-coordinate of the CGPoint + @return CGPoint a CGPoint with an X and Y coordinate equal to the function arguments + */ function CPPointMake(x, y) { return { x: x, y: y }; } +/* + Makes a CGRect with an origin and size equal to aRect less the dX/dY insets specified. + @param dX the size of the inset in the x-axis + @param dY the size of the inset in the y-axis + @group CGRect + @return CGRect a rectangle like aRect with an inset +*/ function CPRectInset(aRect, dX, dY) { return CPRectMake( aRect.origin.x + dX, aRect.origin.y + dY, aRect.size.width - 2 * dX, aRect.size.height - 2*dY); } +/* + @group CGRect + @ignore + @return void + @deprecated +*/ function CPRectIntegral(aRect) { // FIXME!!! alert("CPRectIntegral unimplemented"); } +/* + Returns the intersection of the two provided rectangles as a new rectangle + @group CGRect + @param lhsRect the first rectangle used for calculation + @param rhsRect the second rectangle used for calculation + @return CGRect the intersection of the two rectangles +*/ function CPRectIntersection(lhsRect, rhsRect) { var intersection = CPRectMake( @@ -67,21 +100,49 @@ function CPRectIntersection(lhsRect, rhsRect) return CPRectIsEmpty(intersection) ? CPRectMakeZero() : intersection; } +/* + Creates a copy of the provided rectangle + @group CGRect + @param aRect the CGRect that will be copied + @return CGRect the rectangle copy +*/ function CPRectCreateCopy(aRect) { return { origin: CPPointCreateCopy(aRect.origin), size: CPSizeCreateCopy(aRect.size) }; } +/* + Returns a CGRect made of the specified arguments + @group CGRect + @param x the x-coordinate of the rectangle's origin + @param y the y-coordinate of the rectangle's origin + @param width the width of the new rectangle + @param height the height of the new rectangle + @return CGRect the new rectangle +*/ function CPRectMake(x, y, width, height) { return { origin: CPPointMake(x, y), size: CPSizeMake(width, height) }; } +/* + Creates a new rectangle with its origin offset by dX and dY. + @group CGRect + @param aRect the rectangle to copy the origin and size from + @param dX the amount added to the x-size of the new rectangle + @param dY the amount added to the y-size of the new rectangle + @return CGRect the new rectangle with modified size +*/ function CPRectOffset(aRect, dX, dY) { return CPRectMake(aRect.origin.x + dX, aRect.origin.y + dY, aRect.size.width, aRect.size.height); } +/* + @group CGRect + @param aRect a CGRect + @return CGRect +*/ function CPRectStandardize(aRect) { var width = CPRectGetWidth(aRect), @@ -103,6 +164,13 @@ function CPRectStandardize(aRect) return standardized; } +/* + Returns the smallest rectangle that can contain the two argument CGRects. + @group CGRect + @param lhsRect the first CGRect to use for the union calculation + @param rhsRect the second CGRect to use for the union calculation + @return CGRect the union rectangle +*/ function CPRectUnion(lhsRect, rhsRect) { var minX = Math.min(CPRectGetMinX(lhsRect), CPRectGetMinX(rhsRect)), @@ -113,16 +181,37 @@ function CPRectUnion(lhsRect, rhsRect) return CPRectMake(minX, minY, maxX - minX, maxY - minY); } +/* + Creates and returns a copy of the provided CGSize + @group CGSize + @param aSize the CGSize to copy + @return CGSize the copy of the CGSize +*/ function CPSizeCreateCopy(aSize) { return { width: aSize.width, height: aSize.height }; } +/* + Creates and returns a new CGSize object from the provided dimensions. + @group CGSize + @param width the width for the new CGSize + @param height the height for the new CGSize + @return CGSize the new CGSize +*/ function CPSizeMake(width, height) { return { width: width, height: height }; } +/* + Returns YES if the CGRect, aRect, contains + the CGPoint, aPoint. + @param aRect the rectangle to test with + @param aPoint the point to test with + @group CGRect + @return BOOL YES if the rectangle contains the point, NO otherwise. +*/ function CPRectContainsPoint(aRect, aPoint) { return aPoint.x >= CPRectGetMinX(aRect) && @@ -131,97 +220,211 @@ function CPRectContainsPoint(aRect, aPoint) aPoint.y < CPRectGetMaxY(aRect); } +/* + Returns a BOOL indicating whether CGRect possibleOuter + contains CGRect possibleInner. + @group CGRect + @param possibleOuter the CGRect to test if possibleInner is inside of + @param possibleInner the CGRect to test if it fits inside possibleOuter. + @return BOOL YES if possibleInner fits inside possibleOuter. +*/ function CPRectContainsRect(lhsRect, rhsRect) { return CPRectEqualToRect(CPUnionRect(lhsRect, rhsRect), rhsRect); } +/* + Tests whether the two CGPoints are equal to each other by comparing their + x and y members. + @group @CGPoint + @param lhsPoint the first CGPoint to check + @param rhsPoint the second CGPoint to check + @return BOOL YES if the two points have the same x's, and the same y's. +*/ function CPPointEqualToPoint(lhsPoint, rhsPoint) { return lhsPoint.x == rhsPoint.x && lhsPoint.y == rhsPoint.y; } +/* + Test whether the two CGRects have the same origin and size + @group CGRect + @param lhsRect the first CGRect to compare + @param rhsRect the second CGRect to compare + @return BOOL YES if the two rectangles have the same origin and size. NO, otherwise. +*/ function CPRectEqualToRect(lhsRect, rhsRect) { return CPPointEqualToPoint(lhsRect.origin, rhsRect.origin) && CPSizeEqualToSize(lhsRect.size, rhsRect.size); } +/* + @group CGRect + @param aRect a CGRect + @return int +*/ function CPRectGetHeight(aRect) { return aRect.size.height; } +/* + @group CGRect + @param aRect a CGRect + @return int +*/ function CPRectGetMaxX(aRect) { return aRect.origin.x + aRect.size.width; } +/* + @group CGRect + @param aRect a CGRect + @return int +*/ function CPRectGetMaxY(aRect) { return aRect.origin.y + aRect.size.height; } +/* + @group CGRect + @param aRect a CGRect + @return float +*/ function CPRectGetMidX(aRect) { return aRect.origin.x + (aRect.size.width) / 2.0; } +/* + @group CGRect + @param aRect a CGRect + @return float +*/ function CPRectGetMidY(aRect) { return aRect.origin.y + (aRect.size.height) / 2.0; } +/* + @group CGRect + @param aRect a CGRect + @return int +*/ function CPRectGetMinX(aRect) { return aRect.origin.x; } +/* + @group CGRect + @param aRect a CGRect + @return int +*/ function CPRectGetMinY(aRect) { return aRect.origin.y; } +/* + @group CGRect + @param aRect a CGRect + @return int +*/ function CPRectGetWidth(aRect) { return aRect.size.width; } +/* + Returns YES if the two rectangles intersect + @group CGRect + @param lhsRect the first CGRect + @param rhsRect the second CGRect + @return BOOL YES if the two rectangles have any common spaces, and NO, otherwise. +*/ function CPRectIntersectsRect(lhsRect, rhsRect) { return !CPRectIsEmpty(CPRectIntersection(lhsRect, rhsRect)); } +/* + Returns YES if the CGRect has no area. + The test is performed by checking if the width and height are both zero. + @group CGRect + @param aRect the CGRect to test + @return BOOL YES if the CGRect has no area, and NO, otherwise. +*/ function CPRectIsEmpty(aRect) { return aRect.size.width <= 0.0 || aRect.size.height <= 0.0; } +/* + Returns YES if the CGRect has no area. + The test is performed by checking if the width and height are both zero. + @group CGRect + @return BOOL YES if the CGRect has no area, and NO, otherwise. +*/ function CPRectIsNull(aRect) { return aRect.size.width <= 0.0 || aRect.size.height <= 0.0; } +/* + Returns YES if the two CGSizes are identical. + @group CGSize + @param lhsSize the first CGSize to compare + @param rhsSize the second CGSize to compare + @return BOOL YES if the two sizes are identical. NO, otherwise. +*/ function CPSizeEqualToSize(lhsSize, rhsSize) { return lhsSize.width == rhsSize.width && lhsSize.height == rhsSize.height; } +/* + Returns a human readable string of the provided CGPoint. + @group CGPoint + @param aPoint the point to represent + @return CGPoint a string representation of the CGPoint +*/ function CPStringFromPoint(aPoint) { return "{" + aPoint.x + ", " + aPoint.y + "}"; } +/* + Returns a human readable string of the provided CGSize. + @group CGSize + @param aSize the size to represent + @return CGSize a string representation of the CGSize +*/ function CPStringFromSize(aSize) { return "{" + aSize.width + ", " + aSize.height + "}"; } +/* + Returns a human readable string of the provided CGRect. + @group CGRect + @param aRect the rectangle to represent + @return CGString the string representation of the rectangle +*/ function CPStringFromRect(aRect) { return "{" + CPStringFromPoint(aRect.origin) + ", " + CPStringFromSize(aRect.size) + "}"; } +/* + Returns a CGPoint from a string with a comma separated pair of integers. + @group CGPoint + @param aString a string containing two comma separated integers + @return CGPoint the point object created from the string +*/ function CPPointFromString(aString) { var comma = aString.indexOf(','); @@ -229,6 +432,12 @@ function CPPointFromString(aString) return { x:parseInt(aString.substr(1, comma - 1)), y:parseInt(aString.substring(comma + 1, aString.length)) }; } +/* + Returns a CGSize from a string containing a pair of comma separated integers. + @group CGSize + @param aString a string containing two comma separated integers + @return CGSize the size object created from the string +*/ function CPSizeFromString(aString) { var comma = aString.indexOf(','); @@ -236,6 +445,12 @@ function CPSizeFromString(aString) return { width:parseInt(aString.substr(1, comma - 1)), height:parseInt(aString.substring(comma + 1, aString.length)) }; } +/* + Returns a CGRect created from a string. + @group CGRect + @param aString a string in the form generated by CPStringFromRect + @return CGRect the rectangle created from the string +*/ function CPRectFromString(aString) { var comma = aString.indexOf(',', aString.indexOf(',') + 1); @@ -243,21 +458,41 @@ function CPRectFromString(aString) return { origin:CPPointFromString(aString.substr(1, comma - 1)), size:CPSizeFromString(aString.substring(comma + 2, aString.length)) }; } +/* + @group CGPoint + @param anEvent + @return CGPoint +*/ function CPPointFromEvent(anEvent) { return CPPointMake(anEvent.clientX, anEvent.clientY, 0); } +/* + Returns a zero sized CGSize. + @group CGSize + @return CGSize a size object with zeros for width and height +*/ function CPSizeMakeZero() { return CPSizeMake(0, 0); } +/* + Returns a rectangle at origin (0,0) and size of (0,0). + @group CGRect + @return CGRect a zeroed out CGRect +*/ function CPRectMakeZero() { return CPRectMake(0, 0, 0, 0); } +/* + Returns a point located at (0, 0). + @group CGPoint + @return CGPoint a point located at (0, 0) +*/ function CPPointMakeZero() { return CPPointMake(0, 0, 0); diff --git a/AppKit/CPGraphicsContext.j b/AppKit/CPGraphicsContext.j index 6b4d77f1d0..7e1584cc6a 100644 --- a/AppKit/CPGraphicsContext.j +++ b/AppKit/CPGraphicsContext.j @@ -22,26 +22,46 @@ var CPGraphicsContextCurrent = nil; +/* + Provides an interface for drawing to the screen. +*/ @implementation CPGraphicsContext : CPObject { CPContext _graphicsPort; } -+ (void)currentContext +/* + Returns the current graphics context. +*/ ++ (CPGraphicsContext)currentContext { return CPGraphicsContextCurrent; } +/* + Sets the current graphics context +*/ + (void)setCurrentContext:(CPGraphicsContext)aGraphicsContext { CPGraphicsContextCurrent = aGraphicsContext; } -+ (id)graphicsContextWithGraphicsPort:(CPContext)aContext flipped:(BOOL)aFlag +/* + Creates a graphics context with a provided port. + @param aContext the context to initialize with + @param aFlag whether the context should be flipped + @return the initialized graphics context +*/ ++ (CPGraphicsContext)graphicsContextWithGraphicsPort:(CGContext)aContext flipped:(BOOL)aFlag { return [[self alloc] initWithGraphicsPort:aContext]; } +/* + Initializes the context with a graphics port. + @param aGraphicsPort the graphics port to initialize with + @return the initialized context +*/ - (id)initWithGraphicsPort:(CPContext)aGraphicsPort { self = [super init]; @@ -52,7 +72,10 @@ var CPGraphicsContextCurrent = nil; return self; } -- (CPContext)graphicsPort +/* + Returns the graphics context's port. +*/ +- (CGContext)graphicsPort { return _graphicsPort; } diff --git a/AppKit/CPImage.j b/AppKit/CPImage.j index 2089602a4d..f51d44805a 100644 --- a/AppKit/CPImage.j +++ b/AppKit/CPImage.j @@ -44,9 +44,25 @@ CPImageLoadStatusReadError = 6; @end +/* + CPImage is used to represent images in the Cappuccino framework. It supports loading + all image types supported by the browser. + + @delegate -(void)imageDidLoad:(CPImage)image; + Called when the specified image has finished loading. + @param image the image that loaded + + @delegate -(void)imageDidError:(CPImage)image; + Called when the specified image had an error loading. + @param image the image with the loading error + + @delegate -(void)imageDidAbort:(CPImage)image; + Called when the image loading was aborted. + @param image the image that was aborted +*/ @implementation CPImage : CPObject { - CPSize _size; + CGSize _size; CPString _filename; id _delegate; @@ -55,7 +71,15 @@ CPImageLoadStatusReadError = 6; Image _image; } -- (CPImage)initByReferencingFile:(CPString)aFilename size:(CPSize)aSize +/* + Initializes the image, by associating it with a filename. The image + denoted in aFilename is not actually loaded. It will + be loaded once needed. + @param aFilename the file containing the image + @param aSize the image's size + @return the initialized image +*/ +- (CPImage)initByReferencingFile:(CPString)aFilename size:(CGSize)aSize { self = [super init]; @@ -69,7 +93,13 @@ CPImageLoadStatusReadError = 6; return self; } -- (CPImage)initWithContentsOfFile:(CPString)aFilename size:(CPSize)aSize +/* + Initializes the image. Loads the specified image into memory. + @param aFilename the image to load + @param aSize the size of the image + @return the initialized image. +*/ +- (CPImage)initWithContentsOfFile:(CPString)aFilename size:(CGSize)aSize { self = [self initByReferencingFile:aFilename size:aSize]; @@ -79,6 +109,12 @@ CPImageLoadStatusReadError = 6; return self; } +/* + Initializes the receiver with the contents of the specified + image file. The method loads the data into memory. + @param aFilename the file name of the image + @return the initialized image +*/ - (CPImage)initWithContentsOfFile:(CPString)aFilename { self = [self initByReferencingFile:aFilename size: CGSizeMake(-1, -1)]; @@ -89,36 +125,61 @@ CPImageLoadStatusReadError = 6; return self; } +/* + Returns the path of the file associated with this image. +*/ - (CPString)filename { return _filename; } -- (void)setSize:(CPSize)aSize +/* + Sets the size of the image. + @param the size of the image +*/ +- (void)setSize:(CGSize)aSize { _size = CGSizeMakeCopy(aSize); } +/* + Returns the size of the image +*/ - (CGSize)size { return _size; } +/* + Sets the receiver's delegate. + @param the delegate +*/ - (void)setDelegate:(id)aDelegate { _delegate = aDelegate; } +/* + Returns the receiver's delegate +*/ - (id)delegate { return _delegate; } +/* + Returns YES if the image data has already been loaded. +*/ - (BOOL)loadStatus { return _loadStatus; } +/* + Loads the image data from the file into memory. You + should not call this method directly. Instead use + one of the initializers. +*/ - (void)load { if (_loadStatus == CPImageLoadStatusLoading || _loadStatus == CPImageLoadStatusCompleted) @@ -150,6 +211,7 @@ CPImageLoadStatusReadError = 6; return NO; } +/* @ignore */ - (void)_imageDidLoad { _loadStatus = CPImageLoadStatusCompleted; @@ -164,6 +226,7 @@ CPImageLoadStatusReadError = 6; [[CPRunLoop currentRunLoop] performSelectors]; } +/* @ignore */ - (void)_imageDidError { _loadStatus = CPImageLoadStatusReadError; @@ -174,6 +237,7 @@ CPImageLoadStatusReadError = 6; [[CPRunLoop currentRunLoop] performSelectors]; } +/* @ignore */ - (void)_imageDidAbort { _loadStatus = CPImageLoadStatusCancelled; @@ -188,11 +252,20 @@ CPImageLoadStatusReadError = 6; @implementation CPImage (CPCoding) +/* + Initializes the image with data from a coder. + @param aCoder the coder from which to read the image data + @return the initialized image +*/ - (id)initWithCoder:(CPCoder)aCoder { return [self initWithContentsOfFile:[aCoder decodeObjectForKey:@"CPFilename"] size:[aCoder decodeSizeForKey:@"CPSize"]]; } +/* + Writes the image data from memory into the coder. + @param aCoder the coder to which the data will be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeObject:_filename forKey:@"CPFilename"]; diff --git a/AppKit/CPImageView.j b/AppKit/CPImageView.j index d39f3f4b1c..6aa860c5c3 100644 --- a/AppKit/CPImageView.j +++ b/AppKit/CPImageView.j @@ -30,8 +30,20 @@ import "CPShadowView.j" #include "CoreGraphics/CGGeometry.h" +/* + @global + @group CPImageScaling +*/ CPScaleProportionally = 0; +/* + @global + @group CPImageScaling +*/ CPScaleToFit = 1; +/* + @global + @group CPImageScaling +*/ CPScaleNone = 2; @@ -44,6 +56,9 @@ var LEFT_SHADOW_INSET = 3.0, VERTICAL_SHADOW_INSET = TOP_SHADOW_INSET + BOTTOM_SHADOW_INSET, HORIZONTAL_SHADOW_INSET = LEFT_SHADOW_INSET + RIGHT_SHADOW_INSET; +/* + This class is a control that displays an image. +*/ @implementation CPImageView : CPControl { CPImage _image; @@ -78,11 +93,18 @@ var LEFT_SHADOW_INSET = 3.0, return self; } +/* + Returns the view's image. +*/ - (CPImage)image { return _image; } +/* + Sets the image for the view. + @param anImage the view's image +*/ - (void)setImage:(CPImage)anImage { if (_image == anImage) @@ -105,6 +127,19 @@ var LEFT_SHADOW_INSET = 3.0, [self tile]; } +/* + Returns YES if the image view draws with + a drop shadow. The default is NO. +*/ +- (BOOL)hasShadow +{ + return _hasShadow; +} + +/* + Sets whether the image view should draw with a drop shadow. + @param shouldHaveShadow whether the image view should have a shadow +*/ - (void)setHasShadow:(BOOL)shouldHaveShadow { if (_hasShadow == shouldHaveShadow) @@ -130,6 +165,11 @@ var LEFT_SHADOW_INSET = 3.0, [self hideOrDisplayContents]; } +/* + Sets the type of image scaling that should be used to + render the image. + @param anImageScaling the type of scaling to use +*/ - (void)setImageScaling:(CPImageScaling)anImageScaling { if (_imageScaling == anImageScaling) @@ -152,6 +192,10 @@ var LEFT_SHADOW_INSET = 3.0, [self tile]; } +/* + Returns the image scaling method used to + render this image. +*/ - (CPImageScaling)imageScaling { return _imageScaling; @@ -164,6 +208,9 @@ var LEFT_SHADOW_INSET = 3.0, [self tile]; } +/* + Toggles the display of the image view. +*/ - (void)hideOrDisplayContents { if (!_image) @@ -178,11 +225,17 @@ var LEFT_SHADOW_INSET = 3.0, } } +/* + Returns the view's image rectangle +*/ - (CGRect)imageRect { return _imageRect; } +/* + Add a description +*/ - (void)tile { if (!_image) @@ -256,6 +309,11 @@ var CPImageViewImageKey = @"CPImageViewImageKey", @implementation CPImageView (CPCoding) +/* + Initializes the image view with the provided coder. + @param aCoder the coder from which data will be read. + @return the initialized image view +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super initWithCoder:aCoder]; @@ -281,6 +339,11 @@ var CPImageViewImageKey = @"CPImageViewImageKey", return self; } +/* + Writes the image view out to the coder. + @param aCoder the coder to which the image + view will be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { // We do this in order to avoid encoding the _shadowView, which diff --git a/AppKit/CPKulerColorPicker.j b/AppKit/CPKulerColorPicker.j index d1d6df9383..2e3f649f65 100644 --- a/AppKit/CPKulerColorPicker.j +++ b/AppKit/CPKulerColorPicker.j @@ -32,6 +32,9 @@ import "CPTabView.j" import "CPTabViewItem.j" +/* + @ignore +*/ @implementation CPKulerColorPicker : CPColorPicker { CPView _contentView; @@ -229,6 +232,7 @@ import "CPTabViewItem.j" @end +/* @ignore */ @implementation _CPKulerThemeView : CPView { CPArray _themes; @@ -320,6 +324,7 @@ import "CPTabViewItem.j" @end +/* @ignore */ @implementation _CPColorView : CPControl { diff --git a/AppKit/CPMenu.j b/AppKit/CPMenu.j index 0612244ad9..21abf40dd9 100644 --- a/AppKit/CPMenu.j +++ b/AppKit/CPMenu.j @@ -48,6 +48,9 @@ var _CPMenuBarVisible = NO, _CPMenuBarIconImageAlphaValue = 1.0, _CPMenuBarSharedWindow = nil; +/* + Menus provide the user with a list of actions and/or submenus. Submenus themselves are full fledged menus and so a heirarchical structure appears. +*/ @implementation CPMenu : CPObject { CPString _title; @@ -137,7 +140,11 @@ var _CPMenuBarVisible = NO, } // Creating a CPMenu Object - +/* + Initializes the menu with a specified title. + @param aTile the menu title + @return the initialized menu +*/ - (id)initWithTitle:(CPString)aTitle { self = [super init]; @@ -155,7 +162,11 @@ var _CPMenuBarVisible = NO, } // Setting Up Menu Commands - +/* + Inserts a menu item at the specified index. + @param aMenuItem the item to insert + @param anIndex the index in the menu to insert the item. +*/ - (void)insertItem:(CPMenuItem)aMenuItem atIndex:(unsigned)anIndex { var menu = [aMenuItem menu]; @@ -176,6 +187,14 @@ var _CPMenuBarVisible = NO, } +/* + Creates and inserts a new menu item with the specified attributes. + @param aTitle the title of the menu item + @param anAction the action initiated when the user selects the item + @param aKeyEquivalent the keyboard shortcut for the item + @param anIndex the index location in the menu for the new item + @return the new menu item +*/ - (CPMenuItem)insertItemWithTitle:(CPString)aTitle action:(SEL)anAction keyEquivalent:(CPString)aKeyEquivalent atIndex:(unsigned)anIndex { var item = [[CPMenuItem alloc] initWithTitle:aTitle action:anAction keyEquivalent:aKeyEquivalent]; @@ -185,21 +204,41 @@ var _CPMenuBarVisible = NO, return item; } +/* + Adds a menu item at the end of the menu. + @param aMenuItem the menu item to add +*/ - (void)addItem:(CPMenuItem)aMenuItem { [self insertItem:aMenuItem atIndex:[_items count]]; } +/* + Creates and adds a menu item with the specified attributes + at the end of the menu. + @param aTitle the title of the new menu item + @param anAction the action initiated when the user selects the item + @param aKeyEquivalent the keyboard shortcut for the menu item + @return the new menu item +*/ - (CPMenuItem)addItemWithTitle:(CPString)aTitle action:(SEL)anAction keyEquivalent:(CPString)aKeyEquivalent { return [self insertItemWithTitle:aTitle action:anAction keyEquivalent:aKeyEquivalent atIndex:[_items count]]; } +/* + Removes the specified item from the menu + @param aMenuItem the item to remove +*/ - (void)removeItem:(CPMenuItem)aMenuItem { [self removeItemAtIndex:[_items indexOfObjectIdenticalTo:aMenuItem]]; } +/* + Removes the item at the specified index from the menu + @param anIndex the index of the item to remove +*/ - (void)removeItemAtIndex:(unsigned)anIndex { if (anIndex < 0 || anIndex >= _items.length) @@ -214,6 +253,10 @@ var _CPMenuBarVisible = NO, userInfo:[CPDictionary dictionaryWithObject:anIndex forKey:@"CPMenuItemIndex"]]; } +/* + Called when a menu item has visually changed. + @param aMenuItem the item that changed +*/ - (void)itemChanged:(CPMenuItem)aMenuItem { if ([aMenuItem menu] != self) @@ -226,7 +269,11 @@ var _CPMenuBarVisible = NO, } // Finding Menu Items - +/* + Returns the menu item with the specified tag + @param the tag of the desired menu item + @return the menu item or nil if a match was not found +*/ - (CPMenuItem)menuWithTag:(int)aTag { var index = [self indexOfItemWithTag:aTag]; @@ -237,6 +284,11 @@ var _CPMenuBarVisible = NO, return _items[index]; } +/* + Returns the menu item with the specified title. + @param aTitle the title of the menu item + @return the menu item or nil if a match was not found +*/ - (CPMenuItem)menuWithTitle:(CPString)aTitle { var index = [self indexOfItemWithTitle:aTitle]; @@ -247,23 +299,37 @@ var _CPMenuBarVisible = NO, return _items[index]; } +/* + Returns the menu item at the specified index + @param anIndex the index of the requested item +*/ - (CPMenuItem)itemAtIndex:(int)anIndex { return [_items objectAtIndex:anIndex]; } +/* + Returns the number of menu items in the menu +*/ - (unsigned)numberOfItems { return [_items count]; } +/* + Returns the array of menu items backing this menu +*/ - (CPArray)itemArray { return _items; } // Finding Indices of Menu Items - +/* + Returns the index of the specified menu item + @param aMenuItem the item to find the index for + @return the item index or CPNotFound +*/ - (int)indexOfItem:(CPMenuItem)aMenuItem { if ([aMenuItem menu] != self) @@ -272,6 +338,11 @@ var _CPMenuBarVisible = NO, return [_items indexOfObjectIdenticalTo:aMenuItem]; } +/* + Returns the index of the item with the specified title. + @param aTitle the desired title to match + @return the index of the item or CPNotFound +*/ - (int)indexOfItemWithTitle:(CPString)aTitle { var index = 0, @@ -284,6 +355,11 @@ var _CPMenuBarVisible = NO, return CPNotFound; } +/* + Returns the index of the item with the specified tag + @param aTag the desired tag to match + @return the index of the item or CPNotFound +*/ - (int)indexOfItemWithTag:(int)aTag { var index = 0, @@ -296,6 +372,12 @@ var _CPMenuBarVisible = NO, return CPNotFound; } +/* + Returns the index of the item with the specified target and action. + @param aTarget the target of the desired menu item + @param anAction the action of the desired menu item + @return the index of the item or CPNotFound +*/ - (int)indexOfItemWithTarget:(id)aTarget andAction:(SEL)anAction { var index = 0, @@ -312,6 +394,11 @@ var _CPMenuBarVisible = NO, return CPNotFound; } +/* + Returns the index of the menu item with the specified represented object. + @param anObject the represented object of the desired item + @return the index of the item or CPNotFound +*/ - (int)indexOfItemWithRepresentedObject:(id)anObject { var index = 0, @@ -324,6 +411,11 @@ var _CPMenuBarVisible = NO, return CPNotFound; } +/* + Returns the index of the item with the specified submenu. + @param the submenu of the desired menu item + @return the index of the item or CPNotFound +*/ - (int)indexOfItemWithSubmenu:(CPMenu)aMenu { var index = 0, @@ -337,7 +429,11 @@ var _CPMenuBarVisible = NO, } // Managing Submenus - +/* + Sets a submenu for a menu item + @param aMenu the submenu + @param aMenuItem the menu item to set the submenu on +*/ - (void)setSubmenu:(CPMenu)aMenu forItem:(CPMenuItem)aMenuItem { [aMenuItem setTarget:aMenuItem]; @@ -346,65 +442,106 @@ var _CPMenuBarVisible = NO, [aMenuItem setSubmenu:aMenu]; } +/* + The action method of menu items that open submenus. + The default implementation does nothing, but it may + be subclassed to provide different behavior. + @param aSender the object that sent the message +*/ - (void)submenuAction:(id)aSender { } +/* + Returns the attaced menu, or nil if there isn't one. +*/ - (CPMenu)attachedMenu { return _attachedMenu; } +/* + Returns YES if the menu is attached to another menu. +*/ - (BOOL)isAttached { return _isAttached; } +/* + Not yet implemented +*/ - (CGPoint)locationOfSubmenu:(CPMenu)aMenu { // FIXME: IMPLEMENT. } +/* + Returns the super menu or nil if there is none. +*/ - (CPMenu)supermenu { return _supermenu; } +/* + Sets the super menu. + @param aMenu the new super menu +*/ - (void)setSupermenu:(CPMenu)aMenu { _supermenu = aMenu; } +/* + If there are two instances of this menu visible, return NO. + Otherwise, return YES if we are a detached menu and visible. +*/ - (BOOL)isTornOff { return !_supermenu /* || offscreen(?) */ || self == [CPApp mainMenu]; } // Enabling and Disabling Menu Items - +/* + Sets whether the menu automatically enables menu items. + @param aFlag YES sets the menu to automatically enable items. +*/ - (void)setAutoenablesItems:(BOOL)aFlag { _autoenablesItems = aFlag; } +/* + Returns YES if the menu auto enables items. +*/ - (BOOL)autoenablesItems { return _autoenablesItems; } +/* + Not implemented. +*/ - (void)update { } // Managing the Title - +/* + Sets the menu title. + @param the new title +*/ - (void)setTitle:(CPString)aTitle { _title = aTitle; } +/* + Returns the menu title +*/ - (CPString)title { return _title; @@ -470,20 +607,29 @@ var _CPMenuBarVisible = NO, } // Managing Display of State Column - +/* + Sets whether to show the state column + @param shouldShowStateColumn YES shows the state column +*/ - (void)setShowsStateColumn:(BOOL)shouldShowStateColumn { _showsStateColumn = shouldShowStateColumn; } +/* + Returns YES if the menu shows the state column +*/ - (BOOL)showsStateColumn { return _showsStateColumn; } // Handling Highlighting - -- (BOOL)highlightedItem +/* + Returns the currently highlighted menu item. + @return the highlighted menu item or nil if no item is currently highlighted +*/ +- (CPMenuItem)highlightedItem { return _highlightedIndex >= 0 ? _items[_highlightedIndex] : nil; } @@ -501,17 +647,26 @@ var _CPMenuBarVisible = NO, } // Handling Tracking - +/* + Cancels tracking. +*/ - (void)cancelTracking { [_menuWindow cancelTracking]; } +/* @ignore */ - (void)_setMenuWindow:(_CPMenuWindow)aMenuWindow { _menuWindow = aMenuWindow; } +/* + Initiates the action of the menu item that + has a keyboard shortcut equivalent to anEvent + @param anEvent the keyboard event + @return YES if it was handled. +*/ - (BOOL)performKeyEquivalent:(CPEvent)anEvent { if (_autoenablesItems) @@ -548,7 +703,10 @@ var _CPMenuBarVisible = NO, } // Simulating Mouse Clicks - +/* + Sends the action of the menu item at the specified index. + @param anIndex the index of the item +*/ - (void)performActionForItemAtIndex:(unsigned)anIndex { var item = _items[anIndex]; @@ -557,12 +715,17 @@ var _CPMenuBarVisible = NO, } // - +/* + @ignore +*/ - (BOOL)_itemIsHighlighted:(CPMenuItem)aMenuItem { return _items[_highlightedIndex] == aMenuItem; } +/* + @ignore +*/ - (void)_highlightItemAtIndex:(int)anIndex { var previousHighlightedIndex = _highlightedIndex; @@ -584,6 +747,11 @@ var CPMenuTitleKey = @"CPMenuTitleKey", @implementation CPMenu (CPCoding) +/* + Initializes the menu with data from the specified coder. + @param aCoder the coder from which to read the data + @return the initialized menu +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super init]; @@ -597,6 +765,10 @@ var CPMenuTitleKey = @"CPMenuTitleKey", return self; } +/* + Encodes the data of the menu into a coder + @param aCoder the coder to which the data will be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeObject:_title forKey:CPMenuTitleKey]; @@ -627,6 +799,9 @@ var STICKY_TIME_INTERVAL = 500, SCROLL_INDICATOR_HEIGHT = 16.0; +/* + @ignore +*/ @implementation _CPMenuWindow : CPWindow { _CPMenuView _menuView; @@ -1008,6 +1183,9 @@ var STICKY_TIME_INTERVAL = 500, @end +/* + @ignore +*/ @implementation _CPMenuView : CPView { CPArray _menuItemViews; diff --git a/AppKit/CPMenuItem.j b/AppKit/CPMenuItem.j index 68050294e1..0e4ffdf00e 100644 --- a/AppKit/CPMenuItem.j +++ b/AppKit/CPMenuItem.j @@ -28,7 +28,11 @@ import import import - +/* + A CPMenuItem is added to a CPMenu. + It has an action and a target for that action to be sent to + whenever the item is 'activated'. +*/ @implementation CPMenuItem : CPObject { CPString _title; @@ -69,6 +73,13 @@ import _CPMenuItemView _menuItemView; } +/* + Initializes the menu item with a title, action, and keyboard equivalent. + @param aTitle the menu item's title + @param anAction the action that gets triggered when the item is selected + @param aKeyEquivalent the keyboard shortcut for the item + @return the initialized menu item +*/ - (id)initWithTitle:(CPString)aTitle action:(SEL)anAction keyEquivalent:(CPString)aKeyEquivalent { self = [super init]; @@ -92,7 +103,10 @@ import } // Enabling a Menu Item - +/* + Sets whether the menu item is enabled or not + @param isEnabled YES enables the item. NO disables it. +*/ - (void)setEnabled:(BOOL)isEnabled { if ([_menu autoenablesItems]) @@ -105,23 +119,35 @@ import [_menu itemChanged:self]; } +/* + Returns YES if the item is enabled. +*/ - (BOOL)isEnabled { return _isEnabled; } // Managing Hidden Status - +/* + Sets whether the item should be hidden. A hidden item can not be triggered by keyboard shortcuts. + @param isHidden YES hides the item. NO reveals it. +*/ - (void)setHidden:(BOOL)isHidden { _isHidden = isHidden; } +/* + Returns YES if the item is hidden. +*/ - (BOOL)isHidden { return _isHidden; } +/* + Returns YES if the item is hidden or if one of it's supermenus is hidden. +*/ - (BOOL)isHiddenOrHasHiddenAncestor { if (_isHidden) @@ -134,29 +160,45 @@ import } // Managing Target and Action - +/* + Sets the menu item's action target. + @param aTarget the target for the action +*/ - (void)setTarget:(id)aTarget { _target = aTarget; } +/* + Returns the item's action target +*/ - (id)target { return _target; } +/* + Sets the action that gets sent to the item's target when triggered. + @param anAction the action to send +*/ - (void)setAction:(SEL)anAction { _action = anAction; } +/* + Returns the item's action. +*/ - (SEL)action { return _action; } // Managing the Title - +/* + Sets the item's title. + @param aTitle the item's new title +*/ - (void)setTitle:(CPString)aTitle { _mnemonicLocation = CPNotFound; @@ -171,11 +213,18 @@ import [_menu itemChanged:self]; } +/* + Returns the menu item's title. +*/ - (CPString)title { return _title; } +/* + Sets the font for the text of this menu item + @param aFont the font for the menu item +*/ - (void)setFont:(CPFont)aFont { if (_font == aFont) @@ -188,6 +237,9 @@ import [_menuItemView setDirty]; } +/* + Returns the menu item's font +*/ - (CPFont)font { return _font; @@ -204,17 +256,31 @@ import */ // Managing the Tag - +/* + Sets the menu item's tag + @param aTag the tag for the item +*/ - (void)setTag:(int)aTag { _tag = aTag; } +/* + Returns the item's tag +*/ - (int)tag { return _tag; } +/* + Sets the state of the menu item. Possible states are: +

+CPMixedState
+CPOnState
+CPOffState
+
+*/ - (void)setState:(int)aState { if (_state == aState) @@ -227,13 +293,24 @@ import [_menuItemView setDirty]; } +/* + Returns the menu item's current state. Possible states are: +
+CPMixedState
+CPOnState
+CPOffState
+
+*/ - (int)state { return _state; } // Managing the Image - +/* + Sets the menu item's image + @param anImage the menu item's image +*/ - (void)setImage:(CPImage)anImage { if (_image == anImage) @@ -246,21 +323,36 @@ import [_menu itemChanged:self]; } +/* + Returns the menu item's image +*/ - (CPImage)image { return _image; } +/* + Sets the menu item's alternate image + @param anImage the menu item's alternate image +*/ - (void)setAlternateImage:(CPImage)anImage { _alternateImage = anImage; } +/* + Returns the menu item's alternate image +*/ - (CPImage)alternateImage { return _alternateImage; } +/* + Sets the image that is shown when the + menu item is in the 'on' state. + @param anImage the image to show +*/ - (void)setOnStateImage:(CPImage)anImage { if (_onStateImage == anImage) @@ -270,11 +362,18 @@ import [_menu itemChanged:self]; } +/* + Returns the image shown when the menu item is in the 'on' state. +*/ - (CPImage)onStateImage { return _onStateImage; } +/* + Sets the image that is shown when the menu item is in the 'off' state. + @param anImage the image to show +*/ - (void)setOffStateImage:(CPImage)anImage { if (_offStateImage == anImage) @@ -284,11 +383,18 @@ import [_menu itemChanged:self]; } +/* + Returns the image shown when the menu item is in the 'off' state. +*/ - (CPImage)offStateImage { return _offStateImage; } +/* + Sets the image that is shown when the menu item is in the 'mixed' state. + @param anImage the image to show +*/ - (void)setMixedStateImage:(CPImage)anImage { if (_mixedStateImage == anImage) @@ -298,13 +404,20 @@ import [_menu itemChanged:self]; } +/* + Returns the image shown when the menu item is + in the 'mixed' state. +*/ - (CPImage)mixedStateImage { return _mixedStateImage; } // Managing Subemenus - +/* + Sets the submenu for this item + @param aMenu the submenu +*/ - (void)setSubmenu:(CPMenu)aMenu { var supermenu = [_submenu supermenu]; @@ -324,11 +437,17 @@ import [_menu itemChanged:self]; } +/* + Returns the submenu of the item. nil if there is no submenu. +*/ - (CPMenu)submenu { return _submenu; } +/* + Returns YES if the menu item has a submenu. +*/ - (BOOL)hasSubmenu { return _submenu ? YES : NO; @@ -336,23 +455,35 @@ import // Getting a Separator Item +/* + Returns a new menu item separator. +*/ + (CPMenuItem)separatorItem { return [[_CPMenuItemSeparator alloc] init]; } +/* + Returns YES if the menu item is a separator. +*/ - (BOOL)isSeparatorItem { return NO; } // Managing the Owning Menu - +/* + Set the container menu of this item. + @param aMenu the item's container menu +*/ - (void)setMenu:(CPMenu)aMenu { _menu = aMenu; } +/* + Returns the container menu of this item +*/ - (CPMenu)menu { return _menu; @@ -360,38 +491,76 @@ import // +/* + Sets the keyboard shortcut for this menu item + @param aString the keyboard shortcut +*/ - (void)setKeyEquivalent:(CPString)aString { _keyEquivalent = aString; } +/* + Returns the keyboard shortcut for this menu item +*/ - (CPString)keyEquivalent { return _keyEquivalent; } +/* + Sets the modifier mask used for the item's keyboard shortcut. + Can be a combination of: +
+CPShiftKeyMask
+CPAlternateKeyMask
+CPCommandKeyMask
+CPControlKeyMask
+
+*/ - (void)setKeyEquivalentModifierMask:(unsigned)aMask { _keyEquivalentModifierMask = aMask; } +/* + Returns the item's keyboard shortcut modifier mask. + Can be a combination of: +
+CPShiftKeyMask
+CPAlternateKeyMask
+CPCommandKeyMask
+CPControlKeyMask
+
+*/ - (unsigned)keyEquivalentModifierMask { return _keyEquivalentModifierMask; } // Managing Mnemonics - +/* + Sets the index of the mnemonic character in the title. The character + will be underlined and is used as a shortcut for navigation. + @param aLocation the index of the character in the title +*/ - (void)setMnemonicLocation:(unsigned)aLocation { _mnemonicLocation = aLocation; } +/* + Returns the index of the mnemonic character in the title. +*/ - (unsigned)mnemonicLocation { return _mnemonicLocation; } +/* + Sets the title of the menu item and the mnemonic character. The mnemonic chracter should be preceded by an '&'. + @param aTitle the title string with a denoted mnemonic +*/ - (void)setTitleWithMnemonicLocation:(CPString)aTitle { var location = [aTitle rangeOfString:@"&"].location; @@ -405,6 +574,9 @@ import } } +/* + Returns the menu items mnemonic character +*/ - (CPString)mnemonic { return _mnemonicLocation == CPNotFound ? @"" : [_title characterAtIndex:_mnemonicLocation]; @@ -412,11 +584,18 @@ import // Managing Alternates +/* + Sets whether this item is an alternate for the previous menu item. + @param isAlternate YES denotes that this menu item is an alternate +*/ - (void)setAlternate:(BOOL)isAlternate { _isAlternate = isAlternate; } +/* + Returns YES if the menu item is an alternate for the previous item. +*/ - (BOOL)isAlternate { return _isAlternate; @@ -424,25 +603,40 @@ import // Managing Indentation Levels +/* + Sets the indentation level of the menu item. Must be a value between 0 and 15 (inclusive). + @param aLevel the item's new indentation level + @throws CPInvalidArgumentException if aLevel is less than 0 +*/ - (void)setIndentationLevel:(unsigned)aLevel { if (aLevel < 0) - alert("bad"); + [CPException raise:CPInvalidArgumentException reason:"setIndentationLevel: argument must be greater than 0."]; _indentationLevel = MIN(15, aLevel); } +/* + Returns the menu item's indentation level. This is a value between 0 and 15 (inclusive). +*/ - (unsigned)indentationLevel { return _indentationLevel; } // Managing Tool Tips +/* + Sets the tooltip for the menu item. + @param aToolTip the tool tip for the item +*/ - (void)setToolTip:(CPString)aToolTip { _toolTip = aToolTip; } +/* + Returns the item's tooltip +*/ - (CPString)toolTip { return _toolTip; @@ -450,11 +644,18 @@ import // Representing an Object +/* + Sets the menu item's represented object. This is a kind of tag for the developer. Not a UI feature. + @param anObject the represented object +*/ - (void)setRepresentedObject:(id)anObject { _representedObject = anObject; } +/* + Returns the item's represented object. +*/ - (id)representedObject { return _representedObject; @@ -462,6 +663,10 @@ import // Managing the View +/* + Sets the view for the menu item + @param aView the menu's item's view +*/ - (void)setView:(CPView)aView { if (_view == aView) @@ -474,6 +679,9 @@ import [_menu itemChanged:self]; } +/* + Returns the menu item's view +*/ - (CPView)view { return _view; @@ -481,6 +689,9 @@ import // Getting Highlighted Status +/* + Returns YES if the menu item is highlighted. +*/ - (BOOL)isHighlighted { return [[self menu] highlightedItem] == self; @@ -488,6 +699,9 @@ import // +/* + @ignore +*/ - (id)_menuItemView { if (!_menuItemView) @@ -498,6 +712,7 @@ import @end +/* @ignore */ @implementation _CPMenuItemSeparator : CPMenuItem { } @@ -530,7 +745,11 @@ var CPMenuItemTitleKey = @"CPMenuItemTitleKey", CPMenuItemRepresentedObjectKey = @"CPMenuItemRepresentedObjectKey"; @implementation CPMenuItem (CPCoding) - +/* + Initializes the menu item from a coder. + @param aCoder the coder from which to initialize + @return the initialized menu item +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super init]; @@ -577,6 +796,10 @@ var CPMenuItemTitleKey = @"CPMenuItemTitleKey", return self; } +/* + Writes the menu item out to a coder. + @param aCoder the coder to write the menu item out to +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeObject:_title forKey:CPMenuItemTitleKey]; @@ -611,6 +834,9 @@ var _CPMenuItemSelectionColor = nil, _CPMenuItemViewMenuBarArrowImage = nil, _CPMenuItemViewMenuBarArrowActivatedImage = nil; +/* + @ignore +*/ @implementation _CPMenuItemView : CPView { CPMenuItem _menuItem; diff --git a/AppKit/CPOutlineView.j b/AppKit/CPOutlineView.j index a19b008a8f..7c55bfa685 100644 --- a/AppKit/CPOutlineView.j +++ b/AppKit/CPOutlineView.j @@ -22,6 +22,12 @@ import "CPTableView.j" +/* + @ignore + This class is a subclass of CPTableView which provides the user with a way to display + tree structured data in an outline format. It is particularly useful for displaying hierarchical data + such as a class inheritance tree or any other set of relationships. +*/ @implementation CPOutlineView : CPTableView { @@ -42,13 +48,34 @@ import "CPTableView.j" return self; } +/* + @ignore + Sets the outline's data source. The data source must implement the following methods: +
+- (id)outlineView:(CPOutlineView)outlineView child:(int)index ofItem:(id)item
+- (BOOL)outlineView:(CPOutlineView)outlineView isItemExpandable:(id)item
+- (int)outlineView:(CPOutlineView)outlineView numberOfChildrenOfItem:(id)item
+- (id)outlineView:(CPOutlineView)outlineView objectValueForTableColumn:(CPTableColumn)tableColumn byItem:(id)item
+
+ @param aDataSource the outline's data source + @throws CPInternalInconsistencyException if the data source does not implement all the required methods +*/ - (void)setDataSource:(id)aDataSource { + if (![aDataSource respondsToSelector:@selector(outlineView:child:ofItem)]) + [CPException raise:CPInternalInconsistencyException reason:"Data source must implement 'outlineView:child:ofItem'"]; + if (![aDataSource respondsToSelector:@selector(outlineView:isItemExpandable)]) + [CPException raise:CPInternalInconsistencyException reason:"Data source must implement 'outlineView:isItemExpandable'"]; + if (![aDataSource respondsToSelector:@selector(outlineView:numberOfChildrenOfItem)]) + [CPException raise:CPInternalInconsistencyException reason:"Data source must implement 'outlineView:numberOfChildrenOfItem'"]; + if (![aDataSource respondsToSelector:@selector(outlineView:objectValueForTableColumn:byItem)]) + [CPException raise:CPInternalInconsistencyException reason:"Data source must implement 'outlineView:objectValueForTableColumn:byItem'"]; + _outlineDataSource = aDataSource; [self reloadData]; } - +/* @ignore */ - (void)reloadData { _numberOfVisibleItems = [_outlineDataSource outlineView:self numberOfChildrenOfItem:nil]; @@ -64,13 +91,19 @@ import "CPTableView.j" @end +/* @ignore */ @implementation CPOutlineView (CPTableDataSource) +/* + FIXME +*/ +/* @ignore */ - (void)numberOfRowsInTableView:(CPTableView)aTableView { return _numberOfVisibleItems; } +/* @ignore */ - (void)tableView:(CPTableView)aTableView objectValueForTableColumn:(CPTableColumn)aTableColumn row:(int)aRowIndex { return [_outlineDataSource outlineView:self objectValueForTableColumn:aTableColumn byItem:_itemsByRow[aRowIndex]]; diff --git a/AppKit/CPPanel.j b/AppKit/CPPanel.j index 345acf5a4e..282b24530c 100644 --- a/AppKit/CPPanel.j +++ b/AppKit/CPPanel.j @@ -26,27 +26,60 @@ import "CPWindow.j" CPOKButton = 1; CPCancelButton = 0; +/* + The CPPanel class defines objects that manage the panels of the Cappuccino user interface. A panel is a window that serves an auxiliary function within an application. It generally displays controls that the user can act on to give instructions to the application or to modify the contents of a standard window.

+ +

Panels behave differently from standard windows in only a small number of ways, but the ways are important to the user interface:

+ +
    +
  • Panels can assume key window status but not main window status. (The key window receives keyboard events. The main window is the primary focus of user actions; it might contain the document the user is working on, for example.)
    • +
+ +

To aid in their auxiliary role, panels can be assigned special behaviors:

+ +
    +
  • A panel can be precluded from becoming the key window until the user makes a selection (makes some view in the panel the first responder) indicating an intention to begin typing. This prevents key window status from shifting to the panel unnecessarily.
    • +
  • Palettes and similar panels can be made to float above standard windows and other panels. This prevents them from being covered and keeps them readily available to the user.
    • +
  • A panel can be made to work even when there's an attention panel on-screen. This permits actions within the panel to affect the attention panel.
    • +
+*/ @implementation CPPanel : CPWindow { BOOL _becomesKeyOnlyIfNeeded; BOOL _worksWhenModal; } +/* + Returns YES if the receiver is a floating panel (like a palette). +*/ - (BOOL)isFloatingPanel { return [self level] == CPFloatingWindowLevel; } +/* + Sets the receiver to be a floating panel. YES + makes the window a floating panel. NO makes it a normal window. + @param isFloatingPanel specifies whether to make it floating +*/ - (void)setFloatingPanel:(BOOL)isFloatingPanel { [self setLevel:isFloatingPanel ? CPFloatingWindowLevel : CPNormalWindowLevel]; } +/* + Returns YES if the window only becomes key + if needed. NO means it behaves just like other windows. +*/ - (BOOL)becomesKeyOnlyIfNeeded { return _becomesKeyOnlyIfNeeded; } +/* + Sets whether the the window becomes key only if needed. + @param shouldBecomeKeyOnlyIfNeeded YES makes the window become key only if needed +*/ - (void)setBecomesKeyOnlyIfNeeded:(BOOL)shouldBecomeKeyOnlyIfNeeded { _becomesKeyOnlyIfNeeded = shouldBecomeKeyOnlyIfNeeded @@ -57,6 +90,10 @@ CPCancelButton = 0; return _worksWhenModal; } +/* + Sets whether this window can receive input while another window is running modally. + @param shouldWorkWhenModal whether to receive input while another window is modal +*/ - (void)setWorksWhenModal:(BOOL)shouldWorkWhenModal { _worksWhenModal = shouldWorkWhenModal; diff --git a/AppKit/CPPasteboard.j b/AppKit/CPPasteboard.j index 80283397fe..6e4717936a 100644 --- a/AppKit/CPPasteboard.j +++ b/AppKit/CPPasteboard.j @@ -42,6 +42,9 @@ CPImagePboardType = @"CPImagePboardType"; var CPPasteboards = nil; +/* + CPPasteBoard is the object responsible for cut/copy/paste and drag&drop operations. +*/ @implementation CPPasteboard : CPObject { CPArray _types; @@ -52,6 +55,9 @@ var CPPasteboards = nil; CPString _stateUID; } +/* + @ignore +*/ + (void)initialize { if (self != [CPPasteboard class]) @@ -62,11 +68,19 @@ var CPPasteboards = nil; CPPasteboards = [CPDictionary dictionary]; } +/* + Returns a new instance of a pasteboard +*/ + (id)generalPasteboard { return [CPPasteboard pasteboardWithName:CPGeneralPboard]; } +/* + Returns a pasteboard with the specified name. If the pasteboard doesn't exist, it will be created. + @param aName the name of the pasteboard + @return the requested pasteboard +*/ + (id)pasteboardWithName:(CPString)aName { var pasteboard = [CPPasteboards objectForKey:aName]; @@ -80,6 +94,7 @@ var CPPasteboards = nil; return pasteboard; } +/* @ignore */ - (id)_initWithName:(CPString)aName { self = [super init]; @@ -98,6 +113,12 @@ var CPPasteboards = nil; return self; } +/* + Adds supported data types to the pasteboard + @param types the data types + @param anOwner the object that contains the data types + @return the pasteboard's change count +*/ - (unsigned)addTypes:(CPArray)types owner:(id)anOwner { var i = 0, @@ -119,6 +140,12 @@ var CPPasteboards = nil; return ++_changeCount; } +/* + Sets the data types that this pasteboard will contain. + @param type the data types it will support + @param anOwner the object that contains the the data + @return the pasteboard's change count +*/ - (unsigned)declareTypes:(CPArray)types owner:(id)anOwner { [_types setArray:types]; @@ -134,6 +161,12 @@ var CPPasteboards = nil; return ++_changeCount; } +/* + Sets the pasteboard data for the specified type + @param aData the data + @param aType the data type being set + @return YES if the data was successfully written to the pasteboard +*/ - (BOOL)setData:(CPData)aData forType:(CPString)aType { [_provided setObject:aData forKey:aType]; @@ -141,35 +174,62 @@ var CPPasteboards = nil; return YES; } +/* + Writes the specified property list as data for the specified type + @param aPropertyList the property list to write + @param aType the data type + @return YES if the property list was successfully written to the pasteboard +*/ - (BOOL)setPropertyList:(id)aPropertyList forType:(CPString)aType { return [self setData:[CPPropertyListSerialization dataFromPropertyList:aPropertyList format:CPPropertyListXMLFormat_v1_0 errorDescription:nil] forType:aType]; } +/* + Sets the specified string as data for the specified type + @param aString the string to write + @param aType the data type + @return YES if the string was successfully written to the pasteboard +*/ - (void)setString:(CPString)aString forType:(CPString)aType { return [self setPropertyList:aString forType:aType]; } // Determining Types - +/* + Checks the pasteboard's types for a match with the types listen in the specified array. The array should + be ordered by the requestor's most preferred data type first. + @param anArray an array of requested types ordered by preference + @return the highest match with the pasteboard's supported types or nil if no match was found +*/ - (CPString)availableTypeFromArray:(CPArray)anArray { return [_types firstObjectCommonWithArray:anArray]; } +/* + Returns the pasteboards supported types +*/ - (CPArray)types { return _types; } // Reading data - +/* + Returns the number of changes that have occurred to this pasteboard +*/ - (unsigned)changeCount { return _changeCount; } +/* + Returns the pasteboard data for the specified data type + @param aType the requested data type + @return the requested data or nil if the data doesn't exist +*/ - (CPData)dataForType:(CPString)aType { var data = [_provided objectForKey:aType]; @@ -191,6 +251,11 @@ var CPPasteboards = nil; return nil; } +/* + Returns the property list for the specified data type + @param aType the requested data type + @return the property list or nil if the list was not found +*/ - (id)propertyListForType:(CPString)aType { var data = [self dataForType:aType]; @@ -201,11 +266,17 @@ var CPPasteboards = nil; return nil; } +/* + Returns the string for the specified data type + @param aType the requested data type + @return the string or nil if the string was not found +*/ - (CPString)stringForType:(CPString)aType { return [self propertyListForType:aType]; } +/* @ignore */ - (CPString)_generateStateUID { var bits = 32; @@ -218,6 +289,7 @@ var CPPasteboards = nil; return _stateUID; } +/* @ignore */ - (CPString)_stateUID { return _stateUID; diff --git a/AppKit/CPPopUpButton.j b/AppKit/CPPopUpButton.j index 2c1898990d..a8b4a83c45 100644 --- a/AppKit/CPPopUpButton.j +++ b/AppKit/CPPopUpButton.j @@ -30,6 +30,9 @@ var VISIBLE_MARGIN = 7.0; var CPPopUpButtonArrowsImage = nil; +/* + A CPPopUpButton contains a pop-up menu of items that a user can select from. +*/ @implementation CPPopUpButton : CPButton { BOOL _pullsDown; @@ -41,6 +44,12 @@ var CPPopUpButtonArrowsImage = nil; CPMenu _menu; } +/* + Initializes the pop-up button to the specified size. + @param aFrame the size for the button + @param shouldPullDown YES makes this a pull-down menu, NO makes it a pop-up menu. + @return the initialized pop-up button +*/ - (id)initWithFrame:(CGRect)aFrame pullsDown:(BOOL)shouldPullDown { self = [super initWithFrame:aFrame]; @@ -96,6 +105,11 @@ var CPPopUpButtonArrowsImage = nil; // Setting the Type of Menu +/* + Specifies whether the object is a pull-down or a pop-up menu. + @param shouldPullDown YES makes the pop-up button + a pull-down menu. NO makes it a pop-up menu. +*/ - (void)setPullsDown:(BOOL)shouldPullDown { if (_pullsDown == shouldPullDown) @@ -113,18 +127,28 @@ var CPPopUpButtonArrowsImage = nil; [self synchronizeTitleAndSelectedItem]; } +/* + Returns YES if the button is a pull-down menu. NO if the button is a pop-up menu. +*/ - (BOOL)pullsDown { return _pullsDown; } // Inserting and Deleting Items - +/* + Adds a new menu item with the specified title. + @param the new menu item's tite +*/ - (void)addItemWithTitle:(CPString)aTitle { [_menu addItemWithTitle:aTitle action:NULL keyEquivalent:NULL]; } +/* + Adds multiple new menu items with the titles specified in the provided array. + @param titles an arry of names for the new items +*/ - (void)addItemsWithTitles:(CPArray)titles { var index = 0, @@ -134,6 +158,11 @@ var CPPopUpButtonArrowsImage = nil; [self addItemWithTitle:titles[index]]; } +/* + Inserts a new item with the specified title and index location. + @param aTitle the new itme's title + @param anIndex the item's index in the menu +*/ - (void)insertItemWithTitle:(CPString)aTitle atIndex:(int)anIndex { var items = [self itemArray], @@ -146,6 +175,9 @@ var CPPopUpButtonArrowsImage = nil; [_menu insertItemWithTitle:aTitle action:NULL keyEquivalent:NULL atIndex:anIndex]; } +/* + Removes all menu items from the pop-up button's menu +*/ - (void)removeAllItems { var count = [_menu numberOfItems]; @@ -154,12 +186,20 @@ var CPPopUpButtonArrowsImage = nil; [_menu removeItemAtIndex:0]; } +/* + Removes a menu item with the specified title from the button. + @param aTitle the title of the item to remove +*/ - (void)removeItemWithTitle:(CPString)aTitle { [self removeItemAtIndex:[self indexOfItemWithTitle:aTitle]]; [self synchronizeTitleAndSelectedItem]; } +/* + Removes the menu item at the specified index + @param anIndex the index of the item to remove +*/ - (void)removeItemAtIndex:(int)anIndex { [_menu removeItemAtIndex:anIndex]; @@ -167,7 +207,9 @@ var CPPopUpButtonArrowsImage = nil; } // Getting the User's Selection - +/* + Returns the selected item or nil if no item is selected. +*/ - (CPMenuItem)selectedItem { if (_selectedIndex < 0) @@ -176,29 +218,45 @@ var CPPopUpButtonArrowsImage = nil; return [_menu itemAtIndex:_selectedIndex]; } +/* + Returns the title of the selected item or nil if no item is selected. +*/ - (CPString)titleOfSelectedItem { return [[self selectedItem] title]; } +/* + Returns the index of the selected item. If no item is selected, it returns CPNotFound. +*/ - (int)indexOfSelectedItem { return _selectedIndex; } // For us, CPNumber is toll-free bridged to Number, so just return the selected index. +/* + Returns the selected item's index. If no item is selected, it returns CPNotFound. +*/ - (id)objectValue { return _selectedIndex; } // Setting the Current Selection - +/* + Selects the specified menu item. + @param aMenuItem the item to select +*/ - (void)selectItem:(CPMenuItem)aMenuItem { [self selectItemAtIndex:[self indexOfItem:aMenuItem]]; } +/* + Selects the item at the specified index + @param anIndex the index of the item to select +*/ - (void)selectItemAtIndex:(int)anIndex { if (_selectedIndex == anIndex) @@ -215,28 +273,45 @@ var CPPopUpButtonArrowsImage = nil; [self synchronizeTitleAndSelectedItem]; } +/* + Selects the menu item with the specified tag + @param the tag of the item to select +*/ - (void)selectItemWithTag:(int)aTag { [self selectItemAtIndex:[self indexOfItemWithTag:aTag]]; } +/* + Selects the item with the specified title + @param the title of the item to select +*/ - (void)selectItemWithTitle:(CPString)aTitle { [self selectItemAtIndex:[self indexOfItemWithTitle:aTitle]]; } +/* + Sets the object for the selected item. If no item is selected, then this method has no effect. + @param the object set for the selected item +*/ - (void)setObjectValue:(id)aValue { [self selectItemAtIndex:[aValue intValue]]; } // Getting Menu Items - +/* + Returns the button's menu of items. +*/ - (CPMenu)menu { return _menu; } +/* + Sets the menu for the button +*/ - (void)setMenu:(CPMenu)aMenu { if (_menu == aMenu) @@ -291,26 +366,43 @@ var CPPopUpButtonArrowsImage = nil; [self synchronizeTitleAndSelectedItem]; } +/* + Returns a count of the number of items in the button's menu. +*/ - (int)numberOfItems { return [_menu numberOfItems]; } +/* + Returns an array of the items in the menu +*/ - (CPArray)itemArray { return [_menu itemArray]; } +/* + Returns the item at the specified index or nil if the item does not exist. + @param anIndex the index of the item to obtain +*/ - (CPMenuItem)itemAtIndex:(unsigned)anIndex { return [_menu itemAtIndex:anIndex]; } +/* + Returns the title of the item at the specified index or nil if no item exists. + @param anIndex the index of the item +*/ - (CPString)itemTitleAtIndex:(unsigned)anIndex { return [[_menu itemAtIndex:anIndex] title]; } +/* + Returns an array of all the menu item titles. +*/ - (CPArray)itemTitles { var titles = [], @@ -323,57 +415,100 @@ var CPPopUpButtonArrowsImage = nil; items.push([items[index] title]); } +/* + Returns the menu item with the specified title. + @param aTitle the title of the desired menu item +*/ - (CPMenuItem)itemWithTitle:(CPString)aTitle { return [_menu itemAtIndex:[_menu indexOfItemWithTitle:aTitle]]; } +/* + Returns the last menu item +*/ - (CPMenuItem)lastItem { return [[_menu itemArray] lastObject]; } // Getting the Indices of Menu Items - +/* + Returns the index of the specified item or CPNotFound if the item is not in the list. + @param aMenuItem the item to obtain the index for +*/ - (int)indexOfItem:(CPMenuItem)aMenuItem { return [_menu indexOfItem:aMenuItem]; } +/* + Returns the index of the item with the specified tag or CPNotFound if the item is not in the list. + @param aTag the item's tag +*/ - (int)indexOfItemWithTag:(int)aTag { return [_menu indexOfItemWithTag:aMenuItem]; } +/* + Returns the index of the item with the specified title or CPNotFound. + @param aTitle the item's titel +*/ - (int)indexOfItemWithTitle:(CPString)aTitle { return [_menu indexOfItemWithTitle:aTitle]; } +/* + Returns the index of the item with the specified + represented object or CPNotFound + if a match does not exist. + @param anObject the item's represented object +*/ - (int)indexOfItemWithRepresentedObject:(id)anObject { return [_menu indexOfItemWithRepresentedObejct:anObject]; } +/* + Returns the index of the item with the specified target + and action. Returns CPNotFound if the no + such item is in the list. + @param aTarget the item's target + @param anAction the item's action +*/ - (int)indexOfItemWithTarget:(id)aTarget action:(SEL)anAction { return [_menu indexOfItemWithTarget:aTarget action:anAction]; } // Setting the Cell Edge to Pop out in Restricted Situations - +/* + Returns the button's edge where the pop-up menu will be + displayed when there is not enough room to display directly + above the button. +*/ - (CPRectEdge)preferredEdge { return _preferredEdge; } +/* + Sets the preffered edge of the button to display the + pop-up when there is a limited amount of screen space. + By default, the pop-up should draw on top of the button. +*/ - (void)setPreferredEdge:(CPRectEdge)aRectEdge { _preferredEdge = aRectEdge; } // Setting the Title - +/* + Sets the pop-up button's title. + @param aTitle the new title +*/ - (void)setTitle:(CPString)aTitle { if ([self title] == aTitle) @@ -400,14 +535,21 @@ var CPPopUpButtonArrowsImage = nil; } // Setting the Image - +/* + This method has no effect. Because the image is taken + from the currently selected item, this method serves + no purpose. +*/ - (void)setImage:(CPImage)anImage { // The Image is set by the currently selected item. } // Setting the State - +/* + Makes sure the selected item and the item + being displayed are one and the same. +*/ - (void)synchronizeTitleAndSelectedItem { var item = nil; @@ -427,7 +569,10 @@ var CPPopUpButtonArrowsImage = nil; } // - +/* + Called when the menu has a new item added to it. + @param aNotification information about the event +*/ - (void)menuDidAddItem:(CPNotification)aNotification { var index = [[aNotification userInfo] objectForKey:@"CPMenuItemIndex"]; @@ -452,6 +597,10 @@ var CPPopUpButtonArrowsImage = nil; } } +/* + Called when a menu item has changed. + @param aNotification information about the event +*/ - (void)menuDidChangeItem:(CPNotification)aNotification { var index = [[aNotification userInfo] objectForKey:@"CPMenuItemIndex"]; @@ -465,6 +614,10 @@ var CPPopUpButtonArrowsImage = nil; [self synchronizeTitleAndSelectedItem]; } +/* + Called when an item was removed from the menu. + @param aNotification information about the event +*/ - (void)menuDidRemoveItem:(CPNotification)aNotification { var numberOfItems = [self numberOfItems]; @@ -513,6 +666,9 @@ var CPPopUpButtonArrowsImage = nil; [menuWindow beginTrackingWithEvent:anEvent sessionDelegate:self didEndSelector:@selector(menuWindowDidFinishTracking:highlightedItem:)]; } +/* + @ignore +*/ - (void)menuWindowDidFinishTracking:(_CPMenuWindow)aMenuWindow highlightedItem:(CPMenuItem)aMenuItem { [_CPMenuWindow poolMenuWindow:aMenuWindow]; @@ -550,7 +706,13 @@ var CPPopUpButtonMenuKey = @"CPPopUpButtonMenuKey", CPPopUpButtonPullsDownKey = @"CPPopUpButtonPullsDownKey"; @implementation CPPopUpButton (CPCoding) - +/* + Initializes the pop-up button with data from the + specified coder. + @param aCoder the coder from which to read + the data + @return the initialized pop-up button +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super initWithCoder:aCoder]; @@ -565,6 +727,11 @@ var CPPopUpButtonMenuKey = @"CPPopUpButtonMenuKey", return self; } +/* + Encodes the data of the pop-up button into a coder + @param aCoder the coder to which the data + will be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [super encodeWithCoder:aCoder]; diff --git a/AppKit/CPProgressIndicator.j b/AppKit/CPProgressIndicator.j index e5717ed406..843ed23261 100644 --- a/AppKit/CPProgressIndicator.j +++ b/AppKit/CPProgressIndicator.j @@ -26,9 +26,20 @@ import #include "CoreGraphics/CGGeometry.h" - +/* + @global + @group CPProgressIndicatorStyle +*/ CPProgressIndicatorBarStyle = 0; +/* + @global + @group CPProgressIndicatorStyle +*/ CPProgressIndicatorSpinningStyle = 1; +/* + @global + @group CPProgressIndicatorStyle +*/ CPProgressIndicatorHUDBarStyle = 2; var CPProgressIndicatorSpinningStyleColors = nil, @@ -37,6 +48,11 @@ var CPProgressIndicatorSpinningStyleColors = nil, CPProgressIndicatorStyleIdentifiers = nil, CPProgressIndicatorStyleSizes = nil; +/* + This class is used in a Cappuccino GUI to display the progress of a + function or task. If the duration of the task is unknown, there is + also an indeterminate mode for the indicator. +*/ @implementation CPProgressIndicator : CPView { double _minValue; @@ -57,6 +73,9 @@ var CPProgressIndicatorSpinningStyleColors = nil, CPView _barView; } +/* + @ignore +*/ + (void)initialize { if (self != [CPProgressIndicator class]) @@ -152,10 +171,17 @@ var CPProgressIndicatorSpinningStyleColors = nil, return self; } +/* + @ignore +*/ - (void)setUsesThreadedAnimation:(BOOL)aFlag { } +/* + Starts the animation of the progress indicator in indeterminate mode. + @param the requesting object +*/ - (void)startAnimation:(id)aSender { _isAnimating = YES; @@ -163,6 +189,10 @@ var CPProgressIndicatorSpinningStyleColors = nil, [self _hideOrDisplay]; } +/* + Stops the animation of the progress indicator in indeterminate mode. + @param the requesting object +*/ - (void)stopAnimation:(id)aSender { _isAnimating = NO; @@ -170,18 +200,27 @@ var CPProgressIndicatorSpinningStyleColors = nil, [self _hideOrDisplay]; } +/* + Always returns NO. Cappuccino does not have multiple threads. +*/ - (BOOL)usesThreadedAnimation { return NO; } // Advancing the Progress Bar - +/* + Increases the progress of the bar by the specified value. + @param aValue the amount to increase the progress value +*/ - (void)incrementBy:(double)aValue { [self setDoubleValue:_doubleValue + aValue]; } +/* + Sets the progress value of the indicator. +*/ - (void)setDoubleValue:(double)aValue { _doubleValue = MIN(MAX(aValue, _minValue), _maxValue); @@ -189,33 +228,53 @@ var CPProgressIndicatorSpinningStyleColors = nil, [self drawBar]; } +/* + Returns the value of the progress indicator. +*/ - (double)doubleValue { return _doubleValue; } +/* + Sets the minimum value of the progress indicator. The default is 0.0. + @param aValue the new minimum value +*/ - (void)setMinValue:(double)aValue { _minValue = aValue; } +/* + Returns the minimum value of the progress indicator. +*/ - (double)minValue { return _minValue; } +/* + Sets the maximum value of the progress indicator. The default is 100.0. + @param aValue the new maximum value. +*/ - (void)setMaxValue:(double)aValue { _maxValue = aValue; } +/* + Returns the maximum value of the progress indicator. +*/ - (double)maxValue { return _maxValue; } // Setting the Appearance - +/* + Sets the progress indicator's size. + @param aControlSize the new size +*/ - (void)setControlSize:(CPControlSize)aControlSize { if (_controlSize == aControlSize) @@ -226,29 +285,48 @@ var CPProgressIndicatorSpinningStyleColors = nil, [self updateBackgroundColor]; } +/* + Returns the progress indicator's size +*/ - (CPControlSize)controlSize { return _controlSize; } +/* + Not yet implemented +*/ - (void)setControlTint:(CPControlTint)aControlTint { } +/* + Not yet impemented. +*/ - (CPControlTint)controlTint { return 0; } +/* + Not yet implemented. +*/ - (void)setBezeled:(BOOL)isBezeled { } +/* + Not yet implemented. +*/ - (BOOL)isBezeled { return YES; } +/* + Specifies whether this progress indicator should be indeterminate or display progress based on it's max and min. + @param isDeterminate YES makes the indicator indeterminate +*/ - (void)setIndeterminate:(BOOL)isIndeterminate { if (_indeterminate == isIndeterminate) @@ -259,11 +337,18 @@ var CPProgressIndicatorSpinningStyleColors = nil, [self updateBackgroundColor]; } +/* + Returns YES if the progress bar is indeterminate. +*/ - (BOOL)isIndeterminate { return _isIndeterminate; } +/* + Sets the progress indicator's style + @param aStyle the style to set it to +*/ - (void)setStyle:(CPProgressIndicatorStyle)aStyle { if (_style == aStyle) @@ -274,6 +359,9 @@ var CPProgressIndicatorSpinningStyleColors = nil, [self updateBackgroundColor]; } +/* + Resizes the indicator based on it's style. +*/ - (void)sizeToFit { if (_style == CPProgressIndicatorSpinningStyle) @@ -284,6 +372,11 @@ var CPProgressIndicatorSpinningStyleColors = nil, _CPControlIdentifierForControlSize(_controlSize)][0].height)]; } +/* + Sets whether the indicator should be displayed when it isn't animating. By default this is YES if the style + is CPProgressIndicatorBarStyle, and NO if it's CPProgressIndicatorSpinningStyle. + @param isDisplayedWhenStopped YES means the indicator will be displayed when it's not animating. +*/ - (void)setDisplayedWhenStopped:(BOOL)isDisplayedWhenStopped { if (_isDisplayedWhenStoppedSet && _isDisplayedWhenStopped == isDisplayedWhenStopped) @@ -296,6 +389,9 @@ var CPProgressIndicatorSpinningStyleColors = nil, [self _hideOrDisplay]; } +/* + Returns YES if the progress bar is displayed when not animating. +*/ - (BOOL)isDisplayedWhenStopped { if (_isDisplayedWhenStoppedSet) @@ -307,6 +403,7 @@ var CPProgressIndicatorSpinningStyleColors = nil, return NO; } +/* @ignore */ - (void)_hideOrDisplay { [self setHidden:!_isAnimating && ![self isDisplayedWhenStopped]]; @@ -319,6 +416,7 @@ var CPProgressIndicatorSpinningStyleColors = nil, [self drawBar]; } +/* @ignore */ - (void)drawBar { if (_style == CPProgressIndicatorSpinningStyle) @@ -343,6 +441,7 @@ var CPProgressIndicatorSpinningStyleColors = nil, [_barView setFrameSize:CGSizeMake(CGRectGetWidth([self bounds]) * (_doubleValue - _minValue) / (_maxValue - _minValue) - 4.0, 9.0)]; } +/* @ignore */ - (void)updateBackgroundColor { if (YES)//_isBezeled) diff --git a/AppKit/CPResponder.j b/AppKit/CPResponder.j index e51ed792ff..34e177677d 100644 --- a/AppKit/CPResponder.j +++ b/AppKit/CPResponder.j @@ -35,34 +35,55 @@ CPRightArrowKeyCode = 63235; } // Changing the first responder - +/* + Returns YES if the receiver is able to become the first responder. NO otherwise. +*/ - (BOOL)acceptsFirstResponder { return NO; } +/* + Notifies the receiver that it will become the first responder. The receiver can reject first + responder if it returns NO. The default implementation always returns YES. + @return YES if the receiver accepts first responder status. +*/ - (BOOL)becomeFirstResponder { return YES; } +/* + Notifies the receiver that it has been asked to give up first responder status. + @return YES if the receiver is willing to give up first responder status. +*/ - (BOOL)resignFirstResponder { return YES; } // Setting the next responder - +/* + Sets the receiver's next responder. + @param aResponder the responder after the receiver +*/ - (void)setNextResponder:(CPResponder)aResponder { _nextResponder = aResponder; } +/* + Returns the responder after the receiver. +*/ - (CPResponder)nextResponder { return _nextResponder; } +/* + Called to interpret a series of key events. + @param events an array of key CPEvents +*/ - (void)interpretKeyEvents:(CPArray)events { var event, @@ -90,21 +111,38 @@ CPRightArrowKeyCode = 63235; } } +/* + Notifies the receiver that the user has clicked the mouse down in its area. + @param anEvent contains information about the click +*/ - (void)mouseDown:(CPEvent)anEvent { [_nextResponder performSelector:_cmd withObject:anEvent]; } +/* + Notifies the receiver that the user has initiated a drag + over it. A drag is a mouse movement while the left button is down. + @param anEvent contains information about the drag +*/ - (void)mouseDragged:(CPEvent)anEvent { [_nextResponder performSelector:_cmd withObject:anEvent]; } +/* + Notifies the receiver that the user has released the left mouse button. + @param anEvent contains information about the release +*/ - (void)mouseUp:(CPEvent)anEvent { [_nextResponder performSelector:_cmd withObject:anEvent]; } +/* + Notifies the receiver that the user has moved the mouse (with no buttons down). + @param anEvent contains information about the movement +*/ - (void)mouseMoved:(CPEvent)anEvent { [_nextResponder performSelector:_cmd withObject:anEvent]; @@ -115,47 +153,84 @@ CPRightArrowKeyCode = 63235; [_nextResponder performSelector:_cmd withObject:anEvent]; } +/* + Notifies the receiver that the mouse exited the receiver's area. + @param anEvent contains information about the exit +*/ - (void)mouseExited:(CPEvent)anEvent { [_nextResponder performSelector:_cmd withObject:anEvent]; } +/* + Notifies the receiver that the mouse scroll wheel has moved. + @param anEvent information about the scroll +*/ - (void)scrollWheel:(CPEvent)anEvent { [_nextResponder performSelector:_cmd withObject:anEvent]; } +/* + Notifies the receiver that the user has pressed a key. + @param anEvent information about the key press +*/ - (void)keyDown:(CPEvent)anEvent { [_nextResponder performSelector:_cmd withObject:anEvent]; } +/* + Notifies the receiver that the user has released a key. + @param anEvent information about the key press +*/ - (void)keyUp:(CPEvent)anEvent { [_nextResponder performSelector:_cmd withObject:anEvent]; } +/* + FIXME This description is bad. + Based on anEvent, the receiver should simulate the event. + @param anEvent the event to simulate + @return YES if the event receiver simulated the event +*/ - (BOOL)performKeyEquivalent:(CPEvent)anEvent { return NO; } // Action Methods - +/* + Deletes one character backward, or the selection if anything is selected. + @param aSender the object requesting this +*/ - (void)deleteBackward:(id)aSender { } +/* + Insert a line break at the caret position or selection. + @param aSender the object requesting this +*/ - (void)insertLineBreak:(id)aSender { } +/* + Inserts some text at the caret position or selection. + @param aString the string to insert +*/ - (void)insertText:(CPString)aString { } // Dispatch methods - +/* + The receiver will attempt to perform the command, + if it responds to it. If not, the nextResponder will be called to do it. + @param aSelector the command to attempt +*/ - (void)doCommandBySelector:(SEL)aSelector { if([self respondsToSelector:aSelector]) @@ -164,6 +239,13 @@ CPRightArrowKeyCode = 63235; [_nextResponder doCommandBySelector:aSelector]; } +/* + The receiver will attempt to perform the command, or pass it on to the next responder if it doesn't respond to it. + @param aSelector the command to perform + @param anObject the argument to the method + @return YES if the receiver was able to perform the command, or a responder down the chain was + able to perform the command. +*/ - (BOOL)tryToPerform:(SEL)aSelector with:(id)anObject { if([self respondsToSelector:aSelector]) @@ -189,14 +271,19 @@ CPRightArrowKeyCode = 63235; } // Getting the Undo Manager - +/* + Returns the undo manager for the receiver. +*/ - (CPUndoManager)undoManager { return [_nextResponder performSelector:_cmd]; } // Terminating the responder chain - +/* + Called when an event finds no suitable responder. + @param anEventSelector the command that failed +*/ - (void)noResponderFor:(SEL)anEventSelector { } @@ -207,6 +294,11 @@ var CPResponderNextResponderKey = @"CPResponderNextResponderKey"; @implementation CPResponder (CPCoding) +/* + Initializes the responder with data from a coder. + @param aCoder the coder from which data will be read + @return the initialized responder +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [self init]; @@ -217,6 +309,10 @@ var CPResponderNextResponderKey = @"CPResponderNextResponderKey"; return self; } +/* + Archives the responder to a coder. + @param aCoder the coder to which the responder will be archived +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeConditionalObject:_nextResponder forKey:CPResponderNextResponderKey]; diff --git a/AppKit/CPScrollView.j b/AppKit/CPScrollView.j index 30cacbe55f..989d7ee92e 100644 --- a/AppKit/CPScrollView.j +++ b/AppKit/CPScrollView.j @@ -26,7 +26,11 @@ import "CPScroller.j" #include "CoreGraphics/CGGeometry.h" - +/* + Used to display views that are too large for the viewing area. the CPScrollView + places scroll bars on the side of the view to allow the user to scroll and see the entire + contents of the view. +*/ @implementation CPScrollView : CPView { CPClipView _contentView; @@ -46,7 +50,7 @@ import "CPScroller.j" float _horizontalPageScroll; } -- (id)initWithFrame:(CPRect)aFrame +- (id)initWithFrame:(CGRect)aFrame { self = [super initWithFrame:aFrame]; @@ -70,16 +74,26 @@ import "CPScroller.j" } // Determining component sizes -- (CPRect)contentSize +/* + Returns the size of the scroll view's content view. +*/ +- (CGRect)contentSize { return [_contentView frame].size; } +/* + Returns the view that is scrolled for the user. +*/ - (id)documentView { return [_contentView documentView]; } +/* + Sets the content view that clips the document + @param aContentView the content view +*/ - (void)setContentView:(CPClipView)aContentView { if (!aContentView) @@ -102,17 +116,29 @@ import "CPScroller.j" [self addSubview:_contentView]; } +/* + Returns the content view that clips the document. +*/ - (CPClipView)contentView { return _contentView; } +/* + Sets the view that is scrolled for the user. + @param aView the view that will be scrolled +*/ - (void)setDocumentView:(CPView)aView { [_contentView setDocumentView:aView]; [self reflectScrolledClipView:_contentView]; } +/* + Resizes the scroll view to contain the specified + clip view. + @param aClipView the clip view to resize to +*/ - (void)reflectScrolledClipView:(CPClipView)aClipView { if(_contentView != aClipView) @@ -229,7 +255,10 @@ import "CPScroller.j" } // Managing Scrollers - +/* + Sets the scroll view's horizontal scroller. + @param aScroller the horizontal scroller for the scroll view +*/ - (void)setHorizontalScroller:(CPScroller)aScroller { if (_horizontalScroller == aScroller) @@ -246,11 +275,19 @@ import "CPScroller.j" [self addSubview:_horizontalScroller]; } +/* + Returns the scroll view's horizontal scroller +*/ - (CPScroller)horizontalScroller { return _horizontalScroller; } +/* + Specifies whether the scroll view can have a horizontal scroller. + @param hasHorizontalScroller YES lets the scroll view + allocate a horizontal scroller if necessary. +*/ - (void)setHasHorizontalScroller:(BOOL)hasHorizontalScroller { _hasHorizontalScroller = hasHorizontalScroller; @@ -261,11 +298,19 @@ import "CPScroller.j" [_horizontalScroller setHidden:YES]; } +/* + Returns YES if the scroll view can have a horizontal + scroller. +*/ - (BOOL)hasHorizontalScroller { return _hasHorizontalScroller; } +/* + Sets the scroll view's vertical scroller. + @param aScroller the vertical scroller +*/ - (void)setVerticalScroller:(CPScroller)aScroller { if (_verticalScroller == aScroller) @@ -282,11 +327,20 @@ import "CPScroller.j" [self addSubview:_verticalScroller]; } +/* + Return's the scroll view's vertical scroller +*/ - (CPScroller)verticalScroller { return _verticalScroller; } +/* + Specifies whether the scroll view has can have + a vertical scroller. It allocates it if necessary. + @param hasVerticalScroller YES allows + the scroll view to display a vertical scroller +*/ - (void)setHasVerticalScroller:(BOOL)hasVerticalScroller { _hasVerticalScroller = hasVerticalScroller; @@ -297,16 +351,29 @@ import "CPScroller.j" [_verticalScroller setHidden:YES]; } +/* + Returns YES if the scroll view can have + a vertical scroller. +*/ - (BOOL)hasHorizontalScroller { return _hasHorizontalScroller; } +/* + Sets whether the scroll view hides its scoll bars when not needed. + @param autohidesScrollers YES causes the scroll bars + to be hidden when not needed. +*/ - (void)setAutohidesScrollers:(BOOL)autohidesScrollers { _autohidesScrollers = autohidesScrollers; } +/* + Returns YES if the scroll view hides its scroll + bars when not necessary. +*/ - (BOOL)autohidesScrollers { return _autohidesScrollers; @@ -319,6 +386,7 @@ import "CPScroller.j" [self reflectScrolledClipView:_contentView]; }*/ +/* @ignore */ - (void)_verticalScrollerDidScroll:(CPScroller)aScroller { var value = [aScroller floatValue], @@ -347,6 +415,7 @@ import "CPScroller.j" [_contentView scrollToPoint:contentBounds.origin]; } +/* @ignore */ - (void)_horizontalScrollerDidScroll:(CPScroller)aScroller { var value = [aScroller floatValue], @@ -375,6 +444,9 @@ import "CPScroller.j" [_contentView scrollToPoint:contentBounds.origin]; } +/* + Lays out the scroll view's components. +*/ - (void)tile { // yuck. @@ -383,75 +455,135 @@ import "CPScroller.j" // scroll: refl. } --(void)resizeSubviewsWithOldSize:(CPSize)aSize +/* + @ignore +*/ +-(void)resizeSubviewsWithOldSize:(CGSize)aSize { [self reflectScrolledClipView:_contentView]; } // Setting Scrolling Behavior - +/* + Sets how much the document moves when scrolled. Sets + the vertical and horizontal scroll. + @param aLineScroll the amount to move the document + when scrolled +*/ - (void)setLineScroll:(float)aLineScroll { [self setHorizonalLineScroll:aLineScroll]; [self setVerticalLineScroll:aLineScroll]; } +/* + Returns how much the document moves + when scrolled +*/ - (float)lineScroll { return [self horizontalLineScroll]; } +/* + Sets how much the document moves when scrolled + horizontally. + @param aLineScroll the amount to move horizontally + when scrolled. +*/ - (void)setHorizontalLineScroll:(float)aLineScroll { _horizontalLineScroll = aLineScroll; } +/* + Returns how much the document moves horizontally + when scrolled. +*/ - (float)horizontalLineScroll { return _horizontalLineScroll; } +/* + Sets how much the document moves when scrolled + vertically. + @param aLineScroll the new amount to move vertically + when scrolled. +*/ - (void)setVerticalLineScroll:(float)aLineScroll { _verticalLineScroll = aLineScroll; } +/* + Returns how much the document moves vertically + when scrolled. +*/ - (float)verticalLineScroll { return _verticalLineScroll; } +/* + Sets the horizontal and vertical page scroll amount. + @param aPageScroll the new horizontal and vertical page + scroll amount +*/ - (void)setPageScroll:(float)aPageScroll { [self setHorizontalPageScroll:aPageScroll]; [self setVerticalPageScroll:aPageScroll]; } +/* + Returns the vertical and horizontal page scroll + amount. +*/ - (float)pageScroll { return [self horizontalPageScroll]; } +/* + Sets the horizontal page scroll amount. + @param aPageScroll the new horizontal page scroll amount +*/ - (void)setHorizontalPageScroll:(float)aPageScroll { _horizontalPageScroll = aPageScroll; } +/* + Returns the horizontal page scroll amount. +*/ - (float)horizontalPageScroll { return _horizontalPageScroll; } +/* + Sets the vertical page scroll amount. + @param aPageScroll the new vertcal page scroll + amount +*/ - (void)setVerticalPageScroll:(float)aPageScroll { _verticalPageScroll = aPageScroll; } +/* + Returns the vertical page scroll amount. +*/ - (float)verticalPageScroll { return _verticalPageScroll; } +/* + Handles a scroll wheel event from the user. + @param anEvent the scroll wheel event +*/ - (void)scrollWheel:(CPEvent)anEvent { var value = [_verticalScroller floatValue], diff --git a/AppKit/CPScroller.j b/AppKit/CPScroller.j index 795e567936..ee726b4c32 100644 --- a/AppKit/CPScroller.j +++ b/AppKit/CPScroller.j @@ -96,6 +96,9 @@ var _CPScrollerClassName = nil, CPView _incrementArrowView; } +/* + @ignore +*/ + (void)initialize { if (self != [CPScroller class]) @@ -178,7 +181,7 @@ var _CPScrollerClassName = nil, // Calculating Layout -- (id)initWithFrame:(CPRect)aFrame +- (id)initWithFrame:(CGRect)aFrame { self = [super initWithFrame:aFrame]; @@ -193,7 +196,7 @@ var _CPScrollerClassName = nil, _hitPart = CPScrollerNoPart; - [self checkSpaceForUsableParts]; + [self checkSpaceForParts]; [self drawParts]; [self layoutSubviews]; @@ -203,17 +206,27 @@ var _CPScrollerClassName = nil, } // Determining CPScroller Size - +/* + Returns the CPScroller's width for a CPRegularControlSize. +*/ + (float)scrollerWidth { return [self scrollerWidthForControlSize:CPRegularControlSize]; } +/* + Returns the width of a CPScroller for the specified CPControlSize. + @param aControlSize the size of a controller to return the width for +*/ + (float)scrollerWidthForControlSize:(CPControlSize)aControlSize { return _CPScrollerWidths[aControlSize]; } +/* + Sets the scroller's size. + @param aControlSize the scroller's size +*/ - (void)setControlSize:(CPControlSize)aControlSize { if (_controlSize == aControlSize) @@ -229,21 +242,32 @@ var _CPScrollerClassName = nil, [self layoutSubviews]; } +/* + Returns the scroller's control size +*/ - (CPControlSize)controlSize { return _controlSize; } // Setting the Knob Position - +/* + Sets the scroller's knob position (ranges from 0.0 to 1.0). + @param aValue the knob position (ranges from 0.0 to 1.0) +*/ - (void)setFloatValue:(float)aValue { [super setFloatValue:MIN(1.0, MAX(0.0, aValue))]; - [self checkSpaceForUsableParts]; + [self checkSpaceForParts]; [self layoutSubviews]; } +/* + Sets the position and proportion of the knob. + @param aValue the knob position (ranges from 0.0 to 1.0) + @param aProportion the knob's proportion (ranges from 0.0 to 1.0) +*/ - (void)setFloatValue:(float)aValue knobProportion:(float)aProportion { _knobProportion = MIN(1.0, MAX(0.0001, aProportion)); @@ -251,6 +275,9 @@ var _CPScrollerClassName = nil, [self setFloatValue:aValue]; } +/* + Return's the knob's proportion +*/ - (float)knobProportion { return _knobProportion; @@ -266,6 +293,11 @@ var _CPScrollerClassName = nil, return _partRects[aPart]; } +/* + Returns the part of the scroller that would be hit by aPoint. + @param aPoint the simulated point hit + @return the part of the scroller that intersects the point +*/ - (CPScrollerPart)testPart:(CGPoint)aPoint { aPoint = [self convertPoint:aPoint fromView:nil]; @@ -294,7 +326,10 @@ var _CPScrollerClassName = nil, return CPScrollerNoPart; } -- (void)checkSpaceForUsableParts +/* + Check if there's enough space in the scroller to display the knob +*/ +- (void)checkSpaceForParts { var bounds = [self bounds]; @@ -351,13 +386,21 @@ var _CPScrollerClassName = nil, } } +/* + Returns all the parts of the scroller that + are usable for displaying. +*/ - (CPUsableScrollerParts)usableParts { return _usableParts; } // Drawing the Parts - +/* + Draws the specified arrow and sets the highlight. + @param anArrow the arrow to draw + @param shouldHighlight sets whether the arrow should be highlighted +*/ - (void)drawArrow:(CPScrollerArrow)anArrow highlight:(BOOL)shouldHighlight { var identifier = (anArrow == CPScrollerDecrementArrow ? _CPScrollerDecrementArrowIdentifier : _CPScrollerIncrementArrowIdentifier), @@ -372,6 +415,9 @@ var _CPScrollerClassName = nil, shouldHighlight ? _CPScrollerHighlightedIdentifier : @"")]; } +/* + Draws the knob +*/ - (void)drawKnob { [_knobView setBackgroundColor:_CPControlThreePartImagePattern( @@ -383,6 +429,9 @@ var _CPScrollerClassName = nil, _CPControlIdentifierForControlSize(_controlSize))]; } +/* + Draws the knob's slot +*/ - (void)drawKnobSlot { [_knobSlotView setBackgroundColor:_CPControlColorWithPatternImage( @@ -393,6 +442,9 @@ var _CPScrollerClassName = nil, _CPControlIdentifierForControlSize(_controlSize))]; } +/* + Caches images for the scroll arrow and knob. +*/ - (void)drawParts { _knobSlotView = [[CPView alloc] initWithFrame:_CGRectMakeZero()]; @@ -428,6 +480,12 @@ var _CPScrollerClassName = nil, [self drawArrow:CPScrollerIncrementArrow highlight:NO]; } +/* + Draws the scroller's arrow with a possible highlight, + if the user's mouse is over it. + @param shouldHighlight YES will draw the + arrow highlighted if the mouse is hovering over it. +*/ - (void)highlight:(BOOL)shouldHighlight { if (_trackingPart == CPScrollerDecrementLine) @@ -438,12 +496,18 @@ var _CPScrollerClassName = nil, } // Event Handling - +/* + Returns the part of the scroller that was hit. +*/ - (CPScrollerPart)hitPart { return _hitPart; } +/* + Tracks the knob. + @param anEvent the input event +*/ - (void)trackKnob:(CPEvent)anEvent { var type = [anEvent type]; @@ -483,6 +547,10 @@ var _CPScrollerClassName = nil, [self sendAction:[self action] to:[self target]]; } +/* + Tracks the scroll button. + @param anEvent the input event +*/ - (void)trackScrollButtons:(CPEvent)anEvent { var type = [anEvent type]; @@ -561,7 +629,7 @@ var _CPScrollerClassName = nil, { [super setFrameSize:aSize]; - [self checkSpaceForUsableParts]; + [self checkSpaceForParts]; var frame = [self frame], isHorizontal = CPRectGetWidth(frame) > CPRectGetHeight(frame); @@ -576,6 +644,9 @@ var _CPScrollerClassName = nil, [self layoutSubviews]; } +/* + Lays out the scrollers subviews +*/ - (void)layoutSubviews { [_knobSlotView setFrame:[self rectForPart:CPScrollerKnobSlot]]; diff --git a/AppKit/CPSegmentedControl.j b/AppKit/CPSegmentedControl.j index 925f69c106..c26416cbe9 100644 --- a/AppKit/CPSegmentedControl.j +++ b/AppKit/CPSegmentedControl.j @@ -24,11 +24,26 @@ import import "CPControl.j" - +/* + @global + @group CPSegmentSwitchTracking +*/ CPSegmentSwitchTrackingSelectOne = 0; +/* + @global + @group CPSegmentSwitchTracking +*/ CPSegmentSwitchTrackingSelectAny = 1; +/* + @global + @group CPSegmentSwitchTracking +*/ CPSegmentSwitchTrackingMomentary = 2; +/* + This class is a horizontal button with multiple + segments. +*/ @implementation CPSegmentedControl : CPControl { unsigned _segmentCount; @@ -58,13 +73,20 @@ CPSegmentSwitchTrackingMomentary = 2; return self; } +/* + Returns the tag of the selected segment. +*/ - (int)selectedTag { return _segments[_selectedSegment].tag; } // Specifying the number of segments - +/* + Sets the number of segments in the button. + @param aCount the number of segments on + the button +*/ - (void)setSegmentCount:(unsigned)aCount { if (_segmentCount == aCount) @@ -103,23 +125,38 @@ CPSegmentSwitchTrackingMomentary = 2; [self tileWithChangedSegment:0]; } +/* + Returns the number of segments in the button. +*/ - (unsigned)segmentCount { return _segmentCount; } // Specifying Selected Segment - +/* + Selects a segment. + @param aSegment the segment to select + @throws CPRangeException if aSegment is out of bounds +*/ - (void)setSelectedSegment:(unsigned)aSegment { + // setSelected:forSegment throws the exception for us (if necessary) [self setSelected:YES forSegment:aSegment]; } +/* + Returns the selected segment. +*/ - (unsigned)selectedSegment { return _selectedSegment; } +/* + Selects the button segment with the + specified tag. +*/ - (BOOL)selectSegmentWithTag:(int)aTag { var index = 0; @@ -172,13 +209,21 @@ CPSegmentSwitchTrackingMomentary = 2; } } -- (CPSegmetnSwitchTracking)trackingMode +/* + Returns the control's tracking mode. +*/ +- (CPSegmentSwitchTracking)trackingMode { return _trackingMode; } // Working with Individual Segments - +/* + Sets the width of the specified segment. + @param aWidth the new width for the segment + @param aSegment the segment to set the width for + @throws CPRangeException if aSegment is out of bounds +*/ - (void)setWidth:(float)aWidth forSegment:(unsigned)aSegment { _segments[aSegment].width = aWidth; @@ -186,11 +231,22 @@ CPSegmentSwitchTrackingMomentary = 2; [self tileWithChangedSegment:aSegment]; } +/* + Returns the width for the specified segment. + @param aSegment the segment to get the width for + @throws CPRangeException if aSegment is out of bounds +*/ - (float)widthForSegment:(unsigned)aSegment { return _segments[aSegment].width; } +/* + Sets the image for the specified segment. + @param anImage the image for the segment + @param aSegment the segment to set the image on + @throws CPRangeException if aSegment is out of bounds +*/ - (void)setImage:(CPImage)anImage forSegment:(unsigned)aSegment { var segment = _segments[aSegment]; @@ -223,11 +279,22 @@ CPSegmentSwitchTrackingMomentary = 2; [self tileWithChangedSegment:aSegment]; } +/* + Returns the image for the specified segment + @param aSegment the segment to obtain the image for + @throws CPRangeException if aSegment is out of bounds +*/ - (CPImage)imageForSegment:(unsigned)aSegment { return _segments[aSegment].image; } +/* + Sets the label for the specified segment + @param aLabel the label for the segment + @param aSegment the segment to label + @throws CPRangeException if aSegment is out of bounds +*/ - (void)setLabel:(CPString)aLabel forSegment:(unsigned)aSegment { var segment = _segments[aSegment]; @@ -262,27 +329,46 @@ CPSegmentSwitchTrackingMomentary = 2; [self tileWithChangedSegment:aSegment]; } -- (CPImage)labelForSegment:(unsigned)aSegment +/* + Returns the label for the specified segment + @param the segment to obtain the label for + @throws CPRangeException if aSegment is out of bounds +*/ +- (CPString)labelForSegment:(unsigned)aSegment { return _segments[aSegment].label; } +/* + Sets the menu for the specified segment + @param aMenu the menu to set + @param aSegment the segment to set the menu on + @throws CPRangeException if aSegment is out of bounds +*/ - (void)setMenu:(CPMenu)aMenu forSegment:(unsigned)aSegment { _segments[aSegment].menu = aMenu; } -- (CPImage)menuForSegment:(unsigned)aSegment +/* + Returns the menu for the specified segment. + @param aSegment the segment to obtain the menu for + @throws CPRangeException if aSegment is out of bounds +*/ +- (CPMenu)menuForSegment:(unsigned)aSegment { return _segments[aSegment].menu; } +/* + Sets the selection for the specified segment. If only one segment + can be selected at a time, any other segment will be deselected. + @param isSelected YES selects the segment. NO deselects it. + @param aSegment the segment to set the selection for + @throws CPRangeException if aSegment is out of bounds +*/ - (void)setSelected:(BOOL)isSelected forSegment:(unsigned)aSegment { - // FIXME: EXCEPTION REQUIRED - if (aSegment < 0 || aSegment >= _segments.length) - return; - var segment = _segments[aSegment]; // If we're already in this state, bail. @@ -310,37 +396,71 @@ CPSegmentSwitchTrackingMomentary = 2; [self drawSegmentBezel:aSegment highlight:NO]; } -- (CPImage)isSelectedForSegment:(unsigned)aSegment +/* + Returns YES if the specified segment is selected. + @param aSegment the segment to check for selection + @throws CPRangeException if aSegment is out of bounds +*/ +- (BOOL)isSelectedForSegment:(unsigned)aSegment { return _segments[aSegment].selected; } +/* + Enables/diables the specified segment. + @param isEnabled YES enables the segment + @param aSegment the segment to enable/disble + @throws CPRangeException if aSegment is out of bounds +*/ - (void)setEnabled:(BOOL)isEnabled forSegment:(unsigned)aSegment { _segments[aSegment].enabled = isEnabled; } -- (CPImage)isEnabledForSegment:(unsigned)aSegment +/* + Returns YES if the specified segment is enabled. + @param aSegment the segment to check + @throws CPRangeException if aSegment is out of bounds +*/ +- (BOOL)isEnabledForSegment:(unsigned)aSegment { return _segments[aSegment].enabled; } +/* + Sets a tag for the specified segment. + @param aTag the tag to set + @param aSegment the segment to set the tag on +*/ - (void)setTag:(int)aTag forSegment:(unsigned)aSegment { _segments[aSegment].tag = aTag; } +/* + Returns the tag for the specified segment. + @param aSegment the segment to obtain the tag for +*/ - (int)tagForSegment:(unsigned)aSegment { return _segments[aSegment].tag; } // Drawings - +/* + Draws the specified segment bezel + @param aSegment the segment to draw the bezel for + @param shouldHighlight YES highlights the bezel +*/ - (void)drawSegmentBezel:(int)aSegment highlgiht:(BOOL)shouldHighlight { } +/* + Draws the specified segment + @param aSegment the segment to draw + @param shouldHighlight YES highlights the bezel +*/ - (void)drawSegment:(int)aSegment highlight:(BOOL)shouldHighlight { var segment = _segments[aSegment], @@ -430,11 +550,20 @@ CPSegmentSwitchTrackingMomentary = 2; [self drawSegment:aSegment highlight:NO]; } +/* + Returns the bounding rectangle for the specified segment. + @param aSegment the segment to get the rectangle for +*/ - (CGRect)frameForSegment:(unsigned)aSegment { return _segments[aSegment].frame; } +/* + Returns the segment that is hit by the specified point. + @param aPoint the point to test for a segment hit + @return the intersecting segment +*/ - (unsigned)testSegment:(CGPoint)aPoint { var location = [self convertPoint:aPoint fromView:nil], @@ -460,6 +589,10 @@ CPSegmentSwitchTrackingMomentary = 2; { } +/* + Handles events for the segment + @param anEvent the event to handle +*/ - (void)trackSegment:(CPEvent)anEvent { var type = [anEvent type], diff --git a/AppKit/CPShadow.j b/AppKit/CPShadow.j index 30b92fd526..9269d8ed4e 100644 --- a/AppKit/CPShadow.j +++ b/AppKit/CPShadow.j @@ -22,6 +22,9 @@ import +/* + Instances of this class contain the attributes of a drop shadow used in Cappuccino. +*/ @implementation CPShadow : CPObject { CPSize _offset; @@ -31,11 +34,19 @@ import CPString _cssString; } -+ (id)shadowWithOffset:(CPSize)anOffset blurRadius:(float)aBlurRadius color:(CPColor)aColor +/* + Creates a shadow with the specified attributes. + @param anOffset the shadow's offset + @param aBlurRadius the shadow's blur radius + @param aColor the shadow's color + @return the new shadow +*/ ++ (id)shadowWithOffset:(CGSize)anOffset blurRadius:(float)aBlurRadius color:(CPColor)aColor { return [[CPShadow alloc] _initWithOffset:anOffset blurRadius:aBlurRadius color:aColor]; } +/* @ignore */ - (id)_initWithOffset:(CPSize)anOffset blurRadius:(float)aBlurRadius color:(CPColor)aColor { self = [super init]; @@ -52,21 +63,33 @@ import return self; } -- (CPSize)shadowOffset +/* + Returns the shadow's offset. +*/ +- (CGSize)shadowOffset { return _offset; } +/* + Returns the shadow's blur radius +*/ - (float)shadowBlurRadius { return _blurRadius; } +/* + Returns the shadow's color. +*/ - (CPColor)shadowColor { return _color; } +/* + Returns a CSS string representation of the shadow. +*/ - (CPString)cssString { return _cssString; diff --git a/AppKit/CPSlider.j b/AppKit/CPSlider.j index 2b7b0193c1..8f0240a9df 100644 --- a/AppKit/CPSlider.j +++ b/AppKit/CPSlider.j @@ -27,6 +27,9 @@ var CPSliderHorizontalKnobImage = nil CPSliderHorizontalBarRightImage = nil, CPSliderHorizontalBarCenterImage = nil; +/* + An CPSlider displays, and allows control of, some value in the application. It represents a continuous stream of values of type float, which can be retrieved by the method floatValue and set by the method setFloatValue:. +*/ @implementation CPSlider : CPControl { double _value; @@ -43,6 +46,9 @@ var CPSliderHorizontalKnobImage = nil CPView _standardHorizontalBar; } +/* + @ignore +*/ + (void)initialize { if (self != [CPSlider class]) @@ -57,7 +63,7 @@ var CPSliderHorizontalKnobImage = nil CPSliderHorizontalBarCenterImage = [[CPImage alloc] initWithContentsOfFile:[bundle pathForResource:@"CPSlider/CPSliderTrackHorizontalCenter.png"] size:CPSizeMake(1.0, 4.0)]; } -- (id)initWithFrame:(CPRect)aFrame +- (id)initWithFrame:(CGRect)aFrame { self = [super initWithFrame:aFrame]; @@ -81,7 +87,7 @@ var CPSliderHorizontalKnobImage = nil return self; } -- (void)setFrameSize:(CPSize)aSize +- (void)setFrameSize:(CGSize)aSize { if(aSize.height > 21.0) aSize.height = 21.0; @@ -109,42 +115,68 @@ var CPSliderHorizontalKnobImage = nil [_knob setFrameOrigin:[self knobPosition]]; } - + +/* + Returns the value by which the slider will be + incremented if the user holds down the ALTs key. +*/ - (double)altIncrementValue { return _altIncrementValue; } - + +/* + Returns the thickness of the slider's knob. This value is in pixels, + and is the size of the knob along the slider's track. +*/ - (float)knobThickness { return CPRectGetWidth([_knob frame]); } +/* + @ignore +*/ - (CPImage)leftTrackImage { return CPSliderHorizontalBarLeftImage; } +/* + @ignore +*/ - (CPImage)rightTrackImage { return CPSliderHorizontalBarRightImage; } +/* + @ignore +*/ - (CPImage)centerTrackImage { return CPSliderHorizontalBarCenterImage } +/* + @ignore +*/ - (CPImage)knobImage { return CPSliderKnobImage; } +/* + @ignore +*/ - (CPImage)pushedKnobImage { return CPSliderKnobPushedImage; } +/* + Returns the slider's knob. +*/ - (CPView)knob { if (!_standardKnob) @@ -160,6 +192,9 @@ var CPSliderHorizontalKnobImage = nil return _standardKnob; } +/* + Returns the slider's bar. +*/ - (CPView)bar { // FIXME: veritcal. @@ -185,12 +220,18 @@ var CPSliderHorizontalKnobImage = nil } } +/* + Sets the value the slider will be incremented if the user holds the ALT key. +*/ - (void)setAltIncrementValue:(double)anIncrementValue { _altIncrementValue = anIncrementValue; } -- (int)isVertical +/* + Returns YES if the slider is vertical. +*/ +- (BOOL)isVertical { var frame = [self frame]; @@ -200,26 +241,44 @@ var CPSliderHorizontalKnobImage = nil return CPRectGetWidth(frame) < CPRectGetHeight(frame); } +/* + Returns the slider's maximum value +*/ - (double)maxValue { return _maxValue; } +/* + Returns the slider's minimum value +*/ - (double)minValue { return _minValue; } +/* + Sets the slider's maximum value + @param aMaxValue the new maximum value +*/ - (void)setMaxValue:(double)aMaxValue { _maxValue = aMaxValue; } +/* + Sets the slider's minimum value + @param aMinValue the new minimum value +*/ - (void)setMinValue:(double)aMinValue { _minValue = aMinValue; } +/* + Sets the slider's value + @param aValue the new slider value +*/ - (void)setValue:(double)aValue { _value = aValue; @@ -227,12 +286,19 @@ var CPSliderHorizontalKnobImage = nil [_knob setFrameOrigin:[self knobPosition]]; } +/* + Returns the slider's value +*/ - (double)value { return _value; } -- (CPPoint)knobPosition +/* + Returns the knob's position + @ignore +*/ +- (CGPoint)knobPosition { if ([self isVertical]) return CPPointMake(0.0, 0.0); @@ -242,7 +308,10 @@ var CPSliderHorizontalKnobImage = nil (CPRectGetHeight([self frame]) - CPRectGetHeight([_knob frame])) / 2.0); } -- (float)valueForKnobPosition:(CPPoint)aPoint +/* + @ignore +*/ +- (float)valueForKnobPosition:(CGPoint)aPoint { if ([self isVertical]) return 0.0; @@ -250,7 +319,7 @@ var CPSliderHorizontalKnobImage = nil return MAX(MIN((aPoint.x) * (_maxValue - _minValue) / ( CPRectGetWidth([self frame]) - CPRectGetWidth([_knob frame]) ) + _minValue, _maxValue), _minValue); } -- (CPPoint)constrainKnobPosition:(CPPoint)aPoint +- (CGPoint)constrainKnobPosition:(CGPoint)aPoint { //FIXME aPoint.x -= _knobSize.width / 2.0; @@ -292,6 +361,11 @@ var CPSliderMinValueKey = @"CPSliderMinValueKey", @implementation CPSlider (CPCoding) +/* + Initializes the slider from the data in a coder. + @param aCoder the coder from which to read the data + @return the initialized slider +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super initWithCoder:aCoder]; @@ -316,6 +390,10 @@ var CPSliderMinValueKey = @"CPSliderMinValueKey", return self; } +/* + Writes out the slider's instance information to a coder. + @param aCoder the coder to which to write the data +*/ - (void)encodeWithCoder:(CPCoder)aCoder { var subviews = _subviews; diff --git a/AppKit/CPSliderColorPicker.j b/AppKit/CPSliderColorPicker.j index f115b1154d..ef48581af2 100644 --- a/AppKit/CPSliderColorPicker.j +++ b/AppKit/CPSliderColorPicker.j @@ -27,6 +27,9 @@ import import import +/* + @ignore +*/ @implementation CPSliderColorPicker : CPColorPicker { CPView _contentView; diff --git a/AppKit/CPStringDrawing.j b/AppKit/CPStringDrawing.j index 1d36440735..ac827d732b 100644 --- a/AppKit/CPStringDrawing.j +++ b/AppKit/CPStringDrawing.j @@ -27,6 +27,9 @@ var CPStringReferenceElement = nil; @implementation CPString (CPStringDrawing) +/* + Returns the string +*/ - (CPString)cssString { return self; diff --git a/AppKit/CPTabView.j b/AppKit/CPTabView.j index 5eb3dd1a4c..8b8fb83470 100644 --- a/AppKit/CPTabView.j +++ b/AppKit/CPTabView.j @@ -26,13 +26,32 @@ import "CPView.j" #include "CoreGraphics/CGGeometry.h" - +/* + Places tabs on top with a bezeled border. + @global + @group CPTabViewType +*/ CPTopTabsBezelBorder = 0; //CPLeftTabsBezelBorder = 1; //CPBottomTabsBezelBorder = 2; //CPRightTabsBezelBorder = 3; +/* + Displays no tabs and has a bezeled border. + @global + @group CPTabViewType +*/ CPNoTabsBezelBorder = 4; +/* + Has no tabs and displays a line border. + @global + @group CPTabViewType +*/ CPNoTabsLineBorder = 5; +/* + Displays no tabs and no border. + @global + @group CPTabViewType +*/ CPNoTabsNoBorder = 6; var CPTabViewBezelBorderLeftImage = nil, @@ -49,6 +68,13 @@ var CPTabViewDidSelectTabViewItemSelector = 1, CPTabViewWillSelectTabViewItemSelector = 4, CPTabViewDidChangeNumberOfTabViewItemsSelector = 8; +/* + This class represents a view that has multiple subviews (CPTabViewItem) presented as individual tabs. + Only one CPTabViewItem is shown at a time, and other CPTabViewItems can be made visible + (one at a time) by clicking on the CPTabViewItem's tab at the top of the tab view. + + THe currently selected CPTabViewItem is the view that is displayed. +*/ @implementation CPTabView : CPView { CPView _labelsView; @@ -67,6 +93,9 @@ var CPTabViewDidSelectTabViewItemSelector = 1, unsigned _delegateSelectors; } +/* + @ignore +*/ + (void)initialize { if (self != CPTabView) @@ -99,6 +128,9 @@ var CPTabViewDidSelectTabViewItemSelector = 1, CPTabViewBezelBorderColor = [CPColor colorWithPatternImage:bezerBorderImage]; } +/* + @ignore +*/ + (CPColor)bezelBorderColor { return CPTabViewBezelBorderColor; @@ -126,6 +158,7 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [self layoutSubviews]; } +/* @ignore */ - (void)_createBezelBorder { var bounds = [self bounds]; @@ -153,6 +186,10 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [self addSubview:_separatorView]; } +/* + Lays out the subviews + @ignore +*/ - (void)layoutSubviews { if (_tabViewType == CPTopTabsBezelBorder) @@ -182,12 +219,21 @@ var CPTabViewDidSelectTabViewItemSelector = 1, } // Adding and Removing Tabs - +/* + Adds a CPTabViewItem to the tab view. + @param aTabViewItem the item to add +*/ - (void)addTabViewItem:(CPTabViewItem)aTabViewItem { [self insertTabViewItem:aTabViewItem atIndex:[_tabViewItems count]]; } +/* + Inserts a CPTabViewItem into the tab view + at the specified index. + @param aTabViewItem the item to insert + @param anIndex the index for the item +*/ - (void)insertTabViewItem:(CPTabViewItem)aTabViewItem atIndex:(unsigned)anIndex { [_tabViewItems insertObject:aTabViewItem atIndex:anIndex]; @@ -201,6 +247,10 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [_delegate tabViewDidChangeNumberOfTabViewItems:self]; } +/* + Removes the specified tab view item from the tab view. + @param aTabViewItem the item to remove +*/ - (void)removeTabViewItem:(CPTabViewItem)aTabViewItem { [_tabViewItems removeObjectIdenticalTo:aTabViewItem]; @@ -212,12 +262,19 @@ var CPTabViewDidSelectTabViewItemSelector = 1, } // Accessing Tabs - +/* + Returns the index of the specified item + @param aTabViewItem the item to find the index for +*/ - (int)indexOfTabViewItem:(CPTabViewItem)aTabViewItem { return [_tabViewItems indexOfObjectIdenticalTo:aTabViewItem]; } +/* + Returns the index of the CPTabViewItem with the specified identifier. + @param anIdentifier the identifier of the item +*/ - (int)indexOfTabViewItemWithIdentifier:(CPString)anIdentifier { var index = 0, @@ -230,23 +287,35 @@ var CPTabViewDidSelectTabViewItemSelector = 1, return index; } +/* + Returns the number of items in the tab view. +*/ - (unsigned)numberOfTabViewItems { return [_tabViewItems count]; } +/* + Returns the CPTabViewItem at the specified index. +*/ - (CPTabViewItem)tabViewItemAtIndex:(unsigned)anIndex { return _tabViewItems[anIndex]; } +/* + Returns the array of items that backs this tab view. +*/ - (CPArray)tabViewItems { return _tabViewItems; } // Selecting a Tab - +/* + Sets the first tab view item in the array to be displayed to the user. + @param aSender the object making this request +*/ - (void)selectFirstTabViewItem:(id)aSender { var count = [_tabViewItems count]; @@ -255,6 +324,10 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [self selectTabViewItemAtIndex:0]; } +/* + Sets the last tab view item in the array to be displayed to the user. + @param aSender the object making this request +*/ - (void)selectLastTabViewItem:(id)aSender { var count = [_tabViewItems count]; @@ -263,6 +336,10 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [self selectTabViewItemAtIndex:count - 1]; } +/* + Sets the next tab item in the array to be displayed. + @param aSender the object making this request +*/ - (void)selectNextTabViewItem:(id)aSender { if (!_selectedTabViewItem) @@ -274,6 +351,10 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [self selectTabViewItemAtIndex:index + 1 % count]; } +/* + Selects the previous item in the array for display. + @param aSender the object making this request +*/ - (void)selectPreviousTabViewItem:(id)aSender { if (!_selectedTabViewItem) @@ -285,6 +366,10 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [self selectTabViewItemAtIndex:index == 0 ? count : index - 1]; } +/* + Displays the specified item in the tab view. + @param aTabViewItem the item to display +*/ - (void)selectTabViewItem:(CPTabViewItem)aTabViewItem { if ((_delegateSelectors & CPTabViewShouldSelectTabViewItemSelector) && ![_delegate tabView:self shouldSelectTabViewItem:aTabViewItem]) @@ -324,18 +409,28 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [_delegate tabView:self didSelectTabViewItem:aTabViewItem]; } +/* + Selects the item at the specified index. + @param anIndex the index of the item to display. +*/ - (void)selectTabViewItemAtIndex:(unsigned)anIndex { [self selectTabViewItem:_tabViewItems[anIndex]]; } -- (void)selectedTabViewItem +/* + Returns the current item being displayed. +*/ +- (CPTabViewItem)selectedTabViewItem { return _selectedTabViewItem; } // - +/* + Sets the tab view type. + @param aTabViewType the view type +*/ - (void)setTabViewType:(CPTabViewType)aTabViewType { if (_tabViewType == aTabViewType) @@ -356,13 +451,18 @@ var CPTabViewDidSelectTabViewItemSelector = 1, [self layoutSubviews]; } +/* + Returns the tab view type. +*/ - (CPTabViewType)tabViewType { return _tabViewType; } // Determining the Size - +/* + Returns the content rectangle. +*/ - (CGRect)contentRect { var contentRect = CGRectMakeCopy([self bounds]); @@ -383,6 +483,10 @@ var CPTabViewDidSelectTabViewItemSelector = 1, return contentRect; } +/* + Sets the delegate for this tab view. + @param aDelegate the tab view's delegate +*/ - (void)setDelegate:(id)aDelegate { if (_delegate == aDelegate) @@ -422,6 +526,7 @@ var _CPTabLabelsViewBackgroundColor = nil, _CPTabLabelsViewInsideMargin = 10.0, _CPTabLabelsViewOutsideMargin = 15.0; +/* @ignore */ @implementation _CPTabLabelsView : CPView { CPTabView _tabView; @@ -553,6 +658,7 @@ var _CPTabLabelsViewBackgroundColor = nil, var _CPTabLabelBackgroundColor = nil, _CPTabLabelSelectedBackgroundColor = nil; +/* @ignore */ @implementation _CPTabLabel : CPView { CPTabViewItem _tabViewItem; diff --git a/AppKit/CPTabViewItem.j b/AppKit/CPTabViewItem.j index a5f7306e16..5a6e15fc05 100644 --- a/AppKit/CPTabViewItem.j +++ b/AppKit/CPTabViewItem.j @@ -24,11 +24,29 @@ import import - +/* + The tab is currently selected. + @global + @group CPTabState +*/ CPSelectedTab = 0; +/* + The tab is currently in the background (not selected). + @global + @group CPTabState +*/ CPBackgroundTab = 1; +/* + The tab of this item is currently being pressed by the user. + @global + @group CPTabState +*/ CPPressedTab = 2; +/* + The class representation of an item in a CPTabView. One tab view item + can be shown at a time in a CPTabView. +*/ @implementation CPTabViewItem : CPObject { id _identifier; @@ -38,6 +56,10 @@ CPPressedTab = 2; CPView _auxiliaryView; } +/* + Initializes the tab view item with the specified identifier. + @return the initialized CPTabViewItem +*/ - (id)initWithIdentifier:(id)anIdentifier { self = [super init]; @@ -49,63 +71,90 @@ CPPressedTab = 2; } // Working With Labels - +/* + Sets the CPTabViewItem's label. + @param aLabel the label for the item +*/ - (void)setLabel:(CPString)aLabel { _label = aLabel; } +/* + Returns the CPTabViewItem's label +*/ - (CPString)label { return _label; } // Checking the Tab Display State - +/* + Returns the tab's current state. +*/ - (CPTabState)tabState { return _tabState; } // Assigning an Identifier Object - +/* + Sets the item's identifier. + @param anIdentifier the new identifier for the item +*/ - (void)setIdentifier:(id)anIdentifier { _identifier = anIdentifier; } +/* + Returns the tab's identifier. +*/ - (id)identifier { return _identifier; } // Assigning a View - +/* + Sets the view that gets displayed in this tab. +*/ - (void)setView:(CPView)aView { _view = aView; } +/* + Returns the tab's view. +*/ - (CPView)view { return _view; } // Assigning an Auxiliary View - +/* + Sets the tab's auxillary view. + @param anAuxillaryView the new auxillary view +*/ - (void)setAuxiliaryView:(CPView)anAuxiliaryView { _auxiliaryView = anAuxiliaryView; } +/* + Returns the tab's auxillary view +*/ - (CPView)auxiliaryView { return _auxiliaryView; } // Accessing the Parent Tab View - -- (CPView)tabView +/* + Returns the tab view that contains this item. +*/ +- (CPTabView)tabView { return _tabView; } diff --git a/AppKit/CPTableColumn.j b/AppKit/CPTableColumn.j index 84872362f2..b06506321a 100644 --- a/AppKit/CPTableColumn.j +++ b/AppKit/CPTableColumn.j @@ -20,13 +20,36 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ + import +/* +@ignore +*/ +/* + @global + @class CPTableColumn +*/ CPTableColumnNoResizing = 0; +/* + @global + @class CPTableColumn +*/ CPTableColumnAutoresizingMask = 1; +/* + @global + @class CPTableColumn +*/ CPTableColumnUserResizingMask = 2; +/* + An CPTableColumn object mainly keeps information about the width of the column, its minimum and maximum width; whether the column can be edited or resized; and the cells used to draw the column header and the data in the column. You can change all these attributes of the column by calling the appropriate methods. Please note that the table column does not hold nor has access to the data to be displayed in the column; this data is maintained in the table view's data source.

+ +

Each CPTableColumn object is identified by a CPString, called the column identifier. The reason is that, after a column has been added to a table view, the user might move the columns around, so there is a need to identify the columns regardless of its position in the table. + + @ignore +*/ @implementation CPTableColumn : CPObject { CPString _identifier; @@ -40,6 +63,11 @@ CPTableColumnUserResizingMask = 2; unsigned _resizingMask; } +/* + Initializes the table column with the specified identifier. + @param anIdentifier the identifier + @return the initialized table column +*/ - (id)initWithIdentifier:(CPString)anIdentifier { self = [super init]; @@ -59,67 +87,117 @@ CPTableColumnUserResizingMask = 2; return self; } +/* + Sets the table column's identifier + @param anIdentifier the new identifier +*/ - (void)setIdentifier:(CPString)anIdentifier { _identifier = anIdentifier; } +/* + Returns the table column's identifier +*/ - (CPString)identifier { return _identifier; } -// Setting the NSTableView - -- (void)setTabelView:(CPTableView)aTableView +// Setting the CPTableView +/* + Sets the table's view. This is called automatically by Cappuccino. + @param aTableView the new table view +*/ +- (void)setTableView:(CPTableView)aTableView { _tableView = aTableView; } +/* + Returns the column's table view. +*/ - (CPTableView)tableView { return _tableView; } // Controlling size - +/* + Sets the column's width. + @param aWidth the new column width +*/ - (void)setWidth:(float)aWidth { _width = aWidth; } +/* + Returns the column's width +*/ - (float)width { return _width; } +/* + Sets column's minimum width. + @param aWidth the new minimum column width +*/ - (void)setMinWidth:(float)aWidth { if (_width < (_minWidth = aWidth)) [self setWidth:_minWidth]; } +/* + The column's minimum width +*/ - (float)minWidth { return _minWidth; } -- (float)setMaxWidth:(float)aWidth +/* + Sets the column's maximum width. + @param aWidth the new maximum width +*/ +- (void)setMaxWidth:(float)aWidth { if (_width > (_maxmimumWidth = aWidth)) [self setWidth:_maxWidth]; } +/* + Sets the resizing mask. The mask is one of: +

+CPTableColumnNoResizing;
+CPTableColumnAutoresizingMask;
+CPTableColumnUserResizingMask;
+
+ @param aMask the new resizing mask +*/ - (void)setResizingMask:(unsigned)aMask { _resizingMask = aMask; } +/* + Returns the column's resizing mask. One of: +
+CPTableColumnNoResizing;
+CPTableColumnAutoresizingMask;
+CPTableColumnUserResizingMask;
+
+*/ - (unsigned)resizingMask { return _resizingMask; } +/* + Resizes the column according to the min, max and set width. +*/ - (void)sizeToFit { var width = CPRectGetWidth([_headerView frame]); @@ -133,37 +211,63 @@ CPTableColumnUserResizingMask = 2; [self setWidth:width]; } +/* + Sets whether the column in this data is editable. + @param aFlag YES means the column data is editable +*/ - (void)setEditable:(BOOL)aFlag { _isEditable = aFlag; } +/* + Returns YES if the column data is editable. +*/ - (BOOL)isEditable { return _isEditable; } +/* + Sets the view that draws the column's header. + @param aHeaderView the view that will draws the column header +*/ - (void)setHeaderView:(CPView)aHeaderView { _headerView = aHeaderView; } +/* + Return the view that draws the column's header +*/ - (CPView)headerView { return _headerView; } -- (void)setDataCell:(id)aDataCell +/* + Sets the data cell that draws rows in this column. +*/ +- (void)setDataCell:(CPCell)aDataCell { _dataCell = aDataCell; } -- (id)dataCell +/* + Returns the data cell that draws rows in this column +*/ +- (CPCell)dataCell { return _dataCell; } -- (Class)dataCellForRow:(int)aRowIndex +/* + By default returns the value from dataCell. This can + be overridden by a subclass to return different cells for different + rows. + @param aRowIndex the index of the row to obtain the cell for +*/ +- (CPCell)dataCellForRow:(int)aRowIndex { return [self dataCell]; } diff --git a/AppKit/CPTableView.j b/AppKit/CPTableView.j index ed5d5aee40..8076b89940 100644 --- a/AppKit/CPTableView.j +++ b/AppKit/CPTableView.j @@ -26,6 +26,11 @@ import "CPTableColumn.j" var CPTableViewCellPlaceholder = nil; +/* + CPTableView is located within the AppKit framework and is used to display tables. It uses a delegate model for getting its data i.e. you give it an object that provides it with the data it should display. + + @ignore +*/ @implementation CPTableView : CPControl { id _dataSource; @@ -41,7 +46,7 @@ var CPTableViewCellPlaceholder = nil; CPArray _tableCells; CPArray _tableColumnViews; - CPSize _intercellSpacing; + CGSize _intercellSpacing; } + (void)initialize @@ -52,7 +57,7 @@ var CPTableViewCellPlaceholder = nil; CPTableViewCellPlaceholder = [[CPObject alloc] init]; } -- (id)initWithFrame:(CPRect)aFrame +- (id)initWithFrame:(CGRect)aFrame { self = [super initWithFrame:aFrame]; @@ -83,6 +88,9 @@ var CPTableViewCellPlaceholder = nil; return self; } +/* + Returns the table's column height +*/ - (float)columnHeight { var bounds = [self bounds], @@ -91,7 +99,7 @@ var CPTableViewCellPlaceholder = nil; return CPRectGetHeight(bounds) > height ? CPRectGetHeight(bounds) : height; } -- (void)loadTableCellsInRect:(CPRect)aRect +- (void)loadTableCellsInRect:(CGRect)aRect { if (!_dataSource) return; @@ -132,8 +140,11 @@ var CPTableViewCellPlaceholder = nil; } // Setting display attributes - -- (void)setIntercellSpacing:(CPSize)aSize +/* + Sets the width and height between cell. The default is (3.0, 2.0) (width, height). + @param the width and height spacing +*/ +- (void)setIntercellSpacing:(CGSize)aSize { if (_intercellSpacing.width != aSize.width) { @@ -172,11 +183,19 @@ var CPTableViewCellPlaceholder = nil; _intercellSpacing = CPSizeCreateCopy(aSize); } -- (CPSize)intercellSpacing +/* + Returns the width and height of the space between + cells. +*/ +- (CGSize)intercellSpacing { return _intercellSpacing; } +/* + Sets the height of table rows + @param aRowHeight the new height of the table rows +*/ - (void)setRowHeight:(unsigned)aRowHeight { if (_rowHeight == aRowHeight) @@ -192,11 +211,18 @@ var CPTableViewCellPlaceholder = nil; [_tableCells[column][row] setFrameOrigin:CPPointMake(0.0, row * (_rowHeight + _intercellSpacing.height))]; } +/* + Returns the height of a table row +*/ - (unsigned)rowHeight { return _rowHeight; } +/* + Adds a column to the table + @param aTableColumn the column to be added +*/ - (void)addTableColumn:(CPTableColumn)aTableColumn { var i = 0, @@ -219,6 +245,10 @@ var CPTableViewCellPlaceholder = nil; ++_numberOfColumns; } +/* + Removes a column from the table + @param aTableColumn the column to remove +*/ - (void)removeTableColumn:(CPTableColumn)aTableColumn { var frame = [self frame], @@ -240,6 +270,12 @@ var CPTableViewCellPlaceholder = nil; [self setFrameSize:CPSizeMake(CPRectGetWidth(frame) - width, CPRectGetHeight(frame))]; } +/* + Not yet implemented. Changes the position of the column in + the table. + @param fromIndex the original index of the column + @param toIndex the desired index of the column +*/ - (void)moveColumn:(unsigned)fromIndex toColumn:(unsinged)toIndex { if (fromIndex == toIndex) @@ -247,23 +283,34 @@ var CPTableViewCellPlaceholder = nil; // FIXME: IMPLEMENT } +/* + Returns an array containing the table's CPTableColumns. +*/ - (CPArray)tableColumns { return _tableColumns; } // Getting the dimensions of the table - +/* + Returns the number of columns in the table +*/ - (int)numberOfColumns { return _numberOfColumns; } +/* + Returns the number of rows in the table +*/ - (int)numberOfRows { return _numberOfRows; } +/* + Adjusts the size of the table and it's header view. +*/ - (void)tile { var HEIGHT = 10.0; @@ -272,19 +319,37 @@ var CPTableViewCellPlaceholder = nil; [_scrollView setFrame:CPRectMake(0.0, HEIGHT, CPRectGetWidth([self bounds]), CPRectGetHeight([self bounds]) - HEIGHT)]; } +/* + Sets the object that is used to obtain the table data. The data source must implement the following + methods: +
+- (int)numberOfRowsInTableView:(CPTableView)aTableView
+- (id)tableView:(CPTableView)aTableView objectValueForTableColumn:(CPTableColumn)aTableColumn row:(int)rowIndex
+
+ @param aDataSource the object with the table data + @throws CPInternalInconsistencyException if aDataSource doesn't implement all the required methods +*/ - (void)setDataSource:(id)aDataSource { + if (![aDataSource respondsToSelector:@selector(numberOfRowsInTableView:)]) + [CPException raise:CPInternalInconsistencyException reason:"Data source doesn't support 'numberOfRowsInTableView:'"]; + if (![aDataSource respondsToSelector:@selector(tableView:objectValueForTableColumn:row:)]) + [CPException raise:CPInternalInconsistencyException reason:"Data source doesn't support 'tableView:objectValueForTableColumn:row:'"]; + _dataSource = aDataSource; [self reloadData]; } +/* + Returns the object that has access to the table data +*/ - (id)dataSource { return _dataSource; } -- (void)setFrameSize:(CPSize)aSize +- (void)setFrameSize:(CGSize)aSize { var oldColumnHeight = [self columnHeight]; @@ -303,6 +368,10 @@ var CPTableViewCellPlaceholder = nil; [self tile]; } +/* + Tells the table view that the number of rows in the table + has changed. +*/ - (void)noteNumberOfRowsChanged { var numberOfRows = [_dataSource numberOfRowsInTableView:self]; @@ -314,21 +383,38 @@ var CPTableViewCellPlaceholder = nil; } } -- (CPRect)rectOfRow:(int)aRowIndex +/* + Returns the rectangle bounding the specified row. + @param aRowIndex the row to obtain a rectangle for + @return the bounding rectangle +*/ +- (CGRect)rectOfRow:(int)aRowIndex { return CPRectMake(0.0, aRowIndex * (_rowHeight + _intercellSpacing.height), CPRectGetWidth([self bounds]), _rowHeight); } -- (CPRect)rectOfColumn:(int)aColumnIndex +/* + Returns the rectangle bounding the specified column + @param aColumnIndex the column to obtain a rectangle for + @return the bounding column +*/ +- (CGRect)rectOfColumn:(int)aColumnIndex { return CPRectCreateCopy([_tableColumnViews[aColumnIndex] frame]); } +/* + Adjusts column widths to make them all visible at once. Same as tile. +*/ - (void)sizeToFit { [self tile]; } +/* + Reloads the data from the dataSource. This is an + expensive method, so use it lightly. +*/ - (void)reloadData { _numberOfRows = [_dataSource numberOfRowsInTableView:self]; diff --git a/AppKit/CPTextField.j b/AppKit/CPTextField.j index 67064bb9e9..6184fb61ee 100644 --- a/AppKit/CPTextField.j +++ b/AppKit/CPTextField.j @@ -26,15 +26,48 @@ import "CPStringDrawing.j" #include "Platform/Platform.h" #include "Platform/DOM/CPDOMDisplayServer.h" - -CPLineBreakByWordWrapping = 0, -CPLineBreakByCharWrapping = 1, -CPLineBreakByClipping = 2, -CPLineBreakByTruncatingHead = 3, -CPLineBreakByTruncatingTail = 4, +/* + @global + @group CPLineBreakMode +*/ +CPLineBreakByWordWrapping = 0; +/* + @global + @group CPLineBreakMode +*/ +CPLineBreakByCharWrapping = 1; +/* + @global + @group CPLineBreakMode +*/ +CPLineBreakByClipping = 2; +/* + @global + @group CPLineBreakMode +*/ +CPLineBreakByTruncatingHead = 3; +/* + @global + @group CPLineBreakMode +*/ +CPLineBreakByTruncatingTail = 4; +/* + @global + @group CPLineBreakMode +*/ CPLineBreakByTruncatingMiddle = 5; +/* + A textfield bezel with a squared corners. + @global + @group CPTextFieldBezelStyle +*/ CPTextFieldSquareBezel = 0; +/* + A textfield bezel with rounded corners. + @global + @group CPTextFieldBezelStyle +*/ CPTextFieldRoundedBezel = 1; var TOP_PADDING = 4.0, @@ -49,6 +82,9 @@ var _CPTextFieldSquareBezelColor = nil; @implementation CPString (CPTextFieldAdditions) +/* + Returns the string (self). +*/ - (CPString)string { return self; @@ -56,6 +92,9 @@ var _CPTextFieldSquareBezelColor = nil; @end +/* + This control displays editable text in a Cappuccino application. +*/ @implementation CPTextField : CPControl { BOOL _isBordered; @@ -73,6 +112,7 @@ var _CPTextFieldSquareBezelColor = nil; #endif } +/* @ignore */ #if PLATFORM(DOM) + (DOMElement)_inputElement { @@ -97,7 +137,7 @@ var _CPTextFieldSquareBezelColor = nil; } #endif -- (id)initWithFrame:(CPRect)aFrame +- (id)initWithFrame:(CGRect)aFrame { self = [super initWithFrame:aFrame]; @@ -125,7 +165,11 @@ var _CPTextFieldSquareBezelColor = nil; } // Setting the Bezel Style - +/* + Sets whether the textfield will have a bezeled border. + @param shouldBeBezeled YES means the textfield + will draw a bezeled border +*/ - (void)setBezeled:(BOOL)shouldBeBezeled { if (_isBezeled == shouldBeBezeled) @@ -136,11 +180,19 @@ var _CPTextFieldSquareBezelColor = nil; [self _updateBackground]; } +/* + Returns YES if the textfield draws a + bezeled border. +*/ - (BOOL)isBezeled { return _isBezeled; } +/* + Sets the textfield's bezel style. + @param aBezelStyle the constant for the desired bezel style +*/ - (void)setBezelStyle:(CPTextFieldBezelStyle)aBezelStyle { if (_bezelStyle == aBezelStyle) @@ -151,11 +203,19 @@ var _CPTextFieldSquareBezelColor = nil; [self _updateBackground]; } +/* + Returns the textfield's bezel style. +*/ - (CPTextFieldBezelStyle)bezelStyle { return _bezelStyle; } +/* + Sets whether the textfield will have a border drawn. + @param shouldBeBordered YES makes the + textfield draw a border +*/ - (void)setBordered:(BOOL)shouldBeBordered { if (_isBordered == shouldBeBordered) @@ -166,11 +226,16 @@ var _CPTextFieldSquareBezelColor = nil; [self _updateBackground]; } +/* + Returns YES if the textfield has + a border. +*/ - (BOOL)isBordered { return _isBordered; } +/* @ignore */ - (void)_updateBackground { if (_isBordered && _bezelStyle == CPTextFieldSquareBezel && _isBezeled) @@ -263,6 +328,10 @@ var _CPTextFieldSquareBezelColor = nil; _isEditable = shouldBeEditable; } +/* + Returns YES if the textfield is currently + editable by the user. +*/ - (BOOL)isEditable { return _isEditable; @@ -275,17 +344,30 @@ var _CPTextFieldSquareBezelColor = nil; CPDOMDisplayServerSetStyleSize(_DOMTextElement, _frame.size.width - 2.0 * HORIZONTAL_PADDING, _frame.size.height - TOP_PADDING - BOTTOM_PADDING); } +/* + Returns YES if the field's text is + selectable by the user. +*/ - (BOOL)isSelectable { return _isSelectable; } +/* + Sets whether the field's text is selectable + by the user. + @param aFlag YES makes the text selectable +*/ - (void)setSelectable:(BOOL)aFlag { _isSelectable = aFlag; } -- (void)setAlignment:(int)anAlignment +/* + Sets the alignment of the text in the field. + @param anAlignment +*/ +- (void)setAlignment:(CPTextAlignment)anAlignment { if ([self alignment] == anAlignment) return; @@ -309,6 +391,10 @@ var _CPTextFieldSquareBezelColor = nil; #endif } +/* + Sets the way line breaks occur in the text field. + @param aLineBreakMode the line break style +*/ - (void)setLineBreakMode:(CPLineBreakMode)aLineBreakMode { _lineBreakMode = aLineBreakMode; @@ -329,6 +415,9 @@ var _CPTextFieldSquareBezelColor = nil; #endif } +/* + Returns the string the text field. +*/ - (CPString)stringValue { // All of this needs to be better. @@ -340,6 +429,9 @@ var _CPTextFieldSquareBezelColor = nil; return [_value string]; } +/* + Sets the string the text field. +*/ - (void)setStringValue:(CPString)aStringValue { _value = aStringValue; @@ -354,6 +446,9 @@ var _CPTextFieldSquareBezelColor = nil; #endif } +/* + Adjusts the text field's size in the application. +*/ - (void)sizeToFit { #if PLATFORM(DOM) @@ -371,6 +466,11 @@ var CPTextFieldIsSelectableKey = @"CPTextFieldIsSelectableKey", @implementation CPTextField (CPCoding) +/* + Initializes the textfield with data from a coder. + @param aCoder the coder from which to read the textfield data + @return the initialized textfield +*/ - (id)initWithCoder:(CPCoder)aCoder { #if PLATFORM(DOM) @@ -406,6 +506,12 @@ var CPTextFieldIsSelectableKey = @"CPTextFieldIsSelectableKey", return self; } +/* + Encodes the data of this textfield into the + provided coder. + @param aCoder the coder into which the data + will be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [super encodeWithCoder:aCoder]; diff --git a/AppKit/CPToolbar.j b/AppKit/CPToolbar.j index ba07ae10bb..41fd31005f 100644 --- a/AppKit/CPToolbar.j +++ b/AppKit/CPToolbar.j @@ -25,14 +25,31 @@ import import "CPPopUpButton.j" import "CPToolbarItem.j" +/* + @global + @group CPToolbarDisplayMode +*/ CPToolbarDisplayModeDefault = 0; +/* + @global + @group CPToolbarDisplayMode +*/ CPToolbarDisplayModeIconAndLabel = 1; +/* + @global + @group CPToolbarDisplayMode +*/ CPToolbarDisplayModeIconOnly = 2; +/* + @global + @group CPToolbarDisplayMode +*/ CPToolbarDisplayModeLabelOnly = 3; var CPToolbarsByIdentifier = nil; var CPToolbarConfigurationsByIdentifier = nil; +/* @ignore */ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) { var lhsVisibilityPriority = [lhs visibilityPriority], @@ -47,6 +64,28 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) return CPOrderedDescending; } +/* + A CPToolbar is displayed at the top of a window with multiple + buttons (tools) that offer the user quick access to features. + + @delegate -(CPArray)toolbarDefaultItemIdentifiers:(CPToolbar)toolbar; + Called to obtain the toolbar's default item identifiers. Required. + @param toolbar the toolbar to obtain identifiers for + @return an array of default item identifiers in the order on the toolbar + + @delegate -(CPArray)toolbarAllowedItemIdentifiers:(CPToolbar)toolbar; + Called to obtain the toolbar's default item identifiers. Required. + @param toolbar the toolbar to obtain identifiers for + @return an array of default item identifiers in the order on the toolbar + + @delegate - (CPToolbarItem)toolbar:(CPToolbar)toolbar itemForItemIdentifier:(CPString)itemIdentifier willBeInsertedIntoToolbar:(BOOL)flag; + Called to obtain a toolbar item. Required. + @param toolbar the toolbar the item belongs to + @param itemIdentifier the identifier of the toolbar item + @param flag YES means the item will be placed in the toolbar. NO means the item will be displayed for + some other purpose (non-functional) + @return the toolbar item or nil if no such item belongs in the toolbar +*/ @implementation CPToolbar : CPObject { CPString _identifier; @@ -68,6 +107,7 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) CPMutableDictionary _itemIndexes; } +/* @ignore */ + (void)initialize { if (self != [CPToolbar class]) @@ -77,6 +117,11 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) CPToolbarConfigurationsByIdentifier = [CPDictionary dictionary]; } +/* + Initializes the toolbar with the specified identifier. + @param anIdentifier the identifier for the toolbar + @return the initialized toolbar +*/ - (id)initWithIdentifier:(CPString)anIdentifier { self = [super init]; @@ -103,26 +148,42 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) return self; } +/* + Sets the toolbar's display mode. NOT YET IMPLEMENTED. +*/ - (void)setDisplayMode:(CPToolbarDisplayMode)aDisplayMode { } +/* + Returns the toolbar's identifier +*/ - (CPString)identifier { return _identifier; } +/* + Returns the toolbar's delegate +*/ - (id)delegate { return _delegate; } +/* + Returns YES if the toolbar is currently visible +*/ - (BOOL)isVisible { return _isVisible; } +/* + Sets whether the toolbar should be visible. + @param aFlag YES makes the toolbar visible +*/ - (void)setVisible:(BOOL)aFlag { if (_isVisible == aFlag) @@ -134,6 +195,10 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) [self _reloadToolbarItems]; } +/* + Sets the delegate for the toolbar. + @param aDelegate the new toolbar delegate +*/ - (void)setDelegate:(id)aDelegate { if (_delegate == aDelegate) @@ -148,11 +213,13 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) [self _reloadToolbarItems]; } +/* @ignore */ - (void)_loadConfiguration { } +/* @ignore */ - (CPView)_toolbarView { if (!_toolbarView) @@ -166,6 +233,7 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) return _toolbarView; } +/* @ignore */ - (void)_reloadToolbarItems { if (![_toolbarView superview] || !_delegate) @@ -210,16 +278,26 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) [_toolbarView reloadToolbarItems]; } -- (void)items +/* + Returns all the items in this toolbar. +*/ +- (CPArray)items { return _items; } +/* + Returns all the visible items in this toolbar +*/ - (CPArray)visibleItems { return [_toolbarView visibleItems]; } +/* + Returns the index of the specified toolbar item + @param anItem the item to obtain the index for +*/ - (int)indexOfItem:(CPToolbarItem)anItem { var info = [_itemIndexes objectForKey:[anItem hash]]; @@ -230,6 +308,9 @@ var _CPToolbarItemVisibilityPriorityCompare = function(lhs, rhs) return info.index; } +/* + Returns the toolbar items sorted by their visibilityPriority(ies). +*/ - (CPArray)itemsSortedByVisibilityPriority { return _itemsSortedByVisibilityPriority; @@ -251,6 +332,7 @@ var _CPToolbarItemInfoMake = function(anIndex, aView, aLabel, aMinWidth) return { index:anIndex, view:aView, label:aLabel, minWidth:aMinWidth }; } +/* @ignore */ @implementation _CPToolbarView : CPView { CPToolbar _toolbar; diff --git a/AppKit/CPToolbarItem.j b/AppKit/CPToolbarItem.j index 1a3dc9926a..454b21e080 100644 --- a/AppKit/CPToolbarItem.j +++ b/AppKit/CPToolbarItem.j @@ -26,10 +26,25 @@ import import import - +/* + @global + @class CPToolbarItem +*/ CPToolbarItemVisibilityPriorityStandard = 0; +/* + @global + @class CPToolbarItem +*/ CPToolbarItemVisibilityPriorityLow = -1000; +/* + @global + @class CPToolbarItem +*/ CPToolbarItemVisibilityPriorityHigh = 1000; +/* + @global + @class CPToolbarItem +*/ CPToolbarItemVisibilityPriorityUser = 2000; CPToolbarSeparatorItemIdentifier = @"CPToolbarSeparatorItemIdentifier"; @@ -40,6 +55,9 @@ CPToolbarShowFontsItemIdentifier = @"CPToolbarShowFontsItemIdentifier"; CPToolbarCustomizeToolbarItemIdentifier = @"CPToolbarCustomizeToolbarItemIdentifier"; CPToolbarPrintItemIdentifier = @"CPToolbarPrintItemIdentifier"; +/* + A representation of an item in a CPToolbar. +*/ @implementation CPToolbarItem : CPObject { CPString _itemIdentifier; @@ -63,7 +81,11 @@ CPToolbarPrintItemIdentifier = @"CPToolbarPrintItemIdentifier"; } // Creating a Toolbar Item - +/* + Initializes the toolbar item with a specified identifier. + @param anItemIdentifier the item's identifier + @return the initialized toolbar item +*/ - (id)initWithItemIdentifier:(CPString)anItemIdentifier { self = [super init]; @@ -82,62 +104,105 @@ CPToolbarPrintItemIdentifier = @"CPToolbarPrintItemIdentifier"; } // Managing Attributes - +/* + Returns the item's identifier. +*/ - (CPString)itemIdentifier { return _itemIdentifier; } +/* + Returns the toolbar of which this item is a part. +*/ - (CPToolbar)toolbar { return _toolbar; } +/* + Returns the item's label +*/ - (CPString)label { return _label; } +/* + Sets the item's label. + @param aLabel the new label for the item +*/ - (void)setLabel:(CPString)aLabel { _label = aLabel; } +/* + Returns the palette label. +*/ - (CPString)paletteLabel { return _paletteLabel; } +/* + Sets the palette label + @param aPaletteLabel the new palette label +*/ - (void)setPaletteLabel:(CPString)aPaletteLabel { _paletteLabel = aPaletteLabel; } +/* + Returns the item's tooltip. A tooltip pops up + next to the cursor when the user hovers over + the item with the mouse. +*/ - (CPString)toolTip { return _toolTip; } +/* + Sets the item's tooltip. A tooltip pops up next to the cursor when the user hovers over the item with the mouse. + @param aToolTip the new item tool tip +*/ - (void)setToolTip:(CPString)aToolTip { _toolTip = aToolTip; } +/* + Returns the item's tag. +*/ - (int)tag { return _tag; } +/* + Sets the item's tag. + @param aTag the new tag for the item +*/ - (void)setTag:(int)aTag { _tag = aTag; } +/* + Returns the item's action target. +*/ - (id)target { return _target; } +/* + Sets the target of the action that is triggered when the user clicks this item. nil will cause + the action to be passed on to the first responder. + @param aTarget the new target +*/ - (void)setTarget:(id)aTarget { _target = aTarget; @@ -145,11 +210,18 @@ CPToolbarPrintItemIdentifier = @"CPToolbarPrintItemIdentifier"; [_view setTarget:aTarget]; } +/* + Returns the action that is triggered when the user clicks this item. +*/ - (SEL)action { return _action; } +/* + Sets the action that is triggered when the user clicks this item. + @param anAction the new action +*/ - (void)setAction:(SEL)anAction { _action = anAction; @@ -157,21 +229,35 @@ CPToolbarPrintItemIdentifier = @"CPToolbarPrintItemIdentifier"; [_view setAction:anAction]; } +/* + Returns YES if the item is enabled. +*/ - (BOOL)isEnabled { return _isEnabled; } +/* + Sets whether the item is enabled. + @param aFlag YES enables the item +*/ - (void)setEnabled:(BOOL)aFlag { _isEnabled = aFlag; } +/* + Returns the item's image +*/ - (CPImage)image { return _image; } +/* + Sets the item's image. + @param anImage the new item image +*/ - (void)setImage:(CPImage)anImage { _image = anImage; @@ -179,6 +265,10 @@ CPToolbarPrintItemIdentifier = @"CPToolbarPrintItemIdentifier"; [_view setImage:anImage]; } +/* + Sets the alternate image. This image is displayed on the item when the user is clicking it. + @param anImage the new alternate image +*/ - (void)setAlternateImage:(CPImage)anImage { _alternateImage = anImage; @@ -186,48 +276,90 @@ CPToolbarPrintItemIdentifier = @"CPToolbarPrintItemIdentifier"; [_view setAlternateImage:anImage]; } +/* + Returns the alternate image. This image is displayed on the item when the user is clicking it. +*/ - (CPImage)alternateImage { return _alternateImage; } +/* + Returns the item's view. +*/ - (CPView)view { return _view; } +/* + Sets the item's view + @param aView the item's new view +*/ - (void)setView:(CPView)aView { _view = aView; } +/* + Returns the item's minimum size. +*/ - (CGSize)minSize { return _minSize; } +/* + Sets the item's minimum size. + @param aMinSize the new minimum size +*/ - (void)setMinSize:(CGSize)aMinSize { _minSize = CGSizeCreateCopy(aMinSize); } +/* + Returns the item's maximum size. +*/ - (CGSize)maxSize { return _maxSize; } +/* + Sets the item's new maximum size. + @param aMaxSize the new maximum size +*/ - (void)setMaxSize:(CGSize)aMaxSize { _maxSize = CGSizeCreateCopy(aMaxSize); } // Visibility Priority - +/* + Returns the item's visibility priority. The value will be one of: +
+CPToolbarItemVisibilityPriorityStandard
+CPToolbarItemVisibilityPriorityLow
+CPToolbarItemVisibilityPriorityHigh
+CPToolbarItemVisibilityPriorityUser
+
+*/ - (int)visibilityPriority { return _visibilityPriority; } +/* + Sets the item's visibility priority. The value must be one of: +
+CPToolbarItemVisibilityPriorityStandard
+CPToolbarItemVisibilityPriorityLow
+CPToolbarItemVisibilityPriorityHigh
+CPToolbarItemVisibilityPriorityUser
+
+ @param aVisiblityPriority the priority +*/ - (void)setVisibilityPriority:(int)aVisibilityPriority { _visibilityPriority = aVisibilityPriority; @@ -270,6 +402,7 @@ CPToolbarPrintItemIdentifier = @"CPToolbarPrintItemIdentifier"; @implementation CPToolbarItem (Standard) +/* @ignore */ + (CPToolbarItem)_standardItemWithItemIdentifier:(CPString)anItemIdentifier { var item = [[CPToolbarItem alloc] initWithItemIdentifier:anItemIdentifier]; diff --git a/AppKit/CPView.j b/AppKit/CPView.j index 51cf412de8..e72a2cec74 100644 --- a/AppKit/CPView.j +++ b/AppKit/CPView.j @@ -65,6 +65,20 @@ var DOMCanvasElementZIndex = -1, BackgroundNinePartImage = 3; #endif +/* + CPView is an abstract class which provides facilities for drawing + in a window and receiving events. It is the superclass of many of the visual + elements of the GUI.

+ +

In order to display itself, a view must be placed in a window (represented by an + CPWindow object). Within the window is a hierarchy of CPViews, + headed by the window's content view. Every other view in a window is a descendant + of this view.

+ +

Subclasses can override -drawRect: in order to implement their + appearance. Other methods of CPView and CPResponder can + also be overridden to handle user generated events. +*/ @implementation CPView : CPResponder { CPWindow _window; @@ -115,6 +129,10 @@ var DOMCanvasElementZIndex = -1, _CPViewFullScreenModeState _fullScreenModeState; } +/* + Private method for Objective-J. + @ignore +*/ + (void)initialize { if (self != [CPView class]) @@ -134,7 +152,11 @@ var DOMCanvasElementZIndex = -1, _CPViewNotificationCenter = [CPNotificationCenter defaultCenter]; } -- (id)initWithFrame:(CPRect)aFrame +/* + Initializes the receiver for usage with the specified bounding rectangle + @return the initialized view +*/ +- (id)initWithFrame:(CGRect)aFrame { self = [super init]; @@ -173,26 +195,47 @@ var DOMCanvasElementZIndex = -1, return self; } +/* + Returns the container view of the receiver + @return the receiver's containing view +*/ - (CPView)superview { return _superview; } +/* + Returns an array of all the views contained as direct children of the receiver + @return an array of CPViews +*/ - (CPArray)subviews { return _subviews; } +/* + Returns the window containing this receiver +*/ - (CPWindow)window { return _window; } +/* + Makes the argument a subview of the receiver. + @param aSubview the CPView to make a subview +*/ - (void)addSubview:(CPView)aSubview { [self _insertSubview:aSubview atIndex:CPNotFound]; } +/* + Makes aSubview a subview of the receiver. It is positioned relative to anotherView + @param aSubview the view to add as a subview + @param anOrderingMode specifies aSubview's ordering relative to anotherView + @param anotherView aSubview will be positioned relative to this argument +*/ - (void)addSubview:(CPView)aSubview positioned:(CPWindowOrderingMode)anOrderingMode relativeTo:(CPView)anotherView { var index = anotherView ? [_subviews indexOfObjectIdenticalTo:anotherView] : CPNotFound; @@ -208,6 +251,7 @@ var DOMCanvasElementZIndex = -1, [self _insertSubview:aSubview atIndex:index]; } +/* @ignore */ - (void)_insertSubview:(CPView)aSubview atIndex:(int)anIndex { // We will have to adjust the z-index of all views starting at this index. @@ -270,10 +314,18 @@ var DOMCanvasElementZIndex = -1, [self didAddSubview:aSubview]; } +/* + Called when the receiver has added aSubview to it's child views. + @param aSubview the view that was added +*/ - (void)didAddSubview:(CPView)aSubview { } +/* + Removes the receiver from it's container view and window. + Does nothing if there's no container view. +*/ - (void)removeFromSuperview { if (!_superview) @@ -291,6 +343,11 @@ var DOMCanvasElementZIndex = -1, [self _setWindow:nil]; } +/* + Replaces the specified child view with another view + @param aSubview the view to replace + @param aView the replacement view +*/ - (void)replaceSubview:(CPView)aSubview with:(CPView)aView { if (aSubview._superview != self) @@ -303,6 +360,7 @@ var DOMCanvasElementZIndex = -1, [aView _insertSubview:aView atIndex:index]; } +/* @ignore */ - (void)_setWindow:(CPWindow)aWindow { // FIXME: check _window == aWindow? If not, comment why! @@ -318,6 +376,10 @@ var DOMCanvasElementZIndex = -1, [self viewDidMoveToWindow]; } +/* + Returns YES if the receiver is, or is a descendant of, aView. + @param aView the view to test for ancestry +*/ - (BOOL)isDescendantOf:(CPView)aView { var view = self; @@ -331,28 +393,50 @@ var DOMCanvasElementZIndex = -1, return NO; } +/* + Called when the receiver's superview has changed. +*/ - (void)viewDidMoveToSuperview { if (_graphicsContext) [self setNeedsDisplay:YES]; } +/* + Called when the receiver has been moved to a new CPWindow. +*/ - (void)viewDidMoveToWindow { } +/* + Called when the receiver is about to be moved to a new view. + @param aView the view to which the receiver will be moved +*/ - (void)viewWillMoveToSuperview:(CPView)aView { } +/* + Called when the receiver is about to be moved to a new window. + @param aWindow the window to which the receiver will be moved. +*/ - (void)viewWillMoveToWindow:(CPWindow)aWindow { } +/* + Called when the receiver is about to be remove one of its subviews. + @param aView the view that will be removed +*/ - (void)willRemoveSubview:(CPView)aView { } +/* + Returns the menu item containing the receiver or one of its ancestor views. + @return a menu item, or nil if the view or one of its ancestors wasn't found +*/ - (CPMenuItem)enclosingMenuItem { var view = self; @@ -373,12 +457,23 @@ var DOMCanvasElementZIndex = -1, return enclosingMenuItem;*/ } +/* + Returns whether the view is flipped. + @return YES if the view is flipped. NO, otherwise. +*/ - (BOOL)isFlipped { return YES; } -- (void)setFrame:(CPRect)aFrame +/* + Sets the frame size of the receiver to the dimensions and origin of the provided rectangle in the coordinate system + of the superview. The method also posts an CPViewFrameDidChangeNotification to the notification + center if the receiver is configured to do so. If the frame is the same as the current frame, the method simply + returns (and no notificaion is posted). + @param aFrame the rectangle specifying the new origin and size of the receiver +*/ +- (void)setFrame:(CGRect)aFrame { if (_CGRectEqualToRect(_frame, aFrame)) return; @@ -394,12 +489,23 @@ var DOMCanvasElementZIndex = -1, [_CPViewNotificationCenter postNotificationName:CPViewFrameDidChangeNotification object:self]; } +/* + Returns the receiver's frame. + @return a copy of the receiver's frame +*/ - (CGRect)frame { return _CGRectMakeCopy(_frame); } -- (void)setFrameOrigin:(CPPoint)aPoint +/* + Sets the receiver's frame origin to the provided point. The point is defined in the superview's coordinate system. + The method posts a CPViewFrameDidChangeNotification to the default notification center if the receiver + is configured to do so. If the specified origin is the same as the frame's current origin, the method will + simply return (and no notification will be posted). + @param aPoint the new origin point +*/ +- (void)setFrameOrigin:(CGPoint)aPoint { var origin = _frame.origin; @@ -417,6 +523,12 @@ var DOMCanvasElementZIndex = -1, #endif } +/* + Sets the receiver's frame size. If aSize is the same as the frame's current dimensions, this + method simply returns. The method posts a CPViewFrameDidChangeNotification to the + default notification center if the receiver is configured to do so. + @param aSize the new size for the frame +*/ - (void)setFrameSize:(CGSize)aSize { var size = _frame.size; @@ -476,6 +588,11 @@ var DOMCanvasElementZIndex = -1, #endif } +/* + Sets the receiver's bounds. The bounds define the size and location of the receiver inside it's frame. Posts a + CPViewBoundsDidChangeNotification to the default notification center if the receiver is configured to do so. + @param bounds the new bounds +*/ - (void)setBounds:(CGRect)bounds { if (_CGRectEqualToRect(_bounds, bounds)) @@ -492,11 +609,21 @@ var DOMCanvasElementZIndex = -1, [_CPViewNotificationCenter postNotificationName:CPViewBoundsDidChangeNotification object:self]; } +/* + Returns the receiver's bounds. The bounds define the size + and location of the receiver inside its frame. +*/ - (CGRect)bounds { return _CGRectMakeCopy(_bounds); } +/* + Sets the location of the receiver inside its frame. The method + posts a CPViewBoundsDidChangeNotification to the + default notification center if the receiver is configured to do so. + @param aPoint the new location for the receiver +*/ - (void)setBoundsOrigin:(CGPoint)aPoint { var origin = _bounds.origin; @@ -534,6 +661,12 @@ var DOMCanvasElementZIndex = -1, [_CPViewNotificationCenter postNotificationName:CPViewBoundsDidChangeNotification object:self]; } +/* + Sets the receiver's size inside its frame. The method posts a + CPViewBoundsDidChangeNotification to the default + notification center if the receiver is configured to do so. + @param aSize the new size for the receiver +*/ - (void)setBoundsSize:(CGSize)aSize { var size = _bounds.size; @@ -566,7 +699,12 @@ var DOMCanvasElementZIndex = -1, [_CPViewNotificationCenter postNotificationName:CPViewBoundsDidChangeNotification object:self]; } -- (void)resizeWithOldSuperviewSize:(CPSize)aSize + +/* + Notifies subviews that the superview changed size. + @param aSize the size of the old superview +*/ +- (void)resizeWithOldSuperviewSize:(CGSize)aSize { var mask = _autoresizingMask; @@ -593,7 +731,11 @@ var DOMCanvasElementZIndex = -1, [self setFrame:newFrame]; } -- (void)resizeSubviewsWithOldSize:(CPSize)aSize +/* + Initiates superviewSizeChanged: messages to subviews. + @param aSize the size for the subviews +*/ +- (void)resizeSubviewsWithOldSize:(CGSize)aSize { var count = _subviews.length; @@ -601,28 +743,50 @@ var DOMCanvasElementZIndex = -1, [_subviews[count] resizeWithOldSuperviewSize:aSize]; } +/* + Specifies whether the receiver view should automatically resize its + subviews when its setFrameSize: method receives a change. + @param aFlag If YES, then subviews will automatically be resized + when this view is resized. NO means the views will not + be resized automatically. +*/ - (void)setAutoresizesSubviews:(BOOL)aFlag { _autoresizesSubviews = aFlag; } +/* + Reports whether the receiver automatically resizes its subviews when its frame size changes. + @return YES means it resizes its subviews on a frame size change. +*/ - (BOOL)autoresizesSubviews { return _autoresizesSubviews; } +/* + Determines automatic resizing behavior. + @param aMask a bit mask with options +*/ - (void)setAutoresizingMask:(unsigned)aMask { _autoresizingMask = aMask; } +/* + Returns the bit mask options for resizing behavior +*/ - (unsigned)autoresizingMask { return _autoresizingMask; } // Fullscreen Mode - +/* + Puts the receiver into full screen mode. + @param aScreen the that should be used + @param options configuration options +*/ - (BOOL)enterFullScreenMode:(CPScreen)aScreen withOptions:(CPDictionary)options { _fullScreenModeState = _CPViewFullScreenModeStateMake(self); @@ -649,6 +813,10 @@ var DOMCanvasElementZIndex = -1, return YES; } +/* + The receiver should exit full screen mode. + @param options configurations options +*/ - (void)exitFullScreenModeWithOptions:(CPDictionary)options { if (!_isInFullScreenMode) @@ -663,11 +831,18 @@ var DOMCanvasElementZIndex = -1, [[self window] orderOut:self]; } +/* + Returns YES if the receiver is currently in full screen mode. +*/ - (BOOL)isInFullScreenMode { return _isInFullScreenMode; } +/* + Sets whether the receiver should be hidden. + @param aFlag YES makes the receiver hidden. +*/ - (void)setHidden:(BOOL)aFlag { if(_isHidden == aFlag) @@ -680,11 +855,19 @@ var DOMCanvasElementZIndex = -1, #endif } +/* + Returns YES if the receiver is hidden. +*/ - (BOOL)isHidden { return _isHidden; } +/* + Sets the opacity of the receiver. The value must be in the range of 0.0 to 1.0, where 0.0 is + completely transparent and 1.0 is completely opaque. + @param anAlphaValue an alpha value ranging from 0.0 to 1.0. +*/ - (void)setAlphaValue:(float)anAlphaValue { if (_opacity == anAlphaValue) @@ -702,21 +885,19 @@ var DOMCanvasElementZIndex = -1, #endif } +/* + Returns the alpha value of the receiver. Ranges from 0.0 to + 1.0, where 0.0 is completely transparent and 1.0 is completely opaque. +*/ - (float)alphaValue { return _opacity; } -- (void)setOpacity:(float)anOpacity -{ - [self setAlphaValue:anOpacity]; -} - -- (float)opacity -{ - return _opacity; -} - +/* + Returns YES if the receiver is hidden, or one + of it's ancestor views is hidden. NO, otherwise. +*/ - (BOOL)isHiddenOrHasHiddenAncestor { var view = self; @@ -727,21 +908,36 @@ var DOMCanvasElementZIndex = -1, return view != nil; } +/* + Returns whether the receiver should be sent a mouseDown: message for anEvent.
+ Returns YES by default. + @return YES, if the view object accepts first mouse-down event. NO, otherwise. +*/ +//FIXME: should be NO by default? - (BOOL)acceptsFirstMouse:(CPEvent)anEvent { return YES; } +/* + @ignore +*/ - (BOOL)hitTests { return YES; } +/* + @ignore +*/ - (void)setHitTests:(BOOL)shouldHitTest { _hitTests = shouldHitTest; } +/* + @ignore +*/ - (CPView)hitTest:(CPPoint)aPoint { if(_isHidden || !_hitTests || !CPRectContainsPoint(_frame, aPoint)) @@ -761,6 +957,10 @@ var DOMCanvasElementZIndex = -1, return self; } +/* + Returns YES if mouse events aren't needed by the receiver and can be sent to the superview. The + default implementation returns NO if the view is opaque. +*/ - (BOOL)mouseDownCanMoveWindow { return ![self isOpaque]; @@ -772,6 +972,10 @@ var DOMCanvasElementZIndex = -1, [super mouseDown:anEvent]; } +/* + Sets the background color of the receiver. + @param aColor the new color for the receiver's background +*/ - (void)setBackgroundColor:(CPColor)aColor { if (_backgroundColor == aColor) @@ -883,43 +1087,93 @@ var DOMCanvasElementZIndex = -1, #endif } +/* + Returns the background color of the receiver +*/ - (CPColor)backgroundColor { return _backgroundColor; } // Converting Coordinates - +/* + Converts aPoint from the coordinate space of aView to the coordinate space of the receiver. + @param aPoint the point to convert + @param aView the view space to convert from + @return the converted point +*/ - (CGPoint)convertPoint:(CGPoint)aPoint fromView:(CPView)aView { return CGPointApplyAffineTransform(aPoint, _CPViewGetTransform(aView, self)); } +/* + Converts aPoint from the receiver's coordinate space to the coordinate space of aView. + @param aPoint the point to convert + @param aView the coordinate space to which the point will be converted + @return the converted point +*/ - (CGPoint)convertPoint:(CGPoint)aPoint toView:(CPView)aView { return CGPointApplyAffineTransform(aPoint, _CPViewGetTransform(self, aView)); } +/* + Convert's aSize from aView's coordinate space to the receiver's coordinate space. + @param aSize the size to convert + @param aView the coordinate space to convert from + @return the converted size +*/ - (CGSize)convertSize:(CGSize)aSize fromView:(CPView)aView { return CGSizeApplyAffineTransform(aSize, _CPViewGetTransform(aView, self)); } +/* + Convert's aSize from the receiver's coordinate space to aView's coordinate space. + @param aSize the size to convert + @param the coordinate space to which the size will be converted + @return the converted size +*/ - (CGSize)convertSize:(CGSize)aSize toView:(CPView)aView { return CGSizeApplyAffineTransform(aSize, _CPViewGetTransform(self, aView)); } +/* + Converts aRect from aView's coordinate space to the receiver's space. + @param aRect the rectangle to convert + @param aView the coordinate space from which to convert + @return the converted rectangle +*/ - (CGRect)convertRect:(CGRect)aRect fromView:(CPView)aView { return CGRectApplyAffineTransform(aRect, _CPViewGetTransform(aView, self)); } - + +/* + Converts aRect from the receiver's coordinate space to aView's coordinate space. + @param aRect the rectangle to convert + @param aView the coordinate space to which the rectangle will be converted + @return the converted rectangle +*/ - (CGRect)convertRect:(CGRect)aRect toView:(CPView)aView { return CGRectApplyAffineTransform(aRect, _CPViewGetTransform(self, aView)); } +/* + Sets whether the receiver posts a CPViewFrameDidChangeNotification notification + to the default notification center when its frame is changed. The default is NO. + Methods that could cause a frame change notification are: +

+setFrame:
+setFrameSize:
+setFrameOrigin:
+
+ @param shouldPostFrameChangedNotifications YES makes the receiver post + notifications on frame changes (size or origin) +*/ - (void)setPostsFrameChangedNotifications:(BOOL)shouldPostFrameChangedNotifications { if (_postsFrameChangedNotifications == shouldPostFrameChangedNotifications) @@ -931,11 +1185,26 @@ var DOMCanvasElementZIndex = -1, [_CPViewNotificationCenter postNotificationName:CPViewFrameDidChangeNotification object:self]; } +/* + Returns YES if the receiver posts a CPViewFrameDidChangeNotification if its frame is changed. +*/ - (BOOL)postsFrameChangedNotifications { return _postsFrameChangedNotifications; } +/* + Sets whether the receiver posts a CPViewBoundsDidChangeNotification notification + to the default notification center when its bounds is changed. The default is NO. + Methods that could cause a bounds change notification are: +
+setBounds:
+setBoundsSize:
+setBoundsOrigin:
+
+ @param shouldPostBoundsChangedNotifications YES makes the receiver post + notifications on bounds changes +*/ - (void)setPostsBoundsChangedNotifications:(BOOL)shouldPostBoundsChangedNotifications { if (_postsBoundsChangedNotifications == shouldPostBoundsChangedNotifications) @@ -947,45 +1216,85 @@ var DOMCanvasElementZIndex = -1, [_CPViewNotificationCenter postNotificationName:CPViewBoundsDidChangeNotification object:self]; } +/* + Returns YES if the receiver posts a + CPViewBoundsDidChangeNotification when its + bounds is changed. +*/ - (BOOL)postsBoundsChangedNotifications { return _postsBoundsChangedNotifications; } -- (void)dragImage:(CPImage)anImage at:(CPPoint)aLocation offset:(CPSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack +/* + Initiates a drag operation from the receiver to another view that accepts dragged data. + @param anImage the image to be dragged + @param aLocation the lower-left corner coordinate of anImage + @param mouseOffset the distance from the mouseDown: location and the current location + @param anEvent the mouseDown: that triggered the drag + @param aPastebaord the pasteboard that holds the drag data + @param aSourceObject the drag operation controller + @param slideBack Whether the image should 'slide back' if the drag is rejected +*/ +- (void)dragImage:(CPImage)anImage at:(CGPoint)aLocation offset:(CGSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack { [_window dragImage:anImage at:[self convertPoint:aLocation toView:nil] offset:mouseOffset event:anEvent pasteboard:aPasteboard source:aSourceObject slideBack:slideBack]; } +/* + Initiates a drag operation from the receiver to another view that accepts dragged data. + @param aView the view to be dragged + @param aLocation the lower-left corner coordinate of aView + @param mouseOffset the distance from the mouseDown: location and the current location + @param anEvent the mouseDown: that triggered the drag + @param aPastebaord the pasteboard that holds the drag data + @param aSourceObject the drag operation controller + @param slideBack Whether the view should 'slide back' if the drag is rejected +*/ - (void)dragView:(CPView)aView at:(CPPoint)aLocation offset:(CPSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack { [_window dragView:aView at:[self convertPoint:aLocation toView:nil] offset:mouseOffset event:anEvent pasteboard:aPasteboard source:aSourceObject slideBack:slideBack]; } +/* + Sets the receiver's list of acceptable data types for a dragging operation. + @param pasteboardTypes an array of CPPasteboards +*/ - (void)registerForDraggedTypes:(CPArray)pasteboardTypes { _registeredDraggedTypes = [pasteboardTypes copy]; } +/* + Returns an array of all types the receiver accepts for dragging operations. + @return an array of CPPasteBoards +*/ - (CPArray)registeredDraggedTypes { return _registeredDraggedTypes; } +/* + Resets the array of acceptable data types for a dragging operation. +*/ - (void)unregisterDraggedTypes { _registeredDraggedTypes = nil; } -// - +/* + Draws the receiver into aRect. This method should be overridden by subclasses. + @param aRect the area that should be drawn into +*/ - (void)drawRect:(CPRect)aRect { } // Focus - +/* + Locks focus on the receiver, so drawing commands apply to it. +*/ - (void)lockFocus { // If we don't yet have a graphics context, then we must first create a @@ -1018,6 +1327,9 @@ var DOMCanvasElementZIndex = -1, CGContextSaveGState([_graphicsContext graphicsPort]); } +/* + Takes focus away from the receiver, and restores it to the previous view. +*/ - (void)unlockFocus { var graphicsPort = [_graphicsContext graphicsPort]; @@ -1028,39 +1340,61 @@ var DOMCanvasElementZIndex = -1, } // Displaying - +/* + Marks the entire view as dirty, and needing a redraw. +*/ - (void)setNeedsDisplay:(BOOL)aFlag { if (aFlag) [self display]; } -- (void)setNeedsDisplayInRect:(CPRect)aRect +/* + Marks the area denoted by aRect as dirty, and initiates a redraw on it. + @param aRect the area that needs to be redrawn +*/ +- (void)setNeedsDisplayInRect:(CGRect)aRect { [self displayRect:aRect]; } +/* + Displays the receiver and any of its subviews that need to be displayed. +*/ - (void)displayIfNeeded { } +/* + Draws the entire area of the receiver as defined by its bounds. +*/ - (void)display { [self displayRect:_bounds]; } -- (void)displayRect:(CPRect)aRect +/* + Draws the receiver into the area defined by aRect. + @param aRect the area to be drawn +*/ +- (void)displayRect:(CGRect)aRect { [self lockFocus]; [self drawRect:aRect]; [self unlockFocus]; } +/* + Returns whether the receiver is completely opaque. By default, returns NO. +*/ - (BOOL)isOpaque { return NO; } +/* + Returns the rectangle of the receiver not clipped by its superview. +*/ - (CGRect)visibleRect { if (!_superview) @@ -1070,7 +1404,7 @@ var DOMCanvasElementZIndex = -1, } // Scrolling - +/* @ignore */ - (CPScrollView)_enclosingClipView { var superview = _superview, @@ -1082,6 +1416,10 @@ var DOMCanvasElementZIndex = -1, return superview; } +/* + Changes the receiver's frame origin to a 'constrained' aPoint. + @param aPoint the proposed frame origin +*/ - (void)scrollPoint:(CGPoint)aPoint { var clipView = [self _enclosingClipView]; @@ -1092,6 +1430,11 @@ var DOMCanvasElementZIndex = -1, [clipView scrollToPoint:[self convertPoint:aPoint toView:clipView]]; } +/* + Scrolls the nearest ancestor CPClipView a minimum amount so aRect can become visible. + @param aRect the area to become visible + @return if any scrolling occurred, NO otherwise. +*/ - (BOOL)scrollRectToVisible:(CGRect)aRect { var visibleRect = [self visibleRect]; @@ -1127,22 +1470,38 @@ var DOMCanvasElementZIndex = -1, return YES; } +/* + FIXME Not yet implemented +*/ - (BOOL)autoscroll:(CPEvent)anEvent { // FIXME: Implement. return NO; } +/* + Subclasses can override this to modify the visible rectangle after a + scrolling operation. The default implementation simply returns the provided rectangle. + @param proposedVisibleRect the rectangle to alter + @return the same adjusted rectangle +*/ - (CGRect)adjustScroll:(CGRect)proposedVisibleRect { return proposedVisibleRect; } +/* + Should be overridden by subclasses. +*/ - (void)scrollRect:(CGRect)aRect by:(float)anAmount { } +/* + Returns the CPScrollView containing the receiver. + @return the CPScrollView containing the receiver. +*/ - (CPScrollView)enclosingScrollView { var superview = _superview, @@ -1154,11 +1513,21 @@ var DOMCanvasElementZIndex = -1, return superview; } +/* + Scrolls the clip view to a specified point + @param the clip view to scoll + @param the point to scroll to +*/ - (void)scrollClipView:(CPClipView)aClipView toPoint:(CGPoint)aPoint { [aClipView scrollToPoint:aPoint]; } +/* + Notifies the receiver (superview of a CPClipView) + that the clip view bounds or the document view bounds have changed. + @param aClipView the clip view of the superview being notified +*/ - (void)reflectScrolledClipView:(CPClipView)aClipView { } @@ -1167,6 +1536,9 @@ var DOMCanvasElementZIndex = -1, @implementation CPView (CoreAnimationAdditions) +/* + Sets the core animation layer to be used by this receiver. +*/ - (void)setLayer:(CALayer)aLayer { if (_layer == aLayer) @@ -1196,17 +1568,28 @@ var DOMCanvasElementZIndex = -1, } } +/* + Returns the core animation layer used by the receiver. +*/ - (CALayer)layer { return _layer; } +/* + Sets whether the receiver wants a core animation layer. + @param YES means the receiver wants a layer. +*/ - (void)setWantsLayer:(BOOL)aFlag { _wantsLayer = aFlag; } -- (CALayer)wantsLayer +/* + Returns YES if the receiver uses a CALayer + @returns YES if the receiver uses a CALayer +*/ +- (BOOL)wantsLayer { return _wantsLayer; } @@ -1227,9 +1610,14 @@ var CPViewAutoresizingMaskKey = @"CPViewAutoresizingMask", @implementation CPView (CPCoding) +/* + Initializes the view from an archive. + @param aCoder the coder from which to initialize + @return the initialized view +*/ - (id)initWithCoder:(CPCoder)aCoder { - // We create the DOMElement "early" because there is a change that we + // We create the DOMElement "early" because there is a chance that we // will decode our superview before we are done decoding, at which point // we have to have an element to place in the tree. Perhaps there is // a more "elegant" way to do this...? @@ -1279,6 +1667,10 @@ var CPViewAutoresizingMaskKey = @"CPViewAutoresizingMask", return self; } +/* + Archives the view to a coder. + @param aCoder the object into which the view's data will be archived. +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [super encodeWithCoder:aCoder]; diff --git a/AppKit/CPWindow.j b/AppKit/CPWindow.j index 8f98cb5032..0383b0cd9e 100644 --- a/AppKit/CPWindow.j +++ b/AppKit/CPWindow.j @@ -33,14 +33,51 @@ import "CPResponder.j" #include "CoreGraphics/CGGeometry.h" +/* + Borderless window mask option. + @global + @class CPWindow +*/ CPBorderlessWindowMask = 0; +/* + Titled window mask option. + @global + @class CPWindow +*/ CPTitledWindowMask = 1 << 0; +/* + Closeable window mask option. + @global + @class CPWindow +*/ CPClosableWindowMask = 1 << 1; +/* + Miniaturizabe window mask option. + @global + @class CPWindow +*/ CPMiniaturizableWindowMask = 1 << 2; +/* + Resizable window mask option. + @global + @class CPWindow +*/ CPResizableWindowMask = 1 << 3; +/* + Textured window mask option. + @global + @class CPWindow +*/ CPTexturedBackgroundWindowMask = 1 << 8; - +/* + @global + @class CPWindow +*/ CPBorderlessBridgeWindowMask = 1 << 20; +/* + @global + @class CPWindow +*/ CPHUDBackgroundWindowMask = 1 << 21; CPWindowNotSizable = 0; @@ -51,19 +88,84 @@ CPWindowMinYMargin = 8; CPWindowHeightSizable = 16; CPWindowMaxYMargin = 32; +/* + Default level for windows + @group CPWindowLevel + @global +*/ CPNormalWindowLevel = 4; +/* + Floating palette type window + @group CPWindowLevel + @global +*/ CPFloatingWindowLevel = 5; +/* + Submenu type window + @group CPWindowLevel + @global +*/ CPSubmenuWindowLevel = 6; +/* + For a torn-off menu + @group CPWindowLevel + @global +*/ CPTornOffMenuWindowLevel = 6; +/* + For the application's main menu + @group CPWindowLevel + @global +*/ CPMainMenuWindowLevel = 8; +/* + Status window level + @group CPWindowLevel + @global +*/ CPStatusWindowLevel = 9; +/* + Level for a modal panel + @group CPWindowLevel + @global +*/ CPModalPanelWindowLevel = 10; +/* + Level for a pop up menu + @group CPWindowLevel + @global +*/ CPPopUpMenuWindowLevel = 11; +/* + Level for a window being dragged + @group CPWindowLevel + @global +*/ CPDraggingWindowLevel = 12; +/* + Level for the screens saver + @group CPWindowLevel + @global +*/ CPScreenSaverWindowLevel = 13; +/* + The receiver is removed from the screen list and hidden. + @global + @class CPWindowOrderingMode +*/ CPWindowOut = 0; +/* + The receiver is placed directly in front of the window specified. + @global + @class CPWindowOrderingMode +*/ CPWindowAbove = 1; +/* + The receiver is placed directly behind the window specified. + @global + @class CPWindowOrderingMode +*/ CPWindowBelow = 2; CPWindowWillCloseNotification = @"CPWindowWillCloseNotification"; @@ -82,6 +184,47 @@ var SHADOW_MARGIN_LEFT = 20.0, var CPWindowSaveImage = nil, CPWindowSavingImage = nil; +/* + An CPWindow instance represents a window, panel or menu on the screen.

+ +

Each window has a style, which determines how the window is decorated; whether it has a border, a title bar, a resize bar, minimise and close buttons.

+ +

A window has a frame. This is the frame of the entire window on the screen, including all decorations and borders. The origin of the frame represents its bottom left corner and the frame is expressed in screen coordinates.

+ +

A window always contains a content view which is the highest level view available for public (application) use. This view fills the area of the window inside any decoration/border. This is the only part of the window that application programmers are allowed to draw in directly.

+ +

You can convert between view coordinates and window base coordinates using the [CPView -convertPoint:fromView:], [CPView -convertPoint:toView:], [CPView -convertRect:fromView:], and [CPView -convertRect:toView:] methods with a nil view argument. + + @delegate -(void)windowDidResize:(CPNotification)notification; + Sent from the notification center when the window has been resized. + @param notification contains information about the resize event + + @delegate -(CPUndoManager)windowWillReturnUndoManager:(CPWindow)window; + Called to obtain the undo manager for a window + @param window the window for which to return the undo manager + @return the window's undo manager + + @delegate -(void)windowDidBecomeMain:(CPNotification)notification; + Sent from the notification center when the delegate's window becomes + the main window. + @param notification contains information about the event + + @delegate -(void)windowDidResignMain:(CPNotification)notification; + Sent from the notification center when the delegate's window has + resigned main window status. + @param notification contains information about the event + + @delegate -(void)windowDidResignKey:(CPNotification)notification; + Sent from the notification center when the delegate's window has + resigned key window status. + @param notification contains information about the event + + @delegate -(BOOL)windowShouldClose:(id)window; + Called when the user tries to close the window. + @param window the window to close + @return YES allows the window to close. NO + vetoes the close operation and leaves the window open. +*/ @implementation CPWindow : CPResponder { int _windowNumber; @@ -133,6 +276,10 @@ var CPWindowSaveImage = nil, BOOL _delegateRespondsToWindowWillReturnUndoManagerSelector; } +/* + Private initializer for Objective-J + @ignore +*/ + (void)initialize { if (self != [CPWindow class]) @@ -145,11 +292,43 @@ var CPWindowSaveImage = nil, CPWindowSavingImage = [[CPImage alloc] initWithContentsOfFile:[bundle pathForResource:@"CPProgressIndicator/CPProgressIndicatorSpinningStyleRegular.gif"] size:CGSizeMake(16.0, 16.0)] } +/* + Initializes the window. The method also takes a style bit mask made up + of any of the following values: +

+CPBorderlessWindowMask
+CPTitledWindowMask
+CPClosableWindowMask
+CPMiniaturizableWindowMask
+CPResizableWindowMask
+CPTexturedBackgroundWindowMask
+
+ @param aContentRect the size and location of the window in screen space + @param aStyleMask a style mask + @return the initialized window +*/ - (id)initWithContentRect:(CGRect)aContentRect styleMask:(unsigned int)aStyleMask { return [self initWithContentRect:aContentRect styleMask:aStyleMask bridge:[CPDOMWindowBridge sharedDOMWindowBridge]]; } +/* + Initializes the window. The method also takes a style bit mask made up + of any of the following values: +
+CPBorderlessWindowMask
+CPTitledWindowMask
+CPClosableWindowMask
+CPMiniaturizableWindowMask
+CPResizableWindowMask
+CPTexturedBackgroundWindowMask
+
+ @param aContentRect the size and location of the window in screen space + @param aStyleMask a style mask + @param aBridge a DOM-Window bridge object + @return the initialized window + @ignore +*/ - (id)initWithContentRect:(CGRect)aContentRect styleMask:(unsigned int)aStyleMask bridge:(CPDOMWindowBridge)aBridge { self = [super init]; @@ -205,11 +384,20 @@ var CPWindowSaveImage = nil, return self; } +/* + Returns the window's style mask. +*/ - (unsigned)styleMask { return _styleMask; } +/* + Returns the frame rectangle used by a window. + @param aContentRect the content rectangle of the window + @param aStyleMask the style mask of the window + @return the matching window's frame rectangle +*/ + (CGRect)frameRectForContentRect:(CGRect)aContentRect styleMask:(unsigned)aStyleMask { var frame = CGRectMakeCopy(aContentRect); @@ -217,6 +405,10 @@ var CPWindowSaveImage = nil, return frame; } +/* + Returns the receiver's content rectangle. A content rectangle does not include toolbars. + @param aFrame the window's frame rectangle +*/ - (CGRect)contentRectForFrameRect:(CGRect)aFrame { // FIXME: EXTRA RECT COPY @@ -246,6 +438,11 @@ var CPWindowSaveImage = nil, return contentRect; } +/* + Retrieves the frame rectangle for this window. + @param aContentRect the window's content rectangle + @return the window's frame rectangle +*/ - (CGRect)frameRectForContentRect:(CGRect)aContentRect { if (_styleMask & CPBorderlessBridgeWindowMask) @@ -256,11 +453,21 @@ var CPWindowSaveImage = nil, return frame; } +/* + Returns the window's frame rectangle +*/ - (CGRect)frame { return _frame; } +/* + Sets the window's frame rectangle. Also tells the window whether it should animate + the resize operation, and redraw itself if necessary. + @param aFrame the new size and location for the window + @param shouldDisplay whether the window should redraw its views + @param shouldAnimate whether the window resize should be animated +*/ - (void)setFrame:(CGRect)aFrame display:(BOOL)shouldDisplay animate:(BOOL)shouldAnimate { if (shouldAnimate) @@ -276,11 +483,18 @@ var CPWindowSaveImage = nil, } } +/* + Sets the window's frame rectangle +*/ - (void)setFrame:(CGRect)aFrame { [self setFrame:aFrame display:YES animate:NO]; } +/* + Sets the window's location. + @param anOrigin the new location for the window +*/ - (void)setFrameOrigin:(CGPoint)anOrigin { var origin = _frame.origin; @@ -296,6 +510,10 @@ var CPWindowSaveImage = nil, #endif } +/* + Sets the window's size. + @param aSize the new size for the window +*/ - (void)setFrameSize:(CGSize)aSize { aSize = _CGSizeMake(MIN(MAX(aSize.width, _minSize.width), _maxSize.width), MIN(MAX(aSize.height, _minSize.height), _maxSize.height)); @@ -314,6 +532,9 @@ var CPWindowSaveImage = nil, [_delegate windowDidResize:self]; } +/* + @ignore +*/ - (void)trackMoveWithEvent:(CPEvent)anEvent { var type = [anEvent type]; @@ -336,6 +557,9 @@ var CPWindowSaveImage = nil, [CPApp setTarget:self selector:@selector(trackMoveWithEvent:) forNextEventMatchingMask:CPLeftMouseDraggedMask | CPLeftMouseUpMask untilDate:nil inMode:nil dequeue:YES]; } +/* + @ignore +*/ - (void)trackResizeWithEvent:(CPEvent)anEvent { var location = [anEvent locationInWindow], @@ -353,16 +577,29 @@ var CPWindowSaveImage = nil, [CPApp setTarget:self selector:@selector(trackResizeWithEvent:) forNextEventMatchingMask:CPLeftMouseDraggedMask | CPLeftMouseUpMask untilDate:nil inMode:nil dequeue:YES]; } +/* + Makes the receiver the front most window in the screen ordering. + @param aSender the object that requested this +*/ - (void)orderFront:(id)aSender { [_bridge order:CPWindowAbove window:self relativeTo:nil]; } +/* + Makes the receiver the last window in the screen ordering. + @param aSender the object that requested this + @ignore +*/ - (void)orderBack:(id)aSender { //[_bridge order:CPWindowBelow } +/* + Hides the window. + @param the object that requested this +*/ - (void)orderOut:(id)aSender { if ([_delegate respondsToSelector:@selector(windowWillClose:)]) @@ -378,46 +615,80 @@ var CPWindowSaveImage = nil, } } +/* + Relocates the window in the screen list. + @param aPlace the positioning relative to otherWindowNumber + @param otherWindowNumber the window relative to which the receiver should be placed +*/ - (void)orderWindow:(CPWindowOrderingMode)aPlace relativeTo:(int)otherWindowNumber { [_bridge order:aPlace window:self relativeTo:CPApp._windows[otherWindowNumber]]; } +/* + Sets the window's level + @param the window's new level +*/ - (void)setLevel:(int)aLevel { _level = aLevel; } +/* + Returns the window's current level +*/ - (int)level { return _level; } +/* + Returns YES if the window is visible. It does not mean that the window is not obscured by other windows. +*/ - (BOOL)isVisible { return _isVisible; } +/* + Returns YES if the window's resize indicator is showing. NO otherwise. +*/ - (BOOL)showsResizeIndicator { return [_windowView showsResizeIndicator]; } +/* + Sets the window's resize indicator. + @param shouldShowResizeIndicator YES sets the window to show its resize indicator. +*/ - (void)setShowsResizeIndicator:(BOOL)shouldShowResizeIndicator { [_windowView setShowsResizeIndicator:shouldShowResizeIndicator]; } +/* + Returns the offset of the window's resize indicator. +*/ - (CGSize)resizeIndicatorOffset { return [_windowView resizeIndicatorOffset]; } +/* + Sets the offset of the window's resize indicator. + @param aSize the offset for the resize indicator +*/ - (void)setResizeIndicatorOffset:(CGSize)anOffset { [_windowView setResizeIndicatorOffset:anOffset]; } +/* + Sets the window's content view. The new view will be resized to fit + inside the content rectangle of the window. + @param aView the new content view for the receiver +*/ - (void)setContentView:(CPView)aView { if (_contentView) @@ -430,21 +701,36 @@ var CPWindowSaveImage = nil, [_windowView addSubview:_contentView positioned:CPWindowBelow relativeTo:nil]; } +/* + Returns the window's current content view. +*/ - (CPView)contentView { return _contentView; } +/* + Sets the window's background color. + @param aColor the new color for the background +*/ - (void)setBackgroundColor:(CPColor)aColor { [_windowView setBackgroundColor:aColor]; } +/* + Returns the window's background color. +*/ - (CPColor)backgroundColor { return [_windowView backgroundColor]; } +/* + Sets the window's minimum size. If the provided + size is the same as the current minimum size, the method simply returns. + @aSize the new minimum size for the window +*/ - (void)setMinSize:(CGSize)aSize { if (CGSizeEqualToSize(_minSize, aSize)) @@ -471,11 +757,20 @@ var CPWindowSaveImage = nil, [self setFrameSize:size]; } +/* + Returns the windows minimum size. +*/ - (CGSize)minSize { return _minSize; } +/* + Sets the window's maximum size. If the provided + size is the same as the current maximum size, + the method simply returns. + @param aSize the new maximum size +*/ - (void)setMaxSize:(CGSize)aSize { if (CGSizeEqualToSize(_maxSize, aSize)) @@ -502,16 +797,26 @@ var CPWindowSaveImage = nil, [self setFrameSize:size]; } +/* + Returns the window's maximum size. +*/ - (CGSize)maxSize { return _maxSize; } +/* + Returns YES if the window has a drop shadow. NO otherwise. +*/ - (BOOL)hasShadow { return _hasShadow; } +/* + Sets whether the window should have a drop shadow. + @param shouldHaveShadow YES to have a drop shadow. +*/ - (void)setHasShadow:(BOOL)shouldHaveShadow { if (_hasShadow == shouldHaveShadow) @@ -559,6 +864,10 @@ var CPWindowSaveImage = nil, } } +/* + Sets the delegate for the window. Passing nil will just remove the window's current delegate. + @param aDelegate an object to respond to the various delegate methods of CPWindow +*/ - (void)setDelegate:(id)aDelegate { _delegate = aDelegate; @@ -582,16 +891,26 @@ var CPWindowSaveImage = nil, object:self]; } +/* + Returns window's delegate +*/ - (id)delegate { return _delegate; } -- (void)setWindowController:(CPWindow)aWindowController +/* + Sets the window's controller + @param aWindowController a window controller +*/ +- (void)setWindowController:(CPWindowController)aWindowController { _windowController = aWindowController; } +/* + Returns the window's controller. +*/ - (CPWindowController)windowController { return _windowController; @@ -610,6 +929,13 @@ var CPWindowSaveImage = nil, return YES; } +/* + Attempts to make the aResponder the first responder. Before trying + to make it the first responder, the receiver will ask the current first responder + to resign its first responder status. If it resigns, it will ask + aResponder accept first responder, then finally tell it to become first responder. + @return YES if the attempt was successful. NO otherwise. +*/ - (void)makeFirstResponder:(CPResponder)aResponder { if (_firstResponder == aResponder) @@ -630,6 +956,9 @@ var CPWindowSaveImage = nil, return YES; } +/* + Returns the window's current first responder. +*/ - (CPResponder)firstResponder { return _firstResponder; @@ -647,11 +976,17 @@ var CPWindowSaveImage = nil, // Managing Titles +/* + Returns the window's title bar string +*/ - (CPString)title { return _title; } +/* + Sets the window's title bar string +*/ - (void)setTitle:(CPString)aTitle { _title = aTitle; @@ -661,28 +996,43 @@ var CPWindowSaveImage = nil, [self _synchronizeMenuBarTitleWithWindowTitle]; } +/* + Sets the title bar to represent a file path +*/ - (void)setTitleWithRepresentedFilename:(CPString)aFilePath { [self setRepresentedFilename:aFilePath]; [self setTitle:[aFilePath lastPathComponent]]; } +/* + Sets the path to the file the receiver represents +*/ - (void)setRepresentedFilename:(CPString)aFilePath { // FIXME: urls vs filepaths and all. [self setRepresentedURL:aFilePath]; } +/* + Returns the path to the file the receiver represents +*/ - (CPString)representedFilename { return _representedURL; } +/* + Sets the URL that the receiver represents +*/ - (void)setRepresentedURL:(CPURL)aURL { _representedURL = aURL; } +/* + Returns the URL that the receiver represents +*/ - (CPURL)representedURL { return _representedURL; @@ -690,16 +1040,26 @@ var CPWindowSaveImage = nil, // Moving +/* + Sets whether the window can be moved by dragging its background. The default is based on the window style. + @param shouldBeMovableByWindowBackground YES makes the window move from a background drag. +*/ - (void)setMovableByWindowBackground:(BOOL)shouldBeMovableByWindowBackground { _isMovableByWindowBackground = shouldBeMovableByWindowBackground; } +/* + Returns YES if the window can be moved by dragging its background. +*/ - (BOOL)isMovableByWindowBackground { return _isMovableByWindowBackground; } +/* + Sets the window location to be the center of the screen +*/ - (void)center { var size = [self frame].size, @@ -708,6 +1068,10 @@ var CPWindowSaveImage = nil, [self setFrameOrigin:CGPointMake((bridgeSize.width - size.width) / 2.0, (bridgeSize.height - size.height) / 2.0)]; } +/* + Dispatches events that are sent to it from CPApplication. + @param anEvent the event to be dispatched +*/ - (void)sendEvent:(CPEvent)anEvent { var type = [anEvent type], @@ -778,27 +1142,45 @@ var CPWindowSaveImage = nil, } } +/* + Returns the window's number in the desktop's screen list +*/ - (int)windowNumber { return _windowNumber; } +/* + Called when the receiver should become the key window. It also sends + the becomeKeyWindow message to the first responder. +*/ - (void)becomeKeyWindow { if (_firstResponder != self && [_firstResponder respondsToSelector:@selector(becomeKeyWindow)]) [_firstResponder becomeKeyWindow]; } +/* + Determines if the window can become the key window. + @return YES means the window can become the key window. +*/ - (BOOL)canBecomeKeyWindow { return YES; } +/* + Returns YES if the window is the key window. +*/ - (BOOL)isKeyWindow { return [CPApp keyWindow] == self; } +/* + Makes the window the key window and brings it to the front of the screen list. + @param aSender the object requesting this +*/ - (void)makeKeyAndOrderFront:(id)aSender { [self orderFront:self]; @@ -807,6 +1189,9 @@ var CPWindowSaveImage = nil, [self makeMainWindow]; } +/* + Makes this window the key window. +*/ - (void)makeKeyWindow { if (![self canBecomeKeyWindow]) @@ -819,6 +1204,9 @@ var CPWindowSaveImage = nil, [self becomeKeyWindow]; } +/* + Causes the window to resign it's key window status. +*/ - (void)resignKeyWindow { if (_firstResponder != self && [_firstResponder respondsToSelector:@selector(resignKeyWindow)]) @@ -828,11 +1216,31 @@ var CPWindowSaveImage = nil, [_delegate windowDidResignKey:self]; } +/* + Initiates a drag operation from the receiver to another view that accepts dragged data. + @param anImage the image to be dragged + @param aLocation the lower-left corner coordinate of anImage + @param mouseOffset the distance from the mouseDown: location and the current location + @param anEvent the mouseDown: that triggered the drag + @param aPastebaord the pasteboard that holds the drag data + @param aSourceObject the drag operation controller + @param slideBack Whether the image should 'slide back' if the drag is rejected +*/ - (void)dragImage:(CPImage)anImage at:(CGPoint)imageLocation offset:(CGSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack { [[CPDragServer sharedDragServer] dragImage:anImage fromWindow:self at:[self convertBaseToBridge:imageLocation] offset:mouseOffset event:anEvent pasteboard:aPasteboard source:aSourceObject slideBack:slideBack]; } +/* + Initiates a drag operation from the receiver to another view that accepts dragged data. + @param aView the view to be dragged + @param aLocation the lower-left corner coordinate of aView + @param mouseOffset the distance from the mouseDown: location and the current location + @param anEvent the mouseDown: that triggered the drag + @param aPastebaord the pasteboard that holds the drag data + @param aSourceObject the drag operation controller + @param slideBack Whether the view should 'slide back' if the drag is rejected +*/ - (void)dragView:(CPView)aView at:(CGPoint)imageLocation offset:(CGSize)mouseOffset event:(CPEvent)anEvent pasteboard:(CPPasteboard)aPasteboard source:(id)aSourceObject slideBack:(BOOL)slideBack { [[CPDragServer sharedDragServer] dragView:aView fromWindow:self at:[self convertBaseToBridge:imageLocation] offset:mouseOffset event:anEvent pasteboard:aPasteboard source:aSourceObject slideBack:slideBack]; @@ -840,6 +1248,10 @@ var CPWindowSaveImage = nil, // Accessing Editing Status +/* + Sets whether the document has been edited. + @param isDocumentEdited YES if the document has been edited. +*/ - (void)setDocumentEdited:(BOOL)isDocumentEdited { if (_isDocumentEdited == isDocumentEdited) @@ -850,6 +1262,9 @@ var CPWindowSaveImage = nil, [CPMenu _setMenuBarIconImageAlphaValue:_isDocumentEdited ? 0.5 : 1.0]; } +/* + Returns YES if the document has been edited. +*/ - (BOOL)isDocumentEdited { return _isDocumentEdited; @@ -872,6 +1287,7 @@ var CPWindowSaveImage = nil, return _isDocumentSaving; } +/* @ignore */ - (void)_synchronizeSaveMenuWithDocumentSaving { if (![self isMainWindow]) @@ -903,6 +1319,10 @@ var CPWindowSaveImage = nil, // Closing Windows +/* + Simulates the user closing the window, then closes the window. + @param aSender the object making this request +*/ - (void)performClose:(id)aSender { if ([_delegate respondsToSelector:@selector(windowShouldClose:)] && ![_delegate windowShouldClose:self] || @@ -912,6 +1332,10 @@ var CPWindowSaveImage = nil, [self close]; } +/* + Closes the window. Posts a CPWindowWillCloseNotification to the + notification center before closing the window. +*/ - (void)close { [[CPNotificationCenter defaultCenter] postNotificationName:CPWindowWillCloseNotification object:self]; @@ -920,12 +1344,17 @@ var CPWindowSaveImage = nil, } // Managing Main Status - +/* + Returns YES if this the main window. +*/ - (BOOL)isMainWindow { return [CPApp mainWindow] == self; } +/* + Returns YES if the window can become the main window. +*/ - (BOOL)canBecomeMainWindow { // FIXME: Also check if we can resize and titlebar. @@ -935,6 +1364,9 @@ var CPWindowSaveImage = nil, return NO; } +/* + Makes the receiver the main window. +*/ - (void)makeMainWindow { if (![self canBecomeMainWindow]) @@ -947,6 +1379,9 @@ var CPWindowSaveImage = nil, [self becomeMainWindow]; } +/* + Called to tell the receiver that it has become the main window. +*/ - (void)becomeMainWindow { [self _synchronizeMenuBarTitleWithWindowTitle]; @@ -957,6 +1392,9 @@ var CPWindowSaveImage = nil, object:self]; } +/* + Called when the window resigns main window status. +*/ - (void)resignMainWindow { [[CPNotificationCenter defaultCenter] @@ -965,13 +1403,19 @@ var CPWindowSaveImage = nil, } // Managing Toolbars - +/* + Return's the window's toolbar +*/ - (CPToolbar)toolbar { return _toolbar; } -- (void)setToolbar:(CPView)aToolbar +/* + Sets the window's toolbar. + @param aToolbar the window's new toolbar +*/ +- (void)setToolbar:(CPToolbar)aToolbar { if (_toolbar == aToolbar) return; @@ -998,6 +1442,7 @@ var CPWindowSaveImage = nil, } } +/* @ignore */ - (void)_setToolbarVisible:(BOOL)aFlag { if (aFlag) @@ -1016,6 +1461,7 @@ var CPWindowSaveImage = nil, // Managing Sheets +/* @ignore */ - (void)_setAttachedSheetFrameOrigin { // Position the sheet above the contentRect. @@ -1028,6 +1474,7 @@ var CPWindowSaveImage = nil, [_attachedSheet setFrameOrigin:sheetFrame.origin]; } +/* @ignore */ - (void)_animateAttachedSheet { /* NSWindow *sheet = [sheetContext sheet]; @@ -1052,6 +1499,7 @@ var CPWindowSaveImage = nil, [sheet setFrame:sheetFrame display:YES animate:YES];*/ } +/* @ignore */ - (void)_attachSheet:(CPWindow)aSheet modalDelegate:(id)aModalDelegate didEndSelector:(SEL)aDidEndSelector contextInfo:(id)aContextInfo { // Set this as our attached sheet. @@ -1066,23 +1514,36 @@ var CPWindowSaveImage = nil, [_bridge order:CPWindowAbove window:aSheet relativeTo:self]; } +/* + Returns the window's attached sheet. +*/ - (CPWindow)attachedSheet { return _attachedSheet; } +/* + Returns YES if the window has ever run as a sheet. +*/ - (BOOL)isSheet { return _isSheet; } // - +/* + Used privately. + @ignore +*/ - (BOOL)becomesKeyOnlyIfNeeded { return NO; } +/* + Returns YES if the receiver is able to receive input events + even when a modal session is active. +*/ - (BOOL)worksWhenModal { return NO; @@ -1105,6 +1566,10 @@ var CPWindowSaveImage = nil, @implementation CPWindow (BridgeSupport) +/* + Sets the DOM-Window bridge for this window. + @ignore +*/ - (void)setBridge:(CPDOMWindowBridge)aBridge { if (_bridge == aBridge) @@ -1122,6 +1587,9 @@ var CPWindowSaveImage = nil, [self setFrame:[aBridge contentBounds]]; } +/* + @ignore +*/ - (void)resizeWithOldBridgeSize:(CGSize)aSize { if (_styleMask & CPBorderlessBridgeWindowMask) @@ -1150,16 +1618,25 @@ var CPWindowSaveImage = nil, [self setFrame:newFrame]; } +/* + @ignore +*/ - (void)setAutoresizingMask:(unsigned)anAutoresizingMask { _autoresizingMask = anAutoresizingMask; } +/* + @ignore +*/ - (unsigned)autoresizingMask { return _autoresizingMask; } +/* + @ignore +*/ - (CGPoint)convertBaseToBridge:(CGPoint)aPoint { var origin = [self frame].origin; @@ -1167,6 +1644,9 @@ var CPWindowSaveImage = nil, return CGPointMake(aPoint.x + origin.x, aPoint.y + origin.y); } +/* + @ignore +*/ - (CGPoint)convertBridgeToBase:(CGPoint)aPoint { var origin = [self frame].origin; @@ -1175,7 +1655,9 @@ var CPWindowSaveImage = nil, } // Undo and Redo Support - +/* + Returns the window's undo manager. +*/ - (CPUndoManager)undoManager { if (_delegateRespondsToWindowWillReturnUndoManagerSelector) @@ -1187,11 +1669,19 @@ var CPWindowSaveImage = nil, return _undoManager; } +/* + Sends the undo manager an undo message. + @param aSender the object requesting this +*/ - (void)undo:(id)aSender { [[self undoManager] undo]; } +/* + Sends the undo manager a redo: message. + @param aSender the object requesting this +*/ - (void)redo:(id)aSender { [[self undoManager] redo]; @@ -1204,6 +1694,7 @@ var interpolate = function(fromValue, toValue, progress) return fromValue + (toValue - fromValue) * progress; } +/* @ignore */ @implementation _CPWindowFrameAnimation : CPAnimation { CPWindow _window; diff --git a/AppKit/CPWindowController.j b/AppKit/CPWindowController.j index e0c7b8abcc..aa7a8cc0f6 100644 --- a/AppKit/CPWindowController.j +++ b/AppKit/CPWindowController.j @@ -29,7 +29,12 @@ import "CPDocument.j" #include "Platform/Platform.h" - +/* + An instance of a CPWindowController manages a CPWindow. It has methods + that get called when the window is loading, and after the window has loaded. In the + Model-View-Controller method of program design, the CPWindowController would be + considered the 'Controller' and the CPWindow the 'Model.' +*/ @implementation CPWindowController : CPResponder { id _owner; @@ -38,6 +43,11 @@ import "CPDocument.j" CPString _windowCibName; } +/* + Initializes the controller with a window. + @param aWindow the window to control + @return the initialzed window controller +*/ - (id)initWithWindow:(CPWindow)aWindow { self = [super init]; @@ -52,11 +62,22 @@ import "CPDocument.j" return self; } +/* + Initializes the controller with a Capppuccino Interface Builder name. + @param aWindowCibName the cib name of the window to control + @return the initialized window controller +*/ - (id)initWithWindowCibName:(CPString)aWindowCibName { return [self initWithWindowCibName:aWindowCibName owner:self]; } +/* + Initializes the controller with a cafe name. + @param aWindowCibName the cib name of the window to control + @param anOwner the owner of the cib file + @return the initialized window controller +*/ - (id)initWithWindowCibName:(CPString)aWindowCibName owner:(id)anOwner { self = [super init]; @@ -72,6 +93,9 @@ import "CPDocument.j" return self; } +/* + Loads the window +*/ - (void)loadWindow { [self windowWillLoad]; @@ -81,6 +105,10 @@ import "CPDocument.j" [self windowDidLoad]; } +/* + Shows the window. + @param aSender the object requesting the show +*/ - (CFAction)showWindow:(id)aSender { var theWindow = [self window]; @@ -91,11 +119,18 @@ import "CPDocument.j" [theWindow makeKeyAndOrderFront:aSender]; } +/* + Returns YES if the window has been loaded. Specifically, + if loadWindow has been called. +*/ - (BOOL)isWindowLoaded { return _window; } +/* + Returns the window this object controls. +*/ - (CPWindow)window { if (!_window) @@ -104,6 +139,10 @@ import "CPDocument.j" return _window; } +/* + Sets the window to be controlled. + @param aWindow the new window to control +*/ - (void)setWindow:(CPWindow)aWindow { _window = aWindow; @@ -112,6 +151,9 @@ import "CPDocument.j" [_window setNextResponder:self]; } +/* + The method notifies the controller that it's window has loaded. +*/ - (void)windowDidLoad { [_document windowControllerDidLoadNib:self]; @@ -119,11 +161,18 @@ import "CPDocument.j" [self synchronizeWindowTitleWithDocumentName]; } +/* + The method notifies the controller that it's window is about to load. +*/ - (void)windowWillLoad { [_document windowControllerWillLoadNib:self]; } +/* + Sets the document that is inside the controlled window. + @param aDocument the document in the controlled window +*/ - (void)setDocument:(CPDocument)aDocument { if (_document == aDocument) @@ -171,26 +220,36 @@ import "CPDocument.j" [self synchronizeWindowTitleWithDocumentName]; } +/* @ignore */ - (void)_documentWillSave:(CPNotification)aNotification { [[self window] setDocumentSaving:YES]; } +/* @ignore */ - (void)_documentDidSave:(CPNotification)aNotification { [[self window] setDocumentSaving:NO]; } +/* @ignore */ - (void)_documentDidFailToSave:(CPNotification)aNotification { [[self window] setDocumentSaving:NO]; } +/* + Returns the document in the controlled window. +*/ - (CPDocument)document { return _document; } +/* + Sets whether the document has unsaved changes. The window can use this as a hint to + @param isEdited YES means the document has unsaved changes. +*/ - (void)setDocumentEdited:(BOOL)isEdited { [[self window] setDocumentEdited:isEdited]; @@ -198,6 +257,9 @@ import "CPDocument.j" // Setting and Getting Window Attributes +/* + Sets the title of the window as the name of the document. +*/ - (void)synchronizeWindowTitleWithDocumentName { if (!_document || !_window) @@ -207,6 +269,10 @@ import "CPDocument.j" [_window setTitle:[self windowTitleForDocumentDisplayName:[_document displayName]]]; } +/* + Returns the window title based on the document's name. + @param aDisplayName the document's filename +*/ - (CPString)windowTitleForDocumentDisplayName:(CPString)aDisplayName { return aDisplayName; diff --git a/AppKit/Cib/CPCustomView.j b/AppKit/Cib/CPCustomView.j index 035b97e20a..14d55a712a 100644 --- a/AppKit/Cib/CPCustomView.j +++ b/AppKit/Cib/CPCustomView.j @@ -22,6 +22,7 @@ import "CPView.j" +/* @ignore */ @implementation CPCustomView : CPView { CPString _className; diff --git a/AppKit/CoreAnimation/CAAnimation.j b/AppKit/CoreAnimation/CAAnimation.j index d46f99e1c5..f44127020b 100644 --- a/AppKit/CoreAnimation/CAAnimation.j +++ b/AppKit/CoreAnimation/CAAnimation.j @@ -25,12 +25,18 @@ import import "CAMediaTimingFunction.j" - +/* + This is an animation class. +*/ @implementation CAAnimation : CPObject { BOOL _isRemovedOnCompletion; } +/* + Creates a new CAAnimation instance + @return a new CAAnimation instance +*/ + (id)animation { return [[self alloc] init]; @@ -46,42 +52,70 @@ import "CAMediaTimingFunction.j" return self; } +/* + Returns YES + @return YES +*/ - (void)shouldArchiveValueForKey:(CPString)aKey { return YES; } +/* + Returns nil + @return nil +*/ + (id)defaultValueForKey:(CPString)aKey { return nil; } +/* + Specifies whether this animation should be removed after it has completed. + @param YES means the animation should be removed +*/ - (void)setRemovedOnCompletion:(BOOL)isRemovedOnCompletion { _isRemovedOnCompletion = isRemovedOnCompletion; } +/* + Returns YES if the animation is removed after completion +*/ - (BOOL)removedOnCompletion { return _isRemovedOnCompletion; } +/* + Returns YES if the animation is removed after completion +*/ - (BOOL)isRemovedOnCompletion { return _isRemovedOnCompletion; } +/* + Returns the animation's timing function. If nil, then it has a linear pacing. +*/ - (CAMediaTimingFunction)timingFunction { // Linear Pacing return nil; } +/* + Sets the animation delegate + @param aDelegate the new delegate +*/ - (void)setDelegate:(id)aDelegate { _delegate = aDelegate; } +/* + Returns the animation's delegate +*/ - (id)delegate { return _delegate; @@ -94,6 +128,9 @@ import "CAMediaTimingFunction.j" @end +/* + +*/ @implementation CAPropertyAnimation : CAAnimation { CPString _keyPath; @@ -153,6 +190,11 @@ import "CAMediaTimingFunction.j" @end +/* + A CABasicAnimation is a simple animation that moves a + CALayer from one point to another over a specified + period of time. +*/ @implementation CABasicAnimation : CAPropertyAnimation { id _fromValue; @@ -160,31 +202,52 @@ import "CAMediaTimingFunction.j" id _byValue; } +/* + Sets the starting position for the animation. + @param aValue the animation starting position +*/ - (void)setFromValue:(id)aValue { _fromValue = aValue; } +/* + Returns the animation's starting position. +*/ - (id)fromValue { return _fromValue; } +/* + Sets the ending position for the animation. + @param aValue the animation ending position +*/ - (void)setToValue:(id)aValue { _toValue = aValue; } +/* + Returns the animation's ending position. +*/ - (id)toValue { return _toValue; } +/* + Sets the optional byValue for animation interpolation. + @param aValue the byValue +*/ - (void)setByValue:(id)aValue { _byValue = aValue; } +/* + Returns the animation's byValue. +*/ - (id)byValue { return _byValue; diff --git a/AppKit/CoreAnimation/CALayer.j b/AppKit/CoreAnimation/CALayer.j index 531934f579..dc04f82bcd 100644 --- a/AppKit/CoreAnimation/CALayer.j +++ b/AppKit/CoreAnimation/CALayer.j @@ -49,6 +49,20 @@ var CALayerFrameOriginUpdateMask = 1, var CALayerRegisteredRunLoopUpdates = nil; +/* + A CALayer is similar to a CPView, but with the ability + to have a transform applied to it. + + @delegate -(void)drawLayer:(CALayer)layer inContext:(CGContextRef)ctx; + If the delegate implements this method, the CALayer will + call this in place of its drawInContext:. + @param layer the layer to draw for + @param ctx the context to draw on + + @delegate -(void)displayLayer:(CALayer)layer; + The delegate can override the layer's display method + by implementing this method. +*/ @implementation CALayer : CPObject { // Modifying the Layer Geometry @@ -85,7 +99,7 @@ var CALayerRegisteredRunLoopUpdates = nil; unsigned _runLoopUpdateMask; BOOL _needsDisplayOnBoundsChange; - // Modifyin the Delegate + // Modifying the Delegate id _delegate; @@ -104,11 +118,17 @@ var CALayerRegisteredRunLoopUpdates = nil; CGAffineTransform _transformFromLayer; } +/* + Returns a new animation layer. +*/ + (CALayer)layer { return [[[self class] alloc] init]; } +/* + Initializes the animation layer. +*/ - (id)init { self = [super init]; @@ -152,7 +172,10 @@ var CALayerRegisteredRunLoopUpdates = nil; } // Modifying the Layer Geometry - +/* + Sets the bounds (origin and size) of the rectangle. + @param aBounds the new bounds for the layer +*/ - (void)setBounds:(CGRect)aBounds { if (CGRectEqualToRect(_bounds, aBounds)) @@ -178,11 +201,18 @@ var CALayerRegisteredRunLoopUpdates = nil; _CALayerRecalculateGeometry(self, CALayerGeometryBoundsMask); } +/* + Returns the layer's bound. +*/ - (CGRect)bounds { return _bounds; } +/* + Sets the layer's position. + @param aPosition the layer's new position +*/ - (void)setPosition:(CGPoint)aPosition { if (CGPointEqualToPoint(_position, aPosition)) @@ -193,11 +223,18 @@ var CALayerRegisteredRunLoopUpdates = nil; _CALayerRecalculateGeometry(self, CALayerGeometryPositionMask); } +/* + Returns the layer's position +*/ - (CGPoint)position { return _position; } +/* + Sets the layer's z-ordering. + @param aZPosition the layer's new z-ordering +*/ - (void)setZPosition:(int)aZPosition { if (_zPosition == aZPosition) @@ -208,6 +245,10 @@ var CALayerRegisteredRunLoopUpdates = nil; [self registerRunLoopUpdateWithMask:CALayerZPositionUpdateMask]; } +/* + Sets the layer's anchor point. The default point is [0.5, 0.5]. + @param anAnchorPoint the layer's new anchor point +*/ - (void)setAnchorPoint:(CGPoint)anAnchorPoint { anAnchorPoint = _CGPointMakeCopy(anAnchorPoint); @@ -228,11 +269,18 @@ var CALayerRegisteredRunLoopUpdates = nil; _CALayerRecalculateGeometry(self, CALayerGeometryAnchorPointMask); } +/* + Returns the layer's anchor point. +*/ - (CGPoint)anchorPoint { return _anchorPoint; } +/* + Sets the affine transform applied to this layer. + @param anAffineTransform the new affine transform +*/ - (void)setAffineTransform:(CGAffineTransform)anAffineTransform { if (CGAffineTransformEqualToTransform(_affineTransform, anAffineTransform)) @@ -243,11 +291,18 @@ var CALayerRegisteredRunLoopUpdates = nil; _CALayerRecalculateGeometry(self, CALayerGeometryAffineTransformMask); } +/* + Returns the layer's affine transform. +*/ - (CGAffineTransform)affineTransform { return _affineTransform; } +/* + Sets the affine transform that gets applied to all the sublayers. + @param anAffineTransform the transform to apply to sublayers +*/ - (void)setSublayerTransform:(CGAffineTransform)anAffineTransform { if (CGAffineTransformEqualToTransform(_sublayerTransform, anAffineTransform)) @@ -270,24 +325,40 @@ var CALayerRegisteredRunLoopUpdates = nil; } } +/* + Returns the affine transform applied to the sublayers. +*/ - (CGAffineTransform)sublayerTransform { return _sublayerTransform; } +/* + Private + @ignore +*/ - (CGAffineTransform)transformToLayer { return _transformToLayer; } +/* + Sets the frame of the layer. The frame defines a bounding + rectangle in the superlayer's coordinate system. + @param aFrame the new frame rectangle +*/ - (void)setFrame:(CGRect)aFrame { alert("FIXME IMPLEMENT"); } -// The frame defines the bounding box of the layer: the smallest -// possible rectangle that could fit this layer after transform -// properties are applied in superlayer coordinates. +/* + Returns the layer's frame. + + The frame defines the bounding box of the layer: the smallest + possible rectangle that could fit this layer after transform + properties are applied in superlayer coordinates. +*/ - (CGRect)frame { if (!_frame) @@ -296,16 +367,23 @@ var CALayerRegisteredRunLoopUpdates = nil; return _frame; } -// The Backing Store Frame specifies the frame of the actual backing -// store used to contain this layer. Naturally, by default it is the -// same as the frame, however, users can specify their own custom -// Backing Store Frame in order to speed up certain operations, such as -// live transformation. +/* + The Backing Store Frame specifies the frame of the actual backing + store used to contain this layer. Naturally, by default it is the + same as the frame, however, users can specify their own custom + Backing Store Frame in order to speed up certain operations, such as + live transformation. + @return the backing store frame +*/ - (CGRect)backingStoreFrame { return _backingStoreFrame; } +/* + Sets the frame's backing store. + @param aFrame the new backing store. +*/ - (void)setBackingStoreFrame:(CGRect)aFrame { _hasCustomBackingStoreFrame = (aFrame != nil); @@ -338,12 +416,19 @@ var CALayerRegisteredRunLoopUpdates = nil; } // Providing Layer Content - +/* + Returns the CGImage contents of this layer. + The default contents are nil. +*/ - (CGImage)contents { return _contents; } +/* + Sets the image contents of this layer. + @param contents the image to display +*/ - (void)setContents:(CGImage)contents { if (_contents == contents) @@ -354,6 +439,10 @@ var CALayerRegisteredRunLoopUpdates = nil; [self composite]; } +/* + Composites this layer onto the super layer, and draws its contents as well. + @ignore +*/ - (void)composite { if (USE_BUFFER && !_contents || !_context) @@ -390,6 +479,9 @@ var CALayerRegisteredRunLoopUpdates = nil; CGContextRestoreGState(_context); } +/* + Displays the contents of this layer. +*/ - (void)display { if (!_context) @@ -418,7 +510,7 @@ var CALayerRegisteredRunLoopUpdates = nil; if (USE_BUFFER) { if (_delegateRespondsToDisplayLayerSelector) - return [self displayInLayer:self]; + return [_delegate displayInLayer:self]; if (_CGRectGetWidth(_backingStoreFrame) == 0.0 || _CGRectGetHeight(_backingStoreFrame) == 0.0) return; @@ -434,6 +526,10 @@ var CALayerRegisteredRunLoopUpdates = nil; [self composite]; } +/* + Draws this layer's contents into the specified context. + @param aContext the context to draw the layer into +*/ - (void)drawInContext:(CGContext)aContext { //if (!window.loop || window.nodisplay) CPLog.error("htiasd"); if (_backgroundColor) @@ -448,12 +544,19 @@ var CALayerRegisteredRunLoopUpdates = nil; // Style Attributes - +/* + Returns the opacity of the layer. The value is between + 0.0 (transparent) and 1.0 (opaque). +*/ - (float)opacity { return _opacity; } +/* + Sets the opacity for the layer. + @param anOpacity the new opacity (between 0.0 (transparent) and 1.0 (opaque)). +*/ - (void)setOpacity:(float)anOpacity { if (_opacity == anOpacity) @@ -465,22 +568,36 @@ var CALayerRegisteredRunLoopUpdates = nil; _DOMElement.style.filter = "alpha(opacity=" + anOpacity * 100 + ")"; } +/* + Sets whether the layer is hidden. + @param isHidden YES means the layer will be hidden. NO means the layer will be visible. +*/ - (void)setHidden:(BOOL)isHidden { _isHidden = isHidden; _DOMElement.style.display = isHidden ? "none" : "block"; } +/* + Returns YES if the layer is hidden. +*/ - (BOOL)hidden { return _isHidden; } +/* + Returns YES if the layer is hidden. +*/ - (BOOL)isHidden { return _isHidden; } +/* + Sets whether content that goes lies outside the bounds is hidden or visible. + @param masksToBounds YES hides the excess content. NO makes it visible. +*/ - (void)setMasksToBounds:(BOOL)masksToBounds { if (_masksToBounds == masksToBounds) @@ -490,6 +607,10 @@ var CALayerRegisteredRunLoopUpdates = nil; _DOMElement.style.overflow = _masksToBounds ? "hidden" : "visible"; } +/* + Sets the layer's background color. + @param aColor the new background color +*/ - (void)setBackgroundColor:(CPColor)aColor { _backgroundColor = aColor; @@ -497,18 +618,26 @@ var CALayerRegisteredRunLoopUpdates = nil; [self setNeedsDisplay]; } +/* + Returns the layer's background color. +*/ - (CPColor)backgroundColor { return _backgroundColor; } // Managing Layer Hierarchy - +/* + Returns an array of the receiver's sublayers. +*/ - (CPArray)sublayers { return _sublayers; } +/* + Returns the receiver's superlayer. +*/ - (CALayer)superlayer { return _superlayer; @@ -518,6 +647,9 @@ var CALayerRegisteredRunLoopUpdates = nil; if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex)\ _DOMContentsElement.style.zIndex -= 100.0;\ +/* + Adds the specified layer as a sublayer of the receiver. +*/ - (void)addSublayer:(CALayer)aLayer { [self insertSublayer:aLayer atIndex:_sublayers.length]; @@ -528,6 +660,9 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) _DOMElement.appendChild(DOM(aLayer)); } +/* + Removes the receiver from its superlayer. +*/ - (void)removeFromSuperlayer { if (_owningView) @@ -542,6 +677,11 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) _superlayer = nil; } +/* + Inserts the specified layer as a sublayer into the specified index. + @param aLayer the layer to insert + @param anIndex the index to insert the layer at +*/ - (void)insertSublayer:(CALayer)aLayer atIndex:(unsigned)anIndex { if (!aLayer) @@ -579,6 +719,12 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) _CALayerRecalculateGeometry(aLayer, 0xFFFFFFF); } +/* + Inserts a layer below another layer. + @param aLayer the layer to insert + @param aSublayer the layer to insert below + @throws CALayerNotFoundException if aSublayer is not in the array of sublayers +*/ - (void)insertSublayer:(CALayer)aLayer below:(CALayer)aSublayer { var index = aSublayer ? [_sublayers indexOfObjectIdenticalTo:aSublayer] : 0; @@ -586,13 +732,26 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) [self insertSublayer:aLayer atIndex:index == CPNotFound ? _sublayers.length : index]; } -- (void)insertSublayer:(CALayer)aLayer after:(CALayer)aSublayer +/* + Inserts a layer above another layer. + @param aLayer the layer to insert + @param aSublayer the layer to insert above + @throws CALayerNotFoundException if aSublayer is not in the array of sublayers +*/ +- (void)insertSublayer:(CALayer)aLayer above:(CALayer)aSublayer { var index = aSublayer ? [_sublayers indexOfObjectIdenticalTo:aSublayer] : _sublayers.length; + if (index == CPNotFound) + [CPException raise:"CALayerNotFoundException" reason:"aSublayer is not a sublayer of this layer"]; [_sublayers insertObject:aLayer atIndex:index == CPNotFound ? _sublayers.length : index + 1]; } +/* + Replaces a sublayer. + @param aSublayer the layer to insert + @param aLayer the layer to replace +*/ - (void)replaceSublayer:(CALayer)aSublayer with:(CALayer)aLayer { if (aSublayer == aLayer) @@ -612,7 +771,10 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) } // Updating Layer Display - +/* + Updates the layers on screen. + @ignore +*/ + (void)runLoopUpdateLayers {if (window.oops) {alert(window.latest); objj_debug_print_backtrace();} window.loop = true; @@ -636,6 +798,9 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) CALayerRegisteredRunLoopUpdates = nil; } +/* + @ignore +*/ - (void)registerRunLoopUpdateWithMask:(unsigned)anUpdateMask { if (CALayerRegisteredRunLoopUpdates == nil) @@ -650,26 +815,43 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) CALayerRegisteredRunLoopUpdates[[self hash]] = self; } +/* + @ignore +*/ - (void)setNeedsComposite { [self registerRunLoopUpdateWithMask:CALayerCompositeUpdateMask]; } +/* + Marks the layer as needing to be redrawn. +*/ - (void)setNeedsDisplay { [self registerRunLoopUpdateWithMask:CALayerDisplayUpdateMask]; } +/* + Sets whether the layer needs to be redrawn when its bounds are changed. + @param needsDisplayOnBoundsChange YES means the display is redraw on a bounds change. +*/ - (void)setNeedsDisplayOnBoundsChange:(BOOL)needsDisplayOnBoundsChange { _needsDisplayOnBoundsChange = needsDisplayOnBoundsChange; } +/* + Returns YES if the display should be redrawn on a bounds change. +*/ - (BOOL)needsDisplayOnBoundsChange { return _needsDisplayOnBoundsChange; } +/* + Marks the specified rectange as needing to be redrawn. + @param aRect the area that needs to be redrawn. +*/ - (void)setNeedsDisplayInRect:(CGRect)aRect { _dirtyRect = aRect; @@ -677,34 +859,65 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) } // Mapping Between Coordinate and Time Spaces - +/* + Converts the point from the specified layer's coordinate system into the receiver's coordinate system. + @param aPoint the point to convert + @param aLayer the layer coordinate system to convert from + @return the converted point +*/ - (CGPoint)convertPoint:(CGPoint)aPoint fromLayer:(CALayer)aLayer { return CGPointApplyAffineTransform(aPoint, _CALayerGetTransform(aLayer, self)); } +/* + Converts the point from the receiver's coordinate system to the specified layer's coordinate system. + @param aPoint the point to convert + @param aLayer the layer coordinate system to convert to + @return the converted point +*/ - (CGPoint)convertPoint:(CGPoint)aPoint toLayer:(CALayer)aLayer { return CGPointApplyAffineTransform(aPoint, _CALayerGetTransform(self, aLayer)); } +/* + Converts the rectangle from the specified layer's coordinate system to the receiver's coordinate system. + @param aRect the rectangle to convert + @param aLayer the layer coordinate system to convert from + @return the converted rectangle +*/ - (CGRect)convertRect:(CGRect)aRect fromLayer:(CALayer)aLayer { return CGRectApplyAffineTransform(aRect, _CALayerGetTransform(aLayer, self)); } +/* + Converts the rectangle from the receier's coordinate system to the specified layer's coordinate system. + @param aRect the rectange to convert + @param aLayer the layer coordinate system to convert to + @return the converted rectangle +*/ - (CGRect)convertRect:(CGRect)aRect toLayer:(CALayer)aLayer { return CGRectApplyAffineTransform(aRect, _CALayerGetTransform(self, aLayer)); } // Hit Testing - +/* + Returns YES if the layer contains the point. + @param aPoint the point to test +*/ - (BOOL)containsPoint:(CGPoint)aPoint { return _CGRectContainsPoint(_bounds, aPoint); } +/* + Returns the farthest descendant of this layer that contains the specified point. + @param aPoint the point to test + @return the containing layer or nil if there was no hit. +*/ - (CALayer)hitTest:(CGPoint)aPoint { if (_isHidden) @@ -728,7 +941,10 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) } // Modifying the Delegate - +/* + Sets the delegate for this layer. + @param aDelegate the delegate +*/ - (void)setDelegate:(id)aDelegate { if (_delegate == aDelegate) @@ -743,11 +959,15 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) [self setNeedsDisplay]; } +/* + Returns the layer's delegate +*/ - (id)delegate { return _delegate; } +/* @ignore */ - (void)_setOwningView:(CPView)anOwningView { _owningView = anOwningView; @@ -763,6 +983,7 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) _CALayerRecalculateGeometry(self, CALayerGeometryPositionMask | CALayerGeometryBoundsMask); } +/* @ignore */ - (void)_owningViewBoundsChanged { _bounds.size = CGSizeMakeCopy([_owningView bounds].size); @@ -771,6 +992,7 @@ if (_DOMContentsElement && aLayer._zPosition > _DOMContentsElement.style.zIndex) _CALayerRecalculateGeometry(self, CALayerGeometryPositionMask | CALayerGeometryBoundsMask); } +/* @ignore */ - (void)_update { window.loop = true; diff --git a/AppKit/CoreGraphics/CGAffineTransform.j b/AppKit/CoreGraphics/CGAffineTransform.j index 2bd7e39be5..a3b4502cf8 100644 --- a/AppKit/CoreGraphics/CGAffineTransform.j +++ b/AppKit/CoreGraphics/CGAffineTransform.j @@ -45,12 +45,24 @@ _function(CGAffineTransformEqualToTransform(lhs, rhs)) _function(CGStringCreateWithCGAffineTransform(aTransform)) -// FIXME: !!!! +/* + FIXME: !!!! + @return void + @group CGAffineTransform +*/ function CGAffineTransformCreateCopy(aTransform) { return _CGAffineTransformMakeCopy(aTransform); } +/* + Returns a transform that rotates a coordinate system. + @param anAngle the amount in radians for the transform + to rotate a coordinate system + @return CGAffineTransform the transform with a specified + rotation + @group CGAffineTransform +*/ function CGAffineTransformMakeRotation(anAngle) { var sin = SIN(anAngle), @@ -59,6 +71,13 @@ function CGAffineTransformMakeRotation(anAngle) return _CGAffineTransformMake(cos, sin, -sin, cos, 0.0, 0.0); } +/* + Rotates a transform. + @param aTransform the transform to rotate + @param anAngle the amount to rotate in radians + @return void + @group CGAffineTransform +*/ function CGAffineTransformRotate(aTransform, anAngle) { var sin = SIN(anAngle), @@ -74,6 +93,12 @@ function CGAffineTransformRotate(aTransform, anAngle) }; } +/* + Inverts a transform. + @param aTransform the transform to invert + @return CGAffineTransform an inverted transform + @group CGAffineTransform +*/ function CGAffineTransformInvert(aTransform) { var determinant = 1 / (aTransform.a * aTransform.d - aTransform.b * aTransform.c); @@ -88,6 +113,14 @@ function CGAffineTransformInvert(aTransform) }; } +/* + Applies a transform to the rectangle's points. The transformed rectangle + will be the smallest box that contains the transformed points. + @param aRect the rectangle to transform + @param anAffineTransform the transform to apply + @return CGRect the new transformed rectangle + @group CGAffineTransform +*/ function CGRectApplyAffineTransform(aRect, anAffineTransform) { var top = _CGRectGetMinY(aRect), @@ -106,6 +139,12 @@ function CGRectApplyAffineTransform(aRect, anAffineTransform) return _CGRectMake(minX, minY, (maxX - minX), (maxY - minY)); } +/* + Creates and returns a string representation of an affine transform. + @param anAffineTransform the transform to represent as a string + @return CPString a string describing the transform + @group CGAffineTransform +*/ function CPStringFromCGAffineTransform(anAffineTransform) { return '{' + anAffineTransform.a + ", " + anAffineTransform.b + ", " + anAffineTransform.c + ", " + anAffineTransform.d + ", " + anAffineTransform.tx + ", " + anAffineTransform.ty + '}'; diff --git a/AppKit/CoreGraphics/CGColor.j b/AppKit/CoreGraphics/CGColor.j index a5838e87ff..ba0518c0e2 100644 --- a/AppKit/CoreGraphics/CGColor.j +++ b/AppKit/CoreGraphics/CGColor.j @@ -45,15 +45,28 @@ function CGColorGetConstantColor(aColorName) alert("FIX ME"); } +/* + This function is for source compatability. +*/ function CGColorRetain(aColor) { return aColor; } +/* + This function is for source compatability. +*/ function CGColorRelease() { } +/* + Creates a new CGColor. + @param aColorSpace the CGColorSpace of the color + @param components the color's intensity values plus alpha + @return CGColor the new color object + @group CGColor +*/ function CGColorCreate(aColorSpace, components) { if (!aColorSpace || !components) @@ -71,27 +84,68 @@ function CGColorCreate(aColorSpace, components) return _CGColorMap[UID] = { colorspace:aColorSpace, pattern:NULL, components:components }; } +/* + Creates a copy of a color... but not really. CGColors + are immutable, so to be efficient, this function will just + return the same object that was passed in. + @param aColor the CGColor to 'copy' + @return CGColor the color copy + @group CGColor +*/ function CGColorCreateCopy(aColor) { // Colors should be treated as immutable, so don't mutate it! return aColor; } +/* + Creates a gray color object. + @param gray the value to use for the color intensities (0.0-1.0) + @param alpha the gray's alpha value (0.0-1.0) + @return CGColor the new gray color object + @group CGColor +*/ function CGColorCreateGenericGray(gray, alpha) { return CGColorCreate(0, [gray, alpha]); } +/* + Creates an RGB color. + @param red the red component (0.0-1.0) + @param green the green component (0.0-1.0) + @param blue the blue component (0.0-1.0) + @param alpha the alpha component (0.0-1.0) + @return CGColor the RGB based color + @group CGColor +*/ function CGColorCreateGenericRGB(red, green, blue, alpha) { return CGColorCreate(0, [red, green, blue, alpha]); } +/* + Creates a CMYK color. + @param cyan the cyan component (0.0-1.0) + @param magenta the magenta component (0.0-1.0) + @param yellow the yellow component (0.0-1.0) + @param black the black component (0.0-1.0) + @param alpha the alpha component (0.0-1.0) + @return CGColor the CMYK based color + @group CGColor +*/ function CGColorCreateGenericCMYK(cyan, magenta, yellow, black, alpha) { return CGColorCreate(0, [cyan, magenta, yellow, black, alpha]); } +/* + Creates a copy of the color with a specified alpha. + @param aColor the color object to copy + @param anAlpha the new alpha component for the copy (0.0-1.0) + @return CGColor the new copy + @group CGColor +*/ function CGColorCreateCopyWithAlpha(aColor, anAlpha) { var components = aColor.components; @@ -109,6 +163,14 @@ function CGColorCreateCopyWithAlpha(aColor, anAlpha) return copy; } +/* + Creates a color using the specified pattern. + @param aColorSpace the CGColorSpace + @param aPattern the pattern image + @param components the color components plus the alpha component + @return CGColor the patterned color + @group CGColor +*/ function CGColorCreateWithPattern(aColorSpace, aPattern, components) { if (!aColorSpace || !aPattern || !components) @@ -117,6 +179,13 @@ function CGColorCreateWithPattern(aColorSpace, aPattern, components) return { colorspace:aColorSpace, pattern:aPattern, components:components.slice() }; } +/* + Determines if two colors are the same. + @param lhs the first CGColor + @param rhs the second CGColor + @return YES if the two colors are equal. + NO otherwise. +*/ function CGColorEqualToColor(lhs, rhs) { if (lhs == rhs) @@ -145,6 +214,12 @@ function CGColorEqualToColor(lhs, rhs) return true; } +/* + Returns the color's alpha component. + @param aColor the color + @return float the alpha component (0.0-1.0) + @group CGColor +*/ function CGColorGetAlpha(aColor) { var components = aColor.components; @@ -152,21 +227,45 @@ function CGColorGetAlpha(aColor) return components[components.length - 1]; } +/* + Returns the CGColor's color space. + @return CGColorSpace + @group CGColor +*/ function CGColorGetColorSpace(aColor) { return aColor.colorspace; } +/* + Returns the CGColor's components + including the alpha in an array. + @param aColor the color + @return CPArray the color's components +*/ function CGColorGetComponents(aColor) { return aColor.components; } +/* + Returns the number of color components + (including alpha) in the specified color. + @param aColor the CGColor + @return CPNumber the number of components + @group CGColor +*/ function CGColorGetNumberOfComponents(aColor) { return aColor.components.length; } +/* + Gets the CGColor's pattern. + @param a CGColor + @return CGPatternFIXME the pattern image + @group CGColor +*/ function CGColorGetPattern(aColor) { return aColor.pattern; diff --git a/AppKit/CoreGraphics/CGColorSpace.j b/AppKit/CoreGraphics/CGColorSpace.j index 6befbcf826..887b8ff2b8 100644 --- a/AppKit/CoreGraphics/CGColorSpace.j +++ b/AppKit/CoreGraphics/CGColorSpace.j @@ -29,12 +29,40 @@ kCGColorSpaceModelDeviceN = 4; kCGColorSpaceModelIndexed = 5; kCGColorSpaceModelPattern = 6; +/* + @global + @group CGColorSpace +*/ kCGColorSpaceGenericGray = "CGColorSpaceGenericGray"; +/* + @global + @group CGColorSpace +*/ kCGColorSpaceGenericRGB = "CGColorSpaceGenericRGB"; +/* + @global + @group CGColorSpace +*/ kCGColorSpaceGenericCMYK = "CGColorSpaceGenericCMYK"; +/* + @global + @group CGColorSpace +*/ kCGColorSpaceGenericRGBLinear = "CGColorSpaceGenericRGBLinear"; +/* + @global + @group CGColorSpace +*/ kCGColorSpaceGenericRGBHDR = "CGColorSpaceGenericRGBHDR"; +/* + @global + @group CGColorSpace +*/ kCGColorSpaceAdobeRGB1998 = "CGColorSpaceAdobeRGB1998"; +/* + @global + @group CGColorSpace +*/ kCGColorSpaceSRGB = "CGColorSpaceSRGB"; var _CGNamedColorSpaces = {}; diff --git a/AppKit/CoreGraphics/CGContext.j b/AppKit/CoreGraphics/CGContext.j index ed73a05391..3e371e43ab 100644 --- a/AppKit/CoreGraphics/CGContext.j +++ b/AppKit/CoreGraphics/CGContext.j @@ -41,44 +41,168 @@ kCGPathStroke = 2; kCGPathFillStroke = 3; kCGPathEOFillStroke = 4; +/* + @global + @group CGBlendMode +*/ kCGBlendModeNormal = 0; +/* + @global + @group CGBlendMode +*/ kCGBlendModeMultiply = 1; +/* + @global + @group CGBlendMode +*/ kCGBlendModeScreen = 2; +/* + @global + @group CGBlendMode +*/ kCGBlendModeOverlay = 3; +/* + @global + @group CGBlendMode +*/ kCGBlendModeDarken = 4; +/* + @global + @group CGBlendMode +*/ kCGBlendModeLighten = 5; +/* + @global + @group CGBlendMode +*/ kCGBlendModeColorDodge = 6; +/* + @global + @group CGBlendMode +*/ kCGBlendModeColorBurn = 7; +/* + @global + @group CGBlendMode +*/ kCGBlendModeSoftLight = 8; +/* + @global + @group CGBlendMode +*/ kCGBlendModeHardLight = 9; +/* + @global + @group CGBlendMode +*/ kCGBlendModeDifference = 10; +/* + @global + @group CGBlendMode +*/ kCGBlendModeExclusion = 11; +/* + @global + @group CGBlendMode +*/ kCGBlendModeHue = 12; +/* + @global + @group CGBlendMode +*/ kCGBlendModeSaturation = 13; +/* + @global + @group CGBlendMode +*/ kCGBlendModeColor = 14; +/* + @global + @group CGBlendMode +*/ kCGBlendModeLuminosity = 15; +/* + @global + @group CGBlendMode +*/ kCGBlendModeClear = 16; +/* + @global + @group CGBlendMode +*/ kCGBlendModeCopy = 17; +/* + @global + @group CGBlendMode +*/ kCGBlendModeSourceIn = 18; +/* + @global + @group CGBlendMode +*/ kCGBlendModeSourceOut = 19; +/* + @global + @group CGBlendMode +*/ kCGBlendModeSourceAtop = 20; +/* + @global + @group CGBlendMode +*/ kCGBlendModeDestinationOver = 21; +/* + @global + @group CGBlendMode +*/ kCGBlendModeDestinationIn = 22; +/* + @global + @group CGBlendMode +*/ kCGBlendModeDestinationOut = 23; +/* + @global + @group CGBlendMode +*/ kCGBlendModeDestinationAtop = 24; +/* + @global + @group CGBlendMode +*/ kCGBlendModeXOR = 25; +/* + @global + @group CGBlendMode +*/ kCGBlendModePlusDarker = 26; +/* + @global + @group CGBlendMode +*/ kCGBlendModePlusLighter = 27; +/* + This function is just here for source compatability. + It does nothing. + @group CGContext +*/ function CGContextRelease() { } +/* + This function is just here for source compatability. + It does nothing. + @param aContext a CGContext + @return CGContext the context +*/ function CGContextRetain(aContext) { return aContext; } +// BEGIN CANVAS IF if (!CPFeatureIsCompatible(CPHTMLCanvasFeature)) { @@ -294,15 +418,26 @@ function CGContextSetShadowWithColor(aContext, aSize, aBlur, aColor) gState.shadowColor = aColor; } -} +} // END CANVAS IF // GOOD. - -function CGContextEOFillPath(aContext, aMode) +/* + Fills in the area of the current path, using the even-odd fill rule. + @param aContext the CGContext of the path + @return void + @group CGContext +*/ +function CGContextEOFillPath(aContext) { CGContextDrawPath(aContext, kCGPathEOFill); } +/* + Fills in the area of the current path, using the non-zero winding number rule. + @param aContext the CGContext of the path + @return void + @group CGContext +*/ function CGContextFillPath(aContext) { CGContextDrawPath(aContext, kCGPathFill); @@ -310,6 +445,13 @@ function CGContextFillPath(aContext) var KAPPA = 4.0 * ((SQRT2 - 1.0) / 3.0); +/* + Draws the outline of an ellipse bounded by a rectangle. + @param aContext CGContext to draw on + @param aRect the rectangle bounding the ellipse + @return void + @group CGContext +*/ function CGContextAddEllipseInRect(aContext, aRect) { CGContextBeginPath(aContext); @@ -332,24 +474,54 @@ function CGContextAddEllipseInRect(aContext, aRect) CGContextClosePath(aContext); } - +/* + Fills an ellipse bounded by a rectangle. + @param aContext CGContext to draw on + @param aRect the rectangle bounding the ellipse + @return void + @group CGContext +*/ function CGContextFillEllipseInRect(aContext, aRect) { CGContextAddEllipseInRect(aContext, aRect); CGContextFillPath(aContext); } +/* + Strokes an ellipse bounded by the specified rectangle. + @param aContext CGContext to draw on + @param aRect the rectangle bounding the ellipse + @return void + @group CGContext +*/ function CGContextStrokeEllipseInRect(aContext, aRect) { CGContextAddEllipseInRect(aContext, aRect); CGContextStrokePath(aContext); } +/* + Paints a line in the current path of the current context. + @param aContext CGContext to draw on + @return void + @group CGContext +*/ function CGContextStrokePath(aContext) { CGContextDrawPath(aContext, kCGPathStroke); } +/* + Strokes multiple line segments. + @param aContext CGContext to draw on + @param points an array with an even number of points. The + first point is the beginning of the first line segment, the second + is the end of the first line segment. The third point is + the beginning of second line segment, etc. + @param count the number of points in the array + @return void + @group CGContext +*/ function CGContextStrokeLineSegments(aContext, points, count) { var i = 0; @@ -368,7 +540,16 @@ function CGContextStrokeLineSegments(aContext, points, count) CGContextStrokePath(aContext); } -// FIXME: THIS IS WRONG!!! + +//FIXME: THIS IS WRONG!!! + +/* + Sets the current fill color. + @param aContext the CGContext + @param aColor the new color for the fill + @return void + @group CGContext +*/ function CGContextSetFillColor(aContext, aColor) { @@ -376,12 +557,31 @@ function CGContextSetFillColor(aContext, aColor) aContext.gState.fillStyle = [aColor cssString]; } +/* + Sets the current stroke color. + @param aContext the CGContext + @param aColor the new color for the stroke + @return void + @group CGContext +*/ function CGContextSetStrokeColor(aContext, aColor) { if (aColor) aContext.gState.strokeStyle = [aColor cssString]; } +/* + Fills a rounded rectangle. + @param aContext the CGContext to draw into + @param aRect the base rectangle + @param aRadius the distance from the rectange corner to the rounded corner + @param ne set it to YES for a rounded northeast corner + @param se set it to YES for a rounded southeast corner + @param sw set it to YES for a rounded southwest corner + @param nw set it to YES for a rounded northwest corner + @return void + @group CGContext +*/ function CGContextFillRoundedRectangleInRect(aContext, aRect, aRadius, ne, se, sw, nw) { var xMin = _CGRectGetMinX(aRect), diff --git a/AppKit/CoreGraphics/CGGeometry.j b/AppKit/CoreGraphics/CGGeometry.j index 0e3aced22b..f30f56383a 100644 --- a/AppKit/CoreGraphics/CGGeometry.j +++ b/AppKit/CoreGraphics/CGGeometry.j @@ -65,6 +65,14 @@ _function(CGRectIsNull(aRect)) _function(CGRectContainsPoint(aRect, aPoint)) +/* + Returns a BOOL indicating whether CGRect lhsRect + contains CGRect rhsRect. + @group CGRect + @param lhsRect the CGRect to test if rhsRect is inside of + @param rhsRect the CGRect to test if it fits inside lhsRect. + @return BOOL YES if rhsRect fits inside lhsRect. +*/ function CGRectContainsRect(lhsRect, rhsRect) { var union = CGRectUnion(lhsRect, rhsRect); @@ -72,6 +80,13 @@ function CGRectContainsRect(lhsRect, rhsRect) return _CGRectEqualToRect(union, lhsRect); } +/* + Returns YES if the two rectangles intersect + @group CGRect + @param lhsRect the first CGRect + @param rhsRect the second CGRect + @return BOOL YES if the two rectangles have any common spaces, and NO, otherwise. +*/ function CGRectIntersectsRect(lhsRect, rhsRect) { var intersection = CGRectIntersection(lhsRect, rhsRect); @@ -79,6 +94,13 @@ function CGRectIntersectsRect(lhsRect, rhsRect) return !_CGRectIsEmpty(intersection); } +/* + Makes the origin and size of a CGRect all integers. Specifically, by making + the southwest corner the origin (rounded down), and the northeast corner a CGSize (rounded up). + @param aRect the rectangle to operate on + @return CGRect the modified rectangle (same as the input) + @group CGRect +*/ function CGRectIntegral(aRect) { aRect = CGRectStandardize(aRect); @@ -96,6 +118,13 @@ function CGRectIntegral(aRect) return aRect; } +/* + Returns the intersection of the two provided rectangles as a new rectangle. + @param lhsRect the first rectangle used for calculation + @param rhsRect the second rectangle used for calculation + @return CGRect the intersection of the two rectangles + @group CGRect +*/ function CGRectIntersection(lhsRect, rhsRect) { var intersection = _CGRectMake( @@ -109,6 +138,9 @@ function CGRectIntersection(lhsRect, rhsRect) return _CGRectIsEmpty(intersection) ? _CGRectMakeZero() : intersection; } +/* + +*/ function CGRectStandardize(aRect) { var width = _CGRectGetWidth(aRect), diff --git a/AppKit/Platform/DOM/CPDOMWindowBridge.j b/AppKit/Platform/DOM/CPDOMWindowBridge.j index 1cd45566b3..ad5a3e51cb 100644 --- a/AppKit/Platform/DOM/CPDOMWindowBridge.j +++ b/AppKit/Platform/DOM/CPDOMWindowBridge.j @@ -68,6 +68,9 @@ var ExcludedDOMElements = []; CPString _overriddenEventType; } +/* + Returns the shared DOMWindowBridge. +*/ + (id)sharedDOMWindowBridge { if (!CPSharedDOMWindowBridge) @@ -81,6 +84,7 @@ var ExcludedDOMElements = []; alert("unimplemented"); } +/* @ignore */ - (id)_initWithDOMWindow:(DOMWindow)aDOMWindow { self = [super init]; @@ -267,6 +271,7 @@ var ExcludedDOMElements = []; [layer insertWindow:aWindow atIndex:(otherWindow ? (aPlace == CPWindowAbove ? otherWindow._index + 1 : otherWindow._index) : CPNotFound)]; } +/* @ignore */ - (CPView)_dragHitTest:(CPPoint)aPoint pasteboard:(CPPasteboard)aPasteboard { var view = nil, @@ -299,6 +304,7 @@ var ExcludedDOMElements = []; return view; } +/* @ignore */ - (void)_propagateCurrentDOMEvent:(BOOL)aFlag { StopDOMEventPropagation = !aFlag; @@ -369,38 +375,63 @@ var CTRL_KEY_CODE = 17; @implementation CPDOMWindowBridge (Events) +/* + When using command (mac) or control (windows), keys are propagated to the browser by default. + To prevent a character key from propagating (to prevent its default action, and instead use it + in your own application), use these methods. These methods are additive -- the list builds until you clear it. + + @param characters a list of characters to stop propagating keypresses to the browser. +*/ - (void)preventCharacterKeysFromPropagating:(CPArray)characters { for(var i=characters.length; i>0; i--) CharacterKeysToPrevent[""+characters[i-1].toLowerCase()] = YES; } +/* + @param character a character to stop propagating keypresses to the browser. +*/ - (void)preventCharacterKeyFromPropagating:(CPString)character { CharacterKeysToPrevent[character.toLowerCase()] = YES; } +/* + Clear the list of characters for which we are not sending keypresses to the browser. +*/ - (void)clearCharacterKeysToPreventFromPropagating { CharacterKeysToPrevent = {}; } +/* + Prevent these keyCodes from sending their keypresses to the browser. + @param keyCodes an array of keycodes to prevent propagation. +*/ - (void)preventKeyCodesFromPropagating:(CPArray)keyCodes { for(var i=keyCodes.length; i>0; i--) KeyCodesToPrevent[keyCodes[i-1]] = YES; } +/* + Prevent this keyCode from sending its key events to the browser. + @param keyCode a keycode to prevent propagation. +*/ - (void)preventKeyCodeFromPropagating:(CPString)keyCode { KeyCodesToPrevent[keyCode] = YES; } +/* + Clear the list of keyCodes for which we are not sending keypresses to the browser. +*/ - (void)clearKeyCodesToPreventFromPropagating { KeyCodesToPrevent = {}; } +/* @ignore */ - (void)_bridgeMouseEvent:(DOMEvent)aDOMEvent { var theType = _overriddenEventType || aDOMEvent.type; @@ -530,6 +561,7 @@ var CTRL_KEY_CODE = 17; } } +/* @ignore */ - (void)_bridgeKeyEvent:(DOMEvent)aDOMEvent { try @@ -675,6 +707,7 @@ var CTRL_KEY_CODE = 17; } } +/* @ignore */ - (void)_bridgeScrollEvent:(DOMEvent)aDOMEvent { if(!aDOMEvent) @@ -746,6 +779,7 @@ var CTRL_KEY_CODE = 17; } +/* @ignore */ - (void)_bridgeResizeEvent:(DOMEvent)aDOMEvent { try @@ -784,6 +818,7 @@ var CTRL_KEY_CODE = 17; } } +/* @ignore */ - (void)_checkPasteboardElement { try @@ -816,6 +851,7 @@ var CTRL_KEY_CODE = 17; } } +/* @ignore */ - (void)_clearPasteboardElement { _DOMPasteboardElement.value = ""; diff --git a/AppKit/_CPImageAndTitleView.j b/AppKit/_CPImageAndTitleView.j index 9a950a0037..9db027d95d 100644 --- a/AppKit/_CPImageAndTitleView.j +++ b/AppKit/_CPImageAndTitleView.j @@ -31,7 +31,7 @@ import "CPView.j" #include "Platform/Platform.h" #include "Platform/DOM/CPDOMDisplayServer.h" - +/* @ignore */ @implementation _CPImageAndTitleView : CPView { CPTextAlignment _alignment; diff --git a/Foundation/CPArray.j b/Foundation/CPArray.j index e787d52ceb..c57ecb99fe 100755 --- a/Foundation/CPArray.j +++ b/Foundation/CPArray.j @@ -24,7 +24,9 @@ import "CPObject.j" import "CPRange.j" import "CPEnumerator.j" import "CPSortDescriptor.j" +import "CPException.j" +/* @ignore */ @implementation _CPArrayEnumerator : CPEnumerator { CPArray _array; @@ -54,6 +56,7 @@ import "CPSortDescriptor.j" @end +/* @ignore */ @implementation _CPReverseArrayEnumerator : CPEnumerator { CPArray _array; @@ -83,28 +86,56 @@ import "CPSortDescriptor.j" @end +/* + A mutable array class backed by a JavaScript Array. + There is also a CPMutableArray class, + but it is just a child class of this class with an + empty implementation. All mutable functionality is + implemented directly in CPArray. +*/ @implementation CPArray : CPObject +/* + Returns a new uninitialized CPArray. +*/ + (id)alloc { return []; } +/* + Returns a new initialized CPArray. +*/ + (id)array { return [[self alloc] init]; } +/* + Creates a new array containing the objects in anArray. + @param anArray Objects in this array will be added to the new array + @return a new CPArray of the provided objects +*/ + (id)arrayWithArray:(CPArray)anArray { return [[self alloc] initWithArray:anArray]; } +/* + Creates a new array with anObject in it. + @param anObject the object to be added to the array + @return a new CPArray containing a single object +*/ + (id)arrayWithObject:(id)anObject { return [[self alloc] initWithObjects:anObject]; } +/* + Creates a new CPArray containing all the objects passed as arguments to the method. + @param anObject the objects that will be added to the new array + @return a new CPArray containing the argument objects +*/ + (id)arrayWithObjects:(id)anObject, ... { var i = 2, @@ -117,18 +148,32 @@ import "CPSortDescriptor.j" return array; } +/* + Creates a CPArray from a JavaScript array of objects. + @param objects the JavaScript Array + @param aCount the number of objects in the JS Array + @return a new CPArray containing the specified objects +*/ + (id)arrayWithObjects:(id)objects count:(unsigned)aCount { return [[self alloc] initWithObjects:objects count:aCount]; } +/* + Initializes the CPArray. + @return the initialized array +*/ - (id)init { return self; } // Creating an Array - +/* + Creates a new CPArray from anArray. + @param anArray objects in this array will be added to the new array + @return a new CPArray containing the objects of anArray +*/ - (id)initWithArray:(CPArray)anArray { self = [super init]; @@ -139,6 +184,14 @@ import "CPSortDescriptor.j" return self; } +/* + Initializes a the array with the contents of anArray + and optionally performs a deep copy of the objects based on copyItems. + @param anArray the array to copy the data from + @param copyItems if YES, each object will be copied by having a copy message sent to it, and the + returned object will be added to the receiver. Otherwise, no copying will be performed. + @return the initialized array of objects +*/ - (id)initWithArray:(CPArray)anArray copyItems:(BOOL)copyItems { if (!copyItems) @@ -164,6 +217,9 @@ import "CPSortDescriptor.j" return self; } +/* + initializes +*/ - (id)initWithObjects:(Array)anObject, ... { // The arguments array contains self and _cmd, so the first object is at position 2. @@ -176,6 +232,12 @@ import "CPSortDescriptor.j" return self; } +/* + Initializes the array with a JavaScript array of objects. + @param objects the array of objects to add to the receiver + @param aCount the number of objects in objects + @return the initialized CPArray +*/ - (id)initWithObjects:(id)objects count:(unsigned)aCount { self = [super init]; @@ -191,6 +253,10 @@ import "CPSortDescriptor.j" return self; } +/* + Returns a hash of the CPArray. + @return an unsigned integer hash +*/ - (unsigned)hash { if (self.__address == nil) @@ -200,17 +266,30 @@ import "CPSortDescriptor.j" } // Querying an array - +/* + Returns YES if the array contains anObject. Otherwise, it returns NO. + @param anObject the method checks if this object is already in the array +*/ - (BOOL)containsObject:(id)anObject { return [self indexOfObject:anObject] != CPNotFound; } +/* + Returns the number of elements in the array +*/ - (int)count { return length; } +/* + Returns the index of anObject in this array. + If the object is nil or not in the array, + returns CPNotFound. It first attempts to find + a match using isEqual:, then ==. + @param anObject the object to search for +*/ - (int)indexOfObject:(id)anObject { if (anObject === nil) @@ -239,6 +318,14 @@ import "CPSortDescriptor.j" return CPNotFound; } +/* + Returns the index of anObject in the array + within aRange. It first attempts to find + a match using isEqual:, then ==. + @param anObject the object to search for + @param aRange the range to search within + @return the index of the object, or CPNotFound if it was not found. +*/ - (int)indexOfObject:(id)anObject inRange:(CPRange)aRange { if (anObject === nil) @@ -263,6 +350,11 @@ import "CPSortDescriptor.j" return CPNotFound; } +/* + Returns the index of anObject in the array. The test for equality is done using only ==. + @param anObject the object to search for + @return the index of the object in the array. CPNotFound if the object is not in the array. +*/ - (int)indexOfObjectIdenticalTo:(id)anObject { if (anObject === nil) @@ -287,6 +379,14 @@ import "CPSortDescriptor.j" return CPNotFound; } +/* + Returns the index of anObject in the array + within aRange. The test for equality is + done using only ==. + @param anObject the object to search for + @param aRange the range to search within + @return the index of the object, or CPNotFound if it was not found. +*/ - (int)indexOfObjectIdenticalTo:(id)anObject inRange:(CPRange)aRange { if (anObject === nil) @@ -316,6 +416,9 @@ import "CPSortDescriptor.j" return CPNotFound; } +/* + Returns the last object in the array. If the array is empty, returns nil/ +*/ - (id)lastObject { var count = [self count]; @@ -325,18 +428,27 @@ import "CPSortDescriptor.j" return self[count - 1]; } +/* + Returns the object at index anIndex. + @throws CPRangeException if anIndex is out of bounds +*/ - (id)objectAtIndex:(int)anIndex { return self[anIndex]; } +/* + Returns the objects at indexes in a new CPArray. + @param indexes the set of indices + @throws CPRangeException if any of the indices is greater than or equal to the length of the array +*/ - (CPArray)objectsAtIndexes:(CPIndexSet)indexes { var index = [indexes firstIndex], objects = []; while(index != CPNotFound) - { + { [objects addObject:self[index]]; index = [indexes indexGreaterThanIndex:index]; } @@ -344,20 +456,37 @@ import "CPSortDescriptor.j" return objects; } +/* + Returns an enumerator describing the array sequentially + from the first to the last element. You should not modify + the array during enumeration. +*/ - (CPEnumerator)objectEnumerator { return [[_CPArrayEnumerator alloc] initWithArray:self]; } +/* + Returns an enumerator describing the array sequentially + from the last to the first element. You should not modify + the array during enumeration. +*/ - (CPEnumerator)reverseObjectEnumerator { return [[_CPReverseArrayEnumerator alloc] initWithArray:self]; } // Sending messages to elements - +/* + Sends each element in the array a message. + @param aSelector the selector of the message to send + @throws CPInvalidArgumentException if aSelector is nil +*/ - (void)makeObjectsPerformSelector:(SEL)aSelector { + if (!aSelector) + [CPException raise:CPInvalidArgumentException reason:"makeObjectsPerformSelector: 'aSelector' can't be nil"]; + var index = 0, count = length; @@ -365,8 +494,17 @@ import "CPSortDescriptor.j" objj_msgSend(self[index], aSelector); } +/* + Sends each element in the array a message with an argument. + @param aSelector the selector of the message to send + @param anObject the first argument of the message + @throws CPInvalidArgumentException if aSelector is nil +*/ - (void)makeObjectsPerformSelector:(SEL)aSelector withObject:(id)anObject { + if (!aSelector) + [CPException raise:CPInvalidArgumentException reason:"makeObjectsPerformSelector:withObject 'aSelector' can't be nil"]; + var index = 0, count = length; @@ -375,7 +513,11 @@ import "CPSortDescriptor.j" } // Comparing arrays - +/* + Returns the first object found in the receiver (starting at index 0) which is present in the + otherArray as determined by using the -containsObject: method. + @return the first object found, or nil if no common object was found. +*/ - (id)firstObjectCommonWithArray:(CPArray)anArray { if (![anArray count] || ![self count]) @@ -391,6 +533,9 @@ import "CPSortDescriptor.j" return nil; } +/* + Returns true if anArray contains exactly the same objects as the reciever. +*/ - (BOOL)isEqualToArray:(id)anArray { if(length != anArray.length) @@ -400,16 +545,25 @@ import "CPSortDescriptor.j" count = [self count]; for(; index < count; ++index) - if(self[index] != anObject && (!self[index].isa || !anObject.isa || ![self[index] isEqual:anObject])) + if(!self[index] || !anArray[index] || ![self[index] isEqual:anArray[index]]) return NO; return YES; } // Deriving new arrays - +/* + Returns a copy of this array plus anObject inside the copy. + @param anObject the object to be added to the array copy + @throws CPInvalidArgumentException if anObject is nil + @return a new array that should be n+1 in size compared to the receiver. +*/ - (CPArray)arrayByAddingObject:(id)anObject { + if (!anObject) + [CPException raise:CPInvalidArgumentException + reason:"arrayByAddingObject: object can't be nil"]; + var array = [self copy]; array.push(anObject); @@ -417,6 +571,10 @@ import "CPSortDescriptor.j" return array; } +/* + Returns a new array which is the concatenation of self and otherArray (in this precise order). + @param anArray the array that will be concatenated to the receiver's copy +*/ - (CPArray)arrayByAddingObjectsFromArray:(CPArray)anArray { return slice(0).concat(anArray); @@ -437,13 +595,23 @@ import "CPSortDescriptor.j" } */ +/* + Returns a subarray of the receiver containing the objects found in the specified range aRange. + @param aRange the range of objects to be copied into the subarray + @throws CPRangeException if the specified range exceeds the bounds of the array +*/ - (CPArray)subarrayWithRange:(CPRange)aRange { - return slice(aRange.location, CPMaxRange(aRange)); + if (aRange.location < 0 || (aRange.location + CPMaxRange(aRange)) > length) + [CPException raise:CPRangeException reason:"subarrayWithRange: aRange out of bounds"]; + + return slice(aRange.location, maxRange); } // Sorting arrays - +/* + Not yet described. +*/ - (CPArray)sortedArrayUsingDescriptors:(CPArray)descriptors { var sorted = [self copy]; @@ -453,6 +621,14 @@ import "CPSortDescriptor.j" return sorted; } +/* + Returns an array in which the objects are ordered according + to a sort with aFunction. This invokes + -sortUsingFunction:context. + @param aFunction a JavaScript 'Function' type that compares objects + @param aContext context information + @return a new sorted array +*/ - (CPArray)sortedArrayUsingFunction:(Function)aFunction context:(id)aContext { var sorted = [self copy]; @@ -462,6 +638,10 @@ import "CPSortDescriptor.j" return sorted; } +/* + Returns a new array in which the objects are ordered according to a sort with aSelector. + @param aSelector the selector that will perform object comparisons +*/ - (CPArray)sortedArrayUsingSelector:(SEL)aSelector { var sorted = [self copy] @@ -473,6 +653,14 @@ import "CPSortDescriptor.j" // Working with string elements +/* + Returns a string formed by concatenating the objects in the + receiver, with the specified separator string inserted between each part. + If the element is a Cappuccino object, then the description + of that object will be used, otherwise the default JavaScript representation will be used. + @param aString the separator that will separate each object string + @return the string representation of the array +*/ - (CPString)componentsJoinedByString:(CPString)aString { var index = 0, @@ -487,6 +675,9 @@ import "CPSortDescriptor.j" // Creating a description of the array +/* + Returns a human readable description of this array and it's elements. +*/ - (CPString)description { var i = 0, @@ -505,7 +696,13 @@ import "CPSortDescriptor.j" } // Collecting paths - +/* + Returns a new array subset formed by selecting the elements that have + filename extensions from filterTypes. Only elements + that are of type CPString are candidates for inclusion in the returned array. + @param filterTypes an array of CPString objects that contain file extensions (without the '.') + @return a new array with matching paths +*/ - (CPArray)pathsMatchingExtensions:(CPArray)filterTypes { var index = 0, @@ -513,14 +710,18 @@ import "CPSortDescriptor.j" array = []; for(; index < count; ++index) - if (self[index].isa && [self[index] isKindOfClass:[CPString class]] && [filterTypes containsObject:[self[index] pathExtensions]]) + if (self[index].isa && [self[index] isKindOfClass:[CPString class]] && [filterTypes containsObject:[self[index] pathExtension]]) array.push(self[index]); return array; } // Key value coding - +/* + Sets the key-value for each element in the array. + @param aValue the value for the coding + @param aKey the key for the coding +*/ - (void)setValue:(id)aValue forKey:(CPString)aKey { var i = 0, @@ -530,6 +731,11 @@ import "CPSortDescriptor.j" [self[i] setValue:aValue forKey:aKey]; } +/* + Returns the value for aKey from each element in the array. + @param aKey the key to return the value for + @return an array of containing a value for each element in the array +*/ - (CPArray)valueForKey:(CPString)aKey { var i = 0, @@ -544,6 +750,10 @@ import "CPSortDescriptor.j" // Copying arrays +/* + Makes a copy of the receiver. + @return a new CPArray copy +*/ - (id)copy { return slice(0); @@ -554,34 +764,59 @@ import "CPSortDescriptor.j" @implementation CPArray(CPMutableArray) // Creating arrays - +/* + Creates an array able to store at least aCapacity + items. Because CPArray is backed by JavaScript arrays, + this method ends up simply returning a regular array. +*/ + (CPArray)arrayWithCapacity:(unsigned)aCapacity { return [[self alloc] initWithCapacity:aCapacity]; } +/* + Initializes an array able to store at least aCapacity items. Because CPArray + is backed by JavaScript arrays, this method ends up simply returning a regular array. +*/ - (id)initWithCapacity:(unsigned)aCapacity { return self; } // Adding and replacing objects - +/* + Adds anObject to the end of the array. + @param anObject the object to add to the array +*/ - (void)addObject:(id)anObject { push(anObject); } - + +/* + Adds the objects in anArray to the receiver array. + @param anArray the array of objects to add to the end of the receiver +*/ - (void)addObjectsFromArray:(CPArray)anArray { splice.apply(self, [length, 0].concat(anArray)); } +/* + Inserts an object into the receiver at the specified location. + @param anObject the object to insert into the array + @param anIndex the location to insert anObject at +*/ - (void)insertObject:(id)anObject atIndex:(int)anIndex { splice(anIndex, 0, anObject); } +/* + Inserts the objects in the provided array into the receiver at the indexes specified. + @param objects the objects to add to this array + @param anIndexSet the indices for the objects +*/ - (void)insertObjects:(CPArray)objects atIndexes:(CPIndexSet)anIndexSet { var index = 0, @@ -590,12 +825,23 @@ import "CPSortDescriptor.j" while ((position = [indexes indexGreaterThanIndex:position]) != CPNotFound) [self insertObject:objects[index++] atindex:position]; } - + +/* + Replaces the element at anIndex with anObject. + The current element at position anIndex will be removed from the array. + @param anIndex the position in the array to place anObject +*/ - (void)replaceObjectAtIndex:(int)anIndex withObject:(id)anObject { self[anIndex] = anObject; } +/* + Replace the elements at the indices specified by anIndexSet with + the objects in objects. + @param anIndexSet the set of indices to array positions that will be replaced + @param objects the array of objects to place in the specified indices +*/ - (void)replaceObjectsAtIndexes:(CPIndexSet)anIndexSet withObjects:(CPArray)objects { var i = 0, @@ -608,6 +854,14 @@ import "CPSortDescriptor.j" } } +/* + Replaces some of the receiver's objects with objects from anArray. Specifically, the elements of the + receiver in the range specified by aRange, + with the elements of anArray in the range specified by otherRange. + @param aRange the range of elements to be replaced in the receiver + @param anArray the array to retrieve objects for placement into the receiver + @param otherRange the range of objects in anArray to pull from for placement into the receiver +*/ - (void)replaceObjectsInRange:(CPRange)aRange withObjectsFromArray:(CPArray)anArray range:(CPRange)otherRange { if (!otherRange.location && otherRange.length == [anArray count]) @@ -616,11 +870,22 @@ import "CPSortDescriptor.j" splice.apply(self, [aRange.location, aRange.length].concat([anArray subarrayWithRange:otherRange])); } +/* + Replaces some of the receiver's objects with the objects from + anArray. Specifically, the elements of the + receiver in the range specified by aRange. + @param aRange the range of elements to be replaced in the receiver + @param anArray the array to retrieve objects for placement into the receiver +*/ - (void)replaceObjectsInRange:(CPRange)aRange withObjectsFromArray:(CPArray)anArray { splice.apply(self, [aRange.location, aRange.length].concat(anArray)); } +/* + Sets the contents of the receiver to be identical to the contents of anArray. + @param anArray the array of objects used to replace the receiver's objects +*/ - (void)setArray:(CPArray)anArray { if(self == anArray) return; @@ -629,22 +894,36 @@ import "CPSortDescriptor.j" } // Removing Objects - +/* + Removes all objects from this array. +*/ - (void)removeAllObjects { splice(0, length); } - + +/* + Removes the last object from the array. +*/ - (void)removeLastObject { pop(); } +/* + Removes all entries of anObject from the array. + @param anObject the object whose entries are to be removed +*/ - (void)removeObject:(id)anObject { [self removeObject:anObject inRange:CPMakeRange(0, length)]; } +/* + Removes all entries of anObject from the array, in the range specified by aRange. + @param anObject the object to remove + @param aRange the range to search in the receiver for the object +*/ - (void)removeObject:(id)anObject inRange:(CPRange)aRange { var index; @@ -656,11 +935,19 @@ import "CPSortDescriptor.j" } } +/* + Removes the object at anIndex. + @param anIndex the location of the element to be removed +*/ - (void)removeObjectAtIndex:(int)anIndex { splice(anIndex, 1); } +/* + Removes the objects at the indices specified by CPIndexSet. + @param anIndexSet the indices of the elements to be removed from the array +*/ - (void)removeObjectsAtIndexes:(CPIndexSet)anIndexSet { var index = [anIndexSet lastIndex]; @@ -672,11 +959,23 @@ import "CPSortDescriptor.j" } } +/* + Remove the first instance of anObject from the array. + The search for the object is done using ==. + @param anObject the object to remove +*/ - (void)removeObjectIdenticalTo:(id)anObject { [self removeObjectIdenticalTo:anObject inRange:CPMakeRange(0, length)]; } +/* + Remove the first instance of anObject from the array, + within the range specified by aRange. + The search for the object is done using ==. + @param anObject the object to remove + @param aRange the range in the array to search for the object +*/ - (void)removeObjectIdenticalTo:(id)anObject inRange:(CPRange)aRange { var index; @@ -688,6 +987,10 @@ import "CPSortDescriptor.j" } } +/* + Remove the objects in anArray from the receiver array. + @param anArray the array of objects to remove from the receiver +*/ - (void)removeObjectsInArray:(CPArray)anArray { var index = 0, @@ -697,13 +1000,21 @@ import "CPSortDescriptor.j" [self removeObject:anArray[index]]; } +/* + Removes all the objects in the specified range from the receiver. + @param aRange the range of objects to remove +*/ - (void)removeObjectsInRange:(CPRange)aRange { splice(aRange.location, aRange.length); } // Rearranging objects - +/* + Swaps the elements at the two specified indices. + @param anIndex the first index to swap from + @param otherIndex the second index to swap from +*/ - (void)exchangeObjectAtIndex:(unsigned)anIndex withObjectAtIndex:(unsigned)otherIndex { var temporary = self[anIndex]; @@ -727,11 +1038,20 @@ import "CPSortDescriptor.j" }); } +/* + Sorts the receiver array using a JavaScript function as a comparator, and a specified context. + @param aFunction a JavaScript function that will be called to compare objects + @param aContext an object that will be passed to aFunction with comparison +*/ - (void)sortUsingFunction:(Function)aFunction context:(id)aContext { sort(function(lhs, rhs) { return aFunction(lhs, rhs, aContext); }); } +/* + Sorts the receiver array using an Objective-J method as a comparator. + @param aSelector the selector for the method to call for comparison +*/ - (void)sortUsingSelector:(SEL)aSelector { sort(function(lhs, rhs) { return objj_msgSend(lhs, aSelector, rhs); }); @@ -753,6 +1073,11 @@ import "CPSortDescriptor.j" @end +/* + This class is just an empty subclass of CPArray. + CPArray already implements mutable methods and + this class only exists for source compatability. +*/ @implementation CPMutableArray : CPArray @end diff --git a/Foundation/CPCoder.j b/Foundation/CPCoder.j index 52e057e067..3c670eae62 100644 --- a/Foundation/CPCoder.j +++ b/Foundation/CPCoder.j @@ -23,66 +23,115 @@ import "CPObject.j" import "CPException.j" +/* + Top-level class defining methods for use when archiving (encoding) objects to a byte array + or file, and when restoring (decoding) objects. +*/ @implementation CPCoder : CPObject { } +/* + Returns a flag indicating whether the receiver supports keyed coding. The default implementation returns + NO. Subclasses supporting keyed coding must override this to return YES. +*/ -(BOOL)allowsKeyedCoding { return NO; } --(void)encodeValueOfObjCType:(const char *)aType at:(const void *)anObject +/* + Encodes a structure or object of a specified type. Usually this + is used for primitives though it can be used for objects as well. + Subclasses must override this method. + @param aType the structure or object type + @param anObject the object to be encoded +*/ +-(void)encodeValueOfObjCType:(CPString)aType at:(id)anObject { - NSInvalidAbstractInvocation(); + CPInvalidAbstractInvocation(); } +/* + Encodes a data object. Subclasses must override this method. + @param aData the object to be encoded. +*/ -(void)encodeDataObject:(CPData)aData { - NSInvalidAbstractInvocation(); + CPInvalidAbstractInvocation(); } +/* + Encodes an object. Subclasses must override this method. + @param anObject the object to be encoded +*/ -(void)encodeObject:(id)anObject { // [self encodeValueOfObjCType:@encode(id) at:object]; } +/* + Encodes a point + @param aPoint the point to be encoded. +*/ - (void)encodePoint:(CPPoint)aPoint { [self encodeNumber:aPoint.x]; [self encodeNumber:aPoint.y]; } -- (void)encodeRect:(CPRect)aRect +/* + Encodes a CGRect + @param aRect the rectangle to be encoded. +*/ +- (void)encodeRect:(CGRect)aRect { [self encodePoint:aRect.origin]; [self encodeSize:aRect.size]; } +/* + Encodes a CGSize + @param aSize the size to be encoded +*/ - (void)encodeSize:(CPSize)aSize { [self encodeNumber:aSize.width]; [self encodeNumber:aSize.height]; } +/* + Encodes a property list. Not yet implemented. + @param aPropertyList the property list to be encoded +*/ -(void)encodePropertyList:(id)aPropertyList { // [self encodeValueOfObjCType:@encode(id) at:&propertyList]; } +/* + Encodes the root object of a group of Obj-J objects. + @param rootObject the root object to be encoded. +*/ -(void)encodeRootObject:(id)anObject { [self encodeObject:anObject]; } - +/* + Encodes an object. + @param anObject the object to be encoded. +*/ -(void)encodeBycopyObject:(id)anObject { [self encodeObject:object]; } - +/* + Encodes an object. + @param anObject the object to be encoded. +*/ -(void)encodeConditionalObject:(id)anObject { [self encodeObject:object]; @@ -92,6 +141,12 @@ import "CPException.j" @implementation CPObject (CPCoding) +/* + Called after an object is unarchived in case a different object should be used in place of it. + The defaut method returns self. Interested subclasses should override this. + @param aDecoder + @return the original object or it's substitute. +*/ - (id)awakeAfterUsingCoder:(CPCoder)aDecoder { return self; diff --git a/Foundation/CPDictionary.j b/Foundation/CPDictionary.j index 900396211d..92d74d41d1 100755 --- a/Foundation/CPDictionary.j +++ b/Foundation/CPDictionary.j @@ -23,7 +23,9 @@ //import "CPRange.j" import "CPObject.j" import "CPEnumerator.j" +import "CPException.j" +/* @ignore */ @implementation _CPDictionaryValueEnumerator : CPEnumerator { CPEnumerator _keyEnumerator; @@ -55,35 +57,77 @@ import "CPEnumerator.j" @end +/* + A dictionary is the standard way of passing around key-value pairs in + the Cappuccino framework. It is similar to the + Java map interface, + except all keys are CPStrings and values can be any + Cappuccino or JavaScript object.

+ +

If you are familiar with dictionaries in Cocoa, you'll notice that + there is no CPMutableDictionary class. The regular CPDictionary + has setObject: and removeObjectForKey: methods. + In Cappuccino there is no distinction between immutable and mutable classes. + They are all mutable. +*/ @implementation CPDictionary : CPObject { } +/* + @ignore +*/ + (id)alloc { return new objj_dictionary(); } +/* + Returns a new empty CPDictionary. +*/ + (id)dictionary { return [[self alloc] init]; } +/* + Returns a new dictionary, initialized with the contents of aDictionary. + @param aDictionary the dictionary to copy key-value pairs from + @return the new CPDictionary +*/ + (id)dictionaryWithDictionary:(CPDictionary)aDictionary { return [[self alloc] initWithDictionary:aDictionary]; } +/* + Creates a new dictionary with single key-value pair. + @param anObject the object for the paring + @param aKey the key for the pairing + @return the new CPDictionary +*/ + (id)dictionaryWithObject:(id)anObject forKey:(id)aKey { return [[self alloc] initWithObjects:[anObject] forKeys:[aKey]]; } +/* + Creates a dictionary with multiple key-value pairs. + @param objects the objects to place in the dictionary + @param keys the keys for each of the objects + @throws CPInvalidArgumentException if the number of objects and keys is different + @return the new CPDictionary +*/ + (id)dictionaryWithObjects:(CPArray)objects forKeys:(CPArray)keys { return [[self alloc] initWithObjects:objects forKeys:keys]; } - + +/* + Initializes the dictionary with the contents of another dictionary. + @param aDictionary the dictionary to copy key-value pairs from + @return the initialized dictionary +*/ - (id)initWithDictionary:(CPDictionary)aDictionary { var key = "", @@ -94,11 +138,21 @@ import "CPEnumerator.j" return dictionary; } - + +/* + Initializes the dictionary from the arrays of keys and objects. + @param objects the objects to put in the dictionary + @param keyArray the keys for the objects to put in the dictionary + @throws CPInvalidArgumentException if the number of objects and keys is different + @return the initialized dictionary +*/ - (id)initWithObjects:(CPArray)objects forKeys:(CPArray)keyArray { self = [super init]; + if ([objects count] != [keyArray count]) + [CPException raise:CPInvalidArgumentException reason:"Counts are different.("+[objects count]+"!="+[keyArray count]+")"]; + if (self) { var i = [keyArray count]; @@ -110,16 +164,25 @@ import "CPEnumerator.j" return self; } +/* + Returns the number of entries in the dictionary +*/ - (int)count { return count; } +/* + Returns an array of keys for all the entries in the dictionary. +*/ - (CPArray)allKeys { return keys; } +/* + Returns an array of values for all the entries in the dictionary. +*/ - (CPArray)allValues { var index = keys.length, @@ -131,11 +194,17 @@ import "CPEnumerator.j" return values; } +/* + Returns an enumerator that enumerates over all the dictionary's keys. +*/ - (CPEnumerator)keyEnumerator { return [keys objectEnumerator]; } +/* + Returns an enumerator that enumerates over all the dictionary's values. +*/ - (CPEnumerator)objectEnumerator { return [[_CPDictionaryValueEnumerator alloc] initWithDictionary:self]; @@ -194,6 +263,11 @@ import "CPEnumerator.j" return this._objects.objectEnumerator(); } */ +/* + Returns the object for the entry with key aKey. + @param aKey the key for the object's entry + @return the object for the entry +*/ - (id)objectForKey:(CPString)aKey { // We should really do this with inlining or something of that nature. @@ -232,6 +306,9 @@ import "CPEnumerator.j" while(key= keyEnumerator.nextObject()) this.setObjectForKey(aDictionary.objectForKey(key), key); } */ +/* + Removes all the entries from the dictionary. +*/ - (void)removeAllObjects { keys = []; @@ -239,6 +316,10 @@ import "CPEnumerator.j" buckets = {}; } +/* + Removes the entry for the specified key. + @param aKey the key of the entry to be removed +*/ - (void)removeObjectForKey:(id)aKey { dictionary_removeValue(self, aKey); @@ -270,6 +351,11 @@ import "CPEnumerator.j" while(i--) this._dictionary[this._keys[i]]= { object: this._objects[i], index: i }; } */ +/* + Adds an entry into the dictionary. + @param anObject the object for the entry + @param aKey the entry's key +*/ - (void)setObject:(id)anObject forKey:(id)aKey { dictionary_setValue(self, aKey, anObject); @@ -287,6 +373,9 @@ import "CPEnumerator.j" } */ +/* + Returns a human readable description of the dictionary. +*/ - (CPString)description { var description = @"CPDictionary {\n"; @@ -305,11 +394,20 @@ import "CPEnumerator.j" @implementation CPDictionary (CPCoding) +/* + Initializes the dictionary by unarchiving the data from a coder. + @param aCoder the coder from which the data will be unarchived. + @return the initialized dictionary +*/ - (id)initWithCoder:(CPCoder)aCoder { return [aCoder _decodeDictionaryOfObjectsForKey:@"CP.objects"]; } +/* + Archives the dictionary to a provided coder. + @param aCoder the coder to which the dictionary data will be archived. +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder _encodeDictionaryOfObjects:self forKey:@"CP.objects"]; diff --git a/Foundation/CPEnumerator.j b/Foundation/CPEnumerator.j index f9c27aeb07..73914071e7 100755 --- a/Foundation/CPEnumerator.j +++ b/Foundation/CPEnumerator.j @@ -22,13 +22,27 @@ import "CPObject.j" +/* + CPEnumerator is a superclass (with useless method bodies) + that defines an interface for subclasses to follow. The purpose of an + enumerator is to be a convenient system for traversing over the elements + of a collection of objects. +*/ @implementation CPEnumerator : CPObject +/* + Returns the next object in the collection. + No particular ordering is guaranteed. +*/ - (id)nextObject { return nil; } +/* + Returns all objects in the collection in an array. + No particular ordering is guaranteed. +*/ - (CPArray)allObjects { return []; diff --git a/Foundation/CPException.j b/Foundation/CPException.j index ab797c1dae..d112b9136b 100755 --- a/Foundation/CPException.j +++ b/Foundation/CPException.j @@ -25,28 +25,63 @@ import "CPObject.j" import "CPString.j" -CPInvalidArgumentException = @"CPInvalidArgumentException"; +CPInvalidArgumentException = "CPInvalidArgumentException"; +CPUnsupportedMethodException = "CPUnsupportedMethodException"; +CPRangeException = "CPRangeException"; +CPInternalInconsistencyException = "CPInternalInconsistencyException"; +/* + An example of throwing an exception in Objective-J: +

+// some code here...
+if (input == nil)
+    [CPException raise:"MyException" reason:"You didn't do something right."];
+    
+// code that gets executed if no exception was raised
+
+*/ @implementation CPException : CPObject { } +/* + @ignore +*/ + (id)alloc { return new objj_exception(); } +/* + Raises an exception with a name and reason. + @param aName the name of the exception to raise + @param aReason the reason for the exception +*/ + (void)raise:(CPString)aName reason:(CPString)aReason { [[self exceptionWithName:aName reason:aReason userInfo:nil] raise]; } -+ (id)exceptionWithName:(CPString)aName reason:(CPString)aReason userInfo:(id)aUserInfo +/* + Creates an exception with a name, reason and user info. + @param aName the name of the exception + @param aReason the reason the exception occurred + @param aUserInfo a dictionary containing information about the exception + @return the new exception +*/ ++ (CPException)exceptionWithName:(CPString)aName reason:(CPString)aReason userInfo:(CPDictionary)aUserInfo { return [[self alloc] initWithName:aName reason:aReason userInfo:aUserInfo]; } -- (id)initWithName:(CPString)aName reason:(CPString)aReason userInfo:(id)aUserInfo +/* + Initializes the exception. + @param aName the name of the exception + @param aReason the reason for the exception + @param aUserInfo a dictionary containing information about the exception + @return the initialized exception +*/ +- (id)initWithName:(CPString)aName reason:(CPString)aReason userInfo:(CPDictionary)aUserInfo { self = [super init]; @@ -60,26 +95,41 @@ CPInvalidArgumentException = @"CPInvalidArgumentException"; return self; } +/* + Returns the name of the exception. +*/ - (CPString)name { return name; } +/* + Returns the reason for the exception. +*/ - (CPString)reason { return reason; } -- (id)userInfo +/* + Returns data containing info about the receiver. +*/ +- (CPDictionary)userInfo { return userInfo; } +/* + Returns the exception's reason. +*/ - (CPString)description { return reason; } +/* + Raises the exception and causes the program to go to the exception handler. +*/ - (void)raise { objj_exception_throw(self); @@ -98,6 +148,11 @@ CPInvalidArgumentException = @"CPInvalidArgumentException"; @implementation CPException (CPCoding) +/* + Initializes the exception with data from a coder. + @param aCoder the coder from which to read the exception data + @return the initialized exception +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super init]; @@ -112,6 +167,10 @@ CPInvalidArgumentException = @"CPInvalidArgumentException"; return self; } +/* + Encodes the exception's data into a coder. + @param aCoder the coder to which the data will be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeObject:name forKey:CPExceptionNameKey]; diff --git a/Foundation/CPIndexSet.j b/Foundation/CPIndexSet.j index 7c3b8857b8..f662ff22e0 100644 --- a/Foundation/CPIndexSet.j +++ b/Foundation/CPIndexSet.j @@ -23,6 +23,9 @@ import "CPRange.j" import "CPObject.j" +/* + Instances of this class are collections of numbers. Each integer can appear in a collection only once. +*/ @implementation CPIndexSet : CPObject { unsigned _count; @@ -31,17 +34,26 @@ import "CPObject.j" } // Creating an Index Set - +/* + Returns a new empty index set. +*/ + (id)indexSet { return [[self alloc] init]; } +/* + Returns a new index set with just one index. +*/ + (id)indexSetWithIndex:(int)anIndex { return [[self alloc] initWithIndex:anIndex]; } +/* + Returns a new index set with all the numbers in the specified range. + @param aRange the range of numbers to add to the index set. +*/ + (id)indexSetWithIndexesInRange:(CPRange)aRange { return [[self alloc] initWithIndexesInRange:aRange]; @@ -63,6 +75,10 @@ import "CPObject.j" return self; } +/* + Initializes the index set with a single index. + @return the initialized index set +*/ - (id)initWithIndex:(int)anIndex { self = [super init]; @@ -77,6 +93,11 @@ import "CPObject.j" return self; } +/* + Initializes the index set with numbers from the specified range. + @param aRange the range of numbers to add to the index set + @return the initialized index set +*/ - (id)initWithIndexesInRange:(CPRange)aRange { self = [super init]; @@ -91,6 +112,11 @@ import "CPObject.j" return self; } +/* + Initializes the index set with another index set. + @param anIndexSet the index set from which to read the initial index set + @return the initialized index set +*/ - (id)initWithIndexSet:(CPIndexSet)anIndexSet { self = [super init]; @@ -112,7 +138,11 @@ import "CPObject.j" } // Querying an Index Set - +/* + Compares the receiver with the provided index set. + @param anIndexSet the index set to compare to + @return YES if the receiver and the index set are functionally equivalent +*/ - (BOOL)isEqualToIndexSet:(CPIndexSet)anIndexSet { // Comparisons to ourself are always return YES. @@ -135,11 +165,20 @@ import "CPObject.j" return YES; } +/* + Returns YES if the index set contains the specified index. + @param anIndex the index to check for in the set + @return YES if anIndex is in the receiver index set +*/ - (BOOL)containsIndex:(unsigned)anIndex { return [self containsIndexesInRange:CPMakeRange(anIndex, 1)]; } +/* + Returns YES if the index set contains all the numbers in the specified range. + @param aRange the range of numbers to check for in the index set +*/ - (BOOL)containsIndexesInRange:(CPRange)aRange { if(!_count) @@ -167,6 +206,10 @@ import "CPObject.j" return NO; } +/* + Returns YES if the receving index set contains all the indices in the argument. + @param anIndexSet the set of indices to check for in the receiving index set +*/ - (BOOL)containsIndexes:(CPIndexSet)anIndexSet { // Return YES if anIndexSet has no indexes @@ -188,6 +231,11 @@ import "CPObject.j" return YES; } +/* + Checks if the receiver contains at least one number in aRange. + @param aRange the range of numbers to check. + @return YES if the receiving index set contains at least one number in the provided range +*/ - (BOOL)intersectsIndexesInRange:(CPRange)aRange { // This is fast thanks to the _cachedIndexRange. @@ -207,23 +255,35 @@ import "CPObject.j" return NO; } +/* + The number of indices in the set +*/ - (int)count { return _count; } // Accessing Indexes - +/* + Return the first index in the set +*/ - (int)firstIndex { return _count ? _ranges[0].location : CPNotFound; } +/* + Returns the last index in the set +*/ - (int)lastIndex { return _count ? CPMaxRange(_ranges[_ranges.length - 1]) - 1 : CPNotFound; } +/* + Returns the first index value in the receiver which is greater than anIndex. + @return the closest index or CPNotFound if no match was found +*/ - (unsigned)indexGreaterThanIndex:(unsigned)anIndex { if(!_count) @@ -245,6 +305,10 @@ import "CPObject.j" return anIndex; } +/* + Returns the first index value in the receiver which is less than anIndex. + @return the closest index or CPNotFound if no match was found +*/ - (unsigned)indexLessThanIndex:(unsigned)anIndex { if (!_count) @@ -268,17 +332,34 @@ import "CPObject.j" return CPNotFound; } +/* + Returns the first index value in the receiver which is greater than or equal to anIndex. + @return the matching index or CPNotFound if no match was found +*/ - (unsigned int)indexGreaterThanOrEqualToIndex:(unsigned)anIndex { return [self indexGreaterThanIndex:anIndex - 1]; } +/* + Returns the first index value in the receiver which is less than or equal to anIndex. + @return the matching index or CPNotFound if no match was found +*/ - (unsigned int)indexLessThanOrEqualToIndex:(unsigned)anIndex { return [self indexLessThanIndex:anIndex + 1]; } -- (unsigned)getIndexes:(CPArray)anArray maxCount:(unsigned)aMaxCount inIndexRange:(CPRangePointer)aRangePointer +/* + Fills up the specified array with numbers from the index set within + the specified range. The method stops filling up the array until the + aMaxCount number have been added or the range maximum is reached. + @param anArray the array to fill up + @param aMaxCount the maximum number of numbers to adds + @param aRangePointer the range of indices to add + @return the number of elements added to the array +*/ +- (unsigned)getIndexes:(CPArray)anArray maxCount:(unsigned)aMaxCount inIndexRange:(CPRange)aRangePointer { if (!_count || aMacCount <= 0 || aRangePointer && !aRangePointer.length) return 0; @@ -350,12 +431,19 @@ import "CPObject.j" @implementation CPIndexSet(CPMutableIndexSet) // Adding indexes. - +/* + Adds an index to the set. + @param anIndex the index to add +*/ - (void)addIndex:(unsigned)anIndex { [self addIndexesInRange:CPMakeRange(anIndex, 1)]; } +/* + Adds indices to the set + @param anIndexSet a set of indices to add to the receiver +*/ - (void)addIndexes:(CPIndexSet)anIndexSet { var i = 0, @@ -367,6 +455,10 @@ import "CPObject.j" [self addIndexesInRange:ranges[i]]; } +/* + Adds the range of indices to the set + @param aRange the range of numbers to add as indices to the set +*/ - (void)addIndexesInRange:(CPRange)aRange { if (_ranges.length == 0) @@ -457,12 +549,20 @@ import "CPObject.j" } // Removing Indexes - +/* + Removes an index from the set + @param anIndex the index to remove +*/ - (void)removeIndex:(unsigned int)anIndex { [self removeIndexesInRange:CPMakeRange(anIndex, 1)]; } +/* + Removes the indices from the receiving set. + @param anIndexSet the set of indices to remove + from the receiver +*/ - (void)removeIndexes:(CPIndexSet)anIndexSet { var i = 0, @@ -474,6 +574,9 @@ import "CPObject.j" [self removeIndexesInRange:ranges[i]]; } +/* + Removes all indices from the set +*/ - (void)removeAllIndexes { _ranges = []; @@ -481,6 +584,11 @@ import "CPObject.j" _cachedRangeIndex = 0; } +/* + Removes the indices in the range from the + set. + @param aRange the range of indices to remove +*/ - (void)removeIndexesInRange:(CPRange)aRange { // FIXME: Should we really use SOERangeIndex here? There is no real @@ -543,7 +651,12 @@ import "CPObject.j" } // Shifting Index Groups - +/* + Shifts the values of indices left or right by a specified amount. + @param anIndex the index to start the shifting operation from (inclusive) + @param aDelta the amount and direction to shift. A positive value shifts to + the right. A negative value shifts to the left. +*/ - (void)shiftIndexesStartingAtIndex:(unsigned)anIndex by:(int)aDelta { if (!_count || aDelta == 0) @@ -624,6 +737,12 @@ var CPIndexSetCountKey = @"CPIndexSetCountKey", @implementation CPIndexSet (CPCoding) +/* + Initializes the index set from a coder. + @param aCoder the coder from which to read the + index set data + @return the initialized index set +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super init]; @@ -645,6 +764,11 @@ var CPIndexSetCountKey = @"CPIndexSetCountKey", return self; } +/* + Writes out the index set to the specified coder. + @param aCoder the coder to which the index set will + be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeInt:_count forKey:CPIndexSetCountKey]; @@ -664,11 +788,23 @@ var CPIndexSetCountKey = @"CPIndexSetCountKey", @implementation CPIndexSet (CPCopying) +/* + Creates a deep copy of the index set. The returned copy + is mutable. The reason for the two copy methods is for + source compatability with GNUStep code. + @return the index set copy +*/ - (id)copy { return [[[self class] alloc] initWithIndexSet:self]; } +/* + Creates a deep copy of the index set. The returned copy + is mutable. The reason for the two copy methods is for + source compatability with GNUStep code. + @return the index set copy +*/ - (id)mutableCopy { return [[[self class] alloc] initWithIndexSet:self]; @@ -676,6 +812,11 @@ var CPIndexSetCountKey = @"CPIndexSetCountKey", @end +/* + This class is an empty of subclass of CPIndexSet. + CPIndexSet already implements mutable methods, and + this class only exists for source compatability. +*/ @implementation CPMutableIndexSet : CPIndexSet @end diff --git a/Foundation/CPInvocation.j b/Foundation/CPInvocation.j index 9566889076..bef546a58a 100644 --- a/Foundation/CPInvocation.j +++ b/Foundation/CPInvocation.j @@ -21,7 +21,11 @@ */ import "CPObject.j" +import "CPException.j" +/* + A CPInvocation is an object representation of a message sent to an object. +*/ @implementation CPInvocation : CPObject { id _returnValue; @@ -30,12 +34,21 @@ import "CPObject.j" } // Creating CPInvocation Objects - +/* + Returns a new CPInvocation that represents a message to a method. + @param aMethodSignature the signature of the method to message + @return the new invocation +*/ + (id)invocationWithMethodSignature:(CPMethodSignature)aMethodSignature { return [[self alloc] initWithMethodSignature:aMethodSignature]; } +/* + Initializes the invocation with a provided method signature + @param aMethodSignature the signature of the method to message + @return the initialized invocation +*/ - (id)initWithMethodSignature:(CPMethodSignature)aMethodSignature { self = [super init]; @@ -50,54 +63,91 @@ import "CPObject.j" } // Configuring an Invocation Object - +/* + Sets the invocation's selector. + @param the invocation selector +*/ - (void)setSelector:(SEL)aSelector { _arguments[1] = aSelector; } +/* + Returns the invocation's selector +*/ - (SEL)selector { return _arguments[1]; } +/* + Sets the invocation's target + @param aTarget the invocation target +*/ - (void)setTarget:(id)aTarget { _arguments[0] = aTarget; } +/* + Returns the invocation's target +*/ - (id)target { return _arguments[0]; } +/* + Sets a method argument for the invocation. Arguments 0 and 1 are self and _cmd. + @param anArgument the argument to add + @param anIndex the index of the argument in the method +*/ - (void)setArgument:(id)anArgument atIndex:(unsigned)anIndex { _arguments[anIndex] = anArgument; } +/* + Returns the argument at the specified index. Arguments 0 and 1 are + self and _cmd respectively. Thus, method arguments start at 2. + @param anIndex the index of the argument to return + @throws CPInvalidArgumentException if anIndex is greater than or equal to the invocation's number of arguments. +*/ - (id)argumentAtIndex:(unsigned)anIndex { return _arguments[anIndex]; } +/* + Sets the invocation's return value + @param the invocation return value +*/ - (void)setReturnValue:(id)aReturnValue { _returnValue = aReturnValue; } +/* + Returns the invocation's return value +*/ - (id)returnValue { return _returnValue; } // Dispatching an Invocation - +/* + Sends the encapsulated message to the stored target. +*/ - (void)invoke { _returnValue = objj_msgSend.apply(objj_msgSend, _arguments); } +/* + Sends the encapsulated message to the specified target. + @param the target to which the message will be sent +*/ - (void)invokeWithTarget:(id)aTarget { _arguments[0] = aTarget; @@ -111,6 +161,11 @@ var CPInvocationArguments = @"CPInvocationArguments", @implementation CPInvocation (CPCoding) +/* + Initializes the invocation with data from a coder. + @param aCoder the coder from which to obtain initialization data + @return the initialized invocation +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super init]; @@ -124,6 +179,10 @@ var CPInvocationArguments = @"CPInvocationArguments", return self; } +/* + Writes out the invocation's data to the provided coder. + @param aCoder the coder to which the data will be written +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeObject:_returnValue forKey:CPInvocationReturnValue]; diff --git a/Foundation/CPKeyValueCoding.j b/Foundation/CPKeyValueCoding.j index 260179071b..d0cdbbd13d 100644 --- a/Foundation/CPKeyValueCoding.j +++ b/Foundation/CPKeyValueCoding.j @@ -29,6 +29,7 @@ import "CPObject.j" return YES; } +/* @ignore */ + (SEL)_accessorForKey:(CPString)aKey { var capitalizedKey = aKey.charAt(0).toUpperCase() + aKey.substr(1), @@ -36,12 +37,14 @@ import "CPObject.j" if ([self instancesRespondToSelector:selector] || [self instancesRespondToSelector:selector = CPSelectorFromString(aKey)] || + [self instancesRespondToSelector:selector = CPSelectorFromString("_"+aKey)] || [self instancesRespondToSelector:selector = CPSelectorFromString("is" + capitalizedKey)]) return selector; return nil; } +/* @ignore */ + (SEL)_modifierForKey:(CPString)aKey { var selector = CPSelectorFromString("set" + aKey.charAt(0).toUpperCase() + aKey.substr(1) + ':'); @@ -52,6 +55,7 @@ import "CPObject.j" return nil; } +/* @ignore */ - (CPString)_ivarForKey:(CPString)aKey { var ivar, diff --git a/Foundation/CPKeyedArchiver.j b/Foundation/CPKeyedArchiver.j index 02c71570c5..0951000d2a 100644 --- a/Foundation/CPKeyedArchiver.j +++ b/Foundation/CPKeyedArchiver.j @@ -53,11 +53,44 @@ var _CPKeyedArchiverNullString = "$null", var _CPKeyedArchiverStringClass = Nil, _CPKeyedArchiverNumberClass = Nil; +/* @ignore */ @implementation _CPKeyedArchiverValue : CPValue { } @end +/* + Implements keyed archiving of object graphs. Archiving means to + write data out in a format that be read in again later, or possibly + stored in a file. To read the data back in, use a + CPKeyedUnarchiver. + + @delegate -(void)archiverWillFinish:(CPKeyedArchiver)archiver; + Called when the encoding is about to finish. + @param archiver the archiver that's about to finish + + @delegate -(void)archiver:(CPKeyedArchiver)archiver didEncodeObject:(id)object; + Called when an object is encoded into the archiver. + @param archiver the archiver that encoded the object + @param object the object that was encoded + + @delegate -(void)archiverDidFinish:(CPKeyedArchiver)archiver; + Called when the archiver finishes encoding. + @param archiver the arhiver that finished encoding + + @delegate -(id)archiver:(CPKeyedArchiver)archiver willEncodeObject:(id)object; + Called when an object is about to be encoded. Allows the delegate to replace + the object that gets encoded with a substitute or nil. + @param archiver the archiver encoding the object + @param object the candidate object for encoding + @return the object to encode + + @delegate -(void)archiver:(CPKeyedArchiver)archiver willReplaceObject:(id)object withObject:(id)newObject; + Called when an object is being replaced in the archiver. + @param archiver the archiver encoding the object + @param object the object to be replaced + @param newObject the replacement object +*/ @implementation CPKeyedArchiver : CPCoder { id _delegate; @@ -80,6 +113,9 @@ var _CPKeyedArchiverStringClass = Nil, } +/* + @ignore +*/ + (void)initialize { if (self != [CPKeyedArchiver class]) @@ -96,6 +132,11 @@ var _CPKeyedArchiverStringClass = Nil, return YES; } +/* + Archives the specified object. + @param anObject the object to archive + @return the archived object +*/ + (CPData)archivedDataWithRootObject:(id)anObject { var data = [CPData dataWithPlistObject:nil], @@ -108,7 +149,11 @@ var _CPKeyedArchiverStringClass = Nil, } // Initializing an NSKeyedArchiver object - +/* + Initializes the keyed archiver with the specified CPMutableData for writing. + @param data the object to archive to + @return the initialized keyed archiver +*/ - (id)initForWritingWithMutableData:(CPMutableData)data { self = [super init]; @@ -134,6 +179,10 @@ var _CPKeyedArchiverStringClass = Nil, } // Archiving Data +/* + Finishes up writing any left over data, and notifies delegates. + After calling this method, the archiver can not encode anymore objects. +*/ - (void)finishEncoding { if (_delegate && _delegateSelectors & _CPKeyedArchiverWillFinishSelector) @@ -171,38 +220,67 @@ var _CPKeyedArchiverStringClass = Nil, [_delegate archiverDidFinish:self]; } -- (void)outputFormat +/* + Returns the property list format used to archive objects. +*/ +- (CPPropertyListFormat)outputFormat { return _outputFormat; } +/* + Sets the property list format the archiver should use to archive objects. + @param aPropertyListFormat the format to use +*/ - (void)setOutputFormat:(CPPropertyListFormat)aPropertyListFormat { _outputFormat = aPropertyListFormat; } +/* + Encodes a BOOL value + @param aBool the BOOL value + @param aKey the key to associate with the BOOL +*/ - (void)encodeBool:(BOOL)aBOOL forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, aBOOL, NO) forKey:aKey]; } +/* + Encodes a double value + @param aDouble the double value + @param aKey the key to associate with the double +*/ - (void)encodeDouble:(double)aDouble forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, aDouble, NO) forKey:aKey]; } +/* + Encodes a float value + @param aFloat the float value + @param aKey the key to associate with the float +*/ - (void)encodeFloat:(float)aFloat forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, aFloat, NO) forKey:aKey]; } +/* + Encodes a int value + @param anInt the int value + @param aKey the key to associate with the int +*/ - (void)encodeInt:(float)anInt forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, anInt, NO) forKey:aKey]; } // Managing Delegates - +/* + Sets the keyed archiver's delegate +*/ - (void)setDelegate:(id)aDelegate { _delegate = aDelegate; @@ -224,41 +302,77 @@ var _CPKeyedArchiverStringClass = Nil, } +/* + Returns the keyed archiver's delegate +*/ - (id)delegate { return _delegate; } -- (void)encodePoint:(CPPoint)aPoint forKey:(CPString)aKey +/* + Encodes a CGPoint + @param aPoint the point to encode + @param aKey the key to associate with the point +*/ +- (void)encodePoint:(CGPoint)aPoint forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, CPStringFromPoint(aPoint), NO) forKey:aKey]; } -- (void)encodeRect:(CPRect)aRect forKey:(CPString)aKey +/* + Encodes a CGRect + @param aRect the rectangle to encode + @param aKey the key to associate with the rectangle +*/ +- (void)encodeRect:(CGRect)aRect forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, CPStringFromRect(aRect), NO) forKey:aKey]; } -- (void)encodeSize:(CPSize)aSize forKey:(CPString)aKey +/* + Encodes a CGSize + @param aSize the size to encode + @param aKey the key to associate with the size +*/ +- (void)encodeSize:(CGSize)aSize forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, CPStringFromSize(aSize), NO) forKey:aKey]; } +/* + Encodes an conditionally. The method checks if the object has already been + coded into this data stream before. If so, it will only encode a reference + to that first object to save memory. + @param anObject the object to to conditionally encode + @param aKey the key to associate with the object +*/ - (void)encodeConditionalObject:(id)anObject forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, anObject, YES) forKey:aKey]; } +/* + Encodes a number + @param aNumber the number to encode + @param aKey the key to associate with the object +*/ - (void)encodeNumber:(CPNumber)aNumber forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, aNuumber, NO) forKey:aKey]; } +/* + Encdoes an object + @param anObject the object to encode + @param aKey the key to associate with the object +*/ - (void)encodeObject:(id)anObject forKey:(CPString)aKey { [_plistObject setObject:_CPKeyedArchiverEncodeObject(self, anObject, NO) forKey:aKey]; } +/* @ignore */ - (void)_encodeArrayOfObjects:(CPArray)objects forKey:(CPString)aKey { var i = 0, @@ -271,6 +385,7 @@ var _CPKeyedArchiverStringClass = Nil, [_plistObject setObject:references forKey:aKey]; } +/* @ignore */ - (void)_encodeDictionaryOfObjects:(CPDictionary)aDictionary forKey:(CPString)aKey { var key, @@ -284,7 +399,13 @@ var _CPKeyedArchiverStringClass = Nil, } // Managing classes and class names - +/* + Allows substitution of class types for encoding. Specifically classes + of type aClass encountered by all keyed archivers will + instead be archived as a class of type aClassName. + @param aClassName the substitute class name + @param aClass the class to substitute +*/ + (void)setClassName:(CPString)aClassName forClass:(Class)aClass { if (!CPArchiverReplacementClassNames) @@ -293,6 +414,13 @@ var _CPKeyedArchiverStringClass = Nil, [CPArchiverReplacementClassNames setObject:aClassName forKey:CPStringFromClass(aClass)]; } +/* + Returns the name of the substitute class used for encoding + aClass by all keyed archivers. + @param aClass the class to substitute + @return the name of the substitute class, or nil if there + is no substitute class +*/ + (CPString)classNameForClass:(Class)aClass { if (!CPArchiverReplacementClassNames) @@ -303,6 +431,13 @@ var _CPKeyedArchiverStringClass = Nil, return className ? className : aClass.name; } +/* + Allows substitution of class types for encoding. Specifically classes + of type aClass encountered by this keyed archiver will + instead be archived as a class of type aClassName. + @param aClassName the substitute class name + @param aClass the class to substitute +*/ - (void)setClassName:(CPString)aClassName forClass:(Class)aClass { if (!_replacementClassNames) @@ -311,6 +446,11 @@ var _CPKeyedArchiverStringClass = Nil, [_replacementClassNames setObject:aClassName forKey:CPStringFromClass(aClass)]; } +/* + Returns the name of the substitute class used for encoding aClass by this keyed archiver. + @param aClass the class to substitute + @return the name of the substitute class, or nil if there is no substitute class +*/ - (CPString)classNameForClass:(Class)aClass { if (!_replacementClassNames) diff --git a/Foundation/CPKeyedUnarchiver.j b/Foundation/CPKeyedUnarchiver.j index fb34849f6a..009f749857 100644 --- a/Foundation/CPKeyedUnarchiver.j +++ b/Foundation/CPKeyedUnarchiver.j @@ -24,7 +24,7 @@ import "CPNull.j" import "CPCoder.j" -var _CPKeyedUnarchiverCannotDecodeObjectOfClassNameOriginalClassSelector = 1, +var _CPKeyedUnarchiverCannotDecodeObjectOfClassNameOriginalClassesSelector = 1, _CPKeyedUnarchiverDidDecodeObjectSelector = 1 << 1, _CPKeyedUnarchiverWillReplaceObjectWithObjectSelector = 1 << 2, _CPKeyedUnarchiverWillFinishSelector = 1 << 3, @@ -48,6 +48,48 @@ var _CPKeyedUnarchiverArrayClass = Ni _CPKeyedUnarchiverDictionaryClass = Nil, _CPKeyedUnarchiverArchiverValueClass = Nil; +/* + CPKeyedUnarchiver is used for creating objects out of + coded files or CPData objects that were created by + CPKeyedArchiver. More specifically, this class unarchives + objects from a data stream or file and brings them back into + memory for programmatic usage. + + @delegate -(Class)unarchiver:(CPKeyedUnarchiver)unarchiver + cannotDecodeObjectOfClassName:(CPString)name + originalClasses:(CPArray)classNames; + Called when the specified class is not available during decoding. + The delegate may load the class, or return a substitute class + to use instead. + @param unarchiver the unarchiver performing the decode + @param name the name of the class that can't be found + @param an array of class names describing the encoded object's + class hierarchy. The first index is the encoded class name, and + each superclass is after that. + @return the Class to use instead or nil + to abort the unarchiving operation + + @delegate -(id)unarchiver:(CPKeyedUnarchiver)unarchiver didDecodeObject:(id)object; + Called when the unarchiver decodes an object. + @param unarchiver the unarchiver doing the decoding + @param object the decoded objec + @return a substitute to use for the decoded object. This can be the same object argument provide, + another object or nil. + + @delegate -(void)unarchiver:(CPKeyedUnarchiver)unarchiver willReplaceObject:(id)object withObject:(id)newObject; + Called when a decoded object has been substituted with another. (for example, from unarchiver:didDecodeObject:. + @param unarchiver the unarchiver that decoded the object + @param object the original decoded object + @param newObject the replacement object + + @delegate -(void)unarchiverWillFinish:(CPKeyedUnarchiver)unarchiver; + Called when the unarchiver is about to finish decoding. + @param unarchiver the unarchiver that's about to finish + + @delegate -(void)unarchiverDidFinish:(CPKeyedUnarchiver)unarchiver; + Called when the unarchiver has finished decoding. + @param unarchiver the unarchiver that finished decoding +*/ @implementation CPKeyedUnarchiver : CPCoder { id _delegate; @@ -65,6 +107,9 @@ var _CPKeyedUnarchiverArrayClass = Ni CPArray _plistObjects; } +/* + @ignore +*/ + (void)initialize { if (self != [CPKeyedUnarchiver class]) @@ -76,6 +121,11 @@ var _CPKeyedUnarchiverArrayClass = Ni _CPKeyedUnarchiverArchiverValueClass = [_CPKeyedArchiverValue class]; } +/* + Initializes the receiver to unarchive objects from the specified data object. + @param data the data stream from which to read objects + @return the initialized unarchiver +*/ - (id)initForReadingWithData:(CPData)data { self = [super init]; @@ -92,6 +142,11 @@ var _CPKeyedUnarchiverArrayClass = Ni return self; } +/* + Unarchives the object graph in the provided data object. + @param data the data from which to read the graph + @return the unarchived object +*/ + (id)unarchiveObjectWithData:(CPData)data { var unarchiver = [[self alloc] initForReadingWithData:data], @@ -102,19 +157,30 @@ var _CPKeyedUnarchiverArrayClass = Ni return object; } +/* + Not implemented +*/ + (id)unarchiveObjectWithFile:(CPString)aFilePath { } +/* + Not implemented +*/ + (id)unarchiveObjectWithFile:(CPString)aFilePath asynchronously:(BOOL)aFlag { } +/* + Returns YES if an object exists for aKey. + @param aKey the object's associated key +*/ - (BOOL)containsValueForKey:(CPString)aKey { return [_plistObject objectForKey:aKey] != nil; } +/* @ignore */ - (id)_decodeArrayOfObjectsForKey:(CPString)aKey { var object = [_plistObject objectForKey:aKey]; @@ -134,6 +200,7 @@ var _CPKeyedUnarchiverArrayClass = Ni return nil; } +/* @ignore */ - (void)_decodeDictionaryOfObjectsForKey:(CPString)aKey { var object = [_plistObject objectForKey:aKey]; @@ -153,27 +220,52 @@ var _CPKeyedUnarchiverArrayClass = Ni return nil; } +/* + Decodes a BOOL from the archive + @param aKey the BOOL's associated key + @return the decoded BOOL +*/ - (BOOL)decodeBoolForKey:(CPString)aKey { return [self decodeObjectForKey:aKey]; } +/* + Decodes a float from the archive + @param aKey the float's associated key + @return the decoded float +*/ - (float)decodeFloatForKey:(CPString)aKey { return [self decodeObjectForKey:aKey]; } +/* + Decodes a double from the archive. + @param aKey the double's associated key + @return the decoded double +*/ - (double)decodeDoubleForKey:(CPString)aKey { return [self decodeObjectForKey:aKey]; } +/* + Decodes an int from the archive. + @param aKey the int's associated key + @return the decoded int +*/ - (int)decodeIntForKey:(CPString)aKey { return [self decodeObjectForKey:aKey]; } -- (CPPoint)decodePointForKey:(CPString)aKey +/* + Decodes a CGPoint from the archive. + @param aKey the point's associated key + @return the decoded point +*/ +- (CGPoint)decodePointForKey:(CPString)aKey { var object = [self decodeObjectForKey:aKey]; @@ -183,7 +275,12 @@ var _CPKeyedUnarchiverArrayClass = Ni return CPPointMake(0.0, 0.0); } -- (CPRect)decodeRectForKey:(CPString)aKey +/* + Decodes a CGRect from the archive. + @param aKey the rectangle's associated key + @return the decoded rectangle +*/ +- (CGRect)decodeRectForKey:(CPString)aKey { var object = [self decodeObjectForKey:aKey]; @@ -193,7 +290,12 @@ var _CPKeyedUnarchiverArrayClass = Ni return CPRectMakeZero(); } -- (CPSize)decodeSizeForKey:(CPString)aKey +/* + Decodes a CGSize from the archive. + @param aKey the size's associated key + @return the decoded size +*/ +- (CGSize)decodeSizeForKey:(CPString)aKey { var object = [self decodeObjectForKey:aKey]; @@ -203,6 +305,11 @@ var _CPKeyedUnarchiverArrayClass = Ni return CPSizeMake(0.0, 0.0); } +/* + Decodes an object from the archive. + @param aKey the object's associated key + @return the decoded object +*/ - (id)decodeObjectForKey:(CPString)aKey { var object = [_plistObject objectForKey:aKey]; @@ -217,6 +324,9 @@ var _CPKeyedUnarchiverArrayClass = Ni return nil; } +/* + Notifies the delegates that decoding has finished. +*/ - (void)finishDecoding { if (_delegateSelectors & _CPKeyedUnarchiverWillFinishSelector) @@ -226,17 +336,24 @@ var _CPKeyedUnarchiverArrayClass = Ni [_delegate unarchiverDidFinish:self]; } +/* + Returns the keyed unarchiver's delegate +*/ - (id)delegate { return _delegate; } +/* + Sets the unarchiver's delegate + @param the new delegate +*/ - (void)setDelegate:(id)aDelegate { _delegate = aDelegate; - if ([_delegate respondsToSelector:@selector(unarchiver:CannotDecodeObjectOfClassName:originalClass:)]) - _delegateSelectors |= _CPKeyedUnarchiverCannotDecodeObjectOfClassNameOriginalClassSelector; + if ([_delegate respondsToSelector:@selector(unarchiver:cannotDecodeObjectOfClassName:originalClasses:)]) + _delegateSelectors |= _CPKeyedUnarchiverCannotDecodeObjectOfClassNameOriginalClassesSelector; if ([_delegate respondsToSelector:@selector(unarchiver:didDecodeObject:)]) _delegateSelectors |= _CPKeyedUnarchiverDidDecodeObjectSelector; diff --git a/Foundation/CPNotification.j b/Foundation/CPNotification.j index c3d99a2fb3..d2e3634670 100644 --- a/Foundation/CPNotification.j +++ b/Foundation/CPNotification.j @@ -21,7 +21,14 @@ */ import "CPObject.j" +import "CPException.j" +/* + Represents a notification for posting to an CPNotificationCenter. Consists of a name, an object, and an optional dictionary. The notification center will check for observers registered to receive either notifications with the name, the object, or both and pass the notification instance on to them. + + To create a notification use one of the class methods. The default init method will throw a + CPUnsupportedMethodException. +*/ @implementation CPNotification : CPObject { CPString _name; @@ -29,16 +36,46 @@ import "CPObject.j" CPDictionary _userInfo; } +/* + Creates a new notification with the specified name, object and dictionary. + @param aNotificationName the name of the notification + @param anObject the associated object + @param aUserInfo the associated dictionary + @return the new notification +*/ + (CPNotification)notificationWithName:(CPString)aNotificationName object:(id)anObject userInfo:(CPDictionary)aUserInfo { return [[self alloc] initWithName:aNotificationName object:anObject userInfo:aUserInfo]; } +/* + Creates a new notification with the specified name and object. + @param aNotificationName the name of the notification + @param anObject the associated object + @return the new notification +*/ + (CPNotification)notificationWithName:(CPString)aNotificationName object:(id)anObject { return [[self alloc] initWithName:aNotificationName object:anObject userInfo:nil]; } +/* + @throws CPUnsupportedMethodException always, because the method should not be used +*/ +- (id)init +{ + [CPException raise:CPUnsupportedMethodException + reason:"CPNotification's init method should not be used"]; +} + +/* + Initializes the notification with a name, object and dictionary + @param aNotificationName the name of the notification + @param anObject the associated object + @param aUserInfo the associated dictionary + @return the initialized notification + @ignore +*/ - (id)initWithName:(CPString)aNotificationName object:(id)anObject userInfo:(CPDictionary)aUserInfo { self = [super init]; @@ -53,16 +90,25 @@ import "CPObject.j" return self; } +/* + Returns the notification name. +*/ - (CPString)name { return _name; } +/* + Returns the notification's object. +*/ - (id)object { return _object; } +/* + Returns the notification's dictionary. +*/ - (CPDictionary)userInfo { return _userInfo; diff --git a/Foundation/CPNotificationCenter.j b/Foundation/CPNotificationCenter.j index 025963445d..f0f3017558 100644 --- a/Foundation/CPNotificationCenter.j +++ b/Foundation/CPNotificationCenter.j @@ -23,16 +23,23 @@ import "CPArray.j" import "CPDictionary.j" import "CPNotification.j" +import "CPException.j" var CPNotificationDefaultCenter = nil; +/* + Cappuccino provides a framework for sending messages between objects within a process called notifications. Objects register with an CPNotificationCenter to be informed whenever other objects post CPNotifications to it matching certain criteria. The notification center processes notifications synchronously -- that is, control is only returned to the notification poster once every recipient of the notification has received it and processed it. +*/ @implementation CPNotificationCenter : CPObject { CPMutableDictionary _namedRegistries; _CPNotificationRegistry _unnamedRegistry; } +/* + Returns the application's notification center +*/ + (CPNotifcationCenter)defaultCenter { if (!CPNotificationDefaultCenter) @@ -53,6 +60,14 @@ var CPNotificationDefaultCenter = nil; return self; } +/* + Adds an object as an observer. The observer will receive notifications with the specified name + and/or containing the specified object (depending on if they are nil. + @param anObserver the observing object + @param aSelector the message sent to the observer when a notification occurrs + @param aNotificationName the name of the notification the observer wants to watch + @param anObject the object in the notification the observer wants to watch +*/ - (void)addObserver:(id)anObserver selector:(SEL)aSelector name:(CPString)aNotificationName object:(id)anObject { var registry, @@ -70,6 +85,10 @@ var CPNotificationDefaultCenter = nil; [registry addObserver:observer object:anObject]; } +/* + Unregisters the specified observer from all notifications. + @param anObserver the observer to unregister +*/ - (void)removeObserver:(id)anObserver { var name = nil, @@ -81,6 +100,12 @@ var CPNotificationDefaultCenter = nil; [_unnamedRegistry removeObserver:anObserver object:nil]; } +/* + Unregisters the specified observer from notifications matching the specified name and/or object. + @param anObserver the observer to remove + @param aNotificationName the name of notifications to no longer watch + @param anObject notifications containing this object will no longer be watched +*/ - (void)removeObserver:(id)anObserver name:(CPString)aNotificationName object:(id)anObject { if (aNotificationName == nil) @@ -97,16 +122,35 @@ var CPNotificationDefaultCenter = nil; [[_namedRegistries objectForKey:aNotificationName] removeObserver:anObserver object:anObject]; } +/* + Posts a notification to all observers that match the specified notification's name and object. + @param aNotification the notification being posted + @throws CPInvalidArgumentException if aNotification is nil +*/ - (void)postNotification:(CPNotification)aNotification { + if (!aNotification) + [CPException raise:CPInvalidArgumentException reason:"postNotification: does not except 'nil' notifications"]; + _CPNotificationCenterPostNotification(self, aNotification); } +/* + Posts a new notification with the specified name, object, and dictionary. + @param aNotificationName the name of the notification name + @param anObject the associated object + @param aUserInfo the associated dictionary +*/ - (void)postNotificationName:(CPString)aNotificationName object:(id)anObject userInfo:(CPDictionary)aUserInfo { _CPNotificationCenterPostNotification(self, [[CPNotification alloc] initWithName:aNotificationName object:anObject userInfo:aUserInfo]); } +/* + Posts a new notification with the specified name and object. + @param aNotificationName the name of the notification + @param anObject the associated object +*/ - (void)postNotificationName:(CPString)aNotificationName object:(id)anObject { _CPNotificationCenterPostNotification(self, [[CPNotification alloc] initWithName:aNotificationName object:anObject userInfo:nil]); @@ -120,7 +164,9 @@ var _CPNotificationCenterPostNotification = function(/* CPNotificationCenter */ [[self._namedRegistries objectForKey:[aNotification name]] postNotification:aNotification]; } -// Mapping of Notification Name to listening object/selector. +/** Mapping of Notification Name to listening object/selector. + @ignore + */ @implementation _CPNotificationRegistry : CPObject { CPDictionary _objectObservers; @@ -275,6 +321,7 @@ var _CPNotificationCenterPostNotification = function(/* CPNotificationCenter */ @end +/* @ignore */ @implementation _CPNotificationObserver : CPObject { id _observer; diff --git a/Foundation/CPNull.j b/Foundation/CPNull.j index 7d267a1f96..00288a61ad 100644 --- a/Foundation/CPNull.j +++ b/Foundation/CPNull.j @@ -24,6 +24,10 @@ import "CPObject.j" var CPNullSharedNull = nil; +/* + This class is used as an object representation of nil. This is handy when a collection + only accepts objects as values, but you would like a nil representation in there. +*/ @implementation CPNull : CPObject { } @@ -35,7 +39,11 @@ var CPNullSharedNull = nil; return [super alloc]; }*/ - +/* + Returns the singleton instance of the CPNull + object. While CPNull and nil should + be interpreted as the same, they are not equal ('=='). +*/ + (CPNull)null { if (!CPNullSharedNull) diff --git a/Foundation/CPNumber.j b/Foundation/CPNumber.j index 99ead4aaab..d408d2ecf4 100644 --- a/Foundation/CPNumber.j +++ b/Foundation/CPNumber.j @@ -26,6 +26,11 @@ import "CPObjJRuntime.j" var __placeholder = new Number(), _CPNumberHashes = { }; +/* + This class primarily exists for source compatability. The JavaScript + Number type can be changed on the fly based on context, + so there is no need to call any of these methods. +*/ @implementation CPNumber : CPObject + (id)alloc @@ -93,12 +98,12 @@ var __placeholder = new Number(), { return anUnsignedLong; } - +/* + (id)numberWithUnsignedLongLong:(unsigned long long)anUnsignedLongLong { return anUnsignedLongLong; } - +*/ + (id)numberWithUnsignedShort:(unsigned short)anUnsignedShort { return anUnsignedShort; @@ -164,12 +169,12 @@ var __placeholder = new Number(), { return anUnsignedLong; } - +/* - (id)initWithUnsignedLongLong:(unsigned long long)anUnsignedLongLong { return anUnsignedLongLong; } - +*/ - (id)initWithUnsignedShort:(unsigned short)anUnsignedShort { return anUnsignedShort; @@ -265,13 +270,13 @@ FIXME: Do we need this? if (typeof self == "boolean") return self ? 1 : 0; return self; } - +/* - (unsigned long long)unsignedLongLongValue { if (typeof self == "boolean") return self ? 1 : 0; return self; } - +*/ - (unsigned long)unsignedLongValue { if (typeof self == "boolean") return self ? 1 : 0; diff --git a/Foundation/CPObject.j b/Foundation/CPObject.j index 35587acec0..c67cdaf4ee 100644 --- a/Foundation/CPObject.j +++ b/Foundation/CPObject.j @@ -34,53 +34,87 @@ // CPLog("calling initialize "+self.name); } +/* + Allocates a new instance of the receiver, and sends it an init + @return the new object +*/ + (id)new { return [[self alloc] init]; } +/* + Allocates a new instance of the receiving class +*/ + (id)alloc { // CPLog("calling alloc on " + self.name + "."); return class_createInstance(self); } +/* + Initializes the receiver + @return the initialized receiver +*/ - (id)init { return self; } +/* + Makes a deep copy of the receiver. The copy should be functionally equivalent to the receiver. + @return the copy of the receiver +*/ - (id)copy { return self; } +/* + Creates a deep mutable copy of the receiver. + @return the mutable copy of the receiver +*/ - (id)mutableCopy { return [self copy]; } +/* + Not necessary to call in Objective-J. Only exists for code compatability. +*/ - (void)dealloc { } // Identifying classes - +/* + Returns the Class object for this class definition. +*/ + (Class)class { return self; } +/* + Returns the receiver's Class +*/ - (Class)class { return isa; } +/* + Returns the class object super class +*/ + (Class)superclass { return super_class; } +/* + Returns YES if the receiving class is a subclass of aClass. + @param aClass the class to test inheritance from +*/ + (BOOL)isSubclassOfClass:(Class)aClass { var theClass = self; @@ -91,28 +125,49 @@ return NO; } +/* + Returns YES if the receiver is a aClass type, or a subtype of it. + @param aClass the class to test as the receiver's class or super class. +*/ - (BOOL)isKindOfClass:(Class)aClass { return [isa isSubclassOfClass:aClass]; } +/* + Returns YES if the receiver is of the aClass class type. + @param aClass the class to test the receiper +*/ - (BOOL)isMemberOfClass:(Class)aClass { return self.isa == aClass; } +/* + Determines whether the receiver's root object is a proxy. + @return YES if the root object is a proxy +*/ - (BOOL)isProxy { return NO; } // Testing class functionality - +/* + Test whether instances of this class respond to the provided selector. + @param aSelector the selector for which to test the class + @return YES if instances of the class respond to the selector +*/ + (BOOL)instancesRespondToSelector:(SEL)aSelector { return class_getInstanceMethod(self, aSelector); } +/* + Tests whether the receiver responds to the provided selector. + @param aSelector the selector for which to test the receiver + @return YES if the receiver responds to the selector +*/ - (BOOL)respondsToSelector:(SEL)aSelector { return class_getInstanceMethod(isa, aSelector) != NULL; @@ -120,16 +175,31 @@ // Obtaining method information +/* + Returns the address of the receiver's method for the provided selector. + @param aSelector the selector for the method to return + @return the address of the method's implementation +*/ - (IMP)methodForSelector:(SEL)aSelector { return class_getInstanceMethod(isa, aSelector); } +/* + Returns the address of the receiving class' method for the provided selector. + @param aSelector the selector for the class method to return + @return the address of the method's implementation +*/ + (IMP)instanceMethodForSelector:(SEL)aSelector { return class_getInstanceMethod(isa, aSelector); } +/* + Returns the method signature for the provided selector. + @param aSelector the selector for which to find the method signature + @return the selector's methd signature +*/ - (CPMethodSignature)methodSignatureForSelector:(SEL)aSelector { // FIXME: We need to implement method signatures. @@ -137,36 +207,64 @@ } // Describing objects - +/* + Returns a human readable string describing the receiver +*/ - (CPString)description { return "<" + isa.name + " 0x" + [CPString stringWithHash:[self hash]] + ">"; } // Sending Messages - +/* + Sends the specified message to the receiver. + @param aSelector the message to send + @return the return value of the message +*/ - (id)performSelector:(SEL)aSelector { return objj_msgSend(self, aSelector); } +/* + Sends the specified message to the receiver, with one argument. + @param aSelector the message to send + @param anObject the message argument + @return the return value of the message +*/ - (id)performSelector:(SEL)aSelector withObject:(id)anObject { return objj_msgSend(self, aSelector, anObject); } +/* + Sends the specified message to the receiver, with two arguments. + @param aSelector the message to send + @param anObject the first message argument + @param anotherObject the second message argument + @return the return value of the message +*/ - (id)performSelector:(SEL)aSelector withObject:(id)anObject withObject:(id)anotherObject { return objj_msgSend(self, aSelector, anObject, anotherObject); } // Forwarding Messages - +/* + Subclasses can override this method to forward message to + other objects. Overwriting this method in conjunction with + methodSignatureForSelector: allows the receiver to + forward messages for which it does not respond, to another object that does. +*/ - (void)forwardInvocation:(CPInvocation)anInvocation { [self doesNotRecognizeSelector:[anInvocation selector]]; } +/* + Used for forwarding of messages to other objects. + @ignore +*/ - (void)forward:(SEL)aSelector :(marg_list)args { var signature = [self methodSignatureForSelector:_cmd]; @@ -193,7 +291,11 @@ } // Error Handling - +/* + Called by the Objective-J runtime when an object can't respond to + a message. It's not recommended to call this method directly, unless + you need your class to not support a method that it has inherited from a super class. +*/ - (void)doesNotRecognizeSelector:(SEL)aSelector { [CPException raise:CPInvalidArgumentException reason: @@ -202,37 +304,71 @@ } // Archiving - -- (void)awakeAfterUsingCoder:(CPCoder)aCoder +/* + Subclasses override this method to possibly substitute + the unarchived object with another. This would be + useful if your program utilizes a + flyweight pattern. + The method is called by CPCoder. + @param aCoder the coder that contained the receiver's data +*/ +- (id)awakeAfterUsingCoder:(CPCoder)aCoder { return self; } +/* + Can be overridden by subclasses to substitute a different class to represent the receiver for keyed archiving. + @return the class to use. A nil means to ignore the method result. +*/ - (Class)classForKeyedArchiver { return [self classForCoder]; } +/* + Can be overridden by subclasses to substitute a different class to represent the receiver during coding. + @return the class to use for coding +*/ - (Class)classForCoder { return [self class]; } +/* + Can be overridden by subclasses to substitute another object during archiving. + @param anArchiver that archiver + @return the object to archive +*/ - (id)replacementObjectForArchiver:(CPArchiver)anArchiver { return [self replacementObjectForCoder:anArchiver]; } +/* + Can be overridden by subclasses to substitute another object during keyed archiving. + @param anArchive the keyed archiver + @return the object to archive +*/ - (id)replacementObjectForKeyedArchiver:(CPKeyedArchiver)anArchiver { return [self replacementObjectForCoder:anArchiver]; } +/* + Can be overridden by subclasses to substitute another object during coding. + @param aCoder the coder + @return the object to code +*/ - (id)replacementObjectForCoder:(CPCoder)aCoder { return self; } +/* + Sets the class version number. + @param the new version number for the class +*/ + (id)setVersion:(int)aVersion { version = aVersion; @@ -240,49 +376,77 @@ return self; } +/* + Returns the class version number. +*/ + (int)version { return version; } // Scripting (?) - +/* + Returns the class name +*/ - (CPString)className { return isa.name; } // Extras - +/* + Does nothing. + @return the receiver +*/ - (id)autorelease { return self; } +/* + Returns a hash for the object +*/ - (unsigned)hash { return __address; } +/* + Determines if anObject is functionally equivalent to the receiver. + @return YES if anObject is functionally equivalent to the receiver. +*/ - (BOOL)isEqual:(id)anObject { return self === anObject; } -- (void)retain +/* + Does nothing. + @return the receiver +*/ +- (id)retain { return self; } +/* + Does nothing. +*/ - (void)release { } +/* + Returns the receiver. +*/ - (id)self { return self; } +/* + Returns the receiver's super class. +*/ - (Class)superclass { return isa.super_class; diff --git a/Foundation/CPRange.j b/Foundation/CPRange.j index 30c36c86d6..8172fe7387 100755 --- a/Foundation/CPRange.j +++ b/Foundation/CPRange.j @@ -20,47 +20,106 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/* + Makes a CPRange. + @param location the location for new range + @param length the length of the new range + @group CPRange + @return CPRange the new range object +*/ function CPMakeRange(location, length) { return { location: location, length: length }; } +/* + Makes a copy of a CPRange. + @param aRange the CPRange to copy + @group CPRange + @return CPRange the copy of the range +*/ function CPCopyRange(aRange) { return { location: aRange.location, length: aRange.length }; } +/* + Makes a copy of a CPRange. + @param aRange the CPRange to copy + @group CPRange + @return CPRange the copy of the range +*/ function CPMakeRangeCopy(aRange) { return { location:aRange.location, length:aRange.length }; } +/* + Sets a range's length to 0. + @param aRange the range to empty + @group CPRange + @return CPRange the empty range (same as the argument) +*/ function CPEmptyRange(aRange) { return aRange.length == 0; } +/* + Finds the range maximum. (location + length) + @param aRange the range to calculate a maximum from + @group CPRange + @return int the range maximum +*/ function CPMaxRange(aRange) { return aRange.location + aRange.length; } +/* + Determines if two CPRanges are equal. + @param lhsRange the first CPRange + @param rhsRange the second CPRange + @return BOOL YES if the two CPRanges are equal. +*/ function CPEqualRanges(lhsRange, rhsRange) { return ((lhsRange.location == rhsRange.location) && (lhsRange.length == rhsRange.length)); } +/* + Determines if a number is within a specified CPRange. + @param aLocation the number to check + @param aRange the CPRange to check within + @group CPRange + @return BOOL YES if aLocation/code> is within the range +*/ function CPLocationInRange(aLocation, aRange) { return (aLocation >= aRange.location) && (aLocation < CPMaxRange(aRange)); } +/* + Creates a new range with the minimum location and a length + that extends to the maximum length. + @param lhsRange the first CPRange + @param rhsRange the second CPRange + @group CPRange + @return CPRange the new CPRange +*/ function CPUnionRange(lhsRange, rhsRange) { var location = Math.min(lhsRange.location, rhsRange.location); return CPMakeRange(location, Math.max(CPMaxRange(lhsRange), CPMaxRange(rhsRange)) - location); } +/* + Creates a new CPRange that spans the common range of two CPRanges + @param lhsRange the first CPRange + @param rhsRange the second CPRange + @group CPRange + @return CPRange the new CPRange +*/ function CPIntersectionRange(lhsRange, rhsRange) { if(CPMaxRange(lhsRange) < rhsRange.location || CPMaxRange(rhsRange) < lhsRange.location) @@ -70,11 +129,23 @@ function CPIntersectionRange(lhsRange, rhsRange) return CPMakeRange(location, Math.min(CPMaxRange(lhsRange), CPMaxRange(rhsRange)) - location); } +/* + Returns a string describing a range. + @param aRange the range to describe + @group CPRange + @return CPString a describing string +*/ function CPStringFromRange(aRange) { return "{" + aRange.location + ", " + aRange.length + "}"; } +/* + Creates a CPRange from the contents of a CPString. + @param aString the string to create a CPRange from + @group CPRange + @return CPRange the new range +*/ function CPRangeFromString(aString) { var comma = aString.indexOf(','); diff --git a/Foundation/CPRunLoop.j b/Foundation/CPRunLoop.j index 57c9f690d3..bba2cc0c28 100644 --- a/Foundation/CPRunLoop.j +++ b/Foundation/CPRunLoop.j @@ -24,6 +24,10 @@ import "CPObject.j" import "CPArray.j" import "CPString.j" +/* + @global + @group CPRunLoopMode +*/ CPDefaultRunLoopMode = @"CPDefaultRunLoopMode"; function _CPRunLoopPerformCompare(lhs, rhs) @@ -34,6 +38,7 @@ function _CPRunLoopPerformCompare(lhs, rhs) var _CPRunLoopPerformPool = [], _CPRunLoopPerformPoolCapacity = 5; +/* @ignore */ @implementation _CPRunLoopPerform : CPObject { id _target; @@ -119,6 +124,11 @@ var _CPRunLoopPerformPool = [], @end +/* + CPRunLoop instances handle various utility tasks that must be performed repetitively in an application, such as processing input events. + + There is one run loop per application, which may always be obtained through the +currentRunLoop method, +*/ @implementation CPRunLoop : CPObject { CPArray _queuedPerforms; @@ -126,6 +136,9 @@ var _CPRunLoopPerformPool = [], BOOL _isPerformingSelectors; } +/* + @ignore +*/ + (void)initialize { if (self != [CPRunLoop class]) @@ -147,16 +160,30 @@ var _CPRunLoopPerformPool = [], return self; } +/* + Returns the application's singleton CPRunLoop. +*/ + (CPRunLoop)currentRunLoop { return CPMainRunLoop; } +/* + Returns the application's singleton CPRunLoop. +*/ + (CPRunLoop)mainRunLoop { return CPMainRunLoop; } +/* + Performs the specified selector on the specified target. The method will be invoked synchronously. + @param aSelector the selector of the method to invoke + @param aTarget the target of the selector + @param anArgument the method argument + @param anOrder the message priority + @param modes the modes variable isn't respected. +*/ - (void)performSelector:(SEL)aSelector target:(id)aTarget argument:(id)anArgument order:(int)anOrder modes:(CPArray)modes { var perform = [_CPRunLoopPerform performWithSelector:aSelector target:aTarget argument:anArgument order:anOrder modes:modes]; @@ -176,6 +203,12 @@ var _CPRunLoopPerformPool = [], } } +/* + Cancels the specified selector and target. + @param aSelector the selector of the method to invoke + @param aTarget the target to invoke the method on + @param the argument for the method +*/ - (void)cancelPerformSelector:(SEL)aSelector target:(id)aTarget argument:(id)anArgument { var count = _orderedPerforms.length; @@ -189,6 +222,9 @@ var _CPRunLoopPerformPool = [], } } +/* + @ignore +*/ - (void)performSelectors { if (_isPerformingSelectors) diff --git a/Foundation/CPSortDescriptor.j b/Foundation/CPSortDescriptor.j index 197cc7372a..418b576af5 100755 --- a/Foundation/CPSortDescriptor.j +++ b/Foundation/CPSortDescriptor.j @@ -23,6 +23,30 @@ import "CPObject.j" import "CPObjJRuntime.j" +/* + The left operand is smaller than the right. + @global + @group CPComparisonResult +*/ +CPOrderedAscending = -1; +/* + The left and right operands are equal. + @global + @group CPComparisonResult +*/ +CPOrderedSame = 0; +/* + The left operand is greater than the right. + @global + @group CPComparisonResult +*/ +CPOrderedDescending = 1; + +/* + A CPSortDescriptor holds the attributes necessary to describe how + to sort a set of objects. The sort descriptor instance holds a property key path + to the sort item of the objects to compare, the method selector to call for sorting and the sort order. +*/ @implementation CPSortDescriptor : CPObject { CPString _key; @@ -31,12 +55,24 @@ import "CPObjJRuntime.j" } // Initializing a sort descriptor - +/* + Initializes the sort descriptor. + @param aKey the property key path to sort + @param isAscending the sort order + @return the initialized sort descriptor +*/ - (id)initWithKey:(CPString)aKey ascending:(BOOL)isAscending { return [self initWithKey:aKey ascending:isAscending selector:@selector(compare:)]; } - + +/* + Initializes the sort descriptor + @param aKey the property key path to sort + @param isAscending the sort order + @param aSelector this method gets called to compare objects. The method will take one argument + (the object to compare against itself, and must return a CPComparisonResult. +*/ - (id)initWithKey:(CPString)aKey ascending:(BOOL)isAscending selector:(SEL)aSelector { self = [super init]; @@ -52,29 +88,46 @@ import "CPObjJRuntime.j" } // Getting information about a sort descriptor - +/* + Returns YES if the sort descriptor's order is ascending. +*/ - (BOOL)ascending { return _ascending; } +/* + Returns the descriptor's property key +*/ - (CPString)key { return _key; } +/* + Returns the selector of the method to call when comparing objects. +*/ - (SEL)selector { return _selector; } // Using sort descriptors - +/* + Compares two objects. + @param lhsObject the left hand side object to compre + @param rhsObject the right hand side object to compare + @return the comparison result +*/ - (CPComparisonResult)compareObject:(id)lhsObject withObject:(id)rhsObject { return (_ascending ? 1 : -1) * [[lhsObject valueForKey:_key] performSelector:_selector withObject:[rhsObject valueForKey:_key]]; } - + +/* + Makes a copy of this sort descriptor with a reversed sort order. + @return the reversed copy of the sort descriptor +*/ - (id)reversedSortDescriptor { return [[[self class] alloc] initWithKey:_key ascending:!_ascending selector:_selector]; diff --git a/Foundation/CPString.j b/Foundation/CPString.j index d52d3df7fd..e46de97f6e 100644 --- a/Foundation/CPString.j +++ b/Foundation/CPString.j @@ -21,28 +21,71 @@ */ import "CPObject.j" +import "CPException.j" - +/* + A case insensitive search + @global + @class CPString +*/ CPCaseInsensitiveSearch = 1; +/* + Exact character match + @global + @class CPString +*/ CPLiteralSearch = 2; +/* + Start searching from the end of the string + @global + @class CPString +*/ CPBackwardsSearch = 4; +/* + @global + @class CPString +*/ CPAnchoredSearch = 8; +/* + Numbers in the string are compared as numbers instead of strings + @global + @class CPString +*/ CPNumericSearch = 64; var CPStringHashes = new objj_dictionary(); +/* + CPString is an object that allows management of strings. Because CPString is + based on the JavaScript String object, CPStrings are immutable, although the + class does have methods that create new CPStrings generated from modifications to the + receiving instance.

+ +

A handy feature of CPString instances is that they can be used wherever a JavaScript is + required, and vice versa. +*/ @implementation CPString : CPObject +/* + @ignore +*/ + (id)alloc { return new String; } +/* + Returns a new string +*/ + (id)string { return [[self alloc] init]; } +/* + Returns a CPString containing the specified hash. + @param aHash the hash to represent as a string +*/ + (id)stringWithHash:(unsigned)aHash { var zeros = "000000", @@ -51,38 +94,79 @@ var CPStringHashes = new objj_dictionary(); return zeros.substring(0, zeros.length - digits.length) + digits; } +/* + Returns a copy of the specified string. + @param aString a non-nil string to copy + @throws CPInvalidArgumentException if aString is nil + @return the new CPString +*/ + (id)stringWithString:(CPString)aString { + if (!aString) + [CPException raise:CPInvalidArgumentException + reason:"stringWithString: the string can't be 'nil'"]; + return [[self alloc] initWithString:aString]; } +/* + Initializes the string with data from the specified string. + @param aString the string to copy data from + @return the initialized CPString +*/ - (id)initWithString:(CPString)aString { return aString + ""; } +/* + Returns a description of this CPString object. +*/ - (CPString)description { return "<" + self.isa.name + " 0x" + [CPString stringWithHash:[self hash]] + " \"" + self + "\">"; } +/* + Returns the number of UTF-8 characters in the string. +*/ - (int)length { return length; } -- (char)characterAtIndex:(unsigned)anIndex +/* + Returns the character at the specified index. + @param anIndex the index of the desired character +*/ +- (CPString)characterAtIndex:(unsigned)anIndex { return charAt(anIndex); } // Combining strings - +/* + Creates a new CPString from the concatenation of the receiver and the specified string. + @param aString the string to append to the receiver + @return the new string +*/ - (CPString)stringByAppendingString:(CPString)aString { return self + aString; } +/* + Returns a new string formed by padding characters or removing them. + If the padding length is shorter than the receiver's length, the + new string will be trimmed down to the padding length size. + If the padding length is longer than the receiver's length, then the + new string is repeatedly padded with the characters from the + specified string starting at the specified index. + @param aLength the desired length of the new CPString + @param aString the padding string to use (if necessary) + @param anIndex the index of the padding string to start from (if necessary to use) + @return the new padded string +*/ - (CPString)stringByPaddingToLength:(unsigned)aLength withString:(CPString)aString startingAtIndex:(unsigned)anIndex { if (length == aLength) @@ -101,28 +185,59 @@ var CPStringHashes = new objj_dictionary(); if (difference) string += substring.substr(difference + substring.length); } +/* + Tokenizes the receiver string using the specified + delimiter. For example, if the receiver is: + 

"arash.francisco.ross.tom"
+ and the delimiter is: + 
"."
+ the returned array would contain: + 
["arash", "francisco", "ross", "tom"]
+ @param the delimiter + @return the array of tokens +*/ - (CPArray)componentsSeparatedByString:(CPString)aString { return split(aString); } +/* + Returns a substring starting from the specified index to the end of the receiver. + @param anIndex the starting string (inclusive) + @return the substring +*/ - (CPString)substringFromIndex:(unsigned)anIndex { return substr(anIndex); } +/* + Returns a substring starting from the specified range location to the range length. + @param the range of the substring + @return the substring +*/ - (CPString)substringWithRange:(CPRange)aRange { return substr(aRange.location, aRange.length); } +/* + Creates a substring from the beginning of the receiver to the specified index. + @param anIndex the last index of the receiver to use for the substring (inclusive) + @return the substring +*/ - (CPString)substringToIndex:(unsigned)anIndex { return substring(0, anIndex); } // Finding characters and substrings - +/* + Finds the range of characters in the receiver where the specified string exists. If the string + does not exist in the receiver, the range length will be 0. + @param aString the string to search for in the receiver + @return the range of charactrs in the receiver +*/ - (CPRange)rangeOfString:(CPString)aString { var location = indexOf(aString); @@ -130,6 +245,23 @@ var CPStringHashes = new objj_dictionary(); return CPMakeRange(location, location == CPNotFound ? 0 : aString.length); } +/* + Finds the range of characters in the receiver + where the specified string exists. The search + is subject to the options specified in the + specified mask which can be a combination of: +
+CPCaseInsensitiveSearch
+CPLiteralSearch
+CPBackwardsSearch
+CPAnchoredSearch
+CPNumericSearch
+
+ @param aString the string to search for + @param aMask the options to use in the search + @return the range of characters in the receiver. If the string was not found, + the length of the range will be 0. +*/ - (CPRange)rangeOfString:(CPString)aString options:(int)aMask { var string = self, @@ -149,12 +281,22 @@ var CPStringHashes = new objj_dictionary(); } // Identifying and comparing strings - +/* + Compares the receiver to the specified string. + @param aString the string with which to compare + @return the result of the comparison +*/ - (CPComparisonResult)caseInsensitiveCompare:(CPString)aString { return [self compare:aString options:CPCaseInsensitiveSearch] } +/* + Compares the receiver to the specified string, using options. + @param aString the string with which to compare + @param aMask the options to use for the comparison + @return the result of the comparison +*/ - (CPComparisonResult)compare:(CPString)aString options:(int)aMask { var lhs = self, @@ -174,21 +316,37 @@ var CPStringHashes = new objj_dictionary(); return CPOrderedSame; } +/* + Returns YES if the receiver starts + with the specified string. If aString + is empty, the method will return NO. +*/ - (BOOL)hasPrefix:(CPString)aString { return aString && aString != "" && indexOf(aString) == 0; } +/* + Returns NO if the receiver ends + with the specified string. If aString + is empty, the method will return NO. +*/ - (BOOL)hasSuffix:(CPString)aString { return aString && aString != "" && lastIndexOf(aString) == (length - aString.length); } +/* + Returns YES if the specified string contains the same characters as the receiver. +*/ - (BOOL)isEqualToString:(CPString)aString { return self == aString; } +/* + Returns a hash of the string instance. +*/ - (unsigned)hash { var hash = dictionary_getValue(CPStringHashes, self); @@ -202,6 +360,9 @@ var CPStringHashes = new objj_dictionary(); return hash; } +/* + Returns a copy of the receiver with all the first letters of words capitalized. +*/ - (CPString)capitalizedString { var i = 0, @@ -222,36 +383,61 @@ var CPStringHashes = new objj_dictionary(); return capitalized; } +/* + Returns a copy of the string with all its characters made lower case. +*/ - (CPString)lowercaseString { return toLowerCase(); } +/* + Returns a copy of the string with all its characters made upper case. +*/ - (CPString)uppercaseString { return toUpperCase(); } +/* + Returns the text as a floating point value. +*/ - (double)doubleValue { return eval(self); } +/* + Returns the text as a float point value. +*/ - (float)floatValue { return eval(self); } +/* + Returns the text as an integer +*/ - (int)intValue { return parseInt(self); } +/* + Returns an the path components of this string. This + method assumes that the string's contents is a '/' + separated file system path. +*/ - (CPArray)pathComponents { return split('/'); } +/* + Returns the extension of the file denoted by this string. + The '.' is not a part of the extension. This method assumes + that the string's contents is the path to a file or just a filename. +*/ - (CPString)pathExtension { return substr(lastIndexOf('.')+1); @@ -263,10 +449,14 @@ var CPStringHashes = new objj_dictionary(); return components[components.length -1]; } +/* + Until this is corrected + @ignore +*/ - (CPString)stringByDeletingLastPathComponent { // FIMXE: this is wrong: a/a/ returns a/a/. - return substr(0, lastIndexOf('/') + 1); + return substr(0, lastIndexOf('/')); } - (CPString)stringByStandardizingPath diff --git a/Foundation/CPURLConnection.j b/Foundation/CPURLConnection.j index a98acb9b19..1ff52aab29 100644 --- a/Foundation/CPURLConnection.j +++ b/Foundation/CPURLConnection.j @@ -34,6 +34,47 @@ var XMLHTTPRequestUninitialized = 0, var CPURLConnectionDelegate = nil; +/* + An interface to downloading content at a specified URL. Using one of the + class methods, you can obtain the data. + + @delegate -(void)connection:(CPURLConnection)connection didFailWithError:(id)error; + Called when the connection encounters an error. + @param connection the connection that had an error + @param error the error, which is either a javascript DOMException or an http + status code (javascript number/CPNumber) + + @delegate -(void)connection:(CPURLConnection)connection didReceiveResponse:(CPHTTPURLResponse)response; + Called when the connection receives a response. + @param connection the connection that received a response + @param response the received response + + @delegate -(void)connection:(CPURLConnection)connection didReceiveData:(CPString)data; + Called when the connection has received data. + @param connection the connection that received data + @param data the received data + + @delegate -(void)connectionDidFinishLoading:(CPURLConnection)connection; + Called when the URL has finished loading. + @param connection the connection that finished loading + + Class Delegate Method: + + @delegate -(void)connectionDidReceiveAuthenticationChallenge:(id)connection + The class delegate allows you to set global behavior for when authentication challenges (401 status codes) are returned. + + The recommended way to handle this method is to store a reference to the connection, and then use whatever + method you have to authenticate yourself. Once you've authenticated yourself, you should cancel + and then start the connection: + +
+[connection cancel];
+[connection start];
+
+ + @param connection the connection that received the authentication challenge. +*/ + @implementation CPURLConnection : CPObject { CPURLRequest _request; @@ -48,7 +89,14 @@ var CPURLConnectionDelegate = nil; CPURLConnectionDelegate = delegate; } -+ (CPData)sendSynchronousRequest:(CPURLRequest)aRequest returningResponse:(CPURLResponse **)aURLResponse error:(CPError **)anError +/* + Sends a request for the data from a URL. This is the easiest way to obtain data from a URL. + @param aRequest contains the URL to request the data from + @param aURLResponse not used + @param anError not used + @return the data at the URL or nil if there was an error +*/ ++ (CPData)sendSynchronousRequest:(CPURLRequest)aRequest returningResponse:({CPURLResponse})aURLResponse error:({CPError})anError { try { @@ -74,11 +122,24 @@ var CPURLConnectionDelegate = nil; return nil; } +/* + Creates a url connection with a delegate to monitor the request progress. + @param aRequest contains the URL to obtain data from + @param aDelegate will be sent messages related to the request progress + @return a connection that can be started to initiate the request +*/ + (CPURLConnection)connectionWithRequest:(CPURLRequest)aRequest delegate:(id)aDelegate { return [[self alloc] initWithRequest:aRequest delegate:aDelegate]; } +/* + Default class initializer. Use one of the class methods instead. + @param aRequest contains the URL to contact + @param aDelegate will receive progress messages + @param shouldStartImmediately whether the start method should be called from here + @return the initialized url connection +*/ - (id)initWithRequest:(CPURLRequest)aRequest delegate:(id)aDelegate startImmediately:(BOOL)shouldStartImmediately { self = [super init]; @@ -103,11 +164,17 @@ var CPURLConnectionDelegate = nil; return [self initWithRequest:aRequest delegate:aDelegate startImmediately:YES]; } +/* + return the delegate +*/ - (id)delegate { return _delegate; } +/* + Start the connection. Not needed if you used the class method +connectionWithRequest:delegate: +*/ - (void)start { _isCanceled = NO; @@ -133,6 +200,9 @@ var CPURLConnectionDelegate = nil; } } +/* + Cancels the current request. +*/ - (void)cancel { _isCanceled = YES; @@ -147,6 +217,7 @@ var CPURLConnectionDelegate = nil; } } +/* @ignore */ - (void)_readyStateDidChange { if (_XMLHTTPRequest.readyState == XMLHTTPRequestComplete) @@ -173,6 +244,7 @@ var CPURLConnectionDelegate = nil; [[CPRunLoop currentRunLoop] performSelectors]; } +/* @ignore */ - (void)_XMLHTTPRequest { return _XMLHTTPRequest; diff --git a/Foundation/CPURLRequest.j b/Foundation/CPURLRequest.j index 7a8e61a2a4..f227247d46 100644 --- a/Foundation/CPURLRequest.j +++ b/Foundation/CPURLRequest.j @@ -22,6 +22,10 @@ import "CPObject.j" +/* + A helper object for CPURLConnection, that contains + data obtained during the life of a request. +*/ @implementation CPURLRequest : CPObject { CPURL _URL; @@ -32,11 +36,21 @@ import "CPObject.j" CPDictionary _HTTPHeaderFields; } +/* + Creates a request with a specified URL. + @param aURL the URL of the request + @return a CPURLRequest +*/ + (id)requestWithURL:(CPURL)aURL { return [[CPURLRequest alloc] initWithURL:aURL]; } +/* + Initializes the request with a URL. + @param aURL the url to set + @return the initialized CPURLRequest +*/ - (id)initWithURL:(CPURL)aURL { self = [super init]; @@ -55,46 +69,79 @@ import "CPObject.j" return self; } +/* + Returns the request URL +*/ - (CPURL)URL { return _URL; } +/* + Sets the URL for this request. + @param aURL the new URL +*/ - (void)setURL:(CPURL)aURL { _URL = aURL; } +/* + Sets the HTTP body for this request + @param anHTTPBody the new HTTP body +*/ - (void)setHTTPBody:(CPString)anHTTPBody { _HTTPBody = anHTTPBody; } +/* + Returns the request's http body. +*/ - (CPString)HTTPBody { return _HTTPBody; } +/* + Sets the request's http method. + @param anHTPPMethod the new http method +*/ - (void)setHTTPMethod:(CPString)anHTTPMethod { _HTTPMethod = anHTTPMethod; } +/* + Returns the request's http method +*/ - (CPString)HTTPMethod { return _HTTPMethod; } +/* + Returns a dictionar of the http header fields +*/ - (CPDictionary)allHTTPHeaderFields { return _HTTPHeaderFields; } +/* + Returns the value for the specified header field. + @param aField the header field to obtain a value for +*/ - (CPString)valueForHTTPHeaderField:(CPString)aField { return [_HTTPHeaderFields objectForKey:aField]; } +/* + Sets the value for the specified header field. + @param aValue the value for the header field + @param aField the header field +*/ - (void)setValue:(CPString)aValue forHTTPHeaderField:(CPString)aField { [_HTTPHeaderFields setObject:aValue forKey:aField]; diff --git a/Foundation/CPURLResponse.j b/Foundation/CPURLResponse.j index 4362c2d083..5419086741 100644 --- a/Foundation/CPURLResponse.j +++ b/Foundation/CPURLResponse.j @@ -29,6 +29,9 @@ import "CPObject.j" unsigned _expectedContentLength; CPString _textEncodingName; */ +/* + Contains protocol agnostic information about a request to a specific URL. +*/ @implementation CPURLResponse : CPObject { } @@ -44,11 +47,15 @@ Getting the Response Properties */ @end +/* + Represents the response to an http request. +*/ @implementation CPHTTPURLResponse : CPURLResponse { int _statusCode; } +/* @ignore */ - (id)_initWithStatusCode:(int)aStatusCode { self = [super init]; @@ -59,6 +66,9 @@ Getting the Response Properties return self; } +/* + Returns the HTTP status code. +*/ - (int)statusCode { return _statusCode; diff --git a/Foundation/CPUndoManager.j b/Foundation/CPUndoManager.j index e25703b720..b415e3d301 100644 --- a/Foundation/CPUndoManager.j +++ b/Foundation/CPUndoManager.j @@ -40,6 +40,7 @@ CPUndoCloseGroupingRunLoopOrdering = 350000; var _CPUndoGroupingPool = [], _CPUndoGroupingPoolCapacity = 5; +/* @ignore */ @implementation _CPUndoGrouping : CPObject { _CPUndoGrouping _parent; @@ -149,6 +150,9 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", @end +/* + CPUndoManager provides a general mechanism supporting implementation of user action "undo" in applications. Essentially, it allows you to store sequences of messages and receivers that need to be invoked to undo or redo an action. The various methods in this class provide for grouping of sets of actions, execution of undo or redo actions, and tuning behavior parameters such as the size of the undo stack. Each application entity with its own editing history (e.g., a document) should have its own undo manager instance. Obtain an instance through a simple [[CPUndoManager alloc] init] message. +*/ @implementation CPUndoManager : CPObject { CPMutableArray _redoStack; @@ -166,6 +170,10 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", BOOL _registeredWithRunLoop; } +/* + Initializes the undo manager + @return the initialized undo manager +*/ - (id)init { self = [super init]; @@ -186,16 +194,21 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", } // Registering Undo Operations - +/* + Registers an undo operation. You invoke this method with the target of the undo action providing the selector which can perform the undo with the provided object. The object is often a dictionary of the identifying the attribute and their values before the change. The invocation will be added to the current grouping. If the registrations have been disabled through -disableUndoRegistration, this method does nothing. + @param aTarget the target for the undo invocation + @param aSelector the selector for the action message + @param anObject the argument for the action message + @throws CPInternalInconsistencyException if no undo group is currently open +*/ - (void)registerUndoWithTarget:(id)aTarget selector:(SEL)aSelector object:(id)anObject { + if (!_currentGrouping) + [CPException raise:CPInternalInconsistencyException reason:"No undo group is currently open"]; + if (_disableCount > 0) return; -/* if (_currentGroup == nil) - [NSException raise:NSInternalInconsistencyException - format:@"forwardInvocation called without first opening an undo group"]; -*/ //signature = [target methodSignatureForSelector:selector]; // FIXME: we need method signatures. var invocation = [CPInvocation invocationWithMethodSignature:nil]; @@ -209,7 +222,11 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", if (_state == CPUndoManagerNormal) [_redoStack removeAllObjects]; } - +/* + Prepares the specified target for the undo action. + @param aTarget the target to receive the action + @return the undo manager +*/ - (id)prepareWithInvocationTarget:(id)aTarget { _preparedTarget = aTarget; @@ -217,6 +234,10 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", return self; } +/* + FIXME This method doesn't seem to do anything right + @ignore +*/ -(CPMethodSignature)methodSignatureForSelector:(SEL)aSelector { if ([_preparedTarget respondsToSelector:aSelector]) @@ -225,6 +246,11 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", return nil;//[_preparedTarget methodSignatureForSelector:selector]; } +/* + Records the specified invocation as an undo operation. Sets the + target on the invocation, and adds it to the current grouping. + @param anInvocation the message to record +*/ - (void)forwardInvocation:(CPInvocation)anInvocation { if (_disableCount > 0) @@ -247,12 +273,17 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", } // Checking Undo Ability - +/* + Returns YES if the user can perform a redo operation. +*/ - (BOOL)canRedo { return _redoStack.length > 0; } +/* + Returns YES if the user can perform an undo operation. +*/ - (BOOL)canUndo { if (_undoStack.length > 0) @@ -262,7 +293,9 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", } // Preform Undo and Redo - +/* + Ends the current grouping, and performs an 'undo' operation. +*/ - (void)undo { if ([self groupingLevel] == 1) @@ -271,6 +304,9 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", [self undoNestedGroup]; } +/* + Performs an undo on the last undo group. +*/ - (void)undoNestedGroup { if (_undoStack.length == 0) @@ -297,6 +333,9 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", [defaultCenter postNotificationName:CPUndoManagerDidUndoChangeNotification object:self]; } +/* + Performs the redo operation using the last grouping on the redo stack. +*/ - (void)redo { // Don't do anything if we have no redos. @@ -333,16 +372,22 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", } // Creating Undo Groups - +/* + Starts a new grouping of undo tasks, and makes it the current grouping. +*/ - (void)beginUndoGrouping { _currentGrouping = [_CPUndoGrouping undoGroupingWithParent:_currentGrouping]; } +/* + Closes the current undo grouping. + @throws CPInternalInconsistencyException if no undo group is open +*/ - (void)endUndoGrouping { if (!_currentGrouping) - alert("FIXME: this should be an exception endUndoGrouping - currentUndoGrouping = nil."); + [CPException raise:CPInternalInconsistencyException reason:"endUndoGrouping. No undo group is currently open."]; var parent = [_currentGrouping parent]; @@ -373,19 +418,33 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", _currentGrouping = parent; } +/* + Enables undo registrations. Calls to this method must + be balanced with calls to disableUndoRegistration. + So, if two disable calls were made, two enable calls are required + to actually enable undo registration again. +*/ - (void)enableUndoRegistration { if (_disableCount <= 0) - return; + [CPException raise:CPInternalInconsistencyException + reason:"enableUndoRegistration. There are no disable messages in effect right now."]; _disableCount--; } +/* + Returns YES if the manager groups undo operations at every iteration of the run loop. +*/ - (BOOL)groupsByEvent { return _groupsByEvent; } +/* + Sets whether the manager should group undo operations at every iteration of the run loop. + @param aFlag YES groups undo operations +*/ - (void)setGroupsByEvent:(BOOL)aFlag { if (_groupsByEvent == aFlag) @@ -406,6 +465,9 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", [self _unregisterWithRunLoop]; } +/* + Returns the number of undo/redo groups. +*/ - (unsigned)groupingLevel { var grouping = _currentGrouping, @@ -418,31 +480,43 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", } // Disabling Undo - +/* + Disables undo registrations. +*/ - (void)disableUndoRegistration { ++_disableCount; } +/* + Returns YES if undo registration is enabled. +*/ - (BOOL)isUndoRegistrationEnabled { return _disableCount == 0; } // Checking Whether Undo or Redo Is Being Performed - +/* + Returns YES if the manager is currently performing an undo. +*/ - (BOOL)isUndoing { return _state == CPUndoManagerUndoing; } +/* + Returns YES if the manager is currently performing a redo. +*/ - (BOOL)isRedoing { return _state == CPUndoManagerRedoing; } // Clearing Undo Operations - +/* + Clears all redo and undo operations and enables undo registrations. +*/ - (void)removeAllActions { _redoStack = []; @@ -450,6 +524,10 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", _disableCount = 0; } +/* + Removes any redo and undo operations that use the specified target. + @param aTarget the target for which operations should be removed. +*/ - (void)removeAllActionsWithTarget:(id)aTarget { [_currentGrouping removeInvocationsWithTarget:aTarget]; @@ -480,29 +558,56 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", } // Managing the Action Name - +/* + Sets the name associated with the actions of the current group. + Typically, you can call this method while registering the actions for the current group. + @param anActionName the new name for the current group +*/ - (void)setActionName:(CPString)anActionName { _actionName = anActionName; } +/* + If the receiver can perform a redo, this method returns the action + name previously associated with the top grouping with + -setActionName:. This name should identify the action to be redone. + @return the redo action's name, or nil if no there's no redo on the stack. +*/ - (CPString)redoActionName { return [self canRedo] ? _actionName : nil; } +/* + If the receiver can perform an undo, this method returns the action + name previously associated with the top grouping with + -setActionName:. This name should identify the action to be undone. + @return the undo action name or nil if no if there's no undo on the stack. +*/ - (CPString)undoActionName { return [self canUndo] ? _actionName : nil; } // Working With Run Loops - +/* + Returns the CPRunLoopModes in which the receiver registers + the -endUndoGrouping processing when it -groupsByEvent. +*/ - (CPArray)runLoopModes { return _runLoopModes; } +/* + Sets the modes in which the receiver registers the calls + with the current run loop to invoke -endUndoGrouping + when it -groupsByEvent. This method first + cancels any pending registrations in the old modes and + registers the invocation in the new modes. + @param modes the modes in which calls are registered +*/ - (void)setRunLoopModes:(CPArray)modes { _runLoopModes = modes; @@ -513,6 +618,7 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", [self _registerWithRunLoop]; } +/* @ignore */ - (void)beginUndoGroupingForEvent { if (!_groupsByEvent) @@ -527,6 +633,7 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", target:self argument:nil order:CPUndoCloseGroupingRunLoopOrdering modes:_runLoopModes]; } +/* @ignore */ - (void)_registerWithRunLoop { if (_registeredWithRunLoop) @@ -537,6 +644,7 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", target:self argument:nil order:CPUndoCloseGroupingRunLoopOrdering modes:_runLoopModes]; } +/* @ignore */ - (void)_unregisterWithRunLoop { if (!_registeredWithRunLoop) diff --git a/Foundation/CPValue.j b/Foundation/CPValue.j index 7bfd6c5a7a..3ce9318fb5 100644 --- a/Foundation/CPValue.j +++ b/Foundation/CPValue.j @@ -23,16 +23,29 @@ import "CPObject.j" import "CPCoder.j" +/* + The class can be subclassed to hold different types of scalar values. +*/ @implementation CPValue : CPObject { JSObject _JSObject; } +/* + Creates a value from the specified JavaScript object + @param aJSObject a JavaScript object containing a value + @return the converted CPValue +*/ + (id)valueWithJSObject:(JSObject)aJSObject { return [[self alloc] initWithJSObject:aJSObject]; } +/* + Initializes the value from a JavaScript object + @param aJSObject the object to get data from + @return the initialized CPValue +*/ - (id)initWithJSObject:(JSObject)aJSObject { self = [super init]; @@ -43,6 +56,9 @@ import "CPCoder.j" return self; } +/* + Returns the JavaScript object backing this value. +*/ - (JSObject)JSObject { return _JSObject; @@ -54,6 +70,11 @@ var CPValueValueKey = @"CPValueValueKey"; @implementation CPValue (CPCoding) +/* + Initializes the value from a coder. + @param aCoder the coder from which to initialize + @return the initialized CPValue +*/ - (id)initWithCoder:(CPCoder)aCoder { self = [super init]; @@ -64,6 +85,10 @@ var CPValueValueKey = @"CPValueValueKey"; return self; } +/* + Encodes the data into the specified coder. + @param the coder into which the data will be written. +*/ - (void)encodeWithCoder:(CPCoder)aCoder { [aCoder encodeObject:CPJSObjectCreateJSON(_JSObject) forKey:CPValueValueKey]; diff --git a/Objective-J/Object.j b/Objective-J/Object.j index 0e96b94b2b..3913f7b62b 100644 --- a/Objective-J/Object.j +++ b/Objective-J/Object.j @@ -33,7 +33,7 @@ { } -- (id)forwardSelector:(SEL)selector arguments:(void *)args +- (id)forwardSelector:(SEL)selector arguments:(void)args { return nil; }