---

NSCellForTextAttachment

Overview

The NSCellForTextAttachment interface declares the interface for objects that draw text attachment icons and handle mouse events on their icons. With the exceptions of cellBaselineOffset, setAttachment, and attachment, all of these methods are implemented by the NSCell class and described in that class specification.

See the NSAttributedString and NSTextView class specifications for general information on text attachments.

Tasks

Drawing

• drawWithFrameInView
• highlightWithFrameInView

Cell Size and Position

• cellSize
• cellBaselineOffset
• cellFrame

Event Handling

• wantsToTrackMouse
• wantsToTrackMouseForEvent
• trackMouse

Setting the Attachment

• setAttachment
• attachment

Instance Methods

attachment

Returns the text attachment object that owns the receiver.

public abstract NSTextAttachment attachment()

See Also

• setAttachment

cellBaselineOffset

Returns the position where the attachment cell’s image should be drawn in text, relative to the current point established in the glyph layout.

public abstract NSPoint cellBaselineOffset()

Discussion

The image should be drawn so its lower-left corner lies on this point.

See Also

• icon (NSFileWrapper)

cellFrame

Returns the frame of the cell as it would be drawn as the character at the given glyph position, and character index, charIndex, in textContainer.

public abstract NSRect cellFrame(NSTextContainer textContainer, NSRect lineFrag, NSPoint position, int charIndex)

Discussion

The proposed line fragment is specified by lineFrag.

cellSize

Returns the size of the attachment’s icon.

public abstract NSSize cellSize()

See Also

• icon (NSFileWrapper)
• fileWrapper (NSTextAttachment)

drawWithFrameInView

Draws the receiver’s image within cellFrame in aView, which should be the view currently focused.

public abstract void drawWithFrameInView(NSRect cellFrame, NSView aView)

See Also

• drawWithFrameInView (NSCell)
• lockFocus (NSView)

Draws the receiver’s image within cellFrame in aView, which is the view currently focused.

public abstract void drawWithFrameInView(NSRect cellFrame, NSView aView, int charIndex)

Discussion

charIndex is the index of the attachment character within the text.

Draws the receiver’s image within cellFrame in aView, which is the view currently focused.

public abstract void drawWithFrameInView(NSRect cellFrame, NSView aView, int charIndex, NSLayoutManager layoutManager)

Discussion

charIndex is the index of the attachment character within the text. layoutManager is the layout manager for the text.

highlightWithFrameInView

Draws the receiver’s image—with highlighting if flag is true—within cellFrame in aView, which should be the focus view.

public abstract void highlightWithFrameInView(boolean flag, NSRect cellFrame, NSView aView)

See Also

• highlightWithFrameInView (NSCell)
• lockFocus (NSView)

setAttachment

Sets the text attachment object that owns the receiver to anAttachment.

public abstract void setAttachment(NSTextAttachment anAttachment)

See Also

• attachment
• setAttachmentCell (NSTextAttachment)

trackMouse

Handles a mouse-down event on the receiver’s image.

public abstract boolean trackMouse(NSEvent theEvent, NSRect cellFrame, NSView aTextView, int charIndex, boolean flag)

Discussion

theEvent is the mouse-down event. cellFrame is the region of aTextView in which further mouse events should be tracked. charIndex is the position in the text at which this attachment appears. aTextView is the view that received the event. It’s assumed to be an NSTextView and should be the focus view. If flag is true, the receiver tracks the mouse until a mouse-up event occurs; if flag is false, it stops tracking when a mouse-dragged event occurs outside of cellFrame. Returns true if the receiver successfully finished tracking the mouse (typically through a mouse-up event), false otherwise (such as when the cursor is dragged outside cellFrame).

NSTextAttachmentCell’s implementation of this method calls upon the delegate of aTextView to handle the event. If theEvent is a mouse-up event for a double click, the text attachment cell sends the delegate a textViewDoubleClickedCell message and returns true. Otherwise, depending on whether the user clicks or drags the cell, it sends the delegate a textViewClickedCell or a textViewDraggedCell message and returns true. NSTextAttachmentCell’s implementation returns false only if flag is false and the cursor is dragged outside of cellFrame. The delegate methods are invoked only if the delegate responds.

See Also

• wantsToTrackMouse
• trackMouse (NSCell)
• lockFocus (NSView)

Handles a mouse-down event on the receiver’s image.

public abstract boolean trackMouse(NSEvent theEvent, NSRect cellFrame, NSView aTextView, boolean flag)

Discussion

theEvent is the mouse-down event. cellFrame is the region of aTextView in which further mouse events should be tracked. aTextView is the view that received the event. It’s assumed to be an NSTextView and should be the focus view. If flag is true, the receiver tracks the mouse until a mouse-up event occurs; if flag is false, it stops tracking when a mouse-dragged event occurs outside of cellFrame. Returns true if the receiver successfully finished tracking the mouse (typically through a mouse-up event), false otherwise (such as when the cursor is dragged outside cellFrame).

NSTextAttachmentCell’s implementation of this method calls upon the delegate of aTextView to handle the event. If theEvent is a mouse-up event for a double click, the text attachment cell sends the delegate a textViewDoubleClickedCell message and returns true. Otherwise, depending on whether the user clicks or drags the cell, it sends the delegate a textViewClickedCell or a textViewDraggedCell message and returns true. NSTextAttachmentCell’s implementation returns false only if flag is false and the cursor is dragged outside of cellFrame. The delegate methods are invoked only if the delegate responds.

See Also

• wantsToTrackMouse
• trackMouse (NSCell)
• lockFocus (NSView)

wantsToTrackMouse

Returns true if the receiver will handle a mouse event occurring over its image (to support dragging, for example), false otherwise.

public abstract boolean wantsToTrackMouse()

Discussion

NSTextAttachmentCell’s implementation of this method returns true. The NSView containing the cell should invoke this method before sending a trackMouse message.

For an attachment in an attributed string, if the attachment cell returns false its attachment character should be selected rather than the cell being asked to track the mouse. This results in the attachment icon behaving as any regular glyph in text.

wantsToTrackMouseForEvent

Allows an attachment to specify what events it would want to track the mouse for.

public abstract boolean wantsToTrackMouseForEvent(NSEvent theEvent, NSRect cellFrame, NSView controlView, int charIndex)

Discussion

theEvent is the event in question that occurred in cellFrame inside controlView. charIndex is the index of the attachment character within the text. If wantsToTrackMouse returns true, this method allows the attachment to decide whether it wishes to do so for particular events.

---