interface/wx/hyperlink.h

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