From: Dmitry Kalyanov Date: Sun, 13 Sep 2009 10:47:46 +0000 (+0400) Subject: Add GtkProgressBar documentation X-Git-Url: http://repo.macrolet.net/gitweb/?a=commitdiff_plain;h=2d5b334e50cc4f34a3ea411239deae25e8cb7196;p=cl-gtk2.git Add GtkProgressBar documentation --- diff --git a/doc/gtk.widgets.texi b/doc/gtk.widgets.texi index 37e2748..33eb6a8 100644 --- a/doc/gtk.widgets.texi +++ b/doc/gtk.widgets.texi @@ -2761,18 +2761,74 @@ Signals: @Class progress-bar Superclass: @ref{progress} @ref{atk-implementor-iface} @ref{buildable} +The @ref{progress-bar} is typically used to display the progress of a long running operation. It provides a visual clue that processing is underway. The @ref{progress-bar} can be used in two different modes: percentage mode and activity mode. + +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 @ref{progress-bar} 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 set @SlotRef{progress-bar,fraction} periodically to update the progress bar. + +When an application has no accurate way of knowing the amount of work to do, it can use the @ref{progress-bar} 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 @ref{progress-bar-pulse} perodically to update the progress bar. + +There is quite a bit of flexibility provided to control the appearance of the @ref{progress-bar}. Functions 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. + Slots: @itemize @item @anchor{slot.progress-bar.activity-blocks}activity-blocks. Type: @code{integer}. Accessor: @anchor{fn.progress-bar-activity-blocks}@code{progress-bar-activity-blocks}. + +The number of blocks which can fit in the progress bar area in activity mode (Deprecated). + +Allowed values: >= 2 + +Default value: 5 @item @anchor{slot.progress-bar.activity-step}activity-step. Type: @code{integer}. Accessor: @anchor{fn.progress-bar-activity-step}@code{progress-bar-activity-step}. + +The increment used for each iteration in activity mode (Deprecated). + +Default value: 3 @item @anchor{slot.progress-bar.adjustment}adjustment. Type: @ref{adjustment}. Accessor: @anchor{fn.progress-bar-adjustment}@code{progress-bar-adjustment}. + +The @ref{adjustment} connected to the progress bar (Deprecated @item @anchor{slot.progress-bar.bar-style}bar-style. Type: @ref{progress-bar-style}. Accessor: @anchor{fn.progress-bar-bar-style}@code{progress-bar-bar-style}. + +Specifies the visual style of the bar in percentage mode (Deprecated). + +Default value: @EnumVRef{progress-bar-style,continuous} @item @anchor{slot.progress-bar.discrete-blocks}discrete-blocks. Type: @code{integer}. Accessor: @anchor{fn.progress-bar-discrete-blocks}@code{progress-bar-discrete-blocks}. -@item @anchor{slot.progress-bar.ellipsize}ellipsize. Type: @code{PangoEllipsizeMode}. Accessor: @anchor{fn.progress-bar-ellipsize}@code{progress-bar-ellipsize}. + +The number of discrete blocks in a progress bar (when shown in the discrete style). + +Allowed values: >= 2 + +Default value: 10 +@item @anchor{slot.progress-bar.ellipsize}ellipsize. Type: @ref{pango-ellipsize-mode}. Accessor: @anchor{fn.progress-bar-ellipsize}@code{progress-bar-ellipsize}. + +The preferred place to ellipsize the string, if the progressbar does not have enough room to display the entire string. + +Note that setting this property to a value other than @EnumVRef{pango-ellipsize-mode,none} has the side-effect that the progressbar requests only enough space to display the ellipsis "...". Another means to set a progressbar's width is @SlotRef{widget,width-request}. + +Default value: @EnumVRef{pango-ellipsize-mode,none} @item @anchor{slot.progress-bar.fraction}fraction. Type: @code{double-float}. Accessor: @anchor{fn.progress-bar-fraction}@code{progress-bar-fraction}. + +The fraction of total work that has been completed. + +Allowed values: [0,1] + +Default value: 0 @item @anchor{slot.progress-bar.orientation}orientation. Type: @ref{progress-bar-orientation}. Accessor: @anchor{fn.progress-bar-orientation}@code{progress-bar-orientation}. + +Orientation and growth direction of the progress bar. + +Default value: @EnumVRef{progress-bar-orientation,left-to-right} @item @anchor{slot.progress-bar.pulse-step}pulse-step. Type: @code{double-float}. Accessor: @anchor{fn.progress-bar-pulse-step}@code{progress-bar-pulse-step}. + +The fraction of total progress to move the bouncing block when pulsed. + +Allowed values: [0,1] + +Default value: 0.1 @item @anchor{slot.progress-bar.text}text. Type: @code{string}. Accessor: @anchor{fn.progress-bar-text}@code{progress-bar-text}. + +Text to be displayed in the progress bar. + +Default value: NIL @end itemize @@ -2780,8 +2836,12 @@ Signals: @itemize @end itemize +@RMethod progress-bar-pulse +@lisp +(progress-bar-pulse progress-bar) +@end lisp - +Indicates that some progress is made, but you don't know how much. Causes the progress bar to enter "activity mode," where a block bounces back and forth. Each call to @ref{progress-bar-pulse} causes the block to move by a little bit (the amount of movement per pulse is determined by @SlotRef{progress-bar,pulse-step}). @node radio-button @section radio-button