cef/tools/translator.README.txt

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.