 | 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: Frontend.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_H__ 00024 #define __PLCORE_FRONTEND_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 String; 00046 class FrontendImpl; 00047 class FrontendContext; 00048 template <class ValueType> class Array; 00049 00050 00051 //[-------------------------------------------------------] 00052 //[ Classes ] 00053 //[-------------------------------------------------------] 00054 /** 00055 * @brief 00056 * Abstract frontend base class 00057 * 00058 * @remarks 00059 * This base class provides an abstract frontend API which is used to develop 00060 * an actual PixelLight frontend class. Concrete wrappers for certain browsers, 00061 * such as MS Internet Explorer or Mozilla Firefox are used to map the browser 00062 * specific frontend API to this general base class. 00063 * 00064 * The focus of this class is on applications with just one window (if there's a window 00065 * at all, this depends on the used frontend implementation). This focus makes application development 00066 * somewhat easier because you only have to concentrate our realizing your project and not how it 00067 * will be presented (in a window with border, without border, just rendering into an image etc.) to 00068 * the user. 00069 * 00070 * The PixelLight technology is designed to be as flexible as possible and so, although this 00071 * class has a clear focus, it can also be used to develop multi-window applications as well. 00072 * 00073 * Please note that the frontend system is not designed to be a replacement for a decent GUI 00074 * system. In here, only primitive and commonly used GUI related feature are offered with a 00075 * limited feature set. For more complex stuff one has to use a real GUI system. 00076 * 00077 * @note 00078 * - Do only interact with the frontend when it really makes sense because it's not guaranteed 00079 * that every frontend implementation provides every feature exposed by this interface 00080 * - Stuff like window border, window title bar etc. isn't interesting for the frontend, therefore 00081 * methods like "GetNativeWindowHandle()" or "GetWidth()" return only information relevant for e.g. 00082 * rendering into the frontend 00083 */ 00084 class Frontend : public Object, protected AbstractLifecycle, protected AbstractFrontend { 00085 00086 00087 //[-------------------------------------------------------] 00088 //[ Friends ] 00089 //[-------------------------------------------------------] 00090 friend class FrontendImpl; 00091 00092 00093 //[-------------------------------------------------------] 00094 //[ RTTI interface ] 00095 //[-------------------------------------------------------] 00096 pl_class(PLCORE_RTTI_EXPORT, Frontend, "PLCore", PLCore::Object, "Abstract frontend base class") 00097 #ifdef PLCORE_EXPORTS // The following is only required when compiling PLCore 00098 // Methods 00099 pl_method_0(Redraw, pl_ret_type(void), "Redraw frontend.", "") 00100 pl_method_0(Ping, pl_ret_type(void), "Give the frontend a chance to process OS messages.", "") 00101 pl_method_0(RedrawAndPing, pl_ret_type(void), "Redraw frontend and give the frontend a chance to process OS messages.", "") 00102 pl_method_0(GetTitle, pl_ret_type(String), "Returns the frontend title.", "") 00103 pl_method_1(SetTitle, pl_ret_type(void), const String&, "Sets the frontend title.", "") 00104 // Position and size methods 00105 pl_method_0(GetX, pl_ret_type(int), "Returns the x position of the frontend (in screen coordinates).", "") 00106 pl_method_0(GetY, pl_ret_type(int), "Returns the y position of the frontend (in screen coordinates).", "") 00107 pl_method_0(GetWidth, pl_ret_type(uint32), "Returns the frontend width.", "") 00108 pl_method_0(GetHeight, pl_ret_type(uint32), "Returns the frontend height.", "") 00109 // Fullscreen methods 00110 pl_method_0(GetToggleFullscreenMode, pl_ret_type(bool), "Returns whether it's allowed to toggle the fullscreen mode using hotkeys. 'true' if it's possible to toggle the fullscreen mode using hotkeys, else 'false'.", "") 00111 pl_method_1(SetToggleFullscreenMode, pl_ret_type(void), bool, "Sets whether it's allowed to toggle the fullscreen mode using hotkeys. 'true' as first parameter to allow it, else 'false'.", "") 00112 pl_method_0(GetFullscreenAltTab, pl_ret_type(bool), "Returns whether it's allowed to use Alt-Tab if fullscreen mode is used. 'true' if it's possible to use Alt-Tab if fullscreen mode is used, else 'false'.", "") 00113 pl_method_1(SetFullscreenAltTab, pl_ret_type(void), bool, "Sets whether it's allowed to use Alt-Tab if fullscreen mode is used. 'true' as first parameter to allow it, else 'false'.", "") 00114 pl_method_0(IsFullscreen, pl_ret_type(bool), "Returns whether or not the frontend is currently fullscreen or not. Returns 'true' if the frontend is currently fullscreen, else 'false'.", "") 00115 pl_method_1(SetFullscreen, pl_ret_type(void), bool, "Sets whether or not the frontend is currently fullscreen or not. 'true' as first parameter if the frontend is currently fullscreen, else 'false'.", "") 00116 // Mouse methods 00117 pl_method_0(IsMouseOver, pl_ret_type(bool), "Returns whether or not the mouse cursor is currently over the frontend. Returns 'true' if the mouse cursor is currently over the frontend, else 'false'.", "") 00118 pl_method_0(GetMousePositionX, pl_ret_type(int), "Returns the current mouse cursor X position inside the frontend, negative value if the mouse cursor isn't currently over the frontend", "") 00119 pl_method_0(GetMousePositionY, pl_ret_type(int), "Returns the current mouse cursor Y position inside the frontend, negative value if the mouse cursor isn't currently over the frontend", "") 00120 pl_method_0(IsMouseVisible, pl_ret_type(bool), "Returns whether or not the mouse cursor is currently visible. Returns 'true' if the mouse cursor is currently visible, else 'false'.", "") 00121 pl_method_1(SetMouseVisible, pl_ret_type(void), bool, "Set the mouse cursor visibility. 'true' as first parameter if the mouse cursor shall be visible.", "") 00122 pl_method_1(SetTrapMouse, pl_ret_type(void), bool, "Trap the mouse inside the frontend. 'true' as first parameter if the mouse should be trapped inside the frontend, else 'false'.", "") 00123 #endif 00124 pl_class_end 00125 00126 00127 //[-------------------------------------------------------] 00128 //[ Public static functions ] 00129 //[-------------------------------------------------------] 00130 public: 00131 /** 00132 * @brief 00133 * Run the frontend 00134 * 00135 * @param[in] cFrontendContext 00136 * Frontend context to use (just shared, the given instance must stay valid as long as this frontend lives) 00137 * @param[in] bUrgentMessageAllowed 00138 * Is this method allowed to show an urgent message to the user in case of a failure? 00139 * 00140 * @return 00141 * Exit code (usually 0 means no error), usually <0 when there was an error 00142 * (e.g. an embedded frontend implementation is run and controlled by another application and can't be run by using this method) 00143 */ 00144 static PLCORE_API int Run(const FrontendContext &cFrontendContext, bool bUrgentMessageAllowed = true); 00145 00146 00147 //[-------------------------------------------------------] 00148 //[ Public functions ] 00149 //[-------------------------------------------------------] 00150 public: 00151 /** 00152 * @brief 00153 * Constructor 00154 * 00155 * @param[in] cFrontendContext 00156 * Frontend context to use (just shared, the given instance must stay valid as long as this frontend lives) 00157 * @param[in] cFrontendImpl 00158 * Frontend implementation instance 00159 */ 00160 PLCORE_API Frontend(const FrontendContext &cFrontendContext, FrontendImpl &cFrontendImpl); 00161 00162 /** 00163 * @brief 00164 * Destructor 00165 */ 00166 PLCORE_API virtual ~Frontend(); 00167 00168 /** 00169 * @brief 00170 * Get frontend context 00171 * 00172 * @return 00173 * Frontend context 00174 */ 00175 inline const FrontendContext &GetContext() const; 00176 00177 /** 00178 * @brief 00179 * Get frontend implementation 00180 * 00181 * @return 00182 * Pointer to the implementation backend, can be a null pointer 00183 */ 00184 inline FrontendImpl *GetImpl() const; 00185 00186 /** 00187 * @brief 00188 * Get native window handle 00189 * 00190 * @return 00191 * Native window handle for the frontend window, can be a null pointer 00192 */ 00193 inline handle GetNativeWindowHandle() const; 00194 00195 /** 00196 * @brief 00197 * Redraw frontend 00198 * 00199 * @remarks 00200 * There are situations were an application may do some heavy work without letting 00201 * the frontend a chance to redraw. In such situations, it may be wise 00202 * to call this method from time to time to give the frontend a chance to do redraw 00203 * itself. 00204 * 00205 * @note 00206 * - Whenever possible, don't use this method, do heavy work within e.g. threads 00207 * - Depending on the frontend implementation, the redraw may not be immediate 00208 * - Doesn't include "Ping()" 00209 */ 00210 inline void Redraw(); 00211 00212 /** 00213 * @brief 00214 * Give the frontend a chance to process OS messages 00215 * 00216 * @remarks 00217 * There are situations were an application may do some heavy work without letting 00218 * the frontend a chance to process OS messages. In such situations, it may be wise 00219 * to call this method from time to time to give the frontend a chance to do some 00220 * message processing. 00221 * 00222 * @note 00223 * - Whenever possible, don't use this method, do heavy work within e.g. threads 00224 * - Doesn't include "Redraw()" 00225 */ 00226 inline void Ping() const; 00227 00228 /** 00229 * @brief 00230 * Redraw frontend and give the frontend a chance to process OS messages 00231 * 00232 * @remarks 00233 * Calls "Redraw()", then "Ping()". 00234 * 00235 * @note 00236 * - Whenever possible, don't use this method, do heavy work within e.g. threads 00237 */ 00238 inline void RedrawAndPing(); 00239 00240 /** 00241 * @brief 00242 * Get frontend title 00243 * 00244 * @return 00245 * Frontend title 00246 * 00247 * @remarks 00248 * When the frontend has a window, this title can be seen within the window 00249 * title bar. Please note that there's no guarantee that there's a window 00250 * title bar or even a window. By default, the title is set to the frontend 00251 * context name ("GetContext().GetName()") which is usually sufficient. So, 00252 * unless you have a good reason to explicitly set an individual frontend 00253 * title, just use the default setting and don't touch the frontend. 00254 */ 00255 inline String GetTitle() const; 00256 00257 /** 00258 * @brief 00259 * Set frontend title 00260 * 00261 * @param[in] sTitle 00262 * Frontend title 00263 * 00264 * @see 00265 * - GetTitle() 00266 */ 00267 inline void SetTitle(const String &sTitle); 00268 00269 //[-------------------------------------------------------] 00270 //[ Position and size ] 00271 //[-------------------------------------------------------] 00272 /** 00273 * @brief 00274 * Get the x position of the frontend (in screen coordinates) 00275 * 00276 * @return 00277 * X position of the frontend 00278 */ 00279 inline int GetX() const; 00280 00281 /** 00282 * @brief 00283 * Get the y position of the frontend (in screen coordinates) 00284 * 00285 * @return 00286 * Y position of the frontend 00287 */ 00288 inline int GetY() const; 00289 00290 /** 00291 * @brief 00292 * Get frontend width 00293 * 00294 * @return 00295 * Width of the frontend 00296 */ 00297 inline uint32 GetWidth() const; 00298 00299 /** 00300 * @brief 00301 * Get frontend height 00302 * 00303 * @return 00304 * Height of the frontend 00305 */ 00306 inline uint32 GetHeight() const; 00307 00308 /** 00309 * @brief 00310 * Returns frontend window position and size 00311 * 00312 * @param[out] nX 00313 * Receives the x position of the frontend window (in screen coordinates) 00314 * @param[out] nY 00315 * Receives the y position of the frontend window (in screen coordinates) 00316 * @param[out] nWidth 00317 * Receives the width of the frontend window 00318 * @param[out] nHeight 00319 * Receives the height of the frontend window 00320 * 00321 * @remarks 00322 * The primary argument to allow the user to request a frontend window position and size change is, 00323 * that it should be possible to restore the frontend window position and size of a previous session 00324 * (may be important for the usability). Do not misuse this method to frequently manipulate 00325 * the frontend window appearance. Please note that, as for all other frontend methods, this is only 00326 * considered to be a request. A frontend implementation may deny the request in general or 00327 * just improper settings (e.g. a too small size, position outside the visible screen etc.). 00328 */ 00329 inline void GetWindowPositionSize(int &nX, int &nY, uint32 &nWidth, uint32 &nHeight) const; 00330 00331 /** 00332 * @brief 00333 * Set frontend window position and size 00334 * 00335 * @param[in] nX 00336 * X position of the frontend window (in screen coordinates) 00337 * @param[in] nY 00338 * Y position of the frontend window (in screen coordinates) 00339 * @param[in] nWidth 00340 * Width of the frontend window 00341 * @param[in] nHeight 00342 * Height of the frontend window 00343 * 00344 * @see 00345 * - "GetWindowPositionSize"() 00346 */ 00347 inline void SetWindowPositionSize(int nX, int nY, uint32 nWidth, uint32 nHeight); 00348 00349 //[-------------------------------------------------------] 00350 //[ Fullscreen ] 00351 //[-------------------------------------------------------] 00352 /** 00353 * @brief 00354 * Gets whether it's allowed to toggle the fullscreen mode using hotkeys 00355 * 00356 * @return 00357 * 'true' if it's possible to toggle the fullscreen mode using hotkeys, else 'false' 00358 */ 00359 inline bool GetToggleFullscreenMode() const; 00360 00361 /** 00362 * @brief 00363 * Sets whether it's allowed to toggle the fullscreen mode using hotkeys 00364 * 00365 * @param[in] bToggleFullscreenMode 00366 * Is it allowed to toggle the fullscreen mode using hotkeys? 00367 * 00368 * @note 00369 * - By default, it's allowed to switch widgets into fullscreen mode using Alt-Return or AltGr-Return 00370 */ 00371 inline void SetToggleFullscreenMode(bool bToggleFullscreenMode); 00372 00373 /** 00374 * @brief 00375 * Gets whether it's allowed to use Alt-Tab if fullscreen mode is used 00376 * 00377 * @return 00378 * 'true' if it's possible to use Alt-Tab if fullscreen mode is used, else 'false' 00379 * 00380 * @note 00381 * - Widgets only 00382 */ 00383 inline bool GetFullscreenAltTab() const; 00384 00385 /** 00386 * @brief 00387 * Sets whether it's allowed to use Alt-Tab if fullscreen mode is used 00388 * 00389 * @param[in] bAllowed 00390 * Is it allowed to use Alt-Tab within fullscreen mode? 00391 * 00392 * @note 00393 * - By default, it's allowed to use Alt-Tab 00394 * 00395 * @see 00396 * - GetFullscreenAltTab() 00397 */ 00398 inline void SetFullscreenAltTab(bool bAllowed); 00399 00400 /** 00401 * @brief 00402 * Returns whether the frontend is in fullscreen mode or not 00403 * 00404 * @return 00405 * 'true' if the frontend is in fullscreen mode, else 'false' 00406 */ 00407 inline bool IsFullscreen() const; 00408 00409 /** 00410 * @brief 00411 * Sets the frontend's fullscreen mode 00412 * 00413 * @param[in] bFullscreen 00414 * 'true' if the frontend should be in fullscreen mode, else 'false' 00415 */ 00416 inline void SetFullscreen(bool bFullscreen); 00417 00418 /** 00419 * @brief 00420 * Something related to fullscreen mode has been changed (e.g. the display resolution) 00421 */ 00422 inline void RefreshFullscreen(); 00423 00424 //[-------------------------------------------------------] 00425 //[ Mouse ] 00426 //[-------------------------------------------------------] 00427 /** 00428 * @brief 00429 * Check if the mouse is currently over the frontend 00430 * 00431 * @return 00432 * 'true' if mouse-over, else 'false' 00433 */ 00434 inline bool IsMouseOver() const; 00435 00436 /** 00437 * @brief 00438 * Get current mouse cursor X position inside the frontend 00439 * 00440 * @return 00441 * Current mouse cursor X position inside the frontend, negative value if the mouse cursor isn't currently over the frontend 00442 */ 00443 inline int GetMousePositionX() const; 00444 00445 /** 00446 * @brief 00447 * Get current mouse cursor Y position inside the frontend 00448 * 00449 * @return 00450 * Current mouse cursor Y position inside the frontend, negative value if the mouse cursor isn't currently over the frontend 00451 */ 00452 inline int GetMousePositionY() const; 00453 00454 /** 00455 * @brief 00456 * Check if the mouse cursor is visible 00457 * 00458 * @return 00459 * 'true' if the mouse cursor is visible, else 'false' 00460 * 00461 * @note 00462 * - If the mouse cursor is visible in general, it's still possible that it's 00463 * invisible over some special widgets. 00464 * - If the mouse cursor is invisible in general, it will NEVER be visible! 00465 * - Do only hide the mouse cursor when it really makes sense (e.g. during the period 00466 * the mouse is used to control a "camera look around") 00467 */ 00468 inline bool IsMouseVisible() const; 00469 00470 /** 00471 * @brief 00472 * Set mouse cursor visibility 00473 * 00474 * @param[in] bVisible 00475 * Shall the mouse cursor be visible? 00476 * 00477 * @see 00478 * - IsMouseVisible() 00479 */ 00480 inline void SetMouseVisible(bool bVisible); 00481 00482 /** 00483 * @brief 00484 * Trap mouse inside the frontend 00485 * 00486 * @param[in] bTrap 00487 * 'true' if the mouse should be trapped inside the frontend, else 'false' 00488 * 00489 * @note 00490 * - Do only trap the mouse cursor when it really makes sense (e.g. during the period 00491 * the mouse is used to control a "camera look around") 00492 */ 00493 inline void SetTrapMouse(bool bTrap); 00494 00495 00496 //[-------------------------------------------------------] 00497 //[ Public virtual Frontend functions ] 00498 //[-------------------------------------------------------] 00499 public: 00500 /** 00501 * @brief 00502 * Returns whether or not the frontend is currently running 00503 * 00504 * @return 00505 * 'true' if the frontend is currently running, else 'false' 00506 */ 00507 virtual bool IsRunning() const = 0; 00508 00509 00510 //[-------------------------------------------------------] 00511 //[ Protected virtual Frontend functions ] 00512 //[-------------------------------------------------------] 00513 protected: 00514 /** 00515 * @brief 00516 * Called when the frontend is run 00517 * 00518 * @param[in] sExecutableFilename 00519 * Absolute application executable filename 00520 * @param[in] lstArguments 00521 * List of arguments to the program 00522 * 00523 * @remarks 00524 * This frontend method is called just before the frontend calls it's run-method in order to 00525 * enter it's main-loop. This means that this method is called between "AbstractLifecycle::OnCreate()" 00526 * and "AbstractLifecycle::OnStart()". Use this method for instance to pre-process command line arguments. 00527 * 00528 * The default implementation does the following tasks: 00529 * - none (implement in derived classes) 00530 */ 00531 PLCORE_API virtual void OnRun(const String &sExecutableFilename, const Array<String> &lstArguments); 00532 00533 00534 //[-------------------------------------------------------] 00535 //[ Protected data ] 00536 //[-------------------------------------------------------] 00537 protected: 00538 const FrontendContext &m_cFrontendContext; /**< Frontend context to use (just shared, the given instance must stay valid as long as this frontend lives) */ 00539 FrontendImpl *m_pFrontendImpl; /**< Pointer to implementation backend, can be a null pointer */ 00540 00541 00542 //[-------------------------------------------------------] 00543 //[ Private static functions ] 00544 //[-------------------------------------------------------] 00545 private: 00546 /** 00547 * @brief 00548 * Creates a frontend implementation instance 00549 * 00550 * @param[in] cFrontendContext 00551 * Frontend context to use 00552 * 00553 * @return 00554 * Frontend implementation instance, null pointer on error 00555 */ 00556 static FrontendImpl *CreateFrontendImplementation(const FrontendContext &cFrontendContext); 00557 00558 00559 }; 00560 00561 00562 //[-------------------------------------------------------] 00563 //[ Namespace ] 00564 //[-------------------------------------------------------] 00565 } // PLCore 00566 00567 00568 //[-------------------------------------------------------] 00569 //[ Implementation ] 00570 //[-------------------------------------------------------] 00571 #include "PLCore/Frontend/Frontend.inl" 00572 00573 00574 #endif // __PLCORE_FRONTEND_H__
|