/usr/include/Wt/WMenuItem is in libwt-dev 3.3.3+dfsg-4.1.
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 | // 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 WMENU_ITEM_H_
#define WMENU_ITEM_H_
#include <Wt/WContainerWidget>
#include <Wt/WString>
namespace Wt {
/*! \brief A single item in a menu.
*
* Since %Wt 3.3.0, this item is now a proper widget, which renders a
* single item in a menu.
*
* An optional contents item can be associated with a menu item, which
* is inserted and shown in the widget stack of the menu to which this
* menu item belongs.
*
* <h3>CSS</h3>
*
* A menu item renders as a >li&;lt with additional markup/style
* classes provided by the theme. Unless you use the bootstrap theme,
* you will need to provide appropriate CSS.
*/
class WT_API WMenuItem : public WContainerWidget
{
public:
/*! \brief Enumeration that determines when contents should be loaded.
*/
enum LoadPolicy {
LazyLoading, //!< Lazy loading: on first use
PreLoading //!< Pre-loading: before first use
};
/*! \brief Creates a new item with given label.
*
* The optional contents is a widget that will be shown in the WMenu
* contents stack when the item is selected. For this widget, a load
* \p policy can be indicated which specifies whether the contents
* widgets is transmitted only when it the item is activated for the
* first time (LazyLoading) or transmitted prior to first rendering.
*
* If the menu supports internal path navigation, then a default
* pathComponent() will be derived from the \p label, and can be
* customized using setPathComponent().
*/
WMenuItem(const WString& label, WWidget *contents = 0,
LoadPolicy policy = LazyLoading);
/*
* The icon is displayed left to the text.
*
* \note The icon should have a width of 16 pixels.
*/
WMenuItem(const std::string& iconPath, const WString& label,
WWidget *contents = 0, LoadPolicy policy = LazyLoading);
/* !\brief Destructor.
*
* Removes the item from the menu (if it was added previously to one), and
* also deletes the contents that was associated with the item.
*
* \sa WMenu::removeItem()
*/
~WMenuItem();
/*! \brief Sets the text for this item.
*
* Unless a custom path component was defined, the pathComponent()
* is also updated based on the new text.
*
* The item widget is updated using updateItemWidget().
*
* \sa setPathComponent();
*/
void setText(const WString& text);
/*! \brief Returns the text for this item.
*
* \sa setText();
*/
const WString& text() const;
/*! \brief Sets the item icon path.
*
* The icon should have a width of 16 pixels.
*
* \sa setText()
*/
void setIcon(const std::string& path);
/*! \brief Returns the item icon path.
*
* \sa setIcon()
*/
std::string icon() const;
/*! \brief Sets if the item is checkable.
*
* When an item is checkable, a checkbox is displayed to the left of the
* item text (instead of an icon).
*
* \sa setChecked(), isChecked()
*/
void setCheckable(bool checkable);
/*! \brief Returns whether the item is checkable.
*
* \sa setCheckable()
*/
bool isCheckable() const { return checkBox_ != 0; }
/*! \brief Sets the path component for this item.
*
* The path component is used by the menu item in the application
* internal path (see WApplication::setInternalPath()), when
* internal paths are enabled (see WMenu::setInternalPathEnabled())
* for the menu.
*
* You may specify an empty \p path to let a menu item be the
* "default" menu option.
*
* For example, if WMenu::internalBasePath() is
* <tt>"/examples/"</tt> and pathComponent() for is
* <tt>"charts/"</tt>, then the internal path for the item will be
* <tt>"/examples/charts/"</tt>.
*
* By default, the path is automatically derived from text(). If a
* \link WString::literal() literal text\endlink is used, the path
* is based on the text itself, otherwise on the \link
* WString::key() key\endlink. It is converted to lower case, and
* replacing white space and special characters with '_'.
*
* \sa setText(), WMenu::setInternalPathEnabled()
*
* \if cpp
* \note the \p path should be UTF8 encoded (we may fix the API
* to use WString in the future).
* \endif
*/
virtual void setPathComponent(const std::string& path);
/*! \brief Returns the path component for this item.
*
* You may want to reimplement this to customize the path component
* set by the item in the application internal path.
*
* \sa setPathComponent()
*
* \if cpp
* \note the \p path component is UTF8 encoded (we may fix the API
* to use WString in the future).
* \endif
*/
virtual std::string pathComponent() const;
/*! \brief Configures internal path support for the item.
*
* This configures whether the item supports internal paths (in a menu
* which supports internal paths).
*
* The default value is \c true for all items but section headers and
* separators.
*
* \sa WMenu::setInternalPathEnabled()
*/
virtual void setInternalPathEnabled(bool enabled);
/*! \brief Returns whether an item participates in internal paths.
*
* \sa setInternalPathEnabled()
*/
virtual bool internalPathEnabled() const;
/*! \brief Sets the associated link.
*
* \sa Link()
*/
void setLink(const WLink& link);
/*! \brief Returns the associated link.
*
* \sa setLink()
*/
WLink link() const;
/*! \brief Sets the link target.
*
* \sa setLink()
*/
void setLinkTarget(AnchorTarget target);
/*! \brief Returns the link target.
*
* \sa setLinkTarget()
*/
AnchorTarget linkTarget() const;
/*! \brief Sets a sub menu.
*
* Ownership of the \p subMenu is transferred to the item. In
* most cases, the sub menu would use the same contents stack as the
* parent menu.
*/
void setMenu(WMenu *menu);
/*! \brief Sets a sub menu (<b>deprecated</b>)
*
* \deprecated use setMenu() instead
*/
void setSubMenu(WMenu *menu);
/*! \brief Returns the submenu.
*
* \sa setMenu()
*/
WMenu *menu() const { return subMenu_; }
/*! \brief Sets the checked state.
*
* This is only used when isCheckable() == \c true.
*
* \sa setCheckable(bool), isCheckable()
*/
void setChecked(bool checked);
/*! \brief Returns the checked state.
*
* This is only used when isCheckable() == \c true.
*
* \sa setChecked(bool), isCheckable()
*/
bool isChecked() const;
/*! \brief Sets whether the menu item can be selected.
*
* Only a menu item that can be selected can be the result of a
* popup menu selection.
*
* The default value is \c true for a normal menu item, and \c false
* for a menu item that has a submenu.
*
* An item that is selectable but is disabled can still not be
* selected.
*/
void setSelectable(bool selectable);
/*! \brief Returns whether the menu item can be selected.
*
* \sa setSelectable()
*/
bool isSelectable() const { return selectable_; }
/*! \brief Sets associated additional data with the item.
*
* You can use this to associate model information with a menu item.
*/
void setData(void *data) { data_ = data; }
/*! \brief Returns additional data of the item.
*
* \sa setData()
*/
void *data() const { return data_; }
WCheckBox *checkBox() const { return checkBox_; }
/*! \brief Make it possible to close this item interactively or by close().
*
* \sa close(), isCloseable()
*/
void setCloseable(bool closeable);
/*! \brief Returns whether the item is closeable.
*
* \sa setCloseable()
*/
bool isCloseable() const { return closeable_; }
/*! \brief Closes this item.
*
* Hides the item widget and emits WMenu::itemClosed() signal. Only closeable
* items can be closed.
*
* \sa setCloseable(), hide()
*/
void close();
WMenu *parentMenu() const { return menu_; }
/*! \brief Returns the contents widget for this item.
*
* The contents widget is the widget in the WStackedWidget associated with
* this item.
*/
WWidget *contents() const;
WWidget *takeContents();
/*! \brief Returns the widget that represents the item (<b>deprecated</b>).
*
* This returns this.
*
* \deprecated This is a pre-Wt 3.3.0 artifact which has lost its value
* since WMenuItem is now a widget.
*/
WWidget *itemWidget();
/*! \brief Selects this item.
*
* If the item was previously closed it will be shown.
*
* \sa close()
*/
void select();
/*! \brief %Signal emitted when an item is activated.
*
* Returns this item as argument.
*
* \sa WMenu::triggered()
*/
Signal<WMenuItem *>& triggered() { return triggered_; }
/*! \brief Returns whether this item is a separator.
*
* \sa WMenu::addSeparator()
*/
bool isSeparator() const { return separator_; }
/*! \brief Returns whether this item is a section header.
*
* \sa WMenu::addSectionHeader()
*/
bool isSectionHeader() const;
/*! \brief Renders the item as selected or unselected.
*
* The default implementation sets the styleclass for itemWidget()
* to 'item' for an unselected not closeable, 'itemselected' for
* selected not closeable, 'citem' for an unselected closeable and
* 'citemselected' for selected closeable item.
*
* Note that this method is called from within a stateless slot
* implementation, and thus should be stateless as well.
*/
virtual void renderSelected(bool selected);
virtual void setFromInternalPath(const std::string& path);
virtual void enableAjax();
protected:
virtual void render(WFlags<RenderFlag> flags);
private:
// Constructs a separator or header
WMenuItem(bool separator, const WString& text);
WContainerWidget *contentsContainer_;
WWidget *contents_;
WMenu *menu_, *subMenu_;
WText *icon_;
WLabel *text_;
WCheckBox *checkBox_;
void *data_;
bool separator_, selectable_, signalsConnected_;
Signal<WMenuItem *> triggered_;
Wt::Signals::connection contentsDestroyedConnection_;
std::string pathComponent_;
bool customPathComponent_, internalPathEnabled_;
bool closeable_;
void create(const std::string& iconPath, const WString& text,
WWidget *contents, LoadPolicy policy);
WAnchor *anchor() const;
void purgeContents();
void updateInternalPath();
bool contentsLoaded() const;
void loadContents();
void setParentMenu(WMenu *menu);
void selectNotLoaded();
void selectVisual();
void undoSelectVisual();
void connectClose();
void connectSignals();
void setItemPadding(bool padding);
void contentsDestroyed();
void setCheckBox();
void setUnCheckBox();
friend class WMenu;
friend class WPopupMenu;
};
}
#endif // WMENU_ITEM_H_
|