Aspose::Words::ConvertUtil Class Reference

Detailed Description

Provides helper functions to convert between various measurement units.

Examples

Shows how to adjust paper size, orientation, margins, along with other settings for a section.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_PageSetup()->set_PaperSize(PaperSize::Legal);
builder->get_PageSetup()->set_Orientation(Orientation::Landscape);
builder->get_PageSetup()->set_TopMargin(ConvertUtil::InchToPoint(1.0));
builder->get_PageSetup()->set_BottomMargin(ConvertUtil::InchToPoint(1.0));
builder->get_PageSetup()->set_LeftMargin(ConvertUtil::InchToPoint(1.5));
builder->get_PageSetup()->set_RightMargin(ConvertUtil::InchToPoint(1.5));
builder->get_PageSetup()->set_HeaderDistance(ConvertUtil::InchToPoint(0.2));
builder->get_PageSetup()->set_FooterDistance(ConvertUtil::InchToPoint(0.2));
builder->Writeln(u"Hello world!");
doc->Save(ArtifactsDir + u"PageSetup.PageMargins.docx");

Shows how to specify page properties in inches.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// A section's "Page Setup" defines the size of the page margins in points.
// We can also use the "ConvertUtil" class to use a more familiar measurement unit,
// such as inches when defining boundaries.
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::InchToPoint(1.0));
pageSetup->set_BottomMargin(ConvertUtil::InchToPoint(2.0));
pageSetup->set_LeftMargin(ConvertUtil::InchToPoint(2.5));
pageSetup->set_RightMargin(ConvertUtil::InchToPoint(1.5));
// An inch is 72 points.
ASPOSE_ASSERT_EQ(72.0, ConvertUtil::InchToPoint(1));
ASPOSE_ASSERT_EQ(1.0, ConvertUtil::PointToInch(72));
// Add content to demonstrate the new margins.
builder->Writeln(
String::Format(u"This Text is {0} points/{1} inches from the left, ", pageSetup->get_LeftMargin(),
ConvertUtil::PointToInch(pageSetup->get_LeftMargin())) +
String::Format(u"{0} points/{1} inches from the right, ", pageSetup->get_RightMargin(), ConvertUtil::PointToInch(pageSetup->get_RightMargin())) +
String::Format(u"{0} points/{1} inches from the top, ", pageSetup->get_TopMargin(), ConvertUtil::PointToInch(pageSetup->get_TopMargin())) +
String::Format(u"and {0} points/{1} inches from the bottom of the page.", pageSetup->get_BottomMargin(),
ConvertUtil::PointToInch(pageSetup->get_BottomMargin())));
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndInches.docx");

#include <Aspose.Words.Cpp/ConvertUtil.h>

Public Member Functions

 ConvertUtil ()=delete
 

Static Public Member Functions

static double InchToPoint (double inches)
 Converts inches to points. More...
 
static double MillimeterToPoint (double millimeters)
 Converts millimeters to points. More...
 
static int32_t PixelToNewDpi (double pixels, double oldDpi, double newDpi)
 Converts pixels from one resolution to another. More...
 
static double PixelToPoint (double pixels)
 Converts pixels to points at 96 dpi. More...
 
static double PixelToPoint (double pixels, double resolution)
 Converts pixels to points at the specified pixel resolution. More...
 
static double PointToInch (double points)
 Converts points to inches. More...
 
static double PointToPixel (double points)
 Converts points to pixels at 96 dpi. More...
 
static double PointToPixel (double points, double resolution)
 Converts points to pixels at the specified pixel resolution. More...
 

Constructor & Destructor Documentation

◆ ConvertUtil()

Aspose::Words::ConvertUtil::ConvertUtil ( )
delete

Member Function Documentation

◆ InchToPoint()

static double Aspose::Words::ConvertUtil::InchToPoint ( double  inches)
static

Converts inches to points.

Parameters
inchesThe value to convert.
Examples

Shows how to adjust paper size, orientation, margins, along with other settings for a section.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_PageSetup()->set_PaperSize(PaperSize::Legal);
builder->get_PageSetup()->set_Orientation(Orientation::Landscape);
builder->get_PageSetup()->set_TopMargin(ConvertUtil::InchToPoint(1.0));
builder->get_PageSetup()->set_BottomMargin(ConvertUtil::InchToPoint(1.0));
builder->get_PageSetup()->set_LeftMargin(ConvertUtil::InchToPoint(1.5));
builder->get_PageSetup()->set_RightMargin(ConvertUtil::InchToPoint(1.5));
builder->get_PageSetup()->set_HeaderDistance(ConvertUtil::InchToPoint(0.2));
builder->get_PageSetup()->set_FooterDistance(ConvertUtil::InchToPoint(0.2));
builder->Writeln(u"Hello world!");
doc->Save(ArtifactsDir + u"PageSetup.PageMargins.docx");

Shows how to specify page properties in inches.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// A section's "Page Setup" defines the size of the page margins in points.
// We can also use the "ConvertUtil" class to use a more familiar measurement unit,
// such as inches when defining boundaries.
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::InchToPoint(1.0));
pageSetup->set_BottomMargin(ConvertUtil::InchToPoint(2.0));
pageSetup->set_LeftMargin(ConvertUtil::InchToPoint(2.5));
pageSetup->set_RightMargin(ConvertUtil::InchToPoint(1.5));
// An inch is 72 points.
ASPOSE_ASSERT_EQ(72.0, ConvertUtil::InchToPoint(1));
ASPOSE_ASSERT_EQ(1.0, ConvertUtil::PointToInch(72));
// Add content to demonstrate the new margins.
builder->Writeln(
String::Format(u"This Text is {0} points/{1} inches from the left, ", pageSetup->get_LeftMargin(),
ConvertUtil::PointToInch(pageSetup->get_LeftMargin())) +
String::Format(u"{0} points/{1} inches from the right, ", pageSetup->get_RightMargin(), ConvertUtil::PointToInch(pageSetup->get_RightMargin())) +
String::Format(u"{0} points/{1} inches from the top, ", pageSetup->get_TopMargin(), ConvertUtil::PointToInch(pageSetup->get_TopMargin())) +
String::Format(u"and {0} points/{1} inches from the bottom of the page.", pageSetup->get_BottomMargin(),
ConvertUtil::PointToInch(pageSetup->get_BottomMargin())));
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndInches.docx");

◆ MillimeterToPoint()

static double Aspose::Words::ConvertUtil::MillimeterToPoint ( double  millimeters)
static

Converts millimeters to points.

Parameters
millimetersThe value to convert.
Examples

Shows how to specify page properties in millimeters.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// A section's "Page Setup" defines the size of the page margins in points.
// We can also use the "ConvertUtil" class to use a more familiar measurement unit,
// such as millimeters when defining boundaries.
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::MillimeterToPoint(30));
pageSetup->set_BottomMargin(ConvertUtil::MillimeterToPoint(50));
pageSetup->set_LeftMargin(ConvertUtil::MillimeterToPoint(80));
pageSetup->set_RightMargin(ConvertUtil::MillimeterToPoint(40));
// A centimeter is approximately 28.3 points.
ASSERT_NEAR(28.34, ConvertUtil::MillimeterToPoint(10), 0.01);
// Add content to demonstrate the new margins.
builder->Writeln(String::Format(u"This Text is {0} points from the left, ", pageSetup->get_LeftMargin()) +
String::Format(u"{0} points from the right, ", pageSetup->get_RightMargin()) +
String::Format(u"{0} points from the top, ", pageSetup->get_TopMargin()) +
String::Format(u"and {0} points from the bottom of the page.", pageSetup->get_BottomMargin()));
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndMillimeters.docx");

◆ PixelToNewDpi()

static int32_t Aspose::Words::ConvertUtil::PixelToNewDpi ( double  pixels,
double  oldDpi,
double  newDpi 
)
static

Converts pixels from one resolution to another.

Parameters
pixelsThe value to convert.
oldDpiThe current dpi (dots per inch) resolution.
newDpiThe new dpi (dots per inch) resolution.
Examples

Shows how to use convert points to pixels with default and custom resolution.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Define the size of the top margin of this section in pixels, according to a custom DPI.
const double myDpi = 192;
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::PixelToPoint(100, myDpi));
ASSERT_NEAR(37.5, pageSetup->get_TopMargin(), 0.01);
// At the default DPI of 96, a pixel is 0.75 points.
ASPOSE_ASSERT_EQ(0.75, ConvertUtil::PixelToPoint(1));
builder->Writeln(
String::Format(u"This Text is {0} points/{1} ", pageSetup->get_TopMargin(), ConvertUtil::PointToPixel(pageSetup->get_TopMargin(), myDpi)) +
String::Format(u"pixels (at a DPI of {0}) from the top of the page.", myDpi));
// Set a new DPI and adjust the top margin value accordingly.
const double newDpi = 300;
pageSetup->set_TopMargin(ConvertUtil::PixelToNewDpi(pageSetup->get_TopMargin(), myDpi, newDpi));
ASSERT_NEAR(59.0, pageSetup->get_TopMargin(), 0.01);
builder->Writeln(String::Format(u"At a DPI of {0}, the text is now {1} points/{2} ", newDpi, pageSetup->get_TopMargin(),
ConvertUtil::PointToPixel(pageSetup->get_TopMargin(), myDpi)) +
u"pixels from the top of the page.");
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndPixelsDpi.docx");

◆ PixelToPoint() [1/2]

static double Aspose::Words::ConvertUtil::PixelToPoint ( double  pixels)
static

Converts pixels to points at 96 dpi.

Parameters
pixelsThe value to convert.
Examples

Shows how to specify page properties in pixels.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// A section's "Page Setup" defines the size of the page margins in points.
// We can also use the "ConvertUtil" class to use a different measurement unit,
// such as pixels when defining boundaries.
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::PixelToPoint(100));
pageSetup->set_BottomMargin(ConvertUtil::PixelToPoint(200));
pageSetup->set_LeftMargin(ConvertUtil::PixelToPoint(225));
pageSetup->set_RightMargin(ConvertUtil::PixelToPoint(125));
// A pixel is 0.75 points.
ASPOSE_ASSERT_EQ(0.75, ConvertUtil::PixelToPoint(1));
ASPOSE_ASSERT_EQ(1.0, ConvertUtil::PointToPixel(0.75));
// The default DPI value used is 96.
ASPOSE_ASSERT_EQ(0.75, ConvertUtil::PixelToPoint(1, 96));
// Add content to demonstrate the new margins.
builder->Writeln(
String::Format(u"This Text is {0} points/{1} pixels from the left, ", pageSetup->get_LeftMargin(),
ConvertUtil::PointToPixel(pageSetup->get_LeftMargin())) +
String::Format(u"{0} points/{1} pixels from the right, ", pageSetup->get_RightMargin(), ConvertUtil::PointToPixel(pageSetup->get_RightMargin())) +
String::Format(u"{0} points/{1} pixels from the top, ", pageSetup->get_TopMargin(), ConvertUtil::PointToPixel(pageSetup->get_TopMargin())) +
String::Format(u"and {0} points/{1} pixels from the bottom of the page.", pageSetup->get_BottomMargin(),
ConvertUtil::PointToPixel(pageSetup->get_BottomMargin())));
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndPixels.docx");

◆ PixelToPoint() [2/2]

static double Aspose::Words::ConvertUtil::PixelToPoint ( double  pixels,
double  resolution 
)
static

Converts pixels to points at the specified pixel resolution.

Parameters
pixelsThe value to convert.
resolutionThe dpi (dots per inch) resolution.
Examples

Shows how to use convert points to pixels with default and custom resolution.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Define the size of the top margin of this section in pixels, according to a custom DPI.
const double myDpi = 192;
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::PixelToPoint(100, myDpi));
ASSERT_NEAR(37.5, pageSetup->get_TopMargin(), 0.01);
// At the default DPI of 96, a pixel is 0.75 points.
ASPOSE_ASSERT_EQ(0.75, ConvertUtil::PixelToPoint(1));
builder->Writeln(
String::Format(u"This Text is {0} points/{1} ", pageSetup->get_TopMargin(), ConvertUtil::PointToPixel(pageSetup->get_TopMargin(), myDpi)) +
String::Format(u"pixels (at a DPI of {0}) from the top of the page.", myDpi));
// Set a new DPI and adjust the top margin value accordingly.
const double newDpi = 300;
pageSetup->set_TopMargin(ConvertUtil::PixelToNewDpi(pageSetup->get_TopMargin(), myDpi, newDpi));
ASSERT_NEAR(59.0, pageSetup->get_TopMargin(), 0.01);
builder->Writeln(String::Format(u"At a DPI of {0}, the text is now {1} points/{2} ", newDpi, pageSetup->get_TopMargin(),
ConvertUtil::PointToPixel(pageSetup->get_TopMargin(), myDpi)) +
u"pixels from the top of the page.");
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndPixelsDpi.docx");

◆ PointToInch()

static double Aspose::Words::ConvertUtil::PointToInch ( double  points)
static

Converts points to inches.

Parameters
pointsThe value to convert.
Examples

Shows how to specify page properties in inches.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// A section's "Page Setup" defines the size of the page margins in points.
// We can also use the "ConvertUtil" class to use a more familiar measurement unit,
// such as inches when defining boundaries.
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::InchToPoint(1.0));
pageSetup->set_BottomMargin(ConvertUtil::InchToPoint(2.0));
pageSetup->set_LeftMargin(ConvertUtil::InchToPoint(2.5));
pageSetup->set_RightMargin(ConvertUtil::InchToPoint(1.5));
// An inch is 72 points.
ASPOSE_ASSERT_EQ(72.0, ConvertUtil::InchToPoint(1));
ASPOSE_ASSERT_EQ(1.0, ConvertUtil::PointToInch(72));
// Add content to demonstrate the new margins.
builder->Writeln(
String::Format(u"This Text is {0} points/{1} inches from the left, ", pageSetup->get_LeftMargin(),
ConvertUtil::PointToInch(pageSetup->get_LeftMargin())) +
String::Format(u"{0} points/{1} inches from the right, ", pageSetup->get_RightMargin(), ConvertUtil::PointToInch(pageSetup->get_RightMargin())) +
String::Format(u"{0} points/{1} inches from the top, ", pageSetup->get_TopMargin(), ConvertUtil::PointToInch(pageSetup->get_TopMargin())) +
String::Format(u"and {0} points/{1} inches from the bottom of the page.", pageSetup->get_BottomMargin(),
ConvertUtil::PointToInch(pageSetup->get_BottomMargin())));
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndInches.docx");

◆ PointToPixel() [1/2]

static double Aspose::Words::ConvertUtil::PointToPixel ( double  points)
static

Converts points to pixels at 96 dpi.

Parameters
pointsThe value to convert.
Examples

Shows how to specify page properties in pixels.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// A section's "Page Setup" defines the size of the page margins in points.
// We can also use the "ConvertUtil" class to use a different measurement unit,
// such as pixels when defining boundaries.
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::PixelToPoint(100));
pageSetup->set_BottomMargin(ConvertUtil::PixelToPoint(200));
pageSetup->set_LeftMargin(ConvertUtil::PixelToPoint(225));
pageSetup->set_RightMargin(ConvertUtil::PixelToPoint(125));
// A pixel is 0.75 points.
ASPOSE_ASSERT_EQ(0.75, ConvertUtil::PixelToPoint(1));
ASPOSE_ASSERT_EQ(1.0, ConvertUtil::PointToPixel(0.75));
// The default DPI value used is 96.
ASPOSE_ASSERT_EQ(0.75, ConvertUtil::PixelToPoint(1, 96));
// Add content to demonstrate the new margins.
builder->Writeln(
String::Format(u"This Text is {0} points/{1} pixels from the left, ", pageSetup->get_LeftMargin(),
ConvertUtil::PointToPixel(pageSetup->get_LeftMargin())) +
String::Format(u"{0} points/{1} pixels from the right, ", pageSetup->get_RightMargin(), ConvertUtil::PointToPixel(pageSetup->get_RightMargin())) +
String::Format(u"{0} points/{1} pixels from the top, ", pageSetup->get_TopMargin(), ConvertUtil::PointToPixel(pageSetup->get_TopMargin())) +
String::Format(u"and {0} points/{1} pixels from the bottom of the page.", pageSetup->get_BottomMargin(),
ConvertUtil::PointToPixel(pageSetup->get_BottomMargin())));
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndPixels.docx");

◆ PointToPixel() [2/2]

static double Aspose::Words::ConvertUtil::PointToPixel ( double  points,
double  resolution 
)
static

Converts points to pixels at the specified pixel resolution.

Parameters
pointsThe value to convert.
resolutionThe dpi (dots per inch) resolution.
Examples

Shows how to use convert points to pixels with default and custom resolution.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Define the size of the top margin of this section in pixels, according to a custom DPI.
const double myDpi = 192;
SharedPtr<PageSetup> pageSetup = builder->get_PageSetup();
pageSetup->set_TopMargin(ConvertUtil::PixelToPoint(100, myDpi));
ASSERT_NEAR(37.5, pageSetup->get_TopMargin(), 0.01);
// At the default DPI of 96, a pixel is 0.75 points.
ASPOSE_ASSERT_EQ(0.75, ConvertUtil::PixelToPoint(1));
builder->Writeln(
String::Format(u"This Text is {0} points/{1} ", pageSetup->get_TopMargin(), ConvertUtil::PointToPixel(pageSetup->get_TopMargin(), myDpi)) +
String::Format(u"pixels (at a DPI of {0}) from the top of the page.", myDpi));
// Set a new DPI and adjust the top margin value accordingly.
const double newDpi = 300;
pageSetup->set_TopMargin(ConvertUtil::PixelToNewDpi(pageSetup->get_TopMargin(), myDpi, newDpi));
ASSERT_NEAR(59.0, pageSetup->get_TopMargin(), 0.01);
builder->Writeln(String::Format(u"At a DPI of {0}, the text is now {1} points/{2} ", newDpi, pageSetup->get_TopMargin(),
ConvertUtil::PointToPixel(pageSetup->get_TopMargin(), myDpi)) +
u"pixels from the top of the page.");
doc->Save(ArtifactsDir + u"UtilityClasses.PointsAndPixelsDpi.docx");