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