include/wx/hyperlink.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/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 #include "wx/defs.h"
  16
  17 #if wxUSE_HYPERLINKCTRL
  18
  19 #include "wx/control.h"
  20
  21 // ----------------------------------------------------------------------------
  22 // constants
  23 // ----------------------------------------------------------------------------
  24
  25 #define wxHL_CONTEXTMENU        0x0001
  26 #define wxHL_ALIGN_LEFT         0x0002
  27 #define wxHL_ALIGN_RIGHT        0x0004
  28 #define wxHL_ALIGN_CENTRE       0x0008
  29 #define wxHL_DEFAULT_STYLE      (wxHL_CONTEXTMENU|wxNO_BORDER|wxHL_ALIGN_CENTRE)
  30
  31 extern WXDLLIMPEXP_DATA_ADV(const wxChar) wxHyperlinkCtrlNameStr[];
  32
  33
  34 // ----------------------------------------------------------------------------
  35 // wxHyperlinkCtrl
  36 // ----------------------------------------------------------------------------
  37
  38 // A static text control that emulates a hyperlink. The link is displayed
  39 // in an appropriate text style, derived from the control's normal font.
  40 // When the mouse rolls over the link, the cursor changes to a hand and the
  41 // link's color changes to the active color.
  42 //
  43 // Clicking on the link does not launch a web browser; instead, a
  44 // HyperlinkEvent is fired. The event propagates upward until it is caught,
  45 // just like a wxCommandEvent.
  46 //
  47 // Use the EVT_HYPERLINK() to catch link events.
  48 class WXDLLIMPEXP_ADV wxHyperlinkCtrl : public wxControl
  49 {
  50 public:
  51     // Default constructor (for two-step construction).
  52     wxHyperlinkCtrl() { }
  53
  54     // Constructor.
  55     wxHyperlinkCtrl(wxWindow *parent,
  56                     wxWindowID id,
  57                     const wxString& label, const wxString& url,
  58                     const wxPoint& pos = wxDefaultPosition,
  59                     const wxSize& size = wxDefaultSize,
  60                     long style = wxHL_DEFAULT_STYLE,
  61                     const wxString& name = wxHyperlinkCtrlNameStr)
  62     {
  63         (void)Create(parent, id, label, url, pos, size, style, name);
  64     }
  65
  66     // Creation function (for two-step construction).
  67     bool Create(wxWindow *parent,
  68                 wxWindowID id,
  69                 const wxString& label, const wxString& url,
  70                 const wxPoint& pos = wxDefaultPosition,
  71                 const wxSize& size = wxDefaultSize,
  72                 long style = wxHL_DEFAULT_STYLE,
  73                 const wxString& name = wxHyperlinkCtrlNameStr);
  74
  75
  76     // get/set
  77     wxColour GetHoverColour() const { return m_hoverColour; }
  78     void SetHoverColour(const wxColour &colour) { m_hoverColour = colour; }
  79
  80     wxColour GetNormalColour() const { return m_normalColour; }
  81     void SetNormalColour(const wxColour &colour);
  82
  83     wxColour GetVisitedColour() const { return m_visitedColour; }
  84     void SetVisitedColour(const wxColour &colour);
  85
  86     wxString GetURL() const { return m_url; }
  87     void SetURL (const wxString &url) { m_url=url; }
  88
  89     void SetVisited(bool visited = true) { m_visited=visited; }
  90     bool GetVisited() const { return m_visited; }
  91
  92     // NOTE: also wxWindow::Set/GetLabel, wxWindow::Set/GetBackgroundColour,
  93     //       wxWindow::Get/SetFont, wxWindow::Get/SetCursor are important !
  94
  95
  96 protected:
  97     // event handlers
  98
  99     // Renders the hyperlink.
 100     void OnPaint(wxPaintEvent& event);
 101
 102     // Returns the wxRect of the label of this hyperlink.
 103     // This is different from the clientsize's rectangle when
 104     // clientsize != bestsize and this rectangle is influenced
 105     // by the alignment of the label (wxHL_ALIGN_*).
 106     wxRect GetLabelRect() const;
 107
 108     // If the click originates inside the bounding box of the label,
 109     // a flag is set so that an event will be fired when the left
 110     // button is released.
 111     void OnLeftDown(wxMouseEvent& event);
 112
 113     // If the click both originated and finished inside the bounding box
 114     // of the label, a HyperlinkEvent is fired.
 115     void OnLeftUp(wxMouseEvent& event);
 116     void OnRightUp(wxMouseEvent& event);
 117
 118     // Changes the cursor to a hand, if the mouse is inside the label's
 119     // bounding box.
 120     void OnMotion(wxMouseEvent& event);
 121
 122     // Changes the cursor back to the default, if necessary.
 123     void OnLeaveWindow(wxMouseEvent& event);
 124
 125     // handles "Copy URL" menuitem
 126     void OnPopUpCopy(wxCommandEvent& event);
 127
 128     // Refreshes the control to update label's position if necessary
 129     void OnSize(wxSizeEvent& event);
 130
 131
 132     // overridden base class virtuals
 133
 134     // Returns the best size for the window, which is the size needed
 135     // to display the text label.
 136     virtual void DoGetSize(int *width, int *height) const;
 137     virtual wxSize DoGetBestSize() const;
 138
 139     // creates a context menu with "Copy URL" menuitem
 140     virtual void DoContextMenu(const wxPoint &);
 141
 142 private:
 143     // URL associated with the link. This is transmitted inside
 144     // the HyperlinkEvent fired when the user clicks on the label.
 145     wxString m_url;
 146
 147     // Foreground colours for various link types.
 148     // NOTE: wxWindow::m_backgroundColour is used for background,
 149     //       wxWindow::m_foregroundColour is used to render non-visited links
 150     wxColour m_hoverColour;
 151     wxColour m_normalColour;
 152     wxColour m_visitedColour;
 153
 154     // True if the mouse cursor is inside the label's bounding box.
 155     bool m_rollover;
 156
 157     // True if the link has been clicked before.
 158     bool m_visited;
 159
 160     // True if a click is in progress (left button down) and the click
 161     // originated inside the label's bounding box.
 162     bool m_clicking;
 163
 164 private:
 165     DECLARE_DYNAMIC_CLASS(wxHyperlinkCtrl)
 166     DECLARE_EVENT_TABLE()
 167 };
 168
 169
 170 // ----------------------------------------------------------------------------
 171 // wxHyperlinkEvent
 172 // ----------------------------------------------------------------------------
 173
 174 // Declare an event identifier.
 175 BEGIN_DECLARE_EVENT_TYPES()
 176     DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_ADV, wxEVT_COMMAND_HYPERLINK, 3700)
 177 END_DECLARE_EVENT_TYPES()
 178
 179 //
 180 // An event fired when the user clicks on the label in a hyperlink control.
 181 // See HyperlinkControl for details.
 182 //
 183 class WXDLLIMPEXP_ADV wxHyperlinkEvent : public wxCommandEvent
 184 {
 185 public:
 186     wxHyperlinkEvent() {}
 187     wxHyperlinkEvent(wxObject *generator, wxWindowID id, const wxString& url)
 188         : wxCommandEvent(wxEVT_COMMAND_HYPERLINK, id),
 189           m_url(url)
 190     {
 191         SetEventObject(generator);
 192     }
 193
 194     // Returns the URL associated with the hyperlink control
 195     // that the user clicked on.
 196     wxString GetURL() const { return m_url; }
 197     void SetURL(const wxString &url) { m_url=url; }
 198
 199     // default copy ctor, assignment operator and dtor are ok
 200     virtual wxEvent *Clone() const { return new wxHyperlinkEvent(*this); }
 201
 202 private:
 203
 204     // URL associated with the hyperlink control that the used clicked on.
 205     wxString m_url;
 206
 207     DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxHyperlinkEvent)
 208 };
 209
 210
 211 // ----------------------------------------------------------------------------
 212 // event types and macros
 213 // ----------------------------------------------------------------------------
 214
 215 typedef void (wxEvtHandler::*wxHyperlinkEventFunction)(wxHyperlinkEvent&);
 216
 217 #define wxHyperlinkEventHandler(func) \
 218     (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxHyperlinkEventFunction, &func)
 219
 220 #define EVT_HYPERLINK(id, fn) \
 221     wx__DECLARE_EVT1(wxEVT_COMMAND_HYPERLINK, id, wxHyperlinkEventHandler(fn))
 222
 223 #ifdef _WX_DEFINE_DATE_EVENTS_
 224     DEFINE_EVENT_TYPE(wxEVT_COMMAND_HYPERLINK)
 225
 226     IMPLEMENT_DYNAMIC_CLASS(wxHyperlinkEvent, wxCommandEvent)
 227 #endif
 228
 229
 230 #endif // wxUSE_HYPERLINKCTRL
 231
 232 #endif // _WX_HYPERLINK_H__