PageRenderTime 54ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 1ms

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