Prev

Up

Home

GTK+ Reference Manual

Next

Top  |  Description  |  Object Hierarchy  |  Properties

GtkProgressBar

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 %%"