Revision as of 01:24, 15 October 2022

$input is used to request immediate user-input.

Note: This replaces the deprecated $? identifier.

Synopsis

$input(prompt,options,window,title,text)

Prompts the user for input and returns the result.

Parameters

• prompt - Parameter must not be blank. Text displayed inside the input dialog window. The input dialog is extended vertically as needed to display the prompt message if it is very long. You can also make text in the prompt message appear on different lines by using $crlf to separate lines. The input window widens as needed by 1-3 buttons, the edit or combo dropdown, icon, or titlebar text

(first of 'onyr' or 'pem' or 'tciqwh' used if multiple switches from these mutually-exclusive groups are used)

• options - Options can be a combination of the following:

• e - show input editbox. Content of input editbox returned by clicking leftmost button or pressing <enter>. Defaults to returning empty string if <esc> out of dialog or pressing 'No' 'Cancel'.
• p - show input password editbox. Same return strings as 'e'
• o - 'ok' button
• n - 'yes' 'no' 'cancel' buttons
• y - 'yes' 'no' buttons
• r - 'retry' 'cancel' buttons
• m - indicates that multiple text parameters have been specified. They will be displayed in a combo dropdown box. The first text item is the default item (a reference to an item in the list), the rest are the items in the list. Selected list item is returned from clicking the leftmost button. Dropdown list begins with the 2nd 'text' parameter, and item from list is displayed as default selection only if it has case-insensitive match with the 1st 'text' parameter.
• f - extends button-related strings of 'No' 'Cancel' button behavior of 'onyr' switches to 'pem' edit/combo boxes, as potentially modified by 'vfkN'
• kN - an N seconds timeout value. On timing out, has default action of returning $false for 'onyr' or $null for 'pem' switches based on usage of 'vf' switches, except 'v' changes non-$null return value to $timeout.
• v - changes kN return string from $false to $timeout, return $ok, $yes, $no, $cancel, $retry for buttons if otherwise returning $true, $false
• g - right-align buttons
• b - disables buttons for 1 second when dialog is displayed and clears keyboard buffer
• tciqwh - show the goldstar,recycle bin,info, question, warning, and halt icons respectively.
• d - play system sound associated with icon switch used: 'di' 'dt' = 'asterisk', 'dq' = 'question', 'dw' 'dc' = 'exclamation', 'dh' = 'critical stop'
• s - indicates that window parameter has been specified (making optional 'title' be the 4th parameter)
• a - make $input dialog active if mIRC is not the active application
• u - use current active window as parent window, if blocks clicking on dialog if

• window - if option s is specified, the name of the window to be used as parent window.
• title - the titlebar text.
• text - default text placed in the input editbox

The options, window, title, and text are optional parameters, with 'window' being an inserted parameter only when 's' is used. The 'window' parameter is made the active window by using the 's' switch, and can be many window names including where $window(string) returns that same string, which includes #channel Query @window but excludes Query and #channel windows attached to a different Status Window connection. Because 'window' can be a desktop @window which does not block the main MDI area, care must be taken to avoid having multiple $input dialogs open at the same time.

By default, 'onyr' switches return $true from 'Ok' 'Yes' 'Retry' buttons and returns $false from 'No' 'Cancel' buttons. 'pem' switches defaults buttons returning the contents of editbox/combobox except 'No' 'Cancel' buttons returning $null. f switch extends 'No' 'Cancel' buttons in 'pem' to have same behavior as in 'onyr'. kN defaults to returning $false if dialog not exited within N seconds. 'v' changes $true $false from button clicks to instead return '$yes' '$no' '$ok' '$retry' '$cancel', except for $false strings caused by kN change to $timeout.

Alternate methods to button clicks: pressing <enter> or <spacebar> while focus is on that key. Focus can be changed by <tab> or <arrow> keys. When there is more than 1 button, pressing <esc> simulates clicking the rightmost button. 'Yes' 'No' 'Retry' have Alt+Y Alt+N Alt+R hotkeys but 'Cancel' and 'OK' do not.

For the options parameter, you can also use a number as a combination of value added together, without the presence of any letter switches, which is how $input was originally working:

• 1 - show input editbox (equivalent of the 'e' switch)
• 2 - show input password editbox (equivalent of 'p' switch)
• 4 - ok button (equivalent of 'o')
• 8 - yes/no buttons ('y')
• 16 - yes/no/cancel buttons ('n')
• 32 - return $ok, $yes, $no, $cancel, $retry for buttons. ('v')
• 64 - show the info icon ('i')
• 128 - show the question icon ('q')
• 256 - show the warning icon ('w')
• 512 - show the halt icon ('h')
• 1024 - insert 'window' as the 3rd parameter ('s')
• 2048 - activate the $input dialog when mIRC is not the active application ('a')
• 4096 - show the gold star icon ('t')
• 8192 - retry/cancel buttons ('r')
• 16384 - align buttons to the right ('g')
• 32768 - show the recycle bin icon ('c')
• 65536 - play icon-related sound ('d')
• 131072 - combo dropdown list ('m')

$input(sup,5) is equivalent to $input(sup,eo)

Note: This identifier cannot be used in a remote event. One way around this is to use a /timer to initiate an input request after the script ends. Another way around it is to use /signal to trigger an on signal event.

Examples

alias testme {
  echo -a $input(Type something for me,e)
}

Echoes whatever the user types into the input field to the active window.

alias testme {
  echo -a $input(Enter Password:,p)
}

Does the same as the first example, except while the user is typing, the characters are replaced by password characters. The typed value, however, is visibly legible when it is echoed to the active window.

alias testme {
  echo -a $input(Do you like chocolate?,y)
}

Pops up an input request asking if the user likes chocolate. If they click Yes, it echoes $true to the active window; otherwise, it echoes $false.

See also

• $?