doc: add README

.flutter-plugins-dependencies

@@ -1 +1 @@
-{"info":"This is a generated file; do not edit or check into version control.","plugins":{"ios":[{"name":"path_provider_foundation","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_foundation-2.3.2\\\\","shared_darwin_source":true,"native_build":true,"dependencies":[]},{"name":"shared_preferences_foundation","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_foundation-2.3.5\\\\","shared_darwin_source":true,"native_build":true,"dependencies":[]},{"name":"url_launcher_ios","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_ios-6.2.4\\\\","native_build":true,"dependencies":[]}],"android":[{"name":"path_provider_android","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_android-2.2.2\\\\","native_build":true,"dependencies":[]},{"name":"shared_preferences_android","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_android-2.2.1\\\\","native_build":true,"dependencies":[]},{"name":"url_launcher_android","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_android-6.3.0\\\\","native_build":true,"dependencies":[]}],"macos":[{"name":"path_provider_foundation","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_foundation-2.3.2\\\\","shared_darwin_source":true,"native_build":true,"dependencies":[]},{"name":"screen_retriever","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\screen_retriever-0.1.9\\\\","native_build":true,"dependencies":[]},{"name":"shared_preferences_foundation","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_foundation-2.3.5\\\\","shared_darwin_source":true,"native_build":true,"dependencies":[]},{"name":"url_launcher_macos","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_macos-3.1.0\\\\","native_build":true,"dependencies":[]},{"name":"window_manager","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\window_manager-0.3.8\\\\","native_build":true,"dependencies":["screen_retriever"]}],"linux":[{"name":"path_provider_linux","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_linux-2.2.1\\\\","native_build":false,"dependencies":[]},{"name":"screen_retriever","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\screen_retriever-0.1.9\\\\","native_build":true,"dependencies":[]},{"name":"shared_preferences_linux","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_linux-2.3.2\\\\","native_build":false,"dependencies":["path_provider_linux"]},{"name":"url_launcher_linux","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_linux-3.1.1\\\\","native_build":true,"dependencies":[]},{"name":"window_manager","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\window_manager-0.3.8\\\\","native_build":true,"dependencies":["screen_retriever"]}],"windows":[{"name":"path_provider_windows","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_windows-2.2.1\\\\","native_build":false,"dependencies":[]},{"name":"screen_retriever","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\screen_retriever-0.1.9\\\\","native_build":true,"dependencies":[]},{"name":"shared_preferences_windows","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_windows-2.3.2\\\\","native_build":false,"dependencies":["path_provider_windows"]},{"name":"url_launcher_windows","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_windows-3.1.1\\\\","native_build":true,"dependencies":[]},{"name":"window_manager","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\window_manager-0.3.8\\\\","native_build":true,"dependencies":["screen_retriever"]}],"web":[{"name":"shared_preferences_web","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_web-2.2.2\\\\","dependencies":[]},{"name":"url_launcher_web","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_web-2.2.3\\\\","dependencies":[]}]},"dependencyGraph":[{"name":"path_provider","dependencies":["path_provider_android","path_provider_foundation","path_provider_linux","path_provider_windows"]},{"name":"path_provider_android","dependencies":[]},{"name":"path_provider_foundation","dependencies":[]},{"name":"path_provider_linux","dependencies":[]},{"name":"path_provider_windows","dependencies":[]},{"name":"screen_retriever","dependencies":[]},{"name":"shared_preferences","dependencies":["shared_preferences_android","shared_preferences_foundation","shared_preferences_linux","shared_preferences_web","shared_preferences_windows"]},{"name":"shared_preferences_android","dependencies":[]},{"name":"shared_preferences_foundation","dependencies":[]},{"name":"shared_preferences_linux","dependencies":["path_provider_linux"]},{"name":"shared_preferences_web","dependencies":[]},{"name":"shared_preferences_windows","dependencies":["path_provider_windows"]},{"name":"url_launcher","dependencies":["url_launcher_android","url_launcher_ios","url_launcher_linux","url_launcher_macos","url_launcher_web","url_launcher_windows"]},{"name":"url_launcher_android","dependencies":[]},{"name":"url_launcher_ios","dependencies":[]},{"name":"url_launcher_linux","dependencies":[]},{"name":"url_launcher_macos","dependencies":[]},{"name":"url_launcher_web","dependencies":[]},{"name":"url_launcher_windows","dependencies":[]},{"name":"window_manager","dependencies":["screen_retriever"]}],"date_created":"2024-02-17 23:38:22.656719","version":"3.16.5"}
+{"info":"This is a generated file; do not edit or check into version control.","plugins":{"ios":[{"name":"path_provider_foundation","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_foundation-2.3.2\\\\","shared_darwin_source":true,"native_build":true,"dependencies":[]},{"name":"shared_preferences_foundation","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_foundation-2.3.5\\\\","shared_darwin_source":true,"native_build":true,"dependencies":[]},{"name":"url_launcher_ios","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_ios-6.2.4\\\\","native_build":true,"dependencies":[]}],"android":[{"name":"path_provider_android","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_android-2.2.2\\\\","native_build":true,"dependencies":[]},{"name":"shared_preferences_android","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_android-2.2.1\\\\","native_build":true,"dependencies":[]},{"name":"url_launcher_android","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_android-6.3.0\\\\","native_build":true,"dependencies":[]}],"macos":[{"name":"path_provider_foundation","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_foundation-2.3.2\\\\","shared_darwin_source":true,"native_build":true,"dependencies":[]},{"name":"screen_retriever","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\screen_retriever-0.1.9\\\\","native_build":true,"dependencies":[]},{"name":"shared_preferences_foundation","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_foundation-2.3.5\\\\","shared_darwin_source":true,"native_build":true,"dependencies":[]},{"name":"url_launcher_macos","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_macos-3.1.0\\\\","native_build":true,"dependencies":[]},{"name":"window_manager","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\window_manager-0.3.8\\\\","native_build":true,"dependencies":["screen_retriever"]}],"linux":[{"name":"path_provider_linux","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_linux-2.2.1\\\\","native_build":false,"dependencies":[]},{"name":"screen_retriever","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\screen_retriever-0.1.9\\\\","native_build":true,"dependencies":[]},{"name":"shared_preferences_linux","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_linux-2.3.2\\\\","native_build":false,"dependencies":["path_provider_linux"]},{"name":"url_launcher_linux","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_linux-3.1.1\\\\","native_build":true,"dependencies":[]},{"name":"window_manager","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\window_manager-0.3.8\\\\","native_build":true,"dependencies":["screen_retriever"]}],"windows":[{"name":"path_provider_windows","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\path_provider_windows-2.2.1\\\\","native_build":false,"dependencies":[]},{"name":"screen_retriever","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\screen_retriever-0.1.9\\\\","native_build":true,"dependencies":[]},{"name":"shared_preferences_windows","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_windows-2.3.2\\\\","native_build":false,"dependencies":["path_provider_windows"]},{"name":"url_launcher_windows","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_windows-3.1.1\\\\","native_build":true,"dependencies":[]},{"name":"window_manager","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\window_manager-0.3.8\\\\","native_build":true,"dependencies":["screen_retriever"]}],"web":[{"name":"shared_preferences_web","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\shared_preferences_web-2.2.2\\\\","dependencies":[]},{"name":"url_launcher_web","path":"C:\\\\Users\\\\kekland\\\\AppData\\\\Local\\\\Pub\\\\Cache\\\\hosted\\\\pub.dev\\\\url_launcher_web-2.2.3\\\\","dependencies":[]}]},"dependencyGraph":[{"name":"path_provider","dependencies":["path_provider_android","path_provider_foundation","path_provider_linux","path_provider_windows"]},{"name":"path_provider_android","dependencies":[]},{"name":"path_provider_foundation","dependencies":[]},{"name":"path_provider_linux","dependencies":[]},{"name":"path_provider_windows","dependencies":[]},{"name":"screen_retriever","dependencies":[]},{"name":"shared_preferences","dependencies":["shared_preferences_android","shared_preferences_foundation","shared_preferences_linux","shared_preferences_web","shared_preferences_windows"]},{"name":"shared_preferences_android","dependencies":[]},{"name":"shared_preferences_foundation","dependencies":[]},{"name":"shared_preferences_linux","dependencies":["path_provider_linux"]},{"name":"shared_preferences_web","dependencies":[]},{"name":"shared_preferences_windows","dependencies":["path_provider_windows"]},{"name":"url_launcher","dependencies":["url_launcher_android","url_launcher_ios","url_launcher_linux","url_launcher_macos","url_launcher_web","url_launcher_windows"]},{"name":"url_launcher_android","dependencies":[]},{"name":"url_launcher_ios","dependencies":[]},{"name":"url_launcher_linux","dependencies":[]},{"name":"url_launcher_macos","dependencies":[]},{"name":"url_launcher_web","dependencies":[]},{"name":"url_launcher_windows","dependencies":[]},{"name":"window_manager","dependencies":["screen_retriever"]}],"date_created":"2024-02-18 17:52:55.739225","version":"3.16.5"}

CHANGELOG.md

@@ -1,3 +1,3 @@
 ## 0.0.1
 
-* TODO: Describe initial release.
+* Initial release :)

LICENSE

@@ -1 +1,9 @@
-TODO: Add your license here.
+The MIT License (MIT)
+
+Copyright 2024 Erzhan Kabdykairov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,39 +1,136 @@
-<!--
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
+# simulator
 
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/guides/libraries/writing-package-pages).
+**Warning: This is a work in progress and may contain bugs. Use at your own risk.**
 
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-library-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/developing-packages).
--->
+A device simulator for Flutter. Run your app on the desktop, and simulate a device of your choice. Perfect for rapid development of multi-platform user interfaces.
 
-TODO: Put a short description of the package here that helps potential users
-know whether this package might be useful for them.
+<p align="center">
+  <img alt="Image 1" src="./doc/image3.jpg" width="45%">
+&nbsp; &nbsp; 
+  <img alt="Image 2" src="./doc/image4.jpg" width="45%">
+</p>
+
+## Why?
+
+In my experience, developing a multi-platform app is a pain. You have to constantly switch between devices to see how your app looks and behaves. This is especially true for mobile gestures and keyboard input. This package aims to solve this problem by providing a way to simulate a device on the desktop. It's not perfect, but it's a start. I personally find that I'm much more productive when using this package. 
+
+Another benefit is that building and hot-refreshing the app is much faster on the desktop. This is especially true for complex UIs.
+
+However, this package is not a replacement for testing on real devices. It's just a tool to make development easier.
 
 ## Features
 
-TODO: List what your package can do. Maybe include images, gifs, or videos.
+- Simulate your app on a bunch of Android and iOS devices (list below).
+- Pixel-perfect screenshotting of the simulated device. Great for creating marketing images.
+- Simulate the device keyboard.
+- Synthesize mobile gestures (tap, drag, pinch, etc.) with a mouse.
+- Quickly enable various Flutter debug flags.
+- Complete `MediaQuery` and system locale control.
+- Ability to add custom modules.
+
+**In progress**:
+
+- Device rotations (works, but is buggy).
+- Video recording of the simulated device.
+- Make it easier to intercept system calls.
+- Improve the locale module.
 
-## Getting started
+## Supported devices
 
-TODO: List prerequisites and provide or point to information on how to
-start using the package.
+- iPhone 15
+- iPhone 15 Plus
+- iPhone 15 Pro
+- iPhone 15 Pro Max
+- iPhone SE (gen 3)
+- Pixel phones (from 2 to 7, with `a` and `XL` variants)
 
 ## Usage
 
-TODO: Include short and useful examples for package users. Add longer examples
-to `/example` folder.
+1. Add the package to your `pubspec.yaml`:
+
+```yaml
+dependencies:
+  simulator: ^0.0.1
+```
+
+Note: this package only works in Debug mode. The entire code of the package should be tree-shaken away in Release mode.
+
+2. Create an entrypoint for the simulator. It should be a separate file from your main entrypoint. For example, `main.simulator.dart`:
 
 ```dart
-const like = 'sample';
+import 'package:simulator/simulator.dart';
+
+void main() {
+  runSimulatorApp(MyApp());
+}
 ```
 
-## Additional information
+Note: if you have code that uses `FlutterWidgetsBinding.ensureInitialized()`, you should replace it with `SimulatorFlutterWidgetsBinding.ensureInitialized()`. This makes sure that the simulator initializes its bindings.
+
+Now you can run the simulator with `flutter run -t lib/main.simulator.dart`. Make sure that the simulator is ran for the desktop platform.
+
+## Built-in modules
+
+### Screenshot module
+
+Allows you to take a screenshot of the simulated device (or just the app). By default, the screenshots are saved to the temporary directory.
+
+![Screenshot module](./doc/screenshot-module.jpg)
+
+### Device module
+
+Allows you to pick a device to simulate. The device is picked from a list of supported devices.
+
+![Device module](./doc/device-module.jpg)
+
+### Keyboard module
+
+Allows you to simulate the device keyboard. When the system call to show the keyboard is intercepted, the keyboard is shown in the simulator instead. You can choose between no keyboard, an iOS or an Android keyboard (or auto-detect based on the platform).
+
+![Keyboard module](./doc/keyboard-module.jpg)
+
+### Gestures module
+
+Allows you to simulate mobile gestures with a mouse. The main feature is the conversion of mouse events to touch gestures in the simulator view. You can also simulate a zoom gesture by enabling it and holding the `Ctrl` key.
+
+![Gestures module](./doc/gestures-module.jpg)
+
+### VM module
+
+Shows the heap usage for all of the isolates in the VM. It also allows you to fire the memory pressure event (`didHaveMemoryPressure()`).
+
+![VM module](./doc/vm-module.jpg)
+
+### Debug module
+
+Allows you to enable various Flutter debug flags. You can enable the performance overlay, the debug banner, the repaint rainbow, and the slow animations.
+
+Additionally, includes some custom debugging flags:
+
+- Pointer area highlight - highlights and shows the size of the pointer area of `GestureDetector` widgets when hovered.
+
+- Visualize view paddings - shows the view paddings and insets applied to the app.
+
+![Debug module](./doc/debug-module.jpg)
+
+### Locale module
+
+Allows you to control the system locale. This is work-in-progress and will be improved.
+
+![Locale module](./doc/locale-module.jpg)
+
+### MediaQuery module
+
+Allows you to set the `MediaQuery` properties for the app. This is transparent to the app and appears like host device properties.
+
+![MediaQuery module](./doc/media-query-module.jpg)
+
+
+## Custom modules
+
+More documentation soon. If curious, check the `lib/src/modules` directory.
+
+## Contacts
 
-TODO: Tell users more about the package: where to find more information, how to
-contribute to the package, how to file issues, what response they can expect
-from the package authors, and more.
+For any questions, feel free to contact me at:
+- [email protected]