@@ -91,3 +91,91 @@ API docs (the api/ directory in GitHub's repository):
9191
9292## Handling Python exceptions
9393...
94+
95+
96+ ## Message loop
97+
98+ Message loop is a programming construct that waits for and
99+ dispatches events or messages in a program. All desktop GUI
100+ programs must run some kind of message loop.
101+ The hello_world.py example doesn't depend on any third party GUI
102+ framework and thus can run CEF message loop directly by calling call
103+ cef.MessageLoop(). However in most of other examples that show how
104+ to embed CEF Python browser inside GUI frameworks such as
105+ Qt/wxPython/Tkinter, you can't call cef.MessageLoop(), because these
106+ frameworks run a message loop of its own. For such cases CEF provides
107+ cef.MessageLoopWork() which is for integrating CEF message loop into
108+ existing application message loop. Usually cef.MessageLoopWork() is
109+ called in a 10ms timer.
110+
111+ Calling cef.MessageLoopWork() in a timer is not the best performant
112+ way to run CEF message loop, also there are known bugs on some
113+ platforms when calling message loop work in a timer. CEF provides
114+ ApplicationSettings.[ external_message_pump] ( ../api/ApplicationSettings.md#external_message_pump )
115+ option for running an external message pump that you should use for
116+ best performance and to get rid of some bugs. However this option is
117+ still experimental, as during testing on Linux it actually made app
118+ x2 slower - it's a bug in upstream CEF that was reported. See
119+ [ Issue #246 ] ( ../../../issues/246 ) for more details. On Windows/Mac
120+ external message pump should work good, but it wasn't yet tested
121+ with CEF Python.
122+
123+ On Windows for best performance a multi-threaded message loop should
124+ be used, instead of cef.MessageLoopWork / external message pump. To do
125+ so, set
126+ ApplicationSettings.[ multi_threaded_message_loop] ( ../ApplicationSettings.md#multi_threaded_message_loop )
127+ to True and run a native message loop in your app. Don't call CEF's
128+ message loop. Create browser using
129+ cef.PostTask(cef.TID_UI, cef.CreateBrowserSync, ...).
130+ Note that when using multi-threaded message loop, CEF's UI thread
131+ is no more application's main thread, and that makes it a bit harder
132+ to correctly use CEF API. API docs explain on which threads a function
133+ may be called and in case of handlers' callbacks (and other interfaces)
134+ it is stated on which thread a callback will be called.
135+ See also [ Issue #133 ] ( ../../../issues/133 ) .
136+
137+
138+ ## Settings
139+
140+ ApplicationSettings, BrowserSettings, CommandLineSwitches, Chromium
141+ Preferences (not implemented yet) ...
142+
143+
144+ ## Handlers
145+
146+ ...
147+
148+
149+ ## Javascript integration
150+
151+ ...
152+
153+
154+ ## Plugins
155+
156+ ...
157+
158+
159+ ## Helper functions
160+
161+ GetApplicationPath...
162+ GetModulePath...
163+ others...
164+
165+ ## Build executable
166+
167+ Examples for building an executable are yet to be created:
168+
169+ * On Windows use py2exe ([ #35 ] ( ../../../issues/35 ) )
170+ or pyinstaller ([ #135 ] ( ../../../issues/135 ) )
171+ * On Mac use py2app or pyinstaller
172+ * On Linux use pyinstaller or cx_freeze
173+
174+
175+ ## What's next?
176+
177+ See more examples in the examples/ directory
178+ See API docs in the api/ directory
179+ Example usage of most of API is available in the unittests/ directory
180+ See the Knowledge base document
181+ Ask questions and report problems on the Forum
0 commit comments