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 {
26 
27 GQuark fl_engine_error_quark(void) G_GNUC_CONST;
28 
29 /**
30  * FlEnginePlatformMessageHandler:
31  * @engine: an #FlEngine.
32  * @channel: channel message received on.
33  * @message: message content received from Dart.
34  * @response_handle: a handle to respond to the message with.
35  * @user_data: (closure): data provided when registering this handler.
36  *
37  * Function called when platform messages are received.
38  *
39  * Returns: %TRUE if message has been accepted.
40  */
41 typedef gboolean (*FlEnginePlatformMessageHandler)(
42  FlEngine* engine,
43  const gchar* channel,
44  GBytes* message,
45  const FlutterPlatformMessageResponseHandle* response_handle,
46  gpointer user_data);
47 
48 /**
49  * FlEngineUpdateSemanticsNodeHandler:
50  * @engine: an #FlEngine.
51  * @node: semantic node information.
52  * @user_data: (closure): data provided when registering this handler.
53  *
54  * Function called when semantics node updates are received.
55  */
57  FlEngine* engine,
58  const FlutterSemanticsNode* node,
59  gpointer user_data);
60 
61 /**
62  * FlEngineOnPreEngineRestartHandler:
63  * @engine: an #FlEngine.
64  * @user_data: (closure): data provided when registering this handler.
65  *
66  * Function called right before the engine is restarted.
67  */
68 typedef void (*FlEngineOnPreEngineRestartHandler)(FlEngine* engine,
69  gpointer user_data);
70 
71 /**
72  * fl_engine_new:
73  * @project: an #FlDartProject.
74  * @renderer: an #FlRenderer.
75  *
76  * Creates new Flutter engine.
77  *
78  * Returns: a new #FlEngine.
79  */
80 FlEngine* fl_engine_new(FlDartProject* project, FlRenderer* renderer);
81 
82 /**
83  * fl_engine_get_embedder_api:
84  * @engine: an #FlEngine.
85  *
86  * Gets the embedder API proc table, allowing modificiations for unit testing.
87  *
88  * Returns: a mutable pointer to the embedder API proc table.
89  */
90 FlutterEngineProcTable* fl_engine_get_embedder_api(FlEngine* engine);
91 
92 /**
93  * fl_engine_set_platform_message_handler:
94  * @engine: an #FlEngine.
95  * @handler: function to call when a platform message is received.
96  * @user_data: (closure): user data to pass to @handler.
97  * @destroy_notify: (allow-none): a function which gets called to free
98  * @user_data, or %NULL.
99  *
100  * Registers the function called when a platform message is received. Call
101  * fl_engine_send_platform_message_response() with the response to this message.
102  * Ownership of #FlutterPlatformMessageResponseHandle is
103  * transferred to the caller, and the message must be responded to avoid
104  * memory leaks.
105  */
107  FlEngine* engine,
109  gpointer user_data,
110  GDestroyNotify destroy_notify);
111 
112 /**
113  * fl_engine_set_update_semantics_node_handler:
114  * @engine: an #FlEngine.
115  * @handler: function to call when a semantics node update is received.
116  * @user_data: (closure): user data to pass to @handler.
117  * @destroy_notify: (allow-none): a function which gets called to free
118  * @user_data, or %NULL.
119  *
120  * Registers the function called when a semantics node update is reveived.
121  */
123  FlEngine* engine,
125  gpointer user_data,
126  GDestroyNotify destroy_notify);
127 
128 /**
129  * fl_engine_set_on_pre_engine_restart_handler:
130  * @engine: an #FlEngine.
131  * @handler: function to call when the engine is restarted.
132  * @user_data: (closure): user data to pass to @handler.
133  * @destroy_notify: (allow-none): a function which gets called to free
134  * @user_data, or %NULL.
135  *
136  * Registers the function called right before the engine is restarted.
137  */
139  FlEngine* engine,
141  gpointer user_data,
142  GDestroyNotify destroy_notify);
143 
144 /**
145  * fl_engine_start:
146  * @engine: an #FlEngine.
147  * @error: (allow-none): #GError location to store the error occurring, or %NULL
148  * to ignore.
149  *
150  * Starts the Flutter engine.
151  *
152  * Returns: %TRUE on success.
153  */
154 gboolean fl_engine_start(FlEngine* engine, GError** error);
155 
156 /**
157  * fl_engine_send_window_metrics_event:
158  * @engine: an #FlEngine.
159  * @width: width of the window in pixels.
160  * @height: height of the window in pixels.
161  * @pixel_ratio: scale factor for window.
162  *
163  * Sends a window metrics event to the engine.
164  */
166  size_t width,
167  size_t height,
168  double pixel_ratio);
169 
170 /**
171  * fl_engine_send_window_state_event:
172  * @engine: an #FlEngine.
173  * @visible: whether the window is currently visible or not.
174  * @focused: whether the window is currently focused or not.
175  *
176  * Sends a window state event to the engine.
177  */
179  gboolean visible,
180  gboolean focused);
181 
182 /**
183  * fl_engine_send_mouse_pointer_event:
184  * @engine: an #FlEngine.
185  * @phase: mouse phase.
186  * @timestamp: time when event occurred in microseconds.
187  * @x: x location of mouse cursor.
188  * @y: y location of mouse cursor.
189  * @scroll_delta_x: x offset of scroll.
190  * @scroll_delta_y: y offset of scroll.
191  * @buttons: buttons that are pressed.
192  *
193  * Sends a mouse pointer event to the engine.
194  */
196  FlutterPointerPhase phase,
197  size_t timestamp,
198  double x,
199  double y,
200  double scroll_delta_x,
201  double scroll_delta_y,
202  int64_t buttons);
203 
204 void fl_engine_send_pointer_pan_zoom_event(FlEngine* self,
205  size_t timestamp,
206  double x,
207  double y,
208  FlutterPointerPhase phase,
209  double pan_x,
210  double pan_y,
211  double scale,
212  double rotation);
213 
214 /**
215  * fl_engine_send_key_event:
216  */
217 void fl_engine_send_key_event(FlEngine* engine,
218  const FlutterKeyEvent* event,
219  FlutterKeyEventCallback callback,
220  void* user_data);
221 
222 /**
223  * fl_engine_dispatch_semantics_action:
224  * @engine: an #FlEngine.
225  * @id: the semantics action identifier.
226  * @action: the action being dispatched.
227  * @data: (allow-none): data associated with the action.
228  */
230  uint64_t id,
231  FlutterSemanticsAction action,
232  GBytes* data);
233 
234 /**
235  * fl_engine_send_platform_message_response:
236  * @engine: an #FlEngine.
237  * @handle: handle that was provided in #FlEnginePlatformMessageHandler.
238  * @response: (allow-none): response to send or %NULL for an empty response.
239  * @error: (allow-none): #GError location to store the error occurring, or %NULL
240  * to ignore.
241  *
242  * Responds to a platform message.
243  *
244  * Returns: %TRUE on success.
245  */
247  FlEngine* engine,
248  const FlutterPlatformMessageResponseHandle* handle,
249  GBytes* response,
250  GError** error);
251 
252 /**
253  * fl_engine_send_platform_message:
254  * @engine: an #FlEngine.
255  * @channel: channel to send to.
256  * @message: (allow-none): message buffer to send or %NULL for an empty message
257  * @cancellable: (allow-none): a #GCancellable or %NULL.
258  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
259  * satisfied.
260  * @user_data: (closure): user data to pass to @callback.
261  *
262  * Asynchronously sends a platform message.
263  */
265  const gchar* channel,
266  GBytes* message,
267  GCancellable* cancellable,
268  GAsyncReadyCallback callback,
269  gpointer user_data);
270 
271 /**
272  * fl_engine_send_platform_message_finish:
273  * @engine: an #FlEngine.
274  * @result: a #GAsyncResult.
275  * @error: (allow-none): #GError location to store the error occurring, or %NULL
276  * to ignore.
277  *
278  * Completes request started with fl_engine_send_platform_message().
279  *
280  * Returns: message response on success or %NULL on error.
281  */
283  GAsyncResult* result,
284  GError** error);
285 
286 /**
287  * fl_engine_get_task_runner:
288  * @engine: an #FlEngine.
289  * @result: a #FlTaskRunner.
290  *
291  * Returns: task runner responsible for scheduling Flutter tasks.
292  */
293 FlTaskRunner* fl_engine_get_task_runner(FlEngine* engine);
294 
295 /**
296  * fl_engine_execute_task:
297  * @engine: an #FlEngine.
298  * @task: a #FlutterTask to execute.
299  *
300  * Executes given Flutter task.
301  */
302 void fl_engine_execute_task(FlEngine* engine, FlutterTask* task);
303 
304 /**
305  * fl_engine_mark_texture_frame_available:
306  * @engine: an #FlEngine.
307  * @texture_id: the identifier of the texture whose frame has been updated.
308  *
309  * Tells the Flutter engine that a new texture frame is available for the given
310  * texture.
311  *
312  * Returns: %TRUE on success.
313  */
315  int64_t texture_id);
316 
317 /**
318  * fl_engine_register_external_texture:
319  * @engine: an #FlEngine.
320  * @texture_id: the identifier of the texture that is available.
321  *
322  * Tells the Flutter engine that a new external texture is available.
323  *
324  * Returns: %TRUE on success.
325  */
327  int64_t texture_id);
328 
329 /**
330  * fl_engine_unregister_external_texture:
331  * @engine: an #FlEngine.
332  * @texture_id: the identifier of the texture that is not available anymore.
333  *
334  * Tells the Flutter engine that an existing external texture is not available
335  * anymore.
336  *
337  * Returns: %TRUE on success.
338  */
340  int64_t texture_id);
341 
342 /**
343  * fl_engine_update_accessibility_features:
344  * @engine: an #FlEngine.
345  * @flags: the features to enable in the accessibility tree.
346  *
347  * Tells the Flutter engine to update the flags on the accessibility tree.
348  */
349 void fl_engine_update_accessibility_features(FlEngine* engine, int32_t flags);
350 
351 /**
352  * fl_engine_get_switches:
353  * @project: an #FlEngine.
354  *
355  * Determines the switches that should be passed to the Flutter engine.
356  *
357  * Returns: an array of switches to pass to the Flutter engine.
358  */
359 GPtrArray* fl_engine_get_switches(FlEngine* engine);
360 
361 G_END_DECLS
362 
363 #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:738
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:759
FlEnginePlatformMessageHandler
gboolean(* FlEnginePlatformMessageHandler)(FlEngine *engine, const gchar *channel, GBytes *message, const FlutterPlatformMessageResponseHandle *response_handle, gpointer user_data)
Definition: fl_engine_private.h:41
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:679
FL_ENGINE_ERROR_FAILED
@ FL_ENGINE_ERROR_FAILED
Definition: fl_engine_private.h:24
fl_engine_mark_texture_frame_available
gboolean fl_engine_mark_texture_frame_available(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:872
fl_engine_unregister_external_texture
gboolean fl_engine_unregister_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:886
fl_task_runner.h
fl_engine_start
gboolean fl_engine_start(FlEngine *engine, GError **error)
Definition: fl_engine.cc:482
fl_engine_execute_task
void fl_engine_execute_task(FlEngine *engine, FlutterTask *task)
Definition: fl_engine.cc:904
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:808
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:629
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:647
fl_engine_register_external_texture
gboolean fl_engine_register_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:879
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:838
fl_engine_update_accessibility_features
void fl_engine_update_accessibility_features(FlEngine *engine, int32_t flags)
Definition: fl_engine.cc:915
fl_engine_get_task_runner
FlTaskRunner * fl_engine_get_task_runner(FlEngine *engine)
Definition: fl_engine.cc:899
fl_renderer.h
fl_engine_new
FlEngine * fl_engine_new(FlDartProject *project, FlRenderer *renderer)
Definition: fl_engine.cc:466
fl_engine_get_embedder_api
FlutterEngineProcTable * fl_engine_get_embedder_api(FlEngine *engine)
Definition: fl_engine.cc:590
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:594
fl_engine_get_switches
GPtrArray * fl_engine_get_switches(FlEngine *engine)
Definition: fl_engine.cc:926
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:777
fl_engine_set_update_semantics_node_handler
void fl_engine_set_update_semantics_node_handler(FlEngine *engine, FlEngineUpdateSemanticsNodeHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_engine.cc:612
fl_engine_send_window_state_event
void fl_engine_send_window_state_event(FlEngine *engine, gboolean visible, gboolean focused)
Definition: fl_engine.cc:747
engine
FlEngine * engine
Definition: fl_view_accessible.cc:29
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
FlEngineUpdateSemanticsNodeHandler
void(* FlEngineUpdateSemanticsNodeHandler)(FlEngine *engine, const FlutterSemanticsNode *node, gpointer user_data)
Definition: fl_engine_private.h:56
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:851
FlEngineOnPreEngineRestartHandler
void(* FlEngineOnPreEngineRestartHandler)(FlEngine *engine, gpointer user_data)
Definition: fl_engine_private.h:68
node
G_BEGIN_DECLS const FlutterSemanticsNode * node
Definition: fl_view_accessible.h:40