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 a hyperlink.
22     @endEventTable
23 
24     @library{wxcore}
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.
70     @style{wxHL_ALIGN_CENTRE}
71            Center the text (horizontally). This style is not supported
72            under Windows.
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     and a generic version is used by the other ports.
92 
93     @library{wxcore}
94     @category{ctrl}
95     @appearance{hyperlinkctrl}
96 
97     @see wxURL, wxHyperlinkEvent
98 */
99 class wxHyperlinkCtrl : public wxControl
100 {
101 public:
102     wxHyperlinkCtrl();
103 
104     /**
105         Constructor. See Create() for more info.
106     */
107     wxHyperlinkCtrl(wxWindow* parent, wxWindowID id,
108                     const wxString& label,
109                     const wxString& url,
110                     const wxPoint& pos = wxDefaultPosition,
111                     const wxSize& size = wxDefaultSize,
112                     long style = wxHL_DEFAULT_STYLE,
113                     const wxString& name = wxHyperlinkCtrlNameStr);
114 
115     /**
116         Creates the hyperlink control.
117 
118         @param parent
119             Parent window. Must not be @NULL.
120         @param id
121             Window identifier. A value of wxID_ANY indicates a default value.
122         @param label
123             The label of the hyperlink.
124         @param url
125             The URL associated with the given label.
126         @param pos
127             Window position.
128         @param size
129             Window size.
130             If the wxDefaultSize is specified then the window is sized appropriately.
131         @param style
132             Window style. See wxHyperlinkCtrl.
133         @param name
134             Window name.
135     */
136     bool Create(wxWindow* parent, wxWindowID id, const wxString& label,
137                 const wxString& url, const wxPoint& pos = wxDefaultPosition,
138                 const wxSize& size = wxDefaultSize,
139                 long style = wxHL_DEFAULT_STYLE,
140                 const wxString& name = wxHyperlinkCtrlNameStr);
141 
142     /**
143         Returns the colour used to print the label of the hyperlink when the mouse is
144         over the control.
145     */
146     virtual wxColour GetHoverColour() const;
147 
148     /**
149         Returns the colour used to print the label when the link has never been clicked
150         before (i.e.\ the link has not been @e visited) and the mouse is not over the control.
151     */
152     virtual wxColour GetNormalColour() const;
153 
154     /**
155         Returns the URL associated with the hyperlink.
156     */
157     virtual wxString GetURL() const;
158 
159     /**
160         Returns @true if the hyperlink has already been clicked by the user at least
161         one time.
162     */
163     virtual bool GetVisited() const = 0;
164 
165     /**
166         Returns the colour used to print the label when the mouse is not over the
167         control and the link has already been clicked before (i.e.\ the link has
168         been @e visited).
169     */
170     virtual wxColour GetVisitedColour() const;
171 
172     /**
173         Sets the colour used to print the label of the hyperlink when the mouse is over
174         the control.
175     */
176     virtual void SetHoverColour(const wxColour& colour);
177 
178     /**
179         Sets the colour used to print the label when the link has never been clicked before
180         (i.e.\ the link has not been @e visited) and the mouse is not over the control.
181     */
182     virtual void SetNormalColour(const wxColour& colour);
183 
184     /**
185         Sets the URL associated with the hyperlink.
186     */
187     virtual void SetURL(const wxString& url);
188 
189     /**
190         Marks the hyperlink as visited (see wxHyperlinkCtrl::SetVisitedColour).
191     */
192     virtual void SetVisited(bool visited = true) = 0;
193 
194     /**
195         Sets the colour used to print the label when the mouse is not over the control
196         and the link has already been clicked before (i.e.\ the link has been @e visited).
197     */
198     virtual void SetVisitedColour(const wxColour& colour);
199 };
200 
201