IdeObject

IdeObject — Base object with support for object trees

Functions

Properties

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

Signals

void destroy No Hooks

Types and Values

Object Hierarchy

    GObject
    ╰── IdeObject
        ├── IdeFileSettings
        ├── IdeBufferChangeMonitor
        ├── IdeBufferManager
        ├── IdeBuildManager
        ├── IdeCommandManager
        ├── 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, IdeVcs, IdeVcsCloner, IdeVcsConfig and IdeVcsInitializer.

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.

Owner: IdeObject

Flags: Read / Write / Construct Only

Since: 3.32


The “parent” property

  “parent”                   IdeObject *

The parent IdeObject, if any.

Owner: IdeObject

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