LCOV - code coverage report
Current view: top level - include/svtools - roadmapwizard.hxx (source / functions) Hit Total Coverage
Test: commit e02a6cb2c3e2b23b203b422e4e0680877f232636 Lines: 0 1 0.0 %
Date: 2014-04-14 Functions: 0 1 0.0 %
Legend: Lines: hit not hit

          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 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           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 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             :         virtual ~RoadmapWizard( );
      81             : 
      82             :         void            SetRoadmapHelpId( const OString& _rId );
      83             : 
      84             :         void            SetRoadmapInteractive( bool _bInteractive );
      85             :         virtual void    Resize() SAL_OVERRIDE;
      86             :         virtual void    StateChanged( StateChangedType nStateChange ) SAL_OVERRIDE;
      87             : 
      88             :         // returns whether a given state is enabled
      89             :         bool            isStateEnabled( WizardState _nState ) const;
      90             : 
      91             :         // WizardDialog overridables
      92             :         virtual bool    canAdvance() const SAL_OVERRIDE;
      93             :         virtual void    updateTravelUI() SAL_OVERRIDE;
      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 (WizardDialog),
     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 OUString& _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 OWizardMachine and overwritten here)
     164             :             ensures that traveling happens along the active path.
     165             : 
     166             :             @see activatePath
     167             :         */
     168             :         virtual WizardState     determineNextState( WizardState _nCurrentState ) const SAL_OVERRIDE;
     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 ) SAL_OVERRIDE;
     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 OUString  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 ) SAL_OVERRIDE;
     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_ INCLUDED_SVTOOLS_ROADMAPWIZARD_HXX
     245             : 
     246             : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Generated by: LCOV version 1.10