/usr/include/Wt/WWidget is in libwt-dev 3.3.4+dfsg-6ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 | // This may look like C code, but it's really -*- C++ -*-
/*
* Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
*
* See the LICENSE file for terms of use.
*/
#ifndef WWIDGET_H_
#define WWIDGET_H_
#include <Wt/WObject>
#include <Wt/WGlobal>
#include <Wt/WAnimation>
#include <Wt/WLength>
#include <Wt/WSignal>
#include <Wt/WJavaScript>
#include <boost/utility.hpp>
#include <vector>
#include <sstream>
namespace Wt {
enum RepaintFlag {
RepaintSizeAffected = 0x1,
RepaintToAjax = 0x2
};
W_DECLARE_OPERATORS_FOR_FLAGS(RepaintFlag)
class WContainerWidget;
class WCssDecorationStyle;
class WDropEvent;
class WLayout;
class WLayoutItemImpl;
class WLayoutItem;
class WMouseEvent;
class WString;
class WWebWidget;
class DomElement;
class WCssTextRule;
/*! \class WWidget Wt/WWidget Wt/WWidget
* \brief The abstract base class for a user-interface component.
*
* The user-interface is organized in a tree structure, in which each
* nodes is a widgets. All widgets, except for the application's root
* widget and dialogs, have a parent which is usually a
* WContainerWidget.
*
* \if cpp
*
* When a widget is deleted, it is also visually removed from the
* user-interface and all children are deleted recursively.
*
* \endif
*
* This is an abstract base class. Implementations derive either from
* the abstract WWebWidget (for basic widgets with a direct HTML
* counter-part) or from the abstract WCompositeWidget (for anything
* else). To add a %WWebWidget directly to a parent container, either
* specify the parent in the constructor (which is conventionally the
* last constructor argument), or add the widget to the parent using
* WContainerWidget::addWidget(). Alternatively, you may add the widget
* to a layout manager set for a %WContainerWidget.
*
* A widget provides methods to manage its decorative style base on
* CSS. It also provides access to CSS-based layout, which you may not
* use when the widget is not inserted into a layout manager.
*/
class WT_API WWidget : public WObject
#ifndef WT_TARGET_JAVA
, boost::noncopyable
#endif // WT_TARGET_JAVA
{
public:
/*! \brief Destructor.
*
* Deletes a widget and all children (recursively). If the widget is
* contained in another widget, it is removed first.
*
* \sa WContainerWidget::removeWidget()
*/
virtual ~WWidget();
/*! \brief Returns the parent widget.
*
* With a few exceptions, the parent is a WContainerWidget, and has
* been set implicitly when adding the widget to a container using
* WContainerWidget::addWidget(), by passing a container as a parent
* to the constructor, or by inserting the widget into a layout
* manager.
*/
WWidget *parent() const { return dynamic_cast<WWidget *>(WObject::parent()); }
virtual void removeChild(WObject *child);
/*! \brief Sets the CSS position scheme.
*
* Establishes how the widget must be layed-out relative to its
* siblings. The default position scheme is Static.
*
* This applies to CSS-based layout.
*
* \sa Wt::PositionScheme, positionScheme()
*/
virtual void setPositionScheme(PositionScheme scheme) = 0;
/*! \brief Returns the CSS position scheme.
*
* This applies to CSS-based layout.
*
* \sa Wt::PositionScheme, setPositionScheme(PositionScheme)
*/
virtual PositionScheme positionScheme() const = 0;
/*! \brief Sets CSS offsets for a non-statically positioned widget.
*
* The argument \p sides may be a combination of Wt::Left,
* Wt::Right, Wt::Top, and Wt::Bottom.
*
* This applies only to widgets that have a position scheme that is
* Wt::Relative, Wt::Absolute, or Wt::Fixed, and has a slightly
* different meaning for these three cases.
*
* For a \link Wt::Relative relatively positioned\endlink widget, an
* offset applies relative to the position the widget would have
* when layed-out using a \link Wt::Static static\endlink position
* scheme. The widget may be shifted to the left or right by
* specifying an offset for the \link Wt::Left left\endlink or \link
* Wt::Right right\endlink) side. The widget may be shifted
* vertically, by specifying an offset for the \link Wt::AlignTop
* top\endlink or \link Wt::Bottom bottom\endlink side.
*
* For an \link Wt::Absolute absolutely positioned\endlink widget,
* an offset specifies a distance of the corresponding side of the
* widget with respect to the corresponding side of the reference
* parent widget. Thus, setting all offsets to 0 result in a widget
* that spans the entire reference widget. The reference parent
* widget is the first ancestor widget that is a table cell, or a
* widget with a relative, absolute or fixed position scheme.
*
* For an \link Wt::Fixed fixed positioned\endlink widget, an offset
* specifies a distance of the corresponding side of the widget with
* respect to the browser window, regardless of scrolling. Thus,
* setting all offsets to 0 result in a widget that spans the entire
* browser window.
*
* This applies to CSS-based layout.
*
* \sa offset(Side) const
*/
virtual void setOffsets(const WLength& offset, WFlags<Side> sides = All) = 0;
#ifdef WT_TARGET_JAVA
/*! \brief Sets CSS offsets for a non-statically positioned widget.
*
* This is a convenience method for applying offsets in pixel units.
*
* \sa setOffsets(const WLength&, WFlags<Side>)
*/
void setOffsets(int pixels, WFlags<Side> sides = All);
#endif // WT_TARGET_JAVA
/*! \brief Returns a CSS offset.
*
* This applies to CSS-based layout.
*
* \sa setOffsets(const WLength&, WFlags<Side>)
*/
virtual WLength offset(Side side) const = 0;
/*! \brief Resizes the widget.
*
* Specifies a fixed size for this widget, setting CSS
* <tt>width</tt> and <tt>height</tt> properties. By default a
* widget has automatic width and height, which sets a size for the
* widget following CSS rules.
*
* When the widget is not managed by a layout manager, the automatic
* (natural) size of a widget depends on whether they widget is a
* <i>block</i> or <i>inline</i> widget:
* - a <i>block</i> widget takes by default the width of the parent, and the height
* that it needs based on its contents
* - an <i>inline</i> widget takes the width and height that it needs based on its
* contents (possibly wrapping over multiple lines). The width and height of
* an inline widget cannot be changed (by the letter of CSS, although most
* browsers will react to it in varying ways).
*
* When inserted in a layout manager, the size set will be used as a
* widget's preferred size, but the widget may be given a different
* size by the layout manager based on available space and stretch
* factors. The actual size given by a layout manager may be
* retrieved by making the widget "layout size aware", using
* setLayoutSizeAware(). If you have defined a <tt>"wtResize()"</tt>
* JavaScript method for the widget, then this method will also be
* called.
*
* The default width and height of a widget is WLength::Auto.
*
* \sa width(), height()
*/
virtual void resize(const WLength& width, const WLength& height);
#ifdef WT_TARGET_JAVA
/*! \brief Resizes the widget.
*
* This is a convenience method for resizing a widget using pixel units.
*
* \sa resize(const WLength&, const WLength&)
*/
void resize(int widthPixels, int heightPixels);
#endif // WT_TARGET_JAVA
/*! \brief Returns the width.
*
* Returns the width set for this widget. This is not a calculated
* width, based on layout, but the width as specified with
* resize(const WLength&, const WLength&).
*
* This applies to CSS-based layout.
*
* \sa resize(const WLength&, const WLength&), height()
*/
virtual WLength width() const = 0;
/*! \brief Sets the width.
*
* This is a convenience method to change only the width of a widget, and
* is implemented as:
* \code
* resize(width, height())
* \endcode
*
* \sa resize(), setHeight()
*/
void setWidth(const WLength& width);
/*! \brief Returns the height.
*
* Returns the height set for this widget. This is not a calculated
* height, based on layout, but the height as specified previously
* with resize(const WLength& width, const WLength& height).
*
* This applies to CSS-based layout.
*
* \sa resize(const WLength&, const WLength&), width()
*/
virtual WLength height() const = 0;
/*! \brief Sets the height.
*
* This is a convenience method to change only the width of a widget, and
* is implemented as:
* \code
* resize(width(), height)
* \endcode
*
* This applies to CSS-based layout.
*
* \sa resize(), setWidth()
*/
void setHeight(const WLength& height);
/*! \brief Sets a minimum size.
*
* Specifies a minimum size for this widget, setting CSS <tt>min-width</tt>
* and <tt>min-height</tt> properties.
*
* The default minimum width and height is 0. The special value
* WLength::Auto indicates that the initial width is used as minimum
* size. A WLength::Percentage size should not be used, as this is
* (in virtually all cases) undefined behaviour.
*
* When the widget is inserted in a layout manager, then the minimum size
* will be taken into account.
*
* \sa resize(), minimumWidth(), minimumHeight()
*/
virtual void setMinimumSize(const WLength& width, const WLength& height) = 0;
/*! \brief Returns the minimum width.
*
* Returns the minimum width set for this widget with setMinimumSize().
*
* \sa setMinimumSize(), minimumHeight()
*/
virtual WLength minimumWidth() const = 0;
/*! \brief Returns the minimum height.
*
* Returns the minmum height set for this widget with setMinimumSize().
*
* \sa setMinimumSize(), minimumWidth()
*/
virtual WLength minimumHeight() const = 0;
/*! \brief Sets a maximum size.
*
* Specifies a maximum size for this widget, setting CSS <tt>max-width</tt>
* and <tt>max-height</tt> properties.
*
* The default the maximum width and height are WLength::Auto,
* indicating no maximum size. A WLength::Percentage size should not
* be used, as this is (in virtually all cases) undefined behaviour.
*
* When the widget is a container widget that contains a layout
* manager, then setting a maximum size will have the effect of
* letting the size of the container to reflect the preferred size
* of the contents (rather than constraining the size of the
* children based on the size of the container), up to the specified
* maximum size.
*
* \sa resize(), setMinimumSize()
*/
virtual void setMaximumSize(const WLength& width, const WLength& height) = 0;
/*! \brief Returns the maximum width.
*
* Returns the maximum width set for this widget with setMaximumSize().
*
* \sa setMaximumSize(), maximumHeight()
*/
virtual WLength maximumWidth() const = 0;
/*! \brief Returns the maximum height.
*
* Returns the minmum height set for this widget with setMaximumSize().
*
* \sa setMaximumSize(), maximumWidth()
*/
virtual WLength maximumHeight() const = 0;
/*! \brief Positions a widget next to another widget.
*
* Positions this absolutely positioned widget next to another \p
* widget. Both widgets must be visible (including all their
* ancestors). The current widget is shown automatically if needed.
*
* When \p orientation = Wt::Vertical, the widget is displayed below the
* other widget (or above in case there is not enough room
* below). It is aligned so that the left edges align (or the right
* edges if there is not enough room to the right).
*
* Conversely, when \p orientation = Wt::Horizontal, the widget is
* displayed to the right of the other widget (or to the left in
* case there is not enough room to the right). It is aligned so
* that the top edges align (or the bottom edges if there is not
* enough room below).
*
* \note This only works if JavaScript is available.
*/
virtual void positionAt(const WWidget *widget,
Orientation orientation = Vertical);
/*! \brief Sets the CSS line height for contained text.
*/
virtual void setLineHeight(const WLength& height) = 0;
/*! \brief Returns the CSS line height for contained text.
*
* sa setLineHeight()
*/
virtual WLength lineHeight() const = 0;
/*! \brief Specifies a CSS float side.
*
* This only applies to widgets with a Wt::Static positionScheme().
*
* This lets the widget float to one of the sides of the parent
* widget, at the current line. A typical use is to position images
* within text. Valid values for Side or \if cpp Wt::None \elseif
* java {javadoclink Side#None None} \endif, Wt::Left or Wt::Right.
*
* This applies to CSS-based layout.
*/
virtual void setFloatSide(Side s) = 0;
/*! \brief Returns the CSS float side.
*
* \sa setFloatSide(Side)
*/
virtual Side floatSide() const = 0;
/*! \brief Sets the sides that should be cleared of floats.
*
* This pushes the widget down until it is not surrounded by floats
* at the \p sides (which may be a combination of Wt::Left and
* Wt::Right).
*
* This applies to CSS-based layout.
*
* \sa setFloatSide()
*/
virtual void setClearSides(WFlags<Side> sides) = 0;
/*! \brief Returns the sides that should remain empty.
*
* \sa setClearSides(WFlags<Side>)
*/
virtual WFlags<Side> clearSides() const = 0;
/*! \brief Sets CSS margins around the widget.
*
* Setting margin has the effect of adding a distance between the widget
* and surrounding widgets. The default margin (with an automatic length)
* is zero.
*
* Use any combination of Wt::Left, Wt::Right, Wt::Bottom, or Wt::Top.
*
* This applies to CSS-based layout.
*
* \sa margin()
*/
virtual void setMargin(const WLength& margin, WFlags<Side> sides = All) = 0;
#ifdef WT_TARGET_JAVA
/*! \brief Sets CSS margins around the widget.
*
* This is a convenience method for setting margins in pixel units.
*
* \sa setMargin(const WLength&, WFlags<Side>)
*/
virtual void setMargin(int pixels, WFlags<Side> sides = All);
#endif // WT_TARGET_JAVA
/*! \brief Returns a CSS margin set.
*
* This applies to CSS-based layout.
*
* \sa setMargin()
*/
virtual WLength margin(Side side) const = 0;
/*! \brief Sets whether the widget keeps its geometry when hidden.
*
* Normally, a widget that is hidden will no longer occupy space,
* causing a reflow of sibling widgets. Using this method you may
* change this behavior to keep an (open) space when hidden.
*
* \note Currently you can only set this before initial rendering.
*
* \sa setHidden()
*/
virtual void setHiddenKeepsGeometry(bool enabled) = 0;
/*! \brief Returns whether the widget keeps its geometry when hidden.
*
* \sa setHiddenKeepsGeometry()
*/
virtual bool hiddenKeepsGeometry() const = 0;
/*! \brief Hides or shows the widget.
*
* Hides or show the widget (including all its descendant widgets).
* When setting \p hidden = \c false, this widget and all descendant
* widgets that are not hidden will be shown. A widget is only
* visible if it and all its ancestors in the widget tree are
* visible, which may be checked using isVisible().
*/
virtual void setHidden(bool hidden,
const WAnimation& animation = WAnimation()) = 0;
/*! \brief Returns whether the widget is set hidden.
*
* A widget that is not hidden may still be not visible when one of
* its ancestor widgets is hidden. Use isVisible() to check the
* visibility of a widget.
*
* \sa setHidden(), isVisible()
*/
virtual bool isHidden() const = 0;
/*! \brief Returns whether the widget is visible.
*
* A widget is visible if it is not hidden, and none of its
* ancestors are hidden. This method returns the true visibility,
* while isHidden() returns whether a widget has been explicitly
* hidden.
*
* Note that a widget may be at the same time not hidden, and not
* visible, in case one of its ancestors was hidden.
*
* \sa isHidden()
*/
virtual bool isVisible() const = 0;
/*! \brief Sets whether the widget is disabled.
*
* Enables or disables the widget (including all its descendant
* widgets). setDisabled(false) will enable this widget and all
* descendant widgets that are not disabled. A widget is only
* enabled if it and all its ancestors in the widget tree are
* disabled.
*
* Typically, a disabled form widget will not allow changing the
* value, and disabled widgets will not react to mouse click events.
*
* \sa disable(), enable()
*/
virtual void setDisabled(bool disabled) = 0;
/*! \brief Returns whether the widget is set disabled.
*
* A widget that is not set disabled may still be disabled when one
* of its ancestor widgets is set disabled. Use isEnabled() to find
* out whether a widget is enabled.
*
* \sa setDisabled(), isEnabled()
*/
virtual bool isDisabled() const = 0;
/*! \brief Returns whether the widget is enabled.
*
* A widget is enabled if it is not disabled, and none of its
* ancestors are disabled. This method returns whether the widget is
* rendered as enabled, while isDisabled() returns whether a widget
* has been explicitly disabled.
*
* Note that a widget may be at the same time not enabled, and not
* disabled, in case one of its ancestors was disabled.
*
* \sa isDisabled()
*/
virtual bool isEnabled() const = 0;
/*! \brief Lets the widget overlay over other sibling widgets.
*
* A widget that isPopup() will be rendered on top of any other
* sibling widget contained within the same parent (including other
* popup widgets previously added to the container).
*
* This will only have an effect when the widgetis either
* Wt::Absolute or Wt::Fixed positionScheme().
*
* This applies to CSS-based layout, and configures the z-index
* property.
*/
virtual void setPopup(bool popup) = 0;
/*! \brief Returns whether the widget is overlayed.
*
* This applies to CSS-based layout.
*
* \sa setPopup(bool)
*/
virtual bool isPopup() const = 0;
/*! \brief Sets whether the widget is displayed inline or as a block.
*
* This option changes whether this widget must be rendered in line
* with sibling widgets wrapping at the right edge of the parent
* container (like text), or whether this widget must be rendered as
* a rectangular block that stacks vertically with sibling widgets
* (unless a CSS float property is applied). Depending on the widget
* type, the default value is inline (such as for example for WText,
* or WPushButton), or block (such as for example for a
* WContainerWidget).
*
* This applies to CSS-based layout.
*/
virtual void setInline(bool inlined) = 0;
/*! \brief Returns whether the widget is displayed inline or as block.
*
* \sa setInline(bool)
*/
virtual bool isInline() const = 0;
/*! \brief Sets a CSS decoration style.
*
* This copies the style over its current decorationStyle()
*/
virtual void setDecorationStyle(const WCssDecorationStyle& style) = 0;
/*! \brief Returns the decoration style of this widget.
*
* This groups all decorative aspects of the widget, which do not
* affect the widget layout (except for the border properties which
* may behave like extra margin around the widget).
*
* When a decoration style has not been previously set, it returns a
* default decoration style object.
*
* \sa setDecorationStyle()
*/
virtual WCssDecorationStyle& decorationStyle() = 0;
virtual const WCssDecorationStyle& decorationStyle() const = 0;
/*! \brief Sets (one or more) CSS style classes.
*
* You may set one or more space separated style classes. CSS style
* class works in conjunction with style sheet, and provides a
* flexible way to provide many widgets the same markup.
*
* Setting an empty string removes the style class(es).
*
* \sa WApplication::styleSheet()
*/
virtual void setStyleClass(const WT_USTRING& styleClass) = 0;
void setStyleClass(const char *styleClass);
/*! \brief Returns the CSS style class.
*
* \sa setStyleClass()
*/
virtual WT_USTRING styleClass() const = 0;
/*! \brief Adds a CSS style class.
*
* When \p force = \c true, a JavaScript call will be used to add
* the style class to the DOM element (if JavaScript is
* available). This may be necessary when client-side JavaScript
* manipulates the same style class.
*
* The \p styleClass should be a single class (although multiple
* classes will work for the common case that the additional style classes
* are all not yet present on the element.
*/
virtual void addStyleClass(const WT_USTRING& styleClass,
bool force = false) = 0;
void addStyleClass(const char *styleClass, bool force = false);
/*! \brief Removes a CSS style class.
*
* When \p force = \c true, a JavaScript call will be used to remove
* the style class from the DOM element (if JavaScript is
* available). This may be necessary when client-side JavaScript
* manipulates the same style class.
*
* The \p styleClass should be a single class
*/
virtual void removeStyleClass(const WT_USTRING& styleClass,
bool force = false) = 0;
void removeStyleClass(const char *styleClass, bool force = false);
/*! \brief Toggles a CSS style class.
*/
virtual void toggleStyleClass(const WT_USTRING& styleClass, bool add,
bool force = false);
void toggleStyleClass(const char *styleClass, bool add, bool force = false);
/*! \brief Returns whether the widget has a style class.
*/
virtual bool hasStyleClass(const WT_USTRING& styleClass) const = 0;
/*! \brief Sets the vertical alignment.
*
* This only applies to inline widgets, and determines how to position
* itself on the current line, with respect to sibling inline widgets.
*
* This applies to CSS-based layout.
*/
virtual void setVerticalAlignment(AlignmentFlag alignment,
const WLength& length = WLength::Auto) = 0;
/*! \brief Returns the vertical alignment.
*
* This applies to CSS-based layout.
*
* \sa setVerticalAlignment()
*/
virtual AlignmentFlag verticalAlignment() const = 0;
/*! \brief Returns the fixed vertical alignment that was set.
*
* This applies to CSS-based layout.
*
* \sa setVerticalAlignment()
*/
virtual WLength verticalAlignmentLength() const = 0;
/*! \brief Sets a tooltip.
*
* The tooltip is displayed when the cursor hovers over the widget.
*
* When \p textFormat is XHTMLText, the tooltip may contain any valid
* XHTML snippet. The tooltip will then be rendered using JavaScript.
*
* Note: This will set deferred tooltip to false.
*
* \sa setDeferredTooltip()
*/
virtual void setToolTip(const WString& text,
TextFormat textFormat = PlainText) = 0;
/*! \brief Returns the tooltip.
*/
virtual WString toolTip() const = 0;
/*! \brief Enable deferred tooltip.
*
* You may override toolTip() to read data only when the user hovers over
* the widget.
*
* When \p textFormat is XHTMLText, the tooltip may contain any valid
* XHTML snippet. The tooltip will then be rendered using JavaScript.
*
* Note: To change existing toolTip call setDeferredToolTip() again.
*
* \sa toolTip
*/
virtual void setDeferredToolTip(bool enable,
TextFormat textFormat = PlainText) = 0;
/*! \brief Refresh the widget.
*
* The refresh method is invoked when the locale is changed using
* WApplication::setLocale() or when the user hit the refresh button.
*
* The widget must actualize its contents in response.
*
* \note This does *not* rerender the widget! Calling refresh() usually
* does not have any effect (unless you've reimplemented refresh()
* to attach to it an effect).
*/
virtual void refresh();
/*! \brief Returns a JavaScript expression to the corresponding DOM node.
*
* You may want to use this in conjunction with JSlot or
* doJavaScript() in custom JavaScript code.
*
* \sa isRendered()
*/
std::string jsRef() const;
/*! \brief Sets an attribute value.
*
* Sets the value for an HTML attribute.
*
* This is only useful for HTML features that are not supported directly in
* Wt (and beware that browsers have non-consisten support for many more
* exotic HTML features).
*
* \sa JSlot, doJavaScript()
*/
virtual void setAttributeValue(const std::string& name,
const WT_USTRING& value) = 0;
/*! \brief Returns an attribute value.
*
* \sa setAttributeValue()
*/
virtual WT_USTRING attributeValue(const std::string& name) const = 0;
/*! \brief Sets a JavaScript member.
*
* This binds a JavaScript member, which is set as a JavaScript property
* to the DOM object that implements this widget. The value may be any
* JavaScript expression, including a function.
*
* Members that start with <tt>"wt"</tt> are reserved for internal
* use. You may define a member <tt>"wtResize(self, width,
* height)"</tt> method if your widget needs active layout
* management. If defined, this method will be used by layout
* managers and when doing resize() to set the size of the widget,
* instead of setting the CSS width and height properties.
*/
virtual void setJavaScriptMember(const std::string& name,
const std::string& value) = 0;
/*! \brief Returns the value of a JavaScript member.
*
* \sa setJavaScriptMember()
*/
virtual std::string javaScriptMember(const std::string& name) const = 0;
/*! \brief Calls a JavaScript member.
*
* This calls a JavaScript member.
*
* \sa setJavaScriptMember()
*/
virtual void callJavaScriptMember(const std::string& name,
const std::string& args) = 0;
/*! \brief Short hand for WString::tr()
*
* Creates a localized string with the given key.
*/
static WString tr(const char *key);
static WString tr(const std::string& key);
/*! \brief Loads content just before the widget is used.
*
* When the widget is inserted in the widget hierarchy, this method
* is called. Widgets that get inserted in the widget hierarchy will
* be rendered. Visible widgets are rendered immediately, and
* invisible widgets in the back-ground (or not for a plain HTML
* session). This method is called when the widget is directly or
* indirectly inserted into the widget tree.
*
* The default implementation simply propagates the load signal to
* its children. You may want to override this method to delay loading
* of resource-intensive contents.
*
* During the life-time of a widget, this method may be called
* multiple times, so you should make sure that you do a deferred
* initializiation only once.
*/
virtual void load() = 0;
/*! \brief Returns whether this widget has been loaded.
*
* \sa load()
*/
virtual bool loaded() const = 0;
/*! \brief Sets whether the widget can receive focus.
*
* By default, only form widgets (descendants of WFormWidget),
* anchors (WAnchor) and buttons (WPushButton) can receive focus.
*
* Any other widget can be configured to receive focus however.
*/
virtual void setCanReceiveFocus(bool enabled) = 0;
/*! \brief Returns whether the widget can receive focus.
*
* \sa setCanReceiveFocus()
*/
virtual bool canReceiveFocus() const = 0;
/*! \brief Sets focus.
*
* This only has an effect for a widget which can receive focus, and
* is equivalent to setFocus(true).
*
* \sa setCanReceiveFocus()
*/
void setFocus();
/*! \brief Sets focus.
*
* When using \p focus = \c false, you can undo a previous setFocus() call.
*/
virtual void setFocus(bool focus) = 0;
/*! \brief Set focus on the widget's first descendant.
*
* Set focus on the widget itself, or on a first descendant which can
* receive focus.
*
* Returns whether focus could be set.
*/
virtual bool setFirstFocus() = 0;
/*! \brief Returns whether the widget currently has the focus.
*/
virtual bool hasFocus() const = 0;
/*! \brief Sets the tab index.
*
* For widgets that receive focus (canReceiveFocus()), focus is
* passed on to the next widget in the <i>tabbing chain</i> based on
* their tab index. When the user navigates through form widgets
* using the keyboard, widgets receive focus starting from the
* element with the lowest tab index to elements with the highest
* tab index.
*
* Widgets with a same tab index will receive focus in the same order
* as they are inserted in the widget tree.
*
* The default tab index is 0 (for a widget that can receive focus).
*
* \sa setTabOrder()
*/
virtual void setTabIndex(int index) = 0;
/*! \brief Returns the tab index.
*
* \sa setTabIndex()
*/
virtual int tabIndex() const = 0;
virtual int zIndex() const = 0;
/*! \brief Sets a mime type to be accepted for dropping.
*
* You may specify a style class that is applied to the widget when the
* specified mimetype hovers on top of it.
*
* \sa dropEvent(), WInteractWidget::setDraggable(), stopAcceptDrops()
*/
virtual void acceptDrops(const std::string& mimeType,
const WT_USTRING& hoverStyleClass = WT_USTRING());
/*! \brief Indicates that a mime type is no longer accepted for dropping.
*
* \sa acceptDrops()
*/
virtual void stopAcceptDrops(const std::string& mimeType);
/*! \brief Sets the CSS Id.
*
* Sets a custom Id. Note that the Id must be unique across the whole
* widget tree, can only be set right after construction and cannot
* be changed. This is mostly useful for in tests using a test plan that
* manipulates DOM elements by Id.
*
* By default, auto-generated id's are used.
*
* \note An id must start with a letter ([A-Za-z]), followed by one or more
* letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"),
* and periods (".").
*
* \sa WObject::id()
*/
virtual void setId(const std::string& id) = 0;
/*! \brief Finds a descendent widget by name.
*
* \sa setObjectName()
*/
virtual WWidget *find(const std::string& name) = 0;
/*! \brief Finds a descendent widget by id.
*/
virtual WWidget *findById(const std::string& id) = 0;
/*! \brief Streams the (X)HTML representation.
*
* Streams the widget as UTF8-encoded (HTML-compatible) XHTML.
*
* This may be useful as a debugging tool for the web-savvy, or in
* other rare situations. Usually, you will not deal directly with
* HTML, and calling this method on a widget that is rendered may
* interfere with the library keeping track of changes to the
* widget.
*/
virtual void htmlText(std::ostream& out);
/*! \brief Sets as selectable.
*
* When a widget is made unselectable, a selection of text (or images)
* will not be visible (but may still be possible).
*
* By default, the widget inherits this property from its parent,
* and this property propagates to all children. The top level
* container (WApplication::root()) selectable by default.
*/
virtual void setSelectable(bool selectable) = 0;
/*! \brief Executes the given JavaScript statements when
* the widget is rendered or updated.
*
* Calling WApplication::doJavaScript() with JavaScript code that
* refers to a widget using jsRef(), that is still to be rendered
* may cause JavaScript errors because the corresponding DOM node
* does not exist. This happens for example when a widget is
* created, but not yet inserted in the widget tree.
*
* This method guarantees that the JavaScript code is only run when
* the corresponding DOM node (using jsRef()) resolves to a valid
* DOM object.
*
* \sa jsRef()
*/
virtual void doJavaScript(const std::string& js) = 0;
/*! \brief Returns whether the widget is rendered.
*
* \sa jsRef()
*/
bool isRendered() const;
std::string inlineCssStyle();
std::string createJavaScript(WStringStream& js, std::string insertJS);
/*! \brief Hides the widget.
*
* \sa setHidden()
*/
void hide();
/*! \brief Hides the widget using an animation.
*
* To hide the widget, the animation is replayed in reverse.
*
* \sa setHidden()
*/
void animateHide(const WAnimation& animation);
/*! \brief Shows the widget.
*
* \sa setHidden()
*/
void show();
/*! \brief Shows the widget using an animation.
*
* \sa setHidden()
*/
void animateShow(const WAnimation& animation);
/*! \brief Enables the widget.
*
* This calls \link setDisabled() setDisabled(false)\endlink.
*/
void enable();
/*! \brief Disable thes widget.
*
* This calls \link setDisabled() setDisabled(true)\endlink.
*/
void disable();
/*! \brief Returns whether the widget is layout size aware.
*
* \sa setLayoutSizeAware()
*/
bool layoutSizeAware() const;
DomElement *createSDomElement(WApplication *app);
static void setTabOrder(WWidget *first, WWidget *second);
virtual bool isExposed(WWidget *widget);
protected:
static const char *WT_RESIZE_JS;
static const char *WT_GETPS_JS;
/*! \brief Sets the widget to be aware of its size set by a layout manager.
*
* When the widget is inserted in a layout manager, it will be
* resized to fit within the constraints imposed by the layout
* manager. By default, this done client-side only by setting the
* CSS height (and if needed, width) properties of the DOM element
* corresponding to the widget.
*
* A widget may define a JavaScript method, <tt>"wtResize(self,
* width, height)"</tt>, to actively manage its client-side width
* and height, if it wants to react to these client-side size hints
* in a custom way (see setJavaScriptMember()).
*
* By setting \p sizeAware to true, the widget will propagate the
* width and height provided by the layout manager to the virtual
* layoutSizeChanged() method, so that you may for example change
* the size of contained children in a particular way (doing a
* custom, manual, layout).
*
* \sa layoutSizeChanged()
*/
void setLayoutSizeAware(bool sizeAware);
/*! \brief Virtual method that indicates a size change.
*
* This method propagates the client-side width and height of the
* widget when the widget is contained by a layout manager and
* setLayoutSizeAware(true) was called.
*
* \sa setLayoutSizeAware()
*/
virtual void layoutSizeChanged(int width, int height);
/*! \brief Creates a widget.
*
* When a parent container is specified, the widget is added to the
* container, using WContainerWidget::addWidget().
*/
WWidget(WContainerWidget* parent = 0);
/*! \brief Handles a drop event.
*
* Reimplement this method to handle a drop events for mime types you
* declared to accept using acceptDrops.
*
* The default implementation simply completes the drag and drop operation
* as if nothing happened.
*
* \sa acceptDrops(), WInteractWidget::setDraggable()
*/
virtual void dropEvent(WDropEvent dropEvent);
/*! \brief Progresses to an Ajax-enabled widget.
*
* This method is called when the progressive bootstrap method is
* used, and support for AJAX has been detected. The default
* behavior will upgrade the widget's event handling to use AJAX
* instead of full page reloads, and propagate the call to its
* children.
*
* You may want to reimplement this method if you want to make
* changes to widget when AJAX is enabled. You should always call
* the base implementation.
*
* \sa WApplication::enableAjax()
*/
virtual void enableAjax() = 0;
/*! \brief Returns the widget's built-in padding.
*
* This is used by the layout managers to correct for a built-in
* padding which interferes with setting a widget's width (or
* height) to 100%.
*
* A layout manager needs to set the width to 100% only for form
* widgets (WTextArea, WLineEdit, WComboBox, etc...). Therefore,
* only for those widgets this needs to return the padding (the
* default implementation returns 0).
*
* For form widgets, the padding depends on the specific
* browser/platform combination, unless an explicit padding is set
* for the widget.
*
* When setting an explicit padding for the widget using a style
* class, you will want to reimplement this method to return this
* padding in case you want to set the widget inside a layout
* manager.
*
* \sa boxBorder()
*/
virtual int boxPadding(Orientation orientation) const;
/*! \brief Returns the widget's built-in border width.
*
* This is used by the layout managers to correct for a built-in
* border which interferes with setting a widget's width (or height)
* to 100%.
*
* A layout manager needs to set the width to 100% only for form
* widgets (WTextArea, WLineEdit, WComboBox, etc...). Therefore,
* only for those widgets this needs to return the border width (the
* default implementation returns 0).
*
* For form widgets, the border width depends on the specific
* browser/platform combination, unless an explicit border is set
* for the widget.
*
* When setting an explicit border for the widget using a style
* class, you will want to reimplement this method to return this
* border width, in case you want to set the widget inside a layout
* manager.
*
* \sa boxPadding()
*/
virtual int boxBorder(Orientation orientation) const;
/*! \brief Propagates that a widget was enabled or disabled through children.
*
* When enabling or disabling a widget, you usually also want to disable
* contained children. This method is called by setDisabled() to propagate
* its state to all children.
*
* You may want to reimplement this method if they wish to render
* differently when a widget is disabled. The default implementation will
* propagate the signal to all children.
*/
virtual void propagateSetEnabled(bool enabled) = 0;
void getDrop(const std::string sourceId, const std::string mimeType,
WMouseEvent event);
virtual void addChild(WWidget *child) = 0;
virtual void removeChild(WWidget *child) = 0;
virtual void setHideWithOffsets(bool how = true) = 0;
virtual void setParentWidget(WWidget *parent);
virtual bool isStubbed() const = 0;
/*! \brief Schedules rerendering of the widget.
*
* This schedules a rendering phase after all events have been
* processed. This method is used internally whenever a property of
* a widget has been changed. But you may want to use this if you
* are deferring actual changes to a widget in response to an event,
* and instead postpone this until all events have been received.
*
* \sa render()
*/
void scheduleRender(WFlags<RepaintFlag> flags = 0);
/*! \brief Renders the widget.
*
* This function renders the widget (or an update for the widget), after
* this has been scheduled using scheduleRender().
*
* The default implementation will render the widget by serializing changes
* to JavaScript and HTML. You may want to reimplement this widget if you
* have been postponing some of the layout / rendering implementation
* until the latest moment possible. In that case you should make sure you
* call the base implementation however.
*/
virtual void render(WFlags<RenderFlag> flags);
virtual void childResized(WWidget *child, WFlags<Orientation> directions);
WWidget *adam();
virtual void setLayout(WLayout *layout);
#ifndef WT_NO_BOOST_INTRUSIVE
typedef boost::intrusive::list<EventSignalBase> EventSignalList;
#else
typedef std::list<EventSignalBase *> EventSignalList;
#endif
void addEventSignal(EventSignalBase& s);
EventSignalBase *getEventSignal(const char *name);
EventSignalList& eventSignals() { return eventSignals_; }
virtual WStatelessSlot *getStateless(Method method);
void renderOk();
void scheduleRerender(bool laterOnly, WFlags<RepaintFlag> flags = 0);
bool needRerender() const { return flags_.test(BIT_NEED_RERENDER); }
virtual void getSDomChanges(std::vector<DomElement *>& result,
WApplication *app) = 0;
virtual bool needsToBeRendered() const = 0;
bool isInLayout() const;
virtual bool hasParent() const;
WCssTextRule *addCssRule(const std::string& selector,
const std::string& declarations,
const std::string& ruleName = std::string());
private:
/*
* Booleans packed in a bitset.
*/
static const int BIT_WAS_HIDDEN = 0;
static const int BIT_WAS_DISABLED = 1;
static const int BIT_NEED_RERENDER = 2;
static const int BIT_NEED_RERENDER_SIZE_CHANGE = 3;
static const int BIT_HAS_PARENT = 4;
static const int BIT_RESIZE_AWARE = 5;
std::bitset<6> flags_;
EventSignalList eventSignals_;
void setHasParent(bool hasParent);
void setJsSize();
void undoHideShow();
void undoDisableEnable();
virtual WWebWidget *webWidget() = 0;
virtual WLayoutItemImpl *createLayoutItemImpl(WLayoutItem *layout);
virtual WLayout *layout();
friend class StdWidgetItemImpl;
friend class WebRenderer;
friend class WAbstractArea;
friend class WAbstractItemView;
friend class WApplication;
friend class WCalendar;
friend class WContainerWidget;
friend class WCompositeWidget;
friend class WFileUpload;
friend class WGLWidget;
friend class WLayout;
friend class WMenuItem;
friend class WPaintedWidget;
friend class WPopupWidget;
friend class WScrollArea;
friend class WTemplate;
friend class WViewWidget;
friend class WWebWidget;
friend class WWidgetItem;
};
}
#endif // WWIDGET_H_
|