Line data Source code
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 SVTOOLS_INC_ROADMAPWIZARD_HXX
21 : #define SVTOOLS_INC_ROADMAPWIZARD_HXX
22 :
23 : #include "svtools/svtdllapi.h"
24 : #include <svtools/wizardmachine.hxx>
25 :
26 : //........................................................................
27 : namespace svt
28 : {
29 : //........................................................................
30 :
31 : struct RoadmapWizardImpl;
32 : class RoadmapWizard;
33 :
34 0 : struct RoadmapWizardTypes
35 : {
36 : public:
37 : typedef sal_Int16 PathId;
38 : typedef ::std::vector< WizardTypes::WizardState > WizardPath;
39 : typedef TabPage* (* RoadmapPageFactory)( RoadmapWizard& );
40 : };
41 :
42 : //====================================================================
43 : //= RoadmapWizard
44 : //====================================================================
45 : /** is - no, not a wizard for a raodmap, but the base class for wizards
46 : <em>supporting</em> 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 SVT_DLLPUBLIC RoadmapWizard : public OWizardMachine, public RoadmapWizardTypes
65 : {
66 : private:
67 : RoadmapWizardImpl* m_pImpl;
68 :
69 : public:
70 : RoadmapWizard(
71 : Window* _pParent,
72 : const ResId& _rRes,
73 : sal_uInt32 _nButtonFlags = WZB_NEXT | WZB_PREVIOUS | WZB_FINISH | WZB_CANCEL | WZB_HELP
74 : );
75 : RoadmapWizard(
76 : Window* _pParent,
77 : const WinBits i_nStyle,
78 : sal_uInt32 _nButtonFlags = WZB_NEXT | WZB_PREVIOUS | WZB_FINISH | WZB_CANCEL | WZB_HELP
79 : );
80 : ~RoadmapWizard( );
81 :
82 : void SetRoadmapHelpId( const rtl::OString& _rId );
83 :
84 : void SetRoadmapInteractive( sal_Bool _bInteractive );
85 : virtual void Resize();
86 : virtual void StateChanged( StateChangedType nStateChange );
87 :
88 : // returns whether a given state is enabled
89 : bool isStateEnabled( WizardState _nState ) const;
90 :
91 : // WizardDialog overridables
92 : virtual bool canAdvance() const;
93 : virtual void updateTravelUI();
94 :
95 : protected:
96 : /** declares a valid path in the wizard
97 :
98 : The very first path which is declared is automatically activated.
99 :
100 : Note that all paths which are declared must have the very first state in
101 : common. Also note that due to a restriction of the very base class (<type>WizardDialog</type>),
102 : this common first state must be 0.
103 :
104 : You cannot declare new paths once the wizard started, so it's recommended that
105 : you do all declarations within your derivee's constructor.
106 :
107 : @see activatePath
108 :
109 : @param _nId
110 : the unique id you wish to give this path. This id can later on be used
111 : to refer to the path which you just declared
112 :
113 : @param _nFirstState
114 : the first state in this path. Must not be WZS_INVALID_STATE.<br/>
115 : Declare an arbitrary number of states after this one, and terminate the sequence
116 : with a WZS_INVALID_STATE.
117 : */
118 : void declarePath( PathId _nPathId, WizardState _nFirstState, ... );
119 : void declarePath( PathId _nPathId, const WizardPath& _lWizardStates);
120 :
121 : /** provides basic information about a state
122 :
123 : The given display name is used in the default implementation of getStateDisplayName,
124 : and the given factory is used in the default implementation of createPage.
125 : */
126 : void describeState( WizardState _nState, const String& _rStateDisplayName, RoadmapPageFactory _pPageFactory );
127 :
128 : /** activates a path which has previously been declared with <member>declarePath</member>
129 :
130 : You can only activate paths which share the first <code>k</code> states with the path
131 : which is previously active (if any), where <code>k</code> is the index of the
132 : current state within the current path.
133 :
134 : <example>
135 : Say you have paths, <code>(0,1,2,5)</code> and <code>(0,1,4,5)</code>. This means that after
136 : step <code>1</code>, you either continue with state <code>2</code> or state <code>4</code>,
137 : and after this, you finish in state <code>5</code>.<br/>
138 : Now if the first path is active, and your current state is <code>1</code>, then you can
139 : easily switch to the second path, since both paths start with <code>(0,1)</code>.<br/>
140 : However, if your current state is <code>2</code>, then you can not switch to the second
141 : path anymore.
142 : </example>
143 :
144 : @param _nPathId
145 : the id of the path. The path must have been declared (under this id) with
146 : <member>declarePath</member> before it can be activated.
147 :
148 : @param _bDecideForIt
149 : If <TRUE/>, the path will be completely activated, even if it is a conflicting path
150 : (i.e. there is another path which shares the first <code>k</code> states with
151 : the to-be-activated path.)<br/>
152 : If <FALSE/>, then the new path is checked for conflicts with other paths. If such
153 : conflicts exists, the path is not completely activated, but only up to the point
154 : where it does <em>not</em> conflict.<br/>
155 : With the paths in the example above, if you activate the second path (when both are
156 : already declared), then only steps <code>0</code> and <code>1</code> are activated,
157 : since they are common to both paths.
158 : */
159 : void activatePath( PathId _nPathId, bool _bDecideForIt = false );
160 :
161 : /** determine the next state to travel from the given one
162 :
163 : This method (which is declared in <type>OWizardMachine</type> and overwritten here)
164 : ensures that traveling happens along the active path.
165 :
166 : @see activatePath
167 : */
168 : virtual WizardState determineNextState( WizardState _nCurrentState ) const;
169 :
170 : /** en- or disables a state
171 :
172 : In the wizard's roadmap, states to travel to can be freely chosen. To prevent
173 : users from selecting a state which is currently not available, you can declare this
174 : state as being disabled.
175 :
176 : A situation where you need this may be when you have a checkbox which, when checked
177 : by the user, enables a page with additional settings. As long as this checkbox is
178 : not checked, the respective state would be disabled.
179 :
180 : Note that in theory, you can declare multiple paths, instead of disabling states.
181 : For instance, if you have a path where one state can be potentially disabled, then
182 : you could declare a second path, which does not contain this state. However, the
183 : disadvantage is that then, not the complete path would be visible in the roadmap,
184 : but only all steps up to the point where the both paths diverge.<br/>
185 : Another disadvantage is that the number of needed paths grows exponentially with
186 : the number of states which can be potentially disabled.
187 :
188 : @see declarePath
189 : */
190 : void enableState( WizardState _nState, bool _bEnable = true );
191 :
192 : /** returns true if and only if the given state is known in at least one declared path
193 : */
194 : bool knowsState( WizardState _nState ) const;
195 :
196 : // OWizardMachine overriables
197 : virtual void enterState( WizardState _nState );
198 :
199 : /** returns a human readable name for a given state
200 :
201 : There is a default implementation for this method, which returns the display name
202 : as given in a call to describeState. If there is no description for the given state,
203 : this is worth an assertion in a non-product build, and then an empty string is
204 : returned.
205 : */
206 : virtual String getStateDisplayName( WizardState _nState ) const;
207 :
208 : /** creates a page for a given state
209 :
210 : This member is inherited from OWizardMachine, and default-implemented in this class
211 : for all states which have been described using describeState.
212 : */
213 : virtual TabPage* createPage( WizardState _nState );
214 :
215 : /** asks for a new label of the wizard page
216 :
217 : */
218 : void updateRoadmapItemLabel( WizardState _nState );
219 :
220 : protected:
221 : #ifdef DBG_UTIL
222 : const sal_Char* checkInvariants() const;
223 : friend const char* CheckInvariants( const void* pVoid );
224 : #endif
225 :
226 : private:
227 : SVT_DLLPRIVATE void ResizeFixedLine();
228 :
229 : DECL_DLLPRIVATE_LINK( OnRoadmapItemSelected, void* );
230 :
231 : /** updates the roadmap control to show the given path, as far as possible
232 : (modulo conflicts with other paths)
233 : */
234 : SVT_DLLPRIVATE void implUpdateRoadmap( );
235 :
236 : private:
237 : SVT_DLLPRIVATE void impl_construct();
238 : };
239 :
240 : //........................................................................
241 : } // namespace svt
242 : //........................................................................
243 :
244 : #endif // OOO_SVTOOLS_INC_ROADMAPWIZARD_HXX
245 :
246 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
