htmlbrowsercontrol.h

来自「这是VCF框架的代码」· C头文件 代码 · 共 510 行

#ifndef _VCF_HTMLBROWSERCONTROL_H__
#define _VCF_HTMLBROWSERCONTROL_H__
//HTMLBrowserControl.h

/*
Copyright 2000-2004 The VCF Project.
Please see License.txt in the top level directory
where you installed the VCF.
*/

#ifndef _VCF_HTMLDOMELEMENTS_H__
#include "vcf/ApplicationKit/HTMLDOMElements.h"
#endif


#if _MSC_VER > 1000
#   pragma once
#endif


#define HTMLBROWSERCONTROL_CLASSID		"3bfb2646-a7e9-40b2-948b-9eef92db7965"


namespace VCF  {
	/**
	This is event is used when an authentication event is 
	fired by the underlying browser peer. This happens if a 
	URL is being opened and it needs a username and password.
	The handler for this event should set the username and 
	password to some meaningful value.
	*/
	class HTMLAuthenticationEvent : public Event {
	public:
		inline HTMLAuthenticationEvent( Object* source, const String& url );


		String userName;
		String password;
		String url;
		bool authenticationCancelled;

		virtual Object* clone( bool deep=false ) {
			return new HTMLAuthenticationEvent(*this);
		}		
	};


	/**
	Generic HTML event sent for all other events generated by the HTML Browser.
	*/
	class HTMLKIT_API HTMLEvent : public Event {
	public:
		HTMLEvent( Object* source, uint32 type ):Event(source,type), value(0),maxValue(0) {};

		virtual Object* clone( bool deep=false ) {
			return new HTMLEvent(*this);
		}
	
		/**
		The value of the event. Generally gets set during progress events.
		@see HTMLBrowserControl::StatusChanged
		@see HTMLBrowserControl::URLLoading
		*/
		uint32 value;

		/**
		The maximum value of the event. Generally gets set during progress events.
		@see HTMLBrowserControl::StatusChanged
		@see HTMLBrowserControl::URLLoading
		*/
		uint32 maxValue;

		/**
		The status of the event. 
		@see HTMLBrowserControl::StatusChanged
		*/
		String status;

		/**
		The URL the event is associated with. 
		*/
		String url;

	};


	/**
	An event thats used for HTMLElement events. 
	*/
	class HTMLKIT_API HTMLElementEvent : public Event {
	public:
		HTMLElementEvent( Object* source, uint32 type ):Event(source,type) {};

		virtual Object* clone( bool deep=false ) {
			return new HTMLElementEvent(*this);
		}

		/**
		The id of the element that triggered the event.
		*/
		String elementID;
	};

/**
\class HTMLBrowserControl HTMLBrowserControl.h "vcf/HTMLKit/HTMLBrowserControl.h"
The HTMLBrowserControl provides a wrapper around the native HTML rendering 
and UI presentation for the platform. This class provides  all the basic 
features to implement a simple HTML browsing application. For 
more advanced uses, you can take advantage of it's other features
and use the HTMLElement, HTMLDocument, and HTMLElementCollection
classes.
\par
On Win32 this means a custom COM based wrapper around Internet Explorer's 
IWebBrowser2 interface. 
\par 
The HTMLBrowserControl allows a number of customizations of the UI presented
when the HTML is rendered. You can control features such as 
	\li whether or not scrollbars are shown, 
	\li whether or not to allow popup windows, 
	\li whether or not to allow the user to select text in the UI
	\li whether to use the default authentication dialog when 
	prompted for a user name and password
	\li whether or not the default context menu should be used
\par
There are also a number of events that you can respond to, such as 
	\li when a url starts to load
	\li events fired while the url is in the process of loading
	\li when the url loading is complete
	\li a url loading error
	\li when the status changes, allowing you to output the status text
	\li when a new window is about to be displayed
	\li when the title changes
	\li when authentication is being requested
	\li when an HTML element is clicked on with the mouse

\par
In addition, you can access the HTML document, which allows you to 
traverse to any element within the document.
@see HTMLElement
@see HTMLDocument
@see HTMLElementCollection
*/
class HTMLKIT_API HTMLBrowserControl : public Control {
public:
	HTMLBrowserControl();
	virtual ~HTMLBrowserControl();
	
	/**
	A series of enums that allows you control the behaviour or 
	appearance of the browser control.
	*/
	enum HTMLPolicy {
		hpNone = 0,
		/**
		Allows popup windows to be show if this is set, otherwise if 
		the page contents or script request a new window, it will be 
		denied.
		*/
		hpAllowPopups =			0x0001,

		/**
		Determines whether or not scrollbars are made visible. If it's 
		set, then they are allwos to become visible. If it's not
		then no scrollbars will ever appear.
		*/
		hpAllowsScrollbars =	0x0002,

		/**
		Determines if the browser will allow the user to select text.
		*/
		hpAllowsTextSelection = 0x0004,

		/**
		Determines if the browser should use the platform native authentication
		dialog when a request for user name and password is made. If this
		isn't set then you can customize the interface.
		*/
		hpUseDefaultAuthenticationUI  = 0x0008,

		/**
		Determines whether or not the browser should use it's default popup menu
		or allow it to be customized. If it's customized, then it uses the 
		popup menu of the control if it exists.
		*/
		hpAllowDefaultContextMenu  = 0x0010,
	};

	enum HTMLEvents{
		heBase = 'HTev',
		heURLLoadingBegun,
		heURLLoading,
		heURLLoaded,
		heURLLoadError,
		heStatusChanged,
		heNewWindowDisplayed,
		heTitleChanged,
		heAuthenticationRequested,
		heElementClicked
	};

	/**
	@delegate URLLoadingBegun
	@event HTMLEvent
	@eventtype heURLLoadingBegun
	*/
	DELEGATE( URLLoadingBegun );

	/**
	@delegate URLLoading
	@event HTMLEvent
	@eventtype heURLLoading
	*/
	DELEGATE( URLLoading );

	/**
	@delegate URLLoaded
	@event HTMLEvent
	@eventtype heURLLoaded
	*/
	DELEGATE( URLLoaded );

	/**
	@delegate URLLoadError
	@event HTMLEvent
	@eventtype heURLLoadError
	*/
	DELEGATE( URLLoadError );


	/**
	@delegate StatusChanged
	@event HTMLEvent
	@eventtype heStatusChanged
	*/
	DELEGATE( StatusChanged );

	/**
	@delegate NewWindowDisplayed
	@event HTMLEvent
	@eventtype heNewWindowDisplayed
	*/
	DELEGATE( NewWindowDisplayed );

	/**
	@delegate TitleChanged
	@event HTMLEvent
	@eventtype heTitleChanged
	*/
	DELEGATE( TitleChanged );
	
	/**
	@delegate AuthenticationRequested
	@event HTMLAuthenticationEvent
	@eventtype heAuthenticationRequested
	*/
	DELEGATE( AuthenticationRequested );


	virtual void paint( GraphicsContext* ctx );

	virtual void afterCreate( ComponentEvent* e );

	/**
	Gets the current url of the HTML that the control
	is showing
	*/
	String getCurrentURL();

	/**
	Sets the current URL. This will start the process of loading the URL.
	It's not safe to access the control's HTMLDocument until the
	URLLoaded event is fired.
	*/
	void setCurrentURL( const String& url );

	/**
	Go back to the previously loaded URL
	*/
	void goBack();

	/** 
	Go forward to the next loaded URL
	*/
	void goForward();

	/**
	Go to the "home" page/URL as specified by the platforms internet settings.
	*/
	void goHome();

	/**
	Refresh the current URL. This will cause it to be re-loaded.
	*/
	void refresh();

	/**
	Returns true if the control is currently busy loading a URL.
	*/
	bool isLoadingURL();

	/**
	Programmatically stop the URL from loading.
	*/
	void stopLoadingURL();


	void setFromHTML( const String& html );

	/**
	Get the title for the HTML
	*/
	String getTitle();

	/**
	Toggles the edit mode of the HTML Document. If you pass in true
	the HTML displayed will become editable, if you pass in false it
	will become readonly.
	*/
	void edit( const bool& val );

	/**
	Take the user's current selection and copy it to the clipboard
	*/
	void copy();

	/**
	Select everything in the document
	*/
	void selectAll();

	/**
	Return whether or not popup windows are allowed. 
	*/
	bool getAllowsPopupWindows() {
		return (policyState_ & hpAllowPopups) ? true : false;
	}

	void setAllowsPopupWindows( bool val );

	bool getAllowsScrollbars() {
		return (policyState_ & hpAllowsScrollbars) ? true : false;
	}

	void setAllowsScrollbars( bool val );

	bool getAllowsTextSelection() {
		return (policyState_ & hpAllowsTextSelection) ? true : false;
	}	

	void setAllowsTextSelection( bool val );

	bool getUseDefaultAuthenticationUI() {
		return (policyState_ & hpUseDefaultAuthenticationUI) ? true : false;
	}

	void setUseDefaultAuthenticationUI( bool val ) {
		if ( val ) {
			policyState_ |= hpUseDefaultAuthenticationUI;
		}
		else {
			policyState_ &= ~hpUseDefaultAuthenticationUI;
		}		
	}

	bool getAllowDefaultContextMenu() {
		return (policyState_ & hpAllowDefaultContextMenu) ? true : false;
	}

	void setAllowDefaultContextMenu( bool val ) {
		if ( val ) {
			policyState_ |= hpAllowDefaultContextMenu;
		}
		else {
			policyState_ &= ~hpAllowDefaultContextMenu;
		}		
	}

	String getActiveElementID();

	String getElementIDFromPoint( Point* pt );

	String getElementHTMLText( const String& elementName );

	void setElementHTMLText( const String& elementName, const String& html );

	String getElementText( const String& elementName );

	void setElementText( const String& elementName, const String& text );	
	
	/**
	Sets one of the more common event handlers for an element. Some elements
	may not respond to this.
	This will fire a HTMLElementEvent instance.
	*/
	bool setElementClickedEventHandler( const String& elementName, EventHandler* handler );


	HTMLDocument getDocument();
protected:
	HTMLBrowserPeer* browserPeer_;
	uint32 policyState_;

private:
};



HTMLAuthenticationEvent::HTMLAuthenticationEvent( Object* source, const String& aUrl ):
	Event( source, HTMLBrowserControl::heAuthenticationRequested),
	url(aUrl),
	authenticationCancelled(false)
{

}


}; //end of namespace VCF


/**
*CVS Log info
*$Log$
*Revision 1.2  2006/04/07 02:35:42  ddiego
*initial checkin of merge from 0.6.9 dev branch.
*
*Revision 1.1.2.3  2006/03/14 03:40:22  ddiego
*updated htmlkit and internetkit source docs.
*
*Revision 1.1.2.2  2006/03/06 04:46:44  ddiego
*more stuff.
*
*Revision 1.1.2.1  2006/03/06 03:48:31  ddiego
*more docs, plus update add-ins, plus migrated HTML browser code to a new kit called HTMLKit.
*
*Revision 1.2.6.4  2006/02/15 05:14:33  ddiego
*more browser code.
*
*Revision 1.2.6.3  2006/02/14 05:13:09  ddiego
*more browser updates.
*
*Revision 1.2.6.2  2006/02/13 22:11:59  ddiego
*added further html support and better browser example code.
*
*Revision 1.2.6.1  2006/02/13 05:10:32  ddiego
*added better html browser support.
*
*Revision 1.2  2004/08/07 02:49:08  ddiego
*merged in the devmain-0-6-5 branch to stable
*
*Revision 1.1.2.3  2004/06/06 07:05:30  marcelloptr
*changed macros, text reformatting, copyright sections
*
*Revision 1.1.2.2  2004/04/29 03:43:13  marcelloptr
*reformatting of source files: macros and csvlog and copyright sections
*
*Revision 1.1.2.1  2004/04/28 00:28:17  ddiego
*migration towards new directory structure
*
*Revision 1.4.4.1  2004/04/26 21:58:20  marcelloptr
*changes for dir reorganization: _VCF_MACRO_H__
*
*Revision 1.4  2003/12/18 05:15:57  ddiego
*merge from devmain-0-6-2 branch into the stable branch
*
*Revision 1.3.4.3  2003/09/12 00:09:32  ddiego
*added better tabbing behaviour - fixed an earlier bug.
*Code is easier to understand and it simplified the implementation
*a bit as well
*Moved around the RTTI definitions for various Appkit classes to a
*single inline and stripped them from the various class headers
*
*Revision 1.3.4.2  2003/09/06 19:45:45  ddiego
*changes to ensure that the destroy() is properly called.
*Destructors were moved back to pbulic scope in case that was causing a bug.
*Moving them all(all teh component derived classes) to private scope causes
*a complete failure in hte VC6 compiler. Alas...
*So destructors are present, and modal dialogs can still be created on the
*stack, but almost any other component should be created on the heap, and
*gotten rid of via free() NOT using operator delete directly.
*also moved the vcs info to the end of the file for some of the headers
*This will be an ongoing process.
*
*Revision 1.3.4.1  2003/09/05 21:03:38  ddiego
*moved the various control destructor's to protected scope
*migrated code into destroy() overridden methods
*----------------------------------------------------------------------
*
*Revision 1.3  2003/05/17 20:37:03  ddiego
*this is the checkin for the 0.6.1 release - represents the merge over from
*the devmain-0-6-0 branch plus a few minor bug fixes
*
*Revision 1.2.22.1  2003/03/12 03:09:34  ddiego
*switched all member variable that used the "m_"<name> prefix to
* <name>"_" suffix nameing standard.
*Also changed all vcf builder files to accomadate this.
*Changes were made to the Stream classes to NOT multiple inheritance and to
*be a little more correct. Changes include breaking the FileStream into two
*distinct classes, one for input and one for output.
*
*Revision 1.2  2002/01/24 01:46:47  ddiego
*added a cvs "log" comment to the top of all files in vcf/src and vcf/include
*to facilitate change tracking
*
*/


#endif // _VCF_HTMLBROWSERCONTROL_H__