Sourceforge.net - The VCF's Project Host
   The VCF Website Home   |   Online Discussion Forums   |   Sourceforge.net Project Page   
VCF::HTMLBrowserControl

VCF::HTMLBrowserControl Class Reference

The HTMLBrowserControl provides a wrapper around the native HTML rendering and UI presentation for the platform. More...

#include <vcf/HTMLKit/HTMLBrowserControl.h>

Inheritance diagram for VCF::HTMLBrowserControl:

VCF::Control VCF::UIComponent VCF::AbstractView VCF::Component VCF::View VCF::ObjectWithCallbacks VCF::Object List of all members.

Public Types

enum  HTMLPolicy {
  hpNone = 0, hpAllowPopups = 0x0001, hpAllowsScrollbars = 0x0002, hpAllowsTextSelection = 0x0004,
  hpUseDefaultAuthenticationUI = 0x0008, hpAllowDefaultContextMenu = 0x0010
}
 A series of enums that allows you control the behaviour or appearance of the browser control. More...
enum  HTMLEvents {
  heBase = 'HTev', heURLLoadingBegun, heURLLoading, heURLLoaded,
  heURLLoadError, heStatusChanged, heNewWindowDisplayed, heTitleChanged,
  heAuthenticationRequested, heElementClicked
}

Public Member Functions

 HTMLBrowserControl ()
virtual ~HTMLBrowserControl ()
virtual void paint (GraphicsContext *ctx)
 Paints the control.
virtual void afterCreate (ComponentEvent *e)
 Special initializations may then happen here.
String getCurrentURL ()
 Gets the current url of the HTML that the control is showing.
void setCurrentURL (const String &url)
 Sets the current URL.
void goBack ()
 Go back to the previously loaded URL.
void goForward ()
 Go forward to the next loaded URL.
void goHome ()
 Go to the "home" page/URL as specified by the platforms internet settings.
void refresh ()
 Refresh the current URL.
bool isLoadingURL ()
 Returns true if the control is currently busy loading a URL.
void stopLoadingURL ()
 Programmatically stop the URL from loading.
void setFromHTML (const String &html)
String getTitle ()
 Get the title for the HTML.
void edit (const bool &val)
 Toggles the edit mode of the HTML Document.
void copy ()
 Take the user's current selection and copy it to the clipboard.
void selectAll ()
 Select everything in the document.
bool getAllowsPopupWindows ()
 Return whether or not popup windows are allowed.
void setAllowsPopupWindows (const bool &val)
bool getAllowsScrollbars ()
void setAllowsScrollbars (const bool &val)
bool getAllowsTextSelection ()
void setAllowsTextSelection (const bool &val)
bool getUseDefaultAuthenticationUI ()
void setUseDefaultAuthenticationUI (const bool &val)
bool getAllowDefaultContextMenu ()
void setAllowDefaultContextMenu (const bool &val)
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)
bool setElementClickedEventHandler (const String &elementName, EventHandler *handler)
 Sets one of the more common event handlers for an element.
HTMLDocument getDocument ()

Public Attributes

VCF::Delegate HTMLDelegate
 URLLoadingBegun
 URLLoading
 URLLoaded
 URLLoadError
 StatusChanged
VCF::Delegate HTMLNewWindowDelegate
 NewWindowDisplayed
 TitleChanged
VCF::Delegate HTMLAuthenticationDelegate
 AuthenticationRequested

Protected Attributes

HTMLBrowserPeer * browserPeer_
uint32 policyState_

Detailed Description

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.

On Win32 this means a custom COM based wrapper around Internet Explorer's IWebBrowser2 interface.
The HTMLBrowserControl allows a number of customizations of the UI presented when the HTML is rendered. You can control features such as
  • whether or not scrollbars are shown,
  • whether or not to allow popup windows,
  • whether or not to allow the user to select text in the UI
  • whether to use the default authentication dialog when prompted for a user name and password
  • whether or not the default context menu should be used
There are also a number of events that you can respond to, such as
  • when a url starts to load
  • events fired while the url is in the process of loading
  • when the url loading is complete
  • a url loading error
  • when the status changes, allowing you to output the status text
  • when a new window is about to be displayed
  • when the title changes
  • when authentication is being requested
  • when an HTML element is clicked on with the mouse
In addition, you can access the HTML document, which allows you to traverse to any element within the document.
See also:
HTMLElement

HTMLDocument

HTMLElementCollection

Member Enumeration Documentation

enum VCF::HTMLBrowserControl::HTMLEvents
 

Enumerator:
heBase 
heURLLoadingBegun 
heURLLoading 
heURLLoaded 
heURLLoadError 
heStatusChanged 
heNewWindowDisplayed 
heTitleChanged 
heAuthenticationRequested 
heElementClicked 

enum VCF::HTMLBrowserControl::HTMLPolicy
 

A series of enums that allows you control the behaviour or appearance of the browser control.

Enumerator:
hpNone 
hpAllowPopups  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.
hpAllowsScrollbars  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.

hpAllowsTextSelection  Determines if the browser will allow the user to select text.
hpUseDefaultAuthenticationUI  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.

hpAllowDefaultContextMenu  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.

Constructor & Destructor Documentation

VCF::HTMLBrowserControl::HTMLBrowserControl (   ) 
 

virtual VCF::HTMLBrowserControl::~HTMLBrowserControl (   )  [virtual]
 

Member Function Documentation

virtual void VCF::HTMLBrowserControl::afterCreate (  ComponentEvent *  e  )  [virtual]
 

Special initializations may then happen here.

See also:
Component::afterCreate()

Reimplemented from VCF::Control.

void VCF::HTMLBrowserControl::copy (   ) 
 

Take the user's current selection and copy it to the clipboard.

void VCF::HTMLBrowserControl::edit (  const bool &  val  ) 
 

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.

String VCF::HTMLBrowserControl::getActiveElementID (   ) 
 

bool VCF::HTMLBrowserControl::getAllowDefaultContextMenu (   )  [inline]
 

bool VCF::HTMLBrowserControl::getAllowsPopupWindows (   )  [inline]
 

Return whether or not popup windows are allowed.

bool VCF::HTMLBrowserControl::getAllowsScrollbars (   )  [inline]
 

bool VCF::HTMLBrowserControl::getAllowsTextSelection (   )  [inline]
 

String VCF::HTMLBrowserControl::getCurrentURL (   ) 
 

Gets the current url of the HTML that the control is showing.

HTMLDocument VCF::HTMLBrowserControl::getDocument (   ) 
 

String VCF::HTMLBrowserControl::getElementHTMLText (  const String &  elementName  ) 
 

String VCF::HTMLBrowserControl::getElementIDFromPoint (  Point *  pt  ) 
 

String VCF::HTMLBrowserControl::getElementText (  const String &  elementName  ) 
 

String VCF::HTMLBrowserControl::getTitle (   ) 
 

Get the title for the HTML.

bool VCF::HTMLBrowserControl::getUseDefaultAuthenticationUI (   )  [inline]
 

void VCF::HTMLBrowserControl::goBack (   ) 
 

Go back to the previously loaded URL.

void VCF::HTMLBrowserControl::goForward (   ) 
 

Go forward to the next loaded URL.

void VCF::HTMLBrowserControl::goHome (   ) 
 

Go to the "home" page/URL as specified by the platforms internet settings.

bool VCF::HTMLBrowserControl::isLoadingURL (   ) 
 

Returns true if the control is currently busy loading a URL.

virtual void VCF::HTMLBrowserControl::paint (  GraphicsContext *  ctx  )  [virtual]
 

Paints the control.

Called by the underlying windowing system whenever the control needs to be painted. Note that in some cases the GraphicsContext passed in to this method may not be the same pointer as the GraphicsContext that the control holds itself. During the paint() method you should only use the context value for all your drawing and not the one returned in getContext(). The value returned by getContext() should be used for drawing that takes place outside of the paint() method.

If the control allows paint notification, then the framework will fire an event to the BeforeControlPainted delegate prior to calling the control's paint() method. After the paint() method has returned, if the control allows paint notification, the framework will fire an event to the AfterControlPainted delegate. This allows outside observers to take part in the paint cycle, but beware that this does come at a bit of a cost, so use this feature sparingly.

Note: This should NEVER be called by programmers using the VCF, it will be called for you during the course of your applications native event loop, and is only here for providing custom drawing routines for controls. In other words: you implement it, you never call it yourself.

See also:
getAllowPaintNotification

Implements VCF::Control.

void VCF::HTMLBrowserControl::refresh (   ) 
 

Refresh the current URL.

This will cause it to be re-loaded.

void VCF::HTMLBrowserControl::selectAll (   ) 
 

Select everything in the document.

void VCF::HTMLBrowserControl::setAllowDefaultContextMenu (  const bool &  val  )  [inline]
 

void VCF::HTMLBrowserControl::setAllowsPopupWindows (  const bool &  val  ) 
 

void VCF::HTMLBrowserControl::setAllowsScrollbars (  const bool &  val  ) 
 

void VCF::HTMLBrowserControl::setAllowsTextSelection (  const bool &  val  ) 
 

void VCF::HTMLBrowserControl::setCurrentURL (  const String &  url  ) 
 

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.

bool VCF::HTMLBrowserControl::setElementClickedEventHandler (  const String &  elementName,
EventHandler *  handler
) 
 

Sets one of the more common event handlers for an element.

Some elements may not respond to this. This will fire a HTMLElementEvent instance.

void VCF::HTMLBrowserControl::setElementHTMLText (  const String &  elementName,
const String &  html
) 
 

void VCF::HTMLBrowserControl::setElementText (  const String &  elementName,
const String &  text
) 
 

void VCF::HTMLBrowserControl::setFromHTML (  const String &  html  ) 
 

void VCF::HTMLBrowserControl::setUseDefaultAuthenticationUI (  const bool &  val  )  [inline]
 

void VCF::HTMLBrowserControl::stopLoadingURL (   ) 
 

Programmatically stop the URL from loading.

Member Data Documentation

VCF::HTMLBrowserControl::AuthenticationRequested
 

HTMLBrowserPeer* VCF::HTMLBrowserControl::browserPeer_ [protected]
 

VCF::Delegate VCF::HTMLBrowserControl::HTMLAuthenticationDelegate
 

Event Delegate:
AuthenticationRequested
event class: HTMLAuthenticationEvent
event type: heAuthenticationRequested

VCF::Delegate VCF::HTMLBrowserControl::HTMLDelegate
 

Event Delegate:
URLLoadingBegun
event class: HTMLEvent
event type: heURLLoadingBegun

VCF::Delegate VCF::HTMLBrowserControl::HTMLNewWindowDelegate
 

Event Delegate:
NewWindowDisplayed
event class: HTMLEvent
event type: heNewWindowDisplayed

VCF::HTMLBrowserControl::NewWindowDisplayed
 

uint32 VCF::HTMLBrowserControl::policyState_ [protected]
 

VCF::HTMLBrowserControl::StatusChanged
 

VCF::HTMLBrowserControl::TitleChanged
 

VCF::HTMLBrowserControl::URLLoaded
 

VCF::HTMLBrowserControl::URLLoadError
 

VCF::HTMLBrowserControl::URLLoading
 

VCF::HTMLBrowserControl::URLLoadingBegun
 

The documentation for this class was generated from the following file:
   Comments or Suggestions?    License Information