/src/wrappers/cairo/library/cairo_scaled_font.e
Specman e | 387 lines | 67 code | 24 blank | 296 comment | 2 complexity | 18a9227f813c2190a301b2a6e858f713 MD5 | raw file
1note 2 description: "Scaled Fonts -- Caching metrics for a particular font size." 3 copyright: "[ 4 Copyright (C) 2007-2017: Paolo Redaelli, GTK+ team 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Lesser General Public License 8 as published by the Free Software Foundation; either version 2.1 of 9 the License, or (at your option) any later version. 10 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 16 You should have received a copy of the GNU Lesser General Public 17 License along with this library; if not, write to the Free Software 18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA 20 ]" 21 22 wrapped_version: "1.2.4" 23 24class CAIRO_SCALED_FONT 25 -- A CAIRO_SCALED_FONT is a font scaled to a particular size and 26 -- device resolution. It is most useful for low-level font usage 27 -- where a library or application wants to cache a reference to a 28 -- scaled font to speed up the computation of metrics. 29 30 -- TODO: mostly unimplemented 31inherit C_STRUCT 32 33create {ANY} from_external_pointer 34 35feature {} -- Creation 36 37 -- -------------------------------------------------------------------------- 38 -- 39 -- cairo_scaled_font_create () 40 -- 41 -- cairo_scaled_font_t* cairo_scaled_font_create 42 -- (cairo_font_face_t *font_face, 43 -- const cairo_matrix_t *font_matrix, 44 -- const cairo_matrix_t *ctm, 45 -- const cairo_font_options_t *options); 46 -- 47 -- Creates a cairo_scaled_font_t object from a font face and matrices that 48 -- describe the size of the font and the environment in which it will be 49 -- used. 50 -- 51 -- font_face : a cairo_font_face_t 52 -- font_matrix : font space to user space transformation matrix for the font. 53 -- In the simplest case of a N point font, this matrix is just 54 -- a scale by N, but it can also be used to shear the font or 55 -- stretch it unequally along the two axes. See 56 -- cairo_set_font_matrix(). 57 -- ctm : user to device transformation matrix with which the font 58 -- will be used. 59 -- options : options to use when getting metrics for the font and 60 -- rendering with it. 61 -- Returns : a newly created cairo_scaled_font_t. Destroy with 62 -- cairo_scaled_font_destroy() 63 -- 64 -- -------------------------------------------------------------------------- 65 -- 66 -- cairo_scaled_font_reference () 67 -- 68 -- cairo_scaled_font_t* cairo_scaled_font_reference 69 -- (cairo_scaled_font_t *scaled_font); 70 -- 71 -- Increases the reference count on scaled_font by one. This prevents 72 -- scaled_font from being destroyed until a matching call to 73 -- cairo_scaled_font_destroy() is made. 74 -- 75 -- scaled_font : a cairo_scaled_font_t, (may be NULL in which case this 76 -- function does nothing) 77 -- Returns : the referenced cairo_scaled_font_t 78 -- 79 -- -------------------------------------------------------------------------- 80 -- 81 -- cairo_scaled_font_destroy () 82 -- 83 -- void cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font); 84 -- 85 -- Decreases the reference count on font by one. If the result is zero, then 86 -- font and all associated resources are freed. See 87 -- cairo_scaled_font_reference(). 88 -- 89 -- scaled_font : a cairo_scaled_font_t 90 -- 91 -- -------------------------------------------------------------------------- 92 -- 93 -- cairo_scaled_font_status () 94 -- 95 -- cairo_status_t cairo_scaled_font_status (cairo_scaled_font_t *scaled_font); 96 -- 97 -- Checks whether an error has previously occurred for this scaled_font. 98 -- 99 -- scaled_font : a cairo_scaled_font_t 100 -- Returns : CAIRO_STATUS_SUCCESS or another error such as 101 -- CAIRO_STATUS_NO_MEMORY. 102 -- 103 -- -------------------------------------------------------------------------- 104 -- 105 -- cairo_font_extents_t 106 -- 107 -- typedef struct { 108 -- double ascent; 109 -- double descent; 110 -- double height; 111 -- double max_x_advance; 112 -- double max_y_advance; 113 -- } cairo_font_extents_t; 114 -- 115 -- The cairo_font_extents_t structure stores metric information for a font. 116 -- Values are given in the current user-space coordinate system. 117 -- 118 -- Because font metrics are in user-space coordinates, they are mostly, but 119 -- not entirely, independent of the current transformation matrix. If you 120 -- call cairo_scale(cr, 2.0, 2.0), text will be drawn twice as big, but the 121 -- reported text extents will not be doubled. They will change slightly due 122 -- to hinting (so you can't assume that metrics are independent of the 123 -- transformation matrix), but otherwise will remain unchanged. 124 -- 125 -- double ascent; the distance that the font extends above the 126 -- baseline. Note that this is not always exactly equal 127 -- to the maximum of the extents of all the glyphs in 128 -- the font, but rather is picked to express the font 129 -- designer's intent as to how the font should align 130 -- with elements above it. 131 -- double descent; the distance that the font extends below the 132 -- baseline. This value is positive for typical fonts 133 -- that include portions below the baseline. Note that 134 -- this is not always exactly equal to the maximum of 135 -- the extents of all the glyphs in the font, but 136 -- rather is picked to express the font designer's 137 -- intent as to how the the font should align with 138 -- elements below it. 139 -- double height; the recommended vertical distance between baselines 140 -- when setting consecutive lines of text with the 141 -- font. This is greater than ascent+descent by a 142 -- quantity known as the line spacing or external 143 -- leading. When space is at a premium, most fonts can 144 -- be set with only a distance of ascent+descent 145 -- between lines. 146 -- double max_x_advance; the maximum distance in the X direction that the the 147 -- origin is advanced for any glyph in the font. 148 -- double max_y_advance; the maximum distance in the Y direction that the the 149 -- origin is advanced for any glyph in the font. this 150 -- will be zero for normal fonts used for horizontal 151 -- writing. (The scripts of East Asia are sometimes 152 -- written vertically.) 153 -- 154 -- -------------------------------------------------------------------------- 155 -- 156 -- cairo_scaled_font_extents () 157 -- 158 -- void cairo_scaled_font_extents (cairo_scaled_font_t *scaled_font, 159 -- cairo_font_extents_t *extents); 160 -- 161 -- Gets the metrics for a cairo_scaled_font_t. 162 -- 163 -- scaled_font : a cairo_scaled_font_t 164 -- extents : a cairo_font_extents_t which to store the retrieved extents. 165 -- 166 -- -------------------------------------------------------------------------- 167 -- 168 -- cairo_text_extents_t 169 -- 170 -- typedef struct { 171 -- double x_bearing; 172 -- double y_bearing; 173 -- double width; 174 -- double height; 175 -- double x_advance; 176 -- double y_advance; 177 -- } cairo_text_extents_t; 178 -- 179 -- The cairo_text_extents_t structure stores the extents of a single glyph or 180 -- a string of glyphs in user-space coordinates. Because text extents are in 181 -- user-space coordinates, they are mostly, but not entirely, independent of 182 -- the current transformation matrix. If you call cairo_scale(cr, 2.0, 2.0), 183 -- text will be drawn twice as big, but the reported text extents will not be 184 -- doubled. They will change slightly due to hinting (so you can't assume 185 -- that metrics are independent of the transformation matrix), but otherwise 186 -- will remain unchanged. 187 -- 188 -- double x_bearing; the horizontal distance from the origin to the leftmost 189 -- part of the glyphs as drawn. Positive if the glyphs lie 190 -- entirely to the right of the origin. 191 -- double y_bearing; the vertical distance from the origin to the topmost 192 -- part of the glyphs as drawn. Positive only if the glyphs 193 -- lie completely below the origin; will usually be 194 -- negative. 195 -- double width; width of the glyphs as drawn 196 -- double height; height of the glyphs as drawn 197 -- double x_advance; distance to advance in the X direction after drawing 198 -- these glyphs 199 -- double y_advance; distance to advance in the Y direction after drawing 200 -- these glyphs. Will typically be zero except for vertical 201 -- text layout as found in East-Asian languages. 202 -- 203 -- -------------------------------------------------------------------------- 204 -- 205 -- cairo_scaled_font_text_extents () 206 -- 207 -- void cairo_scaled_font_text_extents (cairo_scaled_font_t *scaled_font, 208 -- const char *utf8, 209 -- cairo_text_extents_t *extents); 210 -- 211 -- Gets the extents for a string of text. The extents describe a user-space 212 -- rectangle that encloses the "inked" portion of the text drawn at the 213 -- origin (0,0) (as it would be drawn by cairo_show_text() if the cairo 214 -- graphics state were set to the same font_face, font_matrix, ctm, and 215 -- font_options as scaled_font). Additionally, the x_advance and y_advance 216 -- values indicate the amount by which the current point would be advanced by 217 -- cairo_show_text(). 218 -- 219 -- Note that whitespace characters do not directly contribute to the size of 220 -- the rectangle (extents.width and extents.height). They do contribute 221 -- indirectly by changing the position of non-whitespace characters. In 222 -- particular, trailing whitespace characters are likely to not affect the 223 -- size of the rectangle, though they will affect the x_advance and y_advance 224 -- values. 225 -- 226 -- scaled_font : a cairo_scaled_font_t 227 -- utf8 : a string of text, encoded in UTF-8 228 -- extents : a cairo_text_extents_t which to store the retrieved extents. 229 -- 230 -- Since 1.2 231 -- 232 -- -------------------------------------------------------------------------- 233 -- 234 -- cairo_scaled_font_glyph_extents () 235 -- 236 -- void cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font, 237 -- cairo_glyph_t *glyphs, 238 -- int num_glyphs, 239 -- cairo_text_extents_t *extents); 240 -- 241 -- Gets the extents for an array of glyphs. The extents describe a user-space 242 -- rectangle that encloses the "inked" portion of the glyphs, (as they would 243 -- be drawn by cairo_show_glyphs() if the cairo graphics state were set to 244 -- the same font_face, font_matrix, ctm, and font_options as scaled_font). 245 -- Additionally, the x_advance and y_advance values indicate the amount by 246 -- which the current point would be advanced by cairo_show_glyphs. 247 -- 248 -- Note that whitespace glyphs do not contribute to the size of the rectangle 249 -- (extents.width and extents.height). 250 -- 251 -- scaled_font : a cairo_scaled_font_t 252 -- glyphs : an array of glyph IDs with X and Y offsets. 253 -- num_glyphs : the number of glyphs in the glyphs array 254 -- extents : a cairo_text_extents_t which to store the retrieved extents. 255 -- 256 -- -------------------------------------------------------------------------- 257 -- 258 -- cairo_scaled_font_get_font_face () 259 -- 260 -- cairo_font_face_t* cairo_scaled_font_get_font_face 261 -- (cairo_scaled_font_t *scaled_font); 262 -- 263 -- Gets the font face that this scaled font was created for. 264 -- 265 -- scaled_font : a cairo_scaled_font_t 266 -- Returns : The cairo_font_face_t with which scaled_font was created. 267 -- 268 -- Since 1.2 269 -- 270 -- -------------------------------------------------------------------------- 271 -- 272 -- cairo_scaled_font_get_font_options () 273 -- 274 -- void cairo_scaled_font_get_font_options 275 -- (cairo_scaled_font_t *scaled_font, 276 -- cairo_font_options_t *options); 277 -- 278 -- Stores the font options with which scaled_font was created into options. 279 -- 280 -- scaled_font : a cairo_scaled_font_t 281 -- options : return value for the font options 282 -- 283 -- Since 1.2 284 -- 285 -- -------------------------------------------------------------------------- 286 -- 287 -- cairo_scaled_font_get_font_matrix () 288 -- 289 -- void cairo_scaled_font_get_font_matrix 290 -- (cairo_scaled_font_t *scaled_font, 291 -- cairo_matrix_t *font_matrix); 292 -- 293 -- Stores the font matrix with which scaled_font was created into matrix. 294 -- 295 -- scaled_font : a cairo_scaled_font_t 296 -- font_matrix : return value for the matrix 297 -- 298 -- Since 1.2 299 -- 300 -- -------------------------------------------------------------------------- 301 -- 302 -- cairo_scaled_font_get_ctm () 303 -- 304 -- void cairo_scaled_font_get_ctm (cairo_scaled_font_t *scaled_font, 305 -- cairo_matrix_t *ctm); 306 -- 307 -- Stores the CTM with which scaled_font was created into ctm. 308 -- 309 -- scaled_font : a cairo_scaled_font_t 310 -- ctm : return value for the CTM 311 -- 312 -- Since 1.2 313 -- 314 -- -------------------------------------------------------------------------- 315 -- 316 -- cairo_scaled_font_get_type () 317 -- 318 -- cairo_font_type_t cairo_scaled_font_get_type 319 -- (cairo_scaled_font_t *scaled_font); 320 -- 321 -- This function returns the type of the backend used to create a scaled 322 -- font. See cairo_font_type_t for available types. 323 -- 324 -- scaled_font : a cairo_scaled_font_t 325 -- Returns : The type of scaled_font. 326 -- 327 -- Since 1.2 328 329feature {ANY} -- Memory handling 330 dispose do free(handle) end 331 332feature {ANY} -- size 333 struct_size: INTEGER 334 external "C inline use <cairo.h>" 335 alias "sizeof(cairo_scaled_font_t)" 336 end 337 338feature {} -- External calls 339 cairo_scaled_font_create (a_font_face, a_font_matrix, a_ctm_matrix, some_font_options: POINTER): POINTER 340 external "C use <cairo.h>" 341 end 342 343 cairo_scaled_font_reference (a_scaled_font: POINTER): POINTER 344 external "C use <cairo.h>" 345 end 346 347 cairo_scaled_font_destroy (a_scaled_font: POINTER) 348 external "C use <cairo.h>" 349 end 350 351 cairo_scaled_font_status (a_scaled_font: POINTER): INTEGER 352 external "C use <cairo.h>" 353 end 354 355 cairo_scaled_font_extents (a_scaled_font, an_extents: POINTER) 356 external "C use <cairo.h>" 357 end 358 359 cairo_scaled_font_text_extents (a_scaled_font, an_utf8, an_extents: POINTER) 360 external "C use <cairo.h>" 361 end 362 363 cairo_scaled_font_glyph_extents (a_scaled_font, some_glyphs: POINTER; a_glyph_num: INTEGER; some_extents: POINTER) 364 external "C use <cairo.h>" 365 end 366 367 cairo_scaled_font_get_font_face (a_scaled_font: POINTER): POINTER 368 external "C use <cairo.h>" 369 end 370 371 cairo_scaled_font_get_font_options (a_scaled_font, a_font_options: POINTER) 372 external "C use <cairo.h>" 373 end 374 375 cairo_scaled_font_get_font_matrix (a_scaled_font, a_font_matrix: POINTER) 376 external "C use <cairo.h>" 377 end 378 379 cairo_scaled_font_get_ctm (a_scaled_font, a_ctm_matrix: POINTER) 380 external "C use <cairo.h>" 381 end 382 383 cairo_scaled_font_get_type (a_scaled_font: POINTER): INTEGER 384 external "C use <cairo.h>" 385 end 386 387end -- class CAIRO_SCALED_FONT