helpviewer.cpp

Go to the documentation of this file.

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
 
#include "helpviewer.h"
#include "helpviewerimpl.h"
 
#include "helpenginewrapper.h"
#include "openpagesmanager.h"
#include "tracer.h"
 
#include <QtCore/QFileInfo>
#include <QtCore/QMimeDatabase>
#include <QtCore/QStringBuilder>
#include <QtCore/QTemporaryFile>
#include <QtCore/QXmlStreamReader>
#include <QtCore/QXmlStreamWriter>
 
#include <QtGui/QDesktopServices>
#if QT_CONFIG(clipboard)
#include <QtGui/QClipboard>
#endif
#include <QtGui/QGuiApplication>
#include <QtGui/QImageReader>
#include <QtGui/QStyleHints>
#include <QtGui/QWheelEvent>
 
#include <QtWidgets/QMenu>
#include <QtWidgets/QScrollBar>
#include <QtWidgets/QVBoxLayout>
 
#include <QtHelp/QHelpEngineCore>
 
#include <qlitehtmlwidget.h>
 
QT_BEGIN_NAMESPACE
 
using namespace Qt::StringLiterals;
 
const int kMaxHistoryItems = 20;
constexpr bool kHasClipboard = QT_CONFIG(clipboard);
 
static void setClipboardText(const QString &text)
{
#if QT_CONFIG(clipboard)
    QGuiApplication::clipboard()->setText(text);
#else
    Q_UNUSED(text)
#endif
}
 
const struct ExtensionMap {
    const char *extension;
    const char *mimeType;
} extensionMap[] = {
    { ".bmp", "image/bmp" },
    { ".css", "text/css" },
    { ".gif", "image/gif" },
    { ".html", "text/html" },
    { ".htm", "text/html" },
    { ".ico", "image/x-icon" },
    { ".jpeg", "image/jpeg" },
    { ".jpg", "image/jpeg" },
    { ".js", "application/x-javascript" },
    { ".mng", "video/x-mng" },
    { ".pbm", "image/x-portable-bitmap" },
    { ".pgm", "image/x-portable-graymap" },
    { ".pdf", nullptr },
    { ".png", "image/png" },
    { ".ppm", "image/x-portable-pixmap" },
    { ".rss", "application/rss+xml" },
    { ".svg", "image/svg+xml" },
    { ".svgz", "image/svg+xml" },
    { ".text", "text/plain" },
    { ".tif", "image/tiff" },
    { ".tiff", "image/tiff" },
    { ".txt", "text/plain" },
    { ".xbm", "image/x-xbitmap" },
    { ".xml", "text/xml" },
    { ".xpm", "image/x-xpm" },
    { ".xsl", "text/xsl" },
    { ".xhtml", "application/xhtml+xml" },
    { ".wml", "text/vnd.wap.wml" },
    { ".wmlc", "application/vnd.wap.wmlc" },
    { "about:blank", nullptr },
    { nullptr, nullptr }
};
 
static void setLight(QWidget *widget)
{
    // Make docs' contents visible in dark theme
    QPalette p = widget->palette();
    p.setColor(QPalette::Inactive, QPalette::Highlight,
               p.color(QPalette::Active, QPalette::Highlight));
    p.setColor(QPalette::Inactive, QPalette::HighlightedText,
               p.color(QPalette::Active, QPalette::HighlightedText));
    p.setColor(QPalette::Base, Qt::white);
    p.setColor(QPalette::Text, Qt::black);
    widget->setPalette(p);
}
 
static bool isDarkTheme()
{
    // Either Qt realizes that it is dark, or the palette exposes it, by having
    // the window background darker than the text
    return QGuiApplication::styleHints()->colorScheme() == Qt::ColorScheme::Dark
            || QGuiApplication::palette().color(QPalette::Base).lightnessF()
            < QGuiApplication::palette().color(QPalette::Text).lightnessF();
}
 
static void setPaletteFromApp(QWidget *widget)
{
    QPalette appPalette = QGuiApplication::palette();
    // Detach the palette from the application palette, so it doesn't change directly when the
    // application palette changes.
    // That ensures that if the system is dark, and dark documentation is show, and the user
    // switches the system to a light theme, that the documentation background stays dark for the
    // visible page until either the we got informed by the change in application palette, or the
    // user switched pages
    appPalette.setColor(QPalette::Base, appPalette.color(QPalette::Base));
    widget->setPalette(appPalette);
}
 
static QByteArray addDarkThemeToSvg(const QByteArray &data)
{
    // Parse the SVG file and attach an attribute to the svg element.
    QXmlStreamReader reader(data);
 
    // Assume that the first element is the svg element.
    if (reader.readNextStartElement()) {
        if (reader.name() == "svg") {
            // The character offset refers to the character after the
            // element start.
            qint64 rest = reader.characterOffset();
 
            // Write the svg element to a new byte array, adding an attribute
            // if the theme is dark.
            QByteArray newData;
            QXmlStreamWriter writer(&newData);
 
            writer.writeStartDocument();
            writer.writeStartElement("svg");
            writer.writeAttributes(reader.attributes());
            writer.writeAttribute("class", "dark");
 
            // Ensure that the opening tag for the svg element is closed.
            writer.writeCharacters("");
 
            // Return the new document start and the rest of the original,
            // discarding the processing instructions before the svg element.
            return newData + data.mid(rest);
        }
    }
 
    // The entire file was read without finding an svg element, or an error
    // occurred, so just return the original data.
    return data;
}
 
static QByteArray getData(const QUrl &url, QWidget *widget)
{
    // This is a hack for Qt documentation,
    // which decides to use a simpler CSS if the viewer does not have JavaScript
    // which was a hack to decide if we are viewing in QTextBrowser or QtWebEngine et al.
    // Force it to use the "normal" offline CSS even without JavaScript, since litehtml can
    // handle that, and inject a dark themed CSS into Qt documentation for dark Qt Creator themes
    QUrl actualUrl = url;
    QString path = url.path(QUrl::FullyEncoded);
    static const char simpleCss[] = "/offline-simple.css";
    if (path.endsWith(simpleCss)) {
        if (isDarkTheme()) {
            // check if dark CSS is shipped with documentation
            QString darkPath = path;
            darkPath.replace(simpleCss, "/offline-dark.css");
            actualUrl.setPath(darkPath);
            QByteArray data = HelpEngineWrapper::instance().fileData(actualUrl);
            if (!data.isEmpty()) {
                // we found the dark style
                // set background dark (by using app palette)
                setPaletteFromApp(widget);
                return data;
            }
        }
        path.replace(simpleCss, "/offline.css");
        actualUrl.setPath(path);
    }
 
    if (actualUrl.isValid()) {
        const QByteArray data = HelpEngineWrapper::instance().fileData(actualUrl);
        if (isDarkTheme() && path.endsWith(".svg"))
            return addDarkThemeToSvg(data);
        else
            return data;
    }
 
    const bool isAbout = (actualUrl.toString() == "about:blank"_L1);
    return isAbout ? HelpViewerImpl::AboutBlank.toUtf8()
                   : HelpViewerImpl::PageNotFoundMessage.arg(url.toString()).toUtf8();
}
 
class HelpViewerPrivate
{
public:
    struct HistoryItem
    {
        QUrl url;
        QString title;
        int vscroll;
    };
    HistoryItem currentHistoryItem() const;
    void setSourceInternal(const QUrl &url, int *vscroll = nullptr, bool reload = false);
    void incrementZoom(int steps);
    void applyZoom(int percentage);
    void openInNewPage(const QUrl &url);
    void showContextMenu(const QPoint &pos, const QUrl &link);
 
    HelpViewer *q = nullptr;
    QLiteHtmlWidget *m_viewer = nullptr;
    std::vector<HistoryItem> m_backItems;
    std::vector<HistoryItem> m_forwardItems;
    int m_fontZoom = 100; // zoom percentage
    QUrl m_highlightedLink;
};
 
HelpViewerPrivate::HistoryItem HelpViewerPrivate::currentHistoryItem() const
{
    return { m_viewer->url(), m_viewer->title(), m_viewer->verticalScrollBar()->value() };
}
 
void HelpViewerPrivate::setSourceInternal(const QUrl &url, int *vscroll, bool reload)
{
    QGuiApplication::setOverrideCursor(QCursor(Qt::WaitCursor));
 
    const bool isHelp = (url.toString() == "help"_L1);
    const QUrl resolvedUrl = (isHelp ? QUrl(HelpViewerImpl::LocalHelpFile)
                                     : HelpEngineWrapper::instance().findFile(url));
 
    QUrl currentUrlWithoutFragment = m_viewer->url();
    currentUrlWithoutFragment.setFragment({});
    QUrl newUrlWithoutFragment = resolvedUrl;
    newUrlWithoutFragment.setFragment({});
 
    m_viewer->setUrl(resolvedUrl);
    if (currentUrlWithoutFragment != newUrlWithoutFragment || reload) {
        // Users can register arbitrary documentation, so we do not expect the documentation to
        // support dark themes, and start with light palette.
        // We override this if we find Qt's dark style
        setLight(q);
        QMimeDatabase mimeDb;
        const QMimeType mimeType = mimeDb.mimeTypeForFile(url.fileName(),
                                                          QMimeDatabase::MatchExtension);
        if (QImageReader::supportedMimeTypes().contains(mimeType.name().toUtf8()))
            m_viewer->setHtml(QString("<img src=\"%1\"/>").arg(QString::fromUtf8(url.toEncoded())));
        else
            m_viewer->setHtml(QString::fromUtf8(getData(resolvedUrl, q)));
 
    }
    if (vscroll)
        m_viewer->verticalScrollBar()->setValue(*vscroll);
    else
        m_viewer->scrollToAnchor(resolvedUrl.fragment(QUrl::FullyEncoded));
 
    QGuiApplication::restoreOverrideCursor();
 
    emit q->sourceChanged(q->source());
    emit q->loadFinished();
    emit q->titleChanged();
}
 
void HelpViewerPrivate::incrementZoom(int steps)
{
    const int incrementPercentage = 10 * steps; // 10 percent increase by single step
    const int previousZoom = m_fontZoom;
    applyZoom(previousZoom + incrementPercentage);
}
 
void HelpViewerPrivate::applyZoom(int percentage)
{
    const int newZoom = qBound(10, percentage, 300);
    if (newZoom == m_fontZoom)
        return;
    m_fontZoom = newZoom;
    m_viewer->setZoomFactor(newZoom / 100.0);
}
 
void HelpViewerPrivate::openInNewPage(const QUrl &url)
{
    if (!url.isEmpty() && url.isValid())
        OpenPagesManager::instance()->createPage(url);
}
 
void HelpViewerPrivate::showContextMenu(const QPoint &pos, const QUrl &link)
{
    QMenu menu;
    if (!link.isEmpty() && link.isValid()) {
        menu.addAction(HelpViewer::tr("Open Link"), q, [this, link] { q->setSource(link); });
        menu.addAction(HelpViewer::tr("Open Link in New Tab\tCtrl+LMB"), q,
                       [this, link] { openInNewPage(link); });
        if (kHasClipboard) {
            menu.addAction(HelpViewer::tr("Copy &Link Location"), q,
                           [link] { setClipboardText(link.toString()); });
        }
    } else if (kHasClipboard && !q->selectedText().isEmpty()) {
        menu.addAction(HelpViewer::tr("Copy"), q, [this] { setClipboardText(q->selectedText()); });
    } else {
        menu.addAction(HelpViewer::tr("Reload"), q, &HelpViewer::reload);
    }
    menu.exec(m_viewer->viewport()->mapToGlobal(pos));
}
 
HelpViewer::HelpViewer(qreal zoom, QWidget *parent)
    : QWidget(parent)
    , d(new HelpViewerPrivate)
{
    auto layout = new QVBoxLayout;
    d->q = this;
    d->m_viewer = new QLiteHtmlWidget(this);
    d->m_viewer->setResourceHandler([this](const QUrl &url) { return getData(url, this); });
    d->m_viewer->viewport()->installEventFilter(this);
    const int zoomPercentage = zoom == 0 ? 100 : zoom * 100;
    d->applyZoom(zoomPercentage);
    connect(d->m_viewer, &QLiteHtmlWidget::linkClicked, this, [this](const QUrl &url) {
        if (QGuiApplication::keyboardModifiers() & Qt::ControlModifier)
            d->openInNewPage(url);
        else
            setSource(url);
    });
    connect(d->m_viewer, &QLiteHtmlWidget::linkHighlighted, this, [this](const QUrl &url) {
        d->m_highlightedLink = url;
        emit highlighted(url);
    });
    connect(d->m_viewer, &QLiteHtmlWidget::contextMenuRequested, this,
            [this](const QPoint &pos, const QUrl &link) { d->showContextMenu(pos, link); });
#if QT_CONFIG(clipboard)
    connect(d->m_viewer, &QLiteHtmlWidget::copyAvailable, this, &HelpViewer::copyAvailable);
#endif
    setLayout(layout);
    layout->setContentsMargins(0, 0, 0, 0);
    layout->addWidget(d->m_viewer, 10);
 
    // If the platform supports it, changes of color scheme light/dark take effect during runtime:
    connect(
            QGuiApplication::styleHints(), &QStyleHints::colorSchemeChanged, this,
            [this] {
                int vscroll = d->m_viewer->verticalScrollBar()->value();
                d->setSourceInternal(source(), &vscroll, /*reload*/ true);
            },
            // Queue to make sure that the palette is actually applied on the application
            Qt::QueuedConnection);
}
 
HelpViewer::~HelpViewer()
{
    delete d;
}
 
QFont HelpViewer::viewerFont() const
{
    return d->m_viewer->defaultFont();
}
 
void HelpViewer::setViewerFont(const QFont &font)
{
    d->m_viewer->setDefaultFont(font);
}
 
void HelpViewer::scaleUp()
{
    d->incrementZoom(1);
}
 
void HelpViewer::scaleDown()
{
    d->incrementZoom(-1);
}
 
void HelpViewer::resetScale()
{
    d->applyZoom(100);
}
 
qreal HelpViewer::scale() const
{
    return d->m_viewer->zoomFactor();
}
 
QString HelpViewer::title() const
{
    return d->m_viewer->title();
}
 
QUrl HelpViewer::source() const
{
    return d->m_viewer->url();
}
 
void HelpViewer::reload()
{
    doSetSource(source(), true);
}
 
void HelpViewer::setSource(const QUrl &url)
{
    doSetSource(url, false);
}
 
void HelpViewer::doSetFocus()
{
    d->m_viewer->setFocus();
}
 
void HelpViewer::doSetSource(const QUrl &url, bool reload)
{
    if (launchWithExternalApp(url))
        return;
 
    d->m_forwardItems.clear();
    emit forwardAvailable(false);
    if (d->m_viewer->url().isValid()) {
        d->m_backItems.push_back(d->currentHistoryItem());
        while (d->m_backItems.size() > kMaxHistoryItems) // this should trigger only once anyhow
            d->m_backItems.erase(d->m_backItems.begin());
        emit backwardAvailable(true);
    }
 
    d->setSourceInternal(url, nullptr, reload);
}
 
#if QT_CONFIG(printer)
void HelpViewer::print(QPrinter *printer)
{
    d->m_viewer->print(printer);
}
#endif
 
QString HelpViewer::selectedText() const
{
    return d->m_viewer->selectedText();
}
 
bool HelpViewer::isForwardAvailable() const
{
    return !d->m_forwardItems.empty();
}
 
bool HelpViewer::isBackwardAvailable() const
{
    return !d->m_backItems.empty();
}
 
static QTextDocument::FindFlags textDocumentFlagsForFindFlags(HelpViewer::FindFlags flags)
{
    QTextDocument::FindFlags textDocFlags;
    if (flags & HelpViewer::FindBackward)
        textDocFlags |= QTextDocument::FindBackward;
    if (flags & HelpViewer::FindCaseSensitively)
        textDocFlags |= QTextDocument::FindCaseSensitively;
    return textDocFlags;
}
 
bool HelpViewer::findText(const QString &text, FindFlags flags, bool incremental, bool fromSearch)
{
    Q_UNUSED(fromSearch);
    return d->m_viewer->findText(text, textDocumentFlagsForFindFlags(flags), incremental);
}
 
#if QT_CONFIG(clipboard)
void HelpViewer::copy()
{
    QGuiApplication::clipboard()->setText(selectedText());
}
#endif
 
void HelpViewer::home()
{
    setSource(QUrl(HelpEngineWrapper::instance().homePage()));
}
 
void HelpViewer::forward()
{
    HelpViewerPrivate::HistoryItem nextItem = d->currentHistoryItem();
    if (d->m_forwardItems.empty())
        return;
    d->m_backItems.push_back(nextItem);
    nextItem = d->m_forwardItems.front();
    d->m_forwardItems.erase(d->m_forwardItems.begin());
 
    emit backwardAvailable(isBackwardAvailable());
    emit forwardAvailable(isForwardAvailable());
    d->setSourceInternal(nextItem.url, &nextItem.vscroll);
}
 
void HelpViewer::backward()
{
    HelpViewerPrivate::HistoryItem previousItem = d->currentHistoryItem();
    if (d->m_backItems.empty())
        return;
    d->m_forwardItems.insert(d->m_forwardItems.begin(), previousItem);
    previousItem = d->m_backItems.back();
    d->m_backItems.pop_back();
 
    emit backwardAvailable(isBackwardAvailable());
    emit forwardAvailable(isForwardAvailable());
    d->setSourceInternal(previousItem.url, &previousItem.vscroll);
}
 
bool HelpViewer::eventFilter(QObject *src, QEvent *event)
{
    if (event->type() == QEvent::Wheel) {
        auto we = static_cast<QWheelEvent *>(event);
        if (we->modifiers() == Qt::ControlModifier) {
            we->accept();
            const int deltaY = we->angleDelta().y();
            if (deltaY != 0)
                d->incrementZoom(deltaY / 120);
            return true;
        }
    } else if (event->type() == QEvent::MouseButtonRelease) {
        // Ctrl+LMB is handled when the link is clicked, as litehtml only reacts on the left button.
        auto me = static_cast<QMouseEvent *>(event);
        if (me->button() == Qt::MiddleButton && !d->m_highlightedLink.isEmpty()
            && d->m_highlightedLink.isValid()) {
            me->accept();
            d->openInNewPage(d->m_highlightedLink);
            return true;
        }
    }
    return QWidget::eventFilter(src, event);
}
 
bool HelpViewer::isLocalUrl(const QUrl &url)
{
    TRACE_OBJ
    const QString &scheme = url.scheme();
    return scheme.isEmpty()
        || scheme == "file"_L1
        || scheme == "qrc"_L1
        || scheme == "data"_L1
        || scheme == "qthelp"_L1
        || scheme == "about"_L1;
}
 
bool HelpViewer::canOpenPage(const QString &path)
{
    TRACE_OBJ
    return !mimeFromUrl(QUrl::fromLocalFile(path)).isEmpty();
}
 
QString HelpViewer::mimeFromUrl(const QUrl &url)
{
    TRACE_OBJ
    const QString &path = url.path();
    const int index = path.lastIndexOf(u'.');
    const QByteArray &ext = path.mid(index).toUtf8().toLower();
 
    const ExtensionMap *e = extensionMap;
    while (e->extension) {
        if (ext == e->extension)
            return QLatin1StringView(e->mimeType);
        ++e;
    }
    return "application/octet-stream"_L1;
}
 
bool HelpViewer::launchWithExternalApp(const QUrl &url)
{
    TRACE_OBJ
    if (isLocalUrl(url)) {
        const HelpEngineWrapper &helpEngine = HelpEngineWrapper::instance();
        const QUrl &resolvedUrl = helpEngine.findFile(url);
        if (!resolvedUrl.isValid())
            return false;
 
        const QString& path = resolvedUrl.toLocalFile();
        if (!canOpenPage(path)) {
            QTemporaryFile tmpTmpFile;
            if (!tmpTmpFile.open())
                return false;
 
            const QString &extension = QFileInfo(path).completeSuffix();
            QFile actualTmpFile(tmpTmpFile.fileName() % "."_L1 % extension);
            if (!actualTmpFile.open(QIODevice::ReadWrite | QIODevice::Truncate))
                return false;
 
            actualTmpFile.write(helpEngine.fileData(resolvedUrl));
            actualTmpFile.close();
            return QDesktopServices::openUrl(QUrl::fromLocalFile(actualTmpFile.fileName()));
        }
        return false;
    }
    return QDesktopServices::openUrl(url);
}
 
QT_END_NAMESPACE