# Favorites

The **Favorites** object holds a collection of all the defined [favorite folders](../../../basic_concepts/the_lister/navigation/favorites). It is retrieved from the [**DOpus**](dopus)**.favorites** property.

| Property Name      | Return Type                           | Description                                                                                         |
| ------------------ | ------------------------------------- | --------------------------------------------------------------------------------------------------- |
| _\<default value>_ | _collection:_[**Favorite**](favorite) | You can enumerate the **Favorites** object to retrieve individual [**Favorite**](favorite) objects. |

<table data-header-hidden><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td>Method// Name//</td><td><strong>Arguments</strong></td><td>Return Type</td><td>Description</td></tr><tr><td>Add</td><td>&#x3C;string:typeOrName><br>&#x3C;string:path><br>&#x3C;int:insertpos> or<br>&#x3C;object:<a href="favorite"><strong>Favorite</strong></a>></td><td><em>object:</em><a href="favorite"><strong>Favorite</strong></a><br>or *object:*<strong>Favorites</strong></td><td><p>Adds a new favorite folder to the favorites list. Note that changes you make to the list are not saved until you call the <strong>Save</strong> method.</p><p>This method performs three separate functions; it can add a separator, a sub-folder or a favorite folder. </p><p>To add a separator, the parameters should be the type string <strong>sep</strong>, optionally followed by the insertion position (see below).</p><p>For example, <code>Favorites.Add("sep");</code></p><p>You can also make the separator a heading (i.e. a label that appears visually different to other items) by appending the heading name to the <strong>sep:</strong> prefix. For example, <code>Favorites.Add("sep:Current Job");</code></p><p>To add a folder, the first parameter should be the string <strong>folder:</strong> followed by the name of the folder (as a single parameter), optionally followed by the insertion position.</p><p>For example, <code>Favorites.Add("folder:Picture Locations");</code></p><p>To add a new favorite, the first parameter can optionally be the name of the favorite, and the second parameter can be the path of the folder to add, or the name can be omitted and only the path can be provided. In either case you can optionally include the insertion position as the last parameter.</p><p>For example,</p><pre><code>Favorites.Add("myfave", "c:\folder\path");
Favorites.Add("c:\folder\path");
</code></pre><p>In all three cases the new item is added to the end by default, but you can optionally specify a position to insert the item somewhere else. E.g. specifying <strong>0</strong> for the insertion position would add it at the top of the list. You can provide either a number or another **<a href="favorite">Favorite</a>**object.</p><p>For example, <code>Favorites.Add("myfave", "c:\folder\path", 0);</code></p><p>The return value is either a **<a href="favorite">Favorite</a>**or a <strong>Favorites</strong> object (depending on whether you added a sub-folder or a favorite folder).</p></td></tr><tr><td>Delete</td><td>&#x3C;object:<a href="favorite"><strong>Favorite</strong></a>> or<br>&#x3C;object:<strong>Favorites</strong>></td><td><em>none</em></td><td>Deletes the specified favorite or sub-folder. Note that changes you make to the list are not saved until you call the <strong>Save</strong> method.</td></tr><tr><td>Find</td><td>&#x3C;string:name><br>&#x3C;int:index></td><td>*object:*<strong>Favorites</strong></td><td><p>Lets you locate a sub-folder one or more levels below the current one. The <strong>name</strong> parameter is the name or path and name of the sub-folder to look for (e.g. "myfave", "pictures/local", etc).</p><p>The optional <strong>index</strong> parameter lets you handle the case when there might be more than one sub-folder with the same name. <strong>Favorites.Find("pictures", 1);</strong> would find the second sub-folder called "pictures" below the current level.</p></td></tr><tr><td>Save</td><td><em>none</em></td><td><em>none</em></td><td>Saves any changes you've made to the favorites list. Once you call this method changes you have made will be reflected in Preferences and the favorites list in Listers. Note that you can only call this method on the main "root" <strong>Favorites</strong> object obtained from the <a href="dopus"><strong>DOpus</strong></a><strong>.favorites</strong> property</td></tr><tr><td>SetName</td><td>&#x3C;string:name></td><td><em>none</em></td><td>Changes the name of this sub-folder. Note that changes you make to the list are not saved until you call the <strong>Save</strong> method. You can only call this method on <strong>Favorites</strong> objects that refer to sub-folders, and not the main "root" folder.</td></tr></tbody></table>
