eric7/HelpViewer/HelpViewerWidget.py

# -*- coding: utf-8 -*-

# Copyright (c) 2021 Detlev Offenbach <detlev@die-offenbachs.de>
#

"""
Module implementing an embedded viewer for QtHelp and local HTML files.
"""

from PyQt6.QtCore import pyqtSlot, QUrl
from PyQt6.QtGui import QTextDocument
from PyQt6.QtWidgets import (
    QWidget, QHBoxLayout, QVBoxLayout, QComboBox, QSizePolicy, QStackedWidget,
    QToolButton, QButtonGroup, QAbstractButton
)

import UI.PixmapCache

from .OpenPagesWidget import OpenPagesWidget


class HelpViewerWidget(QWidget):
    """
    Class implementing an embedded viewer for QtHelp and local HTML files.
    """
    def __init__(self, parent=None):
        """
        Constructor
        
        @param parent reference to the parent widget (defaults to None)
        @type QWidget (optional)
        """
        super().__init__(parent)
        self.setObjectName("HelpViewerWidget")
        
        self.__layout = QVBoxLayout()
        self.__layout.setObjectName("MainLayout")
        self.__layout.setContentsMargins(0, 3, 0, 0)
        
        ###################################################################
        
        self.__selectorLayout = QHBoxLayout()
        
        self.__helpSelector = QComboBox(self)
        self.__helpSelector.setSizePolicy(
            QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
        self.__selectorLayout.addWidget(self.__helpSelector)
        self.__populateHelpSelector()
        
        self.__openButton = QToolButton(self)
        self.__openButton.setIcon(UI.PixmapCache.getIcon("open"))
        self.__openButton.setToolTip(self.tr("Open a local file"))
        self.__openButton.clicked.connect(self.__openFile)
        self.__selectorLayout.addWidget(self.__openButton)
        
        self.__layout.addLayout(self.__selectorLayout)
        
        ###################################################################
        
        self.__helpStack = QStackedWidget(self)
        self.__helpStack.setSizePolicy(
            QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)
        self.__layout.addWidget(self.__helpStack)
        
        ###################################################################
        
        self.__helpNavigationStack = QStackedWidget(self)
        self.__helpNavigationStack.setSizePolicy(
            QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
        self.__helpNavigationStack.setMaximumHeight(200)
        self.__layout.addWidget(self.__helpNavigationStack)
        self.__populateNavigationStack()
        
        ###################################################################
        
        self.__buttonLayout = QHBoxLayout()
        
        self.__buttonGroup = QButtonGroup(self)
        self.__buttonGroup.setExclusive(True)
        self.__buttonGroup.buttonClicked.connect(
            self.__selectNavigationWidget)
        
        self.__buttonLayout.addStretch()
        
        self.__openPagesButton = QToolButton(self)
        self.__openPagesButton.setIcon(UI.PixmapCache.getIcon("fileMisc"))
        self.__openPagesButton.setToolTip(self.tr("Show list of open pages"))
        self.__openPagesButton.setCheckable(True)
        self.__buttonGroup.addButton(self.__openPagesButton)
        self.__buttonLayout.addWidget(self.__openPagesButton)
        
        self.__buttonLayout.addStretch()
        
        self.__layout.addLayout(self.__buttonLayout)
        
        ###################################################################
        
        self.setLayout(self.__layout)
        
        self.__openPagesButton.setChecked(True)
        
        self.addPage()
    
    def __populateNavigationStack(self):
        """
        Private method to populate the stack of navigation widgets.
        """
        self.__openPagesList = OpenPagesWidget(self.__helpStack, self)
        self.__helpNavigationStack.addWidget(self.__openPagesList)
        
        # TODO: not yet implemented
    
    @pyqtSlot(QAbstractButton)
    def __selectNavigationWidget(self, button):
        """
        Private slot to select the navigation widget.
        
        @param button reference to the clicked button
        @type QAbstractButton
        """
        if button == self.__openPagesButton:
            self.__helpNavigationStack.setCurrentWidget(self.__openPagesList)
        
        # TODO: not yet implemented
    
    def __populateHelpSelector(self):
        """
        Private method to populate the help selection combo box.
        """
        # TODO: not yet implemented
    
    def searchQtHelp(self, searchExpression):
        """
        Public method to search for a given search expression.
        
        @param searchExpression expression to search for
        @type str
        """
        # TODO: not yet implemented
    
    def activate(self, searchWord=None):
        """
        Public method to activate the widget and search for a given word.
        
        @param searchWord word to search for (defaults to None)
        @type str (optional)
        """
        # TODO: not yet implemented
        
        if searchWord:
            self.searchQtHelp(searchWord)
    
    @pyqtSlot()
    def __openFile(self):
        """
        Private slot to open a local help file (*.html).
        """
        # TODO: not yet implemented
    
    def addPage(self, url=QUrl("about:blank")):
        """
        Public method to add a new help page with the given URL.
        
        @param url requested URL (defaults to QUrl("about:blank"))
        @type QUrl (optional)
        """
        try:
            from .HelpViewerImpl_qwe import HelpViewerImpl_qwe
            viewer = HelpViewerImpl_qwe(self)
        except ImportError:
            from .HelpViewerImpl_qtb import HelpViewerImpl_qtb
            viewer = HelpViewerImpl_qtb(self)
        
        self.__helpStack.addWidget(viewer)
        self.__openPagesList.addPage(viewer)
        
        viewer.setSource(url, QTextDocument.ResourceType.HtmlResource)