Class Widget

Page Contents

Inheritance Relationships

Base Type

Derived Types

Class Documentation

class Widget : public nanogui::Object

Base class of all widgets.

Widget is the base class of all widgets in nanogui. It can also be used as an panel to arrange an arbitrary number of child widgets using a layout generator (see Layout).

Subclassed by nanogui::Button, nanogui::CheckBox, nanogui::ColorWheel, nanogui::GLCanvas, nanogui::Graph, nanogui::ImagePanel, nanogui::ImageView, nanogui::Label, nanogui::ProgressBar, nanogui::Screen, nanogui::Slider, nanogui::StackedWidget, nanogui::TabHeader, nanogui::TabWidget, nanogui::TextBox, nanogui::VScrollPanel, nanogui::Window

Public Functions

Widget(Widget *parent, const std::string &font = "")

Constructs a Widget.

Parameters
  • parent: The parent of this Widget.
  • font:

    The font face to start with. When anything other than the empty string, this implies that a user has explicitly requested a specific font face. For example, new Label(parent, "text", "sans-bold"). That is, sub-classes that draw text should always provide an explicit font parameter in their constructor, with a default value of "". See How Fonts are Used.

Widget *parent()

Return the parent widget.

const Widget *parent() const

Return the parent widget.

void setParent(Widget *parent)

Set the parent widget.

Layout *layout()

Return the used Layout generator.

const Layout *layout() const

Return the used Layout generator.

void setLayout(Layout *layout)

Set the used Layout generator.

Theme *theme()

Return the Theme used to draw this widget.

const Theme *theme() const

Return the Theme used to draw this widget.

virtual void setTheme(Theme *theme)

Set the Theme used to draw this widget.

const Vector2i &position() const

Return the position relative to the parent widget.

void setPosition(const Vector2i &pos)

Set the position relative to the parent widget.

Vector2i absolutePosition() const

Return the absolute position on screen.

const Vector2i &size() const

Return the size of the widget.

void setSize(const Vector2i &size)

set the size of the widget

int width() const

Return the width of the widget.

void setWidth(int width)

Set the width of the widget.

int height() const

Return the height of the widget.

void setHeight(int height)

Set the height of the widget.

void setFixedSize(const Vector2i &fixedSize)

Set the fixed size of this widget.

If nonzero, components of the fixed size attribute override any values computed by a layout generator associated with this widget. Note that just setting the fixed size alone is not enough to actually change its size; this is done with a call to setSize or a call to performLayout() in the parent widget.

const Vector2i &fixedSize() const

Return the fixed size (see setFixedSize())

int fixedWidth() const
int fixedHeight() const
void setFixedWidth(int width)

Set the fixed width (see setFixedSize())

void setFixedHeight(int height)

Set the fixed height (see setFixedSize())

bool visible() const

Return whether or not the widget is currently visible (assuming all parents are visible)

void setVisible(bool visible)

Set whether or not the widget is currently visible (assuming all parents are visible)

bool visibleRecursive() const

Check if this widget is currently visible, taking parent widgets into account.

int childCount() const

Return the number of child widgets.

const std::vector<Widget *> &children() const

Return the list of child widgets of the current widget.

virtual void addChild(int index, Widget *widget)

Add a child widget to the current widget at the specified index.

This function almost never needs to be called by hand, since the constructor of Widget automatically adds the current widget to its parent

void addChild(Widget *widget)

Convenience function which appends a widget at the end.

void removeChild(int index)

Remove a child widget by index.

void removeChild(const Widget *widget)

Remove a child widget by value.

const Widget *childAt(int index) const

Retrieves the child at the specific position.

Widget *childAt(int index)

Retrieves the child at the specific position.

int childIndex(Widget *widget) const

Returns the index of a specific child or -1 if not found.

template <typename WidgetClass, typename... Args>
WidgetClass *add(const Args&... args)

Variadic shorthand notation to construct and add a child widget.

Window *window()

Walk up the hierarchy and return the parent window.

Screen *screen()

Walk up the hierarchy and return the parent screen.

void setId(const std::string &id)

Associate this widget with an ID value (optional)

const std::string &id() const

Return the ID value associated with this widget, if any.

bool enabled() const

Return whether or not this widget is currently enabled.

void setEnabled(bool enabled)

Set whether or not this widget is currently enabled.

bool focused() const

Return whether or not this widget is currently focused.

void setFocused(bool focused)

Set whether or not this widget is currently focused.

void requestFocus()

Request the focus to be moved to this widget.

float fontSize(const float &defaultFontSize) const

Convenience method to get a valid font size.

If mFontSize is greater than 0 (e.g., setFontSize has been called), then mFontSize will be returned. Otherwise, defaultFontSize is returned.

Parameters
  • defaultFontSize: The default value to return when mFontSize is not set. For example, the Label class uses fontSize(mTheme->mStandardFontSize) whereas Button will use fontSize(mTheme->mButtonFontSize).
Exceptions
  • std::runtime_error: When defaultFontSize < 1.0f.

void setFontSize(float size)

Set the font size of this widget. Set to -1 to revert to a derived class default (e.g. Theme::mStandardFontSize for Label).

Exceptions
  • std::runtime_error: When size >= 0 && size < 1.0f.

bool hasFontSize() const

Return whether the font size is explicitly specified for this widget.

std::string font() const

The current font being used for this Widget (if text is being drawn).

void setFont(const std::string &font)

Sets the font to be used for this Widget (if text is being drawn).

virtual std::string defaultFont() const

Called by Widget::font when mFont is the empty string.

const std::string &tooltip() const

The tooltip for this Widget (displays on mouse hover).

void setTooltip(const std::string &tooltip)

Sets the tooltip for this Widget (displays on mouse hover).

std::string tooltipFont() const

Get the font name being used to draw mTooltip.

void setTooltipFont(const std::string &font)

Set the font to be used to draw mTooltip.

virtual std::string defaultTooltipFont() const

Called by Widget::tooltipFont when mTooltipFont is the empty string.

float iconExtraScale() const

The amount of extra scaling applied to icon fonts. See nanogui::Widget::mIconExtraScale.

void setIconExtraScale(float scale)

Sets the amount of extra scaling applied to icon fonts. See nanogui::Widget::mIconExtraScale.

std::string iconFont() const

Get the font name being used to draw icons for this widget.

void setIconFont(const std::string &iconFont)

Sets the icon font for this Widget (assumes this font is valid / already loaded).

virtual std::string defaultIconFont() const

Called by Widget::iconFont when mIconFont is the empty string.

Cursor cursor() const

Return a pointer to the cursor of the widget.

void setCursor(Cursor cursor)

Set the cursor of the widget.

bool contains(const Vector2i &p) const

Check if the widget contains a certain position.

Widget *findWidget(const Vector2i &p)

Determine the widget located at the given position value (recursive)

virtual bool mouseButtonEvent(const Vector2i &p, int button, bool down, int modifiers)

Handle a mouse button event (default implementation: propagate to children)

virtual bool mouseMotionEvent(const Vector2i &p, const Vector2i &rel, int button, int modifiers)

Handle a mouse motion event (default implementation: propagate to children)

virtual bool mouseDragEvent(const Vector2i &p, const Vector2i &rel, int button, int modifiers)

Handle a mouse drag event (default implementation: do nothing)

virtual bool mouseEnterEvent(const Vector2i &p, bool enter)

Handle a mouse enter/leave event (default implementation: record this fact, but do nothing)

virtual bool scrollEvent(const Vector2i &p, const Vector2f &rel)

Handle a mouse scroll event (default implementation: propagate to children)

virtual bool focusEvent(bool focused)

Handle a focus change event (default implementation: record the focus status, but do nothing)

virtual bool keyboardEvent(int key, int scancode, int action, int modifiers)

Handle a keyboard event (default implementation: do nothing)

virtual bool keyboardCharacterEvent(unsigned int codepoint)

Handle text input (UTF-32 format) (default implementation: do nothing)

virtual Vector2i preferredSize(NVGcontext *ctx) const

Compute the preferred size of the widget.

virtual void performLayout(NVGcontext *ctx)

Invoke the associated layout generator to properly place child widgets, if any.

virtual void draw(NVGcontext *ctx)

Draw the widget (and all child widgets)

virtual void save(Serializer &s) const

Save the state of the widget into the given Serializer instance.

virtual bool load(Serializer &s)

Restore the state of the widget from the given Serializer instance.

Protected Functions

virtual ~Widget()

Free all resources used by the widget and any children.

float icon_scale() const

Convenience definition for subclasses to get the full icon scale for this class of Widget. It simple returns the value mTheme->mIconScale * this->mIconExtraScale.

Remark
See also: nanogui::Theme::mIconScale and nanogui::Widget::mIconExtraScale. This tiered scaling strategy may not be appropriate with fonts other than entypo.ttf.

Protected Attributes

Widget *mParent
ref<Theme> mTheme
ref<Layout> mLayout
std::string mId
Vector2i mPos
Vector2i mSize
Vector2i mFixedSize
std::vector<Widget *> mChildren
bool mVisible

Whether or not this Widget is currently visible. When a Widget is not currently visible, no time is wasted executing its drawing method.

bool mEnabled

Whether or not this Widget is currently enabled. Various different kinds of derived types use this to determine whether or not user input will be accepted. For example, when mEnabled == false, the state of a CheckBox cannot be changed, or a TextBox will not allow new input.

bool mFocused
bool mMouseFocus
std::string mTooltip

The tooltip to draw for this widget (on mouse hover). Empty string means no tooltip.

float mIconExtraScale

The amount of extra icon scaling used in addition the the theme’s default icon font scale. Default value is 1.0, which implies that nanogui::Widget::icon_scale simply returns the value of nanogui::Theme::mIconScale.

Most widgets do not need extra scaling, but some (e.g., CheckBox, TextBox) need to adjust the Theme’s default icon scaling (nanogui::Theme::mIconScale) to properly display icons within their bounds (upscale, or downscale).

Note

When using nvgFontSize for icons in subclasses, make sure to call the nanogui::Widget::icon_scale() function. Expected usage when drawing icon fonts is something like:

virtual void draw(NVGcontext *ctx) {
    // fontSize depends on the kind of Widget.  Search for `FontSize`
    // in the Theme class (e.g., standard vs button)
    float ih = fontSize;
    // assuming your Widget has a declared `mIcon`
    if (nvgIsFontIcon(mIcon)) {
        ih *= icon_scale();
        nvgFontFace(ctx, "icons");
        nvgFontSize(ctx, ih);
        /// remaining drawing code (see button.cpp for more)
    }
}

Cursor mCursor

Private Members

float mFontSize

Used to set the font size of a widget explicitly. The initial value is -1, and a negative number indicates that the theme’s font size should be used instead. Specifically, fontSize will return Theme::mStandardFontSize when mFontSize < 0.

std::string mFont

The explicitly specified font face to use for drawing generic text.

The value of this variable is typically the empty string (""), indicating that no font has been explicitly specified by a user. In this event, either the class or theme will define the font face. See How Fonts are Used.

std::string mTooltipFont

The explicitly specified font face for drawing mTooltip with.

The value of this variable is typically the empty string (""), indicating that no font has been explicitly specified by a user. In this event, either the class or theme will define the font face. See How Fonts are Used.

std::string mIconFont

The explicitly specified font face for drawing icon text.

The value of this variable is typically the empty string (""), indicating that no font has been explicitly specified by a user. In this event, either the class or theme will define the font face. See How Fonts are Used.