gtkprogressbar

			gtk+ reference manual
top \| description \| object hierarchy \| properties

gtkprogressbar — виджет визуально отображающий процесс выполнения

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

#include <gtk/gtk.h>


            gtkprogressbar;
gtkwidget*  gtk_progress_bar_new            (void);
void        gtk_progress_bar_pulse          (gtkprogressbar *pbar);
void        gtk_progress_bar_set_text       (gtkprogressbar *pbar,
                                             const gchar *text);
void        gtk_progress_bar_set_fraction   (gtkprogressbar *pbar,
                                             gdouble fraction);
void        gtk_progress_bar_set_pulse_step (gtkprogressbar *pbar,
                                             gdouble fraction);
void        gtk_progress_bar_set_orientation
                                            (gtkprogressbar *pbar,
                                             gtkprogressbarorientation orientation);
void        gtk_progress_bar_set_ellipsize  (gtkprogressbar *pbar,
                                             pangoellipsizemode mode);
enum        gtkprogressbarorientation;
const gchar* gtk_progress_bar_get_text      (gtkprogressbar *pbar);
gdouble     gtk_progress_bar_get_fraction   (gtkprogressbar *pbar);
gdouble     gtk_progress_bar_get_pulse_step (gtkprogressbar *pbar);
gtkprogressbarorientation gtk_progress_bar_get_orientation
                                            (gtkprogressbar *pbar);
pangoellipsizemode gtk_progress_bar_get_ellipsize
                                            (gtkprogressbar *pbar);
gtkwidget*  gtk_progress_bar_new_with_adjustment
                                            (gtkadjustment *adjustment);
void        gtk_progress_bar_set_bar_style  (gtkprogressbar *pbar,
                                             gtkprogressbarstyle style);
enum        gtkprogressbarstyle;
void        gtk_progress_bar_set_discrete_blocks
                                            (gtkprogressbar *pbar,
                                             guint blocks);
void        gtk_progress_bar_set_activity_step
                                            (gtkprogressbar *pbar,
                                             guint step);
void        gtk_progress_bar_set_activity_blocks
                                            (gtkprogressbar *pbar,
                                             guint blocks);
void        gtk_progress_bar_update         (gtkprogressbar *pbar,
                                             gdouble percentage);

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

  gobject
   +----ginitiallyunowned
         +----gtkobject
               +----gtkwidget
                     +----gtkprogress
                           +----gtkprogressbar

осуществляемый интерфейс

gtkprogressbar осуществляет atkimplementoriface.

свойства

  "activity-blocks"      guint                 : read / write
  "activity-step"        guint                 : read / write
  "adjustment"           gtkadjustment         : read / write
  "bar-style"            gtkprogressbarstyle   : read / write
  "discrete-blocks"      guint                 : read / write
  "ellipsize"            pangoellipsizemode    : read / write
  "fraction"             gdouble               : read / write
  "orientation"          gtkprogressbarorientation  : read / write
  "pulse-step"           gdouble               : read / write
  "text"                 gchararray            : read / write

описание

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

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

когда приложение не имеет возможности определить количество выполняемой работы, то можно использовать gtkprogressbar в активном режиме, который отображает активный блок передвигающийся из конца в конец шкалы выполнения. в этом режиме приложение должно периодически вызывать gtk_progress_bar_pulse() для обновления шкалы выполнения.

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

замечание

gtkprogressbar/gtkprogress api в gtk 1.2 был раздутый, неудобно запутанный и тяжелый в использовании. поэтому gtkprogress полностью устарел, а gtkprogressbar api сокращён до следующих 10 функций: gtk_progress_bar_new(), gtk_progress_bar_pulse(), gtk_progress_bar_set_text(), gtk_progress_bar_set_fraction(), gtk_progress_bar_set_pulse_step(), gtk_progress_bar_set_orientation(), gtk_progress_bar_get_text(), gtk_progress_bar_get_fraction(), gtk_progress_bar_get_pulse_step(), gtk_progress_bar_get_orientation(). они сгруппированы в начале этого раздела, сопровождаемые большим блоком устаревших функций совместимости с версией 1.2.

детали

gtkprogressbar

typedef struct _gtkprogressbar gtkprogressbar;

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

gtk_progress_bar_new ()

gtkwidget*  gtk_progress_bar_new            (void);

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

возвращает :

a gtkprogressbar.

gtk_progress_bar_pulse ()

void        gtk_progress_bar_pulse          (gtkprogressbar *pbar);

отображает некоторый процесс выполнения, но не определяя объём выполнения. вводит шкалу выполнения в "активный режим". каждый вызов gtk_progress_bar_pulse() заставляет блок немного перемещаться (количество перемещений за импульс определяется с помощью gtk_progress_bar_set_pulse_step()).

pbar :

gtkprogressbar

gtk_progress_bar_set_text ()

void        gtk_progress_bar_set_text       (gtkprogressbar *pbar,
                                             const gchar *text);

помещает полученный text на шкалу выполнения.

`pbar` :	gtkprogressbar
`text` :	строка utf-8

gtk_progress_bar_set_fraction ()

void        gtk_progress_bar_set_fraction   (gtkprogressbar *pbar,
                                             gdouble fraction);

заполняет шкалу выполнения на полученную долю (fraction) шкалы. доля(fraction) должна быть между 0.0 и 1.0 включительно.

`pbar` :	gtkprogressbar
`fraction` :	доля (fraction) выполненного процесса

gtk_progress_bar_set_pulse_step ()

void        gtk_progress_bar_set_pulse_step (gtkprogressbar *pbar,
                                             gdouble fraction);

устанавливает область от полной длины шкалы выполнения перемещаемым блоком для каждого вызова gtk_progress_bar_pulse().

`pbar` :	gtkprogressbar
`fraction` :	область между 0.0 и 1.0

gtk_progress_bar_set_orientation ()

void        gtk_progress_bar_set_orientation
                                            (gtkprogressbar *pbar,
                                             gtkprogressbarorientation orientation);

переключает ориентацию шкалы выполнения (слева-направо или справа-налево, сверху вниз или снизу вверх).

`pbar` :	gtkprogressbar
`orientation` :	направление шкалы выполнения

gtk_progress_bar_set_ellipsize ()

void        gtk_progress_bar_set_ellipsize  (gtkprogressbar *pbar,
                                             pangoellipsizemode mode);

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

`pbar` :	gtkprogressbar
`mode` :	pangoellipsizemode

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

enum gtkprogressbarorientation

typedef enum
{
  gtk_progress_left_to_right,
  gtk_progress_right_to_left,
  gtk_progress_bottom_to_top,
  gtk_progress_top_to_bottom
} gtkprogressbarorientation;

перечисление возможных направлений увеличения шкалы выполнения.

`gtk_progress_left_to_right`	горизонтальное увеличение слева-направо.
`gtk_progress_right_to_left`	горизонтальное увеличение справа-налево.
`gtk_progress_bottom_to_top`	вертикальное увеличение снизу вверх.
`gtk_progress_top_to_bottom`	вертикальное увеличение сверху вниз.

gtk_progress_bar_get_text ()

const gchar* gtk_progress_bar_get_text      (gtkprogressbar *pbar);

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

`pbar` :	gtkprogressbar
возвращает :	текст, или `null`; строкой владеет виджет и она не должна изменяться или освобождаться.

gtk_progress_bar_get_fraction ()

gdouble     gtk_progress_bar_get_fraction   (gtkprogressbar *pbar);

возвращает текущую долю выполненного задания.

`pbar` :	gtkprogressbar
возвращает :	доля в пределах от 0.0 до 1.0

gtk_progress_bar_get_pulse_step ()

gdouble     gtk_progress_bar_get_pulse_step (gtkprogressbar *pbar);

находит шаг пульсации установленный с помощью gtk_progress_bar_set_pulse_step()

`pbar` :	gtkprogressbar
возвращает :	доля в пределах от 0.0 до 1.0

gtk_progress_bar_get_orientation ()

gtkprogressbarorientation gtk_progress_bar_get_orientation
                                            (gtkprogressbar *pbar);

находит текущеме направление шкалы выполнения.

`pbar` :	gtkprogressbar
возвращает :	направление шкалы выполнения

gtk_progress_bar_get_ellipsize ()

pangoellipsizemode gtk_progress_bar_get_ellipsize
                                            (gtkprogressbar *pbar);

возвращает позицию замещения шкалы выполнения. смотрите gtk_progress_bar_set_ellipsize().

`pbar` :	gtkprogressbar
возвращает :	pangoellipsizemode

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

gtk_progress_bar_new_with_adjustment ()

gtkwidget*  gtk_progress_bar_new_with_adjustment
                                            (gtkadjustment *adjustment);

внимание

gtk_progress_bar_new_with_adjustment устарела и не должна использоваться во вновь создаваемом коде.

создаёт новый gtkprogressbar с ассоциированным gtkadjustment.

`adjustment` :	gtkadjustment.
возвращает :	gtkprogressbar.

gtk_progress_bar_set_bar_style ()

void        gtk_progress_bar_set_bar_style  (gtkprogressbar *pbar,
                                             gtkprogressbarstyle style);

внимание

gtk_progress_bar_set_bar_style устарела и не должна использоваться во вновь создаваемом коде.

устанавливает стиль gtkprogressbar. по умолчанию стиль gtk_progress_continuous.

`pbar` :	gtkprogressbar.
`style` :	gtkprogressbarstyle значение указывающее желаемый стиль.

enum gtkprogressbarstyle

typedef enum
{
  gtk_progress_continuous,
  gtk_progress_discrete
} gtkprogressbarstyle;

перечисление представляющее стиль отрисовки шкалы выполнения.

`gtk_progress_continuous`	шкала выполнения увеличивается гладким, непрерывным способом.
`gtk_progress_discrete`	шкала выполнения увеличивается отдельными блоками.

gtk_progress_bar_set_discrete_blocks ()

void        gtk_progress_bar_set_discrete_blocks
                                            (gtkprogressbar *pbar,
                                             guint blocks);

внимание

gtk_progress_bar_set_discrete_blocks устарела и не должна использоваться во вновь создаваемом коде.

устанавливает количество блоков из которого состоит шкала выполнения при стиле gtk_progress_discrete.

`pbar` :	gtkprogressbar.
`blocks` :	количество блоков составляющих шкалу выполнения.

gtk_progress_bar_set_activity_step ()

void        gtk_progress_bar_set_activity_step
                                            (gtkprogressbar *pbar,
                                             guint step);

внимание

gtk_progress_bar_set_activity_step устарела и не должна использоваться во вновь создаваемом коде.

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

`pbar` :	gtkprogressbar.
`step` :	количество увеличения в активном режиме.

gtk_progress_bar_set_activity_blocks ()

void        gtk_progress_bar_set_activity_blocks
                                            (gtkprogressbar *pbar,
                                             guint blocks);

внимание

gtk_progress_bar_set_activity_blocks устарела и не должна использоваться во вновь создаваемом коде.

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

`pbar` :	gtkprogressbar.
`blocks` :	число блоков используемое в шкале выполнения.

gtk_progress_bar_update ()

void        gtk_progress_bar_update         (gtkprogressbar *pbar,
                                             gdouble percentage);

внимание

gtk_progress_bar_update устарела и не должна использоваться во вновь создаваемом коде.

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

`pbar` :	gtkprogressbar.
`percentage` :	новое значение процентного выполнения.

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

свойство "`activity-blocks`"

  "activity-blocks"      guint                 : read / write

число блоков которым заполняется шкала в активном режиме (устарело).

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

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

свойство "`activity-step`"

  "activity-step"        guint                 : read / write

увеличение используемое при каждом повторении в активном режиме (устарело).

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

свойство "`adjustment`"

  "adjustment"           gtkadjustment         : read / write

gtkadjustment подключённый к шкале выполнения (устарело).

свойство "`bar-style`"

  "bar-style"            gtkprogressbarstyle   : read / write

конкретизирует визуальный стиль шкалы в процентном режиме (устарело).

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

свойство "`discrete-blocks`"

  "discrete-blocks"      guint                 : read / write

число раздельных блоков в шкале выполнения (когда отображается в раздельном стиле).

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

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

свойство "`ellipsize`"

  "ellipsize"            pangoellipsizemode    : read / write

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

помните что установка этого свойства в значение отличное от pango_ellipsize_none имеет побочный эффект шкалы выполнения требующий достаточного пространства только для отображения заменителя строки "...". другой способ для установки ширины шкалы выполнения - gtk_widget_set_size_request().

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

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

свойство "`fraction`"

  "fraction"             gdouble               : read / write

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

допустимые значения: [0,1]

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

свойство "`orientation`"

  "orientation"          gtkprogressbarorientation  : read / write

направление увеличения шкалы выполнения.

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

свойство "`pulse-step`"

  "pulse-step"           gdouble               : read / write

доля от полного выполнения процесса для пульсирующего перемещения в пределах шкалы.

допустимые значения: [0,1]

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

свойство "`text`"

  "text"                 gchararray            : read / write

текст отображаемый в шкале выполнения.

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

gtkprogressbar

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

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

осуществляемый интерфейс

свойства

описание

замечание

детали

gtkprogressbar

gtk_progress_bar_new ()

gtk_progress_bar_pulse ()

gtk_progress_bar_set_text ()

gtk_progress_bar_set_fraction ()

gtk_progress_bar_set_pulse_step ()

gtk_progress_bar_set_orientation ()

gtk_progress_bar_set_ellipsize ()

enum gtkprogressbarorientation

gtk_progress_bar_get_text ()

gtk_progress_bar_get_fraction ()

gtk_progress_bar_get_pulse_step ()

gtk_progress_bar_get_orientation ()

gtk_progress_bar_get_ellipsize ()

gtk_progress_bar_new_with_adjustment ()

внимание

gtk_progress_bar_set_bar_style ()

внимание

enum gtkprogressbarstyle

gtk_progress_bar_set_discrete_blocks ()

внимание

gtk_progress_bar_set_activity_step ()

внимание

gtk_progress_bar_set_activity_blocks ()

внимание

gtk_progress_bar_update ()

внимание

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

свойство "activity-blocks"

свойство "activity-step"

свойство "adjustment"

свойство "bar-style"

свойство "discrete-blocks"

свойство "ellipsize"

свойство "fraction"

свойство "orientation"

свойство "pulse-step"

свойство "text"

свойство "`activity-blocks`"

свойство "`activity-step`"

свойство "`adjustment`"

свойство "`bar-style`"

свойство "`discrete-blocks`"

свойство "`ellipsize`"

свойство "`fraction`"

свойство "`orientation`"

свойство "`pulse-step`"

свойство "`text`"