/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* * This file is part of the LibreOffice project. * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. * * This file incorporates work covered by the following license notice: * * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed * with this work for additional information regarding copyright * ownership. The ASF licenses this file to you under the Apache * License, Version 2.0 (the "License"); you may not use this file * except in compliance with the License. You may obtain a copy of * the License at http://www.apache.org/licenses/LICENSE-2.0 . */ #ifndef INCLUDED_SVTOOLS_ROADMAPWIZARD_HXX #define INCLUDED_SVTOOLS_ROADMAPWIZARD_HXX #include #include namespace svt { struct RoadmapWizardImpl; class RoadmapWizard; struct RoadmapWizardTypes { public: typedef sal_Int16 PathId; typedef ::std::vector< WizardTypes::WizardState > WizardPath; typedef VclPtr (* RoadmapPageFactory)( RoadmapWizard& ); }; //= RoadmapWizard /** is - no, not a wizard for a roadmap, but the base class for wizards supporting a roadmap. The basic new concept introduced is a path:
A path is a sequence of states, which are to be executed in a linear order. Elements in the path can be skipped, depending on choices the user makes. In the most simple wizards, you will have only one path consisting of n elements, which are to be visited successively. In a slightly more complex wizard, you will have one linear path, were certain steps might be skipped due to user input. For instance, the user may decide to not specify certain aspects of the to-be-created object (e.g. by unchecking a check box), and the wizard then will simply disable the step which corresponds to this step. In a yet more advanced wizards, you will have several paths of length n1 and n2, which share at least the first k states (where k is at least 1), and an arbitrary number of other states. */ class SVT_DLLPUBLIC RoadmapWizard : public OWizardMachine, public RoadmapWizardTypes { private: std::unique_ptr m_pImpl; public: RoadmapWizard( vcl::Window* _pParent, const WinBits i_nStyle, WizardButtonFlags _nButtonFlags = WizardButtonFlags::NEXT | WizardButtonFlags::PREVIOUS | WizardButtonFlags::FINISH | WizardButtonFlags::CANCEL | WizardButtonFlags::HELP ); RoadmapWizard( vcl::Window* _pParent, WizardButtonFlags _nButtonFlags = WizardButtonFlags::NEXT | WizardButtonFlags::PREVIOUS | WizardButtonFlags::FINISH | WizardButtonFlags::CANCEL | WizardButtonFlags::HELP ); virtual ~RoadmapWizard( ); virtual void dispose() override; void SetRoadmapHelpId( const OString& _rId ); void SetRoadmapInteractive( bool _bInteractive ); // returns whether a given state is enabled bool isStateEnabled( WizardState _nState ) const; // WizardDialog overridables virtual bool canAdvance() const override; virtual void updateTravelUI() override; protected: /** declares a valid path in the wizard The very first path which is declared is automatically activated. Note that all paths which are declared must have the very first state in common. Also note that due to a restriction of the very base class (WizardDialog), this common first state must be 0. You cannot declare new paths once the wizard started, so it's recommended that you do all declarations within your derivee's constructor. @see activatePath @param _nId the unique id you wish to give this path. This id can later on be used to refer to the path which you just declared */ void declarePath( PathId _nPathId, const WizardPath& _lWizardStates); /** provides basic information about a state The given display name is used in the default implementation of getStateDisplayName, and the given factory is used in the default implementation of createPage. */ void describeState( WizardState _nState, const OUString& _rStateDisplayName, RoadmapPageFactory _pPageFactory ); /** activates a path which has previously been declared with declarePath You can only activate paths which share the first k states with the path which is previously active (if any), where k is the index of the current state within the current path. Say you have paths, (0,1,2,5) and (0,1,4,5). This means that after step 1, you either continue with state 2 or state 4, and after this, you finish in state 5.
Now if the first path is active, and your current state is 1, then you can easily switch to the second path, since both paths start with (0,1).
However, if your current state is 2, then you can not switch to the second path anymore. @param _nPathId the id of the path. The path must have been declared (under this id) with declarePath before it can be activated. @param _bDecideForIt If , the path will be completely activated, even if it is a conflicting path (i.e. there is another path which shares the first k states with the to-be-activated path.)
If , then the new path is checked for conflicts with other paths. If such conflicts exists, the path is not completely activated, but only up to the point where it does not conflict.
With the paths in the example above, if you activate the second path (when both are already declared), then only steps 0 and 1 are activated, since they are common to both paths. */ void activatePath( PathId _nPathId, bool _bDecideForIt = false ); /** determine the next state to travel from the given one This method (which is declared in OWizardMachine and overwritten here) ensures that traveling happens along the active path. @see activatePath */ virtual WizardState determineNextState( WizardState _nCurrentState ) const override; /** en- or disables a state In the wizard's roadmap, states to travel to can be freely chosen. To prevent users from selecting a state which is currently not available, you can declare this state as being disabled. A situation where you need this may be when you have a checkbox which, when checked by the user, enables a page with additional settings. As long as this checkbox is not checked, the respective state would be disabled. Note that in theory, you can declare multiple paths, instead of disabling states. For instance, if you have a path where one state can be potentially disabled, then you could declare a second path, which does not contain this state. However, the disadvantage is that then, not the complete path would be visible in the roadmap, but only all steps up to the point where the both paths diverge.
Another disadvantage is that the number of needed paths grows exponentially with the number of states which can be potentially disabled. @see declarePath */ void enableState( WizardState _nState, bool _bEnable = true ); /** returns true if and only if the given state is known in at least one declared path */ bool knowsState( WizardState _nState ) const; // OWizardMachine overriables virtual void enterState( WizardState _nState ) override; /** returns a human readable name for a given state There is a default implementation for this method, which returns the display name as given in a call to describeState. If there is no description for the given state, this is worth an assertion in a non-product build, and then an empty string is returned. */ virtual OUString getStateDisplayName( WizardState _nState ) const; /** creates a page for a given state This member is inherited from OWizardMachine, and default-implemented in this class for all states which have been described using describeState. */ virtual VclPtr createPage( WizardState _nState ) override; /** asks for a new label of the wizard page */ void updateRoadmapItemLabel( WizardState _nState ); private: DECL_DLLPRIVATE_LINK_TYPED( OnRoadmapItemSelected, LinkParamNone*, void ); /** updates the roadmap control to show the given path, as far as possible (modulo conflicts with other paths) */ SVT_DLLPRIVATE void implUpdateRoadmap( ); private: SVT_DLLPRIVATE void impl_construct(); }; } // namespace svt #endif // OOO_ INCLUDED_SVTOOLS_ROADMAPWIZARD_HXX /* vim:set shiftwidth=4 softtabstop=4 expandtab: */