1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gtk.ProgressBar;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gtk.OrientableIF;
31 private import gtk.OrientableT;
32 private import gtk.Widget;
33 private import gtkc.gtk;
34 public  import gtkc.gtktypes;
35 
36 
37 /**
38  * The #GtkProgressBar is typically used to display the progress of a long
39  * running operation. It provides a visual clue that processing is underway.
40  * The GtkProgressBar can be used in two different modes: percentage mode
41  * and activity mode.
42  * 
43  * When an application can determine how much work needs to take place
44  * (e.g. read a fixed number of bytes from a file) and can monitor its
45  * progress, it can use the GtkProgressBar in percentage mode and the
46  * user sees a growing bar indicating the percentage of the work that
47  * has been completed. In this mode, the application is required to call
48  * gtk_progress_bar_set_fraction() periodically to update the progress bar.
49  * 
50  * When an application has no accurate way of knowing the amount of work
51  * to do, it can use the #GtkProgressBar in activity mode, which shows
52  * activity by a block moving back and forth within the progress area. In
53  * this mode, the application is required to call gtk_progress_bar_pulse()
54  * periodically to update the progress bar.
55  * 
56  * There is quite a bit of flexibility provided to control the appearance
57  * of the #GtkProgressBar. Functions are provided to control the orientation
58  * of the bar, optional text can be displayed along with the bar, and the
59  * step size used in activity mode can be set.
60  * 
61  * # CSS nodes
62  * 
63  * |[<!-- language="plain" -->
64  * progressbar[.osd]
65  * ╰── trough[.empty][.full]
66  * ├── [text]
67  * ╰── progress[.pulse]
68  * ]|
69  * 
70  * GtkProgressBar has a main CSS node with name progressbar and subnodes with
71  * names text, trough and progress. The text subnode is only present if text
72  * is shown. The progress subnode has the style class .pulse when in activity
73  * mode. It gets the style classes .left, .right, .top or .bottom added when
74  * the progress 'touches' the corresponding end of the GtkProgressBar.
75  * The .osd class on the progressbar node is for use in overlays like the one
76  * epiphany has for page loading progress.
77  */
78 public class ProgressBar : Widget, OrientableIF
79 {
80 	/** the main Gtk struct */
81 	protected GtkProgressBar* gtkProgressBar;
82 
83 	/** Get the main Gtk struct */
84 	public GtkProgressBar* getProgressBarStruct(bool transferOwnership = false)
85 	{
86 		if (transferOwnership)
87 			ownedRef = false;
88 		return gtkProgressBar;
89 	}
90 
91 	/** the main Gtk struct as a void* */
92 	protected override void* getStruct()
93 	{
94 		return cast(void*)gtkProgressBar;
95 	}
96 
97 	protected override void setStruct(GObject* obj)
98 	{
99 		gtkProgressBar = cast(GtkProgressBar*)obj;
100 		super.setStruct(obj);
101 	}
102 
103 	/**
104 	 * Sets our main struct and passes it to the parent class.
105 	 */
106 	public this (GtkProgressBar* gtkProgressBar, bool ownedRef = false)
107 	{
108 		this.gtkProgressBar = gtkProgressBar;
109 		super(cast(GtkWidget*)gtkProgressBar, ownedRef);
110 	}
111 
112 	// add the Orientable capabilities
113 	mixin OrientableT!(GtkProgressBar);
114 
115 
116 	/** */
117 	public static GType getType()
118 	{
119 		return gtk_progress_bar_get_type();
120 	}
121 
122 	/**
123 	 * Creates a new #GtkProgressBar.
124 	 *
125 	 * Returns: a #GtkProgressBar.
126 	 *
127 	 * Throws: ConstructionException GTK+ fails to create the object.
128 	 */
129 	public this()
130 	{
131 		auto p = gtk_progress_bar_new();
132 		
133 		if(p is null)
134 		{
135 			throw new ConstructionException("null returned by new");
136 		}
137 		
138 		this(cast(GtkProgressBar*) p);
139 	}
140 
141 	/**
142 	 * Returns the ellipsizing position of the progress bar.
143 	 * See gtk_progress_bar_set_ellipsize().
144 	 *
145 	 * Returns: #PangoEllipsizeMode
146 	 *
147 	 * Since: 2.6
148 	 */
149 	public PangoEllipsizeMode getEllipsize()
150 	{
151 		return gtk_progress_bar_get_ellipsize(gtkProgressBar);
152 	}
153 
154 	/**
155 	 * Returns the current fraction of the task that’s been completed.
156 	 *
157 	 * Returns: a fraction from 0.0 to 1.0
158 	 */
159 	public double getFraction()
160 	{
161 		return gtk_progress_bar_get_fraction(gtkProgressBar);
162 	}
163 
164 	/**
165 	 * Gets the value set by gtk_progress_bar_set_inverted().
166 	 *
167 	 * Returns: %TRUE if the progress bar is inverted
168 	 */
169 	public bool getInverted()
170 	{
171 		return gtk_progress_bar_get_inverted(gtkProgressBar) != 0;
172 	}
173 
174 	/**
175 	 * Retrieves the pulse step set with gtk_progress_bar_set_pulse_step().
176 	 *
177 	 * Returns: a fraction from 0.0 to 1.0
178 	 */
179 	public double getPulseStep()
180 	{
181 		return gtk_progress_bar_get_pulse_step(gtkProgressBar);
182 	}
183 
184 	/**
185 	 * Gets the value of the #GtkProgressBar:show-text property.
186 	 * See gtk_progress_bar_set_show_text().
187 	 *
188 	 * Returns: %TRUE if text is shown in the progress bar
189 	 *
190 	 * Since: 3.0
191 	 */
192 	public bool getShowText()
193 	{
194 		return gtk_progress_bar_get_show_text(gtkProgressBar) != 0;
195 	}
196 
197 	/**
198 	 * Retrieves the text that is displayed with the progress bar,
199 	 * if any, otherwise %NULL. The return value is a reference
200 	 * to the text, not a copy of it, so will become invalid
201 	 * if you change the text in the progress bar.
202 	 *
203 	 * Returns: text, or %NULL; this string is owned by the widget
204 	 *     and should not be modified or freed.
205 	 */
206 	public string getText()
207 	{
208 		return Str.toString(gtk_progress_bar_get_text(gtkProgressBar));
209 	}
210 
211 	/**
212 	 * Indicates that some progress has been made, but you don’t know how much.
213 	 * Causes the progress bar to enter “activity mode,” where a block
214 	 * bounces back and forth. Each call to gtk_progress_bar_pulse()
215 	 * causes the block to move by a little bit (the amount of movement
216 	 * per pulse is determined by gtk_progress_bar_set_pulse_step()).
217 	 */
218 	public void pulse()
219 	{
220 		gtk_progress_bar_pulse(gtkProgressBar);
221 	}
222 
223 	/**
224 	 * Sets the mode used to ellipsize (add an ellipsis: "...") the
225 	 * text if there is not enough space to render the entire string.
226 	 *
227 	 * Params:
228 	 *     mode = a #PangoEllipsizeMode
229 	 *
230 	 * Since: 2.6
231 	 */
232 	public void setEllipsize(PangoEllipsizeMode mode)
233 	{
234 		gtk_progress_bar_set_ellipsize(gtkProgressBar, mode);
235 	}
236 
237 	/**
238 	 * Causes the progress bar to “fill in” the given fraction
239 	 * of the bar. The fraction should be between 0.0 and 1.0,
240 	 * inclusive.
241 	 *
242 	 * Params:
243 	 *     fraction = fraction of the task that’s been completed
244 	 */
245 	public void setFraction(double fraction)
246 	{
247 		gtk_progress_bar_set_fraction(gtkProgressBar, fraction);
248 	}
249 
250 	/**
251 	 * Progress bars normally grow from top to bottom or left to right.
252 	 * Inverted progress bars grow in the opposite direction.
253 	 *
254 	 * Params:
255 	 *     inverted = %TRUE to invert the progress bar
256 	 */
257 	public void setInverted(bool inverted)
258 	{
259 		gtk_progress_bar_set_inverted(gtkProgressBar, inverted);
260 	}
261 
262 	/**
263 	 * Sets the fraction of total progress bar length to move the
264 	 * bouncing block for each call to gtk_progress_bar_pulse().
265 	 *
266 	 * Params:
267 	 *     fraction = fraction between 0.0 and 1.0
268 	 */
269 	public void setPulseStep(double fraction)
270 	{
271 		gtk_progress_bar_set_pulse_step(gtkProgressBar, fraction);
272 	}
273 
274 	/**
275 	 * Sets whether the progress bar will show text next to the bar.
276 	 * The shown text is either the value of the #GtkProgressBar:text
277 	 * property or, if that is %NULL, the #GtkProgressBar:fraction value,
278 	 * as a percentage.
279 	 *
280 	 * To make a progress bar that is styled and sized suitably for containing
281 	 * text (even if the actual text is blank), set #GtkProgressBar:show-text to
282 	 * %TRUE and #GtkProgressBar:text to the empty string (not %NULL).
283 	 *
284 	 * Params:
285 	 *     showText = whether to show superimposed text
286 	 *
287 	 * Since: 3.0
288 	 */
289 	public void setShowText(bool showText)
290 	{
291 		gtk_progress_bar_set_show_text(gtkProgressBar, showText);
292 	}
293 
294 	/**
295 	 * Causes the given @text to appear next to the progress bar.
296 	 *
297 	 * If @text is %NULL and #GtkProgressBar:show-text is %TRUE, the current
298 	 * value of #GtkProgressBar:fraction will be displayed as a percentage.
299 	 *
300 	 * If @text is non-%NULL and #GtkProgressBar:show-text is %TRUE, the text
301 	 * will be displayed. In this case, it will not display the progress
302 	 * percentage. If @text is the empty string, the progress bar will still
303 	 * be styled and sized suitably for containing text, as long as
304 	 * #GtkProgressBar:show-text is %TRUE.
305 	 *
306 	 * Params:
307 	 *     text = a UTF-8 string, or %NULL
308 	 */
309 	public void setText(string text)
310 	{
311 		gtk_progress_bar_set_text(gtkProgressBar, Str.toStringz(text));
312 	}
313 }