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         void                AddButtonResponse( Button* pButton, int response);
 133
 134         void                SetPageSizePixel( const Size& rSize ) { maPageSize = rSize; }
 135         const Size&         GetPageSizePixel() const { return maPageSize; }
 136
 137         void            SetRoadmapHelpId( const OString& _rId );
 138         void            SetRoadmapBitmap( const BitmapEx& maBitmap );
 139
 140         void            InsertRoadmapItem(int nIndex, const OUString& rLabel, int nId, bool bEnabled);
 141         void            DeleteRoadmapItems();
 142         int             GetCurrentRoadmapItemID() const;
 143         void            SelectRoadmapItemByID(int nId, bool bGrabFocus = true);
 144         void            SetItemSelectHdl( const Link<LinkParamNone*,void>& _rHdl );
 145         void            ShowRoadmap(bool bShow);
 146
 147         FactoryFunction GetUITestFactory() const override;
 148
 149     private:
 150
 151         /// to override to create new pages
 152         VclPtr<TabPage>     createPage(WizardTypes::WizardState nState);
 153
 154         /// will be called when a new page is about to be displayed
 155         void                enterState(WizardTypes::WizardState _nState);
 156
 157         /** determine the next state to travel from the given one
 158
 159             This method ensures that traveling happens along the active path.
 160
 161             Return WZS_INVALID_STATE to prevent traveling.
 162
 163             @see activatePath
 164         */
 165         WizardTypes::WizardState determineNextState(WizardTypes::WizardState nCurrentState) const;
 166
 167         /// travel to the next state
 168         void                travelNext();
 169
 170         /// travel to the previous state
 171         void                travelPrevious();
 172
 173         /** removes a page from the history. Should be called when the page is being disabled
 174         */
 175         void                removePageFromHistory(WizardTypes::WizardState nToRemove);
 176
 177         /** skips one or more states, until a given state is reached
 178
 179             The method behaves as if from the current state, <method>travelNext</method>s were called
 180             successively, until <arg>_nTargetState</arg> is reached, but without actually creating or
 181             displaying the \EDntermediate pages.
 182
 183             The skipped states appear in the state history, so <method>travelPrevious</method> will make use of them.
 184
 185             @return
 186                 <TRUE/> if and only if traveling was successful
 187
 188             @see skip
 189             @see skipBackwardUntil
 190         */
 191         bool                    skipUntil(WizardTypes::WizardState nTargetState);
 192
 193         /** moves back one or more states, until a given state is reached
 194
 195             This method allows traveling backwards more than one state without actually showing the intermediate
 196             states.
 197
 198             For instance, if you want to travel two steps backward at a time, you could used
 199             two travelPrevious calls, but this would <em>show</em> both pages, which is not necessary,
 200             since you're interested in the target page only. Using <member>skipBackwardUntil</member> relieves
 201             you of this.
 202
 203             @return
 204                 <TRUE/> if and only if traveling was successful
 205
 206             @see skipUntil
 207             @see skip
 208         */
 209         bool                    skipBackwardUntil(WizardTypes::WizardState nTargetState);
 210
 211         /** returns the current state of the machine
 212
 213             Vulgo, this is the identifier of the current tab page :)
 214         */
 215         WizardTypes::WizardState getCurrentState() const { return GetCurLevel(); }
 216
 217         /** returns a human readable name for a given state
 218
 219             There is a default implementation for this method, which returns the display name
 220             as given in a call to describeState. If there is no description for the given state,
 221             this is worth an assertion in a non-product build, and then an empty string is
 222             returned.
 223         */
 224         OUString  getStateDisplayName(WizardTypes::WizardState nState) const;
 225
 226         DECL_LINK( OnRoadmapItemSelected, LinkParamNone*, void );
 227
 228         /** updates the roadmap control to show the given path, as far as possible
 229             (modulo conflicts with other paths)
 230         */
 231         void implUpdateRoadmap( );
 232
 233     public:
 234         class AccessGuard
 235         {
 236             friend class RoadmapWizardTravelSuspension;
 237         private:
 238             AccessGuard() { }
 239         };
 240
 241         void                   suspendTraveling( AccessGuard );
 242         void                   resumeTraveling( AccessGuard );
 243         bool                   isTravelingSuspended() const;
 244
 245     private:
 246         void GetOrCreatePage(const WizardTypes::WizardState i_nState);
 247
 248         void             ImplCalcSize( Size& rSize );
 249         void             ImplPosCtrls();
 250         void             ImplPosTabPage();
 251         void             ImplShowTabPage( TabPage* pPage );
 252         TabPage*         ImplGetPage( sal_uInt16 nLevel ) const;
 253
 254
 255         DECL_LINK(OnNextPage, Button*, void);
 256         DECL_LINK(OnPrevPage, Button*, void);
 257         DECL_LINK(OnFinish, Button*, void);
 258
 259         void     implConstruct( const WizardButtonFlags _nButtonFlags );
 260
 261         virtual void     DumpAsPropertyTree(tools::JsonWriter& rJsonWriter) override;
 262     };
 263
 264     /// helper class to temporarily suspend any traveling in the wizard
 265     class RoadmapWizardTravelSuspension
 266     {
 267     public:
 268         RoadmapWizardTravelSuspension(RoadmapWizard& rWizard)
 269             : m_pOWizard(&rWizard)
 270         {
 271             m_pOWizard->suspendTraveling(RoadmapWizard::AccessGuard());
 272         }
 273
 274         ~RoadmapWizardTravelSuspension()
 275         {
 276             if (m_pOWizard)
 277                 m_pOWizard->resumeTraveling(RoadmapWizard::AccessGuard());
 278         }
 279
 280     private:
 281         VclPtr<RoadmapWizard> m_pOWizard;
 282     };
 283
 284 } // namespace vcl
 285
 286 #endif
 287
 288 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */