.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc

.. currentmodule:: wx.lib.agw.hyperlink

.. highlight:: python



.. _wx.lib.agw.hyperlink.HyperLinkCtrl:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.hyperlink.HyperLinkCtrl**
==========================================================================================================================================

:class:`HyperLinkCtrl` is a control for wxPython that acts like a hyper
link in a typical browser. Latest features include the ability to
capture your own left, middle, and right click events to perform
your own custom event handling and ability to open link in a new
or current browser window.



|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>HyperLinkCtrl</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.lib.agw.hyperlink.HyperLinkCtrl_inheritance.png" alt="Inheritance diagram of HyperLinkCtrl" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.agw.hyperlink.HyperLinkCtrl.html" title="HyperLinkCtrl is a control for wxPython that acts like a hyper" alt="" coords="5,469,240,499"/> <area shape="rect" id="node2" href="wx.lib.stattext.GenStaticText.html" title="GenStaticText is a generic implementation of wx.StaticText." alt="" coords="21,392,225,421"/> <area shape="rect" id="node3" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="79,315,167,344"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window  is the base class for all windows and represents any visible object on screen." alt="" coords="78,237,167,267"/> <area shape="rect" id="node5" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="62,160,183,189"/> <area shape="rect" id="node6" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="67,83,179,112"/> <area shape="rect" id="node7" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="23,5,105,35"/> <area shape="rect" id="node8" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="130,5,233,35"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.lib.agw.hyperlink.hyperlinkctrl.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/../no_appearance.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/../no_appearance.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|




|super_classes| Known Superclasses
==================================

:class:`wx.lib.stattext.GenStaticText`

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.__init__`                             Default class constructor.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.AutoBrowse`                           Automatically browse to URL when clicked.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.DisplayError`                         Displays an error message (according to the `ReportErrors` parameter) in a
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.DoPopup`                              Sets whether to show popup menu on right click or not.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.EnableRollover`                       Enable/disable rollover.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.GetBold`                              Returns whether the :class:`HyperLinkCtrl` has text in bold or not.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.GetColours`                           Gets the colours for the link, the visited link and the mouse
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.GetLinkCursor`                        Gets the link cursor.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.GetUnderlines`                        Returns if link is underlined, if the mouse rollover is
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.GetURL`                               Retrieve the URL associated to the :class:`HyperLinkCtrl`.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.GetVisited`                           Returns whether a link has been visited or not.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.GotoURL`                              Goto the specified URL.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.OnMouseEvent`                         Handles the ``wx.EVT_MOUSE_EVENTS`` events for :class:`HyperLinkCtrl`.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.OnPopUpCopy`                          Handles the ``wx.EVT_MENU`` event for :class:`HyperLinkCtrl`.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.OpenInSameWindow`                     Open multiple URL in the same window (if possible).
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.ReportErrors`                         Set whether to report browser errors or not.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.SetBold`                              Sets the :class:`HyperLinkCtrl` label in bold text.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.SetColours`                           Sets the colours for the link, the visited link and the mouse rollover.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.SetLinkCursor`                        Sets link cursor properties.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.SetUnderlines`                        Sets whether the text should be underlined or not for new links, visited
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.SetURL`                               Sets the :class:`HyperLinkCtrl` text to the specified URL.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.SetVisited`                           Sets a link as visited.
:meth:`~wx.lib.agw.hyperlink.HyperLinkCtrl.UpdateLink`                           Updates the link, changing text properties if
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: HyperLinkCtrl(StaticText)

   :class:`HyperLinkCtrl` is a control for wxPython that acts like a hyper
   link in a typical browser. Latest features include the ability to
   capture your own left, middle, and right click events to perform
   your own custom event handling and ability to open link in a new
   or current browser window.

   .. method:: __init__(self, parent, id=-1, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name="staticText", URL="")

      Default class constructor.
      
      :param `parent`: the window parent. Must not be ``None``;
      :param `id`: window identifier. A value of -1 indicates a default value;
      :param `label`: the control label;
      :param `pos`: the control position. A value of (-1, -1) indicates a default position,
       chosen by either the windowing system or wxPython, depending on platform;
      :param `size`: the control size. A value of (-1, -1) indicates a default size,
       chosen by either the windowing system or wxPython, depending on platform;
      :param `style`: the window style;
      :param `name`: the window name;
      :param `URL`: a string specifying the url link to navigate to.
      
      .. note:: Pass URL="" to use the label as the url link to navigate to.


   .. method:: AutoBrowse(self, AutoBrowse=True)

      Automatically browse to URL when clicked.
      
      :param `AutoBrowse`: ``True`` to automatically browse to an URL when clicked,
       ``False`` otherwise.
      
      .. note:: Set `AutoBrowse` to ``False`` to receive ``EVT_HYPERLINK_LEFT`` events.


   .. method:: DisplayError(self, ErrorMessage, ReportErrors=True)

      Displays an error message (according to the `ReportErrors` parameter) in a
      :class:`MessageBox`.
      
      :param `ErrorMessage`: a string representing the error to display;
      :param `ReportErrors`: ``True`` to display error dialog if an error occurs
       navigating to the URL.


   .. method:: DoPopup(self, DoPopup=True)

      Sets whether to show popup menu on right click or not.
      
      :param `DoPopup`: ``True`` to show a popup menu on right click, ``False`` otherwise.


   .. method:: EnableRollover(self, EnableRollover=False)

      Enable/disable rollover.
      
      :param `EnableRollover`: ``True`` to enable text effects during rollover,
       ``False`` to disable them.


   .. method:: GetBold(self)

      Returns whether the :class:`HyperLinkCtrl` has text in bold or not. 


   .. method:: GetColours(self)

      Gets the colours for the link, the visited link and the mouse
      rollover.


   .. method:: GetLinkCursor(self)

      Gets the link cursor. 


   .. method:: GetUnderlines(self)

      Returns if link is underlined, if the mouse rollover is
      underlined and if the visited link is underlined.


   .. method:: GetURL(self)

      Retrieve the URL associated to the :class:`HyperLinkCtrl`. 


   .. method:: GetVisited(self)

      Returns whether a link has been visited or not. 


   .. method:: GotoURL(self, URL, ReportErrors=True, NotSameWinIfPossible=False)

      Goto the specified URL.
      
      :param `URL`: the url link we wish to navigate;
      :param `ReportErrors`: Use ``True`` to display error dialog if an error
       occurs navigating to the URL;
      :param `NotSameWinIfPossible`: Use ``True`` to attempt to open the URL
       in new browser window.


   .. method:: OnMouseEvent(self, event)

      Handles the ``wx.EVT_MOUSE_EVENTS`` events for :class:`HyperLinkCtrl`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnPopUpCopy(self, event)

      Handles the ``wx.EVT_MENU`` event for :class:`HyperLinkCtrl`.
      
      :param `event`: a :class:`wx.MenuEvent` event to be processed.
      
      .. note:: This method copies the data from the :class:`HyperLinkCtrl` to the clipboard.


   .. method:: OpenInSameWindow(self, NotSameWinIfPossible=False)

      Open multiple URL in the same window (if possible).
      
      :param `NotSameWinIfPossible`: ``True`` to open an hyperlink in a new browser
       window, ``False`` to use an existing browser window.


   .. method:: ReportErrors(self, ReportErrors=True)

      Set whether to report browser errors or not.
      
      :param `ReportErrors`: Use ``True`` to display error dialog if an error
       occurs navigating to the URL;


   .. method:: SetBold(self, Bold=False)

      Sets the :class:`HyperLinkCtrl` label in bold text.
      
      :param `Bold`: ``True`` to set the :class:`HyperLinkCtrl` label as bold, ``False``
       otherwise.


   .. method:: SetColours(self, link=wx.BLUE, visited=wx.Colour(79, 47, 79), rollover=wx.BLUE)

      Sets the colours for the link, the visited link and the mouse rollover.
      
      - Visited link: VIOLET
      - Rollover: BLUE
      
      :param `link`: a valid :class:`wx.Colour` to use as text foreground for new links
       (default=RED);
      :param `visited`: a valid :class:`wx.Colour` to use as text foreground for visited
       links (default=VIOLET);
      :param `rollover`: a valid :class:`wx.Colour` to use as text foreground for links
       rollovers (default=BLUE).


   .. method:: SetLinkCursor(self, cur=wx.CURSOR_HAND)

      Sets link cursor properties.
      
      :param `cur`: an integer representing a `Cursor`      constant.


   .. method:: SetUnderlines(self, link=True, visited=True, rollover=True)

      Sets whether the text should be underlined or not for new links, visited
      links and rollovers.
      
      :param `link`: ``True`` to set the text of new links as underlined, ``False``
       otherwise;
      :param `visited`: ``True`` to set the text of visited links as underlined,
       ``False`` otherwise;
      :param `rollover`: ``True`` to set the text of rollovers as underlined,
       ``False`` otherwise.


   .. method:: SetURL(self, URL)

      Sets the :class:`HyperLinkCtrl` text to the specified URL.
      
      :param `URL`: the new URL associated with :class:`HyperLinkCtrl`.


   .. method:: SetVisited(self, Visited=False)

      Sets a link as visited.
      
      :param `Visited`: ``True`` to set a link as visited, ``False`` otherwise.


   .. method:: UpdateLink(self, OnRefresh=True)

      Updates the link, changing text properties if:
      
      - User specific setting;
      - Link visited;
      - New link;
      
      :param `OnRefresh`: ``True`` to refresh the control, ``False`` otherwise.