is - no, not a wizard for a roadmap, but the base class for wizards supporting a roadmap. More...

#include <roadmapwizard.hxx>

Inheritance diagram for vcl::RoadmapWizardMachine:

Collaboration diagram for vcl::RoadmapWizardMachine:

Public Member Functions
	RoadmapWizardMachine (weld::Window *_pParent)

virtual	~RoadmapWizardMachine () override

void	SetRoadmapHelpId (const OUString &_rId)

bool	isStateEnabled (WizardTypes::WizardState nState) const

virtual bool	canAdvance () const override
	determines whether there is a next state to which we can advance More...

virtual void	updateTravelUI () override
	updates the user interface which deals with traveling in the wizard More...

Public Member Functions inherited from vcl::WizardMachine
	WizardMachine (weld::Window *_pParent, WizardButtonFlags _nButtonFlags)

virtual	~WizardMachine () override

bool	Finish (short nResult=RET_CANCEL)

bool	ShowPage (WizardTypes::WizardState nState)

bool	ShowNextPage ()

bool	ShowPrevPage ()

void	AddPage (std::unique_ptr< BuilderPage > xPage)

void	RemovePage (const BuilderPage *pPage)

void	SetPage (WizardTypes::WizardState nLevel, std::unique_ptr< BuilderPage > xPage)

BuilderPage *	GetPage (WizardTypes::WizardState eState) const

void	enableButtons (WizardButtonFlags _nWizardButtonFlags, bool _bEnable)
	enable (or disable) buttons More...

void	defaultButton (WizardButtonFlags _nWizardButtonFlags)
	set the default style for a button More...

void	defaultButton (weld::Button *_pNewDefButton)
	set the default style for a button More...

void	setTitleBase (const OUString &_rTitleBase)
	set the base of the title to use - the title of the current page is appended More...

virtual bool	canAdvance () const
	determines whether there is a next state to which we can advance More...

virtual void	updateTravelUI ()
	updates the user interface which deals with traveling in the wizard More...

void	suspendTraveling (AccessGuard)

void	resumeTraveling (AccessGuard)

bool	isTravelingSuspended () const

Public Member Functions inherited from weld::AssistantController
	AssistantController (weld::Widget *pParent, const OUString &rUIFile, const OUString &rDialogId)

virtual Dialog *	getDialog () override

virtual	~AssistantController () override

Public Member Functions inherited from weld::DialogController
virtual Dialog *	getDialog ()=0

const Dialog *	getConstDialog () const

virtual short	run ()

void	set_title (const OUString &rTitle)

OUString	get_title () const

void	set_help_id (const OUString &rHelpId)

OUString	get_help_id () const

void	response (int nResponse)

virtual	~DialogController () COVERITY_NOEXCEPT_FALSE

Protected Member Functions
void	declarePath (RoadmapWizardTypes::PathId _nPathId, const RoadmapWizardTypes::WizardPath &_lWizardStates)
	declares a valid path in the wizard More...

void	activatePath (RoadmapWizardTypes::PathId _nPathId, bool _bDecideForIt=false)
	activates a path which has previously been declared with <member>declarePath</member> More...

virtual WizardTypes::WizardState	determineNextState (WizardTypes::WizardState nCurrentState) const override
	determine the next state to travel from the given one More...

void	enableState (WizardTypes::WizardState nState, bool _bEnable=true)
	en- or disables a state More...

bool	knowsState (WizardTypes::WizardState nState) const
	returns true if and only if the given state is known in at least one declared path More...

virtual void	enterState (WizardTypes::WizardState nState) override
	will be called when a new page is about to be displayed More...

virtual OUString	getStateDisplayName (WizardTypes::WizardState nState) const
	returns a human readable name for a given state More...

Protected Member Functions inherited from vcl::WizardMachine
virtual void	ActivatePage ()

virtual bool	DeactivatePage ()

virtual std::unique_ptr< BuilderPage >	createPage (WizardTypes::WizardState _nState)=0
	to override to create new pages More...

virtual void	enterState (WizardTypes::WizardState _nState)
	will be called when a new page is about to be displayed More...

virtual bool	prepareLeaveCurrentState (WizardTypes::CommitPageReason eReason)
	will be called when the current state is about to be left for the given reason More...

virtual bool	leaveState (WizardTypes::WizardState nState)
	will be called when the given state is left More...

virtual WizardTypes::WizardState	determineNextState (WizardTypes::WizardState nCurrentState) const
	determine the next state to travel from the given one More...

virtual bool	onFinish ()
	called when the finish button is pressed More...

bool	travelNext ()
	travel to the next state More...

bool	travelPrevious ()
	travel to the previous state More...

void	enableAutomaticNextButtonState ()
	enables the automatic enabled/disabled state of the "Next" button More...

bool	isAutomaticNextButtonStateEnabled () const

void	removePageFromHistory (WizardTypes::WizardState nToRemove)
	removes a page from the history. More...

void	skip ()
	skip a state More...

bool	skipUntil (WizardTypes::WizardState nTargetState)
	skips one or more states, until a given state is reached More...

bool	skipBackwardUntil (WizardTypes::WizardState nTargetState)
	moves back one or more states, until a given state is reached More...

WizardTypes::WizardState	getCurrentState () const
	returns the current state of the machine More...

virtual IWizardPageController *	getPageController (BuilderPage *pCurrentPage) const

void	getStateHistory (std::vector< WizardTypes::WizardState > &out_rHistory)
	retrieves a copy of the state history, i.e. More...

virtual OUString	getPageIdentForState (WizardTypes::WizardState nState) const

virtual WizardTypes::WizardState	getStateFromPageIdent (const OUString &rIdent) const

BuilderPage *	GetOrCreatePage (const WizardTypes::WizardState i_nState)

Private Member Functions
	DECL_DLLPRIVATE_LINK (OnRoadmapItemSelected, const OUString &, bool)

VCL_DLLPRIVATE void	implUpdateRoadmap ()
	updates the roadmap control to show the given path, as far as possible (modulo conflicts with other paths) More...

Private Attributes
std::unique_ptr< RoadmapWizardImpl >	m_pImpl

Additional Inherited Members
Static Public Member Functions inherited from weld::DialogController
static bool	runAsync (const std::shared_ptr< DialogController > &rController, const std::function< void(sal_Int32)> &)

Protected Attributes inherited from vcl::WizardMachine
BuilderPage *	m_pCurTabPage

std::unique_ptr< weld::Button >	m_xFinish

std::unique_ptr< weld::Button >	m_xCancel

std::unique_ptr< weld::Button >	m_xNextPage

std::unique_ptr< weld::Button >	m_xPrevPage

std::unique_ptr< weld::Button >	m_xHelp

Protected Attributes inherited from weld::AssistantController
std::unique_ptr< weld::Builder >	m_xBuilder

std::unique_ptr< weld::Assistant >	m_xAssistant

Detailed Description

is - no, not a wizard for a roadmap, but the base class for wizards supporting a roadmap.

The basic new concept introduced is a path:
A path is a sequence of states, which are to be executed in a linear order. Elements in the path can be skipped, depending on choices the user makes.

In the most simple wizards, you will have only one path consisting of n elements, which are to be visited successively.

In a slightly more complex wizard, you will have one linear path, were certain steps might be skipped due to user input. For instance, the user may decide to not specify certain aspects of the to-be-created object (e.g. by unchecking a check box), and the wizard then will simply disable the step which corresponds to this step.

In a yet more advanced wizards, you will have several paths of length n1 and n2, which share at least the first k states (where k is at least 1), and an arbitrary number of other states.

Definition at line 58 of file roadmapwizard.hxx.

Constructor & Destructor Documentation

◆ RoadmapWizardMachine()

vcl::RoadmapWizardMachine::RoadmapWizardMachine ( weld::Window * _pParent )

Definition at line 167 of file roadmapwizard.cxx.

References CANCEL, FINISH, HELP, LINK, m_pImpl, weld::AssistantController::m_xAssistant, NEXT, and PREVIOUS.

◆ ~RoadmapWizardMachine()

vcl::RoadmapWizardMachine::~RoadmapWizardMachine ( )

overridevirtual

Definition at line 185 of file roadmapwizard.cxx.

Member Function Documentation

◆ activatePath()

void vcl::RoadmapWizardMachine::activatePath	(	RoadmapWizardTypes::PathId	_nPathId,
		bool	_bDecideForIt = `false`
	)

protected

activates a path which has previously been declared with <member>declarePath</member>

You can only activate paths which share the first k states with the path which is previously active (if any), where k is the index of the current state within the current path.

Say you have paths,

(0,1,2,5)

and

(0,1,4,5)

. This means that after step

1

, you either continue with state

2

or state

4

, and after this, you finish in state

5

.
Now if the first path is active, and your current state is

1

, then you can easily switch to the second path, since both paths start with

(0,1)

.
However, if your current state is

2

, then you can not switch to the second path anymore.

Parameters

_nPathId the id of the path. The path must have been declared (under this id) with <member>declarePath</member> before it can be activated.

_bDecideForIt

If <TRUE>, the path will be completely activated, even if it is a conflicting path (i.e. there is another path which shares the first

k

states with the to-be-activated path.)
If <FALSE>, then the new path is checked for conflicts with other paths. If such conflicts exists, the path is not completely activated, but only up to the point where it does not conflict.
With the paths in the example above, if you activate the second path (when both are already declared), then only steps

0

and

1

are activated, since they are common to both paths.

Definition at line 253 of file roadmapwizard.cxx.

References DBG_ASSERT, vcl::WizardMachine::getCurrentState(), vcl::RoadmapWizardImpl::getFirstDifferentIndex(), implUpdateRoadmap(), and m_pImpl.

Referenced by declarePath().

◆ canAdvance()

bool vcl::RoadmapWizardMachine::canAdvance ( ) const

overridevirtual

determines whether there is a next state to which we can advance

Reimplemented from vcl::WizardMachine.

Definition at line 544 of file roadmapwizard.cxx.

References vcl::WizardMachine::getCurrentState(), vcl::RoadmapWizardImpl::getFirstDifferentIndex(), vcl::RoadmapWizardImpl::getStateIndexInPath(), and m_pImpl.

◆ DECL_DLLPRIVATE_LINK()

vcl::RoadmapWizardMachine::DECL_DLLPRIVATE_LINK	(	OnRoadmapItemSelected	,
		const OUString &	,
		bool
	)

private

◆ declarePath()

void vcl::RoadmapWizardMachine::declarePath	(	RoadmapWizardTypes::PathId	_nPathId,
		const RoadmapWizardTypes::WizardPath &	_lWizardStates
	)

protected

declares a valid path in the wizard

The very first path which is declared is automatically activated.

Note that all paths which are declared must have the very first state in common. Also note that due to a restriction of the very base class (WizardDialog), this common first state must be 0.

You cannot declare new paths once the wizard started, so it's recommended that you do all declarations within your derivee's constructor.

See also: activatePath

Parameters

_nId	the unique id you wish to give this path. This id can later on be used to refer to the path which you just declared

Definition at line 242 of file roadmapwizard.cxx.

References activatePath(), implUpdateRoadmap(), and m_pImpl.

◆ determineNextState()

WizardTypes::WizardState vcl::RoadmapWizardMachine::determineNextState ( WizardTypes::WizardState nCurrentState ) const

overrideprotectedvirtual

determine the next state to travel from the given one

This method (which is declared in WizardMachine and overwritten here) ensures that traveling happens along the active path.

See also: activatePath

Reimplemented from vcl::WizardMachine.

Definition at line 516 of file roadmapwizard.cxx.

References DBG_ASSERT, vcl::RoadmapWizardImpl::getStateIndexInPath(), m_pImpl, and WZS_INVALID_STATE.

◆ enableState()

void vcl::RoadmapWizardMachine::enableState	(	WizardTypes::WizardState	nState,
		bool	_bEnable = `true`
	)

protected

en- or disables a state

In the wizard's roadmap, states to travel to can be freely chosen. To prevent users from selecting a state which is currently not available, you can declare this state as being disabled.

A situation where you need this may be when you have a checkbox which, when checked by the user, enables a page with additional settings. As long as this checkbox is not checked, the respective state would be disabled.

Note that in theory, you can declare multiple paths, instead of disabling states. For instance, if you have a path where one state can be potentially disabled, then you could declare a second path, which does not contain this state. However, the disadvantage is that then, not the complete path would be visible in the roadmap, but only all steps up to the point where the both paths diverge.
Another disadvantage is that the number of needed paths grows exponentially with the number of states which can be potentially disabled.

See also: declarePath

Definition at line 738 of file roadmapwizard.cxx.

References vcl::WizardMachine::getPageIdentForState(), m_pImpl, weld::AssistantController::m_xAssistant, and vcl::WizardMachine::removePageFromHistory().

◆ enterState()

void vcl::RoadmapWizardMachine::enterState ( WizardTypes::WizardState _nState )

overrideprotectedvirtual

will be called when a new page is about to be displayed

Reimplemented from vcl::WizardMachine.

Definition at line 688 of file roadmapwizard.cxx.

References vcl::WizardMachine::enterState(), and implUpdateRoadmap().

◆ getStateDisplayName()

OUString vcl::RoadmapWizardMachine::getStateDisplayName ( WizardTypes::WizardState nState ) const

protectedvirtual

returns a human readable name for a given state

There is a default implementation for this method, which returns the display name as given in a call to describeState. If there is no description for the given state, this is worth an assertion in a non-product build, and then an empty string is returned.

Definition at line 709 of file roadmapwizard.cxx.

References m_pImpl, pos, and sDisplayName.

Referenced by implUpdateRoadmap().

◆ implUpdateRoadmap()

void vcl::RoadmapWizardMachine::implUpdateRoadmap ( )

private

updates the roadmap control to show the given path, as far as possible (modulo conflicts with other paths)

Definition at line 383 of file roadmapwizard.cxx.

References DBG_ASSERT, vcl::WizardMachine::getCurrentState(), vcl::RoadmapWizardImpl::getFirstDifferentIndex(), vcl::WizardMachine::GetOrCreatePage(), vcl::WizardMachine::GetPage(), vcl::WizardMachine::getPageController(), vcl::WizardMachine::getPageIdentForState(), getStateDisplayName(), vcl::RoadmapWizardImpl::getStateIndexInPath(), i, m_pImpl, weld::AssistantController::m_xAssistant, and nState.

Referenced by activatePath(), declarePath(), enterState(), and updateTravelUI().

◆ isStateEnabled()

bool vcl::RoadmapWizardMachine::isStateEnabled ( WizardTypes::WizardState nState ) const

Definition at line 766 of file roadmapwizard.cxx.

References m_pImpl.

Referenced by updateTravelUI().

◆ knowsState()

bool vcl::RoadmapWizardMachine::knowsState ( WizardTypes::WizardState nState ) const

protected

returns true if and only if the given state is known in at least one declared path

Definition at line 753 of file roadmapwizard.cxx.

References m_pImpl.

◆ SetRoadmapHelpId()

void vcl::RoadmapWizardMachine::SetRoadmapHelpId ( const OUString & _rId )

Definition at line 237 of file roadmapwizard.cxx.

References weld::AssistantController::m_xAssistant.

◆ updateTravelUI()

void vcl::RoadmapWizardMachine::updateTravelUI ( )

overridevirtual

updates the user interface which deals with traveling in the wizard

The default implementation simply checks whether both the current page and the wizard itself allow to advance to the next state (canAdvance), and enables the "Next" button if and only if this is the case.

Reimplemented from vcl::WizardMachine.

Definition at line 579 of file roadmapwizard.cxx.

References vcl::WizardMachine::enableButtons(), vcl::WizardMachine::getStateHistory(), implUpdateRoadmap(), isStateEnabled(), PREVIOUS, and vcl::WizardMachine::updateTravelUI().

Referenced by vcl::OWizardPage::updateDialogTravelUI().

Member Data Documentation

◆ m_pImpl

std::unique_ptr<RoadmapWizardImpl> vcl::RoadmapWizardMachine::m_pImpl

private

Definition at line 61 of file roadmapwizard.hxx.

Referenced by activatePath(), canAdvance(), declarePath(), determineNextState(), enableState(), getStateDisplayName(), implUpdateRoadmap(), isStateEnabled(), and knowsState().

The documentation for this class was generated from the following files:

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ RoadmapWizardMachine()

◆ ~RoadmapWizardMachine()

Member Function Documentation

◆ activatePath()

◆ canAdvance()

◆ DECL_DLLPRIVATE_LINK()

◆ declarePath()

◆ determineNextState()

◆ enableState()

◆ enterState()

◆ getStateDisplayName()

◆ implUpdateRoadmap()

◆ isStateEnabled()

◆ knowsState()

◆ SetRoadmapHelpId()

◆ updateTravelUI()

Member Data Documentation

◆ m_pImpl