docs/latex/wx/hyperlink.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        hyperlink.tex
   3 %% Purpose:     wxHyperlinkCtrl documentation
   4 %% Author:      Otto Wyss
   5 %% Modified by: Francesco Montorsi
   6 %% Created:     25.4.2004
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2004 wxCode, Francesco Montorsi
   9 %% License:     wxWindows
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxHyperlinkCtrl}}\label{wxhyperlinkctrl}
  13
  14 This class shows a static text element which links to an URL.
  15 Appearance and behaviour is completely customizable. In fact, when the user clicks on the hyperlink, a \helpref{wxHyperlinkEvent}{wxhyperlinkctrlevent} is sent but if that event is not handled (or it's skipped; see \helpref{wxEvent::Skip}{wxeventskip}), then a call to \helpref{wxLaunchDefaultBrowser}{wxlaunchdefaultbrowser} is done with the hyperlink's URL.
  16
  17 Note that standard \helpref{wxWindow}{wxwindow} functions like \helpref{SetBackgroundColour}{wxwindowsetbackgroundcolour}, \helpref{SetFont}{wxwindowsetfont}, \helpref{SetCursor}{wxwindowsetcursor}, \helpref{SetLabel}{wxwindowsetlabel} can be used to customize appearance of the hyperlink.
  18
  19
  20 \wxheading{Derived from}
  21
  22 \helpref{wxControl}{wxcontrol}
  23
  24
  25 \wxheading{Include files}
  26
  27 <wx/hyperlink.h>
  28
  29
  30 \wxheading{Window styles}
  31
  32 \twocolwidtha{7cm}
  33 \begin{twocollist}\itemsep=0pt
  34 \twocolitem{\windowstyle{wxHL\_CONTEXTMENU}}{Pop up a context menu when the hyperlink is right-clicked. The context menu contains a \texttt{``Copy URL"} menu item which is automatically handled by the hyperlink and which just copies in the clipboard the URL (not the label) of the control.}
  35 \twocolitem{\windowstyle{wxHL\_DEFAULT\_STYLE}}{The default style for wxHyperlinkCtrl: \texttt{wxNO\_BORDER|wxHL\_CONTEXTMENU}.}
  36 \end{twocollist}
  37
  38 See also \helpref{window styles overview}{windowstyles}.
  39
  40
  41 \wxheading{Event handling}
  42
  43 To process input from a list control, use these event handler macros to direct input to member
  44 functions that take a \helpref{wxHyperlinkEvent}{wxhyperlinkctrlevent} argument.
  45
  46 \twocolwidtha{7cm}
  47 \begin{twocollist}\itemsep=0pt
  48 \twocolitem{{\bf EVT\_HYPERLINK(id, func)}}{The hyperlink was (left) clicked. If this event is not handled in user's code (or it's skipped; see \helpref{wxEvent::Skip}{wxeventskip}), then a call to \helpref{wxLaunchDefaultBrowser}{wxlaunchdefaultbrowser} is done with the hyperlink's URL.}
  49 \end{twocollist}
  50
  51
  52 \wxheading{See also}
  53
  54 \helpref{wxURL}{wxurl}
  55
  56
  57 \latexignore{\rtfignore{\wxheading{Members}}}
  58
  59 \membersection{wxHyperlinkCtrl::wxHyperLink}\label{wxhyperlinkctrlctor}
  60
  61 \func{}{wxHyperLink}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id}, \param{const wxString \&}{ label}, \param{const wxString \&}{ url}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style}, \param{const wxString\& }{name = ``hyperlink"}}
  62
  63 Constructor. See \helpref{Create}{wxhyperlinkctrlcreate} for more info.
  64
  65
  66 \membersection{wxHyperlinkCtrl::Create}\label{wxhyperlinkctrlcreate}
  67
  68 \func{}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id = wxID\_ANY} \param{const wxString \&}{ label}, \param{const wxString \&}{ url}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\param{long}{ style}, \param{const wxString\& }{name = ``hyperlink"}}
  69
  70 Creates the hyperlink control.
  71
  72 \wxheading{Parameters}
  73
  74 \docparam{parent}{Parent window. Must not be \NULL.}
  75
  76 \docparam{id}{Window identifier. A value of wxID\_ANY indicates a default value.}
  77
  78 \docparam{label}{The label of the hyperlink.}
  79
  80 \docparam{url}{The URL which is .}
  81
  82 \docparam{pos}{Window position.}
  83
  84 \docparam{size}{Window size. If the wxDefaultSize is specified then the window is sized
  85 appropriately.}
  86
  87 \docparam{style}{Window style. See \helpref{wxHyperlinkCtrl}{wxhyperlinkctrl}.}
  88
  89 \docparam{validator}{Window validator.}
  90
  91 \docparam{name}{Window name.}
  92
  93
  94 \membersection{wxHyperlinkCtrl::GetHoverColour}\label{wxhyperlinkctrlgethovercolour}
  95
  96 \constfunc{wxColour}{GetHoverColour}{\void}
  97
  98 Returns the colour used to print the label of the hyperlink when the mouse is over the control.
  99
 100
 101 \membersection{wxHyperlinkCtrl::SetHoverColour}\label{wxhyperlinkctrlsethovercolour}
 102
 103 \func{void}{SetHoverColour}{\param{const wxColour \&}{ colour}}
 104
 105 Sets the colour used to print the label of the hyperlink when the mouse is over the control.
 106
 107
 108 \membersection{wxHyperlinkCtrl::GetNormalColour}\label{wxhyperlinkctrlgetnormalcolour}
 109
 110 \constfunc{wxColour}{GetNormalColour}{\void}
 111
 112 Returns the colour used to print the label when the link has never been clicked before
 113 (i.e. the link has not been {\it visited}) and the mouse is not over the control.
 114
 115
 116 \membersection{wxHyperlinkCtrl::SetNormalColour}\label{wxhyperlinkctrlsetnormalcolour}
 117
 118 \func{void}{SetNormalColour}{\param{const wxColour \&}{ colour}}
 119
 120 Sets the colour used to print the label when the link has never been clicked before
 121 (i.e. the link has not been {\it visited}) and the mouse is not over the control.
 122
 123
 124 \membersection{wxHyperlinkCtrl::GetVisitedColour}\label{wxhyperlinkctrlgetvisitedcolour}
 125
 126 \constfunc{wxColour}{GetVisitedColour}{\void}
 127
 128 Returns the colour used to print the label when the mouse is not over the control
 129 and the link has already been clicked before (i.e. the link has been {\it visited}).
 130
 131
 132 \membersection{wxHyperlinkCtrl::SetVisitedColour}\label{wxhyperlinkctrlsetvisitedcolour}
 133
 134 \func{void}{SetVisitedColour}{\param{const wxColour \&}{ colour}}
 135
 136 Sets the colour used to print the label when the mouse is not over the control
 137 and the link has already been clicked before (i.e. the link has been {\it visited}).
 138
 139
 140 \membersection{wxHyperlinkCtrl::GetVisited}\label{wxhyperlinkctrlgetvisited}
 141
 142 \constfunc{bool}{GetVisited}{\void}
 143
 144 Returns \true if the hyperlink has already been clicked by the user at least one time.
 145
 146
 147 \membersection{wxHyperlinkCtrl::SetVisited}\label{wxhyperlinkctrlsetvisited}
 148
 149 \func{void}{SetVisited}{\param{bool}{ visited = true}}
 150
 151 Marks the hyperlink as visited (see \helpref{SetVisitedColour}{wxhyperlinkctrlsetvisitedcolour}).
 152
 153
 154 \membersection{wxHyperlinkCtrl::GetURL}\label{wxhyperlinkctrlgeturl}
 155
 156 \constfunc{wxString}{GetURL}{\void}
 157
 158 Returns the URL associated with the hyperlink.
 159
 160
 161 \membersection{wxHyperlinkCtrl::SetURL}\label{wxhyperlinkctrlseturl}
 162
 163 \func{void}{SetURL}{\param{const wxString \&}{ url}}
 164
 165 Sets the URL associated with the hyperlink.
 166
 167
 168
 169
 170
 171
 172 \section{\class{wxHyperlinkEvent}}\label{wxhyperlinkctrlevent}
 173
 174 This event class is used for the events generated by
 175 \helpref{wxHyperlinkCtrl}{wxhyperlinkctrl}.
 176
 177 \wxheading{Derived from}
 178
 179 \helpref{wxCommandEvent}{wxcommandevent}\\
 180 \helpref{wxEvent}{wxevent}\\
 181 \helpref{wxObject}{wxobject}
 182
 183 \wxheading{Include files}
 184
 185 <wx/hyperlink.h>
 186
 187 \wxheading{Event handling}
 188
 189 To process input from a wxHyperlinkCtrl, use one of these event handler macros to
 190 direct input to member function that take a
 191 \helpref{wxHyperlinkEvent}{wxhyperlinkctrlevent} argument:
 192
 193 \twocolwidtha{7cm}
 194 \begin{twocollist}
 195 \twocolitem{{\bf EVT\_HYPERLINK(id, func)}}{User clicked on an hyperlink.}
 196 \end{twocollist}
 197
 198
 199 \latexignore{\rtfignore{\wxheading{Members}}}
 200
 201 \membersection{wxHyperlinkEvent::wxHyperlinkEvent}\label{wxhyperlinkctrlctor}
 202
 203 \func{}{wxHyperlinkEvent}{\param{wxObject *}{ generator}, \param{int}{ id}, \param{const wxString \&}{ url}}
 204
 205 The constructor is not normally used by the user code.
 206
 207
 208 \membersection{wxHyperlinkEvent::GetURL}\label{wxhyperlinkctrlgeturl}
 209
 210 \constfunc{wxString}{GetURL}{\void}
 211
 212 Returns the URL of the hyperlink where the user has just clicked.
 213
 214
 215 \membersection{wxHyperlinkEvent::SetURL}\label{wxhyperlinkctrlseturl}
 216
 217 \func{void}{SetURL}{\param{const wxString \&}{ url}}
 218
 219 Sets the URL associated with the event.