Skip to content

Commit

Permalink
Updated readme.
Browse files Browse the repository at this point in the history
  • Loading branch information
@kekyo
kekyo committed Jun 16, 2024
1 parent 9016603 commit 08bc965
Show file tree
Hide file tree
Showing 2 changed files with 124 additions and 63 deletions.
96 changes: 63 additions & 33 deletions README.ja.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,17 @@

## これは何?

* Epoxyは、.NET XAML環境で使える、Model-View-ViewModel (MVVM) アーキテクチャ向けの、独立した柔軟性のあるライブラリです。
* C#を含む.NETの全処理系向け、及びF#用のNuGetパッケージがあります。
あなたは、XAMLを使用するGUIアプリケーションを作ったことはありますか？ WPFから始まり、現在では、Avalonia, OpenSilver, MAUIなど、様々なXAMLプラットフォームが存在します。

これらのXAMLプラットフォームでは、特にMVVM (Model-View-ViewModel) アーキテクチャを併用することが推奨されているのですが、MVVMには解釈の違いによる方言も多く、また完全に統一された強固なアーキテクチャでもないため、実装しようとすると困難に直面することがあります。

Epoxyは、MVVMをアーキテクチャではなく、一種の道具として捉え、学習曲線を緩やかにして、MVVMビギナーへの理解の助けや導入の容易さ、簡単でありながら独立性が高く再利用のしやすい機能群となるように設計しました。

もちろん、Epoxyは初心者専用のライブラリというわけではありません。シンプルであるということは、様々な環境でも柔軟で応用性があるということです。（非公開ではありますが、Epoxyは複数の業務利用実績があります。）

以下に、Epoxyの特徴を示します:

* C#を含む.NETの全処理系向け、及びF#用のNuGetパッケージがあります。
* 以下の環境をサポートしています:
* WPF: .NET 8.0/7.0/6.0/5.0, .NET Core 3.0/3.1, .NET Framework 4.5/4.8
* Avalonia: [Avalonia](https://avaloniaui.net/) (New v11 or 0.10 series)
Expand All @@ -41,10 +50,33 @@
* 大げさにならない、最小の手間とコストで Model-View-ViewModel 設計を実現します。
* Viewにコードビハインドを書かずに済むことが着地点ですが、そのために煩雑な処理を記述しなければならなくなる事を避ける方針です。
* MVVMビギナーが躓きそうな部分に焦点を当てています。
* 完全な共通化は行いません。Epoxyについてだけ同じように記述可能にし、その他の部分はそれぞれの環境に依存させることで、最大公約数的にならないようにしています。
* 完全な共通化は行いません。Epoxyについてだけ同じように記述可能にし、その他の部分はそれぞれの環境に依存させることで、機能が最大公約数的にならないようにしています。
* それぞれの機能が、相互に関係「しません」。独立しているので、自由に組み合わせることが出来ます。
* ほかのフレームワークライブラリ(例: ReactiveProperty)と組み合わせて使えるように、余計な操作や暗黙の前提を排除しています。

## 導入方法

ターゲットとなるGUIフレームワークに対応したNuGetパッケージを導入してください。
Epoxyパッケージは沢山公開されていますが、必要なのは、あなたが使っているXAMLプラットフォームに対応する、以下の特定のパッケージのみです:

* `Epoxy.Avalonia11`
* `Epoxy.Avalonia`
* `Epoxy.WPF`
* `Epoxy.OpenSilver`
* `Epoxy.MAUI`
* `FSharp.Epoxy.Avalonia11`
* `FSharp.Epoxy.Avalonia`
* `FSharp.Epoxy.WPF`

などのパッケージのみです。
他に `Epoxy.Core.WPF`や`Epoxy.Build`と言ったパッケージが見つかるかもしれませんが、
これらは上記のパッケージから依存して自動的に使用されます。

注意: `Epoxy.Templates`には、テンプレートプロジェクト定義が含まれていましたが、1.15.0から廃止されました。これに伴い、Visual Studioのテンプレートウィザードも廃止されています。大丈夫です、ウィザードに頼らなくても、Epoxyは簡単に使い始めることができます！


----

## サンプルコード

様々な環境の実働サンプルがあります。
Expand All @@ -68,29 +100,13 @@

[(再生出来ない場合はこちら)](https://www.youtube.com/watch?v=LkyrgJbuiQs)

### 導入方法

ターゲットとなるGUIフレームワークに対応したNuGetパッケージを導入してください。
Epoxyパッケージは沢山公開されていますが、必要なのは:

* `Epoxy.Avalonia11`
* `Epoxy.Avalonia`
* `Epoxy.WPF`
* `Epoxy.OpenSilver`
* `Epoxy.MAUI`

などのパッケージのみです。
他に `Epoxy.Core.WPF`や`Epoxy.Build`と言ったパッケージが見つかるかもしれませんが、
これらは上記のパッケージから依存して自動的に使用されます。

注意: `Epoxy.Templates`には、テンプレートプロジェクト定義が含まれていましたが、1.15.0から廃止されました。
これに伴い、Visual Studioのテンプレートウィザードも廃止されています。

----

## MVVMアプリケーションの実装を、最小限の手間で始める

Model-View-ViewModelの役割についてのおさらい:
いますぐEpoxyの具体的な機能を確認したい場合は、 [機能一覧](#機能一覧)を参照してください。
ここでは、Model-View-ViewModelのそれぞれの役割について、おさらいします:

* `View`: XAMLでユーザーインターフェイスを記述し、`ViewModel`とバインディングする（コードビハインドを書かない）。
* `ViewModel`: `Model`から情報を取得して、`View`にマッピングするプロパティを定義する。
Expand All @@ -102,13 +118,17 @@ Model-View-ViewModelの役割についてのおさらい:

注意: MVVMの役割については諸説あります。
はじめから完全な設計を目指さずに、ブラッシュアップすると良いでしょう。
Epoxyは段階的に改善する事を想定して開発しています。
Epoxyは段階的に改善する事を想定して設計しています。

XAMLビューの定義とその実装を、MVVMに従って完全に分離しつつ、最小限の手間で実装する例です
XAMLビューの定義とその実装を、MVVMに従って完全に分離しつつ、最小限の手間で実装する例を示します。前節の、The CAT APIを使用する例です。
(このコードはWPFの例で、ポイントとなる点に絞っているため、完全な例はサンプルコードを参照して下さい):

### View (WPF XAML)の実装例

MVVMのViewとは、表示の見た目や構造をXAMLで定義します。ここには、動的な制御処理は記述しません。各コントロールの配置、色、フォントなどが含まれます。

`ListBox`コントロールは、複数の同じ見た目を持つ項目群を並べて表示する機能があります。

```xml
<Window
x:Class="EpoxyHello.Wpf.Views.MainWindow"
Expand Down Expand Up @@ -147,8 +167,21 @@ XAMLビューの定義とその実装を、MVVMに従って完全に分離しつ

### ViewModel (WPF)の実装例

完全に分離された、ViewModelクラスの実装です。
完全に、とは、つまりViewクラスに、コードビハインドを一切記述しないことを指します。
ViewModelの役割は、XAMLで定義された各コントロールを制御するコードを記述して、動的な振る舞いを持たせることです。

かつてのWindows Formsのように、なぜViewとViewModelの実装を一体化させないのか？という疑問には、さまざまな理由がありますが、現実的な問題として、 `ListBox` のような複数の要素に対して異なる内容を表示したり制御するのに、コードだけで実現するのは困難だからです。

これを解決するために、データバインディングと呼ばれる機能があり、データバインディングで問題を解決するために、MVVMというアーキテクチャが考案されたと言っていいでしょう。

`ListBox` の例で言うなら、ViewModelに定義されている `Items` コレクションの内容が、1対1で表示の各要素に対応するように、自動的に表示が更新されます。したがって:

* View側は各要素をどのように表示するか。配置や色やフォント、画像やその加工などをXAMLで指定する。
* ViewModel側は、各要素を追加、削除、あるいは順序の入れ替え、テキスト文字列や画像データの生成を行う。

ことに集中することができます。

以下は、表示と制御が完全に分離された、ViewModelクラスの実装です。
完全に分離、とは、つまりViewクラスに、コードビハインドを一切記述しないことを指します。

```csharp
// ステップ 1: ViewModelクラスを作ります。そしてViewModel属性を付与します。
Expand Down Expand Up @@ -226,12 +259,12 @@ Modelの実装は、直接ユーザーインターフェイスを操作する事
非同期操作でタスクコンテキストを分離 `task.ConfigureAwait(false)` することで、
パフォーマンスを向上させることが出来ます。


----

## 機能一覧

それぞれの機能は独立しているため、自由に組み合わせて使用出来ます
（例えば、`ViewModel`を継承していないと使えない、と言うような事はありません）。
以下に、Epoxyの機能の一覧を示します。Epoxyのそれぞれの機能は独立しているため、自由に組み合わせて使用出来ます（例えば、ViewModelにありがちな、基底クラスの継承は必須ではありません）。

|機能名|概要|
|:----|:----|
Expand Down Expand Up @@ -406,11 +439,7 @@ Avaloniaでは、 `RoutedEvent` からイベントの引数 `EventArgs` の型

```csharp
// Loadedイベントを受信するためのCommandプロパティの定義
public Command? Ready
{
get => this.GetValue();
private set => this.SetValue(value);
}
public Command? Ready { get; private set; }

// ...
Expand Down Expand Up @@ -476,7 +505,7 @@ MVVMアーキテクチャのレアケースにおいて、コントロールを
```csharp
// PileをViewModelに配置します。
// (操作したいTextBoxのXAMLにAnchorを配置して、バインディングします)
this.LogPile = Pile.Factory.Create<TextBox>();
public Pile<TextBox> LogPile { get; } = Pile.Factory.Create<TextBox>();

// ...
Expand Down Expand Up @@ -832,6 +861,7 @@ Apache-v2
* Xamarin Formsを廃止。
* テンプレートプロジェクトを廃止。
* まだしばらくは新規プロジェクト生成として機能すると思いますが、更新されません。
* [ステップバイステップでコミットを作成した、Avalonia 11のサンプルリポジトリ](https://github.com/kekyo/Epoxy.Avalonia11.SampleProject) が役に立つかもしれません。
* 互換性の為に残されていたObsoleteメンバーを削除。
* 1.14.0:
* Avalonia 11で、XAMLからEpoxyを参照する際の名前空間にURLを指定可能にしました。
Expand Down
91 changes: 61 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,17 @@

## What is this ?

* Epoxy is a .NET XAML Model-View-ViewModel data-bindable infrastructure library, independent flexible API sets.
* All .NET languages including C#, and specialized F# NuGet packages are available.
Have you ever created a GUI application that uses XAML? Starting with WPF, there are now various XAML platforms such as Avalonia, OpenSilver, and MAUI.

These XAML platforms are especially recommended to use MVVM (Model-View-ViewModel) architecture together, but since MVVM has many dialects due to different interpretations and is not a completely unified and robust architecture, you may face difficulties when trying to use it.

Epoxy designed MVVM not as an architecture, rather as a kind of tool, with a gentle learning curve to help beginners understand MVVM, ease of introduction, and a set of functions that are simple, independent, and easy to reuse.

Of course, Epoxy is not a beginner-only library. Its simplicity means that it is flexible and applicable in a variety of environments.（Epoxy has been used in several business applications, although not publicly).

The following is a list of Epoxy's features:

* All .NET languages including C#, and specialized F# NuGet packages are available.
* Supported platforms:
* WPF: .NET 8.0/7.0/6.0/5.0, .NET Core 3.0/3.1, .NET Framework 4.5/4.8
* Avalonia: [Avalonia](https://avaloniaui.net/) (New v11 or 0.10 series)
Expand All @@ -45,6 +54,28 @@
* Each function is "unrelated" to each other. Since they are independent, they can be freely combined.
* Friction-free for combination other framework libraries such as ReactiveProperty and etc.

## Introduction

Install the NuGet package that corresponds to your target GUI framework.
There are many Epoxy packages available, but you only need the following specific packages for the XAML platform you are using:

* `Epoxy.Avalonia11`
* `Epoxy.Avalonia`
* `Epoxy.WPF`
* `Epoxy.OpenSilver`
* `Epoxy.MAUI`
* `FSharp.Epoxy.Avalonia11`
* `FSharp.Epoxy.Avalonia`
* `FSharp.Epoxy.WPF`

You may find other packages like `Epoxy.Core.WPF` or `Epoxy.Build`, though,
these are automatically used as dependencies from the above packages.

Note: `Epoxy.Templates` used to contain template project definitions, but is discontinued as of 1.15.0. With this change, the Template Wizard in Visual Studio has also been discontinued too. Don't worry, you don't need to rely on a wizard to get started with Epoxy!


----

## Sample code

You can refer multi-platform application sample code variation in.
Expand All @@ -64,28 +95,13 @@ or F# sample code in the [playground FSharp directory](playground.FSharp/).
If you want to apply Epoxy in a full-scratch or to apply Epoxy into an existing project,
[Avalonia 11 sample repository with step-by-step commits](https://github.com/kekyo/Epoxy.Avalonia11.SampleProject) may be helpful.

### Introduction

Install the NuGet package that corresponds to your target GUI framework.
There are many Epoxy packages available, but all you need is:

* `Epoxy.Avalonia11`
* `Epoxy.Avalonia`
* `Epoxy.WPF`
* `Epoxy.OpenSilver`
* `Epoxy.MAUI`

You may find other packages like `Epoxy.Core.WPF` or `Epoxy.Build`, though,
these are automatically used as dependencies from the above packages.

Note: `Epoxy.Templates` used to contain template project definitions, but is discontinued as of 1.15.0.
With this change, the Template Wizard in Visual Studio has also been discontinued too.

----

## Getting started minimum MVVM application

Review of Model-View-ViewModel architecture:
If you want to see the specific features of Epoxy right now, please refer to the [Feature List](#Features).
In this section, we will review the roles of Model-View-ViewModel:

* `View`: Describes the user interface in XAML and write binding expressions to the `ViewModel` (without writing code-behinds).
* `ViewModel`: Get information from `Model` and define properties that map to `View`.
Expand All @@ -99,11 +115,15 @@ NOTE: There are many theories about the architecture of MVVM.
It is a good idea to brush up on the design without aiming for perfection from the start.
Epoxy is designed to be improved step by step.

Completed separately xaml based view declarations.
Completed separately xaml based view declarations. Here is an example of using The CAT API, from the previous section.
(WPF, introducing focused, refer full sample code instead):

### Example of View (WPF/XAML) implementation

The "View" in MVVM is defined in XAML as the appearance and structure of the display. Dynamic control processing (any code fragmets) is not described here. This includes the placement, colors, fonts, etc. of each control.

The `ListBox` control has the ability to display a group of items with the same appearance side by side.

```xml
<Window
x:Class="EpoxyHello.Wpf.Views.MainWindow"
Expand Down Expand Up @@ -142,8 +162,21 @@ Completed separately xaml based view declarations.

### Example of ViewModel (WPF) implementation

Completed separately `ViewModel` implementation.
Completely, that is, without any code-behind in the View class.
The role of "ViewModel" is to write code to control each control defined in XAML to have dynamic behavior.

Why not unify the View and ViewModel implementations, as "Windows Forms" used to do? There are many reasons for this question, but the practical problem is that it is difficult to display and control different contents for multiple elements, such as a `ListBox` using only code.

To solve this problem, there is a feature called "Data binding", and it is fair to say that the MVVM architecture was invented to solve the problem with data binding.

In the `ListBox` example, the display is automatically updated so that the contents of the `Items` collection defined in the ViewModel correspond to each element of the display on a one-to-one basis. Thus:

* How the View side should display each element. The placement, colors, fonts, images and their processing, etc. are specified in XAML.
* The ViewModel side adds, deletes, or reorders each element, and generates text strings and image data.

The ViewModel side can concentrate on.

The following is an implementation of the ViewModel class in which the display and control are completely separated.
Complete separation means that no code-behind is written in the View class.

```csharp
// Step 1: Create a ViewModel class. Then add the ViewModel attribute.
Expand Down Expand Up @@ -219,12 +252,12 @@ public static async ValueTask<byte[]> FetchImageAsync(Uri url)
Since the Model implementation does not directly manipulate the user interface fragments,
it can isolate task contexts with `task.ConfigureAwait(false)` annotation to improve performance.


----

## Features

Since each function is independent, it can be used in any combination.
(For example, it is NOT necessary to inherit from `ViewModel` to use it.)
The following is a list of Epoxy features, each of which is independent and can be used in any combination (e.g., inheritance of the base class is not required, as is often the case with ViewModel).

|Function|Summary|
|:----|:----|
Expand Down Expand Up @@ -388,11 +421,7 @@ On the `ViewModel` side, you can write handlers in Command, just like Button:

```csharp
// Defining the Command property for receiving Loaded events
public Command? Ready
{
get => this.GetValue();
private set => this.SetValue(value);
}
public Command? Ready { get; private set; }

// ...
Expand Down Expand Up @@ -455,7 +484,7 @@ The `Pile` pull in the `UIElement`'s anchor, and we can rent temporary `UIElemen

```csharp
// Declared a Pile into the ViewModel.
this.LogPile = Pile.Factory.Create<TextBox>();
public Pile<TextBox> LogPile { get; } = Pile.Factory.Create<TextBox>();

// ...
Expand Down Expand Up @@ -826,6 +855,8 @@ Apache-v2
* Deprecated Xamarin Forms.
* Deprecated Template Projects.
* Will still function as a new project generation for a while, but will not be updated.
* If you want to apply Epoxy in a full-scratch or to apply Epoxy into an existing project,
[Avalonia 11 sample repository with step-by-step commits](https://github.com/kekyo/Epoxy.Avalonia11.SampleProject) may be helpful.
* Removed Obsolete member left for compatibility.
* 1.14.0:
* In Avalonia 11, allow URLs to be specified in the namespace when referencing Epoxy from XAML.
Expand Down

0 comments on commit 08bc965

Please sign in to comment.