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