include/svtools/roadmapwizard.hxx

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