|
Ultralight C API 1.4.0
|
Web-page container rendered to an offscreen surface.
#include <Ultralight/CAPI/CAPI_View.h>
The View class 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.
You can create a View by calling ulCreateView():
Functions | |
| ULViewConfig | ulCreateViewConfig () |
| Create view configuration with default values (see <Ultralight/platform/View.h>). | |
| void | ulDestroyViewConfig (ULViewConfig config) |
| Destroy view configuration. | |
| void | ulViewConfigSetDisplayId (ULViewConfig config, unsigned int display_id) |
| Set a user-generated id of the display (monitor, TV, or screen) that the View will be shown on. | |
| void | ulViewConfigSetIsAccelerated (ULViewConfig config, bool is_accelerated) |
| Set whether to render using the GPU renderer (accelerated) or the CPU renderer (unaccelerated). | |
| void | ulViewConfigSetIsTransparent (ULViewConfig config, bool is_transparent) |
| Set whether images should be enabled (Default = True). | |
| void | ulViewConfigSetInitialDeviceScale (ULViewConfig config, double initial_device_scale) |
| Set the initial device scale, ie. | |
| void | ulViewConfigSetInitialFocus (ULViewConfig config, bool is_focused) |
| Set whether or not the View should initially have input focus. | |
| void | ulViewConfigSetEnableImages (ULViewConfig config, bool enabled) |
| Set whether images should be enabled (Default = True). | |
| void | ulViewConfigSetEnableJavaScript (ULViewConfig config, bool enabled) |
| Set whether JavaScript should be enabled (Default = True). | |
| void | ulViewConfigSetFontFamilyStandard (ULViewConfig config, ULString font_name) |
| Set default font-family to use (Default = Times New Roman). | |
| void | ulViewConfigSetFontFamilyFixed (ULViewConfig config, ULString font_name) |
| Set default font-family to use for fixed fonts, eg. | |
| void | ulViewConfigSetFontFamilySerif (ULViewConfig config, ULString font_name) |
| Set default font-family to use for serif fonts (Default = Times New Roman). | |
| void | ulViewConfigSetFontFamilySansSerif (ULViewConfig config, ULString font_name) |
| Set default font-family to use for sans-serif fonts (Default = Arial). | |
| void | ulViewConfigSetUserAgent (ULViewConfig config, ULString agent_string) |
| Set user agent string (See <Ultralight/platform/Config.h> for the default). | |
| ULView | ulCreateView (ULRenderer renderer, unsigned int width, unsigned int height, ULViewConfig view_config, ULSession session) |
| Create a View with certain size (in pixels). | |
| void | ulDestroyView (ULView view) |
| Destroy a View. | |
| ULString | ulViewGetURL (ULView view) |
| Get current URL. | |
| ULString | ulViewGetTitle (ULView view) |
| Get current title. | |
| unsigned int | ulViewGetWidth (ULView view) |
| Get the width, in pixels. | |
| unsigned int | ulViewGetHeight (ULView view) |
| Get the height, in pixels. | |
| unsigned int | ulViewGetDisplayId (ULView view) |
| void | ulViewSetDisplayId (ULView view, unsigned int display_id) |
| Set the display id of the View. | |
| double | ulViewGetDeviceScale (ULView view) |
| Get the device scale, ie. | |
| void | ulViewSetDeviceScale (ULView view, double scale) |
| Set the device scale. | |
| bool | ulViewIsAccelerated (ULView view) |
| Whether or not the View is GPU-accelerated. | |
| bool | ulViewIsTransparent (ULView view) |
| Whether or not the View supports transparent backgrounds. | |
| bool | ulViewIsLoading (ULView view) |
| Check if the main frame of the page is currrently loading. | |
| ULRenderTarget | ulViewGetRenderTarget (ULView view) |
| Get the RenderTarget for the View. | |
| ULSurface | ulViewGetSurface (ULView view) |
| Get the Surface for the View (native pixel buffer that the CPU renderer draws into). | |
| void | ulViewLoadHTML (ULView view, ULString html_string) |
| Load a raw string of HTML. | |
| void | ulViewLoadURL (ULView view, ULString url_string) |
| Load a URL into main frame. | |
| void | ulViewResize (ULView view, unsigned int width, unsigned int height) |
| Resize view to a certain width and height (in pixels). | |
| JSContextRef | ulViewLockJSContext (ULView view) |
| Acquire the page's JSContext for use with JavaScriptCore API. | |
| void | ulViewUnlockJSContext (ULView view) |
| Unlock the page's JSContext after a previous call to ulViewLockJSContext(). | |
| ULString | ulViewEvaluateScript (ULView view, ULString js_string, ULString *exception) |
| Evaluate a string of JavaScript and return result. | |
| bool | ulViewCanGoBack (ULView view) |
| Check if can navigate backwards in history. | |
| bool | ulViewCanGoForward (ULView view) |
| Check if can navigate forwards in history. | |
| void | ulViewGoBack (ULView view) |
| Navigate backwards in history. | |
| void | ulViewGoForward (ULView view) |
| Navigate forwards in history. | |
| void | ulViewGoToHistoryOffset (ULView view, int offset) |
| Navigate to arbitrary offset in history. | |
| void | ulViewReload (ULView view) |
| Reload current page. | |
| void | ulViewStop (ULView view) |
| Stop all page loads. | |
| void | ulViewFocus (ULView view) |
| Give focus to the View. | |
| void | ulViewUnfocus (ULView view) |
| Remove focus from the View and unfocus any focused input elements. | |
| bool | ulViewHasFocus (ULView view) |
| Whether or not the View has focus. | |
| bool | ulViewHasInputFocus (ULView view) |
| Whether or not the View has an input element with visible keyboard focus (indicated by a blinking caret). | |
| void | ulViewFireKeyEvent (ULView view, ULKeyEvent key_event) |
| Fire a keyboard event. | |
| void | ulViewFireMouseEvent (ULView view, ULMouseEvent mouse_event) |
| Fire a mouse event. | |
| void | ulViewFireScrollEvent (ULView view, ULScrollEvent scroll_event) |
| Fire a scroll event. | |
| void | ulViewSetChangeTitleCallback (ULView view, ULChangeTitleCallback callback, void *user_data) |
| Set callback for when the page title changes. | |
| void | ulViewSetChangeURLCallback (ULView view, ULChangeURLCallback callback, void *user_data) |
| Set callback for when the page URL changes. | |
| void | ulViewSetChangeTooltipCallback (ULView view, ULChangeTooltipCallback callback, void *user_data) |
| Set callback for when the tooltip changes (usually result of a mouse hover). | |
| void | ulViewSetChangeCursorCallback (ULView view, ULChangeCursorCallback callback, void *user_data) |
| Set callback for when the mouse cursor changes. | |
| 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). | |
| void | ulViewSetCreateChildViewCallback (ULView view, ULCreateChildViewCallback callback, void *user_data) |
| Set callback for when the page wants to create a new View. | |
| 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. | |
| void | ulViewSetBeginLoadingCallback (ULView view, ULBeginLoadingCallback callback, void *user_data) |
| Set callback for when the page begins loading a new URL into a frame. | |
| void | ulViewSetFinishLoadingCallback (ULView view, ULFinishLoadingCallback callback, void *user_data) |
| Set callback for when the page finishes loading a URL into a frame. | |
| void | ulViewSetFailLoadingCallback (ULView view, ULFailLoadingCallback callback, void *user_data) |
| Set callback for when an error occurs while loading a URL into a frame. | |
| void | ulViewSetWindowObjectReadyCallback (ULView view, ULWindowObjectReadyCallback callback, void *user_data) |
| Set callback for when the JavaScript window object is reset for a new page load. | |
| void | ulViewSetDOMReadyCallback (ULView view, ULDOMReadyCallback callback, void *user_data) |
| Set callback for when all JavaScript has been parsed and the document is ready. | |
| void | ulViewSetUpdateHistoryCallback (ULView view, ULUpdateHistoryCallback callback, void *user_data) |
| Set callback for when the history (back/forward state) is modified. | |
| void | ulViewSetNeedsPaint (ULView view, bool needs_paint) |
| Set whether or not a view should be repainted during the next call to ulRender. | |
| bool | ulViewGetNeedsPaint (ULView view) |
| Whether or not a view should be painted during the next call to ulRender. | |
| 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) |
| ULView ulCreateView | ( | ULRenderer | renderer, |
| unsigned int | width, | ||
| unsigned int | height, | ||
| ULViewConfig | view_config, | ||
| ULSession | session ) |
Create a View with certain size (in pixels).
| ULViewConfig ulCreateViewConfig | ( | ) |
Create view configuration with default values (see <Ultralight/platform/View.h>).
| void ulDestroyView | ( | ULView | view | ) |
Destroy a View.
| void ulDestroyViewConfig | ( | ULViewConfig | config | ) |
Destroy view configuration.
| bool ulViewCanGoBack | ( | ULView | view | ) |
Check if can navigate backwards in history.
| bool ulViewCanGoForward | ( | ULView | view | ) |
Check if can navigate forwards in history.
| void ulViewConfigSetDisplayId | ( | ULViewConfig | config, |
| unsigned int | display_id ) |
Set a user-generated id of the display (monitor, TV, or screen) that the View will be shown on.
Animations are driven based on the physical refresh rate of the display. Multiple Views can share the same display.
| void ulViewConfigSetEnableImages | ( | ULViewConfig | config, |
| bool | enabled ) |
Set whether images should be enabled (Default = True).
| void ulViewConfigSetEnableJavaScript | ( | ULViewConfig | config, |
| bool | enabled ) |
Set whether JavaScript should be enabled (Default = True).
| void ulViewConfigSetFontFamilyFixed | ( | ULViewConfig | config, |
| ULString | font_name ) |
Set default font-family to use for fixed fonts, eg.
and
(Default = Courier New).
| void ulViewConfigSetFontFamilySansSerif | ( | ULViewConfig | config, |
| ULString | font_name ) |
Set default font-family to use for sans-serif fonts (Default = Arial).
| void ulViewConfigSetFontFamilySerif | ( | ULViewConfig | config, |
| ULString | font_name ) |
Set default font-family to use for serif fonts (Default = Times New Roman).
| void ulViewConfigSetFontFamilyStandard | ( | ULViewConfig | config, |
| ULString | font_name ) |
Set default font-family to use (Default = Times New Roman).
| void ulViewConfigSetInitialDeviceScale | ( | ULViewConfig | config, |
| double | initial_device_scale ) |
Set 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)
| void ulViewConfigSetInitialFocus | ( | ULViewConfig | config, |
| bool | is_focused ) |
Set whether or not the View should initially have input focus.
(Default = True)
| void ulViewConfigSetIsAccelerated | ( | ULViewConfig | config, |
| bool | is_accelerated ) |
Set 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().
| void ulViewConfigSetIsTransparent | ( | ULViewConfig | config, |
| bool | is_transparent ) |
Set whether images should be enabled (Default = True).
| void ulViewConfigSetUserAgent | ( | ULViewConfig | config, |
| ULString | agent_string ) |
Set user agent string (See <Ultralight/platform/Config.h> for the default).
| void ulViewCreateLocalInspectorView | ( | ULView | view | ) |
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);
| void ulViewFireKeyEvent | ( | ULView | view, |
| ULKeyEvent | key_event ) |
Fire a keyboard event.
| void ulViewFireMouseEvent | ( | ULView | view, |
| ULMouseEvent | mouse_event ) |
Fire a mouse event.
| void ulViewFireScrollEvent | ( | ULView | view, |
| ULScrollEvent | scroll_event ) |
Fire a scroll event.
| void ulViewFocus | ( | ULView | view | ) |
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).
| double ulViewGetDeviceScale | ( | ULView | view | ) |
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.
| unsigned int ulViewGetDisplayId | ( | ULView | view | ) |
| unsigned int ulViewGetHeight | ( | ULView | view | ) |
Get the height, in pixels.
| bool ulViewGetNeedsPaint | ( | ULView | view | ) |
Whether or not a view should be painted during the next call to ulRender.
| 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.
| unsigned int ulViewGetWidth | ( | ULView | view | ) |
Get the width, in pixels.
| void ulViewGoBack | ( | ULView | view | ) |
Navigate backwards in history.
| void ulViewGoForward | ( | ULView | view | ) |
Navigate forwards in history.
| void ulViewGoToHistoryOffset | ( | ULView | view, |
| int | offset ) |
Navigate to arbitrary offset in history.
| bool ulViewHasFocus | ( | ULView | view | ) |
Whether or not the View has focus.
| bool ulViewHasInputFocus | ( | ULView | view | ) |
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).
| bool ulViewIsAccelerated | ( | ULView | view | ) |
Whether or not the View is GPU-accelerated.
If this is false, the page will be rendered via the CPU renderer.
| bool ulViewIsLoading | ( | ULView | view | ) |
Check if the main frame of the page is currrently loading.
| bool ulViewIsTransparent | ( | ULView | view | ) |
Whether or not the View supports transparent backgrounds.
| JSContextRef ulViewLockJSContext | ( | ULView | view | ) |
Acquire the page's JSContext for use with JavaScriptCore API.
| void ulViewReload | ( | ULView | view | ) |
Reload current page.
| void ulViewResize | ( | ULView | view, |
| unsigned int | width, | ||
| unsigned int | height ) |
Resize view to a certain width and height (in pixels).
| 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).
| void ulViewSetBeginLoadingCallback | ( | ULView | view, |
| ULBeginLoadingCallback | callback, | ||
| void * | user_data ) |
Set callback for when the page begins loading a new URL into a frame.
| void ulViewSetChangeCursorCallback | ( | ULView | view, |
| ULChangeCursorCallback | callback, | ||
| void * | user_data ) |
Set callback for when the mouse cursor changes.
| void ulViewSetChangeTitleCallback | ( | ULView | view, |
| ULChangeTitleCallback | callback, | ||
| void * | user_data ) |
Set callback for when the page title changes.
| void ulViewSetChangeTooltipCallback | ( | ULView | view, |
| ULChangeTooltipCallback | callback, | ||
| void * | user_data ) |
Set callback for when the tooltip changes (usually result of a mouse hover).
| void ulViewSetChangeURLCallback | ( | ULView | view, |
| ULChangeURLCallback | callback, | ||
| void * | user_data ) |
Set callback for when the page URL changes.
| 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.
| 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.
| void ulViewSetDeviceScale | ( | ULView | view, |
| double | scale ) |
Set the device scale.
| void ulViewSetDisplayId | ( | ULView | view, |
| unsigned int | display_id ) |
Set the display id of the View.
This should be called when the View is moved to another display.
| 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.
| void ulViewSetFailLoadingCallback | ( | ULView | view, |
| ULFailLoadingCallback | callback, | ||
| void * | user_data ) |
Set callback for when an error occurs while loading a URL into a frame.
| void ulViewSetFinishLoadingCallback | ( | ULView | view, |
| ULFinishLoadingCallback | callback, | ||
| void * | user_data ) |
Set callback for when the page finishes loading a URL into a frame.
| void ulViewSetNeedsPaint | ( | ULView | view, |
| bool | needs_paint ) |
Set whether or not a view should be repainted during the next call to ulRender.
| void ulViewSetUpdateHistoryCallback | ( | ULView | view, |
| ULUpdateHistoryCallback | callback, | ||
| void * | user_data ) |
Set callback for when the history (back/forward state) is modified.
| 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).
| void ulViewStop | ( | ULView | view | ) |
Stop all page loads.
| void ulViewUnfocus | ( | ULView | view | ) |
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.
| void ulViewUnlockJSContext | ( | ULView | view | ) |
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) |