include/vcl/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_VCL_ROADMAPWIZARD_HXX
  21 #define INCLUDED_VCL_ROADMAPWIZARD_HXX
  22
  23 #include <memory>
  24 #include <vcl/dllapi.h>
  25 #include <vcl/wizardmachine.hxx>
  26
  27 namespace vcl
  28 {
  29     struct RoadmapWizardImpl;
  30
  31     namespace RoadmapWizardTypes
  32     {
  33         typedef sal_Int16                                   PathId;
  34         typedef ::std::vector< WizardTypes::WizardState >   WizardPath;
  35     };
  36
  37     //= RoadmapWizard
  38
  39     /** is - no, not a wizard for a roadmap, but the base class for wizards
  40         <em>supporting</em> a roadmap.
  41
  42         The basic new concept introduced is a <em>path</em>:<br/>
  43         A <em>path</em> is a sequence of states, which are to be executed in a linear order.
  44         Elements in the path can be skipped, depending on choices the user makes.
  45
  46         In the most simple wizards, you will have only one path consisting of <code>n</code> elements,
  47         which are to be visited successively.
  48
  49         In a slightly more complex wizard, you will have one linear path, were certain
  50         steps might be skipped due to user input. For instance, the user may decide to not specify
  51         certain aspects of the to-be-created object (e.g. by unchecking a check box),
  52         and the wizard then will simply disable the step which corresponds to this step.
  53
  54         In a yet more advanced wizards, you will have several paths of length <code>n1</code> and
  55         <code>n2</code>, which share at least the first <code>k</code> states (where <code>k</code>
  56         is at least 1), and an arbitrary number of other states.
  57     */
  58     class VCL_DLLPUBLIC RoadmapWizardMachine : public vcl::WizardMachine
  59     {
  60     private:
  61         std::unique_ptr<RoadmapWizardImpl>  m_pImpl;
  62
  63     public:
  64         RoadmapWizardMachine(weld::Window* _pParent);
  65         virtual ~RoadmapWizardMachine( ) override;
  66
  67         void            SetRoadmapHelpId( const OUString& _rId );
  68
  69         // returns whether a given state is enabled
  70         bool            isStateEnabled(WizardTypes::WizardState nState) const;
  71
  72         // WizardDialog overridables
  73         virtual bool    canAdvance() const override;
  74         virtual void    updateTravelUI() override;
  75
  76     protected:
  77         /** declares a valid path in the wizard
  78
  79             The very first path which is declared is automatically activated.
  80
  81             Note that all paths which are declared must have the very first state in
  82             common. Also note that due to a restriction of the very base class (WizardDialog),
  83             this common first state must be 0.
  84
  85             You cannot declare new paths once the wizard started, so it's recommended that
  86             you do all declarations within your derivee's constructor.
  87
  88             @see activatePath
  89
  90             @param _nId
  91                 the unique id you wish to give this path. This id can later on be used
  92                 to refer to the path which you just declared
  93         */
  94         void    declarePath( RoadmapWizardTypes::PathId _nPathId, const RoadmapWizardTypes::WizardPath& _lWizardStates);
  95
  96         /** activates a path which has previously been declared with <member>declarePath</member>
  97
  98             You can only activate paths which share the first <code>k</code> states with the path
  99             which is previously active (if any), where <code>k</code> is the index of the
 100             current state within the current path.
 101
 102             <example>
 103             Say you have paths, <code>(0,1,2,5)</code> and <code>(0,1,4,5)</code>. This means that after
 104             step <code>1</code>, you either continue with state <code>2</code> or state <code>4</code>,
 105             and after this, you finish in state <code>5</code>.<br/>
 106             Now if the first path is active, and your current state is <code>1</code>, then you can
 107             easily switch to the second path, since both paths start with <code>(0,1)</code>.<br/>
 108             However, if your current state is <code>2</code>, then you can not switch to the second
 109             path anymore.
 110             </example>
 111
 112             @param _nPathId
 113                 the id of the path. The path must have been declared (under this id) with
 114                 <member>declarePath</member> before it can be activated.
 115
 116             @param _bDecideForIt
 117                 If <TRUE/>, the path will be completely activated, even if it is a conflicting path
 118                 (i.e. there is another path which shares the first <code>k</code> states with
 119                 the to-be-activated path.)<br/>
 120                 If <FALSE/>, then the new path is checked for conflicts with other paths. If such
 121                 conflicts exists, the path is not completely activated, but only up to the point
 122                 where it does <em>not</em> conflict.<br/>
 123                 With the paths in the example above, if you activate the second path (when both are
 124                 already declared), then only steps <code>0</code> and <code>1</code> are activated,
 125                 since they are common to both paths.
 126         */
 127         void    activatePath( RoadmapWizardTypes::PathId _nPathId, bool _bDecideForIt = false );
 128
 129         /** determine the next state to travel from the given one
 130
 131             This method (which is declared in WizardMachine and overwritten here)
 132             ensures that traveling happens along the active path.
 133
 134             @see activatePath
 135         */
 136         virtual WizardTypes::WizardState determineNextState(WizardTypes::WizardState nCurrentState) const override;
 137
 138         /** en- or disables a state
 139
 140             In the wizard's roadmap, states to travel to can be freely chosen. To prevent
 141             users from selecting a state which is currently not available, you can declare this
 142             state as being disabled.
 143
 144             A situation where you need this may be when you have a checkbox which, when checked
 145             by the user, enables a page with additional settings. As long as this checkbox is
 146             not checked, the respective state would be disabled.
 147
 148             Note that in theory, you can declare multiple paths, instead of disabling states.
 149             For instance, if you have a path where one state can be potentially disabled, then
 150             you could declare a second path, which does not contain this state. However, the
 151             disadvantage is that then, not the complete path would be visible in the roadmap,
 152             but only all steps up to the point where the both paths diverge.<br/>
 153             Another disadvantage is that the number of needed paths grows exponentially with
 154             the number of states which can be potentially disabled.
 155
 156             @see declarePath
 157         */
 158         void    enableState(WizardTypes::WizardState nState, bool _bEnable = true);
 159
 160         /** returns true if and only if the given state is known in at least one declared path
 161         */
 162         bool    knowsState(WizardTypes::WizardState nState) const;
 163
 164         // WizardMachine overriables
 165         virtual void            enterState(WizardTypes::WizardState nState) override;
 166
 167         /** returns a human readable name for a given state
 168
 169             There is a default implementation for this method, which returns the display name
 170             as given in a call to describeState. If there is no description for the given state,
 171             this is worth an assertion in a non-product build, and then an empty string is
 172             returned.
 173         */
 174         virtual OUString  getStateDisplayName(WizardTypes::WizardState nState) const;
 175
 176     private:
 177         DECL_DLLPRIVATE_LINK( OnRoadmapItemSelected, const OUString&, bool );
 178
 179         /** updates the roadmap control to show the given path, as far as possible
 180             (modulo conflicts with other paths)
 181         */
 182         VCL_DLLPRIVATE void implUpdateRoadmap( );
 183     };
 184 } // namespace vcl
 185
 186
 187 #endif // OOO_ INCLUDED_VCL_ROADMAPWIZARD_HXX
 188
 189 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */