PCL
pcl::Sizer Class Reference

Base class for PixInsight sizer objects. More...

#include <Sizer.h>

+ Inheritance diagram for pcl::Sizer:

Public Types

using item_alignment = Align::value_type
 

Public Member Functions

 Sizer (bool vertical)
 
 ~Sizer () override
 
void Add (Control &c, int stretchFactor=0, item_alignment align=Align::Default)
 
void Add (Sizer &s, int stretchFactor=0)
 
void AddScaledSpacing (int size)
 
void AddSpacing (int size, bool autoScaling=true)
 
void AddStretch (int stretchFactor=100)
 
void AddUnscaledSpacing (int size)
 
bool Contains (const Control &c) const
 
bool Contains (const Sizer &s) const
 
double DisplayPixelRatio () const
 
void EnsureUnique () override
 
int IndexOf (const Control &c) const
 
int IndexOf (const Sizer &s) const
 
void Insert (int index, Control &c, int stretchFactor=0, item_alignment align=Align::Default)
 
void Insert (int index, Sizer &s, int stretchFactor=0)
 
void InsertScaledSpacing (int index, int size)
 
void InsertSpacing (int index, int size, bool autoScaling=true)
 
void InsertStretch (int index, int stretchFactor=100)
 
void InsertUnscaledSpacing (int index, int size)
 
bool IsHorizontal () const
 
bool IsVertical () const
 
int LogicalPixelsToPhysical (int size) const
 
int Margin (bool autoScaling=true) const
 
int NumberOfItems () const
 
ControlParentControl () const
 
int PhysicalPixelsToLogical (int size) const
 
void Remove (Control &c)
 
void Remove (Sizer &s)
 
void SetAlignment (Control &c, item_alignment align)
 
void SetAlignment (Sizer &s, item_alignment align)
 
void SetMargin (int margin, bool autoScaling=true)
 
void SetSpacing (int spacing, bool autoScaling=true)
 
void SetStretchFactor (Control &c, int stretch)
 
void SetStretchFactor (Sizer &s, int stretch)
 
int Spacing (bool autoScaling=true) const
 
- Public Member Functions inherited from pcl::UIObject
virtual ~UIObject () noexcept(false)
 
bool IsAlias () const
 
bool IsGarbage () const
 
bool IsNull () const
 
bool IsSameObject (const UIObject &o) const
 
bool IsUnique () const
 
String ObjectId () const
 
IsoString ObjectType () const
 
bool operator< (const UIObject &o) const
 
bool operator== (const UIObject &o) const
 
size_type RefCount () const
 
void SetObjectId (const String &id)
 

Static Public Member Functions

static SizerNull ()
 
- Static Public Member Functions inherited from pcl::UIObject
static UIObjectNull ()
 

Additional Inherited Members

- Protected Member Functions inherited from pcl::UIObject
 UIObject ()=default
 
 UIObject (const UIObject &x)
 
 UIObject (UIObject &&x)
 
UIObjectoperator= (const UIObject &x)
 
UIObjectoperator= (UIObject &&x)
 

Detailed Description

Sizer allows laying out child controls within their parent controls as simple one-dimensional stacks with precise control over orientations, margins, distances between items, and item alignments. By distributing controls in nested Sizer objects with horizontal and vertical orientations, complex albeit clean user interfaces can be easily defined.

Automatic Scaling

The Sizer class provides an automatic scaling feature that simplifies the adaptation of existing and new PCL-based UI generation code to varying display resolutions. This functionality can be controlled with a Boolean autoScaling parameter available for the following member functions:

Sizer::SetMargin( int margin, bool autoScaling = true );
Sizer::SetSpacing( int spacing, bool autoScaling = true );
Sizer::AddSpacing( int spacing, bool autoScaling = true );
Sizer::InsertSpacing( int index, int spacing, bool autoScaling = true );
int Margin( bool autoScaling = true );
int Spacing( bool autoScaling = true );

As you can see, automatic scaling is always enabled by default. On the PixInsight platform, the reference display density is 109 dpi, corresponding to a 27 inch monitor at QHD resolution (2560x1440 physical pixels).

The automatic scaling feature applies the scaling ratio returned by Sizer::DisplayPixelRatio() to convert horizontal and vertical spaces between items from device-independent (or logical) pixel units to physical device pixel units. When this feature is enabled through the corresponding autoScaling parameters, scaling is applied to both automatic and manual spacings between controls, that is, to spacings defined by SetSpacing(), SetMargin(), AddSpacing(), and InsertSpacing(). The reverse transformation is applied from physical pixels to logical units when dimensions are retrieved by Spacing() and Margin().

See also
HorizontalSizer, VerticalSizer

Definition at line 146 of file Sizer.h.

Member Typedef Documentation

◆ item_alignment

using pcl::Sizer::item_alignment = Align::value_type

Represents the alignment of a Sizer item.

Definition at line 153 of file Sizer.h.

Constructor & Destructor Documentation

◆ Sizer()

pcl::Sizer::Sizer ( bool  vertical)

Constructs a Sizer object.

Parameters
verticalIf true, this sizer will lay out items vertically. If false, items will be laid out horizontally.

◆ ~Sizer()

pcl::Sizer::~Sizer ( )
inlineoverride

Destroys a Sizer object.

Definition at line 166 of file Sizer.h.

Member Function Documentation

◆ Add() [1/2]

void pcl::Sizer::Add ( Control c,
int  stretchFactor = 0,
item_alignment  align = Align::Default 
)

Adds a control to this Sizer object.

Parameters
cThe control to be added.
stretchFactorIndicates how much space the control c will try to occupy within its parent sizer (this sizer), relative to the rest of sibling sizer items. A value of zero indicates that the added control has no particular preference and can be adapted to the existing space, as necessary/possible.
alignItem alignment.

In the following example:

PushButton button1;
PushButton button2;
PushButton button3;
// ...
Sizer fooSizer;
fooSizer.Add( button1, 25 );
fooSizer.Add( button2, 50 );
fooSizer.Add( button3, 25 );

The button1 control will occupy one half of the total available space for fooSizer, and each of button1 and button2 will occupy 1/4 of the space available in fooSizer. Stretch factors don't have to be expressed as percentages necessarily, although using percentage values is usually more readable. The stretch factors 2, 4, 2 would have the same meaning as 25, 50, 25 in the example above.

See also
Add( Sizer&, int ), AddSpacing(), AddStretch(), Insert()

◆ Add() [2/2]

void pcl::Sizer::Add ( Sizer s,
int  stretchFactor = 0 
)

Adds a sizer to this Sizer object.

Parameters
sThe Sizer object to be added.
stretchFactorIndicates how much space the sizer s will tend to occupy within its parent sizer (this sizer), relative to the rest of sibling sizer items.

See the documentation for Add( Control&, int, item_alignment ) for a detailed description.

See also
Add( Control&, int, item_alignment ), AddSpacing(), AddStretch(), Insert()

◆ AddScaledSpacing()

void pcl::Sizer::AddScaledSpacing ( int  size)
inline

Adds a non-stretchable space of size logical pixels to this Sizer. This is a convenience member function equivalent to:

AddSpacing( size, true );

Definition at line 313 of file Sizer.h.

◆ AddSpacing()

void pcl::Sizer::AddSpacing ( int  size,
bool  autoScaling = true 
)

Adds a non-stretchable space of size pixels to this Sizer.

If the autoScaling parameter is set to true, the specified size will be converted from logical device-independent pixel units to physical device pixels automatically. If autoScaling is false, the specified size is assumed to be expressed in physical pixel units, and no automatic scaling will be performed.

See also
InsertSpacing(), AddStretch(), InsertStretch()

◆ AddStretch()

void pcl::Sizer::AddStretch ( int  stretchFactor = 100)

Adds a stretchable space with the specified stretch factor.

See the documentation for Add( Control&, int, item_alignment ) for a detailed description of stretch factors.

See also
AddSpacing(), InsertSpacing(), InsertStretch()

◆ AddUnscaledSpacing()

void pcl::Sizer::AddUnscaledSpacing ( int  size)
inline

Adds a non-stretchable space of size physical pixels to this Sizer. This is a convenience member function equivalent to:

AddSpacing( size, false );

Definition at line 324 of file Sizer.h.

◆ Contains() [1/2]

bool pcl::Sizer::Contains ( const Control c) const
inline

Returns true iff the specified child control c belongs to this Sizer.

Definition at line 235 of file Sizer.h.

◆ Contains() [2/2]

bool pcl::Sizer::Contains ( const Sizer s) const
inline

Returns true iff the specified child sizer s belongs to this Sizer.

Definition at line 227 of file Sizer.h.

◆ DisplayPixelRatio()

double pcl::Sizer::DisplayPixelRatio ( ) const

Returns the ratio between physical screen pixels and device-independent logical units for the parent control of this Sizer object. This ratio is used as a scaling factor by the LogicalPixelsToPhysical() and PhysicalPixelsToLogical() functions, and is also applied automatically when autoScaling parameters are set to true in a number of member functions; see the class description for more information.

The returned value is greater than or equal to one. Typical pixel ratios are 2.0 for high-dpi displays such as Retina monitors, or 1.0 for normal 96 dpi monitors.

See also
LogicalPixelsToPhysical(), PhysicalPixelsToLogical()

◆ EnsureUnique()

void pcl::Sizer::EnsureUnique ( )
inlineoverridevirtual

Ensures that the server-side object managed by this instance is uniquely referenced.

Since sizers are unique objects by definition, calling this member function has no effect.

Reimplemented from pcl::UIObject.

Definition at line 177 of file Sizer.h.

◆ IndexOf() [1/2]

int pcl::Sizer::IndexOf ( const Control c) const

Returns the zero-based index of the specified child control c in this sizer, or -1 if the c control does not belong to this Sizer.

◆ IndexOf() [2/2]

int pcl::Sizer::IndexOf ( const Sizer s) const

Returns the zero-based index of the specified child Sizer object s in this sizer, or -1 if the s sizer does not belong to this Sizer.

◆ Insert() [1/2]

void pcl::Sizer::Insert ( int  index,
Control c,
int  stretchFactor = 0,
item_alignment  align = Align::Default 
)

Inserts a control in this Sizer object.

Parameters
indexZero-based index where the control c will be inserted.
cThe control to be added.
stretchFactorIndicates how much space the control c will tend to occupy within its parent sizer (this sizer), relative to the rest of sibling sizer items.
alignItem alignment.

See the documentation for Add( Control&, int, item_alignment ) for a detailed description.

See also
Insert( int, Sizer&, int ), InsertSpacing(), InsertStretch(), Add()

◆ Insert() [2/2]

void pcl::Sizer::Insert ( int  index,
Sizer s,
int  stretchFactor = 0 
)

Inserts a sizer in this Sizer object.

Parameters
indexZero-based index where the sizer s will be inserted.
sThe Sizer object to be added.
stretchFactorIndicates how much space the sizer s will tend to occupy within its parent sizer (this sizer), relative to the rest of sibling sizer items.

See the documentation for Add( Control&, int, item_alignment ) for a detailed description.

See also
Insert( int, Control&, int, item_alignment ), InsertSpacing(), InsertStretch(), Add()

◆ InsertScaledSpacing()

void pcl::Sizer::InsertScaledSpacing ( int  index,
int  size 
)
inline

Inserts a non-stretchable space of size logical pixels in this Sizer. This is a convenience member function equivalent to:

InsertSpacing( index, size, true );

Definition at line 397 of file Sizer.h.

◆ InsertSpacing()

void pcl::Sizer::InsertSpacing ( int  index,
int  size,
bool  autoScaling = true 
)

Inserts a non-stretchable space of size pixels in this Sizer.

If the autoScaling parameter is set to true, the specified size will be converted from logical device-independent pixel units to physical device pixels automatically. If autoScaling is false, the specified size is assumed to be expressed in physical pixel units, and no automatic scaling will be performed.

See also
AddSpacing(), InsertStretch(), AddStretch()

◆ InsertStretch()

void pcl::Sizer::InsertStretch ( int  index,
int  stretchFactor = 100 
)

Inserts a stretchable space with the specified stretch factor.

See the documentation for Add( Control&, int, item_alignment ) for a detailed description of stretch factors.

See also
InsertSpacing(), AddSpacing(), AddStretch()

◆ InsertUnscaledSpacing()

void pcl::Sizer::InsertUnscaledSpacing ( int  index,
int  size 
)
inline

Inserts a non-stretchable space of size physical pixels in this Sizer. This is a convenience member function equivalent to:

InsertSpacing( index, size, false );

Definition at line 408 of file Sizer.h.

◆ IsHorizontal()

bool pcl::Sizer::IsHorizontal ( ) const
inline

Returns true iff this Sizer lays out items horizontally.

Definition at line 202 of file Sizer.h.

◆ IsVertical()

bool pcl::Sizer::IsVertical ( ) const

Returns true iff this Sizer lays out items vertically.

◆ LogicalPixelsToPhysical()

int pcl::Sizer::LogicalPixelsToPhysical ( int  size) const
inline

Returns the specified size in logical device-independent pixel units converted to physical device pixels.

See also
DisplayPixelRatio(), PhysicalPixelsToLogical()

Definition at line 544 of file Sizer.h.

References pcl::RoundInt().

◆ Margin()

int pcl::Sizer::Margin ( bool  autoScaling = true) const

Returns the margin in pixels around this sizer.

The margin is the empty space that is automatically reserved around this sizer on its parent control's (or parent sizer's) client area. The default margin is always zero pixels for all sizer types, unless explicitly changed with this function.

If the autoScaling parameter is set to true, the returned value will be expressed in logical device-independent pixel units. This means that the returned value has been converted from physical device pixels automatically. If autoScaling is false, the returned value will be expressed in physical device pixels, and no automatic scaling is applied.

See also
SetMargin(), Spacing(), SetSpacing()

◆ Null()

static Sizer& pcl::Sizer::Null ( )
static

Returns a reference to a null Sizer instance. A null Sizer does not correspond to an existing sizer in the PixInsight core application.

◆ NumberOfItems()

int pcl::Sizer::NumberOfItems ( ) const

Returns the number of items in this Sizer object.

◆ ParentControl()

Control& pcl::Sizer::ParentControl ( ) const

Returns a reference to the parent control of this Sizer object, or Control::Null() if this sizer has no parent control.

◆ PhysicalPixelsToLogical()

int pcl::Sizer::PhysicalPixelsToLogical ( int  size) const
inline

Returns the specified size in physical device pixels converted to logical device-independent pixel units.

See also
DisplayPixelRatio(), LogicalPixelsToPhysical()

Definition at line 555 of file Sizer.h.

References pcl::RoundInt().

◆ Remove() [1/2]

void pcl::Sizer::Remove ( Control c)

Removes the specified control c from this Sizer object. If c doesn't belong to this sizer, nothing happens.

◆ Remove() [2/2]

void pcl::Sizer::Remove ( Sizer s)

Removes the specified sizer s from this Sizer object. If s doesn't belong to this sizer, nothing happens.

◆ SetAlignment() [1/2]

void pcl::Sizer::SetAlignment ( Control c,
item_alignment  align 
)

Changes the alignment of a child control c belonging to this Sizer object.

◆ SetAlignment() [2/2]

void pcl::Sizer::SetAlignment ( Sizer s,
item_alignment  align 
)

Changes the alignment of a child sizer s belonging to this Sizer object.

◆ SetMargin()

void pcl::Sizer::SetMargin ( int  margin,
bool  autoScaling = true 
)

Sets the margin in pixels around this sizer.

If the autoScaling parameter is set to true, the specified margin will be converted from logical device-independent pixel units to physical device pixels automatically. If autoScaling is false, the specified margin is assumed to be expressed in physical pixel units, and no automatic scaling will be performed.

See also
Margin(), Spacing(), SetSpacing()

◆ SetSpacing()

void pcl::Sizer::SetSpacing ( int  spacing,
bool  autoScaling = true 
)

Sets the spacing in pixels between items in this Sizer object.

If the autoScaling parameter is set to true, the specified spacing will be converted from logical device-independent pixel units to physical device pixels automatically. If autoScaling is false, the specified spacing is assumed to be expressed in physical pixel units, and no automatic scaling will be performed.

See also
Spacing(), Margin(), SetMargin()

◆ SetStretchFactor() [1/2]

void pcl::Sizer::SetStretchFactor ( Control c,
int  stretch 
)

Changes the stretch factor for a child control s belonging to this Sizer object.

See the documentation for Add( Control&, int, item_alignment ) for a detailed description of stretch factors.

◆ SetStretchFactor() [2/2]

void pcl::Sizer::SetStretchFactor ( Sizer s,
int  stretch 
)

Changes the stretch factor for a child sizer s belonging to this Sizer object.

See the documentation for Add( Control&, int, item_alignment ) for a detailed description of stretch factors.

◆ Spacing()

int pcl::Sizer::Spacing ( bool  autoScaling = true) const

Returns the spacing in pixels between items in this Sizer object.

If the autoScaling parameter is set to true, the returned value will be expressed in logical device-independent pixel units. This means that the returned value has been converted from physical device pixels automatically. If autoScaling is false, the returned value will be expressed in physical device pixels, and no automatic scaling is applied.

See also
SetSpacing(), Margin(), SetMargin()

The documentation for this class was generated from the following file:
pcl::Sizer::AddSpacing
void AddSpacing(int size, bool autoScaling=true)
pcl::Sizer::Sizer
Sizer(bool vertical)
pcl::Sizer::InsertSpacing
void InsertSpacing(int index, int size, bool autoScaling=true)