## GarconMenu

GarconMenu — Menu element.

## Synopsis

    #include <garcon/garcon.h>

    struct              GarconMenuClass;
    void                garcon_menu_add_menu                (GarconMenu *menu,
                                                             GarconMenu *submenu);
    GarconMenuDirectory * garcon_menu_get_directory         (GarconMenu *menu);
    GList *             garcon_menu_get_elements            (GarconMenu *menu);
    GFile *             garcon_menu_get_file                (GarconMenu *menu);
    GarconMenuItemPool * garcon_menu_get_item_pool          (GarconMenu *menu);
    GList *             garcon_menu_get_items               (GarconMenu *menu);
    GarconMenu *        garcon_menu_get_menu_with_name      (GarconMenu *menu,
                                                             const gchar *name);
    GList *             garcon_menu_get_menus               (GarconMenu *menu);
    GarconMenu *        garcon_menu_get_parent              (GarconMenu *menu);
    gboolean            garcon_menu_load                    (GarconMenu *menu,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GarconMenu *        garcon_menu_new                     (GFile *file);
    GarconMenu *        garcon_menu_new_applications        (void);
    GarconMenu *        garcon_menu_new_for_path            (const gchar *filename);

## Description

Main element the contains the parsed menu.

## Details

### struct GarconMenuClass

    struct GarconMenuClass {
      GObjectClass __parent__;
    };

### garcon_menu_add_menu ()

    void                garcon_menu_add_menu                (GarconMenu *menu,
                                                             GarconMenu *submenu);

Adds `submenu` as a sub menu to `menu`.

`menu` : | a GarconMenu
`submenu` : | a GarconMenu

### garcon_menu_get_directory ()

    GarconMenuDirectory * garcon_menu_get_directory         (GarconMenu *menu);

Returns the GarconMenuDirectory of `menu` or `NULL` if the <Menu> element that corresponds to `menu` has no valid <Directory> element. The menu directory may contain a lot of useful information about the menu like the display and icon name, desktop environments it should show up in etc.

`menu` : | a GarconMenu.
Returns : | GarconMenuDirectory of `menu` or `NULL` if `menu` has no valid directory element. The returned object should be unreffed with `g_object_unref()` when no longer needed.

### garcon_menu_get_elements ()

    GList *             garcon_menu_get_elements            (GarconMenu *menu);

Get all the menu element in `menu`. This contains sub menus, menu items and separators.

`menu` : | a GarconMenu.
Returns : | a list of GarconMenuItem elements or `NULL`. Free the list with `g_list_free()`.

### garcon_menu_get_file ()

    GFile *             garcon_menu_get_file                (GarconMenu *menu);

Get the file for `menu`. It refers to the .menu file from which `menu` was or will be loaded.

`menu` : | a GarconMenu.
Returns : | a GFile. The returned object should be unreffed with `g_object_unref()` when no longer needed.

### garcon_menu_get_item_pool ()

    GarconMenuItemPool * garcon_menu_get_item_pool          (GarconMenu *menu);

Get the item pool of the menu. This pool contains all items in this menu (for that of its submenus).

`menu` : | a GarconMenu.
Returns : | a GarconMenuItemPool.

### garcon_menu_get_items ()

    GList *             garcon_menu_get_items               (GarconMenu *menu);

Returns all GarconMenuItems included in `menu`. The items are sorted by their display names in ascending order.

The caller is responsible to free the returned list using

    g_list_free (list);

when no longer needed.

`menu` : | a GarconMenu.
Returns : | list of GarconMenuItems included in `menu`.

### garcon_menu_get_menu_with_name ()

    GarconMenu *        garcon_menu_get_menu_with_name      (GarconMenu *menu,
                                                             const gchar *name);

Looks in `menu` for a submenu with `name` as name.

`menu` : | a GarconMenu
`name` : | a sub menu name
Returns : | a GarconMenu or `NULL`.

### garcon_menu_get_menus ()

    GList *             garcon_menu_get_menus               (GarconMenu *menu);

Returns a sorted list of GarconMenu submenus of `menu`.

`menu` : | a GarconMenu
Returns : | a sorted list of GarconMenu object. The list should be freed with `g_list_free()`.

### garcon_menu_get_parent ()

    GarconMenu *        garcon_menu_get_parent              (GarconMenu *menu);

Returns the parent GarconMenu or `menu`.

`menu` : | a GarconMenu
Returns : | a GarconMenu or `NULL` if `menu` is the root menu.

### garcon_menu_load ()

    gboolean            garcon_menu_load                    (GarconMenu *menu,
                                                             GCancellable *cancellable,
                                                             GError **error);

This function loads the entire menu tree from the file referred to by `menu`. It resolves merges, moves and everything else defined in the menu specification. The resulting tree information is stored within `menu` and can be accessed using the public GarconMenu API afterwards.

`cancellable` can be used to handle blocking I/O when reading data from files during the loading process.

`error` should either be NULL or point to a GError return location where errors should be stored in.

`menu` : | a GarconMenu
`cancellable` : | a GCancellable
`error` : | GError return location
Returns : | `TRUE` if the menu was loaded successfully or `FALSE` if there was an error or the process was cancelled.

### garcon_menu_new ()

    GarconMenu *        garcon_menu_new                     (GFile *file);

Creates a new GarconMenu for the .menu file referred to by `file`. This operation only fails `file` is invalid. To load the menu tree from the file, you need to call `garcon_menu_load()` with the returned GarconMenu.

The caller is responsible to destroy the returned GarconMenu using `g_object_unref()`.

For more information about the usage `see` `garcon_menu_new()`.

`file` : | GFile for the .menu file you want to load.
Returns : | a new GarconMenu for `file`.

### garcon_menu_new_applications ()

    GarconMenu *        garcon_menu_new_applications        (void);

Creates a new GarconMenu for the applications.menu file which is being used to display installed applications.

For more information about the usage `see` `garcon_menu_new()`.

Returns : | a new GarconMenu for applications.menu.

### garcon_menu_new_for_path ()

    GarconMenu *        garcon_menu_new_for_path            (const gchar *filename);

Creates a new GarconMenu for the .menu file referred to by `filename`. This operation only fails if the filename is NULL. To load the menu tree from the file, you need to call `garcon_menu_load()` with the returned GarconMenu.

    GarconMenu *menu = garcon_menu_new (filename);

    if (garcon_menu_load (menu, &error))
      ...
    else
      ...

    g_object_unref (menu);

The caller is responsible to destroy the returned GarconMenu using `g_object_unref()`.

`filename` : | Path/URI of the .menu file you want to load.
Returns : | a new GarconMenu for `filename`.