include/wx/hyperlink.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        hyperlink.h
   3 // Purpose:     Hyperlink control
   4 // Author:      David Norris <danorris@gmail.com>, Otto Wyss
   5 // Modified by: Ryan Norton, Francesco Montorsi
   6 // Created:     04/02/2005
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2005 David Norris
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_HYPERLINK_H__
  13 #define _WX_HYPERLINK_H__
  14
  15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16     #pragma interface "hyperlink.h"
  17 #endif
  18
  19 #include "wx/defs.h"
  20
  21 #if wxUSE_HYPERLINKCTRL
  22
  23 #include "wx/control.h"
  24
  25 // ----------------------------------------------------------------------------
  26 // constants
  27 // ----------------------------------------------------------------------------
  28
  29 #define wxHL_CONTEXTMENU        0x0001
  30 #define wxHL_DEFAULT_STYLE      wxHL_CONTEXTMENU|wxNO_BORDER
  31
  32 extern WXDLLEXPORT_DATA(const wxChar) wxHyperlinkCtrlNameStr[];
  33
  34
  35 // ----------------------------------------------------------------------------
  36 // wxHyperlinkCtrl
  37 // ----------------------------------------------------------------------------
  38
  39 // A static text control that emulates a hyperlink. The link is displayed
  40 // in an appropriate text style, derived from the control's normal font.
  41 // When the mouse rolls over the link, the cursor changes to a hand and the
  42 // link's color changes to the active color.
  43 //
  44 // Clicking on the link does not launch a web browser; instead, a
  45 // HyperlinkEvent is fired. The event propagates upward until it is caught,
  46 // just like a wxCommandEvent.
  47 //
  48 // Use the EVT_HYPERLINK() to catch link events.
  49 class WXDLLIMPEXP_CORE wxHyperlinkCtrl : public wxControl
  50 {
  51 public:
  52     // Default constructor (for two-step construction).
  53     wxHyperlinkCtrl() { }
  54
  55     // Constructor.
  56     wxHyperlinkCtrl(wxWindow *parent,
  57                     wxWindowID id,
  58                     const wxString& label, const wxString& url,
  59                     const wxPoint& pos = wxDefaultPosition,
  60                     const wxSize& size = wxDefaultSize,
  61                     long style = wxHL_DEFAULT_STYLE,
  62                     const wxString& name = wxHyperlinkCtrlNameStr)
  63     {
  64         (void)Create(parent, id, label, url, pos, size, style, name);
  65     }
  66
  67     // Creation function (for two-step construction).
  68     bool Create(wxWindow *parent,
  69                 wxWindowID id,
  70                 const wxString& label, const wxString& url,
  71                 const wxPoint& pos = wxDefaultPosition,
  72                 const wxSize& size = wxDefaultSize,
  73                 long style = wxHL_DEFAULT_STYLE,
  74                 const wxString& name = wxHyperlinkCtrlNameStr);
  75
  76
  77     // get/set
  78     wxColour GetHoverColour() const { return m_hoverColour; }
  79     void SetHoverColour(const wxColour &colour) { m_hoverColour = colour; }
  80
  81     wxColour GetNormalColour() const { return m_normalColour; }
  82     void SetNormalColour(const wxColour &colour);
  83
  84     wxColour GetVisitedColour() const { return m_visitedColour; }
  85     void SetVisitedColour(const wxColour &colour);
  86
  87     wxString GetURL() const { return m_url; }
  88     void SetURL (const wxString &url) { m_url=url; }
  89
  90     void SetVisited(bool visited = true) { m_visited=visited; }
  91     bool GetVisited() const { return m_visited; }
  92
  93     // NOTE: also wxWindow::Set/GetLabel, wxWindow::Set/GetBackgroundColour,
  94     //       wxWindow::Get/SetFont, wxWindow::Get/SetCursor are important !
  95
  96
  97 protected:
  98     // event handlers
  99
 100     // Renders the hyperlink.
 101     void OnPaint(wxPaintEvent& event);
 102
 103     // If the click originates inside the bounding box of the label,
 104     // a flag is set so that an event will be fired when the left
 105     // button is released.
 106     void OnLeftDown(wxMouseEvent& event);
 107
 108     // If the click both originated and finished inside the bounding box
 109     // of the label, a HyperlinkEvent is fired.
 110     void OnLeftUp(wxMouseEvent& event);
 111     void OnRightUp(wxMouseEvent& event);
 112
 113     // Changes the cursor to a hand, if the mouse is inside the label's
 114     // bounding box.
 115     void OnEnterWindow(wxMouseEvent& event);
 116
 117     // Changes the cursor back to the default, if necessary.
 118     void OnLeaveWindow(wxMouseEvent& event);
 119
 120     // handles "Copy URL" menuitem
 121     void OnPopUpCopy(wxCommandEvent& event);
 122
 123
 124     // overridden base class virtuals
 125
 126     // Returns the best size for the window, which is the size needed
 127     // to display the text label.
 128     virtual void DoGetSize(int *width, int *height) const;
 129     virtual wxSize DoGetBestSize() const;
 130
 131     // creates a context menu with "Copy URL" menuitem
 132     virtual void DoContextMenu(const wxPoint &);
 133
 134 private:
 135     // URL associated with the link. This is transmitted inside
 136     // the HyperlinkEvent fired when the user clicks on the label.
 137     wxString m_url;
 138
 139     // Foreground colours for various link types.
 140     // NOTE: wxWindow::m_backgroundColour is used for background,
 141     //       wxWindow::m_foregroundColour is used to render non-visited links
 142     wxColour m_hoverColour;
 143     wxColour m_normalColour;
 144     wxColour m_visitedColour;
 145
 146     // True if the mouse cursor is inside the label's bounding box.
 147     bool m_rollover;
 148
 149     // True if the link has been clicked before.
 150     bool m_visited;
 151
 152     // True if a click is in progress (left button down) and the click
 153     // originated inside the label's bounding box.
 154     bool m_clicking;
 155
 156 private:
 157     DECLARE_DYNAMIC_CLASS(wxHyperlinkCtrl)
 158     DECLARE_EVENT_TABLE()
 159 };
 160
 161
 162 // ----------------------------------------------------------------------------
 163 // wxHyperlinkEvent
 164 // ----------------------------------------------------------------------------
 165
 166 // Declare an event identifier.
 167 BEGIN_DECLARE_EVENT_TYPES()
 168     DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_CORE, wxEVT_COMMAND_HYPERLINK, 3700)
 169 END_DECLARE_EVENT_TYPES()
 170
 171 //
 172 // An event fired when the user clicks on the label in a hyperlink control.
 173 // See HyperlinkControl for details.
 174 //
 175 class WXDLLIMPEXP_CORE wxHyperlinkEvent : public wxCommandEvent
 176 {
 177 public:
 178
 179     wxHyperlinkEvent() {}
 180     wxHyperlinkEvent(wxObject *generator, wxWindowID id, const wxString& url)
 181      : wxCommandEvent(wxEVT_COMMAND_HYPERLINK, id), m_url(url)
 182         { SetEventObject(generator); }
 183
 184     // Returns the URL associated with the hyperlink control
 185     // that the user clicked on.
 186     wxString GetURL() const { return m_url; }
 187     void SetURL(const wxString &url) { m_url=url; }
 188
 189 private:
 190
 191     // URL associated with the hyperlink control that the used clicked on.
 192     wxString m_url;
 193 };
 194
 195 // Define a typedef for event handler functions.
 196 typedef void (wxEvtHandler::*wxHyperlinkEventFunction)(wxHyperlinkEvent&);
 197
 198 // Define an event table macro.
 199 #define EVT_HYPERLINK(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_COMMAND_HYPERLINK, \
 200     id, id, (wxObjectEventFunction) (wxEventFunction) \
 201     wxStaticCastEvent(wxHyperlinkEventFunction, &fn), (wxObject *) NULL),
 202
 203 // Newer event macro
 204 #define wxHyperlinkEventHandler(func) \
 205     (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxHyperlinkEventFunction, &func)
 206
 207 #endif // wxUSE_HYPERLINKCTRL
 208
 209 #endif // _WX_HYPERLINK_H__
 210