 | PixelLight 0.9.10-R1 Copyright (C) 2002-2011 by The PixelLight Team Last modified Fri Dec 23 2011 15:50:53 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: FrontendImpl.h * 00003 * 00004 * Copyright (C) 2002-2011 The PixelLight Team (http://www.pixellight.org/) 00005 * 00006 * This file is part of PixelLight. 00007 * 00008 * PixelLight is free software: you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License as published by 00010 * the Free Software Foundation, either version 3 of the License, or 00011 * (at your option) any later version. 00012 * 00013 * PixelLight is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00016 * GNU Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public License 00019 * along with PixelLight. If not, see <http://www.gnu.org/licenses/>. 00020 \*********************************************************/ 00021 00022 00023 #ifndef __PLCORE_FRONTEND_IMPL_H__ 00024 #define __PLCORE_FRONTEND_IMPL_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include "PLCore/Base/Object.h" 00032 #include "PLCore/Frontend/AbstractFrontend.h" 00033 #include "PLCore/Core/AbstractLifecycle.h" 00034 00035 00036 //[-------------------------------------------------------] 00037 //[ Namespace ] 00038 //[-------------------------------------------------------] 00039 namespace PLCore { 00040 00041 00042 //[-------------------------------------------------------] 00043 //[ Forward declarations ] 00044 //[-------------------------------------------------------] 00045 class Frontend; 00046 class FrontendContext; 00047 00048 00049 //[-------------------------------------------------------] 00050 //[ Classes ] 00051 //[-------------------------------------------------------] 00052 /** 00053 * @brief 00054 * Abstract frontend implementation base class 00055 * 00056 * @remarks 00057 * This base class provides the backend interface for concrete implementations. 00058 * Just think of the frontend implementation as a puppet master, while the puppet 00059 * is the "Frontend"-class. The frontend implementation is e.g. a simple native OS 00060 * window or a browser such as MS Internet Explorer or Mozilla Firefox. 00061 */ 00062 class FrontendImpl : public Object, protected AbstractLifecycle, protected AbstractFrontend { 00063 00064 00065 //[-------------------------------------------------------] 00066 //[ Friends ] 00067 //[-------------------------------------------------------] 00068 friend class Frontend; 00069 00070 00071 //[-------------------------------------------------------] 00072 //[ RTTI interface ] 00073 //[-------------------------------------------------------] 00074 pl_class(PLCORE_RTTI_EXPORT, FrontendImpl, "PLCore", PLCore::Object, "Abstract frontend implementation base class") 00075 pl_class_end 00076 00077 00078 //[-------------------------------------------------------] 00079 //[ Public functions ] 00080 //[-------------------------------------------------------] 00081 public: 00082 /** 00083 * @brief 00084 * Constructor 00085 */ 00086 PLCORE_API FrontendImpl(); 00087 00088 /** 00089 * @brief 00090 * Destructor 00091 */ 00092 PLCORE_API virtual ~FrontendImpl(); 00093 00094 /** 00095 * @brief 00096 * Returns the frontend instance 00097 * 00098 * @return 00099 * The frontend instance, can be a null pointer 00100 */ 00101 inline Frontend *GetFrontend() const; 00102 00103 00104 //[-------------------------------------------------------] 00105 //[ Protected virtual AbstractLifecycle functions ] 00106 //[-------------------------------------------------------] 00107 protected: 00108 PLCORE_API virtual void OnCreate() override; // Automatically called from within "Frontend::Run()" 00109 PLCORE_API virtual void OnRestart() override; // Don't forget to call this within derived frontend implementations 00110 PLCORE_API virtual bool OnStart() override; // Don't forget to call this within derived frontend implementations 00111 PLCORE_API virtual void OnResume() override; // Don't forget to call this within derived frontend implementations 00112 PLCORE_API virtual void OnPause() override; // Don't forget to call this within derived frontend implementations 00113 PLCORE_API virtual void OnStop() override; // Don't forget to call this within derived frontend implementations 00114 PLCORE_API virtual void OnDestroy() override; // Automatically called from within "Frontend::Run()" 00115 00116 00117 //[-------------------------------------------------------] 00118 //[ Protected virtual AbstractFrontend functions ] 00119 //[-------------------------------------------------------] 00120 protected: 00121 PLCORE_API virtual void OnSize() override; 00122 PLCORE_API virtual void OnFullscreenMode() override; 00123 PLCORE_API virtual void OnDraw() override; 00124 PLCORE_API virtual void OnUpdate() override; 00125 PLCORE_API virtual void OnDrop(const Container<String> &lstFiles) override; 00126 00127 00128 //[-------------------------------------------------------] 00129 //[ Protected virtual FrontendImpl functions ] 00130 //[-------------------------------------------------------] 00131 protected: 00132 /** 00133 * @brief 00134 * Called when the frontend is run 00135 * 00136 * @param[in] sExecutableFilename 00137 * Absolute application executable filename 00138 * @param[in] lstArguments 00139 * List of arguments to the program 00140 * 00141 * @remarks 00142 * This frontend method is called just before the frontend calls it's run-method in order to 00143 * enter it's main-loop. This means that this method is called between "AbstractLifecycle::OnCreate()" 00144 * and "AbstractLifecycle::OnStart()". Use this method for instance to pre-process command line arguments. 00145 * 00146 * @note 00147 * - Automatically called from within "Frontend::Run()" 00148 */ 00149 PLCORE_API virtual void OnRun(const String &sExecutableFilename, const Array<String> &lstArguments); 00150 00151 /** 00152 * @brief 00153 * Called when the frontend should run 00154 * 00155 * @param[in] sExecutableFilename 00156 * Absolute application executable filename 00157 * @param[in] lstArguments 00158 * List of arguments to the program 00159 * 00160 * @return 00161 * Exit code (usually 0 means no error), usually <0 when there was an error 00162 * (e.g. an embedded frontend implementation is run and controlled by another application and can't be run by using this method) 00163 * 00164 * @note 00165 * - The default implementation does nothing at all 00166 * - Automatically called from within "Frontend::Run()" 00167 */ 00168 PLCORE_API virtual int Run(const String &sExecutableFilename, const Array<String> &lstArguments); 00169 00170 /** 00171 * @brief 00172 * Get native window handle 00173 * 00174 * @return 00175 * Native window handle for the frontend window, can be a null pointer 00176 */ 00177 virtual handle GetNativeWindowHandle() const = 0; 00178 00179 /** 00180 * @brief 00181 * Redraw frontend 00182 * 00183 * @remarks 00184 * There are situations were an application may do some heavy work without letting 00185 * the frontend a chance to redraw. In such situations, it may be wise 00186 * to call this method from time to time to give the frontend a chance to do redraw 00187 * itself. 00188 * 00189 * @note 00190 * - Whenever possible, don't use this method, do heavy work within e.g. threads 00191 * - Depending on the frontend implementation, the redraw may not be immediate 00192 * - Doesn't include "Ping()" 00193 */ 00194 virtual void Redraw() = 0; 00195 00196 /** 00197 * @brief 00198 * Give the frontend a chance to process OS messages 00199 * 00200 * @remarks 00201 * There are situations were an application may do some heavy work without letting 00202 * the frontend a chance to process OS messages. In such situations, it may be wise 00203 * to call this method from time to time to give the frontend a chance to do some 00204 * message processing. 00205 * 00206 * @note 00207 * - Whenever possible, don't use this method, do heavy work within e.g. threads 00208 */ 00209 virtual void Ping() = 0; 00210 00211 /** 00212 * @brief 00213 * Get frontend title 00214 * 00215 * @return 00216 * Frontend title 00217 * 00218 * @remarks 00219 * When the frontend has a window, this title can be seen within the window 00220 * title bar. Please note that there's no guarantee that there's a window 00221 * title bar or even a window. By default, the title is set to the frontend 00222 * context name ("GetContext().GetName()") which is usually sufficient. So, 00223 * unless you have a good reason to explicitly set an individual frontend 00224 * title, just use the default setting and don't touch the frontend. 00225 */ 00226 virtual String GetTitle() const = 0; 00227 00228 /** 00229 * @brief 00230 * Set frontend title 00231 * 00232 * @param[in] sTitle 00233 * Frontend title 00234 * 00235 * @see 00236 * - GetTitle() 00237 */ 00238 virtual void SetTitle(const String &sTitle) = 0; 00239 00240 //[-------------------------------------------------------] 00241 //[ Position and size ] 00242 //[-------------------------------------------------------] 00243 /** 00244 * @brief 00245 * Get the x position of the frontend (in screen coordinates) 00246 * 00247 * @return 00248 * X position of the frontend 00249 */ 00250 virtual int GetX() const = 0; 00251 00252 /** 00253 * @brief 00254 * Get the y position of the frontend (in screen coordinates) 00255 * 00256 * @return 00257 * Y position of the frontend 00258 */ 00259 virtual int GetY() const = 0; 00260 00261 /** 00262 * @brief 00263 * Get frontend width 00264 * 00265 * @return 00266 * Width of the frontend 00267 */ 00268 virtual uint32 GetWidth() const = 0; 00269 00270 /** 00271 * @brief 00272 * Get frontend height 00273 * 00274 * @return 00275 * Height of the frontend 00276 */ 00277 virtual uint32 GetHeight() const = 0; 00278 00279 /** 00280 * @brief 00281 * Set frontend position and size 00282 * 00283 * @param[in] nX 00284 * X position of the frontend (in screen coordinates) 00285 * @param[in] nY 00286 * Y position of the frontend (in screen coordinates) 00287 * @param[in] nWidth 00288 * Width of the frontend 00289 * @param[in] nHeight 00290 * Height of the frontend 00291 * 00292 * @remarks 00293 * The primary argument to allow the user to request a frontend position and size change is, 00294 * that it should be possible to restore the frontend position and size of a previous session 00295 * (may be important for the usability). Do not misuse this method to frequently manipulate 00296 * the frontend appearance. Please note that, as for all other frontend methods, this is only 00297 * considered to be a request. A frontend implementation may deny the request in general or 00298 * just improper settings (e.g. a too small size, position outside the visible screen etc.). 00299 */ 00300 virtual void SetPositionSize(int nX, int nY, uint32 nWidth, uint32 nHeight) = 0; 00301 00302 //[-------------------------------------------------------] 00303 //[ Fullscreen ] 00304 //[-------------------------------------------------------] 00305 /** 00306 * @brief 00307 * Gets whether it's allowed to toggle the fullscreen mode using hotkeys 00308 * 00309 * @return 00310 * 'true' if it's possible to toggle the fullscreen mode using hotkeys, else 'false' 00311 */ 00312 virtual bool GetToggleFullscreenMode() const = 0; 00313 00314 /** 00315 * @brief 00316 * Sets whether it's allowed to toggle the fullscreen mode using hotkeys 00317 * 00318 * @param[in] bToggleFullscreenMode 00319 * Is it allowed to toggle the fullscreen mode using hotkeys? 00320 * 00321 * @note 00322 * - By default, it's allowed to switch widgets into fullscreen mode using Alt-Return or AltGr-Return 00323 */ 00324 virtual void SetToggleFullscreenMode(bool bToggleFullscreenMode) = 0; 00325 00326 /** 00327 * @brief 00328 * Gets whether it's allowed to use Alt-Tab if fullscreen mode is used 00329 * 00330 * @return 00331 * 'true' if it's possible to use Alt-Tab if fullscreen mode is used, else 'false' 00332 * 00333 * @note 00334 * - Widgets only 00335 */ 00336 virtual bool GetFullscreenAltTab() const = 0; 00337 00338 /** 00339 * @brief 00340 * Sets whether it's allowed to use Alt-Tab if fullscreen mode is used 00341 * 00342 * @param[in] bAllowed 00343 * Is it allowed to use Alt-Tab within fullscreen mode? 00344 * 00345 * @note 00346 * - By default, it's allowed to use Alt-Tab 00347 * 00348 * @see 00349 * - GetFullscreenAltTab() 00350 */ 00351 virtual void SetFullscreenAltTab(bool bAllowed) = 0; 00352 00353 /** 00354 * @brief 00355 * Returns whether the frontend is in fullscreen mode or not 00356 * 00357 * @return 00358 * 'true' if the frontend is in fullscreen mode, else 'false' 00359 */ 00360 virtual bool IsFullscreen() const = 0; 00361 00362 /** 00363 * @brief 00364 * Sets the frontend's fullscreen mode 00365 * 00366 * @param[in] bFullscreen 00367 * 'true' if the frontend should be in fullscreen mode, else 'false' 00368 */ 00369 virtual void SetFullscreen(bool bFullscreen) = 0; 00370 00371 /** 00372 * @brief 00373 * Something related to fullscreen mode has been changed (e.g. the display resolution) 00374 */ 00375 virtual void RefreshFullscreen() = 0; 00376 00377 //[-------------------------------------------------------] 00378 //[ Mouse ] 00379 //[-------------------------------------------------------] 00380 /** 00381 * @brief 00382 * Check if the mouse is currently over the frontend 00383 * 00384 * @return 00385 * 'true' if mouse-over, else 'false' 00386 */ 00387 virtual bool IsMouseOver() const = 0; 00388 00389 /** 00390 * @brief 00391 * Get current mouse cursor X position inside the frontend 00392 * 00393 * @return 00394 * Current mouse cursor X position inside the frontend, negative value if the mouse cursor isn't currently over the frontend 00395 */ 00396 virtual int GetMousePositionX() const = 0; 00397 00398 /** 00399 * @brief 00400 * Get current mouse cursor Y position inside the frontend 00401 * 00402 * @return 00403 * Current mouse cursor Y position inside the frontend, negative value if the mouse cursor isn't currently over the frontend 00404 */ 00405 virtual int GetMousePositionY() const = 0; 00406 00407 /** 00408 * @brief 00409 * Check if the mouse cursor is visible 00410 * 00411 * @return 00412 * 'true' if the mouse cursor is visible, else 'false' 00413 * 00414 * @note 00415 * - If the mouse cursor is visible in general, it's still possible that it's 00416 * invisible over some special widgets. 00417 * - If the mouse cursor is invisible in general, it will NEVER be visible! 00418 */ 00419 virtual bool IsMouseVisible() const = 0; 00420 00421 /** 00422 * @brief 00423 * Set mouse cursor visibility 00424 * 00425 * @param[in] bVisible 00426 * Shall the mouse cursor be visible? 00427 * 00428 * @see 00429 * - IsMouseVisible() 00430 */ 00431 virtual void SetMouseVisible(bool bVisible) = 0; 00432 00433 /** 00434 * @brief 00435 * Trap mouse inside the frontend 00436 * 00437 * @param[in] bTrap 00438 * 'true' if the mouse should be trapped inside the frontend, else 'false' 00439 */ 00440 virtual void SetTrapMouse(bool bTrap) = 0; 00441 00442 00443 //[-------------------------------------------------------] 00444 //[ Protected static functions ] 00445 //[-------------------------------------------------------] 00446 protected: 00447 /** 00448 * @brief 00449 * Creates a frontend instance 00450 * 00451 * @param[in] cFrontendContext 00452 * Frontend context to use 00453 * @param[in] cFrontendImpl 00454 * Frontend implementation instance 00455 * 00456 * @return 00457 * Frontend instance, null pointer on error 00458 */ 00459 static PLCORE_API Frontend *CreateFrontend(const FrontendContext &cFrontendContext, FrontendImpl &cFrontendImpl); 00460 00461 /** 00462 * @brief 00463 * Correct frontend position and size settings 00464 * 00465 * @param[in, out] nX 00466 * X position of the frontend (in screen coordinates) 00467 * @param[in, out] nY 00468 * Y position of the frontend (in screen coordinates) 00469 * @param[in, out] nWidth 00470 * Width of the frontend 00471 * @param[in, out] nHeight 00472 * Height of the frontend 00473 * @param[in] nScreenLeft 00474 * Screen left side 00475 * @param[in] nScreenTop 00476 * Screen top side 00477 * @param[in] nScreenWidth 00478 * Screen width 00479 * @param[in] nScreenHeight 00480 * Screen height 00481 * @param[in] nMinWidth 00482 * Minimum allowed frontend width 00483 * @param[in] nMinHeight 00484 * Minimum allowed frontend height 00485 * 00486 * @note 00487 * - Corrects: The frontend position shouldn't be negative 00488 * - Corrects: The frontend position shouldn't be outside the visible screen 00489 * - Corrects: The size of the frontend shouldn't leave the visible screen 00490 */ 00491 static PLCORE_API void CorrectPositionSize(int &nX, int &nY, uint32 &nWidth, uint32 &nHeight, int nScreenLeft, int nScreenTop, int nScreenWidth, int nScreenHeight, uint32 nMinWidth = 200, uint32 nMinHeight = 200); 00492 00493 00494 //[-------------------------------------------------------] 00495 //[ Protected data ] 00496 //[-------------------------------------------------------] 00497 protected: 00498 Frontend *m_pFrontend; /**< Pointer to frontend, can be a null pointer */ 00499 00500 00501 }; 00502 00503 00504 //[-------------------------------------------------------] 00505 //[ Namespace ] 00506 //[-------------------------------------------------------] 00507 } // PLCore 00508 00509 00510 //[-------------------------------------------------------] 00511 //[ Implementation ] 00512 //[-------------------------------------------------------] 00513 #include "PLCore/Frontend/FrontendImpl.inl" 00514 00515 00516 #endif // __PLCORE_FRONTEND_IMPL_H__
|