URLView 2.11
|
URLView 2.11Derived from: public BStringView
Declared in: URLView.h
This class provides an underlined and clickable BStringView that will launch the web browser, e-mail program, or FTP client when clicked on. Other features include hover-highlighting, right-click menus, and drag-and-drop support for TextViews and bookmark/person files. See the example application to see various types of links in action.
You are free to use URLView in your own programs (both open-source and closed-source) free of charge, but a mention in your read me file or your program's about box would be appreciated. See http://www.tallhill.com for current contact information.
URLView is provided as-is, with no warranties of any kind. If you use it, you are on your own.
Note: tallhill.com is currently in transition from old ownership to new, so please forgive any stale links for the time being.
Notable features new in version 2.0:
- Supports HTTP (including "file://"), e-mail, and FTP links. Each will open in the application designated to handle those links. When a URLView link is clicked on, it does a query of the operating system for the correct program to use, so any changes made to the user's "preferred application" choice will be instantly reflected in URLView.
- Supports drag-and-drop, although it can be disabled if desired. If a link is dragged into a standard TextView, it will copy the URL or e-mail address there. If a link is dragged to Tracker, it will create either a bookmark (for web and FTP links) or a person file (for e-mail links). Furthermore, the developer can specify additional attributes to be added to the new file. So a simple e-mail link can now be a full business card.
- Supports hovering, where the link will be highlighted when the mouse cursor is over it. Like the other features, this can be turned off if desired.
- Supports right-click popup menus, from which the user can choose to open the link or copy the URL/e-mail address to the system clipboard.
Changes since version 2.0:
- 2.11: Added "this->url = null" to the constructor to ensure that SetURL() wouldn't try to delete a bad pointer.
- 2.1: A slew of relatively minor changes:
- Improved drawing, so a URLView item will draw at exactly the same height as a BStringView with the same frame. Also, the underlining of the text could be a pixel or two off in previous versions; no more. Thanks to YNOP for pointing this out.
- Added a SetURL() function (to set the text, you can use SetText(), as with a normal BStringView). Thanks to YNOP for the suggestion.
- Added a SetEnabled() function to disable the link. Also added a corresponding IsEnabled() function. Thanks to YNOP for the suggestion. Any URLViews with URLs that are not recognized will be disabled by default.
- Changed the way e-mail links are handled a bit. You can still pass "mailto:email@server.com" to specify the link as an e-mail link, but now anything with an @ sign in it and no other protocol will be treated as an e-mail address. In other words, bkakes@tallhill.com is now treated as an e-mail address, but it is still possible to define http://username:password@www.mysite.com if desired. This makes defining e-mail links easier and more intuitive.
- Added a SetDisabledColor() function to set the link's color when disabled.
- Added SetColor(uchar red, uchar green, uchar blue, uchar alpha) for all SetColor() functions for convenience and to behave more like a standard BView.
- Switched to using bounding boxes to determine if the cursor is over the URL text, which provides more accuracy (previous versions could occasionally be a pixel or two off).
- Made all public functions virtual.
- 2.03: Made URLView draw according to BStringView's SetAlignment() function. Earlier, the view was always drawn left-justified. Thanks to Thomas for pointing out this bug.
- 2.02: Fixed a small bug where, if hovering was disabled, the mouse cursor would retain the "over link" look when the cursor was no longer over the link. Thanks to Daniel Cachapa for finding this bug.
- 2.01: Changed link highlighting to only be active when the view's window is the frontmost window.
| URLView() |
URLView(BRect frame, const char *name, const char *label, const char *url,
uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
uint32 flags = B_WILL_DRAW)Initializes the URLView by assigning it a label string and the system plain font (be_plain_font) colored blue with a one-pixel underline. The URL linked to is specified by url. The frame, name, resizingMode, and flags arguments are passed unchanged to the BView constructor.
The frame rectangle needs to be large enough to display the entire link label in the current font. The link is drawn at the bottom of the frame rectangle and, by default, is aligned to the left side. Colors and certain features can be changed and toggled through the various methods.
The constructor assumes some default values which may be changed using the Set() methods. The default link color is blue, turning red when clicked. When the mouse cursor is over the link, the link turns a darker blue (not only can this color be changed, but the behavior can be toggled). Drag-and-drop is enabled, and an icon size of B_MINI_ICON is used. Finally, the underline thickness is set to one pixel.
If you want a web link, specify the URL starting with "http://". For a web link to a file on the hard drive, start the URL with "file://". For an e-mail link, you can start it with "mailto:", but that is no longer required (any URL looking like "jlq@be.com" will be treated as an e-mail link). For an FTP link, begin the URL with "ftp://"
|
| ~URLView() |
virtual ~URLView() Frees the label and URL strings and deletes any attribute key pairs defined using AddAttribute().
|
| AddAttribute() |
virtual void AddAttribute(const char *name, const char *value ) Specifies an attribute to be added to the new file created when the link is drag-and-dropped to Tracker (assuming SetDraggable() was not used to turn off drag-and-drop ability). Web links create bookmarks when dragged to Tracker, with the "Title" and "URL" attributes automatically filled in by URLView. If you wish to add a value for "Keyword" or any other attribute, this function may be used.
When the user drags an e-mail address to Tracker, a new person file is created. Only the "Name" and "E-mail" attributes are automatically set by URLView. Using this function, you can fill in the standard "Name", "Company", "Address", etc. person attributes and any others you wish to create.
The attributes set by this function are written after the default URLView attributes, so if you wish to set, for example, the person's "Name" attribute to something besides the label of the link, you can use this function.
Note: The strings are copied, so it is safe to delete your copies, if desired.
|
| IsEnabled() |
virtual bool IsEnabled() Returns whether or not the link is currently enabled. You can enable/disable the link by calling SetEnabled().
|
| SetColor() |
virtual void SetColor(rgb_color color) virtual void SetColor(uchar red, uchar green, uchar blue, uchar alpha = 255 ) Sets the color in which to draw the link when it is not being clicked on or hovered over with the mouse cursor.
Note: It is not sufficient to call SetHighColor() on the URLView. SetColor() must be used.
|
| SetClickColor() |
virtual void SetClickColor(rgb_color color virtual void SetClickColor(uchar red, uchar green, uchar blue, uchar alpha = 255 ) Sets the color in which to draw the link when it is being clicked on.
|
| SetDisabledColor() |
virtual void SetDisabledColor(rgb_color color virtual void SetDisabledColor(uchar red, uchar green, uchar blue, uchar alpha = 255 ) Sets the color in which to draw the link when it is disabled. Use SetEnabled() to disable it.
|
| SetDraggable() |
virtual void SetDraggable(bool draggable) Toggles whether or not the link will support drag-and-drop. If it is not draggable, it will behave just like a standard button.
|
| SetEnabled() |
virtual void SetEnabled(bool enabled ) Sets whether or not the link is enabled. If it is disabled, it will look and behave just like a normal BStringView (i.e. the underline will not be drawn and it will not highlight or respond to mouse clicks). It will be drawn in gray by default, but you can override this by using SetDisabledColor().
|
| SetHoverColor() |