1 /* 2 * This source file is part of libRocket, the HTML/CSS Interface Middleware 3 * 4 * For the latest information, see http://www.librocket.com 5 * 6 * Copyright (c) 2008-2010 CodePoint Ltd, Shift Technology Ltd 7 * 8 * Permission is hereby granted, free of charge, to any person obtaining a copy 9 * of this software and associated documentation files (the "Software"), to deal 10 * in the Software without restriction, including without limitation the rights 11 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 12 * copies of the Software, and to permit persons to whom the Software is 13 * furnished to do so, subject to the following conditions: 14 * 15 * The above copyright notice and this permission notice shall be included in 16 * all copies or substantial portions of the Software. 17 * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 23 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 24 * THE SOFTWARE. 25 * 26 */ 27 28 #ifndef ROCKETCOREELEMENT_H 29 #define ROCKETCOREELEMENT_H 30 31 #include "ReferenceCountable.h" 32 #include "ScriptInterface.h" 33 #include "ValueReference.h" 34 #include "Header.h" 35 #include "Box.h" 36 #include "Event.h" 37 #include "Property.h" 38 #include "Types.h" 39 40 #include <memory> 41 42 namespace Rocket { 43 namespace Core { 44 class Dictionary; 45 } 46 } 47 48 namespace Rocket { 49 namespace Core { 50 51 class Context; 52 class Decorator; 53 class ElementInstancer; 54 class EventDispatcher; 55 class EventListener; 56 class ElementBackground; 57 class ElementBorder; 58 class ElementDecoration; 59 class ElementDefinition; 60 class ElementDocument; 61 class ElementScroll; 62 class ElementStyle; 63 class FontFaceHandle; 64 class PropertyDictionary; 65 class RenderInterface; 66 class StyleSheet; 67 68 /** 69 A generic element in the DOM tree. 70 71 @author Peter Curry 72 */ 73 74 class ROCKETCORE_API Element : public ScriptInterface 75 { 76 public: 77 /// Constructs a new libRocket element. This should not be called directly; use the Factory 78 /// instead. 79 /// @param[in] tag The tag the element was declared as in RML. 80 Element(const String& tag); 81 virtual ~Element(); 82 83 void Update(); 84 void Render(); 85 86 /// Clones this element, returning a new, unparented element. 87 Element* Clone() const; 88 89 /** @name Classes 90 */ 91 //@{ 92 /// Sets or removes a class on the element. 93 /// @param[in] class_name The name of the class to add or remove from the class list. 94 /// @param[in] activate True if the class is to be added, false to be removed. 95 void SetClass(const String& class_name, bool activate); 96 /// Checks if a class is set on the element. 97 /// @param[in] class_name The name of the class to check for. 98 /// @return True if the class is set on the element, false otherwise. 99 bool IsClassSet(const String& class_name) const; 100 /// Specifies the entire list of classes for this element. This will replace any others specified. 101 /// @param[in] class_names The list of class names to set on the style, separated by spaces. 102 void SetClassNames(const String& class_names); 103 /// Return the active class list. 104 /// @return The space-separated list of classes active on the element. 105 String GetClassNames() const; 106 //@} 107 108 /// Returns the active style sheet for this element. This may be NULL. 109 /// @return The element's style sheet. 110 virtual StyleSheet* GetStyleSheet() const; 111 112 /// Returns the element's definition, updating if necessary. 113 /// @return The element's definition. 114 const ElementDefinition* GetDefinition(); 115 116 /// Fills a string with the full address of this element. 117 /// @param[in] include_pseudo_classes True if the address is to include the pseudo-classes of the leaf element. 118 /// @return The address of the element, including its full parentage. 119 String GetAddress(bool include_pseudo_classes = false) const; 120 121 /// Sets the position of this element, as a two-dimensional offset from another element. 122 /// @param[in] offset The offset (in pixels) of our primary box's top-left border corner from our offset parent's top-left border corner. 123 /// @param[in] offset_parent The element this element is being positioned relative to. 124 /// @param[in] offset_fixed True if the element is fixed in place (and will not scroll), false if not. 125 void SetOffset(const Vector2f& offset, Element* offset_parent, bool offset_fixed = false); 126 /// Returns the position of the top-left corner of one of the areas of this element's primary box, relative to its 127 /// offset parent's top-left border corner. 128 /// @param[in] area The desired area position. 129 /// @return The relative offset. 130 Vector2f GetRelativeOffset(Box::Area area = Box::CONTENT); 131 /// Returns the position of the top-left corner of one of the areas of this element's primary box, relative to 132 /// the element root. 133 /// @param[in] area The desired area position. 134 /// @return The absolute offset. 135 Vector2f GetAbsoluteOffset(Box::Area area = Box::CONTENT); 136 137 /// Sets an alternate area to use as the client area. 138 /// @param[in] client_area The box area to use as the element's client area. 139 void SetClientArea(Box::Area client_area); 140 /// Returns the area the element uses as its client area. 141 /// @return The box area used as the element's client area. 142 Box::Area GetClientArea() const; 143 144 /// Sets the dimensions of the element's internal content. This is the tightest fitting box surrounding all of 145 /// this element's logical children, plus the element's padding. 146 /// @param[in] content_offset The offset of the box's internal content. 147 /// @param[in] content_box The dimensions of the box's internal content. 148 void SetContentBox(const Vector2f& content_offset, const Vector2f& content_box); 149 /// Sets the box describing the size of the element, and removes all others. 150 /// @param[in] box The new dimensions box for the element. 151 void SetBox(const Box& box); 152 /// Adds a box to the end of the list describing this element's geometry. 153 /// @param[in] box The auxiliary box for the element. 154 void AddBox(const Box& box); 155 /// Returns one of the boxes describing the size of the element. 156 /// @param[in] index The index of the desired box. If this is outside of the bounds of the element's list of boxes, it will be clamped. 157 /// @return The requested box. 158 const Box& GetBox(int index = 0); 159 /// Returns the number of boxes making up this element's geometry. 160 /// @return the number of boxes making up this element's geometry. 161 int GetNumBoxes(); 162 163 /// Returns the baseline of the element, in pixels offset from the bottom of the element's content area. 164 /// @return The element's baseline. A negative baseline will be further 'up' the element, a positive on further 'down'. The default element will return 0. 165 virtual float GetBaseline() const; 166 /// Gets the intrinsic dimensions of this element, if it is of a type that has an inherent size. This size will 167 /// only be overriden by a styled width or height. 168 /// @param[in] dimensions The dimensions to size, if appropriate. 169 /// @return True if the element has intrinsic dimensions, false otherwise. The default element will return false. 170 virtual bool GetIntrinsicDimensions(Vector2f& dimensions); 171 172 /// Checks if a given point in screen coordinates lies within the bordered area of this element. 173 /// @param[in] point The point to test. 174 /// @return True if the element is within this element, false otherwise. 175 virtual bool IsPointWithinElement(const Vector2f& point); 176 177 /// Returns the visibility of the element. 178 /// @return True if the element is visible, false otherwise. 179 bool IsVisible() const; 180 /// Returns the z-index of the element. 181 /// @return The element's z-index. 182 float GetZIndex() const; 183 184 /// Returns the element's font face handle. 185 /// @return The element's font face handle. 186 FontFaceHandle* GetFontFaceHandle() const; 187 188 /** @name Properties 189 */ 190 //@{ 191 /// Sets a local property override on the element. 192 /// @param[in] name The name of the new property. 193 /// @param[in] value The new property to set. 194 /// @return True if the property parsed successfully, false otherwise. 195 bool SetProperty(const String& name, const String& value); 196 /// Sets a local property override on the element to a pre-parsed value. 197 /// @param[in] name The name of the new property. 198 /// @param[in] property The parsed property to set. 199 /// @return True if the property was set successfully, false otherwise. 200 bool SetProperty(const String& name, const Property& property); 201 /// Removes a local property override on the element; its value will revert to that defined in 202 /// the style sheet. 203 /// @param[in] name The name of the local property definition to remove. 204 void RemoveProperty(const String& name); 205 /// Returns one of this element's properties. If this element is not defined this property, or a parent cannot 206 /// be found that we can inherit the property from, the default value will be returned. 207 /// @param[in] name The name of the property to fetch the value for. 208 /// @return The value of this property for this element, or NULL if no property exists with the given name. 209 const Property* GetProperty(const String& name); 210 /// Returns the values of one of this element's properties. 211 /// @param[in] name The name of the property to get. 212 /// @return The value of this property. 213 template < typename T > 214 T GetProperty(const String& name); 215 /// Returns one of this element's properties. If this element is not defined this property, NULL will be 216 /// returned. 217 /// @param[in] name The name of the property to fetch the value for. 218 /// @return The value of this property for this element, or NULL if this property has not been explicitly defined for this element. 219 const Property* GetLocalProperty(const String& name); 220 /// Resolves one of this element's properties. If the value is a number or px, this is returned. If it's a 221 /// percentage then it is resolved based on the second argument (the base value). 222 /// @param[in] name The name of the property to resolve the value for. 223 /// @param[in] base_value The value that is scaled by the percentage value, if it is a percentage. 224 /// @return The value of this property for this element. 225 float ResolveProperty(const String& name, float base_value); 226 /// Resolves one of this element's non-inherited properties. If the value is a number or px, this is returned. If it's a 227 /// percentage then it is resolved based on the second argument (the base value). 228 /// @param[in] name The property to resolve the value for. 229 /// @param[in] base_value The value that is scaled by the percentage value, if it is a percentage. 230 /// @return The value of this property for this element. 231 float ResolveProperty(const Property *property, float base_value); 232 233 /// Returns 'top', 'bottom', 'left' and 'right' properties from element's style or local cache. 234 void GetOffsetProperties(const Property **top, const Property **bottom, const Property **left, const Property **right ); 235 /// Returns 'border-width' properties from element's style or local cache. 236 void GetBorderWidthProperties(const Property **border_top_width, const Property **border_bottom_width, const Property **border_left_width, const Property **border_right_width); 237 /// Returns 'margin' properties from element's style or local cache. 238 void GetMarginProperties(const Property **margin_top, const Property **margin_bottom, const Property **margin_left, const Property **margin_right); 239 /// Returns 'padding' properties from element's style or local cache. 240 void GetPaddingProperties(const Property **padding_top, const Property **padding_bottom, const Property **padding_left, const Property **padding_right); 241 /// Returns 'width' and 'height' properties from element's style or local cache. 242 void GetDimensionProperties(const Property **width, const Property **height); 243 /// Returns local 'width' and 'height' properties from element's style or local cache, 244 /// ignoring default values. 245 void GetLocalDimensionProperties(const Property **width, const Property **height); 246 /// Returns 'overflow' properties' values from element's style or local cache. 247 void GetOverflow(int *overflow_x, int *overflow_y); 248 /// Returns 'position' property value from element's style or local cache. 249 int GetPosition(); 250 /// Returns 'float' property value from element's style or local cache. 251 int GetFloat(); 252 /// Returns 'display' property value from element's style or local cache. 253 int GetDisplay(); 254 /// Returns 'white-space' property value from element's style or local cache. 255 int GetWhitespace(); 256 257 /// Returns 'line-height' property value from element's style or local cache. 258 const Property *GetLineHeightProperty(); 259 /// Returns 'text-align' property value from element's style or local cache. 260 int GetTextAlign(); 261 /// Returns 'text-transform' property value from element's style or local cache. 262 int GetTextTransform(); 263 /// Returns 'vertical-align' property value from element's style or local cache. 264 const Property *GetVerticalAlignProperty(); 265 266 /// Iterates over the properties defined on this element. 267 /// @param[inout] index Index of the property to fetch. This is incremented to the next valid index after the fetch. Indices are not necessarily incremental. 268 /// @param[out] pseudo_classes The pseudo-classes the property is defined by. 269 /// @param[out] name The name of the property at the specified index. 270 /// @param[out] property The property at the specified index. 271 /// @return True if a property was successfully fetched. 272 bool IterateProperties(int& index, PseudoClassList& pseudo_classes, String& name, const Property*& property) const; 273 ///@} 274 275 /** @name Pseudo-classes 276 */ 277 //@{ 278 /// Sets or removes a pseudo-class on the element. 279 /// @param[in] pseudo_class The pseudo class to activate or deactivate. 280 /// @param[in] activate True if the pseudo-class is to be activated, false to be deactivated. 281 void SetPseudoClass(const String& pseudo_class, bool activate); 282 /// Checks if a specific pseudo-class has been set on the element. 283 /// @param[in] pseudo_class The name of the pseudo-class to check for. 284 /// @return True if the pseudo-class is set on the element, false if not. 285 bool IsPseudoClassSet(const String& pseudo_class) const; 286 /// Checks if a complete set of pseudo-classes are set on the element. 287 /// @param[in] pseudo_classes The set of pseudo-classes to check for. 288 /// @return True if all of the pseudo-classes are set, false if not. 289 bool ArePseudoClassesSet(const PseudoClassList& pseudo_classes) const; 290 /// Gets a list of the current active pseudo-classes. 291 /// @return The list of active pseudo-classes. 292 const PseudoClassList& GetActivePseudoClasses() const; 293 //@} 294 295 /** @name Attributes 296 */ 297 //@{ 298 /// Sets an attribute on the element. 299 /// @param[in] name Name of the attribute. 300 /// @param[in] value Value of the attribute. 301 template< typename T > 302 void SetAttribute(const String& name, const T& value); 303 /// Gets the specified attribute. 304 /// @param[in] name Name of the attribute to retrieve. 305 /// @return A variant representing the attribute, or NULL if the attribute doesn't exist. 306 Variant* GetAttribute(const String& name) const; 307 /// Gets the specified attribute, with default value. 308 /// @param[in] name Name of the attribute to retrieve. 309 /// @param[in] default_value Value to return if the attribute doesn't exist. 310 template< typename T > 311 T GetAttribute(const String& name, const T& default_value) const; 312 /// Checks if the element has a certain attribute. 313 /// @param[in] name The name of the attribute to check for. 314 /// @return True if the element has the given attribute, false if not. 315 bool HasAttribute(const String& name); 316 /// Removes the attribute from the element. 317 /// @param[in] name Name of the attribute. 318 void RemoveAttribute(const String& name); 319 /// Set a group of attributes. 320 /// @param[in] attributes Attributes to set. 321 void SetAttributes(const ElementAttributes* attributes); 322 /// Iterates over the attributes. 323 /// @param[inout] index Index to fetch. This is incremented after the fetch. 324 /// @param[out] name Name of the attribute at the specified index 325 /// @param[out] value Value of the attribute at the specified index. 326 /// @return True if an attribute was successfully fetched. 327 template< typename T > 328 bool IterateAttributes(int& index, String& name, T& value) const; 329 /// Returns the number of attributes on the element. 330 /// @return The number of attributes on the element. 331 int GetNumAttributes() const; 332 //@} 333 334 /** @name Decorators 335 */ 336 //@{ 337 /// Iterates over all decorators attached to the element. Note that all decorators are iterated 338 /// over, not just active ones. 339 /// @param[inout] index Index to fetch. This is incremented after the fetch. 340 /// @param[out] pseudo_classes The pseudo-classes the decorator required to be active before it renders. 341 /// @param[out] name The name of the decorator at the specified index. 342 /// @param[out] decorator The decorator at the specified index. 343 /// @param[out] decorator_data This element's handle to any data is has stored against the decorator. 344 /// @return True if a decorator was successfully fetched, false if not. 345 bool IterateDecorators(int& index, PseudoClassList& pseudo_classes, String& name, Decorator*& decorator, DecoratorDataHandle& decorator_data); 346 //@} 347 348 /// Gets the outer-most focus element down the tree from this node. 349 /// @return Outer-most focus element. 350 Element* GetFocusLeafNode(); 351 352 /// Returns the element's context. 353 /// @return The context this element's document exists within. 354 Context* GetContext(); 355 356 /** @name DOM Properties 357 */ 358 //@{ 359 360 /// Gets the name of the element. 361 /// @return The name of the element. 362 const String& GetTagName() const; 363 364 /// Gets the id of the element. 365 /// @return The element's id. 366 const String& GetId() const; 367 /// Sets the id of the element. 368 /// @param[in] id The new id of the element. 369 void SetId(const String& id); 370 371 /// Gets the horizontal offset from the context's left edge to element's left border edge. 372 /// @return The horizontal offset of the element within its context, in pixels. 373 float GetAbsoluteLeft(); 374 /// Gets the vertical offset from the context's top edge to element's top border edge. 375 /// @return The vertical offset of the element within its context, in pixels. 376 float GetAbsoluteTop(); 377 378 /// Gets the horizontal offset from the element's left border edge to the left edge of its client area. This is 379 /// usually the edge of the padding, but may be the content area for some replaced elements. 380 /// @return The horizontal offset of the element's client area, in pixels. 381 float GetClientLeft(); 382 /// Gets the vertical offset from the element's top border edge to the top edge of its client area. This is 383 /// usually the edge of the padding, but may be the content area for some replaced elements. 384 /// @return The vertical offset of the element's client area, in pixels. 385 float GetClientTop(); 386 /// Gets the width of the element's client area. This is usually the padded area less the vertical scrollbar 387 /// width, but may be the content area for some replaced elements. 388 /// @return The width of the element's client area, usually including padding but not the vertical scrollbar width, border or margin. 389 float GetClientWidth(); 390 /// Gets the height of the element's client area. This is usually the padded area less the horizontal scrollbar 391 /// height, but may be the content area for some replaced elements. 392 /// @return The inner height of the element, usually including padding but not the horizontal scrollbar height, border or margin. 393 float GetClientHeight(); 394 395 /// Returns the element from which all offset calculations are currently computed. 396 /// @return This element's offset parent. 397 Element* GetOffsetParent(); 398 /// Gets the distance from this element's left border to its offset parent's left border. 399 /// @return The horizontal distance (in pixels) from this element's offset parent to itself. 400 float GetOffsetLeft(); 401 /// Gets the distance from this element's top border to its offset parent's top border. 402 /// @return The vertical distance (in pixels) from this element's offset parent to itself. 403 float GetOffsetTop(); 404 /// Gets the width of the element, including the client area, padding, borders and scrollbars, but not margins. 405 /// @return The width of the rendered element, in pixels. 406 float GetOffsetWidth(); 407 /// Gets the height of the element, including the client area, padding, borders and scrollbars, but not margins. 408 /// @return The height of the rendered element, in pixels. 409 float GetOffsetHeight(); 410 411 /// Gets the left scroll offset of the element. 412 /// @return The element's left scroll offset. 413 float GetScrollLeft(); 414 /// Sets the left scroll offset of the element. 415 /// @param[in] scroll_left The element's new left scroll offset. 416 void SetScrollLeft(float scroll_left); 417 /// Gets the top scroll offset of the element. 418 /// @return The element's top scroll offset. 419 float GetScrollTop(); 420 /// Sets the top scroll offset of the element. 421 /// @param[in] scroll_top The element's new top scroll offset. 422 void SetScrollTop(float scroll_top); 423 /// Gets the width of the scrollable content of the element; it includes the element padding but not its margin. 424 /// @return The width (in pixels) of the of the scrollable content of the element. 425 float GetScrollWidth(); 426 /// Gets the height of the scrollable content of the element; it includes the element padding but not its margin. 427 /// @return The height (in pixels) of the of the scrollable content of the element. 428 float GetScrollHeight(); 429 430 /// Gets the object representing the declarations of an element's style attributes. 431 /// @return The element's style. 432 ElementStyle* GetStyle(); 433 434 /// Gets the document this element belongs to. 435 /// @return This element's document. 436 virtual ElementDocument* GetOwnerDocument(); 437 438 /// Gets this element's parent node. 439 /// @return This element's parent. 440 Element* GetParentNode() const; 441 442 /// Gets the element immediately following this one in the tree. 443 /// @return This element's next sibling element, or NULL if there is no sibling element. 444 Element* GetNextSibling() const; 445 /// Gets the element immediately preceding this one in the tree. 446 /// @return This element's previous sibling element, or NULL if there is no sibling element. 447 Element* GetPreviousSibling() const; 448 449 /// Returns the first child of this element. 450 /// @return This element's first child, or NULL if it contains no children. 451 Element* GetFirstChild() const; 452 /// Gets the last child of this element. 453 /// @return This element's last child, or NULL if it contains no children. 454 Element* GetLastChild() const; 455 /// Get the child element at the given index. 456 /// @param[in] index Index of child to get. 457 /// @return The child element at the given index. 458 Element* GetChild(int index) const; 459 /// Get the current number of children in this element 460 /// @param[in] include_non_dom_elements True if the caller wants to include the non DOM children. Only set this to true if you know what you're doing! 461 /// @return The number of children. 462 int GetNumChildren(bool include_non_dom_elements = false) const; 463 464 /// Gets the markup and content of the element. 465 /// @param[out] content The content of the element. 466 virtual void GetInnerRML(String& content) const; 467 /// Gets the markup and content of the element. 468 /// @return The content of the element. 469 String GetInnerRML() const; 470 /// Sets the markup and content of the element. All existing children will be replaced. 471 /// @param[in] rml The new content of the element. 472 void SetInnerRML(const String& rml); 473 474 //@} 475 476 /** @name DOM Methods 477 */ 478 //@{ 479 480 /// Gives focus to the current element. 481 /// @return True if the change focus request was successful 482 bool Focus(); 483 /// Removes focus from from this element. 484 void Blur(); 485 /// Fakes a mouse click on this element. 486 void Click(); 487 488 /// Adds an event listener to this element. 489 /// @param[in] event Event to attach to. 490 /// @param[in] listener The listener object to be attached. 491 /// @param[in] in_capture_phase True to attach in the capture phase, false in bubble phase. 492 void AddEventListener(const String& event, EventListener* listener, bool in_capture_phase = false); 493 /// Removes an event listener from this element. 494 /// @param[in] event Event to detach from. 495 /// @param[in] listener The listener object to be detached. 496 /// @param[in] in_capture_phase True to detach from the capture phase, false from the bubble phase. 497 void RemoveEventListener(const String& event, EventListener* listener, bool in_capture_phase = false); 498 /// Sends an event to this element. 499 /// @param[in] event Name of the event in string form. 500 /// @param[in] parameters The event parameters. 501 /// @param[in] interruptible True if the propagation of the event be stopped. 502 /// @return True if the event was not consumed (ie, was prevented from propagating by an element), false if it was. 503 bool DispatchEvent(const String& event, const Dictionary& parameters, bool interruptible = false); 504 505 /// Scrolls the parent element's contents so that this element is visible. 506 /// @param[in] align_with_top If true, the element will align itself to the top of the parent element's window. If false, the element will be aligned to the bottom of the parent element's window. 507 void ScrollIntoView(bool align_with_top = true); 508 509 /// Append a child to this element. 510 /// @param[in] element The element to append as a child. 511 /// @param[in] dom_element True if the element is to be part of the DOM, false otherwise. Only set this to false if you know what you're doing! 512 void AppendChild(Element* element, bool dom_element = true); 513 /// Adds a child to this element, directly after the adjacent element. The new element inherits the DOM/non-DOM 514 /// status from the adjacent element. 515 /// @param[in] element Element to insert into the this element. 516 /// @param[in] adjacent_element The element to insert directly before. 517 void InsertBefore(Element* element, Element* adjacent_element); 518 /// Replaces the second node with the first node. 519 /// @param[in] inserted_element The element that will be inserted and replace the other element. 520 /// @param[in] replaced_element The existing element that will be replaced. If this doesn't exist, inserted_element will be appended. 521 /// @return True if the replaced_element was found, false otherwise. 522 bool ReplaceChild(Element* inserted_element, Element* replaced_element); 523 /// Remove a child element from this element. 524 /// @param[in] The element to remove. 525 /// @returns True if the element was found and removed. 526 bool RemoveChild(Element* element); 527 /// Returns whether or not this element has any DOM children. 528 /// @return True if the element has at least one DOM child, false otherwise. 529 bool HasChildNodes() const; 530 531 /// Get a child element by its ID. 532 /// @param[in] id Id of the the child element 533 /// @return The child of this element with the given ID, or NULL if no such child exists. 534 Element* GetElementById(const String& id); 535 /// Get all descendant elements with the given tag. 536 /// @param[out] elements Resulting elements. 537 /// @param[in] tag Tag to search for. 538 void GetElementsByTagName(ElementList& elements, const String& tag); 539 /// Get all descendant elements with the given class set on them. 540 /// @param[out] elements Resulting elements. 541 /// @param[in] tag Tag to search for. 542 void GetElementsByClassName(ElementList& elements, const String& class_name); 543 //@} 544 545 /** 546 @name Internal Functions 547 */ 548 //@{ 549 /// Access the event dispatcher for this element. 550 /// @return The element's dispatcher. 551 EventDispatcher* GetEventDispatcher() const; 552 /// Access the element background. 553 /// @return The element's background. 554 ElementBackground* GetElementBackground() const; 555 /// Access the element border. 556 /// @return The element's boder. 557 ElementBorder* GetElementBorder() const; 558 /// Access the element decorators. 559 /// @return The element decoration. 560 ElementDecoration* GetElementDecoration() const; 561 /// Returns the element's scrollbar functionality. 562 /// @return The element's scrolling functionality. 563 ElementScroll* GetElementScroll() const; 564 //@} 565 566 /// Returns true if this element requires clipping 567 int GetClippingIgnoreDepth(); 568 /// Returns true if this element has clipping enabled 569 bool IsClippingEnabled(); 570 571 /// Gets the render interface owned by this element's context. 572 /// @return The element's context's render interface. 573 RenderInterface* GetRenderInterface(); 574 575 /// Sets the instancer to use for releasing this element. 576 /// @param[in] instancer Instancer to set on this element. 577 void SetInstancer(ElementInstancer* instancer); 578 579 /// Called for every event sent to this element or one of its descendants. 580 /// @param[in] event The event to process. 581 virtual void ProcessEvent(Event& event); 582 583 /// Update the element's layout if required. 584 void UpdateLayout(); 585 586 void PutUserValue(const String& identifier, std::unique_ptr<ValueReference> reference); 587 ValueReference* GetUserValue(const String& identifier) const; 588 589 protected: 590 /// Forces the element to generate a local stacking context, regardless of the value of its z-index 591 /// property. 592 void ForceLocalStackingContext(); 593 594 /// Called during the update loop after children are updated. 595 virtual void OnUpdate(); 596 /// Called during render after backgrounds, borders, decorators, but before children, are rendered. 597 virtual void OnRender(); 598 virtual void OnBeforeRender(); 599 virtual void OnAfterRender(); 600 601 /// Called during a layout operation, when the element is being positioned and sized. 602 virtual void OnLayout(); 603 604 /// Called when attributes on the element are changed. 605 /// @param[in] changed_attributes The attributes changed on the element. 606 virtual void OnAttributeChange(const AttributeNameList& changed_attributes); 607 /// Called when properties on the element are changed. 608 /// @param[in] changed_properties The properties changed on the element. 609 virtual void OnPropertyChange(const PropertyNameList& changed_properties); 610 611 /// Called when a child node has been added somewhere in the hierarchy. 612 // @param[in] child The element that has been added. This may be this element. 613 virtual void OnChildAdd(Element* child); 614 /// Called when a child node has been removed somewhere in the hierarchy. 615 // @param[in] child The element that has been removed. This may be this element. 616 virtual void OnChildRemove(Element* child); 617 618 /// Forces a re-layout of this element, and any other elements required. 619 virtual void DirtyLayout(); 620 621 /// Returns true if the element has been marked as needing a re-layout. 622 virtual bool IsLayoutDirty(); 623 624 /// Increment/Decrement the layout lock 625 virtual void LockLayout(bool lock); 626 627 /// Forces a reevaluation of applicable font effects. 628 virtual void DirtyFont(); 629 630 /// Returns the RML of this element and all children. 631 /// @param[out] content The content of this element and those under it, in XML form. 632 virtual void GetRML(String& content); 633 634 virtual void OnReferenceDeactivate(); 635 636 private: 637 void SetParent(Element* parent); 638 639 void ReleaseDeletedElements(); 640 void ReleaseElements(ElementList& elements); 641 642 void DirtyOffset(); 643 void UpdateOffset(); 644 645 void BuildLocalStackingContext(); 646 void BuildStackingContext(ElementList* stacking_context); 647 void DirtyStackingContext(); 648 649 void DirtyStructure(); 650 651 // Original tag this element came from. 652 String tag; 653 654 // The optional, unique ID of this object. 655 String id; 656 657 // Instancer that created us, used for destruction. 658 ElementInstancer* instancer; 659 660 // Parent element. 661 Element* parent; 662 // Currently focused child object 663 Element* focus; 664 // The owning document 665 ElementDocument* owner_document; 666 667 // The event dispatcher for this element. 668 EventDispatcher* event_dispatcher; 669 // Style information for this element. 670 ElementStyle* style; 671 // Background functionality for this element. 672 ElementBackground* background; 673 // Border functionality for this element. 674 ElementBorder* border; 675 // Decorator information for this element. 676 ElementDecoration* decoration; 677 // Scrollbar information for this element. 678 ElementScroll* scroll; 679 // Attributes on this element. 680 ElementAttributes attributes; 681 682 // The offset of the element, and the element it is offset from. 683 Element* offset_parent; 684 Vector2f relative_offset_base; // the base offset from the parent 685 Vector2f relative_offset_position; // the offset of a relatively positioned element 686 bool offset_fixed; 687 688 mutable Vector2f absolute_offset; 689 mutable bool offset_dirty; 690 691 // The offset this element adds to its logical children due to scrolling content. 692 Vector2f scroll_offset; 693 694 // The size of the element. 695 typedef std::vector< Box > BoxList; 696 BoxList boxes; 697 // And of the element's internal content. 698 Vector2f content_offset; 699 Vector2f content_box; 700 701 // Defines what box area represents the element's client area; this is usually padding, but may be content. 702 Box::Area client_area; 703 704 // True if the element is visible and active. 705 bool visible; 706 707 ElementList children; 708 int num_non_dom_children; 709 710 ElementList active_children; 711 ElementList deleted_children; 712 713 float z_index; 714 bool local_stacking_context; 715 bool local_stacking_context_forced; 716 717 ElementList stacking_context; 718 bool stacking_context_dirty; 719 720 // The element's font face; used to render text and resolve em / ex properties. 721 FontFaceHandle* font_face_handle; 722 723 std::map<String, std::unique_ptr<ValueReference>> user_values; 724 725 // Cached rendering information 726 int clipping_ignore_depth; 727 bool clipping_enabled; 728 bool clipping_state_dirty; 729 730 friend class Context; 731 friend class ElementStyle; 732 friend class LayoutEngine; 733 friend class LayoutInlineBox; 734 }; 735 736 #include "Element.inl" 737 738 } 739 } 740 741 #endif 742