| 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 * @device_kind: kind of pointing device.
192 * @scroll_delta_x: x offset of scroll.
193 * @scroll_delta_y: y offset of scroll.
194 * @buttons: buttons that are pressed.
195 *
196 * Sends a mouse pointer event to the engine.
197 */
198 void fl_engine_send_mouse_pointer_event(FlEngine* engine,
199 FlutterPointerPhase phase,
200 size_t timestamp,
201 double x,
202 double y,
203 FlutterPointerDeviceKind device_kind,
204 double scroll_delta_x,
205 double scroll_delta_y,
206 int64_t buttons);
207
208 void fl_engine_send_pointer_pan_zoom_event(FlEngine* self,
209 size_t timestamp,
210 double x,
211 double y,
212 FlutterPointerPhase phase,
213 double pan_x,
214 double pan_y,
215 double scale,
216 double rotation);
217
218 /**
219 * fl_engine_send_key_event:
220 */
221 void fl_engine_send_key_event(FlEngine* engine,
222 const FlutterKeyEvent* event,
223 FlutterKeyEventCallback callback,
224 void* user_data);
225
226 /**
227 * fl_engine_dispatch_semantics_action:
228 * @engine: an #FlEngine.
229 * @id: the semantics action identifier.
230 * @action: the action being dispatched.
231 * @data: (allow-none): data associated with the action.
232 */
233 void fl_engine_dispatch_semantics_action(FlEngine* engine,
234 uint64_t id,
235 FlutterSemanticsAction action,
236 GBytes* data);
237
238 /**
239 * fl_engine_send_platform_message_response:
240 * @engine: an #FlEngine.
241 * @handle: handle that was provided in #FlEnginePlatformMessageHandler.
242 * @response: (allow-none): response to send or %NULL for an empty response.
243 * @error: (allow-none): #GError location to store the error occurring, or %NULL
244 * to ignore.
245 *
246 * Responds to a platform message.
247 *
248 * Returns: %TRUE on success.
249 */
250 gboolean fl_engine_send_platform_message_response(
251 FlEngine* engine,
252 const FlutterPlatformMessageResponseHandle* handle,
253 GBytes* response,
254 GError** error);
255
256 /**
257 * fl_engine_send_platform_message:
258 * @engine: an #FlEngine.
259 * @channel: channel to send to.
260 * @message: (allow-none): message buffer to send or %NULL for an empty message
261 * @cancellable: (allow-none): a #GCancellable or %NULL.
262 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
263 * satisfied.
264 * @user_data: (closure): user data to pass to @callback.
265 *
266 * Asynchronously sends a platform message.
267 */
268 void fl_engine_send_platform_message(FlEngine* engine,
269 const gchar* channel,
270 GBytes* message,
271 GCancellable* cancellable,
272 GAsyncReadyCallback callback,
273 gpointer user_data);
274
275 /**
276 * fl_engine_send_platform_message_finish:
277 * @engine: an #FlEngine.
278 * @result: a #GAsyncResult.
279 * @error: (allow-none): #GError location to store the error occurring, or %NULL
280 * to ignore.
281 *
282 * Completes request started with fl_engine_send_platform_message().
283 *
284 * Returns: message response on success or %NULL on error.
285 */
286 GBytes* fl_engine_send_platform_message_finish(FlEngine* engine,
287 GAsyncResult* result,
288 GError** error);
289
290 /**
291 * fl_engine_get_task_runner:
292 * @engine: an #FlEngine.
293 * @result: a #FlTaskRunner.
294 *
295 * Returns: task runner responsible for scheduling Flutter tasks.
296 */
297 FlTaskRunner* fl_engine_get_task_runner(FlEngine* engine);
298
299 /**
300 * fl_engine_execute_task:
301 * @engine: an #FlEngine.
302 * @task: a #FlutterTask to execute.
303 *
304 * Executes given Flutter task.
305 */
306 void fl_engine_execute_task(FlEngine* engine, FlutterTask* task);
307
308 /**
309 * fl_engine_mark_texture_frame_available:
310 * @engine: an #FlEngine.
311 * @texture_id: the identifier of the texture whose frame has been updated.
312 *
313 * Tells the Flutter engine that a new texture frame is available for the given
314 * texture.
315 *
316 * Returns: %TRUE on success.
317 */
318 gboolean fl_engine_mark_texture_frame_available(FlEngine* engine,
319 int64_t texture_id);
320
321 /**
322 * fl_engine_register_external_texture:
323 * @engine: an #FlEngine.
324 * @texture_id: the identifier of the texture that is available.
325 *
326 * Tells the Flutter engine that a new external texture is available.
327 *
328 * Returns: %TRUE on success.
329 */
330 gboolean fl_engine_register_external_texture(FlEngine* engine,
331 int64_t texture_id);
332
333 /**
334 * fl_engine_unregister_external_texture:
335 * @engine: an #FlEngine.
336 * @texture_id: the identifier of the texture that is not available anymore.
337 *
338 * Tells the Flutter engine that an existing external texture is not available
339 * anymore.
340 *
341 * Returns: %TRUE on success.
342 */
343 gboolean fl_engine_unregister_external_texture(FlEngine* engine,
344 int64_t texture_id);
345
346 /**
347 * fl_engine_update_accessibility_features:
348 * @engine: an #FlEngine.
349 * @flags: the features to enable in the accessibility tree.
350 *
351 * Tells the Flutter engine to update the flags on the accessibility tree.
352 */
353 void fl_engine_update_accessibility_features(FlEngine* engine, int32_t flags);
354
355 /**
356 * fl_engine_get_switches:
357 * @project: an #FlEngine.
358 *
359 * Determines the switches that should be passed to the Flutter engine.
360 *
361 * Returns: an array of switches to pass to the Flutter engine.
362 */
363 GPtrArray* fl_engine_get_switches(FlEngine* engine);
364
365 G_END_DECLS
366
367 #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:750
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:771
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:691
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:897
fl_engine_unregister_external_texture
gboolean fl_engine_unregister_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:911
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:474
fl_engine_send_mouse_pointer_event
void fl_engine_send_mouse_pointer_event(FlEngine *engine, 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:793
fl_engine_execute_task
void fl_engine_execute_task(FlEngine *engine, FlutterTask *task)
Definition: fl_engine.cc:929
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:829
flags
FlutterSemanticsFlag flags
Definition: fl_accessible_node.cc:106
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:641
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:659
fl_engine_register_external_texture
gboolean fl_engine_register_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:904
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:863
fl_engine_update_accessibility_features
void fl_engine_update_accessibility_features(FlEngine *engine, int32_t flags)
Definition: fl_engine.cc:940
fl_engine_get_task_runner
FlTaskRunner * fl_engine_get_task_runner(FlEngine *engine)
Definition: fl_engine.cc:924
fl_renderer.h
fl_engine_new
FlEngine * fl_engine_new(FlDartProject *project, FlRenderer *renderer)
Definition: fl_engine.cc:458
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:624
fl_engine_get_embedder_api
FlutterEngineProcTable * fl_engine_get_embedder_api(FlEngine *engine)
Definition: fl_engine.cc:602
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:606
fl_engine_get_switches
GPtrArray * fl_engine_get_switches(FlEngine *engine)
Definition: fl_engine.cc:951
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_window_state_event
void fl_engine_send_window_state_event(FlEngine *engine, gboolean visible, gboolean focused)
Definition: fl_engine.cc:759
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:876
FlEngineOnPreEngineRestartHandler
void(* FlEngineOnPreEngineRestartHandler)(FlEngine *engine, gpointer user_data)
Definition: fl_engine_private.h:70