IdeObject: Builder SDK Reference

## IdeObject IdeObject — Base object with support for object trees |

## Functions

gpointer | ide_object_new ()
GCancellable * | ide_object_ref_cancellable ()
IdeObject * | ide_object_get_parent ()
IdeObject * | ide_object_ref_parent ()
IdeObject * | ide_object_ref_root ()
gboolean | ide_object_is_root ()
void | ide_object_lock ()
void | ide_object_unlock ()
void | ide_object_add ()
void | ide_object_append ()
void | ide_object_prepend ()
void | ide_object_insert_before ()
void | ide_object_insert_after ()
void | ide_object_insert_sorted ()
void | ide_object_remove ()
void | ide_object_foreach ()
gboolean | ide_object_set_error_if_destroyed ()
void | ide_object_destroy ()
void | ide_object_destroyed ()
guint | ide_object_get_position ()
guint | ide_object_get_n_children ()
IdeObject * | ide_object_get_nth_child ()
gpointer | ide_object_get_child_typed ()
GPtrArray * | ide_object_get_children_typed ()
gpointer | ide_object_ensure_child_typed ()
void | ide_object_notify_in_main ()
void | ide_object_notify_by_pspec ()
gboolean | ide_object_in_destruction ()
gchar * | ide_object_repr ()
void | ide_object_log ()
#define | ide_object_message()
#define | ide_object_warning()

## Properties

GCancellable * | cancellable | Read / Write / Construct Only
IdeObject * | parent | Read / Write / Construct Only

## Signals

void | destroy | No Hooks

## Types and Values

#define | IDE_TYPE_OBJECT
enum | IdeObjectLocation
struct | IdeObjectClass
| IdeObject

## Object Hierarchy

        GObject
        ╰── IdeObject
            ├── IdeFileSettings
            ├── IdeBufferChangeMonitor
            ├── IdeBufferManager
            ├── IdeBuildManager
            ├── IdeConfig
            ├── IdeConfigManager
            ├── IdeContext
            ├── IdeDebugManager
            ├── IdeDebugger
            ├── IdeDeployStrategy
            ├── IdeDevice
            ├── IdeDeviceManager
            ├── IdeDeviceProvider
            ├── IdeDiagnostic
            ├── IdeDiagnostics
            ├── IdeDiagnosticsManager
            ├── IdeDirectoryVcs
            ├── IdeExtensionAdapter
            ├── IdeExtensionSetAdapter
            ├── IdeFallbackBuildSystem
            ├── IdeHighlightEngine
            ├── IdeLspClient
            ├── IdeLspCompletionProvider
            ├── IdeLspDiagnosticProvider
            ├── IdeLspFormatter
            ├── IdeLspHighlighter
            ├── IdeLspHoverProvider
            ├── IdeLspRenameProvider
            ├── IdeLspSymbolResolver
            ├── IdeNotification
            ├── IdeNotifications
            ├── IdeObjectBox
            ├── IdePipeline
            ├── IdePipelineStage
            ├── IdeTransfer
            ├── IdeRunManager
            ├── IdeRunner
            ├── IdeRuntime
            ├── IdeRuntimeManager
            ├── IdeSearchEngine
            ├── IdeSimpleBuildSystemDiscovery
            ├── IdeSimpleBuildTarget
            ├── IdeToolchain
            ├── IdeSnippetStorage
            ├── IdeTestManager
            ├── IdeTestProvider
            ├── IdeTextEdit
            ├── IdeToolchainManager
            ├── IdeTreeModel
            ├── IdeUnsavedFiles
            ╰── IdeVcsMonitor

## Known Derived Interfaces

IdeObject is required by IdeBuildSystem, IdeBuildTarget, IdeCodeIndexer, IdeCommand, IdeConfigProvider, IdeDependencyUpdater, IdeDiagnosticProvider, IdeHighlighter, IdeIndenter, IdePipelineAddin, IdeRenameProvider, IdeRuntimeProvider, IdeSearchProvider, IdeSessionAddin, IdeSymbolResolver, IdeToolchainProvider and IdeVcs.

## Description

IdeObject is a specialized GObject for use in Builder. It provides a hierarchy of objects using a specialized tree similar to a DOM. You can insert/append/prepend objects to a parent node, and track their lifetime as part of the tree.

When an object is removed from the tree, it can automatically be destroyed via the “destroy” signal. This is useful as it may cause the children of that object to be removed, recursively destroying the objects descendants. This behavior is ideal when you want a large amount of objects to be reclaimed once an ancestor is no longer necessary.

IdeObject's may also have a GCancellable associated with them. The cancellable is created on demand when `ide_object_ref_cancellable()` is called. When the object is destroyed, the “cancel” signal is emitted. This allows automatic cleanup of asynchronous operations when used properly.

## Functions

### ide_object_new ()

    gpointer
    ide_object_new (GType type,
                    IdeObject *parent);

This is a convenience function for creating an IdeObject and appending it to a parent.

This function may only be called from the main-thread, as calling from any other thread would potentially risk being disposed before returning.

#### Parameters

type | a GType of an IdeObject derived object |
parent | an optional IdeObject parent. | [nullable]

#### Returns

a new IdeObject.

[transfer full][type IdeObject]

Since: 3.32

### ide_object_ref_cancellable ()

    GCancellable *
    ide_object_ref_cancellable (IdeObject *self);

Gets a GCancellable for the object.

#### Parameters

self | a IdeObject |

#### Returns

a GCancellable.

[transfer none][not nullable]

Since: 3.32

### ide_object_get_parent ()

    IdeObject *
    ide_object_get_parent (IdeObject *self);

Gets the parent IdeObject, if any.

This function may only be called from the main thread.

#### Parameters

self | a IdeObject |

#### Returns

an IdeObject or `NULL`.

[transfer none][nullable]

Since: 3.32

### ide_object_ref_parent ()

    IdeObject *
    ide_object_ref_parent (IdeObject *self);

Gets the parent IdeObject, if any.

#### Parameters

self | a IdeObject |

#### Returns

an IdeObject or `NULL`.

[transfer full][nullable]

Since: 3.32

### ide_object_ref_root ()

    IdeObject *
    ide_object_ref_root (IdeObject *self);

Finds and returns the toplevel object in the tree.

#### Parameters

self | a IdeObject |

#### Returns

an IdeObject.

[transfer full]

Since: 3.32

### ide_object_is_root ()

    gboolean
    ide_object_is_root (IdeObject *self);

Checks if `self` is root, meaning it has no parent.

#### Parameters

self | a IdeObject |

#### Returns

`TRUE` if `self` has no parent

Since: 3.32

### ide_object_lock ()

    void
    ide_object_lock (IdeObject *self);

Acquires the lock for `self` . This can be useful when you need to do multi-threaded work with `self` and want to ensure exclusivity.

Call `ide_object_unlock()` to release the lock.

The synchronization used is a GRecMutex.

#### Parameters

self | a IdeObject |

Since: 3.32

### ide_object_unlock ()

    void
    ide_object_unlock (IdeObject *self);

Releases a previously acuiqred lock from `ide_object_lock()`.

The synchronization used is a GRecMutex.

#### Parameters

self | a IdeObject |

Since: 3.32

### ide_object_add ()

    void
    ide_object_add (IdeObject *self,
                    IdeObject *sibling,
                    IdeObject *child,
                    IdeObjectLocation location);

Adds `child` to `self` , with location dependent on `location` .

Generally, it is simpler to use the helper functions such as `ide_object_append()`, `ide_object_prepend()`, `ide_object_insert_before()`, or `ide_object_insert_after()`.

This function is primarily meant for consumers that don't know the relative position they need until runtime.

#### Parameters

self | an IdeObject |
sibling | an IdeObject or `NULL`. | [nullable]
child | an IdeObject |
location | location for child |

Since: 3.32

### ide_object_append ()

    void
    ide_object_append (IdeObject *self,
                       IdeObject *child);

Inserts `child` as the last child of `self` .

#### Parameters

self | an IdeObject |
child | an IdeObject |

Since: 3.32

### ide_object_prepend ()

    void
    ide_object_prepend (IdeObject *self,
                        IdeObject *child);

Inserts `child` as the first child of `self` .

#### Parameters

self | an IdeObject |
child | an IdeObject |

Since: 3.32

### ide_object_insert_before ()

    void
    ide_object_insert_before (IdeObject *self,
                              IdeObject *sibling,
                              IdeObject *child);

Inserts `child` into `self` 's children, directly before `sibling` .

`sibling` MUST BE a child of `self` .

#### Parameters

self | an IdeObject |
sibling | an IdeObject |
child | an IdeObject |

Since: 3.32

### ide_object_insert_after ()

    void
    ide_object_insert_after (IdeObject *self,
                             IdeObject *sibling,
                             IdeObject *child);

Inserts `child` into `self` 's children, directly after `sibling` .

`sibling` MUST BE a child of `self` .

#### Parameters

self | an IdeObject |
sibling | an IdeObject |
child | an IdeObject |

Since: 3.32

### ide_object_insert_sorted ()

    void
    ide_object_insert_sorted (IdeObject *self,
                              IdeObject *child,
                              GCompareDataFunc func,
                              gpointer user_data);

Locates the proper sibling for `child` by using `func` amongst `self` 's children IdeObject. Those objects must already be sorted.

#### Parameters

self | a IdeObject |
child | an IdeObject |
func | a GCompareDataFunc that can be used to locate the proper sibling. | [scope call]
user_data | user data for `func` |

Since: 3.32

### ide_object_remove ()

    void
    ide_object_remove (IdeObject *self,
                       IdeObject *child);

Removes `child` from `self` .

If `child` is a borrowed reference, it may be finalized before this function returns.

#### Parameters

self | an IdeObject |
child | an IdeObject |

Since: 3.32

### ide_object_foreach ()

    void
    ide_object_foreach (IdeObject *self,
                        GFunc callback,
                        gpointer user_data);

Calls `callback` for each child of `self` .

`callback` is allowed to remove children from `self` , but only as long as they are the child passed to callback (or child itself). See `g_queue_foreach()` for more details about what is allowed.

#### Parameters

self | a IdeObject |
callback | a GFunc to call for each child. | [scope call]
user_data | closure data for `callback` |

Since: 3.32

### ide_object_set_error_if_destroyed ()

    gboolean
    ide_object_set_error_if_destroyed (IdeObject *self,
                                       GError **error);

### ide_object_destroy ()

    void
    ide_object_destroy (IdeObject *self);

### ide_object_destroyed ()

    void
    ide_object_destroyed (IdeObject **self);

This function sets *object_pointer to NULL if object_pointer != NULL. It's intended to be used as a callback connected to the "destroy" signal of a object. You connect `ide_object_destroyed()` as a signal handler, and pass the address of your object variable as user data. Then when the object is destroyed, the variable will be set to NULL. Useful for example to avoid multiple copies of the same dialog.

#### Parameters

self | a IdeObject |

Since: 3.32

### ide_object_get_position ()

    guint
    ide_object_get_position (IdeObject *self);

Gets the position of `self` within the parent node.

#### Parameters

self | a IdeObject |

#### Returns

the position, starting from 0

Since: 3.32

### ide_object_get_n_children ()

    guint
    ide_object_get_n_children (IdeObject *self);

Gets the number of children for an object.

#### Parameters

self | a IdeObject |

#### Returns

the number of children

Since: 3.32

### ide_object_get_nth_child ()

    IdeObject *
    ide_object_get_nth_child (IdeObject *self,
                              guint nth);

Gets the `nth` child of `self` .

A full reference to the child is returned.

#### Parameters

self | a IdeObject |
nth | position of child to fetch |

#### Returns

an IdeObject or `NULL`.

[transfer full][nullable]

Since: 3.32

### ide_object_get_child_typed ()

    gpointer
    ide_object_get_child_typed (IdeObject *self,
                                GType type);

Finds the first child of `self` that is of `type` .

#### Parameters

self | a IdeObject |
type | the GType of the child to match |

#### Returns

an IdeObject or `NULL`.

[transfer full][type IdeObject][nullable]

Since: 3.32

### ide_object_get_children_typed ()

    GPtrArray *
    ide_object_get_children_typed (IdeObject *self,
                                   GType type);

Gets all children matching `type` .

#### Parameters

self | a IdeObject |
type | a GType |

#### Returns

a GPtrArray of IdeObject matching `type` .

[transfer full][element-type IdeObject]

Since: 3.32

### ide_object_ensure_child_typed ()

    gpointer
    ide_object_ensure_child_typed (IdeObject *self,
                                   GType type);

Like `ide_object_get_child_typed()` except that it creates an object of `type` if it is missing.

#### Parameters

self | a IdeObject |
type | the GType of the child |

#### Returns

an IdeObject or `NULL`.

[transfer full][nullable][type IdeObject]

Since: 3.32

### ide_object_notify_in_main ()

    void
    ide_object_notify_in_main (gpointer instance,
                               GParamSpec *pspec);

This helper will perform a `g_object_notify_by_pspec()` with the added requirement that it is run from the applications main thread.

You may want to do this when modifying state from a thread, but only notify from the Gtk+ thread.

This will *always* return to the default main context, and never emit ::notify immediately.

#### Parameters

instance | a GObject. | [type GObject.Object]
pspec | a GParamSpec |

Since: 3.32

### ide_object_notify_by_pspec ()

    void
    ide_object_notify_by_pspec (gpointer instance,
                                GParamSpec *pspec);

Like `g_object_notify_by_pspec()` if the caller is in the main-thread. Otherwise, the request is deferred to the main thread.

#### Parameters

instance | a IdeObjectNotify |
pspec | a GParamSpec |

Since: 3.32

### ide_object_in_destruction ()

    gboolean
    ide_object_in_destruction (IdeObject *self);

### ide_object_repr ()

    gchar *
    ide_object_repr (IdeObject *self);

This function is similar to Python's ``repr()`` which gives a string representation for the object. It is useful when debugging Builder or when writing plugins.

#### Parameters

self | a IdeObject |

#### Returns

a string containing the string representation of the IdeObject.

[transfer full]

Since: 3.32

### ide_object_log ()

    void
    ide_object_log (gpointer instance,
                    GLogLevelFlags level,
                    const gchar *domain,
                    const gchar *format,
                    ...);

### ide_object_message()

    #define ide_object_message(instance, format, ...) ide_object_log(instance, G_LOG_LEVEL_MESSAGE, G_LOG_DOMAIN, format __VA_OPT__(,) __VA_ARGS__)

### ide_object_warning()

    #define ide_object_warning(instance, format, ...) ide_object_log(instance, G_LOG_LEVEL_WARNING, G_LOG_DOMAIN, format __VA_OPT__(,) __VA_ARGS__)

## Types and Values

### IDE_TYPE_OBJECT

    #define IDE_TYPE_OBJECT (ide_object_get_type())

### enum IdeObjectLocation

#### Members

IDE_OBJECT_START |  |
IDE_OBJECT_END |  |
IDE_OBJECT_BEFORE_SIBLING |  |
IDE_OBJECT_AFTER_SIBLING |  |

### struct IdeObjectClass

    struct IdeObjectClass {
      GObjectClass parent_class;

      void     (*destroy)    (IdeObject         *self);
      void     (*add)        (IdeObject         *self,
                              IdeObject         *sibling,
                              IdeObject         *child,
                              IdeObjectLocation  location);
      void     (*remove)     (IdeObject         *self,
                              IdeObject         *child);
      void     (*parent_set) (IdeObject         *self,
                              IdeObject         *parent);
      gchar  *(*repr)        (IdeObject         *self);

      /*< private */
      gpointer _reserved[16];
    };

### IdeObject

    typedef struct _IdeObject IdeObject;

## Property Details

### The `“cancellable”` property

      “cancellable”              GCancellable *

The "cancellable" property is a GCancellable that can be used by operations that will be cancelled when the “destroy” signal is emitted on `self` .

This is convenient when you want operations to automatically be cancelled when part of teh object tree is segmented.

Flags: Read / Write / Construct Only

Since: 3.32

### The `“parent”` property

      “parent”                   IdeObject *

The parent IdeObject, if any.

Flags: Read / Write / Construct Only

Since: 3.32

## Signal Details

### The `“destroy”` signal

    void
    user_function (IdeObject *ideobject,
                   gpointer   user_data)

The "destroy" signal is emitted when the object should destroy itself and cleanup any state that is no longer necessary. This happens when the object has been removed from the because it was requested to be destroyed, or because a parent object is being destroyed.

If you do not want to receive the "destroy" signal, then you must manually remove the object from the tree using `ide_object_remove()` while holding a reference to the object.

#### Parameters

user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 3.32