vcl/inc/wizdlg.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_VCL_WIZDLG_HXX
  21 #define INCLUDED_VCL_WIZDLG_HXX
  22
  23 #include <memory>
  24 #include <vcl/toolkit/button.hxx>
  25 #include <vcl/toolkit/dialog.hxx>
  26 #include <vcl/roadmapwizard.hxx>
  27 #include <vcl/tabpage.hxx>
  28
  29 struct ImplWizPageData
  30 {
  31     ImplWizPageData*    mpNext;
  32     VclPtr<TabPage>     mpPage;
  33 };
  34
  35 namespace vcl
  36 {
  37     struct RoadmapWizardImpl;
  38     class RoadmapWizard;
  39
  40     namespace RoadmapWizardTypes
  41     {
  42         typedef VclPtr<TabPage> (* RoadmapPageFactory)( RoadmapWizard& );
  43     };
  44
  45     //= RoadmapWizard
  46
  47     /** wizard for a roadmap
  48
  49         The basic new concept introduced is a <em>path</em>:<br/>
  50         A <em>path</em> is a sequence of states, which are to be executed in a linear order.
  51         Elements in the path can be skipped, depending on choices the user makes.
  52
  53         In the most simple wizards, you will have only one path consisting of <code>n</code> elements,
  54         which are to be visited successively.
  55
  56         In a slightly more complex wizard, you will have one linear path, were certain
  57         steps might be skipped due to user input. For instance, the user may decide to not specify
  58         certain aspects of the to-be-created object (e.g. by unchecking a check box),
  59         and the wizard then will simply disable the step which corresponds to this step.
  60
  61         In a yet more advanced wizards, you will have several paths of length <code>n1</code> and
  62         <code>n2</code>, which share at least the first <code>k</code> states (where <code>k</code>
  63         is at least 1), and an arbitrary number of other states.
  64     */
  65     class RoadmapWizard final : public Dialog
  66     {
  67     private:
  68         Idle                    maWizardLayoutIdle;
  69         Size                    maPageSize;
  70         ImplWizPageData*        mpFirstPage;
  71         ImplWizButtonData*      mpFirstBtn;
  72         VclPtr<TabPage>         mpCurTabPage;
  73         VclPtr<PushButton>      mpPrevBtn;
  74         VclPtr<PushButton>      mpNextBtn;
  75         VclPtr<vcl::Window>     mpViewWindow;
  76         sal_uInt16              mnCurLevel;
  77         sal_Int16               mnLeftAlignCount;
  78         bool                    mbEmptyViewMargin;
  79
  80         DECL_LINK( ImplHandleWizardLayoutTimerHdl, Timer*, void );
  81
  82         // IMPORTANT:
  83         // traveling pages should not be done by calling these base class member, some mechanisms of this class
  84         // here (e.g. committing page data) depend on having full control over page traveling.
  85         // So use the travelXXX methods if you need to travel
  86
  87         tools::Long                LogicalCoordinateToPixel(int iCoordinate) const;
  88         /**sets the number of buttons which should be left-aligned. Normally, buttons are right-aligned.
  89
  90             only to be used during construction, before any layouting happened
  91         */
  92         void                SetLeftAlignedButtonCount( sal_Int16 _nCount );
  93
  94         void                CalcAndSetSize();
  95
  96     public:
  97         VclPtr<OKButton>       m_pFinish;
  98         VclPtr<CancelButton>   m_pCancel;
  99         VclPtr<PushButton>     m_pNextPage;
 100         VclPtr<PushButton>     m_pPrevPage;
 101         VclPtr<HelpButton>     m_pHelp;
 102
 103     private:
 104         std::unique_ptr<WizardMachineImplData> m_xWizardImpl;
 105         // hold members in this structure to allow keeping compatible when members are added
 106         std::unique_ptr<RoadmapWizardImpl> m_xRoadmapImpl;
 107
 108     public:
 109         RoadmapWizard(vcl::Window* pParent, WinBits nStyle = WB_STDDIALOG, InitFlag eFlag = InitFlag::Default);
 110         virtual ~RoadmapWizard( ) override;
 111         virtual void dispose() override;
 112
 113         virtual void        Resize() override;
 114         virtual void        StateChanged( StateChangedType nStateChange ) override;
 115         virtual bool        EventNotify( NotifyEvent& rNEvt ) override;
 116
 117         void                ActivatePage();
 118
 119         virtual void        queue_resize(StateChangedType eReason = StateChangedType::Layout) override;
 120
 121         bool                ShowPage( sal_uInt16 nLevel );
 122         void                Finish( tools::Long nResult = 0 );
 123         sal_uInt16          GetCurLevel() const { return mnCurLevel; }
 124
 125         void                AddPage( TabPage* pPage );
 126         void                RemovePage( TabPage* pPage );
 127         void                SetPage( sal_uInt16 nLevel, TabPage* pPage );
 128         TabPage*            GetPage( sal_uInt16 nLevel ) const;
 129
 130         void                AddButton( Button* pButton, tools::Long nOffset = 0 );
 131         void                RemoveButton( Button* pButton );
 132
 133         void                SetPageSizePixel( const Size& rSize ) { maPageSize = rSize; }
 134         const Size&         GetPageSizePixel() const { return maPageSize; }
 135
 136         void            SetRoadmapHelpId( const OString& _rId );
 137
 138         void            InsertRoadmapItem(int nIndex, const OUString& rLabel, int nId, bool bEnabled);
 139         void            DeleteRoadmapItems();
 140         int             GetCurrentRoadmapItemID() const;
 141         void            SelectRoadmapItemByID(int nId, bool bGrabFocus = true);
 142         void            SetItemSelectHdl( const Link<LinkParamNone*,void>& _rHdl );
 143         void            ShowRoadmap(bool bShow);
 144
 145         FactoryFunction GetUITestFactory() const override;
 146
 147     private:
 148
 149         /// to override to create new pages
 150         VclPtr<TabPage>     createPage(WizardTypes::WizardState nState);
 151
 152         /// will be called when a new page is about to be displayed
 153         void                enterState(WizardTypes::WizardState _nState);
 154
 155         /** determine the next state to travel from the given one
 156
 157             This method ensures that traveling happens along the active path.
 158
 159             Return WZS_INVALID_STATE to prevent traveling.
 160
 161             @see activatePath
 162         */
 163         WizardTypes::WizardState determineNextState(WizardTypes::WizardState nCurrentState) const;
 164
 165         /// travel to the next state
 166         void                travelNext();
 167
 168         /// travel to the previous state
 169         void                travelPrevious();
 170
 171         /** removes a page from the history. Should be called when the page is being disabled
 172         */
 173         void                removePageFromHistory(WizardTypes::WizardState nToRemove);
 174
 175         /** skips one or more states, until a given state is reached
 176
 177             The method behaves as if from the current state, <method>travelNext</method>s were called
 178             successively, until <arg>_nTargetState</arg> is reached, but without actually creating or
 179             displaying the \EDntermediate pages.
 180
 181             The skipped states appear in the state history, so <method>travelPrevious</method> will make use of them.
 182
 183             @return
 184                 <TRUE/> if and only if traveling was successful
 185
 186             @see skip
 187             @see skipBackwardUntil
 188         */
 189         bool                    skipUntil(WizardTypes::WizardState nTargetState);
 190
 191         /** moves back one or more states, until a given state is reached
 192
 193             This method allows traveling backwards more than one state without actually showing the intermediate
 194             states.
 195
 196             For instance, if you want to travel two steps backward at a time, you could used
 197             two travelPrevious calls, but this would <em>show</em> both pages, which is not necessary,
 198             since you're interested in the target page only. Using <member>skipBackwardUntil</member> relieves
 199             you of this.
 200
 201             @return
 202                 <TRUE/> if and only if traveling was successful
 203
 204             @see skipUntil
 205             @see skip
 206         */
 207         bool                    skipBackwardUntil(WizardTypes::WizardState nTargetState);
 208
 209         /** returns the current state of the machine
 210
 211             Vulgo, this is the identifier of the current tab page :)
 212         */
 213         WizardTypes::WizardState getCurrentState() const { return GetCurLevel(); }
 214
 215         /** returns a human readable name for a given state
 216
 217             There is a default implementation for this method, which returns the display name
 218             as given in a call to describeState. If there is no description for the given state,
 219             this is worth an assertion in a non-product build, and then an empty string is
 220             returned.
 221         */
 222         OUString  getStateDisplayName(WizardTypes::WizardState nState) const;
 223
 224         DECL_LINK( OnRoadmapItemSelected, LinkParamNone*, void );
 225
 226         /** updates the roadmap control to show the given path, as far as possible
 227             (modulo conflicts with other paths)
 228         */
 229         void implUpdateRoadmap( );
 230
 231     public:
 232         class AccessGuard
 233         {
 234             friend class RoadmapWizardTravelSuspension;
 235         private:
 236             AccessGuard() { }
 237         };
 238
 239         void                   suspendTraveling( AccessGuard );
 240         void                   resumeTraveling( AccessGuard );
 241         bool                   isTravelingSuspended() const;
 242
 243     private:
 244         void GetOrCreatePage(const WizardTypes::WizardState i_nState);
 245
 246         void             ImplCalcSize( Size& rSize );
 247         void             ImplPosCtrls();
 248         void             ImplPosTabPage();
 249         void             ImplShowTabPage( TabPage* pPage );
 250         TabPage*         ImplGetPage( sal_uInt16 nLevel ) const;
 251
 252
 253         DECL_LINK(OnNextPage, Button*, void);
 254         DECL_LINK(OnPrevPage, Button*, void);
 255         DECL_LINK(OnFinish, Button*, void);
 256
 257         void     implConstruct( const WizardButtonFlags _nButtonFlags );
 258     };
 259
 260     /// helper class to temporarily suspend any traveling in the wizard
 261     class RoadmapWizardTravelSuspension
 262     {
 263     public:
 264         RoadmapWizardTravelSuspension(RoadmapWizard& rWizard)
 265             : m_pOWizard(&rWizard)
 266         {
 267             m_pOWizard->suspendTraveling(RoadmapWizard::AccessGuard());
 268         }
 269
 270         ~RoadmapWizardTravelSuspension()
 271         {
 272             if (m_pOWizard)
 273                 m_pOWizard->resumeTraveling(RoadmapWizard::AccessGuard());
 274         }
 275
 276     private:
 277         VclPtr<RoadmapWizard> m_pOWizard;
 278     };
 279
 280 } // namespace vcl
 281
 282 #endif
 283
 284 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */