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

implements some kind of finite automata, where the states of the automata exactly correlate with tab pages. More...

#include <wizardmachine.hxx>

Inheritance diagram for vcl::WizardMachine:
[legend]
Collaboration diagram for vcl::WizardMachine:
[legend]

Classes

class  AccessGuard
 

Public Member Functions

 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...
 
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 DialoggetDialog () override
 
virtual ~AssistantController () override
 
- Public Member Functions inherited from weld::DialogController
virtual DialoggetDialog ()=0
 
const DialoggetConstDialog () 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

virtual void ActivatePage ()
 
virtual bool DeactivatePage ()
 
virtual std::unique_ptr< BuilderPagecreatePage (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
 
BuilderPageGetOrCreatePage (const WizardTypes::WizardState i_nState)
 

Protected Attributes

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
 

Private Member Functions

 DECL_DLLPRIVATE_LINK (OnNextPage, weld::Button &, void)
 
 DECL_DLLPRIVATE_LINK (OnPrevPage, weld::Button &, void)
 
 DECL_DLLPRIVATE_LINK (OnFinish, weld::Button &, void)
 
 DECL_DLLPRIVATE_LINK (OnCancel, weld::Button &, void)
 
VCL_DLLPRIVATE void implUpdateTitle ()
 
VCL_DLLPRIVATE void implConstruct (const WizardButtonFlags _nButtonFlags)
 

Private Attributes

WizardTypes::WizardState m_nCurState
 
WizPageDatam_pFirstPage
 
std::unique_ptr< WizardMachineImplDatam_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)> &)
 

Detailed Description

implements some kind of finite automata, where the states of the automata exactly correlate with tab pages.

That is, the machine can have up to n states, where at each point in time exactly one state is the current one. A state being current is represented as one of n tab pages being displayed currently.

The class handles the UI for traveling between the states (e.g. it administrates the Next and Previous buttons which you usually find in a wizard.

Derived classes have to implement the travel logic by overriding <member>determineNextState</member>, which has to determine the state which follows the current state. Since this may depend on the actual data presented in the wizard (e.g. checkboxes checked, or something like this), they can implement non-linear traveling this way.

Definition at line 119 of file wizardmachine.hxx.

Constructor & Destructor Documentation

◆ WizardMachine()

vcl::WizardMachine::WizardMachine ( weld::Window _pParent,
WizardButtonFlags  _nButtonFlags 
)

Definition at line 797 of file wizardmachine.cxx.

References implConstruct(), and m_pImpl.

◆ ~WizardMachine()

vcl::WizardMachine::~WizardMachine ( )
overridevirtual

Definition at line 867 of file wizardmachine.cxx.

References m_pFirstPage, m_pImpl, WizPageData::mxPage, and RemovePage().

Member Function Documentation

◆ ActivatePage()

void vcl::WizardMachine::ActivatePage ( )
protectedvirtual

Definition at line 934 of file wizardmachine.cxx.

References enterState(), GetOrCreatePage(), and m_nCurState.

Referenced by ShowPage().

◆ AddPage()

void vcl::WizardMachine::AddPage ( std::unique_ptr< BuilderPage xPage)

Definition at line 1349 of file wizardmachine.cxx.

References m_pFirstPage, WizPageData::mpNext, and WizPageData::mxPage.

Referenced by GetOrCreatePage().

◆ canAdvance()

bool vcl::WizardMachine::canAdvance ( ) const
virtual

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

Reimplemented in vcl::RoadmapWizardMachine.

Definition at line 1299 of file wizardmachine.cxx.

References determineNextState(), getCurrentState(), and WZS_INVALID_STATE.

Referenced by enterState(), and updateTravelUI().

◆ createPage()

virtual std::unique_ptr< BuilderPage > vcl::WizardMachine::createPage ( WizardTypes::WizardState  _nState)
protectedpure virtual

to override to create new pages

Referenced by GetOrCreatePage().

◆ DeactivatePage()

bool vcl::WizardMachine::DeactivatePage ( )
protectedvirtual

Definition at line 942 of file wizardmachine.cxx.

References getCurrentState(), and leaveState().

Referenced by Finish(), and ShowPage().

◆ DECL_DLLPRIVATE_LINK() [1/4]

vcl::WizardMachine::DECL_DLLPRIVATE_LINK ( OnCancel  ,
weld::Button ,
void   
)
private

◆ DECL_DLLPRIVATE_LINK() [2/4]

vcl::WizardMachine::DECL_DLLPRIVATE_LINK ( OnFinish  ,
weld::Button ,
void   
)
private

◆ DECL_DLLPRIVATE_LINK() [3/4]

vcl::WizardMachine::DECL_DLLPRIVATE_LINK ( OnNextPage  ,
weld::Button ,
void   
)
private

◆ DECL_DLLPRIVATE_LINK() [4/4]

vcl::WizardMachine::DECL_DLLPRIVATE_LINK ( OnPrevPage  ,
weld::Button ,
void   
)
private

◆ defaultButton() [1/2]

void vcl::WizardMachine::defaultButton ( weld::Button _pNewDefButton)

set the default style for a button

Definition at line 966 of file wizardmachine.cxx.

References weld::AssistantController::m_xAssistant.

◆ defaultButton() [2/2]

void vcl::WizardMachine::defaultButton ( WizardButtonFlags  _nWizardButtonFlags)

set the default style for a button

Definition at line 948 of file wizardmachine.cxx.

References CANCEL, defaultButton(), FINISH, HELP, m_xCancel, m_xFinish, m_xHelp, m_xNextPage, m_xPrevPage, NEXT, and PREVIOUS.

Referenced by defaultButton().

◆ determineNextState()

WizardTypes::WizardState vcl::WizardMachine::determineNextState ( WizardTypes::WizardState  nCurrentState) const
protectedvirtual

determine the next state to travel from the given one

The default behaviour is linear traveling, overwrite this to change it

Return WZS_INVALID_STATE to prevent traveling.

Reimplemented in vcl::RoadmapWizardMachine.

Definition at line 1042 of file wizardmachine.cxx.

Referenced by canAdvance(), skip(), skipUntil(), and travelNext().

◆ enableAutomaticNextButtonState()

void vcl::WizardMachine::enableAutomaticNextButtonState ( )
protected

enables the automatic enabled/disabled state of the "Next" button

If this is <TRUE>, then upon entering a new state, the "Next" button will automatically be enabled if and only if determineNextState does not return WZS_INVALID_STATE.

Definition at line 1256 of file wizardmachine.cxx.

References m_pImpl.

◆ enableButtons()

void vcl::WizardMachine::enableButtons ( WizardButtonFlags  _nWizardButtonFlags,
bool  _bEnable 
)

enable (or disable) buttons

Definition at line 974 of file wizardmachine.cxx.

References CANCEL, FINISH, HELP, m_xCancel, m_xFinish, m_xHelp, m_xNextPage, m_xPrevPage, NEXT, and PREVIOUS.

Referenced by enterState(), updateTravelUI(), and vcl::RoadmapWizardMachine::updateTravelUI().

◆ enterState()

void vcl::WizardMachine::enterState ( WizardTypes::WizardState  _nState)
protectedvirtual

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

Reimplemented in vcl::RoadmapWizardMachine.

Definition at line 988 of file wizardmachine.cxx.

References canAdvance(), enableButtons(), GetPage(), getPageController(), implUpdateTitle(), isAutomaticNextButtonStateEnabled(), m_pImpl, NEXT, and PREVIOUS.

Referenced by ActivatePage(), and vcl::RoadmapWizardMachine::enterState().

◆ Finish()

bool vcl::WizardMachine::Finish ( short  nResult = RET_CANCEL)

◆ getCurrentState()

WizardTypes::WizardState vcl::WizardMachine::getCurrentState ( ) const
inlineprotected

◆ GetOrCreatePage()

BuilderPage * vcl::WizardMachine::GetOrCreatePage ( const WizardTypes::WizardState  i_nState)
protected

◆ GetPage()

BuilderPage * vcl::WizardMachine::GetPage ( WizardTypes::WizardState  eState) const

◆ getPageController()

IWizardPageController * vcl::WizardMachine::getPageController ( BuilderPage pCurrentPage) const
protectedvirtual

◆ getPageIdentForState()

OUString vcl::WizardMachine::getPageIdentForState ( WizardTypes::WizardState  nState) const
protectedvirtual

◆ getStateFromPageIdent()

WizardTypes::WizardState vcl::WizardMachine::getStateFromPageIdent ( const OUString &  rIdent) const
protectedvirtual

Definition at line 902 of file wizardmachine.cxx.

◆ getStateHistory()

void vcl::WizardMachine::getStateHistory ( std::vector< WizardTypes::WizardState > &  out_rHistory)
protected

retrieves a copy of the state history, i.e.

all states we already visited

Definition at line 1289 of file wizardmachine.cxx.

References m_pImpl.

Referenced by vcl::RoadmapWizardMachine::updateTravelUI().

◆ implConstruct()

void vcl::WizardMachine::implConstruct ( const WizardButtonFlags  _nButtonFlags)
private

◆ implUpdateTitle()

void vcl::WizardMachine::implUpdateTitle ( )
private

◆ isAutomaticNextButtonStateEnabled()

bool vcl::WizardMachine::isAutomaticNextButtonStateEnabled ( ) const
protected

Definition at line 1262 of file wizardmachine.cxx.

References m_pImpl.

Referenced by enterState().

◆ isTravelingSuspended()

bool vcl::WizardMachine::isTravelingSuspended ( ) const

Definition at line 1315 of file wizardmachine.cxx.

References m_pImpl.

◆ leaveState()

bool vcl::WizardMachine::leaveState ( WizardTypes::WizardState  nState)
protectedvirtual

will be called when the given state is left

This is the very last possibility for derived classes to veto the deactivation of a page.

Returns
<TRUE> if and only if the page is allowed to be left

Definition at line 1005 of file wizardmachine.cxx.

Referenced by DeactivatePage().

◆ onFinish()

bool vcl::WizardMachine::onFinish ( )
protectedvirtual

called when the finish button is pressed

By default, only the base class' Finish method (which is not virtual) is called

Definition at line 1014 of file wizardmachine.cxx.

References Finish(), and RET_OK.

◆ prepareLeaveCurrentState()

bool vcl::WizardMachine::prepareLeaveCurrentState ( WizardTypes::CommitPageReason  eReason)
protectedvirtual

will be called when the current state is about to be left for the given reason

The base implementation in this class will simply call <member>OWizardPage::commitPage</member> for the current page, and return whatever this call returns.

Parameters
_eReasonThe reason why the state is to be left.
Returns
<TRUE> if and only if the page is allowed to be left

Definition at line 1047 of file wizardmachine.cxx.

References ENSURE_OR_RETURN, getCurrentState(), GetPage(), and getPageController().

Referenced by skip(), skipBackwardUntil(), skipUntil(), travelNext(), and travelPrevious().

◆ RemovePage()

void vcl::WizardMachine::RemovePage ( const BuilderPage pPage)

Definition at line 1366 of file wizardmachine.cxx.

References m_pCurTabPage, m_pFirstPage, WizPageData::mpNext, and WizPageData::mxPage.

Referenced by ~WizardMachine().

◆ removePageFromHistory()

void vcl::WizardMachine::removePageFromHistory ( WizardTypes::WizardState  nToRemove)
protected

removes a page from the history.

Should be called when the page is being disabled

Definition at line 1235 of file wizardmachine.cxx.

References m_pImpl.

Referenced by vcl::RoadmapWizardMachine::enableState().

◆ resumeTraveling()

void vcl::WizardMachine::resumeTraveling ( AccessGuard  )

Definition at line 1326 of file wizardmachine.cxx.

References DBG_ASSERT, and m_pImpl.

Referenced by vcl::WizardTravelSuspension::~WizardTravelSuspension().

◆ SetPage()

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

Definition at line 1391 of file wizardmachine.cxx.

References m_pCurTabPage, m_pFirstPage, WizPageData::mpNext, and WizPageData::mxPage.

Referenced by GetOrCreatePage().

◆ setTitleBase()

void vcl::WizardMachine::setTitleBase ( const OUString &  _rTitleBase)

set the base of the title to use - the title of the current page is appended

Definition at line 891 of file wizardmachine.cxx.

References implUpdateTitle(), and m_pImpl.

◆ ShowNextPage()

bool vcl::WizardMachine::ShowNextPage ( )

Definition at line 1198 of file wizardmachine.cxx.

References m_nCurState, and ShowPage().

◆ ShowPage()

bool vcl::WizardMachine::ShowPage ( WizardTypes::WizardState  nState)

◆ ShowPrevPage()

bool vcl::WizardMachine::ShowPrevPage ( )

Definition at line 1203 of file wizardmachine.cxx.

References m_nCurState, and ShowPage().

◆ skip()

void vcl::WizardMachine::skip ( )
protected

skip a state

The method behaves as if from the current state, <arg>_nSteps</arg> <method>travelNext</method>s were called, but without actually creating or displaying the \EDntermediate pages. Only the (<arg>_nSteps</arg> + 1)th page is created.

The skipped states appear in the state history, so <method>travelPrevious</method> will make use of them.

A very essential precondition for using this method is that your <method>determineNextState</method> method is able to determine the next state without actually having the page of the current state.

See also
skipUntil
skipBackwardUntil

Definition at line 1119 of file wizardmachine.cxx.

References determineNextState(), vcl::WizardTypes::eTravelForward, getCurrentState(), m_pImpl, prepareLeaveCurrentState(), ShowPage(), and WZS_INVALID_STATE.

◆ skipBackwardUntil()

bool vcl::WizardMachine::skipBackwardUntil ( WizardTypes::WizardState  nTargetState)
protected

moves back one or more states, until a given state is reached

This method allows traveling backwards more than one state without actually showing the intermediate states.

For instance, if you want to travel two steps backward at a time, you could used two travelPrevious calls, but this would show both pages, which is not necessary, since you're interested in the target page only. Using <member>skipBackwardUntil</member> relieves you of this.

Returns
<TRUE> if and only if traveling was successful
See also
skipUntil
skip

Definition at line 1054 of file wizardmachine.cxx.

References DBG_ASSERT, vcl::WizardTypes::eTravelBackward, getCurrentState(), m_pImpl, prepareLeaveCurrentState(), and ShowPage().

◆ skipUntil()

bool vcl::WizardMachine::skipUntil ( WizardTypes::WizardState  nTargetState)
protected

skips one or more states, until a given state is reached

The method behaves as if from the current state, <method>travelNext</method>s were called successively, until <arg>_nTargetState</arg> is reached, but without actually creating or displaying the \EDntermediate pages.

The skipped states appear in the state history, so <method>travelPrevious</method> will make use of them.

Returns
<TRUE> if and only if traveling was successful
See also
skip
skipBackwardUntil

Definition at line 1080 of file wizardmachine.cxx.

References determineNextState(), vcl::WizardTypes::eTravelBackward, vcl::WizardTypes::eTravelForward, getCurrentState(), m_pImpl, prepareLeaveCurrentState(), ShowPage(), and WZS_INVALID_STATE.

◆ suspendTraveling()

void vcl::WizardMachine::suspendTraveling ( AccessGuard  )

Definition at line 1320 of file wizardmachine.cxx.

References DBG_ASSERT, and m_pImpl.

Referenced by vcl::WizardTravelSuspension::WizardTravelSuspension().

◆ travelNext()

bool vcl::WizardMachine::travelNext ( )
protected

◆ travelPrevious()

bool vcl::WizardMachine::travelPrevious ( )
protected

travel to the previous state

Definition at line 1210 of file wizardmachine.cxx.

References DBG_ASSERT, vcl::WizardTypes::eTravelBackward, m_pImpl, prepareLeaveCurrentState(), and ShowPage().

◆ updateTravelUI()

void vcl::WizardMachine::updateTravelUI ( )
virtual

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 in vcl::RoadmapWizardMachine.

Definition at line 1304 of file wizardmachine.cxx.

References canAdvance(), enableButtons(), getCurrentState(), GetPage(), getPageController(), and NEXT.

Referenced by vcl::RoadmapWizardMachine::updateTravelUI().

Member Data Documentation

◆ m_nCurState

WizardTypes::WizardState vcl::WizardMachine::m_nCurState
private

Definition at line 124 of file wizardmachine.hxx.

Referenced by ActivatePage(), ShowNextPage(), ShowPage(), and ShowPrevPage().

◆ m_pCurTabPage

BuilderPage* vcl::WizardMachine::m_pCurTabPage
protected

Definition at line 122 of file wizardmachine.hxx.

Referenced by Finish(), RemovePage(), SetPage(), and ShowPage().

◆ m_pFirstPage

WizPageData* vcl::WizardMachine::m_pFirstPage
private

Definition at line 125 of file wizardmachine.hxx.

Referenced by AddPage(), GetPage(), RemovePage(), SetPage(), and ~WizardMachine().

◆ m_pImpl

std::unique_ptr<WizardMachineImplData> vcl::WizardMachine::m_pImpl
private

◆ m_xCancel

std::unique_ptr<weld::Button> vcl::WizardMachine::m_xCancel
protected

Definition at line 129 of file wizardmachine.hxx.

Referenced by defaultButton(), enableButtons(), and implConstruct().

◆ m_xFinish

std::unique_ptr<weld::Button> vcl::WizardMachine::m_xFinish
protected

Definition at line 128 of file wizardmachine.hxx.

Referenced by defaultButton(), enableButtons(), and implConstruct().

◆ m_xHelp

std::unique_ptr<weld::Button> vcl::WizardMachine::m_xHelp
protected

Definition at line 132 of file wizardmachine.hxx.

Referenced by defaultButton(), enableButtons(), and implConstruct().

◆ m_xNextPage

std::unique_ptr<weld::Button> vcl::WizardMachine::m_xNextPage
protected

Definition at line 130 of file wizardmachine.hxx.

Referenced by defaultButton(), enableButtons(), and implConstruct().

◆ m_xPrevPage

std::unique_ptr<weld::Button> vcl::WizardMachine::m_xPrevPage
protected

Definition at line 131 of file wizardmachine.hxx.

Referenced by defaultButton(), enableButtons(), and implConstruct().


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