1 // Generated by gmmproc 2.56.0 -- DO NOT MODIFY!
2 #ifndef _ATKMM_TEXT_H
3 #define _ATKMM_TEXT_H
4
5
6 #include <glibmm/ustring.h>
7 #include <sigc++/sigc++.h>
8
9 /* $Id: text.hg,v 1.7 2005/01/05 18:21:30 murrayc Exp $ */
10
11 /* Copyright (C) 2002 The gtkmm Development Team
12 *
13 * This library is free software; you can redistribute it and/or
14 * modify it under the terms of the GNU Lesser General Public
15 * License as published by the Free Software Foundation; either
16 * version 2.1 of the License, or (at your option) any later version.
17 *
18 * This library is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 * Lesser General Public License for more details.
22 *
23 * You should have received a copy of the GNU Lesser General Public
24 * License along with this library; if not, write to the Free
25 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
26 */
27
28
29 #include <atkmm/component.h> /* for Atk::CoordType */
30 #include <glibmm/slisthandle.h>
31 #include <atk/atktext.h>
32
33
34 #ifndef DOXYGEN_SHOULD_SKIP_THIS
35 using AtkText = struct _AtkText;
36 using AtkTextClass = struct _AtkTextClass;
37 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
38
39
40 #ifndef DOXYGEN_SHOULD_SKIP_THIS
41 namespace Atk
42 { class Text_Class; } // namespace Atk
43 #endif // DOXYGEN_SHOULD_SKIP_THIS
44
45 namespace Atk
46 {
47
48 class Attribute
49 {
50 public:
51 #ifndef DOXYGEN_SHOULD_SKIP_THIS
52 using CppObjectType = Attribute;
53 using BaseObjectType = AtkAttribute;
54 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
55
56 private:
57
58
59 public:
60 Attribute();
61 Attribute(const Glib::ustring& name, const Glib::ustring& value);
62 explicit Attribute(const AtkAttribute* gobject);
63 ~Attribute();
64
65 Attribute(const Attribute& other);
66 Attribute& operator=(const Attribute& other);
67
68 void swap(Attribute& other);
69
70 Glib::ustring get_name() const;
71 Glib::ustring get_value() const;
72
73 /// Provides access to the underlying C GObject.
gobj()74 AtkAttribute* gobj() { return &gobject_; }
75
76 /// Provides access to the underlying C GObject.
gobj()77 const AtkAttribute* gobj() const { return &gobject_; }
78
79 protected:
80 AtkAttribute gobject_;
81
82
83 };
84
85 /** @relates Atk::Attribute */
swap(Attribute & lhs,Attribute & rhs)86 inline void swap(Attribute& lhs, Attribute& rhs)
87 { lhs.swap(rhs); }
88
89 struct AttributeTraits
90 {
91 typedef Atk::Attribute CppType;
92 typedef const AtkAttribute* CType;
93 typedef AtkAttribute* CTypeNonConst;
94
to_c_typeAttributeTraits95 static CType to_c_type(CType item) { return item; }
to_c_typeAttributeTraits96 static CType to_c_type(const CppType& item) { return item.gobj(); }
to_cpp_typeAttributeTraits97 static CppType to_cpp_type(CType item) { return CppType(item); }
release_c_typeAttributeTraits98 static void release_c_type(CType item) { g_free(const_cast<CTypeNonConst>(item)); }
99 };
100
101 typedef Glib::SListHandle<Attribute, AttributeTraits> AttributeSet;
102
103
104 /** @addtogroup atkmmEnums atkmm Enums and Flags */
105
106 /**
107 * @var BuiltinTextAttribute TEXT_ATTR_INVALID
108 * Invalid attribute, like bad spelling or grammar.
109 *
110 * @var BuiltinTextAttribute TEXT_ATTR_LEFT_MARGIN
111 * The pixel width of the left margin.
112 *
113 * @var BuiltinTextAttribute TEXT_ATTR_RIGHT_MARGIN
114 * The pixel width of the right margin.
115 *
116 * @var BuiltinTextAttribute TEXT_ATTR_INDENT
117 * The number of pixels that the text is indented.
118 *
119 * @var BuiltinTextAttribute TEXT_ATTR_INVISIBLE
120 * Either "true" or "false" indicating whether text is visible or not.
121 *
122 * @var BuiltinTextAttribute TEXT_ATTR_EDITABLE
123 * Either "true" or "false" indicating whether text is editable or not.
124 *
125 * @var BuiltinTextAttribute TEXT_ATTR_PIXELS_ABOVE_LINES
126 * Pixels of blank space to leave above each newline-terminated line.
127 *
128 * @var BuiltinTextAttribute TEXT_ATTR_PIXELS_BELOW_LINES
129 * Pixels of blank space to leave below each newline-terminated line.
130 *
131 * @var BuiltinTextAttribute TEXT_ATTR_PIXELS_INSIDE_WRAP
132 * Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph).
133 *
134 * @var BuiltinTextAttribute TEXT_ATTR_BG_FULL_HEIGHT
135 * "true" or "false" whether to make the background color for each character the height of the highest font used on the current line, or the height of the font used for the current character.
136 *
137 * @var BuiltinTextAttribute TEXT_ATTR_RISE
138 * Number of pixels that the characters are risen above the baseline.
139 *
140 * @var BuiltinTextAttribute TEXT_ATTR_UNDERLINE
141 * "none", "single", "double", "low", or "error".
142 *
143 * @var BuiltinTextAttribute TEXT_ATTR_STRIKETHROUGH
144 * "true" or "false" whether the text is strikethrough.
145 *
146 * @var BuiltinTextAttribute TEXT_ATTR_SIZE
147 * The size of the characters in points. eg: 10.
148 *
149 * @var BuiltinTextAttribute TEXT_ATTR_SCALE
150 * The scale of the characters. The value is a string representation of a double.
151 *
152 * @var BuiltinTextAttribute TEXT_ATTR_WEIGHT
153 * The weight of the characters.
154 *
155 * @var BuiltinTextAttribute TEXT_ATTR_LANGUAGE
156 * The language used.
157 *
158 * @var BuiltinTextAttribute TEXT_ATTR_FAMILY_NAME
159 * The font family name.
160 *
161 * @var BuiltinTextAttribute TEXT_ATTR_BG_COLOR
162 * The background color. The value is an RGB value of the format "%u,%u,%u".
163 *
164 * @var BuiltinTextAttribute TEXT_ATTR_FG_COLOR
165 * The foreground color. The value is an RGB value of the format "%u,%u,%u".
166 *
167 * @var BuiltinTextAttribute TEXT_ATTR_BG_STIPPLE
168 * "true" if a Gdk::Bitmap is set for stippling the background color.
169 *
170 * @var BuiltinTextAttribute TEXT_ATTR_FG_STIPPLE
171 * "true" if a Gdk::Bitmap is set for stippling the foreground color.
172 *
173 * @var BuiltinTextAttribute TEXT_ATTR_WRAP_MODE
174 * The wrap mode of the text, if any. Values are "none", "char", "word", or "word_char".
175 *
176 * @var BuiltinTextAttribute TEXT_ATTR_DIRECTION
177 * The direction of the text, if set. Values are "none", "ltr" or "rtl".
178 *
179 * @var BuiltinTextAttribute TEXT_ATTR_JUSTIFICATION
180 * The justification of the text, if set. Values are "left", "right", "center" or "fill".
181 *
182 * @var BuiltinTextAttribute TEXT_ATTR_STRETCH
183 * The stretch of the text, if set. Values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" or "ultra_expanded".
184 *
185 * @var BuiltinTextAttribute TEXT_ATTR_VARIANT
186 * The capitalization variant of the text, if set. Values are "normal" or "small_caps".
187 *
188 * @var BuiltinTextAttribute TEXT_ATTR_STYLE
189 * The slant style of the text, if set. Values are "normal", "oblique" or "italic".
190 *
191 * @var BuiltinTextAttribute TEXT_ATTR_LAST_DEFINED
192 * Not a valid text attribute, used for finding end of enumeration.
193 *
194 * @enum BuiltinTextAttribute
195 *
196 * Describes the text attributes supported
197 *
198 * @ingroup atkmmEnums
199 */
200 enum BuiltinTextAttribute
201 {
202 TEXT_ATTR_INVALID,
203 TEXT_ATTR_LEFT_MARGIN,
204 TEXT_ATTR_RIGHT_MARGIN,
205 TEXT_ATTR_INDENT,
206 TEXT_ATTR_INVISIBLE,
207 TEXT_ATTR_EDITABLE,
208 TEXT_ATTR_PIXELS_ABOVE_LINES,
209 TEXT_ATTR_PIXELS_BELOW_LINES,
210 TEXT_ATTR_PIXELS_INSIDE_WRAP,
211 TEXT_ATTR_BG_FULL_HEIGHT,
212 TEXT_ATTR_RISE,
213 TEXT_ATTR_UNDERLINE,
214 TEXT_ATTR_STRIKETHROUGH,
215 TEXT_ATTR_SIZE,
216 TEXT_ATTR_SCALE,
217 TEXT_ATTR_WEIGHT,
218 TEXT_ATTR_LANGUAGE,
219 TEXT_ATTR_FAMILY_NAME,
220 TEXT_ATTR_BG_COLOR,
221 TEXT_ATTR_FG_COLOR,
222 TEXT_ATTR_BG_STIPPLE,
223 TEXT_ATTR_FG_STIPPLE,
224 TEXT_ATTR_WRAP_MODE,
225 TEXT_ATTR_DIRECTION,
226 TEXT_ATTR_JUSTIFICATION,
227 TEXT_ATTR_STRETCH,
228 TEXT_ATTR_VARIANT,
229 TEXT_ATTR_STYLE,
230 TEXT_ATTR_LAST_DEFINED
231 };
232
233 } // namespace Atk
234
235 #ifndef DOXYGEN_SHOULD_SKIP_THIS
236 namespace Glib
237 {
238
239 template <>
240 class Value<Atk::BuiltinTextAttribute> : public Glib::Value_Enum<Atk::BuiltinTextAttribute>
241 {
242 public:
243 static GType value_type() G_GNUC_CONST;
244 };
245
246 } // namespace Glib
247 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
248
249 namespace Atk
250 {
251
252
253 class TextAttribute
254 {
255 private:
256 int attribute_;
257
258 public:
TextAttribute()259 TextAttribute() : attribute_ (0) {}
TextAttribute(BuiltinTextAttribute attribute)260 TextAttribute(BuiltinTextAttribute attribute) : attribute_ (attribute) {}
261
262 // Behave like an ordinary enum.
TextAttribute(int attribute)263 explicit TextAttribute(int attribute) : attribute_ (attribute) {}
264 operator int() const { return attribute_; }
265
266 static TextAttribute for_name(const Glib::ustring& name);
267 static Glib::ustring get_name(TextAttribute attribute);
268 static Glib::ustring get_value(TextAttribute attribute, int index);
269 };
270
271 } // namespace Atk
272
273 #ifndef DOXYGEN_SHOULD_SKIP_THIS
274 namespace Glib
275 {
276
277 template <>
278 class Value<Atk::TextAttribute> : public Glib::Value_Enum<Atk::TextAttribute>
279 {
280 public:
281 static GType value_type() G_GNUC_CONST;
282 };
283
284 } // namespace Glib
285 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
286
287 namespace Atk
288 {
289
290 /**
291 * @var TextBoundary TEXT_BOUNDARY_CHAR
292 * Boundary is the boundary between characters
293 * (including non-printing characters).
294 *
295 * @var TextBoundary TEXT_BOUNDARY_WORD_START
296 * Boundary is the start (i.e. first character) of a word.
297 *
298 * @var TextBoundary TEXT_BOUNDARY_WORD_END
299 * Boundary is the end (i.e. last
300 * character) of a word.
301 *
302 * @var TextBoundary TEXT_BOUNDARY_SENTENCE_START
303 * Boundary is the first character in a sentence.
304 *
305 * @var TextBoundary TEXT_BOUNDARY_SENTENCE_END
306 * Boundary is the last (terminal)
307 * character in a sentence; in languages which use "sentence stop"
308 * punctuation such as English, the boundary is thus the '.', '?', or
309 * similar terminal punctuation character.
310 *
311 * @var TextBoundary TEXT_BOUNDARY_LINE_START
312 * Boundary is the initial character of the content or a
313 * character immediately following a newline, linefeed, or return character.
314 *
315 * @var TextBoundary TEXT_BOUNDARY_LINE_END
316 * Boundary is the linefeed, or return
317 * character.
318 *
319 * @enum TextBoundary
320 *
321 * Text boundary types used for specifying boundaries for regions of text.
322 * This enumerationis deprecated since 2.9.4 and should not be used. Use
323 * AtkTextGranularity with #atk_text_get_string_at_offset instead.
324 *
325 * @ingroup atkmmEnums
326 */
327 enum TextBoundary
328 {
329 TEXT_BOUNDARY_CHAR,
330 TEXT_BOUNDARY_WORD_START,
331 TEXT_BOUNDARY_WORD_END,
332 TEXT_BOUNDARY_SENTENCE_START,
333 TEXT_BOUNDARY_SENTENCE_END,
334 TEXT_BOUNDARY_LINE_START,
335 TEXT_BOUNDARY_LINE_END
336 };
337
338 } // namespace Atk
339
340 #ifndef DOXYGEN_SHOULD_SKIP_THIS
341 namespace Glib
342 {
343
344 template <>
345 class Value<Atk::TextBoundary> : public Glib::Value_Enum<Atk::TextBoundary>
346 {
347 public:
348 static GType value_type() G_GNUC_CONST;
349 };
350
351 } // namespace Glib
352 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
353
354 namespace Atk
355 {
356
357 /**
358 * @var TextClipType TEXT_CLIP_NONE
359 * No clipping to be done.
360 *
361 * @var TextClipType TEXT_CLIP_MIN
362 * Text clipped by min coordinate is omitted.
363 *
364 * @var TextClipType TEXT_CLIP_MAX
365 * Text clipped by max coordinate is omitted.
366 *
367 * @var TextClipType TEXT_CLIP_BOTH
368 * Only text fully within mix/max bound is retained.
369 *
370 * @enum TextClipType
371 *
372 * Describes the type of clipping required.
373 *
374 * @ingroup atkmmEnums
375 */
376 enum TextClipType
377 {
378 TEXT_CLIP_NONE,
379 TEXT_CLIP_MIN,
380 TEXT_CLIP_MAX,
381 TEXT_CLIP_BOTH
382 };
383
384 } // namespace Atk
385
386 #ifndef DOXYGEN_SHOULD_SKIP_THIS
387 namespace Glib
388 {
389
390 template <>
391 class Value<Atk::TextClipType> : public Glib::Value_Enum<Atk::TextClipType>
392 {
393 public:
394 static GType value_type() G_GNUC_CONST;
395 };
396
397 } // namespace Glib
398 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
399
400 namespace Atk
401 {
402
403 /**
404 * @var TextGranularity TEXT_GRANULARITY_CHAR
405 * Granularity is defined by the boundaries between characters
406 * (including non-printing characters).
407 *
408 * @var TextGranularity TEXT_GRANULARITY_WORD
409 * Granularity is defined by the boundaries of a word,
410 * starting at the beginning of the current word and finishing at the beginning of
411 * the following one, if present.
412 *
413 * @var TextGranularity TEXT_GRANULARITY_SENTENCE
414 * Granularity is defined by the boundaries of a sentence,
415 * starting at the beginning of the current sentence and finishing at the beginning of
416 * the following one, if present.
417 *
418 * @var TextGranularity TEXT_GRANULARITY_LINE
419 * Granularity is defined by the boundaries of a line,
420 * starting at the beginning of the current line and finishing at the beginning of
421 * the following one, if present.
422 *
423 * @var TextGranularity TEXT_GRANULARITY_PARAGRAPH
424 * Granularity is defined by the boundaries of a paragraph,
425 * starting at the beginning of the current paragraph and finishing at the beginning of
426 * the following one, if present.
427 *
428 * @enum TextGranularity
429 *
430 * Text granularity types used for specifying the granularity of the region of
431 * text we are interested in.
432 *
433 * @ingroup atkmmEnums
434 */
435 enum TextGranularity
436 {
437 TEXT_GRANULARITY_CHAR,
438 TEXT_GRANULARITY_WORD,
439 TEXT_GRANULARITY_SENTENCE,
440 TEXT_GRANULARITY_LINE,
441 TEXT_GRANULARITY_PARAGRAPH
442 };
443
444 } // namespace Atk
445
446 #ifndef DOXYGEN_SHOULD_SKIP_THIS
447 namespace Glib
448 {
449
450 template <>
451 class Value<Atk::TextGranularity> : public Glib::Value_Enum<Atk::TextGranularity>
452 {
453 public:
454 static GType value_type() G_GNUC_CONST;
455 };
456
457 } // namespace Glib
458 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
459
460 namespace Atk
461 {
462
463
464 /** The ATK interface implemented by components with text content.
465 * This should be implemented by Atk::Objects on behalf of widgets that have text content which is either attributed
466 * or otherwise non-trivial. Atk::Objects whose text content is simple, unattributed, and very brief may expose that
467 * content via Atk::Object::get_name() instead; however if the text is editable, multi-line, typically longer than
468 * three or four words, attributed, selectable, or if the object already uses the 'name' ATK property for other
469 * information, this Text interface should be used to expose the text content. In the case of editable text content,
470 * Atk::EditableText (a subtype of the Atk::Text interface) should be implemented instead.
471 *
472 * Atk::Text provides not only traversal facilities and change notification for text content, but also caret tracking
473 * and glyph bounding box calculations. Note that the text strings are exposed as UTF-8, and are therefore potentially
474 * multi-byte, and caret-to-byte offset mapping makes no assumptions about the character length; also bounding box
475 * glyph-to-offset mapping may be complex for languages which use ligatures.
476 */
477
478 class Text : public Glib::Interface
479 {
480
481 #ifndef DOXYGEN_SHOULD_SKIP_THIS
482
483 public:
484 using CppObjectType = Text;
485 using CppClassType = Text_Class;
486 using BaseObjectType = AtkText;
487 using BaseClassType = AtkTextIface;
488
489 // noncopyable
490 Text(const Text&) = delete;
491 Text& operator=(const Text&) = delete;
492
493 private:
494 friend class Text_Class;
495 static CppClassType text_class_;
496
497 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
498 protected:
499 /**
500 * You should derive from this class to use it.
501 */
502 Text();
503
504 #ifndef DOXYGEN_SHOULD_SKIP_THIS
505 /** Called by constructors of derived classes. Provide the result of
506 * the Class init() function to ensure that it is properly
507 * initialized.
508 *
509 * @param interface_class The Class object for the derived type.
510 */
511 explicit Text(const Glib::Interface_Class& interface_class);
512
513 public:
514 // This is public so that C++ wrapper instances can be
515 // created for C instances of unwrapped types.
516 // For instance, if an unexpected C type implements the C interface.
517 explicit Text(AtkText* castitem);
518
519 protected:
520 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
521
522 public:
523
524 Text(Text&& src) noexcept;
525 Text& operator=(Text&& src) noexcept;
526
527 ~Text() noexcept override;
528
529 static void add_interface(GType gtype_implementer);
530
531 /** Get the GType for this class, for use with the underlying GObject type system.
532 */
533 static GType get_type() G_GNUC_CONST;
534
535 #ifndef DOXYGEN_SHOULD_SKIP_THIS
536 static GType get_base_type() G_GNUC_CONST;
537 #endif
538
539 ///Provides access to the underlying C GObject.
gobj()540 AtkText* gobj() { return reinterpret_cast<AtkText*>(gobject_); }
541
542 ///Provides access to the underlying C GObject.
gobj()543 const AtkText* gobj() const { return reinterpret_cast<AtkText*>(gobject_); }
544
545 private:
546
547
548 public:
549
550 /** Gets the specified text.
551 *
552 * @param start_offset Start position.
553 * @param end_offset End position, or -1 for the end of the string.
554 * @return A newly allocated string containing the text from @a start_offset up
555 * to, but not including @a end_offset.
556 */
557 Glib::ustring get_text(int start_offset, int end_offset) const;
558
559 /** Gets the specified text.
560 *
561 * @param offset Position.
562 * @return The character at @a offset.
563 */
564 gunichar get_character_at_offset(int offset) const;
565
566 #ifndef ATKMM_DISABLE_DEPRECATED
567
568 /** Gets the specified text.
569 *
570 * Deprecated: 2.9.3: Please use get_string_at_offset() instead.
571 *
572 * @deprecated Use get_string_at_offset() instead.
573 *
574 * @param offset Position.
575 * @param boundary_type An Atk::TextBoundary.
576 * @param start_offset The start offset of the returned string.
577 * @param end_offset The offset of the first character after the
578 * returned substring.
579 * @return A newly allocated string containing the text after @a offset bounded
580 * by the specified @a boundary_type.
581 */
582 Glib::ustring get_text_after_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const;
583 #endif // ATKMM_DISABLE_DEPRECATED
584
585
586 #ifndef ATKMM_DISABLE_DEPRECATED
587
588 /** Gets the specified text.
589 *
590 * If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the
591 * offset is returned.
592 *
593 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string
594 * is from the word start at or before the offset to the word start after
595 * the offset.
596 *
597 * The returned string will contain the word at the offset if the offset
598 * is inside a word and will contain the word before the offset if the
599 * offset is not inside a word.
600 *
601 * If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned
602 * string is from the sentence start at or before the offset to the sentence
603 * start after the offset.
604 *
605 * The returned string will contain the sentence at the offset if the offset
606 * is inside a sentence and will contain the sentence before the offset
607 * if the offset is not inside a sentence.
608 *
609 * If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
610 * string is from the line start at or before the offset to the line
611 * start after the offset.
612 *
613 * Deprecated: This method is deprecated since ATK version
614 * 2.9.4. Please use get_string_at_offset() instead.
615 *
616 * @deprecated Use get_string_at_offset() instead.
617 *
618 * @param offset Position.
619 * @param boundary_type An Atk::TextBoundary.
620 * @param start_offset The start offset of the returned string.
621 * @param end_offset The offset of the first character after the
622 * returned substring.
623 * @return A newly allocated string containing the text at @a offset bounded by
624 * the specified @a boundary_type.
625 */
626 Glib::ustring get_text_at_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const;
627 #endif // ATKMM_DISABLE_DEPRECATED
628
629
630 #ifndef ATKMM_DISABLE_DEPRECATED
631
632 /** Gets the specified text.
633 *
634 * Deprecated: 2.9.3: Please use get_string_at_offset() instead.
635 *
636 * @deprecated Use get_string_at_offset() instead.
637 *
638 * @param offset Position.
639 * @param boundary_type An Atk::TextBoundary.
640 * @param start_offset The start offset of the returned string.
641 * @param end_offset The offset of the first character after the
642 * returned substring.
643 * @return A newly allocated string containing the text before @a offset bounded
644 * by the specified @a boundary_type.
645 */
646 Glib::ustring get_text_before_offset(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const;
647 #endif // ATKMM_DISABLE_DEPRECATED
648
649
650 /** Gets a portion of the text exposed through an Atk::Text according to a given @a offset
651 * and a specific @a granularity, along with the start and end offsets defining the
652 * boundaries of such a portion of text.
653 *
654 * If @a granularity is ATK_TEXT_GRANULARITY_CHAR the character at the
655 * offset is returned.
656 *
657 * If @a granularity is ATK_TEXT_GRANULARITY_WORD the returned string
658 * is from the word start at or before the offset to the word start after
659 * the offset.
660 *
661 * The returned string will contain the word at the offset if the offset
662 * is inside a word and will contain the word before the offset if the
663 * offset is not inside a word.
664 *
665 * If @a granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string
666 * is from the sentence start at or before the offset to the sentence
667 * start after the offset.
668 *
669 * The returned string will contain the sentence at the offset if the offset
670 * is inside a sentence and will contain the sentence before the offset
671 * if the offset is not inside a sentence.
672 *
673 * If @a granularity is ATK_TEXT_GRANULARITY_LINE the returned string
674 * is from the line start at or before the offset to the line
675 * start after the offset.
676 *
677 * If @a granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string
678 * is from the start of the paragraph at or before the offset to the start
679 * of the following paragraph after the offset.
680 *
681 * @newin{2,10}
682 *
683 * @param offset Position.
684 * @param granularity An Atk::TextGranularity.
685 * @param start_offset The start offset of the returned string, or -1
686 * if an error has occurred (e.g. invalid offset, not implemented).
687 * @param end_offset The offset of the first character after the returned string,
688 * or -1 if an error has occurred (e.g. invalid offset, not implemented).
689 * @return A newly allocated string containing the text
690 * at the @a offset bounded by the specified @a granularity. Returns <tt>nullptr</tt> if the
691 * offset is invalid or no implementation is available.
692 */
693 Glib::ustring get_string_at_offset(int offset, TextGranularity granularity, int& start_offset, int& end_offset);
694
695
696 /** Gets the offset position of the caret (cursor).
697 *
698 * @return The offset position of the caret (cursor).
699 */
700 int get_caret_offset() const;
701
702 /** Get the bounding box containing the glyph representing the character at
703 * a particular text offset.
704 *
705 * @param offset The offset of the text character for which bounding information is required.
706 * @param x Pointer for the x cordinate of the bounding box.
707 * @param y Pointer for the y cordinate of the bounding box.
708 * @param width Pointer for the width of the bounding box.
709 * @param height Pointer for the height of the bounding box.
710 * @param coords Specify whether coordinates are relative to the screen or widget window.
711 */
712 void get_character_extents(int offset, int& x, int& y, int& width, int& height, CoordType coords) const;
713
714 /** Creates an Atk::AttributeSet which consists of the attributes explicitly
715 * set at the position @a offset in the text. @a start_offset and @a end_offset are
716 * set to the start and end of the range around @a offset where the attributes are
717 * invariant. See the enum AtkTextAttribute for types of text attributes that
718 * can be returned. Note that other attributes may also be returned.
719 *
720 * @param offset The offset at which to get the attributes.
721 * @param start_offset The address to put the start offset of the range.
722 * @param end_offset The address to put the end offset of the range.
723 * @return An Atk::AttributeSet which contains the attributes explicitly set
724 * at @a offset.
725 */
726 AttributeSet get_run_attributes(int offset, int& start_offset, int& end_offset) const;
727
728 /** Creates an Atk::AttributeSet which consists of the default values of
729 * attributes for the text. See the enum AtkTextAttribute for types of text
730 * attributes that can be returned. Note that other attributes may also be
731 * returned.
732 *
733 * @return An Atk::AttributeSet which contains the default values of attributes.
734 * at @a offset.
735 */
736 AttributeSet get_default_attributes() const;
737
738 /** Gets the character count.
739 *
740 * @return The number of characters.
741 */
742 int get_character_count() const;
743
744 /** Gets the offset of the character located at coordinates @a x and @a y. @a x and @a y
745 * are interpreted as being relative to the screen or this widget's window
746 * depending on @a coords.
747 *
748 * @param x Screen x-position of character.
749 * @param y Screen y-position of character.
750 * @param coords Specify whether coordinates are relative to the screen or
751 * widget window.
752 * @return The offset to the character which is located at
753 * the specified @a x and @a y coordinates.
754 */
755 int get_offset_at_point(int x, int y, CoordType coords) const;
756
757 /** Gets the number of selected regions.
758 *
759 * @return The number of selected regions, or -1 if a failure
760 * occurred.
761 */
762 int get_n_selections() const;
763
764 /** Gets the text from the specified selection.
765 *
766 * @param selection_num The selection number. The selected regions are
767 * assigned numbers that correspond to how far the region is from the
768 * start of the text. The selected region closest to the beginning
769 * of the text region is assigned the number 0, etc. Note that adding,
770 * moving or deleting a selected region can change the numbering.
771 * @param start_offset Passes back the start position of the selected region.
772 * @param end_offset Passes back the end position of (e.g. offset immediately past)
773 * the selected region.
774 * @return A newly allocated string containing the selected text.
775 */
776 Glib::ustring get_selection(int selection_num, int& start_offset, int& end_offset) const;
777
778 /** Adds a selection bounded by the specified offsets.
779 *
780 * @param start_offset The start position of the selected region.
781 * @param end_offset The offset of the first character after the selected region.
782 * @return <tt>true</tt> if success, <tt>false</tt> otherwise.
783 */
784 bool add_selection(int start_offset, int end_offset);
785
786 /** Removes the specified selection.
787 *
788 * @param selection_num The selection number. The selected regions are
789 * assigned numbers that correspond to how far the region is from the
790 * start of the text. The selected region closest to the beginning
791 * of the text region is assigned the number 0, etc. Note that adding,
792 * moving or deleting a selected region can change the numbering.
793 * @return <tt>true</tt> if success, <tt>false</tt> otherwise.
794 */
795 bool remove_selection(int selection_num);
796
797 /** Changes the start and end offset of the specified selection.
798 *
799 * @param selection_num The selection number. The selected regions are
800 * assigned numbers that correspond to how far the region is from the
801 * start of the text. The selected region closest to the beginning
802 * of the text region is assigned the number 0, etc. Note that adding,
803 * moving or deleting a selected region can change the numbering.
804 * @param start_offset The new start position of the selection.
805 * @param end_offset The new end position of (e.g. offset immediately past)
806 * the selection.
807 * @return <tt>true</tt> if success, <tt>false</tt> otherwise.
808 */
809 bool set_selection(int selection_num, int start_offset, int end_offset);
810
811 /** Sets the caret (cursor) position to the specified @a offset.
812 *
813 * @param offset Position.
814 * @return <tt>true</tt> if success, <tt>false</tt> otherwise.
815 */
816 bool set_caret_offset(int offset);
817
818 typedef AtkTextRectangle Rectangle;
819
820
821 /** Get the bounding box for text within the specified range.
822 *
823 * @newin{1,3}
824 *
825 * @param start_offset The offset of the first text character for which boundary
826 * information is required.
827 * @param end_offset The offset of the text character after the last character
828 * for which boundary information is required.
829 * @param coord_type Specify whether coordinates are relative to the screen or widget window.
830 * @param rect A pointer to a AtkTextRectangle which is filled in by this function.
831 */
832 void get_range_extents(int start_offset, int end_offset, CoordType coord_type, Rectangle& rect);
833
834 /** Get the ranges of text in the specified bounding box.
835 *
836 * @newin{1,3}
837 *
838 * @param rect An AtkTextRectangle giving the dimensions of the bounding box.
839 * @param coord_type Specify whether coordinates are relative to the screen or widget window.
840 * @param x_clip_type Specify the horizontal clip type.
841 * @param y_clip_type Specify the vertical clip type.
842 * @return Array of AtkTextRange. The last
843 * element of the array returned by this function will be <tt>nullptr</tt>.
844 */
845 AtkTextRange** get_bounded_ranges(const Rectangle& rect, CoordType coord_type, TextClipType x_clip_type, TextClipType y_clip_type);
846
847
848 /**
849 * @par Slot Prototype:
850 * <tt>void on_my_%text_changed(int position, int length)</tt>
851 *
852 * Flags: Run Last
853 *
854 * The "text-changed" signal is emitted when the text of the
855 * object which implements the AtkText interface changes, This
856 * signal will have a detail which is either "insert" or
857 * "delete" which identifies whether the text change was an
858 * insertion or a deletion.
859 *
860 * Deprecated: 2.9.4: Use Atk::Object::signal_text_insert() or
861 * Atk::Object::signal_text_remove() instead.
862 *
863 * @param position The position (character offset) of the insertion or deletion.
864 * @param length The length (in characters) of text inserted or deleted.
865 */
866
867 Glib::SignalProxy< void,int,int > signal_text_changed();
868
869
870 /**
871 * @par Slot Prototype:
872 * <tt>void on_my_%text_caret_moved(int location)</tt>
873 *
874 * Flags: Run Last
875 *
876 * The "text-caret-moved" signal is emitted when the caret
877 * position of the text of an object which implements AtkText
878 * changes.
879 *
880 * @param location The new position of the text caret.
881 */
882
883 Glib::SignalProxy< void,int > signal_text_caret_moved();
884
885
886 /**
887 * @par Slot Prototype:
888 * <tt>void on_my_%text_selection_changed()</tt>
889 *
890 * Flags: Run Last
891 *
892 * The "text-selection-changed" signal is emitted when the
893 * selected text of an object which implements AtkText changes.
894 */
895
896 Glib::SignalProxy< void > signal_text_selection_changed();
897
898
899 /**
900 * @par Slot Prototype:
901 * <tt>void on_my_%text_attributes_changed()</tt>
902 *
903 * Flags: Run Last
904 *
905 * The "text-attributes-changed" signal is emitted when the text
906 * attributes of the text of an object which implements AtkText
907 * changes.
908 */
909
910 Glib::SignalProxy< void > signal_text_attributes_changed();
911
912
913 protected:
914
915
916 virtual Glib::ustring get_text_vfunc(int start_offset, int end_offset) const;
917
918 virtual gunichar get_character_at_offset_vfunc(int offset) const;
919
920
921 /** @deprecated This virtual function is deprecated and it should not be overridden.
922 */
923 virtual Glib::ustring get_text_after_offset_vfunc(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const;
924
925
926 virtual Glib::ustring get_text_at_offset_vfunc(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const;
927
928
929 /** @deprecated This virtual function is deprecated and it should not be overridden.
930 */
931 virtual Glib::ustring get_text_before_offset_vfunc(int offset, TextBoundary boundary_type, int& start_offset, int& end_offset) const;
932
933
934 virtual int get_caret_offset_vfunc() const;
935
936 virtual void get_character_extents_vfunc(int offset, int& x, int& y, int& width, int& height, CoordType coords) const;
937
938 virtual AtkAttributeSet* get_run_attributes_vfunc(int offset, int& start_offset, int& end_offset) const;
939
940 virtual AtkAttributeSet* get_default_attributes_vfunc() const;
941
942 virtual int get_character_count_vfunc() const;
943
944 virtual int get_offset_at_point_vfunc(int x, int y, CoordType coords) const;
945
946 virtual int get_n_selections_vfunc() const;
947
948 virtual Glib::ustring get_selection_vfunc(int selection_num, int& start_offset, int& end_offset) const;
949
950 virtual bool add_selection_vfunc(int start_offset, int end_offset);
951
952 virtual bool remove_selection_vfunc(int selection_num);
953
954 virtual bool set_selection_vfunc(int selection_num, int start_offset, int end_offset);
955
956 virtual bool set_caret_offset_vfunc(int offset);
957
958
959 //TODO: Add get_range_extents(), and get_bounded_ranges() vfuncs when we can break ABI.
960
961
962 public:
963
964 public:
965 //C++ methods used to invoke GTK+ virtual functions:
966
967 protected:
968 //GTK+ Virtual Functions (override these to change behaviour):
969
970 //Default Signal Handlers::
971 /// This is a default handler for the signal signal_text_changed().
972 virtual void on_text_changed(int position, int length);
973 /// This is a default handler for the signal signal_text_caret_moved().
974 virtual void on_text_caret_moved(int location);
975 /// This is a default handler for the signal signal_text_selection_changed().
976 virtual void on_text_selection_changed();
977 /// This is a default handler for the signal signal_text_attributes_changed().
978 virtual void on_text_attributes_changed();
979
980
981 };
982
983 } // namespace Atk
984
985
986 namespace Glib
987 {
988 /** A Glib::wrap() method for this object.
989 *
990 * @param object The C instance.
991 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
992 * @result A C++ instance that wraps this C instance.
993 *
994 * @relates Atk::Text
995 */
996 Glib::RefPtr<Atk::Text> wrap(AtkText* object, bool take_copy = false);
997
998 } // namespace Glib
999
1000
1001 #endif /* _ATKMM_TEXT_H */
1002
1003