//
//  MPExpressionView.h
//  MathKit
//
//  Created by Kim Wittenburg on 17.04.14.
//  Copyright (c) 2014 Kim Wittenburg. All rights reserved.
//


/*!
 @header
 This file contains the <code>MPExpressionView</code> class.
 
 <h2>The MathKit Expression System</h2>
 MathKit contains class es that make up the so called <i>expression system</i>.
 The expression system is divided into three layers: the model, the view and the
 controller layer. The <code>MPExpressionView</code> class represents the view
 layer and interacts with the Cocoa <code>NSView</code> system. The model is
 represented by the classes <code>@link
 //apple_ref/occ/cl/MPExpression@/link</code> and <code>@link
 //apple_ref/occ/cl/MPFunction@/link</code>. The controller layer between the two
 consists of the class <code>@link //apple_ref/occ/cl/MPLayout@/link</code> and
 its subclasses. The purpose of the expression system is presenting expressions
 to the user and offering possibilities to manipulate and work with expressions.
 */



@class MPExpressionView, MPExpressionStorage, MPFunction, MPRangePath;


/*!
    @class      MPExpressionView
    @abstract   The <code>MPExpressionView</code> class is the front-end class of
                the MathKit expression system.
 
    @discussion The class draws the expression managed by the the back-end class
                <code>@link //apple_ref/occ/cl/MPExpressionStorage@/link</code>
                and is the interface between Application Kit's view system and
                the MathKit expression system.
 */
@interface MPExpressionView : NSView <NSUserInterfaceValidations>

#pragma mark Creation Methods
/*!
 @methodgroup Creation Methods
 */


/*!
    @method     initWithFrame:
    @abstract   Initializes a <code>MPExpressionView</code> instance.
 
    @discussion This method sets up all layers of the expression system including
                an empty expression storage.
 
                This method is the designated initializer of the
                <code>MPExpressionView</code> class.
 
    @param      frameRect
                The frame rectangle for the created view.
 
    @return     An initialized <code>MPExpressionView</code> or <code>nil</code>
                if the object could not be created.
 */
- (id)initWithFrame:(NSRect)frameRect;


#pragma mark Properties
/*!
 @methodgroup Properties
 */


/*!
    @property   expressionStorage
    @abstract   The receiver's expression storage.
 
    @discussion The expression storage maintains the contents of the receiver.
                User interactions change the underlying data. If the expression
                storage or the underlying expression change the expression
                storage updates the receiver.
 */
@property (nonatomic, strong) MPExpressionStorage *expressionStorage;


/*!
    @property   selection
    @abstract   The receiver's selection.
 */
@property (nonatomic, strong) MPRangePath *selection;


/*!
    @property   mathError
    @abstract   If set the receiver will display the localized description of the
                specified error.
 
    @discussion There can only be one math error at a time. This property should
                not be set simutaneously with the <code>@link
                //apple_ref/occ/instp/MPExpressionView/syntaxErrors@/link</code>
                property.
 */
@property (nonatomic, strong) NSError *mathError;


/*!
    @property   syntaxErrors
    @abstract   If set the receiver will display a dropdown list of syntax
                errors.
 
    @discussion The array must only contain <code>NSError</code> instances. In
                addition to that every instance must contain a valid
                <code>NSIndexPath</code> for the <code>@link
                //apple_ref/c/data/MPPathToExpressionKey@/link</code> in its
                <code>userDict</code> acompanied by a <code>NSRange</code> 
                wrapped in a <code>NSValue</code> instance for the <code>@link
                //apple_ref/c/data/MPErrorRangeKey@/link</code>.
 
                If the user selects an item from the dropdown list the part of
                the expression displayed by the receiver will be selected that is
                specified by the values in the corresponding <code>NSError</code>
                instance.
 */
@property (nonatomic, strong) NSArray *syntaxErrors;


/*!
    @property   target
    @abstract   The target object to receive action messages from the receiver.
 */
@property (nonatomic, weak) id target;


/*!
    @property   action
    @abstract   The receiver's action method to the specified selector.
 
    @discussion The action method is invoked when the user presses <i>enter</i>
                in the receiver. Typically this is understood as evaluation
                request.
 */
@property (nonatomic) SEL action;


#pragma mark Actions
/*!
 @methodgroup Actions
 */


/*!
    @method     switchToRadians:
    @abstract   Tells the receiver that it should switch the interpretation of
                trigonometric function values to radians.
 
    @param      sender
                Typically the object that invoked the method.
 */
- (IBAction)switchToRadians:(id)sender;


/*!
    @method     switchToDegrees:
    @abstract   Tells the receiver that it should switch the interpretation of
                trigonometric function values to degrees.
 
    @param      sender
                Typically the object that invoked the method.
 */
- (IBAction)switchToDegrees:(id)sender;


/*!
    @method     switchRadiansDegrees:
    @abstract   Tells the receiver that it should switch the interpretation of 
                trigonometric function values.
 
    @discussion If the interpretation is currently degrees it is changed to
                radians or vice versa.
 
    @param      sender
                Typically the object that invoked the method.
 */
- (IBAction)switchRadiansDegrees:(id)sender;


/*!
    @method     toggleFunctionsPopover:
    @abstract   Tells the receiver to toggle the visibility of the functions
                popover.
 
    @discussion From the functions popover the user can select and insert
                functions into the displayed expression
 
    @param      sender
                Typically the object that invoked the method.
 */
- (IBAction)toggleFunctionsPopover:(id)sender;

@end