Class Text

Whenever the source_property is changed the target_property is updated using the same value. For instance:

  g_object_bind_property (action, "active", widget, "sensitive", 0);

Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.

If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on source will be updated as well.

The binding will automatically be removed when either the source or the target instances are finalized. To remove the binding without affecting the source and the target you can just call g_object_unref() on the returned #GBinding instance.

Removing the binding by calling g_object_unref() on it must only be done if the binding, source and target are only used from a single thread and it is clear that both source and target outlive the binding. Especially it is not safe to rely on this if the binding, source or target can be finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side.

A #GObject can have multiple bindings.

This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.

Toolkit implementor note: ATK provides a default implementation for this virtual method. In general there are little reason to re-implement it.

This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

Get the bounding box containing the glyph representing the character at a particular text offset.

If the extent can not be obtained (e.g. a non-embedded plug or missing support), all of x, y, width, height are set to -1.

• The mnemonic key activates the object if it is presently enabled onscreen. This typically corresponds to the underlined letter within the widget. Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for a button.
• The sequence is the full list of keys which invoke the action even if the relevant element is not currently shown on screen. For instance, for a menu item the sequence is the keybindings used to open the parent menus before invoking. The sequence string is colon-delimited. Example: "Alt+F:N" in a traditional "New..." menu item.
• The shortcut, if it exists, will invoke the same action without showing the component or its enclosing menus or dialogs. Example: "Ctrl+N" in a traditional "New..." menu item.

Example: For a traditional "New..." menu item, the expected return value would be: "N;Alt+F:N;Ctrl+N" for the English locale and "N;Alt+D:N;Strg+N" for the German locale. If, hypothetically, this menu item lacked a mnemonic, it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively.

If you are only interested on the parent assigned with atk_object_set_parent(), use atk_object_peek_parent().

If the position can not be obtained (e.g. a non-embedded plug or missing support), x and y are set to -1.

The value can be:

• an empty #GValue initialized by %G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
• a #GValue initialized with the expected type of the property
• a #GValue initialized with a type to which the expected type of the property can be transformed

In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().

Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.

If the extents can not be obtained (e.g. or missing support), the rectangle fields are set to -1.

If the size can not be obtained (e.g. a non-embedded plug or missing support), width and height are set to -1.

If granularity is ATK_TEXT_GRANULARITY_CHAR the character at the offset is returned.

If granularity is ATK_TEXT_GRANULARITY_WORD the returned string is from the word start at or before the offset to the word start after the offset.

The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word.

If granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string is from the sentence start at or before the offset to the sentence start after the offset.

The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence.

If granularity is ATK_TEXT_GRANULARITY_LINE the returned string is from the line start at or before the offset to the line start after the offset.

If granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string is from the start of the paragraph at or before the offset to the start of the following paragraph after the offset.

If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the offset is returned.

If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string is from the word start at or before the offset to the word start after the offset.

The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word.

If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned string is from the sentence start at or before the offset to the sentence start after the offset.

The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence.

If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned string is from the line start at or before the offset to the line start after the offset.

When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

This function omits the property name lookup, hence it is faster than g_object_notify().

One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:

  enum
  {
    PROP_0,
    PROP_FOO,
    PROP_LAST
  };

  static GParamSpec *properties[PROP_LAST];

  static void
  my_object_class_init (MyObjectClass *klass)
  {
    properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
                                             0, 100,
                                             50,
                                             G_PARAM_READWRITE);
    g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
  }

and then notify a change on the "foo" property with:

  g_object_notify_by_pspec (self, properties[PROP_FOO]);

Note that as a general rule when the state of an existing object changes, emitting a notification is expected.

This method is intended as an utility for ATK implementors, and not to be exposed to accessible tools. See atk_object_get_parent() for further reference.

Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit.

In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

Since GLib 2.56, the type of object will be propagated to the return type under the same conditions as for g_object_ref().

This function should only be called from object system implementations.

Contrary to atk_component_set_position, this does not actually move component in its parent, this only makes the parents scroll so that the object shows up on the screen, given its current position within the parents.

In the case of rich-text content, this method should either grab focus or move the sequential focus navigation starting point (if the application supports this concept) as if the user had clicked on the new caret position. Typically, this means that the target of this operation is the node containing the new caret position or one of its ancestors. In other words, after this method is called, if the user advances focus, it should move to the first focusable node following the new caret position.

Calling this method should also scroll the application viewport in a way that matches the behavior of the application's typical caret motion or tab navigation as closely as possible. This also means that if the application's caret motion or focus navigation does not trigger a scroll operation, this method should not trigger one either. If the application does not have a caret motion or focus navigation operation, this method should try to scroll the new caret position into view while minimizing unnecessary scroll motion.

If the object already had an association with that name, the old association will be destroyed.

Internally, the key is converted to a #GQuark using g_quark_from_string(). This means a copy of key is kept permanently (even after object has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the #GQuark storage growing unbounded.

Contrary to atk_component_scroll_to, this does not trigger any scrolling, this just moves component in its parent.

void
object_add_to_user_list (GObject     *object,
                         const gchar *new_string)
{
  // the quark, naming the object data
  GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
  // retrieve the old string list
  GList *list = g_object_steal_qdata (object, quark_string_list);

  // prepend new string
  list = g_list_prepend (list, g_strdup (new_string));
  // this changed 'list', so we need to set it again
  g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
  GList *node, *list = data;

  for (node = list; node; node = node->next)
    g_free (node->data);
  g_list_free (list);
}