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