====== Garcon Thoughts ======

There are some issues in garcon (previously libxfce4menu, with API changes and GIO support) that needs some discussion, most important: file monitoring support.

**Specifications:** [[http://standards.freedesktop.org/menu-spec/latest/|Desktop Menu]], [[http://standards.freedesktop.org/desktop-entry-spec/latest/|Desktop Entry]].\\
**Sources:** [[http://git.xfce.org/xfce/garcon/|Garcon]], [[http://git.gnome.org/cgit/alacarte/|Alacarte]].

===== File Monitoring =====

We'd like the give the library built-in support for monitoring menu changes. This means we monitor the .menu file(s) for changes (for example made by Alacarte) and the .desktop file directories for added/removed/changed desktop files. When something changed we don't want to rebuild everything, but rather update and trigger some signals and notify properties.


==== GarconMenuDirectory ====
**Description:** FIXME

==== GarconMenuItemCache ====
**Description:** URI -> GarconMenuItem item relation (hash table).

Maybe a signal when a item is added or removed to the pool, but I doubt this is very useful.

==== GarconMenuItemPool ====
**Description:** Desktop-ID -> GarconMenuItem item relation (hash table).

Maybe a signal when a item is added or removed to the pool, but I doubt this is very useful.

==== GarconMenuItem ====
**Description:** The desktop file.

We're not going to implement file monitoring on this level. However there will be some new API to reload a desktop entry (possibly from a new location) and the possibility to watch changes (signal, property notifications).

''GarconMenuItem::changed (VOID:VOID)''\\
Always triggered then the item is reloaded.

''void garcon_menu_item_reload (void)''\\
Reload the menu item from the same GFile. This will notify the changed properties and trigger the 'changed' signal.

''void garcon_menu_item_reload_from_file (GFile *file)''\\
Will do the same as ''garcon_menu_item_reload()'' but from another location, useful when a user changed a desktop file in a read-only location and the menu editor moved the file to ''~/.local/share/applications/''.

==== GarconMenu ====
**Description:** FIXME

This is where we will do all the monitoring work. We will setup monitors for the menu file itself, as well for the merged files and the desktop entry directories. The object will probably get some signals when an item is added/removed/moved, but we need to do this in such a way it is efficient to update menu or tree implementations.

===== TODO =====
  * <del>Fix handling of the Hidden key in .desktop files</del>.
    * <del>Right now we return NULL when loading a desktop files with Hidden=True, this is wrong, we should instead return a GarconMenuItem, add _{get.set}_hidden functions and property. There is a possibility the hidden attribute changes during runtime, then the menu item should be visible again</del>.
  * Always return a reffed object in the _get_ functions and mention this in the API docs.
    * Because we always ref and because of the implementation of the singletons: we also return reffed items in the GList's. This means that developers should also call ''g_list_foreach (list, (GFunc) g_object_unref, NULL);'' or unref in their own loop. This is not a bad thing tho, because of the file monitoring it could be that the menu implementation releases an item (because the .desktop file was destroyed), so apps _should_ have their own references.
    * We could add a helper: ''#define garcon_free_list(l) G_STMT_START { g_list_foreach ((l), (GFunc) g_object_unref, NULL); g_list_free (l); } G_STMT_END''
  * A couple of structs need to move to the header.
    * We need to reserve space if we do this.
  * Personally I find the gio helpers a bit ugly in the public api, maybe we can make this private (preferred) or rename them to start with garcon_.
  * <del>Possibly drop ''garcon_init()'' and ''garcon_shutdown()''. Still needs some thoughts, but it would be nice if we can simplify this as much as possible</del>.
    * <del>Implement ''GarconMenuSeparator'' and ''GarconMenuItemCache'' as a singleton</del>.
    * <del>Get rid of ''g_thread_init()''. This should be possible if we use ''GStaticMutex'' instead of ''GMutex''</del>.
    * <del>People only need to call ''garcon_set_environment()'', this will 'leak' once if they don't call ''garcon_set_environment (NULL)'', but I don't think we really care</del>.
    * <del>Don't know about ''g_type_init()'' yet. Probably not needed 99% of the time, so I think if we mention this in the API docs we're pretty much safe</del>.
  * <del>GIO file loading in ''GarconMenuDirectory''</del>.
  * <del>Get rid of the ''g_strv_length()'' calls in loops</del>.
  * <del>Use the G_KEY_FILE_DESKTOP_* defines where possible</del>.

===== Future=====

  * We currently support desktop files with the type Application and Directory, but not Link.