DSClickableURLTextField Class Reference





Author


Overview
Tasks
Instance Methods
Delegate Methods
Version History

Overview


DSClickableURLTextField is a subclass of NSTextField that does one thing: allow links to be clicked on and opened.

To use this class, all you need to do is set the text field's attributed string value, with some portion of it being a link, and the text field will do the rest. You'll get the “pointy hand” cursor over the link, and clicking on it will open that link.

Note that the class only works if it is non-editable and non-selectable. This is setup by default, but I wanted to mention it so nobody wastes time trying to figure out why the text field is acting the way it is.

Tasks



Working with cursor rects

— resetCursorRects

Working With Links

— canCopyURLs
— setCanCopyURLs:
— copyURL:
— urlAtMouse:
— textField:openURL: (delegate method)

Setting the text field's contents

— setAttributedStringValue:
— setStringValue:

Instance Methods


canCopyURLs

Returns if the text field allows copying of URLs to the clipboard.

— (BOOL)canCopyURLs

Return Value

If the text field allows copying of URLs, returns YES, otherwise returns NO.

Discussion

If the text field allows copying of URLs, it will pop up a menu allowing the user to copy the URL to the clipboard.

By default, this is set to NO.

See Also

— setCanCopyURLs:

copyURL:

Action used to copy an URL to the clipboard.

— (void)copyURL:(id)sender

Parameters

sender

The menu item the user selected in the pop up menu.

Discussion

This is the action method called by the “Copy URL” menu item in the pop up menu shown to the user. You should never call this method directly — the URL is set as the menu item's represented object and is referenced that way.

See Also

— canCopyURLs
— setCanCopyURLs

resetCursorRects

Resets the cursor rects used to show the cursor over links.

— (void)resetCursorRects

Discussion

Resets the cursor rects used to show the “pointy hand” cursor over links. Note that unless the text field is empty or you're running on 10.2 or earlier, this method doesn't call to super.

This method is called automatically; there should be no need to call it directly.

setAttributedStringValue:

Sets the text field's attributed string value.

— (void)setAttributedStringValue:(NSAttributedString *)aStr

Parameters

aStr

The attributed string you wish the text field to display.

Discussion

This method sets the attributed string value and resets the text field's cursor rects.

See Also

— setStringValue:

setCanCopyURLs:

Sets if the text field will allow copying of URLs to the clipboard.

— (void)setCanCopyURLS:(BOOL)aFlag

Parameters

aFlag

If YES, the text field will allow copying URLs to the clipboard.

See Also

— canCopyURLs

setStringValue:

Sets the text field's string value.

— (void)setStringValue:(NSString *)aStr

Parameters

aStr

The string you wish the text field to display.

Discussion

This method converts the string to an attributed string, then calls —setAttributedStringValue: with it.

Note that if you set a simple string value, the text field will have no links.

See Also

— setAttributedStringValue:

urlAtMouse:

Returns the link at the given mouse coordinates.

— (NSURL *)urlAtMouse:(NSEvent *)mouseEvent

Parameters

mouseEvent

The mouse event that generated the event.

Return Value

Returns the link under the mouse position, or nil if there is no link at that position.

Discussion

This method must only be called by -mouseDown: or -mouseUp:, never directly.

Delegate Methods


textField:openURL:

Lets the text field's delegate handle an URL.

— (BOOL)textField:(NSTextField *)textField openURL:(NSURL *)anURL

Parameters

textField

The text field being clicked on.

anURL

The link being clicked on.

Return Value

If the delegate handles the URL, return YES otherwise return NO.

Discussion

You can use this method to handle custom URL schemes or open an URL in a different manner than the default (passing it to NSWorkspace to open the URL).

Version History



0.3
May 25 2007
Changes by Jens Miltner:
  • Fixed a problem with the text storage and the text field's attributed string value having different lengths, causing range exceptions.
  • Added a delegate method allowing custom handling of URLs.
  • Tracks initially clicked URL at -mouseDown: to avoid situations where dragging would end up in a different URL at -mouseUp:, opening that URL. This includes situations where the user clicks on an empty area of the text field, drags the mouse, and ends up on top of a link, which would then erroneously open that link.
  • Fixed to allow string links to work as well as URL links.
Changes by Darkshadow:
  • Overrode -initWithCoder:, -initWithFrame:, and -awakeFromNib to explicitly set the text field to non-editable and non-selectable. Now you don't need to remember to set this up, and the class will work correctly regardless.
  • Added in the ability for the user to copy URLs to the clipboard. Note that this is off by default.
  • Some code clean up.
0.2
August 30, 2006
  • Fixed a bug where cursor rects would be enabled even if the text field wasn't visible. i.e. it's in a scroll view, but the text field isn't scrolled to where it's visible.
  • Fixed an issue where -mouseUp: wouldn't be called and so clicking on the URL would have no effect when the text field is a subview of a split view (and possibly other views). I did this by not calling super in -mouseDown:. Since the text field is non-editable and non-selectable, I don't believe this will cause any problems.
  • Fixed the fact that it was using the text field's bounds rather than the cell's bounds to calculate rects.
0.1
August 25, 2006 - Initial release.