#include <Step.h>

Inheritance diagram for ktutorial::Step:

Signals
void	nextStepRequested (const QString &nextStepId)
	Request a change to the next step.
Public Member Functions
	Step (const QString &id)
	Creates a new Step with the specified identifier.
virtual	~Step ()
	Destroys this Step.
QString	id () const
	Returns the identifier of this Step.
QList< Option * >	options () const
	Returns the Options added to this Step.
QString	text () const
	Returns the text to be shown to the user.
Q_INVOKABLE void	setText (const QString &text)
	Sets the text to be shown to the user.
bool	isActive () const
	Returns true if this Step is active, false otherwise.
void	setActive (bool active)
	Makes this Step active or inactive.
Q_INVOKABLE void	addOption (Option option, QObject receiver, const QString &slot)
	Adds an Option to this Step.
Q_INVOKABLE void	addOption (Option *option, const QString &nextStepId)
	Adds an Option to this Step.
Q_INVOKABLE void	addWaitFor (WaitFor waitFor, QObject receiver, const QString &slot)
	Adds a condition to wait for to this Step.
Q_INVOKABLE void	addWaitFor (WaitFor *waitFor, const QString &nextStepId)
	Adds a condition to wait for to this Step.
Q_INVOKABLE void	removeOption (Option *option)
	Removes an Option from this Step.
Q_INVOKABLE void	removeWaitFor (WaitFor *waitFor)
	Removes a condition to wait for from this Step.
Protected Member Functions
virtual void	setup ()
	Sets up the Step when it is activated.
virtual void	tearDown ()
	Tears down the Step when it is deactivated.
virtual void	connectWaitFor (WaitFor waitFor, QObject receiver, const QString &slot)
	Connects the given WaitFor with the slot in the receiver.
virtual void	disconnectWaitFor (WaitFor *waitFor)
	Disconnects the given WaitFor.

Detailed Description

A step in a Tutorial.

It is each of the tasks that must be accomplished when following a Tutorial. It must contain a text that explains what must be done by the user.

Each of the Steps in a Tutorial must have a unique identifier. Two steps can have the same identifier, but only if they aren't part of the same Tutorial. The identifier must be an untranslated string, and it is used for easy setting of the active Step.

A Step is active if it is the Step the user is in. That is, if it is the one currently being shown. Making a Step active or not is handled by KTutorial. You shouldn't set a Step active yourself. In order to change the current Step, you must use any of Tutorial::nextStep.

Most of times, the text of the Step are instructions that, when accomplished, activates the next Step. To do this, several conditions to wait for can be added to the Step, and when a condition is met and the Step is active, a slot specified when adding the condition is called. The conditions to wait for are modelled using the hierarchy of classes derived from WaitFor.

   Step* step = new Step("someStep");
   step->setText(i18nc("@info", "Write something in the text area"));

   QObject* textArea = KTutorial::self()->findObject<QObject*>("textArea");
   step->addWaitFor(new WaitForSignal(textArea, SIGNAL(textChanged())),
                    this, SLOT(startDone()));

   addStep(startStep);

There will usually be just one condition in each Step (although it can be a composed condition, see WaitForComposed). However, there is nothing wrong in adding more than one WaitFor if needed. It will behave as it does with one condition: when a condition is met, its associated slot will be called.

However, you must be careful with the added WaitFors. You shouldn't add in the same Step more than one WaitFor that wait for the same condition, directly or indirectly. For example, waiting for textChanged() signal in a text area and activating an action that clears the text area (as when the action clears the text area, the textChanged() is emitted). Behaviour is undefined in that case. Of course, there is no problem in adding WaitFors that wait for the same condition in different Steps (but each WaitFor must be a different object, they can't be reused).

Also, sometimes is needed to show some Options to the user, for example to head the Tutorial in one way or another. When an Option is selected by the user, the slot specified when adding it is called, just as it happened with WaitFors. You can have several Options and WaitFors added in the same Step, although it is not very common.

The slots called when an option is selected or when a condition in a WaitFor is met can't have arguments. If you need further processing of the condition, you must do it in the slot by your own means. For example, if you wait for a clicked(bool checked) signal in a QAbstractButton and need to know if it is checked, you should get the button in the slot code and look there whether it is checked or not.

 void SomeTutorial::clickedButton() {
     QAbstractButton* button = KTutorial::self()->findObject<QAbstractButton*>("myButton");

     if (button->isChecked()) {
         nextStep("otherStep");
     }
 }

Sometimes, when a condition to wait for is met or an option is selected you may only want to change to another step, without further checks or actions. In these cases, you can create a slot that just changes to the next step and connect to it when adding the Option or WaitFor. But you can also use a shortcut: there are special versions of addOption and addWaitFor methods that receive the id of the next step to change to, which saves you the need to create a slot just for that.

When you need to perform something special when a Step is activated, you must define a subclass of Step and redefine the setup() method in it. If something must be performed when a Step is deactivated, you must redefine tearDown() instead.

This may be needed, for example, when a Step needs to use an object that didn't exist when the Tutorial was created (like something in a dialog deleted every time it is closed). In this case, a subclass of Step should be made with a setup() method adding the WaitFor for the "volatile" object. Note, however, that you don't have to remove nor delete the WaitFor added in the setup() method. It is done automatically when the step is deactivated.

 void StepSubclass::setup() {
     QObject* textArea = KTutorial::self()->findObject<QObject*>("textAreaInDialog");

     waitForAttribute = new WaitForSignal(textArea, SIGNAL(textChanged()));
     addWaitFor(waitForAttribute, this, SLOT(startDone()));
 }

Definition at line 134 of file Step.h.

Constructor & Destructor Documentation

ktutorial::Step::Step ( const QString & id ) [explicit]

Creates a new Step with the specified identifier.

The identifier must be unique in the Tutorial this Step belongs to.

Parameters:

id	The identifier of this Step.

Definition at line 38 of file Step.cpp.

References id(), ktutorial::StepPrivate::mActive, ktutorial::StepPrivate::mDeleteAddedObjectsInTearDown, and ktutorial::StepPrivate::mId.

Member Function Documentation

void ktutorial::Step::addOption	(	Option *	option,
		QObject *	receiver,
		const QString &	slot
	)

Adds an Option to this Step.

When the Option is selected by the user, the slot of the receiver object is called. Note that the slot name can be set with or without using the SLOT macro.

The Option is reparented to this Step, and thus deleted when this Step is deleted. However, if the Option is added in the setup() method of a Step derived class, the Option is automatically removed and deleted when the Step is deactivated (that is, you don't have to do it explicitly in the tearDown() method).

If you try to add the same Option (or different ones with the same name) twice, nothing will happen. Only the Option added in first place and its associated slot will be taken in consideration.

This method can be invoked from a script.

Parameters:

option	The Option to add.
receiver	The object to call its slot.
slot	The slot name of the object to call.

Definition at line 84 of file Step.cpp.

References addWaitFor(), ktutorial::StepPrivate::mDeleteAddedObjectsInTearDown, and ktutorial::StepPrivate::mOptionsWaitsFor.

Referenced by addOption().

void ktutorial::Step::addOption	(	Option *	option,
		const QString &	nextStepId
	)

Adds an Option to this Step.

When the Option is selected by the user, the tutorial this Step is part of will activate the step identified by nextStepId.

This method only provides a shortcut to avoid creating an slot that just calls tutorial.nextStep(nextStepId).

In evey other aspect, it behaves like addOption(Option*, QObject*, const QString&). See its documentation for further details.

This method can be invoked from a script.

Parameters:

option	The Option to add.
nextStepId	The id of the step to change to.

See also:: addOption(Option*, QObject*, const QString&)

Definition at line 100 of file Step.cpp.

References addOption(), addWaitFor(), ktutorial::StepPrivate::mDeleteAddedObjectsInTearDown, and ktutorial::StepPrivate::mOptionsWaitsFor.

void ktutorial::Step::addWaitFor	(	WaitFor *	waitFor,
		QObject *	receiver,
		const QString &	slot
	)

Adds a condition to wait for to this Step.

When the condition is met and this Step is active, the slot of the receiver object is called. Note that the slot name can be set with or without using the SLOT macro.

The WaitFor is reparented to this Step, and thus deleted when this Step is deleted. However, if the WaitFor is added in the setup() method of a Step derived class, the WaitFor is automatically removed and deleted when the Step is deactivated (that is, you don't have to do it explicitly in the tearDown() method).

If you try to add the same WaitFor twice, nothing will happen. Only the WaitFor added in first place and its associated slot will be taken in consideration.

This method can be invoked from a script.

Parameters:

waitFor	The condition to wait for.
receiver	The object to call its slot.
slot	The slot name of the object to call.

Definition at line 116 of file Step.cpp.

References connectWaitFor().

Referenced by addOption(), and addWaitFor().

void ktutorial::Step::addWaitFor	(	WaitFor *	waitFor,
		const QString &	nextStepId
	)

Adds a condition to wait for to this Step.

When the condition is met and this Step is active, the tutorial this Step is part of will activate the step identified by nextStepId.

This method only provides a shortcut to avoid creating an slot that just calls tutorial.nextStep(nextStepId).

In evey other aspect, it behaves like addWaitFor(WaitFor*, QObject*, const QString&). See its documentation for further details.

This method can be invoked from a script.

Parameters:

waitFor	The condition to wait for.
nextStepId	The id of the step to change to.

See also:: addOption(Option*, QObject*, const QString&)

Definition at line 124 of file Step.cpp.

References addWaitFor(), and ktutorial::StepPrivate::mNextStepForWaitFor.

void ktutorial::Step::connectWaitFor	(	WaitFor *	waitFor,
		QObject *	receiver,
		const QString &	slot
	)		`[protected, virtual]`

Connects the given WaitFor with the slot in the receiver.

This is a helper method for ScriptedStep, as it has an special behavior when connecting and disconnecting slots. You should not redefine this method in your Step subclasses. Note that the slot name can be set with or without using the SLOT macro.

Parameters:

waitFor	The WaitFor to connect.
receiver	The object to connect to.
slot	The slot to connect to.

Reimplemented in ktutorial::scripting::ScriptedStep.

Definition at line 183 of file Step.cpp.

Referenced by addWaitFor().

void ktutorial::Step::disconnectWaitFor ( WaitFor * waitFor ) [protected, virtual]

Disconnects the given WaitFor.

This is a helper method for ScriptedStep, as it has an special behavior when connecting and disconnecting slots. You should not redefine this method in your Step subclasses.

Parameters:

waitFor The WaitFor to disconnect.

Reimplemented in ktutorial::scripting::ScriptedStep.

Definition at line 194 of file Step.cpp.

Referenced by removeWaitFor().

QString ktutorial::Step::id ( ) const

Returns the identifier of this Step.

Returns:: The identifier of this Step.

Definition at line 49 of file Step.cpp.

References ktutorial::StepPrivate::mId.

Referenced by ktutorial::Tutorial::addStep(), and Step().

bool ktutorial::Step::isActive ( ) const

Returns true if this Step is active, false otherwise.

Returns:: True if this Step is active, false otherwise.

Definition at line 65 of file Step.cpp.

References ktutorial::StepPrivate::mActive.

void ktutorial::Step::nextStepRequested ( const QString & nextStepId ) [signal]

Request a change to the next step.

Don't connect nor emit this signal yourself. It is connected automatically by KTutorial.

Parameters:

nextStepId The id of the Step to request a change to.

QList< Option * > ktutorial::Step::options ( ) const

Returns the Options added to this Step.

Returns:: The Options added to this Step.

Definition at line 53 of file Step.cpp.

References ktutorial::StepPrivate::mOptions.

Referenced by ktutorial::view::StepWidget::setStep().

void ktutorial::Step::removeOption ( Option * option )

Removes an Option from this Step.

The Option is reparented to null, so you must delete it explicitly.

If you try to remove an Option that wasn't added, nothing will happen.

This method can be invoked from a script.

Parameters:

option The Option to remove.

Definition at line 135 of file Step.cpp.

References ktutorial::StepPrivate::mId, ktutorial::StepPrivate::mOptions, ktutorial::StepPrivate::mOptionsWaitsFor, and removeWaitFor().

void ktutorial::Step::removeWaitFor ( WaitFor * waitFor )

Removes a condition to wait for from this Step.

The slot of the receiver object associated when adding the WaitFor will not be notified anymore when the condition is met (note that all the slots connected with waitEnded(WaitFor*) will be disconnected). If the WaitFor was associated with a step id, the tutorial won't change to it anymore when the condition is met. In any case, the WaitFor will be also deactivated.

The WaitFor is reparented to null, so you must delete it explicitly.

If you try to remove a WaitFor that wasn't added, nothing will happen.

This method can be invoked from a script.

Parameters:

waitFor The WaitFor to remove.

Definition at line 154 of file Step.cpp.

References disconnectWaitFor(), ktutorial::StepPrivate::mId, ktutorial::StepPrivate::mNextStepForWaitFor, ktutorial::StepPrivate::mWaitsFor, and ktutorial::WaitFor::setActive().

Referenced by removeOption().

void ktutorial::Step::setActive ( bool active )

Makes this Step active or inactive.

This method is used internally. Do not call this method yourself.

Parameters:

active True if the Step is active, false otherwise.

Definition at line 69 of file Step.cpp.

References ktutorial::StepPrivate::mActive, and ktutorial::StepPrivate::mWaitsFor.

Referenced by ktutorial::Tutorial::finish().

void ktutorial::Step::setText ( const QString & text )

Sets the text to be shown to the user.

Note that if the text is set while this Step is being shown it won't be updated in the GUI. The text will be updated in the GUI the next time this Step is activated.

This method can be invoked from a script.

Parameters: