 | PixelLight 0.9.11-R1 Copyright (C) 2002-2012 by The PixelLight Team Last modified Thu Feb 23 2012 14:08:54 |  | 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-2012 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 * Returns frontend window position and size 00282 * 00283 * @param[out] nX 00284 * Receives the x position of the frontend window (in screen coordinates) 00285 * @param[out] nY 00286 * Receives the y position of the frontend window (in screen coordinates) 00287 * @param[out] nWidth 00288 * Receives the width of the frontend window 00289 * @param[out] nHeight 00290 * Receives the height of the frontend window 00291 * 00292 * @remarks 00293 * The primary argument to allow the user to request a frontend window position and size change is, 00294 * that it should be possible to restore the frontend window 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 window 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 GetWindowPositionSize(int &nX, int &nY, uint32 &nWidth, uint32 &nHeight) const = 0; 00301 00302 /** 00303 * @brief 00304 * Set frontend window position and size 00305 * 00306 * @param[in] nX 00307 * X position of the frontend window (in screen coordinates) 00308 * @param[in] nY 00309 * Y position of the frontend window (in screen coordinates) 00310 * @param[in] nWidth 00311 * Width of the frontend window 00312 * @param[in] nHeight 00313 * Height of the frontend window 00314 * 00315 * @see 00316 * - "GetWindowPositionSize"() 00317 */ 00318 virtual void SetWindowPositionSize(int nX, int nY, uint32 nWidth, uint32 nHeight) = 0; 00319 00320 //[-------------------------------------------------------] 00321 //[ Fullscreen ] 00322 //[-------------------------------------------------------] 00323 /** 00324 * @brief 00325 * Gets whether it's allowed to toggle the fullscreen mode using hotkeys 00326 * 00327 * @return 00328 * 'true' if it's possible to toggle the fullscreen mode using hotkeys, else 'false' 00329 */ 00330 virtual bool GetToggleFullscreenMode() const = 0; 00331 00332 /** 00333 * @brief 00334 * Sets whether it's allowed to toggle the fullscreen mode using hotkeys 00335 * 00336 * @param[in] bToggleFullscreenMode 00337 * Is it allowed to toggle the fullscreen mode using hotkeys? 00338 * 00339 * @note 00340 * - By default, it's allowed to switch widgets into fullscreen mode using Alt-Return or AltGr-Return 00341 */ 00342 virtual void SetToggleFullscreenMode(bool bToggleFullscreenMode) = 0; 00343 00344 /** 00345 * @brief 00346 * Gets whether it's allowed to use Alt-Tab if fullscreen mode is used 00347 * 00348 * @return 00349 * 'true' if it's possible to use Alt-Tab if fullscreen mode is used, else 'false' 00350 * 00351 * @note 00352 * - Widgets only 00353 */ 00354 virtual bool GetFullscreenAltTab() const = 0; 00355 00356 /** 00357 * @brief 00358 * Sets whether it's allowed to use Alt-Tab if fullscreen mode is used 00359 * 00360 * @param[in] bAllowed 00361 * Is it allowed to use Alt-Tab within fullscreen mode? 00362 * 00363 * @note 00364 * - By default, it's allowed to use Alt-Tab 00365 * 00366 * @see 00367 * - GetFullscreenAltTab() 00368 */ 00369 virtual void SetFullscreenAltTab(bool bAllowed) = 0; 00370 00371 /** 00372 * @brief 00373 * Returns whether the frontend is in fullscreen mode or not 00374 * 00375 * @return 00376 * 'true' if the frontend is in fullscreen mode, else 'false' 00377 */ 00378 virtual bool IsFullscreen() const = 0; 00379 00380 /** 00381 * @brief 00382 * Sets the frontend's fullscreen mode 00383 * 00384 * @param[in] bFullscreen 00385 * 'true' if the frontend should be in fullscreen mode, else 'false' 00386 */ 00387 virtual void SetFullscreen(bool bFullscreen) = 0; 00388 00389 /** 00390 * @brief 00391 * Something related to fullscreen mode has been changed (e.g. the display resolution) 00392 */ 00393 virtual void RefreshFullscreen() = 0; 00394 00395 //[-------------------------------------------------------] 00396 //[ Mouse ] 00397 //[-------------------------------------------------------] 00398 /** 00399 * @brief 00400 * Check if the mouse is currently over the frontend 00401 * 00402 * @return 00403 * 'true' if mouse-over, else 'false' 00404 */ 00405 virtual bool IsMouseOver() const = 0; 00406 00407 /** 00408 * @brief 00409 * Get current mouse cursor X position inside the frontend 00410 * 00411 * @return 00412 * Current mouse cursor X position inside the frontend, negative value if the mouse cursor isn't currently over the frontend 00413 */ 00414 virtual int GetMousePositionX() const = 0; 00415 00416 /** 00417 * @brief 00418 * Get current mouse cursor Y position inside the frontend 00419 * 00420 * @return 00421 * Current mouse cursor Y position inside the frontend, negative value if the mouse cursor isn't currently over the frontend 00422 */ 00423 virtual int GetMousePositionY() const = 0; 00424 00425 /** 00426 * @brief 00427 * Check if the mouse cursor is visible 00428 * 00429 * @return 00430 * 'true' if the mouse cursor is visible, else 'false' 00431 * 00432 * @note 00433 * - If the mouse cursor is visible in general, it's still possible that it's 00434 * invisible over some special widgets. 00435 * - If the mouse cursor is invisible in general, it will NEVER be visible! 00436 */ 00437 virtual bool IsMouseVisible() const = 0; 00438 00439 /** 00440 * @brief 00441 * Set mouse cursor visibility 00442 * 00443 * @param[in] bVisible 00444 * Shall the mouse cursor be visible? 00445 * 00446 * @see 00447 * - IsMouseVisible() 00448 */ 00449 virtual void SetMouseVisible(bool bVisible) = 0; 00450 00451 /** 00452 * @brief 00453 * Trap mouse inside the frontend 00454 * 00455 * @param[in] bTrap 00456 * 'true' if the mouse should be trapped inside the frontend, else 'false' 00457 */ 00458 virtual void SetTrapMouse(bool bTrap) = 0; 00459 00460 00461 //[-------------------------------------------------------] 00462 //[ Protected static functions ] 00463 //[-------------------------------------------------------] 00464 protected: 00465 /** 00466 * @brief 00467 * Creates a frontend instance 00468 * 00469 * @param[in] cFrontendContext 00470 * Frontend context to use 00471 * @param[in] cFrontendImpl 00472 * Frontend implementation instance 00473 * 00474 * @return 00475 * Frontend instance, null pointer on error 00476 */ 00477 static PLCORE_API Frontend *CreateFrontend(const FrontendContext &cFrontendContext, FrontendImpl &cFrontendImpl); 00478 00479 /** 00480 * @brief 00481 * Correct frontend position and size settings 00482 * 00483 * @param[in, out] nX 00484 * X position of the frontend (in screen coordinates) 00485 * @param[in, out] nY 00486 * Y position of the frontend (in screen coordinates) 00487 * @param[in, out] nWidth 00488 * Width of the frontend 00489 * @param[in, out] nHeight 00490 * Height of the frontend 00491 * @param[in] nScreenLeft 00492 * Screen left side 00493 * @param[in] nScreenTop 00494 * Screen top side 00495 * @param[in] nScreenWidth 00496 * Screen width 00497 * @param[in] nScreenHeight 00498 * Screen height 00499 * @param[in] nMinWidth 00500 * Minimum allowed frontend width 00501 * @param[in] nMinHeight 00502 * Minimum allowed frontend height 00503 * 00504 * @note 00505 * - Corrects: The frontend position shouldn't be negative 00506 * - Corrects: The frontend position shouldn't be outside the visible screen 00507 * - Corrects: The size of the frontend shouldn't leave the visible screen 00508 */ 00509 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); 00510 00511 00512 //[-------------------------------------------------------] 00513 //[ Protected data ] 00514 //[-------------------------------------------------------] 00515 protected: 00516 Frontend *m_pFrontend; /**< Pointer to frontend, can be a null pointer */ 00517 00518 00519 }; 00520 00521 00522 //[-------------------------------------------------------] 00523 //[ Namespace ] 00524 //[-------------------------------------------------------] 00525 } // PLCore 00526 00527 00528 //[-------------------------------------------------------] 00529 //[ Implementation ] 00530 //[-------------------------------------------------------] 00531 #include "PLCore/Frontend/FrontendImpl.inl" 00532 00533 00534 #endif // __PLCORE_FRONTEND_IMPL_H__
|