Skip to content

Commit 81f0953

Browse files
NSTechBytesNSTechBytes
committed
Updated Readme
1 parent b9d1314 commit 81f0953

File tree

1 file changed

+3
-344
lines changed

1 file changed

+3
-344
lines changed

‎README.md‎

Lines changed: 3 additions & 344 deletions
Original file line numberDiff line numberDiff line change
@@ -2,349 +2,8 @@
22

33
**InputTextX** is a [Rainmeter](https://www.rainmeter.net/) plugin that creates a customizable text input overlay. It allows users to capture text input on-the-fly and inject that text into Rainmeter commands with dynamic placeholder replacement. The plugin supports various input types, custom validation, styling options, and configurable actions for enter, escape, and dismissal events.
44

5-
---
65

7-
## Features
6+
# Documentation
87

9-
- **Customizable Appearance:**Configure dimensions, colors, fonts (including custom font files), and borders.
10-
- **Input Types & Validation:**Supports `String`, `Integer`, `Float`, `Letters`, `Alphanumeric`, `Hexadecimal`, `Email`, and a custom mode with allowed characters.
11-
- **Action Handling:**Execute custom Rainmeter commands on key events:
12-
13-
- **OnEnterAction:** Triggered when the user submits the input.
14-
- **OnESCAction:** Triggered when the user presses the Escape key.
15-
- **OnDismissAction:** Triggered when the input overlay loses focus.
16-
- **Dynamic Placeholder Replacement:**Replace the placeholder `$UserInput$` with the current text input before executing commands.`<span style="color: red;"><strong>`Note:`</strong>` Special characters (e.g., double quotes) are automatically escaped to ensure valid command syntax.
17-
- **Logging:**
18-
Detailed logging can be enabled for debugging. All logs are printed only when the `Logging` key is set to `1`.
19-
20-
---
21-
22-
## Getting Started
23-
24-
### Installation
25-
26-
1. **Build the Plugin:**Compile the C# code into a DLL (e.g., using Visual Studio) and place it into your Rainmeter plugins folder.
27-
2. **Add the Plugin to Your Skin:**Create a Rainmeter skin and add the following measure:
28-
29-
```ini
30-
[MeasureInput]
31-
Measure=Plugin
32-
Plugin=InputTextX.dll
33-
```
34-
3. **Configure the Plugin:**
35-
Set the desired configuration keys (see below) in your Rainmeter skin.
36-
Example:
37-
38-
```ini
39-
[MeasureInput]
40-
Measure=Plugin
41-
Plugin=InputTextX.dll
42-
W=300
43-
H=40
44-
SolidColor=255,255,255
45-
FontColor=0,0,0
46-
FontSize=12
47-
Align=Center
48-
Password=0
49-
FontStyle=Normal
50-
FontFace=Segoe UI
51-
Multiline=0
52-
AllowScroll=0
53-
InputLimit=0
54-
DefaultValue=Enter text here...
55-
InputType=String
56-
AllowedChars=
57-
OnDismissAction=[!Log "Dismissed: $UserInput$"]
58-
OnEnterAction=[!Log "Submitted: $UserInput$"]
59-
OnESCAction=[!Log "Cancelled: $UserInput$"]
60-
InValidAction=[!Log "Invalid input"]
61-
X=20
62-
Y=20
63-
AllowBorder=1
64-
BorderColor=0,0,0
65-
BorderThickness=2
66-
MinValue=-999999
67-
MaxValue=999999
68-
TopMost=1
69-
Logging=1
70-
```
71-
72-
---
73-
74-
## Configuration Keys
75-
76-
The following table lists each configuration key along with its description, type, and default value.
77-
78-
<table>
79-
<tr>
80-
<th>Key</th>
81-
<th>Description</th>
82-
<th>Type</th>
83-
<th>Default</th>
84-
</tr>
85-
<tr>
86-
<td>W</td>
87-
<td>Width of the input overlay</td>
88-
<td>Integer</td>
89-
<td>300</td>
90-
</tr>
91-
<tr>
92-
<td>H</td>
93-
<td>Height of the input overlay</td>
94-
<td>Integer</td>
95-
<td>40</td>
96-
</tr>
97-
<tr>
98-
<td>SolidColor</td>
99-
<td>Background color in R,G,B format</td>
100-
<td>Color</td>
101-
<td>255,255,255</td>
102-
</tr>
103-
<tr>
104-
<td>FontColor</td>
105-
<td>Text color in R,G,B format</td>
106-
<td>Color</td>
107-
<td>0,0,0</td>
108-
</tr>
109-
<tr>
110-
<td>FontSize</td>
111-
<td>Font size for text input</td>
112-
<td>Float</td>
113-
<td>12</td>
114-
</tr>
115-
<tr>
116-
<td>Align</td>
117-
<td>Text alignment (`Left`, `Center`, or `Right`)</td>
118-
<td>String</td>
119-
<td>Center</td>
120-
</tr>
121-
<tr>
122-
<td>Password</td>
123-
<td>If set to 1, input will be masked</td>
124-
<td>Integer</td>
125-
<td>0</td>
126-
</tr>
127-
<tr>
128-
<td>FontStyle</td>
129-
<td>Font style (`Normal`, `Bold`, `Italic`, or `BoldItalic`)</td>
130-
<td>String</td>
131-
<td>Normal</td>
132-
</tr>
133-
<tr>
134-
<td>FontFace</td>
135-
<td>Name or path to the font file</td>
136-
<td>String</td>
137-
<td>Segoe UI</td>
138-
</tr>
139-
<tr>
140-
<td>Multiline</td>
141-
<td>If set to 1, allows multiline input</td>
142-
<td>Integer</td>
143-
<td>0</td>
144-
</tr>
145-
<tr>
146-
<td>AllowScroll</td>
147-
<td>If set to 1, enables vertical scroll for multiline input</td>
148-
<td>Integer</td>
149-
<td>0</td>
150-
</tr>
151-
<tr>
152-
<td>InputLimit</td>
153-
<td>Maximum number of characters allowed</td>
154-
<td>Integer</td>
155-
<td>0 (no limit)</td>
156-
</tr>
157-
<tr>
158-
<td>DefaultValue</td>
159-
<td>Initial text in the input box</td>
160-
<td>String</td>
161-
<td>Empty</td>
162-
</tr>
163-
<tr>
164-
<td>InputType</td>
165-
<td>Type of allowed input (see list below)</td>
166-
<td>String</td>
167-
<td>String</td>
168-
</tr>
169-
<tr>
170-
<td>AllowedChars</td>
171-
<td>For InputType=Custom, characters allowed</td>
172-
<td>String</td>
173-
<td>Empty</td>
174-
</tr>
175-
<tr>
176-
<td>OnDismissAction</td>
177-
<td>Rainmeter command executed when the input overlay loses focus</td>
178-
<td>String</td>
179-
<td>Empty</td>
180-
</tr>
181-
<tr>
182-
<td>OnEnterAction</td>
183-
<td>Rainmeter command executed on pressing Enter</td>
184-
<td>String</td>
185-
<td>Empty</td>
186-
</tr>
187-
<tr>
188-
<td>OnESCAction</td>
189-
<td>Rainmeter command executed on pressing Escape</td>
190-
<td>String</td>
191-
<td>Empty</td>
192-
</tr>
193-
<tr>
194-
<td>InValidAction</td>
195-
<td>Command executed when invalid input is detected</td>
196-
<td>String</td>
197-
<td>Empty</td>
198-
</tr>
199-
<tr>
200-
<td>X</td>
201-
<td>Horizontal offset for the overlay relative to the skin</td>
202-
<td>Integer</td>
203-
<td>20</td>
204-
</tr>
205-
<tr>
206-
<td>Y</td>
207-
<td>Vertical offset for the overlay relative to the skin</td>
208-
<td>Integer</td>
209-
<td>20</td>
210-
</tr>
211-
<tr>
212-
<td>AllowBorder</td>
213-
<td>If set to 1, a border will be drawn around the input box</td>
214-
<td>Integer</td>
215-
<td>0</td>
216-
</tr>
217-
<tr>
218-
<td>BorderColor</td>
219-
<td>Border color in R,G,B format</td>
220-
<td>Color</td>
221-
<td>0,0,0</td>
222-
</tr>
223-
<tr>
224-
<td>BorderThickness</td>
225-
<td>Thickness of the border in pixels</td>
226-
<td>Integer</td>
227-
<td>2</td>
228-
</tr>
229-
<tr>
230-
<td>MinValue</td>
231-
<td>Minimum numeric value (for Integer/Float types)</td>
232-
<td>Double</td>
233-
<td>double.MinValue</td>
234-
</tr>
235-
<tr>
236-
<td>MaxValue</td>
237-
<td>Maximum numeric value (for Integer/Float types)</td>
238-
<td>Double</td>
239-
<td>double.MaxValue</td>
240-
</tr>
241-
<tr>
242-
<td>TopMost</td>
243-
<td>If set to 1, the overlay is displayed on top of other windows</td>
244-
<td>Integer</td>
245-
<td>1</td>
246-
</tr>
247-
<tr>
248-
<td>Logging</td>
249-
<td>If set to 1, detailed log messages will be printed to the Rainmeter log</td>
250-
<td>Integer</td>
251-
<td>0</td>
252-
</tr>
253-
</table>
254-
255-
---
256-
257-
## Input Types
258-
259-
The `InputType` key supports the following values:
260-
261-
- **String**: Accepts any text.
262-
- **Integer**: Accepts numeric digits and a leading minus sign.
263-
- **Float**: Accepts numeric digits, a decimal point, and a leading minus sign.
264-
- **Letters**: Accepts only alphabetical characters.
265-
- **Alphanumeric**: Accepts letters and digits.
266-
- **Hexadecimal**: Accepts digits and letters A-F (case insensitive).
267-
- **Email**: Accepts characters typically allowed in email addresses.
268-
- **Custom**: Only allows characters specified in the `AllowedChars` key.
269-
270-
---
271-
272-
## Usage Notes
273-
274-
> **Note:**
275-
> The plugin dynamically replaces the placeholder `$UserInput$` in action keys with the current input text. It also escapes special characters (such as double quotes) to ensure the resulting Rainmeter command is valid.
276-
277-
> **InputTextX** is incompatible with skins set to **Stay Topmost**, or **AlwaysOnTop=2**, as the conflict between the input field, which requires "focus", and the constant attempts by the skin to stay on "top", in front of the input field, will not allow InputTextX to function correctly.
278-
279-
> **Warning:**
280-
> Ensure that your custom commands (especially those using `$UserInput$`) are properly formatted. Improper command syntax may cause unexpected behavior in Rainmeter.
281-
282-
---
283-
284-
## Troubleshooting
285-
286-
- **Crash on Input:**If Rainmeter crashes when submitting input, enable logging by setting `Logging=1` to view the final command strings in the Rainmeter log. Verify that the commands are correctly formed.
287-
- **No Command Execution:**Double-check the action keys (e.g., `OnEnterAction`, `OnESCAction`) in your skin configuration. They must contain valid Rainmeter commands.
288-
- **Positioning Issues:**
289-
If the overlay does not appear in the expected location, adjust the `X` and `Y` offset values.
290-
291-
---
292-
293-
## Example Skin Configuration
294-
295-
Below is a sample Rainmeter skin configuration that demonstrates how to use **InputTextX**:
296-
297-
```ini
298-
[Rainmeter]
299-
Update=1000
300-
301-
[MeasureInput]
302-
Measure=Plugin
303-
Plugin=InputTextX.dll
304-
W=300
305-
H=40
306-
SolidColor=255,255,255
307-
FontColor=0,0,0
308-
FontSize=12
309-
Align=Center
310-
Password=0
311-
FontStyle=Normal
312-
FontFace=Segoe UI
313-
Multiline=0
314-
AllowScroll=0
315-
InputLimit=0
316-
DefaultValue=Type here...
317-
InputType=String
318-
AllowedChars=
319-
OnDismissAction=[!Log "Dismissed: $UserInput$"]
320-
OnEnterAction=[!Log "Submitted: $UserInput$"]
321-
OnESCAction=[!Log "Cancelled: $UserInput$"]
322-
InValidAction=[!Log "Invalid input"]
323-
X=20
324-
Y=20
325-
AllowBorder=1
326-
BorderColor=0,0,0
327-
BorderThickness=2
328-
MinValue=-999999
329-
MaxValue=999999
330-
TopMost=1
331-
Logging=1
332-
```
333-
334-
---
335-
336-
## License
337-
338-
Distributed under the MIT License. See [LICENSE](LICENSE) for more information.
339-
340-
---
341-
342-
## Contributing
343-
344-
Contributions are welcome! Please fork the repository and create a pull request with your changes.
345-
346-
---
347-
348-
## Contact
349-
350-
For support or questions, please open an issue on GitHub or contact [[email protected]](mailto:[email protected]).
8+
Visit the website:
9+
[InputTextX](https://www.rainmeter.net/)

0 commit comments

Comments
 (0)