краткое описание

#include <gtk/gtk.h>

            gtkprintoperation;
enum        gtkprintstatus;
enum        gtkprintoperationaction;
enum        gtkprintoperationresult;
enum        gtkprinterror;
#define     gtk_print_error
gtkprintoperation* gtk_print_operation_new  (void);
void        gtk_print_operation_set_allow_async

                                            (gtkprintoperation *op,
                                             gboolean allow_async);
void        gtk_print_operation_get_error   (gtkprintoperation *op,
                                             gerror **error);
void        gtk_print_operation_set_default_page_setup

                                            (gtkprintoperation *op,
                                             gtkpagesetup *default_page_setup);
gtkpagesetup* gtk_print_operation_get_default_page_setup
                                            (gtkprintoperation *op);
void        gtk_print_operation_set_print_settings

                                            (gtkprintoperation *op,
                                             gtkprintsettings *print_settings);
gtkprintsettings* gtk_print_operation_get_print_settings
                                            (gtkprintoperation *op);
void        gtk_print_operation_set_job_name

                                            (gtkprintoperation *op,
                                             const gchar *job_name);
void        gtk_print_operation_set_n_pages (gtkprintoperation *op,
                                             gint n_pages);
void        gtk_print_operation_set_current_page

                                            (gtkprintoperation *op,
                                             gint current_page);
void        gtk_print_operation_set_use_full_page
                                            (gtkprintoperation *op,
                                             gboolean full_page);
void        gtk_print_operation_set_unit    (gtkprintoperation *op,
                                             gtkunit unit);
void        gtk_print_operation_set_export_filename

                                            (gtkprintoperation *op,
                                             const gchar *filename);
void        gtk_print_operation_set_show_progress
                                            (gtkprintoperation *op,
                                             gboolean show_progress);
void        gtk_print_operation_set_track_print_status

                                            (gtkprintoperation *op,
                                             gboolean track_status);
void        gtk_print_operation_set_custom_tab_label
                                            (gtkprintoperation *op,
                                             const gchar *label);

gtkprintoperationresult gtk_print_operation_run
                                            (gtkprintoperation *op,
                                             gtkprintoperationaction action,
                                             gtkwindow *parent,
                                             gerror **error);
void        gtk_print_operation_cancel      (gtkprintoperation *op);

gtkprintstatus gtk_print_operation_get_status
                                            (gtkprintoperation *op);
const gchar* gtk_print_operation_get_status_string
                                            (gtkprintoperation *op);

gboolean    gtk_print_operation_is_finished (gtkprintoperation *op);
void        gtk_print_operation_get_error   (gtkprintoperation *op,
                                             gerror **error);

gtkpagesetup* gtk_print_run_page_setup_dialog
                                            (gtkwindow *parent,
                                             gtkpagesetup *page_setup,
                                             gtkprintsettings *settings);
void        (*gtkpagesetupdonefunc)         (gtkpagesetup *page_setup,
                                             gpointer data);
void        gtk_print_run_page_setup_dialog_async

                                            (gtkwindow *parent,
                                             gtkpagesetup *page_setup,
                                             gtkprintsettings *settings,
                                             gtkpagesetupdonefunc done_cb,
                                             gpointer data);

            gtkprintoperationpreview;
void        gtk_print_operation_preview_end_preview

                                            (gtkprintoperationpreview *preview);
gboolean    gtk_print_operation_preview_is_selected
                                            (gtkprintoperationpreview *preview,
                                             gint page_nr);
void        gtk_print_operation_preview_render_page

                                            (gtkprintoperationpreview *preview,
                                             gint page_nr);

иерархия объектов

  gobject

   +----gtkprintoperation

  ginterface
   +----gtkprintoperationpreview

предварительные требования

gtkprintoperationpreview требует gobject.

реализуемые интерфейсы

gtkprintoperation реализует gtkprintoperationpreview.

известные реализации

gtkprintoperationpreview реализован gtkprintoperation.

свойства

  "allow-async"          gboolean              : read / write
  "current-page"         gint                  : read / write
  "custom-tab-label"     gchararray            : read / write
  "default-page-setup"   gtkpagesetup          : read / write
  "export-filename"      gchararray            : read / write
  "job-name"             gchararray            : read / write
  "n-pages"              gint                  : read / write
  "print-settings"       gtkprintsettings      : read / write
  "show-progress"        gboolean              : read / write
  "status"               gtkprintstatus        : read
  "status-string"        gchararray            : read
  "track-print-status"   gboolean              : read / write
  "unit"                 gtkunit               : read / write
  "use-full-page"        gboolean              : read / write

сигналы

"begin-print"
            void        user_function      (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gpointer           user_data)      : run last
"create-custom-widget"
            gobject*    user_function      (gtkprintoperation *operation,
                                            gpointer           user_data)      : run last
"custom-widget-apply"
            void        user_function      (gtkprintoperation *operation,
                                            gtkwidget         *widget,
                                            gpointer           user_data)      : run last
"done"      void        user_function      (gtkprintoperation      *operation,
                                            gtkprintoperationresult result,
                                            gpointer                user_data)      : run last
"draw-page" void        user_function      (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gint               page_nr,
                                            gpointer           user_data)      : run last
"end-print" void        user_function      (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gpointer           user_data)      : run last
"paginate"  gboolean    user_function      (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gpointer           user_data)      : run last
"preview"   gboolean    user_function      (gtkprintoperation        *operation,
                                            gtkprintoperationpreview *preview,
                                            gtkprintcontext          *context,
                                            gtkwindow                *parent,
                                            gpointer                  user_data)      : run last
"request-page-setup"
            void        user_function      (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gint               page_nr,
                                            gtkpagesetup      *setup,
                                            gpointer           user_data)      : run last
"status-changed"
            void        user_function      (gtkprintoperation *operation,
                                            gpointer           user_data)      : run last

описание

gtkprintoperation – это высший уровень, портируемого api печати. он выглядит немного иначе чем другие диалоги gtk+, такие как gtkfilechooser, так как некоторые платформы не представляют достаточно инфраструктуры для реализации хороших диалогов печати. на таких платформах, gtkprintoperation использует родные диалоги печати. на платформах которые не обеспечивают родные диалоги печати, gtk+ использует собственный, смотрите gtkprintunixdialog.

обычный способ использования high-level printing api это создание объекта gtkprintoperation с помощью gtk_print_operation_new() когда пользователь выбирает печать. затем вы устанавливаете некоторые свойства, например размер страницы, любые gtkprintsettings из предварительных операций печати, количество страниц, текущую страницу, и т.д..

потом вы вызываете операцию печати используя gtk_print_operation_run(). она покажет пользователю диалог, позволяя выбрать принтер и опции. когда пользователь закончит, диалог издаст различные сигналы gtkprintoperation, основным из которых является ::draw-page, вы должны перехватить его и создать страницу обеспечивая gtkprintcontext используя cairo.

пример 1. the high-level printing api

static gtkprintsettings *settings = null;

static void
do_print (void)
{
  gtkprintoperation *print;
  gtkprintoperationresult res;

  print = gtk_print_operation_new ();

  if (settings != null) 
    gtk_print_operation_set_print_settings (print, settings);

  g_signal_connect (print, "begin_print", g_callback (begin_print), null);
  g_signal_connect (print, "draw_page", g_callback (draw_page), null);

  res = gtk_print_operation_run (print, gtk_print_operation_action_print_dialog,
                                 gtk_window (main_window), null);

  if (res == gtk_print_operation_result_apply)
    {
      if (settings != null)
        g_object_unref (settings);
      settings = g_object_ref (gtk_print_operation_get_print_settings (print));
    }

  g_object_unref (print);
}

по умолчанию gtkprintoperation использует внешние приложения для предварительного просмотра печатаемой страницы. для настройки предварительного просмотра печати приложение должно подключиться к сигналу предварительного просмотра. функции gtk_print_operation_print_preview_render_page(), gtk_print_operation_preview_end_preview() и gtk_print_operation_preview_is_selected() полезны при реализации предварительного просмотра.

печать поддерживается начиная с версии gtk+ 2.10.

детали

gtkprintoperation

typedef struct _gtkprintoperation gtkprintoperation;

enum gtkprintstatus

typedef enum {
  gtk_print_status_initial,
  gtk_print_status_preparing,
  gtk_print_status_generating_data,
  gtk_print_status_sending_data,
  gtk_print_status_pending,
  gtk_print_status_pending_issue,
  gtk_print_status_printing,
  gtk_print_status_finished,
  gtk_print_status_finished_aborted
} gtkprintstatus;

выдаёт состояние приблизительно указывая выполнение запущенной операции печати.

enum gtkprintoperationaction

typedef enum {
  gtk_print_operation_action_print_dialog,
  gtk_print_operation_action_print,
  gtk_print_operation_action_preview,
  gtk_print_operation_action_export
} gtkprintoperationaction;

параметр action в gtk_print_operation_run() определяет какое действие операции печати должно быть выполнено.

enum gtkprintoperationresult

typedef enum {
  gtk_print_operation_result_error,
  gtk_print_operation_result_apply,
  gtk_print_operation_result_cancel,
  gtk_print_operation_result_in_progress
} gtkprintoperationresult;

значение этого типа возвращается из gtk_print_operation_run().

enum gtkprinterror

typedef enum
{
  gtk_print_error_general,
  gtk_print_error_internal_error,
  gtk_print_error_nomem
} gtkprinterror;

gtk_print_error

#define gtk_print_error gtk_print_error_quark ()

gquark используется для gtkprinterror ошибок.

gtk_print_operation_new ()

gtkprintoperation* gtk_print_operation_new  (void);

создаёт новый gtkprintoperation.

начиная с версии 2.10

gtk_print_operation_set_allow_async ()

void        gtk_print_operation_set_allow_async
                                            (gtkprintoperation *op,
                                             gboolean allow_async);

устанавливает может ли gtk_print_operation_run() вернуть результат перед выполнением операции печати. помните, некоторые платформы не позволяют асинхронные операции.

начиная с версии 2.10

gtk_print_operation_get_error ()

void        gtk_print_operation_get_error   (gtkprintoperation *op,
                                             gerror **error);

эта функция вызывается когда результат операции печати равен gtk_print_operation_result_error, любой возвращаемой gtk_print_operation_run(), или в обработчике сигнала ::done. возвращаемый gerror должен содержать подробности произошедшего.

начиная с версии 2.10

gtk_print_operation_set_default_page_setup ()

void        gtk_print_operation_set_default_page_setup
                                            (gtkprintoperation *op,
                                             gtkpagesetup *default_page_setup);

делает default_page_setup параметрами страницы по умолчанию для op.

эта страница будет использована в gtk_print_operation_run(), но она может быть переписана на основании предварительной страницы подключением сигнала ::request-page-setup.

начиная с версии 2.10

gtk_print_operation_get_default_page_setup ()

gtkpagesetup* gtk_print_operation_get_default_page_setup
                                            (gtkprintoperation *op);

возвращает установки страницы по умолчанию, смотрите gtk_print_operation_set_default_page_setup().

начиная с версии 2.10

gtk_print_operation_set_print_settings ()

void        gtk_print_operation_set_print_settings
                                            (gtkprintoperation *op,
                                             gtkprintsettings *print_settings);

устанавливает настройки принтера для op. это обычно используется для пере-установки настроек принтера из предыдущей операции, смотрите gtk_print_operation_run().

начиная с версии 2.10

gtk_print_operation_get_print_settings ()

gtkprintsettings* gtk_print_operation_get_print_settings
                                            (gtkprintoperation *op);

возвращает текущие настройки принтера.

помните что возвращаемое значение null до тех пор пока не вызвана gtk_print_operation_set_print_settings() или gtk_print_operation_run().

начиная с версии 2.10

gtk_print_operation_set_job_name ()

void        gtk_print_operation_set_job_name
                                            (gtkprintoperation *op,
                                             const gchar *job_name);

устанавливает имя задания принтера. имя используется для идентификации задания (например в приложении контроля такой как eggcups).

если вы не установили имя задания, gtk+ выберет один из номеров последовательности заданий печати.

начиная с версии 2.10

gtk_print_operation_set_n_pages ()

void        gtk_print_operation_set_n_pages (gtkprintoperation *op,
                                             gint n_pages);

устанавливает количество страниц в документе.

должно устанавливаться в положительное значение перед началом представления страниц. может быть установлено обработчиком сигнала ::begin-print.

запомните, количество страниц помещаемое в ::request-page-setup и ::draw-page сигналы начинается с 0, то есть если пользователь выберет для печати все страницы, последний сигнал ::draw-page будет для страницы n_pages - 1.

начиная с версии 2.10

gtk_print_operation_set_current_page ()

void        gtk_print_operation_set_current_page
                                            (gtkprintoperation *op,
                                             gint current_page);

устанавливает текущую страницу.

если она вызвана перед gtk_print_operation_run(), пользователь сможет выбрать печать только текущемй страницы.

отметьте сто это имеет смысл только для документов предварительно разбитых постранично.

начиная с версии 2.10

gtk_print_operation_set_use_full_page ()

void        gtk_print_operation_set_use_full_page
                                            (gtkprintoperation *op,
                                             gboolean full_page);

если параметр full_page равен true, преобразует контекст gtkprintcontext в контекст cairo, помещая начало в верхний левый угол страницы (который может не быть верхним левым углом листа, зависит от ориентации страницы и номера страницы относительно листа). иначе, начало в левом верхнем углу изображаемой области (то есть в пределах границ).

начиная с версии 2.10

gtk_print_operation_set_unit ()

void        gtk_print_operation_set_unit    (gtkprintoperation *op,
                                             gtkunit unit);

устанавливает преобразование полученного gtkprintcontext в контекст cairo, таким образом что расстояние измеряется в единицах unit.

начиная с версии 2.10

gtk_print_operation_set_export_filename ()

void        gtk_print_operation_set_export_filename
                                            (gtkprintoperation *op,
                                             const gchar *filename);

устанавливает gtkprintoperation для генерации файла, вместо отображения диалога печати. эта функция используется для осуществления операции "export to pdf". в настоящее время, pdf единственный поддерживаемый формат.

"print to pdf" поддерживается независимо от этого, позволяя пользователю выбрать пункт "print to pdf" из списка принтеров в диалоге печати.

начиная с версии 2.10

gtk_print_operation_set_show_progress ()

void        gtk_print_operation_set_show_progress
                                            (gtkprintoperation *op,
                                             gboolean show_progress);

если параметр show_progress равен true, операция печати будет отображать диалог шкалы выполнения в процессе печати.

начиная с версии 2.10

gtk_print_operation_set_track_print_status ()

void        gtk_print_operation_set_track_print_status
                                            (gtkprintoperation *op,
                                             gboolean track_status);

если track_status равен true, операция печати будет пытаться сообщать статус задания печати в очереди печати и принтера. это позволит вашему приложению отображать такие сообщения как "закончилась бумага" или задание печати отправлено на принтер.

эта функция часто реализуется используя некоторую форму опроса, поэтому она не должна использоваться без явной необходимости.

начиная с версии 2.10

gtk_print_operation_set_custom_tab_label ()

void        gtk_print_operation_set_custom_tab_label
                                            (gtkprintoperation *op,
                                             const gchar *label);

устанавливает ярлык для вкладки содержащей виджеты настроек.

начиная с версии 2.10

gtk_print_operation_run ()

gtkprintoperationresult gtk_print_operation_run
                                            (gtkprintoperation *op,
                                             gtkprintoperationaction action,
                                             gtkwindow *parent,
                                             gerror **error);

выполняет операцию печати, сначала позволяя пользователю изменить настройки печати с помощью диалога, а затем печатает документ.

обычно эта функция не возвращается до тех пор пока не выполнит представление всех страниц. вы можете подключить сигнал ::status-changed к op для определения некоторой информации о процессе выполнения печати. кроме того, можно использовать рекурсию основного цикла (mainloop) для отображения диалога печати.

если вы вызвали gtk_print_operation_set_allow_async() или установили свойство позволяющее асинхронные операции (allow-async) то эта операция будет выполняться асинхронно, если позволяет платформа. сигнал ::done издаётся когда операция выполнена (то есть когда диалог прекращён, или когда печать прерывается ошибкой).

if (settings != null)
  gtk_print_operation_set_print_settings (print, settings);
  
if (page_setup != null)
  gtk_print_operation_set_default_page_setup (print, page_setup);
  
g_signal_connect (print, "begin-print", 
                  g_callback (begin_print), &data);
g_signal_connect (print, "draw-page", 
                  g_callback (draw_page), &data);
 
res = gtk_print_operation_run (print, gtk_print_operation_action_print_dialog, parent, &error);
 
if (res == gtk_print_operation_result_error)
 {
   error_dialog = gtk_message_dialog_new (gtk_window (parent),
                                             gtk_dialog_destroy_with_parent,
                                             gtk_message_error,
                                             gtk_buttons_close,
                                             "error printing file:\ns",
                                             error->message);
   g_signal_connect (error_dialog, "response", 
                     g_callback (gtk_widget_destroy), null);
   gtk_widget_show (error_dialog);
   g_error_free (error);
 }
else if (res == gtk_print_operation_result_apply)
 {
   if (settings != null)
g_object_unref (settings);
   settings = g_object_ref (gtk_print_operation_get_print_settings (print));
 }

начиная с версии 2.10

gtk_print_operation_cancel ()

void        gtk_print_operation_cancel      (gtkprintoperation *op);

прекращает запущенную операцию печати. эта функция может быть вызвана при начале печати, разбиении на страницы или при обработке сигнала draw-page для остановки текущемй выполняемой операции печати.

начиная с версии 2.10

gtk_print_operation_get_status ()

gtkprintstatus gtk_print_operation_get_status
                                            (gtkprintoperation *op);

определяет статус операции печати. смотрите также gtk_print_operation_get_status_string().

начиная с версии 2.10

gtk_print_operation_get_status_string ()

const gchar* gtk_print_operation_get_status_string
                                            (gtkprintoperation *op);

возвращает строку представляющую статус операции печати. строка преобразована и удобна для отображения состояния печати например в gtkstatusbar.

используйте gtk_print_operation_get_status() для определения значения статуса подходящего для программного использования.

начиная с версии 2.10

gtk_print_operation_is_finished ()

gboolean    gtk_print_operation_is_finished (gtkprintoperation *op);

удобная функция для определения закончилась ли операция печати успешно (gtk_print_status_finished) или нет (gtk_print_status_finished_aborted).

помните: когда вы позволяете отслеживание статуса операции печати, она может находиться в не завершённом состоянии даже после выполнения, так как статус операции отслеживает статус задания печати на принтере.

начиная с версии 2.10

gtk_print_operation_get_error ()

void        gtk_print_operation_get_error   (gtkprintoperation *op,
                                             gerror **error);

вызывается когда результат операции печати равен gtk_print_operation_result_error, любой возвращенный из gtk_print_operation_run(), или в обработчике сигнала ::done. возвращаемый gerror будет содержать подробности произошедшего.

начиная с версии 2.10

gtk_print_run_page_setup_dialog ()

gtkpagesetup* gtk_print_run_page_setup_dialog
                                            (gtkwindow *parent,
                                             gtkpagesetup *page_setup,
                                             gtkprintsettings *settings);

запускает диалог параметров страницы, позволяя пользователю изменять значения из page_setup. если пользователь отменил диалог, возвращаемый gtkpagesetup идентичен переданному в page_setup, иначе он содержит изменения сделанные с помощью диалога.

помните, эта функция может использовать рекурсию основного цикла (mainloop) для отображения диалога параметров страницы. смотрите gtk_print_run_page_setup_dialog_async() если это проблема.

начиная с версии 2.10

gtkpagesetupdonefunc ()

void        (*gtkpagesetupdonefunc)         (gtkpagesetup *page_setup,
                                             gpointer data);

тип функции помещаемой в gtk_print_run_page_setup_dialog_async(). эта функция вызывается когда диалог параметров страницы отключен, а так же служит как уведомление завершения для data.

gtk_print_run_page_setup_dialog_async ()

void        gtk_print_run_page_setup_dialog_async
                                            (gtkwindow *parent,
                                             gtkpagesetup *page_setup,
                                             gtkprintsettings *settings,
                                             gtkpagesetupdonefunc done_cb,
                                             gpointer data);

запускает диалог параметров страницы, позволяя пользователю изменять значения из page_setup.

в отличии от gtk_print_run_page_setup_dialog(), эта функция возвращается после отображения диалога параметров страницы на платформах которые это поддерживают, и вызывает done_cb из обработчика сигнала ::response диалога.

начиная с версии 2.10

gtkprintoperationpreview

typedef struct _gtkprintoperationpreview gtkprintoperationpreview;

gtk_print_operation_preview_end_preview ()

void        gtk_print_operation_preview_end_preview
                                            (gtkprintoperationpreview *preview);

завершает предварительный промотр.

эта функция должна вызываться для завершения выбранного предварительного просмотра печати.

начиная с версии 2.10

gtk_print_operation_preview_is_selected ()

gboolean    gtk_print_operation_preview_is_selected
                                            (gtkprintoperationpreview *preview,
                                             gint page_nr);

определяет включена ли данная страница в набор страниц которые выбраны для печати.

начиная с версии 2.10

gtk_print_operation_preview_render_page ()

void        gtk_print_operation_preview_render_page
                                            (gtkprintoperationpreview *preview,
                                             gint page_nr);

представляет страницу для предварительного просмотра, используя контекст печати который передаётся в обработчик gtkprintoperation::preview вместе с preview.

помните, этой функции требуется чтобы контекст cairo был связан с контекстом печати.

начиная с версии 2.10

детали свойств

свойство "allow-async"

  "allow-async"          gboolean              : read / write

определяет может ли операция печати выполняться в асинхронном режиме.

некоторые системы не поддерживают асинхронную печать, но те которые это делают, возвращают gtk_print_operation_result_in_progress как статус, и издают сигнал выполнено когда операция фактически выполнится.

windows порт не поддерживает асинхронные операции вообще (это вряд ли изменится). на других платформах, все действия за исключением gtk_print_operation_action_export поддерживают асинхронные операции.

значение по умолчанию: false

начиная с версии 2.10

свойство "current-page"

  "current-page"         gint                  : read / write

текущая страница в документе.

если установлена перед gtk_print_operation_run(), пользователь сможет выбрать только текущую страницу для печати.

помните, это имеет смысл только для документов предварительно разбитых на страницы.

допустимые значения: >= -1

значение по умолчанию: -1

начиная с версии 2.10

свойство "custom-tab-label"

  "custom-tab-label"     gchararray            : read / write

используется как ярлык вкладки содержащей виджеты настройки. это свойство может игнорироваться на некоторых платформах.

если оно равно null, gtk+ использует ярлык по умолчанию.

значение по умолчанию: null

начиная с версии 2.10

свойство "default-page-setup"

  "default-page-setup"   gtkpagesetup          : read / write

gtkpagesetup используемый по умолчанию.

эти настройки страницы используются в gtk_print_operation_run(), но они могут быть переписаны на основании предварительно установленной странице, подключив сигнал ::request-page-setup.

начиная с версии 2.10

свойство "export-filename"

  "export-filename"      gchararray            : read / write

имя файла для генерации вместо отображения диалога печати. в данный момент, поддерживается только формат pdf.

преднамеренное использование этого свойства реализуется действием "export to pdf".

"print to pdf" поддерживается, независимо от того установлено это свойство или нет, с помощью пункта меню "print to pdf" из списка принтеров в диалоге печати.

значение по умолчанию: null

начиная с версии 2.10

свойство "job-name"

  "job-name"             gchararray            : read / write

строка используемая для идентификации задания (например в приложениях контроля таких как eggcups).

если вы не установили имя задания, gtk+ выберет по умолчанию один из номеров последовательности заданий.

значение по умолчанию: ""

начиная с версии 2.10

свойство "n-pages"

  "n-pages"              gint                  : read / write

количество страниц в документе.

устанавливается в положительное число перед началом представления страниц. может быть установлено обработчиком сигнала ::begin-print.

помните, количество помещаемых сигналов ::request-page-setup и ::draw-page начинается с 0, то есть если пользователь выбрал печать всех страниц, последний сигнал ::draw-page будет для n_pages - 1.

допустимые значения: >= -1

значение по умолчанию: -1

начиная с версии 2.10

свойство "print-settings"

  "print-settings"       gtkprintsettings      : read / write

gtkprintsettings используемый для инициализации диалога.

установка этого свойства обычно используется для пере-установки параметров печати из предыдущей операции печати, смотрите gtk_print_operation_run().

начиная с версии 2.10

свойство "show-progress"

  "show-progress"        gboolean              : read / write

определяет показывается ли диалог выполнения в течении операции печати.

значение по умолчанию: false

начиная с версии 2.10

свойство "status"

  "status"               gtkprintstatus        : read

статус операции печати.

значение по умолчанию: gtk_print_status_initial

начиная с версии 2.10

свойство "status-string"

  "status-string"        gchararray            : read

строка представляющая статус операции. строка преобразуется для удобного отображения статуса печати, например в gtkstatusbar.

смотрите свойство ::status которое удобно для программного использования.

значение по умолчанию: ""

начиная с версии 2.10

свойство "track-print-status"

  "track-print-status"   gboolean              : read / write

если true, операция печати попытается сообщать статус задания печати в очереди принтера и печати. это позволяет вашему приложению отображать такие случаи как "закончилась бумага", и когда задание печати фактически отправлено на принтер. однако, это часто реализуется используя опрос и не должно задействоваться без особой необходимости.

значение по умолчанию: false

начиная с версии 2.10

свойство "unit"

  "unit"                 gtkunit               : read / write

преобразование в контекст cairo полученного из gtkprintcontext установленного таким образом что расстояния измеряются в единицах unit.

значение по умолчанию: gtk_unit_pixel

начиная с версии 2.10

свойство "use-full-page"

  "use-full-page"        gboolean              : read / write

если true, преобразование в контекст cairo полученного из gtkprintcontext помещает начало в верхний левый угол страницы (который может не быть верхним левым углом листа, в зависимости от ориентации страницы и количества страниц в листе). иначе, начало это верхний левый угол области изображения (то есть в пределах границ).

значение по умолчанию: false

начиная с версии 2.10

детали сигналов

сигнал "begin-print"

void        user_function                  (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gpointer           user_data)      : run last

издаётся после завершения настроек печати пользователем с помощью диалога, пред фактическим началом представления страниц.

обычное использование этого сигнала – это установка параметров из gtkprintcontext и разбиение на страницы соответственно, а затем установка количества страниц с помощью gtk_print_operation_set_n_pages().

начиная с версии 2.10

сигнал "create-custom-widget"

gobject*    user_function                  (gtkprintoperation *operation,
                                            gpointer           user_data)      : run last

издаётся при отображении диалога печати. если вы вернёте виджет в обработчик этого сигнала он будет добавлен во вкладку настройки диалога печати. обычно возвращается контейнер со множеством виджетов в нем.

возвращаемым виджетом владеет диалог печати, а время его существования контролирует приложение. однако, виджет гарантировано останется в течении издания сигнала custom-widget-apply в операции. тогда вы сможете прочесть вывод любой информации в которой нуждаетесь от виджетов.

начиная с версии 2.10

сигнал "custom-widget-apply"

void        user_function                  (gtkprintoperation *operation,
                                            gtkwidget         *widget,
                                            gpointer           user_data)      : run last

издаётся непосредственно перед началом печати, если вы добавили виджет настройки в обработчик create-custom-widget. когда вы получаете этот сигнал, вам нужно прочесть информацию из виджетов настройки, так как не гарантировано что она будет доступна длительное время.

начиная с версии 2.10

сигнал "done"

void        user_function                  (gtkprintoperation      *operation,
                                            gtkprintoperationresult result,
                                            gpointer                user_data)      : run last

издаётся когда операция печати завершила выполнять все запросы печати. result выдаёт вам информацию о произошедшем во время печати. если result это gtk_print_operation_result_error то для получения подробностей произошедшего можно вызвать gtk_print_operation_get_error().

если вы включили отслеживание состояния печати, то когда gtk_print_operation_is_finished() может продолжить возвращать false после издания этого сигнала.

начиная с версии 2.10

сигнал "draw-page"

void        user_function                  (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gint               page_nr,
                                            gpointer           user_data)      : run last

издаётся для каждой печатаемой страницы. обработчик сигнала должен представлять page_nr's страницу в контексте cairo полученном из context используя gtk_print_context_get_cairo_context().

static void
draw_page (gtkprintoperation *operation,
           gtkprintcontext   *context,
           gint               page_nr,
           gpointer           user_data)
{
  cairo_t *cr;
  pangolayout *layout;
  gdouble width, text_height;
  gint layout_height;
  pangofontdescription *desc;
  
  cr = gtk_print_context_get_cairo_context (context);
  width = gtk_print_context_get_width (context);
  
  cairo_rectangle (cr, 0, 0, width, header_height);
  
  cairo_set_source_rgb (cr, 0.8, 0.8, 0.8);
  cairo_fill (cr);
  
  layout = gtk_print_context_create_pango_layout (context);
  
  desc = pango_font_description_from_string ("sans 14");
  pango_layout_set_font_description (layout, desc);
  pango_font_description_free (desc);
  
  pango_layout_set_text (layout, "some text", -1);
  pango_layout_set_width (layout, width);
  pango_layout_set_alignment (layout, pango_align_center);
                      
  pango_layout_get_size (layout, null, &layout_height);
  text_height = (gdouble)layout_height / pango_scale;
  
  cairo_move_to (cr, width / 2,  (header_height - text_height) / 2);
  pango_cairo_show_layout (cr, layout);
  
  g_object_unref (layout);
}

используйте gtk_print_operation_set_use_full_page() и gtk_print_operation_set_unit() перед началом операции печати для преобразования в контекст cairo согласно вашим потребностям.

начиная с версии 2.10

сигнал "end-print"

void        user_function                  (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gpointer           user_data)      : run last

издаётся после представления всех страниц (rendered). обработчик сигнала может очистить любой ресурс который был распределён в обработчике ::begin-print.

начиная с версии 2.10

сигнал "paginate"

gboolean    user_function                  (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gpointer           user_data)      : run last

издаётся после сигнала begin-print, но перед фактическим началом представления страниц (rendering). издаётся пока не вернёт false.

этот сигнал предназначен для постраничного разбиения документа в небольших частях, избегая блокировки пользовательского интерфейса в течении длительного времени. обработчик сигнала должен обновлять количество страниц используя gtk_print_operation_set_n_pages(), и возвращать true если документ полностью разобран постранично.

если вам не нужно разбиение по частям, вы можете просто сделать всё в обработчике begin-print, и оттуда же установить количество страниц.

начиная с версии 2.10

сигнал "preview"

gboolean    user_function                  (gtkprintoperation        *operation,
                                            gtkprintoperationpreview *preview,
                                            gtkprintcontext          *context,
                                            gtkwindow                *parent,
                                            gpointer                  user_data)      : run last

издаётся при запросе предварительного просмотра из родного диалога.

обработчик по умолчанию для этого сигнала, использует внешнее приложение для предварительного просмотра печати.

для осуществления выбора предварительного просмотра печати, приложение должно вернуть true из этого обработчика сигнала. чтобы использовать поставляемый context для осуществления предварительного просмотра, нужно преобразовать в подходящий cairo контекст с помощью gtk_print_context_set_cairo_context().

реализованный предварительный просмотр может использовать gtk_print_operation_preview_is_selected() и gtk_print_operation_preview_render_page() для определения страниц которые выбраны для печати и представлять их. предварительный просмотр должен заканчиваться вызовом gtk_print_operation_preview_end_preview() (обычно в ответ на нажатие пользователем кнопки close).

начиная с версии 2.10

сигнал "request-page-setup"

void        user_function                  (gtkprintoperation *operation,
                                            gtkprintcontext   *context,
                                            gint               page_nr,
                                            gtkpagesetup      *setup,
                                            gpointer           user_data)      : run last

издаётся один раз для каждой печатаемой страницы, давая приложению возможность изменить параметры страницы. любые изменения выполненные для setup будут в силе только для печати этой страницы.

начиная с версии 2.10

сигнал "status-changed"

void        user_function                  (gtkprintoperation *operation,
                                            gpointer           user_data)      : run last

издаётся между различными фазами операции печати. смотрите gtkprintstatus описывающий различные фазы. используйте gtk_print_operation_get_status() для определения текущемго состояния.

начиная с версии 2.10

смотрите также

gtkprintcontext, gtkprintunixdialog