|
Displays a dialog window on the screen. You can use this window to ask the user interactively for information that your Blend script needs.
Returns embedded XML describing the runtime state of the dialog. See the "Return value" section.
Syntax
<pc:Dialog
variable = "xpath >> (any)"
[ variable = "xpath >> (any)" ... ] >
embedded-xml
</pc:Dialog>
|
The optional variable assignments can be used to catch user input. See the "Catching user input" section below.
The required embedded-xml describes the look and behaviour of the dialog you want to produce. For the concept, go to Embedded XML. You can code embedded-xml inline, or you can read it from a file, or you can have a different script section supply it.
To determine what a dialog looks like and what it does, your embedded XML should specify dialog controls. A dialog control is a screen element with a specific look and function. For aspects of visual appearance, such as position, size and colour, you can use visual attributes.
Example
<example xmlns:pc="Processing.Command" xmlns:assign="Processing.Command.Assign" pc:hideme="true">
<pc:Dialog>
<Form w="250">
<Title>USoft Blend dialog</Title>
<Label dx="5" dy="10" w="40" >This is a USoft Blend dialog.</Label>
<Button dy="20" newline="true"><Result>OK</Result>OK</Button>
<Button><Result>Cancel</Result>Cancel</Button>
</Form>
</pc:Dialog>
</example>
|
Some dialog controls only have a visible presence (Title, Label), but most controls allow the user to interact with the dialog to provide information that your Blend script needs.
This table includes XML elements that are not themselves a dialog control but contribute to make a dialog control work properly (Panel, Result).
Visual attributes (see next section) apply in the same way to a range of different controls.
Dialog control
|
Description
|
Button
|
A push button.
|
CheckBox
|
A 2-valued check box.
|
ComboBox
|
A drop-down list box in a dialog window. The user can expand the list and choose one of the alternatives.
|
FileButton
|
A push button leading to a Browse dialog where the user can select a file from the file system.
|
FolderButton
|
A push button leading to a Browse dialog where the user can select a folder from the file system.
|
Form
|
The dialog window as a whole.
|
Label
|
A line of hard-coded text on the dialog canvas itself.
|
Panel
|
A group of radio buttons. Selecting one radio button causes the other radio buttons in the group (in the panel) to be deselected.
|
Picture
|
A picture on the dialog canvas itself.
|
RadioButton
|
A button in a panel of radio buttons. Selecting one radio button causes the other radio buttons in the panel to be deselected.
|
Result
|
A value associated with a button that allows you to detect that a user has pressed the button.
|
TextBox
|
A field in which the user can enter or read text.
|
Title
|
The title text in the window bar at the top of the dialog.
|
|
Many dialog controls support attributes for determining visuals aspects such as position, size and colour.
Position attributes
|
dx
|
The horizontal offset of the control relative to its x position.
|
dy
|
The vertical offset of the control relative to its y position.
|
newline
|
By default, controls are positioned from left to right next to each other.
A control with newline="true" is displayed on a new line relative to the previous control.
|
x
|
The control's horizontal distance (in pixels) from the left side of the dialog window.
The default is 0 (zero).
|
y
|
The control's vertical distance (in pixels) from the top side of the dialog window.
The default is 0 (zero).
|
Size attributes
|
h
|
The height of the control (in pixels).
|
multiline
|
multiline="yes" causes a TextBox control to be multi-line, that is: to be able to have variable height. Set the actual height you want by using the h attribute.
|
w
|
The width of the control (in pixels).
|
Colour attributes
|
fgcolor
|
Foreground colour. In the case of controls that display text: font color.
|
bgcolor
|
Background colour.
|
Font and text attributes
|
bold
|
bold="yes": the Bold font is applied.
bold="no": the non-Bold font is applied.
|
fontsize
|
The size of the font (in pixels).
|
tip
|
A text message that pops up when the user hovers the control.
|
|
You can catch user input by using a name attribute for an input control, for example, for a text box:
<TextBox name="username" />
You can then catch what the user typed in the text box. Assign a variable at the level of the pc:Dialog element, like so:
<pc:Dialog
assign:userinput="/Forms/Form/TextBox[@name='username']/text()"
...
/>
|
To refer to the value supplied by the user, write:
$userinput
|
You can hide password characters being typed by a runtime user by specifying the following passwordchar attribute of a TextBox element:
<TextBox passwordchar="*" />
|
You can use a Result child element of Button to associate the event of the user pressing the button to a value. The value associated with the user's button push is returned in the return attribute of Form. This allows you to test what the user did, and respond accordingly.
Example
<example xmlns:pc="Processing.Command" xmlns:assign="Processing.Command.Assign" pc:hideme="true">
<pc:Dialog
assign:proceed="/Forms/Form/@result='OK'">
<Form w="250">
<Title>USoft Blend dialog</Title>
<Label dx="5" dy="10" w="40" >Please press OK to dismiss this dialog.</Label>
<Button dy="20" newline="true"><Result>OK</Result>OK</Button>
</Form>
</pc:Dialog>
<pc:if test="xslutil:test($proceed)">
<pc:then>The user pressed OK.</pc:then>
<pc:else>Cancelled</pc:else>
</pc:if>
</example>
|
|
The return value of Example 1 is:
<Forms><Form name="Form0" result="OK"><Label name="Label0">This is a USoft Blend dialog.</Label></Form></Forms>
|
The return value is automatically suppressed if you assign a variable like so (as in Example 2 in the previous section):
<pc:Dialog assign:variable=""/>
|
and also if you include a pc:return attribute. Consequently, you can simply suppress output by coding:
<pc:Dialog pc:return=""/>
|
|
See also
Dialogs
|
