IdeContext: Builder SDK Reference

## IdeContext IdeContext — Encapsulates all processing related to a project |

## Functions

GFile * | ide_context_get_project_file ()
IdeBufferManager * | ide_context_get_buffer_manager ()
IdeBuildManager * | ide_context_get_build_manager ()
IdeBuildSystem * | ide_context_get_build_system ()
IdeConfigurationManager * | ide_context_get_configuration_manager ()
IdeDebugManager * | ide_context_get_debug_manager ()
IdeDiagnosticsManager * | ide_context_get_diagnostics_manager ()
IdeDeviceManager * | ide_context_get_device_manager ()
IdeProject * | ide_context_get_project ()
GSettings * | ide_context_get_project_settings ()
GtkRecentManager * | ide_context_get_recent_manager ()
IdeRunManager * | ide_context_get_run_manager ()
IdeRuntimeManager * | ide_context_get_runtime_manager ()
IdeToolchainManager * | ide_context_get_toolchain_manager ()
IdeSearchEngine * | ide_context_get_search_engine ()
IdeSettings * | ide_context_get_settings ()
IdeSnippetStorage * | ide_context_get_snippets ()
IdeTestManager * | ide_context_get_test_manager ()
IdeUnsavedFiles * | ide_context_get_unsaved_files ()
IdeVcs * | ide_context_get_vcs ()
gpointer | ide_context_get_service_typed ()
void | ide_context_unload_async ()
gboolean | ide_context_unload_finish ()
void | ide_context_new_async ()
IdeContext * | ide_context_new_finish ()
void | ide_context_restore_async ()
gboolean | ide_context_restore_finish ()
void | ide_context_add_pausable ()
void | ide_context_remove_pausable ()
void | ide_context_hold ()
void | ide_context_hold_for_object ()
void | ide_context_release ()
void | ide_context_message ()
void | ide_context_warning ()
void | ide_context_emit_log ()
gchar * | ide_context_build_filename ()
GFile * | ide_context_cache_file ()
gchar * | ide_context_cache_filename ()
IdeVcsMonitor * | ide_context_get_monitor ()
gboolean | ide_context_is_unloading ()
GtkWidget * | ide_context_get_workbench ()

## Properties

IdeBufferManager * | buffer-manager | Read
IdeBuildSystem * | build-system | Read
IdeConfigurationManager * | configuration-manager | Read
IdeDeviceManager * | device-manager | Read
IdeProject * | project | Read
GFile * | project-file | Read / Write / Construct Only
IdeRuntimeManager * | runtime-manager | Read
IdeSearchEngine * | search-engine | Read
IdeSnippetStorage * | snippets | Read
IdeToolchainManager * | toolchain-manager | Read
IdeUnsavedFiles * | unsaved-files | Read
IdeVcs * | vcs | Read

## Signals

void | loaded | Run Last
void | log | Run Last

## Types and Values

#define | IDE_TYPE_CONTEXT
| IdeContext

## Object Hierarchy

        GObject
        ╰── IdeContext

## Implemented Interfaces

IdeContext implements GAsyncInitable.

## Description

The IdeContext encapsulates all processing related to a project. This includes everything from project management, version control, debugging, building, running the project, and more.

#### Subsystems

The context is broken into a series of subsystems which can be accessed via accessors on the IdeContext. Some subsystems include IdeBufferManager, IdeBuildManager, IdeBuildSystem, IdeConfigurationManager, IdeDiagnosticsManager, IdeDebugManager, IdeDeviceManager, IdeRuntimeManager, IdeRunManager, IdeSearchEngine, IdeSnippetStorage, IdeTestManager, IdeProject, and IdeVcs.

#### Services

If you need a long running service that has it's life-time synchronized to the lifetime of the IdeContext, you may want to use IdeService. It allows a simple addin interface to provide long-running services to your plugin.

#### Unloading the project context

The context can be unloaded with `ide_context_unload_async()`, which should generally only be called by the IdeWorkbench when closing the project. If you want to prevent unloading of the context during an operation, use the `ide_context_hold()` and `ide_context_release()` functions to prevent pre-mature unloading.

## Functions

### ide_context_get_project_file ()

    GFile *
    ide_context_get_project_file (IdeContext *self);

Retrieves a GFile containing the project file that was used to load the context.

#### Returns

a GFile.

[transfer none]

### ide_context_get_buffer_manager ()

    IdeBufferManager *
    ide_context_get_buffer_manager (IdeContext *self);

Gets the “buffer-manager” property. The buffer manager is responsible for loading and saving buffers (files) within the IdeContext. It provides a convenient place for scripts to hook into the load and save process.

#### Returns

An IdeBufferManager.

[transfer none]

### ide_context_get_build_manager ()

    IdeBuildManager *
    ide_context_get_build_manager (IdeContext *self);

#### Returns

An IdeBuildManager.

[transfer none]

### ide_context_get_build_system ()

    IdeBuildSystem *
    ide_context_get_build_system (IdeContext *self);

Fetches the "build-system" property of `context` .

#### Returns

An IdeBuildSystem.

[transfer none]

### ide_context_get_configuration_manager ()

    IdeConfigurationManager *
    ide_context_get_configuration_manager (IdeContext *self);

Gets the IdeConfigurationManager for the context.

The configuration manager is responsible for loading and saving configurations. Configurations consist of information about how to perform a particular build. Such information includes the target IdeDevice, the IdeRuntime to use, and various other build options.

#### Parameters

self | An IdeContext |

#### Returns

An IdeConfigurationManager.

[transfer none]

### ide_context_get_debug_manager ()

    IdeDebugManager *
    ide_context_get_debug_manager (IdeContext *self);

Gets the debug manager for the context.

#### Parameters

self | An IdeContext |

#### Returns

An IdeDebugManager.

[transfer none]

### ide_context_get_diagnostics_manager ()

    IdeDiagnosticsManager *
    ide_context_get_diagnostics_manager (IdeContext *self);

Gets the IdeDiagnosticsManager for the context.

#### Returns

An IdeDiagnosticsManager.

[transfer none]

### ide_context_get_device_manager ()

    IdeDeviceManager *
    ide_context_get_device_manager (IdeContext *self);

Retrieves the "device-manager" property. The device manager is responsible for connecting and disconnecting to physical or virtual devices within LibIDE.

#### Returns

An IdeDeviceManager.

[transfer none]

### ide_context_get_project ()

    IdeProject *
    ide_context_get_project (IdeContext *self);

Retrieves the IdeProject for the context.

#### Returns

An IdeContext.

[transfer none]

### ide_context_get_project_settings ()

    GSettings *
    ide_context_get_project_settings (IdeContext *self);

Gets an org.gnome.builder.project GSettings.

This creates a new GSettings instance for the project.

#### Parameters

self | a IdeContext |

#### Returns

a GSettings.

[transfer full]

### ide_context_get_recent_manager ()

    GtkRecentManager *
    ide_context_get_recent_manager (IdeContext *self);

Gets the IdeContext:recent-manager property. The recent manager is a GtkRecentManager instance that should be used for the workbench.

#### Returns

a GtkRecentManager.

[transfer none]

### ide_context_get_run_manager ()

    IdeRunManager *
    ide_context_get_run_manager (IdeContext *self);

Gets the IdeRunManager for the context. This manager object simplifies the process of running an IdeBuildTarget from the build system. Primarily, it enforces that only a single target may be run at a time, since that is what the UI will expect.

#### Returns

An IdeRunManager.

[transfer none]

### ide_context_get_runtime_manager ()

    IdeRuntimeManager *
    ide_context_get_runtime_manager (IdeContext *self);

Gets the IdeRuntimeManager for the LibIDE context.

The runtime manager provies access to IdeRuntime instances via the GListModel interface. These can provide support for building projects in various runtimes such as xdg-app.

#### Parameters

self | An IdeContext |

#### Returns

An IdeRuntimeManager.

[transfer none]

### ide_context_get_toolchain_manager ()

    IdeToolchainManager *
    ide_context_get_toolchain_manager (IdeContext *self);

Gets the IdeToolchainManager for the LibIDE context.

The toolchain manager provies access to IdeToolchain instances via the GListModel interface. These can provide support for building projects using different specified toolchains.

#### Parameters

self | An IdeContext |

#### Returns

An IdeToolchainManager.

[transfer none]

### ide_context_get_search_engine ()

    IdeSearchEngine *
    ide_context_get_search_engine (IdeContext *self);

Retrieves the search engine for the context.

#### Returns

An IdeSearchEngine.

[transfer none]

### ide_context_get_settings ()

    IdeSettings *
    ide_context_get_settings (IdeContext *self,
                              const gchar *schema_id,
                              const gchar *relative_path);

Gets an IdeSettings representing the given GSettingsSchema.

`relative_path` will be used to apply multiple layers of settings. Project settings will be applied to first, followed by global settings.

#### Parameters

self | an IdeContext |
schema_id | the GSettings schema identifier |
relative_path | the path for the settings or `NULL`. | [nullable]

#### Returns

An IdeSettings.

[transfer full]

### ide_context_get_snippets ()

    IdeSnippetStorage *
    ide_context_get_snippets (IdeContext *self);

Gets the “snippets” property.

#### Returns

An IdeSnippetStorage.

[transfer none]

Since: 3.30

### ide_context_get_test_manager ()

    IdeTestManager *
    ide_context_get_test_manager (IdeContext *self);

Gets the test manager for the IdeContext.

#### Parameters

self | An IdeTestManager |

#### Returns

An IdeTestManager.

[transfer none]

Since: 3.28

### ide_context_get_unsaved_files ()

    IdeUnsavedFiles *
    ide_context_get_unsaved_files (IdeContext *self);

Returns the unsaved files for the IdeContext. These are the contents of open buffers in the IDE.

#### Returns

An IdeUnsavedFiles.

[transfer none]

### ide_context_get_vcs ()

    IdeVcs *
    ide_context_get_vcs (IdeContext *self);

Retrieves the IdeVcs used to load the project. If no version control system could be found, this will return an IdeDirectoryVcs.

#### Returns

An IdeVcs.

[transfer none]

### ide_context_get_service_typed ()

    gpointer
    ide_context_get_service_typed (IdeContext *self,
                                   GType service_type);

Retrieves a service matching `service_type` . If no match was found, a type implementing the requested service type will be returned. If no matching service type could be found, then an instance of the service will be created, started, and returned.

#### Parameters

service_type | a GType of the service desired. |

#### Returns

An IdeService or `NULL`.

[type Ide.Service][transfer none][nullable]

### ide_context_unload_async ()

    void
    ide_context_unload_async (IdeContext *self,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

This function attempts to unload various components in the IdeContext. This should be called before you dispose the context. Unsaved buffers will be persisted to the drafts directory. More operations may be added in the future.

If there is a hold on the IdeContext, created by `ide_context_hold()`, then the unload request will be delayed until the appropriate number of calls to `ide_context_release()` have been called.

### ide_context_unload_finish ()

    gboolean
    ide_context_unload_finish (IdeContext *self,
                               GAsyncResult *result,
                               GError **error);

### ide_context_new_async ()

    void
    ide_context_new_async (GFile *project_file,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

### ide_context_new_finish ()

    IdeContext *
    ide_context_new_finish (GAsyncResult *result,
                            GError **error);

#### Returns

An IdeContext or `NULL` upon failure and `error` is set.

[transfer full]

### ide_context_restore_async ()

    void
    ide_context_restore_async (IdeContext *self,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

### ide_context_restore_finish ()

    gboolean
    ide_context_restore_finish (IdeContext *self,
                                GAsyncResult *result,
                                GError **error);

### ide_context_add_pausable ()

    void
    ide_context_add_pausable (IdeContext *self,
                              IdePausable *pausable);

Adds a pausable which can be used to associate pausable actions with the context. Various UI in Builder may use this to present pausable actions to the user.

#### Parameters

self | an IdeContext |
pausable | an IdePausable |

Since: 3.26

### ide_context_remove_pausable ()

    void
    ide_context_remove_pausable (IdeContext *self,
                                 IdePausable *pausable);

Remove a previously registered IdePausable.

#### Parameters

self | an IdeContext |
pausable | an IdePausable |

Since: 3.26

### ide_context_hold ()

    void
    ide_context_hold (IdeContext *self);

Puts a hold on the IdeContext, preventing the context from being unloaded until a call to `ide_context_release()`.

If `ide_context_unload_async()` is called while a hold is in progress, the unload will be delayed until `ide_context_release()` has been called the same number of times as `ide_context_hold()`.

#### Parameters

self | the IdeContext |

### ide_context_hold_for_object ()

    void
    ide_context_hold_for_object (IdeContext *self,
                                 gpointer instance);

Adds a hold on `self` for the lifetime of `instance` .

#### Parameters

self | An IdeContext |
instance | a GObject instance. | [type GObject.Object]

### ide_context_release ()

    void
    ide_context_release (IdeContext *self);

Releases a hold on the context previously created with `ide_context_hold()`.

If a pending unload of the context has been requested, it will be dispatched once the hold count reaches zero.

#### Parameters

self | the IdeContext |

### ide_context_message ()

    void
    ide_context_message (IdeContext *self,
                         const gchar *format,
                         ...);

Emits a log message for the context, which is useful so that messages may be displayed to the user in the workbench window.

Thread-safety: you may call this from any thread, so long as the thread owns a reference to the context.

#### Parameters

self | a IdeContext |
format | a printf style format |
... | parameters for `format` |

Since: 3.28

### ide_context_warning ()

    void
    ide_context_warning (IdeContext *self,
                         const gchar *format,
                         ...);

Emits a log message for the context, which is useful so that error messages may be displayed to the user in the workbench window.

Thread-safety: you may call this from any thread, so long as the thread owns a reference to the context.

#### Parameters

self | a IdeContext |
format | a printf style format |
... | parameters for `format` |

### ide_context_emit_log ()

    void
    ide_context_emit_log (IdeContext *self,
                          GLogLevelFlags log_level,
                          const gchar *message,
                          gssize message_len);

Emits the “log” signal, possibly after sending the message to the main loop.

Thread-safety: you may call this from any thread that holds a reference to the IdeContext object.

#### Parameters

self | a IdeContext |
log_level | a GLogLevelFlags |
message | the log message |
message_len | the length of `message` , not including a `NULL` byte, or -1 to indicate the message is `NULL` terminated. |

### ide_context_build_filename ()

    gchar *
    ide_context_build_filename (IdeContext *self,
                                const gchar *first_part,
                                ...);

Creates a new path that starts from the working directory of the loaded project.

#### Parameters

self | a IdeContext |
first_part | first path part |

#### Returns

a string containing the new path.

[transfer full]

Since: 3.28

### ide_context_cache_file ()

    GFile *
    ide_context_cache_file (IdeContext *self,
                            const gchar *first_part,
                            ...);

Like `ide_context_cache_filename()` but returns a GFile.

#### Parameters

self | a IdeContext |
first_part | The first part of the path |

#### Returns

a GFile for the cache file.

[transfer full]

Since: 3.28

### ide_context_cache_filename ()

    gchar *
    ide_context_cache_filename (IdeContext *self,
                                const gchar *first_part,
                                ...);

Creates a new filename that will be located in the projects cache directory. This makes it convenient to remove files when a project is deleted as all cache files will share a unified parent directory.

The file will be located in a directory similar to ~/.cache/gnome-builder/project_name. This may change based on the value of `g_get_user_cache_dir()`.

#### Parameters

self | a IdeContext |
first_part | the first part of the filename |

#### Returns

A new string containing the cache filename.

[transfer full]

Since: 3.28

### ide_context_get_monitor ()

    IdeVcsMonitor *
    ide_context_get_monitor (IdeContext *self);

Gets a DzlRecursiveFileMonitor that monitors the project directory recursively. You can use this to track changes across the project tree without creating your own GFileMonitor.

#### Parameters

self | a IdeContext |

#### Returns

a IdeVcsMonitor to monitor the project tree.

[transfer none]

Since: 3.28

### ide_context_is_unloading ()

    gboolean
    ide_context_is_unloading (IdeContext *self);

Checks if `ide_context_unload_async()` has been called.

You might use this to avoid starting any new work once the context has started the shutdown sequence.

#### Parameters

self | a IdeContext |

#### Returns

`TRUE` if `ide_context_unload_async()` has been called.

Since: 3.28

### ide_context_get_workbench ()

    GtkWidget *
    ide_context_get_workbench (IdeContext *self);

When a workbench has registered itself with this context, you can use this to get the IdeWorkbench instance.

#### Parameters

self | a IdeContext |

#### Returns

an IdeWorkbench, or `NULL`.

[transfer none][nullable]

Since: 3.30

## Types and Values

### IDE_TYPE_CONTEXT

    #define IDE_TYPE_CONTEXT (ide_context_get_type())

### IdeContext

    typedef struct _IdeContext IdeContext;

## Property Details

### The `“buffer-manager”` property

      “buffer-manager”           IdeBufferManager *

The buffer manager for the context.

Flags: Read

### The `“build-system”` property

      “build-system”             IdeBuildSystem *

The build system used by the context.

Flags: Read

### The `“configuration-manager”` property

      “configuration-manager”    IdeConfigurationManager *

The configuration manager for the context.

Flags: Read

### The `“device-manager”` property

      “device-manager”           IdeDeviceManager *

The device manager for the context.

Flags: Read

### The `“project”` property

      “project”                  IdeProject *

The project for the context.

Flags: Read

### The `“project-file”` property

      “project-file”             GFile *

The project file for the context.

Flags: Read / Write / Construct Only

### The `“runtime-manager”` property

      “runtime-manager”          IdeRuntimeManager *

Runtime Manager.

Flags: Read

### The `“search-engine”` property

      “search-engine”            IdeSearchEngine *

The search engine for the context.

Flags: Read

### The `“snippets”` property

      “snippets”                 IdeSnippetStorage *

The snippets manager for the context.

Flags: Read

### The `“toolchain-manager”` property

      “toolchain-manager”        IdeToolchainManager *

Toolchain Manager.

Flags: Read

### The `“unsaved-files”` property

      “unsaved-files”            IdeUnsavedFiles *

The unsaved files in the context.

Flags: Read

### The `“vcs”` property

      “vcs”                      IdeVcs *

The VCS for the context.

Flags: Read

## Signal Details

### The `“loaded”` signal

    void
    user_function (IdeContext *idecontext,
                   gpointer    user_data)

This signal is emitted when loading of the context has completed. Plugins and services might want to get notified of this to perform work that requires subsystems that may not be loaded during context startup.

#### Parameters

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

Flags: Run Last

### The `“log”` signal

    void
    user_function (IdeContext *self,
                   guint       log_level,
                   gchar      *message,
                   gpointer    user_data)

The "log" signal is emitted when `ide_context_warning()` or other log messages are sent.

#### Parameters

self | an IdeContext |
log_level | the GLogLevelFlags |
message | the log message |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.28