Add tkinter_.py example (#255) among others.

Update examples and unit tests, minor fixes.

Add FocusHandler interface, see API docs and Tkinter example.

Update documentation for cefpython.ExceptHook.

Fix cefpython Shutdown internals.

Refactor client_handler/.

Rename src/cython_includes/ to src/extern/, and create src/extern_cef/.

Author: cztomczak

api/API-categories.md

@@ -40,6 +40,7 @@
 
  * [DisplayHandler](DisplayHandler.md)
  * [DownloadHandler](DownloadHandler.md)
+ * [FocusHandler](FocusHandler.md)
  * [JavascriptContextHandler](JavascriptContextHandler.md)
  * [JavascriptDialogHandler](JavascriptDialogHandler.md)
  * [KeyboardHandler](KeyboardHandler.md)

api/API-index.md

@@ -45,7 +45,7 @@
   * [OnKeyEvent](KeyboardHandler.md#onkeyevent)
 * [StringVisitor (interface)](StringVisitor.md)
   * [Visit](StringVisitor.md#visit)
-* [Frame (object)](Image.md)
+* [Image (object)](Image.md)
   * [GetAsBitmap](Image.md#getasbitmap)
   * [GetAsPng](Image.md#getaspng)
   * [GetHeight](Image.md#getheight)
@@ -56,6 +56,10 @@
   * [OnBeforeUnloadJavascriptDialog](JavascriptDialogHandler.md#onbeforeunloadjavascriptdialog)
   * [OnResetJavascriptDialogState](JavascriptDialogHandler.md#onresetjavascriptdialogstate)
   * [OnJavascriptDialogClosed](JavascriptDialogHandler.md#onjavascriptdialogclosed)
+* [FocusHandler (interface)](FocusHandler.md)
+  * [OnTakeFocus](FocusHandler.md#ontakefocus)
+  * [OnSetFocus](FocusHandler.md#onsetfocus)
+  * [OnGotFocus](FocusHandler.md#ongotfocus)
 * [DisplayHandler (interface)](DisplayHandler.md)
   * [OnAddressChange](DisplayHandler.md#onaddresschange)
   * [OnTitleChange](DisplayHandler.md#ontitlechange)

api/FocusHandler.md

@@ -0,0 +1,62 @@
+[API categories](API-categories.md) | [API index](API-index.md)
+
+
+# FocusHandler (interface)
+
+Implement this interface to handle events related to focus. The methods of
+this class will be called on the UI thread.
+
+
+Table of contents:
+* [Callbacks](#callbacks)
+  * [OnTakeFocus](#ontakefocus)
+  * [OnSetFocus](#onsetfocus)
+  * [OnGotFocus](#ongotfocus)
+
+
+## Callbacks
+
+
+### OnTakeFocus
+
+| Parameter | Type |
+| --- | --- |
+| browser | [Browser](Browser.md) |
+| next | bool |
+| __Return__ | void |
+
+Description from upstream CEF:
+> Called when the browser component is about to loose focus. For instance, if
+> focus was on the last HTML element and the user pressed the TAB key. |next|
+> will be true if the browser is giving focus to the next component and false
+> if the browser is giving focus to the previous component.
+
+
+### OnSetFocus
+
+| Parameter | Type |
+| --- | --- |
+| browser | [Browser](Browser.md) |
+| source | cef_focus_source_t |
+| __Return__ | bool |
+
+Description from upstream CEF:
+> Called when the browser component is requesting focus. |source| indicates
+> where the focus request is originating from. Return false to allow the
+> focus to be set or true to cancel setting the focus.
+
+The `cef_focus_source_t` enum constants in the cefpython module:
+* FOCUS_SOURCE_NAVIGATION (The source is explicit navigation
+  via the API (LoadURL(), etc))
+* FOCUS_SOURCE_SYSTEM (The source is a system-generated focus event)
+
+
+### OnGotFocus
+
+| Parameter | Type |
+| --- | --- |
+| browser | [Browser](Browser.md) |
+| __Return__ | void |
+
+Description from upstream CEF:
+> Called when the browser component has received focus.

api/cefpython.md

@@ -74,8 +74,9 @@ browser.SetClientCallback("OnLoadEnd", OnLoadEnd)
 | traceObject | - |
 | __Return__ | string |
 
-Global except hook to exit app cleanly on error.
-
+Global except hook to exit app cleanly on error. CEF has a multiprocess
+architecture and when exiting you need to close all processes (main Browser
+process, Renderer process, GPU process, etc.) by calling Shutdown().
 This hook does the following: in case of exception write it to
 the "error.log" file, display it to the console, shutdown CEF
 and exit application immediately by ignoring "finally" (_exit()).

examples/gtk.py

@@ -6,21 +6,21 @@
 from gi.repository import GdkX11, Gtk, GObject, GdkPixbuf
 import sys
 import os
-import time
 
 
 def main():
-    version_info()
+    print("CEF Python {ver}".format(ver=cef.__version__))
+    print("Python {ver}".format(ver=sys.version[:6]))
+    print("GTK {major}.{minor}".format(
+            major=Gtk.get_major_version(),
+            minor=Gtk.get_minor_version()))
+    assert cef.__version__ >= "53.1", "CEF Python v53.1+ required to run this"
+    sys.excepthook = cef.ExceptHook  # To shutdown all CEF processes on error
+    cef.Initialize()
     app = GtkExample()
     SystemExit(app.run(sys.argv))
 
 
-def version_info():
-    print("CEF Python "+cef.__version__)
-    print("Python "+sys.version[:6])
-    print("GTK %s.%s" % (Gtk.get_major_version(), Gtk.get_minor_version()))
-
-
 class GtkExample(Gtk.Application):
 
     def __init__(self):
@@ -29,7 +29,6 @@ def __init__(self):
         self.window = None
 
     def run(self, argv):
-        cef.Initialize()
         GObject.threads_init()
         GObject.timeout_add(10, self.on_timer)
         self.connect("activate", self.on_activate)
@@ -54,7 +53,6 @@ def on_activate(self, *_):
         window_info.SetAsChild(self.window.get_property("window").get_xid())
         self.browser = cef.CreateBrowserSync(window_info,
                                              url="https://www.google.com/")
-        self.window.get_property("window").focus(False)
         self.window.show_all()
 
     def on_configure(self, *_):
@@ -73,13 +71,9 @@ def on_focus_in(self, *_):
         return False
 
     def on_window_close(self, *_):
-        # Close browser and free reference
+        # Close browser and free reference by setting to None
         self.browser.CloseBrowser(True)
-        del self.browser
-        # Give the browser some time to close before calling cef.Shutdown()
-        for i in range(10):
-            cef.MessageLoopWork()
-            time.sleep(0.01)
+        self.browser = None
 
     def on_shutdown(self, *_):
         cef.Shutdown()

examples/hello_world.py

@@ -5,22 +5,18 @@
 
 
 def main():
-    """Main entry point."""
-    version_info()
-    sys.excepthook = cef.ExceptHook
+    print("CEF Python {ver}".format(ver=cef.__version__))
+    print("Python {ver}".format(ver=sys.version[:6]))
+    assert cef.__version__ >= "53.1", "CEF Python v53.1+ required to run this"
+    sys.excepthook = cef.ExceptHook  # To shutdown all CEF processes on error
     cef.Initialize()
     browser = cef.CreateBrowserSync(url="https://www.google.com/")
     browser.SetClientHandler(ClientHandler())
     cef.MessageLoop()
     cef.Shutdown()
 
 
-def version_info():
-    print("CEF Python "+cef.__version__)
-    print("Python "+sys.version[:6])
-
-
-class ClientHandler:
+class ClientHandler(object):
 
     def OnBeforeClose(self, browser):
         """Called just before a browser is destroyed."""