1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module atk.TextIF; 26 27 private import glib.Str; 28 private import gobject.Signals; 29 private import gtkc.atk; 30 public import gtkc.atktypes; 31 public import gtkc.gdktypes; 32 33 34 /** 35 * #AtkText should be implemented by #AtkObjects on behalf of widgets 36 * that have text content which is either attributed or otherwise 37 * non-trivial. #AtkObjects whose text content is simple, 38 * unattributed, and very brief may expose that content via 39 * #atk_object_get_name instead; however if the text is editable, 40 * multi-line, typically longer than three or four words, attributed, 41 * selectable, or if the object already uses the 'name' ATK property 42 * for other information, the #AtkText interface should be used to 43 * expose the text content. In the case of editable text content, 44 * #AtkEditableText (a subtype of the #AtkText interface) should be 45 * implemented instead. 46 * 47 * #AtkText provides not only traversal facilities and change 48 * notification for text content, but also caret tracking and glyph 49 * bounding box calculations. Note that the text strings are exposed 50 * as UTF-8, and are therefore potentially multi-byte, and 51 * caret-to-byte offset mapping makes no assumptions about the 52 * character length; also bounding box glyph-to-offset mapping may be 53 * complex for languages which use ligatures. 54 */ 55 public interface TextIF{ 56 /** Get the main Gtk struct */ 57 public AtkText* getTextStruct(); 58 59 /** the main Gtk struct as a void* */ 60 protected void* getStruct(); 61 62 63 /** 64 * Frees the memory associated with an array of AtkTextRange. It is assumed 65 * that the array was returned by the function atk_text_get_bounded_ranges 66 * and is NULL terminated. 67 * 68 * Params: 69 * ranges = A pointer to an array of #AtkTextRange which is 70 * to be freed. 71 * 72 * Since: 1.3 73 */ 74 public static void freeRanges(AtkTextRange*[] ranges); 75 76 /** 77 * Adds a selection bounded by the specified offsets. 78 * 79 * Params: 80 * startOffset = the start position of the selected region 81 * endOffset = the offset of the first character after the selected region. 82 * 83 * Return: %TRUE if success, %FALSE otherwise 84 */ 85 public bool addSelection(int startOffset, int endOffset); 86 87 /** 88 * Get the ranges of text in the specified bounding box. 89 * 90 * Params: 91 * rect = An AtkTextRectangle giving the dimensions of the bounding box. 92 * coordType = Specify whether coordinates are relative to the screen or widget window. 93 * xClipType = Specify the horizontal clip type. 94 * yClipType = Specify the vertical clip type. 95 * 96 * Return: Array of AtkTextRange. The last 97 * element of the array returned by this function will be NULL. 98 * 99 * Since: 1.3 100 */ 101 public AtkTextRange*[] getBoundedRanges(AtkTextRectangle* rect, AtkCoordType coordType, AtkTextClipType xClipType, AtkTextClipType yClipType); 102 103 /** 104 * Gets the offset position of the caret (cursor). 105 * 106 * Return: the offset position of the caret (cursor). 107 */ 108 public int getCaretOffset(); 109 110 /** 111 * Gets the specified text. 112 * 113 * Params: 114 * offset = position 115 * 116 * Return: the character at @offset. 117 */ 118 public dchar getCharacterAtOffset(int offset); 119 120 /** 121 * Gets the character count. 122 * 123 * Return: the number of characters. 124 */ 125 public int getCharacterCount(); 126 127 /** 128 * Get the bounding box containing the glyph representing the character at 129 * a particular text offset. 130 * 131 * Params: 132 * offset = The offset of the text character for which bounding information is required. 133 * x = Pointer for the x cordinate of the bounding box 134 * y = Pointer for the y cordinate of the bounding box 135 * width = Pointer for the width of the bounding box 136 * height = Pointer for the height of the bounding box 137 * coords = specify whether coordinates are relative to the screen or widget window 138 */ 139 public void getCharacterExtents(int offset, out int x, out int y, out int width, out int height, AtkCoordType coords); 140 141 /** 142 * Creates an #AtkAttributeSet which consists of the default values of 143 * attributes for the text. See the enum AtkTextAttribute for types of text 144 * attributes that can be returned. Note that other attributes may also be 145 * returned. 146 * 147 * Return: an #AtkAttributeSet which contains the default 148 * values of attributes. at @offset. this #atkattributeset should be freed by 149 * a call to atk_attribute_set_free(). 150 */ 151 public AtkAttributeSet* getDefaultAttributes(); 152 153 /** 154 * Gets the number of selected regions. 155 * 156 * Return: The number of selected regions, or -1 if a failure 157 * occurred. 158 */ 159 public int getNSelections(); 160 161 /** 162 * Gets the offset of the character located at coordinates @x and @y. @x and @y 163 * are interpreted as being relative to the screen or this widget's window 164 * depending on @coords. 165 * 166 * Params: 167 * x = screen x-position of character 168 * y = screen y-position of character 169 * coords = specify whether coordinates are relative to the screen or 170 * widget window 171 * 172 * Return: the offset to the character which is located at 173 * the specified @x and @y coordinates. 174 */ 175 public int getOffsetAtPoint(int x, int y, AtkCoordType coords); 176 177 /** 178 * Get the bounding box for text within the specified range. 179 * 180 * Params: 181 * startOffset = The offset of the first text character for which boundary 182 * information is required. 183 * endOffset = The offset of the text character after the last character 184 * for which boundary information is required. 185 * coordType = Specify whether coordinates are relative to the screen or widget window. 186 * rect = A pointer to a AtkTextRectangle which is filled in by this function. 187 * 188 * Since: 1.3 189 */ 190 public void getRangeExtents(int startOffset, int endOffset, AtkCoordType coordType, out AtkTextRectangle rect); 191 192 /** 193 * Creates an #AtkAttributeSet which consists of the attributes explicitly 194 * set at the position @offset in the text. @start_offset and @end_offset are 195 * set to the start and end of the range around @offset where the attributes are 196 * invariant. Note that @end_offset is the offset of the first character 197 * after the range. See the enum AtkTextAttribute for types of text 198 * attributes that can be returned. Note that other attributes may also be 199 * returned. 200 * 201 * Params: 202 * offset = the offset at which to get the attributes, -1 means the offset of 203 * the character to be inserted at the caret location. 204 * startOffset = the address to put the start offset of the range 205 * endOffset = the address to put the end offset of the range 206 * 207 * Return: an #AtkAttributeSet which contains the attributes 208 * explicitly set at @offset. This #AtkAttributeSet should be freed by a call 209 * to atk_attribute_set_free(). 210 */ 211 public AtkAttributeSet* getRunAttributes(int offset, out int startOffset, out int endOffset); 212 213 /** 214 * Gets the text from the specified selection. 215 * 216 * Params: 217 * selectionNum = The selection number. The selected regions are 218 * assigned numbers that correspond to how far the region is from the 219 * start of the text. The selected region closest to the beginning 220 * of the text region is assigned the number 0, etc. Note that adding, 221 * moving or deleting a selected region can change the numbering. 222 * startOffset = passes back the start position of the selected region 223 * endOffset = passes back the end position of (e.g. offset immediately past) 224 * the selected region 225 * 226 * Return: a newly allocated string containing the selected text. Use g_free() 227 * to free the returned string. 228 */ 229 public string getSelection(int selectionNum, out int startOffset, out int endOffset); 230 231 /** 232 * Gets a portion of the text exposed through an #AtkText according to a given @offset 233 * and a specific @granularity, along with the start and end offsets defining the 234 * boundaries of such a portion of text. 235 * 236 * If @granularity is ATK_TEXT_GRANULARITY_CHAR the character at the 237 * offset is returned. 238 * 239 * If @granularity is ATK_TEXT_GRANULARITY_WORD the returned string 240 * is from the word start at or before the offset to the word start after 241 * the offset. 242 * 243 * The returned string will contain the word at the offset if the offset 244 * is inside a word and will contain the word before the offset if the 245 * offset is not inside a word. 246 * 247 * If @granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string 248 * is from the sentence start at or before the offset to the sentence 249 * start after the offset. 250 * 251 * The returned string will contain the sentence at the offset if the offset 252 * is inside a sentence and will contain the sentence before the offset 253 * if the offset is not inside a sentence. 254 * 255 * If @granularity is ATK_TEXT_GRANULARITY_LINE the returned string 256 * is from the line start at or before the offset to the line 257 * start after the offset. 258 * 259 * If @granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string 260 * is from the start of the paragraph at or before the offset to the start 261 * of the following paragraph after the offset. 262 * 263 * Params: 264 * offset = position 265 * granularity = An #AtkTextGranularity 266 * startOffset = the start offset of the returned string, or -1 267 * if an error has occurred (e.g. invalid offset, not implemented) 268 * endOffset = the offset of the first character after the returned string, 269 * or -1 if an error has occurred (e.g. invalid offset, not implemented) 270 * 271 * Return: a newly allocated string containing the text 272 * at the @offset bounded by the specified @granularity. Use 273 * g_free() to free the returned string. Returns %NULL if the 274 * offset is invalid or no implementation is available. 275 * 276 * Since: 2.10 277 */ 278 public string getStringAtOffset(int offset, AtkTextGranularity granularity, out int startOffset, out int endOffset); 279 280 /** 281 * Gets the specified text. 282 * 283 * Params: 284 * startOffset = start position 285 * endOffset = end position, or -1 for the end of the string. 286 * 287 * Return: a newly allocated string containing the text from @start_offset up 288 * to, but not including @end_offset. Use g_free() to free the returned string. 289 */ 290 public string getText(int startOffset, int endOffset); 291 292 /** 293 * Gets the specified text. 294 * 295 * Deprecated: Please use atk_text_get_string_at_offset() instead. 296 * 297 * Params: 298 * offset = position 299 * boundaryType = An #AtkTextBoundary 300 * startOffset = the start offset of the returned string 301 * endOffset = the offset of the first character after the 302 * returned substring 303 * 304 * Return: a newly allocated string containing the text after @offset bounded 305 * by the specified @boundary_type. Use g_free() to free the returned string. 306 */ 307 public string getTextAfterOffset(int offset, AtkTextBoundary boundaryType, out int startOffset, out int endOffset); 308 309 /** 310 * Gets the specified text. 311 * 312 * If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the 313 * offset is returned. 314 * 315 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string 316 * is from the word start at or before the offset to the word start after 317 * the offset. 318 * 319 * The returned string will contain the word at the offset if the offset 320 * is inside a word and will contain the word before the offset if the 321 * offset is not inside a word. 322 * 323 * If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned 324 * string is from the sentence start at or before the offset to the sentence 325 * start after the offset. 326 * 327 * The returned string will contain the sentence at the offset if the offset 328 * is inside a sentence and will contain the sentence before the offset 329 * if the offset is not inside a sentence. 330 * 331 * If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned 332 * string is from the line start at or before the offset to the line 333 * start after the offset. 334 * 335 * Deprecated: This method is deprecated since ATK version 336 * 2.9.4. Please use atk_text_get_string_at_offset() instead. 337 * 338 * Params: 339 * offset = position 340 * boundaryType = An #AtkTextBoundary 341 * startOffset = the start offset of the returned string 342 * endOffset = the offset of the first character after the 343 * returned substring 344 * 345 * Return: a newly allocated string containing the text at @offset bounded by 346 * the specified @boundary_type. Use g_free() to free the returned string. 347 */ 348 public string getTextAtOffset(int offset, AtkTextBoundary boundaryType, out int startOffset, out int endOffset); 349 350 /** 351 * Gets the specified text. 352 * 353 * Deprecated: Please use atk_text_get_string_at_offset() instead. 354 * 355 * Params: 356 * offset = position 357 * boundaryType = An #AtkTextBoundary 358 * startOffset = the start offset of the returned string 359 * endOffset = the offset of the first character after the 360 * returned substring 361 * 362 * Return: a newly allocated string containing the text before @offset bounded 363 * by the specified @boundary_type. Use g_free() to free the returned string. 364 */ 365 public string getTextBeforeOffset(int offset, AtkTextBoundary boundaryType, out int startOffset, out int endOffset); 366 367 /** 368 * Removes the specified selection. 369 * 370 * Params: 371 * selectionNum = The selection number. The selected regions are 372 * assigned numbers that correspond to how far the region is from the 373 * start of the text. The selected region closest to the beginning 374 * of the text region is assigned the number 0, etc. Note that adding, 375 * moving or deleting a selected region can change the numbering. 376 * 377 * Return: %TRUE if success, %FALSE otherwise 378 */ 379 public bool removeSelection(int selectionNum); 380 381 /** 382 * Sets the caret (cursor) position to the specified @offset. 383 * 384 * Params: 385 * offset = position 386 * 387 * Return: %TRUE if success, %FALSE otherwise. 388 */ 389 public bool setCaretOffset(int offset); 390 391 /** 392 * Changes the start and end offset of the specified selection. 393 * 394 * Params: 395 * selectionNum = The selection number. The selected regions are 396 * assigned numbers that correspond to how far the region is from the 397 * start of the text. The selected region closest to the beginning 398 * of the text region is assigned the number 0, etc. Note that adding, 399 * moving or deleting a selected region can change the numbering. 400 * startOffset = the new start position of the selection 401 * endOffset = the new end position of (e.g. offset immediately past) 402 * the selection 403 * 404 * Return: %TRUE if success, %FALSE otherwise 405 */ 406 public bool setSelection(int selectionNum, int startOffset, int endOffset); 407 @property void delegate(TextIF)[] onTextAttributesChangedListeners(); 408 /** 409 * The "text-attributes-changed" signal is emitted when the text 410 * attributes of the text of an object which implements AtkText 411 * changes. 412 */ 413 void addOnTextAttributesChanged(void delegate(TextIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 414 415 @property void delegate(int, TextIF)[] onTextCaretMovedListeners(); 416 /** 417 * The "text-caret-moved" signal is emitted when the caret 418 * position of the text of an object which implements AtkText 419 * changes. 420 * 421 * Params: 422 * arg1 = The new position of the text caret. 423 */ 424 void addOnTextCaretMoved(void delegate(int, TextIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 425 426 @property void delegate(int, int, TextIF)[] onTextChangedListeners(); 427 /** 428 * The "text-changed" signal is emitted when the text of the 429 * object which implements the AtkText interface changes, This 430 * signal will have a detail which is either "insert" or 431 * "delete" which identifies whether the text change was an 432 * insertion or a deletion. 433 * 434 * Deprecated: Use #AtkObject::text-insert or 435 * #AtkObject::text-remove instead. 436 * 437 * Params: 438 * arg1 = The position (character offset) of the insertion or deletion. 439 * arg2 = The length (in characters) of text inserted or deleted. 440 */ 441 void addOnTextChanged(void delegate(int, int, TextIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 442 443 @property void delegate(int, int, string, TextIF)[] onTextInsertListeners(); 444 /** 445 * The "text-insert" signal is emitted when a new text is 446 * inserted. If the signal was not triggered by the user 447 * (e.g. typing or pasting text), the "system" detail should be 448 * included. 449 * 450 * Params: 451 * arg1 = The position (character offset) of the insertion. 452 * arg2 = The length (in characters) of text inserted. 453 * arg3 = The new text inserted 454 */ 455 void addOnTextInsert(void delegate(int, int, string, TextIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 456 457 @property void delegate(int, int, string, TextIF)[] onTextRemoveListeners(); 458 /** 459 * The "text-remove" signal is emitted when a new text is 460 * removed. If the signal was not triggered by the user 461 * (e.g. typing or pasting text), the "system" detail should be 462 * included. 463 * 464 * Params: 465 * arg1 = The position (character offset) of the removal. 466 * arg2 = The length (in characters) of text removed. 467 * arg3 = The old text removed 468 */ 469 void addOnTextRemove(void delegate(int, int, string, TextIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 470 471 @property void delegate(TextIF)[] onTextSelectionChangedListeners(); 472 /** 473 * The "text-selection-changed" signal is emitted when the 474 * selected text of an object which implements AtkText changes. 475 */ 476 void addOnTextSelectionChanged(void delegate(TextIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 477 478 479 /** 480 * Frees the memory used by an #AtkAttributeSet, including all its 481 * #AtkAttributes. 482 * 483 * Params: 484 * attribSet = The #AtkAttributeSet to free 485 */ 486 public static void attributeSetFree(AtkAttributeSet* attribSet); 487 488 /** 489 * Get the #AtkTextAttribute type corresponding to a text attribute name. 490 * 491 * Params: 492 * name = a string which is the (non-localized) name of an ATK text attribute. 493 * 494 * Return: the #AtkTextAttribute enumerated type corresponding to the specified 495 * name, 496 * or #ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute is found. 497 */ 498 public static AtkTextAttribute attributeForName(string name); 499 500 /** 501 * Gets the name corresponding to the #AtkTextAttribute 502 * 503 * Params: 504 * attr = The #AtkTextAttribute whose name is required 505 * 506 * Return: a string containing the name; this string should not be freed 507 */ 508 public static string attributeGetName(AtkTextAttribute attr); 509 510 /** 511 * Gets the value for the index of the #AtkTextAttribute 512 * 513 * Params: 514 * attr = The #AtkTextAttribute for which a value is required 515 * index = The index of the required value 516 * 517 * Return: a string containing the value; this string 518 * should not be freed; %NULL is returned if there are no values 519 * maintained for the attr value. 520 */ 521 public static string attributeGetValue(AtkTextAttribute attr, int index); 522 523 /** 524 * Associate @name with a new #AtkTextAttribute 525 * 526 * Params: 527 * name = a name string 528 * 529 * Return: an #AtkTextAttribute associated with @name 530 */ 531 public static AtkTextAttribute attributeRegister(string name); 532 }