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 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 OString& 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);

    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: */