ElementBoxWidget Class Reference

#include "stage/widget/element-box-widget.hpp"

Description

A basic building block of the Lumiera UI.

Representation of an entity, with a marker icon, a menu, descriptive label and possibly a content renderer (e.g. for a video clip). Depending on the presentation intent, the widget can be set to a fixed horizontal extension, to allow presentation on a time calibrated canvas. Pre-defined styling and bindings to expand the display and to invoke a menu are provided.

Todo:

consider policy based design, //////////////////////////////////////////////////////////////////TICKET #1239 : re-evaluate Design, maybe use Policy Based Design but need more exposure and real world usage as of 9/22

Definition at line 143 of file element-box-widget.hpp.

Public Member Functions
template<class... QS>
	ElementBoxWidget (Kind kind, Type type, QS ...qualifiers)
	setup an ElementBoxWidget with suitable presentation style. More...
	ElementBoxWidget (Config)
cuString	get_label () const
cuString	getName () const
void	set_label (cuString &s)
	redirect Gtk::Frame setters to ElementBoxWidget
void	setName (cuString &)

Classes
class	Config
struct	Strategy

Private Types
using	_Base = Gtk::EventBox

Private Member Functions
void	get_preferred_height_for_width_vfunc (int, int &, int &) const override
void	get_preferred_height_vfunc (int &, int &) const override
void	get_preferred_width_vfunc (int &, int &) const override
	Layout preferences are delegated through the Strategy. More...
Gtk::SizeRequestMode	get_request_mode_vfunc () const final
	Layout trend for ElementBoxWidget is nailed down (final) to "height-for-width". More...
void	imposeSizeConstraint (int, int)
	Ensure the child widgets can be represented and possibly adjust or hide content, in case the extension of ElementBoxWidget is explicitly constrained in size. More...
void	on_size_allocate (Gtk::Allocation &) override
	Tap into the notification of screen space allocation to possibly enforce size constraints. More...

Private Attributes
Gtk::Frame	frame_
IDLabel	label_
Strategy	strategy_
	actual layout strategy binding for this widget

Constructor & Destructor Documentation

ElementBoxWidget()

ElementBoxWidget ( Kind  widgetKind, Type  type, QS ...  qualifiers  )

inline

setup an ElementBoxWidget with suitable presentation style.

Parameters

widgetKind	the basic presentation intent
type	qualify the type of data represented by this object
qualifiers	pass further qualifiers to fine-tune the presentation

Definition at line 302 of file element-box-widget.hpp.

Referenced by MarkerWidget::MarkerWidget().

Here is the caller graph for this function:

Member Function Documentation

get_request_mode_vfunc()

Gtk::SizeRequestMode get_request_mode_vfunc ( ) const

finalprivate

Layout trend for ElementBoxWidget is nailed down (final) to "height-for-width".

The reason is, some of the use cases entail placing the element box onto a canvas with horizontal extension calibrated to time units; doing so requires us to control the extension, which is delegated through the strategy

Definition at line 241 of file element-box-widget.cpp.

get_preferred_width_vfunc()

void get_preferred_width_vfunc ( int &  minimum_width, int &  natural_width  ) const

overrideprivate

Layout preferences are delegated through the Strategy.

• by default, the strategy will just invoke the inherited VFuncs
• however, when a size constraint for the ElementBoxWidget must be observed, the strategy will control the extension of our child widgets (side-effect) and then just return the extension as dictated by the constraints

  Remarks

  Based on the GTK-3.24 implementation code, we know that most usages will draw upon the natural_width, but there are some use cases (esp. Gtk::Layout), where the calculation takes minimum_width as starting point. The returned values will always be respected, while the GTK layout engine might increase the given extensions...

  • do adjust for additional border and margin settings from CSS
  • and to expand the widget when used within a container with fill-alignment Moreover the #get_preferred_height_for_width_vfunc will be invoked with the results from this function. The possible adjustment is done by invoking the VFunc adjust_size_allocation on the GTK-class, which typically delegates to gtk_widget_real_adjust_size_allocation, and the latter invokes
  • adjust_for_margin
  • adjust_for_align After these adjustments and some sanity checks, the resulting size allocation is passed to the size_allocate VFunc, which passes through the Gtk::Widget::on_size_allocate() and after that by default stores this allocation into the widget's private data.

Definition at line 269 of file element-box-widget.cpp.

get_preferred_height_vfunc()

void get_preferred_height_vfunc ( int &  minimum_height, int &  natural_height  ) const

overrideprivate

Remarks

only provided for sake of completeness, since GTK code is complex and some code path might ignore our request mode preference and invoke both functions.

Definition at line 282 of file element-box-widget.cpp.

on_size_allocate()

void on_size_allocate ( Gtk::Allocation &  availableSize )

overrideprivate

Tap into the notification of screen space allocation to possibly enforce size constraints.

Generally speaking, explicit size constrained widgets are not a concept supported by GTK, due to its flexible layout model and the use of CSS for styling and theming. Unfortunately we need this feature, in order to implement Clip widgets on a time calibrated canvas. Thus we use an implementation trick: we report our size constraints as "natural size" to GTK, knowing that GTK will respect those extensions (unless the widget is placed into a container with fill-alignment). However, by doing so, we have effectively lied to GTK with respect to our child widgets. Thus we now have to take on the responsibility to somehow make those child widgets fit into the limited size allocation....

Definition at line 311 of file element-box-widget.cpp.

imposeSizeConstraint()

void imposeSizeConstraint ( int  widthC, int  heightC  )

private

Ensure the child widgets can be represented and possibly adjust or hide content, in case the extension of ElementBoxWidget is explicitly constrained in size.

Note

• this code works even when the widget is not(yet) realized;
• 💡 as soon as a GTK widget is marked visible it will respond properly to queries regarding the required extension

Definition at line 328 of file element-box-widget.cpp.

Inheritance diagram for ElementBoxWidget:

Collaboration diagram for ElementBoxWidget:

---

The documentation for this class was generated from the following files:

• element-box-widget.hpp
• element-box-widget.cpp