249 lines
9.6 KiB
Plaintext
249 lines
9.6 KiB
Plaintext
Chromium Embedded Framework (CEF) Translator Tool -- translator.py
|
|
-------------------------------------------------------------------------------
|
|
|
|
Document Last Updated: June 20, 2009
|
|
|
|
|
|
OVERVIEW
|
|
--------
|
|
|
|
The CEF translator tool automatically generates CEF source code based on the
|
|
contents of the CEF header file (cef.h). The generated source code includes the
|
|
main C API header file (cef_capi.h) and all files in the libcef_dll/cpptoc and
|
|
libcef_dll/ctocpp directories.
|
|
|
|
If any differences are detected between the new translator-generated output and
|
|
the file that currently exists on disk a backup of the existing file will be
|
|
created before the new file is written (this behavior can be controlled using
|
|
a command-line switch -- see 'translator.py -h' for more information). Header
|
|
files (*.h) are completely generated by the translator and should never be
|
|
edited by hand. Implementation files (*.cc) contain user-created content within
|
|
method and function body blocks. The user-created content is extracted from the
|
|
existing file and inserted into the new translator-generated file. Any
|
|
differences between existing method/function prototypes and new method/function
|
|
prototypes will be noted as a warning in new output file.
|
|
|
|
// WARNING - CHANGED ATTRIBUTES
|
|
// REMOVED: const wchar_t* key
|
|
// ADDED: int index
|
|
// WARNING - CHANGED RETURN VALUE
|
|
// WAS: void
|
|
// NOW: int
|
|
#pragma message("Warning: "__FILE__": MyFunction prototype has changed")
|
|
|
|
Place-holder implementations will be added in the new output file for any
|
|
methods/functions that exist in the CEF header file but did not exist in the
|
|
current on-disk implementation file. Each time the translator re-generates the
|
|
implementation file it will warn if place-holder implementations exist. Delete
|
|
the indicated portion of the generated code after adding the implementation by
|
|
hand.
|
|
|
|
size_t CEF_CALLBACK frame_new_func(struct _cef_frame_t* self)
|
|
{
|
|
// BEGIN DELETE BEFORE MODIFYING
|
|
// AUTO-GENERATED CONTENT
|
|
#pragma message("Warning: "__FILE__": frame_new_func is not implemented")
|
|
// END DELETE BEFORE MODIFYING
|
|
}
|
|
|
|
The 'translator.bat' file can be used to run the translator tool with command-
|
|
line arguments that match the default CEF directory structure and output
|
|
options. Run 'translator.py -h' for a complete list of available command-line
|
|
arguments.
|
|
|
|
|
|
HEADER ATTRIBUTES
|
|
-----------------
|
|
|
|
Comment-based attribute tags are added before each function, class and method
|
|
definition in the CEF header file to provide the translator with additional
|
|
information about how the output should be generated. The attribute tags must
|
|
be in the form of a comma-delimited list of name=value pairs. Attribute names
|
|
and values must contain only alpha-numeric characters, numbers and underscores,
|
|
and must all exist on a single line.
|
|
|
|
/*--cef(name1=value1,name2=value2,name3=value3)--*/
|
|
|
|
Supported method attributes:
|
|
|
|
capi_name=[string] (Optional) Force a specific output name for the
|
|
resulting C API function.
|
|
|
|
Supported class attributes:
|
|
|
|
source=[library|client] (Required) Indicates whether the class
|
|
implementation is provided by the library or the
|
|
client. This effects the generation of guard
|
|
blocks in the cpptoc and ctocpp header files.
|
|
|
|
|
|
TRANSLATION RULES
|
|
-----------------
|
|
|
|
All C++ names in the CEF header file are written in CamelCaps format and all
|
|
C API translations are generated in lowercase_underscore format.
|
|
|
|
|
|
Translating Classes and Methods
|
|
-------------------------------
|
|
|
|
Class names and global function names must be prefixed with the 'Cef' string.
|
|
|
|
Global function translation
|
|
C++: void CefShutdown()
|
|
C API: void cef_shutdown()
|
|
|
|
The translation of a C++ class name to a C API structure name is prefixed with
|
|
'_' and postfixed with '_t'. A typedef of the C API structure to a value
|
|
without the prefixed '_' is also provided and may be used interchangeably.
|
|
|
|
Class name translation
|
|
C++: class CefPostData
|
|
C API: typedef struct _cef_post_data_t { ... } cef_post_data_t
|
|
|
|
The translation of a C++ virtual class method to a C API member function adds a
|
|
'self' structure pointer as the first parameter. This will always be a pointer
|
|
to the structure that contains the member function.
|
|
|
|
Virtual method translation
|
|
C++: virtual void SetFocus(bool enable)
|
|
C API: void set_focus(struct _cef_browser_t* self, int enable)
|
|
|
|
The translation of a C++ static class method to a C API global function
|
|
is prefixed with 'cef_classname_' where 'classname' is the
|
|
lowercase_underscore name of the class that contains the static method. Any
|
|
repeat of 'classname' in the function name is removed.
|
|
|
|
Static method translation
|
|
C++: static CefRefPtr<CefRequest> CreateRequest()
|
|
C API: struct _cef_request_t* cef_request_create()
|
|
|
|
|
|
Translating Data Types
|
|
----------------------
|
|
|
|
Data types that are available in both C++ and C are left unchanged. This
|
|
includes the 'double', 'int', 'long', 'size_t' and 'void' built-in types. Other
|
|
data types have differing levels of support as indicated below. The translation
|
|
tool will terminate with an exception if it encounters a data type
|
|
that it cannot translate.
|
|
|
|
Boolean type translation (argument or return value):
|
|
C++: bool
|
|
C API: int
|
|
|
|
String const by reference type translation (argument only)
|
|
C++: const std::wstring& value
|
|
C API: const wchar_t* value
|
|
|
|
String non-const by reference type translation (argument only)
|
|
C++: std::wstring& value
|
|
C API (result must be freed by the user):
|
|
cef_string_t* value
|
|
|
|
String non-const by reference type translation (return value only)
|
|
C++: std::wstring
|
|
C API (result must be freed by the user):
|
|
cef_string_t
|
|
|
|
Smart pointer type translation (argument or return value)
|
|
C++: CefRefPtr<CefBrowser>
|
|
C API: cef_browser_t*
|
|
|
|
Smart pointer by reference type translation (argument only)
|
|
C++: CefRefPtr<CefBrowser>& value
|
|
C API: cef_browser_t** value
|
|
|
|
String vector by reference type translation (argument only)
|
|
C++: std::vector<std::wstring>& value
|
|
C API (must be allocated and freed by the user):
|
|
cef_string_list_t value
|
|
|
|
Non-string vector non-const by reference type translation (argument only)
|
|
C++: std::vector<CefRefPtr<CefPostDataElement>>& elements
|
|
C API (changes the function prototype):
|
|
cef_post_data_element_t* func(..., int elementIndex, ...)
|
|
|
|
Non-string vector const by reference type translation (argument only)
|
|
C++: const std::vector<CefRefPtr<CefV8Value>>& arguments
|
|
C API (changes the function prototype):
|
|
... func(..., size_t argumentCount,
|
|
const struct _cef_v8value_t** arguments, ...)
|
|
|
|
String-to-string map by reference type translation (argument only)
|
|
C++: std::map<std::wstring,std::wstring>& value
|
|
C API (must be allocated and freed by the user):
|
|
cef_string_map_t value
|
|
|
|
|
|
Translating Comments
|
|
--------------------
|
|
|
|
Comments from the CEF header file are reproduced in the C API header file with
|
|
any referenced C++ types and terminology changed to reflect C API types and
|
|
terminology.
|
|
|
|
C++:
|
|
// Create a new CefV8Value object of the specified type. These methods
|
|
// should only be called from within the JavaScript context -- either in a
|
|
// CefV8Handler::Execute() callback or a CefHandler::HandleJSBinding()
|
|
// callback.
|
|
|
|
C API:
|
|
// Create a new cef_v8value_t object of the specified type. These functions
|
|
// should only be called from within the JavaScript context -- either in a
|
|
// cef_v8handler_t::execute() callback or a cef_handler_t::handle_jsbinding()
|
|
// callback.
|
|
|
|
Situations where the user is responsible for freeing strings allocated and
|
|
returned by the library are also noted by comments in the C API header file.
|
|
|
|
C API:
|
|
// The resulting string must be freed by calling cef_string_free().
|
|
|
|
A comment must occur immediately before the function, class or method that it
|
|
documents with no extra space in between. Comments may span multiple lines
|
|
but each line must start with the '//' comment identifier.
|
|
|
|
C++:
|
|
// Set focus for the browser window. If |enable| is true focus will be set
|
|
// to the window. Otherwise, focus will be removed.
|
|
/*--cef()--*/
|
|
virtual void SetFocus(bool enable) =0;
|
|
|
|
If two comments are separated by an empty line it will be assumed that the
|
|
higher comment represents a section header and additional space will be added
|
|
before it in the translated output.
|
|
|
|
C++:
|
|
// ARRAY METHODS - These methods are only available on arrays.
|
|
|
|
// Returns the number of elements in the array.
|
|
/*--cef()--*/
|
|
virtual int GetArrayLength() =0;
|
|
|
|
Empty lines and lines with the comment identifier but no content are considered
|
|
paragraph breaks for the purposes of wrapping the translated text. Any content
|
|
indented more than one space is reproduced as-is without content translation
|
|
or wrapping.
|
|
|
|
C++:
|
|
// Register a new V8 extension with the specified JavaScript extension code and
|
|
// handler. Functions implemented by the handler are prototyped using the
|
|
// keyword 'native'. The calling of a native function is restricted to the scope
|
|
// in which the prototype of the native function is defined.
|
|
//
|
|
// Example JavaScript extension code:
|
|
//
|
|
// // create the 'example' global object if it doesn't already exist.
|
|
// if (!example)
|
|
// example = {};
|
|
|
|
|
|
WORK REMAINING
|
|
--------------
|
|
|
|
o Generate place-holder implementations for C++ global functions.
|
|
o Automatically generate some function implementations based on an analysis of
|
|
the function prototype.
|