Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSRulerMarker
| Inherits from | |
| Implements | |
| Package | com.apple.cocoa.application |
| Companion guide |
Overview
An NSRulerMarker displays a symbol on an NSRulerView, indicating a location for whatever graphics 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).
Tasks
Constructors
Getting the Ruler View
Setting the Image
Setting Movability
Setting the Location
Setting the Represented Object
Drawing and Event Handling
Constructors
NSRulerMarker
Creates an empty NSRulerMarker.
public NSRulerMarker()
Creates an NSRulerMarker object, associating it with (but not adding it to) aRulerView and assigning the attributes provided.
public NSRulerMarker(NSRulerView aRulerView, float location, NSImage anImage, NSPoint imageOrigin)
Discussion
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
Instance Methods
drawRect
Draws the part of the receiver’s image that intersects aRect in the NSRulerView’s coordinate system.
public void drawRect(NSRect aRect)
See Also
image
Returns the NSImage object displayed by the receiver.
public NSImage image()
See Also
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.
public NSPoint imageOrigin()
Discussion
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
imageRectInRuler
Returns the rectangle occupied by the receiver’s image, in the NSRulerView’s coordinate system, accounting for whether the NSRulerView’s coordinate system is flipped.
public NSRect imageRectInRuler()
See Also
isDragging
Returns true if the receiver is being dragged, false otherwise.
public boolean isDragging()
See Also
isMovable
Returns true if the user can move the receiver on its NSRulerView, false otherwise.
public boolean isMovable()
Discussion
NSRulerMarkers are by default movable.
See Also
isRemovable
Returns true if the user can remove the receiver from its NSRulerView, false otherwise.
public boolean isRemovable()
Discussion
NSRulerMarkers cannot by default be removed from their NSRulerViews.
See Also
markerLocation
Returns the location of the receiver in the coordinate system of the NSRulerView’s client view.
public float markerLocation()
Discussion
This is an x position for a horizontal ruler, a y position for a vertical ruler.
See Also
representedObject
Returns the object the receiver represents, as explained in the class description.
public Object representedObject()
See Also
ruler
Returns the NSRulerView the receiver belongs to.
public NSRulerView ruler()
See Also
-
addMarker(NSRulerView)
setImage
Sets the receiver’s image to anImage.
public void setImage(NSImage anImage)
See Also
setImageOrigin
Sets the point in the receiver’s image positioned at the receiver’s location on the NSRulerView to aPoint.
public void setImageOrigin(NSPoint aPoint)
Discussion
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
setMarkerLocation
Sets the location of the receiver in the coordinate system of the NSRulerView’s client view to location.
public void setMarkerLocation(float location)
Discussion
This location is an x position for a horizontal ruler, a y position for a vertical ruler.
See Also
setMovable
Controls whether the user can move the receiver in its NSRulerView.
public void setMovable(boolean flag)
Discussion
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
setRemovable
Controls whether the user can remove the receiver from its NSRulerView.
public void setRemovable(boolean flag)
Discussion
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
setRepresentedObject
Sets the object the receiver represents to anObject.
public void setRepresentedObject(Object anObject)
Discussion
See the class description for more information on the represented object.
See Also
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.
public float thicknessRequiredInRuler()
See Also
trackMouseToAddMarker
Handles user manipulation of the receiver in its NSRulerView specified by theEvent.
public boolean trackMouseToAddMarker(NSEvent theEvent, boolean flag)
Discussion
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 cursor on the baseline if it’s movable).
When the user releases the mouse button, 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
© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)