ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Application Kit Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSRulerView

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guide

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

Creation

Constructor
setHasHorizontalRuler (NSScrollView)
setHasVerticalRuler (NSScrollView)

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

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

Constructors

Altering Measurement Units

Setting the Client View

Setting an Accessory View

Setting the Zero Mark Position

Adding and Removing Markers

Drawing Temporary Ruler Lines

Drawing

Ruler Layout

Adding markers

Moving markers

Removing markers

Handling mouse events

Changing client view

Constructors

NSRulerView

Creates an NSRulerView with a zero-sized frame rectangle.

public NSRulerView()

Discussion

The orientation is horizontal (HorizontalRuler).

Creates an NSRulerView with aRect as its frame rectangle.

public NSRulerView(NSRect aRect)

Discussion

The orientation is horizontal (HorizontalRuler).

Creates an NSRulerView with orientation (HorizontalRuler or VerticalRuler) within aScrollView.

public NSRulerView(NSScrollView aScrollView, int 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.

Static Methods

registerUnit

Registers a new unit of measurement with the NSRulerView class, making it available to all instances of NSRulerView.

public static void registerUnit(String unitName, String abbreviation, float conversionFactor, NSArray stepUpCycle, NSArray stepDownCycle)

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 Numbers 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
See Also

Instance Methods

accessoryView

Returns the receiver’s accessory view, if it has one.

public NSView accessoryView()

See Also

addMarker

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

public void addMarker(NSRulerMarker aMarker)

Discussion

Throws an InternalInconsistencyException if the receiver has no client view.

See Also

baselineLocation

Returns the location of the receiver’s baseline, in its own coordinate system.

public float baselineLocation()

Discussion

This is a y position for horizontal rulers and an x position for vertical ones.

See Also

clientView

Returns the receiver’s client view, if it has one.

public NSView clientView()

See Also

drawHashMarksAndLabelsInRect

Draws the receiver’s hash marks and labels in aRect, which is expressed in the receiver’s coordinate system.

public void drawHashMarksAndLabelsInRect(NSRect aRect)

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 registerUnit. Override this method if you want to customize the appearance of the hash marks themselves.

See Also

drawMarkersInRect

Draws the receiver’s markers in aRect, which is expressed in the receiver’s coordinate system.

public void drawMarkersInRect(NSRect aRect)

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.

See Also

invalidateHashMarks

Forces recalculation of the hash mark spacing for the next time the receiver is displayed.

public void invalidateHashMarks()

Discussion

You should never need to invoke this method directly, but might need to override it if you override drawHashMarksAndLabelsInRect.

See Also

isFlipped

Returns true if the NSRulerView’s coordinate system is flipped, false otherwise.

public boolean isFlipped()

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.

markers

Returns the receiver’s NSRulerMarkers.

public NSArray markers()

Discussion

The markers aren’t guaranteed to be sorted in any particular order.

See Also

measurementUnits

Returns the full name of the measurement units in effect for the receiver.

public String measurementUnits()

See Also

moveRulerline

Draws temporary lines in the ruler area.

public void moveRulerline(float oldLoc, float newLoc)

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.

orientation

Returns the orientation of the receiver.

public int orientation()

Discussion

Possible values are described in “Constants.”

See Also

originOffset

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.

public float originOffset()

See Also

removeMarker

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

public void removeMarker(NSRulerMarker aMarker)

See Also

requiredThickness

Returns the thickness needed for proper tiling of the receiver within an NSScrollView.

public float 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.

See Also

reservedThicknessForAccessoryView

Returns the thickness reserved to contain the receiver’s accessory view, its height or width depending on the receiver’s orientation.

public float reservedThicknessForAccessoryView()

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.

reservedThicknessForMarkers

Returns the thickness reserved to contain the images of the receiver’s ruler markers, the height or width depending on the receiver’s orientation.

public float reservedThicknessForMarkers()

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.

See Also

ruleThickness

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.

public float ruleThickness()

See Also

scrollView

Returns the NSScrollView object that contains the receiver.

public NSScrollView scrollView()

See Also

setAccessoryView

Sets the receiver’s accessory view to aView.

public void setAccessoryView(NSView aView)

Discussion

Throws an InternalInconsistencyException if aView is not null and the receiver has no client view.

See Also

setClientView

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

public void setClientView(NSView aView)

Discussion

aView must be either the document view of the NSScrollView that contains the receiver or a subview of the document view.

See Also

setMarkers

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

public void setMarkers(NSArray markers)

Discussion

markers can be null or empty to remove all ruler markers. Throws an InternalInconsistencyException if markers is not null and the receiver has no client view.

See Also

setMeasurementUnits

Sets the measurement units used by the ruler to unitName.

public void setMeasurementUnits(String unitName)

Discussion

unitName must have been registered with the NSRulerView class object prior to invoking this method. See the description of the class method registerUnit for a list of predefined units.

See Also

setOrientation

Sets the orientation of the receiver to orientation.

public void setOrientation(int 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.

See Also

setOriginOffset

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.

public void setOriginOffset(float offset)

Discussion

The default offset is 0.0, meaning that the ruler origin coincides with the bounds origin of the document view.

See Also

setReservedThicknessForAccessoryView

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

public void setReservedThicknessForAccessoryView(float 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.

See Also

setReservedThicknessForMarkers

Sets the room available for ruler markers to thickness.

public void setReservedThicknessForMarkers(float 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.

See Also

setRuleThickness

Sets to thickness the thickness of the area where ruler hash marks and labels are drawn.

public void setRuleThickness(float thickness)

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.

See Also

setScrollView

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

public void setScrollView(NSScrollView scrollView)

Discussion

This method is generally invoked only by the ruler’s scroll view; you should rarely need to invoke it directly.

See Also

trackMarker

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

public boolean trackMarker(NSRulerMarker aMarker, NSEvent theEvent)

Discussion

Returns true if the receiver adds aMarker, false if it doesn’t. This method works by sending trackMouseToAddMarker to aMarker with theEvent and true as arguments.

An application typically invokes this method in one of two cases. In the simpler case, the client view can implement rulerViewHandleMouseDown 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.

See Also

Constants

The following constants are defined to specify a ruler’s orientation and are used by orientation and setOrientation:

Constant

Description

HorizontalRuler

Ruler is oriented horizontally.

VerticalRuler

Ruler is oriented vertically.

Delegate Methods

rulerViewDidAddMarker

Informs the client that aRulerView allowed the user to add aMarker.

public abstract void rulerViewDidAddMarker(NSRulerView aRulerView, NSRulerMarker 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.

See Also

rulerViewDidMoveMarker

Informs the client that aRulerView allowed the user to move aMarker.

public abstract void rulerViewDidMoveMarker(NSRulerView aRulerView, NSRulerMarker 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.

See Also

rulerViewDidRemoveMarker

Informs the client that aRulerView allowed the user to remove aMarker.

public abstract void rulerViewDidRemoveMarker(NSRulerView aRulerView, NSRulerMarker 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.

See Also

rulerViewHandleMouseDown

Informs the client that the user has pressed the mouse button while the cursor is in the ruler area of aRulerView.

public abstract void rulerViewHandleMouseDown(NSRulerView aRulerView, NSEvent theEvent)

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 or adding layout guidelines.

rulerViewShouldAddMarker

Requests permission for aRulerView to add aMarker, an NSRulerMarker being dragged onto the ruler by the user.

public abstract boolean rulerViewShouldAddMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

If the client returns true the ruler view accepts the new marker and begins tracking its movement; if the client returns false the ruler view refuses the new marker.

See Also

rulerViewShouldMoveMarker

Requests permission for aRulerView to move aMarker.

public abstract boolean rulerViewShouldMoveMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

If the client returns true the ruler view allows the user to move the marker; if the client returns false 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).

See Also

rulerViewShouldRemoveMarker

Requests permission for aRulerView to remove aMarker.

public abstract boolean rulerViewShouldRemoveMarker(NSRulerView aRulerView, NSRulerMarker aMarker)

Discussion

If the client returns true the ruler view allows the user to remove the marker; if the client returns false 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).

rulerViewWillAddMarker

Informs the client that aRulerView will add the new NSRulerMarker, aMarker.

public abstract float rulerViewWillAddMarker(NSRulerView aRulerView, NSRulerMarker aMarker, float location)

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.

See Also

rulerViewWillMoveMarker

Informs the client that aRulerView will move aMarker, an NSRulerMarker already on the ruler view.

public abstract float rulerViewWillMoveMarker(NSRulerView aRulerView, NSRulerMarker aMarker, float location)

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.

See Also

rulerViewWillSetClientView

Informs the client view that aRulerView is about to be appropriated by newClient.

public abstract void rulerViewWillSetClientView(NSRulerView aRulerView, NSView newClient)

Discussion

The client view can use this opportunity to clear any cached information related to the ruler.



Next Page > Hide TOC

© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.