luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 23:16:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

gappinfo: Clarify one-shot behaviour of GAppInfoMonitor::changed in docs

Browse Source 
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>

Fixes: #799
This commit is contained in:
Philip Withnall 2023-03-22 14:30:39 +00:00
parent 0be2555704
commit c62643adc3
1 changed files with 28 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
gio/gappinfo.c
View File

@ -1658,19 +1658,34 @@ g_app_launch_context_launch_failed (GAppLaunchContext *context,
* @short_description: Monitor application information for changes
*
* #GAppInfoMonitor is a very simple object used for monitoring the app
* info database for changes (ie: newly installed or removed
* applications).
* info database for changes (newly installed or removed applications).
*
* Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
* to the "changed" signal.
* to the #GAppInfoMonitor::changed signal. The signal will be emitted once when
* the app info database changes, and will not be emitted again until after the
* next call to g_app_info_get_all() or another `g_app_info_*()` function. This
* is because monitoring the app info database for changes is expensive.
*
* The following functions will re-arm the #GAppInfoMonitor::changed signal so
* it can be emitted again:
* - g_app_info_get_all()
* - g_app_info_get_all_for_type()
* - g_app_info_get_default_for_type()
* - g_app_info_get_fallback_for_type()
* - g_app_info_get_recommended_for_type()
* - g_desktop_app_info_get_implementations()
* - g_desktop_app_info_new()
* - g_desktop_app_info_new_from_filename()
* - g_desktop_app_info_new_from_keyfile()
* - g_desktop_app_info_search()
*
* In the usual case, applications should try to make note of the change
* (doing things like invalidating caches) but not act on it. In
* particular, applications should avoid making calls to #GAppInfo APIs
* in response to the change signal, deferring these until the time that
* the data is actually required. The exception to this case is when
* the updated data is actually required. The exception to this case is when
* application information is actually being displayed on the screen
* (eg: during a search or when the list of all applications is shown).
* (for example, during a search or when the list of all applications is shown).
* The reason for this is that changes to the list of installed
* applications often come in groups (like during system updates) and
* rescanning the list on every change is pointless and expensive.
@ -1728,8 +1743,10 @@ g_app_info_monitor_class_init (GAppInfoMonitorClass *class)
/**
* GAppInfoMonitor::changed:
*
* Signal emitted when the app info database for changes (ie: newly installed
* or removed applications).
* Signal emitted when the app info database changes, when applications are
* installed or removed.
*
* Since: 2.40
**/
g_app_info_monitor_changed_signal = g_signal_new (I_("changed"), G_TYPE_APP_INFO_MONITOR, G_SIGNAL_RUN_FIRST,
0, NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
@ -1747,6 +1764,10 @@ g_app_info_monitor_class_init (GAppInfoMonitorClass *class)
* thread-default main context whenever the list of installed
* applications (as reported by g_app_info_get_all()) may have changed.
*
* The #GAppInfoMonitor::changed signal will only be emitted once until
* g_app_info_get_all() (or another `g_app_info_*()` function) is called. Doing
* so will re-arm the signal ready to notify about the next change.
*
* You must only call g_object_unref() on the return value from under
* the same main context as you created it.
*