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

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

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 120 of file wizardmachine.hxx.

Constructor & Destructor Documentation

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

Definition at line 934 of file wizardmachine.cxx.

References implConstruct(), and m_pImpl.

vcl::WizardMachine::~WizardMachine ( )
overridevirtual

Definition at line 1004 of file wizardmachine.cxx.

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

Member Function Documentation

void vcl::WizardMachine::ActivatePage ( )
protectedvirtual

Definition at line 1061 of file wizardmachine.cxx.

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

Referenced by ShowPage().

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

Definition at line 1473 of file wizardmachine.cxx.

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

Referenced by GetOrCreatePage().

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 1426 of file wizardmachine.cxx.

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

Referenced by enterState(), and updateTravelUI().

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

to override to create new pages

Referenced by GetOrCreatePage().

bool vcl::WizardMachine::DeactivatePage ( )
protectedvirtual

Definition at line 1069 of file wizardmachine.cxx.

References getCurrentState(), and leaveState().

Referenced by Finish(), and ShowPage().

vcl::WizardMachine::DECL_DLLPRIVATE_LINK ( OnNextPage  ,
weld::Button ,
void   
)
private
vcl::WizardMachine::DECL_DLLPRIVATE_LINK ( OnPrevPage  ,
weld::Button ,
void   
)
private
vcl::WizardMachine::DECL_DLLPRIVATE_LINK ( OnFinish  ,
weld::Button ,
void   
)
private
vcl::WizardMachine::DECL_DLLPRIVATE_LINK ( OnCancel  ,
weld::Button ,
void   
)
private
void vcl::WizardMachine::defaultButton ( WizardButtonFlags  _nWizardButtonFlags)

set the default style for a button

Definition at line 1075 of file wizardmachine.cxx.

References CANCEL, FINISH, HELP, weld::AssistantController::m_xAssistant, m_xCancel, m_xFinish, m_xHelp, m_xNextPage, m_xPrevPage, NEXT, and PREVIOUS.

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

set the default style for a button

Definition at line 1096 of file wizardmachine.cxx.

References weld::AssistantController::m_xAssistant, and weld::Widget::set_has_default().

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 1169 of file wizardmachine.cxx.

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

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 1383 of file wizardmachine.cxx.

References m_pImpl.

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

enable (or disable) buttons

Definition at line 1107 of file wizardmachine.cxx.

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

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

void vcl::WizardMachine::enterState ( WizardTypes::WizardState  _nState)
protectedvirtual
bool vcl::WizardMachine::Finish ( short  nResult = RET_CANCEL)
WizardTypes::WizardState vcl::WizardMachine::getCurrentState ( ) const
inlineprotected
BuilderPage * vcl::WizardMachine::GetOrCreatePage ( const WizardTypes::WizardState  i_nState)
protected
BuilderPage * vcl::WizardMachine::GetPage ( WizardTypes::WizardState  eState) const
IWizardPageController * vcl::WizardMachine::getPageController ( BuilderPage pCurrentPage) const
protectedvirtual
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 1416 of file wizardmachine.cxx.

References m_pImpl.

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

void vcl::WizardMachine::implConstruct ( const WizardButtonFlags  _nButtonFlags)
private
void vcl::WizardMachine::implUpdateTitle ( )
private
bool vcl::WizardMachine::isAutomaticNextButtonStateEnabled ( ) const
protected

Definition at line 1389 of file wizardmachine.cxx.

References m_pImpl.

Referenced by enterState().

bool vcl::WizardMachine::isTravelingSuspended ( ) const

Definition at line 1442 of file wizardmachine.cxx.

References m_pImpl.

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 1138 of file wizardmachine.cxx.

Referenced by DeactivatePage().

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 1147 of file wizardmachine.cxx.

References Finish(), and RET_OK.

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 1174 of file wizardmachine.cxx.

References vcl::IWizardPageController::commitPage(), ENSURE_OR_RETURN, getCurrentState(), GetPage(), and getPageController().

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

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

Definition at line 1490 of file wizardmachine.cxx.

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

Referenced by ~WizardMachine().

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 1362 of file wizardmachine.cxx.

References m_pImpl.

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

void vcl::WizardMachine::resumeTraveling ( AccessGuard  )

Definition at line 1453 of file wizardmachine.cxx.

References DBG_ASSERT, and m_pImpl.

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

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

Definition at line 1515 of file wizardmachine.cxx.

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

Referenced by GetOrCreatePage().

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 1028 of file wizardmachine.cxx.

References implUpdateTitle(), and m_pImpl.

bool vcl::WizardMachine::ShowNextPage ( )

Definition at line 1325 of file wizardmachine.cxx.

References m_nCurState, and ShowPage().

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

Definition at line 1330 of file wizardmachine.cxx.

References m_nCurState, and ShowPage().

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 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 1246 of file wizardmachine.cxx.

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

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 1181 of file wizardmachine.cxx.

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

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 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 1207 of file wizardmachine.cxx.

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

void vcl::WizardMachine::suspendTraveling ( AccessGuard  )

Definition at line 1447 of file wizardmachine.cxx.

References DBG_ASSERT, and m_pImpl.

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

bool vcl::WizardMachine::travelNext ( )
protected
bool vcl::WizardMachine::travelPrevious ( )
protected

travel to the previous state

Definition at line 1337 of file wizardmachine.cxx.

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

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 1431 of file wizardmachine.cxx.

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

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

Member Data Documentation

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

Definition at line 125 of file wizardmachine.hxx.

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

BuilderPage* vcl::WizardMachine::m_pCurTabPage
protected

Definition at line 123 of file wizardmachine.hxx.

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

WizPageData* vcl::WizardMachine::m_pFirstPage
private

Definition at line 126 of file wizardmachine.hxx.

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

std::unique_ptr<WizardMachineImplData> vcl::WizardMachine::m_pImpl
private
std::unique_ptr<weld::Button> vcl::WizardMachine::m_xCancel
protected

Definition at line 130 of file wizardmachine.hxx.

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

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

Definition at line 129 of file wizardmachine.hxx.

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

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

Definition at line 133 of file wizardmachine.hxx.

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

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

Definition at line 131 of file wizardmachine.hxx.

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

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

Definition at line 132 of file wizardmachine.hxx.

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


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