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