Awesomium::WebView Class Reference

#include <WebView.h>

List of all members.

Public Member Functions

void destroy ()
void setListener (WebViewListener *listener)
WebViewListenergetListener ()
void loadURL (const std::string &url, const std::wstring &frameName=L"", const std::string &username="", const std::string &password="")
void loadURL (const std::wstring &url, const std::wstring &frameName=L"", const std::string &username="", const std::string &password="")
void loadHTML (const std::string &html, const std::wstring &frameName=L"")
void loadHTML (const std::wstring &html, const std::wstring &frameName=L"")
void loadFile (const std::string &file, const std::wstring &frameName=L"")
void goToHistoryOffset (int offset)
void executeJavascript (const std::string &javascript, const std::wstring &frameName=L"")
void executeJavascript (const std::wstring &javascript, const std::wstring &frameName=L"")
Awesomium::FutureJSValue executeJavascriptWithResult (const std::string &javascript, const std::wstring &frameName=L"")
Awesomium::FutureJSValue executeJavascriptWithResult (const std::wstring &javascript, const std::wstring &frameName=L"")
void callJavascriptFunction (const std::wstring &object, const std::wstring &function, const JSArguments &args, const std::wstring &frameName=L"")
void createObject (const std::wstring &objectName)
void destroyObject (const std::wstring &objectName)
void setObjectProperty (const std::wstring &objectName, const std::wstring &propName, const JSValue &value)
void setObjectCallback (const std::wstring &objectName, const std::wstring &callbackName)
bool isDirty ()
void render (unsigned char *destination, int destRowSpan, int destDepth, Awesomium::Rect *renderedRect=0)
void injectMouseMove (int x, int y)
void injectMouseDown (Awesomium::MouseButton button)
void injectMouseUp (Awesomium::MouseButton button)
void injectMouseWheel (int scrollAmount)
void injectKeyboardEvent (const WebKeyboardEvent &keyboardEvent)
void cut ()
void copy ()
void paste ()
void selectAll ()
void deselectAll ()
void getContentAsText (std::wstring &result, int maxChars)
void zoomIn ()
void zoomOut ()
void resetZoom ()
void resize (int width, int height)
void unfocus ()
void focus ()
void setTransparent (bool isTransparent)
void setURLFilteringMode (URLFilteringMode mode)
void addURLFilter (const std::wstring &filter)
void clearAllURLFilters ()
void setHeaderDefinition (const std::string &name, const Awesomium::HeaderDefinition &definition)
void addHeaderRewriteRule (const std::wstring &rule, const std::string &name)
void removeHeaderRewriteRule (const std::wstring &rule)
void removeHeaderRewriteRulesByDefinitionName (const std::string &name)

Protected Member Functions

 WebView (int width, int height, bool isTransparent, bool enableAsyncRendering, int maxAsyncRenderPerSec, base::Thread *coreThread)
void startup ()
void setDirty (bool val=true)
void setAsyncDirty (bool val=true)
void setFinishRender ()
void setFinishShutdown ()
void setFinishGetContentText ()
void setFinishResize ()
void resolveJSValueFuture (int requestID, Awesomium::JSValue *result)
void handleFutureJSValueCallback (const Awesomium::JSArguments &args)
void nullifyFutureJSValueCallbacks ()
void handleCheckKeyboardFocus (bool isFocused)

Protected Attributes

base::Thread * coreThread
WebViewProxy * viewProxy
WebViewWaitState * waitState
WebViewListenerlistener
LockImpl * dirtinessLock
bool dirtiness
bool isKeyboardFocused
LockImpl * jsValueFutureMapLock
std::map< int,
JSValueFutureImpl * > 
jsValueFutureMap
const bool enableAsyncRendering

Friends

class WebCore
class ::WebViewProxy
class ::FutureValueCallback
class ::CheckKeyboardFocusCallback


Detailed Description

A WebView is essentially a single instance of a web-browser (created via the WebCore singleton) that you can interact with (via input injection, javascript, etc.) and render to an off-screen buffer.

Member Function Documentation

void Awesomium::WebView::addHeaderRewriteRule ( const std::wstring &  rule,
const std::string &  name 
)

Adds a new a header re-write rule. All requests whose URL matches the specified rule will have its HTTP headers re-written with the specified header definition before sending it to the server.

Parameters:
rule A wide string with optional wildcards (*, ?) that matches the URL(s) that will have its headers re-written with the specified header definition.
name The name of the header definition (specified in WebView::setHeaderDefinition).
Note:
The case where a URL is matched by multiple rules is unsupported, only the first match will be used.

void Awesomium::WebView::addURLFilter ( const std::wstring &  filter  ) 

Adds a new URL Filter rule.

Parameters:
filter A string with optional wildcards that describes a certain URL.
Note:
For example, to match all URLs from the domain "google.com", your filter string might be: http://google.com/*

You may also use the "local://" scheme prefix to describe the URL to the base directory (set via WebCore::setBaseDirectory).

void Awesomium::WebView::callJavascriptFunction ( const std::wstring &  object,
const std::wstring &  function,
const JSArguments &  args,
const std::wstring &  frameName = L"" 
)

Call a certain function defined in Javascript directly.

Parameters:
object The name of the object that contains the function, pass an empty string if the function is defined in the global scope.
function The name of the function.
args The arguments to pass to the function.
frameName Optional, the name of the frame to execute in; leave this blank to execute in the main frame.

void Awesomium::WebView::clearAllURLFilters (  ) 

Clears all URL Filter rules.

void Awesomium::WebView::copy (  ) 

Invokes a 'copy' action using the system clipboard.

void Awesomium::WebView::createObject ( const std::wstring &  objectName  ) 

Creates a new global Javascript object that will persist throughout the lifetime of this WebView. This object is managed directly by Awesomium and so you can modify its properties and bind callback functions via WebView::setObjectProperty and WebView::setObjectCallback, respectively.

Parameters:
objectName The name of the object.

void Awesomium::WebView::cut (  ) 

Invokes a 'cut' action using the system clipboard.

void Awesomium::WebView::deselectAll (  ) 

De-selects all items on the current page.

void Awesomium::WebView::destroy (  ) 

Explicitly destroys this WebView instance. If you neglect to call this, the WebCore singleton will automatically destroy all lingering WebView instances at shutdown.

Note:
This should NEVER be called directly from one of the notifications of WebViewListener.

void Awesomium::WebView::destroyObject ( const std::wstring &  objectName  ) 

Destroys a Javascript object previously created by WebView::createObject.

Parameters:
objectName The name of the object to destroy.

void Awesomium::WebView::executeJavascript ( const std::wstring &  javascript,
const std::wstring &  frameName = L"" 
)

Executes a string of Javascript in the context of the current page asynchronously.

Parameters:
javascript The wide string of Javascript to execute.
frameName Optional, the name of the frame to execute in; leave this blank to execute in the main frame.

void Awesomium::WebView::executeJavascript ( const std::string &  javascript,
const std::wstring &  frameName = L"" 
)

Executes a string of Javascript in the context of the current page asynchronously.

Parameters:
javascript The ASCII string of Javascript to execute.
frameName Optional, the name of the frame to execute in; leave this blank to execute in the main frame.

Awesomium::FutureJSValue Awesomium::WebView::executeJavascriptWithResult ( const std::wstring &  javascript,
const std::wstring &  frameName = L"" 
)

Executes a string of Javascript in the context of the current page asynchronously with a result.

Parameters:
javascript The wide string of Javascript to execute.
frameName Optional, the name of the frame to execute in; leave this blank to execute in the main frame.
Returns:
Returns a 'FutureJSValue' which is basically an 'IOU' for the future JSValue result. You can obtain the actual result via FutureJSValue::get later.

Awesomium::FutureJSValue Awesomium::WebView::executeJavascriptWithResult ( const std::string &  javascript,
const std::wstring &  frameName = L"" 
)

Executes a string of Javascript in the context of the current page asynchronously with a result.

Parameters:
javascript The ASCII string of Javascript to execute.
frameName Optional, the name of the frame to execute in; leave this blank to execute in the main frame.
Returns:
Returns a 'FutureJSValue' which is basically an 'IOU' for the future JSValue result. You can obtain the actual result via FutureJSValue::get later.

void Awesomium::WebView::focus (  ) 

Notifies the current page that is has gained focus.

void Awesomium::WebView::getContentAsText ( std::wstring &  result,
int  maxChars 
)

Retrieves the content of the current page as plain text.

Parameters:
result The wide string to store the retrieved text in.
maxChars The maximum number of characters to retrieve.
Note:
Warning: The performance of this function depends upon the number of retrieved characters and the complexity of the page.

Awesomium::WebViewListener * Awesomium::WebView::getListener (  ) 

Retrieves the current WebViewListener.

Returns:
If a WebViewListener is registered, returns a pointer to the instance, otherwise returns 0.

void Awesomium::WebView::goToHistoryOffset ( int  offset  ) 

Navigates back/forward in history via a relative offset.

Note:
For example, to go back one page: myView->goToHistoryOffset(-1); Or, to go forward one page: myView->goToHistoryOffset(1);
Parameters:
offset The relative offset in history to navigate to.

void Awesomium::WebView::injectKeyboardEvent ( const WebKeyboardEvent keyboardEvent  ) 

Injects a keyboard event. See WebKeyboardEvent.h for more information.

Parameters:
keyboardEvent The keyboard event to inject.

void Awesomium::WebView::injectMouseDown ( Awesomium::MouseButton  button  ) 

Injects a mouse-down event.

Parameters:
button The button that was pressed.

void Awesomium::WebView::injectMouseMove ( int  x,
int  y 
)

Injects a mouse-move event in local coordinates.

Parameters:
x The absolute x-coordinate of the mouse (localized to the WebView).
y The absolute y-coordinate of the mouse (localized to the WebView).

void Awesomium::WebView::injectMouseUp ( Awesomium::MouseButton  button  ) 

Injects a mouse-up event.

Parameters:
button The button that was released.

void Awesomium::WebView::injectMouseWheel ( int  scrollAmount  ) 

Injects a mouse-wheel event.

Parameters:
scrollAmount The relative amount of pixels to scroll by.

bool Awesomium::WebView::isDirty (  ) 

Returns whether or not the WebView is dirty and needs to be re-rendered via WebView::render.

Returns:
If the WebView is dirty, returns true, otherwise returns false.

void Awesomium::WebView::loadFile ( const std::string &  file,
const std::wstring &  frameName = L"" 
)

Loads a local file into the WebView asynchronously.

Parameters:
file The file to load.
frameName Optional, the name of the frame to load the file in; leave this blank to load in the main frame.
Note:
The file should exist within the base directory (specified via WebCore::setBaseDirectory).

void Awesomium::WebView::loadHTML ( const std::wstring &  html,
const std::wstring &  frameName = L"" 
)

Loads a string of HTML into the WebView asynchronously.

Parameters:
html The HTML string (wide) to load.
frameName Optional, the name of the frame to load the HTML in; leave this blank to load in the main frame.
Note:
The base directory (specified via WebCore::setBaseDirectory) will be used to resolve relative URLs/resources (such as images, links, etc).

void Awesomium::WebView::loadHTML ( const std::string &  html,
const std::wstring &  frameName = L"" 
)

Loads a string of HTML into the WebView asynchronously.

Parameters:
html The HTML string (ASCII) to load.
frameName Optional, the name of the frame to load the HTML in; leave this blank to load in the main frame.
Note:
The base directory (specified via WebCore::setBaseDirectory) will be used to resolve relative URLs/resources (such as images, links, etc).

void Awesomium::WebView::loadURL ( const std::wstring &  url,
const std::wstring &  frameName = L"",
const std::string &  username = "",
const std::string &  password = "" 
)

Loads a URL into the WebView asynchronously.

Parameters:
url The URL to load.
frameName Optional, the name of the frame to load the URL in; leave this blank to load in the main frame.
username Optional, if the URL requires authentication, the username to authorize as.
password Optional, if the URL requires authentication, the password to use.

void Awesomium::WebView::loadURL ( const std::string &  url,
const std::wstring &  frameName = L"",
const std::string &  username = "",
const std::string &  password = "" 
)

Loads a URL into the WebView asynchronously.

Parameters:
url The URL to load.
frameName Optional, the name of the frame to load the URL in; leave this blank to load in the main frame.
username Optional, if the URL requires authentication, the username to authorize as.
password Optional, if the URL requires authentication, the password to use.

void Awesomium::WebView::paste (  ) 

Invokes a 'paste' action using the system clipboard.

void Awesomium::WebView::removeHeaderRewriteRule ( const std::wstring &  rule  ) 

Removes a header re-write rule from this WebView.

Parameters:
rule The rule to remove (should match the string specified in WebView::addHeaderRewriteRule exactly).

void Awesomium::WebView::removeHeaderRewriteRulesByDefinitionName ( const std::string &  name  ) 

Removes all header re-write rules that are using a certain header definition.

Parameters:
name The name of the header definition (specified in WebView::setHeaderDefinition). If you specify an empty string, this will remove ALL header re-write rules.

void Awesomium::WebView::render ( unsigned char *  destination,
int  destRowSpan,
int  destDepth,
Awesomium::Rect renderedRect = 0 
)

Renders the WebView to an off-screen buffer.

Parameters:
destination The buffer to render to, its width and height should match the WebView's.
destRowSpan The row-span of the destination buffer (number of bytes per row).
destDepth The depth (bytes per pixel) of the destination buffer. Valid options include 3 (BGR/RGB) or 4 (BGRA/RGBA).
renderedRect Optional (pass 0 to ignore); if asynchronous rendering is not enabled, you can provide a pointer to a Rect to store the dimensions of the rendered area, or rather, the dimensions of the area that actually changed since the last render.

void Awesomium::WebView::resetZoom (  ) 

Resets the zoom level.

void Awesomium::WebView::resize ( int  width,
int  height 
)

Resizes this WebView to certain dimensions.

Parameters:
width The width to resize to.
height The height to resize to.

void Awesomium::WebView::selectAll (  ) 

Selects all items on the current page.

void Awesomium::WebView::setHeaderDefinition ( const std::string &  name,
const Awesomium::HeaderDefinition &  definition 
)

Defines a new Header Definition or updates it if it already exists.

Parameters:
name The unique name of the Header Definition; this is used to refer to it later in WebView::addHeaderRewriteRule and WebView::removeHeaderRewriteRulesByDefinitionName.
definition The header definition, a map of key/values representing an HTTP header.

void Awesomium::WebView::setListener ( Awesomium::WebViewListener listener  ) 

Registers a WebViewListener to call upon various events (such as load completions, callbacks, title receptions, cursor changes, etc).

Parameters:
listener The WebViewListener to register or NULL to clear any current registrations.

void Awesomium::WebView::setObjectCallback ( const std::wstring &  objectName,
const std::wstring &  callbackName 
)

Sets a callback function of a Javascript object previously created by WebView::createObject. This is very useful for passing events from Javascript to C++. To receive notification of the callback, a WebViewListener should be registered (see WebView::setListener and WebViewListener::onCallback).

Parameters:
objectName The name of the Javascript object.
callbackName The name of the callback function.

void Awesomium::WebView::setObjectProperty ( const std::wstring &  objectName,
const std::wstring &  propName,
const JSValue value 
)

Sets a property of a Javascript object previously created by WebView::createObject.

Parameters:
objectName The name of the Javascript object.
propName The name of the property.
value The javascript-value of the property.

void Awesomium::WebView::setTransparent ( bool  isTransparent  ) 

Sets whether or not pages should be rendered with a transparent background-color.

Parameters:
isTransparent Whether or not to force the background-color as transparent.

void Awesomium::WebView::setURLFilteringMode ( URLFilteringMode  mode  ) 

Sets the current URL Filtering Mode (default is UFM_NONE). See URLFilteringMode for more information on the modes.

Parameters:
mode The URL filtering mode to use.

void Awesomium::WebView::unfocus (  ) 

Notifies the current page that it has lost focus.

void Awesomium::WebView::zoomIn (  ) 

Zooms into the page, enlarging by 20%.

void Awesomium::WebView::zoomOut (  ) 

Zooms out of the page, reducing by 20%.


The documentation for this class was generated from the following files:

Generated on Wed Sep 23 14:27:48 2009 for Awesomium by  doxygen 1.5.8