Ultralight C API 1.3.0
|
Go to the source code of this file.
View is a web-page container rendered to an offscreen surface that you display yourself.
The View object is responsible for loading and rendering web-pages to an offscreen surface. It is completely isolated from the OS windowing system, you must forward all input events to it from your application.
Functions | |
ULExport ULViewConfig | ulCreateViewConfig () |
Create view configuration with default values (see <Ultralight/platform/View.h>). | |
ULExport void | ulDestroyViewConfig (ULViewConfig config) |
Destroy view configuration. | |
ULExport void | ulViewConfigSetIsAccelerated (ULViewConfig config, bool is_accelerated) |
Whether to render using the GPU renderer (accelerated) or the CPU renderer (unaccelerated). | |
ULExport void | ulViewConfigSetIsTransparent (ULViewConfig config, bool is_transparent) |
Set whether images should be enabled (Default = True). | |
ULExport void | ulViewConfigSetInitialDeviceScale (ULViewConfig config, double initial_device_scale) |
The initial device scale, ie. | |
ULExport void | ulViewConfigSetInitialFocus (ULViewConfig config, bool is_focused) |
Whether or not the View should initially have input focus. | |
ULExport void | ulViewConfigSetEnableImages (ULViewConfig config, bool enabled) |
Set whether images should be enabled (Default = True). | |
ULExport void | ulViewConfigSetEnableJavaScript (ULViewConfig config, bool enabled) |
Set whether JavaScript should be enabled (Default = True). | |
ULExport void | ulViewConfigSetFontFamilyStandard (ULViewConfig config, ULString font_name) |
Set default font-family to use (Default = Times New Roman). | |
ULExport void | ulViewConfigSetFontFamilyFixed (ULViewConfig config, ULString font_name) |
Set default font-family to use for fixed fonts, eg. | |
ULExport void | ulViewConfigSetFontFamilySerif (ULViewConfig config, ULString font_name) |
Set default font-family to use for serif fonts (Default = Times New Roman). | |
ULExport void | ulViewConfigSetFontFamilySansSerif (ULViewConfig config, ULString font_name) |
Set default font-family to use for sans-serif fonts (Default = Arial). | |
ULExport void | ulViewConfigSetUserAgent (ULViewConfig config, ULString agent_string) |
Set user agent string (See <Ultralight/platform/Config.h> for the default). | |
ULExport ULView | ulCreateView (ULRenderer renderer, unsigned int width, unsigned int height, ULViewConfig view_config, ULSession session) |
Create a View with certain size (in pixels). | |
ULExport void | ulDestroyView (ULView view) |
Destroy a View. | |
ULExport ULString | ulViewGetURL (ULView view) |
Get current URL. | |
ULExport ULString | ulViewGetTitle (ULView view) |
Get current title. | |
ULExport unsigned int | ulViewGetWidth (ULView view) |
Get the width, in pixels. | |
ULExport unsigned int | ulViewGetHeight (ULView view) |
Get the height, in pixels. | |
ULExport double | ulViewGetDeviceScale (ULView view) |
Get the device scale, ie. | |
ULExport void | ulViewSetDeviceScale (ULView view, double scale) |
Set the device scale. | |
ULExport bool | ulViewIsAccelerated (ULView view) |
Whether or not the View is GPU-accelerated. | |
ULExport bool | ulViewIsTransparent (ULView view) |
Whether or not the View supports transparent backgrounds. | |
ULExport bool | ulViewIsLoading (ULView view) |
Check if the main frame of the page is currrently loading. | |
ULExport ULRenderTarget | ulViewGetRenderTarget (ULView view) |
Get the RenderTarget for the View. | |
ULExport ULSurface | ulViewGetSurface (ULView view) |
Get the Surface for the View (native pixel buffer that the CPU renderer draws into). | |
ULExport void | ulViewLoadHTML (ULView view, ULString html_string) |
Load a raw string of HTML. | |
ULExport void | ulViewLoadURL (ULView view, ULString url_string) |
Load a URL into main frame. | |
ULExport void | ulViewResize (ULView view, unsigned int width, unsigned int height) |
Resize view to a certain width and height (in pixels). | |
ULExport JSContextRef | ulViewLockJSContext (ULView view) |
Acquire the page's JSContext for use with JavaScriptCore API. | |
ULExport void | ulViewUnlockJSContext (ULView view) |
Unlock the page's JSContext after a previous call to ulViewLockJSContext(). | |
ULExport ULString | ulViewEvaluateScript (ULView view, ULString js_string, ULString *exception) |
Evaluate a string of JavaScript and return result. | |
ULExport bool | ulViewCanGoBack (ULView view) |
Check if can navigate backwards in history. | |
ULExport bool | ulViewCanGoForward (ULView view) |
Check if can navigate forwards in history. | |
ULExport void | ulViewGoBack (ULView view) |
Navigate backwards in history. | |
ULExport void | ulViewGoForward (ULView view) |
Navigate forwards in history. | |
ULExport void | ulViewGoToHistoryOffset (ULView view, int offset) |
Navigate to arbitrary offset in history. | |
ULExport void | ulViewReload (ULView view) |
Reload current page. | |
ULExport void | ulViewStop (ULView view) |
Stop all page loads. | |
ULExport void | ulViewFocus (ULView view) |
Give focus to the View. | |
ULExport void | ulViewUnfocus (ULView view) |
Remove focus from the View and unfocus any focused input elements. | |
ULExport bool | ulViewHasFocus (ULView view) |
Whether or not the View has focus. | |
ULExport bool | ulViewHasInputFocus (ULView view) |
Whether or not the View has an input element with visible keyboard focus (indicated by a blinking caret). | |
ULExport void | ulViewFireKeyEvent (ULView view, ULKeyEvent key_event) |
Fire a keyboard event. | |
ULExport void | ulViewFireMouseEvent (ULView view, ULMouseEvent mouse_event) |
Fire a mouse event. | |
ULExport void | ulViewFireScrollEvent (ULView view, ULScrollEvent scroll_event) |
Fire a scroll event. | |
ULExport void | ulViewSetChangeTitleCallback (ULView view, ULChangeTitleCallback callback, void *user_data) |
Set callback for when the page title changes. | |
ULExport void | ulViewSetChangeURLCallback (ULView view, ULChangeURLCallback callback, void *user_data) |
Set callback for when the page URL changes. | |
ULExport void | ulViewSetChangeTooltipCallback (ULView view, ULChangeTooltipCallback callback, void *user_data) |
Set callback for when the tooltip changes (usually result of a mouse hover). | |
ULExport void | ulViewSetChangeCursorCallback (ULView view, ULChangeCursorCallback callback, void *user_data) |
Set callback for when the mouse cursor changes. | |
ULExport void | ulViewSetAddConsoleMessageCallback (ULView view, ULAddConsoleMessageCallback callback, void *user_data) |
Set callback for when a message is added to the console (useful for JavaScript / network errors and debugging). | |
ULExport void | ulViewSetCreateChildViewCallback (ULView view, ULCreateChildViewCallback callback, void *user_data) |
Set callback for when the page wants to create a new View. | |
ULExport void | ulViewSetCreateInspectorViewCallback (ULView view, ULCreateInspectorViewCallback callback, void *user_data) |
Set callback for when the page wants to create a new View to display the local inspector in. | |
ULExport void | ulViewSetBeginLoadingCallback (ULView view, ULBeginLoadingCallback callback, void *user_data) |
Set callback for when the page begins loading a new URL into a frame. | |
ULExport void | ulViewSetFinishLoadingCallback (ULView view, ULFinishLoadingCallback callback, void *user_data) |
Set callback for when the page finishes loading a URL into a frame. | |
ULExport void | ulViewSetFailLoadingCallback (ULView view, ULFailLoadingCallback callback, void *user_data) |
Set callback for when an error occurs while loading a URL into a frame. | |
ULExport void | ulViewSetWindowObjectReadyCallback (ULView view, ULWindowObjectReadyCallback callback, void *user_data) |
Set callback for when the JavaScript window object is reset for a new page load. | |
ULExport void | ulViewSetDOMReadyCallback (ULView view, ULDOMReadyCallback callback, void *user_data) |
Set callback for when all JavaScript has been parsed and the document is ready. | |
ULExport void | ulViewSetUpdateHistoryCallback (ULView view, ULUpdateHistoryCallback callback, void *user_data) |
Set callback for when the history (back/forward state) is modified. | |
ULExport void | ulViewSetNeedsPaint (ULView view, bool needs_paint) |
Set whether or not a view should be repainted during the next call to ulRender. | |
ULExport bool | ulViewGetNeedsPaint (ULView view) |
Whether or not a view should be painted during the next call to ulRender. | |
ULExport void | ulViewCreateLocalInspectorView (ULView view) |
Create an Inspector View to inspect / debug this View locally. | |
Typedefs | |
typedef void(* | ULChangeTitleCallback) (void *user_data, ULView caller, ULString title) |
typedef void(* | ULChangeURLCallback) (void *user_data, ULView caller, ULString url) |
typedef void(* | ULChangeTooltipCallback) (void *user_data, ULView caller, ULString tooltip) |
typedef void(* | ULChangeCursorCallback) (void *user_data, ULView caller, ULCursor cursor) |
typedef void(* | ULAddConsoleMessageCallback) (void *user_data, ULView caller, ULMessageSource source, ULMessageLevel level, ULString message, unsigned int line_number, unsigned int column_number, ULString source_id) |
typedef ULView(* | ULCreateChildViewCallback) (void *user_data, ULView caller, ULString opener_url, ULString target_url, bool is_popup, ULIntRect popup_rect) |
typedef ULView(* | ULCreateInspectorViewCallback) (void *user_data, ULView caller, bool is_local, ULString inspected_url) |
typedef void(* | ULBeginLoadingCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url) |
typedef void(* | ULFinishLoadingCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url) |
typedef void(* | ULFailLoadingCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url, ULString description, ULString error_domain, int error_code) |
typedef void(* | ULWindowObjectReadyCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url) |
typedef void(* | ULDOMReadyCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url) |
typedef void(* | ULUpdateHistoryCallback) (void *user_data, ULView caller) |
ULExport ULView ulCreateView | ( | ULRenderer | renderer, |
unsigned int | width, | ||
unsigned int | height, | ||
ULViewConfig | view_config, | ||
ULSession | session | ||
) |
Create a View with certain size (in pixels).
ULExport ULViewConfig ulCreateViewConfig | ( | ) |
Create view configuration with default values (see <Ultralight/platform/View.h>).
ULExport void ulDestroyViewConfig | ( | ULViewConfig | config | ) |
Destroy view configuration.
ULExport void ulViewConfigSetEnableImages | ( | ULViewConfig | config, |
bool | enabled | ||
) |
Set whether images should be enabled (Default = True).
ULExport void ulViewConfigSetEnableJavaScript | ( | ULViewConfig | config, |
bool | enabled | ||
) |
Set whether JavaScript should be enabled (Default = True).
ULExport void ulViewConfigSetFontFamilyFixed | ( | ULViewConfig | config, |
ULString | font_name | ||
) |
Set default font-family to use for fixed fonts, eg.
and
(Default = Courier New).
ULExport void ulViewConfigSetFontFamilySansSerif | ( | ULViewConfig | config, |
ULString | font_name | ||
) |
Set default font-family to use for sans-serif fonts (Default = Arial).
ULExport void ulViewConfigSetFontFamilySerif | ( | ULViewConfig | config, |
ULString | font_name | ||
) |
Set default font-family to use for serif fonts (Default = Times New Roman).
ULExport void ulViewConfigSetFontFamilyStandard | ( | ULViewConfig | config, |
ULString | font_name | ||
) |
Set default font-family to use (Default = Times New Roman).
ULExport void ulViewConfigSetInitialDeviceScale | ( | ULViewConfig | config, |
double | initial_device_scale | ||
) |
The initial device scale, ie.
the amount to scale page units to screen pixels. This should be set to the scaling factor of the device that the View is displayed on. (Default = 1.0)
ULExport void ulViewConfigSetInitialFocus | ( | ULViewConfig | config, |
bool | is_focused | ||
) |
Whether or not the View should initially have input focus.
(Default = True)
ULExport void ulViewConfigSetIsAccelerated | ( | ULViewConfig | config, |
bool | is_accelerated | ||
) |
Whether to render using the GPU renderer (accelerated) or the CPU renderer (unaccelerated).
This option is only valid if you're managing the Renderer yourself (eg, you've previously called ulCreateRenderer() instead of ulCreateApp()).
When true, the View will be rendered to an offscreen GPU texture using the GPU driver set in ulPlatformSetGPUDriver(). You can fetch details for the texture via ulViewGetRenderTarget().
When false (the default), the View will be rendered to an offscreen pixel buffer using the multithreaded CPU renderer. This pixel buffer can optionally be provided by the user– for more info see ulViewGetSurface().
ULExport void ulViewConfigSetIsTransparent | ( | ULViewConfig | config, |
bool | is_transparent | ||
) |
Set whether images should be enabled (Default = True).
ULExport void ulViewConfigSetUserAgent | ( | ULViewConfig | config, |
ULString | agent_string | ||
) |
Set user agent string (See <Ultralight/platform/Config.h> for the default).
Create an Inspector View to inspect / debug this View locally.
This will only succeed if you have the inspector assets in your filesystem– the inspector will look for file:///inspector/Main.html when it first loads.
You must handle ulViewSetCreateInspectorViewCallback so that the library has a View to display the inspector in. This function will call the callback only if an inspector view is not currently active.
Evaluate a string of JavaScript and return result.
js_string | The string of JavaScript to evaluate. |
exception | The address of a ULString to store a description of the last exception. Pass NULL to ignore this. Don't destroy the exception string returned, it's owned by the View. |
ULString script = ulCreateString("1 + 1"); ULString exception; ULString result = ulViewEvaluateScript(view, script, &exception); /* Use the result ("2") and exception description (if any) here. */ ulDestroyString(script);
ULExport void ulViewFireKeyEvent | ( | ULView | view, |
ULKeyEvent | key_event | ||
) |
Fire a keyboard event.
ULExport void ulViewFireMouseEvent | ( | ULView | view, |
ULMouseEvent | mouse_event | ||
) |
Fire a mouse event.
ULExport void ulViewFireScrollEvent | ( | ULView | view, |
ULScrollEvent | scroll_event | ||
) |
Fire a scroll event.
Give focus to the View.
You should call this to give visual indication that the View has input focus (changes active text selection colors, for example).
Get the device scale, ie.
the amount to scale page units to screen pixels.
For example, a value of 1.0 is equivalent to 100% zoom. A value of 2.0 is 200% zoom.
Whether or not a view should be painted during the next call to ulRender.
ULExport ULRenderTarget ulViewGetRenderTarget | ( | ULView | view | ) |
Get the RenderTarget for the View.
You can use this with your GPUDriver implementation to bind and display the corresponding texture in your application.
Get the Surface for the View (native pixel buffer that the CPU renderer draws into).
This function will return NULL if this View is GPU accelerated.
The default Surface is BitmapSurface but you can provide your own Surface implementation via ulPlatformSetSurfaceDefinition.
When using the default Surface, you can retrieve the underlying bitmap by casting ULSurface to ULBitmapSurface and calling ulBitmapSurfaceGetBitmap().
Get current title.
Get current URL.
Navigate to arbitrary offset in history.
Whether or not the View has an input element with visible keyboard focus (indicated by a blinking caret).
You can use this to decide whether or not the View should consume keyboard input events (useful in games with mixed UI and key handling).
Whether or not the View is GPU-accelerated.
If this is false, the page will be rendered via the CPU renderer.
Check if the main frame of the page is currrently loading.
Whether or not the View supports transparent backgrounds.
ULExport JSContextRef ulViewLockJSContext | ( | ULView | view | ) |
Acquire the page's JSContext for use with JavaScriptCore API.
Resize view to a certain width and height (in pixels).
ULExport void ulViewSetAddConsoleMessageCallback | ( | ULView | view, |
ULAddConsoleMessageCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when a message is added to the console (useful for JavaScript / network errors and debugging).
ULExport void ulViewSetBeginLoadingCallback | ( | ULView | view, |
ULBeginLoadingCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the page begins loading a new URL into a frame.
ULExport void ulViewSetChangeCursorCallback | ( | ULView | view, |
ULChangeCursorCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the mouse cursor changes.
ULExport void ulViewSetChangeTitleCallback | ( | ULView | view, |
ULChangeTitleCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the page title changes.
ULExport void ulViewSetChangeTooltipCallback | ( | ULView | view, |
ULChangeTooltipCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the tooltip changes (usually result of a mouse hover).
ULExport void ulViewSetChangeURLCallback | ( | ULView | view, |
ULChangeURLCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the page URL changes.
ULExport void ulViewSetCreateChildViewCallback | ( | ULView | view, |
ULCreateChildViewCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the page wants to create a new View.
This is usually the result of a user clicking a link with target="_blank" or by JavaScript calling window.open(url).
To allow creation of these new Views, you should create a new View in this callback, resize it to your container, and return it. You are responsible for displaying the returned View.
You should return NULL if you want to block the action.
ULExport void ulViewSetCreateInspectorViewCallback | ( | ULView | view, |
ULCreateInspectorViewCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the page wants to create a new View to display the local inspector in.
You should create a new View in this callback, resize it to your container, and return it. You are responsible for displaying the returned View.
ULExport void ulViewSetDOMReadyCallback | ( | ULView | view, |
ULDOMReadyCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when all JavaScript has been parsed and the document is ready.
This is the best time to make any JavaScript calls that are dependent on DOM elements or scripts on the page.
ULExport void ulViewSetFailLoadingCallback | ( | ULView | view, |
ULFailLoadingCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when an error occurs while loading a URL into a frame.
ULExport void ulViewSetFinishLoadingCallback | ( | ULView | view, |
ULFinishLoadingCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the page finishes loading a URL into a frame.
Set whether or not a view should be repainted during the next call to ulRender.
ULExport void ulViewSetUpdateHistoryCallback | ( | ULView | view, |
ULUpdateHistoryCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the history (back/forward state) is modified.
ULExport void ulViewSetWindowObjectReadyCallback | ( | ULView | view, |
ULWindowObjectReadyCallback | callback, | ||
void * | user_data | ||
) |
Set callback for when the JavaScript window object is reset for a new page load.
This is called before any scripts are executed on the page and is the earliest time to setup any initial JavaScript state or bindings.
The document is not guaranteed to be loaded/parsed at this point. If you need to make any JavaScript calls that are dependent on DOM elements or scripts on the page, use DOMReady instead.
The window object is lazily initialized (this will not be called on pages with no scripts).
Remove focus from the View and unfocus any focused input elements.
You should call this to give visual indication that the View has lost input focus.
Unlock the page's JSContext after a previous call to ulViewLockJSContext().
typedef void(* ULAddConsoleMessageCallback) (void *user_data, ULView caller, ULMessageSource source, ULMessageLevel level, ULString message, unsigned int line_number, unsigned int column_number, ULString source_id) |
typedef void(* ULBeginLoadingCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url) |
typedef ULView(* ULCreateChildViewCallback) (void *user_data, ULView caller, ULString opener_url, ULString target_url, bool is_popup, ULIntRect popup_rect) |
typedef ULView(* ULCreateInspectorViewCallback) (void *user_data, ULView caller, bool is_local, ULString inspected_url) |
typedef void(* ULDOMReadyCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url) |
typedef void(* ULFailLoadingCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url, ULString description, ULString error_domain, int error_code) |
typedef void(* ULFinishLoadingCallback) (void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url) |
typedef void(* ULUpdateHistoryCallback) (void *user_data, ULView caller) |