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