 | PixelLight 0.9.11-R1 Copyright (C) 2002-2012 by The PixelLight Team Last modified Thu Feb 23 2012 14:08:56 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: Gui.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 __PLGUI_GUI_H__ 00024 #define __PLGUI_GUI_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include <PLCore/Base/Object.h> 00032 #include <PLCore/Base/Event/EventHandler.h> 00033 #include <PLMath/Vector2i.h> 00034 #include "PLGui/Gui/FontManager.h" 00035 #include "PLGui/Gui/CursorManager.h" 00036 #include "PLGui/Gui/ClipBoard.h" 00037 #include "PLGui/PLGuiDefinitions.h" 00038 00039 00040 //[-------------------------------------------------------] 00041 //[ Forward declarations ] 00042 //[-------------------------------------------------------] 00043 namespace PLGui { 00044 class GuiMessage; 00045 class MessageFilter; 00046 class GuiImpl; 00047 class Screen; 00048 class Theme; 00049 class Widget; 00050 class WidgetImpl; 00051 class Graphics; 00052 class GraphicsImpl; 00053 class Image; 00054 class ImageImpl; 00055 class Font; 00056 class FontImpl; 00057 class Cursor; 00058 class CursorImpl; 00059 class TrayIcon; 00060 class TrayIconImpl; 00061 class ClipBoardImpl; 00062 class Timer; 00063 class Tooltip; 00064 } 00065 00066 00067 //[-------------------------------------------------------] 00068 //[ Namespace ] 00069 //[-------------------------------------------------------] 00070 namespace PLGui { 00071 00072 00073 //[-------------------------------------------------------] 00074 //[ Classes ] 00075 //[-------------------------------------------------------] 00076 /** 00077 * @brief 00078 * Main GUI class 00079 * 00080 * @remarks 00081 * This class provides the main functions of a GUI system (desktop, widgets, ...) 00082 * 00083 * @note 00084 * - Implementation of the bridge design pattern, this class is the abstraction 00085 */ 00086 class Gui : public PLCore::Object { 00087 00088 00089 //[-------------------------------------------------------] 00090 //[ Friends ] 00091 //[-------------------------------------------------------] 00092 friend class Widget; 00093 friend class Graphics; 00094 friend class Image; 00095 friend class Font; 00096 friend class Cursor; 00097 friend class TrayIcon; 00098 friend class ClipBoard; 00099 friend class Timer; 00100 00101 00102 //[-------------------------------------------------------] 00103 //[ Class definition ] 00104 //[-------------------------------------------------------] 00105 pl_class(PLGUI_RTTI_EXPORT, Gui, "PLGui", PLCore::Object, "Main GUI class") 00106 #ifdef PLGUI_EXPORTS // The following is only required when compiling PLGui 00107 // Methods 00108 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.", "") 00109 #endif 00110 pl_class_end 00111 00112 00113 //[-------------------------------------------------------] 00114 //[ Public static functions ] 00115 //[-------------------------------------------------------] 00116 public: 00117 /** 00118 * @brief 00119 * Get system GUI 00120 * 00121 * @return 00122 * Pointer to system GUI 00123 */ 00124 static PLGUI_API Gui *GetSystemGui(); 00125 00126 00127 //[-------------------------------------------------------] 00128 //[ Public functions ] 00129 //[-------------------------------------------------------] 00130 public: 00131 /** 00132 * @brief 00133 * Constructor 00134 * 00135 * @param[in] sGui 00136 * Name of the GUI backend that shall be used. Just leave this empty for the system GUI 00137 * 00138 * @remarks 00139 * To obtain a pointer to the system GUI, use GetSystemGui() instead of creating a new instance 00140 */ 00141 PLGUI_API Gui(const PLCore::String &sGui = ""); 00142 00143 /** 00144 * @brief 00145 * Destructor 00146 */ 00147 PLGUI_API virtual ~Gui(); 00148 00149 /** 00150 * @brief 00151 * Get implementation 00152 * 00153 * @return 00154 * Pointer to platform specific implementation 00155 */ 00156 PLGUI_API GuiImpl *GetImpl() const; 00157 00158 /** 00159 * @brief 00160 * Shut down GUI and clean up 00161 * 00162 * @remarks 00163 * Call this for the system GUI at the end of your application, otherwise there 00164 * might be trouble with the static deinitialization order! 00165 */ 00166 PLGUI_API void Shutdown(); 00167 00168 //[-------------------------------------------------------] 00169 //[ Control and message loop ] 00170 //[-------------------------------------------------------] 00171 /** 00172 * @brief 00173 * Check if the GUI is still active 00174 * 00175 * @return 00176 * 'true', if the GUI is active, 'false' if the program shall quit 00177 */ 00178 PLGUI_API bool IsActive() const; 00179 00180 /** 00181 * @brief 00182 * Exit application 00183 */ 00184 PLGUI_API void Exit(); 00185 00186 /** 00187 * @brief 00188 * Check if there are system messages waiting 00189 * 00190 * @return 00191 * 'true' if there are messages in the queue 00192 */ 00193 PLGUI_API bool HasPendingMessages() const; 00194 00195 /** 00196 * @brief 00197 * Process all waiting messages, blocks if no messages are waiting 00198 */ 00199 PLGUI_API void ProcessMessages(); 00200 00201 /** 00202 * @brief 00203 * Post message to the message queue 00204 * 00205 * @param[in] cMessage 00206 * Message to be posted 00207 * 00208 * @remarks 00209 * This function adds the given message to the message queue, so that it will be processed 00210 * with subsequent call(s) to ProcessMessages(). To send a message directly (bypassing the 00211 * message queue), see SendMessage(). 00212 */ 00213 PLGUI_API void PostMessage(const GuiMessage &cMessage); 00214 00215 /** 00216 * @brief 00217 * Send and process a message directly 00218 * 00219 * @param[in] cMessage 00220 * Message to be sent 00221 * 00222 * @remarks 00223 * This function sends a message directly to the GUI. Use this only if you know exactly, what you are 00224 * doing, because this bypasses the message queue. Usually it is the right way to post a message to the 00225 * queue for it to get processed in the right order (after calling ProcessMessages()). 00226 */ 00227 PLGUI_API void SendMessage(const GuiMessage &cMessage); 00228 00229 /** 00230 * @brief 00231 * Wakeup message loop 00232 * 00233 * @remarks 00234 * This function posts a wakeup-message to the message loop, so that it wakes up 00235 */ 00236 PLGUI_API void WakeUp(); 00237 00238 /** 00239 * @brief 00240 * Get message filters 00241 * 00242 * @return 00243 * List of message filters 00244 */ 00245 PLGUI_API const PLCore::Container<MessageFilter*> &GetMessageFilters() const; 00246 00247 /** 00248 * @brief 00249 * Add message filter 00250 * 00251 * @param[in] pFilter 00252 * Message filter, will be destroyed by Gui automatically 00253 */ 00254 PLGUI_API void AddMessageFilter(MessageFilter *pFilter); 00255 00256 /** 00257 * @brief 00258 * Remove and destroy message filter 00259 * 00260 * @param[in] pFilter 00261 * Message filter 00262 */ 00263 PLGUI_API void RemoveMessageFilter(MessageFilter *pFilter); 00264 00265 /** 00266 * @brief 00267 * Returns the root widget 00268 * 00269 * @return 00270 * Root widget, a null pointer on error 00271 */ 00272 PLGUI_API Widget *GetRootWidget() const; 00273 00274 //[-------------------------------------------------------] 00275 //[ Screens ] 00276 //[-------------------------------------------------------] 00277 /** 00278 * @brief 00279 * Get list of screens (monitors) 00280 * 00281 * @return 00282 * List of screens 00283 */ 00284 PLGUI_API const PLCore::Container<Screen*> &GetScreens() const; 00285 00286 /** 00287 * @brief 00288 * Get screen by name 00289 * 00290 * @param[in] sName 00291 * Name of screen 00292 * 00293 * @return 00294 * Pointer to the specific screen, or a null pointer if that screen doesn't exist 00295 */ 00296 PLGUI_API Screen *GetScreen(const PLCore::String &sName) const; 00297 00298 /** 00299 * @brief 00300 * Get default screen 00301 * 00302 * @return 00303 * Pointer to the default screen, never a null pointer 00304 */ 00305 PLGUI_API Screen *GetDefaultScreen() const; 00306 00307 //[-------------------------------------------------------] 00308 //[ Resources ] 00309 //[-------------------------------------------------------] 00310 /** 00311 * @brief 00312 * Get font manager 00313 * 00314 * @return 00315 * Font manager 00316 */ 00317 PLGUI_API FontManager &GetFontManager(); 00318 00319 /** 00320 * @brief 00321 * Get cursor manager 00322 * 00323 * @return 00324 * Cursor manager 00325 */ 00326 PLGUI_API CursorManager &GetCursorManager(); 00327 00328 /** 00329 * @brief 00330 * Get clipboard 00331 * 00332 * @return 00333 * Clipboard 00334 */ 00335 PLGUI_API ClipBoard &GetClipBoard(); 00336 00337 //[-------------------------------------------------------] 00338 //[ Gui info and state ] 00339 //[-------------------------------------------------------] 00340 /** 00341 * @brief 00342 * Check if the GUI has a taskbar 00343 * 00344 * @return 00345 * 'true', if the GUI has a taskbar, else 'false' 00346 */ 00347 PLGUI_API bool HasTaskbar() const; 00348 00349 /** 00350 * @brief 00351 * Check if the mouse cursor is visible 00352 * 00353 * @return 00354 * 'true' if the mouse cursor is visible, else 'false' 00355 * 00356 * @note 00357 * - If the mouse cursor is visible in general, it's still possible that it's 00358 * invisible over some special widgets. 00359 * - If the mouse cursor is invisible in general, it will NEVER be visible! 00360 */ 00361 PLGUI_API bool IsMouseVisible() const; 00362 00363 /** 00364 * @brief 00365 * Set mouse cursor visibility 00366 * 00367 * @param[in] bVisible 00368 * Shall the mouse cursor be visible? 00369 * 00370 * @see 00371 * - IsMouseVisible() 00372 */ 00373 PLGUI_API void SetMouseVisible(bool bVisible); 00374 00375 /** 00376 * @brief 00377 * Get widget that the mouse is currently in 00378 * 00379 * @return 00380 * Widget the mouse is currently in, or a null pointer 00381 */ 00382 PLGUI_API Widget *GetMouseOverWidget() const; 00383 00384 /** 00385 * @brief 00386 * Get widget that currently has the focus 00387 * 00388 * @return 00389 * Widget that currently has the focus, or a null pointer 00390 */ 00391 PLGUI_API Widget *GetFocusWidget() const; 00392 00393 /** 00394 * @brief 00395 * Display a tooltip 00396 * 00397 * @param[in] vPos 00398 * Position of tooltip 00399 * @param[in] sTooltip 00400 * Tooltip text 00401 */ 00402 PLGUI_API void ShowTooltip(const PLMath::Vector2i &vPos, const PLCore::String &sTooltip); 00403 00404 //[-------------------------------------------------------] 00405 //[ Theme ] 00406 //[-------------------------------------------------------] 00407 /** 00408 * @brief 00409 * Get theme 00410 * 00411 * @return 00412 * Pointer to current theme 00413 */ 00414 PLGUI_API Theme *GetTheme() const; 00415 00416 /** 00417 * @brief 00418 * Set theme 00419 * 00420 * @param[in] pTheme 00421 * Theme 00422 */ 00423 PLGUI_API void SetTheme(Theme *pTheme); 00424 00425 /** 00426 * @brief 00427 * Set theme 00428 * 00429 * @param[in] sClass 00430 * Theme class 00431 * @param[in] sOptions 00432 * Theme options 00433 */ 00434 PLGUI_API void SetTheme(const PLCore::String &sClass, const PLCore::String &sOptions); 00435 00436 //[-------------------------------------------------------] 00437 //[ Options ] 00438 //[-------------------------------------------------------] 00439 /** 00440 * @brief 00441 * Get time after which a hove event occurs 00442 * 00443 * @return 00444 * Timeout (in milliseconds) 00445 */ 00446 PLGUI_API PLCore::uint64 GetHoverTime() const; 00447 00448 /** 00449 * @brief 00450 * Set time after which a hove event occurs 00451 * 00452 * @param[in] nTimeout 00453 * Timeout (in milliseconds) 00454 * 00455 * @remarks 00456 * If set to 0, hover events will be disabled completely. 00457 */ 00458 PLGUI_API void SetHoverTime(PLCore::uint64 nTimeout); 00459 00460 00461 //[-------------------------------------------------------] 00462 //[ Private functions ] 00463 //[-------------------------------------------------------] 00464 private: 00465 /** 00466 * @brief 00467 * Get new widget ID 00468 * 00469 * @return 00470 * Widget ID for a newly created widget 00471 */ 00472 PLCore::uint32 GetUniqueWidgetID(); 00473 00474 /** 00475 * @brief 00476 * Delete destroyed widgets 00477 * 00478 * @remarks 00479 * Widgets, that are destroyed, will receive an OnDestroy-Event an have their system window destroyed 00480 * immediately, while their actual Widget object remains intact for a while. This function actually 00481 * deletes those Widgets. Usually, this is called occasionally by the GUI itself, therefor it should 00482 * not be needed to call this directly. 00483 */ 00484 void DeleteDestroyedWidgets(); 00485 00486 /** 00487 * @brief 00488 * Add widget to list of top-level widgets 00489 * 00490 * @param[in] pWidget 00491 * Widget 00492 */ 00493 void AddTopLevelWidget(Widget *pWidget); 00494 00495 /** 00496 * @brief 00497 * Add widget to list of wrapper widgets 00498 * 00499 * @param[in] pWidget 00500 * Widget 00501 */ 00502 void AddWrapperWidget(Widget *pWidget); 00503 00504 /** 00505 * @brief 00506 * Add timer to list of active timers 00507 * 00508 * @param[in] pTimer 00509 * Timer 00510 */ 00511 void AddTimer(Timer *pTimer); 00512 00513 /** 00514 * @brief 00515 * Remove timer from list of active timers 00516 * 00517 * @param[in] pTimer 00518 * Timer 00519 */ 00520 void RemoveTimer(Timer *pTimer); 00521 00522 /** 00523 * @brief 00524 * Update mouse-over widget 00525 */ 00526 void UpdateMouseOverWidget(); 00527 00528 /** 00529 * @brief 00530 * Update focus widget 00531 */ 00532 void UpdateFocusWidget(); 00533 00534 /** 00535 * @brief 00536 * Callback for hover timer 00537 */ 00538 void OnHoverTimer(); 00539 00540 /** 00541 * @brief 00542 * Create a widget implementation 00543 * 00544 * @param[in] cWidget 00545 * Widget 00546 * 00547 * @return 00548 * Platform specific widget implementation 00549 */ 00550 WidgetImpl *CreateWidgetImpl(Widget &cWidget) const; 00551 00552 /** 00553 * @brief 00554 * Create a graphics implementation 00555 * 00556 * @param[in] cGraphics 00557 * Graphics object 00558 * 00559 * @return 00560 * Platform specific graphics implementation 00561 */ 00562 GraphicsImpl *CreateGraphicsImpl(Graphics &cGraphics) const; 00563 00564 /** 00565 * @brief 00566 * Create an image implementation 00567 * 00568 * @param[in] cImage 00569 * Image object 00570 * 00571 * @return 00572 * Platform specific image implementation 00573 */ 00574 ImageImpl *CreateImageImpl(Image &cImage) const; 00575 00576 /** 00577 * @brief 00578 * Create a font implementation 00579 * 00580 * @param[in] cFont 00581 * Font object 00582 * 00583 * @return 00584 * Platform specific font implementation 00585 */ 00586 FontImpl *CreateFontImpl(Font &cFont) const; 00587 00588 /** 00589 * @brief 00590 * Create a cursor implementation 00591 * 00592 * @param[in] cCursor 00593 * Cursor object 00594 * 00595 * @return 00596 * Platform specific cursor implementation 00597 */ 00598 CursorImpl *CreateCursorImpl(Cursor &cCursor) const; 00599 00600 /** 00601 * @brief 00602 * Create a tray-icon implementation 00603 * 00604 * @param[in] cTrayIcon 00605 * TrayIcon object 00606 * 00607 * @return 00608 * Platform specific tray-icon implementation 00609 */ 00610 TrayIconImpl *CreateTrayIconImpl(TrayIcon &cTrayIcon) const; 00611 00612 /** 00613 * @brief 00614 * Create a clipboard implementation 00615 * 00616 * @param[in] cClipBoard 00617 * ClipBoard object 00618 * 00619 * @return 00620 * Platform specific clipboard implementation 00621 */ 00622 ClipBoardImpl *CreateClipBoardImpl(ClipBoard &cClipBoard) const; 00623 00624 00625 //[-------------------------------------------------------] 00626 //[ Private data ] 00627 //[-------------------------------------------------------] 00628 private: 00629 // Data 00630 GuiImpl *m_pGuiImpl; /**< Gui implementation, always valid! */ 00631 bool m_bShutdown; /**< Has the GUI shut down? */ 00632 Theme *m_pTheme; /**< Current theme */ 00633 PLCore::uint64 m_nHoverTime; /**< Time in milliseconds before a hove event shall occur */ 00634 FontManager m_cFontManager; /**< Font manager */ 00635 CursorManager m_cCursorManager; /**< Cursor manager */ 00636 ClipBoard m_cClipBoard; /**< Clip board */ 00637 bool m_bActive; /**< 'true' if the GUI is active */ 00638 PLCore::uint32 m_nNextWidgetID; /**< Sequential widget ID */ 00639 PLCore::List<Screen*> m_lstScreens; /**< List of available screens (monitors) */ 00640 Screen *m_pDefaultScreen; /**< Pointer to default (primary) screen */ 00641 bool m_bMouseVisible; /**< Is the mouse cursor visible? */ 00642 Widget *m_pRootWidget; /**< Dummy root widget */ 00643 PLCore::List<Widget*> m_lstTopLevelWidgets; /**< List of top-level widgets */ 00644 PLCore::List<Widget*> m_lstWrapperWidgets; /**< List of wrapper widgets */ 00645 PLCore::List<Widget*> m_lstDestroyedWidgets; /**< List of destroyed widgets */ 00646 PLCore::List<Timer*> m_lstTimers; /**< List of active timers */ 00647 PLCore::List<MessageFilter*> m_lstMessageFilters; /**< Message filters */ 00648 Widget *m_pMouseOverWidget; /**< Widget that is currently selected by the mouse */ 00649 Widget *m_pMouseOverWidgetNew; /**< New mouse-over widget */ 00650 Timer *m_pHoverTimer; /**< Timer for hover messages */ 00651 Widget *m_pFocusWidget; /**< Widget that currently has the keyboard focus */ 00652 Widget *m_pFocusWidgetNew; /**< New focus widget */ 00653 Tooltip *m_pTooltip; /**< Tooltip widget */ 00654 00655 // Event handlers 00656 PLCore::EventHandler<> EventHandlerOnHoverTimer; /**< Event handler for hover timer event */ 00657 00658 00659 }; 00660 00661 00662 //[-------------------------------------------------------] 00663 //[ Namespace ] 00664 //[-------------------------------------------------------] 00665 } // PLGui 00666 00667 00668 #endif // __PLGUI_GUI_H__
|