DrawKit
Vector and illustration framework for Mac OS X
Instance Methods | Protected Attributes | List of all members
DKViewController Class Reference

DKViewController is a basic controller class that sits between a DKDrawingView and the DKDrawing itself, which implements the data model. More...

Inheritance diagram for DKViewController:
Inheritance graph
[legend]

Instance Methods

(BOOL- activatesLayersAutomatically
 Should a mouse down activate the layer it hits automatically? More...
 
(NSRect- activeCursorRect
 Return the active cursor rect. More...
 
(DKLayer *) - activeLayer
 Return the drawing's current active layer. More...
 
(void) - activeLayerDidChangeToLayer:
 A new layer was activated. More...
 
(id- activeLayerOfClass:
 Return the drawing's current active layer if it matches the given class, else nil. More...
 
(void) - activeLayerWillChangeToLayer:
 A new layer is about to be activated. More...
 
(BOOL- autoActivateLayerWithEvent:
 If layers can be automatically activated, perform that switch. More...
 
(void) - autoscrollTimerCallback:
 
(BOOL- contextualMenusEnabled
 Are the standard contextual menus within DK are enabled or not? More...
 
(IBAction) - copyDrawing:
 
(NSCursor *) - cursor
 Return the cursor to display when the mouse is in the view. More...
 
(DKDrawing *) - drawing
 Return the controller's drawing. More...
 
(void) - drawingDidChangeToSize:
 Notify that the drawing has had its size changed. More...
 
(void) - exitTemporaryTextEditingMode
 Stop any text editing that may be taking place in the view. More...
 
(DKLayer *) - findLayer:
 Which layer did the point hit? More...
 
(void) - flagsChanged:
 Handle the flags changed event. More...
 
(IBAction) - hideInactiveLayers:
 Hides all inactive layers and shows the active layer (if it's hidden) More...
 
(void) - hideViewRulerMarkers
 Hide the view's ruler markers. More...
 
(id- initWithView:
 Initialize the controller. More...
 
(void) - invalidateCursors
 Invalidate the cursor rects for the view. More...
 
(IBAction) - layerBringForward:
 Move the active layer 1 position forward within its group. More...
 
(IBAction) - layerBringToFront:
 Bring the active layer to the front of its group. More...
 
(IBAction) - layerSendBackward:
 Move the active layer 1 position towards the back within its group. More...
 
(IBAction) - layerSendToBack:
 Move the active layer to the back within its group. More...
 
(NSMenu *) - menuForEvent:
 
(void) - mouseDown:
 Handle the mouse down event. More...
 
(void) - mouseDragged:
 Handle the mouse dragged event. More...
 
(void) - mouseMoved:
 Handle the mouse moved event. More...
 
(void) - mouseUp:
 Handle the mouse up event. More...
 
(void) - objectDidNotifyStatusChange:
 An object in the drawing notified a status (rather than visual) change. More...
 
(void) - rulerView:handleMouseDown:
 Respond to a mouse-down in one of the view's rulers. More...
 
(void) - scrollViewToRect:
 Scroll the view so that the given area is visible. More...
 
(void) - setActivatesLayersAutomatically:
 Should a mouse down activate the layer it hits automatically? More...
 
(void) - setContextualMenusEnabled:
 Set whether the standard contextual menus within DK are enabled or not. More...
 
(void) - setDrawing:
 Set the drawing that the controller is attached to. More...
 
(void) - setView:
 Set the view that the controller is associated with. More...
 
(void) - setViewNeedsDisplay:
 Mark the entire view for update. More...
 
(void) - setViewNeedsDisplayInRect:
 Mark part of the view for update. More...
 
(IBAction) - showAllLayers:
 Shows all layers. More...
 
(void) - startAutoscrolling
 Start the autoscroll timer. More...
 
(void) - stopAutoscrolling
 Stop the autoscroll timer. More...
 
(void) - synchronizeViewRulersWithUnits:
 Set the rulers to match the unit string. More...
 
(IBAction) - toggleGridVisible:
 
(IBAction) - toggleGuidesVisible:
 
(IBAction) - toggleSnapToGrid:
 
(IBAction) - toggleSnapToGuides:
 
(void) - updateViewRulerMarkersForRect:
 Set the ruler markers to the given rect. More...
 
(NSView *) - view
 Return the controller's view. More...
 
(CGFloat- viewScale
 Return the current scale of the view. More...
 
- Instance Methods inherited from NSObject
(NSString *) - address
 
(DKStyleRegistry *) - applicationWillReturnStyleRegistry
 
(BOOL- canBeUsedWithSelectionTool
 
(id- categoryManager:shouldReplaceObject:withObject:
 
(Class- classForCoder
 
(NSColor *) - colorValue
 
(NSColor *) - colourValue
 
(id- copy
 
(void) - dealloc
 
(id- deepCopy
 
(NSDictionary *) - dimensionValuesForArrowStroke:
 
(CGFloat- drawing:convertDistanceToExternalCoordinates:
 
(NSPoint) - drawing:convertLocationToExternalCoordinates:
 
(void) - drawing:didDrawRect:inView:
 
(void) - drawing:willDrawRect:inView:
 
(NSString *) - drawing:willReturnAbbreviationForUnit:
 
(NSString *) - drawing:willReturnFormattedCoordinateForDistance:
 
(CGFloat- drawingWillReturnUnitToPointsConversonFactor:
 
(void) - finalize
 
(NSString *) - hexString
 
(void) - hotspot:didEndTrackingWithEvent:inView:
 
(void) - hotspot:isTrackingWithEvent:inView:
 
(void) - hotspot:willBeginTrackingWithEvent:inView:
 
(NSData *) - imageData
 
(NSImage *) - imageResourceNamed:
 
(id- init
 
(id- initWithExpression:
 
(id- instantiateObjectWithShortName:parameters:
 
(BOOL- isLiteralValue
 
(void) - layoutManager:willPlaceGlyphAtIndex:atLocation:pathAngle:yOffset:
 
(void) - menuItem:wasAddedForObject:inCategory:
 
(BOOL- moveObjectTo:position:slope:userInfo:
 
(id- mutableCopy
 
(void) - oneShotComplete
 
(void) - oneShotHasReached:
 
(void) - oneShotWillBegin
 
(void) - path:elementIndex:type:points:subPathIndex:subPathClosed:contextInfo:
 
(id- placeLinkFromPoint:toPoint:onPath:linkNumber:userInfo:
 
(id- placeObjectAtPoint:onPath:position:slope:userInfo:
 
(NSPoint) - point
 
(NSPoint) - pointForTextLayout
 
(DKStyle *) - registry:shouldReplaceStyle:withStyle:
 
(NSBezierPath *) - renderer:willRenderPath:
 
(void) - routeFinder:progressHasReached:
 
(void) - setValue:forNumericParameter:
 
(NSString *) - stringValue
 
(CGFloat- taperFactorAtDistance:onPath:ofLength:
 
(void) - toolDidPerformUndoableAction:
 
(void) - toolWillPerformUndoableAction:
 
(NSURL *) - url
 
- Instance Methods inherited from <NSObject>
(NSString *) - description
 
(NSUInteger- hash
 
(BOOL- isEqual:
 
- Instance Methods inherited from <NSKeyValueBindingCreation>
(void) - bind:toObject:withKeyPath:options:
 
(NSArray *) - exposedBindings
 
(NSDictionary *) - infoForBinding:
 
(NSArray *) - optionDescriptionsForBinding:
 
(void) - unbind:
 
(Class- valueClassForBinding:
 

Protected Attributes

NSEventmDragEvent
 

Additional Inherited Members

- Class Methods inherited from NSObject
(id+ alloc
 
(Class+ class
 
(void) + initialize
 
(void) + load
 
(id+ new
 
- Class Methods inherited from <NSKeyValueBindingCreation>
(void) + exposeBinding:
 

Detailed Description

DKViewController is a basic controller class that sits between a DKDrawingView and the DKDrawing itself, which implements the data model.

DKViewController is a basic controller class that sits between a DKDrawingView and the DKDrawing itself, which implements the data model.

Its job is broadly divided into two areas, input and output.

When part of a drawing needs to be redisplayed in the view, the drawing will pass the area needing update to the controller, which will set that area for redisplay in the view, if appropriate. The view redisplays the content accordingly (it may call DKDrawing's drawRect:inView: method). Other subclasses of this might present the drawing differently - for example a layers palette could display the layers as a list in a tableview.

Each view of the drawing has one controller, so the drawing has a to-many relationship with its controllers, but each controller has a to-one relationship with the view.

An important function of the controller is to receive user input from the view and direct it to the active layer in an appropriate way. This includes handling the "tool" that a user might select in an interface and applying it to the drawing. See DKToolController (a subclass of this). This also implements autoscrolling around the mouse down/up calls which by and large "just work". However if you override these methods you should call super to keep autoscrolling operative.

Ownership: drawings own the controllers which reference the view. Views keep a reference to their controllers. When a view is dealloc'd, its controller is removed from the drawing. The controller has weak references to both its view and the drawing - this permits a view to own a drawing without a retain cycle being introduced - whichever of the drawing or the view gets dealloc'd first, the view controller is also dealloc'd. A view can own a drawing in the special circumstance of a view creating the drawing automatically if none has been set up prior to the first call to -drawRect:

Flow of control: initially all messages that cannot be directly handled by DKDrawingView are forwarded to its controller. The controller can handle the message or pass it on to the active layer. This is the default behaviour - typically layer subclasses handle most of their own action messages and some handle their own mouse input. For most object layers, where a "tool" can be applied, the controller works with the tool to implement the desired behaviour within the target layer. The view and the controller both use invocation forwarding to push messages down into the DK system via the controller, the active layer, any selection within it, and finally the target object(s) there.

A subclass of this can also implement drawRect: if it needs to, and can thus draw into its view. This is called after all other drawing has been completed except for page breaks. Tool controllers for example can draw selection rects, etc.

Method Documentation

- (BOOL) activatesLayersAutomatically

Should a mouse down activate the layer it hits automatically?

The default is YES

Returns
YES to auto-activate a layer, NO to leave it to someone else
- (NSRect) activeCursorRect

Return the active cursor rect.

Defines the area in which -cursor will be displayed - outside this rect the arrow cursor is displayed.

Returns
a rect
- (DKLayer*) activeLayer

Return the drawing's current active layer.

Returns
the active layer
- (void) activeLayerDidChangeToLayer: (DKLayer *)  aLayer

A new layer was activated.

The default method sets up the drag types for the view based on what drag types the layer is able to receive. If you override this, call super to ensure dragging still operates correctly.

Parameters
aLayerthe layer that was activated
- (id) activeLayerOfClass: (Class aClass

Return the drawing's current active layer if it matches the given class, else nil.

Parameters
aClassa layer class
Returns
the active layer if it matches the class, otherwise nil
- (void) activeLayerWillChangeToLayer: (DKLayer *)  aLayer

A new layer is about to be activated.

Parameters
aLayerthe layer about to be activated
- (BOOL) autoActivateLayerWithEvent: (NSEvent *)  event

If layers can be automatically activated, perform that switch.

Parameters
eventthe initiating event - typically a mouseDown event.
Returns
YES if a new layer was actually made active, NO if it remained the same
- (void) autoscrollTimerCallback: (NSTimer *)  timer
- (BOOL) contextualMenusEnabled

Are the standard contextual menus within DK are enabled or not?

The default is to enable the menus

Returns
YES if standard contextual menus are enabled, NO if not
- (IBAction) copyDrawing: (id sender
- (NSCursor*) cursor

Return the cursor to display when the mouse is in the view.

Returns
a cursor
- (DKDrawing*) drawing

Return the controller's drawing.

Returns
the controller's drawing
- (void) drawingDidChangeToSize: (NSValue *)  drawingSizeValue

Notify that the drawing has had its size changed.

The view's bounds and frame are adjusted to enclose the full drawing size and the view is updated

Parameters
drawingSizeValuean NSValue containing a sizeValue
- (void) exitTemporaryTextEditingMode

Stop any text editing that may be taking place in the view.

This is called by the drawing - generally you shouldn't call it directly, but instead use the similar drawing methods that take simple parameter types

- (DKLayer*) findLayer: (NSPoint)  p

Which layer did the point hit?

Test layers top-down. Each layer can decide for itself what constitutes a "hit". Typically a layer is hit when any object it contains is hit.

Parameters
pa point in local coordinates
Returns
the topmost layer hit by the given point, else nil
- (void) flagsChanged: (NSEvent *)  event

Handle the flags changed event.

Parameters
eventthe event
- (IBAction) hideInactiveLayers: (id sender

Hides all inactive layers and shows the active layer (if it's hidden)

High-level method can be invoked directly from a menu.

Parameters
senderthe sender of the action
- (void) hideViewRulerMarkers

Hide the view's ruler markers.

This is called by the drawing - generally you shouldn't call it directly, but instead use the similar drawing methods that take simple parameter types

- (id) initWithView: (NSView *)  aView

Initialize the controller.

Parameters
aViewthe view object that this controller manages
Returns
the controller object
- (void) invalidateCursors

Invalidate the cursor rects for the view.

This is called by the drawing - generally you shouldn't call it directly, but instead use the similar drawing methods that take simple parameter types

- (IBAction) layerBringForward: (id sender

Move the active layer 1 position forward within its group.

High-level method can be invoked directly from a menu. Undoably moves the layer forward.

Parameters
senderthe sender of the action
- (IBAction) layerBringToFront: (id sender

Bring the active layer to the front of its group.

High-level method can be invoked directly from a menu. Undoably moves the layer to front.

Parameters
senderthe sender of the action
- (IBAction) layerSendBackward: (id sender

Move the active layer 1 position towards the back within its group.

High-level method can be invoked directly from a menu. Undoably moves the layer backwards.

Parameters
senderthe sender of the action
- (IBAction) layerSendToBack: (id sender

Move the active layer to the back within its group.

High-level method can be invoked directly from a menu. Undoably moves the layer to the back.

Parameters
senderthe sender of the action
- (NSMenu*) menuForEvent: (NSEvent *)  event
- (void) mouseDown: (NSEvent *)  event

Handle the mouse down event.

If set to activate layers automatically, this will do so if the mouse hit something. It also starts a timer for autoscrolling, so if you override this, call super to get autoscrolling, or call startAutoscrolling on mouseDown.

Parameters
eventthe event
- (void) mouseDragged: (NSEvent *)  event

Handle the mouse dragged event.

Parameters
eventthe event
- (void) mouseMoved: (NSEvent *)  event

Handle the mouse moved event.

The basic controller ignores this - override to use it. DKDrawingView turns on mouse moved events by default but other view types may not.

Parameters
eventthe event
- (void) mouseUp: (NSEvent *)  event

Handle the mouse up event.

This stops the autoscrolling. If you override it, call super or stopAutoscrolling to ensure auto- scrolling works as intended.

Parameters
eventthe event
- (void) objectDidNotifyStatusChange: (id object

An object in the drawing notified a status (rather than visual) change.

Override to make use of this - the normal view controller just ignores this

Parameters
objectthe object that changed
- (void) rulerView: (NSRulerView *)  aRulerView
handleMouseDown: (NSEvent *)  event 

Respond to a mouse-down in one of the view's rulers.

This implements the dragging of a guide "off' a ruler and into place in the drawing's guide layer. If there is no guide layer it does nothing. This keeps control during the drag and invokes

Parameters
aRulerViewthe ruler view that started the event
eventthe event
- (void) scrollViewToRect: (NSValue *)  rectValue

Scroll the view so that the given area is visible.

This is called by the drawing - generally you shouldn't call it directly, but instead use the similar drawing methods that take simple parameter types

Parameters
rectValuean NSValue containing a rectValue, the rect to scroll into view
- (void) setActivatesLayersAutomatically: (BOOL acts

Should a mouse down activate the layer it hits automatically?

The default is YES

Parameters
actsYES to auto-activate a layer, NO to leave it to someone else
- (void) setContextualMenusEnabled: (BOOL enable

Set whether the standard contextual menus within DK are enabled or not.

The default is to enable the menus - some apps may wish to turn off the standard menus altogether rather than overriding each point where they are set up.

Parameters
enableYES to enable the menus, NO to disable them
- (void) setDrawing: (DKDrawing *)  aDrawing

Set the drawing that the controller is attached to.

DKDrawing objects own the controllers added to them. You should not call this directly - DKDrawing calls this at the appropriate time when the controller is added.

Parameters
aDrawingthe drawing object
- (void) setView: (NSView *)  aView

Set the view that the controller is associated with.

You should not call this directly, it is called by the designated initializer

Parameters
aViewthe view
- (void) setViewNeedsDisplay: (NSNumber *)  updateBoolValue

Mark the entire view for update.

This is called by the drawing - generally you shouldn't call it directly, but instead use the similar drawing methods that take simple parameter types

Parameters
updateBoolValuean NSNumber containing a boolValue, YES to update, NO to not update
- (void) setViewNeedsDisplayInRect: (NSValue *)  updateRectValue

Mark part of the view for update.

This is called by the drawing - generally you shouldn't call it directly, but instead use the similar drawing methods that take simple parameter types

Parameters
updateRectValuean NSValue containing a rectValue, the area to mark for update
- (IBAction) showAllLayers: (id sender

Shows all layers.

High-level method can be invoked directly from a menu.

Parameters
senderthe sender of the action
- (void) startAutoscrolling

Start the autoscroll timer.

Starts a timer running at 20fps which will cause autscrolling as long as the mouse is outside the view. Normally autoscrolling should start on mouse down and stop on mouse up.

- (void) stopAutoscrolling

Stop the autoscroll timer.

Normally autoscrolling should start on mouse down and stop on mouse up.

- (void) synchronizeViewRulersWithUnits: (NSString *)  unitString

Set the rulers to match the unit string.

This is called by the drawing - generally you shouldn't call it directly, but instead use the similar drawing methods that take simple parameter types

Parameters
unitStringa string used to look up the previously established ruler settings
- (IBAction) toggleGridVisible: (id sender
- (IBAction) toggleGuidesVisible: (id sender
- (IBAction) toggleSnapToGrid: (id sender
- (IBAction) toggleSnapToGuides: (id sender
- (void) updateViewRulerMarkersForRect: (NSValue *)  rectValue

Set the ruler markers to the given rect.

This is called by the drawing - generally you shouldn't call it directly, but instead use the similar drawing methods that take simple parameter types

Parameters
rectValuean NSValue containing a rectValue, the rect to move ruler markers to
- (NSView*) view

Return the controller's view.

Returns
the controller's view
- (CGFloat) viewScale

Return the current scale of the view.

Returns
a float value representing the view's zoom scale, 1.0 = 100%, 2.0 = 200% etc.

Member Data Documentation

- (NSEvent*) mDragEvent
protected