interface/hyperlink.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        hyperlink.h
   3 // Purpose:     interface of wxHyperlinkEvent
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHyperlinkEvent
  11     @wxheader{hyperlink.h}
  12
  13     This event class is used for the events generated by
  14     wxHyperlinkCtrl.
  15
  16     @library{wxadv}
  17     @category{FIXME}
  18 */
  19 class wxHyperlinkEvent : public wxCommandEvent
  20 {
  21 public:
  22     /**
  23         The constructor is not normally used by the user code.
  24     */
  25     wxHyperlinkEvent(wxObject* generator, int id,
  26                      const wxString& url);
  27
  28     /**
  29         Returns the URL of the hyperlink where the user has just clicked.
  30     */
  31     wxString GetURL() const;
  32
  33     /**
  34         Sets the URL associated with the event.
  35     */
  36     void SetURL(const wxString& url);
  37 };
  38
  39
  40
  41 /**
  42     @class wxHyperlinkCtrl
  43     @wxheader{hyperlink.h}
  44
  45     This class shows a static text element which links to an URL.
  46     Appearance and behaviour is completely customizable. In fact, when the user
  47     clicks on the hyperlink, a wxHyperlinkEvent is
  48     sent but if that event is not handled (or it's skipped; see
  49     wxEvent::Skip), then a call to
  50     wxLaunchDefaultBrowser() is done with the
  51     hyperlink's URL.
  52
  53     Note that standard wxWindow functions like wxWindow::SetBackgroundColour,
  54     wxWindow::SetFont, wxWindow::SetCursor, wxWindow::SetLabel can be used to customize appearance of the hyperlink.
  55
  56     @beginStyleTable
  57     @style{wxHL_ALIGN_LEFT}:
  58            Align the text to the left.
  59     @style{wxHL_ALIGN_RIGHT}:
  60            Align the text to the right.
  61     @style{wxHL_ALIGN_CENTRE}:
  62            Center the text (horizontally).
  63     @style{wxHL_CONTEXTMENU}:
  64            Pop up a context menu when the hyperlink is right-clicked. The
  65            context menu contains a "Copy URL" menu item which is automatically
  66            handled by the hyperlink and which just copies in the clipboard the
  67            URL (not the label) of the control.
  68     @style{wxHL_DEFAULT_STYLE}:
  69            The default style for wxHyperlinkCtrl:
  70            wxBORDER_NONE|wxHL_CONTEXTMENU|wxHL_ALIGN_CENTRE.
  71     @endStyleTable
  72
  73     @library{wxadv}
  74     @category{ctrl}
  75     @appearance{hyperlinkctrl.png}
  76
  77     @see wxURL, wxHyperlinkEvent
  78 */
  79 class wxHyperlinkCtrl : public wxControl
  80 {
  81 public:
  82     /**
  83         Creates the hyperlink control.
  84
  85         @param parent
  86             Parent window. Must not be @NULL.
  87         @param id
  88             Window identifier. A value of wxID_ANY indicates a default value.
  89         @param label
  90             The label of the hyperlink.
  91         @param url
  92             The URL associated with the given label.
  93         @param pos
  94             Window position.
  95         @param size
  96             Window size. If the wxDefaultSize is specified then the window is sized
  97             appropriately.
  98         @param style
  99             Window style. See wxHyperlinkCtrl.
 100         @param validator
 101             Window validator.
 102         @param name
 103             Window name.
 104     */
 105     bool Create(wxWindow* parent, wxWindowID id,
 106                 const wxString& label,
 107                 const wxString& url,
 108                 const wxPoint& pos = wxDefaultPosition,
 109                 const wxSize& size = wxDefaultSize,
 110                 long style,
 111                 const wxString& name = "hyperlink");
 112
 113     /**
 114         Returns the colour used to print the label of the hyperlink when the mouse is
 115         over the control.
 116     */
 117     wxColour GetHoverColour() const;
 118
 119     /**
 120         Returns the colour used to print the label when the link has never been clicked
 121         before
 122         (i.e. the link has not been @e visited) and the mouse is not over the control.
 123     */
 124     wxColour GetNormalColour() const;
 125
 126     /**
 127         Returns the URL associated with the hyperlink.
 128     */
 129     wxString GetURL() const;
 130
 131     /**
 132         Returns @true if the hyperlink has already been clicked by the user at least
 133         one time.
 134     */
 135     bool GetVisited() const;
 136
 137     /**
 138         Returns the colour used to print the label when the mouse is not over the
 139         control
 140         and the link has already been clicked before (i.e. the link has been @e
 141         visited).
 142     */
 143     wxColour GetVisitedColour() const;
 144
 145     /**
 146         Sets the colour used to print the label of the hyperlink when the mouse is over
 147         the control.
 148     */
 149     void SetHoverColour(const wxColour& colour);
 150
 151     /**
 152         Sets the colour used to print the label when the link has never been clicked
 153         before
 154         (i.e. the link has not been @e visited) and the mouse is not over the control.
 155     */
 156     void SetNormalColour(const wxColour& colour);
 157
 158     /**
 159         Sets the URL associated with the hyperlink.
 160     */
 161     void SetURL(const wxString& url);
 162
 163     /**
 164         Marks the hyperlink as visited (see wxHyperlinkCtrl::SetVisitedColour).
 165     */
 166     void SetVisited(bool visited = true);
 167
 168     /**
 169         Sets the colour used to print the label when the mouse is not over the control
 170         and the link has already been clicked before (i.e. the link has been @e
 171         visited).
 172     */
 173     void SetVisitedColour(const wxColour& colour);
 174
 175     /**
 176         Constructor. See Create() for more info.
 177     */
 178     wxHyperLink(wxWindow* parent, wxWindowID id,
 179                 const wxString& label,
 180                 const wxString& url,
 181                 const wxPoint& pos = wxDefaultPosition,
 182                 const wxSize& size = wxDefaultSize,
 183                 long style,
 184                 const wxString& name = "hyperlink");
 185 };
 186