Public Member Functions | Protected Member Functions

Wt::WAnchor Class Reference

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

#include <Wt/WAnchor>

Inheritance diagram for Wt::WAnchor:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 WAnchor (WContainerWidget *parent=0)
 Creates an anchor.
 WAnchor (const std::string &url, WContainerWidget *parent=0)
 Creates an anchor referring to a URL.
 WAnchor (WResource *resource, WContainerWidget *parent=0)
 Creates an anchor referrring a resource.
 WAnchor (const std::string &url, const WString &text, WContainerWidget *parent=0)
 Creates an anchor referring to a URL, using a text message.
 WAnchor (WResource *resource, const WString &text, WContainerWidget *parent=0)
 Creates an anchor referring to a resource, using a text message.
 WAnchor (const std::string &ref, WImage *image, WContainerWidget *parent=0)
 Creates an anchor referring to a URL, using an image.
 WAnchor (WResource *resource, WImage *image, WContainerWidget *parent=0)
 Creates an anchor referring to a resource, using an image.
void setRef (const std::string &url)
 Sets the destination URL.
void setRefInternalPath (const std::string &path)
 Sets the destination URL as an internal path.
const std::string & ref () const
 Returns the destination URL.
void setResource (WResource *resource)
 Sets a destination resource.
WResourceresource () const
 Returns the destination resource.
void setText (const WString &text)
 Sets the label text.
const WStringtext () const
 Returns the label text.
void setWordWrap (bool wordWrap)
 Configures text word wrapping.
bool wordWrap () const
 Returns whether the widget may break lines.
void setImage (WImage *image)
 Sets an image.
WImageimage () const
 Returns the image.
void setTarget (AnchorTarget target)
 Sets the location where the referred content should be displayed.
AnchorTarget target () const
 Returns the location where the referred content should be displayed.

Protected Member Functions

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. The anchor may contain a label text, an image, or any other widget (as it inherits from WContainerWidget). If you 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.

Usage example:

 WAnchor *a;

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

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

 // Create an anchor that references 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 ( WResource resource,
WContainerWidget parent = 0 
)

Creates an anchor referrring a resource.

The resource specifies application-dependent content that may be generated by your application on demand.

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

See also:
WResource
Wt::WAnchor::WAnchor ( WResource resource,
const WString text,
WContainerWidget parent = 0 
)

Creates an anchor referring to a resource, using a text message.

The resource specifies application-dependent content that may be generated by your application on demand.

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

Wt::WAnchor::WAnchor ( const std::string &  ref,
WImage image,
WContainerWidget parent = 0 
)

Creates an anchor referring to a URL, using an image.

Ownership of the image is transferred to the anchor.

Wt::WAnchor::WAnchor ( WResource resource,
WImage image,
WContainerWidget parent = 0 
)

Creates an anchor referring to a resource, using an image.

The resource specifies application-dependent content that may be generated by your application on demand.

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

Ownership of the image is transferred to the anchor.


Member Function Documentation

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 [inline]

Returns the image.

Returns 0 if no image is set.

See also:
setImage()
const std::string& Wt::WAnchor::ref (  ) const [inline]

Returns the destination URL.

When the anchor refers to a resource, the current resource URL is returned. When the anchor refers to an internal path, the internal path is returned. Otherwise, the URL is returned that was set using setRef().

See also:
setRef(), WResource::url()
WResource* Wt::WAnchor::resource (  ) const [inline]

Returns the destination resource.

Returns 0 if no resource has been set.

See also:
setResource()
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::setRef ( const std::string &  url )

Sets the destination URL.

This method should not be used when the anchor has been pointed to a dynamically generated resource using setResource().

See also:
setResource(), setRefInternalPath()
void Wt::WAnchor::setRefInternalPath ( const std::string &  path )

Sets the destination URL as an internal path.

Sets the anchor to point to the internal path path. When the anchor is activated, the internal path is set to path, and the WApplication::internalPathChanged() signal is emitted.

This is the easiest way to let the application participate in browser history, and generate URLs that are bookmarkable and search engine friendly.

Internally, this method sets the destination URL using:

 setRef(WApplication::instance()->bookmarkUrl(path)) 

The clicked() signal is connected to a slot that changes the internal path by calling

 WApplication::instance()->setInternalPath(ref(), true);
See also:
setRef(), setResource()
WApplication::bookmarkUrl(), WApplication::setInternalPath()
void Wt::WAnchor::setResource ( WResource resource )

Sets a destination resource.

A resource specifies application-dependent content, which may be generated by your application on demand.

This sets the resource as the destination of the anchor, and is an alternative to setRef(). The resource may be cleared by passing resource = 0.

The anchor does not assume ownership of the resource.

See also:
setRef()
void Wt::WAnchor::setTarget ( AnchorTarget  target )

Sets the location where the referred content should be displayed.

By default, the referred 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 reference is 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::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()
AnchorTarget Wt::WAnchor::target (  ) const [inline]

Returns the location where the referred 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()
bool Wt::WAnchor::wordWrap (  ) const

Returns whether the widget may break lines.

See also:
setWordWrap(bool)

Generated on Sat Dec 4 2010 06:32:34 for Wt by doxygen 1.7.2