Source: tohelp.h


Annotated List
Files
Globals
Hierarchy
Index
//***************************************************************************
/*
 * TOra - An Oracle Toolkit for DBA's and developers
 * Copyright (C) 2003 Quest Software, Inc
 * 
 * This program 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;  only version 2 of
 * the License is valid for this program.
 * 
 * This program 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 this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 *      As a special exception, you have permission to link this program
 *      with the Oracle Client libraries and distribute executables, as long
 *      as you follow the requirements of the GNU GPL in regard to all of the
 *      software in the executable aside from Oracle client libraries.
 *
 *      Specifically you are not permitted to link this program with the
 *      Qt/UNIX, Qt/Windows or Qt Non Commercial products of TrollTech.
 *      And you are not permitted to distribute binaries compiled against
 *      these libraries without written consent from Quest Software, Inc.
 *      Observe that this does not disallow linking to the Qt Free Edition.
 *
 * All trademarks belong to their respective owners.
 *
 ****************************************************************************/

#ifndef TOHELP_H
#define TOHELP_H

#include <qdialog.h>

#include <map>

class toListView;
class QLineEdit;
class QTextBrowser;
class QListViewItem;
class QProgressBar;
class toHelpBrowser;
class QToolButton;
class toHelpPrefs;
class QComboBox;

/** This class is used to indicate a help context of an object. When the current context
 * is to be determined you start at the widget that currently has focus and walk upwards
 * to it's parent until you find a widget that also inherits this class which specify the
 * context of all underlying widgets.
 */

class toHelpContext {
  /**
   * The current context.
   */
  QString Context;
public:
  /** Create a context.
   * @param file File in the help directory that describes the current context.
   */
  toHelpContext(const QString &file)
    : Context(file)
  { }
  virtual ~toHelpContext()
  { }
  /**
   * Get this context
   * @return The location of a file that describes the current context.
   */
  virtual const QString &context(void) const
  { return Context; }
};

#include "totool.h"

/**
 * Additional help tool. Also used as object to connect to to display help
 * for modal dialogs. Only to be used internally.
 * @internal
 */
class toHelpTool : public toTool {
  Q_OBJECT
public:
  toHelpTool()
    : toTool(501,"Additional Help")
  { }
  virtual QWidget *toolWindow(QWidget *,toConnection &)
  { return NULL; }
  virtual QWidget *configurationTab(QWidget *parent);
public slots:
  void displayHelp(void);
};

/**
 * Display a help browser. A help manual consists of HTML pages where at least
 * two pages are mandatory.
 *
 * The first one is toc.htm which is parsed for links which are added to the left
 * pane tree view. Indentation is handled with the tag dl which open and close a
 * tree branch.
 *
 * The following file would result in two main headings with the first one having
 * one leaf widget as well.
 *
<pre>
<A HREF="first.html">1 Head</A><BR>
<DL>
<A HREF="second.html>1.1 Head Head</A></BR>
</DL>
<A HREF="third.html">2 Foot</A><BR>
</pre>
 * 
 * The second file which is optional and should be called index.htm if it exists
 * should contain a file with links to keywords in the manual. This must be present
 * for search to be possible in the manual. Keywords are indicated by the <dd> tag
 * in these files as well as a link to where the keyword is described. Indentation
 * is possible using the <dl> tag is possible here as well.
 *
 * The following will make the keywords "Head", "Head, Head Head" and "Foot" available.
<pre>
<DD><A HREF="first.html">Head</A><BR>
<DL>
    <DD><A HREF="second.html">Head Head</A><BR>
</DL>
<DD><A HREF="third.html">Foot</A>
</pre>
 * The reason the files look this way is that this way they are compatible with
 * the Oracle manuals from Oracle Corporation and these can be browsed as well in
 * this help viewer.
 */

class toHelp : public QDialog {
  Q_OBJECT

  /** @internal
   * Pointer to open helpwindow if available, otherwise NULL
   */

  static toHelp *Window;

  /**
   * True if you are currently searching. You can't close the window while search, would
   * coredump.
   */
  bool Searching;

  /**
   * List containing the manuals and their sections, compiled from the toc.htm files.
   * @see toHelp
   */
  toListView *Sections;
  /**
   * List containing the search result of the latest search. Search reads the index.htm files.
   */
  toListView *Result;
  /**
   * The line containing the search text.
   */
  QLineEdit *SearchLine;
  /**
   * Manuals to include in search.
   */
  QComboBox *Manuals;
#ifdef TO_KDE
  /**
   * Displays the actual help window.
   */
  toHelpBrowser *Help;
#else
  QTextBrowser *Help;
#endif
  /**
   * Display progress of current search.
   */
  QProgressBar *Progress;

  /**
   * Set selection and also update selected item in list if any item matches the
   * selected location.
   * @param lst Listview to update selected item in.
   * @param str Location of next help text.
   */
  virtual void setSelection(toListView *lst,const QString &str);
  /**
   * Reimplemented for internal reasons.
   */
  virtual void closeEvent(QCloseEvent *e)
  { if (!Searching) QWidget::closeEvent(e); }
private slots:
  /** Initiate a search with the parameters in the internal widgets.
   * @internal
   */
  void search(void);
  /** Remove the current selection in the sections and result lists. 
   * @internal
   */
  void removeSelection(void);
  /** Item selected in left pane. Change contents of help viewer.
   * @internal
   */
  void changeContent(QListViewItem *);
public:
  /**
   * Create help widget.
   * @param parent Parent widget.
   * @param name Name of widget.
   * @param modal If dialog is for a modal dialog or not
   */
  toHelp(QWidget *parent,const char *name,bool modal=true);
  /** Help function to get a clean path from a path string. Strips trailing / etc.
   * @param path Path to strip.
   * @return Stripped path in string.
   */
  static QString path(const QString &path=QString::null);
  virtual ~toHelp();
  /** Display a specific help context in the internal manual. Pops up a help window that
   * displays the selected topic.
   * @param context Context to diaplay.
   * @param parent If NULL use modal dialog and main window.
   */
  static void displayHelp(const QString &context,QWidget *parent=NULL);
  /** Display a specific help context in the internal manual. The context is derived from
   * the widget that currently holds the focus.
   * @param parent If NULL use modal dialog and main window.
   */
  static void displayHelp(QWidget *parent=NULL);
  /** Connect the F1 key to display help for a modal dialog. Don't use this directly,
   * instead call displayHelp directly and bind Key_F1 to that call. This is because the
   * help in modal dialogs are cludgy at best and should be avoided if possible.
   * @param dialog Dialog to connect accelerator to.
   */
  static void connectDialog(QDialog *dialog);

  friend class toHelpPrefs;
};

#endif