unity.scopes.ColumnLayout

Defines a layout for preview widgets with given column setup. More...

Public Member Functions

 ColumnLayout (int num_of_columns)
 Creates a layout definition that expects num_of_columns columns to be added with ColumnLayout::add_column. More...
 
void add_column (std::vector< std::string > widget_ids)
 Adds a new column and assigns widgets to it. More...
 
int size () const noexcept
 Get the current number of columns in this layout. More...
 
int number_of_columns () const noexcept
 Get the number of columns expected by this layout as specified in the constructor. More...
 
std::vector< std::string > column (int index) const
 Retrieve the list of widgets for given column. More...
 
Copy and assignment

Copy and assignment operators (move and non-move versions) have the usual value semantics.

 ColumnLayout (ColumnLayout const &other)
 
 ColumnLayout (ColumnLayout &&)
 
ColumnLayout & operator= (ColumnLayout const &other)
 
ColumnLayout & operator= (ColumnLayout &&)
 

Detailed Description

Defines a layout for preview widgets with given column setup.

ColumnLayout defines how widgets should be laid out on a display with a given number of columns. In typical use cases, a scope creates ColumnLayout instances for all supported displays (number of columns), and defines for every instance what widgets belong to which columns. The shell uses the layout that is most appropriate for the device in use. Column layout definitions are optional. However, we recommend that scopes define layouts for the best visual appearance.

An example of creating two layouts, one for a screen with one column and and one for a screen with two columns.

<span class="keywordtype">void</span> MyPreview::run(<a class="code" href="unity.scopes.md#a7b46ef0e880da4c75314fe60bdd55754">PreviewReplyProxy</a> <span class="keyword">const</span>&amp; reply)
<span class="comment">// layout definition for a screen with just 1 column</span>
<a class="code" href="#ac93fd7c6681f2013b4dcf2ed16f95401">ColumnLayout</a> layout1col(1);
layout1col.add_column({<span class="stringliteral">&quot;art&quot;</span>, <span class="stringliteral">&quot;header&quot;</span>, <span class="stringliteral">&quot;actions&quot;</span>}); <span class="comment">// all widgets in a single column</span>
<span class="comment">// layout definition for a screen with 2 columns</span>
<a class="code" href="#ac93fd7c6681f2013b4dcf2ed16f95401">ColumnLayout</a> layout2col(2);
layout2col.add_column({<span class="stringliteral">&quot;art&quot;</span>});  <span class="comment">// widget in 1st column</span>
layout2col.add_column({<span class="stringliteral">&quot;header&quot;</span>, <span class="stringliteral">&quot;actions&quot;</span>}); <span class="comment">// widgets in 2nd column</span>
reply-&gt;register_layout({layout1col, layout2col});
<span class="comment">// create widgets</span>
PreviewWidget w1(<span class="stringliteral">&quot;art&quot;</span>, <span class="stringliteral">&quot;image&quot;</span>);
...

Constructor & Destructor Documentation

unity::scopes::ColumnLayout::ColumnLayout ( int  num_of_columns)
explicit

Creates a layout definition that expects num_of_columns columns to be added with ColumnLayout::add_column.

Parameters
num_of_columnsThe number of columns for the layout.
Exceptions
unity::InvalidArgumentExceptionfor an invalid number of columns.

Member Function Documentation

void unity::scopes::ColumnLayout::add_column ( std::vector< std::string >  widget_ids)

Adds a new column and assigns widgets to it.

ColumnLayout expects exactly the number of columns passed to the constructor to be created with the add_column method.

Exceptions
unity::LogicExceptionif an attempt is made to add more columns than specified in the constructor.
unity::LogicExceptionfrom unity::scopes::PreviewReply::register_layout if a layout has fewer columns than specified in the constructor.
std::vector< std::string > unity::scopes::ColumnLayout::column ( int  index) const

Retrieve the list of widgets for given column.

Parameters
indexThe index of a column.
Returns
The widget identifiers for the given column index.
Exceptions
unity::InvalidArgumentExceptionif the index is invalid.
int unity::scopes::ColumnLayout::number_of_columns ( ) const
noexcept

Get the number of columns expected by this layout as specified in the constructor.

Returns
The number of columns expected by this layout.
int unity::scopes::ColumnLayout::size ( ) const
noexcept

Get the current number of columns in this layout.

Returns
The number of columns added with add_column().