LibreOffice Module vcl (master) 1
|
implements some kind of finite automata, where the states of the automata exactly correlate with tab pages. More...
#include <wizardmachine.hxx>
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) |
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 | |
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) |
Protected Attributes | |
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 |
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 |
WizPageData * | m_pFirstPage |
std::unique_ptr< WizardMachineImplData > | 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)> &) |
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.
vcl::WizardMachine::WizardMachine | ( | weld::Window * | _pParent, |
WizardButtonFlags | _nButtonFlags | ||
) |
Definition at line 797 of file wizardmachine.cxx.
References implConstruct(), and m_pImpl.
|
overridevirtual |
Definition at line 867 of file wizardmachine.cxx.
References m_pFirstPage, m_pImpl, WizPageData::mxPage, and RemovePage().
|
protectedvirtual |
Definition at line 934 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 1349 of file wizardmachine.cxx.
References m_pFirstPage, WizPageData::mpNext, and WizPageData::mxPage.
Referenced by GetOrCreatePage().
|
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().
|
protectedpure virtual |
to override to create new pages
Referenced by GetOrCreatePage().
|
protectedvirtual |
Definition at line 942 of file wizardmachine.cxx.
References getCurrentState(), and leaveState().
Referenced by Finish(), and ShowPage().
|
private |
|
private |
|
private |
|
private |
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.
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().
|
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().
|
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.
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().
|
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().
bool vcl::WizardMachine::Finish | ( | short | nResult = RET_CANCEL | ) |
Definition at line 1335 of file wizardmachine.cxx.
References BuilderPage::Deactivate(), DeactivatePage(), m_pCurTabPage, and weld::AssistantController::m_xAssistant.
Referenced by onFinish().
|
inlineprotected |
returns the current state of the machine
Vulgo, this is the identifier of the current tab page :)
Definition at line 297 of file wizardmachine.hxx.
Referenced by vcl::RoadmapWizardMachine::activatePath(), canAdvance(), vcl::RoadmapWizardMachine::canAdvance(), DeactivatePage(), vcl::RoadmapWizardMachine::implUpdateRoadmap(), implUpdateTitle(), prepareLeaveCurrentState(), skip(), skipBackwardUntil(), skipUntil(), travelNext(), and updateTravelUI().
|
protected |
Definition at line 907 of file wizardmachine.cxx.
References AddPage(), createPage(), DBG_ASSERT, GetPage(), m_pImpl, and SetPage().
Referenced by ActivatePage(), and vcl::RoadmapWizardMachine::implUpdateRoadmap().
BuilderPage * vcl::WizardMachine::GetPage | ( | WizardTypes::WizardState | eState | ) | const |
Definition at line 1412 of file wizardmachine.cxx.
References m_pFirstPage, and WizPageData::mpNext.
Referenced by enterState(), GetOrCreatePage(), vcl::RoadmapWizardMachine::implUpdateRoadmap(), implUpdateTitle(), prepareLeaveCurrentState(), ShowPage(), and updateTravelUI().
|
protectedvirtual |
Definition at line 1283 of file wizardmachine.cxx.
Referenced by enterState(), vcl::RoadmapWizardMachine::implUpdateRoadmap(), prepareLeaveCurrentState(), and updateTravelUI().
|
protectedvirtual |
Definition at line 897 of file wizardmachine.cxx.
References nState.
Referenced by vcl::RoadmapWizardMachine::enableState(), vcl::RoadmapWizardMachine::implUpdateRoadmap(), and ShowPage().
|
protectedvirtual |
Definition at line 902 of file wizardmachine.cxx.
|
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().
|
private |
Definition at line 812 of file wizardmachine.cxx.
References CANCEL, FINISH, HELP, HID_WIZARD_NEXT, HID_WIZARD_PREVIOUS, comphelper::LibreOfficeKit::isActive(), LINK, m_pImpl, weld::AssistantController::m_xAssistant, m_xCancel, m_xFinish, m_xHelp, m_xNextPage, m_xPrevPage, NEXT, and PREVIOUS.
Referenced by WizardMachine().
|
private |
Definition at line 877 of file wizardmachine.cxx.
References getCurrentState(), GetPage(), BuilderPage::GetPageTitle(), m_pImpl, and weld::AssistantController::m_xAssistant.
Referenced by enterState(), and setTitleBase().
|
protected |
bool vcl::WizardMachine::isTravelingSuspended | ( | ) | const |
Definition at line 1315 of file wizardmachine.cxx.
References m_pImpl.
|
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.
Definition at line 1005 of file wizardmachine.cxx.
Referenced by DeactivatePage().
|
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.
|
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.
_eReason | The reason why the state is 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().
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().
|
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().
void vcl::WizardMachine::resumeTraveling | ( | AccessGuard | ) |
Definition at line 1326 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 1391 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 891 of file wizardmachine.cxx.
References implUpdateTitle(), and m_pImpl.
bool vcl::WizardMachine::ShowNextPage | ( | ) |
Definition at line 1198 of file wizardmachine.cxx.
References m_nCurState, and ShowPage().
bool vcl::WizardMachine::ShowPage | ( | WizardTypes::WizardState | nState | ) |
Definition at line 1176 of file wizardmachine.cxx.
References BuilderPage::Activate(), ActivatePage(), BuilderPage::Deactivate(), DeactivatePage(), GetPage(), getPageIdentForState(), m_nCurState, m_pCurTabPage, weld::AssistantController::m_xAssistant, and nState.
Referenced by ShowNextPage(), ShowPrevPage(), skip(), skipBackwardUntil(), skipUntil(), travelNext(), and travelPrevious().
bool vcl::WizardMachine::ShowPrevPage | ( | ) |
Definition at line 1203 of file wizardmachine.cxx.
References m_nCurState, and ShowPage().
|
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.
Definition at line 1119 of file wizardmachine.cxx.
References determineNextState(), vcl::WizardTypes::eTravelForward, getCurrentState(), m_pImpl, prepareLeaveCurrentState(), ShowPage(), and WZS_INVALID_STATE.
|
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.
Definition at line 1054 of file wizardmachine.cxx.
References DBG_ASSERT, vcl::WizardTypes::eTravelBackward, getCurrentState(), m_pImpl, prepareLeaveCurrentState(), and ShowPage().
|
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.
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.
void vcl::WizardMachine::suspendTraveling | ( | AccessGuard | ) |
Definition at line 1320 of file wizardmachine.cxx.
References DBG_ASSERT, and m_pImpl.
Referenced by vcl::WizardTravelSuspension::WizardTravelSuspension().
|
protected |
travel to the next state
Definition at line 1152 of file wizardmachine.cxx.
References determineNextState(), vcl::WizardTypes::eTravelForward, getCurrentState(), m_pImpl, prepareLeaveCurrentState(), ShowPage(), and WZS_INVALID_STATE.
|
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().
|
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().
|
private |
Definition at line 124 of file wizardmachine.hxx.
Referenced by ActivatePage(), ShowNextPage(), ShowPage(), and ShowPrevPage().
|
protected |
Definition at line 122 of file wizardmachine.hxx.
Referenced by Finish(), RemovePage(), SetPage(), and ShowPage().
|
private |
Definition at line 125 of file wizardmachine.hxx.
Referenced by AddPage(), GetPage(), RemovePage(), SetPage(), and ~WizardMachine().
|
private |
Definition at line 136 of file wizardmachine.hxx.
Referenced by enableAutomaticNextButtonState(), enterState(), GetOrCreatePage(), getStateHistory(), implConstruct(), implUpdateTitle(), isAutomaticNextButtonStateEnabled(), isTravelingSuspended(), removePageFromHistory(), resumeTraveling(), setTitleBase(), skip(), skipBackwardUntil(), skipUntil(), suspendTraveling(), travelNext(), travelPrevious(), and ~WizardMachine().
|
protected |
Definition at line 129 of file wizardmachine.hxx.
Referenced by defaultButton(), enableButtons(), and implConstruct().
|
protected |
Definition at line 128 of file wizardmachine.hxx.
Referenced by defaultButton(), enableButtons(), and implConstruct().
|
protected |
Definition at line 132 of file wizardmachine.hxx.
Referenced by defaultButton(), enableButtons(), and implConstruct().
|
protected |
Definition at line 130 of file wizardmachine.hxx.
Referenced by defaultButton(), enableButtons(), and implConstruct().
|
protected |
Definition at line 131 of file wizardmachine.hxx.
Referenced by defaultButton(), enableButtons(), and implConstruct().