Skip to content

Commit 5b3cbf7

Browse files
XuanchenLinXuanchenLin
committed
📖 Documentation
1 parent ae41408 commit 5b3cbf7

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+3174
-117
lines changed

‎docs/Configuration/App-Manifest.md

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Use application manifest file
2+
3+
## Overview
4+
5+
In traditional WinForm application development, you don't need to care too much about the application manifest file, because these files are not necessary for traditional WinForm applications. But in a WinFormium application, a lot of functionality is tied to the application manifest file, so you need to know how to use the application manifest file.
6+
7+
## Create a manifest file for the application
8+
9+
Right-click Add on your WinFormium application project file, select "Application Manifest File" in "Add", "New Item" and click "Add" to add an application manifest file to the current project.
10+
11+
You can configure the following capabilities for your current app in the application manifest file:
12+
13+
**Set Windows User Account Control Level**
14+
15+
Some applications require an elevated user level to run properly. In this case, you can set the Windows User Account Control level in the application manifest file. For example: reading and writing the registry, reading and writing system files, etc.
16+
17+
Configuration information of each level has been added for you by default in the manifest file. You can select the appropriate level according to your needs.
18+
19+
```xml
20+
<trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
21+
<security>
22+
<requestedPrivileges xmlns="urn:schemas-microsoft-com:asm.v3">
23+
<!-- UAC manifest options
24+
If you want to change the Windows User Account Control level, use
25+
Replace the requestedExecutionLevel node with one of the following nodes.
26+
27+
<requestedExecutionLevel level="asInvoker" uiAccess="false" />
28+
<requestedExecutionLevel level="requireAdministrator" uiAccess="false" />
29+
<requestedExecutionLevel level="highestAvailable" uiAccess="false" />
30+
31+
Specifying the requestedExecutionLevel element disables file and registry virtualization.
32+
If your application requires this virtualization for backward compatibility, remove this
33+
element.
34+
-->
35+
<requestedExecutionLevel level="asInvoker" uiAccess="false" />
36+
</requestedPrivileges>
37+
</security>
38+
</trustInfo>
39+
```
40+
41+
If you need to know more about Windows User Account Control levels, please refer to [Windows User Account Control](https://docs.microsoft.com/zh-cn/windows/win32/secauthz/user-account-control).
42+
43+
**Set application DPI awareness**
44+
45+
In Windows 10 and later versions of the Windows operating system, you can set DPI awareness for your application so that the application displays properly on monitors with high DPI scaling. The .NET Core framework already provides you with these features. You do not need to configure the application manifest file for these versions of the framework. However, in applications based on the .NET Framework, you still need to add the following configuration to the application manifest file:
46+
47+
```xml
48+
<application xmlns="urn:schemas-microsoft-com:asm.v3">
49+
<windowsSettings>
50+
<dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true</dpiAware>
51+
<dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
52+
</windowsSettings>
53+
</application>
54+
```
55+
56+
If you need to know more about DPI awareness, please refer to [DPI awareness](https://docs.microsoft.com/zh-cn/windows/win32/hidpi/dpi-awareness).
57+
58+
**Enable theming of Windows common controls and dialog boxes**
59+
60+
In the CEF runtime, you can use Windows common controls and dialog boxes, but the themes of these controls and dialog boxes are not enabled by default. You can add the following configuration in the application manifest file to enable the themes of these controls and dialog boxes. :
61+
62+
```xml
63+
<dependency>
64+
<dependentAssembly>
65+
<assemblyIdentity
66+
type="win32"
67+
name="Microsoft.Windows.Common-Controls"
68+
version="6.0.0.0"
69+
processorArchitecture="*"
70+
publicKeyToken="6595b64144ccf1df"
71+
language="*"
72+
/>
73+
</dependentAssembly>
74+
</dependency>
75+
```
76+
77+
The most intuitive performance after enabling the above configuration is that if this configuration is not enabled, the elements with the `title` attribute in the web page will not be displayed normally, but after enabling it, they can be displayed normally.
78+
79+
## Hint
80+
81+
If your application uses the main process and the browser sub-process to run independently, then you need to add the above configuration to the application manifest files of both the main process and the browser sub-process. And the configuration content needs to be consistent.
82+
83+
## See also
84+
85+
- [Overview](Overview.md)
86+
- [Startup Configuration](./Startup.md)
87+
- [The Subprocess](./Subprocess.md)

‎docs/Configuration/Overview.md

+107
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Configure WinFormium Applications
2+
3+
## Overview
4+
5+
WinFormium uses the static method `CreateBuilder` of the `WinFormiumApp` class to create the application builder `AppBuilder`. In the builder you can set CEF's environment parameters, the application's run mode, the application's user data folder, the application's resource folder, etc.
6+
7+
`AppBuilder` provides a series of methods for configuring WinFormium applications. After you configure these parameters, use the `Build` method to create a WinFormium application instance and use the `Run` method to start the application.
8+
9+
```csharp
10+
var app = WinFormiumApp.CreateBuilder()
11+
// Configure the application here
12+
// ...
13+
.Build()
14+
.Run();
15+
```
16+
17+
Please refer to this section to learn how to configure a WinFormium application.
18+
19+
## Use startup configuration
20+
21+
Use the `UseWinFormiumApp<T>()` generic method of the WinFormium application constructor `AppBuilder` to pass in the startup configuration class. For more information, please refer to ["Startup Configuration"](./Startup Configuration.md).
22+
23+
## Enable built-in browser
24+
25+
When using a WinFormium app, when a user clicks a link in the app, the WinFormium app automatically opens the system default browser to open the link. If you wish to use WinFormium's built-in browser window to open links, you can enable the built-in browser using the `AppBuilder.UseBuiltInBrowser()` method.
26+
27+
```csharp
28+
var app = WinFormiumApp.CreateBuilder()
29+
.UseBuiltInBrowser()
30+
//...
31+
;
32+
```
33+
34+
## Configure culture of the application
35+
36+
WinFormium applications use the current system's language and culture by default, and you can configure the application's language and culture using the `AppBuilder.UseCulture()` method. The `UserCulture` method accepts a `string` type parameter, which is a language and culture identifier, for example `zh-CN` means Chinese Simplified, `en-US` means English United States.
37+
38+
```csharp
39+
var app = WinFormiumApp.CreateBuilder()
40+
.UseCulture("en-US")
41+
//...
42+
;
43+
```
44+
45+
## Singleton mode
46+
47+
Use the `AppBuilder.UseSingleInstance()` method to configure the application to run in singleton mode. If the application is already running, you can choose to activate the already running application. The `UseSingleInstance` method accepts an `Aciton<OnApplicationInstanceRunningHanlder>` parameter. `OnApplicationInstanceRunningHanlder` contains the following parameters and methods:
48+
49+
- int ProcessId { get; }
50+
The process ID of the application that is already running.
51+
- IntPtr MainWindowHandle { get; }
52+
The main form handle of the already running application.
53+
- Process RunningProcess { get; }
54+
The process object of an already running application.
55+
- void ActiveRunningInstance()
56+
Activate an already running application.
57+
58+
```csharp
59+
var app = WinFormiumApp.CreateBuilder()
60+
.UseSingleApplicationInstanceMode(handler =>
61+
{
62+
var retval = MessageBox.Show($"There is already an instance running: {handler.ProcessId}.\r\nDo you want to open its main form?", "Singleton mode is enabled", MessageBoxButtons.YesNo, MessageBoxIcon. Warning);
63+
if (retval == DialogResult.Yes)
64+
{
65+
handler.ActiveRunningInstance();
66+
}
67+
})
68+
//...
69+
;
70+
```
71+
72+
## Configure services
73+
74+
Use the `AppBuilder.UseServices()` method to configure the application's services, which accepts an `Action<IServiceCollection>` parameter, which contains a parameter of type `IServiceCollection` where you can register your service. Using `AppBuilder` the service will be registered in each process of the application.
75+
76+
If the service needs to run in the main process, the service should be registered in the `WinFormiumMain` method of `WinFormiumStartup`. For more information about `WinFormiumStartup`, please refer to ["Startup Configuration"](./Startup.md).
77+
78+
## Enable development tools menu
79+
80+
Using DevTools debugging tools is very useful when designing WinFormium applications. You can open DevTools debugging tools in `Formium` using the `OpenDevTools` method. If you wish to enable the DevTools menu in your application, you can enable the DevTools menu using the `AppBuilder.UseDevToolsMenu()` method, which allows you to right-click anywhere to launch DevTools in the context menu.
81+
82+
```csharp
83+
var app = WinFormiumApp.CreateBuilder()
84+
.UseDevToolsMenu()
85+
//...
86+
;
87+
```
88+
89+
## Clear browser cache
90+
91+
In the CEF interface, there is no method to clear the browser cache. Although WinFormium provides the `AppBuilder.ClearCache()` method to clear the browser cache, this is a very violent way to clear the cache. This method will delete the `Cache` folder in the CEF user data folder. Doing so The consequence is that all caches in your application will be cleared, including cookies, browser history, etc., so you cannot specify a certain type of cache to be deleted.
92+
93+
Also, when CEF loads, it locks the user data folder so you cannot delete files in the user data folder, so you must clear the cache before CEF loads.
94+
95+
```csharp
96+
var app = WinFormiumApp.CreateBuilder()
97+
.ClearCache()
98+
//...
99+
;
100+
```
101+
102+
## See also
103+
104+
- [Documentation](../Home.md)
105+
- [Startup Configuration](./Startup.md)
106+
- [Setup CEF](./Setup-CEF.md)
107+
- [The Subprocess](./Subprocess.md)

‎docs/Configuration/Setup-CEF.md

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Set up CEF
2+
3+
[Startup Configuration](./Startup.md) briefly introduces how to use the `UseChromiumEmbeddedFramework` method of the `AppBuilder` class to configure CEF. This chapter will introduce configurations not covered in this document.
4+
5+
## Disable Hidpi scaling for CEF
6+
7+
In CEF, when your application runs on a display with a high DPI scaling ratio, CEF will automatically scale the page content to adapt to the high DPI scaling ratio. The purpose of this is to make the page content appear on the display with a high DPI scaling ratio. The display is clearer. But in some cases, you may not want CEF to automatically scale the page content, then you can use the `DisableHidpiSupport` method to disable CEF's Hidpi scaling.
8+
9+
```csharp
10+
protected override void ConfigurationChromiumEmbedded(ChromiumEnvironmentBuiler cef)
11+
{
12+
cef.DisableHiDpiSupport();
13+
}
14+
```
15+
16+
## Use custom CEF runtime path
17+
18+
Normally you do not need to manually set the CEF runtime path because WinFormium automatically loads the CEF runtime from the NuGet package, but in some cases you may need to manually set the CEF runtime path, such as in your project When there are multiple WinFormium applications, it is not necessary for each WinFormium application to include a CEF runtime. This will cause your application to be too large. In this case, you can put the CEF runtime in a common location, and then Set the CEF runtime path in each WinFormium application.
19+
20+
The runtime path of CEF can be set using the `UseCustomDistributionDirectory` method, which accepts an `Action<CustomDistributionDirectoryOptions>` parameter, which contains a series of configuration options where you can configure the runtime path of CEF.
21+
22+
- public PlatformArchitecture Architecture { get; }
23+
The architecture of the CEF runtime, which can be x86 or x64.
24+
- public string LibCefPath { get; set; }
25+
Path to the libcef.dll file of the CEF runtime.
26+
- public string ResourceFilePath { get; set; }
27+
The path to the resource folder of the CEF runtime.
28+
29+
```csharp
30+
protected override void ConfigurationChromiumEmbedded(ChromiumEnvironmentBuiler cef)
31+
{
32+
cef.UseCustomDistributionDirectory(options => {
33+
if(options.Architecture == PlatformArchitecture.x86)
34+
{
35+
options.LibCefPath = Path.Combine("<path to 32bit libcef.dll>");
36+
}
37+
else
38+
{
39+
options.LibCefPath = Path.Combine("<path to 64bit libcef.dll>");
40+
}
41+
options.ResourceFilePath = Path.Combine("<path to resources of cef>");
42+
});
43+
}
44+
```
45+
46+
## Set user data folder
47+
48+
In CEF, the user data folder is used to store user configuration files, cache files, cookies and other data. You can use the `UseCustomUserDataDirectory` method to set the user data folder. This method accepts a `string` type parameter, which is The path to the user data folder.
49+
50+
```csharp
51+
protected override void ConfigurationChromiumEmbedded(ChromiumEnvironmentBuiler cef)
52+
{
53+
cef.UseCustomUserDataDirectory("<path to user data>");
54+
}
55+
```
56+
57+
Different application instances cannot share the same user data folder.
58+
59+
If your application does not want to store user data locally, you can use the `UseInMemoryUserData` method to set the user data folder to memory. When the application exits, the user data will be cleared from memory immediately.
60+
61+
```csharp
62+
protected override void ConfigurationChromiumEmbedded(ChromiumEnvironmentBuiler cef)
63+
{
64+
cef.UseInMemoryUserData();
65+
}
66+
```
67+
68+
## Set custom protocol scheme
69+
70+
Various custom resource processors of WinFormium will be introduced in ["Overview"](./Use Resources/Overview.md) of the "Using Resources" chapter. The resource processor registration interface allows you to specify the protocol scheme. By default in CEF A series of protocol schemes, such as `http`, `https`, `file`, `ftp`, etc. If the protocol scheme you specify is not within the default scheme range, such as `app`, `myapp`, etc., then you need Register these custom protocol schemes in CEF, otherwise CEF will not recognize these custom protocol schemes.
71+
72+
You can set custom protocol schemes using the `ConfigureCustomSchemes` method, which accepts an `Action<CefSchemeRegistrar>` parameter, which contains a series of configuration options where you can configure custom protocol schemes.
73+
74+
- public bool AddCustomScheme(string schemeName, CefSchemeOptions options);
75+
Add custom protocol scheme.
76+
77+
The first parameter of the `AddCustomScheme` method is the name of the custom protocol scheme, and the second parameter `CefSchemeOptions` is the configuration options of the custom protocol scheme. Use the `CefSchemeOptions` enumeration value to configure the properties of a custom protocol scheme.
78+
79+
```csharp
80+
protected override void ConfigurationChromiumEmbedded(ChromiumEnvironmentBuiler cef)
81+
{
82+
cef.ConfigureCustomSchemes(register => {
83+
register.AddCustomScheme("app", CefSchemeOptions.Standard);
84+
});
85+
}
86+
```
87+
88+
## See also
89+
90+
- [Overview](Overview.md)
91+
- [Startup Configuration](./Startup.md)
92+
- [Resources](./Resources/Overview.md)

0 commit comments

Comments
 (0)