GarconMenu: garcon Reference Manual

## GarconMenu GarconMenu — Menu element. |

## Functions

GarconMenu * | garcon_menu_new ()
GarconMenu * | garcon_menu_new_for_path ()
GarconMenu * | garcon_menu_new_applications ()
gboolean | garcon_menu_load ()
GFile * | garcon_menu_get_file ()
GarconMenuDirectory * | garcon_menu_get_directory ()
GList * | garcon_menu_get_menus ()
void | garcon_menu_add_menu ()
GarconMenu * | garcon_menu_get_menu_with_name ()
GarconMenu * | garcon_menu_get_parent ()
GarconMenuItemPool * | garcon_menu_get_item_pool ()
GList * | garcon_menu_get_items ()
GList * | garcon_menu_get_elements ()

## Properties

GarconMenuDirectory * | directory | Read / Write
GFile * | file | Read / Write / Construct Only

## Signals

void | directory-changed | No Hooks
void | reload-required | No Hooks

## Object Hierarchy

        GObject
        ╰── GarconMenu

## Includes

    #include <garcon/garcon.h>

## Description

Main element the contains the parsed menu.

## Functions

### 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 if `file` is invalid. To load the menu tree from the file, you need to call `garcon_menu_load()` with the returned GarconMenu.

    1
    2
    3
    4
    5
    6
    7
    8
    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()`.

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

[constructor]

#### Parameters

file | GFile for the .menu file you want to load. |

#### Returns

a new GarconMenu.

[transfer full]

### 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.

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

[constructor]

#### Parameters

filename | Path/URI of the .menu file you want to load. |

#### Returns

a new GarconMenu for `filename` .

[transfer full]

### 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.

[transfer full]

### 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.

#### Parameters

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_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.

The returned object should be unreffed with `g_object_unref()` when no longer needed.

#### Parameters

menu | a GarconMenu. |

#### Returns

a GFile.

[transfer full]

### garcon_menu_get_directory ()

    GarconMenuDirectory *
    garcon_menu_get_directory (GarconMenu *menu);

Returns the GarconMenuDirectory of `menu` or `NULL` if `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.

#### Parameters

menu | a GarconMenu. |

#### Returns

a GarconMenuDirectory.

[transfer none][nullable]

### garcon_menu_get_menus ()

    GList *
    garcon_menu_get_menus (GarconMenu *menu);

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

#### Parameters

menu | a GarconMenu |

#### Returns

a sorted list of GarconMenu.

[transfer container][element-type GarconMenu]

### garcon_menu_add_menu ()

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

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

#### Parameters

menu | a GarconMenu |
submenu | a GarconMenu |

### 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.

#### Parameters

menu | a GarconMenu |
name | a sub menu name |

#### Returns

a GarconMenu or `NULL`.

[transfer none][nullable]

### garcon_menu_get_parent ()

    GarconMenu *
    garcon_menu_get_parent (GarconMenu *menu);

Returns the parent GarconMenu or `menu` .

#### Parameters

menu | a GarconMenu |

#### Returns

a GarconMenu or `NULL` if `menu` is the root menu.

[transfer none][nullable]

### 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).

#### Parameters

menu | a GarconMenu. |

#### Returns

a GarconMenuItemPool.

[transfer none]

### garcon_menu_get_items ()

    GList *
    garcon_menu_get_items (GarconMenu *menu);

Returns all GarconMenuItem 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()` when no longer needed.

#### Parameters

menu | a GarconMenu. |

#### Returns

list of GarconMenuItem included in `menu` .

[element-type GarconMenuItem][transfer container]

### 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.

Returns a list of GarconMenuItem or `NULL`. Free the list with `g_list_free()`.

#### Parameters

menu | a GarconMenu. |

#### Returns

.

[element-type GarconMenuItem][nullable][transfer container]

## Property Details

### The `“directory”` property

      “directory”                GarconMenuDirectory *

The directory entry associated with this menu.

Owner: GarconMenu

Flags: Read / Write

### The `“file”` property

      “file”                     GFile *

The GFile from which the `GarconMenu` was loaded.

Owner: GarconMenu

Flags: Read / Write / Construct Only

## Signal Details

### The `“directory-changed”` signal

    void
    user_function (GarconMenu          *garconmenu,
                   GarconMenuDirectory *arg1,
                   GarconMenuDirectory *arg2,
                   gpointer             user_data)

Flags: No Hooks

### The `“reload-required”` signal

    void
    user_function (GarconMenu *garconmenu,
                   gpointer    user_data)

Flags: No Hooks