WAnchor.h

// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2008 Emweb bv, Herent, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WANCHOR_H_
#define WANCHOR_H_

#include <Wt/WContainerWidget.h>
#include <Wt/WJavaScript.h>
#include <Wt/WImage.h>
#include <Wt/WLink.h>

namespace Wt {

  namespace Impl {
    class AreaWidget;
  }

/*! \class WAnchor Wt/WAnchor.h Wt/WAnchor.h
 *  \brief 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 \link WLink.setTarget(LinkTarget)
 * link.setTarget(LinkTarget::NewWindow)\endlink. 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.
 *
 * \if cpp
 * Usage example:
 * \code
 * WAnchor *a;
 *
 * // Create an anchor that links to a URL
 * a = addWidget(std::make_unique<Wt::WAnchor>("https://www.webtoolkit.eu/", "Wt web toolkit"));
 *
 * // Create an anchor that links to an internal path
 * a = addWidget(std::make_unique<Wt::WAnchor>(
 *       WLink(LinkType::InternalPath, "/docs/" + myDocName()), "Doc"));
 * //   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 = addChild(std::make_unique<PdfResource>()); // serializes to a PDF file.
 * a = addWidget(std::make_unique<Wt::WAnchor>(r, "PDF version"));
 * \endcode
 * \endif
 *
 * %WAnchor is an \link WWidget::setInline(bool) inline \endlink widget.
 *
 * <h3>CSS</h3>
 *
 * The widget corresponds to the HTML <tt>&lt;a&gt;</tt> tag and does
 * not provide styling. It can be styled using inline or external CSS
 * as appropriate.
 */
class WT_API WAnchor : public WContainerWidget
{
public:
  /*! \brief Creates an anchor.
   */
  WAnchor();

  /*! \brief Creates an anchor for the given link.
   *
   * The \p link may point to a URL, a dynamic resource, or an
   * internal path.
   *
   * \sa setLink()
   */
  WAnchor(const WLink& link);

  /*! \brief Creates an anchor for the given link with a text.
   *
   * The \p link may point to a URL, a dynamic resource, or an
   * internal path.
   *
   * \sa setLink(), setText()
   */
  WAnchor(const WLink& link, const WString& text);

  /*! \brief Creates an anchor for the given link with an image.
   *
   * \if cpp
   * Ownership of the image is transferred to the anchor.
   * \endif
   *
   * \sa setLink(), setImage()
   */
  WAnchor(const WLink& link, std::unique_ptr<WImage> image);

  /*! \brief Sets the link.
   *
   * The link may hold a URL, a resource, or an internal path.
   *
   * When the link points to a \link LinkType::Resource resource\endlink,
   * the contents of the link may be generated by your application on
   * demand.
   *
   * When the link points to an \link LinkType::InternalPath internal
   * path\endlink, activating the anchor will change the \link
   * WApplication::internalPath() application's internal path\endlink
   * or open a new session with the given path as \link
   * WEnvironment::internalPath() initial path\endlink). This is the
   * easiest way to let the application participate in browser
   * history, and generate URLs that are bookmarkable and search
   * engine friendly.
   */
  void setLink(const WLink& link);

  /*! \brief Returns the link.
   *
   * \sa setLink()
   */
  const WLink& link() const { return linkState_.link; }

  /*! \brief Sets the label text
   *
   * If no text was previously set, a new WText widget is added using
   * addWidget().
   */
  void setText(const WString& text);

  /*! \brief Returns the label text.
   *
   * Returns an empty string if no label was set.
   *
   * \sa setText()
   */
  const WString& text() const;

  /*! \brief Configures text word wrapping.
   *
   * When \p wordWrap is \c true, the text set with setText() may be
   * broken up over multiple lines. When \p wordWrap is \c false, the
   * text will displayed on a single line, unless the text contains
   * <tt>&lt;br /&gt;</tt> tags or other block-level tags.
   *
   * The default value is \c true.
   *
   * \sa wordWrap()
   */
  void setWordWrap(bool wordWrap);

  /*! \brief Configures the text format.
   *
   * The default text format is TextFormat::XHTML.
   *
   * \sa WText::setTextFormat()
   */
  void setTextFormat(TextFormat format);

  /*! \brief Returns the text format.
   *
   * \sa setTextFormat()
   */
  TextFormat textFormat() const;

  /*! \brief Returns whether the widget may break lines.
   *
   * \sa setWordWrap(bool)
   */
  bool wordWrap() const;

  /*! \brief Sets an image.
   *
   * If an image was previously set, it is deleted. The \p image
   * is added using addWidget().
   */
  void setImage(std::unique_ptr<WImage> image);

  /*! \brief Returns the image.
   *
   * Returns \c 0 if no image is set.
   *
   * \sa setImage()
   */
  WImage *image() const { return image_.get(); }

  virtual bool canReceiveFocus() const override;
  virtual int tabIndex() const override;
  virtual bool setFirstFocus() override;

private:
  static const int BIT_LINK_CHANGED = 0;
  static const int BIT_TARGET_CHANGED = 1;

  struct WT_API LinkState {
    LinkState();
    ~LinkState();

    WLink link;
    JSlot *clickJS;
  };

  LinkState linkState_;

  observing_ptr<WText> text_;
  observing_ptr<WImage> image_;
  std::bitset<2> flags_;

  void resourceChanged();

  static bool renderHRef(WInteractWidget *widget,
                         LinkState& linkState, DomElement& element);
  static void renderHTarget(LinkState& linkState, DomElement& element,
                            bool all);
  static void renderUrlResolution(WWidget *widget, DomElement& element,
                                  bool all);

protected:
  virtual void updateDom(DomElement& element, bool all) override;
  virtual DomElementType domElementType() const override;
  virtual void propagateRenderOk(bool deep) override;
  virtual void propagateSetEnabled(bool enabled) override;
  virtual void enableAjax() override;

  friend class WAbstractArea;
  friend class WPushButton;
  friend class Impl::AreaWidget;
};

}

#endif // WANCHOR_H_