Skip to main content

TourStep

Namespace: Wisej.Web.Ext.TourPanel

Assembly: Wisej.Web.Ext.TourPanel (4.1.0.0)

Represents a step in a TourPanel.

public class TourStep

Each step displays its Title and Text in the TourPanel, placed next to the control identified by TargetName or Target. Changes to a step that is currently visible are applied immediately.

Example:

Defining a step that points to a button inside a panel:

var step = new TourStep
{
    Title = "Save",
    Text = "Click <b>Save</b> to store your changes.",
    TargetName = "panelTools.buttonSave",
    Alignment = Placement.RightMiddle,
    AutoPlayTime = 8
};
step.Show += (s, e) => this.buttonSave.Enabled = true;

Constructors​

Instance member TourStep()​

Initializes a new instance of TourStep.

Properties​

Instance member Alignment​

Placement: Returns or sets the alignment side and position of the TourPanel in relation to the target when this TourStep is shown.

The default value is BottomCenter. When the value is the same as DefaultAlignment, the default alignment of the TourPanel is used.

Instance member AllowPointerEvents​

Boolean: Returns or sets a value indicating whether pointer events are allowed on the current target. (Default: False)

When false (default), the mask displayed over the page blocks all pointer events while this step is shown. When true, the mask lets pointer events through and the user can interact with the target.

Instance member AutoPlayTime​

Int32: Returns or sets the number of seconds to wait before showing the next step when the TourPanel is auto playing the steps. The default value is 0 to use the time set in the DefaultAutoPlayTime property. (Default: 0)

Throws:

Instance member Enabled​

Boolean: Returns or sets whether the step is enabled. When a step is disabled it is skipped from the rotation. (Default: True)

Disabled steps are skipped by First, Next and Back, but they can still be shown by setting SelectedIndex or CurrentStep.

Instance member Index​

Int32: Returns the index of this step in the Steps list.

Returns -1 when the step doesn't belong to a TourPanel.

Instance member IsVisible​

Boolean: Returns true when this step is currently visible on the TourPanel.

The value is set to true before the Show event and to false after the Hide event.

Instance member Offset​

Padding: Returns or sets the offset in pixels of the calculated position of the TourPanel when this TourStep is shown.

The Padding sides are used according to the placement: for example Top adds space between the target and a panel placed below it, and Left between the target and a panel placed at its right. When the value is the same as DefaultOffset, the default offset of the TourPanel is used.

Example:

Moving the panel 20 pixels away from the bottom of the target:

this.tourStep1.Alignment = Placement.BottomCenter;
this.tourStep1.Offset = new Padding(0, 20, 0, 0);

Instance member ShowClose​

Boolean: Returns or sets whether the TourPanel shows the CloseButton and ExitButton buttons when showing this TourStep.

The ExitButton is always shown on the last step. When the value is the same as DefaultShowClose, the default value of the TourPanel is used.

Instance member Tag​

Object: Returns or sets user-defined data associated with the step. (Default: null)

Value: An object representing the data.

Instance member Target​

Object: Returns or sets the target for the step. The object can be a reference to a control, a component, or a string with the numeric ID (the Handle) of the target.

When set, TargetName is ignored. When the target is resolved from TargetName, this property is set to a string with the handle of the target followed by the child path (i.e. "12/tools[0]"). When the target is a control or component, the TourPanel makes it visible before showing the step (selects its tab page, expands its panel, scrolls it into view, etc.).

Example:

Targeting a control created at runtime, which doesn't have a designer name:

var button = new Button { Text = "Export" };
this.panelTools.Controls.Add(button);

this.tourStep3.Target = button;

Instance member TargetName​

String: Returns or sets the name or path that identifies the target control within the Container of the TourPanel. (Default: "")

The value of the TargetName property uses the following syntax: controlName.childControlName.childControlName, etc.

Nested controls can be reached by specifying the full path. For example, the button child of a panel can be identified as "panel1.button1".

Child widgets (widgets that compose more complex widget) can be reached using the slash separator and the name of the child widget. For example, the tools added to a control that supports tools can be reached as "textBox1/tools".

Child widgets that are part of the children collection on the client can be reached using the "[]" syntax. For example, the first tool in a tools widget is addressable as "textBox1/tools[0]".

The names in the path can also refer to the columns of a DataGridView or ListView, the items of a MenuBar or MainMenu, the "menu" of a Form and MDI child forms. When the tour is started with Show (no container), the first name is the name of an open Form or Page, or "Desktop" or "MainPage".

When the target is not found, the NotFound event is fired. The target is resolved only the first time the step is shown, the result is stored in Target.

Example:

Pointing to nested controls, tools and grid columns:

this.tour.Steps = new[]
{
    new TourStep { Title = "Name", Text = "Enter the name here.", TargetName = "panelDetails.textBoxName" },
    new TourStep { Title = "Tools", Text = "Use the first tool to clear the field.", TargetName = "textBoxSearch/tools[0]" },
    new TourStep { Title = "Total", Text = "This column shows the total.", TargetName = "dataGridView1.colTotal" }
};
this.tour.Show(this);

Instance member Text​

String: Returns or sets the HTML text to display in the TourPanel. (Default: "")

The text is displayed in HtmlText and can contain HTML markup. When AutoSize is true, the panel is resized to fit the text. Setting it to null sets it to an empty string.

Example:

Using HTML to format the text of a step:

this.tourStep1.Text = "Use the <b>search</b> box to find a customer by:<ul><li>Name</li><li>Email</li></ul>";

Instance member Title​

String: Returns or sets the title to display in the TourPanel. (Default: "")

The title is displayed in TitleLabel. Setting it to null sets it to an empty string.

Instance member Tour​

TourPanel: Returns the TourPanel that owns this TourStep.

The value is set when the step is assigned to the Steps property; it's null otherwise.

Instance member UserData​

Object: Returns a dynamic object that can be used to store custom data in relation to this component.

The object is created on first access and it's never sent to the client.

Example:

Storing and reading custom values on a step:

this.tourStep1.UserData.HelpTopic = "customers";

private void tour_BeforeStep(object sender, TourPanelEventArgs e)
{
    string topic = e.Step.UserData.HelpTopic;
    if (topic != null)
        LoadHelpTopic(topic);
}

Methods​

Instance member OnHide(e)​

Fires the Hide event.

ParameterTypeDescription
eEventArgs

Instance member OnShow(e)​

Fires the Show event.

ParameterTypeDescription
eEventArgs

Events​

Instance member Hide​

EventHandler Fired when the step is hidden.

Instance member Show​

EventHandler Fired when the step is shown.