TourPanel

Namespace: Wisej.Web.Ext.TourPanel

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

Control
- ScrollableControl
  - ContainerControl
    - TourPanel

Provides a tour panel template that can be used to create a guided tour of an application.

C#
VB.NET

public class TourPanel : ContainerControl

Public Class TourPanel
    Inherits ContainerControl

A TourPanel is a top-level popup that displays the Title and Text of each TourStep in the Steps array next to the step's target control, optionally highlighting the target with a mask that covers the rest of the page.

The usual approach is to add a new class that inherits from TourPanel to the project, design it in the Visual Studio designer (change the buttons, colors, layout) and define the steps in the Steps property. The tour is then started calling Show.

Example:

Creating a tour in code and starting it for the current form:

private void buttonHelp_Click(object sender, EventArgs e)
{
    var tour = new TourPanel();
    tour.Steps = new[]
    {
        new TourStep { Title = "Welcome", Text = "This short tour shows you the main features." },
        new TourStep { Title = "Search", Text = "Type here to search the <b>customers</b>.", TargetName = "textBoxSearch" },
        new TourStep { Title = "Save", Text = "Click to save your changes.", TargetName = "panelTools.buttonSave", Alignment = Placement.RightMiddle }
    };
    tour.Ended += (s, args) => AlertBox.Show("Tour completed!");
    tour.Show(this);
}

Constructors

TourPanel()

Initializes a new instance of the TourPanel class.

The standard buttons (ExitButton, BackButton, NextButton, CloseButton and PlayButton) that are hidden in the designer of a derived class are never shown by the TourPanel.

TourPanel(parent)

Initializes a new instance of the TourPanel control and assigns it to the specified parent .

Name	Type	Description
parent	Control	The parent control that owns this tour panel.

Throws:

ArgumentNullException The value of parent is null.

Properties

AutoClose

Boolean: Returns or sets whether the TourPanel closes automatically when the user clicks outside of the control. (Default: False)

When the panel is closed this way, the Closed event is fired but Ended is not.

AutoPlay

Boolean: Returns or sets whether the TourPanel advances the steps automatically. (Default: True)

Setting this property to true immediately calls Play and setting it to false calls Pause. When true, Show also starts playing. The time each step is displayed is set by AutoPlayTime or DefaultAutoPlayTime.

Example:

Running a tour that advances every 3 seconds:

var tour = new MyTour();
tour.DefaultAutoPlayTime = 3;
tour.Show(this);
tour.AutoPlay = true;

AutoSize

Boolean: Returns or sets whether the TourPanel automatically adjusts its size when the step changes. (Default: True)

When true, the size is calculated asynchronously by measuring the HTML in Text using the font of HtmlText, and it's limited to the size of the browser.

Container

ContainerControl: Returns the ContainerControl that this TourPanel is attached to.

The value is set by Show and it's null when the tour was started with Show.

CurrentStep

TourStep: Returns or sets the current TourStep.

Returns null when no step is displayed. Setting this property is equivalent to setting SelectedIndex to the index of the step in Steps, which fires AfterStep and BeforeStep.

Throws:

ArgumentNullException The value is null.
ArgumentOutOfRangeException The value is not in the Steps array.

Example:

Jumping to a specific step:

this.tour.CurrentStep = this.tour.Steps.First(s => s.TargetName == "buttonSave");

DefaultAlignment

Placement: Returns or sets the default Placement of the TourPanel in relation to the target of the step. (Default: BottomCenter)

Each TourStep can override the default value using the Alignment property. The panel is moved to a different side automatically when there isn't enough space in the browser. Steps without a target are always shown at the top of the Container.

DefaultAutoPlayTime

Int32: Returns or sets the default number of seconds before showing the next step when the TourPanel is playing the steps automatically (see AutoPlay and Play). (Default: 5)

Each TourStep can override the default value using the AutoPlayTime property.

Throws:

ArgumentException When the value is less than 1.

DefaultOffset

Padding: Returns or sets the default offset from the target, in pixels.

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. Each TourStep can override the default value using the Offset property.

Example:

Leaving a 10 pixels gap between the panel and the target:

this.tour.DefaultOffset = new Padding(10);

DefaultShowClose

Boolean: Returns or sets whether the TourPanel shows the CloseButton and ExitButton buttons. (Default: True)

The ExitButton is always shown on the last step. Each TourStep can override the default value using the ShowClose property.

HighlightColor

Color: Returns or sets the color of the highlight mask. (Default: Color [Empty])

Uses the highlightColor set in the theme when this property is Empty. Use a semi-transparent color to let the user see the page under the mask.

Example:

Using a semi-transparent dark mask:

this.tour.HighlightTarget = true;
this.tour.HighlightColor = Color.FromArgb(128, 0, 0, 0);

HighlightTarget

Boolean: Returns or sets a value indicating whether the current target is highlighted. (Default: True)

When true, the page is covered by a mask of HighlightColor with a hole over the target of the current step. When false and AllowPointerEvents is also false, a transparent mask still blocks the pointer events on the page.

IsPlaying

Boolean: Returns whether the TourPanel is currently playing the steps automatically.

The value is changed by Play and Pause, and by the play button.

SelectedIndex

Int32: Returns or sets the index of the current TourStep in the Steps collection. (Default: 0)

The value is -1 before the first step is shown. Setting a new index fires AfterStep for the current step and BeforeStep for the new one, then resolves the target, makes it visible (selecting its tab page, expanding its panel, scrolling it into view, etc.) and places the panel next to it. The new step is shown even if Enabled is false; use Next and Back to skip disabled steps. If the BeforeStep event is canceled, the index doesn't change.

Throws:

ArgumentOutOfRangeException The value is less than 0 or greater than the length of Steps.

Steps

TourStep[]: Returns or sets the steps to show in this TourPanel.

Never returns null: when no steps are set it returns an empty array. Assigning a new array sets the Tour property of each step; since the value is an array, replacing or adding single elements doesn't update the owner of the steps, so always assign a new array. Steps with Enabled set to false are skipped by First, Next and Back.

Example:

Adding a step to an existing tour:

var steps = this.tour.Steps.ToList();
steps.Add(new TourStep { Title = "Reports", Text = "Open the reports from here.", TargetName = "menuBar1.menuReports" });
this.tour.Steps = steps.ToArray();

Methods

Back()

Shows the previous step.

Skips the steps with Enabled set to false. Nothing happens when the current step is the first enabled step.

Example:

Going back one step from a custom button:

private void buttonPrevious_Click(object sender, EventArgs e)
{
    this.tour.Back();
}

Close()

Closes the TourPanel.

Fires the Ended event and hides the panel, which fires the Closed event when the client widget disappears. The close and exit buttons call this method. The TourPanel is not disposed.

Example:

Closing the tour from a custom button:

private void buttonSkipTour_Click(object sender, EventArgs e)
{
    this.tour.Close();
}

Dispose(disposing)

Disposes the TourPanel.

Parameter	Type	Description
disposing	Boolean

First()

Shows the first step.

Shows the first step in Steps with Enabled set to true. Nothing happens if there are no enabled steps or if the first enabled step is already the current step.

Example:

Restarting the tour from the beginning:

private void buttonRestart_Click(object sender, EventArgs e)
{
    this.tour.First();
}

Next()

Shows the next step.

Skips the steps with Enabled set to false. When there are no more steps it fires the Ended event and, if the tour is playing, hides the TourPanel.

Example:

Advancing the tour when the user completes the action described in the current step:

private void textBoxSearch_TextChanged(object sender, EventArgs e)
{
    if (this.tour.CurrentStep?.TargetName == "textBoxSearch")
        this.tour.Next();
}

OnAfterStep(e)

Fires the AfterStep event.

Parameter	Type	Description
e	TourPanelEventArgs	A TourPanelEventArgs that contains the event data.

After the AfterStep handlers run, this method also fires the Hide event of the step in Step and sets its IsVisible to false. It's called by the TourPanel when leaving a step; override it in a derived class to customize the behavior.

Example:

Overriding the method in a custom tour to track the steps the user has seen:

public class MyTour : TourPanel
{
    public override void OnAfterStep(TourPanelEventArgs e)
    {
        base.OnAfterStep(e);

        Application.Session.lastTourStep = e.StepIndex;
    }
}

OnBeforeStep(e)

Fires the BeforeStep event.

Parameter	Type	Description
e	TourPanelEventArgs	A TourPanelEventArgs that contains the event data.

After the BeforeStep handlers run, this method also fires the Show event of the step in Step and sets its IsVisible to true. Setting Cancel to true in a handler prevents the step from being shown. It's called by the TourPanel when changing steps; override it in a derived class to customize the behavior.

Example:

Overriding the method in a custom tour to load the content of a step on demand:

public class MyTour : TourPanel
{
    public override void OnBeforeStep(TourPanelEventArgs e)
    {
        if (String.IsNullOrEmpty(e.Step.Text))
            e.Step.Text = LoadHelpText(e.Step.TargetName);

        base.OnBeforeStep(e);
    }
}

OnEnded(e)

Fires the Ended event.

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

OnNotFound(e)

Fires the NotFound event.

Parameter	Type	Description
e	HandledEventArgs	A HandledEventArgs that contains the event data.

OnPaused(e)

Fires the Paused event.

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

OnPlaying(e)

Fires the Playing event.

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

OnWebEvent(e)

Processes the event from the client.

Parameter	Type	Description
e	WisejEventArgs	Event arguments.

OnWebRender(config)

Renders the client component.

Parameter	Type	Description
config	Object	Dynamic configuration object.

Pause()

Pauses auto-advancing the steps.

Stops the timer, resets IsPlaying, changes the icon of the PlayButton to "icon-play" and fires the Paused event. Nothing happens if the tour is not playing. Call Play to resume from the current step.

Example:

Pausing the tour while the user interacts with a target:

private void textBoxSearch_Enter(object sender, EventArgs e)
{
    if (this.tour.IsPlaying)
        this.tour.Pause();
}

Play()

Starts auto-advancing the steps.

Starts a timer that calls Next after the number of seconds set in AutoPlayTime or DefaultAutoPlayTime, sets IsPlaying, changes the icon of the PlayButton to "icon-pause" and fires the Playing event. If the current step is the last one, the tour restarts from the first step. Nothing happens if the tour is already playing.

Example:

Showing a tour and playing it automatically:

var tour = new MyTour();
tour.Show(this);
tour.Play();

Show()

Shows the TourPanel without a container.

Without a container, the first name in TargetName is resolved as the name of an open Form or Page, or as "Desktop" or "MainPage". All the steps should specify a TargetName or a Target, otherwise the NotFound event is fired.

Example:

Touring controls in different windows:

var tour = new TourPanel();
tour.Steps = new[]
{
    new TourStep { Title = "Navigation", Text = "Use this menu to navigate.", TargetName = "MainPage.navigationBar1" },
    new TourStep { Title = "Customer", Text = "Edit the customer here.", TargetName = "CustomerForm.textBoxName" }
};
tour.Show();

Show(container)

Shows the TourPanel for the specified container control.

Parameter	Type	Description
container	ContainerControl	The ContainerControl that hosts the controls that are the target for this TourPanel.

The TargetName of each step is resolved starting from the controls in container , and steps without a target are shown at the top of the container . This method sets Container, shows the first enabled step, moves the focus to the NextButton (or the BackButton) and starts playing when AutoPlay is true.

Example:

Starting the tour of the current page:

private void Page1_Load(object sender, EventArgs e)
{
    var tour = new MyTour();
    tour.Show(this);
}

Events

AfterStep

TourPanelEventHandler Fired when the current step is replaced by a new step. This event is not cancelable.

BeforeStep

TourPanelEventHandler Fired when the TourPanel shows a new step. This event is cancelable.

Closed

EventHandler Fired when the TourPanel control is closed.

Ended

EventHandler Fires when the TourPanel has finished showing the steps.

NotFound

HandledEventHandler Fires when the TourPanel cannot find the target widget specified in the TargetName property of the CurrentStep.

If this event is not handled, the default behavior is to throw an exception.

Paused

EventHandler Fired when the TourPanel has been paused.

Playing

EventHandler Fires when the TourPanel is playing the steps automatically.

Implements

Name	Description
IUserData
IBindableComponent
IContainerControl
IDropTarget
IWisejComponent
IWisejControl
IWisejSerializable

Constructors​

TourPanel()​

TourPanel(parent)​

Properties​

AutoClose​

AutoPlay​

AutoSize​

Container​

CurrentStep​

DefaultAlignment​

DefaultAutoPlayTime​

DefaultOffset​

DefaultShowClose​

HighlightColor​

HighlightTarget​

IsPlaying​

SelectedIndex​

Steps​

Methods​

Back()​

Close()​

Dispose(disposing)​

First()​

Next()​

OnAfterStep(e)​

OnBeforeStep(e)​

OnEnded(e)​

OnNotFound(e)​

OnPaused(e)​

OnPlaying(e)​

OnWebEvent(e)​

OnWebRender(config)​

Pause()​

Play()​

Show()​

Show(container)​

Events​

AfterStep​

BeforeStep​

Closed​

Ended​

NotFound​

Paused​

Playing​

Implements​

Constructors

TourPanel()

TourPanel(parent)

Properties

AutoClose

AutoPlay

AutoSize

Container

CurrentStep

DefaultAlignment

DefaultAutoPlayTime

DefaultOffset

DefaultShowClose

HighlightColor

HighlightTarget

IsPlaying

SelectedIndex

Steps

Methods

Back()

Close()

Dispose(disposing)

First()

Next()

OnAfterStep(e)

OnBeforeStep(e)

OnEnded(e)

OnNotFound(e)

OnPaused(e)

OnPlaying(e)

OnWebEvent(e)

OnWebRender(config)

Pause()

Play()

Show()

Show(container)

Events

AfterStep

BeforeStep

Closed

Ended

NotFound

Paused

Playing

Implements