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 
26 namespace weld {
27  class Builder;
28  class Container;
29 }
30 
31 struct WizPageData;
32 struct ImplWizButtonData;
33 
34 // wizard states
35 #define WZS_INVALID_STATE (::vcl::WizardTypes::WizardState(-1))
36 
37 namespace vcl
38 {
39  //= WizardTypes
40  namespace WizardTypes
41  {
42  typedef sal_Int16 WizardState;
44  {
45  eTravelForward, // traveling forward (maybe with skipping pages)
46  eTravelBackward, // traveling backward (maybe with skipping pages)
47  eFinish, // the wizard is about to be finished
48  eValidate // the data should be validated only, no traveling will happen
49  };
50  };
51 
53  {
54  public:
55 
56  // This methods behave somewhat different than ActivatePage/DeactivatePage
57  // The latter are handled by the base class itself whenever changing the pages is in the offing,
58  // i.e., when it's already decided which page is the next.
59  // We may have situations where the next page depends on the state of the current, which needs
60  // to be committed for this.
61  // So initializePage and commitPage are designated to initializing/committing data on the page.
62  virtual void initializePage() = 0;
63  virtual bool commitPage( WizardTypes::CommitPageReason _eReason ) = 0;
64 
72  virtual bool canAdvance() const = 0;
73 
74  protected:
76  };
77 
78  //= OWizardPage
80  {
81  public:
82  OWizardPage(weld::Container* pPage, weld::DialogController* pController, const OUString& rUIXMLDescription, const OString& rID);
83  virtual ~OWizardPage() override;
84 
85  // IWizardPageController overridables
86  virtual void initializePage() override;
87  virtual bool commitPage( WizardTypes::CommitPageReason _eReason ) override;
88  virtual bool canAdvance() const override;
89 
90  protected:
91  // BuilderPage overridables
92  virtual void Activate() override;
93 
99  void updateDialogTravelUI();
100  };
101 
102  //= OWizardMachine
103  struct WizardMachineImplData;
120  {
121  protected:
123  private:
126 
127  protected:
128  std::unique_ptr<weld::Button> m_xFinish;
129  std::unique_ptr<weld::Button> m_xCancel;
130  std::unique_ptr<weld::Button> m_xNextPage;
131  std::unique_ptr<weld::Button> m_xPrevPage;
132  std::unique_ptr<weld::Button> m_xHelp;
133 
134  private:
135  // hold members in this structure to allow keeping compatible when members are added
136  std::unique_ptr<WizardMachineImplData> m_pImpl;
137 
138  public:
139  WizardMachine(weld::Window* _pParent, WizardButtonFlags _nButtonFlags );
140  virtual ~WizardMachine() override;
141 
142  bool Finish(short nResult = RET_CANCEL);
143  bool ShowPage(WizardTypes::WizardState nState);
144 
145  bool ShowNextPage();
146  bool ShowPrevPage();
147 
148  void AddPage( std::unique_ptr<BuilderPage> xPage );
149  void RemovePage( const BuilderPage* pPage );
150  void SetPage( WizardTypes::WizardState nLevel, std::unique_ptr<BuilderPage> xPage );
151  BuilderPage* GetPage( WizardTypes::WizardState eState ) const;
152 
154  void enableButtons(WizardButtonFlags _nWizardButtonFlags, bool _bEnable);
156  void defaultButton(WizardButtonFlags _nWizardButtonFlags);
158  void defaultButton(weld::Button* _pNewDefButton);
159 
161  void setTitleBase(const OUString& _rTitleBase);
162 
164  virtual bool canAdvance() const;
165 
172  virtual void updateTravelUI();
173 
174  protected:
175  virtual void ActivatePage();
176  virtual bool DeactivatePage();
177 
178  // our own overridables
179 
181  virtual std::unique_ptr<BuilderPage> createPage(WizardTypes::WizardState _nState) = 0;
182 
184  virtual void enterState(WizardTypes::WizardState _nState);
185 
196  virtual bool prepareLeaveCurrentState( WizardTypes::CommitPageReason eReason );
197 
210  virtual bool leaveState(WizardTypes::WizardState nState);
211 
218  virtual WizardTypes::WizardState determineNextState(WizardTypes::WizardState nCurrentState) const;
219 
223  virtual bool onFinish();
224 
226  bool travelNext();
227 
229  bool travelPrevious();
230 
236  void enableAutomaticNextButtonState();
237  bool isAutomaticNextButtonStateEnabled() const;
238 
241  void removePageFromHistory(WizardTypes::WizardState nToRemove);
242 
257  void skip();
258 
273  bool skipUntil(WizardTypes::WizardState nTargetState);
274 
291  bool skipBackwardUntil(WizardTypes::WizardState nTargetState);
292 
297  WizardTypes::WizardState getCurrentState() const { return m_nCurState; }
298 
299  virtual IWizardPageController* getPageController(BuilderPage* pCurrentPage) const;
300 
303  void getStateHistory(std::vector<WizardTypes::WizardState>& out_rHistory);
304 
305  public:
307  {
309  private:
311  };
312 
313  void suspendTraveling( AccessGuard );
314  void resumeTraveling( AccessGuard );
315  bool isTravelingSuspended() const;
316 
317  protected:
318  BuilderPage* GetOrCreatePage(const WizardTypes::WizardState i_nState);
319 
320  private:
321  DECL_DLLPRIVATE_LINK(OnNextPage, weld::Button&, void);
322  DECL_DLLPRIVATE_LINK(OnPrevPage, weld::Button&, void);
323  DECL_DLLPRIVATE_LINK(OnFinish, weld::Button&, void);
324  DECL_DLLPRIVATE_LINK(OnCancel, weld::Button&, void);
325 
326  VCL_DLLPRIVATE void implUpdateTitle();
327  VCL_DLLPRIVATE void implConstruct( const WizardButtonFlags _nButtonFlags );
328  };
329 
330 
333  {
334  public:
336  : m_pWizard(&rWizard)
337  {
339  }
340 
342  {
344  }
345 
346  private:
348  };
349 } // namespace vcl
350 
351 #define WIZARDDIALOG_BUTTON_STDOFFSET_X 6
352 #define WIZARDDIALOG_BUTTON_SMALLSTDOFFSET_X 3
353 
354 #endif // INCLUDED_VCL_WIZARDMACHINE_HXX
355 
356 /* 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:280
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