Mac Developer Library

Developer

AppKit Framework Reference NSRulerView Class Reference

Options
Deployment Target:

On This Page
Language:

NSRulerView

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.

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.

See NSRulerMarkerClientViewDelegation for delegate methods that may be of interest.

  • Initializes a newly allocated NSRulerView to have orientation (NSHorizontalRuler or NSVerticalRuler) within aScrollView.

    Declaration

    Swift

    init(scrollView scrollView: NSScrollView?, orientation orientation: NSRulerOrientation)

    Objective-C

    - (instancetype)initWithScrollView:(NSScrollView *)scrollView orientation:(NSRulerOrientation)orientation

    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.

  • The receiver’s client view, if it has one.

    Declaration

    Swift

    unowned(unsafe) var clientView: NSView?

    Objective-C

    @property(assign) NSView *clientView

    Discussion

    aView is 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.

  • 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.

    Declaration

    Swift

    var originOffset: CGFloat

    Objective-C

    @property CGFloat originOffset

    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.

  • The receiver’s ruler markers to markers, removing any existing ruler markers and not consulting with the client view about the new markers.

    Declaration

    Swift

    var markers: [NSRulerMarker]?

    Objective-C

    @property(copy) NSArray <NSRulerMarker *> *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.

  • Adds aMarker to the receiver, without consulting the client view for approval.

    Declaration

    Swift

    func addMarker(_ marker: NSRulerMarker)

    Objective-C

    - (void)addMarker:(NSRulerMarker *)marker

    Discussion

    Raises an NSInternalInconsistencyException if the receiver has no client view.

    Availability

    Available in OS X v10.0 and later.

  • Removes aMarker from the receiver, without consulting the client view for approval.

    Declaration

    Swift

    func removeMarker(_ marker: NSRulerMarker)

    Objective-C

    - (void)removeMarker:(NSRulerMarker *)marker

    Availability

    Available in OS X v10.0 and later.

  • Tracks the mouse to add aMarker based on the initial mouse-down or mouse-dragged event theEvent.

    Declaration

    Swift

    func trackMarker(_ marker: NSRulerMarker, withMouseEvent event: NSEvent) -> Bool

    Objective-C

    - (BOOL)trackMarker:(NSRulerMarker *)marker withMouseEvent:(NSEvent *)event

    Discussion

    Returns YEStrue if the receiver adds aMarker, NOfalse if it doesn’t. This method works by sending trackMouse:adding: to aMarker with theEvent and YEStrue 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.

  • Draws temporary lines in the ruler area.

    Declaration

    Swift

    func moveRulerlineFromLocation(_ oldLocation: CGFloat, toLocation newLocation: CGFloat)

    Objective-C

    - (void)moveRulerlineFromLocation:(CGFloat)oldLocation toLocation:(CGFloat)newLocation

    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.

  • The NSScrollView that owns the receiver to scrollView, without retaining it.

    Declaration

    Swift

    unowned(unsafe) var scrollView: NSScrollView?

    Objective-C

    @property(assign) NSScrollView *scrollView

    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

    – setHorizontalRulerView: (NSScrollView)
    – setVerticalRulerView: (NSScrollView)

  • The orientation of the receiver to orientation.

    Declaration

    Swift

    var orientation: NSRulerOrientation

    Objective-C

    @property NSRulerOrientation orientation

    Discussion

    Possible values for orientation are described in Constants.

    Availability

    Available in OS X v10.0 and later.

  • The room available for the receiver’s accessory view to thickness.

    Declaration

    Swift

    var reservedThicknessForAccessoryView: CGFloat

    Objective-C

    @property CGFloat reservedThicknessForAccessoryView

    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.

  • The room available for ruler markers to thickness.

    Declaration

    Swift

    var reservedThicknessForMarkers: CGFloat

    Objective-C

    @property CGFloat reservedThicknessForMarkers

    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.

  • The thickness of the area where ruler hash marks and labels are drawn.

    Declaration

    Swift

    var ruleThickness: CGFloat

    Objective-C

    @property CGFloat ruleThickness

    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.

  • The thickness needed for proper tiling of the receiver within an NSScrollView. (read-only)

    Declaration

    Swift

    var requiredThickness: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat requiredThickness

    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.

  • The location of the receiver’s baseline, in its own coordinate system. (read-only)

    Declaration

    Swift

    var baselineLocation: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat baselineLocation

    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

    ruleThickness

  • A boolean that indicates if the NSRulerView’s coordinate system is flipped. (read-only)

    Declaration

    Swift

    var flipped: Bool { get }

    Objective-C

    @property(getter=isFlipped, readonly) BOOL flipped

    Discussion

    YEStrue if the NSRulerView’s coordinate system is flipped, NOfalse otherwise.

    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.

Data Types

  • These constants are defined to specify a ruler’s orientation and are used by orientation.

    Declaration

    Swift

    enum NSRulerOrientation : UInt { case HorizontalRuler case VerticalRuler }

    Objective-C

    typedef enum { NSHorizontalRuler, NSVerticalRuler } NSRulerOrientation;

    Constants

    • horizontalRuler

      NSHorizontalRuler

      Ruler is oriented horizontally.

      Available in OS X v10.0 and later.

    • verticalRuler

      NSVerticalRuler

      Ruler is oriented vertically.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.