Software Público Brasileiro

# --------------------------------------------------------------------------- #
# HYPERLINKSCTRL wxPython IMPLEMENTATION
# Ported From Angelo Mandato C++ Code By:
#
# Andrea Gavana, @ 27 Mar 2005
# Latest Revision: 14 Mar 2012, 21.00 GMT
#
#
# Original Web Site (For The C++ Code):
#
# http://www.spaceblue.com/codedetail.php?CodeID=7
#
#
# Thanks to E. A. Tacao for his nice suggestions and improvements of the code.
#
# For all kind of problems, requests of enhancements and bug reports, please
# write to me at:
#
# andrea.gavana@gmail.com
# andrea.gavana@maerskoil.com
#
# Or, obviously, to the wxPython mailing list!!!
#
#
# End Of Comments
# --------------------------------------------------------------------------- #

"""
:class:`HyperLinkCtrl` is a control for wxPython that acts like a hyper link
in a typical browser.


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

: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.

Special thanks to Robin Dunn for the event binder for the 3 mouse buttons.


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.hyperlink as hl

    class MyFrame(wx.Frame):

        def __init__(self, parent):
        
            wx.Frame.__init__(self, parent, -1, "HyperLink Demo")

            panel = wx.Panel(self, -1)

            # Default Web links:
            hyper1 = hl.HyperLinkCtrl(panel, -1, "wxPython Main Page", pos=(100, 100),
                                      URL="http://www.wxpython.org/")
            
            
            # Web link with underline rollovers, opens in same window
            hyper2 = hl.HyperLinkCtrl(panel, -1, "My Home Page", pos=(100, 150),
                                      URL="http://xoomer.virgilio.it/infinity77/")
                                      
            hyper2.AutoBrowse(False)
            hyper2.SetColours("BLUE", "BLUE", "BLUE")
            hyper2.EnableRollover(True)
            hyper2.SetUnderlines(False, False, True)
            hyper2.SetBold(True)
            hyper2.OpenInSameWindow(True)
            hyper2.SetToolTip(wx.ToolTip("Hello World!"))
            hyper2.UpdateLink()
        

    # our normal wxApp-derived class, as usual

    app = wx.App(0)

    frame = MyFrame(None)
    app.SetTopWindow(frame)
    frame.Show()

    app.MainLoop()
    


Window Styles
=============

`No particular window styles are available for this class.`


Events Processing
=================

This class processes the following events:

======================== ==================================================
Event Name               Description
======================== ==================================================
``EVT_HYPERLINK_LEFT``   Responds to a left mouse button event. Sent when the left mouse button is clicked, but only if `AutoBrowse` is set to ``False``.
``EVT_HYPERLINK_MIDDLE`` Responds to a middle mouse button event. Sent when the middle mouse button is clicked.
``EVT_HYPERLINK_RIGHT``  Handles a right mouse button event. Sent when the right mouse button is clicked, but only if `DoPopup` is set to ``False``.
======================== ==================================================


License And Version
===================

:class:`HyperLinkCtrl` is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 14 Mar 2012, 21.00 GMT

Version 0.6

"""

import wx
from wx.lib.stattext import GenStaticText as StaticText

# Import the useful webbrowser module for platform-independent results
import webbrowser

# Set no delay time to open the web page
webbrowser.PROCESS_CREATION_DELAY = 0

# To show a popup that copies the hyperlinks on the clipboard
wxHYPERLINKS_POPUP_COPY = 1000
""" Flag used to show a popup that copies the hyperlinks on the clipboard. """


#-----------------------------------#
#        HyperLinksEvents
#-----------------------------------#

# wxEVT_HYPERLINK_LEFT: Respond To A Left Mouse Button Event
# wxEVT_HYPERLINK_MIDDLE: Respond To A Middle Mouse Button Event
# wxEVT_HYPERLINK_RIGHT: Respond To A Right Mouse Button Event

wxEVT_HYPERLINK_LEFT = wx.NewEventType()
wxEVT_HYPERLINK_MIDDLE = wx.NewEventType()
wxEVT_HYPERLINK_RIGHT = wx.NewEventType()

EVT_HYPERLINK_LEFT = wx.PyEventBinder(wxEVT_HYPERLINK_LEFT, 1)
""" Responds to a left mouse button event. Sent when the left mouse button is""" \
""" clicked, but only if `AutoBrowse` is set to ``False``. """
EVT_HYPERLINK_MIDDLE = wx.PyEventBinder(wxEVT_HYPERLINK_MIDDLE, 1)
""" Responds to a middle mouse button event. Sent when the middle mouse button is clicked. """
EVT_HYPERLINK_RIGHT = wx.PyEventBinder(wxEVT_HYPERLINK_RIGHT, 1)
""" Handles a right mouse button event. Sent when the right mouse button is""" \
""" clicked, but only if `DoPopup` is set to ``False``. """


# ------------------------------------------------------------
# This class implements the event listener for the hyperlinks
# ------------------------------------------------------------

class HyperLinkEvent(wx.PyCommandEvent):
    """
    Event object sent in response to clicking on a :class:`HyperLinkCtrl`.
    """

    def __init__(self, eventType, eventId):
        """
        Default Class Constructor.

        :param `eventType`: the event type;
        :param `eventId`: the event identifier.
        """
        
        wx.PyCommandEvent.__init__(self, eventType, eventId)
        self._eventType = eventType


    def SetPosition(self, pos):
        """
        Sets the event position.

        :param `pos`: an instance of :class:`Point`.        
        """
        
        self._pos = pos


    def GetPosition(self):
        """ Returns the event position. """
        
        return self._pos


# -------------------------------------------------
# This is the main HyperLinkCtrl implementation
# it user the StatiText from wx.lib.stattext
# because of its "quasi-dynamic" behavior
# -------------------------------------------------

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.
    """
    
    def __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.
        """
        
        StaticText.__init__(self, parent, id, label, pos, size,
                            style, name)

        if URL.strip() == "":
            self._URL = label
        else:
            self._URL = URL

        # Set Tooltip
        self.SetToolTip(wx.ToolTip(self._URL))

        # Set default properties
        # default: True
        self.ReportErrors()

        # default: True, True, True
        self.SetUnderlines()

        # default: blue, violet, blue        
        self.SetColours()

        # default: False
        self.SetVisited()

        # default: False 
        self.EnableRollover()

        # default: False        
        self.SetBold()

        # default: wx.CURSOR_HAND        
        self.SetLinkCursor() 

        # default True
        self.AutoBrowse()

        # default True        
        self.DoPopup() 

        # default False
        self.OpenInSameWindow()

        # Set control properties and refresh
        self.UpdateLink(True)

        self.Bind(wx.EVT_MOUSE_EVENTS, self.OnMouseEvent)
        self.Bind(wx.EVT_MOTION, self.OnMouseEvent)        
    
    
    def 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
         occurrs navigating to the URL;
        :param `NotSameWinIfPossible`: Use ``True`` to attempt to open the URL
         in new browser window.
        """
    
        logOff = wx.LogNull()

        try:            
            webbrowser.open(URL, new=NotSameWinIfPossible)
            self.SetVisited(True)
            self.UpdateLink(True)

            return True
        
        except:            
            self.DisplayError("Unable To Launch Browser.", ReportErrors)
            return False


    def OnMouseEvent(self, event):
        """
        Handles the ``wx.EVT_MOUSE_EVENTS`` events for :class:`HyperLinkCtrl`.

        :param `event`: a :class:`MouseEvent` event to be processed.        
        """

        if event.Moving():
            # Mouse Is Moving On The StaticText
            # Set The Hand Cursor On The Link
            self.SetCursor(self._CursorHand)

            if self._EnableRollover:
                fontTemp = self.GetFont()
                fontTemp.SetUnderlined(self._RolloverUnderline)
                if self._Bold:
                    fontTemp.SetWeight(wx.BOLD)
                    
                needRefresh = False

                if self.GetFont() != fontTemp:
                    self.SetFont(fontTemp)
                    needRefresh = True

                if self.GetForegroundColour() != self._LinkRolloverColour:
                    self.SetForegroundColour(self._LinkRolloverColour)
                    needRefresh = True

                if needRefresh:
                    self.Refresh()
            
        else:            
            # Restore The Original Cursor            
            self.SetCursor(wx.NullCursor)
            if self._EnableRollover:
                self.UpdateLink(True)
            
            if event.LeftUp():
                # Left Button Was Pressed
                if self._AutoBrowse:                    
                    self.GotoURL(self._URL, self._ReportErrors,
                                 self._NotSameWinIfPossible)

                else:
                    eventOut = HyperLinkEvent(wxEVT_HYPERLINK_LEFT, self.GetId())
                    eventOut.SetEventObject(self)
                    eventOut.SetPosition(event.GetPosition())
                    self.GetEventHandler().ProcessEvent(eventOut)

                self.SetVisited(True)

            elif event.RightUp():
                # Right Button Was Pressed
                if self._DoPopup:
                    # Popups A Menu With The "Copy HyperLynks" Feature
                    menuPopUp = wx.Menu("", wx.MENU_TEAROFF)
                    menuPopUp.Append(wxHYPERLINKS_POPUP_COPY, "Copy HyperLink")
                    self.Bind(wx.EVT_MENU, self.OnPopUpCopy, id=wxHYPERLINKS_POPUP_COPY)
                    self.PopupMenu(menuPopUp, wx.Point(event.X, event.Y))
                    menuPopUp.Destroy()
                    self.Unbind(wx.EVT_MENU, id=wxHYPERLINKS_POPUP_COPY)
                    
                else:                    
                    eventOut = HyperLinkEvent(wxEVT_HYPERLINK_RIGHT, self.GetId())
                    eventOut.SetEventObject(self)
                    eventOut.SetPosition(event.GetPosition())
                    self.GetEventHandler().ProcessEvent(eventOut)

            elif event.MiddleUp():
                # Middle Button Was Pressed
                eventOut = HyperLinkEvent(wxEVT_HYPERLINK_MIDDLE, self.GetId())
                eventOut.SetEventObject(self)
                eventOut.SetPosition(event.GetPosition())
                self.GetEventHandler().ProcessEvent(eventOut)

        event.Skip()


    def OnPopUpCopy(self, event):
        """
        Handles the ``wx.EVT_MENU`` event for :class:`HyperLinkCtrl`.

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

        wx.TheClipboard.UsePrimarySelection(False)
        if not wx.TheClipboard.Open():
            return
        data = wx.TextDataObject(self._URL)
        wx.TheClipboard.SetData(data)
        wx.TheClipboard.Close()


    def 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.        
        
        """

        fontTemp = self.GetFont()

        if self._Visited:
            self.SetForegroundColour(self._VisitedColour)
            fontTemp.SetUnderlined(self._VisitedUnderline)
        
        else:

            self.SetForegroundColour(self._LinkColour)
            fontTemp.SetUnderlined(self._LinkUnderline)

        if self._Bold:
            fontTemp.SetWeight(wx.BOLD)

        if self.GetFont() != fontTemp:
            self.SetFont(fontTemp)

        self.Refresh(OnRefresh)            


    def 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 occurrs
         navigating to the URL.
        """
        
        if ReportErrors:
            wx.MessageBox(ErrorMessage, "HyperLinks Error", wx.OK | wx.CENTRE | wx.ICON_ERROR)


    def SetColours(self, link=wx.Colour(0, 0, 255), visited=wx.Colour(79, 47, 79),
                   rollover=wx.Colour(0, 0, 255)):
        """
        Sets the colours for the link, the visited link and the mouse rollover.

        - Visited link: VIOLET
        - Rollover: BLUE

        :param `link`: a valid :class:`Colour` to use as text foreground for new links
         (default=RED);
        :param `visited`: a valid :class:`Colour` to use as text foreground for visited
         links (default=VIOLET);
        :param `rollover`: a valid :class:`Colour` to use as text foreground for links
         rollovers (default=BLUE).
        """
        
        self._LinkColour = link
        self._VisitedColour = visited
        self._LinkRolloverColour = rollover

    
    def GetColours(self):
        """
        Gets the colours for the link, the visited link and the mouse
        rollover.
        """
        
        return self._LinkColour, self._VisitedColour, self._LinkRolloverColour

    
    def 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.
        """
        
        self._LinkUnderline = link
        self._RolloverUnderline = rollover
        self._VisitedUnderline = visited


    def GetUnderlines(self):
        """
        Returns if link is underlined, if the mouse rollover is
        underlined and if the visited link is underlined.
        """
        
        return self._LinkUnderline, self._RolloverUnderline, self._VisitedUnderline
    

    def SetLinkCursor(self, cur=wx.CURSOR_HAND):
        """
        Sets link cursor properties.

        :param `cur`: an integer representing a :class:`StockCursor` constant.
        """
        
        self._CursorHand = wx.StockCursor(cur)


    def GetLinkCursor(self):
        """ Gets the link cursor. """
        
        return self._CursorHand


    def SetVisited(self, Visited=False):
        """
        Sets a link as visited.

        :param `Visited`: ``True`` to set a link as visited, ``False`` otherwise.
        """
        
        self._Visited = Visited

        
    def GetVisited(self):
        """ Returns whether a link has been visited or not. """
        
        return self._Visited


    def 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.
        """
        
        self._Bold = Bold

        
    def GetBold(self):
        """ Returns whether the :class:`HyperLinkCtrl` has text in bold or not. """
        
        return self._Bold


    def SetURL(self, URL):
        """
        Sets the :class:`HyperLinkCtrl` text to the specified URL.

        :param `URL`: the new URL associated with :class:`HyperLinkCtrl`.
        """
        
        self._URL = URL

        
    def GetURL(self):
        """ Retrieve the URL associated to the :class:`HyperLinkCtrl`. """
        
        return self._URL


    def 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.
        """
        
        self._NotSameWinIfPossible = NotSameWinIfPossible


    def EnableRollover(self, EnableRollover=False):
        """
        Enable/disable rollover.

        :param `EnableRollover`: ``True`` to enable text effects during rollover,
         ``False`` to disable them.
        """
        
        self._EnableRollover = EnableRollover

    
    def ReportErrors(self, ReportErrors=True):
        """
        Set whether to report browser errors or not.

        :param `ReportErrors`: Use ``True`` to display error dialog if an error
         occurrs navigating to the URL;
        """
        
        self._ReportErrors = ReportErrors


    def 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.
        """
        
        self._AutoBrowse = AutoBrowse


    def 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.
        """
        
        self._DoPopup = DoPopup