You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

380 lines
20 KiB

  1. <!DOCTYPE html>
  2. <!--[if IE]><![endif]-->
  3. <html>
  4. <head>
  5. <meta charset="utf-8">
  6. <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  7. <title>Class GeneratedStore
  8. </title>
  9. <meta name="viewport" content="width=device-width">
  10. <meta name="title" content="Class GeneratedStore
  11. ">
  12. <meta name="generator" content="docfx 2.48.0.0">
  13. <link rel="shortcut icon" href="../favicon.ico">
  14. <link rel="stylesheet" href="../styles/docfx.vendor.css">
  15. <link rel="stylesheet" href="../styles/docfx.css">
  16. <link rel="stylesheet" href="../styles/main.css">
  17. <link rel="stylesheet" href="../styles/fix.css">
  18. <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
  19. <meta property="docfx:navrel" content="../toc.html">
  20. <meta property="docfx:tocrel" content="toc.html">
  21. <meta property="docfx:rel" content="../">
  22. <meta property="docfx:newtab" content="true">
  23. </head> <body data-spy="scroll" data-target="#affix" data-offset="120">
  24. <div id="wrapper">
  25. <header>
  26. <nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
  27. <div class="container">
  28. <div class="navbar-header">
  29. <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
  30. <span class="sr-only">Toggle navigation</span>
  31. <span class="icon-bar"></span>
  32. <span class="icon-bar"></span>
  33. <span class="icon-bar"></span>
  34. </button>
  35. <a class="navbar-brand" href="../index.html">
  36. <img id="logo" class="svg" src="../logo.svg" alt="">
  37. </a>
  38. </div>
  39. <div class="collapse navbar-collapse" id="navbar">
  40. <form class="navbar-form navbar-right" role="search" id="search">
  41. <div class="form-group">
  42. <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
  43. </div>
  44. </form>
  45. </div>
  46. </div>
  47. </nav>
  48. <div class="subnav navbar navbar-default">
  49. <div class="container hide-when-search" id="breadcrumb">
  50. <ul class="breadcrumb">
  51. <li></li>
  52. </ul>
  53. </div>
  54. </div>
  55. </header>
  56. <div class="container body-content">
  57. <div id="search-results">
  58. <div class="search-list"></div>
  59. <div class="sr-items">
  60. <p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
  61. </div>
  62. <ul id="pagination"></ul>
  63. </div>
  64. </div>
  65. <div role="main" class="container body-content hide-when-search">
  66. <div class="sidenav hide-when-search">
  67. <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
  68. <div class="sidetoggle collapse" id="sidetoggle">
  69. <div id="sidetoc"></div>
  70. </div>
  71. </div>
  72. <div class="article row grid-right">
  73. <div class="col-md-10">
  74. <article class="content wrap" id="_content" data-uid="IPA.Config.Stores.GeneratedStore">
  75. <h1 id="IPA_Config_Stores_GeneratedStore" data-uid="IPA.Config.Stores.GeneratedStore" class="text-break">Class GeneratedStore
  76. </h1>
  77. <div class="markdown level0 summary"><p>A class providing an extension for <a class="xref" href="IPA.Config.Config.html">Config</a> to make it easy to use generated
  78. config stores.</p>
  79. </div>
  80. <div class="markdown level0 conceptual"></div>
  81. <div class="inheritance">
  82. <h5>Inheritance</h5>
  83. <div class="level0"><a class="xref" href="https://docs.microsoft.com/dotnet/api/system.object">Object</a></div>
  84. <div class="level1"><span class="xref">GeneratedStore</span></div>
  85. </div>
  86. <div class="inheritedMembers">
  87. <h5>Inherited Members</h5>
  88. <div>
  89. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.object.tostring#System_Object_ToString">Object.ToString()</a>
  90. </div>
  91. <div>
  92. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.object.equals#System_Object_Equals_System_Object_">Object.Equals(Object)</a>
  93. </div>
  94. <div>
  95. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.object.equals#System_Object_Equals_System_Object_System_Object_">Object.Equals(Object, Object)</a>
  96. </div>
  97. <div>
  98. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.object.referenceequals#System_Object_ReferenceEquals_System_Object_System_Object_">Object.ReferenceEquals(Object, Object)</a>
  99. </div>
  100. <div>
  101. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.object.gethashcode#System_Object_GetHashCode">Object.GetHashCode()</a>
  102. </div>
  103. <div>
  104. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.object.gettype#System_Object_GetType">Object.GetType()</a>
  105. </div>
  106. <div>
  107. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.object.memberwiseclone#System_Object_MemberwiseClone">Object.MemberwiseClone()</a>
  108. </div>
  109. </div>
  110. <h6><strong>Namespace</strong>: <a class="xref" href="IPA.Config.Stores.html">IPA.Config.Stores</a></h6>
  111. <h6><strong>Assembly</strong>: IPA.Loader.dll</h6>
  112. <h5 id="IPA_Config_Stores_GeneratedStore_syntax">Syntax</h5>
  113. <div class="codewrapper">
  114. <pre><code class="lang-csharp hljs">public static class GeneratedStore</code></pre>
  115. </div>
  116. <h3 id="fields">Fields
  117. </h3>
  118. <span class="small pull-right mobile-hide">
  119. <span class="divider">|</span>
  120. <a href="https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded/new/master/docs/override/new?filename=IPA_Config_Stores_GeneratedStore_AssemblyVisibilityTarget.md&amp;value=---%0Auid%3A%20IPA.Config.Stores.GeneratedStore.AssemblyVisibilityTarget%0Asummary%3A%20'*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax'%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A">Improve this Doc</a>
  121. </span>
  122. <span class="small pull-right mobile-hide">
  123. <a href="https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded/blob/ade7e026f76e532d77191ea443a7e0be1d807633/IPA.Loader/Config/Stores/GeneratedStoreImpl.cs/#L37">View Source</a>
  124. </span>
  125. <h4 id="IPA_Config_Stores_GeneratedStore_AssemblyVisibilityTarget" data-uid="IPA.Config.Stores.GeneratedStore.AssemblyVisibilityTarget">AssemblyVisibilityTarget</h4>
  126. <div class="markdown level1 summary"><p>The name of the assembly that internals must be visible to to allow internal protection.</p>
  127. </div>
  128. <div class="markdown level1 conceptual"></div>
  129. <h5 class="decalaration">Declaration</h5>
  130. <div class="codewrapper">
  131. <pre><code class="lang-csharp hljs">public const string AssemblyVisibilityTarget = &quot;IPA.Config.Generated&quot;</code></pre>
  132. </div>
  133. <h5 class="fieldValue">Field Value</h5>
  134. <table class="table table-bordered table-striped table-condensed">
  135. <thead>
  136. <tr>
  137. <th>Type</th>
  138. <th>Description</th>
  139. </tr>
  140. </thead>
  141. <tbody>
  142. <tr>
  143. <td><a class="xref" href="https://docs.microsoft.com/dotnet/api/system.string">String</a></td>
  144. <td></td>
  145. </tr>
  146. </tbody>
  147. </table>
  148. <h3 id="methods">Methods
  149. </h3>
  150. <span class="small pull-right mobile-hide">
  151. <span class="divider">|</span>
  152. <a href="https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded/new/master/docs/override/new?filename=IPA_Config_Stores_GeneratedStore_Create__1.md&amp;value=---%0Auid%3A%20IPA.Config.Stores.GeneratedStore.Create%60%601%0Asummary%3A%20'*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax'%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A">Improve this Doc</a>
  153. </span>
  154. <span class="small pull-right mobile-hide">
  155. <a href="https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded/blob/ade7e026f76e532d77191ea443a7e0be1d807633/IPA.Loader/Config/Stores/GeneratedStoreImpl.cs/#L119">View Source</a>
  156. </span>
  157. <a id="IPA_Config_Stores_GeneratedStore_Create_" data-uid="IPA.Config.Stores.GeneratedStore.Create*"></a>
  158. <h4 id="IPA_Config_Stores_GeneratedStore_Create__1" data-uid="IPA.Config.Stores.GeneratedStore.Create``1">Create&lt;T&gt;()</h4>
  159. <div class="markdown level1 summary"><p>Creates a generated store outside of the context of the config system.</p>
  160. </div>
  161. <div class="markdown level1 conceptual"></div>
  162. <h5 class="decalaration">Declaration</h5>
  163. <div class="codewrapper">
  164. <pre><code class="lang-csharp hljs">public static T Create&lt;T&gt;()
  165. where T : class</code></pre>
  166. </div>
  167. <h5 class="returns">Returns</h5>
  168. <table class="table table-bordered table-striped table-condensed">
  169. <thead>
  170. <tr>
  171. <th>Type</th>
  172. <th>Description</th>
  173. </tr>
  174. </thead>
  175. <tbody>
  176. <tr>
  177. <td><span class="xref">T</span></td>
  178. <td><p>a generated instance of <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> implementing functionality described by <a class="xref" href="IPA.Config.Stores.GeneratedStore.html#IPA_Config_Stores_GeneratedStore_Generated__1_IPA_Config_Config_System_Boolean_">Generated&lt;T&gt;(Config, Boolean)</a></p>
  179. </td>
  180. </tr>
  181. </tbody>
  182. </table>
  183. <h5 class="typeParameters">Type Parameters</h5>
  184. <table class="table table-bordered table-striped table-condensed">
  185. <thead>
  186. <tr>
  187. <th>Name</th>
  188. <th>Description</th>
  189. </tr>
  190. </thead>
  191. <tbody>
  192. <tr>
  193. <td><span class="parametername">T</span></td>
  194. <td><p>the type to wrap</p>
  195. </td>
  196. </tr>
  197. </tbody>
  198. </table>
  199. <h5 id="IPA_Config_Stores_GeneratedStore_Create__1_remarks">Remarks</h5>
  200. <div class="markdown level1 remarks"><p>See <a class="xref" href="IPA.Config.Stores.GeneratedStore.html#IPA_Config_Stores_GeneratedStore_Generated__1_IPA_Config_Config_System_Boolean_">Generated&lt;T&gt;(Config, Boolean)</a> for more information about how it behaves.</p>
  201. </div>
  202. <h5 id="IPA_Config_Stores_GeneratedStore_Create__1_seealso">See Also</h5>
  203. <div class="seealso">
  204. <div><a class="xref" href="IPA.Config.Stores.GeneratedStore.html#IPA_Config_Stores_GeneratedStore_Generated__1_IPA_Config_Config_System_Boolean_">Generated&lt;T&gt;(Config, Boolean)</a></div>
  205. </div>
  206. <span class="small pull-right mobile-hide">
  207. <span class="divider">|</span>
  208. <a href="https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded/new/master/docs/override/new?filename=IPA_Config_Stores_GeneratedStore_Generated__1_IPA_Config_Config_System_Boolean_.md&amp;value=---%0Auid%3A%20IPA.Config.Stores.GeneratedStore.Generated%60%601(IPA.Config.Config%2CSystem.Boolean)%0Asummary%3A%20'*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax'%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A">Improve this Doc</a>
  209. </span>
  210. <span class="small pull-right mobile-hide">
  211. <a href="https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded/blob/ade7e026f76e532d77191ea443a7e0be1d807633/IPA.Loader/Config/Stores/GeneratedStoreImpl.cs/#L98">View Source</a>
  212. </span>
  213. <a id="IPA_Config_Stores_GeneratedStore_Generated_" data-uid="IPA.Config.Stores.GeneratedStore.Generated*"></a>
  214. <h4 id="IPA_Config_Stores_GeneratedStore_Generated__1_IPA_Config_Config_System_Boolean_" data-uid="IPA.Config.Stores.GeneratedStore.Generated``1(IPA.Config.Config,System.Boolean)">Generated&lt;T&gt;(Config, Boolean)</h4>
  215. <div class="markdown level1 summary"><p>Creates a generated <a class="xref" href="IPA.Config.IConfigStore.html">IConfigStore</a> of type <code data-dev-comment-type="typeparamref" class="typeparamref">T</code>, registers it to
  216. the <a class="xref" href="IPA.Config.Config.html">Config</a> object, and returns it. This also forces a synchronous config load via
  217. <a class="xref" href="IPA.Config.Config.html#IPA_Config_Config_LoadSync">LoadSync()</a> if <code data-dev-comment-type="paramref" class="paramref">loadSync</code> is <span class="xref">true</span>.</p>
  218. </div>
  219. <div class="markdown level1 conceptual"></div>
  220. <h5 class="decalaration">Declaration</h5>
  221. <div class="codewrapper">
  222. <pre><code class="lang-csharp hljs">public static T Generated&lt;T&gt;(this Config cfg, bool loadSync = true)
  223. where T : class</code></pre>
  224. </div>
  225. <h5 class="parameters">Parameters</h5>
  226. <table class="table table-bordered table-striped table-condensed">
  227. <thead>
  228. <tr>
  229. <th>Type</th>
  230. <th>Name</th>
  231. <th>Description</th>
  232. </tr>
  233. </thead>
  234. <tbody>
  235. <tr>
  236. <td><a class="xref" href="IPA.Config.Config.html">Config</a></td>
  237. <td><span class="parametername">cfg</span></td>
  238. <td><p>the <a class="xref" href="IPA.Config.Config.html">Config</a> to register to</p>
  239. </td>
  240. </tr>
  241. <tr>
  242. <td><a class="xref" href="https://docs.microsoft.com/dotnet/api/system.boolean">Boolean</a></td>
  243. <td><span class="parametername">loadSync</span></td>
  244. <td><p>whether to synchronously load the content, or trigger an async load</p>
  245. </td>
  246. </tr>
  247. </tbody>
  248. </table>
  249. <h5 class="returns">Returns</h5>
  250. <table class="table table-bordered table-striped table-condensed">
  251. <thead>
  252. <tr>
  253. <th>Type</th>
  254. <th>Description</th>
  255. </tr>
  256. </thead>
  257. <tbody>
  258. <tr>
  259. <td><span class="xref">T</span></td>
  260. <td><p>a generated instance of <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> as a special <a class="xref" href="IPA.Config.IConfigStore.html">IConfigStore</a></p>
  261. </td>
  262. </tr>
  263. </tbody>
  264. </table>
  265. <h5 class="typeParameters">Type Parameters</h5>
  266. <table class="table table-bordered table-striped table-condensed">
  267. <thead>
  268. <tr>
  269. <th>Name</th>
  270. <th>Description</th>
  271. </tr>
  272. </thead>
  273. <tbody>
  274. <tr>
  275. <td><span class="parametername">T</span></td>
  276. <td><p>the type to wrap</p>
  277. </td>
  278. </tr>
  279. </tbody>
  280. </table>
  281. <h5 id="IPA_Config_Stores_GeneratedStore_Generated__1_IPA_Config_Config_System_Boolean__remarks">Remarks</h5>
  282. <div class="markdown level1 remarks"><p>
  283. <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> must be a public non-<span class="xref">sealed</span> class.
  284. It can also be internal, but in that case, then your assembly must have the following attribute
  285. to allow the generated code to reference it.
  286. <pre><code>[assembly: InternalsVisibleTo(IPA.Config.Stores.GeneratedStore.AssemblyVisibilityTarget)]</code></pre>
  287. </p>
  288. <p>
  289. Only fields and properties that are public or protected will be considered, and only properties
  290. where both the getter and setter are public or protected are considered. Any fields or properties
  291. with an <a class="xref" href="IPA.Config.Stores.Attributes.IgnoreAttribute.html">IgnoreAttribute</a> applied to them are also ignored. Having properties be <span class="xref">virtual</span> is not strictly
  292. necessary, however it allows the generated type to keep track of changes and lock around them so that the config will auto-save.
  293. </p>
  294. <p>
  295. All of the attributes in the <a class="xref" href="IPA.Config.Stores.Attributes.html">IPA.Config.Stores.Attributes</a> namespace are handled as described by them.
  296. </p>
  297. <p>
  298. If the <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> declares a public or protected, <span class="xref">virtual</span>
  299. method <code>Changed()</code>, then that method may be called to artificially signal to the runtime that the content of the object
  300. has changed. That method will also be called after the write locks are released when a property is set anywhere in the owning
  301. tree. This will only be called on the outermost generated object of the config structure, even if the change being signaled
  302. is somewhere deep into the tree. TODO: is this a good idea?
  303. </p>
  304. <p>
  305. Similarly, <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> can declare a public or protected, <span class="xref">virtual</span>
  306. method <code>OnReload()</code>, which will be called on the filesystem reader thread after the object has been repopulated with new data
  307. values. It will be called <em>after</em> the write lock for this object is released. This will only be called on the outermost generated
  308. object of the config structure.
  309. </p>
  310. <p>
  311. Similarly, <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> can declare a public or protected, <span class="xref">virtual</span>
  312. method <code>CopyFrom(ConfigType)</code> (the first parameter is the type it is defined on), which may be called to copy the properties from
  313. another object of its type easily, and more importantly, as only one change. Its body will be executed after the values have been copied.
  314. </p>
  315. <p>
  316. Similarly, <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> can declare a public or protected, <span class="xref">virtual</span>
  317. method <code>ChangeTransaction()</code> returning <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.idisposable">IDisposable</a>, which may be called to get an object representing a transactional
  318. change. This may be used to change a lot of properties at once without triggering a save multiple times. Ideally, this is used in a
  319. <span class="xref">langword_csharp_using</span> block or declaration. The <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.idisposable">IDisposable</a> returned from your implementation will have its
  320. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.idisposable.dispose#System_IDisposable_Dispose">Dispose()</a> called <em>after</em> <code>Changed()</code> is called, but <em>before</em> the write lock is released.
  321. Unless you have a very good reason to use the nested <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.idisposable">IDisposable</a>, avoid it.
  322. </p>
  323. <p>
  324. If <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> is marked with <a class="xref" href="IPA.Config.Stores.Attributes.NotifyPropertyChangesAttribute.html">NotifyPropertyChangesAttribute</a>, the resulting object will implement
  325. <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.componentmodel.inotifypropertychanged">INotifyPropertyChanged</a>. Similarly, if <code data-dev-comment-type="typeparamref" class="typeparamref">T</code> implements <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.componentmodel.inotifypropertychanged">INotifyPropertyChanged</a>,
  326. the resulting object will implement it and notify it too.
  327. </p>
  328. </div>
  329. </article>
  330. </div>
  331. <div class="hidden-sm col-md-2" role="complementary">
  332. <div class="sideaffix">
  333. <div class="contribution">
  334. <ul class="nav">
  335. <li>
  336. <a href="https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded/new/master/docs/override/new?filename=IPA_Config_Stores_GeneratedStore.md&amp;value=---%0Auid%3A%20IPA.Config.Stores.GeneratedStore%0Asummary%3A%20'*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax'%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A" class="contribution-link">Improve this Doc</a>
  337. </li>
  338. <li>
  339. <a href="https://github.com/beat-saber-modding-group/BeatSaber-IPA-Reloaded/blob/ade7e026f76e532d77191ea443a7e0be1d807633/IPA.Loader/Config/Stores/GeneratedStoreImpl.cs/#L32" class="contribution-link">View Source</a>
  340. </li>
  341. </ul>
  342. </div>
  343. <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
  344. <!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
  345. </nav>
  346. </div>
  347. </div>
  348. </div>
  349. </div>
  350. <footer>
  351. <div class="grad-bottom"></div>
  352. <div class="footer">
  353. <div class="container">
  354. <span class="pull-right">
  355. <a href="#top">Back to top</a>
  356. </span>
  357. <span>Generated by <strong>DocFX</strong></span>
  358. </div>
  359. </div>
  360. </footer>
  361. </div>
  362. <script type="text/javascript" src="../styles/docfx.vendor.js"></script>
  363. <script type="text/javascript" src="../styles/docfx.js"></script>
  364. <script type="text/javascript" src="../styles/main.js"></script>
  365. </body>
  366. </html>