Skip to content

Commit

Permalink
Added a bunch of Notes and Alerts
Browse files Browse the repository at this point in the history
  • Loading branch information
@jsmorley
jsmorley committed Jan 20, 2025
1 parent a359de4 commit fe10ffe
Show file tree
Hide file tree
Showing 17 changed files with 133 additions and 67 deletions.
5 changes: 4 additions & 1 deletion source/manual/bangs.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@
<li><a href="#Deprecated"><em>Deprecated bangs</a></em></li>
</ul>

<p><b>Note:</b> Many bangs have a <code>Config</code> parameter. Unless otherwise specified, valid values are the <a href="!skins/#Config">config name</a> of a currently loaded skin to be acted upon or <code>*</code> (asterisk) to act on all currently loaded skins. When optional and not supplied, the parameter defaults to the current config. If executing a bang with a "config" parameter from the Windows command line, the parameter is always required.</p>
<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>Many bangs have a <code>Config</code> parameter. Unless otherwise specified, valid values are the <a href="!skins/#Config">config name</a> of a currently loaded skin to be acted upon or <code>*</code> (asterisk) to act on all currently loaded skins. When optional and not supplied, the parameter defaults to the current config. If executing a bang with a "config" parameter from the Windows command line, the parameter is always required.</p>
</div>

<h3>Command Line Arguments</h3>

Expand Down
5 changes: 4 additions & 1 deletion source/manual/formulas.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,10 @@

<p>Mathematical formulas must be entirely enclosed in (parentheses) to alert Rainmeter that it is a formula, unless they are being used in the <a href="!measures/calc/#Formula">Formula</a> option of a <a href="!measures/calc/">Calc</a> measure or in a <a href="!measures/general-options/ifconditions/">IfCondition</a> option, where the function is always assumed to be a formula, and the enclosing parentheses are optional.</p>

<p><b>Note:</b> While [Measures], [SectionVariables:] and #Variables# can be used in a formula, all the components of a formula must be numeric, using only numbers, operators, functions and constants. Using .5 or .25 in a formula will cause an error. It must be 0.5 or 0.25.</p>
<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>While [Measures], [SectionVariables:] and #Variables# can be used in a formula, all the components of a formula must be numeric, using only numbers, operators, functions and constants. Using .5 or .25 in a formula will cause an error. It must be 0.5 or 0.25.</p>
</div>

<h2 id="Formulas">Formula Syntax</h2>

Expand Down
57 changes: 32 additions & 25 deletions source/manual/lua-scripting/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,10 @@ <h2 id="Initialize">Initialize</h2>
end
```

<p><b>Note:</b> While a dofile you call can be anywhere on your system, be aware that if you do not put the dofile .lua file somewhere in the path to the current config, you won't be able to distribute it with your skin as a .rmskin package. A .rmskin package can only distribute the contents of a single root config folder.</p>
<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>While a dofile you call can be anywhere on your system, be aware that if you do not put the dofile .lua file somewhere in the path to the current config, you won't be able to distribute it with your skin as a .rmskin package. A .rmskin package can only distribute the contents of a single root config folder.</p>
</div>

<h2 id="Update">Update</h2>

Expand Down Expand Up @@ -372,27 +375,31 @@ <h3 id="MeterObject">Meter object</h3>
</dd>
</dl>

<h2 id="Restrictions">Restrictions</h2>

<p>The following Lua features are not available in Rainmeter at this time:</p>

<ul>
<li>External compiled libraries, such as <a href="https://github.com/Lua-cURL">Lua-cURL</a>.</li>
<li>The <code><a href="https://www.lua.org/manual/5.1/manual.html#pdf-require">require</a></code>, <code>os.exit</code>, <code>os.setlocale</code>, <code>io.popen</code>, and <code>collectgarbage</code> functions.</li>
</ul>

<h3 id="Deprecated">Deprecated Features</h3>

<p>The following Rainmeter-specific features have been deprecated and should not be used. They are still supported, but may be removed in future versions.</p>

<ul>
<li><p><code>PROPERTIES = { ... }</code><br>
This table was previously used to read options on the script measure. Instead, use:<br>
<code>SELF:GetOption('MyOption')</code> or <code>SELF:GetNumberOption('MyOption')</code></p></li>
<li><p><code>MyMeter:SetText('...')</code><br>
This function was used to change a <a href="!meters/string/">string meter's</a> text. Instead, use:<br>
<code>SKIN:Bang('!SetOption', 'MeterName', 'Text', '...')</code></p></li>
<li><p><code>function GetStringValue()</code><br>
This function was used to set the script measure's value. Instead, use:<br>
<code>function Update() ... return ... end</code></p></li>
</ul>
<br>
<div class="alert alert-warning alert-tight" role="alert">
<h2 class="alert-heading h5" id="Restrictions"><i class="fa-solid fa-bomb"></i> Alert: Restrictions</h2>
<p>The following Lua features are not available in Rainmeter at this time:</p>

<ul>
<li>External compiled libraries, such as <a href="https://github.com/Lua-cURL">Lua-cURL</a>.</li>
<li>The <code><a href="https://www.lua.org/manual/5.1/manual.html#pdf-require">require</a></code>, <code>os.exit</code>, <code>os.setlocale</code>, <code>io.popen</code>, and <code>collectgarbage</code> functions.</li>
</ul>
</div>

<div class="alert alert-warning alert-tight" role="alert">
<h2 class="alert-heading h5" id="Deprecated"><i class="fa-solid fa-bomb"></i> Alert: Deprecated Features</h2>

<p>The following Rainmeter-specific features have been deprecated and should not be used. They are still supported, but may be removed in future versions.</p>

<ul>
<li><p><code>PROPERTIES = { ... }</code><br>
This table was previously used to read options on the script measure. Instead, use:<br>
<code>SELF:GetOption('MyOption')</code> or <code>SELF:GetNumberOption('MyOption')</code></p></li>
<li><p><code>MyMeter:SetText('...')</code><br>
This function was used to change a <a href="!meters/string/">string meter's</a> text. Instead, use:<br>
<code>SKIN:Bang('!SetOption', 'MeterName', 'Text', '...')</code></p></li>
<li><p><code>function GetStringValue()</code><br>
This function was used to set the script measure's value. Instead, use:<br>
<code>function Update() ... return ... end</code></p></li>
</ul>
</div>
18 changes: 10 additions & 8 deletions source/manual/lua-scripting/inline-lua.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ <h2 id="NestedVariables">Nested Variables in Rainmeter</h2>

<p>In general, anything useful that you do with this functionality is going to entail passing variables of one form or another to the Lua function, and just always using the Nested Variables syntax with any inline Lua will save a lot of frustration and confusion.</p>

<h2 id="Notes">Inline Lua Notes</h2>
<h2 id="Guidelines">Inline Lua Guidelines</h2>

<p><code>DynamicVariables=1</code> MUST be set on any measures or meters where inlineLua is used.</p>

Expand All @@ -82,19 +82,21 @@ <h2 id="Notes">Inline Lua Notes</h2>

<p>The Lua <code>nil</code> data type, indicating that a value doesn't exist, may be used in a parameter, but not as a return type to Rainmeter. In some cases, the <code>boolean</code> value of <code>false</code> may be used to indicate NOT, in place of <code>nil</code>.</p>

<p><b>Important Final Note</b></p>
<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="FinalNote"><i class="fa-solid fa-thumbtack"></i> Note: Important Final Note</h2>

<p>Any inline Lua used in options in measures or meters are resolved when the skin is first read and created on load or refresh. This is the same for all [SectionVariables] in Rainmeter.</p>
<p>Any inline Lua used in options in measures or meters are resolved when the skin is first read and created on load or refresh. This is the same for all [SectionVariables] in Rainmeter.</p>

<p>During this "initialization" phase of the skin, before the first actual "update" of the skin, the value of all measures will be set to an initial numeric value of <code>0</code>, and if applicable, a string value of "". This will normally be transparent, as before any "result" of the inline Lua is "used", before the skin is "drawn" for the first time, all measures and meters will have been updated and the correct and expected results will happen. However some care should be taken to ensure that a one-time initial value of 0 being passed to your Lua doesn't cause any logic or formula errors.</p>
<p>During this "initialization" phase of the skin, before the first actual "update" of the skin, the value of all measures will be set to an initial numeric value of <code>0</code>, and if applicable, a string value of "". This will normally be transparent, as before any "result" of the inline Lua is "used", before the skin is "drawn" for the first time, all measures and meters will have been updated and the correct and expected results will happen. However some care should be taken to ensure that a one-time initial value of 0 being passed to your Lua doesn't cause any logic or formula errors.</p>

<p>In addition, the Initialize() function in a Lua script will only be executed during the first update cycle of the skin. This means that if you are defining and setting some default values for variables in Initialize() in your Lua, those values will not be visible before the first skin update, which will be after any inline Lua in measures or meters are first run. This may cause "nil" values to be seen and result in errors.</p>
<p>In addition, the Initialize() function in a Lua script will only be executed during the first update cycle of the skin. This means that if you are defining and setting some default values for variables in Initialize() in your Lua, those values will not be visible before the first skin update, which will be after any inline Lua in measures or meters are first run. This may cause "nil" values to be seen and result in errors.</p>

<p>In many cases, this can be resolved by defining and setting these variables in the global scope of the Lua script, outside of any function block. This global scope will be executed during the initialization phase of the skin, and the values will be immediately available. The global scope of Lua has not been much needed before in Rainmeter, but with inline Lua it can be valuable.</p>
<p>In many cases, this can be resolved by defining and setting these variables in the global scope of the Lua script, outside of any function block. This global scope will be executed during the initialization phase of the skin, and the values will be immediately available. The global scope of Lua has not been much needed before in Rainmeter, but with inline Lua it can be valuable.</p>

<p>Again, in both cases, this all will generally be transparent and of no consequence, since by the time the skin is first drawn, at the end of the first skin update, all will be well. This issue should be kept in mind however, if you find you are getting single initial error messages in the log.</p>
<p>Again, in both cases, this all will generally be transparent and of no consequence, since by the time the skin is first drawn, at the end of the first skin update, all will be well. This issue should be kept in mind however, if you find you are getting single initial error messages in the log.</p>

<p>Inline Lua used in bangs in actions in the skin will only be executed when the action is executed, and so will not display this behavior. They simply can't be executed before the first update of the skin.</p>
<p>Inline Lua used in bangs in actions in the skin will only be executed when the action is executed, and so will not display this behavior. They simply can't be executed before the first update of the skin.</p>
</div>

<h2 id="Examples">Examples</h2>

Expand Down
11 changes: 9 additions & 2 deletions source/manual/mouse-actions.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,18 @@ <h2>Usage</h2>
<li>On any <a href="!meters/">meter</a>. The target area detected by the mouse will be any non-transparent areas of the meter, or any part of the meter which has a non-transparent meter or skin background behind it.</li>
<li>In the <a href="!skins/rainmeter-section/">[Rainmeter]</a> section of the skin. The target area detected by the mouse will be any non-transparent areas of the skin.</li>
</ul>
<p><b>Note:</b> Actions defined for a meter will override actions defined in the <code>[Rainmeter]</code> section.</p>

<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>Actions defined for a meter will override actions defined in the <code>[Rainmeter]</code> section.</p>
</div>

<h2 id="MouseClickOptions">Mouse Click Options</h2>
<p><b>Note:</b> Mouse Click Options may be overridden by holding down <b>CTRL</b> while clicking.</p>
<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>Mouse Click Options may be overridden by holding down <b>CTRL</b> while clicking.</p>
</div>

<dl>
<dt id="LeftMouseDownAction"><code>LeftMouseDownAction</code></dt>
<dd>
Expand Down
24 changes: 18 additions & 6 deletions source/manual/plugins/audiolevel.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@

<p><em>The plugin monitors the amplitude of the post-mixer signal at a Windows audio endpoint. (i.e. sound card speaker output, USB audio interface, headphone port, microphone input) It does this by creating a <a href="https://docs.microsoft.com/windows/win32/coreaudio/wasapi">WASAPI</a> capture client in <a href="https://docs.microsoft.com/windows/win32/coreaudio/loopback-recording">loopback mode</a>. The capture client streams audio data to the plugin where it can be filtered and measured. The resulting volume level is returned by the plugin for use in Rainmeter measures and meters.</em></p>

<p><b>Note:</b> Creating meters that display sound levels in real-time will require that the skin be set with a fairly low <a href="!skins/rainmeter-section/#Update">Update</a> rate in the [Rainmeter] section of the skin. While the plugin is quite resource friendly and efficient, some care should be taken when deciding how much analysis should be done on the signal, and it is recommended that this plugin be used in a skin dedicated to it, and not as a part of a larger skin where the low update rate may cause higher CPU usage.</p>
<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>Creating meters that display sound levels in real-time will require that the skin be set with a fairly low <a href="!skins/rainmeter-section/#Update">Update</a> rate in the [Rainmeter] section of the skin. While the plugin is quite resource friendly and efficient, some care should be taken when deciding how much analysis should be done on the signal, and it is recommended that this plugin be used in a skin dedicated to it, and not as a part of a larger skin where the low update rate may cause higher CPU usage.</p>
</div>

<h2>Usage</h2>

Expand Down Expand Up @@ -40,7 +43,10 @@ <h2>Usage</h2>
Type=RMS
```

<p><b>Note:</b> Only the <code>Type</code>, <code>Channel</code>, <code>FFTIdx</code> and <code>BandIdx</code> child measure options can be changed dynamically with !SetVariable or !SetOption. Parent measure options may not be changed dynamically.</p>
<div class="alert alert-warning alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeAlert"><i class="fa-solid fa-bomb"></i> Alert:</h2>
<p>Only the <code>Type</code>, <code>Channel</code>, <code>FFTIdx</code> and <code>BandIdx</code> child measure options can be changed dynamically with !SetVariable or !SetOption. Parent measure options may not be changed dynamically.</p>
</div>

<h2>Options</h2>

Expand Down Expand Up @@ -84,8 +90,11 @@ <h3 id="RMSOptions">RMS options</h3>

<p>This is the most meaningful way of measuring audio volume levels in a skin.</p>

<p><b>Note:</b> To disable all RMS filtering, set both <a href="#RMSAttack">RMSAttack</a> and <a href="#RMSDecay">RMSDecay</a> to <code>0</code>, and <a href="#RMSGain">RMSGain</a> as the default <code>1.0</code>.</p>

<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>To disable all RMS filtering, set both <a href="#RMSAttack">RMSAttack</a> and <a href="#RMSDecay">RMSDecay</a> to <code>0</code>, and <a href="#RMSGain">RMSGain</a> as the default <code>1.0</code>.</p>
</div>

<p>The following parent options are used in combination with child measures having the <code>Type=RMS</code> option set.</p>

<dt id="RMSAttack"><code>RMSAttack</code> <small>Default: <code>300</code></small></dt>
Expand All @@ -107,8 +116,11 @@ <h3 id="PeakOptions">Peak options</h3>

<p>Peak options are similar to <a href="#RMSOptions">RMS options</a>, but measure the peak (high) values rather than squaring to obtain an average over a period of time.</p>

<p><b>Note:</b> To disable all Peak filtering, set both <a href="#PeakAttack">PeakAttack</a> and <a href="#PeakDecay">PeakDecay</a> to <code>0</code>, and <a href="#PeakGain">PeakGain</a> as the default <code>1.0</code>.</p>

<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>To disable all Peak filtering, set both <a href="#PeakAttack">PeakAttack</a> and <a href="#PeakDecay">PeakDecay</a> to <code>0</code>, and <a href="#PeakGain">PeakGain</a> as the default <code>1.0</code>.</p>
</div>

<p>The following parent options are used in combination with child measures having the <code>Type=Peak</code> option set.</p>

<dt id="PeakAttack"><code>PeakAttack</code> <small>Default: <code>50</code></small></dt>
Expand Down
5 changes: 4 additions & 1 deletion source/manual/plugins/coretemp.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@
---
<p><code>Plugin=CoreTemp</code> retrieves infromation from the <a href="https://www.alcpu.com/CoreTemp/">CoreTemp</a> application. The latest CoreTemp application <b>must</b> be running in the background.</p>

<p><b>Note:</b> If the value of the measure is to be used in a meter which requires a <a href="!measures/#Percentage">percentage</a>, then appropriate <a href="!measures/general-options/#MinValue">MinValue</a> and/or <a href="!measures/general-options/#MaxValue">MaxValue</a> options must be added to the measure.</p>
<div class="alert alert-info alert-tight" role="alert">
<h2 class="alert-heading h5" id="SomeNote"><i class="fa-solid fa-thumbtack"></i> Note:</h2>
<p>If the value of the measure is to be used in a meter which requires a <a href="!measures/#Percentage">percentage</a>, then appropriate <a href="!measures/general-options/#MinValue">MinValue</a> and/or <a href="!measures/general-options/#MaxValue">MaxValue</a> options must be added to the measure.</p>
</div>

<h2>Options</h2>
<dl>
Expand Down
Loading

0 comments on commit fe10ffe

Please sign in to comment.