documentation.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 2018-2022 The Octave Project Developers
//
// See the file COPYRIGHT.md in the top-level directory of this
// distribution or <https://octave.org/copyright/>.
//
// This file is part of Octave.
//
// Octave is free software: you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Octave is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Octave; see the file COPYING.  If not, see
// <https://www.gnu.org/licenses/>.
//
////////////////////////////////////////////////////////////////////////
 
#if ! defined (octave_documentation_h)
#define octave_documentation_h 1
 
#include <QComboBox>
#include <QMenu>
#include <QShortcut>
#include <QSplitter>
#include <QTextBrowser>
#include <QToolBar>
#include <QListWidget>
#include <QToolButton>
#include <QWidget>
#include <QtHelp/QHelpEngine>
 
#include "gui-settings.h"
 
namespace octave
{
  class base_qobject;
  class documentation;
  class documentation_bookmarks;
 
  //! Documentation browser derived from Textbrowser
 
  class documentation_browser : public QTextBrowser
  {
    Q_OBJECT
 
  public:
 
    documentation_browser (QHelpEngine *help_engine, QWidget *parent = nullptr);
    ~documentation_browser (void) = default;
 
    virtual QVariant loadResource (int type, const QUrl& url);
 
  public slots:
 
    void handle_index_clicked (const QUrl& url,
                               const QString& keyword = QString ());
    void notice_settings (const gui_settings *settings);
    void save_settings (gui_settings *settings);
 
    //! Zooming in and out while taking care of the zoom level
    //!@{
    void zoom_in (void);
    void zoom_out (void);
    void zoom_original (void);
    //!@}
 
  protected:
 
    void wheelEvent (QWheelEvent *we);
 
  private:
 
    QHelpEngine *m_help_engine;
 
    //! Store the current zoom level
    int m_zoom_level;
 
    //! Minimal and maximal zoom level avoiding calling
    //! zoom_in and zoom_out without actually zooming but
    //! with changing the stored zoom level
    enum
    {
      min_zoom_level = -5,
      max_zoom_level = 10
    };
  };
 
 
  //! The documentation main class derived from QSplitter
 
  class documentation : public QSplitter
  {
    Q_OBJECT
 
  public:
 
    documentation (QWidget *parent, base_qobject& oct_qobj);
    ~documentation (void);
 
    /*!
        Generate a string with page name @p title and current anchor
        from @p url for using in prev/next or bookmarks menu:
 
          @param title current title of the page as QString
          @param url   current url  as QUrl
 
          @return QString "title: anchor"
    */
    QString title_and_anchor (const QString& title, const QUrl& url);
 
  signals:
 
    void show_single_result (const QUrl&);
 
  public slots:
 
    void notice_settings (const gui_settings *settings);
    void save_settings (void);
 
    void copyClipboard (void);
    void pasteClipboard (void);
    void selectAll (void);
 
    void load_index (void);
    void load_ref (const QString& name = QString ());
    void registerDoc (const QString& name);
    void unregisterDoc (const QString& name);
 
  private slots:
 
    void activate_find (void);
    void global_search (void);
    void global_search_started (void);
    void global_search_finished (int hits);
    void filter_update (const QString& expression);
    void filter_update_history (void);
    void find (bool backward = false);
    void find_backward (void);
    void find_forward_from_anchor (const QString& text);
    void record_anchor_position (void);
    void handle_cursor_position_change (void);
    void handle_search_result_clicked (const QUrl& url);
 
    void update_history_menus (void);
    void open_hist_url (QAction *a);
 
  private:
 
    void construct_tool_bar (void);
    QAction * add_action (const QIcon& icon, const QString& text,
                          const char *member, QWidget *receiver = nullptr,
                          QToolBar *tool_bar = nullptr);
    void update_history (int new_count, QAction **actions);
 
    //! Select all occurrences of a string in the doc browser
    void select_all_occurrences (const QString& text);
 
    base_qobject& m_octave_qobj;
 
    QHelpEngine *m_help_engine;
    QString m_internal_search;
    documentation_browser *m_doc_browser;
    documentation_bookmarks *m_bookmarks;
    QLineEdit *m_find_line_edit;
    int m_search_anchor_position;
    QComboBox *m_filter;
    QString m_collection;
 
    QWidget *m_doc_widget;
    QToolBar *m_tool_bar;
    QString m_query_string;
 
    bool m_indexed;
    QString m_current_ref_name;
 
    QAction *m_action_go_home;
    QAction *m_action_go_prev;
    QAction *m_action_go_next;
    QMenu *m_prev_pages_menu;
    QMenu *m_next_pages_menu;
    int m_prev_pages_count;
    int m_next_pages_count;
 
    enum { max_history_entries = 10 };
    QAction *m_prev_pages_actions[max_history_entries];
    QAction *m_next_pages_actions[max_history_entries];
 
    QAction *m_action_bookmark;
 
    QAction *m_action_find;
    QShortcut *m_findnext_shortcut;
    QShortcut *m_findprev_shortcut;
 
    QAction *m_action_zoom_in;
    QAction *m_action_zoom_out;
    QAction *m_action_zoom_original;
  };
 
}
 
#endif