From 255d0eef91709d9f386412dd1355671f7c9753cd Mon Sep 17 00:00:00 2001 From: Atul R Date: Fri, 2 Aug 2019 22:46:03 +0200 Subject: [PATCH] Adds documentation for all internal widgets. --- config/moc.gypi | 2 +- docs/README.md | 8 +++- docs/api/Component.md | 23 ++++++++++ docs/api/EventWidget.md | 60 +++++++++++++++++++++++++++ docs/api/NodeLayout.md | 59 ++++++++++++++++++++++++++ docs/api/NodeWidget.md | 3 +- docs/api/YogaWidget.md | 37 +++++++++++++++++ src/cpp/QtGui/QWidget/qwidget_macro.h | 4 +- src/lib/QtGui/QWidget/index.ts | 2 +- src/lib/core/Component/index.ts | 2 +- 10 files changed, 193 insertions(+), 7 deletions(-) create mode 100644 docs/api/Component.md create mode 100644 docs/api/EventWidget.md create mode 100644 docs/api/YogaWidget.md diff --git a/config/moc.gypi b/config/moc.gypi index f6826c648..aa9f6fe69 100644 --- a/config/moc.gypi +++ b/config/moc.gypi @@ -13,4 +13,4 @@ "../src/cpp/autogen/nradiobutton_moc.cpp" ] } -} +} \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 39681bdd0..a47cdd0b3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -36,9 +36,15 @@ - [QMainWindow (Window)](api/QMainWindow.md) - [QWidget (View)](api/QWidget.md) +- [FlexLayout](api/FlexLayout.md) + +### Internal Modules + - [NodeWidget](api/NodeWidget.md) - [NodeLayout](api/NodeLayout.md) -- [FlexLayout](api/FlexLayout.md) +- [EventWidget](api/EventWidget.md) +- [Component](api/Component.md) +- [YogaWidget](api/YogaWidget.md) ## Development diff --git a/docs/api/Component.md b/docs/api/Component.md new file mode 100644 index 000000000..ffb30283e --- /dev/null +++ b/docs/api/Component.md @@ -0,0 +1,23 @@ +## Class: Component + +> Abstract class that is root most base class for all widgets and layouts in the NodeGui World. + +**This class is used to add core properties to all widgets, layouts etc in NodeGui world. Currently it helps us maintain references to the native C++ instance of the widget or layout. It also helps in preventing gc of child elements of a layout or widget** + +`Component` is an abstract class and hence no instances of the same should be created. It exists so that we can add core functionalities to all widgets and layouts easily. This is an internal class. + +**Component is the base class for YogaWidget and NodeLayout which means all widgets and layouts inherit it aswell. Its the root base class in NodeGui world** + +To get a clearer picture you can take a look at the Component source code here: `src/lib/core/Component/index.ts` + +### Static Methods + +There are no public static methods for Component. + +### Instance Properties + +There are no public instance properties for Component. + +### Instance Methods + +There are no public instance methods for Component. diff --git a/docs/api/EventWidget.md b/docs/api/EventWidget.md new file mode 100644 index 000000000..fb8adc50a --- /dev/null +++ b/docs/api/EventWidget.md @@ -0,0 +1,60 @@ +## Class: EventWidget + +> Abstract class that adds event handling support to all widgets. + +**This class implements an event emitter and merges it with Qt's event and signal system. It allows us to register and unregister event and signal listener at will from javascript** + +`EventWidget` is an abstract class and hence no instances of the same should be created. It exists so that we can add event handling functionalities to all widget's easily. This is an internal class. + +**EventWidget is the base class for NodeWidget which means all widgets inherit it aswell. It inherits from another abstract class [YogaWidget](api/YogaWidget.md)** + +### Example + +```javascript +const { QWidget, QWidgetEvents } = require("@nodegui/nodegui"); + +const view = new QWidget(); +// addEventListener is a method from EventWidget +view.addEventListener("MouseMove", () => { + console.log("mouse moved"); +}); + +or; + +// addEventListener is a method from EventWidget +view.addEventListener(QWidgetEvents.MouseMove, () => { + console.log("mouse moved"); +}); +``` + +EventWidget will contain all methods and properties that are useful to handle events and signals of widgets in the NodeGui world. + +### Static Methods + +EventWidget can access all the static methods defined in [YogaWidget](api/YogaWidget.md) + +### Instance Properties + +EventWidget can access all the instance properties defined in [YogaWidget](api/YogaWidget.md) + +### Instance Methods + +EventWidget can access all the instance methods defined in [YogaWidget](api/YogaWidget.md) + +Additionally it also has the following instance methods: + +#### `widget.addEventListener()` + +Adds an event listener to the widget to listen to events that occur on a widget. + +- `eventType` string - The event or signal you wish to listen to for the widget. Every widget exports its own enum of all possible events and signal types it can take. For example: `QWidget` exports `QWidgetEvents`, `QPushButton` exports `QPushButtonEvents`. + +- `callback` (payload?: NativeEvent | any) => void - A callback function to invoke when an event occurs. Usually you receive a nativeEvent or a string as argument. + +#### `widget.removeEventListener()` + +Removes the specified event listener from the widget. + +- `eventType` string - The event or signal for which you wish to remove the listener. + +- `callback` Function (_Optional_) - If specified the removeEventListener will remove the specified listener only, otherwise all eventlisteners of the eventType on the widget will be removed. diff --git a/docs/api/NodeLayout.md b/docs/api/NodeLayout.md index e69de29bb..660ea26f1 100644 --- a/docs/api/NodeLayout.md +++ b/docs/api/NodeLayout.md @@ -0,0 +1,59 @@ +## Class: NodeLayout + +> Abstract class to add functionalities common to all Layout. + +**This class implements all methods, properties of Qt's [QLayout class](https://doc.qt.io/qt-5/qlayout.html) so that it can be inherited by all layouts** + +`NodeLayout` is an abstract class and hence no instances of the same should be created. It exists so that we can add similar functionalities to all layout's easily. Additionally it helps in typechecking process. + +**NodeLayout is the base class for all layouts. It inherits from another abstract class [Component](api/Component.md)** + +### Example + +```javascript +const { + NodeLayout, + NodeWidget, + FlexLayout, + GridLayout, + QPushButton, + QWidget +} = require("@nodegui/nodegui"); + +// addChildToLayout can accept any layout since it expects NodeLayout +const addChildToLayout = (layout: NodeLayout, widget: NodeWidget) => { + layout.addWidget(widget); +}; + +addChildToLayout(new FlexLayout(), new QPushButton()); +addChildToLayout(new GridLayout(), new QWidget()); +``` + +NodeLayout will list all methods and properties that are common to all layouts in the NodeGui world. + +### Static Methods + +NodeLayout can access all the static methods defined in [Component](api/Component.md) + +### Instance Properties + +NodeLayout can access all the instance properties defined in [Component](api/Component.md) + +Additionally it also has the following instance properties: + +#### `layout.type` + +This will return the string `layout` for all layouts. + +### Instance Methods + +NodeLayout can access all the instance methods defined in [Component](api/Component.md) + +Additionally it also has the following instance methods: + +#### `layout.addWidget()` + +This is an abstract method in NodeLayout class. All Layouts inheriting from NodeLayout should implement this method. + +- `childWidget` NodeWidget - Any widget in the NodeGui world. +- `...args` any[] - Additional params as required by the layout. diff --git a/docs/api/NodeWidget.md b/docs/api/NodeWidget.md index aa6d7fd5e..3abf4206e 100644 --- a/docs/api/NodeWidget.md +++ b/docs/api/NodeWidget.md @@ -4,7 +4,7 @@ **This class implements all methods, properties of Qt's [QWidget class](https://doc.qt.io/qt-5/qwidget.html) so that it can be inherited by all widgets** -`NodeWidget` is an abstract class and hence no instances of the same should be created. It exists so that we can add similar functionalities to all widget's easily. Additionally it helps in typechecking process. +`NodeWidget` is an abstract class and hence no instances of the same should be created. It exists so that we can add similar functionalities to all widget's easily. Additionally it helps in typechecking process. If you wish to create a `div` like widget use [QWidget](api/QWidget.md) instead. **NodeWidget is the base class for all widgets. It inherits from another abstract class [EventWidget](api/EventWidget.md)** @@ -68,6 +68,7 @@ Resizes the widget. It calls the native method [QWidget: resize](https://doc.qt. #### `widget.close()` Closes this widget. It calls the native method [QWidget: close](https://doc.qt.io/qt-5/qwidget.html#close). +Returns true if the widget was closed; otherwise returns false. #### `widget.setLayout()` diff --git a/docs/api/YogaWidget.md b/docs/api/YogaWidget.md new file mode 100644 index 000000000..d85d188c8 --- /dev/null +++ b/docs/api/YogaWidget.md @@ -0,0 +1,37 @@ +## Class: YogaWidget + +> Abstract class to add common functionality related to Flex layout to all Widgets. + +**This class implements methods related to flex layout required to be present in all widgets** + +`YogaWidget` is an abstract class and hence no instances of the same should be created. It exists so that we can add similar functionalities related to flex layout to all widget's easily. We implement flex layout using a library called [Yoga](https://github.com/facebook/yoga). As part of yoga every widget needs to store its own flex properties such as alignItems, flexDirection etc. This is done with the help of YogaWidget. + +**YogaWidget is the base class for EventWidget which means all widgets inherit it aswell. It inherits from another abstract class [Component](api/Component.md)** + +```javascript +const { QWidget } = require("@nodegui/nodegui"); + +const view = new QWidget(); +// getFlexNode is a method from YogaWidget +const flexNode = view.getFlexNode(); +``` + +YogaWidget helps in storing all flex properties of a widget. + +### Static Methods + +YogaWidget can access all the static methods defined in [Component](api/Component.md) + +### Instance Properties + +YogaWidget can access all the instance properties defined in [Component](api/Component.md) + +### Instance Methods + +YogaWidget can access all the instance methods defined in [Component](api/Component.md) + +Additionally it also has the following instance methods: + +#### `widget.getFlexNode()` + +Returns a native reference to the flex node used in c++ instance for the widget. This is not a regular javascript object and hence no methods or properties can be accessed from it. It exists so that we pass around a widgets flex node to layouts, etc. diff --git a/src/cpp/QtGui/QWidget/qwidget_macro.h b/src/cpp/QtGui/QWidget/qwidget_macro.h index 2e3f01dc2..2b581ff58 100644 --- a/src/cpp/QtGui/QWidget/qwidget_macro.h +++ b/src/cpp/QtGui/QWidget/qwidget_macro.h @@ -34,8 +34,8 @@ Napi::Value resize(const Napi::CallbackInfo& info) { \ Napi::Value close(const Napi::CallbackInfo& info) { \ Napi::Env env = info.Env(); \ Napi::HandleScope scope(env); \ - this->instance->close(); \ - return env.Null(); \ + bool hasClosed = this->instance->close(); \ + return Napi::Boolean::New(env, hasClosed); \ } \ \ Napi::Value setLayout(const Napi::CallbackInfo& info){ \ diff --git a/src/lib/QtGui/QWidget/index.ts b/src/lib/QtGui/QWidget/index.ts index 0275ba1d4..f5a1bb8e4 100644 --- a/src/lib/QtGui/QWidget/index.ts +++ b/src/lib/QtGui/QWidget/index.ts @@ -16,7 +16,7 @@ export abstract class NodeWidget extends EventWidget { this.native.resize(width, height); }; close = () => { - this.native.close(); + return this.native.close(); }; setLayout = (parentLayout: NodeLayout) => { const flexLayout = parentLayout as FlexLayout; diff --git a/src/lib/core/Component/index.ts b/src/lib/core/Component/index.ts index 3cba532c9..2f16c8b14 100644 --- a/src/lib/core/Component/index.ts +++ b/src/lib/core/Component/index.ts @@ -1,6 +1,6 @@ export type NativeElement = any; export abstract class Component { - protected children = new Set(); //TODO if react stub these as react will manage the instances from beings gc'ed better. + protected children = new Set(); protected parent?: Component; abstract native: NativeElement; }