A widget that represents an HTML anchor (to link to other documents). More...

#include <Wt/WAnchor>

Inheritance diagram for Wt::WAnchor:

Public Member Functions
	WAnchor (WContainerWidget *parent=0)
	Creates an anchor.
	WAnchor (const WLink &link, WContainerWidget *parent=0)
	Creates an anchor for the given link.
	WAnchor (const WLink &link, const WString &text, WContainerWidget *parent=0)
	Creates an anchor for the given link with a text.
	WAnchor (const WLink &link, WImage image, WContainerWidget parent=0)
	Creates an anchor for the given link with an image.
void	setLink (const WLink &link)
	Sets the link.
const WLink &	link () const
	Returns the link.
void	setRef (const std::string &url)
	Sets the linked URL (deprecated).
void	setRefInternalPath (const std::string &path)
	Sets a link to an internal path (deprecated).
std::string &	ref () const
	Returns the destination URL or internal path (deprecated).
void	setResource (WResource *resource)
	Sets a destination resource (deprecated).
WResource *	resource () const
	Returns the destination resource (deprecated).
void	setText (const WString &text)
	Sets the label text.
const WString &	text () const
	Returns the label text.
void	setWordWrap (bool wordWrap)
	Configures text word wrapping.
void	setTextFormat (TextFormat format)
	Configures the text format.
TextFormat	textFormat () const
	Returns the text format.
bool	wordWrap () const
	Returns whether the widget may break lines.
void	setImage (WImage *image)
	Sets an image.
WImage *	image () const
	Returns the image.
void	setTarget (AnchorTarget target)
	Sets the location where the linked content should be displayed.
AnchorTarget	target () const
	Returns the location where the linked content should be displayed.
virtual bool	canReceiveFocus () const
	Returns whether the widget can receive focus.
virtual int	tabIndex () const
	Returns the tab index.
virtual bool	setFirstFocus ()
	Set focus on the widget's first descendant.
Protected Member Functions
virtual void	propagateSetEnabled (bool enabled)
	Propagates that a widget was enabled or disabled through children.
virtual void	enableAjax ()
	Progresses to an Ajax-enabled widget.

Detailed Description

A widget that represents an HTML anchor (to link to other documents).

Use an anchor to link to another web page, document, internal application path or a resource (which specifies application-dependent content that may be generated by your application on demand). The anchor may contain a label text, an image, or any other widget (as it inherits from WContainerWidget). If you link to a document or external url, and do not want the application to terminate when the user follows the anchor, you must use setTarget(TargetNewWindow). Even for non-HTML documents, this may be important since pending Ajax requests are cancelled if documents are not served within the browser window in certain browsers.

When linking to a resource, the anchor does not assume ownership of resource, so that you may share the same resources for several anchors.

Usage example:

 WAnchor *a;

 // Create an anchor that links to a URL
 a = new WAnchor("http://www.webtoolkit.eu/", "Wt web toolkit", this);

 // Create an anchor that links to an internal path
 a = new WAnchor(WLink(WLink::InternalPath, "/docs/" + myDocName()), "Doc", this);
 //   and listen to the corresponding change in internal path
 WApplication::instance()->internalPathChanged().connect(this, &DocsListWidget::onInternalPathChange);

 // Create an anchor that links to a resource
 WResource *r = new PdfResource(this); // serializes to a PDF file.
 a = new WAnchor(r, "PDF version", this);
 a->setTarget(TargetNewWindow);

WAnchor is an inline widget.

Note:: If you set a text or image using one of the API methods like setText() or setImage() or a constructor, you should not attempt to remove all contents (using clear(), or provide a layout (using setLayout()), as this will result in undefined behaviour: the text or image are simply inserted as widgets into the container.

CSS

The widget corresponds to the HTML <a> tag and does not provide styling. It can be styled using inline or external CSS as appropriate.

Constructor & Destructor Documentation

Wt::WAnchor::WAnchor	(	const WLink &	link,
		WContainerWidget *	parent = `0`
	)

Creates an anchor for the given link.

The link may point to a URL, a dynamic resource, or an internal path.

See also:: setLink()

Wt::WAnchor::WAnchor	(	const WLink &	link,
		const WString &	text,
		WContainerWidget *	parent = `0`
	)

Creates an anchor for the given link with a text.

The link may point to a URL, a dynamic resource, or an internal path.

See also:: setLink(), setText()

Wt::WAnchor::WAnchor	(	const WLink &	link,
		WImage *	image,
		WContainerWidget *	parent = `0`
	)

Creates an anchor for the given link with an image.

Ownership of the image is transferred to the anchor.

See also:: setLink(), setImage()

Member Function Documentation

bool Wt::WAnchor::canReceiveFocus ( ) const [virtual]

Returns whether the widget can receive focus.

See also:: setCanReceiveFocus()

Reimplemented from Wt::WWebWidget.

void Wt::WAnchor::enableAjax ( ) [protected, virtual]

Progresses to an Ajax-enabled widget.

This method is called when the progressive bootstrap method is used, and support for AJAX has been detected. The default behavior will upgrade the widget's event handling to use AJAX instead of full page reloads, and propagate the call to its children.

You may want to reimplement this method if you want to make changes to widget when AJAX is enabled. You should always call the base implementation.

See also:: WApplication::enableAjax()

Reimplemented from Wt::WWebWidget.

WImage* Wt::WAnchor::image ( ) const

Returns the image.

Returns 0 if no image is set.

See also:: setImage()

const WLink& Wt::WAnchor::link ( ) const

Returns the link.

See also:: setLink()

void Wt::WAnchor::propagateSetEnabled ( bool enabled ) [protected, virtual]

Propagates that a widget was enabled or disabled through children.

When enabling or disabling a widget, you usually also want to disable contained children. This method is called by setDisabled() to propagate its state to all children.

You may want to reimplement this method if they wish to render differently when a widget is disabled. The default implementation will propagate the signal to all children.

Reimplemented from Wt::WInteractWidget.

std::string& Wt::WAnchor::ref ( ) const

Returns the destination URL or internal path (deprecated).

When the anchor links to a resource, the current resource URL is returned. When the anchor links to an internal path, the internal path is returned. Otherwise, the linked URL is returned.

Deprecated:: Use link() instead.

WResource * Wt::WAnchor::resource ( ) const

Returns the destination resource (deprecated).

Returns 0 if no resource has been set.

Deprecated:: Use link() instead.

bool Wt::WAnchor::setFirstFocus ( ) [virtual]

Set focus on the widget's first descendant.

Set focus on the widget itself, or on a first descendant which can receive focus.

Returns whether focus could be set.

Reimplemented from Wt::WWebWidget.

void Wt::WAnchor::setImage ( WImage * image )

Sets an image.

If an image was previously set, it is deleted. The image is added using addWidget().

Ownership of the image is transferred to the anchor.

void Wt::WAnchor::setLink ( const WLink & link )

Sets the link.

The link may hold a URL, a resource, or an internal path.

When the link points to a resource, the contents of the link may be generated by your application on demand.

When the link points to an internal path, activating the anchor will change the application's internal path or open a new session with the given path as initial path). This is the easiest way to let the application participate in browser history, and generate URLs that are bookmarkable and search engine friendly.

void Wt::WAnchor::setRef ( const std::string & url )

Sets the linked URL (deprecated).

Deprecated:: Use setLink() instead.

void Wt::WAnchor::setRefInternalPath ( const std::string & path )

Sets a link to an internal path (deprecated).

Note:: the path should be UTF8 encoded (we may fix the API to use WString in the future).

Deprecated:: Use setLink() instead.

void Wt::WAnchor::setResource ( WResource * resource )

Sets a destination resource (deprecated).

The anchor does not assume ownership of the resource.

Deprecated:: Use setLink() instead.

void Wt::WAnchor::setTarget ( AnchorTarget target )

Sets the location where the linked content should be displayed.

By default, the linked content is displayed in the application (Wt::TargetSelf). When the destination is an HTML document, the application is replaced with the new document. When the link is to a document that cannot be displayed in the browser, it is offered for download or opened using an external program, depending on browser settings.

By setting target to Wt::TargetNewWindow, the destination is displayed in a new browser window or tab.

See also:: target()

void Wt::WAnchor::setText ( const WString & text )

Sets the label text.

If no text was previously set, a new WText widget is added using addWidget().

void Wt::WAnchor::setTextFormat ( TextFormat format )

Configures the text format.

The default text format is XHTMLText.

See also:: WText::setTextFormat()

void Wt::WAnchor::setWordWrap ( bool wordWrap )

Configures text word wrapping.

When wordWrap is true, the text set with setText() may be broken up over multiple lines. When wordWrap is false, the text will displayed on a single line, unless the text contains <br /> tags or other block-level tags.

The default value is true.

See also:: wordWrap()

int Wt::WAnchor::tabIndex ( ) const [virtual]

Returns the tab index.

See also:: setTabIndex()

Reimplemented from Wt::WWebWidget.

AnchorTarget Wt::WAnchor::target ( ) const

Returns the location where the linked content should be displayed.

See also:: setTarget()

const WString & Wt::WAnchor::text ( ) const

Returns the label text.

Returns an empty string if no label was set.

See also:: setText()

TextFormat Wt::WAnchor::textFormat ( ) const

Returns the text format.

See also:: setTextFormat()

bool Wt::WAnchor::wordWrap ( ) const

Returns whether the widget may break lines.

See also:: setWordWrap(bool)

Public Member Functions

Protected Member Functions

Detailed Description

CSS

Constructor & Destructor Documentation

Member Function Documentation