Editing Foobar2000:Components/Quicksearch UI Element (foo quicksearch)

{{fb2k}}
[[Category:foobar2000 3rd-Party Components|Quicksearch UI Element (foo quicksearch)]]
[[Image:QuickSearch3.png|thumb|right|405px|Quick Search]]
=General=
'''foo_quicksearch''' is derived from [http://www.hydrogenaudio.org/forums/index.php?showtopic=44012 foo_uie_quicksearch] and ported to foobar2000 V1.0.x. It is now available as either a Column UI panel or an UI element for the default UI. The version has been rewritten (almost) from scratch to benefit from the new SDK and introduce new features such as autoplaylist generation, full customization of the context menu, ....

Configuration has also been simplified with separation of general and toolbar customization, and performances have been improved thanks to new features in the SDK.

===Download link===
The component is available from [http://www.foobar2000.org/components/view/foo_quicksearch here]. Download an place in your foobar components directory (or use the automatic updater with foobar V1.1)

===Discussion===
Please use [http://www.hydrogenaudio.org/forums/index.php?showtopic=80259 this thread] to provide feedback or report any bug.

===Requirements===
As of version 2.4 [2011-04-16]:
* Foobar 1.1 (or newer) is required and Column UI 0.3.8.x (Optional). The component will not work with previous versions of Foobar.
* [[http://www.microsoft.com/downloads/en/details.aspx?FamilyID=c32f406a-f8fc-4164-b6eb-5328b8578f03 Microsoft Visual C++ 2010 Redistributable Package] may also be needed if not already present on your system Microsoft Visual C++ 2010 Redistributable Package] may also be needed if not already present on your system

===Getting started===
Although the toolbar is highly configurable, the recommended scenario is to just install the toolbar as an UI element (Default UI) or a column UI panel, then type a string and press the enter key to visualize the results. A popup instance of the toolbar can also be activated from the main Menu (Library->Quicksearch).

If you are using column UI, it is recommended that your remove 'foo_uie_quicksearch' from your components directory.

=Usage=

===Basic usage===
A search is triggered by the enter key, using the string typed in the toolbar as the basic criteria.

The target playlist (as set in the Preferences page) will be fed with the results of the search ... or a new playlist (or autoplaylist) will be created (according to the corresponding toolbar menu options or depending on the special keys used to trigger the search).

The toolbar is highlighted when the search is not successful.

===Special Keys===
Pressing "Crtl", "Alt" or "Shift" keys (together with the enter key) will trigger the following processings, regardless of the search parameters that are currently selected :
* Ctrl: Force the creation of a new results playlist
* Ctrl+Shift: Force the creation of a new (results) autoplaylist
* Alt: Force search in the current playlist
* Alt+Shift: Force search in all playlist(except the last search results) 
* Shift: Force inline playlist search
* Ctrl+Alt: Force the creation of a new results playlist and use the current playlist as the search source
* Ctrl+Alt+Shift: Force the creation of a new results playlist and use all playlists (except the last search results) as the search source

===About playlists created with the toolbar===
You can do whatever you want with the playlists that are created when the "New Playlist" or "New Autoplaylist" options are checked in the toolbar menu, except for the restrictions that apply to autoplaylists.

The "standard" results playlist behaves slightly differently. You can add or remove items or even delete it (it will be recreated automatically). As its contents is controlled by the toolbar,it cannot be renamed in order to avoid the situation where it would have been renamed and its contents changed by the next search.

===Main menu entry===
A menu entry (Library-->Quicksearch) is available to launch the toolbar in standalone pop-up mode, when the toolbar is not already available (DUI). This entry can be mapped to a keyboard shortcut.
===Main keyboard shortcuts===
Three additional entries are available to be mapped as (main) keyboard shortcuts :
* '''Activate toolbar''' will set focus to the toolbar
* '''Create playlist from last search''' will re execute the last search and create a new playlist
* '''Create autoplaylist from last search''' will re execute the last search and create a new autoplaylist. If the last search was not from the media library, a simple playlist is created instead.

Note that generated autoplaylists can later be edited to change their content and underlying query (See [[Foobar2000:Components/Quicksearch_UI_Element_(foo_quicksearch)#Autoplaylist_Client|Autoplaylist Client]] below).

===Context menu===
[[Image:QsContextMenu.png|thumb|right|405px|Quicksearch Context Menu]]

A context menu is available from the playlist view (Search for same) and will list some tags to be used in order to search in the media library for similar entries. 

The content of the context menu is now fully customizable. Please refer to the "Tagz strings" area of the preferences page for details.

These context menu entries can be mapped to keyboard shortcuts.

Please note that the context menu is not available (and grayed) when several entries are selected in the playlist view.

=Configuration=
==Toolbar Menu==
A toolbar menu is available by (left) clicking on the toolbar icon and provides with the ability to customize search parameters or the look of the toolbar. Options are divided into sections which are described below :
[[Image:QsToolbarMenu.PNG|thumb|left|405px|Quicksearch Toolbar Menu]]
===Search configuration===
'''Search in :'''

Indicates where to search : 
* '''Database''' Will search in the media library
* '''Playlist''' will search in the currently selected playlist
* '''Playlist (inline) ''' will search in the currently selected playlist but will highlight the results in the currently selected playlist. If "Set Focus to search results" is not selected in the preferences page, navigation in the selected results is available through the "Up" and "Down" arrow keys.
* '''All Playlists ''' will search in the contents of all playlist. Please note that the playlist containing the previous search results will be skipped when searching in all playlists.

'''Tags'''

Provides with the ability to select in which tags the search will be performed. The contents of this option is customizable in the general preferences page (See "Tagz strings" section).

'''Match :'''

Determines what kind of processing will be performed to produce the results, in particular when several keywords are typed :
* '''Match all''' will select tracks if all keywords are found in the tags determined by the "Search in ..." option
* '''Match all''' will select tracks if one of the keywords is found in the tags determined by the "Search ins" option
* '''Exact''' will select tracks if the typed string exactly matches the contents of the tags determined by the "Search in ..." option
* '''Prefix''' will select tracks if when the contents of the tags determined by the "Search in ..." option are starting with the typed string
* '''Extended''' will use the foobar query syntax. Look [http://wiki.hydrogenaudio.org/index.php?title=Foobar2000:Query_syntax here] for further details.

'''Autosearch'''

Enables automatic searching. The toolbar will automatically (e.g. without the need to press the enter key) trigger a search when this option is selected. The launch of the search is control by a delay that can be tuned in the general Preferences page.
Autosearch is mutually exclusive with "New playlist" and "New autoplaylist" options.

Please note that the autosearch is not triggered when the searched string has only one character.

===Results Playlist Management===
These options are mutually exclusive with "Autosearch ..." option. Thee are not available as well for autoplaylist clients.

'''New Playlist'''

Will generate a new playlist instead of sending the results to the "Target Playlist" indicated in the preferences page. Please note this option is deactivated when "Playlist (inline)" is selected as the source. 

'''New Autoplaylist'''

Will generate a new playlist instead of sending the results to the "Target Playlist" indicated in the preferences page, and set up this new playlist as an autopaylist, using the transformed search criteria. Please note this option is deactivated when anything else than "Database" is selected as the source and is mutually exclusive with the "New Playlist" option.

===History and Favorites===

'''History'''

This menu entry provides with the list of recent queries. Selecting one of them will reexecute the corresponding search. A visual indication of the source of each search appears in history (From DB=Noting, Playlist=[P], All Playlist=[A], Inline=[I]) after the searched pattern.

Please note that parameters (Search in ..., Tags ..., Match ...) are saved within the history and will be recalled together with the search criteria.

An option ("Clear") is provided to clear the history below the list.

'''Favorites'''

The search history can be used to flag some entries as favorites. The menu entry provides options :
* to add history items to favorites
* to delete favorites
* to recall one of the favorites searches for reexecution

===Options and Preferences===

'''Options'''

This option enable to customize the look of the toolbar, including :
* Loading a custom bitmap (Must be 2 x 16x20, e.g. hight=16, width=40 with the second part used as the mouseover image. The top left pixel of each part will be used as the transparent color). Selecting this option when a custombitmap is loaded will revert to the standard image.
* Customizing the frame style (None Grey, Sunken).
* Customizing the colors. Default toolbar colors are those set in DUI or CUI preferences, and a custom color can be set for each category (Text and Background ... for normal and errors state). When customized, these options will revert to the default colors if selected.

'''Options->Reset configuration'''

This option will revert to the default toolbar configuration, for all the toolbar menu options.

'''Preferences'''

Will give access to the general preferences.

===Notes===
* "New playlist" and "New autoplaylist" options are not compatible with "Inline playlist search" and will be deactivated accordingly.
* "New autoplaylist" cannot be used when searching from an other source than the media library and will be deactivated accordingly.
* You are not allowed to rename the results playlist. It is automatically managed by the plugin.
* Sorting (Foobar Query syntax) is not currently supported.

==Toolbar Icon Status==
The toolbar icon gives and indication of currently selected options and can take the following appearance :
* [[File:QsIcon-Normal.png]]   Standard search in Media Library
* [[File:QsIcon-Autosearch.png]]   Autosearch (e.g. search as you type)
* [[File:QsIcon-NewPlaylist.png]]   A new playlist will be created
* [[File:QsIcon-NewAutoPlaylist.png]]   A new autoplaylist will be created

* [[File:QsIcon-InPlaylist.png]]   Search will take place in the current playlist
* [[File:QsIcon-Error.png]]   Autosearch takes place in the current playlist, but there is no active selection. Selecting a playlist different from the search results playlist and reactivating the toolbar will revert to normal search in playlist
* [[File:QsIcon-PlaylistInline.png]]   Search will take place using all playlists
* [[File:QsIcon-AllPlaylists.png]]   Search will take place using all playlists

Please note that the corresponding situations may be combined in a single icon to reflect the actual selected search parameters.

==Preferences==
The general configuration is available from the Preferences menu (under Media Library/Quicksearch) or by selecting "Preferences" from the toolbar Menu. 

Note that the general configuration is now consistent with the standard foobar behavior for preference pages (OK, Cancel and Apply buttons). Changes (including any change made in the Tagz list) are '''not''' taken into account until the OK or Apply buttons are hit. 
[[Image:QsPreferences.png‎|thumb|right|600px|Quick Search Preferences Page]]
Options are divided into sections as follows :
===Search ...===
'''Reset searchstring when successfull'''

Will blank the string you have typed after a successfull search.

'''Reset "New Playlist" after execution'''

Will unselect "New Playlist" or "New Autoplaylist" after execution.

'''Remove parenthesis from search tags (context menu)'''

Will automatically remove parenthesis found in tags from the selected track before building the query. Can be usefull to search more globally (e.g. excluding "(Disc 1 ... n)" from the search criteria).

'''Automatic switch to extended search'''

Will automatically force the "Match ..." option in the toolbar to "Extended" when a "%" character is typed in the toolbar. Enables easier usage of extended queries.
The "Match ..." option will revert to its previous value if only normal characters are present or if the typing area is cleared.

'''Autosearch delay'''

Enables to fine tune the delay which triggers the search when the "Autosearch" option is selected in the toolbar. It is recommended that you set this option to "Slow" if your system is Slow or if you have a large library.

===Tagz strings===
Enables the customization of strings to look for during a search. The list can be manipulated using the "Add", "Change", "Delete", "Reset", "Up" and "Down" buttons and the fields below the list :
* '''Name''' is the human readable index of the list and will appear in the "Tagz strings ..." menu of the toolbar and in the context menu options
* '''Value''' contains the Tagz language strings used for the search
* '''Context Menu''' will enable the entry in the context menu and keyboard shortcuts mapping.
'''Please note :'''
* The status of the "Add", "Change" and "Delete" buttons is managed to avoid duplicates in the list. Rules are the following :
** You cannot have the same value with two different name
** You cannot have several entries with the same name
* For the strings to appear in Keyboards shortcuts preferences, the "OK" button needs to be hit in Quicksearch Preferences page before moving to the keyboard shortcuts preference pages.

===Search Results===
'''Target Playlist'''

Indicates the name of the playlist that will be fed with the search results.

'''Target Playlist (New)'''

Indicates the name of the playlist that will be fed with the search results when generating a new playlist or a new autoplaylist.

'''Append searchstring to playlist name'''

When selected, the string used for the search will be appended (between brackets) to the playlist name.

'''Set focus to search results'''

Will set the focus to the main foobar window after a successful search. Please note that this option is irrelevant when Autosearch is activated.

'''History size'''

Indicates the desired length for the search history. Setting this parameter to zero will clear the search history.

'''Manage Favorites'''

Indicates whether the management of favorites is desired.

==Autoplaylist Client==
[[File:PlContextMenu.png|thumb|right|450px|Playlist Context Menu]]
Autoplaylists created with foo_quicksearch can be edited from the context menu (right click) of the playlist manager. 

Activating this entry will pop-up a new instance of the quicksearch toolbar, in order to modify the search parameters. Results are directly fed into the selected playlist.

Please note that autoplaylists can only lookup in foobar's media library (and not playlists). Some options in the toolbar menu of autoplaylist clients are grayed out accordingly.

The "New playlist" and "New Autoplaylist" entries are not available in this context, as the results will only be updated in the selected autoplaylist.

=Change Log=
* '''V2.9''' [to be released]
** Reviewed history management in case of recall to acccount for forced parameters
** Provided visual indication of source in history (From DB=Noting, Playlist=[P], All Playlist=[A], Inline=[I]
* '''V2.8''' [2011-05-11]
** Invalidated Shift and Alt key in autoplaylist clients
** Fixed bug :Alt+Enter, Alt+Shift+Enter not working (since V2.3)
* '''V2.7''' [2011-05-10]
** Fixed behavior during copy/paste operations by core uie mgt.
** Implemented autoplaylist client (to easily edit previously generated autoplaylist)
** Various bugs fixed and code reorganized
** Implemented Quicksearch as a referenced media library viewer (Prefs pages->Media Library)
** Automatic refresh when in Autosearch mode when search criterias (e.g. Search in ..., Tags ..., Match ...) are changed
* '''V2.6''' [2011-05-05]
** Integrated Quicksearch in media library preferences page
** Implemented "bump" on activation request (From media library preferences page OR "Quicksearch" playlist lock OR menu command: activate toolbar)
* '''V2.5''' [2011-04-29]
** Removed default selection of first item after a search
* '''V2.4''' [2011-04-16]
** Compiled with the latest SDK [2011-03-11] & VS2010
** Fixed Alt+F4 Key behavior
* '''V2.3''' [2010-10-19]
** Fixed Alt Key behavior
* '''V2.2''' [2010-10-07]
** Reworked context menu management
** Branch to toolbar instead of preferences when invoking show_ui() from playlist lock in playlist managers
** Fixed GDI leak
* '''V2.1''' [2010-09-26]
** Reworked the removal of leading/trailing blanks in "search for same ..." query string when parenthesis removal is active (suspected crash)
* '''V2.0''' [2010-09-02]
** Eliminated leading/trailing blanks in "search for same ..." pattern when parenthesis removal is active
** Updated to latest SDK version [2010-05-21]
* '''V1.9''' [2010-05-14]
** Eliminated flickering
* '''V1.8'''
** Augmented max history and favorites size
** Fixed background color of preferences page
* '''V1.7'''
** ''V1.7.1 Quickfix'' : Removed setting the search results playlist as the playing playlist
** Invalidated "Tags ..." in toolbar Menu when "Extended" is selected
** Fixed small glitch in preferences display
** Fixed ''DURING LAST'' queries not working properly
* '''V1.6'''
** Fixed improper management of favorites
* '''V1.5'''
** Various minor bugfix in toolbar menus and playlist generation
** Revisited keyboard shortcut recalls to generate new playlist (instead of simply recalling the last search) and added autoplaylist option
* '''V1.4'''
** New keyboard shortcut to recall last search
** Separate field for target "new" playlist name (Preferences)
** Various labels changed in toolbar menu
** Permanent alignment of playlist name with preferences
** (Internal) re engineering of the playlist lock management (now in Init section)
* '''V1.3'''
** Results Playlist can be removed
** Implemented max favorites size (32)
* '''V1.2'''
** Implemented a new keyboard shortcut to focus on the toolbar
** Implemented a minmax size option for CUI
* '''V1.1'''
** CUI: Now available as a toolbar, not only a panel
** Renamed menu entries to "Quicksearch ..."
** Fixed (tbc) context menu option label glitch
** Invalidated "Set focus to search results" when Autosearch is active
** Updated help page address
* '''V1.0'''
** Initial version

=To do=
* Implement history dropdown
* Feed the shared selection instead of target playlist (maybe)
* Check "Set focus to search results" (improve focus mgt to focus on playlist manager, through service_enum ??)
* Add an option to play the results after a search
* Think about multi valued fields