wizardmachine.hxx

Go to the documentation of this file.

/* -*- 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_VCL_WIZARDMACHINE_HXX
#define INCLUDED_VCL_WIZARDMACHINE_HXX
 
#include <memory>
#include <vcl/dllapi.h>
#include <vcl/builderpage.hxx>
 
namespace weld {
    class Builder;
    class Container;
}
 
struct WizPageData;
struct ImplWizButtonData;
 
// wizard states
#define WZS_INVALID_STATE (::vcl::WizardTypes::WizardState(-1))
 
namespace vcl
{
    //= WizardTypes
    namespace WizardTypes
    {
        typedef sal_Int16  WizardState;
        enum CommitPageReason
        {
            eTravelForward,         // traveling forward (maybe with skipping pages)
            eTravelBackward,        // traveling backward (maybe with skipping pages)
            eFinish,                // the wizard is about to be finished
            eValidate               // the data should be validated only, no traveling will happen
        };
    };
 
    class SAL_NO_VTABLE SAL_LOPLUGIN_ANNOTATE("crosscast") IWizardPageController
    {
    public:
 
        // This methods  behave somewhat different than ActivatePage/DeactivatePage
        // The latter are handled by the base class itself whenever changing the pages is in the offing,
        // i.e., when it's already decided which page is the next.
        // We may have situations where the next page depends on the state of the current, which needs
        // to be committed for this.
        // So initializePage and commitPage are designated to initializing/committing data on the page.
        virtual void        initializePage() = 0;
        virtual bool        commitPage( WizardTypes::CommitPageReason _eReason ) = 0;
 
        virtual bool        canAdvance() const = 0;
 
    protected:
        ~IWizardPageController() {}
    };
 
    //= OWizardPage
    class VCL_DLLPUBLIC OWizardPage : public BuilderPage, public IWizardPageController
    {
    public:
        OWizardPage(weld::Container* pPage, weld::DialogController* pController, const OUString& rUIXMLDescription, const OUString& rID);
        virtual ~OWizardPage() override;
 
        // IWizardPageController overridables
        virtual void        initializePage() override;
        virtual bool        commitPage( WizardTypes::CommitPageReason _eReason ) override;
        virtual bool        canAdvance() const override;
 
    protected:
        // BuilderPage overridables
        virtual void        Activate() override;
 
        void                updateDialogTravelUI();
    };
 
    //= OWizardMachine
    struct WizardMachineImplData;
    class VCL_DLLPUBLIC WizardMachine : public weld::AssistantController
    {
    protected:
        BuilderPage* m_pCurTabPage;
    private:
        WizardTypes::WizardState m_nCurState;
        WizPageData* m_pFirstPage;
 
    protected:
        std::unique_ptr<weld::Button> m_xFinish;
        std::unique_ptr<weld::Button> m_xCancel;
        std::unique_ptr<weld::Button> m_xNextPage;
        std::unique_ptr<weld::Button> m_xPrevPage;
        std::unique_ptr<weld::Button> m_xHelp;
 
    private:
        // hold members in this structure to allow keeping compatible when members are added
        std::unique_ptr<WizardMachineImplData>  m_pImpl;
 
    public:
        WizardMachine(weld::Window* _pParent, WizardButtonFlags _nButtonFlags );
        virtual ~WizardMachine() override;
 
        bool Finish(short nResult = RET_CANCEL);
        bool ShowPage(WizardTypes::WizardState nState);
 
        bool ShowNextPage();
        bool ShowPrevPage();
 
        void                AddPage( std::unique_ptr<BuilderPage> xPage );
        void                RemovePage( const BuilderPage* pPage );
        void                SetPage( WizardTypes::WizardState nLevel, std::unique_ptr<BuilderPage> xPage );
        BuilderPage*        GetPage( WizardTypes::WizardState eState ) const;
 
        void                enableButtons(WizardButtonFlags _nWizardButtonFlags, bool _bEnable);
        void                defaultButton(WizardButtonFlags _nWizardButtonFlags);
        void                defaultButton(weld::Button* _pNewDefButton);
 
        void                setTitleBase(const OUString& _rTitleBase);
 
        virtual bool        canAdvance() const;
 
        virtual void        updateTravelUI();
 
    protected:
        virtual void        ActivatePage();
        virtual bool        DeactivatePage();
 
        // our own overridables
 
        virtual std::unique_ptr<BuilderPage> createPage(WizardTypes::WizardState _nState) = 0;
 
        virtual void        enterState(WizardTypes::WizardState _nState);
 
        virtual bool        prepareLeaveCurrentState( WizardTypes::CommitPageReason eReason );
 
        virtual bool        leaveState(WizardTypes::WizardState nState);
 
        virtual WizardTypes::WizardState determineNextState(WizardTypes::WizardState nCurrentState) const;
 
        virtual bool        onFinish();
 
        bool                travelNext();
 
        bool                travelPrevious();
 
        void                enableAutomaticNextButtonState();
        bool                isAutomaticNextButtonStateEnabled() const;
 
        void                removePageFromHistory(WizardTypes::WizardState nToRemove);
 
        void                    skip();
 
        bool                    skipUntil(WizardTypes::WizardState nTargetState);
 
        bool                    skipBackwardUntil(WizardTypes::WizardState nTargetState);
 
        WizardTypes::WizardState getCurrentState() const { return m_nCurState; }
 
        virtual IWizardPageController* getPageController(BuilderPage* pCurrentPage) const;
 
        void                    getStateHistory(std::vector<WizardTypes::WizardState>& out_rHistory);
 
        virtual OUString         getPageIdentForState(WizardTypes::WizardState nState) const;
        virtual WizardTypes::WizardState getStateFromPageIdent(const OUString& rIdent) const;
 
    public:
        class AccessGuard
        {
            friend class WizardTravelSuspension;
        private:
            AccessGuard() { }
        };
 
        void                   suspendTraveling( AccessGuard );
        void                   resumeTraveling( AccessGuard );
        bool                   isTravelingSuspended() const;
 
    protected:
        BuilderPage* GetOrCreatePage(const WizardTypes::WizardState i_nState);
 
    private:
        DECL_DLLPRIVATE_LINK(OnNextPage, weld::Button&, void);
        DECL_DLLPRIVATE_LINK(OnPrevPage, weld::Button&, void);
        DECL_DLLPRIVATE_LINK(OnFinish, weld::Button&, void);
        DECL_DLLPRIVATE_LINK(OnCancel, weld::Button&, void);
 
        VCL_DLLPRIVATE void     implUpdateTitle();
        VCL_DLLPRIVATE void     implConstruct( const WizardButtonFlags _nButtonFlags );
    };
 
 
    class WizardTravelSuspension
    {
    public:
        WizardTravelSuspension(WizardMachine& rWizard)
            : m_pWizard(&rWizard)
        {
            m_pWizard->suspendTraveling(WizardMachine::AccessGuard());
        }
 
        ~WizardTravelSuspension()
        {
            m_pWizard->resumeTraveling(WizardMachine::AccessGuard());
        }
 
    private:
        WizardMachine* m_pWizard;
    };
}   // namespace vcl
 
#define WIZARDDIALOG_BUTTON_STDOFFSET_X         6
#define WIZARDDIALOG_BUTTON_SMALLSTDOFFSET_X    3
 
#endif // INCLUDED_VCL_WIZARDMACHINE_HXX
 
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */