Flutter Engine
flutter_glfw.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_GLFW_PUBLIC_FLUTTER_GLFW_H_
6 #define FLUTTER_SHELL_PLATFORM_GLFW_PUBLIC_FLUTTER_GLFW_H_
7 
8 #include <stddef.h>
9 #include <stdint.h>
10 
11 #include "flutter_export.h"
12 #include "flutter_messenger.h"
14 
15 #if defined(__cplusplus)
16 extern "C" {
17 #endif
18 
19 // Indicates that any value is acceptable for an otherwise required property.
20 extern const int32_t kFlutterDesktopDontCare;
21 
22 // Opaque reference to a Flutter window controller.
25 
26 // Opaque reference to a Flutter window.
28 
29 // Opaque reference to a Flutter engine instance.
31 
32 // Properties representing a generic rectangular size.
33 typedef struct {
34  int32_t width;
35  int32_t height;
37 
38 // Properties for configuring a Flutter engine instance.
39 typedef struct {
40  // The path to the flutter_assets folder for the application to be run.
41  // This can either be an absolute path, or on Windows or Linux, a path
42  // relative to the directory containing the executable.
43  const char* assets_path;
44  // The path to the icudtl.dat file for the version of Flutter you are using.
45  // This can either be an absolute path, or on Windows or Linux, a path
46  // relative to the directory containing the executable.
47  const char* icu_data_path;
48  // The path to the libapp.so file for the application to be run.
49  // This can either be an absolute path or a path relative to the directory
50  // containing the executable.
51  const char* aot_library_path;
52  // The switches to pass to the Flutter engine.
53  //
54  // See: https://github.com/flutter/engine/blob/master/shell/common/switches.h
55  // for details. Not all arguments will apply to desktop.
56  const char** switches;
57  // The number of elements in |switches|.
60 
61 // Properties for configuring the initial settings of a Flutter window.
62 typedef struct {
63  // The display title.
64  const char* title;
65  // Width in screen coordinates.
66  int32_t width;
67  // Height in screen coordinates.
68  int32_t height;
69  // Whether or not the user is prevented from resizing the window.
70  // Reversed so that the default for a cleared struct is to allow resizing.
73 
74 // Sets up the library's graphic context. Must be called before any other
75 // methods.
76 //
77 // Note: Internally, this library uses GLFW, which does not support multiple
78 // copies within the same process. Internally this calls glfwInit, which will
79 // fail if you have called glfwInit elsewhere in the process.
81 
82 // Tears down library state. Must be called before the process terminates.
84 
85 // Creates a Window running a Flutter Application.
86 //
87 // FlutterDesktopInit() must be called prior to this function.
88 //
89 // This will set up and run an associated Flutter engine using the settings in
90 // |engine_properties|.
91 //
92 // Returns a null pointer in the event of an error. Otherwise, the pointer is
93 // valid until FlutterDesktopDestroyWindow is called.
94 // Note that calling FlutterDesktopCreateWindow without later calling
95 // FlutterDesktopDestroyWindow on the returned reference is a memory leak.
96 FLUTTER_EXPORT FlutterDesktopWindowControllerRef FlutterDesktopCreateWindow(
97  const FlutterDesktopWindowProperties& window_properties,
98  const FlutterDesktopEngineProperties& engine_properties);
99 
100 // Shuts down the engine instance associated with |controller|, and cleans up
101 // associated state.
102 //
103 // |controller| is no longer valid after this call.
105  FlutterDesktopWindowControllerRef controller);
106 
107 // Waits for and processes the next event before |timeout_milliseconds|.
108 //
109 // If |timeout_milliseconds| is zero, it will wait for the next event
110 // indefinitely. A non-zero timeout is needed only if processing unrelated to
111 // the event loop is necessary (e.g., to handle events from another source).
112 //
113 // Returns false if the window should be closed as a result of the last event
114 // processed.
116  FlutterDesktopWindowControllerRef controller,
117  uint32_t timeout_milliseconds);
118 
119 // Returns the window handle for the window associated with
120 // FlutterDesktopWindowControllerRef.
121 //
122 // Its lifetime is the same as the |controller|'s.
123 FLUTTER_EXPORT FlutterDesktopWindowRef
124 FlutterDesktopGetWindow(FlutterDesktopWindowControllerRef controller);
125 
126 // Returns the handle for the engine running in
127 // FlutterDesktopWindowControllerRef.
128 //
129 // Its lifetime is the same as the |controller|'s.
130 FLUTTER_EXPORT FlutterDesktopEngineRef
131 FlutterDesktopGetEngine(FlutterDesktopWindowControllerRef controller);
132 
133 // Returns the plugin registrar handle for the plugin with the given name.
134 //
135 // The name must be unique across the application.
137 FlutterDesktopGetPluginRegistrar(FlutterDesktopEngineRef engine,
138  const char* plugin_name);
139 
140 // Enables or disables hover tracking.
141 //
142 // If hover is enabled, mouse movement will send hover events to the Flutter
143 // engine, rather than only tracking the mouse while the button is pressed.
144 // Defaults to on.
146  FlutterDesktopWindowRef flutter_window,
147  bool enabled);
148 
149 // Sets the displayed title for |flutter_window|.
151  FlutterDesktopWindowRef flutter_window,
152  const char* title);
153 
154 // Sets the displayed icon for |flutter_window|.
155 //
156 // The pixel format is 32-bit RGBA. The provided image data only needs to be
157 // valid for the duration of the call to this method. Pass a nullptr to revert
158 // to the default icon.
160  FlutterDesktopWindowRef flutter_window,
161  uint8_t* pixel_data,
162  int width,
163  int height);
164 
165 // Gets the position and size of |flutter_window| in screen coordinates.
167  FlutterDesktopWindowRef flutter_window,
168  int* x,
169  int* y,
170  int* width,
171  int* height);
172 
173 // Sets the position and size of |flutter_window| in screen coordinates.
175  FlutterDesktopWindowRef flutter_window,
176  int x,
177  int y,
178  int width,
179  int height);
180 
181 // Returns the scale factor--the number of pixels per screen coordinate--for
182 // |flutter_window|.
184  FlutterDesktopWindowRef flutter_window);
185 
186 // Forces a specific pixel ratio for Flutter rendering in |flutter_window|,
187 // rather than one computed automatically from screen information.
188 //
189 // To clear a previously set override, pass an override value of zero.
191  FlutterDesktopWindowRef flutter_window,
192  double pixel_ratio);
193 
194 // Sets the min/max size of |flutter_window| in screen coordinates. Use
195 // kFlutterDesktopDontCare for any dimension you wish to leave unconstrained.
197  FlutterDesktopWindowRef flutter_window,
198  FlutterDesktopSize minimum_size,
199  FlutterDesktopSize maximum_size);
200 
201 // Runs an instance of a headless Flutter engine.
202 //
203 // Returns a null pointer in the event of an error.
204 FLUTTER_EXPORT FlutterDesktopEngineRef
206 
207 // Waits for and processes the next event before |timeout_milliseconds|.
208 //
209 // If |timeout_milliseconds| is zero, it will wait for the next event
210 // indefinitely. A non-zero timeout is needed only if processing unrelated to
211 // the event loop is necessary (e.g., to handle events from another source).
213  FlutterDesktopEngineRef engine,
214  uint32_t timeout_milliseconds);
215 
216 // Shuts down the given engine instance. Returns true if the shutdown was
217 // successful. |engine_ref| is no longer valid after this call.
219  FlutterDesktopEngineRef engine);
220 
221 // Returns the window associated with this registrar's engine instance.
222 //
223 // This is a GLFW shell-specific extension to flutter_plugin_registrar.h
226 
227 // Enables input blocking on the given channel.
228 //
229 // If set, then the Flutter window will disable input callbacks
230 // while waiting for the handler for messages on that channel to run. This is
231 // useful if handling the message involves showing a modal window, for instance.
232 //
233 // This must be called after FlutterDesktopSetMessageHandler, as setting a
234 // handler on a channel will reset the input blocking state back to the
235 // default of disabled.
236 //
237 // This is a GLFW shell-specific extension to flutter_plugin_registrar.h
240  const char* channel);
241 
242 #if defined(__cplusplus)
243 } // extern "C"
244 #endif
245 
246 #endif // FLUTTER_SHELL_PLATFORM_GLFW_PUBLIC_FLUTTER_GLFW_H_
FLUTTER_EXPORT FlutterDesktopWindowControllerRef FlutterDesktopCreateWindow(const FlutterDesktopWindowProperties &window_properties, const FlutterDesktopEngineProperties &engine_properties)
FLUTTER_EXPORT void FlutterDesktopRunEngineEventLoopWithTimeout(FlutterDesktopEngineRef engine, uint32_t timeout_milliseconds)
FLUTTER_EXPORT bool FlutterDesktopShutDownEngine(FlutterDesktopEngineRef engine)
FLUTTER_EXPORT double FlutterDesktopWindowGetScaleFactor(FlutterDesktopWindowRef flutter_window)
FLUTTER_EXPORT void FlutterDesktopWindowSetFrame(FlutterDesktopWindowRef flutter_window, int x, int y, int width, int height)
FLUTTER_EXPORT void FlutterDesktopWindowSetTitle(FlutterDesktopWindowRef flutter_window, const char *title)
FLUTTER_EXPORT FlutterDesktopPluginRegistrarRef FlutterDesktopGetPluginRegistrar(FlutterDesktopEngineRef engine, const char *plugin_name)
FLUTTER_EXPORT FlutterDesktopWindowRef FlutterDesktopGetWindow(FlutterDesktopWindowControllerRef controller)
struct FlutterDesktopEngineState * FlutterDesktopEngineRef
Definition: flutter_glfw.h:30
FLUTTER_EXPORT void FlutterDesktopPluginRegistrarEnableInputBlocking(FlutterDesktopPluginRegistrarRef registrar, const char *channel)
FLUTTER_EXPORT void FlutterDesktopWindowSetSizeLimits(FlutterDesktopWindowRef flutter_window, FlutterDesktopSize minimum_size, FlutterDesktopSize maximum_size)
FLUTTER_EXPORT bool FlutterDesktopInit()
struct FlutterDesktopWindowControllerState * FlutterDesktopWindowControllerRef
Definition: flutter_glfw.h:23
FLUTTER_EXPORT FlutterDesktopWindowRef FlutterDesktopPluginRegistrarGetWindow(FlutterDesktopPluginRegistrarRef registrar)
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopRunEngine(const FlutterDesktopEngineProperties &properties)
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopGetEngine(FlutterDesktopWindowControllerRef controller)
int32_t height
int32_t width
FLUTTER_EXPORT void FlutterDesktopDestroyWindow(FlutterDesktopWindowControllerRef controller)
const int32_t kFlutterDesktopDontCare
Definition: flutter_glfw.cc:40
FLUTTER_EXPORT void FlutterDesktopWindowSetHoverEnabled(FlutterDesktopWindowRef flutter_window, bool enabled)
FLUTTER_EXPORT void FlutterDesktopWindowSetPixelRatioOverride(FlutterDesktopWindowRef flutter_window, double pixel_ratio)
struct FlutterDesktopWindow * FlutterDesktopWindowRef
Definition: flutter_glfw.h:27
FLUTTER_EXPORT void FlutterDesktopTerminate()
FLUTTER_EXPORT void FlutterDesktopWindowGetFrame(FlutterDesktopWindowRef flutter_window, int *x, int *y, int *width, int *height)
FLUTTER_EXPORT bool FlutterDesktopRunWindowEventLoopWithTimeout(FlutterDesktopWindowControllerRef controller, uint32_t timeout_milliseconds)
FLUTTER_EXPORT void FlutterDesktopWindowSetIcon(FlutterDesktopWindowRef flutter_window, uint8_t *pixel_data, int width, int height)
#define FLUTTER_EXPORT