| 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 * fl_engine_new_with_renderer:
65 * @project: an #FlDartProject.
66 * @renderer: an #FlRenderer.
67 *
68 * Creates new Flutter engine.
69 *
70 * Returns: a new #FlEngine.
71 */
72 FlEngine* fl_engine_new_with_renderer(FlDartProject* project,
73 FlRenderer* renderer);
74
75 /**
76 * fl_engine_get_renderer:
77 * @engine: an #FlEngine.
78 *
79 * Gets the renderer used by this engine.
80 *
81 * Returns: an #FlRenderer.
82 */
83 FlRenderer* fl_engine_get_renderer(FlEngine* engine);
84
85 /**
86 * fl_engine_start:
87 * @engine: an #FlEngine.
88 * @error: (allow-none): #GError location to store the error occurring, or %NULL
89 * to ignore.
90 *
91 * Starts the Flutter engine.
92 *
93 * Returns: %TRUE on success.
94 */
95 gboolean fl_engine_start(FlEngine* engine, GError** error);
96
97 /**
98 * fl_engine_get_embedder_api:
99 * @engine: an #FlEngine.
100 *
101 * Gets the embedder API proc table, allowing modificiations for unit testing.
102 *
103 * Returns: a mutable pointer to the embedder API proc table.
104 */
105 FlutterEngineProcTable* fl_engine_get_embedder_api(FlEngine* engine);
106
107 /**
108 * fl_engine_add_view:
109 * @engine: an #FlEngine.
110 * @width: width of view in pixels.
111 * @height: height of view in pixels.
112 * @pixel_ratio: scale factor for view.
113 * @cancellable: (allow-none): a #GCancellable or %NULL.
114 * @callback: (scope async): a #GAsyncReadyCallback to call when the view is
115 * added.
116 * @user_data: (closure): user data to pass to @callback.
117 *
118 * Asynchronously add a new view. The returned view ID should not be used until
119 * this function completes.
120 *
121 * Returns: the ID for the view.
122 */
123 FlutterViewId fl_engine_add_view(FlEngine* engine,
124 size_t width,
125 size_t height,
126 double pixel_ratio,
127 GCancellable* cancellable,
128 GAsyncReadyCallback callback,
129 gpointer user_data);
130
131 /**
132 * fl_engine_add_view_finish:
133 * @engine: an #FlEngine.
134 * @result: a #GAsyncResult.
135 * @error: (allow-none): #GError location to store the error occurring, or %NULL
136 * to ignore.
137 *
138 * Completes request started with fl_engine_add_view().
139 *
140 * Returns: %TRUE on success.
141 */
142 gboolean fl_engine_add_view_finish(FlEngine* engine,
143 GAsyncResult* result,
144 GError** error);
145
146 /**
147 * fl_engine_remove_view:
148 * @engine: an #FlEngine.
149 * @view_id: ID to remove.
150 * @cancellable: (allow-none): a #GCancellable or %NULL.
151 * @callback: (scope async): a #GAsyncReadyCallback to call when the view is
152 * added.
153 * @user_data: (closure): user data to pass to @callback.
154 *
155 * Removes a view previously added with fl_engine_add_view().
156 */
157 void fl_engine_remove_view(FlEngine* engine,
158 FlutterViewId view_id,
159 GCancellable* cancellable,
160 GAsyncReadyCallback callback,
161 gpointer user_data);
162
163 /**
164 * fl_engine_remove_view_finish:
165 * @engine: an #FlEngine.
166 * @result: a #GAsyncResult.
167 * @error: (allow-none): #GError location to store the error occurring, or %NULL
168 * to ignore.
169 *
170 * Completes request started with fl_engine_remove_view().
171 *
172 * Returns: %TRUE on succcess.
173 */
174 gboolean fl_engine_remove_view_finish(FlEngine* engine,
175 GAsyncResult* result,
176 GError** error);
177
178 /**
179 * fl_engine_set_platform_message_handler:
180 * @engine: an #FlEngine.
181 * @handler: function to call when a platform message is received.
182 * @user_data: (closure): user data to pass to @handler.
183 * @destroy_notify: (allow-none): a function which gets called to free
184 * @user_data, or %NULL.
185 *
186 * Registers the function called when a platform message is received. Call
187 * fl_engine_send_platform_message_response() with the response to this message.
188 * Ownership of #FlutterPlatformMessageResponseHandle is
189 * transferred to the caller, and the message must be responded to avoid
190 * memory leaks.
191 */
192 void fl_engine_set_platform_message_handler(
193 FlEngine* engine,
194 FlEnginePlatformMessageHandler handler,
195 gpointer user_data,
196 GDestroyNotify destroy_notify);
197
198 /**
199 * fl_engine_set_update_semantics_handler:
200 * @engine: an #FlEngine.
201 * @handler: function to call when a semantics update is received.
202 * @user_data: (closure): user data to pass to @handler.
203 * @destroy_notify: (allow-none): a function which gets called to free
204 * @user_data, or %NULL.
205 *
206 * Registers the function called when a semantics update is received.
207 */
208 void fl_engine_set_update_semantics_handler(
209 FlEngine* engine,
210 FlEngineUpdateSemanticsHandler handler,
211 gpointer user_data,
212 GDestroyNotify destroy_notify);
213
214 /**
215 * fl_engine_send_window_metrics_event:
216 * @engine: an #FlEngine.
217 * @view_id: the view that the event occured on.
218 * @width: width of the window in pixels.
219 * @height: height of the window in pixels.
220 * @pixel_ratio: scale factor for window.
221 *
222 * Sends a window metrics event to the engine.
223 */
224 void fl_engine_send_window_metrics_event(FlEngine* engine,
225 FlutterViewId view_id,
226 size_t width,
227 size_t height,
228 double pixel_ratio);
229
230 /**
231 * fl_engine_send_mouse_pointer_event:
232 * @engine: an #FlEngine.
233 * @view_id: the view that the event occured on.
234 * @phase: mouse phase.
235 * @timestamp: time when event occurred in microseconds.
236 * @x: x location of mouse cursor.
237 * @y: y location of mouse cursor.
238 * @device_kind: kind of pointing device.
239 * @scroll_delta_x: x offset of scroll.
240 * @scroll_delta_y: y offset of scroll.
241 * @buttons: buttons that are pressed.
242 *
243 * Sends a mouse pointer event to the engine.
244 */
245 void fl_engine_send_mouse_pointer_event(FlEngine* engine,
246 FlutterViewId view_id,
247 FlutterPointerPhase phase,
248 size_t timestamp,
249 double x,
250 double y,
251 FlutterPointerDeviceKind device_kind,
252 double scroll_delta_x,
253 double scroll_delta_y,
254 int64_t buttons);
255
256 /**
257 * fl_engine_send_pointer_pan_zoom_event:
258 * @engine: an #FlEngine.
259 * @view_id: the view that the event occured on.
260 * @timestamp: time when event occurred in microseconds.
261 * @x: x location of mouse cursor.
262 * @y: y location of mouse cursor.
263 * @phase: mouse phase.
264 * @pan_x: x offset of the pan/zoom in pixels.
265 * @pan_y: y offset of the pan/zoom in pixels.
266 * @scale: scale of the pan/zoom.
267 * @rotation: rotation of the pan/zoom in radians.
268 *
269 * Sends a pan/zoom pointer event to the engine.
270 */
271 void fl_engine_send_pointer_pan_zoom_event(FlEngine* engine,
272 FlutterViewId view_id,
273 size_t timestamp,
274 double x,
275 double y,
276 FlutterPointerPhase phase,
277 double pan_x,
278 double pan_y,
279 double scale,
280 double rotation);
281
282 /**
283 * fl_engine_send_key_event:
284 */
285 void fl_engine_send_key_event(FlEngine* engine,
286 const FlutterKeyEvent* event,
287 FlutterKeyEventCallback callback,
288 void* user_data);
289
290 /**
291 * fl_engine_dispatch_semantics_action:
292 * @engine: an #FlEngine.
293 * @id: the semantics action identifier.
294 * @action: the action being dispatched.
295 * @data: (allow-none): data associated with the action.
296 */
297 void fl_engine_dispatch_semantics_action(FlEngine* engine,
298 uint64_t id,
299 FlutterSemanticsAction action,
300 GBytes* data);
301
302 /**
303 * fl_engine_send_platform_message_response:
304 * @engine: an #FlEngine.
305 * @handle: handle that was provided in #FlEnginePlatformMessageHandler.
306 * @response: (allow-none): response to send or %NULL for an empty response.
307 * @error: (allow-none): #GError location to store the error occurring, or %NULL
308 * to ignore.
309 *
310 * Responds to a platform message.
311 *
312 * Returns: %TRUE on success.
313 */
314 gboolean fl_engine_send_platform_message_response(
315 FlEngine* engine,
316 const FlutterPlatformMessageResponseHandle* handle,
317 GBytes* response,
318 GError** error);
319
320 /**
321 * fl_engine_send_platform_message:
322 * @engine: an #FlEngine.
323 * @channel: channel to send to.
324 * @message: (allow-none): message buffer to send or %NULL for an empty message
325 * @cancellable: (allow-none): a #GCancellable or %NULL.
326 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
327 * satisfied.
328 * @user_data: (closure): user data to pass to @callback.
329 *
330 * Asynchronously sends a platform message.
331 */
332 void fl_engine_send_platform_message(FlEngine* engine,
333 const gchar* channel,
334 GBytes* message,
335 GCancellable* cancellable,
336 GAsyncReadyCallback callback,
337 gpointer user_data);
338
339 /**
340 * fl_engine_send_platform_message_finish:
341 * @engine: an #FlEngine.
342 * @result: a #GAsyncResult.
343 * @error: (allow-none): #GError location to store the error occurring, or %NULL
344 * to ignore.
345 *
346 * Completes request started with fl_engine_send_platform_message().
347 *
348 * Returns: message response on success or %NULL on error.
349 */
350 GBytes* fl_engine_send_platform_message_finish(FlEngine* engine,
351 GAsyncResult* result,
352 GError** error);
353
354 /**
355 * fl_engine_get_task_runner:
356 * @engine: an #FlEngine.
357 * @result: a #FlTaskRunner.
358 *
359 * Returns: task runner responsible for scheduling Flutter tasks.
360 */
361 FlTaskRunner* fl_engine_get_task_runner(FlEngine* engine);
362
363 /**
364 * fl_engine_execute_task:
365 * @engine: an #FlEngine.
366 * @task: a #FlutterTask to execute.
367 *
368 * Executes given Flutter task.
369 */
370 void fl_engine_execute_task(FlEngine* engine, FlutterTask* task);
371
372 /**
373 * fl_engine_mark_texture_frame_available:
374 * @engine: an #FlEngine.
375 * @texture_id: the identifier of the texture whose frame has been updated.
376 *
377 * Tells the Flutter engine that a new texture frame is available for the given
378 * texture.
379 *
380 * Returns: %TRUE on success.
381 */
382 gboolean fl_engine_mark_texture_frame_available(FlEngine* engine,
383 int64_t texture_id);
384
385 /**
386 * fl_engine_register_external_texture:
387 * @engine: an #FlEngine.
388 * @texture_id: the identifier of the texture that is available.
389 *
390 * Tells the Flutter engine that a new external texture is available.
391 *
392 * Returns: %TRUE on success.
393 */
394 gboolean fl_engine_register_external_texture(FlEngine* engine,
395 int64_t texture_id);
396
397 /**
398 * fl_engine_unregister_external_texture:
399 * @engine: an #FlEngine.
400 * @texture_id: the identifier of the texture that is not available anymore.
401 *
402 * Tells the Flutter engine that an existing external texture is not available
403 * anymore.
404 *
405 * Returns: %TRUE on success.
406 */
407 gboolean fl_engine_unregister_external_texture(FlEngine* engine,
408 int64_t texture_id);
409
410 /**
411 * fl_engine_update_accessibility_features:
412 * @engine: an #FlEngine.
413 * @flags: the features to enable in the accessibility tree.
414 *
415 * Tells the Flutter engine to update the flags on the accessibility tree.
416 */
417 void fl_engine_update_accessibility_features(FlEngine* engine, int32_t flags);
418
419 /**
420 * fl_engine_get_switches:
421 * @project: an #FlEngine.
422 *
423 * Determines the switches that should be passed to the Flutter engine.
424 *
425 * Returns: an array of switches to pass to the Flutter engine.
426 */
427 GPtrArray* fl_engine_get_switches(FlEngine* engine);
428
429 G_END_DECLS
430
431 #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:845
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:786
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:974
fl_engine_unregister_external_texture
gboolean fl_engine_unregister_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:988
fl_engine_add_view
FlutterViewId fl_engine_add_view(FlEngine *engine, size_t width, size_t height, double pixel_ratio, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
Definition: fl_engine.cc:641
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:509
fl_engine_execute_task
void fl_engine_execute_task(FlEngine *engine, FlutterTask *task)
Definition: fl_engine.cc:1006
flags
FlutterSemanticsFlag flags
Definition: fl_accessible_node.cc:106
fl_engine_add_view_finish
gboolean fl_engine_add_view_finish(FlEngine *engine, GAsyncResult *result, GError **error)
Definition: fl_engine.cc:679
user_data
FlKeyEvent uint64_t FlKeyResponderAsyncCallback gpointer user_data
Definition: fl_key_channel_responder.cc:121
fl_engine_remove_view_finish
gboolean fl_engine_remove_view_finish(FlEngine *engine, GAsyncResult *result, GError **error)
Definition: fl_engine.cc:711
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:754
fl_engine_register_external_texture
gboolean fl_engine_register_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:981
fl_engine_new_with_renderer
FlEngine * fl_engine_new_with_renderer(FlDartProject *project, FlRenderer *renderer)
Definition: fl_engine.cc:479
fl_engine_send_mouse_pointer_event
void fl_engine_send_mouse_pointer_event(FlEngine *engine, FlutterViewId view_id, FlutterPointerPhase phase, size_t timestamp, double x, double y, FlutterPointerDeviceKind device_kind, double scroll_delta_x, double scroll_delta_y, int64_t buttons)
Definition: fl_engine.cc:874
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:940
fl_engine_update_accessibility_features
void fl_engine_update_accessibility_features(FlEngine *engine, int32_t flags)
Definition: fl_engine.cc:1017
fl_engine_get_renderer
FlRenderer * fl_engine_get_renderer(FlEngine *engine)
Definition: fl_engine.cc:504
fl_engine_send_window_metrics_event
void fl_engine_send_window_metrics_event(FlEngine *engine, FlutterViewId view_id, size_t width, size_t height, double pixel_ratio)
Definition: fl_engine.cc:854
fl_engine_get_task_runner
FlTaskRunner * fl_engine_get_task_runner(FlEngine *engine)
Definition: fl_engine.cc:1001
fl_renderer.h
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:736
fl_engine_get_embedder_api
FlutterEngineProcTable * fl_engine_get_embedder_api(FlEngine *engine)
Definition: fl_engine.cc:637
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:718
height
const uint8_t uint32_t uint32_t * height
Definition: fl_pixel_buffer_texture_test.cc:39
fl_engine_get_switches
GPtrArray * fl_engine_get_switches(FlEngine *engine)
Definition: fl_engine.cc:1028
result
GAsyncResult * result
Definition: fl_text_input_handler.cc:106
FlEngineError
FlEngineError
Definition: fl_engine_private.h:23
fl_engine_remove_view
void fl_engine_remove_view(FlEngine *engine, FlutterViewId view_id, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
Definition: fl_engine.cc:686
fl_engine.h
error
const uint8_t uint32_t uint32_t GError ** error
Definition: fl_pixel_buffer_texture_test.cc:40
fl_engine_send_pointer_pan_zoom_event
void fl_engine_send_pointer_pan_zoom_event(FlEngine *engine, FlutterViewId view_id, size_t timestamp, double x, double y, FlutterPointerPhase phase, double pan_x, double pan_y, double scale, double rotation)
Definition: fl_engine.cc:908
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:953