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