Merge pull request #1061 from gircore/remove-notifypropertychanged

Remove INotifyPropertyChanged

docs/docs/faq.md

@@ -0,0 +1,38 @@
+# Frequently asked questions
+Common questions which can come up during development.
+
+## DLL not found Exception
+If the binaries are installed on the system but are not found during runtime a `DllNotFoundException` is raised. In this case the names of the installed libraries probably don't match the expected names.
+
+The gir.core nuget packages are build against 3 different package sources:
+1. Gnome SDK (Linux)
+2. MSYS2 (Windows)
+3. Homebrew (MacOS)
+
+Each of those sources defines the names of the binaries which must be available to call into them. If a custom build binary is used, the resulting name of the binary can differ from the one specified by the package source, thus resulting in a `DllNotFoundException`.
+
+In case of a custom build C binary it is recommended to use a custom gir.core build, too. Please follow the [build instructions](build.md) to get started. It is important to update the gir-files with the corresponding custom build gir-files.
+
+This allows projects with custom build C binaries to create matching C# binaries without being dependent on one of the package sources.
+
+## Property changed notifications
+C# developers are familar with the `INotifyPropertyChanged` interface, which can be used to notify an event listener about a changed property. The GObject type system uses a different but similar approach.
+
+Every class which inherits from `GObject.Object` has an event called `Object.OnNotify`. Subscriber to this event get notified about every changed property similar to `INotifyPropertyChanged`. The `NotifySignalArgs` event argument contains a `ParamSpec` instance which can be queried for the *native* property name via `GetName()`.
+
+As the *native* `Object` instance is represented in C# the properties in C# are named differently (mostly camel cased) in comparision to their *native* counterparts. To be able to match the *native* property name with their managed one, every *native* property has a static `Property` descriptor which provides the managed and unmanged name. Additionally it is possible to get or set the properties via their descriptor.
+
+In Addition to the `OnNotify` event there is a static field for each event which describes the event. Similar to properties it provides the managed and unmanaged name of every event and allows to connect to the event.
+
+The GObject type system is more advanced than `INotifyPropertyChanged` as it allows to subscribe to specific properties of an instance: This means there are only events received for properties the application is actually interested in. This feature can be used if an event listener is registered via the `NotifySignal.Connect()` method instead of the `OnNotify` event and supplies a *detail* parameter containing the *native* name of the property to watch. (Other events have a *detail* parameter, too with different meanings.)
+
+Sample Code:
+```csharp
+NotifySignal.Connect(
+    sender: myObj,
+    signalHandler: OnMyPropertyChanged,
+    detail: "my-property"
+);
+```
+
+Please remember that the detail information must contain the *native name* of a property which is available through the static property descriptor, too.

docs/docs/use.md

@@ -19,21 +19,4 @@ The easiest way to get started on Windows is by installing the packages through
 1. Download msys2 from the [official website](https://www.msys2.org/).
 2. Run `pacman -Syu` to update the package database.
 3. Run `pacman -S mingw-w64-x86_64-XXX` to install a package named XXX.
-4. Add the directory `C:/msys64/mingw64/bin` to the front of the PATH.
-
-## Troubleshooting
-Common problems which can come up during development.
-
-### DLL not found Exception
-If the binaries are installed on the system but are not found during runtime a `DllNotFoundException` is raised. In this case the names of the installed libraries probably don't match the expected names.
-
-The gir.core nuget packages are build against 3 different package sources:
-1. Gnome SDK (Linux)
-2. MSYS2 (Windows)
-3. Homebrew (MacOS)
-
-Each of those sources defines the names of the binaries which must be available to call into them. If a custom build binary is used, the resulting name of the binary can differ from the one specified by the package source, thus resulting in a `DllNotFoundException`.
-
-In case of a custom build C binary it is recommended to use a custom gir.core build, too. Please follow the [build instructions](build.md) to get started. It is important to update the gir-files with the corresponding custom build gir-files.
-
-This allows projects with custom build C binaries to create matching C# binaries without being dependent on one of the package sources.
+4. Add the directory `C:/msys64/mingw64/bin` to the front of the PATH.

docs/toc.yml

@@ -4,14 +4,16 @@ items:
 - name: Api Documentation
   href: api/
   homepage: api/index.md
-- name: Use
+- name: Get started
   items:
-  - name: Get started
+  - name: Use
     href: docs/use.md
   - name: Apps
     href: docs/apps.md
   - name: Libraries
     href: docs/libraries.md
+  - name: Faq
+    href: docs/faq.md
 - name: Contribute
   items:
   - name: Guidelines

src/GirCore.sln

@@ -155,6 +155,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{4EE9860B-6
 		..\docs\docs\use.md = ..\docs\docs\use.md
 		..\docs\docs\apps.md = ..\docs\docs\apps.md
 		..\docs\docs\build.md = ..\docs\docs\build.md
+		..\docs\docs\faq.md = ..\docs\docs\faq.md
 	EndProjectSection
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Adw-1", "Libs\Adw-1\Adw-1.csproj", "{CC67D284-6ADE-4F4D-9EE0-544143A7FF40}"

src/Libs/GObject-2.0/Public/Object.cs

@@ -8,13 +8,8 @@
 
 namespace GObject;
 
-public partial class Object : IObject, INotifyPropertyChanged, IDisposable, IHandle
+public partial class Object : IObject, IDisposable, IHandle
 {
-    /// <summary>
-    /// Event triggered when a property value changes.
-    /// </summary>
-    public event PropertyChangedEventHandler? PropertyChanged;
-
     private readonly ObjectHandle _handle;
 
     public IntPtr Handle => _handle.Handle;
@@ -73,18 +68,6 @@ protected virtual void Initialize()
         Debug.WriteLine($"Initialising Object: Address {_handle.Handle}, Type {GetType()}.");
     }
 
-    /// <summary>
-    /// Notify this object that a property has just changed.
-    /// </summary>
-    /// <param name="propertyName">The name of the property who changed.</param>
-    protected internal void OnPropertyChanged([CallerMemberName] string? propertyName = null)
-    {
-        if (propertyName == null)
-            return;
-
-        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
-    }
-
     public virtual void Dispose()
     {
         Debug.WriteLine($"Disposing Object: Address {_handle.Handle}, Type {GetType()}.");