mirror of
https://bitbucket.org/chromiumembedded/cef
synced 2025-06-05 21:39:12 +02:00
Set eol-style property on all files. Future commits will use the subversion auto-props configuration at http://src.chromium.org/viewvc/chrome/trunk/tools/buildbot/slave/config
git-svn-id: https://chromiumembedded.googlecode.com/svn/trunk@109 5089003a-bbd8-11dd-ad1f-f1f9622dbc98
This commit is contained in:
Marshall Greenblatt
@@ -1,248 +1,248 @@
|
||||
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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user