| Flutter Linux Embedder |

fl_engine_private.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #ifndef FLUTTER_SHELL_PLATFORM_LINUX_FL_ENGINE_PRIVATE_H_
6 #define FLUTTER_SHELL_PLATFORM_LINUX_FL_ENGINE_PRIVATE_H_
7
8 #include <glib-object.h>
9
10 #include "flutter/shell/platform/embedder/embedder.h"
11 #include "flutter/shell/platform/linux/fl_renderer.h"
12 #include "flutter/shell/platform/linux/fl_task_runner.h"
13 #include "flutter/shell/platform/linux/public/flutter_linux/fl_dart_project.h"
14 #include "flutter/shell/platform/linux/public/flutter_linux/fl_engine.h"
15
16 G_BEGIN_DECLS
17
18 /**
19 * FlEngineError:
20 * Errors for #FlEngine objects to set on failures.
21 */
22
23 typedef enum {
24 // NOLINTBEGIN(readability-identifier-naming)
25 FL_ENGINE_ERROR_FAILED,
26 // NOLINTEND(readability-identifier-naming)
27 } FlEngineError;
28
29 GQuark fl_engine_error_quark(void) G_GNUC_CONST;
30
31 /**
32 * FlEnginePlatformMessageHandler:
33 * @engine: an #FlEngine.
34 * @channel: channel message received on.
35 * @message: message content received from Dart.
36 * @response_handle: a handle to respond to the message with.
37 * @user_data: (closure): data provided when registering this handler.
38 *
39 * Function called when platform messages are received.
40 *
41 * Returns: %TRUE if message has been accepted.
42 */
43 typedef gboolean (*FlEnginePlatformMessageHandler)(
44 FlEngine* engine,
45 const gchar* channel,
46 GBytes* message,
47 const FlutterPlatformMessageResponseHandle* response_handle,
48 gpointer user_data);
49
50 /**
51 * FlEngineUpdateSemanticsHandler:
52 * @engine: an #FlEngine.
53 * @node: semantic node information.
54 * @user_data: (closure): data provided when registering this handler.
55 *
56 * Function called when semantics node updates are received.
57 */
58 typedef void (*FlEngineUpdateSemanticsHandler)(
59 FlEngine* engine,
60 const FlutterSemanticsUpdate2* update,
61 gpointer user_data);
62
63 /**
64 * FlEngineOnPreEngineRestartHandler:
65 * @engine: an #FlEngine.
66 * @user_data: (closure): data provided when registering this handler.
67 *
68 * Function called right before the engine is restarted.
69 */
70 typedef void (*FlEngineOnPreEngineRestartHandler)(FlEngine* engine,
71 gpointer user_data);
72
73 /**
74 * fl_engine_new:
75 * @project: an #FlDartProject.
76 * @renderer: an #FlRenderer.
77 *
78 * Creates new Flutter engine.
79 *
80 * Returns: a new #FlEngine.
81 */
82 FlEngine* fl_engine_new(FlDartProject* project, FlRenderer* renderer);
83
84 /**
85 * fl_engine_get_embedder_api:
86 * @engine: an #FlEngine.
87 *
88 * Gets the embedder API proc table, allowing modificiations for unit testing.
89 *
90 * Returns: a mutable pointer to the embedder API proc table.
91 */
92 FlutterEngineProcTable* fl_engine_get_embedder_api(FlEngine* engine);
93
94 /**
95 * fl_engine_set_platform_message_handler:
96 * @engine: an #FlEngine.
97 * @handler: function to call when a platform message is received.
98 * @user_data: (closure): user data to pass to @handler.
99 * @destroy_notify: (allow-none): a function which gets called to free
100 * @user_data, or %NULL.
101 *
102 * Registers the function called when a platform message is received. Call
103 * fl_engine_send_platform_message_response() with the response to this message.
104 * Ownership of #FlutterPlatformMessageResponseHandle is
105 * transferred to the caller, and the message must be responded to avoid
106 * memory leaks.
107 */
108 void fl_engine_set_platform_message_handler(
109 FlEngine* engine,
110 FlEnginePlatformMessageHandler handler,
111 gpointer user_data,
112 GDestroyNotify destroy_notify);
113
114 /**
115 * fl_engine_set_update_semantics_handler:
116 * @engine: an #FlEngine.
117 * @handler: function to call when a semantics update is received.
118 * @user_data: (closure): user data to pass to @handler.
119 * @destroy_notify: (allow-none): a function which gets called to free
120 * @user_data, or %NULL.
121 *
122 * Registers the function called when a semantics update is received.
123 */
124 void fl_engine_set_update_semantics_handler(
125 FlEngine* engine,
126 FlEngineUpdateSemanticsHandler handler,
127 gpointer user_data,
128 GDestroyNotify destroy_notify);
129
130 /**
131 * fl_engine_set_on_pre_engine_restart_handler:
132 * @engine: an #FlEngine.
133 * @handler: function to call when the engine is restarted.
134 * @user_data: (closure): user data to pass to @handler.
135 * @destroy_notify: (allow-none): a function which gets called to free
136 * @user_data, or %NULL.
137 *
138 * Registers the function called right before the engine is restarted.
139 */
140 void fl_engine_set_on_pre_engine_restart_handler(
141 FlEngine* engine,
142 FlEngineOnPreEngineRestartHandler handler,
143 gpointer user_data,
144 GDestroyNotify destroy_notify);
145
146 /**
147 * fl_engine_start:
148 * @engine: an #FlEngine.
149 * @error: (allow-none): #GError location to store the error occurring, or %NULL
150 * to ignore.
151 *
152 * Starts the Flutter engine.
153 *
154 * Returns: %TRUE on success.
155 */
156 gboolean fl_engine_start(FlEngine* engine, GError** error);
157
158 /**
159 * fl_engine_send_window_metrics_event:
160 * @engine: an #FlEngine.
161 * @width: width of the window in pixels.
162 * @height: height of the window in pixels.
163 * @pixel_ratio: scale factor for window.
164 *
165 * Sends a window metrics event to the engine.
166 */
167 void fl_engine_send_window_metrics_event(FlEngine* engine,
168 size_t width,
169 size_t height,
170 double pixel_ratio);
171
172 /**
173 * fl_engine_send_window_state_event:
174 * @engine: an #FlEngine.
175 * @visible: whether the window is currently visible or not.
176 * @focused: whether the window is currently focused or not.
177 *
178 * Sends a window state event to the engine.
179 */
180 void fl_engine_send_window_state_event(FlEngine* engine,
181 gboolean visible,
182 gboolean focused);
183
184 /**
185 * fl_engine_send_mouse_pointer_event:
186 * @engine: an #FlEngine.
187 * @phase: mouse phase.
188 * @timestamp: time when event occurred in microseconds.
189 * @x: x location of mouse cursor.
190 * @y: y location of mouse cursor.
191 * @scroll_delta_x: x offset of scroll.
192 * @scroll_delta_y: y offset of scroll.
193 * @buttons: buttons that are pressed.
194 *
195 * Sends a mouse pointer event to the engine.
196 */
197 void fl_engine_send_mouse_pointer_event(FlEngine* engine,
198 FlutterPointerPhase phase,
199 size_t timestamp,
200 double x,
201 double y,
202 double scroll_delta_x,
203 double scroll_delta_y,
204 int64_t buttons);
205
206 void fl_engine_send_pointer_pan_zoom_event(FlEngine* self,
207 size_t timestamp,
208 double x,
209 double y,
210 FlutterPointerPhase phase,
211 double pan_x,
212 double pan_y,
213 double scale,
214 double rotation);
215
216 /**
217 * fl_engine_send_key_event:
218 */
219 void fl_engine_send_key_event(FlEngine* engine,
220 const FlutterKeyEvent* event,
221 FlutterKeyEventCallback callback,
222 void* user_data);
223
224 /**
225 * fl_engine_dispatch_semantics_action:
226 * @engine: an #FlEngine.
227 * @id: the semantics action identifier.
228 * @action: the action being dispatched.
229 * @data: (allow-none): data associated with the action.
230 */
231 void fl_engine_dispatch_semantics_action(FlEngine* engine,
232 uint64_t id,
233 FlutterSemanticsAction action,
234 GBytes* data);
235
236 /**
237 * fl_engine_send_platform_message_response:
238 * @engine: an #FlEngine.
239 * @handle: handle that was provided in #FlEnginePlatformMessageHandler.
240 * @response: (allow-none): response to send or %NULL for an empty response.
241 * @error: (allow-none): #GError location to store the error occurring, or %NULL
242 * to ignore.
243 *
244 * Responds to a platform message.
245 *
246 * Returns: %TRUE on success.
247 */
248 gboolean fl_engine_send_platform_message_response(
249 FlEngine* engine,
250 const FlutterPlatformMessageResponseHandle* handle,
251 GBytes* response,
252 GError** error);
253
254 /**
255 * fl_engine_send_platform_message:
256 * @engine: an #FlEngine.
257 * @channel: channel to send to.
258 * @message: (allow-none): message buffer to send or %NULL for an empty message
259 * @cancellable: (allow-none): a #GCancellable or %NULL.
260 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
261 * satisfied.
262 * @user_data: (closure): user data to pass to @callback.
263 *
264 * Asynchronously sends a platform message.
265 */
266 void fl_engine_send_platform_message(FlEngine* engine,
267 const gchar* channel,
268 GBytes* message,
269 GCancellable* cancellable,
270 GAsyncReadyCallback callback,
271 gpointer user_data);
272
273 /**
274 * fl_engine_send_platform_message_finish:
275 * @engine: an #FlEngine.
276 * @result: a #GAsyncResult.
277 * @error: (allow-none): #GError location to store the error occurring, or %NULL
278 * to ignore.
279 *
280 * Completes request started with fl_engine_send_platform_message().
281 *
282 * Returns: message response on success or %NULL on error.
283 */
284 GBytes* fl_engine_send_platform_message_finish(FlEngine* engine,
285 GAsyncResult* result,
286 GError** error);
287
288 /**
289 * fl_engine_get_task_runner:
290 * @engine: an #FlEngine.
291 * @result: a #FlTaskRunner.
292 *
293 * Returns: task runner responsible for scheduling Flutter tasks.
294 */
295 FlTaskRunner* fl_engine_get_task_runner(FlEngine* engine);
296
297 /**
298 * fl_engine_execute_task:
299 * @engine: an #FlEngine.
300 * @task: a #FlutterTask to execute.
301 *
302 * Executes given Flutter task.
303 */
304 void fl_engine_execute_task(FlEngine* engine, FlutterTask* task);
305
306 /**
307 * fl_engine_mark_texture_frame_available:
308 * @engine: an #FlEngine.
309 * @texture_id: the identifier of the texture whose frame has been updated.
310 *
311 * Tells the Flutter engine that a new texture frame is available for the given
312 * texture.
313 *
314 * Returns: %TRUE on success.
315 */
316 gboolean fl_engine_mark_texture_frame_available(FlEngine* engine,
317 int64_t texture_id);
318
319 /**
320 * fl_engine_register_external_texture:
321 * @engine: an #FlEngine.
322 * @texture_id: the identifier of the texture that is available.
323 *
324 * Tells the Flutter engine that a new external texture is available.
325 *
326 * Returns: %TRUE on success.
327 */
328 gboolean fl_engine_register_external_texture(FlEngine* engine,
329 int64_t texture_id);
330
331 /**
332 * fl_engine_unregister_external_texture:
333 * @engine: an #FlEngine.
334 * @texture_id: the identifier of the texture that is not available anymore.
335 *
336 * Tells the Flutter engine that an existing external texture is not available
337 * anymore.
338 *
339 * Returns: %TRUE on success.
340 */
341 gboolean fl_engine_unregister_external_texture(FlEngine* engine,
342 int64_t texture_id);
343
344 /**
345 * fl_engine_update_accessibility_features:
346 * @engine: an #FlEngine.
347 * @flags: the features to enable in the accessibility tree.
348 *
349 * Tells the Flutter engine to update the flags on the accessibility tree.
350 */
351 void fl_engine_update_accessibility_features(FlEngine* engine, int32_t flags);
352
353 /**
354 * fl_engine_get_switches:
355 * @project: an #FlEngine.
356 *
357 * Determines the switches that should be passed to the Flutter engine.
358 *
359 * Returns: an array of switches to pass to the Flutter engine.
360 */
361 GPtrArray* fl_engine_get_switches(FlEngine* engine);
362
363 G_END_DECLS
364
365 #endif // FLUTTER_SHELL_PLATFORM_LINUX_FL_ENGINE_PRIVATE_H_
fl_engine_send_platform_message_finish
GBytes * fl_engine_send_platform_message_finish(FlEngine *engine, GAsyncResult *result, GError **error)
Definition: fl_engine.cc:727
fl_engine_send_window_metrics_event
void fl_engine_send_window_metrics_event(FlEngine *engine, size_t width, size_t height, double pixel_ratio)
Definition: fl_engine.cc:748
FlEnginePlatformMessageHandler
gboolean(* FlEnginePlatformMessageHandler)(FlEngine *engine, const gchar *channel, GBytes *message, const FlutterPlatformMessageResponseHandle *response_handle, gpointer user_data)
Definition: fl_engine_private.h:43
event
FlKeyEvent * event
Definition: fl_key_channel_responder.cc:118
fl_engine_send_platform_message
void fl_engine_send_platform_message(FlEngine *engine, const gchar *channel, GBytes *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
Definition: fl_engine.cc:668
FL_ENGINE_ERROR_FAILED
@ FL_ENGINE_ERROR_FAILED
Definition: fl_engine_private.h:25
fl_engine_mark_texture_frame_available
gboolean fl_engine_mark_texture_frame_available(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:873
fl_engine_unregister_external_texture
gboolean fl_engine_unregister_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:887
fl_task_runner.h
FlEngineUpdateSemanticsHandler
void(* FlEngineUpdateSemanticsHandler)(FlEngine *engine, const FlutterSemanticsUpdate2 *update, gpointer user_data)
Definition: fl_engine_private.h:58
fl_engine_start
gboolean fl_engine_start(FlEngine *engine, GError **error)
Definition: fl_engine.cc:471
fl_engine_execute_task
void fl_engine_execute_task(FlEngine *engine, FlutterTask *task)
Definition: fl_engine.cc:905
fl_engine_send_pointer_pan_zoom_event
void fl_engine_send_pointer_pan_zoom_event(FlEngine *self, size_t timestamp, double x, double y, FlutterPointerPhase phase, double pan_x, double pan_y, double scale, double rotation)
Definition: fl_engine.cc:805
flags
FlutterSemanticsFlag flags
Definition: fl_accessible_node.cc:105
user_data
FlKeyEvent uint64_t FlKeyResponderAsyncCallback gpointer user_data
Definition: fl_key_channel_responder.cc:121
fl_engine_set_on_pre_engine_restart_handler
void fl_engine_set_on_pre_engine_restart_handler(FlEngine *engine, FlEngineOnPreEngineRestartHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_engine.cc:618
height
G_BEGIN_DECLS int height
Definition: fl_backing_store_provider.h:37
fl_engine_send_platform_message_response
gboolean fl_engine_send_platform_message_response(FlEngine *engine, const FlutterPlatformMessageResponseHandle *handle, GBytes *response, GError **error)
Definition: fl_engine.cc:636
fl_engine_register_external_texture
gboolean fl_engine_register_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:880
update
G_BEGIN_DECLS const FlutterSemanticsUpdate2 * update
Definition: fl_view_accessible.h:40
fl_dart_project.h
fl_engine_send_key_event
void fl_engine_send_key_event(FlEngine *engine, const FlutterKeyEvent *event, FlutterKeyEventCallback callback, void *user_data)
Definition: fl_engine.cc:839
fl_engine_update_accessibility_features
void fl_engine_update_accessibility_features(FlEngine *engine, int32_t flags)
Definition: fl_engine.cc:916
fl_engine_get_task_runner
FlTaskRunner * fl_engine_get_task_runner(FlEngine *engine)
Definition: fl_engine.cc:900
fl_renderer.h
fl_engine_new
FlEngine * fl_engine_new(FlDartProject *project, FlRenderer *renderer)
Definition: fl_engine.cc:455
fl_engine_set_update_semantics_handler
void fl_engine_set_update_semantics_handler(FlEngine *engine, FlEngineUpdateSemanticsHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_engine.cc:601
fl_engine_get_embedder_api
FlutterEngineProcTable * fl_engine_get_embedder_api(FlEngine *engine)
Definition: fl_engine.cc:579
fl_engine_set_platform_message_handler
void fl_engine_set_platform_message_handler(FlEngine *engine, FlEnginePlatformMessageHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_engine.cc:583
fl_engine_get_switches
GPtrArray * fl_engine_get_switches(FlEngine *engine)
Definition: fl_engine.cc:927
result
GAsyncResult * result
Definition: fl_text_input_plugin.cc:106
FlEngineError
FlEngineError
Definition: fl_engine_private.h:23
fl_engine.h
error
const uint8_t uint32_t uint32_t GError ** error
Definition: fl_pixel_buffer_texture_test.cc:40
fl_engine_send_mouse_pointer_event
void fl_engine_send_mouse_pointer_event(FlEngine *engine, FlutterPointerPhase phase, size_t timestamp, double x, double y, double scroll_delta_x, double scroll_delta_y, int64_t buttons)
Definition: fl_engine.cc:770
fl_engine_send_window_state_event
void fl_engine_send_window_state_event(FlEngine *engine, gboolean visible, gboolean focused)
Definition: fl_engine.cc:736
engine
FlEngine * engine
Definition: fl_view_accessible.cc:26
callback
FlKeyEvent uint64_t FlKeyResponderAsyncCallback callback
Definition: fl_key_channel_responder.cc:120
fl_engine_error_quark
GQuark fl_engine_error_quark(void) G_GNUC_CONST
texture_id
int64_t texture_id
Definition: texture_registrar_unittests.cc:24
width
const uint8_t uint32_t * width
Definition: fl_pixel_buffer_texture_test.cc:38
fl_engine_dispatch_semantics_action
void fl_engine_dispatch_semantics_action(FlEngine *engine, uint64_t id, FlutterSemanticsAction action, GBytes *data)
Definition: fl_engine.cc:852
FlEngineOnPreEngineRestartHandler
void(* FlEngineOnPreEngineRestartHandler)(FlEngine *engine, gpointer user_data)
Definition: fl_engine_private.h:70