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"
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)
26  // NOLINTEND(readability-identifier-naming)
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  */
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  */
109  FlEngine* engine,
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  */
125  FlEngine* engine,
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  */
141  FlEngine* engine,
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  */
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