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