PATH  Documentation > Mac OS X > Application Kit Reference: Java

Table of Contents

NSRulerMarker


Inherits from:
NSObject
Package:
com.apple.yellow.application


Class Description


An NSRulerMarker displays a symbol on an NSRulerView, indicating a location for whatever graphic element it represents in the client of the NSRulerView (for example, a margin or tab setting, or the edges of a graphic on the page). A ruler marker comprises three primary attributes: the image it displays on the NSRulerView, the location of that image, and the object it represents. The setImage, setMarkerLocation and setRepresentedObject methods set each of these attributes, respectively. In addition, a ruler marker records an offset for the image, allowing it to be placed relative to the marker location much in the way a cursor's hot spot relates a cursor image to the mouse location; the setImageOrigin method establishes this offset.

Most of these attributes are set upon initialization by the constructor. New ruler markers don't have represented objects; the client typically establishes the represented object in its rulerViewDidAddMarker method. A new NSRulerMarker can be moved around in its NSRulerView, but not removed from it. The setMovable and setRemovable methods alter these default settings.

Represented objects allow the NSRulerView's client to distinguish among different attributes of the selection. In the NSRulerView client methods, the client can retrieve the marker's represented object to determine what attribute to alter. Generic attributes can be represented by string or other value objects, such as the edge names "Left", "Right", "Top", and "Bottom". Attributes already implemented as objects can be represented by those objects. For example, the text system records tab stops as NSTextTab objects, which include the tab location and its alignment. When an NSTextView is the client view of a ruler, it simply makes the NSTextTabs the represented objects of the ruler markers.




Method Types


Constructors
NSRulerMarker
Getting the ruler view
ruler
Setting the image
setImage
image
setImageOrigin
imageOrigin
imageRectInRuler
thicknessRequiredInRuler
Setting movability
setMovable
isMovable
setRemovable
isRemovable
Setting the location
setMarkerLocation
markerLocation
Setting the represented object
setRepresentedObject
representedObject
Drawing and event handling
drawRect
isDragging
trackMouseToAddMarker


Constructors



NSRulerMarker

public NSRulerMarker()

Description forthcoming.

public NSRulerMarker( NSRulerView aRulerView, float location, NSImage anImage, NSPoint imageOrigin)

Creates an NSRulerMarker object, associating it with (but not adding it to) aRulerView and assigning the attributes provided. location is the x or y position of the marker in the client view's coordinate system, depending on whether the NSRulerView is horizontal or vertical. anImage is the image displayed at the marker location, and imageOrigin is the point within the image positioned at the marker location, expressed in pixels relative to the lower-left corner of the image. This method throws an exception if aRulerView or anImage is null.

The image used to draw the marker must be appropriate for the orientation of the ruler. Markers may need to look different on a horizontal ruler than on a vertical ruler, and the NSRulerView neither scales nor rotates the images.

To add the new ruler marker to aRulerView, use either of NSRulerView's addMarker or trackMarker methods. addMarker immediately puts the marker on the ruler, while trackMarker allows the client view to intercede in the addition and placement of the marker.

A new ruler marker can be moved on its NSRulerView, but not removed. Use setMovable and setRemovable to change these attributes. The new ruler marker also has no represented object; use setRepresentedObject to provide or change it.

See Also: setMarkerLocation, setImage, setImageOrigin




Instance Methods



drawRect

public void drawRect(NSRect aRect)

Draws the part of the receiver's image that intersects aRect in the NSRulerView's coordinate system.

See Also: imageRectInRuler



image

public NSImage image()

Returns the NSImage object displayed by the receiver.

See Also: setImage



imageOrigin

public NSPoint imageOrigin()

Returns the point in the receiver's image positioned at the receiver's location on the NSRulerView, expressed in the image's coordinate system.

For a horizontal ruler, the x coordinate of the image origin is aligned with the location of the marker, and the y coordinate lies on the baseline of the ruler. For vertical rulers, the y coordinate of the image origin is the location, and the x coordinate lies on the baseline.

See Also: setImageOrigin, imageRectInRuler



imageRectInRuler

public NSRect imageRectInRuler()

Returns the rectangle occupied by the marker's image, in the NSRulerView's coordinate system, accounting for whether the NSRulerView's coordinate system is flipped.

See Also: drawRect, thicknessRequiredInRuler



isDragging

public boolean isDragging()

Returns true if the receiver is being dragged, false otherwise.

See Also: trackMouseToAddMarker



isMovable

public boolean isMovable()

Returns true if the user can move the receiver on its NSRulerView, false otherwise. NSRulerMarkers are by default movable.

See Also: setMovable, isRemovable



isRemovable

public boolean isRemovable()

Returns true if the user can remove the receiver from its NSRulerView, false otherwise. NSRulerMarkers cannot by default be removed from their NSRulerViews.

See Also: setRemovable, isMovable



markerLocation

public float markerLocation()

Returns the location of the receiver in the coordinate system of the NSRulerView's client view. This is an x position for a horizontal ruler, a y position for a vertical ruler.

See Also: setMarkerLocation



representedObject

public Object representedObject()

Returns the object the receiver represents, as explained in the class description.

See Also: setRepresentedObject



ruler

public NSRulerView ruler()

Returns the NSRulerView the receiver belongs to.

See Also: addMarker (NSRulerView)



setImage

public void setImage(NSImage anImage)

Sets the receiver's image to anImage.

See Also: image, setImageOrigin



setImageOrigin

public void setImageOrigin(NSPoint aPoint)

Sets the point in the receiver's image positioned at the receiver's location on the NSRulerView to aPoint. This point is always expressed in pixels relative to the lower-left corner of the image.

For a horizontal ruler, the x coordinate of the image origin is aligned with the location of the marker, and the y coordinate lies on the baseline of the ruler. For vertical rulers, the y coordinate of the image origin is the location, and the x coordinate lies on the baseline.

See Also: imageOrigin, setImage, setMarkerLocation



setMarkerLocation

public void setMarkerLocation(float location)

Sets the location of the receiver in the coordinate system of the NSRulerView's client view to location. This is an x position for a horizontal ruler, a y position for a vertical ruler.

See Also: markerLocation, setImageOrigin



setMovable

public void setMovable(boolean flag)

Controls whether the user can move the receiver in its NSRulerView. If flag is true, the user can drag the marker image in the ruler. If flag is false, the receiver is immovable. NSRulerMarkers are by default movable.

See Also: isMovable, setRemovable



setRemovable

public void setRemovable(boolean flag)

Controls whether the user can remove the receiver from its NSRulerView. If flag is true, the user can drag the marker image off of the ruler. If flag is false, the receiver can't be removed. NSRulerMarkers are by default not removable.

See Also: isRemovable, setMovable



setRepresentedObject

public void setRepresentedObject(Object anObject)

Sets the object the receiver represents to anObject. See the class description for more information on the represented object.

See Also: representedObject



thicknessRequiredInRuler

public float thicknessRequiredInRuler()

Returns the amount of the receiver's image that's displayed above or to the left of the NSRulerView's baseline, the height for a horizontal ruler or width for a vertical ruler.

See Also: imageOrigin



trackMouseToAddMarker

public boolean trackMouseToAddMarker( NSEvent theEvent, boolean flag)

Handles user manipulation of the receiver in its NSRulerView. NSRulerView invokes this method automatically to add a new marker or to move or remove an existing marker. You should never need to invoke it directly.

If flag is true, the receiver is a new marker being added to its NSRulerView. Before the receiver actually adds itself to the NSRulerView, it queries the NSRulerView's client view using rulerViewShouldAddMarker. If the client view responds to this method and returns false, this method immediately returns false and the new marker isn't added.

If flag is false, this method attempts to move or remove an existing marker, once again based on responses from the NSRulerView's client view. If the receiver is neither movable nor removable, this method immediately returns false. Further, if the NSRulerView's client responds to rulerViewShouldMoveMarker and returns false, this method returns false, indicating the receiver can't be moved.

If the receiver is being added or moved, this method queries the client view using rulerViewWillAddMarker or rulerViewWillMoveMarker, respectively. If the client responds to the method, the return value is used as the receiver's location. These methods are invoked repeatedly as the receiver is dragged within the NSRulerView.

If the receiver is an existing marker being removed (dragged off the ruler), this method queries the client view using rulerViewShouldRemoveMarker. If the client responds to this method and returns false, the marker is pinned to the NSRulerView's baseline (following the mouse on the baseline if it's movable).

When the user releases the mouse, this method informs the client view of the marker's new status using rulerViewDidAddMarker, rulerViewDidMoveMarker, or rulerViewDidRemoveMarker as appropriate. The client view can use this notification to set the marker's represented object, modify its state and redisplay (for example, adjusting text layout around a new tab stop), or take whatever other action it might need. If flag is true and the user dragged the new marker away from the ruler, the marker isn't added, no message is sent, and this method returns false.

See the NSRulerView class description for more information on these client methods.

See Also: isMovable, isRemovable




Table of Contents