feat: updated the documentation

collectFlutter · Dec 9, 2021 · 75a9e6f · 75a9e6f
1 parent 3b625be
commit 75a9e6f
Show file tree

Hide file tree

Showing 3 changed files with 176 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -83,4 +83,150 @@ in your `myapp.dart` file
     }
 ```
 
+
+## Running
+
+### To run your project
+- change the directory to out
+- and run the dart file as shown
+
+```bash
+  cd out
+  dart run ../myapp.dart
+```
+
+
+## API Reference
+
+#### Create Window
+creates a new webview instance that can be run
+
+```dart
+  final webview = new Webview(true)
+```
+
+| Parameter | Type     | Description                                                                        |
+| :-------- | :------- | :----------------------------------------------------------------------------------|
+| `debug`   | `bool`   | **Optional**. Sets if dev tool can be accessed from the app on supported platforms |
+
+#### Navigate to a url
+starts the app with given settings
+
+```dart
+  webview.navigate("Your url")
+```
+
+| Parameter | Type     | Description                                                                    |
+| :-------- | :------- | :----------------------------------------------------------------------------- |
+| `url`     | `String` | **Required**. Navigates to the given url as soon as the `run` method is called |
+
+#### Run the app
+starts the app with given settings
+
+```dart
+  webview.run()
+```
+
+| Parameter        | Type     | Description                                                     |
+| :--------        | :------- | :-------------------------------------------------------------- |
+| `autoDestroy`   | `String` | **Optional**. Destroys the window as soon as the execution ends |
+
+#### Change Title
+Used to change the title of the window
+
+```dart
+  webview.setTitle("New Title")
+```
+
+| Parameter | Type     | Description                                   |
+| :-------- | :------- | :-------------------------------------------- |
+| `title`   | `String` | **Required**. Changes the title of the window |
+
+#### Change Size
+Used to change the Size of the window
+
+```dart
+  webview.setSize(400, 600, SizeHint.none)
+```
+
+| Parameter | Type       | Description                                    |
+| :-------- | :--------- | :--------------------------------------------- |
+| `width`   | `int`      | **Required**. Sets the Width of the window     |
+| `height`  | `int`      | **Required**. Sets the height of the window    |
+| `sizeHint`| `SizeHint` | **Optional**. Sets the Size Hint of the window |
+
+
+#### Size Hint
+Sets the window resize behaviour
+
+##### SizeHint has the following values
+
+    - SizeHint.none
+
+    - SizeHint.min
+
+    - SizeHint.max
+
+    - SizeHint.fixed
+
+
+| Value     | Description                                    |
+| :-------- | :--------------------------------------------- |
+| `none`    | **Default**. Width and height are default size |
+| `min`     | Width and height are minimum bounds            |
+| `max`     | Width and height are maximum bounds            |
+| `fixed`   | Window size can not be changed by a user       |
+
+
+#### Evaluate js
+runs the js given as soon as the method is called
+
+```dart
+  webview.eval("A valid string of Js")
+```
+
+| Parameter | Type       | Description                                    |
+| :-------- | :--------- | :--------------------------------------------- |
+| `js`      | `String`      | **Required**. The JavaScript to run         |
+
+#### Initialization logic
+runs the js given as soon as the window starts
+
+```dart
+  webview.init("A valid string of Js")
+```
+
+| Parameter | Type       | Description                                    |
+| :-------- | :--------- | :--------------------------------------------- |
+| `js`      | `String`      | **Required**. The JavaScript to run         |
+
+#### Binding Native functions
+Binds the given dart function with the given name
+
+```dart
+  webview.bind("jsName", (List<dynamic> args) {
+      // some code
+  })
+```
+
+| Parameter  | Type                                     | Description                                                  |
+| :--------- | :--------------------------------------- | :----------------------------------------------------------- |
+| `name`     | `String`                                 | **Required**. The name of the function to be exposed to js   |
+| `function` | `void Function(List<dynamic args>)`      | **Required**. The function to be exposed to js the args param is the list of parameters that are passed from js               |
+
+
+#### Destroying the Window
+Destroys a webview and closes the native window.
+
+```dart
+  webview.destroy()
+```
+
+#### Terminating the Main loop
+Stops the main loop. It is safe to call this function from another other
+background thread.
+
+```dart
+  webview.terminate()
+```
 
diff --git a/example/webview_dart_example.dart b/example/webview_dart_example.dart
@@ -5,7 +5,7 @@ void main() async {
   Webview(true)
       .setTitle("Google")
       .setSize(1280, 800,
-          SIzeHint.none /* Sizehint is optional and can be omitted */)
+          SizeHint.none /* Sizehint is optional and can be omitted */)
       .navigate(url)
       .run();
 }
diff --git a/lib/src/webview_dart_api.dart b/lib/src/webview_dart_api.dart
@@ -3,12 +3,14 @@ import 'dart:ffi';
 import 'dart:io';
 
 import 'package:ffi/ffi.dart';
-import 'package:ffi/src/utf8.dart';
 
 import 'bindings.dart';
 
-enum SIzeHint { none, min, max, fixed }
+enum SizeHint { none, min, max, fixed }
 
+/// Creates a new webview instance. If debug true - developer tools will
+/// be enabled (if the platform supports them).
+/// Depending on the platform, a GtkWindow, NSWindow or HWND is used
 class Webview {
   static final WebviewLib _lib = loadLibrary(
     Directory(
@@ -31,41 +33,55 @@ class Webview {
 
   static final Map<String, void Function(List<dynamic>)> _bindings = {};
 
+  /// Creates a new webview instance. If debug true - developer tools will
+  /// be enabled (if the platform supports them).
+  /// Depending on the platform, a GtkWindow, NSWindow or HWND is used
   Webview([bool debug = false]) {
     _handle = _create(debug ? 1 : 0, nullptr);
   }
 
+  /// Stops the main loop.
   void terminate() {
     _terminate(_handle);
   }
 
+  /// Updates the title of the native window.
   Webview setTitle(String title) {
     final cTitle = title.toNativeUtf8();
     _setTitle(_handle, cTitle);
     malloc.free(cTitle);
     return this;
   }
 
+  /// Updates native window size.
   Webview setSize(final int width, final int height,
-      [SIzeHint sIzeHint = SIzeHint.none]) {
-    _setSize(_handle, width, height, sIzeHint.index);
+      [SizeHint sizeHint = SizeHint.none]) {
+    _setSize(_handle, width, height, sizeHint.index);
     return this;
   }
 
+  /// Navigates webview to the given URL. URL may be a data URI, i.e.
+  /// "data:text/text,<html>...</html>". It is often ok not to url-encode it
+  /// properly, webview will re-encode it for you.
   Webview navigate(String url) {
     final cUrl = url.toNativeUtf8();
     _navigate(_handle, cUrl);
     malloc.free(cUrl);
     return this;
   }
 
+  /// Injects JavaScript code at the initialization of the new page. Every time
+  /// the webview will open a the new page - this initialization code will be
+  /// executed. It is guaranteed that code is executed before window.onload.
   Webview init(String js) {
     final cJs = js.toNativeUtf8();
     _init(_handle, cJs);
     malloc.free(cJs);
     return this;
   }
 
+  /// Evaluates arbitrary JavaScript code. Evaluation happens asynchronously, also
+  /// the result of the expression is ignored.
   Webview eval(String js) {
     final cJs = js.toNativeUtf8();
     print("evaluating: ${cJs.toDartString()}");
@@ -74,12 +90,14 @@ class Webview {
     return this;
   }
 
+  /// Runs the main loop until it's terminated. After this function exits - you
+  /// must destroy the webview if autoDestroy is set to false
   void run([bool autoDestroy = true]) {
     _run(_handle);
     if (autoDestroy) destroy();
   }
 
-  static void cb(Pointer<Utf8> seq, Pointer<Utf8> req, Pointer<Void> arg) {
+  static void _cb(Pointer<Utf8> seq, Pointer<Utf8> req, Pointer<Void> arg) {
     final request = req.toDartString();
     List<dynamic> data = jsonDecode(request);
     final binding = data[0] as String;
@@ -89,14 +107,19 @@ class Webview {
     }
   }
 
+  /// Binds a native callback so that it will appear under the given name as a
+  /// global JavaScript function. Internally it uses webview_init(). Callback
+  /// receives a list of all the arguments passed to the JavaScript
+  /// function.
   Webview bind(String name, void Function(List<dynamic>) callback) {
     final cName = name.toNativeUtf8();
     _bindings[name] = callback;
-    _bind(_handle, cName, Pointer.fromFunction(cb), nullptr);
+    _bind(_handle, cName, Pointer.fromFunction(_cb), nullptr);
     malloc.free(cName);
     return this;
   }
 
+  /// Destroys a webview and closes the native window.
   void destroy() {
     _destroy(_handle);
   }