htmlview.h

PIXIL is a small footprint operating environment, complete with PDA PIM applications, a browser and

/* This file is part of the KDE libraries
    Copyright (C) 1997 Martin Jones ([e-mail])
              (C) 1997 Torben Weis ([e-mail])

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library 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
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*/
//----------------------------------------------------------------------------
//
// KDE HTML Widget
//
// Copyright (c) 1997 The KDE Project
//

#ifndef HTMLVIEW_H
#define HTMLVIEW_H

#include <qscrollbar.h>
#include <qlist.h>
#include <html.h>
#include <drag.h>

/**
 * @short Widget for displaying HTML.  Manages srcollbars and frames.
 *
 * This widget makes displaying HTML text very easy. It handles scrollbars
 * and stuff. It is able to handle most HTML 3.x including tables and frames.
 * To fill the widget with content you should do the follwing:
 * <PRE>
 * view->begin( "file:/tmp/test.html" );
 * view->parse();
 * view->write( "&lt;HTML&gt;&lt;TITLE&gt;...." );
 * .....
 * view->end();
 * view->show();
 * </PRE>
 * The widget will care for resize events and paint events and for scrolling.
 * Have a look at the set of signals emitted by this widget. You should connect
 * to most of them.
 */
class KHTMLView : public QWidget
{
    Q_OBJECT
public:
    /**
     * Created a new HTML View. The widget is empty by default.
     * You must use @ref #begin, @ref #write, @ref #end and @ref #parse
     * to fill the widget with content.
     *
     * @param _name is the name of the widget. Usually this name is only
     *          meaningful for Qt but in this case it is the name of
     *          the HTML window. This means you can reference this name
     *          in the &lt; href=... target=... &gt; tag. If this argument is 0L
     *          then a unique default name is chosen.
     */
    KHTMLView( QWidget *_parent = 0L, const char *_name = 0L, int _flags = 0,
	KHTMLView *_parent_view = 0L );
    /**
     * Destroys the widget and all of its child widgets.
     */
    virtual ~KHTMLView();

    /**
     * Clears the widget and prepares it for new content. If you display
     * for example "file:/tmp/test.html", you can use the following code
     * to get a value for '_url':
     * <PRE>
     * KURL u( "file:/tmp/test.html" );
     * view->begin( u.directoryURL() );
     * </PRE>
     *
     * @param _dx is the initial horizontal scrollbar value. Usually you don't
     *            want to use this.
     * @param _dy is the initial vertical scrollbar value. Usually you don't
     *            want to use this.
     */
    virtual void begin( const char *_url = 0L, int _dx = 0, int _dy = 0 );

    /**
     * Writes another part of the HTML code to the widget. You may call
     * this function many times in sequence. But remember: The less calls
     * the faster the widget is.
     */
    virtual void write( const char *_text );

    /**
     * Call this after your last call to @ref #write.
     */
    virtual void end();

    /**
     * This function will parse the code that has been previously written using
     * the @ref #write function. Call this one after calling @ref #end.
     */
    virtual void parse();

    /**
     * Shows '_url' in this view. Usually a @ref #documentRequest signal is
     * emitted to load the url.
     */
    virtual void openURL( const char *_url );

    /**
     * Prints this view to the printer.
     */
    virtual void print();
    
    /**
     * Creates a new view. This function is not intended to be called by the
     * application that uses this widget. It is intended to be overloaded by
     * some class. If for example you have done this:
     * <PRE>
     * class MyView : public KHTMLView
     * {
     * ...
     *    virtual KHTMLView* newView( QWidget *_parent, const char *_name, int _flags );
     * };
     * </PRE>
     * You may now want to reimplement like this
     * <PRE>
     * KHTMLView* myView::newView( QWidget *_parent, const char *_name, int _flags );
     * {
     *   return new MyView( ... );
     * }
     * </PRE>
     * This will cause that all frames ( if you have some ) will be an instance
     * of MyView, too.<br>
     * FOR INTERNAL USE ONLY.
     */
    virtual KHTMLView* newView( QWidget *_parent = 0L, const char *_name = 0L, int _flags = 0L );
    
    /**
     * Changes the name of the widget.
     * This name is used in the &lt;a href=.. target=... &gt; tag.
     *
     * @see #findView
     * @see #name
     */
    virtual void setFrameName( const char *_name ) { frameName = _name; }

    /**
     * @return the name of this window.
     *
     * @see #setName
     * @see #name
     * @see #findView
     */
    virtual const char* getFrameName() { return frameName.data(); }

    /**
     * Tells the widget that it is a frameset
     * This is for internal use only.
     * FOR INTERNAL USE ONLY.
     */
    void setIsFrameSet( bool _frameset );

    /**
     * FOR INTERNAL USE ONLY.
     *
     * @return TRUE if the view displays a frameset right now.
     */
    bool isFrameSet();

    /**
     * Tells the widget that it is a frame of some frameset.
     * This is for internal use only.
     * FOR INTERNAL USE ONLY.
     */
    void setIsFrame( bool _frame );

    /**
     * FOR INTERNAL USE ONLY.
     *
     * @return TRUE if the view displays a frame right now.
     */
    bool isFrame();

    /**
     * Find the anchor named '_name'. If the anchor is found, the widget
     * scrolls to the closest position. Returns TRUE if the anchor has
     * been found.
     */
    bool gotoAnchor( const char *_name );

    /**
     * Scrolls to the position (_x, _y). Returns TRUE if succeeded.
     */
    bool gotoXY( int _x, int _y );

    /**
     * Sets the width of the border. This is used to implement the tag
     * &lt;frame frameborder=... &gt; tag. FOR INTERNAL USE ONLY.
     * 
     * @see frameBorder
     */
    void setFrameBorder( int _b ) { frameBorder = _b;  }

    /**
     * @return the width of the border in pixels.
     *
     * @see #setFrameBorder
     */
    int getFrameBorder() { return frameBorder; }

    /**
     * Tells the widget to show/hide the scrollbars. This function will have
     * effect only when called before @ref #begin. It is used to implement the
     * <tt>&lt;frame scrolling=... &gt;</tt> tag.<br>
     * FOR INTERNAL USE ONLY.
     *
     * @param _scroll is 1 for yes, 0 for no and -1 for auto.
     *
     * @see #scrolling
     */  
    void setScrolling( int _scroll ) { scrolling = _scroll;  }

    /**
     * @return 1 for yes, 0 for no and -1 for auto.
     *
     * @see #setScrolling
     */
    int getScrolling() { return scrolling; }
  
    /**
     * Tells the widget wether it should be resizeable or not.
     * The widget may still resize. Its only intention is to provide
     * information for @ref HTMLFrameSet. @ref HTMLFrameSet looks at this flag
     * to determine wether the separator between this frame and another one
     * may be moved by the user. It is used to impement the
     * <tt>&lt;frame noresize &gt;</tt> tag.<br>
     * FOR INTERNAL USE ONLY.
     */
    void setAllowResize( bool _allow ) { bAllowResize = _allow; }

    /**
     * This function is used in @ref HTMLFrameSet. It is for
     * INTERNAL USE ONLY.
     *
     * @return TRUE if the widget may be resized by the user.
     *
     * @see #setAllowResize
     */
    bool allowResize() { return bAllowResize; }

    /**
     * Sets the width of the margin. This function is used to implement
     * the <tt>&lt;frame marginwidth=... &gt;</tt> tag.<br>
     * FOR INTERNAL USE ONLY.
     */
    void setMarginWidth( int _w );

    /**
     * Sets the width of the margin. This function is used to implement
     * the <tt>&lt;frame marginheight=... &gt;</tt> tag.<br>
     * FOR INTERNAL USE ONLY.
     */
    void setMarginHeight( int _h );

    /**
     * Tells the widget that it has been selected. This will result
     * in a black border around the widget. This happens only if this
     * widget represents a frame.
     * FOR INTERNAL USE ONLY.
     */
    void setSelected( bool _selected );

    /**
     * FOR INTERNAL USE ONLY.
     *
     * @return TRUE if this widget represents a frame and if it has been
     *         selected by the user. The selected frame has a black inner
     *         border.
     */
    bool isSelected();
    
    /**
     * FOR INTERNAL USE ONLY.
     *
     * @return the x offset of the widget. You may use this function to remeber
     *          which part of the document the user is currently looking at.
     */
    int xOffset();

    /**
     * @return the y offset of the widget. You may use this function to remeber
     *          which part of the document the user is currently looking at.
     */
    int yOffset();
    
    /**
     * Checks out wether there is a URL under the point p and returns a pointer
     * to this URL or 0L if there is none.
     */
    const char* getURL( QPoint & p );

	/**
	 * Returns the current URL
	 */
	QString *getCurURL() {return &url;}

    /**
     * Seaerches for a KHTMLView with a specific name as mentioned in the
     * constructor.
     * 
     * @see #setName
     * @see #name
     */
    KHTMLView* findView( const char *_name );

    /**
     * @return the view that represents the currently selected frame or 0L
     *         if we dont have frames or a selected one right now.
     */
    virtual KHTMLView* getSelectedView();

    /**
     * Select all objects matching the regular expression.
     *
     * @param _select if TRUE then all matching objects are marked, otherwise
     *                they become unmarked.
     */
    virtual void select( QRegExp& _pattern, bool _select );