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