CEF Tutorial: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 29: Line 29:


Apart from these options a domain might be blacklisted due to malicious content. Such domains cannot be requested.
Apart from these options a domain might be blacklisted due to malicious content. Such domains cannot be requested.
=Local vs remote mode=
There are two modes CEF can run in:
Characteristics of local mode:
*you '''can''' execute Javascript code without any restriction (See: [[executeBrowserJavascript]])
*you '''can''' only load websites stored in the resource folder
*you '''cannot''' load remote content
Characteristics of remote mode:
*you '''cannot''' execute Javascript code
*you '''can''' only load remote content
*keep in mind that either loading remote websites or Javascript on remote websites can be disabled in the MTA settings
Changing the mode after the browser was created is not possible due to technical reasons.


=Resource management=
=Resource management=
Line 72: Line 87:
</body>
</body>
</html></syntaxhighlight>
</html></syntaxhighlight>
=Advanced usage=
Since our CEF implementation does not do z-ordering by default, you have to provide your own z-ordering mechanism.
You can find a basic implementation of such a mechanism here: https://github.com/Jusonex/mtasa_cef_tools
There are also a few utility functions which allow you to integrate these classes easily into your own object-oriented UI system.
I'll provide some code to use CEF along with CEGUI soon too.

Revision as of 21:32, 22 February 2015

This page gives you a brief introduction to CEF.

What is CEF?

CEF stands for Chromium Embedded Framework and is a framework for embedding Chromium-based browsers in other applications - in our case MTA. CEF is based on Google's Chromium project so it is also a fast, secure and stable web engine.

You can find more information about CEF on CEF's GoogleCode project page: https://code.google.com/p/chromiumembedded/

The basics

Creating a new browser is really simple. Let's open YouTube for example: 

-- Create a new remote browser (size is 800*600px) with transparency enabled
local browser = createBrowser(800, 600, true, true)

-- "Wait" for the browser (this is necessary, because CEF runs in a secondary thread and hence requires the 'asynchronous' event mechanism)
addEventHandler("onClientBrowserCreated", browser,
    function()
        -- We're ready to load the URL now (the source of this event is the browser that has been created)
        loadBrowserURL(source, "https://youtube.com/")
    end
)

This example does not require any domain requests as YouTube is whitelisted by default. More about domain requests below.

Domain request system

In order to prevent people from abusing the possibilities CEF offers, we decided to introduce a request system. This means the domain you want to load has to meet at least one of the following requirements:

  • it is whitelisted globally by the MTA team (you can create a post in [this topic] to suggest a new domain to be whitelisted) - **TODO: Add forum URL here**
  • the domain was requsted via requestBrowserDomains/Browser.requestDomains and accepted by the player before
  • the domain is on the user's whitelist (MTA settings => Tab: Browser => Whitelist)

Apart from these options a domain might be blacklisted due to malicious content. Such domains cannot be requested.

Local vs remote mode

There are two modes CEF can run in:

Characteristics of local mode:

  • you can execute Javascript code without any restriction (See: executeBrowserJavascript)
  • you can only load websites stored in the resource folder
  • you cannot load remote content

Characteristics of remote mode:

  • you cannot execute Javascript code
  • you can only load remote content
  • keep in mind that either loading remote websites or Javascript on remote websites can be disabled in the MTA settings

Changing the mode after the browser was created is not possible due to technical reasons.

Resource management

How to load local HTML files

Loading local HTML files works similar to loading images.

Add your HTML files to your meta.xml through the file tag: 

<file src="html/myAwesomeUI.html"/>

How to load local resources in local HTML files

Imagine you want to load an image or play a video from your MTA resource. This is possible via a custom URI scheme named mtalocal://

Example

This examples shows how to play a video. Note that you have to enable OOP.

Lua

-- Create a browser (local mode is also required to access local data)
local webView = Browser.create(640, 480, true, true)

addEventHandler("onClientBrowserCreated", webView,
     function()
    
          -- Load HTML UI
          webView:loadURL("html/myVideo.html")

     end
)

meta.xml

<file src="html/myVideo.html"/>
<file src="media/myVideo.webm"/>

HTML

This is the most interesting part: 

[html]
<!DOCTYPE HTML>
<html>
<head></head>
<body>
    <video width="640" height="480" controls>
         <source src="mtalocal://media/myVideo.webm" type="video/webm"/>
    </video>
</body>
</html>

Advanced usage

Since our CEF implementation does not do z-ordering by default, you have to provide your own z-ordering mechanism. You can find a basic implementation of such a mechanism here: https://github.com/Jusonex/mtasa_cef_tools There are also a few utility functions which allow you to integrate these classes easily into your own object-oriented UI system. I'll provide some code to use CEF along with CEGUI soon too.

Retrieved from "https://wiki.multitheftauto.com/wiki/CEF_Tutorial?oldid=44720"