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         Constructor. See Create() for more info.
  84     */
  85     wxHyperLink(wxWindow* parent, wxWindowID id,
  86                 const wxString& label,
  87                 const wxString& url,
  88                 const wxPoint& pos = wxDefaultPosition,
  89                 const wxSize& size = wxDefaultSize,
  90                 long style = wxHL_DEFAULT_STYLE,
  91                 const wxString& name = "hyperlink");
  92
  93     /**
  94         Creates the hyperlink control.
  95
  96         @param parent
  97             Parent window. Must not be @NULL.
  98         @param id
  99             Window identifier. A value of wxID_ANY indicates a default value.
 100         @param label
 101             The label of the hyperlink.
 102         @param url
 103             The URL associated with the given label.
 104         @param pos
 105             Window position.
 106         @param size
 107             Window size. If the wxDefaultSize is specified then the window is sized
 108             appropriately.
 109         @param style
 110             Window style. See wxHyperlinkCtrl.
 111         @param validator
 112             Window validator.
 113         @param name
 114             Window name.
 115     */
 116     bool Create(wxWindow* parent, wxWindowID id,
 117                 const wxString& label,
 118                 const wxString& url,
 119                 const wxPoint& pos = wxDefaultPosition,
 120                 const wxSize& size = wxDefaultSize,
 121                 long style = wxHL_DEFAULT_STYLE,
 122                 const wxString& name = "hyperlink");
 123
 124     /**
 125         Returns the colour used to print the label of the hyperlink when the mouse is
 126         over the control.
 127     */
 128     wxColour GetHoverColour() const;
 129
 130     /**
 131         Returns the colour used to print the label when the link has never been clicked
 132         before
 133         (i.e. the link has not been @e visited) and the mouse is not over the control.
 134     */
 135     wxColour GetNormalColour() const;
 136
 137     /**
 138         Returns the URL associated with the hyperlink.
 139     */
 140     wxString GetURL() const;
 141
 142     /**
 143         Returns @true if the hyperlink has already been clicked by the user at least
 144         one time.
 145     */
 146     virtual bool GetVisited() const = 0;
 147
 148     /**
 149         Returns the colour used to print the label when the mouse is not over the
 150         control
 151         and the link has already been clicked before (i.e. the link has been @e
 152         visited).
 153     */
 154     wxColour GetVisitedColour() const;
 155
 156     /**
 157         Sets the colour used to print the label of the hyperlink when the mouse is over
 158         the control.
 159     */
 160     void SetHoverColour(const wxColour& colour);
 161
 162     /**
 163         Sets the colour used to print the label when the link has never been clicked
 164         before
 165         (i.e. the link has not been @e visited) and the mouse is not over the control.
 166     */
 167     void SetNormalColour(const wxColour& colour);
 168
 169     /**
 170         Sets the URL associated with the hyperlink.
 171     */
 172     void SetURL(const wxString& url);
 173
 174     /**
 175         Marks the hyperlink as visited (see wxHyperlinkCtrl::SetVisitedColour).
 176     */
 177     virtual void SetVisited(bool visited = true) = 0;
 178
 179     /**
 180         Sets the colour used to print the label when the mouse is not over the control
 181         and the link has already been clicked before (i.e. the link has been @e
 182         visited).
 183     */
 184     void SetVisitedColour(const wxColour& colour);
 185 };
 186