LibreOffice Module vcl (master)  1
wizardmachine.hxx
Go to the documentation of this file.
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 #ifndef INCLUDED_VCL_WIZARDMACHINE_HXX
20 #define INCLUDED_VCL_WIZARDMACHINE_HXX
21 
22 #include <memory>
23 #include <vcl/dllapi.h>
24 #include <vcl/builderpage.hxx>
25 #include <vcl/idle.hxx>
26 
27 namespace weld {
28  class Builder;
29  class Container;
30 }
31 
32 struct WizPageData;
33 struct ImplWizButtonData;
34 
35 // wizard states
36 #define WZS_INVALID_STATE (::vcl::WizardTypes::WizardState(-1))
37 
38 namespace vcl
39 {
40  //= WizardTypes
41  namespace WizardTypes
42  {
43  typedef sal_Int16 WizardState;
45  {
46  eTravelForward, // traveling forward (maybe with skipping pages)
47  eTravelBackward, // traveling backward (maybe with skipping pages)
48  eFinish, // the wizard is about to be finished
49  eValidate // the data should be validated only, no traveling will happen
50  };
51  };
52 
54  {
55  public:
56 
57  // This methods behave somewhat different than ActivatePage/DeactivatePage
58  // The latter are handled by the base class itself whenever changing the pages is in the offing,
59  // i.e., when it's already decided which page is the next.
60  // We may have situations where the next page depends on the state of the current, which needs
61  // to be committed for this.
62  // So initializePage and commitPage are designated to initializing/committing data on the page.
63  virtual void initializePage() = 0;
64  virtual bool commitPage( WizardTypes::CommitPageReason _eReason ) = 0;
65 
73  virtual bool canAdvance() const = 0;
74 
75  protected:
77  };
78 
79  //= OWizardPage
81  {
82  public:
83  OWizardPage(weld::Container* pPage, weld::DialogController* pController, const OUString& rUIXMLDescription, const OString& rID);
84  virtual ~OWizardPage() override;
85 
86  // IWizardPageController overridables
87  virtual void initializePage() override;
88  virtual bool commitPage( WizardTypes::CommitPageReason _eReason ) override;
89  virtual bool canAdvance() const override;
90 
91  protected:
92  // BuilderPage overridables
93  virtual void Activate() override;
94 
100  void updateDialogTravelUI();
101  };
102 
103  //= OWizardMachine
104  struct WizardMachineImplData;
121  {
122  protected:
124  private:
127 
128  protected:
129  std::unique_ptr<weld::Button> m_xFinish;
130  std::unique_ptr<weld::Button> m_xCancel;
131  std::unique_ptr<weld::Button> m_xNextPage;
132  std::unique_ptr<weld::Button> m_xPrevPage;
133  std::unique_ptr<weld::Button> m_xHelp;
134 
135  private:
136  // hold members in this structure to allow keeping compatible when members are added
137  std::unique_ptr<WizardMachineImplData> m_pImpl;
138 
139  public:
140  WizardMachine(weld::Window* _pParent, WizardButtonFlags _nButtonFlags );
141  virtual ~WizardMachine() override;
142 
143  bool Finish(short nResult = RET_CANCEL);
144  bool ShowPage(WizardTypes::WizardState nState);
145 
146  bool ShowNextPage();
147  bool ShowPrevPage();
148 
149  void AddPage( std::unique_ptr<BuilderPage> xPage );
150  void RemovePage( const BuilderPage* pPage );
151  void SetPage( WizardTypes::WizardState nLevel, std::unique_ptr<BuilderPage> xPage );
152  BuilderPage* GetPage( WizardTypes::WizardState eState ) const;
153 
155  void enableButtons(WizardButtonFlags _nWizardButtonFlags, bool _bEnable);
157  void defaultButton(WizardButtonFlags _nWizardButtonFlags);
159  void defaultButton(weld::Button* _pNewDefButton);
160 
162  void setTitleBase(const OUString& _rTitleBase);
163 
165  virtual bool canAdvance() const;
166 
173  virtual void updateTravelUI();
174 
175  protected:
176  virtual void ActivatePage();
177  virtual bool DeactivatePage();
178 
179  // our own overridables
180 
182  virtual std::unique_ptr<BuilderPage> createPage(WizardTypes::WizardState _nState) = 0;
183 
185  virtual void enterState(WizardTypes::WizardState _nState);
186 
197  virtual bool prepareLeaveCurrentState( WizardTypes::CommitPageReason eReason );
198 
211  virtual bool leaveState(WizardTypes::WizardState nState);
212 
219  virtual WizardTypes::WizardState determineNextState(WizardTypes::WizardState nCurrentState) const;
220 
224  virtual bool onFinish();
225 
227  bool travelNext();
228 
230  bool travelPrevious();
231 
237  void enableAutomaticNextButtonState();
238  bool isAutomaticNextButtonStateEnabled() const;
239 
242  void removePageFromHistory(WizardTypes::WizardState nToRemove);
243 
258  void skip();
259 
274  bool skipUntil(WizardTypes::WizardState nTargetState);
275 
292  bool skipBackwardUntil(WizardTypes::WizardState nTargetState);
293 
298  WizardTypes::WizardState getCurrentState() const { return m_nCurState; }
299 
300  virtual IWizardPageController* getPageController(BuilderPage* pCurrentPage) const;
301 
304  void getStateHistory(std::vector<WizardTypes::WizardState>& out_rHistory);
305 
306  public:
308  {
310  private:
312  };
313 
314  void suspendTraveling( AccessGuard );
315  void resumeTraveling( AccessGuard );
316  bool isTravelingSuspended() const;
317 
318  protected:
319  BuilderPage* GetOrCreatePage(const WizardTypes::WizardState i_nState);
320 
321  private:
322  DECL_DLLPRIVATE_LINK(OnNextPage, weld::Button&, void);
323  DECL_DLLPRIVATE_LINK(OnPrevPage, weld::Button&, void);
324  DECL_DLLPRIVATE_LINK(OnFinish, weld::Button&, void);
325  DECL_DLLPRIVATE_LINK(OnCancel, weld::Button&, void);
326 
327  VCL_DLLPRIVATE void implUpdateTitle();
328  VCL_DLLPRIVATE void implConstruct( const WizardButtonFlags _nButtonFlags );
329  };
330 
331 
334  {
335  public:
337  : m_pWizard(&rWizard)
338  {
340  }
341 
343  {
345  }
346 
347  private:
349  };
350 } // namespace vcl
351 
352 #define WIZARDDIALOG_BUTTON_STDOFFSET_X 6
353 #define WIZARDDIALOG_BUTTON_SMALLSTDOFFSET_X 3
354 
355 #endif // INCLUDED_VCL_WIZARDMACHINE_HXX
356 
357 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
std::unique_ptr< weld::Button > m_xPrevPage
void suspendTraveling(AccessGuard)
#define VCL_DLLPUBLIC
Definition: dllapi.h:29
std::unique_ptr< WizardMachineImplData > m_pImpl
std::unique_ptr< weld::Button > m_xHelp
WizardButtonFlags
Definition: vclenum.hxx:276
std::unique_ptr< weld::Button > m_xCancel
WizPageData * m_pFirstPage
std::unique_ptr< weld::Button > m_xNextPage
sal_Int16 WizardState
implements some kind of finite automata, where the states of the automata exactly correlate with tab ...
WizardTypes::WizardState getCurrentState() const
returns the current state of the machine
std::unique_ptr< weld::Button > m_xFinish
WizardTravelSuspension(WizardMachine &rWizard)
void resumeTraveling(AccessGuard)
#define VCL_DLLPRIVATE
Definition: dllapi.h:31
BuilderPage * m_pCurTabPage
#define SAL_NO_VTABLE
WizardTypes::WizardState m_nCurState
helper class to temporarily suspend any traveling in the wizard