diff options
| -rw-r--r-- | include/vcl/roadmapwizard.hxx | 410 | ||||
| -rw-r--r-- | include/vcl/wizdlg.hxx | 521 | ||||
| -rw-r--r-- | solenv/clang-format/blacklist | 1 | ||||
| -rw-r--r-- | svtools/source/uno/wizard/wizardshell.hxx | 2 | ||||
| -rw-r--r-- | vcl/source/app/salvtables.cxx | 2 | ||||
| -rw-r--r-- | vcl/source/control/roadmapwizard.cxx | 2 | ||||
| -rw-r--r-- | vcl/source/control/wizardmachine.cxx | 2 | ||||
| -rw-r--r-- | vcl/source/window/builder.cxx | 2 |
8 files changed, 415 insertions, 527 deletions
diff --git a/include/vcl/roadmapwizard.hxx b/include/vcl/roadmapwizard.hxx index bae94ee05c1a..a720cce8b684 100644 --- a/include/vcl/roadmapwizard.hxx +++ b/include/vcl/roadmapwizard.hxx @@ -27,16 +27,13 @@ namespace vcl { struct RoadmapWizardImpl; - class RoadmapWizard; namespace RoadmapWizardTypes { typedef sal_Int16 PathId; typedef ::std::vector< WizardTypes::WizardState > WizardPath; - typedef VclPtr<TabPage> (* RoadmapPageFactory)( RoadmapWizard& ); }; - //= RoadmapWizard /** is - no, not a wizard for a roadmap, but the base class for wizards @@ -58,392 +55,6 @@ namespace vcl <code>n2</code>, which share at least the first <code>k</code> states (where <code>k</code> is at least 1), and an arbitrary number of other states. */ - class VCL_DLLPUBLIC RoadmapWizard : public ModalDialog - { - private: - Idle maWizardLayoutIdle; - Size maPageSize; - ImplWizPageData* mpFirstPage; - ImplWizButtonData* mpFirstBtn; - VclPtr<TabPage> mpCurTabPage; - VclPtr<PushButton> mpPrevBtn; - VclPtr<PushButton> mpNextBtn; - VclPtr<vcl::Window> mpViewWindow; - sal_uInt16 mnCurLevel; - WindowAlign meViewAlign; - Link<RoadmapWizard*,void> maActivateHdl; - sal_Int16 mnLeftAlignCount; - bool mbEmptyViewMargin; - - DECL_DLLPRIVATE_LINK( ImplHandleWizardLayoutTimerHdl, Timer*, void ); - - // IMPORTANT: - // traveling pages should not be done by calling these base class member, some mechanisms of this class - // here (e.g. committing page data) depend on having full control over page traveling. - // So use the travelXXX methods if you need to travel - - protected: - long LogicalCoordinateToPixel(int iCoordinate); - /**sets the number of buttons which should be left-aligned. Normally, buttons are right-aligned. - - only to be used during construction, before any layouting happened - */ - void SetLeftAlignedButtonCount( sal_Int16 _nCount ); - /** declares the view area to have an empty margin - - Normally, the view area has a certain margin to the top/left/bottom/right of the - dialog. By calling this method, you can reduce this margin to 0. - */ - void SetEmptyViewMargin(); - - void CalcAndSetSize(); - - public: - VclPtr<OKButton> m_pFinish; - VclPtr<CancelButton> m_pCancel; - VclPtr<PushButton> m_pNextPage; - VclPtr<PushButton> m_pPrevPage; - VclPtr<HelpButton> m_pHelp; - - private: - std::unique_ptr<WizardMachineImplData> m_xWizardImpl; - // hold members in this structure to allow keeping compatible when members are added - std::unique_ptr<RoadmapWizardImpl> m_xRoadmapImpl; - - public: - RoadmapWizard(vcl::Window* pParent); - virtual ~RoadmapWizard( ) override; - virtual void dispose() override; - - virtual void Resize() override; - virtual void StateChanged( StateChangedType nStateChange ) override; - virtual bool EventNotify( NotifyEvent& rNEvt ) override; - - virtual void ActivatePage(); - virtual bool DeactivatePage(); - - virtual void queue_resize(StateChangedType eReason = StateChangedType::Layout) override; - - bool ShowPrevPage(); - bool ShowNextPage(); - bool ShowPage( sal_uInt16 nLevel ); - bool Finish( long nResult = 0 ); - sal_uInt16 GetCurLevel() const { return mnCurLevel; } - - void AddPage( TabPage* pPage ); - void RemovePage( TabPage* pPage ); - void SetPage( sal_uInt16 nLevel, TabPage* pPage ); - TabPage* GetPage( sal_uInt16 nLevel ) const; - - void AddButton( Button* pButton, long nOffset = 0 ); - void RemoveButton( Button* pButton ); - - void SetPrevButton( PushButton* pButton ) { mpPrevBtn = pButton; } - void SetNextButton( PushButton* pButton ) { mpNextBtn = pButton; } - - void SetViewWindow( vcl::Window* pWindow ) { mpViewWindow = pWindow; } - void SetViewAlign( WindowAlign eAlign ) { meViewAlign = eAlign; } - - void SetPageSizePixel( const Size& rSize ) { maPageSize = rSize; } - const Size& GetPageSizePixel() const { return maPageSize; } - - void SetActivatePageHdl( const Link<RoadmapWizard*,void>& rLink ) { maActivateHdl = rLink; } - - /// enable (or disable) buttons - void enableButtons(WizardButtonFlags _nWizardButtonFlags, bool _bEnable); - /// set the default style for a button - void defaultButton(WizardButtonFlags _nWizardButtonFlags); - /// set the default style for a button - void defaultButton(PushButton* _pNewDefButton); - - /// set the base of the title to use - the title of the current page is appended - void setTitleBase(const OUString& _rTitleBase); - - /// determines whether there is a next state to which we can advance - virtual bool canAdvance() const; - - /** 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 (<code>canAdvance</code>), and enables the "Next" - button if and only if this is the case. - */ - virtual void updateTravelUI(); - - void SetRoadmapHelpId( const OString& _rId ); - - void SetRoadmapInteractive( bool _bInteractive ); - - void InsertRoadmapItem(int nIndex, const OUString& rLabel, int nId, bool bEnabled); - void DeleteRoadmapItems(); - int GetCurrentRoadmapItemID() const; - void SelectRoadmapItemByID(int nId); - void SetItemSelectHdl( const Link<LinkParamNone*,void>& _rHdl ); - void ShowRoadmap(bool bShow); - - // returns whether a given state is enabled - bool isStateEnabled( WizardTypes::WizardState _nState ) const; - - protected: - - /// to override to create new pages - virtual VclPtr<TabPage> createPage(WizardTypes::WizardState nState); - - /// will be called when a new page is about to be displayed - virtual void enterState(WizardTypes::WizardState _nState); - - /** 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. - - @param _eReason - The reason why the state is to be left. - @return - <TRUE/> if and only if the page is allowed to be left - */ - virtual bool prepareLeaveCurrentState( WizardTypes::CommitPageReason eReason ); - - /** 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. - - @todo Normally, we would not need the return value here - derived classes now have - the possibility to veto page deactivations in <member>prepareLeaveCurrentState</member>. However, - changing this return type is too incompatible at the moment ... - - @return - <TRUE/> if and only if the page is allowed to be left - */ - virtual bool leaveState(WizardTypes::WizardState _nState); - - /** determine the next state to travel from the given one - - This method ensures that traveling happens along the active path. - - Return WZS_INVALID_STATE to prevent traveling. - - @see activatePath - */ - virtual WizardTypes::WizardState determineNextState(WizardTypes::WizardState nCurrentState) const; - - /** called when the finish button is pressed - <p>By default, only the base class' Finish method (which is not virtual) is called</p> - */ - virtual bool onFinish(); - - /// travel to the next state - bool travelNext(); - - /// travel to the previous state - bool travelPrevious(); - - /** 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. - */ - void enableAutomaticNextButtonState(); - bool isAutomaticNextButtonStateEnabled() const; - - /** removes a page from the history. Should be called when the page is being disabled - */ - void removePageFromHistory(WizardTypes::WizardState nToRemove); - - /** 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 skipUntil - @see skipBackwardUntil - */ - void skip(); - - /** 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. - - @return - <TRUE/> if and only if traveling was successful - - @see skip - @see skipBackwardUntil - */ - bool skipUntil(WizardTypes::WizardState nTargetState); - - /** 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 <em>show</em> both pages, which is not necessary, - since you're interested in the target page only. Using <member>skipBackwardUntil</member> relieves - you of this. - - @return - <TRUE/> if and only if traveling was successful - - @see skipUntil - @see skip - */ - bool skipBackwardUntil(WizardTypes::WizardState nTargetState); - - /** returns the current state of the machine - - Vulgo, this is the identifier of the current tab page :) - */ - WizardTypes::WizardState getCurrentState() const { return GetCurLevel(); } - - virtual IWizardPageController* - getPageController( TabPage* _pCurrentPage ) const; - - /** retrieves a copy of the state history, i.e. all states we already visited - */ - void getStateHistory(std::vector<WizardTypes::WizardState>& out_rHistory); - - /** 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 activatePath - - @param _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 - */ - void declarePath( RoadmapWizardTypes::PathId _nPathId, const RoadmapWizardTypes::WizardPath& _lWizardStates); - - /** activates a path which has previously been declared with <member>declarePath</member> - - You can only activate paths which share the first <code>k</code> states with the path - which is previously active (if any), where <code>k</code> is the index of the - current state within the current path. - - <example> - Say you have paths, <code>(0,1,2,5)</code> and <code>(0,1,4,5)</code>. This means that after - step <code>1</code>, you either continue with state <code>2</code> or state <code>4</code>, - and after this, you finish in state <code>5</code>.<br/> - Now if the first path is active, and your current state is <code>1</code>, then you can - easily switch to the second path, since both paths start with <code>(0,1)</code>.<br/> - However, if your current state is <code>2</code>, then you can not switch to the second - path anymore. - </example> - - @param _nPathId - the id of the path. The path must have been declared (under this id) with - <member>declarePath</member> before it can be activated. - - @param _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 <code>k</code> states with - the to-be-activated path.)<br/> - 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 <em>not</em> conflict.<br/> - With the paths in the example above, if you activate the second path (when both are - already declared), then only steps <code>0</code> and <code>1</code> are activated, - since they are common to both paths. - */ - void activatePath( RoadmapWizardTypes::PathId _nPathId, bool _bDecideForIt = false ); - - /** 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.<br/> - Another disadvantage is that the number of needed paths grows exponentially with - the number of states which can be potentially disabled. - - @see declarePath - */ - void enableState(WizardTypes::WizardState nState, bool _bEnable = true); - - /** returns true if and only if the given state is known in at least one declared path - */ - bool knowsState(WizardTypes::WizardState nState) const; - - /** 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. - */ - virtual OUString getStateDisplayName(WizardTypes::WizardState nState) const; - - private: - DECL_DLLPRIVATE_LINK( OnRoadmapItemSelected, LinkParamNone*, void ); - - /** updates the roadmap control to show the given path, as far as possible - (modulo conflicts with other paths) - */ - VCL_DLLPRIVATE void implUpdateRoadmap( ); - - VCL_DLLPRIVATE void impl_construct(); - - public: - class AccessGuard - { - friend class RoadmapWizardTravelSuspension; - private: - AccessGuard() { } - }; - - void suspendTraveling( AccessGuard ); - void resumeTraveling( AccessGuard ); - bool isTravelingSuspended() const; - - protected: - TabPage* GetOrCreatePage(const WizardTypes::WizardState i_nState); - - private: - VCL_DLLPRIVATE void ImplInitData(); - VCL_DLLPRIVATE void ImplCalcSize( Size& rSize ); - VCL_DLLPRIVATE void ImplPosCtrls(); - VCL_DLLPRIVATE void ImplPosTabPage(); - VCL_DLLPRIVATE void ImplShowTabPage( TabPage* pPage ); - VCL_DLLPRIVATE TabPage* ImplGetPage( sal_uInt16 nLevel ) const; - - - DECL_DLLPRIVATE_LINK(OnNextPage, Button*, void); - DECL_DLLPRIVATE_LINK(OnPrevPage, Button*, void); - DECL_DLLPRIVATE_LINK(OnFinish, Button*, void); - - VCL_DLLPRIVATE void implResetDefault(vcl::Window const * _pWindow); - VCL_DLLPRIVATE void implUpdateTitle(); - VCL_DLLPRIVATE void implConstruct( const WizardButtonFlags _nButtonFlags ); - }; - class VCL_DLLPUBLIC RoadmapWizardMachine : public vcl::WizardMachine { private: @@ -566,27 +177,6 @@ namespace vcl */ VCL_DLLPRIVATE void implUpdateRoadmap( ); }; - - /// helper class to temporarily suspend any traveling in the wizard - class RoadmapWizardTravelSuspension - { - public: - RoadmapWizardTravelSuspension(RoadmapWizard& rWizard) - : m_pOWizard(&rWizard) - { - m_pOWizard->suspendTraveling(RoadmapWizard::AccessGuard()); - } - - ~RoadmapWizardTravelSuspension() - { - if (m_pOWizard) - m_pOWizard->resumeTraveling(RoadmapWizard::AccessGuard()); - } - - private: - VclPtr<RoadmapWizard> m_pOWizard; - }; - } // namespace vcl diff --git a/include/vcl/wizdlg.hxx b/include/vcl/wizdlg.hxx index 3e87bff37c5b..d2c4520a0191 100644 --- a/include/vcl/wizdlg.hxx +++ b/include/vcl/wizdlg.hxx @@ -20,151 +20,448 @@ #ifndef INCLUDED_VCL_WIZDLG_HXX #define INCLUDED_VCL_WIZDLG_HXX +#include <memory> #include <vcl/dllapi.h> +#include <vcl/roadmapwizard.hxx> -class TabPage; +namespace vcl +{ + struct RoadmapWizardImpl; + class RoadmapWizard; -/* + namespace RoadmapWizardTypes + { + typedef VclPtr<TabPage> (* RoadmapPageFactory)( RoadmapWizard& ); + }; -Description -========== + //= RoadmapWizard -class WizardDialog + /** wizard for a roadmap -This class is the base for WizardDialog. The basic functionality is to -order the Controls. Besides it's a helper method for switching the TabPages. -The dialog orders the Controls when their size changed. + The basic new concept introduced is a <em>path</em>:<br/> + A <em>path</em> 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 <code>n</code> elements, + which are to be visited successively. -SetPageSizePixel() sets the biggest TabPage size. When the dialog -should be displayed, first the dialog size is calculated and set. -If there is no size set with SetPageSizePixel(), max size of the -current TabPage is set as default. + 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. -ShowPrevPage()/ShowNextPage() shows the previous/next TabPage. -First the Deactivate-Handler is called by dialog and if the return -value is sal_True the Active-Handler is called by dialog and the -corresponding TabPage is showed. Finnish() can only be called -if the Finnish-Button is activated. Then the Deactivate-Page-Handler -is called by dialog and by the current TabPage. Now the dialog ends -(Close() or EndDialog()). + In a yet more advanced wizards, you will have several paths of length <code>n1</code> and + <code>n2</code>, which share at least the first <code>k</code> states (where <code>k</code> + is at least 1), and an arbitrary number of other states. + */ + class VCL_DLLPUBLIC RoadmapWizard : public ModalDialog + { + private: + Idle maWizardLayoutIdle; + Size maPageSize; + ImplWizPageData* mpFirstPage; + ImplWizButtonData* mpFirstBtn; + VclPtr<TabPage> mpCurTabPage; + VclPtr<PushButton> mpPrevBtn; + VclPtr<PushButton> mpNextBtn; + VclPtr<vcl::Window> mpViewWindow; + sal_uInt16 mnCurLevel; + WindowAlign meViewAlign; + Link<RoadmapWizard*,void> maActivateHdl; + sal_Int16 mnLeftAlignCount; + bool mbEmptyViewMargin; + + DECL_DLLPRIVATE_LINK( ImplHandleWizardLayoutTimerHdl, Timer*, void ); + + // IMPORTANT: + // traveling pages should not be done by calling these base class member, some mechanisms of this class + // here (e.g. committing page data) depend on having full control over page traveling. + // So use the travelXXX methods if you need to travel + + protected: + long LogicalCoordinateToPixel(int iCoordinate); + /**sets the number of buttons which should be left-aligned. Normally, buttons are right-aligned. + + only to be used during construction, before any layouting happened + */ + void SetLeftAlignedButtonCount( sal_Int16 _nCount ); + /** declares the view area to have an empty margin + + Normally, the view area has a certain margin to the top/left/bottom/right of the + dialog. By calling this method, you can reduce this margin to 0. + */ + void SetEmptyViewMargin(); + + void CalcAndSetSize(); -AddPage()/RemovePage()/SetPage() TabPages are made known to the Wizard. -The TabPage of the current Level is always shown and if no TabPage is -available at that level then the TabPage of the highest level is used. -Because of that the current TabPage always can be swapped under the -condition that in the Activate-Handler the current TabPage cannot be -destroyed. + public: + VclPtr<OKButton> m_pFinish; + VclPtr<CancelButton> m_pCancel; + VclPtr<PushButton> m_pNextPage; + VclPtr<PushButton> m_pPrevPage; + VclPtr<HelpButton> m_pHelp; + + private: + std::unique_ptr<WizardMachineImplData> m_xWizardImpl; + // hold members in this structure to allow keeping compatible when members are added + std::unique_ptr<RoadmapWizardImpl> m_xRoadmapImpl; -SetPrevButton()/SetNextButton() add the Prev-Button and the -Next-Button to the dialog. In that case the dialog emits the Click-Handler -of the assigned Button when Ctrl+Tab, Shift-Ctrl-Tab are pressed. The Buttons -are not disabled by the WizardDialog and such an action must be -programmed by the user of this Dialog. + public: + RoadmapWizard(vcl::Window* pParent); + virtual ~RoadmapWizard( ) override; + virtual void dispose() override; -AddButton()/RemoveButton() can add Buttons to the Wizard and they're shown -the order of adding them. The Buttons are ordered independent of their -visibility state, so that also later a Button can be shown/hidden. -The Offset is in Pixels and always refers to the following Button. So that -the distance between the Buttons is the same for all dialogs, there is the -macro WIZARDDIALOG_BUTTON_STDOFFSET_X to be used as the default offset. + virtual void Resize() override; + virtual void StateChanged( StateChangedType nStateChange ) override; + virtual bool EventNotify( NotifyEvent& rNEvt ) override; -With SetViewWindow() and SetViewAlign() a Control can be set, which can -be used as Preview-Window or for displaying of pretty Bitmaps. + virtual void ActivatePage(); + virtual bool DeactivatePage(); --------------------------------------------------------------------------- + virtual void queue_resize(StateChangedType eReason = StateChangedType::Layout) override; -The ActivatePage()-Handler is called, if a new TabPage is shown. In that -handler a new TabPage can be created if it was not created before; the -handler can be set as a Link. GetCurLevel() returns the current level and -Level 0 is the first page. + bool ShowPrevPage(); + bool ShowNextPage(); + bool ShowPage( sal_uInt16 nLevel ); + bool Finish( long nResult = 0 ); + sal_uInt16 GetCurLevel() const { return mnCurLevel; } -The DeactivatePage()-Handler is called if a new TabPage should be shown. -In that handler has an optional error check and returns sal_False, if the -switch should not be done. Also the Handler can be set as a Link. The -default implementation calls the Link and returns the Links value or returns -sal_True if no Link is set. + void AddPage( TabPage* pPage ); + void RemovePage( TabPage* pPage ); + void SetPage( sal_uInt16 nLevel, TabPage* pPage ); + TabPage* GetPage( sal_uInt16 nLevel ) const; --------------------------------------------------------------------------- + void AddButton( Button* pButton, long nOffset = 0 ); + void RemoveButton( Button* pButton ); -Example: + void SetPrevButton( PushButton* pButton ) { mpPrevBtn = pButton; } + void SetNextButton( PushButton* pButton ) { mpNextBtn = pButton; } -MyWizardDlg-Ctor ----------------- + void SetViewWindow( vcl::Window* pWindow ) { mpViewWindow = pWindow; } + void SetViewAlign( WindowAlign eAlign ) { meViewAlign = eAlign; } -// add buttons -AddButton( &maHelpBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X ); -AddButton( &maCancelBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X ); -AddButton( &maPrevBtn ); -AddButton( &maNextBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X ); -AddButton( &maFinnishBtn ); -SetPrevButton( &maPrevBtn ); -SetNextButton( &maNextBtn ); + void SetPageSizePixel( const Size& rSize ) { maPageSize = rSize; } + const Size& GetPageSizePixel() const { return maPageSize; } -// SetHandler -maPrevBtn.SetClickHdl( LINK( this, MyWizardDlg, ImplPrevHdl ) ); -maNextBtn.SetClickHdl( LINK( this, MyWizardDlg, ImplNextHdl ) ); + void SetActivatePageHdl( const Link<RoadmapWizard*,void>& rLink ) { maActivateHdl = rLink; } -// Set PreviewWindow -SetViewWindow( &maPreview ); + /// enable (or disable) buttons + void enableButtons(WizardButtonFlags _nWizardButtonFlags, bool _bEnable); + /// set the default style for a button + void defaultButton(WizardButtonFlags _nWizardButtonFlags); + /// set the default style for a button + void defaultButton(PushButton* _pNewDefButton); -// Call ActivatePage, because the first page should be created an activated -ActivatePage(); + /// set the base of the title to use - the title of the current page is appended + void setTitleBase(const OUString& _rTitleBase); + /// determines whether there is a next state to which we can advance + virtual bool canAdvance() const; -MyWizardDlg-ActivatePage-Handler --------------------------------- + /** updates the user interface which deals with traveling in the wizard -void MyWizardDlg::ActivatePage() -{ - WizardDialog::ActivatePage(); + The default implementation simply checks whether both the current page and the wizard + itself allow to advance to the next state (<code>canAdvance</code>), and enables the "Next" + button if and only if this is the case. + */ + virtual void updateTravelUI(); - // Test, if Page is created already - if ( !GetPage( GetCurLevel() ) ) - { - // Create and add new page - TabPage* pNewTabPage; - switch ( GetCurLevel() ) - { - case 0: - pNewTabPage = CreateIntroPage(); - break; - case 1: - pNewTabPage = CreateSecondPage(); - break; - case 2: - pNewTabPage = CreateThirdPage(); - break; - case 3: - pNewTabPage = CreateFinnishedPage(); - break; + void SetRoadmapHelpId( const OString& _rId ); - } - AddPage( pNewTabPage ); - } -} + void SetRoadmapInteractive( bool _bInteractive ); + void InsertRoadmapItem(int nIndex, const OUString& rLabel, int nId, bool bEnabled); + void DeleteRoadmapItems(); + int GetCurrentRoadmapItemID() const; + void SelectRoadmapItemByID(int nId); + void SetItemSelectHdl( const Link<LinkParamNone*,void>& _rHdl ); + void ShowRoadmap(bool bShow); -MyWizardDlg-Prev/Next-Handler ------------------------------ + // returns whether a given state is enabled + bool isStateEnabled( WizardTypes::WizardState _nState ) const; -IMPL_LINK( MyWizardDlg, ImplPrevHdl, PushButton*, pBtn, void ) -{ - ShowPrevPage(); - if ( !GetCurLevel() ) - pBtn->Disable(); -} + protected: -IMPL_LINK( MyWizardDlg, ImplNextHdl, PushButton*, pBtn, void ) -{ - ShowNextPage(); - if ( GetCurLevel() < 3 ) - pBtn->Disable(); -} + /// to override to create new pages + virtual VclPtr<TabPage> createPage(WizardTypes::WizardState nState); + + /// will be called when a new page is about to be displayed + virtual void enterState(WizardTypes::WizardState _nState); + + /** 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. + + @param _eReason + The reason why the state is to be left. + @return + <TRUE/> if and only if the page is allowed to be left + */ + virtual bool prepareLeaveCurrentState( WizardTypes::CommitPageReason eReason ); + + /** 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. + + @todo Normally, we would not need the return value here - derived classes now have + the possibility to veto page deactivations in <member>prepareLeaveCurrentState</member>. However, + changing this return type is too incompatible at the moment ... + + @return + <TRUE/> if and only if the page is allowed to be left + */ + virtual bool leaveState(WizardTypes::WizardState _nState); + + /** determine the next state to travel from the given one + + This method ensures that traveling happens along the active path. + + Return WZS_INVALID_STATE to prevent traveling. + + @see activatePath + */ + virtual WizardTypes::WizardState determineNextState(WizardTypes::WizardState nCurrentState) const; + + /** called when the finish button is pressed + <p>By default, only the base class' Finish method (which is not virtual) is called</p> + */ + virtual bool onFinish(); + + /// travel to the next state + bool travelNext(); + + /// travel to the previous state + bool travelPrevious(); + + /** 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. + */ + void enableAutomaticNextButtonState(); + bool isAutomaticNextButtonStateEnabled() const; + + /** removes a page from the history. Should be called when the page is being disabled + */ + void removePageFromHistory(WizardTypes::WizardState nToRemove); + + /** 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 skipUntil + @see skipBackwardUntil + */ + void skip(); + + /** 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. + + @return + <TRUE/> if and only if traveling was successful + + @see skip + @see skipBackwardUntil + */ + bool skipUntil(WizardTypes::WizardState nTargetState); + + /** 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 <em>show</em> both pages, which is not necessary, + since you're interested in the target page only. Using <member>skipBackwardUntil</member> relieves + you of this. + + @return + <TRUE/> if and only if traveling was successful + + @see skipUntil + @see skip + */ + bool skipBackwardUntil(WizardTypes::WizardState nTargetState); + + /** returns the current state of the machine + + Vulgo, this is the identifier of the current tab page :) + */ + WizardTypes::WizardState getCurrentState() const { return GetCurLevel(); } + + virtual IWizardPageController* + getPageController( TabPage* _pCurrentPage ) const; + + /** retrieves a copy of the state history, i.e. all states we already visited + */ + void getStateHistory(std::vector<WizardTypes::WizardState>& out_rHistory); + + /** 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 activatePath + + @param _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 + */ + void declarePath( RoadmapWizardTypes::PathId _nPathId, const RoadmapWizardTypes::WizardPath& _lWizardStates); + + /** activates a path which has previously been declared with <member>declarePath</member> + + You can only activate paths which share the first <code>k</code> states with the path + which is previously active (if any), where <code>k</code> is the index of the + current state within the current path. + + <example> + Say you have paths, <code>(0,1,2,5)</code> and <code>(0,1,4,5)</code>. This means that after + step <code>1</code>, you either continue with state <code>2</code> or state <code>4</code>, + and after this, you finish in state <code>5</code>.<br/> + Now if the first path is active, and your current state is <code>1</code>, then you can + easily switch to the second path, since both paths start with <code>(0,1)</code>.<br/> + However, if your current state is <code>2</code>, then you can not switch to the second + path anymore. + </example> + + @param _nPathId + the id of the path. The path must have been declared (under this id) with + <member>declarePath</member> before it can be activated. + + @param _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 <code>k</code> states with + the to-be-activated path.)<br/> + 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 <em>not</em> conflict.<br/> + With the paths in the example above, if you activate the second path (when both are + already declared), then only steps <code>0</code> and <code>1</code> are activated, + since they are common to both paths. + */ + void activatePath( RoadmapWizardTypes::PathId _nPathId, bool _bDecideForIt = false ); + + /** 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.<br/> + Another disadvantage is that the number of needed paths grows exponentially with + the number of states which can be potentially disabled. + + @see declarePath + */ + void enableState(WizardTypes::WizardState nState, bool _bEnable = true); + + /** returns true if and only if the given state is known in at least one declared path + */ + bool knowsState(WizardTypes::WizardState nState) const; + + /** 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. + */ + virtual OUString getStateDisplayName(WizardTypes::WizardState nState) const; + + private: + DECL_DLLPRIVATE_LINK( OnRoadmapItemSelected, LinkParamNone*, void ); + + /** updates the roadmap control to show the given path, as far as possible + (modulo conflicts with other paths) + */ + VCL_DLLPRIVATE void implUpdateRoadmap( ); + + VCL_DLLPRIVATE void impl_construct(); + + public: + class AccessGuard + { + friend class RoadmapWizardTravelSuspension; + private: + AccessGuard() { } + }; + + void suspendTraveling( AccessGuard ); + void resumeTraveling( AccessGuard ); + bool isTravelingSuspended() const; + + protected: + TabPage* GetOrCreatePage(const WizardTypes::WizardState i_nState); + + private: + VCL_DLLPRIVATE void ImplInitData(); + VCL_DLLPRIVATE void ImplCalcSize( Size& rSize ); + VCL_DLLPRIVATE void ImplPosCtrls(); + VCL_DLLPRIVATE void ImplPosTabPage(); + VCL_DLLPRIVATE void ImplShowTabPage( TabPage* pPage ); + VCL_DLLPRIVATE TabPage* ImplGetPage( sal_uInt16 nLevel ) const; + + + DECL_DLLPRIVATE_LINK(OnNextPage, Button*, void); + DECL_DLLPRIVATE_LINK(OnPrevPage, Button*, void); + DECL_DLLPRIVATE_LINK(OnFinish, Button*, void); + + VCL_DLLPRIVATE void implResetDefault(vcl::Window const * _pWindow); + VCL_DLLPRIVATE void implUpdateTitle(); + VCL_DLLPRIVATE void implConstruct( const WizardButtonFlags _nButtonFlags ); + }; + + /// helper class to temporarily suspend any traveling in the wizard + class RoadmapWizardTravelSuspension + { + public: + RoadmapWizardTravelSuspension(RoadmapWizard& rWizard) + : m_pOWizard(&rWizard) + { + m_pOWizard->suspendTraveling(RoadmapWizard::AccessGuard()); + } + + ~RoadmapWizardTravelSuspension() + { + if (m_pOWizard) + m_pOWizard->resumeTraveling(RoadmapWizard::AccessGuard()); + } + + private: + VclPtr<RoadmapWizard> m_pOWizard; + }; -*/ +} // namespace vcl -#endif // INCLUDED_VCL_WIZDLG_HXX +#endif /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ diff --git a/solenv/clang-format/blacklist b/solenv/clang-format/blacklist index 510fdc225b1b..fcf6e3c6ed84 100644 --- a/solenv/clang-format/blacklist +++ b/solenv/clang-format/blacklist @@ -7946,6 +7946,7 @@ include/vcl/waitobj.hxx include/vcl/wall.hxx include/vcl/window.hxx include/vcl/wizardmachine.hxx +include/vcl/wizdlg.hxx include/vcl/wmf.hxx include/vcl/wmfexternal.hxx include/vcl/wrkwin.hxx diff --git a/svtools/source/uno/wizard/wizardshell.hxx b/svtools/source/uno/wizard/wizardshell.hxx index 6217f5822770..f56451397d25 100644 --- a/svtools/source/uno/wizard/wizardshell.hxx +++ b/svtools/source/uno/wizard/wizardshell.hxx @@ -22,7 +22,7 @@ #include <com/sun/star/ui/dialogs/XWizardController.hpp> #include <com/sun/star/ui/dialogs/XWizard.hpp> -#include <vcl/roadmapwizard.hxx> +#include <vcl/wizdlg.hxx> #include <map> #include <memory> diff --git a/vcl/source/app/salvtables.cxx b/vcl/source/app/salvtables.cxx index f4bc9708018b..2efef7a22f48 100644 --- a/vcl/source/app/salvtables.cxx +++ b/vcl/source/app/salvtables.cxx @@ -49,7 +49,7 @@ #include <vcl/menubtn.hxx> #include <vcl/prgsbar.hxx> #include <vcl/ptrstyle.hxx> -#include <vcl/roadmapwizard.hxx> +#include <vcl/wizdlg.hxx> #include <vcl/slider.hxx> #include <vcl/sysdata.hxx> #include <vcl/svimpbox.hxx> diff --git a/vcl/source/control/roadmapwizard.cxx b/vcl/source/control/roadmapwizard.cxx index 2e66d2ed4027..94f12e0dcfdf 100644 --- a/vcl/source/control/roadmapwizard.cxx +++ b/vcl/source/control/roadmapwizard.cxx @@ -18,7 +18,7 @@ */ -#include <vcl/roadmapwizard.hxx> +#include <vcl/wizdlg.hxx> #include <vcl/toolkit/roadmap.hxx> #include <tools/debug.hxx> #include <osl/diagnose.h> diff --git a/vcl/source/control/wizardmachine.cxx b/vcl/source/control/wizardmachine.cxx index f8f6753074cd..35a432200c2c 100644 --- a/vcl/source/control/wizardmachine.cxx +++ b/vcl/source/control/wizardmachine.cxx @@ -19,7 +19,7 @@ #include <vcl/event.hxx> #include <vcl/svapp.hxx> -#include <vcl/roadmapwizard.hxx> +#include <vcl/wizdlg.hxx> #include <tools/debug.hxx> #include <tools/diagnose_ex.h> #include <strings.hrc> diff --git a/vcl/source/window/builder.cxx b/vcl/source/window/builder.cxx index f27665c40be5..cc7dac554b0c 100644 --- a/vcl/source/window/builder.cxx +++ b/vcl/source/window/builder.cxx @@ -35,7 +35,6 @@ #include <vcl/menubtn.hxx> #include <vcl/mnemonic.hxx> #include <vcl/prgsbar.hxx> -#include <vcl/roadmapwizard.hxx> #include <vcl/scrbar.hxx> #include <vcl/svapp.hxx> #include <vcl/svtabbx.hxx> @@ -49,6 +48,7 @@ #include <vcl/slider.hxx> #include <vcl/listctrl.hxx> #include <vcl/weld.hxx> +#include <vcl/wizdlg.hxx> #include <vcl/commandinfoprovider.hxx> #include <svdata.hxx> #include <bitmaps.hlst> |