/src/wrappers/gobject/library/g_signals.e

  1indexing
  2	description: "Utility functions dealing with Gobject signals"
  3
  4	
  5deferred class G_SIGNALS
  6inherit
  7	WRAPPER_HANDLER
  8		undefine null_or end
  9
 10insert G_SIGNAL_EXTERNALS
 11feature
 12
 13	query (an_id: INTEGER): G_SIGNAL_QUERY is
 14			-- Queries the signal system for in-depth information about a
 15			-- specific signal. This function will fill in a
 16			-- user-provided structure to hold signal-specific
 17			-- information. If an invalid signal id is passed in, the
 18			-- signal_id member of the GSignalQuery is 0.
 19
 20			-- `an_id': The signal id of the signal to query information
 21			-- for.
 22		do
 23			create Result.allocate
 24			-- Note: TODO: signal_id is guint therefore an_id shall be NATURAL
 25			g_signal_query (an_id, Result.handle)
 26		end
 27	
 28	lookup (a_name: STRING; a_type: INTEGER): INTEGER is
 29			-- identifying integer of signal `a_name' emitted by objects
 30			-- with type number `a_type`. Emitting the signal by number
 31			-- is somewhat faster than using the name each time.
 32		
 33			-- Also tries the ancestors of the given type.
 34
 35			-- It is 0 if no signal was found.
 36		do
 37			Result:=g_signal_lookup (a_name.to_external,a_type)
 38		ensure positive: Result>=0
 39		end
 40
 41
 42	get_signal_name (an_id: INTEGER): STRING is
 43			-- Name of the signal with identifier equals to `an_id'. Two
 44			-- different signals may have the same name, if they have
 45			-- differing types.
 46		require valid_id: an_id>0
 47		local ptr: POINTER
 48		do
 49			ptr:=g_signal_name (an_id)
 50			if ptr.is_not_null
 51			then create Result.from_external_copy (ptr)
 52			else Result:=Void -- Note: Redundant, but more clear
 53			end
 54		end
 55
 56	connect (an_object: G_OBJECT;
 57				a_signal_name: STRING;
 58				a_function_pointer: POINTER) is
 59			-- Directly connect `a_function' to the signal named
 60			-- `a_signal_name' for `an_object' (i.e. when `an_object'
 61			-- emits `a_signal_name' `a_function_pointer' will be called)
 62
 63			-- Note: this function must be always called in this way:
 64			-- connect(Current,"my-signal",$a_feature_of_current). If you
 65			-- need a more flexible approach you can use CALLBACKs.
 66		require
 67			valid_object: an_object /= Void
 68			valid_signal_name: a_signal_name /= Void
 69			valid_function: a_function_pointer.is_not_null
 70		local an_id: INTEGER
 71		do
 72			-- The handler will be called before the default handler of the signal.
 73			-- instance : 	the instance to connect to.
 74			-- detailed_signal : 	a string of the form "signal-name::detail".
 75			-- c_handler : 	the GCallback to connect.
 76			-- data : 	data to pass to c_handler calls.
 77			-- Returns : 	the handler id
 78			an_id := g_signal_connect_swapped (an_object.handle,a_signal_name.to_external,
 79														  a_function_pointer, an_object.to_pointer)
 80			-- g_signal_connect_swapped is necessary because SmartEiffel
 81			-- expect a pointer to an Eiffel object as first parameter of
 82			-- each function.
 83			debug 
 84				print ("connect("+an_object.to_pointer.to_string+
 85						 ", `"+a_signal_name+"', "+
 86						 a_function_pointer.to_string+")%N")
 87			end
 88		end
 89
 90	stop_by_name (instance: G_OBJECT; name: STRING) is
 91			-- Stops a signal's current emission.
 92			-- like `stop' except it will look up the signal id for you.
 93			-- `instance': the object whose signal handlers you wish to stop.
 94			-- `name': a string of the form "signal-name::detail".
 95		require
 96			instance /= Void
 97			name /= Void
 98		do
 99			g_signal_stop_emission_by_name (instance.handle, name.to_external)
100		end
101
102end