path: root/docs/reference/pygtk-gtkprogressbar.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkprogressbar">
  <refnamediv>
    <refname>gtk.ProgressBar</refname>
    <refpurpose>a widget which indicates progress visually.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.ProgressBar</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkprogress">gtk.Progress</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkprogressbar">gtk.ProgressBar</link></methodname>
	<methodparam></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--pulse">pulse</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--set-text">set_text</link></methodname>
	<methodparam><parameter
		       role="keyword">text</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--set-fraction">set_fraction</link></methodname>
	<methodparam><parameter
		       role="keyword">fraction</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--set-pulse-step">set_pulse_step</link></methodname>
	<methodparam><parameter
		       role="keyword">fraction</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--set-orientation">set_orientation</link></methodname>
	<methodparam><parameter
		       role="keyword">orientation</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--get-text">get_text</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--get-fraction">get_fraction</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--get-pulse-step">get_pulse_step</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--get-orientation">get_orientation</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--set-ellipsize">set_ellipsize</link></methodname>
	<methodparam><parameter
		       role="keyword">mode</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkprogressbar--get-ellipsize">get_ellipsize</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkprogress">gtk.Progress</link>
        +-- <link linkend="class-gtkprogressbar">gtk.ProgressBar</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkprogressbar"><classname>gtk.ProgressBar</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkprogressbar">
    <title>gtk.ProgressBar Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkprogress">gtk.Progress Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

        <row valign="top">
          <entry>"discrete-blocks"</entry>
          <entry>Read-Write</entry>
          <entry>The number of discrete blocks in a progress bar (when shown
          in the discrete style)</entry>
        </row>

        <row valign="top">
          <entry>"ellipsize"</entry>
          <entry>Read-Write</entry>
          <entry>The preferred place to ellipsize the string, if the
          progressbar does not have enough room to display the entire
          string, specified as one of the <xref
          linkend="pango-ellipsize-mode-constants"
          endterm="pango-ellipsize-mode-constants-title"></xref>.  Note that
          setting this property to a value other than
          <literal>pango.ELLIPSIZE_NONE</literal> has the side-effect that
          the progressbar requests only enough space to display the ellipsis
          "...". Another means to set a progressbar's width is the <link
          linkend="method-gtkwidget--set-size-request"><methodname>gtk.Widget.set_size_request()</methodname></link>.
          This property is available in GTK+ 2.6 and above.</entry>
        </row>

	    <row valign="top">
	      <entry>"fraction"</entry>
	      <entry>Read-Write</entry>
	      <entry>The fraction of total work that has been completed</entry>
	    </row>

	    <row valign="top">
	      <entry>"orientation"</entry>
	      <entry>Read-Write</entry>
	      <entry>The orientation and growth direction of the progress
bar - one of the <xref
linkend="gtk-progressbar-orientation-constants"
endterm="gtk-progressbar-orientation-constants-title"></xref>:
<literal>gtk.PROGRESS_LEFT_TO_RIGHT</literal>,
<literal>gtk.PROGRESS_RIGHT_TO_LEFT</literal>,
<literal>gtk.PROGRESS_BOTTOM_TO_TOP</literal>,
<literal>gtk.PROGRESS_TOP_TO_BOTTOM</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"pulse-step"</entry>
	      <entry>Read-Write</entry>
	      <entry>The fraction of total progress to move the bouncing
block when pulsed</entry>
	    </row>

	    <row valign="top">
	      <entry>"text"</entry>
	      <entry>Read-Write</entry>
	      <entry>The text to be displayed in the progress bar</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkprogressbar">
    <title>gtk.ProgressBar Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
    
    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"min-horizontal-bar-height"</entry>
	      <entry>Read</entry>
	      <entry>
		Minimum horizontal height of the progress bar.
		Allowed values: >= 1. Default value: 20.
		Available in GTK+ 2.14 and above.
	      </entry>
	    </row>

	    <row valign="top">
	      <entry>"min-horizontal-bar-width"</entry>
	      <entry>Read</entry>
	      <entry>
		The minimum horizontal width of the progress bar.
		Allowed values: >= 1. Default value: 150.
		Available in GTK+ 2.14 and above.
	      </entry>
	    </row>

	    <row valign="top">
	      <entry>"min-vertical-bar-height"</entry>
	      <entry>Read</entry>
	      <entry>
		The minimum vertical height of the progress bar.
		Allowed values: >= 1. Default value: 80.
		Available in GTK+ 2.14 and above.
	      </entry>
	    </row>

	    <row valign="top">
	      <entry>"min-vertical-bar-width"</entry>
	      <entry>Read</entry>
	      <entry>
		The minimum vertical width of the progress bar.
		Allowed values: >= 1. Default value: 22.
		Available in GTK+ 2.14 and above.
	      </entry>
	    </row>

	    <row valign="top">
	      <entry>"xspacing"</entry>
	      <entry>Read</entry>
	      <entry>
		Extra spacing applied to the width of a progress bar.
		Allowed values: >= 0. Default value: 7.
	      </entry>
	    </row>

	    <row valign="top">
	      <entry>"yspacing"</entry>
	      <entry>Read</entry>
	      <entry>
		Extra spacing applied to the width of a progress bar.
		Allowed values: >= 0. Default value: 7.
	      </entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>
  </refsect1>

  <refsect1 id="signal-prototypes-gtkprogressbar">
    <title>gtk.ProgressBar Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkprogressbar"><classname>gtk.ProgressBar</classname></link>
is typically used to display the progress of a long running operation. It
provides a visual clue that processing is underway. The <link
linkend="class-gtkprogressbar"><classname>gtk.ProgressBar</classname></link>
can be used in two different modes: percentage mode and activity
mode.</para>

    <para>When an application can determine how much work needs to take
place (e.g. read a fixed number of bytes from a file) and can monitor its
progress, it can use the <link
linkend="class-gtkprogressbar"><classname>gtk.ProgressBar</classname></link>
in percentage mode and the user sees a growing bar indicating the percentage
of the work that has been completed. In this mode, the application is
required to call the <link
linkend="method-gtkprogressbar--set-fraction"><methodname>set_fraction</methodname>()</link> 
method periodically to update the progress bar.</para>

    <para>When an application has no accurate way of knowing the amount of
work to do, it can use the <link
linkend="class-gtkprogressbar"><classname>gtk.ProgressBar</classname></link>
in activity mode, which shows activity by a block moving back and forth
within the progress area. In this mode, the application is required to call
the <link
linkend="method-gtkprogressbar--pulse"><methodname>pulse</methodname>()</link> 
method periodically to update the progress bar.</para>

    <para>There is quite a bit of flexibility provided to control the
appearance of the <link
linkend="class-gtkprogressbar"><classname>gtk.ProgressBar</classname></link>. 
Methods are provided to control the orientation of the bar, optional text
can be displayed along with the bar, and the step size used in activity mode
can be set.</para>

  </refsect1>

  <refsect1 id="constructor-gtkprogressbar">
    <title>Constructor</title>

<programlisting><constructorsynopsis language="python">
    <methodname>gtk.ProgressBar</methodname>
    <methodparam></methodparam>
  </constructorsynopsis></programlisting>
  <variablelist>
    <varlistentry>
      <term><emphasis>Returns</emphasis>&nbsp;:</term>
      <listitem><simpara>a new <link
linkend="class-gtkprogressbar"><classname>gtk.ProgressBar</classname></link>
widget</simpara></listitem>
    </varlistentry>
  </variablelist>

    <para>Creates a new <link
linkend="class-gtkprogressbar"><classname>gtk.Progressbar</classname></link>
widget.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkprogressbar--pulse">
      <title>gtk.ProgressBar.pulse</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>pulse</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>pulse</methodname>() method nudges the
progressbar to indicate that some progress has been made, but you don't know
how much. This method also changes progress bar mode to "activity mode,"
where a block bounces back and forth. Each call to the <link
linkend="method-gtkprogressbar--pulse"><methodname>pulse</methodname>()</link> 
method causes the block to move by a little bit (the amount of movement per
pulse is determined by the <link
linkend="method-gtkprogressbar--set-pulse-step"><methodname>set_pulse_step</methodname>()</link> 
method).</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--set-text">
      <title>gtk.ProgressBar.set_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_text</methodname>
	  <methodparam><parameter
			 role="keyword">text</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">text</parameter>&nbsp;:</term>
	  <listitem><simpara>a UTF-8 string</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_text</methodname>() method superimposes the
text specified by <parameter>text</parameter> on the progress bar.</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--set-fraction">
      <title>gtk.ProgressBar.set_fraction</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_fraction</methodname>
	  <methodparam><parameter
			 role="keyword">fraction</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">fraction</parameter>&nbsp;:</term>
	  <listitem><simpara>the fraction of the task that's been
completed</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_fraction</methodname>() method causes the
progress bar to "fill in" the portion of the bar specified by
<parameter>fraction</parameter>. The value of
<parameter>fraction</parameter> should be between 0.0 and 1.0.</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--set-pulse-step">
      <title>gtk.ProgressBar.set_pulse_step</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_pulse_step</methodname>
	  <methodparam><parameter
			 role="keyword">fraction</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">fraction</parameter>&nbsp;:</term>
	  <listitem><simpara>a value between 0.0 and
1.0</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_pulse_step</methodname>() method sets the
portion (specified by <parameter>fraction</parameter>) of the total progress
bar length to move the bouncing block for each call to the <link
linkend="method-gtkprogressbar--pulse"><methodname>pulse</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--set-orientation">
      <title>gtk.ProgressBar.set_orientation</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_orientation</methodname>
	  <methodparam><parameter
			 role="keyword">orientation</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">orientation</parameter>&nbsp;:</term>
	  <listitem><simpara>the orientation of the progress
bar</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_orientation</methodname>() method switches
the progress bar to a different orientation as specified by the value of
<parameter>orientation</parameter>. The value of
<parameter>orientation</parameter> must be one of the <xref
linkend="gtk-progressbar-orientation-constants"
endterm="gtk-progressbar-orientation-constants-title"></xref>.</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--get-text">
      <title>gtk.ProgressBar.get_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_text</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the text, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_text</methodname>() method returns the text
superimposed on the progress bar. If there is no superimposed text this
method returns <literal>None</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--get-fraction">
      <title>gtk.ProgressBar.get_fraction</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_fraction</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a fraction from 0.0 to 1.0</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_fraction</methodname>() method returns the
current fraction of the task that's been set by the <link
linkend="method-gtkprogressbar--set-fraction"><methodname>set_fraction</methodname>()</link> 
method .</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--get-pulse-step">
      <title>gtk.ProgressBar.get_pulse_step</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_pulse_step</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a fraction from 0.0 to 1.0</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_pulse_step</methodname>() method returns the
pulse step set with the <link
linkend="method-gtkprogressbar--set-pulse-step"><methodname>set_pulse_step</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--get-orientation">
      <title>gtk.ProgressBar.get_orientation</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_orientation</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the orientation of the progress
bar</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_orientation</methodname>() method returns
the current progress bar orientation. See the <link
linkend="method-gtkprogressbar--set-orientation"><methodname>set_orientation</methodname>()</link>
method for information about the orientation values.</para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--set-ellipsize">
      <title>gtk.ProgressBar.set_ellipsize</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_ellipsize</methodname>
	  <methodparam><parameter
			 role="keyword">mode</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">mode</parameter>&nbsp;:</term>
	  <listitem><simpara>one of the <xref
linkend="pango-ellipsize-mode-constants"
endterm="pango-ellipsize-mode-constants-title"></xref></simpara></listitem>
	</varlistentry>
      </variablelist>

    <note>
      <para>This method is available in PyGTK 2.6 and above.</para>
    </note>

      <para>The <methodname>set_ellipsize</methodname>() method sets the
mode used to ellipsize (add an ellipsis "...") the text if there is not
enough space to render the entire string to the value specified by
<parameter>mode</parameter>. <parameter>mode</parameter> must be one of the
<xref linkend="pango-ellipsize-mode-constants"
endterm="pango-ellipsize-mode-constants-title"></xref></para>

    </refsect2>

    <refsect2 id="method-gtkprogressbar--get-ellipsize">
      <title>gtk.ProgressBar.get_ellipsize</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_ellipsize</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the mode used to ellipsize
text</simpara></listitem>
	</varlistentry>
      </variablelist>

    <note>
      <para>This method is available in PyGTK 2.6 and above.</para>
    </note>

      <para>The <methodname>get_ellipsize</methodname>() method returns the
mode used to ellipsize text when there is not enough space. See the <link
linkend="method-gtkprogressbar--set-ellipsize"><methodname>set_ellipsize</methodname>()</link>
method for information.</para>

    </refsect2>

  </refsect1>

</refentry>