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