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