## XfceMenu

XfceMenu

## Synopsis

    #include <libxfce4menu/libxfce4menu.h>

                        XfceMenuPrivate;
                        XfceMenuClass;
                        XfceMenu;
    XfceMenu*           xfce_menu_get_root                  (GError **error);
    XfceMenu*           xfce_menu_new                       (const gchar *filename,
                                                             GError **error);
    const gchar*        xfce_menu_get_filename              (XfceMenu *menu);
    void                xfce_menu_set_filename              (XfceMenu *menu,
                                                             const gchar *filename);
    const gchar*        xfce_menu_get_name                  (XfceMenu *menu);
    void                xfce_menu_set_name                  (XfceMenu *menu,
                                                             const gchar *name);
    XfceMenuDirectory*  xfce_menu_get_directory             (XfceMenu *menu);
    void                xfce_menu_set_directory             (XfceMenu *menu,
                                                             XfceMenuDirectory *directory);
    GSList*             xfce_menu_get_directory_dirs        (XfceMenu *menu);
    GSList*             xfce_menu_get_legacy_dirs           (XfceMenu *menu);
    GSList*             xfce_menu_get_app_dirs              (XfceMenu *menu);
    gboolean            xfce_menu_get_only_unallocated      (XfceMenu *menu);
    void                xfce_menu_set_only_unallocated      (XfceMenu *menu,
                                                             gboolean only_unallocated);
    gboolean            xfce_menu_get_deleted               (XfceMenu *menu);
    void                xfce_menu_set_deleted               (XfceMenu *menu,
                                                             gboolean deleted);
    GSList*             xfce_menu_get_menus                 (XfceMenu *menu);
    void                xfce_menu_add_menu                  (XfceMenu *menu,
                                                             XfceMenu *submenu);
    XfceMenu*           xfce_menu_get_menu_with_name        (XfceMenu *menu,
                                                             const gchar *name);
    XfceMenu*           xfce_menu_get_parent                (XfceMenu *menu);
    XfceMenuItemPool*   xfce_menu_get_item_pool             (XfceMenu *menu);
    GSList*             xfce_menu_get_items                 (XfceMenu *menu);
    gboolean            xfce_menu_has_layout                (XfceMenu *menu);
    GSList*             xfce_menu_get_layout_elements       (XfceMenu *menu);

## Object Hierarchy

      GObject
       +----XfceMenu

## Implemented Interfaces

XfceMenu implements XfceMenuElement.

## Properties

      "deleted"                  gboolean              : Read / Write
      "directory"                XfceMenuDirectory*    : Read / Write
      "filename"                 gchar*                : Read / Write
      "name"                     gchar*                : Read / Write
      "only-unallocated"         gboolean              : Read / Write

## Description

XfceMenu is the most important part of libxfce4menu. In almost all use cases the first thing to be created is an XfceMenu based on a filename.

## Details

### XfceMenuPrivate

    typedef struct _XfceMenuPrivate XfceMenuPrivate;

### XfceMenuClass

    typedef struct _XfceMenuClass XfceMenuClass;

### XfceMenu

    typedef struct _XfceMenu XfceMenu;

### xfce_menu_get_root ()

    XfceMenu*           xfce_menu_get_root                  (GError **error);

Loads the system's root menu. This may take some time as it involves parsing and merging a lot of files. So if you call this function from a GUI program it should be done in a way that won't block the user interface (e.g. by using a worker thread). The returned pointer needs to be released using

    g_object_unref (menu);

when no longer needed.

`error` : | Return location for errors or `NULL`.
Returns : | The system root menu. The menu has to be released when no longer needed.

### xfce_menu_new ()

    XfceMenu*           xfce_menu_new                       (const gchar *filename,
                                                             GError **error);

Parses a file and returns the menu structure found in this file. This may involve parsing and merging of a lot of other files. So if you call this function from a GUI program it should be done in a way that won't block the user interface (e.g. by using a worker thread). The returned pointer needs to be released using

    g_object_unref (menu);

when it is not used anymore.

`filename` : | filename containing the menu structure you want to load.
`error` : | return location for errors or `NULL`.
Returns : | Menu structure found in `filename`.

### xfce_menu_get_filename ()

    const gchar*        xfce_menu_get_filename              (XfceMenu *menu);

Returns the filename from which `menu` was loaded.

`menu` : | a XfceMenu.
Returns : | filename from which `menu` was loaded.

### xfce_menu_set_filename ()

    void                xfce_menu_set_filename              (XfceMenu *menu,
                                                             const gchar *filename);

Sets the menu filename. It should not be necessary to call this function anywhere - it's only of internal use.

`menu` : | a XfceMenu.
`filename` : | new filename of the menu.

### xfce_menu_get_name ()

    const gchar*        xfce_menu_get_name                  (XfceMenu *menu);

Returns the name of `menu`. In most cases this will be the contents of the <Menu> element. It may be useful for providing a display name for the menu if it does not have a menu directory.

`menu` : | a XfceMenu.
Returns : | name of `menu`.

### xfce_menu_set_name ()

    void                xfce_menu_set_name                  (XfceMenu *menu,
                                                             const gchar *name);

Sets the name of `menu`. This might come in handy if you want to replace certain menu names with your own names. However, in most cases this function won't be useful.

`menu` : | a XfceMenu
`name` : | new name of the menu.

### xfce_menu_get_directory ()

    XfceMenuDirectory*  xfce_menu_get_directory             (XfceMenu *menu);

Returns the XfceMenuDirectory of `menu` or `NULL`. The menu directory may contain a lot of useful information about the menu, like display name, desktop environments it should show up in etc.

`menu` : | a XfceMenu.
Returns : | XfceMenuDirectory of `menu` or `NULL`.

### xfce_menu_set_directory ()

    void                xfce_menu_set_directory             (XfceMenu *menu,
                                                             XfceMenuDirectory *directory);

Replaces the XfceMenuDirectory of `menu` with `directory`. This may be useful if `menu` has no directory or if you want to define your own directory for menus. Usually, there's no need to call this function.

`menu` : | a XfceMenu.
`directory` : | a XfceMenuDirectory.

### xfce_menu_get_directory_dirs ()

    GSList*             xfce_menu_get_directory_dirs        (XfceMenu *menu);

Returns a list with all directory dirs of `menu`. Collects directory dirs from `menu` up to the root menu so that the root menu directory dirs come first.

`menu` : | a XfceMenu
Returns : | List with all relevant directory dirs of `menu`.

### xfce_menu_get_legacy_dirs ()

    GSList*             xfce_menu_get_legacy_dirs           (XfceMenu *menu);

`menu` : |
Returns : |

### xfce_menu_get_app_dirs ()

    GSList*             xfce_menu_get_app_dirs              (XfceMenu *menu);

`menu` : |
Returns : |

### xfce_menu_get_only_unallocated ()

    gboolean            xfce_menu_get_only_unallocated      (XfceMenu *menu);

Returns whether `menu` only contains XfceMenuItems which are not already included in other menus.

`menu` : | a XfceMenu.
Returns : | Whether the menu contains only items not used already included in other menus.

### xfce_menu_set_only_unallocated ()

    void                xfce_menu_set_only_unallocated      (XfceMenu *menu,
                                                             gboolean only_unallocated);

Since all items are resolved directly after parsing the menu file, this won't be useful other than internally.

`menu` : | a XfceMenu.
`only_unallocated` : | Whether to include only unused XfceMenuItems

### xfce_menu_get_deleted ()

    gboolean            xfce_menu_get_deleted               (XfceMenu *menu);

`menu` : |
Returns : |

### xfce_menu_set_deleted ()

    void                xfce_menu_set_deleted               (XfceMenu *menu,
                                                             gboolean deleted);

`menu` : |
`deleted` : |

### xfce_menu_get_menus ()

    GSList*             xfce_menu_get_menus                 (XfceMenu *menu);

`menu` : |
Returns : |

### xfce_menu_add_menu ()

    void                xfce_menu_add_menu                  (XfceMenu *menu,
                                                             XfceMenu *submenu);

`menu` : |
`submenu` : |

### xfce_menu_get_menu_with_name ()

    XfceMenu*           xfce_menu_get_menu_with_name        (XfceMenu *menu,
                                                             const gchar *name);

`menu` : |
`name` : |
Returns : |

### xfce_menu_get_parent ()

    XfceMenu*           xfce_menu_get_parent                (XfceMenu *menu);

`menu` : |
Returns : |

### xfce_menu_get_item_pool ()

    XfceMenuItemPool*   xfce_menu_get_item_pool             (XfceMenu *menu);

`menu` : |
Returns : |

### xfce_menu_get_items ()

    GSList*             xfce_menu_get_items                 (XfceMenu *menu);

Convenience wrapper around `xfce_menu_get_item_pool()`, which simply returns the XfceMenuItems contained within the associated item pool as singly linked list.

The caller is responsible to free the returned list using

    g_slist_free (list);

when no longer needed.

`menu` : | a XfceMenu.
Returns : | the list of XfceMenuItems within this menu.

### xfce_menu_has_layout ()

    gboolean            xfce_menu_has_layout                (XfceMenu *menu);

`menu` : |
Returns : |

### xfce_menu_get_layout_elements ()

    GSList*             xfce_menu_get_layout_elements       (XfceMenu *menu);

`menu` : |
Returns : |

## Property Details

### The `"deleted"` property

      "deleted"                  gboolean              : Read / Write

Whether this menu should be ignored.

Default value: FALSE

### The `"directory"` property

      "directory"                XfceMenuDirectory*    : Read / Write

The directory entry associated with this menu.

### The `"filename"` property

      "filename"                 gchar*                : Read / Write

The filename of an `XfceMenu` object. Whenever this is redefined, the menu is reloaded.

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write

The name of the menu.

Default value: NULL

### The `"only-unallocated"` property

      "only-unallocated"         gboolean              : Read / Write

Whether this menu should only contain desktop entries not used by other menus.

Default value: FALSE