PCL
User Interface Scaling Functions

Functions

double pcl::Control::DisplayPixelRatio () const
 
int pcl::Control::LogicalPixelsToPhysical (int size) const
 
int pcl::Control::LogicalPixelsToResource (int size) const
 
double pcl::Bitmap::PhysicalPixelRatio () const
 
int pcl::Control::PhysicalPixelsToLogical (int size) const
 
double pcl::Control::ResourcePixelRatio () const
 
int pcl::Control::ResourcePixelsToLogical (int size) const
 
Point pcl::Control::ScaledCursorHotSpot (const Point &hotSpot) const
 
Point pcl::Control::ScaledCursorHotSpot (int xHot, int yHot) const
 
template<class R >
String pcl::Control::ScaledResource (R resource) const
 
template<class S >
String pcl::Control::ScaledStyleSheet (S cssCode, int fontDPI=0) const
 
void pcl::Bitmap::SetPhysicalPixelRatio (double ratio)
 
double pcl::UIResourceScalingFactor (double scalingFactor)
 
double pcl::UIResourceScalingFactorForIndex (int index)
 
int pcl::UIResourceScalingIndex (double scalingFactor)
 
int pcl::UIScaled (double scalingFactor, int size)
 
template<class R >
String pcl::UIScaledResource (double scalingFactor, R resource)
 
template<class R >
String pcl::UIScaledResourceForIndex (int index, R resource)
 
template<class S >
String pcl::UIScaledStyleSheet (double displayScalingFactor, double resourceScalingFactor, S styleSheet, int fontDPI=0)
 
int pcl::UIUnscaled (double scalingFactor, int size)
 

Detailed Description

Function Documentation

◆ DisplayPixelRatio()

double pcl::Control::DisplayPixelRatio ( ) const

Returns the ratio between physical screen pixels and device-independent logical screen units for the parent top-level window of this Control object. This ratio is used as a scaling factor by the LogicalPixelsToPhysical() and PhysicalPixelsToLogical() functions, which are used internally by automatic size scaling member functions such as SetScaledFixedSize(), ScaledMinWidth(), etc.

The returned value is greater than or equal to one. Typical pixel ratios are 1.5 and 2.0 for high-density displays such as 4K and 5K monitors, respectively, or 1.0 for normal 96 dpi monitors.

On macOS, this function normally returns 1.0 for Retina displays working in high-dpi modes, since the operating system performs the conversion from logical to physical pixels automatically. The ResourcePixelRatio() member function returns the actual ratio between physical and logical screen pixels on macOS.

See also
LogicalPixelsToPhysical(), PhysicalPixelsToLogical(), ResourcePixelRatio()

◆ LogicalPixelsToPhysical()

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

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

See also
DisplayPixelRatio(), PhysicalPixelsToLogical(), LogicalPixelsToResource()

Definition at line 1470 of file Control.h.

References pcl::RoundInt().

◆ LogicalPixelsToResource()

int pcl::Control::LogicalPixelsToResource ( int  size) const
inline

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

The returned value corresponds to physical display device pixels on all supported operating systems and desktop managers.

See also
ResourcePixelRatio(), ResourcePixelsToLogical(), LogicalPixelsToPhysical()

Definition at line 1499 of file Control.h.

References pcl::RoundInt().

◆ PhysicalPixelRatio()

double pcl::Bitmap::PhysicalPixelRatio ( ) const

Returns the ratio between output device pixels and pixels of this device-independent bitmap. See the SetPhysicalPixelRatio() member function for a detailed description.

See also
SetPhysicalPixelRatio()

◆ PhysicalPixelsToLogical()

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

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

See also
DisplayPixelRatio(), LogicalPixelsToPhysical(), ResourcePixelsToLogical()

Definition at line 1483 of file Control.h.

References pcl::RoundInt().

◆ ResourcePixelRatio()

double pcl::Control::ResourcePixelRatio ( ) const

Returns the ratio between physical screen pixels and pixels of device-independent image resources reproduced on the parent top-level window of this Control object. This ratio is used as a scaling factor by the ScaledResource() member function.

The returned value is greater than or equal to one. Typical resource pixel ratios are 1.5 and 2.0 for high-density displays such as 4K and 5K monitors, respectively, 2.0 for Retina displays, or 1.0 for normal 96 dpi monitors.

On macOS with Retina monitors working in high-dpi modes, this function returns a value greater than one (typically 2.0), while DisplayPixelRatio() normally returns one by default. This is because in high-dpi modes, macOS works in logical display coordinates to represent text, control sizes and distances. However, image resources must be provided with pixel data in the physical screen resolution. On X11 and Windows platforms, where no automatic display scaling is performed, this member function is equivalent to DisplayPixelRatio().

Portable code should use the value returned by this member function to scale image resources drawn on controls, such as icons and bitmaps. The ScaledResource() function can be used to select the appropriate file paths from PixInsight core resources. The LogicalPixelsToResource() function can be used to calculate scaled dimensions of graphical elements generated dynamically from scalable resources, e.g. with Bitmap::FromSVGFile() and similar routines.

See also
LogicalPixelsToResource(), ResourcePixelsToLogical(), ScaledResource(), DisplayPixelRatio(),

◆ ResourcePixelsToLogical()

int pcl::Control::ResourcePixelsToLogical ( int  size) const
inline

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

See also
ResourcePixelRatio(), LogicalPixelsToResource(), PhysicalPixelsToLogical()

Definition at line 1512 of file Control.h.

References pcl::RoundInt().

◆ ScaledCursorHotSpot() [1/2]

Point pcl::Control::ScaledCursorHotSpot ( const Point hotSpot) const
inline

Returns a cursor hot spot point with coordinates scaled according to the physical display pixel ratio of this control.

This function is equivalent to:

ScaledCursorHotSpot( hotSpot.x, hotSpot.y );

Definition at line 1457 of file Control.h.

References pcl::GenericPoint< T >::x, and pcl::GenericPoint< T >::y.

◆ ScaledCursorHotSpot() [2/2]

Point pcl::Control::ScaledCursorHotSpot ( int  xHot,
int  yHot 
) const
inline

Returns a cursor hot spot point with coordinates scaled according to the physical display pixel ratio of this control.

Standard cursor images in PixInsight are scaled in a special way to guarantee that cursors always have a unique central pixel, irrespective of the applied display pixel ratios. This is functionally equivalent to ensure that cursors always have odd dimensions.

According to this rule, a standard cursor is a square image with the following dimensions in pixels:

21, 33, 43, 53, 63, 75, 85

respectively for the standard scaling ratios 1.0, 1.5, 2.0, 2.5, 3.0, 3.5 and 4.0. For dynamic cursors this function must be used to calculate scaled cursor hot spot coordinates, instead of simply scaling by multiplication with ResourcePixelRatio() and rounding. This also guarantees source code compatibility with future versions of PixInsight, where standard cursor dimensions might change.

See also
ResourcePixelRatio();

Definition at line 1441 of file Control.h.

References pcl::RoundInt().

◆ ScaledResource()

template<class R >
String pcl::Control::ScaledResource ( resource) const
inline

Returns the specified bitmap resource path adapted to be represented with the physical display pixel ratio of this control. Calling this function is equivalent to:

Example:

Dialog dlg;
Bitmap bmp( dlg.ScaledResource( ":/browser/enabled.png" ) );
See also
ResourcePixelRatio()

Definition at line 1340 of file Control.h.

◆ ScaledStyleSheet()

template<class S >
String pcl::Control::ScaledStyleSheet ( cssCode,
int  fontDPI = 0 
) const
inline

Returns a CSS source code fragment transformed with scaled dimensions in pixels and scaled resource file paths, and optionally point sizes converted to scaled pixel sizes.

Parameters
cssCodeA string containing the input CSS source code. The function will return a transformed version of this string.
fontDPIIf greater than zero, this is the font resolution, in dots per inch (dpi), for transformation of point sizes to scaled pixel sizes. If this parameter is zero (the default value), this routine will use the font resolution currently selected in core user preferences (which is the value of the "Application/FontResolution" global integer variable; see PixInsightSettings). If this parameter is a negative integer, no point-to-pixel conversions will be applied.

Calling this function is equivalent to:

Example:

Data_TreeBox.SetStyleSheet( ScaledStyleSheet(
"QTreeView {"
" font-family: DejaVu Sans Mono, Monospace;"
" font-size: 10pt;"
" background-image: url(:/image-window/transparent.png);"
"}"
"QTreeView::item {"
" padding: 4px 8px 4px 8px;"
"}"
"QHeaderView::section {"
" padding: 2px 8px 2px 8px;"
"}"
) );

If the display and resource pixel ratios of Data_TreeBox were 1.5 (for example, on a 4K monitor), and the current font resolution were 100 dpi, the code above would be equivalent to:

Data_TreeBox.SetStyleSheet(
"QTreeView {"
" font-family: DejaVu Sans Mono, Monospace;"
" font-size: 21px;"
" background-image: url(:/image-window/1.5/transparent.png);"
"}"
"QTreeView::item {"
" padding: 6px 12px 6px 12px;"
"}"
"QHeaderView::section {"
" padding: 3px 12px 3px 12px;"
"}"
);
See also
DisplayPixelRatio(), ResourcePixelRatio(), ScaledResource()

Definition at line 1412 of file Control.h.

◆ SetPhysicalPixelRatio()

void pcl::Bitmap::SetPhysicalPixelRatio ( double  ratio)

Sets the ratio between output device pixels and pixels of this device-independent bitmap. This ratio is used as a scaling factor by core bitmap rendering routines to reproduce bitmaps on high-dpi screens and other high-density graphics output devices.

The specified ratio must be greater than or equal to one. On macOS with Retina monitors working in high-dpi modes, this function can be used to ensure that a bitmap will be reproduced as a high-resolution image by setting its output pixel ratio to 2.0. In such case the bitmap will be drawn on the screen with one half its actual pixel dimensions in logical pixels, using the native physical monitor resoluton. On other platforms such as X11 (Linux and FreeBSD) and Windows, where no automatic display scaling is performed, the physical pixel ratio of a bitmap is ignored.

See also
PhysicalPixelRatio()

◆ UIResourceScalingFactor()

double pcl::UIResourceScalingFactor ( double  scalingFactor)
inline

Returns the resource scaling factor corresponding to the specified display scaling factor.

A display scaling factor is the ratio of physical device pixels to device-independent logical pixel units for a particular control or resource. A resource scaling factor has the same definition, but is constrained to the finite set {1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0}.

On the PixInsight platform, the reference display density is 109 dpi, corresponding to a 27-inch monitor at QHD resolution (2560x1440 physical display pixels). This density corresponds to a display/resource scaling factor of 1.0.

Definition at line 114 of file UIScaling.h.

References pcl::UIResourceScalingIndex().

◆ UIResourceScalingFactorForIndex()

double pcl::UIResourceScalingFactorForIndex ( int  index)
inline

Returns the resource scaling factor corresponding to the specified resource scaling index.

Resource scaling indexes pertain to the set {0,1,2,3,4,5,6}, respectively for the resource scaling factors {1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0}.

On the PixInsight platform, the reference display density is 109 dpi, corresponding to a 27-inch monitor at QHD resolution (2560x1440 physical display pixels). This density corresponds to a display/resource scaling factor of 1.0 and a zero resource scaling index.

Definition at line 133 of file UIScaling.h.

References pcl::Range().

◆ UIResourceScalingIndex()

int pcl::UIResourceScalingIndex ( double  scalingFactor)
inline

Returns the resource scaling index corresponding to the specified resource scaling factor.

Resource scaling indexes pertain to the set {0,1,2,3,4,5,6}, respectively for the resource scaling factors {1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0}.

Definition at line 87 of file UIScaling.h.

References pcl::Min(), and pcl::RoundInt().

Referenced by pcl::UIResourceScalingFactor().

◆ UIScaled()

int pcl::UIScaled ( double  scalingFactor,
int  size 
)
inline

Applies the specified scaling factor to convert size from device-independent logical pixel units to physical device pixels. The returned value is always rounded to the nearest integer.

Definition at line 145 of file UIScaling.h.

References pcl::RoundInt().

◆ UIScaledResource()

template<class R >
String pcl::UIScaledResource ( double  scalingFactor,
resource 
)
inline

Returns a user interface resource path corresponding to the specified resource path scaled for the specified resource scaling factor.

For example, if this function is called as follows:

UIScaledResourceForIndex( 1.47, "/:icons/pencil.png" );

the returned string will be "/:icons/1.5/pencil.png" for a resource scaling factor of 1.5.

Definition at line 203 of file UIScaling.h.

◆ UIScaledResourceForIndex()

template<class R >
String pcl::UIScaledResourceForIndex ( int  index,
resource 
)
inline

Returns a user interface resource path corresponding to the specified resource path scaled for the specified resource scaling index.

For example, if this function is called as follows:

UIScaledResourceForIndex( 3, "/:icons/delete.png" );

the returned string will be "/:icons/2.5/delete.png" for a resource scaling factor of 2.5.

Definition at line 176 of file UIScaling.h.

◆ UIScaledStyleSheet()

template<class S >
String pcl::UIScaledStyleSheet ( double  displayScalingFactor,
double  resourceScalingFactor,
styleSheet,
int  fontDPI = 0 
)

Returns a CSS source code string transformed with scaled dimensions in pixels and scaled resource file paths, and optionally font sizes in points converted to scaled pixels.

Parameters
displayScalingFactorThe display scaling factor that will be applied to scale pixel dimensions and (optionally) font sizes.
resourceScalingFactorThe resource scaling factor that will be applied to select bitmap resources.
styleSheetA string containing valid input CSS source code. The function will return a transformed version of this string.
fontDPIIf greater than zero, this is the font resolution, in dots per inch (dpi), for transformation of point sizes to scaled pixel sizes. If this parameter is zero (the default value), this routine will use the font resolution currently selected in core user preferences (which is the value of the "Application/FontResolution" global integer variable; see PixInsightSettings). If this parameter is a negative integer, no point-to-pixel conversions will be applied.

See Control::ScaledStyleSheet() for a detailed example.

Definition at line 259 of file UIScaling.h.

◆ UIUnscaled()

int pcl::UIUnscaled ( double  scalingFactor,
int  size 
)
inline

Applies the specified scaling factor to convert size from physical device pixels to device-independent logical pixel units. The returned value is always rounded to the nearest integer.

Definition at line 157 of file UIScaling.h.

References pcl::RoundInt().

pcl::Control::DisplayPixelRatio
double DisplayPixelRatio() const
pcl::Control::ResourcePixelRatio
double ResourcePixelRatio() const
pcl::UIScaledResourceForIndex
String UIScaledResourceForIndex(int index, R resource)
Definition: UIScaling.h:176
pcl::Control::ScaledStyleSheet
String ScaledStyleSheet(S cssCode, int fontDPI=0) const
Definition: Control.h:1412
pcl::Control::ScaledCursorHotSpot
Point ScaledCursorHotSpot(int xHot, int yHot) const
Definition: Control.h:1441
pcl::UIScaledStyleSheet
String UIScaledStyleSheet(double displayScalingFactor, double resourceScalingFactor, S styleSheet, int fontDPI=0)
Definition: UIScaling.h:259
pcl::UIScaledResource
String UIScaledResource(double scalingFactor, R resource)
Definition: UIScaling.h:203