Skip to content

Commit 4c7c112

Browse files
SerafimArtsSerafimArts
committed
Add basic information about application
1 parent deccd28 commit 4c7c112

File tree

4 files changed

+184
-2
lines changed

4 files changed

+184
-2
lines changed

‎Writerside/boson.tree‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
</toc-element>
1717
<toc-element toc-title="The Basics">
1818
<toc-element toc-title="Lifecycle" />
19-
<toc-element toc-title="Application" />
19+
<toc-element topic="application.md" />
2020
<toc-element toc-title="Window">
2121
<toc-element toc-title="Multiple Windows" />
2222
</toc-element>

‎Writerside/cfg/glossary.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
<!DOCTYPE terms SYSTEM "https://resources.jetbrains.com/writerside/1.0/glossary.dtd">
33
<terms>
44
<term name="FQN">Fully Qualified Name</term>
5-
<term name="TODO">This functionality is not implemented at the moment</term>
5+
<term name="TODO">This functionality or documentation is not implemented at the moment</term>
66
<term name="optional class">Can be created without requiring any mandatory arguments.</term>
77
</terms>

‎Writerside/topics/application.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Application
2+
3+
The `Application` is the central component of the Boson and is responsible for
4+
managing the application lifecycle. It provides a single entry point for
5+
creating and managing web applications using WebView.
6+
7+
The application is responsible for:
8+
9+
- Lifecycle management (startup, shutdown)
10+
- Window creation and management
11+
- WebView integration for web content display
12+
- Application, webview and window event handling
13+
14+
...and more
15+
16+
Architecturally, the application, like most key components, is divided into
17+
two "layers":
18+
- The main functionality belonging to the application itself.
19+
- Facades over methods and properties of descendants for quick access to the
20+
main internal components of the core.
21+
22+
23+
## Creating
24+
25+
To create an application, simply create a new <code>Boson\Application</code>
26+
object. This will be sufficient for the vast majority of cases.
27+
28+
<code-block lang="PHP">
29+
$app = new Boson\Application();
30+
</code-block>
31+
32+
The application constructor also contains several optional arguments that you
33+
can pass explicitly if you wish.
34+
35+
The first optional argument is responsible for the <code>Boson\ApplicationCreateInfo</code>
36+
application settings and allows you to fine-tune the application's operation.
37+
38+
<tip>
39+
More details about the application configuration are written on the
40+
<a href="configuration.md#application">corresponding documentation pages</a>.
41+
</tip>
42+
43+
<code-block lang="PHP">
44+
$config = new Boson\ApplicationCreateInfo(
45+
// application configuration options
46+
);
47+
48+
$app = new Boson\Application(info: $config);
49+
</code-block>
50+
51+
The remaining optional parameters are responsible for passing external
52+
dependencies.
53+
54+
For example, the second argument takes an optional reference to an external
55+
<code>Psr\EventDispatcher\EventDispatcherInterface</code> event dispatcher
56+
to which all events within the application can be delegated.
57+
58+
<code-block lang="PHP">
59+
$dispatcher = new Any\Vendor\PsrEventDispatcher();
60+
61+
$app = new Boson\Application(dispatcher: $dispatcher);
62+
</code-block>
63+
64+
After creating the application, you will have access to the API to work with
65+
it, and after the necessary actions, the application will automatically start,
66+
<a href="configuration.md#autorun">unless otherwise specified</a>.
67+
68+
## Running and Stopping
69+
70+
The application can be started manually using the <code>run()</code> method.
71+
72+
<code-block lang="PHP">
73+
$app = new Boson\Application();
74+
$app->run();
75+
</code-block>
76+
77+
<warning>
78+
The <code>run()</code> method is <b>blocking</b>, which means it will block
79+
the current execution thread until the application is stopped.
80+
81+
<code-block lang="PHP">
82+
$app = new Boson\Application();
83+
84+
echo 'Application will start...';
85+
86+
$app->run(); // This is a blocking operation
87+
88+
echo 'Application WAS stopped'; // The code will be executed ONLY
89+
// after stopping an application
90+
</code-block>
91+
</warning>
92+
93+
The application can be stopped at any time using the `quit()` method:
94+
95+
<code-block lang="PHP">
96+
$app->quit();
97+
</code-block>
98+
99+
<tip>
100+
For correct organization of the code, the stop should be made from the
101+
event subscription
102+
<code-block lang="PHP">
103+
$app = new Boson\Application();
104+
105+
$app->events->addEventListener(SomeEvent::class,
106+
function() use ($app): void {
107+
$app->quit();
108+
}
109+
);
110+
111+
$app->run();
112+
</code-block>
113+
</tip>
114+
115+
To find out if the application is running, you can use the
116+
`Application::$isRunning` property, which returns `true` if the application
117+
is currently running.
118+
119+
<code-block>
120+
$app = new Boson\Application();
121+
122+
// any code
123+
124+
if ($app->isRunning === false) {
125+
$app->run();
126+
}
127+
</code-block>
128+
129+
## Main Window
130+
131+
<tooltip term="TODO">TODO</tooltip>
132+
133+
## Main WebView
134+
135+
<tooltip term="TODO">TODO</tooltip>
136+
137+
## Application Events
138+
139+
The application will automatically emit the following events (and intentions)
140+
during its lifecycle:
141+
142+
- <code>ApplicationStarting</code> - when the application is about to start.
143+
<tip>This is an <b>intention</b>: You can prevent it from running using the
144+
<code>$starting->cancel()</code> method.</tip>
145+
146+
- <code>ApplicationStarted</code> - when the application has started.
147+
<tip>This is an <b>event</b>: Tells you that the application has already started.
148+
You cannot influence this in any way.</tip>
149+
150+
- <code>ApplicationStopping</code> - when the application is about to stop.
151+
<tip>This is an <b>intention</b>: You can prevent it from stopping using the
152+
<code>$stopping->cancel()</code> method.</tip>
153+
154+
- <code>ApplicationStopped</code> - when the application has stopped.
155+
<tip>This is an <b>event</b>: Tells you that the application has already stopped.
156+
You cannot influence this in any way.</tip>
157+
158+
More information about events can be found in the
159+
<tooltip term="TODO">events documentation</tooltip>.

‎Writerside/topics/getting-started/configuration.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,29 @@ $appConfig = new Boson\ApplicationCreateInfo(
234234

235235
<warning>The value cannot be changed after the application is created.</warning>
236236

237+
### Autorun
238+
239+
Responsible for automatic application launch. If autorun is set to
240+
<code>false</code>, you will need to launch the application yourself at the
241+
moment when it is needed.
242+
243+
<code-block lang="PHP">
244+
$appConfig = new Boson\ApplicationCreateInfo(
245+
autorun: false, // Default is true
246+
);
247+
</code-block>
248+
249+
250+
<tip>
251+
Autorun is disabled automatically if the application was launched manually
252+
using <code>$app->run()</code>. In other words, autostart will not work again
253+
(the application will not start twice) if you have already started it yourself.
254+
255+
Therefore, disabling this setting does not make sense.
256+
</tip>
257+
258+
<warning>The value cannot be changed after the application is created.</warning>
259+
237260
## Window
238261

239262
The window configuration class <code>Boson\Window\WindowCreateInfo</code> is

0 commit comments

Comments
 (0)