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