descriptive labels and types for $macroArgs #2843
Description
The macro language will offer a new macroArg command. These commands can be used at the beginning of a macro.
macroArg argument_name [ : type ] descriptive label
Examples:
macroArg myintvalue:int "Number of cycles"
macroArg mystring:string 'Text to be repeated'
macroArg something:any "An arbitrary expression"
macroArg anotherthing :any "Another value" // There can be a space before the colon
macroArg onemorething: any "One more value" // There can be a space between the colon and the type
macroArg anadditionalthing : any "An additional value" // There can be spaces before and after the colon
macroArg anything "Anything goes here" // Types are optional and will default to :any
// this is how the parameters are accessed by name (irrelevant for Agent):
// in addition, they can also still be accessed as $macroArg.1, $macroArg.2 etc.
setVar counter $macroArg.myintvalue // identical to $macroArg.1
loop: write $macroArg.mystring // identical to $macroArg.2
repeatFor counter loop
Agent should parse the macroArg statements and use the information to display argument lists when mapping a key to this macro.
If a macro has no macroArg statements, behaviour remains unchanged: Agent allows the user to add macro arguments and they will be labelled $macroArg.1, $macroArg.2 etc.
If a macro has macroArg statements, then Agent shall automatically show as many argument fields as there are macroArg statements in this macro. Each argument field shall be labelled with the descriptive label. When the user enters values for the fields, only valid values for each argument type shall be allowed. Valid types are: int, float, bool, string, keyid | keyId, scancode | scanCode | moddedScancode | moddedScanCode | shortcut | shortCut, and any. Types are optional, a missing type is equivalent to any.
- For
int, the value needs to match the regex/^-?[0-9]+$/ - For
float, the value needs to match the regex/^-?[0-9]+(\.[0-9]*)?$/ - For
bool, the value can betrueorfalse. - For
string, the value can be anything, but when storing in config, the value will be enclosed in single quotes automatically, and any single quotes and escape characters will be escaped ('=>\'and\=>\\). - For
keyid, a popup will allow only the selection of key legends, and the values field will internally be set to the KEYID for that legend. - For
scancode, a popup will allow only the selection of scancodes (similar to Keypress action), and buttons for modifiers will be shown (again, similar to Keypress action). The value field will internally be set to the corresponding SHORTCUT. - For
any, the value can be anything, and it will be passed verbatim (= as entered) without any checks. This is identical to manually added parameters but the field will be labelled with the descriptive label instead of "$macroArg.x").
The descriptive label is a string literal; it can be enclosed in single or double quotes, or it can be a raw string. That means: enclosing quotes have to be removed before displaying the descriptive label in the Agent UI.