 | PixelLight 0.9.11-R1 Copyright (C) 2002-2012 by The PixelLight Team Last modified Thu Feb 23 2012 14:09:01 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: Widget.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_WIDGET_H__ 00024 #define __PLGUI_WIDGET_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include <PLGraphics/Color/Color4.h> 00032 #include <PLMath/Vector2i.h> 00033 #include <PLCore/Base/Object.h> 00034 #include <PLCore/Base/Event/Event.h> 00035 #include "PLGui/PLGuiDefinitions.h" 00036 #include "PLGui/Gui/Data/LayoutHints.h" 00037 #include "PLGui/Gui/Resources/Image.h" 00038 #include "PLGui/Gui/Resources/Cursor.h" 00039 #include "PLGui/Gui/Base/WidgetFunctions.h" 00040 00041 00042 //[-------------------------------------------------------] 00043 //[ Forward declarations ] 00044 //[-------------------------------------------------------] 00045 namespace PLMath { 00046 class Vector2i; 00047 } 00048 namespace PLGui { 00049 class Gui; 00050 class GuiMessage; 00051 class Screen; 00052 class Theme; 00053 class WidgetImpl; 00054 class Graphics; 00055 class DataObject; 00056 class Modifier; 00057 class Layout; 00058 } 00059 00060 00061 //[-------------------------------------------------------] 00062 //[ Namespace ] 00063 //[-------------------------------------------------------] 00064 namespace PLGui { 00065 00066 00067 //[-------------------------------------------------------] 00068 //[ Classes ] 00069 //[-------------------------------------------------------] 00070 /** 00071 * @brief 00072 * Widget class 00073 * 00074 * @remarks 00075 * This class represents a basic widget 00076 * 00077 * @note 00078 * - Implementation of the bridge design pattern, this class is the abstraction 00079 */ 00080 class Widget : public PLCore::Object, public WidgetFunctions { 00081 00082 00083 //[-------------------------------------------------------] 00084 //[ Friends ] 00085 //[-------------------------------------------------------] 00086 friend class Gui; 00087 friend class Screen; 00088 friend class WidgetImpl; 00089 00090 00091 //[-------------------------------------------------------] 00092 //[ Class definition ] 00093 //[-------------------------------------------------------] 00094 pl_class(PLGUI_RTTI_EXPORT, Widget, "PLGui", PLCore::Object, "Widget base class") 00095 // Attributes 00096 pl_attribute(ID, PLCore::uint32, 0, ReadWrite, GetSet, "Widget ID", "") 00097 pl_attribute(Name, PLCore::String, "", ReadWrite, GetSet, "Widget name", "") 00098 pl_attribute(Title, PLCore::String, "No Title", ReadWrite, GetSet, "Widget title", "") 00099 pl_attribute(Pos, PLMath::Vector2i, PLMath::Vector2i(0, 0), ReadWrite, GetSet, "Widget position", "") 00100 pl_attribute(Size, PLMath::Vector2i, PLMath::Vector2i(0, 0), ReadWrite, GetSet, "Widget size", "") 00101 pl_attribute(Topmost, bool, false, ReadWrite, GetSet, "Topmost state", "") 00102 pl_attribute(BackgroundColor, PLGraphics::Color4, PLGraphics::Color4(), ReadWrite, GetSet, "Background color", "") 00103 #ifdef PLGUI_EXPORTS // The following is only required when compiling PLGui 00104 // Constructors 00105 pl_constructor_0(DefaultConstructor, "Default constructor", "") 00106 // Methods 00107 pl_method_0(GetGui, pl_ret_type(Gui*), "Get the owner GUI. Returns pointer to GUI object, can be a null pointer.", "") 00108 pl_method_0(GetContentWidget, pl_ret_type(Widget*), "Get the content widget, can be a null pointer.", "") 00109 pl_method_1(SetTrapMouse, pl_ret_type(void), bool, "Trap the mouse inside the widget. 'true' as first parameter if the mouse should be trapped inside the widget, else 'false'.", "") 00110 #endif 00111 // Signals 00112 pl_signal_2(SignalUserMessage, PLCore::uint32, void*, "User message, two custom parameters", "") 00113 pl_signal_0(SignalOnThemeChanged, "Theme has been changed", "") 00114 pl_signal_0(SignalUpdateContent, "Widget content has been changed", "") 00115 pl_signal_1(SignalUpdateChildWidget, Widget*, "Child widget has been changed, child widget as parameter", "") 00116 pl_signal_1(SignalAddChildWidget, Widget*, "Child widget has been added, child widget as parameter", "") 00117 pl_signal_1(SignalRemoveChildWidget, Widget*, "Child widget has been removed, child widget as parameter", "") 00118 pl_signal_0(SignalClose, "Widget shall be closed (ALT+F4 or X-Button pressed)", "") 00119 pl_signal_0(SignalCreate, "Widget has just been created", "") 00120 pl_signal_0(SignalDestroy, "Widget is going to be destroyed", "") 00121 pl_signal_0(SignalShow, "Widget gets shown", "") 00122 pl_signal_0(SignalHide, "Widget gets hidden", "") 00123 pl_signal_0(SignalEnable, "Widget gets enabled", "") 00124 pl_signal_0(SignalDisable, "Widget gets disabled", "") 00125 pl_signal_0(SignalGetFocus, "Widget gets focus", "") 00126 pl_signal_0(SignalLooseFocus, "Widget looses focus", "") 00127 pl_signal_1(SignalActivate, bool, "Widget has been activated or deactivated (focus-widget has changed), state as parameter", "") 00128 pl_signal_1(SignalDrawBackground, Graphics&, "Widget background gets drawn, graphics object used for painting as parameter", "") 00129 pl_signal_1(SignalDraw, Graphics&, "Widget gets drawn, graphics object used for painting as parameter", "") 00130 pl_signal_1(SignalMove, const PLMath::Vector2i&, "Widget gets moved, new widget position as parameter", "") 00131 pl_signal_1(SignalSize, const PLMath::Vector2i&, "Widget gets resized, new widget size as parameter", "") 00132 pl_signal_1(SignalWindowState, EWindowState, "Window state has changed, new window state as parameter", "") 00133 pl_signal_0(SignalEnterFullscreen, "Widget enters fullscreen mode", "") 00134 pl_signal_0(SignalLeaveFullscreen, "Widget leaves fullscreen mode", "") 00135 pl_signal_1(SignalPreferredSize, const PLMath::Vector2i&, "Widget has calculated it's preferred size, preferred size as parameter", "") 00136 pl_signal_0(SignalAdjustContent, "Widget content has to be adjusted", "") 00137 pl_signal_0(SignalMouseEnter, "Mouse enters widget", "") 00138 pl_signal_0(SignalMouseLeave, "Mouse leaves widget", "") 00139 pl_signal_1(SignalMouseOver, bool, "Mouse-over widget has changed, state as parameter", "") 00140 pl_signal_1(SignalMouseMove, const PLMath::Vector2i&, "Mouse moves inside the widget, mouse position within the widget as parameter", "") 00141 pl_signal_0(SignalMouseHover, "Mouse hovers over the widget", "") 00142 pl_signal_1(SignalMousePosUpdate, const PLMath::Vector2i&, "Mouse position inside the widget has changed due to the movement of widget, position as parameter", "") 00143 pl_signal_2(SignalMouseButtonDown, PLCore::uint32, const PLMath::Vector2i&, "Mouse button is pressed, mouse button and mouse position within the widget as parameters", "") 00144 pl_signal_2(SignalMouseButtonUp, PLCore::uint32, const PLMath::Vector2i&, "Mouse button is released, mouse button and mouse position within the widget as parameters", "") 00145 pl_signal_2(SignalMouseButtonClick, PLCore::uint32, const PLMath::Vector2i&, "Mouse button has been clicked, mouse button and mouse position within the widget as parameters", "") 00146 pl_signal_2(SignalMouseButtonDoubleClick, PLCore::uint32, const PLMath::Vector2i&, "Mouse button has been double-clicked, mouse button and mouse position within the widget as parameters", "") 00147 pl_signal_1(SignalMouseWheel, int, "Mouse wheel moved, mouse wheel movement as parameter", "") 00148 pl_signal_2(SignalKeyDown, PLCore::uint32, PLCore::uint32, "Key gets pressed, pressed key and modifier keys pressed as parameters", "") 00149 pl_signal_2(SignalKeyUp, PLCore::uint32, PLCore::uint32, "Key gets released, released key and modifier keys pressed as parameters", "") 00150 pl_signal_1(SignalHotkey, PLCore::uint32, "Hotkey pressed, hotkey ID as parameter", "") 00151 pl_signal_1(SignalDrop, const DataObject&, "Data has been dropped onto the widget, data as parameter", "") 00152 pl_class_end 00153 00154 00155 //[-------------------------------------------------------] 00156 //[ Public functions ] 00157 //[-------------------------------------------------------] 00158 public: 00159 /** 00160 * @brief 00161 * Constructor 00162 * 00163 * @param[in] pParent 00164 * Pointer to the parent widget 00165 * @param[in] bManaged 00166 * If 'true', the widget is not automatically destroyed by Gui and will not appear in the list of top-level windows 00167 * 00168 * @remarks 00169 * If pParent == nullptr, the root widget of the system GUI is used as parent widget 00170 */ 00171 PLGUI_API Widget(Widget *pParent = nullptr, bool bManaged = false); 00172 00173 /** 00174 * @brief 00175 * Constructor 00176 * 00177 * @param[in] nNativeWindowHandle 00178 * System native window handle 00179 * 00180 * @remarks 00181 * This constructor can be used to wrap an already existing system window into a PLGui Widget, 00182 * there you need to pass a valid system handle for the window being wrapped. This only works 00183 * with the system GUI, which is being used automatically. 00184 */ 00185 PLGUI_API Widget(PLCore::handle nNativeWindowHandle); 00186 00187 /** 00188 * @brief 00189 * Destructor 00190 */ 00191 PLGUI_API virtual ~Widget(); 00192 00193 /** 00194 * @brief 00195 * Get owner GUI 00196 * 00197 * @return 00198 * Pointer to GUI object 00199 */ 00200 PLGUI_API Gui *GetGui() const; 00201 00202 /** 00203 * @brief 00204 * Get implementation 00205 * 00206 * @return 00207 * Pointer to platform specific implementation 00208 */ 00209 PLGUI_API WidgetImpl *GetImpl() const; 00210 00211 /** 00212 * @brief 00213 * Get system native window handle 00214 * 00215 * @return 00216 * Native window handle 00217 */ 00218 PLGUI_API PLCore::handle GetNativeWindowHandle() const; 00219 00220 //[-------------------------------------------------------] 00221 //[ Widget information ] 00222 //[-------------------------------------------------------] 00223 /** 00224 * @brief 00225 * Get ID 00226 * 00227 * @return 00228 * Widget ID 00229 */ 00230 PLGUI_API PLCore::uint32 GetID() const; 00231 00232 /** 00233 * @brief 00234 * Set ID 00235 * 00236 * @param[in] nID 00237 * Widget ID 00238 */ 00239 PLGUI_API void SetID(PLCore::uint32 nID); 00240 00241 /** 00242 * @brief 00243 * Get name 00244 * 00245 * @return 00246 * Widget name 00247 */ 00248 PLGUI_API PLCore::String GetName() const; 00249 00250 /** 00251 * @brief 00252 * Set name 00253 * 00254 * @param[in] sName 00255 * Widget name 00256 */ 00257 PLGUI_API void SetName(const PLCore::String &sName); 00258 00259 /** 00260 * @brief 00261 * Get descriptor 00262 * 00263 * @return 00264 * Descriptor for widget (Name, ID or window handle) 00265 * 00266 * @remarks 00267 * This functions returns a readable descriptor for the widget, which is 00268 * either the name (if a name has been set), the ID (if set) or the window 00269 * handle if all of the previous mentioned weren't available. 00270 * Use this function e.g. to output a widget descriptor in debug messages. 00271 */ 00272 PLGUI_API PLCore::String GetDescriptor() const; 00273 00274 /** 00275 * @brief 00276 * Get user defined data 00277 * 00278 * @return 00279 * User data 00280 */ 00281 PLGUI_API void *GetUserData() const; 00282 00283 /** 00284 * @brief 00285 * Set user defined data 00286 * 00287 * @param[in] pData 00288 * User data 00289 */ 00290 PLGUI_API void SetUserData(void *pData); 00291 00292 /** 00293 * @brief 00294 * Get whether or not the widget is managed 00295 * 00296 * @return 00297 * 'true' if the widget is managed, else 'false' 00298 */ 00299 PLGUI_API bool IsManaged() const; 00300 00301 //[-------------------------------------------------------] 00302 //[ Appearance (title, icon etc.) ] 00303 //[-------------------------------------------------------] 00304 /** 00305 * @brief 00306 * Get title 00307 * 00308 * @return 00309 * Widget title 00310 */ 00311 PLGUI_API PLCore::String GetTitle() const; 00312 00313 /** 00314 * @brief 00315 * Set title 00316 * 00317 * @param[in] sTitle 00318 * Widget title 00319 */ 00320 PLGUI_API void SetTitle(const PLCore::String &sTitle); 00321 00322 /** 00323 * @brief 00324 * Get icon 00325 * 00326 * @return 00327 * Image of window icon 00328 */ 00329 PLGUI_API const Image &GetIcon() const; 00330 00331 /** 00332 * @brief 00333 * Set icon 00334 * 00335 * @param[in] cIcon 00336 * Image of window icon 00337 */ 00338 PLGUI_API void SetIcon(const Image &cIcon); 00339 00340 /** 00341 * @brief 00342 * Get cursor 00343 * 00344 * @return 00345 * Mouse cursor 00346 */ 00347 PLGUI_API const Cursor &GetCursor() const; 00348 00349 /** 00350 * @brief 00351 * Set cursor 00352 * 00353 * @param[in] cCursor 00354 * Mouse cursor 00355 */ 00356 PLGUI_API void SetCursor(const Cursor &cCursor); 00357 00358 //[-------------------------------------------------------] 00359 //[ Hierarchy ] 00360 //[-------------------------------------------------------] 00361 /** 00362 * @brief 00363 * Get parent widget 00364 * 00365 * @return 00366 * Parent widget, can be a null pointer 00367 */ 00368 PLGUI_API Widget *GetParent() const; 00369 00370 /** 00371 * @brief 00372 * Get common parent of this and another widget 00373 * 00374 * @param[in] cWidget 00375 * The other widget 00376 * 00377 * @return 00378 * The first widget that is parent of both widgets, or a null pointer if there is none 00379 */ 00380 PLGUI_API Widget *GetCommonParent(const Widget &cWidget) const; 00381 00382 /** 00383 * @brief 00384 * Get top level widget that is parent of this widget 00385 * 00386 * @return 00387 * The top level parent widget, can be this widget 00388 */ 00389 PLGUI_API Widget *GetTopLevelWidget() const; 00390 00391 /** 00392 * @brief 00393 * Get content widget 00394 * 00395 * @return 00396 * Content widget 00397 * 00398 * @remarks 00399 * If a widget is a container for other widgets, a content widget is often used as the parent for all of 00400 * the child widgets. This is e.g. necessary to separate the "outside" from the "inside", e.g. there may be 00401 * other (internal) child widgets, that are also children of the same parent (e.g. buttons in the title bar or 00402 * frame widgets). So if you want to insert widgets inside other widgets, you should use the widget return by 00403 * GetContentWidget() as the parent widget, not the widget itself. If a widget don't have a content widget, 00404 * it will return a pointer to itself as the content widget. 00405 */ 00406 PLGUI_API virtual Widget *GetContentWidget() const; 00407 00408 /** 00409 * @brief 00410 * Get list of children 00411 * 00412 * @return 00413 * List of child widgets 00414 */ 00415 PLGUI_API const PLCore::List<Widget*> &GetChildren() const; 00416 00417 /** 00418 * @brief 00419 * Get first child widget 00420 * 00421 * @return 00422 * Child widget, or a null pointer 00423 */ 00424 PLGUI_API Widget *GetFirstChild() const; 00425 00426 /** 00427 * @brief 00428 * Get last child widget 00429 * 00430 * @return 00431 * Child widget, or a null pointer 00432 */ 00433 PLGUI_API Widget *GetLastChild() const; 00434 00435 /** 00436 * @brief 00437 * Get previous sibling widget 00438 * 00439 * @return 00440 * Sibling widget, or a null pointer 00441 */ 00442 PLGUI_API Widget *GetPreviousSibling() const; 00443 00444 /** 00445 * @brief 00446 * Get next sibling widget 00447 * 00448 * @return 00449 * Sibling widget, or a null pointer 00450 */ 00451 PLGUI_API Widget *GetNextSibling() const; 00452 00453 /** 00454 * @brief 00455 * Check if widget is a top level window 00456 * 00457 * @return 00458 * 'true' if the widget is a top level window (has no other parent than the desktop) 00459 */ 00460 PLGUI_API bool IsTopLevel() const; 00461 00462 //[-------------------------------------------------------] 00463 //[ Position and appearance ] 00464 //[-------------------------------------------------------] 00465 /** 00466 * @brief 00467 * Check if widget is visible in the taskbar 00468 * 00469 * @return 00470 * 'true' if the widget is visible in the taskbar, else 'false' 00471 * 00472 * @note 00473 * - If the system doesn't support a taskbar, the function will always return 'false' 00474 */ 00475 PLGUI_API bool IsShowInTaskbar() const; 00476 00477 /** 00478 * @brief 00479 * Set if widget is visible in the taskbar 00480 * 00481 * @param[in] bShowInTaskbar 00482 * 'true' if the widget is visible in the taskbar, else 'false' 00483 * 00484 * @see 00485 * - IsShowInTaskbar() 00486 */ 00487 PLGUI_API void SetShowInTaskbar(bool bShowInTaskbar); 00488 00489 /** 00490 * @brief 00491 * Get screen the widget is on 00492 * 00493 * @return 00494 * Pointer to the screen that contains this widget 00495 */ 00496 PLGUI_API Screen *GetScreen() const; 00497 00498 /** 00499 * @brief 00500 * Move widget to another screen 00501 * 00502 * @param[in] cScreen 00503 * Screen to which the widget shall be moved 00504 */ 00505 PLGUI_API void MoveToScreen(Screen &cScreen); 00506 00507 /** 00508 * @brief 00509 * Get widget position 00510 * 00511 * @return 00512 * Position (X, Y) 00513 */ 00514 PLGUI_API PLMath::Vector2i GetPos() const; 00515 00516 /** 00517 * @brief 00518 * Set widget position 00519 * 00520 * @param[in] vPos 00521 * Position (X, Y) 00522 */ 00523 PLGUI_API void SetPos(const PLMath::Vector2i &vPos); 00524 00525 /** 00526 * @brief 00527 * Get widget size 00528 * 00529 * @return 00530 * Size (width, height) 00531 */ 00532 PLGUI_API PLMath::Vector2i GetSize() const; 00533 00534 /** 00535 * @brief 00536 * Set widget size 00537 * 00538 * @param[in] vSize 00539 * Size (width, height) 00540 */ 00541 PLGUI_API void SetSize(const PLMath::Vector2i &vSize); 00542 00543 /** 00544 * @brief 00545 * Check if widget is topmost (always above all other widgets) 00546 * 00547 * @return 00548 * 'true' if the widget is topmost, else 'false' 00549 */ 00550 PLGUI_API bool GetTopmost() const; 00551 00552 /** 00553 * @brief 00554 * Set if widget is topmost (always above all other widgets) 00555 * 00556 * @param[in] bTopmost 00557 * 'true' if the widget is topmost, else 'false' 00558 * 00559 * @note 00560 * - Whenever possible, do not use topmost, this may backfire when you don't expect it 00561 */ 00562 PLGUI_API void SetTopmost(bool bTopmost); 00563 00564 /** 00565 * @brief 00566 * Get absolute widget position 00567 * 00568 * @return 00569 * Position (X, Y) 00570 */ 00571 PLGUI_API PLMath::Vector2i GetAbsPos() const; 00572 00573 /** 00574 * @brief 00575 * Get position relative to another widget 00576 * 00577 * @param[in] cWidget 00578 * Widget to which the relative position shall be computed 00579 * 00580 * @return 00581 * Position relative to the given widget (X, Y) 00582 */ 00583 PLGUI_API PLMath::Vector2i GetRelativePos(Widget &cWidget) const; 00584 00585 /** 00586 * @brief 00587 * Center widget 00588 * 00589 * @param[in] nCenter 00590 * How to center the widget (see ECenter) 00591 */ 00592 PLGUI_API void Center(ECenter nCenter); 00593 00594 /** 00595 * @brief 00596 * Center widget relative to the screen 00597 * 00598 * @param[in] cScreen 00599 * Screen to which this widget is centered 00600 */ 00601 PLGUI_API void CenterOnScreen(Screen &cScreen); 00602 00603 /** 00604 * @brief 00605 * Center widget relative to another widget 00606 * 00607 * @param[in] cWidget 00608 * Widget to which this widget is centered 00609 */ 00610 PLGUI_API void CenterOnWidget(Widget &cWidget); 00611 00612 /** 00613 * @brief 00614 * Calculate preferred size 00615 * 00616 * @param[in] vRefSize 00617 * Precalculated reference size, can be (-1, -1) if no reference size is available 00618 * 00619 * @remarks 00620 * This causes the widget to calculate it's preferred size by calling the 00621 * virtual function OnPreferredSize() and stores the result. 00622 * To retrieve the preferred size of a widget, call GetPreferredSize(). 00623 */ 00624 PLGUI_API void CalculatePreferredSize(const PLMath::Vector2i &vRefSize = PLMath::Vector2i(-1, -1)); 00625 00626 /** 00627 * @brief 00628 * Get preferred size 00629 * 00630 * @return 00631 * Preferred size 00632 * 00633 * @remarks 00634 * This return the preferred size of a widget. If the widget does not do it itself (which it should), 00635 * you have to call CalculatePreferredSize(), in order to calculate the preferred size before retrieving it. 00636 */ 00637 PLGUI_API PLMath::Vector2i GetPreferredSize() const; 00638 00639 /** 00640 * @brief 00641 * Set size of widget to fit it's content 00642 * 00643 * @remarks 00644 * This sets the widget's size to the preferred size (see CalculatePreferredSize()) 00645 */ 00646 PLGUI_API void FitSize(); 00647 00648 /** 00649 * @brief 00650 * Set Z position 00651 * 00652 * @param[in] nZPos 00653 * Z position (see EZPos) 00654 * @param[in] pWidget 00655 * Other widget used to align relative to (only matters for 'ZAbove' or 'ZBehind') 00656 */ 00657 PLGUI_API void SetZPos(EZPos nZPos, Widget *pWidget = nullptr); 00658 00659 /** 00660 * @brief 00661 * Get window state 00662 * 00663 * @return 00664 * Window state (see EWindowState) 00665 */ 00666 PLGUI_API EWindowState GetWindowState() const; 00667 00668 /** 00669 * @brief 00670 * Set window state 00671 * 00672 * @param[in] nWindowState 00673 * Window state (see EWindowState) 00674 */ 00675 PLGUI_API void SetWindowState(EWindowState nWindowState); 00676 00677 /** 00678 * @brief 00679 * Get background color 00680 * 00681 * @return 00682 * Background color 00683 * 00684 * @see 00685 * SetBackgroundColor() 00686 */ 00687 PLGUI_API PLGraphics::Color4 GetBackgroundColor() const; 00688 00689 /** 00690 * @brief 00691 * Set background color 00692 * 00693 * @param[in] cColor 00694 * Background color 00695 * 00696 * @remarks 00697 * The background color is used to automatically fill the background of the widget whenever 00698 * the background is painted. If you don't want a background to be painted or if you 00699 * paint it yourself (see OnDrawBackground), set this color to Color4::Transparent. 00700 */ 00701 PLGUI_API void SetBackgroundColor(const PLGraphics::Color4 &cColor); 00702 00703 /** 00704 * @brief 00705 * Set transparency mode 00706 * 00707 * @param[in] nTransparency 00708 * Transparency mode (see ETransparency) 00709 * @param[in] cColor 00710 * If nMode is ColorKey, all pixels of the specified color will be transparent. 00711 * If nMode is Alpha, only the alpha channel of the color will be used (1.0 = opaque, 0.0 = transparent) 00712 */ 00713 PLGUI_API void SetTransparency(ETransparency nTransparency, const PLGraphics::Color4 &cColor); 00714 00715 //[-------------------------------------------------------] 00716 //[ State ] 00717 //[-------------------------------------------------------] 00718 /** 00719 * @brief 00720 * Close widget 00721 * 00722 * @remarks 00723 * "Closing a widget" means sending it a message, that it shall close. This message is sent 00724 * automatically if you press the 'X'-Button or e.g. with "ALT+F4" on Windows. The default 00725 * behavior of widgets is: nothing. The default behavior of windows is: destroying the window. 00726 * You can control the behavior by overriding OnClose() or hooking into SignalClose. 00727 */ 00728 PLGUI_API void Close(); 00729 00730 /** 00731 * @brief 00732 * Check if widget has been destroyed 00733 * 00734 * @return 00735 * 'true' if the widget is destroyed, else 'false' 00736 */ 00737 PLGUI_API bool IsDestroyed() const; 00738 00739 /** 00740 * @brief 00741 * Destroy widget 00742 */ 00743 PLGUI_API void Destroy(); 00744 00745 /** 00746 * @brief 00747 * Check if widget is visible 00748 * 00749 * @return 00750 * 'true' if the widget is visible, else 'false' 00751 */ 00752 PLGUI_API bool IsVisible() const; 00753 00754 /** 00755 * @brief 00756 * Show or hide widget 00757 * 00758 * @param[in] bVisible 00759 * 'true' shows the widget, 'false' hides it 00760 * 00761 * @note 00762 * - When a widget is created, it is invisible by default 00763 */ 00764 PLGUI_API void SetVisible(bool bVisible); 00765 00766 /** 00767 * @brief 00768 * Check if widget is enabled 00769 * 00770 * @return 00771 * 'true' if the widget is enabled, else 'false' 00772 */ 00773 PLGUI_API bool IsEnabled() const; 00774 00775 /** 00776 * @brief 00777 * Enable or disable widget 00778 * 00779 * @param[in] bEnabled 00780 * 'true' if the widget is enabled, else 'false' 00781 */ 00782 PLGUI_API void SetEnabled(bool bEnabled); 00783 00784 /** 00785 * @brief 00786 * Get focus style 00787 * 00788 * @return 00789 * Focus style(s) 00790 */ 00791 PLGUI_API EFocusStyle GetFocusStyle() const; 00792 00793 /** 00794 * @brief 00795 * Set focus style 00796 * 00797 * @param[in] nFocusStyle 00798 * Focus style(s) 00799 * 00800 * @remarks 00801 * The focus style determines how a widget is able to get the focus. 00802 * If this is set to NoFocus (as by default), a widget will never get the focus. 00803 * See EFocusStyle for other possible values. 00804 */ 00805 PLGUI_API void SetFocusStyle(EFocusStyle nFocusStyle); 00806 00807 /** 00808 * @brief 00809 * Check if widget can accept the focus 00810 * 00811 * @return 00812 * 'true' if widget can get the focus, else 'false' 00813 * 00814 * @remarks 00815 * Returns 'true' if the focus style is set to AcceptFocus, ChildFocus or ChildFocusOrSelf 00816 * and the widget is not disabled. 00817 */ 00818 PLGUI_API bool CanAcceptFocus() const; 00819 00820 /** 00821 * @brief 00822 * Get tab-stop 00823 * 00824 * @return 00825 * 'true' if widget can get the focus by tabbing, else 'false' 00826 */ 00827 PLGUI_API bool IsTabStop(); 00828 00829 /** 00830 * @brief 00831 * Set tab-stop 00832 * 00833 * @param[in] bTabStop 00834 * 'true' if widget can get the focus by tabbing, else 'false' 00835 */ 00836 PLGUI_API void SetTabStop(bool bTabStop); 00837 00838 /** 00839 * @brief 00840 * Check if widget has the focus 00841 * 00842 * @return 00843 * 'true' if this widget has the focus, else 'false' 00844 */ 00845 PLGUI_API bool HasFocus() const; 00846 00847 /** 00848 * @brief 00849 * Set keyboard focus to the widget 00850 * 00851 * @return 00852 * 'true' if keyboard focus is accepted by this widget or one of it's child widgets, else 'false' 00853 * 00854 * @remarks 00855 * This function should be called by a GUI backend in order to set the keyboard focus 00856 * to this widget. The widget will then decide on base of it's parameter, if it accepts 00857 * the keyboard focus, or if it delegates it to a child widget. It will then call 00858 * SetFocus() from the backend, to finally set the focus. So don't call this function again 00859 * when receiving the event caused by SetFocus(), otherwise it will end in an endless loop. 00860 */ 00861 PLGUI_API bool SetFocus(); 00862 00863 /** 00864 * @brief 00865 * Check if widget is active (either the widget or one of it's children has the focus) 00866 * 00867 * @return 00868 * 'true' if this widget is active, else 'false' 00869 */ 00870 PLGUI_API bool IsActive() const; 00871 00872 /** 00873 * @brief 00874 * Activate a widget (bring it to the top and set the focus to it) 00875 */ 00876 PLGUI_API void Activate(); 00877 00878 /** 00879 * @brief 00880 * Give keyboard focus to next tab-stop widget 00881 * 00882 * @param[in] bForward 00883 * 'true' to go forward, 'false' to go backwards 00884 * 00885 * @return 00886 * 'true' if a tab-stop widget could be found, else 'false' 00887 */ 00888 PLGUI_API bool NextTabStop(bool bForward); 00889 00890 /** 00891 * @brief 00892 * Check if the mouse is currently inside the widget 00893 * 00894 * @return 00895 * 'true' if this widget is the mouse-over widget, else 'false' 00896 */ 00897 PLGUI_API bool IsMouseIn() const; 00898 00899 /** 00900 * @brief 00901 * Check if the mouse is currently over either the widget or one of it's child widgets 00902 * 00903 * @return 00904 * 'true' if mouse-over, else 'false' 00905 */ 00906 PLGUI_API bool IsMouseOver() const; 00907 00908 /** 00909 * @brief 00910 * Get current mouse cursor position inside the widget 00911 * 00912 * @param[out] vPos 00913 * Receives the mouse cursor position if all went fine, on error, the given variable is not manipulated 00914 * 00915 * @return 00916 * 'true' if all went fine, else 'false' (maybe the mouse cursor is currently not over the widget?) 00917 */ 00918 PLGUI_API bool GetMousePos(PLMath::Vector2i &vPos) const; 00919 00920 /** 00921 * @brief 00922 * Get widget state 00923 * 00924 * @return 00925 * Widget states as flags (see EWidgetState) 00926 * 00927 * @remarks 00928 * This returns the current states of the widget together as a single flags-variable 00929 * containing a combination of the values defined by EWidgetState. Not that this virtual 00930 * function can be overwritten in derived classes to modify it's behavior according to 00931 * the widget or add new states (e.g. WidgetPressed for buttons) 00932 */ 00933 PLGUI_API virtual PLCore::uint32 GetWidgetState() const; 00934 00935 /** 00936 * @brief 00937 * Redraw widget 00938 */ 00939 PLGUI_API void Redraw(); 00940 00941 /** 00942 * @brief 00943 * Redraw widget and all child widgets 00944 */ 00945 PLGUI_API void RedrawAll(); 00946 00947 //[-------------------------------------------------------] 00948 //[ Input ] 00949 //[-------------------------------------------------------] 00950 /** 00951 * @brief 00952 * Check if widget has captured mouse input 00953 * 00954 * @return 00955 * 'true' if the mouse is captured by the widget, else 'false' 00956 */ 00957 PLGUI_API bool IsCaptureMouse() const; 00958 00959 /** 00960 * @brief 00961 * Capture mouse input 00962 * 00963 * @param[in] bCapture 00964 * 'true' if the mouse should be captured by the widget, else 'false' 00965 */ 00966 PLGUI_API void SetCaptureMouse(bool bCapture); 00967 00968 /** 00969 * @brief 00970 * Trap mouse inside the widget 00971 * 00972 * @param[in] bTrap 00973 * 'true' if the mouse should be trapped inside the widget, else 'false' 00974 */ 00975 PLGUI_API void SetTrapMouse(bool bTrap); 00976 00977 /** 00978 * @brief 00979 * Register a hotkey 00980 * 00981 * @param[in] nModKey 00982 * Modification key (for example PLGUIMOD_ALT) 00983 * @param[in] nKey 00984 * Key (for example PLGUIKEY_RETURN) 00985 * 00986 * @return 00987 * Hotkey ID, 0 on error 00988 */ 00989 PLGUI_API PLCore::uint32 RegisterHotkey(PLCore::uint32 nModKey, PLCore::uint32 nKey); 00990 00991 /** 00992 * @brief 00993 * Unregister a hotkey 00994 * 00995 * @param[in] nID 00996 * Hotkey ID 00997 */ 00998 PLGUI_API void UnregisterHotkey(PLCore::uint32 nID); 00999 01000 //[-------------------------------------------------------] 01001 //[ Theme ] 01002 //[-------------------------------------------------------] 01003 /** 01004 * @brief 01005 * Get theme 01006 * 01007 * @return 01008 * Pointer to current theme 01009 */ 01010 PLGUI_API Theme *GetTheme() const; 01011 01012 /** 01013 * @brief 01014 * Set theme 01015 * 01016 * @param[in] pTheme 01017 * Theme 01018 */ 01019 PLGUI_API void SetTheme(Theme *pTheme); 01020 01021 //[-------------------------------------------------------] 01022 //[ Modifiers ] 01023 //[-------------------------------------------------------] 01024 /** 01025 * @brief 01026 * Get modifiers 01027 * 01028 * @return 01029 * List of modifiers that belong to the widget 01030 */ 01031 PLGUI_API const PLCore::List<Modifier*> &GetModifiers() const; 01032 01033 /** 01034 * @brief 01035 * Get modifier 01036 * 01037 * @param[in] sName 01038 * Name of modifier 01039 * 01040 * @remarks 01041 * Modifier, or a null pointer if no modifier with that name exists 01042 */ 01043 PLGUI_API Modifier *GetModifier(const PLCore::String &sName) const; 01044 01045 /** 01046 * @brief 01047 * Add modifier 01048 * 01049 * @param[in] pModifier 01050 * Pointer to the new modifier 01051 * 01052 * @remarks 01053 * The widget will take over the modifier and also destroy it later 01054 */ 01055 PLGUI_API void AddModifier(Modifier *pModifier); 01056 01057 /** 01058 * @brief 01059 * Add modifier 01060 * 01061 * @param[in] sName 01062 * Name of modifier (can be empty) 01063 * @param[in] pModifier 01064 * Pointer to the new modifier 01065 * 01066 * @remarks 01067 * The widget will take over the modifier and also destroy it later. 01068 * The name of the modifier is optional and can be left empty, if a name is provided, it must be unique. 01069 * If a name is provided and there is already a modifier with the same name, the old modifier is 01070 * destroyed and replaced by the new one. 01071 */ 01072 PLGUI_API void AddModifier(const PLCore::String &sName, Modifier *pModifier); 01073 01074 /** 01075 * @brief 01076 * Add modifier 01077 * 01078 * @param[in] sClass 01079 * Name of the modifier class 01080 * @param[in] sOptions 01081 * Options for the modifier 01082 */ 01083 PLGUI_API void AddModifier(const PLCore::String &sClass, const PLCore::String &sOptions); 01084 01085 /** 01086 * @brief 01087 * Add modifier 01088 * 01089 * @param[in] sName 01090 * Name of modifier (can be empty) 01091 * @param[in] sClass 01092 * Name of the modifier class 01093 * @param[in] sOptions 01094 * Options for the modifier 01095 * 01096 * @remarks 01097 * The name of the modifier is optional and can be left empty, if a name is provided, it must be unique. 01098 * If a name is provided and there is already a modifier with the same name, the old modifier is 01099 * destroyed and replaced by the new one. 01100 */ 01101 PLGUI_API void AddModifier(const PLCore::String &sName, const PLCore::String &sClass, const PLCore::String &sOptions); 01102 01103 /** 01104 * @brief 01105 * Remove modifier 01106 * 01107 * @param[in] pModifier 01108 * Pointer to the modifier 01109 * 01110 * @remarks 01111 * The widget will remove and delete the modifier 01112 */ 01113 PLGUI_API void RemoveModifier(Modifier *pModifier); 01114 01115 /** 01116 * @brief 01117 * Remove modifier 01118 * 01119 * @param[in] sName 01120 * Name of modifier 01121 * 01122 * @remarks 01123 * The widget will remove and delete the modifier 01124 */ 01125 PLGUI_API void RemoveModifier(const PLCore::String &sName); 01126 01127 //[-------------------------------------------------------] 01128 //[ Layout ] 01129 //[-------------------------------------------------------] 01130 /** 01131 * @brief 01132 * Get layout 01133 * 01134 * @return 01135 * Layout 01136 * 01137 * @remarks 01138 * As a layout is just a modifier, this is equal to GetModifier("Layout") 01139 */ 01140 PLGUI_API Layout *GetLayout() const; 01141 01142 /** 01143 * @brief 01144 * Set layout 01145 * 01146 * @param[in] pLayout 01147 * Layout 01148 */ 01149 PLGUI_API void SetLayout(Layout *pLayout); 01150 01151 /** 01152 * @brief 01153 * Set layout 01154 * 01155 * @param[in] sClass 01156 * Layout class 01157 * @param[in] sOptions 01158 * Layout options 01159 */ 01160 PLGUI_API void SetLayout(const PLCore::String &sClass, const PLCore::String &sOptions); 01161 01162 /** 01163 * @brief 01164 * Get layout hints 01165 * 01166 * @remarks 01167 * For widgets that are positioned by a layout manager, additional hints can be set for the layout 01168 * manager on how to layout the specific widget. These options include e.g. the minimum and maximum 01169 * size, hints on when and how to resize the widget etc. Note that it depends on the layout manager, 01170 * which (if any) of the layout hints it uses to modify the layout behavior. 01171 */ 01172 PLGUI_API LayoutHints &GetLayoutHints(); 01173 01174 /** 01175 * @brief 01176 * Adjust content of the widget 01177 */ 01178 PLGUI_API void AdjustContent(); 01179 01180 /** 01181 * @brief 01182 * Update content 01183 * 01184 * @remarks 01185 * This function has to be called by a widget whenever it has been changed 01186 * in a way that could alter it's appearance or size. E.G. if the text of a label 01187 * has been altered, it will most certainly change the size of the text label on 01188 * the screen. To indicate this, the widget has to call UpdateContent() after such a 01189 * change, so that the layout of the parent widget can be updated accordingly. 01190 */ 01191 PLGUI_API void UpdateContent(); 01192 01193 01194 //[-------------------------------------------------------] 01195 //[ Protected functions ] 01196 //[-------------------------------------------------------] 01197 protected: 01198 /** 01199 * @brief 01200 * Constructor 01201 * 01202 * @param[in] pGui 01203 * Pointer to the parent GUI 01204 * 01205 * @remarks 01206 * This create a dummy widget for the 'root' of a GUI. This widget is not a real widget, so 01207 * don't call anything that would need a real widget backend to be present. It is only used 01208 * to server as a parent for new widgets and should not be used for anything else. Also note 01209 * that if you pass a root widget as parent, it will be used to obtain the GUI pointer but 01210 * than be discarded (afterwards, GetParent() of the new widget will return a null pointer) 01211 */ 01212 PLGUI_API Widget(Gui *pGui); 01213 01214 /** 01215 * @brief 01216 * Add child widget 01217 * 01218 * @param[in] pWidget 01219 * Widget to add 01220 */ 01221 PLGUI_API void AddChild(Widget *pWidget); 01222 01223 /** 01224 * @brief 01225 * Remove child widget 01226 * 01227 * @param[in] pWidget 01228 * Widget to remove 01229 */ 01230 PLGUI_API void RemoveChild(Widget *pWidget); 01231 01232 /** 01233 * @brief 01234 * Give focus to first tab-stop widget (including this and all children) 01235 * 01236 * @return 01237 * 'true' if a tab-stop widget could be found, else 'false' 01238 */ 01239 PLGUI_API bool ActivateFirstTabStop(); 01240 01241 /** 01242 * @brief 01243 * Give focus to last tab-stop widget (including this and all children) 01244 * 01245 * @return 01246 * 'true' if a tab-stop widget could be found, else 'false' 01247 */ 01248 PLGUI_API bool ActivateLastTabStop(); 01249 01250 /** 01251 * @brief 01252 * Draw background 01253 * 01254 * @param[in] cGraphics 01255 * Graphics object used for painting 01256 */ 01257 PLGUI_API void DrawBackground(Graphics &cGraphics); 01258 01259 /** 01260 * @brief 01261 * Draw widget 01262 * 01263 * @param[in] cGraphics 01264 * Graphics object used for painting 01265 */ 01266 PLGUI_API void Draw(Graphics &cGraphics); 01267 01268 01269 //[-------------------------------------------------------] 01270 //[ Protected virtual WidgetFunctions functions ] 01271 //[-------------------------------------------------------] 01272 protected: 01273 PLGUI_API virtual void OnMessage(const GuiMessage &cMessage) override; 01274 PLGUI_API virtual PLMath::Vector2i OnPreferredSize(const PLMath::Vector2i &vRefSize) const override; 01275 PLGUI_API virtual void OnThemeChanged() override; 01276 PLGUI_API virtual void OnUpdateContent() override; 01277 PLGUI_API virtual void OnAdjustContent() override; 01278 01279 01280 //[-------------------------------------------------------] 01281 //[ Protected data ] 01282 //[-------------------------------------------------------] 01283 protected: 01284 Gui *m_pGui; /**< Pointer to GUI instance */ 01285 bool m_bManaged; /**< If a widget is managed, it will not be listed in the list of top level widgets and not be deleted automatically! */ 01286 bool m_bRootWidget; /**< If 'true', the widget is a dummy object for the 'root' of a GUI implementation (no real widget at all!) */ 01287 PLCore::uint32 m_nID; /**< Widget ID */ 01288 PLCore::String m_sName; /**< Widget name */ 01289 Widget *m_pParent; /**< Pointer to parent widget */ 01290 WidgetImpl *m_pWidgetImpl; /**< Widget implementation */ 01291 Theme *m_pTheme; /**< Current theme */ 01292 PLCore::List<Widget*> m_lstChildren; /**< List of child widgets */ 01293 PLCore::List<Modifier*> m_lstModifiers; /**< List of modifiers */ 01294 PLCore::HashMap<PLCore::String, Modifier*> m_mapModifiers; /**< Map 'Name' -> 'Modifier' */ 01295 Layout *m_pLayout; /**< Layout */ 01296 LayoutHints m_cLayoutHints; /**< Layout hints for the widget */ 01297 EWindowState m_nWindowState; /**< Current window state */ 01298 PLMath::Vector2i m_vPos; /**< Position of the widget */ 01299 PLMath::Vector2i m_vSize; /**< Size of the widget */ 01300 bool m_bTopmost; /**< Topmost flag */ 01301 PLCore::String m_sTitle; /**< Widget title */ 01302 Image m_cIcon; /**< Widget icon */ 01303 Cursor m_cCursor; /**< Mouse cursor */ 01304 EFocusStyle m_nFocusStyle; /**< How does this widget accept the keyboard focus? */ 01305 bool m_bTabStop; /**< Does the widget accept the focus by tabbing? */ 01306 bool m_bCaptureMouse; /**< Is the mouse captured by the widget? */ 01307 PLGraphics::Color4 m_cBackgroundColor; /**< Background color of the widget */ 01308 PLMath::Vector2i m_vPreferredSize; /**< Preferred size of the widget */ 01309 void *m_pUserData; /**< User defined data */ 01310 01311 01312 }; 01313 01314 01315 //[-------------------------------------------------------] 01316 //[ Namespace ] 01317 //[-------------------------------------------------------] 01318 } // PLGui 01319 01320 01321 #endif // __PLGUI_WIDGET_H__
|