indexing
	description: "[
				Abstraction for objects onto which graphical primitives may be applied.
		
				Note: When line style is dashed and line width is bigger than one,
				lines are not guaranteed to be dashed on all platforms.
				All drawing operations are performed in the current
				oreground color unless otherwise stated. i.e. clear_rectangle
				uses the current background color.
	]"
	legal: "See notice at end of class."
	status: "See notice at end of class."
	keywords: "figure, primitive, drawing, line, point, ellipse"
	date: "$Date: 2007-08-30 11:34:36 -0700 (Thu, 30 Aug 2007) $"
	revision: "$Revision: 70204 $"

deferred class interface
	EV_DRAWABLE


feature -- Access

	background_color: EV_COLOR
			-- Color displayed behind foreground features.
			-- (from EV_COLORIZABLE)
		require -- from EV_COLORIZABLE
			not_destroyed: not is_destroyed
		ensure -- from EV_COLORIZABLE
			bridge_ok: Result.is_equal (implementation.background_color)

	clip_area: EV_RECTANGLE
			-- Rectangular area to apply clipping on.
		require
			not_destroyed: not is_destroyed
		ensure
			bridge_ok: (Result = Void) = (implementation.clip_area = Void)

	dashed_line_style: BOOLEAN
			-- Are lines drawn dashed?
		require
			not_destroyed: not is_destroyed
		ensure
			bridge_ok: Result = implementation.dashed_line_style

	data: ANY
			-- Arbitrary user data may be stored here.
			-- (from EV_ANY)

	drawing_mode: INTEGER_32
			-- Logical operation on pixels when drawing.
			-- Default: drawing_mode_copy.
		require
			not_destroyed: not is_destroyed
		ensure
			bridge_ok: Result = implementation.drawing_mode

	font: EV_FONT
			-- Typeface appearance for `Current'.
			-- (from EV_FONTABLE)
		require -- from EV_FONTABLE
			not_destroyed: not is_destroyed
		ensure -- from EV_FONTABLE
			not_void: Result /= Void
			bridge_ok: Result.is_equal (implementation.font)

	foreground_color: EV_COLOR
			-- Color of foreground features like text.
			-- (from EV_COLORIZABLE)
		require -- from EV_COLORIZABLE
			not_destroyed: not is_destroyed
		ensure -- from EV_COLORIZABLE
			bridge_ok: Result.is_equal (implementation.foreground_color)

	generating_type: STRING_8
			-- Name of current object's generating type
			-- (type of which it is a direct instance)
			-- (from ANY)
		ensure -- from ANY
			generating_type_not_void: Result /= Void
			generating_type_not_empty: not Result.is_empty

	generator: STRING_8
			-- Name of current object's generating class
			-- (base class of the type of which it is a direct instance)
			-- (from ANY)
		ensure -- from ANY
			generator_not_void: Result /= Void
			generator_not_empty: not Result.is_empty

	line_width: INTEGER_32
			-- Line thickness. Default: 1.
		require
			not_destroyed: not is_destroyed
		ensure
			bridge_ok: Result = implementation.line_width

	tile: EV_PIXMAP
			-- Pixmap that is used to draw filled primitives with
			-- instead of foreground_color.
		require
			not_destroyed: not is_destroyed
		ensure
			bridge_ok: (Result = Void) = (implementation.tile = Void)
	
feature -- Measurement

	height: INTEGER_32
			-- Vertical size in pixels.
		require
			not_destroyed: not is_destroyed

	width: INTEGER_32
			-- Horizontal size in pixels.
		require
			not_destroyed: not is_destroyed
	
feature -- Comparison

	frozen deep_equal (some: ?ANY; other: like arg #1): BOOLEAN
			-- Are `some' and `other' either both void
			-- or attached to isomorphic object structures?
			-- (from ANY)
		ensure -- from ANY
			shallow_implies_deep: standard_equal (some, other) implies Result
			both_or_none_void: (some = Void) implies (Result = (other = Void))
			same_type: (Result and (some /= Void)) implies (other /= Void and then some.same_type (other))
			symmetric: Result implies deep_equal (other, some)

	frozen equal (some: ?ANY; other: like arg #1): BOOLEAN
			-- Are `some' and `other' either both void or attached
			-- to objects considered equal?
			-- (from ANY)
		ensure -- from ANY
			definition: Result = (some = Void and other = Void) or else ((some /= Void and other /= Void) and then some.is_equal (other))

	frozen is_deep_equal (other: EV_DRAWABLE): BOOLEAN
			-- Are `Current' and `other' attached to isomorphic object structures?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			shallow_implies_deep: standard_is_equal (other) implies Result
			same_type: Result implies same_type (other)
			symmetric: Result implies other.is_deep_equal (Current)

	is_equal (other: EV_DRAWABLE): BOOLEAN
			-- Is `other' attached to an object considered
			-- equal to current object?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			symmetric: Result implies other.is_equal (Current)
			consistent: standard_is_equal (other) implies Result

	frozen standard_equal (some: ?ANY; other: like arg #1): BOOLEAN
			-- Are `some' and `other' either both void or attached to
			-- field-by-field identical objects of the same type?
			-- Always uses default object comparison criterion.
			-- (from ANY)
		ensure -- from ANY
			definition: Result = (some = Void and other = Void) or else ((some /= Void and other /= Void) and then some.standard_is_equal (other))

	frozen standard_is_equal (other: EV_DRAWABLE): BOOLEAN
			-- Is `other' attached to an object of the same type
			-- as current object, and field-by-field identical to it?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			same_type: Result implies same_type (other)
			symmetric: Result implies other.standard_is_equal (Current)
	
feature -- Status report

	conforms_to (other: ANY): BOOLEAN
			-- Does type of current object conform to type
			-- of `other' (as per Eiffel: The Language, chapter 13)?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void

	same_type (other: ANY): BOOLEAN
			-- Is type of current object identical to type of `other'?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			definition: Result = (conforms_to (other) and other.conforms_to (Current))
	
feature -- Status setting

	set_default_colors
			-- Set foreground and background color to their default values.
			-- (from EV_COLORIZABLE)
		require -- from EV_COLORIZABLE
			not_destroyed: not is_destroyed
	
feature -- Element change

	disable_dashed_line_style
			-- Draw lines solid.
		require
			not_destroyed: not is_destroyed
		ensure
			dashed_line_style_disabled: not dashed_line_style

	enable_dashed_line_style
			-- Draw lines dashed.
			-- See note at top.
		require
			not_destroyed: not is_destroyed
		ensure
			dashed_line_style_enabled: dashed_line_style

	remove_clip_area
			-- Do not apply any clipping.
			-- Was declared in EV_DRAWABLE as synonym of remove_clipping.
		require
			not_destroyed: not is_destroyed
		ensure
			clip_area_void: clip_area = Void

	remove_clipping
			-- Do not apply any clipping.
			-- Was declared in EV_DRAWABLE as synonym of remove_clip_area.
		require
			not_destroyed: not is_destroyed
		ensure
			clip_area_void: clip_area = Void

	remove_tile
			-- Do not apply a tile when filling.
		require
			not_destroyed: not is_destroyed
		ensure
			tile_void: tile = Void

	set_background_color (a_color: like background_color)
			-- Assign `a_color' to background_color.
			-- (from EV_COLORIZABLE)
		require -- from EV_COLORIZABLE
			not_destroyed: not is_destroyed
			a_color_not_void: a_color /= Void
		ensure -- from EV_COLORIZABLE
			background_color_assigned: background_color.is_equal (a_color)

	set_clip_area (an_area: EV_RECTANGLE)
			-- Set area which will be refreshed.
		require
			not_destroyed: not is_destroyed
			an_area_not_void: an_area /= Void
		ensure
			clip_area_assigned: clip_area.is_equal (an_area)

	set_clip_region (a_region: EV_REGION)
			-- Set region which will be refreshed.
		require
			not_destroyed: not is_destroyed
			a_region_not_void: a_region /= Void

	set_data (some_data: like data)
			-- Assign `some_data' to data.
			-- (from EV_ANY)
		require -- from EV_ANY
			not_destroyed: not is_destroyed
		ensure -- from EV_ANY
			data_assigned: data = some_data

	set_drawing_mode (a_mode: INTEGER_32)
			-- Set drawing mode to `a_logical_mode'.
		require
			not_destroyed: not is_destroyed
			a_mode_valid: valid_drawing_mode (a_mode)
		ensure
			drawing_mode_assigned: drawing_mode = a_mode

	set_font (a_font: EV_FONT)
			-- Assign `a_font' to font.
			-- (from EV_FONTABLE)
		require -- from EV_FONTABLE
			not_destroyed: not is_destroyed
			a_font_not_void: a_font /= Void
		ensure -- from EV_FONTABLE
			font_assigned: font.is_equal (a_font) and font /= a_font

	set_foreground_color (a_color: like foreground_color)
			-- Assign `a_color' to foreground_color.
			-- (from EV_COLORIZABLE)
		require -- from EV_COLORIZABLE
			not_destroyed: not is_destroyed
			a_color_not_void: a_color /= Void
		ensure -- from EV_COLORIZABLE
			foreground_color_assigned: foreground_color.is_equal (a_color)

	set_line_width (a_width: INTEGER_32)
			-- Assign `a_width' to line_width.
			-- See note at top.
		require
			not_destroyed: not is_destroyed
			a_width_positive_or_zero: a_width >= 0
		ensure
			line_width_assigned: line_width = a_width

	set_tile (a_pixmap: EV_PIXMAP)
			-- Set tile used to fill figures.
			-- Set to Void to use background_color to fill.
		require
			not_destroyed: not is_destroyed
			a_pixmap_not_void: a_pixmap /= Void
		ensure
			tile_assigned: tile /= Void
	
feature -- Duplication

	copy (other: EV_DRAWABLE)
			-- Update current object using fields of object attached
			-- to `other', so as to yield equal objects.
			-- (from EV_ANY)
		require -- from ANY
			other_not_void: other /= Void
			type_identity: same_type (other)
		ensure -- from ANY
			is_equal: is_equal (other)

	frozen deep_copy (other: EV_DRAWABLE)
			-- Effect equivalent to that of:
			--		copy (`other' . deep_twin)
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			deep_equal: deep_equal (Current, other)

	frozen deep_twin: EV_DRAWABLE
			-- New object structure recursively duplicated from Current.
			-- (from ANY)
		ensure -- from ANY
			deep_twin_not_void: Result /= Void
			deep_equal: deep_equal (Current, Result)

	frozen standard_copy (other: EV_DRAWABLE)
			-- Copy every field of `other' onto corresponding field
			-- of current object.
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
			type_identity: same_type (other)
		ensure -- from ANY
			is_standard_equal: standard_is_equal (other)

	frozen standard_twin: EV_DRAWABLE
			-- New object field-by-field identical to `other'.
			-- Always uses default copying semantics.
			-- (from ANY)
		ensure -- from ANY
			standard_twin_not_void: Result /= Void
			equal: standard_equal (Result, Current)

	sub_pixmap (area: EV_RECTANGLE): EV_PIXMAP
			-- Return a pixmap region of `Current' represented by rectangle `area'
		require
			not_destroyed: not is_destroyed
			area_not_void: area /= Void
		ensure
			result_not_void: Result /= Void

	frozen twin: EV_DRAWABLE
			-- New object equal to `Current'
			-- twin calls copy; to change copying/twining semantics, redefine copy.
			-- (from ANY)
		ensure -- from ANY
			twin_not_void: Result /= Void
			is_equal: Result.is_equal (Current)
	
feature -- Basic operations

	frozen default: ?EV_DRAWABLE
			-- Default value of object's type
			-- (from ANY)

	frozen default_pointer: POINTER
			-- Default value of type `POINTER'
			-- (Avoid the need to write `p'.default for
			-- some `p' of type `POINTER'.)
			-- (from ANY)

	default_rescue
			-- Process exception for routines with no Rescue clause.
			-- (Default: do nothing.)
			-- (from ANY)

	frozen do_nothing
			-- Execute a null action.
			-- (from ANY)
	
feature -- Clearing operations

	clear
			-- Erase `Current' with background_color.
		require
			not_destroyed: not is_destroyed

	clear_rectangle (x, y, a_width, a_height: INTEGER_32)
			-- Draw rectangle with upper-left corner on (`x', `y')
			-- with size `a_width' and `a_height' in background_color.
		require
			not_destroyed: not is_destroyed
			a_width_positive_or_zero: a_width >= 0
			a_height_positive_or_zero: a_height >= 0
	
feature -- Command

	destroy
			-- Destroy underlying native toolkit object.
			-- Render `Current' unusable.
			-- (from EV_ANY)
		ensure -- from EV_ANY
			is_destroyed: is_destroyed
	
feature -- Contract support

	is_background_color_void: BOOLEAN
			-- If background_color void?
			-- (from EV_COLORIZABLE)

	is_foreground_color_void: BOOLEAN
			-- If foreground_color void?
			-- (from EV_COLORIZABLE)

	valid_drawing_mode (a_mode: INTEGER_32): BOOLEAN
			-- Is `a_mode' a valid drawing mode?
			-- (from EV_DRAWABLE_CONSTANTS)
	
feature -- Drawing mode setting

	set_and_mode
			-- Set drawing_mode to bitwise AND.
		require
			not_destroyed: not is_destroyed
		ensure
			drawing_mode_assigned: drawing_mode = drawing_mode_and

	set_copy_mode
			-- Set drawing_mode to normal.
		require
			not_destroyed: not is_destroyed
		ensure
			drawing_mode_assigned: drawing_mode = drawing_mode_copy

	set_invert_mode
			-- Set drawing_mode to bitwise invert.
		require
			not_destroyed: not is_destroyed
		ensure
			drawing_mode_assigned: drawing_mode = drawing_mode_invert

	set_or_mode
			-- Set drawing_mode to bitwise OR.
		require
			not_destroyed: not is_destroyed
		ensure
			drawing_mode_assigned: drawing_mode = drawing_mode_or

	set_xor_mode
			-- Set drawing_mode to bitwise XOR.
		require
			not_destroyed: not is_destroyed
		ensure
			drawing_mode_assigned: drawing_mode = drawing_mode_xor
	
feature -- Drawing operations

	draw_arc (x, y, a_bounding_width, a_bounding_height: INTEGER_32; a_start_angle, an_aperture: REAL_32)
			-- Draw part of an ellipse defined by a rectangular area with an
			-- upper left corner at `x',`y', width `a_bounding_width' and height
			-- `a_bounding_height'.
			-- Start at `a_start_angle' and stop at `a_start_angle' + `an_aperture'.
			-- Angles are measured in radians, and go
			-- counterclockwise from the 3 o'clock angle.
		require
			not_destroyed: not is_destroyed
			a_bounding_width_positive_or_zero: a_bounding_width >= 0
			a_bounding_height_positive_or_zero: a_bounding_width >= 0

	draw_ellipse (x, y, a_bounding_width, a_bounding_height: INTEGER_32)
			-- Draw an ellipse defined by a rectangular area with an
			-- upper left corner at `x',`y', width `a_bounding_width' and height
			-- `a_bounding_height'.
		require
			not_destroyed: not is_destroyed
			a_bounding_width_positive_or_zero: a_bounding_width >= 0
			a_bounding_height_positive_or_zero: a_bounding_height >= 0

	draw_ellipsed_text (x, y: INTEGER_32; a_text: STRING_GENERAL; clipping_width: INTEGER_32)
			-- Draw `a_text' with left of baseline at (`x', `y') using font.
			-- Text is clipped to `clipping_width' in pixels and ellipses are displayed
			-- to show truncated characters if any.
		require
			not_destroyed: not is_destroyed
			a_text_not_void: a_text /= Void
			clipping_width_positive: clipping_width >= 0

	draw_ellipsed_text_top_left (x, y: INTEGER_32; a_text: STRING_GENERAL; clipping_width: INTEGER_32)
			-- Draw `a_text' with top left corner at (`x', `y') using font.
			-- Text is clipped to `clipping_width' in pixels and ellipses are displayed
			-- to show truncated characters if any.
		require
			not_destroyed: not is_destroyed
			a_text_not_void: a_text /= Void
			clipping_width_positive: clipping_width >= 0

	draw_pie_slice (x, y, a_bounding_width, a_bounding_height: INTEGER_32; a_start_angle, an_aperture: REAL_32)
			-- Draw part of an ellipse defined by a rectangular area with an
			-- upper left corner at `x',`y', width `a_bounding_width' and height
			-- `a_bounding_height'.
			-- Start at `a_start_angle' and stop at `a_start_angle' + `an_aperture'.
			-- The arc is then closed by two segments through (`x', 'y').
			-- Angles are measured in radians, start at the
			-- 3 o'clock angle and grow counterclockwise.
		require
			not_destroyed: not is_destroyed
			a_bounding_width_positive_or_zero: a_bounding_width >= 0
			a_bounding_height_positive_or_zero: a_bounding_height >= 0

	draw_pixmap (x, y: INTEGER_32; a_pixmap: EV_PIXMAP)
			-- Draw `a_pixmap' with upper-left corner on (`x', `y').
		require
			not_destroyed: not is_destroyed
			a_pixmap_not_void: a_pixmap /= Void

	draw_point (x, y: INTEGER_32)
			-- Draw point at (`x', `y').
		require
			not_destroyed: not is_destroyed

	draw_polyline (points: ARRAY [EV_COORDINATE]; is_closed: BOOLEAN)
			-- Draw line segments between subsequent points in
			-- `points'. If `is_closed' draw line segment between first
			-- and last point in `points'.
		require
			not_destroyed: not is_destroyed
			points_not_void: points /= Void
			points_contains_no_void_items: not points.has (Void)
			points_contains_first_and_last: points.count >= 2

	draw_rectangle (x, y, a_width, a_height: INTEGER_32)
			-- Draw rectangle with upper-left corner on (`x', `y')
			-- with size `a_width' and `a_height'.
		require
			not_destroyed: not is_destroyed
			a_width_positive_or_zero: a_width >= 0
			a_height_positive_or_zero: a_height >= 0

	draw_segment (x1, y1, x2, y2: INTEGER_32)
			-- Draw line segment from (`x1', `y1') to (`x2', `y2').
		require
			not_destroyed: not is_destroyed

	draw_straight_line (x1, y1, x2, y2: INTEGER_32)
			-- Draw infinite straight line through (`x1', `y1') and
			-- (`x2', `y2').
		require
			not_destroyed: not is_destroyed
			points_not_equal: x1 /= x2 or y1 /= y2

	draw_sub_pixel_buffer (x, y: INTEGER_32; a_pixel_buffer: EV_PIXEL_BUFFER; area: EV_RECTANGLE)
			-- Draw `area' of `a_pixel_buffer with upper-left corner on (`x', `y').
		require
			not_destroyed: not is_destroyed
			a_pixel_buffer_not_void: a_pixel_buffer /= Void
			area_not_void: area /= Void

	draw_sub_pixmap (x, y: INTEGER_32; a_pixmap: EV_PIXMAP; area: EV_RECTANGLE)
			-- Draw `area' of `a_pixmap' with upper-left corner on (`x', `y').
		require
			not_destroyed: not is_destroyed
			a_pixmap_not_void: a_pixmap /= Void
			area_not_void: area /= Void

	draw_text (x, y: INTEGER_32; a_text: STRING_GENERAL)
			-- Draw `a_text' with left of baseline at (`x', `y') using font.
		require
			not_destroyed: not is_destroyed
			a_text_not_void: a_text /= Void

	draw_text_top_left (x, y: INTEGER_32; a_text: STRING_GENERAL)
			-- Draw `a_text' with top left corner at (`x', `y') using font.
		require
			not_destroyed: not is_destroyed
			a_text_not_void: a_text /= Void
	
feature -- Drawing operations (filled)

	fill_ellipse (x, y, a_bounding_width, a_bounding_height: INTEGER_32)
			-- Fill an ellipse defined by a rectangular area with an
			-- upper left corner at `x',`y', width `a_bounding_width' and height
			-- `a_bounding_height'.
		require
			not_destroyed: not is_destroyed
			a_bounding_width_positive_or_zero: a_bounding_width >= 0
			a_bounding_height_positive_or_zero: a_bounding_height >= 0

	fill_pie_slice (x, y, a_bounding_width, a_bounding_height: INTEGER_32; a_start_angle, an_aperture: REAL_32)
			-- Fill part of an ellipse defined by a rectangular area with an
			-- upper left corner at `x',`y', width `a_bounding_width' and height
			-- `a_bounding_height'.
			-- Start at `a_start_angle' and stop at `a_start_angle' + `an_aperture'.
			-- The arc is then closed by two segments through (`x', `y').
			-- Angles are measured in radians, start at the 3
			-- o'clock angle and grow counterclockwise.
		require
			not_destroyed: not is_destroyed
			a_bounding_width_positive_or_zero: a_bounding_width >= 0
			a_bounding_height_positive_or_zero: a_bounding_height >= 0

	fill_polygon (points: ARRAY [EV_COORDINATE])
			-- Draw filled polygon between subsequent points in `points'.
		require
			not_destroyed: not is_destroyed
			points_not_void: points /= Void
			points_contains_no_void_items: not points.has (Void)
			points_contains_first_and_last: points.count >= 2

	fill_rectangle (x, y, a_width, a_height: INTEGER_32)
			-- Draw filled rectangle with upper-left corner on (`x', `y')
			-- with size `a_width' and `a_height'.
		require
			not_destroyed: not is_destroyed
			a_width_positive_or_zero: a_width >= 0
			a_height_positive_or_zero: a_height >= 0
	
feature -- Output

	io: STD_FILES
			-- Handle to standard file setup
			-- (from ANY)
		ensure -- from ANY
			io_not_void: Result /= Void

	out: STRING_8
			-- New string containing terse printable representation
			-- of current object
			-- (from ANY)
		ensure -- from ANY
			out_not_void: Result /= Void

	print (some: ?ANY)
			-- Write terse external representation of `some'
			-- on standard output.
			-- (from ANY)

	frozen tagged_out: STRING_8
			-- New string containing terse printable representation
			-- of current object
			-- (from ANY)
		ensure -- from ANY
			tagged_out_not_void: Result /= Void
	
feature -- Platform

	operating_environment: OPERATING_ENVIRONMENT
			-- Objects available from the operating system
			-- (from ANY)
		ensure -- from ANY
			operating_environment_not_void: Result /= Void
	
feature -- Status Report

	is_destroyed: BOOLEAN
			-- Is `Current' no longer usable?
			-- (from EV_ANY)
		ensure -- from EV_ANY
			bridge_ok: Result = implementation.is_destroyed
	
invariant
	line_width_positive_or_zero: is_usable implies line_width >= 0
	drawing_mode_valid: is_usable implies valid_drawing_mode (drawing_mode)

		-- from EV_COLORIZABLE
	background_color_not_void: is_usable implies not is_background_color_void
	foreground_color_not_void: is_usable implies not is_foreground_color_void

		-- from EV_ANY
	is_initialized: is_initialized
	is_coupled: implementation /= Void and then implementation.interface = Current
	default_create_called: default_create_called

		-- from ANY
	reflexive_equality: standard_is_equal (Current)
	reflexive_conformance: conforms_to (Current)

indexing
	copyright: "Copyright (c) 1984-2006, Eiffel Software and others"
	license: "Eiffel Forum License v2 (see http://www.eiffel.com/licensing/forum.txt)"