include/svtools/wizdlg.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_SVTOOLS_WIZDLG_HXX
  21 #define INCLUDED_SVTOOLS_WIZDLG_HXX
  22
  23 #include <svtools/svtdllapi.h>
  24
  25 #include <vcl/button.hxx>
  26 #include <vcl/dialog.hxx>
  27 #include <vcl/idle.hxx>
  28
  29 class TabPage;
  30 struct ImplWizPageData;
  31 struct ImplWizButtonData;
  32
  33 /*
  34
  35 Description
  36 ==========
  37
  38 class WizardDialog
  39
  40 This class is the base for WizardDialog. The basic functionality is to
  41 order the Controls. Besides it's a helper method for switching the TabPages.
  42 The dialog orders the Controls when their size changed.
  43
  44 --------------------------------------------------------------------------
  45
  46 SetPageSizePixel() sets the biggest TabPage size. When the dialog
  47 should be displayed, first the dialog size is calculated and set.
  48 If there is no size set with SetPageSizePixel(), max size of the
  49 current TabPage is set as default.
  50
  51 ShowPrevPage()/ShowNextPage() shows the previous/next TabPage.
  52 First the Deactivate-Handler is called by dialog and if the return
  53 value is sal_True the Active-Handler is called by dialog and the
  54 corresponding TabPage is showed. Finnish() can only be called
  55 if the Finnish-Button is activated. Then the Deactivate-Page-Handler
  56 is called by dialog and by the current TabPage. Now the dialog ends
  57 (Close() or EndDialog()).
  58
  59 AddPage()/RemovePage()/SetPage() TabPages are made known to the Wizard.
  60 The TabPage of the current Level is always shown and if no TabPage is
  61 available at that level then the TabPage of the highest level is used.
  62 Because of that the current TabPage always can be swapped under the
  63 condition that in the Activate-Handler the current TabPage cannot be
  64 destroyed.
  65
  66 SetPrevButton()/SetNextButton() add the Prev-Button and the
  67 Next-Button to the dialog. In that case the dialog emits the Click-Handler
  68 of the assigned Button when Ctrl+Tab, Shift-Ctrl-Tab are pressed. The Buttons
  69 are not disabled by the WizardDialog and such an action must be
  70 programmed by the user of this Dialog.
  71
  72 AddButton()/RemoveButton() can add Buttons to the Wizard and they're shown
  73 the order of adding them. The Buttons are ordered independent of their
  74 visibility state, so that also later a Button can be shown/hidden.
  75 The Offset is in Pixels and always refers to the following Button. So that
  76 the distance between the Buttons is the same for all dialogs, there is the
  77 macro WIZARDDIALOG_BUTTON_STDOFFSET_X to be used as the default offset.
  78
  79 With SetViewWindow() and SetViewAlign() a Control can be set, which can
  80 be used as Preview-Window or for displaying of pretty Bitmaps.
  81
  82 --------------------------------------------------------------------------
  83
  84 The ActivatePage()-Handler is called, if a new TabPage is shown. In that
  85 handler a new TabPage can be created if it was not created before; the
  86 handler can be set as a Link. GetCurLevel() returns the current level and
  87 Level 0 is the first page.
  88
  89 The DeactivatePage()-Handler is called if a new TabPage should be shown.
  90 In that handler has a optional error check and returns sal_False, if the
  91 switch should not be done. Also the Handler can be set as a Link. The
  92 default implementation calls the Link and returns the Links value or returns
  93 sal_True if no Link is set.
  94
  95 --------------------------------------------------------------------------
  96
  97 Example:
  98
  99 MyWizardDlg-Ctor
 100 ----------------
 101
 102 // add buttons
 103 AddButton( &maHelpBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X );
 104 AddButton( &maCancelBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X );
 105 AddButton( &maPrevBtn );
 106 AddButton( &maNextBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X );
 107 AddButton( &maFinnishBtn );
 108 SetPrevButton( &maPrevBtn );
 109 SetNextButton( &maNextBtn );
 110
 111 // SetHandler
 112 maPrevBtn.SetClickHdl( LINK( this, MyWizardDlg, ImplPrevHdl ) );
 113 maNextBtn.SetClickHdl( LINK( this, MyWizardDlg, ImplNextHdl ) );
 114
 115 // Set PreviewWindow
 116 SetViewWindow( &maPreview );
 117
 118 // Call ActivatePage, because the first page should be created an activated
 119 ActivatePage();
 120
 121
 122 MyWizardDlg-ActivatePage-Handler
 123 --------------------------------
 124
 125 void MyWizardDlg::ActivatePage()
 126 {
 127     WizardDialog::ActivatePage();
 128
 129     // Test, if Page is created already
 130     if ( !GetPage( GetCurLevel() ) )
 131     {
 132         // Create and add new page
 133         TabPage* pNewTabPage;
 134         switch ( GetCurLevel() )
 135         {
 136             case 0:
 137                 pNewTabPage = CreateIntroPage();
 138                 break;
 139             case 1:
 140                 pNewTabPage = CreateSecondPage();
 141                 break;
 142             case 2:
 143                 pNewTabPage = CreateThirdPage();
 144                 break;
 145             case 3:
 146                 pNewTabPage = CreateFinnishedPage();
 147                 break;
 148
 149         }
 150         AddPage( pNewTabPage );
 151     }
 152 }
 153
 154
 155 MyWizardDlg-Prev/Next-Handler
 156 -----------------------------
 157
 158 IMPL_LINK( MyWizardDlg, ImplPrevHdl, PushButton*, pBtn, void )
 159 {
 160     ShowPrevPage();
 161     if ( !GetCurLevel() )
 162         pBtn->Disable();
 163 }
 164
 165 IMPL_LINK( MyWizardDlg, ImplNextHdl, PushButton*, pBtn, void )
 166 {
 167     ShowNextPage();
 168     if ( GetCurLevel() < 3 )
 169         pBtn->Disable();
 170 }
 171
 172 */
 173
 174 #define WIZARDDIALOG_BUTTON_STDOFFSET_X         6
 175 #define WIZARDDIALOG_BUTTON_SMALLSTDOFFSET_X    3
 176
 177
 178 class SVT_DLLPUBLIC WizardDialog : public ModalDialog
 179 {
 180 private:
 181     Idle                    maWizardLayoutIdle;
 182     Size                    maPageSize;
 183     ImplWizPageData*        mpFirstPage;
 184     ImplWizButtonData*      mpFirstBtn;
 185     VclPtr<TabPage>         mpCurTabPage;
 186     VclPtr<PushButton>      mpPrevBtn;
 187     VclPtr<PushButton>      mpNextBtn;
 188     VclPtr<vcl::Window>     mpViewWindow;
 189     sal_uInt16              mnCurLevel;
 190     WindowAlign             meViewAlign;
 191     Link<WizardDialog*,void>  maActivateHdl;
 192     sal_Int16               mnLeftAlignCount;
 193     bool                    mbEmptyViewMargin;
 194
 195     DECL_DLLPRIVATE_LINK( ImplHandleWizardLayoutTimerHdl, Timer*, void );
 196
 197 protected:
 198     long                LogicalCoordinateToPixel(int iCoordinate);
 199     /**sets the number of buttons which should be left-aligned. Normally, buttons are right-aligned.
 200
 201         only to be used during construction, before any layouting happened
 202     */
 203     void                SetLeftAlignedButtonCount( sal_Int16 _nCount );
 204     /** declares the view area to have an empty margin
 205
 206         Normally, the view area has a certain margin to the top/left/bottom/right of the
 207         dialog. By calling this method, you can reduce this margin to 0.
 208     */
 209     void                SetEmptyViewMargin();
 210
 211 private:
 212     SVT_DLLPRIVATE void             ImplInitData();
 213     SVT_DLLPRIVATE void             ImplCalcSize( Size& rSize );
 214     SVT_DLLPRIVATE void             ImplPosCtrls();
 215     SVT_DLLPRIVATE void             ImplPosTabPage();
 216     SVT_DLLPRIVATE void             ImplShowTabPage( TabPage* pPage );
 217     SVT_DLLPRIVATE TabPage*         ImplGetPage( sal_uInt16 nLevel ) const;
 218
 219 public:
 220     WizardDialog( vcl::Window* pParent, const OUString& rID, const OUString& rUIXMLDescription );
 221     virtual ~WizardDialog() override;
 222     virtual void dispose() override;
 223
 224     virtual void        Resize() override;
 225     virtual void        StateChanged( StateChangedType nStateChange ) override;
 226     virtual bool        EventNotify( NotifyEvent& rNEvt ) override;
 227
 228     virtual void        ActivatePage();
 229     virtual bool        DeactivatePage();
 230
 231     virtual void        queue_resize(StateChangedType eReason = StateChangedType::Layout) override;
 232
 233     bool                ShowPrevPage();
 234     bool                ShowNextPage();
 235     bool                ShowPage( sal_uInt16 nLevel );
 236     bool                Finish( long nResult = 0 );
 237     sal_uInt16          GetCurLevel() const { return mnCurLevel; }
 238
 239     void                AddPage( TabPage* pPage );
 240     void                RemovePage( TabPage* pPage );
 241     void                SetPage( sal_uInt16 nLevel, TabPage* pPage );
 242     TabPage*            GetPage( sal_uInt16 nLevel ) const;
 243
 244     void                AddButton( Button* pButton, long nOffset = 0 );
 245     void                RemoveButton( Button* pButton );
 246
 247     void                SetPrevButton( PushButton* pButton ) { mpPrevBtn = pButton; }
 248     void                SetNextButton( PushButton* pButton ) { mpNextBtn = pButton; }
 249
 250     void                SetViewWindow( vcl::Window* pWindow ) { mpViewWindow = pWindow; }
 251     void                SetViewAlign( WindowAlign eAlign ) { meViewAlign = eAlign; }
 252
 253     void                SetPageSizePixel( const Size& rSize ) { maPageSize = rSize; }
 254     const Size&         GetPageSizePixel() const { return maPageSize; }
 255
 256     void                SetActivatePageHdl( const Link<WizardDialog*,void>& rLink ) { maActivateHdl = rLink; }
 257 };
 258
 259 #endif // INCLUDED_SVTOOLS_WIZDLG_HXX
 260
 261 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */