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

Control &	ParentControl () 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 Sizer &	Null ()

Static Public Member Functions inherited from pcl::UIObject
static UIObject &	Null ()

Additional Inherited Members
Protected Member Functions inherited from pcl::UIObject
	UIObject ()=default

	UIObject (const UIObject &x)

	UIObject (UIObject &&x)

UIObject &	operator= (const UIObject &x)

UIObject &	operator= (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

vertical If 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

c	The control to be added.
stretchFactor	Indicates 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.
align	Item 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

s	The Sizer object to be added.
stretchFactor	Indicates 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 );

pcl::Sizer::AddSpacing

void AddSpacing(int size, bool autoScaling=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

index	Zero-based index where the control c will be inserted.
c	The control to be added.
stretchFactor	Indicates how much space the control c will tend to occupy within its parent sizer (this sizer), relative to the rest of sibling sizer items.
align	Item 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

index	Zero-based index where the sizer s will be inserted.
s	The Sizer object to be added.
stretchFactor	Indicates 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 );

pcl::Sizer::InsertSpacing

void InsertSpacing(int index, int size, bool autoScaling=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:

Sizer.h

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ item_alignment

Constructor & Destructor Documentation

◆ Sizer()

◆ ~Sizer()

Member Function Documentation

◆ Add() [1/2]

◆ Add() [2/2]

◆ AddScaledSpacing()

◆ AddSpacing()

◆ AddStretch()

◆ AddUnscaledSpacing()

◆ Contains() [1/2]

◆ Contains() [2/2]

◆ DisplayPixelRatio()

◆ EnsureUnique()

◆ IndexOf() [1/2]

◆ IndexOf() [2/2]

◆ Insert() [1/2]

◆ Insert() [2/2]

◆ InsertScaledSpacing()

◆ InsertSpacing()

◆ InsertStretch()

◆ InsertUnscaledSpacing()

◆ IsHorizontal()

◆ IsVertical()

◆ LogicalPixelsToPhysical()

◆ Margin()

◆ Null()

◆ NumberOfItems()

◆ ParentControl()

◆ PhysicalPixelsToLogical()

◆ Remove() [1/2]

◆ Remove() [2/2]

◆ SetAlignment() [1/2]

◆ SetAlignment() [2/2]

◆ SetMargin()

◆ SetSpacing()

◆ SetStretchFactor() [1/2]

◆ SetStretchFactor() [2/2]

◆ Spacing()