LibreOffice Module vcl (master)  1
Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | List of all members
vcl::RoadmapWizardMachine Class Reference

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:
[legend]
Collaboration diagram for vcl::RoadmapWizardMachine:
[legend]

Public Member Functions

 RoadmapWizardMachine (weld::Window *_pParent)
 
virtual ~RoadmapWizardMachine () override
 
void SetRoadmapHelpId (const OString &_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)
 
BuilderPageGetPage (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...
 
void suspendTraveling (AccessGuard)
 
void resumeTraveling (AccessGuard)
 
bool isTravelingSuspended () const
 
- Public Member Functions inherited from weld::AssistantController
 AssistantController (weld::Widget *pParent, const OUString &rUIFile, const OString &rDialogId)
 
virtual DialoggetDialog () override
 
virtual ~AssistantController () override
 
- Public Member Functions inherited from weld::DialogController
const DialoggetConstDialog () const
 
virtual short run ()
 
void set_title (const OUString &rTitle)
 
OUString get_title () const
 
void set_help_id (const OString &rHelpId)
 
OString 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< BuilderPagecreatePage (WizardTypes::WizardState _nState)=0
 to override to create new pages 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 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 IWizardPageControllergetPageController (BuilderPage *pCurrentPage) const
 
void getStateHistory (std::vector< WizardTypes::WizardState > &out_rHistory)
 retrieves a copy of the state history, i.e. More...
 
BuilderPageGetOrCreatePage (const WizardTypes::WizardState i_nState)
 

Private Member Functions

 DECL_DLLPRIVATE_LINK (OnRoadmapItemSelected, const OString &, 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< RoadmapWizardImplm_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
BuilderPagem_pCurTabPage
 
std::unique_ptr< weld::Buttonm_xFinish
 
std::unique_ptr< weld::Buttonm_xCancel
 
std::unique_ptr< weld::Buttonm_xNextPage
 
std::unique_ptr< weld::Buttonm_xPrevPage
 
std::unique_ptr< weld::Buttonm_xHelp
 
- Protected Attributes inherited from weld::AssistantController
std::unique_ptr< weld::Builderm_xBuilder
 
std::unique_ptr< weld::Assistantm_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

vcl::RoadmapWizardMachine::RoadmapWizardMachine ( weld::Window _pParent)
vcl::RoadmapWizardMachine::~RoadmapWizardMachine ( )
overridevirtual

Definition at line 177 of file roadmapwizard.cxx.

Member Function Documentation

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
_nPathIdthe id of the path. The path must have been declared (under this id) with <member>declarePath</member> before it can be activated.
_bDecideForItIf <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 240 of file roadmapwizard.cxx.

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

Referenced by declarePath().

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 577 of file roadmapwizard.cxx.

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

vcl::RoadmapWizardMachine::DECL_DLLPRIVATE_LINK ( OnRoadmapItemSelected  ,
const OString &  ,
bool   
)
private
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
_nIdthe 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 229 of file roadmapwizard.cxx.

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

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 519 of file roadmapwizard.cxx.

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

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 781 of file roadmapwizard.cxx.

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

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 731 of file roadmapwizard.cxx.

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

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 752 of file roadmapwizard.cxx.

References m_pImpl, and sDisplayName.

Referenced by implUpdateRoadmap().

void vcl::RoadmapWizardMachine::implUpdateRoadmap ( )
private
bool vcl::RoadmapWizardMachine::isStateEnabled ( WizardTypes::WizardState  nState) const

Definition at line 809 of file roadmapwizard.cxx.

References m_pImpl.

Referenced by updateTravelUI().

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 796 of file roadmapwizard.cxx.

References m_pImpl.

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

Definition at line 224 of file roadmapwizard.cxx.

References weld::AssistantController::m_xAssistant.

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 607 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

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

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