/src/wrappers/gtk/library/gtk_progress_bar.e

  1indexing
  2	description: "GtkProgressBar: A widget which indicates progress visually"
  3	copyright: "[
  4					Copyright (C) 2006 Nicolas Fafchamps <nicolas.fafchamps@gmail-com
  5					Copyright (C) 2006 eiffel-libraries team, GTK+ team
  6					
  7					This library is free software; you can redistribute it and/or
  8					modify it under the terms of the GNU Lesser General Public License
  9					as published by the Free Software Foundation; either version 2.1 of
 10					the License, or (at your option) any later version.
 11					
 12					This library is distributed in the hope that it will be useful, but
 13					WITHOUT ANY WARRANTY; without even the implied warranty of
 14					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 15					Lesser General Public License for more details.
 16
 17					You should have received a copy of the GNU Lesser General Public
 18					License along with this library; if not, write to the Free Software
 19					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 20					02110-1301 USA
 21				]"
 22	copyright: "(C) 2006 Nicolas Fafchamps <nicolas.fafchamps@gmail.com> and Others"
 23	license: "LGPL v2 or later"
 24	date: "$Date:$"
 25	revision "$REvision:$"
 26
 27class GTK_PROGRESS_BAR
 28	-- the GtkProgressBar is typically used to display the progress of
 29	-- a long running operation. It provides a visual clue that
 30	-- processing is underway. The GtkProgressBar can be used in two
 31	-- different modes: percentage mode and activity mode.
 32	
 33	-- When an application can determine how much work needs to take
 34	-- place (e.g. read a fixed number of bytes from a file) and can
 35	-- monitor its progress, it can use the GtkProgressBar in
 36	-- percentage mode and the user sees a growing bar indicating the
 37	-- percentage of the work that has been completed. In this mode,
 38	-- the application is required to call `set_fraction' periodically
 39	-- to update the progress bar.
 40
 41	-- When an application has no accurate way of knowing the amount of
 42	-- work to do, it can use the GtkProgressBar in activity mode,
 43	-- which shows activity by a block moving back and forth within the
 44	-- progress area. In this mode, the application is required to call
 45	-- `pulse' perodically to update the progress bar.
 46
 47	-- There is quite a bit of flexibility provided to control the
 48	-- appearance of the GtkProgressBar. Functions are provided to
 49	-- control the orientation of the bar, optional text can be
 50	-- displayed along with the bar, and the step size used in activity
 51	-- mode can be set.
 52
 53inherit GTK_BIN
 54
 55insert
 56	GTK_PROGRESS_BAR_EXTERNALS
 57	GTK_PROGRESS_BAR_ORIENTATION
 58	PANGO_ELLIPSIZE_MODE
 59	
 60creation
 61	make, from_external_pointer
 62
 63feature {} -- Initialization
 64
 65	make is
 66			-- Create a new GtkProgressBar.
 67		require gtk_initialized: gtk.is_initialized
 68		do
 69			from_external_pointer (gtk_progress_bar_new) 
 70		end
 71
 72feature -- Element change
 73	pulse is
 74			-- Move the bar with `pulse_step'.
 75		do
 76			gtk_progress_bar_pulse(handle)
 77		end
 78
 79feature -- Status setting
 80	set_text (a_text : STRING) is
 81			-- Set the text to appear superimposed on the progress bar.
 82		require
 83			valid_text: a_text/=Void
 84		do
 85			gtk_progress_bar_set_text(handle,a_text.to_external)
 86		end
 87
 88	set_fraction (a_fraction : REAL) is
 89			-- Cause the progress bar to "fill in" the given fraction of the bar.
 90		require
 91			valid_fraction: a_fraction >= 0 and a_fraction <= 1
 92		do
 93			gtk_progress_bar_set_fraction(handle,a_fraction)
 94		end
 95
 96	set_pulse_step (a_fraction : REAL) is
 97			-- Sets the fraction of total progress bar length to move the bouncing block for each call to `pulse'.
 98		require
 99			valid_fraction: a_fraction >= 0 and a_fraction <= 1
100		do
101			gtk_progress_bar_set_pulse_step(handle,a_fraction)
102		end
103
104	set_orientation (an_orientation: INTEGER) is
105			-- Causes the progress bar to switch to a different
106			-- orientation (left-to-right, right-to-left, top-to-bottom,
107			-- or bottom-to-top).
108		require valid_orientation: is_valid_gtk_progress_bar_orientation (an_orientation)
109		do
110			gtk_progress_bar_set_orientation (handle, an_orientation)
111		end
112
113	set_ellipsize (a_mode: INTEGER) is
114			-- Sets the mode used to ellipsize (add an ellipsis: "...")
115			-- the text if there is not enough space to render the entire
116			-- string.
117		require is_valid_ellipsize_mode: is_valid_pango_ellipsize_mode(a_mode)
118		do
119			gtk_progress_bar_set_ellipsize (handle, a_mode)
120		end
121
122feature -- Status report
123	text : STRING is
124			-- Text displayed superimposed on the progress bar.
125		local ptr: POINTER
126		do
127			ptr:=gtk_progress_bar_get_text(handle)
128			if ptr.is_not_null then
129				create Result.from_external_copy (ptr)
130			else
131				Result := Void
132			end
133		end
134
135	fraction: REAL is
136			-- Current fraction of the task that's been completed
137		do
138			Result := gtk_progress_bar_get_fraction (handle)
139		end
140
141	orientation: INTEGER is
142			-- the current progress bar orientation
143		do
144			Result:=gtk_progress_bar_get_orientation(handle)
145		ensure valid_progress_bar_orientation:
146			is_valid_gtk_progress_bar_orientation (Result)
147		end
148
149	ellipsize_mode: INTEGER is
150			-- the ellipsizing position of the progressbar. See `set_ellipsize'
151		do
152			Result := gtk_progress_bar_get_ellipsize (handle)
153		ensure valid_ellipsize_mode: is_valid_pango_ellipsize_mode(Result)
154		end
155
156	pulse_step: REAL is
157			-- The fraction of total progress to move the bouncing block
158			-- when pulsed.
159		do
160			invoke_get_property (pulse_step_property.owner_class,	handle,
161										pulse_step_property.param_id, pulse_step_gvalue.handle,
162										pulse_step_property.handle)
163			Result := pulse_step_gvalue.real
164		ensure valid: Result.in_range(0.0, 1.0)
165		end
166	
167	-- Note : Other functions are deprecated
168
169feature {} -- Properties implementation
170	pulse_step_label: STRING is "pulse-step"
171							
172	pulse_step_property: G_PARAM_SPEC is
173		once
174			Result := find_property(pulse_step_label)
175		end
176
177	pulse_step_gvalue: G_VALUE is
178		once
179			create Result.with_gtype (pulse_step_property.value_gtype)
180		ensure not_void: Result /= Void
181		end
182	
183feature -- size
184	struct_size: INTEGER is
185		external "C inline use <gtk/gtk.h>"
186		alias "sizeof(GtkProgressBar)"
187		end
188end