NSRulerView Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSRulerView.h |
Class at a Glance
An NSRulerView displays a ruler and markers above or to the side of an NSScrollView’s document view. Views within the NSScrollView can become clients of the ruler view, having it display markers for their elements, and receiving messages from the ruler view when the user manipulates the markers.
Principal Attributes
Displays markers that represent elements of the client view.
Displays in arbitrary units.
Provides for an accessory view containing extra controls.
Creation
setHasHorizontalRuler:(NSScrollView)setHasVerticalRuler:(NSScrollView)-
initWithScrollView:orientation:Designated initializer.
Commonly Used Methods
setClientView:Changes the ruler’s client view.
setMarkers:Sets the markers displayed by the ruler view.
setAccessoryView:Sets the accessory view.
trackMarker:withMouseEvent:Allows the user to add a new marker.
Overview
An NSRulerView resides in an NSScrollView, displaying a labeled ruler and markers for its client, the document view of the NSScrollView, or a subview of the document view.
Tasks
Creating Instances
Altering Measurement Units
-
+ registerUnitWithName:abbreviation:unitToPointsConversionFactor:stepUpCycle:stepDownCycle: -
– setMeasurementUnits: -
– measurementUnits
Setting the Client View
Setting an Accessory View
Setting the Zero Mark Position
Adding and Removing Markers
Drawing Temporary Ruler Lines
Drawing
Ruler Layout
-
– setScrollView: -
– scrollView -
– setOrientation: -
– orientation -
– setReservedThicknessForAccessoryView: -
– reservedThicknessForAccessoryView -
– setReservedThicknessForMarkers: -
– reservedThicknessForMarkers -
– setRuleThickness: -
– ruleThickness -
– requiredThickness -
– baselineLocation -
– isFlipped
Adding markers
-
– rulerView:shouldAddMarker:delegate method -
– rulerView:willAddMarker:atLocation:delegate method -
– rulerView:didAddMarker:delegate method
Moving markers
-
– rulerView:shouldMoveMarker:delegate method -
– rulerView:willMoveMarker:toLocation:delegate method -
– rulerView:didMoveMarker:delegate method
Removing markers
-
– rulerView:shouldRemoveMarker:delegate method -
– rulerView:didRemoveMarker:delegate method
Handling mouse events
-
– rulerView:handleMouseDown:delegate method
Changing client view
-
– rulerView:willSetClientView:delegate method
Class Methods
registerUnitWithName:abbreviation:unitToPointsConversionFactor:stepUpCycle:stepDownCycle:
Registers a new unit of measurement with the NSRulerView class, making it available to all instances of NSRulerView.
Discussion
unitName is the name of the unit in English, in plural form and capitalized by convention—“Inches”, for example. The unit name is used as a key to identify the measurement units and so shouldn’t be localized. abbreviation is a localized short form of the unit name, such as “in” for Inches. conversionFactor is the number of PostScript points in the specified unit; there are 72.0 points per inch, for example. stepUpCycle and stepDownCycle are arrays of NSNumbers that specify how hash marks are calculated, as explained in “Setting Up a Ruler View”. All numbers in stepUpCycle should be greater than 1.0, those in stepDownCycle should be less than 1.0.
NSRulerView supports these units by default:
Unit Name |
Abbreviation |
Points/Unit |
Step-Up Cycle |
Step-Down Cycle |
|---|---|---|---|---|
Inches |
in |
72.0 |
2.0 |
0.5 |
Centimeters |
cm |
28.35 |
2.0 |
0.5, 0.2 |
Points |
pt |
1.0 |
10.0 |
0.5 |
Picas |
pc |
12.0 |
10.0 |
0.5 |
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hInstance Methods
accessoryView
Returns the receiver’s accessory view, if it has one.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.haddMarker:
Adds aMarker to the receiver, without consulting the client view for approval.
Discussion
Raises an NSInternalInconsistencyException if the receiver has no client view.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hbaselineLocation
Returns the location of the receiver’s baseline, in its own coordinate system.
Discussion
This is a y position for horizontal rulers and an x position for vertical ones.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hclientView
Returns the receiver’s client view, if it has one.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hdrawHashMarksAndLabelsInRect:
Draws the receiver’s hash marks and labels in aRect, which is expressed in the receiver’s coordinate system.
Discussion
This method is invoked by drawRect:—you should never need to invoke it directly. You can define custom measurement units using the class method registerUnitWithName:abbreviation:unitToPointsConversionFactor:stepUpCycle:stepDownCycle:. Override this method if you want to customize the appearance of the hash marks themselves.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hdrawMarkersInRect:
Draws the receiver’s markers in aRect, which is expressed in the receiver’s coordinate system.
Discussion
This method is invoked by drawRect:; you should never need to invoke it directly, but you might want to override it if you want to do something different when drawing markers.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hinitWithScrollView:orientation:
Initializes a newly allocated NSRulerView to have orientation (NSHorizontalRuler or NSVerticalRuler) within aScrollView.
Discussion
The new ruler view displays the user’s preferred measurement units and has no client, markers, or accessory view. Unlike most subclasses of NSView, no initial frame rectangle is given for NSRulerView; its containing NSScrollView adjusts its frame rectangle as needed.
This method is the designated initializer for the NSRulerView class. Returns an initialized object.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hinvalidateHashMarks
Forces recalculation of the hash mark spacing for the next time the receiver is displayed.
Discussion
You should never need to invoke this method directly, but might need to override it if you override drawHashMarksAndLabelsInRect:.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hisFlipped
Returns YES if the NSRulerView’s coordinate system is flipped, NO otherwise.
Discussion
A vertical ruler takes into account whether the coordinate system of the NSScrollView’s document view—not the receiver’s client view—is flipped. A horizontal ruler is always flipped.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hmarkers
Returns the receiver’s NSRulerMarkers.
Discussion
The markers aren’t guaranteed to be sorted in any particular order.
Availability
- Available in OS X v10.0 and later.
See Also
-
– setMarkers: -
– addMarker: -
– removeMarker: -
– markerLocation(NSRulerMarker)
Declared In
NSRulerView.hmeasurementUnits
Returns the full name of the measurement units in effect for the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hmoveRulerlineFromLocation:toLocation:
Draws temporary lines in the ruler area.
Discussion
If oldLoc is 0 or greater, erases the ruler line at that location; if newLoc is 0 or greater, draws a new rulerline at that location. oldLoc and newLoc are expressed in the coordinate system of the NSRulerView, not the client or document view, and are x coordinates for horizontal rulers and y coordinates for vertical rulers. Use NSView’s convert... methods to convert coordinates from the client or document view’s coordinate system to that of the NSRulerView.
This method is useful for drawing highlight lines in the ruler to show the position or extent of an object while it’s being dragged in the client view. The sender is responsible for keeping track of the number and positions of temporary lines—the NSRulerView only does the drawing.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.horientation
Returns the orientation of the receiver.
Discussion
Possible values are described in “Constants.”
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.horiginOffset
Returns the distance from the receiver’s zero hash mark to the bounds origin of the NSScrollView’s document view (not the receiver’s client view), in the document view’s coordinate system.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hremoveMarker:
Removes aMarker from the receiver, without consulting the client view for approval.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hrequiredThickness
Returns the thickness needed for proper tiling of the receiver within an NSScrollView.
Discussion
This thickness is the height of a horizontal ruler and the width of a vertical ruler. The required thickness is the sum of the thicknesses of the ruler area, the marker area, and the accessory view.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hreservedThicknessForAccessoryView
Returns the thickness reserved to contain the receiver’s accessory view, its height or width depending on the receiver’s orientation.
Discussion
This thickness is automatically enlarged as necessary to the accessory view’s thickness (but never automatically reduced). To prevent retiling of a ruler view’s scroll view, you should set its maximal thickness upon creating using setReservedThicknessForAccessoryView:.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hreservedThicknessForMarkers
Returns the thickness reserved to contain the images of the receiver’s ruler markers, the height or width depending on the receiver’s orientation.
Discussion
This thickness is automatically enlarged as necessary to accommodate the thickest ruler marker image (but never automatically reduced). To prevent retiling of a ruler view’s scroll view, you should set its maximal thickness upon creating using setReservedThicknessForMarkers:.
Availability
- Available in OS X v10.0 and later.
See Also
-
– thicknessRequiredInRuler(NSRulerMarker)
Declared In
NSRulerView.hruleThickness
Returns the thickness of the receiver’s ruler area (the area where hash marks and labels are drawn), its height or width depending on the receiver’s orientation.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hscrollView
Returns the NSScrollView object that contains the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
-
– setScrollView: -
– setHorizontalRulerView:(NSScrollView) -
– setVerticalRulerView:(NSScrollView)
Declared In
NSRulerView.hsetAccessoryView:
Sets the receiver’s accessory view to aView.
Discussion
Raises an NSInternalInconsistencyException if aView is not nil and the receiver has no client view.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hsetClientView:
Sets the receiver’s client view to aView, without retaining it, and removes its ruler markers, after informing the prior client of the change using rulerView:willSetClientView:.
Discussion
aView must be either the document view of the NSScrollView that contains the receiver or a subview of the document view.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hsetMarkers:
Sets the receiver’s ruler markers to markers, removing any existing ruler markers and not consulting with the client view about the new markers.
Discussion
markers can be nil or empty to remove all ruler markers. Raises an NSInternalInconsistencyException if markers is not nil and the receiver has no client view.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hsetMeasurementUnits:
Sets the measurement units used by the ruler to unitName.
Discussion
unitName must have been registered with the NSRulerView class object prior to invoking this method. See the description of the class method registerUnitWithName:abbreviation:unitToPointsConversionFactor:stepUpCycle:stepDownCycle: for a list of predefined units.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hsetOrientation:
Sets the orientation of the receiver to orientation.
Discussion
Possible values for orientation are described in “Constants.” You should never need to invoke this method directly—it’s automatically invoked by the containing NSScrollView.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hsetOriginOffset:
Sets the distance to the zero hash mark from the bounds origin of the NSScrollView’s document view (not of the receiver’s client view), in the document view’s coordinate system.
Discussion
The default offset is 0.0, meaning that the ruler origin coincides with the bounds origin of the document view.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hsetReservedThicknessForAccessoryView:
Sets the room available for the receiver’s accessory view to thickness.
Discussion
If the ruler is horizontal, thickness is the height of the accessory view; otherwise, it’s the width. NSRulerViews by default reserve no space for an accessory view.
An NSRulerView automatically increases the reserved thickness as necessary to that of the accessory view. When the accessory view is thinner than the reserved space, it’s centered in that space. If you plan to use several accessory views of different sizes, you should set the reserved thickness beforehand to that of the thickest accessory view, in order to avoid retiling of the NSScrollView.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hsetReservedThicknessForMarkers:
Sets the room available for ruler markers to thickness.
Discussion
The default thickness reserved for markers is 15.0 PostScript units for a horizontal ruler and 0.0 PostScript units for a vertical ruler (under the assumption that vertical rulers rarely contain markers). If you don’t expect to have any markers on the ruler, you can set the reserved thickness to 0.0.
An NSRulerView automatically increases the reserved thickness as necessary to that of its thickest marker. If you plan to use markers of varying sizes, you should set the reserved thickness beforehand to that of the thickest one in order to avoid retiling of the NSScrollView.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hsetRuleThickness:
Sets to thickness the thickness of the area where ruler hash marks and labels are drawn.
Discussion
This value is the height of the ruler area for a horizontal ruler or the width of the ruler area for a vertical ruler. Rulers are by default 16.0 PostScript units thick. You should rarely need to change this layout attribute, but subclasses might do so to accommodate custom drawing.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hsetScrollView:
Sets the NSScrollView that owns the receiver to scrollView, without retaining it.
Discussion
This method is generally invoked only by the ruler’s scroll view; you should rarely need to invoke it directly.
Availability
- Available in OS X v10.0 and later.
See Also
-
– scrollView -
– setHorizontalRulerView:(NSScrollView) -
– setVerticalRulerView:(NSScrollView)
Declared In
NSRulerView.htrackMarker:withMouseEvent:
Tracks the mouse to add aMarker based on the initial mouse-down or mouse-dragged event theEvent.
Discussion
Returns YES if the receiver adds aMarker, NO if it doesn’t. This method works by sending trackMouse:adding: to aMarker with theEvent and YES as arguments.
An application typically invokes this method in one of two cases. In the simpler case, the client view can implement rulerView:handleMouseDown: to invoke this method when the user presses the mouse button while the cursor is in the NSRulerView’s ruler area. This technique is appropriate when it’s clear what kind of marker will be added by clicking the ruler area. The second, more general, case involves the application providing a palette of different kinds of markers that can be dragged onto the ruler, from the ruler’s accessory view or from some other place. With this technique the palette tracks the cursor until it enters the ruler view, at which time it hands over control to the ruler view by invoking trackMarker:withMouseEvent:.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSRulerView.hDelegate Methods
rulerView:didAddMarker:
Informs the client that aRulerView allowed the user to add aMarker.
Discussion
The client can take whatever action it needs based on this message, such as adding a new tab stop to the selected paragraph or creating a layout guideline.
Availability
- Available in OS X v10.0 and later.
See Also
-
– representedObject(NSRulerMarker) -
– markerLocation(NSRulerMarker)
Declared In
NSRulerView.hrulerView:didMoveMarker:
Informs the client that aRulerView allowed the user to move aMarker.
Discussion
The client can take whatever action it needs based on this message, such as updating the location of a tab stop in the selected paragraph, moving a layout guideline, or resizing a graphics element.
Availability
- Available in OS X v10.0 and later.
See Also
-
– representedObject(NSRulerMarker) -
– markerLocation(NSRulerMarker)
Declared In
NSRulerView.hrulerView:didRemoveMarker:
Informs the client that aRulerView allowed the user to remove aMarker.
Discussion
The client can take whatever action it needs based on this message, such as deleting a tab stop from the paragraph style or removing a layout guideline.
Availability
- Available in OS X v10.0 and later.
See Also
-
– representedObject(NSRulerMarker)
Declared In
NSRulerView.hrulerView:handleMouseDown:
Informs the client that the user has pressed the mouse button while the cursor is in the ruler area of aRulerView.
Discussion
theEvent is the mouse-down event that triggered the message. The client view can implement this method to perform an action such as adding a new marker using trackMarker:withMouseEvent: or adding layout guidelines.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hrulerView:shouldAddMarker:
Requests permission for aRulerView to add aMarker, an NSRulerMarker being dragged onto the ruler by the user.
Discussion
If the client returns YES the ruler view accepts the new marker and begins tracking its movement; if the client returns NO the ruler view refuses the new marker.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hrulerView:shouldMoveMarker:
Requests permission for aRulerView to move aMarker.
Discussion
If the client returns YES the ruler view allows the user to move the marker; if the client returns NO the marker doesn’t move.
The user’s ability to move a marker is typically set on the marker itself, using NSRulerMarker’s setMovable: method. You should use this client view method only when the marker’s movability can vary depending on a variable condition (for example, if graphic items can be locked down to prevent them from being inadvertently moved).
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hrulerView:shouldRemoveMarker:
Requests permission for aRulerView to remove aMarker.
Discussion
If the client returns YES the ruler view allows the user to remove the marker; if the client returns NO the marker is kept pinned to the ruler’s baseline. This message is sent as many times as needed while the user drags the marker.
The user’s ability to remove a marker is typically set on the marker itself, using NSRulerMarker’s setRemovable: method. You should use this client view method only when the marker’s removability can vary while the user drags it (for example, if the user must press the Shift key to remove a marker).
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hrulerView:willAddMarker:atLocation:
Informs the client that aRulerView will add the new NSRulerMarker, aMarker.
Discussion
location is the marker’s tentative new location, expressed in the client view’s coordinate system. The value returned by the client view is actually used; the client can simply return location unchanged or adjust it as needed. For example, it may snap the location to a grid. This message is sent repeatedly to the client as the user drags the marker.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hrulerView:willMoveMarker:toLocation:
Informs the client that aRulerView will move aMarker, an NSRulerMarker already on the ruler view.
Discussion
location is the marker’s tentative new location, expressed in the client view’s coordinate system. The value returned by the client view is actually used; the client can simply return location unchanged or adjust it as needed. For example, it may snap the location to a grid. This message is sent repeatedly to the client as the user drags the marker.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hrulerView:willSetClientView:
Informs the client view that aRulerView is about to be appropriated by newClient.
Discussion
The client view can use this opportunity to clear any cached information related to the ruler.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.hConstants
NSRulerOrientation
These constants are defined to specify a ruler’s orientation and are used by orientation and setOrientation:.
typedef enum {
NSHorizontalRuler,
NSVerticalRuler
} NSRulerOrientation;
Constants
NSHorizontalRulerRuler is oriented horizontally.
Available in OS X v10.0 and later.
Declared in
NSRulerView.h.NSVerticalRulerRuler is oriented vertically.
Available in OS X v10.0 and later.
Declared in
NSRulerView.h.
Availability
- Available in OS X v10.0 and later.
Declared In
NSRulerView.h© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-05-23)