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
26namespace weld {
27 class Builder;
28 class Container;
29}
30
31struct WizPageData;
33
34// wizard states
35#define WZS_INVALID_STATE (::vcl::WizardTypes::WizardState(-1))
36
37namespace 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
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:
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: */
virtual bool canAdvance() const =0
determines whether or not it is allowed to advance to a next page
virtual void initializePage()=0
virtual bool commitPage(WizardTypes::CommitPageReason _eReason)=0
implements some kind of finite automata, where the states of the automata exactly correlate with tab ...
std::unique_ptr< weld::Button > m_xNextPage
std::unique_ptr< weld::Button > m_xCancel
DECL_DLLPRIVATE_LINK(OnNextPage, weld::Button &, void)
std::unique_ptr< weld::Button > m_xPrevPage
std::unique_ptr< weld::Button > m_xHelp
WizardTypes::WizardState m_nCurState
DECL_DLLPRIVATE_LINK(OnFinish, weld::Button &, void)
std::unique_ptr< weld::Button > m_xFinish
std::unique_ptr< WizardMachineImplData > m_pImpl
void resumeTraveling(AccessGuard)
DECL_DLLPRIVATE_LINK(OnPrevPage, weld::Button &, void)
DECL_DLLPRIVATE_LINK(OnCancel, weld::Button &, void)
virtual std::unique_ptr< BuilderPage > createPage(WizardTypes::WizardState _nState)=0
to override to create new pages
WizPageData * m_pFirstPage
WizardTypes::WizardState getCurrentState() const
returns the current state of the machine
BuilderPage * m_pCurTabPage
void suspendTraveling(AccessGuard)
helper class to temporarily suspend any traveling in the wizard
WizardTravelSuspension(WizardMachine &rWizard)
#define VCL_DLLPRIVATE
Definition: dllapi.h:31
#define VCL_DLLPUBLIC
Definition: dllapi.h:29
sal_Int16 WizardState
#define SAL_NO_VTABLE
WizardButtonFlags
Definition: vclenum.hxx:257
@ RET_CANCEL
Definition: vclenum.hxx:212