****************
wx.HyperlinkCtrl
****************

Inheritance diagram for `wx.HyperlinkCtrl`:

|

.. inheritance-diagram:: wx.HyperlinkCtrl

|

Description
===========

This class shows a static text element which links to an URL. Appearance and behaviour is completely customizable. 
In fact, when the user clicks on the hyperlink, a `wx.HyperlinkEvent <../Events/wx.HyperlinkEvent.html>`_ is sent but if that event 
is not handled (or it's skipped; see `wx.Event.Skip <../Events/wx.Event.html#Skip>`_), then a call to 
`wx.LaunchDefaultBrowser <../wxFunctions.html#LaunchDefaultBrowser>`_ is done with the hyperlink's URL.

.. note:: Note that standard `wx.Window <wx.Window.html>`_ functions like `SetBackgroundColour <wx.Window.html#SetBackgroundColour>`_, 
   `SetFont <wx.Window.html#SetFont>`_, `SetCursor <wx.Window.html#SetCursor>`_, `SetLabel <wx.Control.html#SetLabel>`_ 
   can be used to customize appearance of the hyperlink.

.. seealso:: `wx.HyperlinkEvent <../Events/wx.HyperlinkEvent.html>`_


Derived From
^^^^^^^^^^^^^

* `wx.Control <wx.Control.html>`_ 
* `wx.Window <wx.Window.html>`_ 
* `wx.EvtHandler <wx.EvtHandler.html>`_ 
* `wx.Object <wx.Object.html>`_ 


Window Styles
^^^^^^^^^^^^^

==================================================  ==================================================  
Window Style                                        Description
==================================================  ==================================================  
``wx.HL_ALIGN_LEFT``                                Align the text to the left.
``wx.HL_ALIGN_RIGHT``                               Align the text to the right.
``wx.HL_ALIGN_CENTRE``                              Center the text (horizontally).
``wx.HL_CONTEXTMENU``                               Pop up a context menu when the hyperlink is right-clicked. The context menu contains a "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.
``wx.HL_DEFAULT_STYLE``                             The default style for wx.HyperlinkCtrl: ``wx.NO_BORDER`` | ``wx.HL_CONTEXTMENU`` | ``wx.HL_ALIGN_CENTRE``.
==================================================  ==================================================  


Event Handling
^^^^^^^^^^^^^^

==================================================  ==================================================  
Event Name                                          Description
==================================================  ==================================================  
wx.EVT_HYPERLINK(id, func)                          The hyperlink was (left) clicked. If this event is not handled in user's code (or it's skipped; see `wx.Event.Skip <../Events/wx.Event.html#Skip>`_), then a call to `wx.LaunchDefaultBrowser <../wxFunctions.html#LaunchDefaultBrowser>`_ is done with the hyperlink's URL.
==================================================  ==================================================  

|

Control Appearance
^^^^^^^^^^^^^^^^^^

|

.. figure:: ../images/wxWidgets/wxmsw/hyperlinkctrl.png 
   :alt: wxMSW
   :figclass: floatleft
   
   **wxMSW**


.. figure:: ../images/wxWidgets/wxmac/hyperlinkctrl.png 
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: ../images/wxWidgets/wxgtk/hyperlinkctrl.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|

Methods Summary
^^^^^^^^^^^^^^^

* `__init__ <#__init__>`_ 
* `GetHoverColour <#GetHoverColour>`_ 
* `GetNormalColour <#GetNormalColour>`_ 
* `GetURL <#GetURL>`_ 
* `GetVisited <#GetVisited>`_ 
* `GetVisitedColour <#GetVisitedColour>`_ 
* `SetHoverColour <#SetHoverColour>`_ 
* `SetNormalColour <#SetNormalColour>`_ 
* `SetURL <#SetURL>`_ 
* `SetVisited <#SetVisited>`_ 
* `SetVisitedColour <#SetVisitedColour>`_ 

Properties Summary
^^^^^^^^^^^^^^^^^^

* `HoverColour <#HoverColour>`_ 
* `NormalColour <#NormalColour>`_ 
* `URL <#URL>`_ 
* `Visited <#Visited>`_ 
* `VisitedColour <#VisitedColour>`_ 

Class API
=========

Methods
^^^^^^^


.. method:: __init__(parent, id, label, url, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.HL_DEFAULT_STYLE, name=wx.HyperlinkCtrlNameStr)

   A static text control that emulates a hyperlink. The link is displayed
   in an appropriate text style, derived from the control's normal font.
   When the mouse rolls over the link, the cursor changes to a hand and
   the link's color changes to the active color.
   
   Clicking on the link does not launch a web browser; instead, a
   `wx.HyperlinkEvent <../Events/wx.HyperlinkEvent.html>`_ is fired. 

   Use the ``wx.EVT_HYPERLINK`` event binding to catch link events.
   
   
   **Parameters:**

   * `parent` (`wx.Window <wx.Window.html>`_)
   * `id` (int)
   * `label` (string)
   * `url` (string)
   * `pos` (`wx.Point <wx.Point.html>`_)
   * `size` (`wx.Size <wx.Size.html>`_)
   * `style` (long)
   * `name` (string)

   |

   **Returns:**

   `wx.HyperlinkCtrl <wx.HyperlinkCtrl.html>`_
 

--------

.. method:: GetHoverColour()

   Returns the colour used to print the label of the hyperlink when the mouse is over the control.

   |  

   **Returns:**

   `wx.Colour <wx.Colour.html>`_
 

--------

.. method:: GetNormalColour()

   Returns the colour used to print the label when the link has never been clicked before (i.e. the link has not been *visited*) 
   and the mouse is not over the control.

   |  

   **Returns:**

   `wx.Colour <wx.Colour.html>`_
 

--------

.. method:: GetURL()

   Returns the URL associated with the hyperlink.

   |  

   **Returns:**

   `string` 

--------

.. method:: GetVisited()

   Returns ``True`` if the hyperlink has already been clicked by the user at least one time.

   |  

   **Returns:**

   `bool` 

--------

.. method:: GetVisitedColour()

   Returns the colour used to print the label when the mouse is not over the control and the link has already been clicked before 
   (i.e. the link has been *visited*).

   |  

   **Returns:**

   `wx.Colour <wx.Colour.html>`_
 

--------

.. method:: SetHoverColour(colour)

   Sets the colour used to print the label of the hyperlink when the mouse is over the control.

   **Parameters:**

   * `colour` (`wx.Colour <wx.Colour.html>`_) 

--------

.. method:: SetNormalColour(colour)

   Sets the colour used to print the label when the link has never been clicked before (i.e. the link has not been *visited*) and the 
   mouse is not over the control.

   **Parameters:**

   * `colour` (`wx.Colour <wx.Colour.html>`_) 

--------

.. method:: SetURL(url)

   Sets the URL associated with the hyperlink.

   **Parameters:**

   * `url` (string) 

--------

.. method:: SetVisited(visited=True)

   Marks the hyperlink as visited.

   **Parameters:**

   * `visited` (bool) 


.. seealso:: `SetVisitedColour <#SetVisitedColour>`_

--------

.. method:: SetVisitedColour(colour)

   Sets the colour used to print the label when the mouse is not over the control and the link has already been clicked before (i.e. 
   the link has been *visited*).

   **Parameters:**

   * `colour` (`wx.Colour <wx.Colour.html>`_) 

--------

Properties
^^^^^^^^^^


.. attribute:: HoverColour

   See `GetHoverColour <#GetHoverColour>`_ and `SetHoverColour <#SetHoverColour>`_

.. attribute:: NormalColour

   See `GetNormalColour <#GetNormalColour>`_ and `SetNormalColour <#SetNormalColour>`_

.. attribute:: URL

   See `GetURL <#GetURL>`_ and `SetURL <#SetURL>`_

.. attribute:: Visited

   See `GetVisited <#GetVisited>`_ and `SetVisited <#SetVisited>`_

.. attribute:: VisitedColour

   See `GetVisitedColour <#GetVisitedColour>`_ and `SetVisitedColour <#SetVisitedColour>`_