Branch data Line data Source code
1 : : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 : : /*************************************************************************
3 : : *
4 : : * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 : : *
6 : : * Copyright 2000, 2010 Oracle and/or its affiliates.
7 : : *
8 : : * OpenOffice.org - a multi-platform office productivity suite
9 : : *
10 : : * This file is part of OpenOffice.org.
11 : : *
12 : : * OpenOffice.org is free software: you can redistribute it and/or modify
13 : : * it under the terms of the GNU Lesser General Public License version 3
14 : : * only, as published by the Free Software Foundation.
15 : : *
16 : : * OpenOffice.org is distributed in the hope that it will be useful,
17 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 : : * GNU Lesser General Public License version 3 for more details
20 : : * (a copy is included in the LICENSE file that accompanied this code).
21 : : *
22 : : * You should have received a copy of the GNU Lesser General Public License
23 : : * version 3 along with OpenOffice.org. If not, see
24 : : * <http://www.openoffice.org/license.html>
25 : : * for a copy of the LGPLv3 License.
26 : : *
27 : : ************************************************************************/
28 : :
29 : : #ifndef SVTOOLS_INC_ROADMAPWIZARD_HXX
30 : : #define SVTOOLS_INC_ROADMAPWIZARD_HXX
31 : :
32 : : #include "svtools/svtdllapi.h"
33 : : #include <svtools/wizardmachine.hxx>
34 : :
35 : : //........................................................................
36 : : namespace svt
37 : : {
38 : : //........................................................................
39 : :
40 : : struct RoadmapWizardImpl;
41 : : class RoadmapWizard;
42 : :
43 : 0 : struct RoadmapWizardTypes
44 : : {
45 : : public:
46 : : typedef sal_Int16 PathId;
47 : : typedef ::std::vector< WizardTypes::WizardState > WizardPath;
48 : : typedef TabPage* (* RoadmapPageFactory)( RoadmapWizard& );
49 : : };
50 : :
51 : : //====================================================================
52 : : //= RoadmapWizard
53 : : //====================================================================
54 : : /** is - no, not a wizard for a raodmap, but the base class for wizards
55 : : <em>supporting</em> a roadmap.
56 : :
57 : : The basic new concept introduced is a <em>path</em>:<br/>
58 : : A <em>path</em> is a sequence of states, which are to be executed in a linear order.
59 : : Elements in the path can be skipped, depending on choices the user makes.
60 : :
61 : : In the most simple wizards, you will have only one path consisting of <code>n</code> elements,
62 : : which are to be visited successively.
63 : :
64 : : In a slightly more complex wizard, you will have one linear path, were certain
65 : : steps might be skipped due to user input. For instance, the user may decide to not specify
66 : : certain aspects of the to-be-created object (e.g. by unchecking a check box),
67 : : and the wizard then will simply disable the step which corresponds to this step.
68 : :
69 : : In a yet more advanced wizards, you will have several paths of length <code>n1</code> and
70 : : <code>n2</code>, which share at least the first <code>k</code> states (where <code>k</code>
71 : : is at least 1), and an arbitrary number of other states.
72 : : */
73 : : class SVT_DLLPUBLIC RoadmapWizard : public OWizardMachine, public RoadmapWizardTypes
74 : : {
75 : : private:
76 : : RoadmapWizardImpl* m_pImpl;
77 : :
78 : : public:
79 : : RoadmapWizard(
80 : : Window* _pParent,
81 : : const ResId& _rRes,
82 : : sal_uInt32 _nButtonFlags = WZB_NEXT | WZB_PREVIOUS | WZB_FINISH | WZB_CANCEL | WZB_HELP
83 : : );
84 : : RoadmapWizard(
85 : : Window* _pParent,
86 : : const WinBits i_nStyle,
87 : : sal_uInt32 _nButtonFlags = WZB_NEXT | WZB_PREVIOUS | WZB_FINISH | WZB_CANCEL | WZB_HELP
88 : : );
89 : : ~RoadmapWizard( );
90 : :
91 : : void SetRoadmapHelpId( const rtl::OString& _rId );
92 : :
93 : : void SetRoadmapInteractive( sal_Bool _bInteractive );
94 : : virtual void Resize();
95 : : virtual void StateChanged( StateChangedType nStateChange );
96 : :
97 : : // returns whether a given state is enabled
98 : : bool isStateEnabled( WizardState _nState ) const;
99 : :
100 : : // WizardDialog overridables
101 : : virtual bool canAdvance() const;
102 : : virtual void updateTravelUI();
103 : :
104 : : protected:
105 : : /** declares a valid path in the wizard
106 : :
107 : : The very first path which is declared is automatically activated.
108 : :
109 : : Note that all paths which are declared must have the very first state in
110 : : common. Also note that due to a restriction of the very base class (<type>WizardDialog</type>),
111 : : this common first state must be 0.
112 : :
113 : : You cannot declare new paths once the wizard started, so it's recommended that
114 : : you do all declarations within your derivee's constructor.
115 : :
116 : : @see activatePath
117 : :
118 : : @param _nId
119 : : the unique id you wish to give this path. This id can later on be used
120 : : to refer to the path which you just declared
121 : :
122 : : @param _nFirstState
123 : : the first state in this path. Must not be WZS_INVALID_STATE.<br/>
124 : : Declare an arbitrary number of states after this one, and terminate the sequence
125 : : with a WZS_INVALID_STATE.
126 : : */
127 : : void declarePath( PathId _nPathId, WizardState _nFirstState, ... );
128 : : void declarePath( PathId _nPathId, const WizardPath& _lWizardStates);
129 : :
130 : : /** provides basic information about a state
131 : :
132 : : The given display name is used in the default implementation of getStateDisplayName,
133 : : and the given factory is used in the default implementation of createPage.
134 : : */
135 : : void describeState( WizardState _nState, const String& _rStateDisplayName, RoadmapPageFactory _pPageFactory );
136 : :
137 : : /** activates a path which has previously been declared with <member>declarePath</member>
138 : :
139 : : You can only activate paths which share the first <code>k</code> states with the path
140 : : which is previously active (if any), where <code>k</code> is the index of the
141 : : current state within the current path.
142 : :
143 : : <example>
144 : : Say you have paths, <code>(0,1,2,5)</code> and <code>(0,1,4,5)</code>. This means that after
145 : : step <code>1</code>, you either continue with state <code>2</code> or state <code>4</code>,
146 : : and after this, you finish in state <code>5</code>.<br/>
147 : : Now if the first path is active, and your current state is <code>1</code>, then you can
148 : : easily switch to the second path, since both paths start with <code>(0,1)</code>.<br/>
149 : : However, if your current state is <code>2</code>, then you can not switch to the second
150 : : path anymore.
151 : : </example>
152 : :
153 : : @param _nPathId
154 : : the id of the path. The path must have been declared (under this id) with
155 : : <member>declarePath</member> before it can be activated.
156 : :
157 : : @param _bDecideForIt
158 : : If <TRUE/>, the path will be completely activated, even if it is a conflicting path
159 : : (i.e. there is another path which shares the first <code>k</code> states with
160 : : the to-be-activated path.)<br/>
161 : : If <FALSE/>, then the new path is checked for conflicts with other paths. If such
162 : : conflicts exists, the path is not completely activated, but only up to the point
163 : : where it does <em>not</em> conflict.<br/>
164 : : With the paths in the example above, if you activate the second path (when both are
165 : : already declared), then only steps <code>0</code> and <code>1</code> are activated,
166 : : since they are common to both paths.
167 : : */
168 : : void activatePath( PathId _nPathId, bool _bDecideForIt = false );
169 : :
170 : : /** determine the next state to travel from the given one
171 : :
172 : : This method (which is declared in <type>OWizardMachine</type> and overwritten here)
173 : : ensures that traveling happens along the active path.
174 : :
175 : : @see activatePath
176 : : */
177 : : virtual WizardState determineNextState( WizardState _nCurrentState ) const;
178 : :
179 : : /** en- or disables a state
180 : :
181 : : In the wizard's roadmap, states to travel to can be freely chosen. To prevent
182 : : users from selecting a state which is currently not available, you can declare this
183 : : state as being disabled.
184 : :
185 : : A situation where you need this may be when you have a checkbox which, when checked
186 : : by the user, enables a page with additional settings. As long as this checkbox is
187 : : not checked, the respective state would be disabled.
188 : :
189 : : Note that in theory, you can declare multiple paths, instead of disabling states.
190 : : For instance, if you have a path where one state can be potentially disabled, then
191 : : you could declare a second path, which does not contain this state. However, the
192 : : disadvantage is that then, not the complete path would be visible in the roadmap,
193 : : but only all steps up to the point where the both paths diverge.<br/>
194 : : Another disadvantage is that the number of needed paths grows exponentially with
195 : : the number of states which can be potentially disabled.
196 : :
197 : : @see declarePath
198 : : */
199 : : void enableState( WizardState _nState, bool _bEnable = true );
200 : :
201 : : /** returns true if and only if the given state is known in at least one declared path
202 : : */
203 : : bool knowsState( WizardState _nState ) const;
204 : :
205 : : // OWizardMachine overriables
206 : : virtual void enterState( WizardState _nState );
207 : :
208 : : /** returns a human readable name for a given state
209 : :
210 : : There is a default implementation for this method, which returns the display name
211 : : as given in a call to describeState. If there is no description for the given state,
212 : : this is worth an assertion in a non-product build, and then an empty string is
213 : : returned.
214 : : */
215 : : virtual String getStateDisplayName( WizardState _nState ) const;
216 : :
217 : : /** creates a page for a given state
218 : :
219 : : This member is inherited from OWizardMachine, and default-implemented in this class
220 : : for all states which have been described using describeState.
221 : : */
222 : : virtual TabPage* createPage( WizardState _nState );
223 : :
224 : : /** asks for a new label of the wizard page
225 : :
226 : : */
227 : : void updateRoadmapItemLabel( WizardState _nState );
228 : :
229 : : protected:
230 : : #ifdef DBG_UTIL
231 : : const sal_Char* checkInvariants() const;
232 : : friend const char* CheckInvariants( const void* pVoid );
233 : : #endif
234 : :
235 : : private:
236 : : SVT_DLLPRIVATE void ResizeFixedLine();
237 : :
238 : : DECL_DLLPRIVATE_LINK( OnRoadmapItemSelected, void* );
239 : :
240 : : /** updates the roadmap control to show the given path, as far as possible
241 : : (modulo conflicts with other paths)
242 : : */
243 : : SVT_DLLPRIVATE void implUpdateRoadmap( );
244 : :
245 : : private:
246 : : SVT_DLLPRIVATE void impl_construct();
247 : : };
248 : :
249 : : //........................................................................
250 : : } // namespace svt
251 : : //........................................................................
252 : :
253 : : #endif // OOO_SVTOOLS_INC_ROADMAPWIZARD_HXX
254 : :
255 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
