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/dialog.hxx>
  26
  27 class TabPage;
  28 class Button;
  29 class PushButton;
  30 class FixedLine;
  31 struct ImplWizPageData;
  32 struct ImplWizButtonData;
  33
  34 /*************************************************************************
  35
  36 Beschreibung
  37 ============
  38
  39 class WizardDialog
  40
  41 Diese Klasse dient als Basis fuer einen WizardDialog. Als
  42 Basisfunktionalitaet wird das Anordnen der Controls angeboten und
  43 Hilfesmethoden fuer das Umschalten von TabPages. Der Dialog
  44 ordnet bei einer Groessenanderung die Controls auch wieder
  45 entsprechend an.
  46
  47 --------------------------------------------------------------------------
  48
  49 Mit SetPageSizePixel() kann als Groesse die Groesse der groessten
  50 TabPage vorgegeben werden. Wenn der Dialog angezeigt wird, wird
  51 zu dem Zeitpunkt wenn noch keine Groesse gesetzt wurde, dafuer
  52 die entsprechende Dialoggroesse berechnet und gesetzt. Wenn mit
  53 SetPageSizePixel() keine Groesse gesetzt wurde, wird als Groesse
  54 die maximale Groesse der zu diesem Zeitpunkt zugewiesenen TabPages
  55 berechnet und genommen.
  56
  57 ShowPrevPage()/ShowNextPage() zeigt die vorherige/naechste TabPage
  58 an. Dazu wird zuerst der Deactivate-Handler vom Dialog gerufen und
  59 wenn dieser sal_True zurueckgegeben hat, wird der Acivate-Handler
  60 vom Dialog gerufen und die entsprechende TabPage angezeigt.
  61 Finnsh() kann gerufen werden, wenn der Finnish-Button betaetigt
  62 wird. Dort wird dann auch noch der Deactivate-Page-Handler vom
  63 Dialog und der aktuellen TabPage gerufen und dann der Dialog
  64 beendet (Close() oder EndDialog()).
  65
  66 Mit AddPage()/RemovePage()/SetPage() koennen die TabPages dem Wizard
  67 bekannt gemacht werden. Es wird immer die TabPage des aktuellen Levels
  68 angezeigt, wenn fuer den aktuellen Level keine TabPage zugewiesen
  69 ist, wird die TabPages des hoechsten Levels angezeigt. Somit kann auch
  70 immer die aktuelle TabPage ausgetauscht werden, wobei zu
  71 beruecksichtigen ist, das im Activate-Handler die aktuelle TabPage
  72 nicht zerstoert werden darf.
  73
  74 Mit SetPrevButton()/SetNextButton() werden der Prev-Button und der
  75 Next-Button dem Dialog bekannt gemacht. In dem Fall loest der
  76 Dialog bei Ctr+Tab, Shift+Ctrl+Tab den entsprechenden Click-Handler
  77 am zugewiesenen Button aus. Die Button werden nicht vom WizardDialog
  78 disablte. Eine entsprechende Steuerung muss der Benutzer dieses
  79 Dialoges selber programieren.
  80
  81 Mit AddButton()/RemoveButton() koennen Buttons dem Wizard bekannt
  82 gemacht werden, die in der Reihenfolge der Hinzufuegung angeordnet
  83 werden. Die Buttons werden unabhengig von ihrem sichtbarkeitsstatus
  84 angeordnet, so das auch spaeter ein entsprechender Button angezeigt/
  85 gehidet werden kann. Der Offset wird in Pixeln angegeben und bezieht
  86 sich immer auf den nachfolgenden Button. Damit der Abstand zwischen
  87 den Buttons bei allen Dialogen gleich ist, gibt es das Define
  88 WIZARDDIALOG_BUTTON_STDOFFSET_X, welches als Standard-Offset genommen
  89 werden sollte.
  90
  91 Mit ShowButtonFixedLine() kann gesteuert werden, ob die zwischen den
  92 Buttons und der TabPage eine Trennlinie angezeigt werden soll.
  93
  94 Mit SetViewWindow() und SetViewAlign() kann ein Control gesetzt werden,
  95 welches als Preview-Window oder fuer die Anzeige von schoenen Bitmaps
  96 genutzt werden kann.
  97
  98 --------------------------------------------------------------------------
  99
 100 Der ActivatePage()-Handler wird gerufen, wenn eine neue TabPages
 101 angezeigt wird. In diesem Handler kann beispielsweise die neue
 102 TabPage erzeugt werden, wenn diese zu diesem Zeitpunkt noch nicht
 103 erzeugt wurde. Der Handler kann auch als Link gesetzt werden. Mit
 104 GetCurLevel() kann die aktuelle ebene abgefragt werden, wobei
 105 Level 0 die erste Seite ist.
 106
 107 Der DeactivatePage()-Handler wird gerufen, wenn eine neue TabPage
 108 angezeigt werden soll. In diesem Handler kann noch eine Fehler-
 109 ueberprufung stattfinden und das Umschalten gegebenenfalls verhindert
 110 werden, indem sal_False zurueckgegeben wird. Der Handler kann auch als
 111 Link gesetzt werden. Die Defaultimplementierung ruft den Link und
 112 gibt den Rueckgabewert des Links zurueck und wenn kein Link gesetzt
 113 ist, wird sal_True zurueckgegeben.
 114
 115 --------------------------------------------------------------------------
 116
 117 Beispiel:
 118
 119 MyWizardDlg-Ctor
 120 ----------------
 121
 122 // add buttons
 123 AddButton( &maHelpBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X );
 124 AddButton( &maCancelBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X );
 125 AddButton( &maPrevBtn );
 126 AddButton( &maNextBtn, WIZARDDIALOG_BUTTON_STDOFFSET_X );
 127 AddButton( &maFinnishBtn );
 128 SetPrevButton( &maPrevBtn );
 129 SetNextButton( &maNextBtn );
 130
 131 // SetHandler
 132 maPrevBtn.SetClickHdl( LINK( this, MyWizardDlg, ImplPrevHdl ) );
 133 maNextBtn.SetClickHdl( LINK( this, MyWizardDlg, ImplNextHdl ) );
 134
 135 // Set PreviewWindow
 136 SetViewWindow( &maPreview );
 137
 138 // Show line between Buttons and Page
 139 ShowButtonFixedLine( sal_True );
 140
 141 // Call ActivatePage, because the first page should be created an activated
 142 ActivatePage();
 143
 144
 145 MyWizardDlg-ActivatePage-Handler
 146 --------------------------------
 147
 148 void MyWizardDlg::ActivatePage()
 149 {
 150     WizardDialog::ActivatePage();
 151
 152     // Test, if Page is created already
 153     if ( !GetPage( GetCurLevel() ) )
 154     {
 155         // Create and add new page
 156         TabPage* pNewTabPage;
 157         switch ( GetCurLevel() )
 158         {
 159             case 0:
 160                 pNewTabPage = CreateIntroPage();
 161                 break;
 162             case 1:
 163                 pNewTabPage = CreateSecondPage();
 164                 break;
 165             case 2:
 166                 pNewTabPage = CreateThirdPage();
 167                 break;
 168             case 3:
 169                 pNewTabPage = CreateFinnishedPage();
 170                 break;
 171
 172         }
 173         AddPage( pNewTabPage );
 174     }
 175 }
 176
 177
 178 MyWizardDlg-Prev/Next-Handler
 179 -----------------------------
 180
 181 IMPL_LINK( MyWizardDlg, ImplPrevHdl, PushButton*, pBtn )
 182 {
 183     ShowPrevPage();
 184     if ( !GetCurLevel() )
 185         pBtn->Disable();
 186     return 0;
 187 }
 188
 189 IMPL_LINK( MyWizardDlg, ImplNextHdl, PushButton*, pBtn )
 190 {
 191     ShowNextPage();
 192     if ( GetCurLevel() < 3 )
 193         pBtn->Disable();
 194     return 0;
 195 }
 196
 197 *************************************************************************/
 198
 199 // ----------------------
 200 // - WizardDialog-Types -
 201 // ----------------------
 202
 203 #define WIZARDDIALOG_BUTTON_STDOFFSET_X         6
 204 #define WIZARDDIALOG_BUTTON_SMALLSTDOFFSET_X    3
 205
 206 // ----------------
 207 // - WizardDialog -
 208 // ----------------
 209
 210 class SVT_DLLPUBLIC WizardDialog : public ModalDialog
 211 {
 212 private:
 213     Timer               maWizardLayoutTimer;
 214     Size                maPageSize;
 215     ImplWizPageData*    mpFirstPage;
 216     ImplWizButtonData*  mpFirstBtn;
 217     FixedLine*          mpFixedLine;
 218     TabPage*            mpCurTabPage;
 219     PushButton*         mpPrevBtn;
 220     PushButton*         mpNextBtn;
 221     Window*             mpViewWindow;
 222     sal_uInt16              mnCurLevel;
 223     WindowAlign         meViewAlign;
 224     Link                maActivateHdl;
 225     Link                maDeactivateHdl;
 226     sal_Int16           mnLeftAlignCount;
 227     bool                mbEmptyViewMargin;
 228
 229     DECL_DLLPRIVATE_LINK( ImplHandleWizardLayoutTimerHdl, void* );
 230     bool hasWizardPendingLayout() const;
 231
 232 protected:
 233     long                LogicalCoordinateToPixel(int iCoordinate);
 234     /**sets the number of buttons which should be left-aligned. Normally, buttons are right-aligned.
 235
 236         only to be used during construction, before any layouting happened
 237     */
 238     void                SetLeftAlignedButtonCount( sal_Int16 _nCount );
 239     /** declares the view area to have an empty margin
 240
 241         Normally, the view area has a certain margin to the top/left/bottom/right of the
 242         dialog. By calling this method, you can reduce this margin to 0.
 243     */
 244     void                SetEmptyViewMargin();
 245
 246 private:
 247     SVT_DLLPRIVATE void             ImplInitData();
 248     SVT_DLLPRIVATE void             ImplCalcSize( Size& rSize );
 249     SVT_DLLPRIVATE void             ImplPosCtrls();
 250     SVT_DLLPRIVATE void             ImplPosTabPage();
 251     SVT_DLLPRIVATE void             ImplShowTabPage( TabPage* pPage );
 252     SVT_DLLPRIVATE TabPage*         ImplGetPage( sal_uInt16 nLevel ) const;
 253
 254 public:
 255     WizardDialog( Window* pParent, WinBits nStyle = WB_STDTABDIALOG );
 256     WizardDialog( Window* pParent, const ResId& rResId );
 257     ~WizardDialog();
 258
 259     virtual void        Resize();
 260     virtual void        StateChanged( StateChangedType nStateChange );
 261     virtual long        Notify( NotifyEvent& rNEvt );
 262
 263     virtual void        ActivatePage();
 264     virtual long        DeactivatePage();
 265
 266     virtual void        queue_resize();
 267
 268     sal_Bool            ShowPrevPage();
 269     sal_Bool            ShowNextPage();
 270     sal_Bool            ShowPage( sal_uInt16 nLevel );
 271     sal_Bool            Finnish( long nResult = 0 );
 272     sal_uInt16          GetCurLevel() const { return mnCurLevel; }
 273
 274     void                AddPage( TabPage* pPage );
 275     void                RemovePage( TabPage* pPage );
 276     void                SetPage( sal_uInt16 nLevel, TabPage* pPage );
 277     TabPage*            GetPage( sal_uInt16 nLevel ) const;
 278
 279     void                AddButton( Button* pButton, long nOffset = 0 );
 280     void                RemoveButton( Button* pButton );
 281
 282     void                SetPrevButton( PushButton* pButton ) { mpPrevBtn = pButton; }
 283     PushButton*         GetPrevButton() const { return mpPrevBtn; }
 284     void                SetNextButton( PushButton* pButton ) { mpNextBtn = pButton; }
 285     PushButton*         GetNextButton() const { return mpNextBtn; }
 286
 287     void                ShowButtonFixedLine( sal_Bool bVisible );
 288
 289     void                SetViewWindow( Window* pWindow ) { mpViewWindow = pWindow; }
 290     Window*             GetViewWindow() const { return mpViewWindow; }
 291     void                SetViewAlign( WindowAlign eAlign ) { meViewAlign = eAlign; }
 292     WindowAlign         GetViewAlign() const { return meViewAlign; }
 293
 294     void                SetPageSizePixel( const Size& rSize ) { maPageSize = rSize; }
 295     const Size&         GetPageSizePixel() const { return maPageSize; }
 296
 297     void                SetActivatePageHdl( const Link& rLink ) { maActivateHdl = rLink; }
 298     const Link&         GetActivatePageHdl() const { return maActivateHdl; }
 299     void                SetDeactivatePageHdl( const Link& rLink ) { maDeactivateHdl = rLink; }
 300     const Link&         GetDeactivatePageHdl() const { return maDeactivateHdl; }
 301 };
 302
 303 #endif // INCLUDED_SVTOOLS_WIZDLG_HXX
 304
 305 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */