Skip to content

Commit cc14260

Browse files
dipeshmsftdipeshmsft
committed
Adding doc comments for ThemeMode, ThemeModeConverter introduced in PresentationFramework
1 parent c98899a commit cc14260

File tree

4 files changed

+124
-52
lines changed

4 files changed

+124
-52
lines changed

‎xml/System.Windows/Application.xml‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2476,9 +2476,30 @@ This example illustrates how to use XAML together with application-scope resourc
24762476
<ReturnType>System.Windows.ThemeMode</ReturnType>
24772477
</ReturnValue>
24782478
<Docs>
2479-
<summary>To be added.</summary>
2479+
<summary>
2480+
<para>The ThemeMode property is used to set the Fluent theme mode of the application.</para>
2481+
<para>Setting this property controls if Fluent is loaded in Light, Dark or System mode.</para>
2482+
<para>It also controls the application of backdrop and darkmode on window.</para>
2483+
<para>The four values for the ThemeMode enum are :</para>
2484+
<para>
2485+
<see cref="P:System.Windows.ThemeMode.None" /> - No Fluent theme is loaded.</para>
2486+
<para>
2487+
<see cref="P:System.Windows.ThemeMode.System" /> - Fluent theme is loaded based on the system theme.</para>
2488+
<para>
2489+
<see cref="P:System.Windows.ThemeMode.Light" /> - Fluent theme is loaded in Light mode.</para>
2490+
<para>
2491+
<see cref="P:System.Windows.ThemeMode.Dark" /> - Fluent theme is loaded in Dark mode.</para>
2492+
<para>These values are predefined in <see cref="P:System.Windows.Application.ThemeMode" /> struct The default value is <see cref="P:System.Windows.ThemeMode.None" />.</para>
2493+
</summary>
24802494
<value>To be added.</value>
2481-
<remarks>To be added.</remarks>
2495+
<remarks>
2496+
<para>
2497+
<see cref="P:System.Windows.Application.ThemeMode" /> and <see cref="P:System.Windows.Application.Resources" /> are designed to be in sync with each other.</para>
2498+
<para>Syncing is done in order to avoid UI inconsistencies, where the window is in dark mode but the controls within are in light mode or vice versa.</para>
2499+
<para>Setting this property will load the Fluent theme dictionaries in the application resources.</para>
2500+
<para>So, if you are setting this property, it is preferrable to not include Fluent theme dictionaries in the application resources manually. If you do, the Fluent theme dictionaries added in the application resources will take precedence over the ones added by setting this property.</para>
2501+
<para>This property is experimental and may be removed in future versions.</para>
2502+
</remarks>
24822503
</Docs>
24832504
</Member>
24842505
<Member MemberName="TryFindResource">

‎xml/System.Windows/ThemeMode.xml‎

Lines changed: 51 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,13 @@
2828
</Attribute>
2929
</Attributes>
3030
<Docs>
31-
<summary>To be added.</summary>
32-
<remarks>To be added.</remarks>
31+
<summary>
32+
<para>ThemeMode structure describes the Fluent theme mode to be applied on Application or a Window.</para>
33+
</summary>
34+
<remarks>
35+
<para>This is an experimental API and may be modified or removed in future releases.</para>
36+
<para>Since this is an experimental API, rather than creating a new instance of ThemeMode, use the static properties Light, Dark, System and None.</para>
37+
</remarks>
3338
</Docs>
3439
<Members>
3540
<Member MemberName=".ctor">
@@ -48,8 +53,8 @@
4853
<Parameter Name="value" Type="System.String" />
4954
</Parameters>
5055
<Docs>
51-
<param name="value">To be added.</param>
52-
<summary>To be added.</summary>
56+
<param name="value">Name of theme mode</param>
57+
<summary>Creates a new ThemeMode object with the specified value.</summary>
5358
<remarks>To be added.</remarks>
5459
</Docs>
5560
</Member>
@@ -69,7 +74,10 @@
6974
<ReturnType>System.Windows.ThemeMode</ReturnType>
7075
</ReturnValue>
7176
<Docs>
72-
<summary>To be added.</summary>
77+
<summary>
78+
<para>Predefined theme mode: Dark.</para>
79+
<para>Whenever this mode is set on <see cref="T:System.Windows.Application" /> or <see cref="T:System.Windows.Window" />, Fluent Dark theme will be applied.</para>
80+
</summary>
7381
<value>To be added.</value>
7482
<remarks>To be added.</remarks>
7583
</Docs>
@@ -93,9 +101,9 @@
93101
<Parameter Name="obj" Type="System.Object" />
94102
</Parameters>
95103
<Docs>
96-
<param name="obj">To be added.</param>
97-
<summary>To be added.</summary>
98-
<returns>To be added.</returns>
104+
<param name="obj">ThemeMode object to compare with.</param>
105+
<summary>Checks whether the object is equal to another ThemeMode object.</summary>
106+
<returns>Returns <see langword="true" /> when the ThemeMode objects are equal, and <see langword="false" /> otherwise.</returns>
99107
<remarks>To be added.</remarks>
100108
</Docs>
101109
</Member>
@@ -121,9 +129,9 @@
121129
<Parameter Name="other" Type="System.Windows.ThemeMode" />
122130
</Parameters>
123131
<Docs>
124-
<param name="other">To be added.</param>
125-
<summary>To be added.</summary>
126-
<returns>To be added.</returns>
132+
<param name="other">ThemeMode object to compare with</param>
133+
<summary>Checks whether the ThemeMode object is equal to another ThemeMode object.</summary>
134+
<returns>Returns <see langword="true" /> when the ThemeMode objects are equal, and <see langword="false" /> otherwise.</returns>
127135
<remarks>To be added.</remarks>
128136
</Docs>
129137
</Member>
@@ -144,8 +152,8 @@
144152
</ReturnValue>
145153
<Parameters />
146154
<Docs>
147-
<summary>To be added.</summary>
148-
<returns>To be added.</returns>
155+
<summary>Compute hash code for this object.</summary>
156+
<returns>A 32-bit signed integer hash code.</returns>
149157
<remarks>To be added.</remarks>
150158
</Docs>
151159
</Member>
@@ -165,7 +173,10 @@
165173
<ReturnType>System.Windows.ThemeMode</ReturnType>
166174
</ReturnValue>
167175
<Docs>
168-
<summary>To be added.</summary>
176+
<summary>
177+
<para>Predefined theme mode: Light.</para>
178+
<para>Whenever this mode is set on <see cref="T:System.Windows.Application" /> or <see cref="T:System.Windows.Window" />, Fluent Light theme will be applied.</para>
179+
</summary>
169180
<value>To be added.</value>
170181
<remarks>To be added.</remarks>
171182
</Docs>
@@ -186,9 +197,14 @@
186197
<ReturnType>System.Windows.ThemeMode</ReturnType>
187198
</ReturnValue>
188199
<Docs>
189-
<summary>To be added.</summary>
200+
<summary>
201+
<para>Predefined theme mode: None.</para>
202+
<para>This is the default value for <see cref="P:System.Windows.Application.ThemeMode" /> and <see cref="P:System.Windows.Window.ThemeMode" /> and it means that Fluent theme will not be applied on the Application or Window.</para>
203+
</summary>
190204
<value>To be added.</value>
191-
<remarks>To be added.</remarks>
205+
<remarks>
206+
<para>In case, when Application.ThemeNode is not set to None, even if Window.ThemeMode is set to None, the Fluent theme will be applied on the Window.</para>
207+
</remarks>
192208
</Docs>
193209
</Member>
194210
<Member MemberName="op_Equality">
@@ -211,10 +227,12 @@
211227
<Parameter Name="right" Type="System.Windows.ThemeMode" />
212228
</Parameters>
213229
<Docs>
214-
<param name="left">To be added.</param>
215-
<param name="right">To be added.</param>
216-
<summary>To be added.</summary>
217-
<returns>To be added.</returns>
230+
<param name="left">First ThemeMode object to compare</param>
231+
<param name="right">Second ThemeMode object to compare</param>
232+
<summary>Checks whether two ThemeMode objects are equal.</summary>
233+
<returns>
234+
<para>Returns <see langword="true" /> when both the ThemeMode objects are equal, and <see langword="false" /> otherwise.</para>
235+
</returns>
218236
<remarks>To be added.</remarks>
219237
</Docs>
220238
</Member>
@@ -238,10 +256,12 @@
238256
<Parameter Name="right" Type="System.Windows.ThemeMode" />
239257
</Parameters>
240258
<Docs>
241-
<param name="left">To be added.</param>
242-
<param name="right">To be added.</param>
243-
<summary>To be added.</summary>
244-
<returns>To be added.</returns>
259+
<param name="left">First ThemeMode object to compare</param>
260+
<param name="right">Second ThemeMode object to compare</param>
261+
<summary>Checks whether two ThemeMode objects are not equal.</summary>
262+
<returns>
263+
<para>Returns <see langword="true" /> when the ThemeMode objects are not equal, and <see langword="false" /> otherwise.</para>
264+
</returns>
245265
<remarks>To be added.</remarks>
246266
</Docs>
247267
</Member>
@@ -261,7 +281,10 @@
261281
<ReturnType>System.Windows.ThemeMode</ReturnType>
262282
</ReturnValue>
263283
<Docs>
264-
<summary>To be added.</summary>
284+
<summary>
285+
<para>Perdefined theme mode : System.</para>
286+
<para>Whenever this mode is set on <see cref="T:System.Windows.Application" /> or <see cref="T:System.Windows.Window" />, Fluent theme will be applied based on the system theme.</para>
287+
</summary>
265288
<value>To be added.</value>
266289
<remarks>To be added.</remarks>
267290
</Docs>
@@ -283,8 +306,8 @@
283306
</ReturnValue>
284307
<Parameters />
285308
<Docs>
286-
<summary>To be added.</summary>
287-
<returns>To be added.</returns>
309+
<summary>Creates a string representation of the ThemeMode object.</summary>
310+
<returns>A string representation of this object.</returns>
288311
<remarks>To be added.</remarks>
289312
</Docs>
290313
</Member>
@@ -304,7 +327,7 @@
304327
<ReturnType>System.String</ReturnType>
305328
</ReturnValue>
306329
<Docs>
307-
<summary>To be added.</summary>
330+
<summary>Gets the value of the ThemeMode.</summary>
308331
<value>To be added.</value>
309332
<remarks>To be added.</remarks>
310333
</Docs>

‎xml/System.Windows/ThemeModeConverter.xml‎

Lines changed: 27 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,9 @@
2020
</Attribute>
2121
</Attributes>
2222
<Docs>
23-
<summary>To be added.</summary>
23+
<summary>
24+
<para>ThemeModeConverter - Converter class for converting instances of other types to and from ThemeMode instances.</para>
25+
</summary>
2426
<remarks>To be added.</remarks>
2527
</Docs>
2628
<Members>
@@ -61,10 +63,10 @@
6163
<Parameter Name="sourceType" Type="System.Type" />
6264
</Parameters>
6365
<Docs>
64-
<param name="typeDescriptorContext">To be added.</param>
65-
<param name="sourceType">To be added.</param>
66-
<summary>To be added.</summary>
67-
<returns>To be added.</returns>
66+
<param name="typeDescriptorContext">The ITypeDescriptorContext for this call.</param>
67+
<param name="sourceType">The Type being queried for support.</param>
68+
<summary>CanConvertFrom - Returns whether or not this class can convert from a given type.</summary>
69+
<returns>bool - <see langword="true" /> if thie converter can convert from the provided type, <see langword="false" /> if not.</returns>
6870
<remarks>To be added.</remarks>
6971
</Docs>
7072
</Member>
@@ -88,10 +90,10 @@
8890
<Parameter Name="destinationType" Type="System.Type" />
8991
</Parameters>
9092
<Docs>
91-
<param name="typeDescriptorContext">To be added.</param>
92-
<param name="destinationType">To be added.</param>
93-
<summary>To be added.</summary>
94-
<returns>To be added.</returns>
93+
<param name="typeDescriptorContext">The ITypeDescriptorContext for this call.</param>
94+
<param name="destinationType">The Type being queried for support.</param>
95+
<summary>CanConvertTo - Returns whether or not this class can convert to a given type.</summary>
96+
<returns>bool - <see langword="true" /> if this converter can convert to the provided type, <see langword="false" /> if not.</returns>
9597
<remarks>To be added.</remarks>
9698
</Docs>
9799
</Member>
@@ -116,12 +118,13 @@
116118
<Parameter Name="source" Type="System.Object" />
117119
</Parameters>
118120
<Docs>
119-
<param name="typeDescriptorContext">To be added.</param>
120-
<param name="cultureInfo">To be added.</param>
121-
<param name="source">To be added.</param>
122-
<summary>To be added.</summary>
123-
<returns>To be added.</returns>
121+
<param name="typeDescriptorContext">The ITypeDescriptorContext for this call.</param>
122+
<param name="cultureInfo">The CultureInfo which is respected when converting.</param>
123+
<param name="source">The object to convert to a ThemeMode.</param>
124+
<summary>ConvertFrom - Attempts to convert to a ThemeMode from the given object</summary>
125+
<returns>ThemeMode instance which was constructed.</returns>
124126
<remarks>To be added.</remarks>
127+
<exception cref="T:System.ArgumentNullException">An ArgumentNullException is thrown if the example object is <see langword="null" />.</exception>
125128
</Docs>
126129
</Member>
127130
<Member MemberName="ConvertTo">
@@ -146,13 +149,17 @@
146149
<Parameter Name="destinationType" Type="System.Type" />
147150
</Parameters>
148151
<Docs>
149-
<param name="typeDescriptorContext">To be added.</param>
150-
<param name="cultureInfo">To be added.</param>
151-
<param name="value">To be added.</param>
152-
<param name="destinationType">To be added.</param>
153-
<summary>To be added.</summary>
154-
<returns>To be added.</returns>
152+
<param name="typeDescriptorContext">The ITypeDescriptorContext for this call.</param>
153+
<param name="cultureInfo">The CultureInfo which is respected when converting.</param>
154+
<param name="value">The ThemeMode to convert.</param>
155+
<param name="destinationType">The type to which to convert the ThemeMode instance.</param>
156+
<summary>ConvertTo - Attempts to convert a ThemeMode to the given type</summary>
157+
<returns>The object which was constructoed.</returns>
155158
<remarks>To be added.</remarks>
159+
<exception cref="T:System.ArgumentNullException">An ArgumentNullException is thrown if the example object is <see langword="null" />.</exception>
160+
<exception cref="T:System.ArgumentException">
161+
<para>An ArgumentException is thrown if the object is not <see langword="null" /> and is not a ThemeMode, or if the destinationType isn't one of the valid destination types.</para>
162+
</exception>
156163
</Docs>
157164
</Member>
158165
</Members>

‎xml/System.Windows/Window.xml‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2597,9 +2597,30 @@ The following example shows a **File** > **Exit** menu being handled to explicit
25972597
<ReturnType>System.Windows.ThemeMode</ReturnType>
25982598
</ReturnValue>
25992599
<Docs>
2600-
<summary>To be added.</summary>
2600+
<summary>
2601+
<para>The ThemeMode property is used to set the Fluent theme mode of the application.</para>
2602+
<para>Setting this property controls if Fluent is loaded in Light, Dark or System mode.</para>
2603+
<para>It also controls the application of backdrop and darkmode on window.</para>
2604+
<para>The four values for the ThemeMode enum are :</para>
2605+
<para>
2606+
<see cref="P:System.Windows.ThemeMode.None" /> - No Fluent theme is loaded.</para>
2607+
<para>
2608+
<see cref="P:System.Windows.ThemeMode.System" /> - Fluent theme is loaded based on the system theme.</para>
2609+
<para>
2610+
<see cref="P:System.Windows.ThemeMode.Light" /> - Fluent theme is loaded in Light mode.</para>
2611+
<para>
2612+
<see cref="P:System.Windows.ThemeMode.Dark" /> - Fluent theme is loaded in Dark mode.</para>
2613+
<para>These values are predefined in <see cref="P:System.Windows.Window.ThemeMode" /> struct The default value is <see cref="P:System.Windows.ThemeMode.None" />.</para>
2614+
</summary>
26012615
<value>To be added.</value>
2602-
<remarks>To be added.</remarks>
2616+
<remarks>
2617+
<para>
2618+
<see cref="P:System.Windows.Window.ThemeMode" /> and <see cref="N:System.Windows.Resources" /> are designed to be in sync with each other.</para>
2619+
<para>Syncing is done in order to avoid UI inconsistencies, where the window is in dark mode but the controls within are in light mode or vice versa.</para>
2620+
<para>Setting this property will load the Fluent theme dictionaries in the application resources.</para>
2621+
<para>So, if you are setting this property, it is preferrable to not include Fluent theme dictionaries in the application resources manually. If you do, the Fluent theme dictionaries added in the application resources will take precedence over the ones added by setting this property.</para>
2622+
<para>This property is experimental and may be removed in future versions.</para>
2623+
</remarks>
26032624
</Docs>
26042625
</Member>
26052626
<Member MemberName="Title">

0 commit comments

Comments
 (0)