interface/hyperlink.h

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