GtkPaperSize

GtkPaperSize — Support for named paper sizes

Object Hierarchy

    GBoxed
    ╰── GtkPaperSize

Includes

#include <gtk/gtk.h>

Description

GtkPaperSize handles paper sizes. It uses the standard called PWG 5101.1-2002 PWG: Standard for Media Standardized Names to name the paper sizes (and to get the data for the page sizes). In addition to standard paper sizes, GtkPaperSize allows to construct custom paper sizes with arbitrary dimensions.

The GtkPaperSize object stores not only the dimensions (width and height) of a paper size and its name, it also provides default print margins.

Functions

gtk_paper_size_new ()

GtkPaperSize *
gtk_paper_size_new (const char *name);

Creates a new GtkPaperSize object by parsing a PWG 5101.1-2002 paper name.

If name is NULL, the default paper size is returned, see gtk_paper_size_get_default().

Parameters

name

a paper size name, or NULL.

[allow-none]

Returns

a new GtkPaperSize, use gtk_paper_size_free() to free it


gtk_paper_size_new_from_ppd ()

GtkPaperSize *
gtk_paper_size_new_from_ppd (const char *ppd_name,
                             const char *ppd_display_name,
                             double width,
                             double height);

Creates a new GtkPaperSize object by using PPD information.

If ppd_name is not a recognized PPD paper name, ppd_display_name , width and height are used to construct a custom GtkPaperSize object.

Parameters

ppd_name

a PPD paper name

 

ppd_display_name

the corresponding human-readable name

 

width

the paper width, in points

 

height

the paper height in points

 

Returns

a new GtkPaperSize, use gtk_paper_size_free() to free it


gtk_paper_size_new_from_ipp ()

GtkPaperSize *
gtk_paper_size_new_from_ipp (const char *ipp_name,
                             double width,
                             double height);

Creates a new GtkPaperSize object by using IPP information.

If ipp_name is not a recognized paper name, width and height are used to construct a custom GtkPaperSize object.

Parameters

ipp_name

an IPP paper name

 

width

the paper width, in points

 

height

the paper height in points

 

Returns

a new GtkPaperSize, use gtk_paper_size_free() to free it


gtk_paper_size_new_custom ()

GtkPaperSize *
gtk_paper_size_new_custom (const char *name,
                           const char *display_name,
                           double width,
                           double height,
                           GtkUnit unit);

Creates a new GtkPaperSize object with the given parameters.

Parameters

name

the paper name

 

display_name

the human-readable name

 

width

the paper width, in units of unit

 

height

the paper height, in units of unit

 

unit

the unit for width and height . not GTK_UNIT_NONE.

 

Returns

a new GtkPaperSize object, use gtk_paper_size_free() to free it


gtk_paper_size_copy ()

GtkPaperSize *
gtk_paper_size_copy (GtkPaperSize *other);

Copies an existing GtkPaperSize.

Parameters

other

a GtkPaperSize

 

Returns

a copy of other


gtk_paper_size_free ()

void
gtk_paper_size_free (GtkPaperSize *size);

Free the given GtkPaperSize object.

Parameters

size

a GtkPaperSize

 

gtk_paper_size_is_equal ()

gboolean
gtk_paper_size_is_equal (GtkPaperSize *size1,
                         GtkPaperSize *size2);

Compares two GtkPaperSize objects.

Parameters

size1

a GtkPaperSize object

 

size2

another GtkPaperSize object

 

Returns

TRUE, if size1 and size2 represent the same paper size


gtk_paper_size_get_paper_sizes ()

GList *
gtk_paper_size_get_paper_sizes (gboolean include_custom);

Creates a list of known paper sizes.

Parameters

include_custom

whether to include custom paper sizes as defined in the page setup dialog

 

Returns

a newly allocated list of newly allocated GtkPaperSize objects.

[element-type GtkPaperSize][transfer full]


gtk_paper_size_get_name ()

const char *
gtk_paper_size_get_name (GtkPaperSize *size);

Gets the name of the GtkPaperSize.

Parameters

size

a GtkPaperSize object

 

Returns

the name of size


gtk_paper_size_get_display_name ()

const char *
gtk_paper_size_get_display_name (GtkPaperSize *size);

Gets the human-readable name of the GtkPaperSize.

Parameters

size

a GtkPaperSize object

 

Returns

the human-readable name of size


gtk_paper_size_get_ppd_name ()

const char *
gtk_paper_size_get_ppd_name (GtkPaperSize *size);

Gets the PPD name of the GtkPaperSize, which may be NULL.

Parameters

size

a GtkPaperSize object

 

Returns

the PPD name of size


gtk_paper_size_get_width ()

double
gtk_paper_size_get_width (GtkPaperSize *size,
                          GtkUnit unit);

Gets the paper width of the GtkPaperSize, in units of unit .

Parameters

size

a GtkPaperSize object

 

unit

the unit for the return value, not GTK_UNIT_NONE

 

Returns

the paper width


gtk_paper_size_get_height ()

double
gtk_paper_size_get_height (GtkPaperSize *size,
                           GtkUnit unit);

Gets the paper height of the GtkPaperSize, in units of unit .

Parameters

size

a GtkPaperSize object

 

unit

the unit for the return value, not GTK_UNIT_NONE

 

Returns

the paper height


gtk_paper_size_is_ipp ()

gboolean
gtk_paper_size_is_ipp (GtkPaperSize *size);

Returns TRUE if size is an IPP standard paper size.

Parameters

size

a GtkPaperSize object

 

Returns

whether size is not an IPP custom paper size.


gtk_paper_size_is_custom ()

gboolean
gtk_paper_size_is_custom (GtkPaperSize *size);

Returns TRUE if size is not a standard paper size.

Parameters

size

a GtkPaperSize object

 

Returns

whether size is a custom paper size.


gtk_paper_size_set_size ()

void
gtk_paper_size_set_size (GtkPaperSize *size,
                         double width,
                         double height,
                         GtkUnit unit);

Changes the dimensions of a size to width x height .

Parameters

size

a custom GtkPaperSize object

 

width

the new width in units of unit

 

height

the new height in units of unit

 

unit

the unit for width and height

 

gtk_paper_size_get_default_top_margin ()

double
gtk_paper_size_get_default_top_margin (GtkPaperSize *size,
                                       GtkUnit unit);

Gets the default top margin for the GtkPaperSize.

Parameters

size

a GtkPaperSize object

 

unit

the unit for the return value, not GTK_UNIT_NONE

 

Returns

the default top margin


gtk_paper_size_get_default_bottom_margin ()

double
gtk_paper_size_get_default_bottom_margin
                               (GtkPaperSize *size,
                                GtkUnit unit);

Gets the default bottom margin for the GtkPaperSize.

Parameters

size

a GtkPaperSize object

 

unit

the unit for the return value, not GTK_UNIT_NONE

 

Returns

the default bottom margin


gtk_paper_size_get_default_left_margin ()

double
gtk_paper_size_get_default_left_margin
                               (GtkPaperSize *size,
                                GtkUnit unit);

Gets the default left margin for the GtkPaperSize.

Parameters

size

a GtkPaperSize object

 

unit

the unit for the return value, not GTK_UNIT_NONE

 

Returns

the default left margin


gtk_paper_size_get_default_right_margin ()

double
gtk_paper_size_get_default_right_margin
                               (GtkPaperSize *size,
                                GtkUnit unit);

Gets the default right margin for the GtkPaperSize.

Parameters

size

a GtkPaperSize object

 

unit

the unit for the return value, not GTK_UNIT_NONE

 

Returns

the default right margin


gtk_paper_size_get_default ()

const char *
gtk_paper_size_get_default (void);

Returns the name of the default paper size, which depends on the current locale.

Returns

the name of the default paper size. The string is owned by GTK and should not be modified.


gtk_paper_size_new_from_key_file ()

GtkPaperSize *
gtk_paper_size_new_from_key_file (GKeyFile *key_file,
                                  const char *group_name,
                                  GError **error);

Reads a paper size from the group group_name in the key file key_file .

Parameters

key_file

the GKeyFile to retrieve the papersize from

 

group_name

the name of the group in the key file to read, or NULL to read the first group.

[nullable]

error

return location for an error, or NULL.

[allow-none]

Returns

a new GtkPaperSize object with the restored paper size, or NULL if an error occurred


gtk_paper_size_new_from_gvariant ()

GtkPaperSize *
gtk_paper_size_new_from_gvariant (GVariant *variant);

Deserialize a paper size from an a{sv} variant in the format produced by gtk_paper_size_to_gvariant().

Parameters

variant

an a{sv} GVariant

 

Returns

a new GtkPaperSize object.

[transfer full]


gtk_paper_size_to_key_file ()

void
gtk_paper_size_to_key_file (GtkPaperSize *size,
                            GKeyFile *key_file,
                            const char *group_name);

This function adds the paper size from size to key_file .

Parameters

size

a GtkPaperSize

 

key_file

the GKeyFile to save the paper size to

 

group_name

the group to add the settings to in key_file

 

gtk_paper_size_to_gvariant ()

GVariant *
gtk_paper_size_to_gvariant (GtkPaperSize *paper_size);

Serialize a paper size to an a{sv} variant.

Parameters

paper_size

a GtkPaperSize

 

Returns

a new, floating, GVariant.

[transfer none]

Types and Values

GtkPaperSize

typedef struct _GtkPaperSize GtkPaperSize;

enum GtkUnit

See also gtk_print_settings_set_paper_width().

Members

GTK_UNIT_NONE

No units.

 

GTK_UNIT_POINTS

Dimensions in points.

 

GTK_UNIT_INCH

Dimensions in inches.

 

GTK_UNIT_MM

Dimensions in millimeters

 

GTK_UNIT_PIXEL

#define GTK_UNIT_PIXEL GTK_UNIT_NONE

GTK_PAPER_NAME_A3

#define GTK_PAPER_NAME_A3 "iso_a3"

Name for the A3 paper size.


GTK_PAPER_NAME_A4

#define GTK_PAPER_NAME_A4 "iso_a4"

Name for the A4 paper size.


GTK_PAPER_NAME_A5

#define GTK_PAPER_NAME_A5 "iso_a5"

Name for the A5 paper size.


GTK_PAPER_NAME_B5

#define GTK_PAPER_NAME_B5 "iso_b5"

Name for the B5 paper size.


GTK_PAPER_NAME_LETTER

#define GTK_PAPER_NAME_LETTER "na_letter"

Name for the Letter paper size.


GTK_PAPER_NAME_EXECUTIVE

#define GTK_PAPER_NAME_EXECUTIVE "na_executive"

Name for the Executive paper size.


GTK_PAPER_NAME_LEGAL

#define GTK_PAPER_NAME_LEGAL "na_legal"

Name for the Legal paper size.

See Also

GtkPageSetup