nsINavHistoryQueryOptions

In This Article

toolkit/components/places/nsINavHistoryService.idlScriptable

Represents the global options for executing a query.

1.0

Introduced

Gecko 1.9

Inherits from: nsISupports Last changed in Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10)

Method overview

nsINavHistoryQueryOptions clone();

Attributes

Attribute	Type	Description
`applyOptionsToContainers`	`boolean`	If `true`, the query options are only applied to the containers.
`asyncEnabled`	`boolean`	When `true`, the root container node generated by these options and all of its descendant containers are opened asynchronously if they support doing so. By default, this is `false`. Note: Currently, only bookmark folder containers support being opened asynchronously.
`excludeItemIfParentHasAnnotation` Obsolete since Gecko 13.0	`AUTF8String`	This option excludes items from a bookmarks query if the parent of the item has this annotation. An example is to exclude livemark items (parent folders have the `"livemark/feedURI"` annotation). Ignored for queries over history.
`excludeItems`	`boolean`	This option excludes all URIs and separators from a bookmarks query. This would be used if you just wanted a list of bookmark folders and queries (such as the left pane of the places page). Ignored for queries over history. Defaults to `false`.
`excludeQueries`	`boolean`	Set to `true` to exclude queries (`"place:"` URIs) from the query results. Simple folder queries (bookmark folder symlinks) will still be included. Defaults to `false`.
`excludeReadOnlyFolders`	`boolean`	Set to `true` to exclude read-only folders from the query results. This is designed for cases where you want to give the user the option of filing something into a list of folders. It only affects cases where the actual folder result node would appear in its parent folder and filters it out. It doesn't affect the query at all, and doesn't affect more complex queries (such as "folders with annotation X").
`expandQueries`	`boolean`	When set, allows items with `"place:"` URIs to appear as containers, with the container's contents filled in from the stored query. If not set, these will appear as normal items. Doesn't do anything if `excludeQueries` is set. Defaults to `false`. Note that this has no effect on folder links, which are place: URIs returned by `nsINavBookmarkService`'s `getFolderURI` method. These are always expanded and will appear as bookmark folders.
`includeHidden`	`boolean`	Most items in history are marked "hidden." Only toplevel pages that the user sees in the URL bar are not hidden. Hidden things include the content of iframes and all images on web pages. Normally, you don't want these things. If you do, set this flag and you'll get all items, even hidden ones. Does nothing for bookmark queries. Defaults to `false`.
`maxResults`	`long`	This is the maximum number of results that you want. The query is exeucted, the results are sorted, and then the top `maxResults` results are taken and returned. Set to `"0"` (the default) to get all results. This does not work in conjunction with sorting by title. This is because sorting by title requires us to sort after using locale-sensetive sorting (as opposed to letting the database do it for us). Instead, we get the result ordered by date, pick the `maxResult` most recent ones, and then sort by title.
`queryType`	`short`	The type of search to use when querying the DB; This attribute is only honored by query nodes. It is silently ignored for simple folder queries. See Query type constants for possible values.
`redirectsMode`	`unsigned short`	Specifies how to handle redirects; see Redirects mode constants for details. The default value is `REDIRECTS_MODE_ALL`. Note: This option is only used on `QUERY_TYPE_HISTORY`.
`resolveNullBookmarkTitles`	`boolean`	If a bookmark title is `NULL` (note, not empty), attempt to use the history title. It is set to `false` by default.
`resultType`	`short`	Sets the result type. See Result type constants for possible values.
`showSessions`	`boolean`	Separate/group history items based on session information. Only matters when sorting by date.
`sortingAnnotation`	`AUTF8String`	The annotation to use in `SORT_BY_ANNOTATION_*` sorting modes.
`sortingMode`	`short`	The sorting annotation to use; see Sorting methods for possible values.

Constants

Sorting methods

You can ask for the results to be pre-sorted. Since the DB has indices of many items, it can produce sorted results almost for free. Note: re-sorting is slower, as is sorting by title or when you have a host name.

Constant	Value	Description
`SORT_BY_NONE`	0	For bookmark items, this constant means sort by the natural bookmark order.
`SORT_BY_TITLE_ASCENDING`	1	Sort by the ascending title order.
`SORT_BY_TITLE_DESCENDING`	2	Sort by the descending title order.
`SORT_BY_DATE_ASCENDING`	3	Sort by the ascending date order.
`SORT_BY_DATE_DESCENDING`	4	Sort by the descending date order.
`SORT_BY_URI_ASCENDING`	5	Sort by the ascending URI order.
`SORT_BY_URI_DESCENDING`	6	Sort by the descending URI order.
`SORT_BY_VISITCOUNT_ASCENDING`	7	Sort by the ascending visit count order.
`SORT_BY_VISITCOUNT_DESCENDING`	8	Sort by the descending visit count order.
`SORT_BY_KEYWORD_ASCENDING`	9	Sort by the ascending keyword order.
`SORT_BY_KEYWORD_DESCENDING`	10	Sort by the descending keyword order.
`SORT_BY_DATEADDED_ASCENDING`	11	Sort by the ascending added date order.
`SORT_BY_DATEADDED_DESCENDING`	12	Sort by the descending added date order.
`SORT_BY_LASTMODIFIED_ASCENDING`	13	Sort by the ascending last modified order.
`SORT_BY_LASTMODIFIED_DESCENDING`	14	Sort by the descending last modified order.
`SORT_BY_TAGS_ASCENDING`	17	Sort by the ascending tags order.
`SORT_BY_TAGS_DESCENDING`	18	Sort by the descending tags order.
`SORT_BY_ANNOTATION_ASCENDING`	19	Sort by the ascending annotation order.
`SORT_BY_ANNOTATION_DESCENDING`	20	Sort by the descending annotation order.
`SORT_BY_FRECENCY_ASCENDING`	21	Sort by ascending frecency order.
`SORT_BY_FRECENCY_DESCENDING`	22	Sort by descending frecency order.

Result type constants

Constant	Value	Description
`RESULTS_AS_URI`	0	"URI" results, one for each URI visited in the range. Individual result nodes will be of type "URI".
`RESULTS_AS_VISIT`	1	"Visit" results, with one for each time a page was visited (this will often give you multiple results for one URI). Individual result nodes will have type "Visit".
`RESULTS_AS_FULL_VISIT`	2	This is identical to `RESULT_TYPE_VISIT` except that individual result nodes will have type "FullVisit". This is used for the attributes that are not commonly accessed to save space in the common case (the lists can be very long). Note: Supported only for `QUERY_TYPE_HISTORY`.
`RESULTS_AS_DATE_QUERY`	3	Returns `nsINavHistoryQueryResultNode` nodes for each predefined date range where we had visits. Note: Supported only for `QUERY_TYPE_HISTORY`.
`RESULTS_AS_SITE_QUERY`	4	Returns `nsINavHistoryQueryResultNode` nodes for each site where we have visits. Note: Supported only for `QUERY_TYPE_HISTORY`.
`RESULTS_AS_DATE_SITE_QUERY`	5	Returns `nsINavHistoryQueryResultNode` nodes for each site where we have visits, grouped by date. Note: Supported only for `QUERY_TYPE_HISTORY`.
`RESULTS_AS_TAG_QUERY`	6	Returns `nsINavHistoryQueryResultNode` nodes for each tag. Each tag node is a `RESULTS_AS_TAG_CONTENTS` container defined as `place:querytype=1&resultType=7&folder=tag_folder_id`. Note: Using this result type forces the query type to be `QUERY_TYPE_BOOKMARKS`.
`RESULTS_AS_TAG_CONTENTS`	7	Returns `nsINavHistoryResultNode` nodes for each bookmark contained into the defined tag. To specify the tag you need to add a `folder=tag_folder_id` to the query, and only one folder is allowed. Note: Using this result type forces the query type to be `QUERY_TYPE_BOOKMARKS`. At this time, sorting methods are not supported; results will always be returned in reverse order of insertion.

Query type constants

Constant	Value	Description
`QUERY_TYPE_HISTORY`	0	Query's type is history.
`QUERY_TYPE_BOOKMARKS`	1	Query's type is bookmarks.
`QUERY_TYPE_UNIFIED`	2	Query's type is unified.

Redirects mode constants

Constant	Value	Description
`REDIRECTS_MODE_ALL`	0	Include both redirected-from and redirected-to pages in the results.
`REDIRECTS_MODE_SOURCE`	1	Include redirected-from pages but not redirected-to pages in the results.
`REDIRECTS_MODE_TARGET`	2	Include redirected-to pages but not redirected-from pages in the results.

Methods

clone()

This method creates a new options item with the same parameters of this one.

 nsINavHistoryQueryOptions clone();

Parameters

None.

Return value

Returns the newly created cloned options.

Document Tags and Contributors

Tags:

Contributors to this page: Sheppy, trevorh, Ecmanaut, Erwan, Mak77, Jesse, Mook, Arehman4

Last updated by: Sheppy, Apr 14, 2014, 10:41:57 AM