PageRenderTime 33ms CodeModel.GetById 12ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/cairo/library/cairo_context.e

http://github.com/tybor/Liberty
Specman e | 1508 lines | 473 code | 212 blank | 823 comment | 3 complexity | 0415c23e588548b2114c3aafa0c67348 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1note
   2	description: "The cairo drawing context (cairo_t in C)"
   3	copyright: "[
   4					Copyright (C) 2007-2017: Paolo Redaelli,
   5											 Soluciones Informaticas Libres S.A. (Except),
   6											 Cairo team
   7					
   8					This library is free software; you can redistribute it and/or
   9					modify it under the terms of the GNU Lesser General Public License
  10					as published by the Free Software Foundation; either version 2.1 of
  11					the License, or (at your option) any later version.
  12					
  13					This library is distributed in the hope that it will be useful, but
  14					WITHOUT ANY WARRANTY; without even the implied warranty of
  15					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16					Lesser General Public License for more details.
  17
  18					You should have received a copy of the GNU Lesser General Public
  19					License along with this library; if not, write to the Free Software
  20					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  21					02110-1301 USA
  22			]"
  23	date: "$Date:$"
  24	revision: "$Revision:$"
  25	wrapped_version: "1.2.4"
  26
  27class CAIRO_CONTEXT
  28	-- CAIRO_CONTEXT (cairo_t in C) is the main object used when
  29	-- drawing with cairo. To draw with cairo, you create a
  30	-- CAIRO_CONTEXT, set the target surface, and drawing options for
  31	-- the CAIRO_CONTEXT, create shapes with functions like `move_to'
  32	-- and `line_to', and then draw shapes with `stroke' or `fill'.
  33
  34	-- A CAIRO_CONTEXT contains the current state of the rendering
  35	-- device, including coordinates of yet to be drawn shapes.
  36	
  37	-- TODO: How to Eiffellize this? cairo_t's can be pushed to a stack
  38	-- via cairo_save(). They may then safely be changed, without
  39	-- loosing the current state. Use cairo_restore() to restore to the
  40	-- saved state.
  41
  42inherit
  43	C_STRUCT
  44		redefine
  45			from_external_pointer
  46		end
  47
  48	REFERENCE_COUNTED 
  49		redefine 
  50			dispose
  51		end
  52
  53insert
  54	CAIRO_CONTEXT_EXTERNALS
  55	CAIRO_PATH_EXTERNALS
  56	CAIRO_FONT_EXTERNALS
  57	CAIRO_TRANSFORMATIONS_EXTERNALS
  58
  59	CAIRO_ANTIALIAS_TYPE
  60	CAIRO_FILL_RULE
  61	CAIRO_LINE_CAP
  62	CAIRO_LINE_JOIN
  63	CAIRO_OPERATOR
  64	CAIRO_FONT_SLANT
  65	CAIRO_FONT_WEIGHT
  66	CAIRO_STATUS
  67
  68create {ANY} make, from_external_pointer
  69
  70feature {} -- Creation
  71	make (a_target: CAIRO_SURFACE)
  72			-- Creates a new context with all graphics state parameters
  73			-- set to default values and with target as a target
  74			-- surface. `a_target' should be a backend-specific surface 
  75
  76			-- If memory cannot be allocated, it will be a special object
  77			-- and `status' will be set to `cairo_status_no_memory'. You
  78			-- can use this object normally, but no drawing will be done.
  79		require
  80			target_not_void: a_target /= Void
  81		do
  82			from_external_pointer(cairo_create(a_target.handle))
  83			-- cairo_create references the target, so you can immediately
  84			-- call cairo_surface_destroy() on it if you don't need to
  85			-- maintain a separate reference to it.
  86		end
  87
  88feature {WRAPPER, WRAPPER_HANDLER} -- Creation
  89
  90	from_external_pointer (a_ptr: POINTER)
  91		do
  92			Precursor(a_ptr)
  93			ref
  94		end
  95
  96feature {ANY} -- State and memory handling
  97	dispose do unref end
  98
  99	ref
 100			-- Increases the reference count on cr by one. This prevents
 101			-- cr from being destroyed until a matching call to `dispose'
 102			-- is made.
 103		local
 104			ptr: POINTER
 105		do
 106			ptr := cairo_reference(handle)
 107		end
 108
 109	unref
 110			-- Decreases the reference count on cr by one. If the result
 111			-- is zero, then cr and all associated resources are
 112			-- freed. See `ref'.
 113		do
 114			cairo_destroy (handle)
 115		end
 116
 117	status: INTEGER
 118			--  the current status of this context; see CAIRO_STATUS. 
 119		do
 120			Result := cairo_status (handle)
 121		ensure
 122			valid_status: is_valid_cairo_status (Result)
 123		end
 124
 125	save
 126			-- Makes a copy of the current state of cr and saves it on an
 127			-- internal stack of saved states for cr. When `restore' is
 128			-- called, cr will be restored to the saved state. Multiple
 129			-- calls to `save' and `restore' can be nested; each call to
 130			-- `restore' restores the state from the matching paired
 131			-- `save'.
 132
 133			-- It isn't necessary to clear all saved states before a
 134			-- cairo_t is freed. If the reference count of a cairo_t
 135			-- drops to zero in response to a call to `unref,'
 136			-- any saved states will be freed along with the cairo_t.
 137		do
 138			cairo_save (handle)
 139		end
 140
 141	restore
 142			-- Restores the context to the state saved by a preceding
 143			-- call to `save' and removes that state from the stack of
 144			-- saved states.
 145		do
 146			cairo_restore (handle)
 147		end
 148
 149	target: CAIRO_SURFACE
 150			--  the target surface for the cairo context as passed to `make'.
 151
 152			-- This function will always return a valid pointer, but the
 153			-- result can be a "nil" surface if cr is already in an error
 154			-- state, (ie. `status' /= cairo_status_success). A nil
 155			-- surface is indicated by CAIRO_SURFACE.status /=
 156			-- `cairo_status_success'.
 157		local ptr: POINTER
 158		do
 159			create Result.from_external_pointer(cairo_get_target(handle))
 160			-- cairo_get_target returns the target surface. This object
 161			-- is owned by cairo. To keep a reference to it, you must
 162			-- call `ref'.
 163			Result.ref
 164		end
 165
 166	push_group
 167			-- Temporarily redirects drawing to an intermediate surface
 168			-- known as a group.  The redirection lasts until the group
 169			-- is completed by a call to cairo_pop_group() or
 170			-- cairo_pop_group_to_source(). These calls provide the
 171			-- result of any drawing to the group as a pattern, (either
 172			-- as an explicit object, or set as the source pattern).
 173
 174			-- This group functionality can be convenient for performing
 175			-- intermediate compositing. One common use of a group is to
 176			-- render objects as opaque within the group, (so that they
 177			-- occlude each other), and then blend the result with
 178			-- translucence onto the destination.
 179
 180			-- Groups can be nested arbitrarily deep by making balanced
 181			-- calls to cairo_push_group()/cairo_pop_group(). Each call
 182			-- pushes/pops the new target group onto/from a stack.
 183
 184			-- The cairo_push_group() function calls cairo_save() so that
 185			-- any changes to the graphics state will not be visible
 186			-- outside the group, (the pop_group functions call
 187			-- cairo_restore()).
 188
 189			-- By default the intermediate group will have a content type
 190			-- of CAIRO_CONTENT_COLOR_ALPHA. Other content types can be
 191			-- chosen for the group by using
 192			-- cairo_push_group_with_content() instead.
 193
 194			-- As an example, here is how one might fill and stroke a
 195			-- path with translucence, but without any portion of the
 196			-- fill being visible under the stroke:
 197
 198			-- cairo_push_group (cr);
 199			-- cairo_set_source (cr, fill_pattern);
 200			-- cairo_fill_preserve (cr);
 201			-- cairo_set_source (cr, stroke_pattern);
 202			-- cairo_stroke (cr);
 203			-- cairo_pop_group_to_source (cr);
 204			-- cairo_paint_with_alpha (cr, alpha);
 205		do
 206			cairo_push_group(handle)
 207		end
 208
 209	
 210	--  cairo_push_group_with_content ()
 211	--
 212	-- void        cairo_push_group_with_content   (cairo_t *cr,
 213	--                                              cairo_content_t content);
 214	--
 215	--   Temporarily redirects drawing to an intermediate surface known as a group.
 216	--   The redirection lasts until the group is completed by a call to
 217	--   cairo_pop_group() or cairo_pop_group_to_source(). These calls provide the
 218	--   result of any drawing to the group as a pattern, (either as an explicit
 219	--   object, or set as the source pattern).
 220	--
 221	--   The group will have a content type of content. The ability to control this
 222	--   content type is the only distinction between this function and
 223	--   cairo_push_group() which you should see for a more detailed description of
 224	--   group rendering.
 225	--
 226	--   cr :      a cairo context
 227	--   content : a cairo_content_t indicating the type of group that will be
 228	--             created
 229	--
 230	--   Since 1.2
 231	--
 232	--   --------------------------------------------------------------------------
 233	--
 234	--  cairo_pop_group ()
 235	--
 236	-- cairo_pattern_t* cairo_pop_group            (cairo_t *cr);
 237	--
 238	--   Terminates the redirection begun by a call to cairo_push_group() or
 239	--   cairo_push_group_with_content() and returns a new pattern containing the
 240	--   results of all drawing operations performed to the group.
 241	--
 242	--   The cairo_pop_group() function calls cairo_restore(), (balancing a call to
 243	--   cairo_save() by the push_group function), so that any changes to the
 244	--   graphics state will not be visible outside the group.
 245	--
 246	--   cr :      a cairo context
 247	--   Returns : a newly created (surface) pattern containing the results of all
 248	--             drawing operations performed to the group. The caller owns the
 249	--             returned object and should call cairo_pattern_destroy() when
 250	--             finished with it.
 251	--
 252	--   Since 1.2
 253	--
 254	--   --------------------------------------------------------------------------
 255	--
 256	--  cairo_pop_group_to_source ()
 257	--
 258	-- void        cairo_pop_group_to_source       (cairo_t *cr);
 259	--
 260	--   Terminates the redirection begun by a call to cairo_push_group() or
 261	--   cairo_push_group_with_content() and installs the resulting pattern as the
 262	--   source pattern in the given cairo context.
 263	--
 264	--   The behavior of this function is equivalent to the sequence of operations:
 265	--
 266	-- cairo_pattern_t *group = cairo_pop_group (cr);
 267	-- cairo_set_source (cr, group);
 268	-- cairo_pattern_destroy (group);
 269	--
 270	--   but is more convenient as their is no need for a variable to store the
 271	--   short-lived pointer to the pattern.
 272	--
 273	--   The cairo_pop_group() function calls cairo_restore(), (balancing a call to
 274	--   cairo_save() by the push_group function), so that any changes to the
 275	--   graphics state will not be visible outside the group.
 276	--
 277	--   cr : a cairo context
 278	--
 279	--   Since 1.2
 280	--
 281	--   --------------------------------------------------------------------------
 282	--
 283	--  cairo_get_group_target ()
 284	--
 285	-- cairo_surface_t* cairo_get_group_target     (cairo_t *cr);
 286	--
 287	--   Gets the target surface for the current group as started by the most
 288	--   recent call to cairo_push_group() or cairo_push_group_with_content().
 289	--
 290	--   This function will return NULL if called "outside" of any group rendering
 291	--   blocks, (that is, after the last balancing call to cairo_pop_group() or
 292	--   cairo_pop_group_to_source()).
 293	--
 294	--   cr :      a cairo context
 295	--   Returns : the target group surface, or NULL if none. This object is owned
 296	--             by cairo. To keep a reference to it, you must call
 297	--             cairo_surface_reference().
 298	--
 299	--   Since 1.2
 300	--
 301
 302	set_source_rgb (a_red, a_green, a_blue: REAL)
 303			-- Sets the source pattern within cr to an opaque color. This
 304			-- opaque color will then be used for any subsequent drawing
 305			-- operation until a new source pattern is set.
 306
 307			-- The color components are floating point numbers in the
 308			-- range 0 to 1. If the values passed in are outside that
 309			-- range, they will be clamped.
 310
 311			-- `a_red': red component of color
 312			-- `a_green': green component of color
 313			-- `a_blue':  blue component of color
 314		do
 315			cairo_set_source_rgb (handle, a_red, a_green, a_blue)
 316		end
 317
 318	set_source_rgba (a_red, a_green, a_blue, an_alpha: REAL)
 319			-- Sets the source pattern within cr to a translucent
 320			-- color. This color will then be used for any subsequent
 321			-- drawing operation until a new source pattern is set.
 322			
 323			-- The color and alpha components are floating point numbers
 324			-- in the range 0 to 1. If the values passed in are outside
 325			-- that range, they will be clamped.
 326
 327			-- `a_red': red component of color
 328			-- `a_green': green component of color
 329			-- `a_blue':  blue component of color
 330			-- `an_alpha': alpha component of color
 331		do
 332			cairo_set_source_rgba (handle, a_red, a_green, a_blue, an_alpha)
 333		end
 334
 335	set_source (a_source: CAIRO_PATTERN)
 336			-- Sets the source pattern within context to source. This
 337			-- pattern will then be used for any subsequent drawing
 338			-- operation until a new source pattern is set.
 339
 340			-- Note: The pattern's transformation matrix will be locked
 341			-- to the user space in effect at the time of
 342			-- `set_source'. This means that further modifications of the
 343			-- current transformation matrix will not affect the source
 344			-- pattern. See CAIRO_PATTERN.`set_matrix'.
 345		require source_not_void: a_source /= Void
 346		do
 347			cairo_set_source (handle, a_source.handle)
 348		end
 349
 350	set_source_surface (a_surface: CAIRO_SURFACE; an_x, an_y: REAL)
 351			-- A convenience feature for creating a pattern from surface
 352			-- and setting it as the source with `set_source'.
 353
 354			-- `an_x' and `an_y' parameters give the user-space
 355			-- coordinate at which the surface origin should appear. (The
 356			-- surface origin is its upper-left corner before any
 357			-- transformation has been applied.) The x and y patterns are
 358			-- negated and then set as translation values in the pattern
 359			-- matrix.
 360
 361			-- Other than the initial translation pattern matrix, as
 362			-- described above, all other pattern attributes, (such as
 363			-- its extend mode), are set to the default values as in
 364			-- CAIRO_PATTERN's `create_for_surface'. The resulting
 365			-- pattern can be queried with `source' so that these
 366			-- attributes can be modified if desired, (eg. to create a
 367			-- repeating pattern with CAIRO_PATTERN's `set_extend').
 368		
 369			-- `a_surface': the surface used to set the source pattern
 370		
 371			-- `an_x' : User-space X coordinate for surface origin
 372		
 373			-- `an_y' : User-space Y coordinate for surface origin
 374		require surface_not_void: a_surface/=Void
 375		do
 376			cairo_set_source_surface (handle, a_surface.handle, an_x, an_y)
 377		end
 378
 379	source: CAIRO_PATTERN
 380			--  the current source pattern for context.
 381		do
 382			create Result.from_external_pointer(cairo_get_source(handle))
 383			-- cairo_get_source returns the current source
 384			-- pattern. This object is owned by cairo. To keep a
 385			-- reference to it, you must call CAIRO_PATTERN.`ref'.
 386			Result.ref
 387		end
 388
 389	set_antialias (an_antialias_type: INTEGER)
 390			-- Set the antialiasing mode of the rasterizer used for
 391			-- drawing shapes. This value is a hint, and a particular
 392			-- backend may or may not support a particular value. At the
 393			-- current time, no backend supports
 394			-- `cairo_antialias_subpixel' when drawing shapes.
 395
 396			-- Note that this option does not affect text rendering,
 397			-- instead see CAIRO_FONT.`options_set_antialias'.
 398		require
 399			valid_type: is_valid_antialias_type (an_antialias_type)
 400		do
 401			cairo_set_antialias (handle, an_antialias_type)
 402		end
 403
 404	antialias: INTEGER
 405			-- the current shape antialiasing mode, as set by
 406			-- `set_shape_antialias'.
 407		do
 408			Result := cairo_get_antialias (handle);
 409		end
 410
 411feature {ANY} -- Dashing
 412
 413	disable_dashes
 414			-- Disable dashing
 415		do
 416			cairo_set_dash (handle, default_pointer, 1, 0.0)
 417		end
 418
 419	set_dash (some_dashes: ARRAY[REAL]; an_offset: REAL)
 420			-- Sets the dash pattern to be used by `stroke'. A dash
 421			-- pattern is specified by dashes, an array of positive
 422			-- values. Each value provides the length of alternate "on"
 423			-- and "off" portions of the stroke. The offset specifies an
 424			-- offset into the pattern at which the stroke begins.
 425		
 426			-- Each "on" segment will have caps applied as if the segment
 427			-- were a separate sub-path. In particular, it is valid to
 428			-- use an "on" length of 0.0 with CAIRO_LINE_CAP_ROUND or
 429			-- CAIRO_LINE_CAP_SQUARE in order to distributed dots or
 430			-- squares along a path.
 431
 432			-- Note: The length values are in user-space units as
 433			-- evaluated at the time of stroking. This is not necessarily
 434			-- the same as the user space at the time of `set_dash'.
 435
 436			-- If `some_dashes'.count is 1 a symmetric pattern is assumed
 437			-- with alternating on and off portions of the size specified
 438			-- by the single value in dashes.
 439		
 440			-- If any value in dashes is negative, or if all values are
 441			-- 0, then cairo_t will be put into an error state with a
 442			-- status of CAIRO_STATUS_INVALID_DASH.
 443
 444			-- `some_dashes': an array specifying alternate lengths of on
 445			-- and off stroke portions
 446		
 447			-- `an_offset': an offset into the dash pattern at which the
 448			-- stroke should start
 449		do
 450			cairo_set_dash (handle, some_dashes.to_external,
 451							some_dashes.count, an_offset)
 452		end
 453
 454	set_fill_rule (a_rule: INTEGER)
 455			-- Set the current fill rule within the cairo context. The
 456			-- fill rule is used to determine which regions are inside or
 457			-- outside a complex (potentially self-intersecting)
 458			-- path. The current fill rule affects both cairo_fill and
 459			-- cairo_clip. See cairo_fill_rule_t for details on the
 460			-- semantics of each available fill rule.
 461		require
 462			valid_rule: is_valid_fill_rule (a_rule)
 463		do
 464			cairo_set_fill_rule (handle, a_rule)
 465		end
 466
 467	fill_rule: INTEGER
 468			-- the current fill rule.
 469		do
 470			Result := cairo_get_fill_rule(handle)
 471		ensure
 472			valid: is_valid_fill_rule (Result)
 473		end
 474
 475	set_line_cap (a_line_cap: INTEGER)
 476			-- Sets the current line cap style within the cairo
 477			-- context. See CAIRO_LINE_CAP for details about how the
 478			-- available line cap styles are drawn.
 479
 480			-- As with the other stroke parameters, the current line cap
 481			-- style is examined by `stroke', `stroke_extents', and
 482			-- `stroke_to_path', but does not have any effect during path
 483			-- construction.
 484
 485			--   cr :       a cairo context, as a cairo_t
 486			--   line_cap : a line cap style, as a cairo_line_cap_t
 487		require
 488			is_valid_line_cap: is_valid_line_cap (a_line_cap)
 489		do
 490			cairo_set_line_cap (handle, a_line_cap)
 491		end
 492
 493	line_cap: INTEGER
 494			-- the current line cap style, as set by `set_line_cap'.
 495		do
 496			Result := cairo_get_line_cap (handle)
 497		ensure
 498			is_valid_line_cap: is_valid_line_cap (Result)
 499		end
 500
 501	set_line_join (a_line_join: INTEGER)
 502			-- Sets the current line join style within the cairo
 503			-- context. See CAIRO_LINE_JOIN for details about how the
 504			-- available line join styles are drawn.
 505		
 506			-- As with the other stroke parameters, the current line join
 507			-- style is examined by `stroke', `stroke_extents,' and
 508			-- `stroke_to_path', but does not have any effect during path
 509			-- construction.
 510		require
 511			is_valid_line_join: is_valid_line_join (a_line_join)
 512		do
 513			cairo_set_line_join (handle, a_line_join)
 514		end
 515
 516	line_join: INTEGER
 517			-- the current line join style, as set by `set_line_join'.
 518		do
 519			Result := cairo_get_line_join (handle)
 520		ensure
 521			is_valid_line_join: is_valid_line_join (Result)
 522		end
 523
 524	set_line_width (a_width: REAL)
 525			-- Sets the current line width within the cairo context. The
 526			-- line width value specifies the diameter of a pen that is
 527			-- circular in user space, (though device-space pen may be an
 528			-- ellipse in general due to scaling/shear/rotation of the
 529			-- CTM).
 530		
 531			-- Note: When the description above refers to user space and
 532			-- CTM it refers to the user space and CTM in effect at the
 533			-- time of the stroking operation, not the user space and CTM
 534			-- in effect at the time of the call to `set_line_width'. The
 535			-- simplest usage makes both of these spaces identical. That
 536			-- is, if there is no change to the CTM between a call to
 537			-- `set_line_with' and the stroking operation, then one can
 538			-- just pass user-space values to `set_line_width' and ignore
 539			-- this note.
 540		
 541			-- As with the other stroke parameters, the current line
 542			-- width is examined by `stroke', `stroke_extents', and
 543			-- `stroke_to_path', but does not have any effect
 544			-- during path construction.
 545		
 546			--   The default line width value is 2.0.
 547		do
 548			cairo_set_line_width (handle, a_width)
 549		end
 550
 551	line_width: REAL
 552			-- the current line width value exactly as set by
 553			-- `set_line_width'. Note that the value is unchanged even if
 554			-- the CTM has changed between the calls to `set_line_width'
 555			-- and `line_width'.
 556		do
 557			Result := cairo_get_line_width (handle)
 558		end
 559	
 560	set_miter_limit (a_limit: REAL)
 561		do
 562			cairo_set_miter_limit (handle, a_limit)
 563		end
 564
 565	miter_limit: REAL
 566			-- the current miter limit, as set by `set_miter_limit'.
 567		do
 568			Result := cairo_get_miter_limit (handle)
 569		end
 570	
 571	set_operator (an_operator: INTEGER)
 572			-- Sets the compositing operator to be used for all drawing
 573			-- operations. See `CAIRO_OPERATOR' for details on the
 574			-- semantics of each available compositing operator.
 575		require
 576			valid_operator: is_valid_operator (an_operator)
 577		do
 578			cairo_set_operator (handle, an_operator)
 579		end
 580
 581	operator: INTEGER
 582			-- the current compositing operator for a cairo context.
 583		do
 584			Result := cairo_get_operator (handle)
 585		ensure
 586			valid_operator: is_valid_operator (Result)
 587		end
 588
 589	set_tolerance (a_tolerance: REAL)
 590			-- Sets the tolerance used when converting paths into
 591			-- trapezoids. Curved segments of the path will be subdivided
 592			-- until the maximum deviation between the original path and
 593			-- the polygonal approximation is less than tolerance. The
 594			-- default value is 0.1. A larger value will give better
 595			-- performance, a smaller value, better appearance. (Reducing
 596			-- the value from the default value of 0.1 is unlikely to
 597			-- improve appearance significantly.)
 598		do
 599			cairo_set_tolerance (handle, a_tolerance)
 600		end
 601
 602	tolerance: REAL
 603			-- the current tolerance value, as set by `set_tolerance'.
 604		do
 605			Result := cairo_get_tolerance (handle)
 606		end
 607
 608	clip
 609			-- Establishes a new clip region by intersecting the current
 610			-- clip region with the current path as it would be filled by
 611			-- `fill' and according to the current fill rule (see
 612			-- `set_fill_rule').
 613
 614			-- After `clip,' the current path will be cleared from the
 615			-- cairo context.
 616	
 617			-- The current clip region affects all drawing operations by
 618			-- effectively masking out any changes to the surface that
 619			-- are outside the current clip region.
 620	
 621			-- Calling `clip' can only make the clip region smaller,
 622			-- never larger.  But the current clip is part of the
 623			-- graphics state, so a temporary restriction of the clip
 624			-- region can be achieved by calling `clip' within a
 625			-- `save'/`restore' pair. The only other means of
 626			-- increasing the size of the clip region is
 627			-- `reset_clip'.
 628		do
 629			cairo_clip (handle)
 630		end
 631
 632	clip_preserve
 633			-- Establishes a new clip region by intersecting the current
 634			-- clip region with the current path as it would be filled by
 635			-- `fill'() and according to the current fill rule (see
 636			-- `set_fill_rule').
 637			
 638			-- Unlike `clip'(), `clip_preserve' preserves the path
 639			-- within the cairo context.
 640		
 641			-- The current clip region affects all drawing operations by
 642			-- effectively masking out any changes to the surface that
 643			-- are outside the current clip region.
 644		
 645			-- Calling `clip' can only make the clip region smaller,
 646			-- never larger. But the current clip is part of the graphics
 647			-- state, so a temporary restriction of the clip region can
 648			-- be achieved by calling `clip' within a `save'/`restore'
 649			-- pair. The only other means of increasing the size of the
 650			-- clip region is `reset_clip'.
 651		do
 652			cairo_clip_preserve (handle)
 653		end
 654
 655	reset_clip
 656			-- Reset the current clip region to its original,
 657			-- unrestricted state. That is, set the clip region to an
 658			-- infinitely large shape containing the target
 659			-- surface. Equivalently, if infinity is too hard to grasp,
 660			-- one can imagine the clip region being reset to the exact
 661			-- bounds of the target surface.
 662	
 663			-- Note that code meant to be reusable should not call
 664			-- `reset_clip' as it will cause results unexpected by
 665			-- higher-level code which calls `clip'. Consider using
 666			-- `save' and `restore' around `clip' as a more robust means
 667			-- of temporarily restricting the clip region.
 668		do
 669			cairo_reset_clip (handle)
 670		end
 671
 672	fill
 673			-- A drawing operator that fills the current path according
 674			-- to the current fill rule, (each sub-path is implicitly
 675			-- closed before being filled). After cairo_fill, the current
 676			-- path will be cleared from the cairo context. See
 677			-- `set_fill_rule' and `fill_preserve'.
 678		do
 679			cairo_fill (handle)
 680		end
 681
 682	fill_preserve
 683			-- A drawing operator that fills the current path according
 684			-- to the current fill rule, (each sub-path is implicitly
 685			-- closed before being filled). Unlike `fill',
 686			-- `fill_preserve' preserves the path within the cairo
 687			-- context.
 688
 689			-- See `set_fill_rule' and `fill'.
 690		do
 691			cairo_fill_preserve (handle)
 692		end
 693
 694	extents: TUPLE [CAIRO_POINT, CAIRO_POINT]
 695			-- The extents in format [x1,y1,x2,y2]
 696		local
 697			an_x1, an_y1, an_x2, an_y2: REAL
 698			p1, p2: CAIRO_POINT
 699		do
 700			cairo_fill_extents (handle, $an_x1, $an_y1, $an_x2, $an_y2)
 701			create p1.make (an_x1, an_y1)
 702			create p2.make (an_x2, an_y2)
 703			create Result.make_2 (p1, p2)
 704		end
 705
 706	in_fill (an_x, an_y: REAL): BOOLEAN
 707			-- Is the given point on the area filled by doing a `stroke'
 708			-- operation on current context given the current path and filling
 709			-- parameters?
 710
 711			-- See `fill', `set_fill_rule' and `fill_preserve'.
 712			
 713			-- `an_x': X coordinate of the point to test
 714			-- `an_y': Y coordinate of the point to test
 715		do
 716			Result := cairo_in_fill (handle, an_x, an_y).to_boolean
 717		end
 718
 719	mask (a_pattern: CAIRO_PATTERN)
 720			-- A drawing operator that paints the current source using
 721			-- the alpha channel of pattern as a mask. (Opaque areas of
 722			-- pattern are painted with the source, transparent areas are
 723			-- not painted.)
 724		require
 725			pattern_not_void: a_pattern /= Void
 726		do
 727			cairo_mask (handle, a_pattern.handle)
 728		end
 729
 730	mask_surface (a_surface: CAIRO_SURFACE; an_x, an_y: REAL)
 731			-- A drawing operator that paints the current source using
 732			-- the alpha channel of surface as a mask. (Opaque areas of
 733			-- surface are painted with the source, transparent areas are
 734			-- not painted.)
 735
 736			-- `an_x': X coordinate at which to place the origin of surface
 737
 738			-- `an_y': Y coordinate at which to place the origin of surface
 739		require
 740			surface_not_void: a_surface /= Void
 741		do
 742			cairo_mask_surface (handle, a_surface.handle, an_x, an_y)
 743		end
 744
 745	paint
 746			-- A drawing operator that paints the current source
 747			-- everywhere within the current clip region.
 748		do
 749			cairo_paint (handle)
 750		end
 751
 752	paint_with_alpha (an_alpha: REAL)
 753			-- A drawing operator that paints the current source
 754			-- everywhere within the current clip region using a mask of
 755			-- constant `an_alpha' value. The effect is similar to
 756			-- `paint', but the drawing is faded out using `an_alpha'
 757			-- value.
 758		require valid_alpha: an_alpha.in_range(0.0, 1.0)
 759		do
 760			cairo_paint_with_alpha (handle, an_alpha)
 761		end
 762
 763	stroke
 764			-- A drawing operator that strokes the current path according
 765			-- to the current line width, line join, line cap, and dash
 766			-- settings. After `stroke,' the current path will be cleared
 767			-- from the cairo context. See `set_line_width',
 768			-- `set_line_join', `set_line_cap', `set_dash', and
 769			-- `stroke_preserve'.
 770
 771			-- Note: Degenerate segments and sub-paths are treated
 772			-- specially and provide a useful result. These can result in
 773			-- two different situations:
 774		
 775			-- 1. Zero-length "on" segments set in `set_dash'. If the cap
 776			-- style is `cairo_line_cap_round' or `cairo_line_cap_square'
 777			-- then these segments will be drawn as circular dots or
 778			-- squares respectively. In the case of
 779			-- `cairo_line_cap_square', the orientation of the squares is
 780			-- determined by the direction of the underlying path.
 781	
 782			-- 2. A sub-path created by `move_to' followed by either a
 783			-- `close_path' or one or more calls to `line_to' to the same
 784			-- coordinate as the `move_to'. If the cap style is
 785			-- `cairo_line_cap_round' then these sub-paths will be drawn
 786			-- as circular dots.  Note that in the case of
 787			-- `cairo_line_cap_square' a degenerate sub-path will not be
 788			-- drawn at all, (since the correct orientation is
 789			-- indeterminate).
 790			
 791			-- In no case will a cap style of `cairo_line_cap_butt' cause
 792			-- anything to be drawn in the case of either degenerate
 793			-- segments or sub-paths.
 794		do
 795			cairo_stroke(handle)
 796		end
 797
 798	stroke_preserve
 799			-- A drawing operator that strokes the current path according
 800			-- to the current line width, line join, line cap, and dash
 801			-- settings. Unlike `stroke', cairo_stroke_preserve preserves
 802			-- the path within the cairo context.
 803
 804			-- See `set_line_width', `set_line_join', `set_line_cap',
 805			-- `set_dash', and `stroke_preserve'.
 806		do
 807			cairo_stroke_preserve(handle)
 808		end
 809	
 810	stroke_extents: TUPLE [CAIRO_POINT, CAIRO_POINT]
 811			-- The stroke extents in format [(x1,y1),(x2,y2)]
 812		local
 813			an_x1, an_y1, an_x2, an_y2: REAL
 814			p1, p2: CAIRO_POINT
 815		do
 816			cairo_stroke_extents (handle, $an_x1, $an_y1, $an_x2, $an_y2)
 817			create p1.make(an_x1, an_y1)
 818			create p2.make(an_x2, an_y2)
 819			create Result.make_2(p1, p2)
 820		end
 821
 822	in_stroke (an_x, an_y: REAL): BOOLEAN
 823			-- Is the given point is on the area stroked by doing a
 824			-- `stroke' operation on current context given the current
 825			-- path and stroking parameters?
 826	
 827			-- See `stroke', `set_line_width', `set_line_join',
 828			-- `set_line_cap', `set_dash', and `stroke_preserve'.
 829
 830			-- `an_x': X coordinate of the point to test
 831		
 832			-- `an_y': Y coordinate of the point to test
 833		do
 834			Result := cairo_in_stroke (handle, an_x, an_y).to_boolean
 835		end
 836
 837	copy_page
 838			-- Emits the current page for backends that support multiple
 839			-- pages, but doesn't clear it, so, the contents of the
 840			-- current page will be retained for the next page too. Use
 841			-- `show_page' if you want to get an empty page after the
 842			-- emission.
 843		do
 844			cairo_copy_page (handle)
 845		end
 846
 847	show_page
 848			-- Emits and clears the current page for backends that
 849			-- support multiple pages. Use `copy_page' if you don't want
 850			-- to clear the page.
 851		do
 852			cairo_show_page (handle)
 853		end
 854
 855feature {ANY} -- Path managing
 856	get_path: CAIRO_PATH
 857			-- Creates a copy of the current path and returns it to the
 858			-- user as a cairo_path_t. See cairo_path_data_t for hints on
 859			-- how to iterate over the returned data structure.
 860
 861			-- The returned path can be unusable, having no data and
 862			-- `count'=0, if either of the following conditions hold:
 863	
 864			--    1. If there is insufficient memory to copy the path.
 865
 866			--    2. If the context is already in an error state.
 867	
 868			-- In either case, CAIRO_PATH's `status' will be set to
 869			-- `cairo_status_no_memory' (regardless of what the error
 870			-- status in cr might have been).
 871		do
 872			create Result.from_external_pointer (cairo_copy_path (handle))
 873		end
 874
 875	get_flat_path: CAIRO_PATHG
 876			-- Gets a newly-allocated flattened copy of the current path
 877	
 878			-- This feature is like `get_path' except that any curves in
 879			-- the path will be approximated with piecewise-linear
 880			-- approximations, (accurate to within the current tolerance
 881			-- value). That is, the result is guaranteed to not have any
 882			-- elements of type `cairo_path_curve_to' which will instead be
 883			-- replaced by a series of `cairo_path_line_to' elements.
 884		
 885			-- This function will always return a valid pointer, but the
 886			-- result will have no data (data==NULL and `count'=0), if
 887			-- either of the following conditions hold:
 888
 889			-- 1. If there is insufficient memory to copy the path. In
 890			-- this case Result.`status' will be set to
 891			-- `cairo_status_no_memory'.
 892		
 893			-- 2. If cr is already in an error state. In this case
 894			-- path.status will contain the same status that would be
 895			-- returned by Current.`status'.
 896		do
 897			from_external_pointer (cairo_copy_path_flat (handle))
 898		end
 899
 900	append_path (a_path: CAIRO_PATH)
 901			-- Append the path onto the current path. The path may be
 902			-- either obtained from `get_path' or `get_flat_path' or it
 903			-- may be created manually. 
 904		require
 905			path_not_void: a_path /= Void
 906			valid_path: a_path.status = cairo_status_success
 907		do
 908			cairo_append_path (handle, a_path.handle)
 909		end
 910	
 911	has_current_point: BOOLEAN
 912			-- TODO: implenment it, without using cairo_get_current_point
 913			-- which is *not* general; in fact it fails to discriminate
 914			-- between no point and the origin.
 915		do
 916		end
 917
 918	current_point: CAIRO_POINT
 919			-- the current point [x,y] of the current path, which is
 920			-- conceptually the final point reached by the path so far.
 921
 922			-- The current point is returned in the user-space coordinate
 923			-- system. If there is no defined current point then x and y
 924			-- will both be set to 0.0.
 925			
 926			-- Most path construction functions alter the current
 927			-- point. See the following for details on how they affect
 928			-- the current point:
 929	
 930			-- `new_path', `move_to', `line_to', `curve_to', `arc',
 931			-- `rel_move_to', `rel_line_to', `rel_curve_to', `text_path',
 932			-- `stroke_to_path'
 933		local
 934			an_x, an_y: REAL
 935		do
 936			cairo_get_current_point (handle, $an_x, $an_y)
 937			create Result.make (an_x,  an_y)
 938		ensure
 939			not_void: Result /= Void
 940		end
 941
 942	new_path
 943			-- Clears the current path. After this call there will be no
 944			-- path and no current point.
 945		do
 946			cairo_new_path (handle)
 947		end
 948
 949	new_sub_path
 950			-- Begin a new sub-path. Note that the existing path is not
 951			-- affected. After this call there will be no current point.
 952
 953			-- In many cases, this call is not needed since new sub-paths
 954			-- are frequently started with `move_to'.
 955		
 956			-- A call to `new_sub_path' is particularly useful when
 957			-- beginning a new sub-path with one of the `arc' calls. This
 958			-- makes things easier as it is no longer necessary to
 959			-- manually compute the arc's initial coordinates for a call
 960			-- to `move_to'.
 961		do
 962			cairo_new_sub_path(handle)
 963		end
 964
 965	close_path
 966			-- Adds a line segment to the path from the current point to
 967			-- the beginning of the current sub-path, (the most recent
 968			-- point passed to `move_to'), and closes this
 969			-- sub-path. After this call the current point will be at the
 970			-- joined endpoint of the sub-path.
 971
 972			-- The behavior of `close_path' is distinct from simply
 973			-- calling `line_to' with the equivalent coordinate in the
 974			-- case of stroking.  When a closed sub-path is stroked,
 975			-- there are no caps on the ends of the sub-path. Instead,
 976			-- there is a line join connecting the final and initial
 977			-- segments of the sub-path.
 978		
 979			-- If there is no current point before the call to
 980			-- `close_path', this function will have no effect.
 981
 982			-- Note: As of cairo version 1.2.4 any call to `close_path'
 983			-- will place an explicit MOVE_TO element into the path
 984			-- immediately after the CLOSE_PATH element, (which can be
 985			-- seen in `egt_path' for example). This can simplify path
 986			-- processing in some cases as it may not be necessary to
 987			-- save the "last move_to point" during processing as the
 988			-- MOVE_TO immediately after the CLOSE_PATH will provide that
 989			-- point.
 990		do
 991			cairo_close_path (handle)
 992		end
 993
 994	arc (an_x, an_y, a_radiud, an_angle_1, an_angle_2: REAL)
 995			-- Adds a circular arc of the given radius to the current
 996			-- path. The arc is centered at (`an_x', `an_y'), begins at
 997			-- `an_angle_1' and proceeds in the direction of increasing
 998			-- angles to end at `an_angle_2'. If `an_angle_2' is less than `an_angle_1' it
 999			-- will be progressively increased by 2*M_PI until it is
1000			-- greater than `an_angle_1'.
1001
1002			-- If there is a current point, an initial line segment will
1003			-- be added to the path to connect the current point to the
1004			-- beginning of the arc.
1005
1006			-- Angles are measured in radians. An angle of 0.0 is in the
1007			-- direction of the positive X axis (in user space). An angle
1008			-- of M_PI/2.0 radians (90 degrees) is in the direction of
1009			-- the positive Y axis (in user space). Angles increase in
1010			-- the direction from the positive X axis toward the positive
1011			-- Y axis. So with the default transformation matrix, angles
1012			-- increase in a clockwise direction.
1013
1014			-- (To convert from degrees to radians, use
1015			-- degrees*(M_PI/180.)).
1016
1017			-- This function gives the arc in the direction of increasing
1018			-- angles; see `arc_negative' to get the arc in the direction
1019			-- of decreasing angles.
1020
1021			-- The arc is circular in user space. To achieve an
1022			-- elliptical arc, you can scale the current transformation
1023			-- matrix by different amounts in the X and Y directions. For
1024			-- example, to draw an ellipse in the box given by x, y,
1025			-- width, height:
1026
1027			-- save 
1028			-- translate (x + width / 2., y + height / 2.)
1029			-- scale (1. / (height / 2.), 1. / (width / 2.))
1030			-- arc (0., 0., 1., 0., 2 * M_PI);
1031			-- restore
1032
1033			-- `an_x' :     X position of the center of the arc
1034			-- `an_y' :     Y position of the center of the arc
1035			-- `a_radius' : the radius of the arc
1036			-- `an_angle_1' : the start angle, in radians
1037			-- `an_angle_2' : the end angle, in radians
1038		do
1039			cairo_arc(handle, an_x, an_y, a_radiud, an_angle_1, an_angle_2)
1040		end
1041
1042	arc_negative (an_x, an_y, a_radiud, an_angle_1, an_angle_2: REAL)
1043			-- Adds a circular arc of the given radius to the current
1044			-- path. The arc is centered at (`an_x', `an_y'), begins at
1045			-- `an_angle_1' and proceeds in the direction of decreasing
1046			-- angles to end at `an_angle_2'. If `an_angle_2' is greater
1047			-- than `an_angle_1' it will be progressively decreased by
1048			-- 2*M_PI until it is greater than `an_angle_1'.
1049		
1050			-- See arc() for more details. This function differs only in
1051			-- the direction of the arc between the two angles.
1052		
1053			-- `an_x' :     X position of the center of the arc
1054			-- `an_y' :     Y position of the center of the arc
1055			-- `a_radius' : the radius of the arc
1056			-- `an_angle_1' : the start angle, in radians
1057			-- `an_angle_2' : the end angle, in radians
1058		do
1059			cairo_arc_negative (handle, an_x, an_y, a_radiud, an_angle_1, an_angle_2)
1060		end
1061
1062	curve_to (x1,y1,x2,y2,x3,y3: REAL)
1063			-- Adds a cubic Bezier spline to the path from the current
1064			-- point to position (x3, y3) in user-space coordinates,
1065			-- using (x1, y1) and (x2, y2) as the control points. After
1066			-- this call the current point will be (x3, y3).
1067		
1068			-- If there is no current point before the call to `curve_to'
1069			-- this function will behave as if preceded by a call to
1070			-- move_to (x1, y1).
1071
1072			--   x1 : the X coordinate of the first control point
1073			--   y1 : the Y coordinate of the first control point
1074			--   x2 : the X coordinate of the second control point
1075			--   y2 : the Y coordinate of the second control point
1076			--   x3 : the X coordinate of the end of the curve
1077			--   y3 : the Y coordinate of the end of the curve
1078		do
1079			cairo_curve_to(handle, x1, y1, x2,y2, x3, y3)
1080		end
1081
1082	line_to (an_x, an_y: REAL)
1083			-- Adds a line to the path from the current point to position
1084			-- (`an_x', `an_y') in user-space coordinates. After this call the
1085			-- current point will be (`an_x', `an_y').
1086
1087			-- If there is no current point before the call to `line_to'
1088			-- this function will behave as move_to(an_x,an_y).
1089
1090			-- `an_x' :  the X coordinate of the end of the new line
1091			-- `an_y' :  the Y coordinate of the end of the new line
1092		do
1093			cairo_line_to(handle,an_x,an_y)
1094		end
1095
1096	move_to (an_x, an_y: REAL)
1097			-- Begin a new sub-path. After this call the current point
1098			-- will be (`an_x', `an_y').
1099		
1100			-- `an_x' :  the X coordinate of the new position
1101			-- `an_y' :  the Y coordinate of the new position
1102		do
1103				cairo_move_to(handle,an_x,an_y)
1104		end
1105
1106	rectangle (an_x,an_y,a_width,an_height: REAL)
1107			-- Adds a closed sub-path rectangle of the given size to the
1108			-- current path at position (`an_x', `an_y') in user-space
1109			-- coordinates.
1110		
1111			-- This feature is logically equivalent to:
1112
1113			-- move_to (an_x, an_y);
1114			-- rel_line_to (a_width, 0);
1115			-- rel_line_to (0, an_height);
1116			-- rel_line_to (-a_width, 0);
1117			-- close_path
1118
1119			-- `an_x': the X coordinate of the top left corner of the rectangle
1120			-- `an_y': the Y coordinate to the top left corner of the rectangle
1121			-- `a_width':  the width of the rectangle
1122			-- `an_height': the height of the rectangle
1123		do
1124			cairo_rectangle(handle, an_x, an_y, a_width, an_height)
1125		end
1126
1127	-- TODO: cairo_glyph_path, since it is undocumented
1128
1129	-- void cairo_glyph_path (cairo_t *cr, cairo_glyph_t *glyphs, int
1130	-- num_glyphs);
1131
1132	-- TODO: cairo_text_path since it is undocumented
1133
1134	-- void cairo_text_path (cairo_t *cr, const char *utf8);
1135
1136
1137
1138	relative_curve_to (dx1,dy1,dx2,dy2,dx3,dy3: REAL)
1139			-- Relative-coordinate version of `curve_to'. All offsets are
1140			-- relative to the current point. Adds a cubic Bezier spline
1141			-- to the path from the current point to a point offset from
1142			-- the current point by (dx3, dy3), using points offset by
1143			-- (dx1, dy1) and (dx2, dy2) as the control points.  After
1144			-- this call the current point will be offset by (dx3, dy3).
1145
1146			-- Given a current point of (x, y), cairo_rel_curve_to (cr,
1147			-- dx1, dy1, dx2, dy2, dx3, dy3) is logically equivalent to
1148			-- cairo_curve_to (cr, x + dx1, y + dy1, x + dx2, y + dy2, x
1149			-- + dx3, y + dy3).
1150		
1151			-- It is an error to call this function with no current
1152			-- point. Doing so will cause the context to shutdown with a
1153			-- status of `cairo_status_no_current_point'.
1154
1155			--   dx1 : the X offset to the first control point
1156			--   dy1 : the Y offset to the first control point
1157			--   dx2 : the X offset to the second control point
1158			--   dy2 : the Y offset to the second control point
1159			--   dx3 : the X offset to the end of the curve
1160			--   dy3 : the Y offset to the end of the curve
1161		do
1162			cairo_rel_curve_to(handle,dx1,dy1,dx2,dy2,dx3,dy3)
1163		end
1164			
1165	relative_line_to (dx, dy: REAL)
1166			-- Relative-coordinate version of `line_to'. Adds a
1167			-- line to the path from the current point to a point that is
1168			-- offset from the current point by (dx, dy) in user
1169			-- space. After this call the current point will be offset by
1170			-- (dx, dy).
1171
1172			-- Given a current point (x, y), relative_line_to(dx,dy) is
1173			-- logically equivalent to line_to(x+dx,y+dy).
1174		
1175			-- It is an error to call this function with no current
1176			-- point. Doing so will cause cr to shutdown with a status of
1177			-- CAIRO_STATUS_NO_CURRENT_POINT.
1178		
1179			--   dx : the X offset to the end of the new line
1180			--   dy : the Y offset to the end of the new line		
1181		do
1182			cairo_rel_line_to(handle, dx, dy)
1183		end
1184
1185	relative_move_to (dx,dy: REAL)
1186			-- Begin a new sub-path. After this call the current point
1187			-- will offset by (x, y).
1188		
1189			-- Given a current point of (x, y), relative_move_to(dx,dy)
1190			-- is logically equivalent to move_to(x+dx,y+dy).
1191		
1192			-- It is an error to call this function with no current
1193			-- point. Doing so will cause cr to shutdown with a status of
1194			-- `cairo_status_no_current_point'.
1195		
1196			--   dx : the X offset
1197			--   dy : the Y offset
1198		do
1199			cairo_rel_move_to(handle, dx, dy)
1200		end
1201
1202feature {ANY} --   Transformations, manipulating the current transformation matrix
1203	translate (an_x, an_y: REAL)
1204			-- Modifies the current transformation matrix (CTM) by
1205			-- translating the user-space origin by (`an_x',`an_y'). This
1206			-- offset is interpreted as a user-space coordinate according
1207			-- to the CTM in place before the new call to `translate'. In
1208			-- other words, the translation of the user-space origin
1209			-- takes place after any existing transformation.
1210		
1211			-- `an_x' : amount to translate in the X direction
1212			-- `an_y' : amount to translate in the Y direction
1213		do
1214			cairo_translate(handle, an_x, an_y)
1215		end
1216	
1217	scale (an_x, an_y: REAL)
1218			-- Modifies the current transformation matrix (CTM) by
1219			-- scaling the X and Y user-space axes by `an_x' and `an_y'
1220			-- respectively. The scaling of the axes takes place after
1221			-- any existing transformation of user space.
1222		
1223			-- `an_x' : scale factor for the X dimension
1224			-- `an_y' : scale factor for the Y dimension
1225		do
1226			cairo_scale(handle,an_x,an_y)
1227		end
1228
1229	rotate (an_angle: REAL)
1230			-- Modifies the current transformation matrix (CTM) by
1231			-- rotating the user-space axes by angle radians. The
1232			-- rotation of the axes takes places after any existing
1233			-- transformation of user space. The rotation direction for
1234			-- positive angles is from the positive X axis toward the
1235			-- positive Y axis.
1236		
1237			-- `an_angle': the angle (in radians) by which the user-space
1238			-- axes will be rotated
1239		do
1240			cairo_rotate(handle, an_angle)
1241		end
1242	
1243	transform (a_matrix: CAIRO_MATRIX)
1244			-- Modifies the current transformation matrix (CTM) by
1245			-- applying `a_matrix' as an additional transformation. The
1246			-- new transformation of user space takes place after any
1247			-- existing transformation.
1248		require matrix_not_void: a_matrix/=Void
1249		do
1250			cairo_transform(handle, a_matrix.handle)
1251		end
1252
1253	set_matrix (a_matrix: CAIRO_MATRIX)
1254			-- Modifies the current transformation matrix (CTM) by
1255			-- setting it equal to `a_matrix', a transformation matrix
1256			-- from user space to device space.
1257		require matrix_not_void: a_matrix /= Void
1258		do
1259			cairo_set_matrix (handle, a_matrix.handle)
1260		end
1261
1262	matrix: CAIRO_MATRIX
1263			-- a new copy of the current transformation matrix (CTM).
1264		do
1265			create Result.allocate
1266			cairo_get_matrix (handle, Result.handle)
1267		end
1268
1269	reset_transformation
1270			-- Resets the current transformation matrix (CTM) by setting
1271			-- it equal to the identity matrix. That is, the user-space
1272			-- and device-space axes will be aligned and one user-space
1273			-- unit will transform to one device-space unit.
1274		do
1275			cairo_identity_matrix (handle)
1276		end
1277
1278feature {ANY} --   Text -- Rendering text and sets of glyphs
1279	select_font_face (a_family: STRING; a_slant, a_weight: INTEGER)
1280			-- Selects a family and style of font from a simplified
1281			-- description as a family name, slant and weight. This
1282			-- function is meant to be used only for applications with
1283			-- simple font needs: Cairo doesn't provide for operations
1284			-- such as listing all available fonts on the system, and it
1285			-- is expected that most applications will need to use a more
1286			-- comprehensive font handling and text layout library in
1287			-- addition to cairo.
1288		
1289			--   family : a font family name, encoded in UTF-8
1290			--   slant :  the slant for the font
1291			--   weight : the weight for the font
1292		require
1293			family_not_void: a_family /= Void
1294			valid_slant: is_valid_font_slant (a_slant)
1295			valid_weight: is_valid_font_weight (a_weight)
1296		do
1297			cairo_select_font_face (handle, a_family.to_external,
1298										  a_slant, a_weight)
1299		end
1300
1301	set_font_size (a_size: REAL)
1302			-- Sets the current font matrix to a scale by a factor of size,
1303			-- replacing any font matrix previously set with `set_font_size' or
1304			-- `set_font_matrix'. This results in a font size of size user
1305			-- space units. (More precisely, this matrix will result in the font's
1306			-- em-square being a size by size square in user space.)
1307		
1308			-- `a_size' : the new font size, in user space units
1309		do
1310			cairo_set_font_size (handle, a_size)
1311		end
1312
1313	set_font_matrix (a_matrix: CAIRO_MATRIX)
1314			-- Sets the current font matrix to matrix. The font matrix gives a
1315			-- transformation from the design space of the font (in this space, the
1316			-- em-square is 1 unit by 1 unit) to user space. Normally, a simple
1317			-- scale is used (see `set_font_size'), but a more complex font matrix
1318			-- can be used to shear the font or stretch it unequally along the two
1319			-- axes
1320
1321			-- `a_matrix': a cairo_matrix_t describing a transform to be applied to
1322			-- the current font.
1323		require
1324			matrix_not_void: a_matrix /= Void
1325		do
1326			cairo_set_font_matrix (handle, a_matrix.handle)
1327		end
1328
1329	font_matrix: CAIRO_MATRIX
1330			-- the current font matrix.
1331		do
1332			create Result.allocate
1333			cairo_get_font_matrix (handle, Result.handle)
1334		ensure
1335			Result /= Void
1336		end
1337
1338	set_font_options (some_options: CAIRO_FONT_OPTIONS)
1339			-- Sets a set of custom font rendering options for the
1340			-- context. Rendering options are derived by merging these options with
1341			-- the options derived from underlying surface; if the value in options
1342			-- has a default value (like CAIRO_ANTIALIAS_DEFAULT), then the value
1343			-- from the surface is used.
1344		require
1345			options_not_void: some_options /= Void
1346		do
1347			cairo_set_font_options(handle, some_options.handle)
1348		end
1349
1350	font_options: CAIRO_FONT_OPTIONS
1351			-- Retrieves font rendering options set via
1352			-- `set_font_options'. Note that the returned options do not
1353			-- include any options derived from the underlying surface;
1354			-- they are literally the options passed to
1355			-- `set_font_options'.
1356		do
1357			create Result.make
1358			cairo_get_font_options (handle, Result.handle)
1359		end
1360
1361	show_text (an_utf8: STRING)
1362			-- A drawing operator that generates the shape from a string
1363			-- of UTF-8 characters, rendered according to the current
1364			-- font_face, font_size (font_matrix), and font_options.
1365		
1366			-- This function first computes a set of glyphs for the
1367			-- string of text. The first glyph is placed so that its
1368			-- origin is at the current point. The origin of each
1369			-- subsequent glyph is offset from that of the previous glyph
1370			-- by the advance values of the previous glyph.
1371
1372			-- After this call the current point is moved to the origin
1373			-- of where the next glyph would be placed in this same
1374			-- progression. That is, the current point will be at the
1375			-- origin of the final glyph offset by its advance values.
1376			-- This allows for easy display of a single logical string
1377			-- with multiple calls to `show_text'.
1378
1379			-- NOTE: The `show_text' function call is part of what the
1380			-- cairo designers call the "toy" text API. It is convenient
1381			-- for short demos and simple programs, but it is not
1382			-- expected to be adequate for the most serious of text-using
1383			-- applications. See `show_glyphs' for the "real" text
1384			-- display API in cairo.
1385		do
1386			cairo_show_text (handle, an_utf8.to_external)
1387		end
1388
1389	show_glyphs (some_glyphs: ARRAY [INTEGER_32])
1390		require
1391			glyphs_not_void: some_glyphs /= Void
1392		do
1393			cairo_show_glyphs (handle, some_glyphs.to_external,
1394									some_glyphs.count)
1395		end
1396
1397	font_face: CAIRO_FONT_FACE
1398			-- the current font face for a cairo_t.
1399		local
1400			ptr: POINTER
1401		do
1402			ptr := cairo_get_font_face (handle)
1403			-- cairo_get_font_face returns the current font object. Can
1404			-- return NULL on out-of-memory or if the context is…

Large files files are truncated, but you can click here to view the full file