GtkPaperSize: GTK+ 3 Reference Manual

## GtkPaperSize GtkPaperSize — Support for named paper sizes |

## Functions

GtkPaperSize * | gtk_paper_size_new ()
GtkPaperSize * | gtk_paper_size_new_from_ppd ()
GtkPaperSize * | gtk_paper_size_new_from_ipp ()
GtkPaperSize * | gtk_paper_size_new_custom ()
GtkPaperSize * | gtk_paper_size_copy ()
void | gtk_paper_size_free ()
gboolean | gtk_paper_size_is_equal ()
GList * | gtk_paper_size_get_paper_sizes ()
const gchar * | gtk_paper_size_get_name ()
const gchar * | gtk_paper_size_get_display_name ()
const gchar * | gtk_paper_size_get_ppd_name ()
gdouble | gtk_paper_size_get_width ()
gdouble | gtk_paper_size_get_height ()
gboolean | gtk_paper_size_is_ipp ()
gboolean | gtk_paper_size_is_custom ()
void | gtk_paper_size_set_size ()
gdouble | gtk_paper_size_get_default_top_margin ()
gdouble | gtk_paper_size_get_default_bottom_margin ()
gdouble | gtk_paper_size_get_default_left_margin ()
gdouble | gtk_paper_size_get_default_right_margin ()
const gchar * | gtk_paper_size_get_default ()
GtkPaperSize * | gtk_paper_size_new_from_key_file ()
GtkPaperSize * | gtk_paper_size_new_from_gvariant ()
void | gtk_paper_size_to_key_file ()
GVariant * | gtk_paper_size_to_gvariant ()

## Types and Values

| GtkPaperSize
enum | GtkUnit
#define | GTK_UNIT_PIXEL
#define | GTK_PAPER_NAME_A3
#define | GTK_PAPER_NAME_A4
#define | GTK_PAPER_NAME_A5
#define | GTK_PAPER_NAME_B5
#define | GTK_PAPER_NAME_LETTER
#define | GTK_PAPER_NAME_EXECUTIVE
#define | GTK_PAPER_NAME_LEGAL

## 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.

Printing support has been added in GTK+ 2.10.

## Functions

### gtk_paper_size_new ()

    GtkPaperSize *
    gtk_paper_size_new (const gchar *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

Since: 2.10

### gtk_paper_size_new_from_ppd ()

    GtkPaperSize *
    gtk_paper_size_new_from_ppd (const gchar *ppd_name,
                                 const gchar *ppd_display_name,
                                 gdouble width,
                                 gdouble 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

Since: 2.10

### gtk_paper_size_new_from_ipp ()

    GtkPaperSize *
    gtk_paper_size_new_from_ipp (const gchar *ipp_name,
                                 gdouble width,
                                 gdouble 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

Since: 3.16

### gtk_paper_size_new_custom ()

    GtkPaperSize *
    gtk_paper_size_new_custom (const gchar *name,
                               const gchar *display_name,
                               gdouble width,
                               gdouble 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

Since: 2.10

### gtk_paper_size_copy ()

    GtkPaperSize *
    gtk_paper_size_copy (GtkPaperSize *other);

Copies an existing GtkPaperSize.

#### Parameters

other | a GtkPaperSize |

#### Returns

a copy of `other`

Since: 2.10

### gtk_paper_size_free ()

    void
    gtk_paper_size_free (GtkPaperSize *size);

Free the given GtkPaperSize object.

#### Parameters

size | a GtkPaperSize |

Since: 2.10

### 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

Since: 2.10

### 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]

Since: 2.12

### gtk_paper_size_get_name ()

    const gchar *
    gtk_paper_size_get_name (GtkPaperSize *size);

Gets the name of the GtkPaperSize.

#### Parameters

size | a GtkPaperSize object |

#### Returns

the name of `size`

Since: 2.10

### gtk_paper_size_get_display_name ()

    const gchar *
    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`

Since: 2.10

### gtk_paper_size_get_ppd_name ()

    const gchar *
    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`

Since: 2.10

### gtk_paper_size_get_width ()

    gdouble
    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

Since: 2.10

### gtk_paper_size_get_height ()

    gdouble
    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

Since: 2.10

### 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,
                             gdouble width,
                             gdouble 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` |

Since: 2.10

### gtk_paper_size_get_default_top_margin ()

    gdouble
    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

Since: 2.10

### gtk_paper_size_get_default_bottom_margin ()

    gdouble
    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

Since: 2.10

### gtk_paper_size_get_default_left_margin ()

    gdouble
    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

Since: 2.10

### gtk_paper_size_get_default_right_margin ()

    gdouble
    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

Since: 2.10

### gtk_paper_size_get_default ()

    const gchar *
    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.

Since: 2.10

### gtk_paper_size_new_from_key_file ()

    GtkPaperSize *
    gtk_paper_size_new_from_key_file (GKeyFile *key_file,
                                      const gchar *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

Since: 2.12

### 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]

Since: 3.22

### gtk_paper_size_to_key_file ()

    void
    gtk_paper_size_to_key_file (GtkPaperSize *size,
                                GKeyFile *key_file,
                                const gchar *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` |

Since: 2.12

### 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]

Since: 3.22

## 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