Query Box
Query Box is used to create a contextual prompt that asks a question to the user and captures a response at runtime. It appears as a dialog box, typically when an action is triggered (i.e. Control Ex attribute at Form Level or Query Box Ex at function level). The Query Box allows developers to seek confirmation, request specific values, or guide user decisions before proceeding further. Through its attributes, the Query Box controls the message displayed, the type of response expected, default values, and how the user’s input influences subsequent processing.
Syntax
[Query Box: <Query Box Name>]
Example
[Query Box: TSPL Query Box]
➥ Click here to download the Query Box Sample
Attributes
When a Query Box appears, the user should instantly understand its purpose. The Title attribute helps achieve this by displaying a clear and meaningful heading at the top of the Query Box. It instantly sets the context, helping users understand the decision or action expected from them, reducing confusion, and making the interaction more intuitive and purposeful.
Syntax
Title : <Title Name>
<Title Name> is title to be displayed in the Query Box.
Example
[Query Box: TSPL Query Box]
Title : “Sample Query Box”
Explanation
The example defines a query box TSPL Query Box with the title ‘Sample Query Box’.
The Query attribute defines an individual option inside the Query Box. It allows you to specify the hotkey the user can press, the text that appears for that option, and an optional description to add clarity. By using this attribute thoughtfully, you can design decision prompts that are clear, meaningful, and easy for users to understand so users know exactly what choice they are making.
Each Query option is internally indexed as 1, 2, 3, and so on. This internal indexing plays a key role in defining the default behaviour for the Enter and Esc keys. By referring to these index numbers through the Default attribute, you can ensure that pressing Enter or Esc triggers the intended option even when the user does not explicitly use a hotkey, resulting in a smooth and predictable user experience.
Syntax
Query : <HotKey> : <Query String> : <Description>
<HotKey> is the key pressed by the user to select the option.
<Query String> is the text displayed for the option.
<Description> is the additional information explaining what the option does.
Example
[Function: TSPL Smp Query Box]
Variable : SelectedIndex : Number
000 : Query Box Ex : TSPL Query Box
010 : Set : SelectedIndex : $$LastResult
020 : Log : ##SelectedIndex
[Query Box: TSPL Query Box]
Title : “Sample Query Box”
Query : Y : “Accept” : “Accept the Screen”
Query : N : “Back” : “Cancel the operation”
Explanation
This example defines a query box TSPL Query Box with title Sample Query Box. This query box has 2 options specified using the attribute Query. The first statement Query : Y : “Accept” : “Accept the Screen” specifies that pressing the hot key Y selects the first option, while the second statement Query : N : “Back” : “Cancel the operation” specifies that pressing the hot key N selects the second option. Internally these options are indexed 1 and 2 respectively and when the user selects the option, system records the index and the same can be used in further processing. In the example, the function TSPL Smp Query Box, invokes the query box through the action Query Box Ex. Once the user selects an option, the internal index recorded is retrieved using the platform function $$LastResult which is set to a function variable and further displayed in the calculator panel log.
A Query Box can contain multiple Query options, each associated with its own hot key and it is internally indexded as 1,2,3 and so on. However, users are naturally habituated to press Enter to proceed and Esc to reject. To ensure this familiar behaviour is preserved and to avoid Tally waiting indefinitely for an explicit key choice, the Default attribute is used.
The Default attribute specifies which Query should be triggered automatically when the user presses Enter or Esc, without selecting any hot key. It accepts index numbers of the Query attributes, where the first parameter corresponds to Enter and the second parameter corresponds to Esc. This ensures predictable flow, consistent user experience, and uninterrupted execution.
Syntax
Default : <Enter Index> : <Escape Index>
<Enter Index> is the option number selected when Enter is pressed.
<Escape Index> is the option number selected when Escape is pressed.
Example
[Function: TSPL Smp Query Box]
Variable : SelectedIndex : Number
000 : Query Box Ex : TSPL Query Box
010 : Set : SelectedIndex : $$LastResult
020 : Log : ##SelectedIndex
[Query Box: TSPL Query Box]
Title : “Sample Query Box”
Query : Y : “Accept” : “Accept the Screen”
Query : N : “Back” : “Cancel the operation”
Default: 1 : 2
Explanation
This example defines a query box TSPL Query Box with title Sample Query Box. This query box has 2 options specified using the attribute Query. The first statement Query : Y : “Accept” : “Accept the Screen” specifies that pressing the hot key Y selects the first option, while the second statement Query : N : “Back” : “Cancel the operation” specifies that pressing the hot key N selects the second option. Internally these options are indexed 1 and 2 respectively and when the user selects the option, system records the index and the same can be used in further processing. The statement Default: 1 : 2 specifies the default behaviours of enter and escape keys. When the user presses enter key, the first option gets selected and when user presses escape key, the second option gets selected.
In the example, the function TSPL Smp Query Box, invokes the query box through the action Query Box Ex. Once the user selects an option, the internal index recorded is retrieved using the platform function $$LastResult which is set to a function variable and further displayed in the calculator panel log.
Sometimes you really want the user to pause and pay attention. The Gray Background attribute (alias: Grey Background) helps you do exactly that by graying out the rest of the screen and allowing the Query Box to stand out clearly. It accepts a logical value (Yes/No). When this attribute is set to Yes, the user’s focus naturally shifts to the question being asked, making the decision easier and reducing distractions. This is especially useful for confirmations, warnings, or any critical prompt that you don’t want the user to overlook.
Syntax
Gray Background : <Logical Value>
<Logical Value> A logical value deciding whether the background should be grayed.
Example
[Query Box: TSPL Query Box]
Title : “Sample Query Box”
Gray Background : Yes
Explanation
The example defines a query box TSPL Query Box with title ‘Sample Query Box’. When the query box pops up, the screen behind the Query Box becomes grey, as specified in the attribute Gray Background. Thus, helping the Query Box stand out clearly to the user.
Sometimes you may want the Query Box to appear exactly where the user’s eyes naturally go. The Horizontal Alignment attribute helps you control where the Query Box is positioned horizontally on the screen whether it should appear on the left, right, or center. By choosing the accurate alignment, you can match the context of the screen, improve visual balance, and make the interaction feel more natural and intuitive for the user.
Syntax
Horizontal Align : <Alignment Type>
<Alignment Type> Specifies the horizontal position of the Query Box. It takes the following values, Bottom, Center, Centre, Justified, Left, Prompt, Right, Top.
Example
[Query Box: TSPL Query Box]
Title : “Sample Query Box”
Horizontal Align : Right
Vertical Align : Top
Explanation
This example defines a query box TSPL Query box with title ‘Sample Query Box’. With the alignment attributes Horizontal Align and Vertical Align, the query box is placed horizontally on the right side of the screen and vertically in the top of the screen thus resulting in a query box aligned in the top right corner of the screen.
Sometimes you may want the Query Box to appear exactly where the user’s eyes naturally go. The Vertical Alignment attribute helps you control where the Query Box is positioned vertically on the screen whether it should appear on the top, bottom, or center. By choosing the accurate alignment, you can match the context of the screen, improve visual balance, and make the interaction feel more natural and intuitive for the user.
Syntax
Vertical Align : <Alignment Type>
<Alignment Type> Specifies the horizontal position of the Query Box. It takes the following values, Bottom, Center, Centre, Justified, Left, Prompt, Right, Top.
Example
[Query Box: TSPL Query Box]
Title : “Sample Query Box”
Horizontal Align : Right
Vertical Align : Top
Explanation
This example defines a query box TSPL Query box with title ‘Sample Query Box’. With the alignment attributes Horizontal Align and Vertical Align, the query box is placed horizontally on the right side of the screen and vertically in the top of the screen thus resulting in a query box aligned in the top right corner of the screen.
