Update API docs, build instructions, tools and Tkinter example (#255).

.gitignore

@@ -3,3 +3,4 @@ build/
 *.log
 __pycache__/
 *.pyc
+cefclient

api/ApplicationSettings.md

@@ -47,6 +47,9 @@ The default values of options that are suggested in descriptions may not always
 
 There are hundreds of options that can be set through CEF/Chromium command line switches. These switches can be set programmatically by passing a dictionary with switches as second argument to [cefpython](cefpython.md).Initialize(). See the [CommandLineSwitches](CommandLineSwitches.md) wiki page for more information.
 
+Issue #244 is to add even more configurable settings by exposing API
+to Chromium Preferences.
+
 
 ## Settings
 

api/PaintBuffer.md

@@ -23,6 +23,10 @@ Table of contents:
 
 Get int pointer to the `void*` buffer.
 
+Description from upstream CEF:
+> |buffer| will be |width|*|height|*4 bytes in size and represents a BGRA
+> image with an upper-left origin.
+
 
 ### GetString
 

docs/Build-instructions.md

@@ -264,3 +264,9 @@ to be correct, try the -p0 or -p1 flag:
 ```
 git apply -p0 issue251.patch
 ```
+
+To create a patch from last two commits (no --relative flag available
+in this case, so must be in root CEF dir):
+```
+git format-patch --no-prefix -2 HEAD --stdout > issue251.patch
+```

examples/tkinter_.py

@@ -1,7 +1,8 @@
 # Example of embedding CEF Python browser using Tkinter toolkit.
 # This example has two widgets: a navigation bar and a browser.
 # Tested with Tk 8.6.
-# TODO: fix focus issues when switching controls / moving window
+
+# TODO: url entry loses keyboard focus when mouse hovers over browser (#255)
 
 from cefpython3 import cefpython as cef
 try:
@@ -143,6 +144,7 @@ def __init__(self, master):
         self.url_entry.bind("<FocusIn>", self.on_url_focus_in)
         self.url_entry.bind("<FocusOut>", self.on_url_focus_out)
         self.url_entry.bind("<Return>", self.on_load_url)
+        self.url_entry.bind("<Button-1>", self.on_button1)
         self.url_entry.grid(row=0, column=3,
                             sticky=(tk.N + tk.S + tk.E + tk.W))
         tk.Grid.rowconfigure(self, 0, weight=100)
@@ -177,6 +179,11 @@ def on_load_url(self, _):
         if self.master.get_browser():
             self.master.get_browser().LoadUrl(self.url_entry.get())
 
+    def on_button1(self, _):
+        """Fix CEF focus issues (#255). See also FocusHandler.OnGotFocus."""
+        logger.debug("NavigationBar.on_button1")
+        self.master.master.focus_force()
+
     def update_state(self):
         browser = self.master.get_browser()
         if not browser:
@@ -233,7 +240,8 @@ def embed_browser(self):
                                              url="https://www.google.com/")
         self.browser.SetClientHandler(LoadHandler(self))
         # FocusHandler requires cefpython 53.2+
-        # self.browser.SetClientHandler(FocusHandler(self))
+        if cef.__version__ >= "53.2":
+            self.browser.SetClientHandler(FocusHandler(self))
         self.message_loop_work()
 
     def message_loop_work(self):
@@ -277,6 +285,7 @@ def OnLoadStart(self, browser, _):
 
 
 class FocusHandler(object):
+    """FocusHandler is available in CEF Python 53.2 and higher."""
 
     def __init__(self, browser_frame):
         self.browser_frame = browser_frame
@@ -291,7 +300,10 @@ def OnSetFocus(self, _, source):
         return False
 
     def OnGotFocus(self, _):
+        """Fix CEF focus issues (#255). Call browser frame's focus_set
+           to get rid of type cursor in url entry widget."""
         logger.debug("FocusHandler.OnGotFocus")
+        self.browser_frame.focus_set()
 
 
 if __name__ == '__main__':

src/cefpython.pyx

@@ -429,6 +429,7 @@ from cef_path_util cimport *
 from cef_drag_data cimport *
 from cef_image cimport *
 from main_message_loop cimport *
+# noinspection PyUnresolvedReferences
 from cef_scoped_ptr cimport scoped_ptr
 
 

tools/automate.py

@@ -1,8 +1,6 @@
 # Copyright (c) 2016 CEF Python, see the Authors file. All rights reserved.
 
-# TODO: run automate-git.py using Python 2.7 from depot_tools
-
-"""Build CEF Python and use prebuilt CEF binaries or build CEF from sources.
+"""This tool automates building CEF from with CEF Python patches applied.
 
 Usage:
     automate.py (--prebuilt-cef | --build-cef)
@@ -24,9 +22,9 @@
     --no-cef-update          Do not update CEF sources (by default both cef/
                              directories are deleted on every run).
     --cef-branch=<b>         CEF branch. Defaults to CHROME_VERSION_BUILD from
-                             "src/version/cef_version_{platform}.h" (TODO).
+                             "src/version/cef_version_{platform}.h".
     --cef-commit=<c>         CEF revision. Defaults to CEF_COMMIT_HASH from
-                             "src/version/cef_version_{platform}.h" (TODO).
+                             "src/version/cef_version_{platform}.h".
     --build-dir=<dir1>       Build directory.
     --cef-build-dir=<dir2>   CEF build directory. By default same
                              as --build-dir.