1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
|
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/
/*!
\contentspage index.html
\previouspage creator-editor-finding.html
\page creator-editor-locator.html
\nextpage creator-editor-refactoring.html
\title Searching with the Locator
You can find the locator in the bottom left of the \QC window.
\image qtcreator-locator.png "List of locator filters"
To activate the locator:
\list
\li Press \key {Ctrl+K} (\key {Cmd+K} on \macos).
\li Select \uicontrol Tools > \uicontrol Locate.
\li Select \uicontrol Edit > \uicontrol {Go to Line}.
\li Click the line and column indicator on the
\l{Using the Editor Toolbar}{editor toolbar}.
\endlist
To open a QML file called \e HelloWorld.qml in the currently open project
using the locator:
\list 1
\li Activate the locator by pressing \key {Ctrl+K}.
\li Start typing the filename.
\image qtcreator-locator-open.png "List of files found in the locator"
\li Move to the filename in the list and press \key Enter.
The file opens in the editor.
\li To move to a line in the file, enter the line number in the locator.
\endlist
To move directly to a particular line and column in the document when you
open the document, append them to the file name in the locator, separated by
plus signs (+) or colons (:). For example, to open \e HelloWorld.qml to line
41 and column 2, enter: \c {HelloWorld.qml:41:2}.
If the path to a file is very long, it might not fit into the locator
window. To view the full path, press \key Alt when the filename is selected
or use the handle next to the locator window to increase the window width.
It is also possible to enter only a part of a search string. As you type,
the locator shows the occurrences of that string regardless of where in the
name of an component it appears. Some locator filters, such as colon and
\c m, support \e fuzzy matching, which means that you can enter the
uppercase letters to locate a symbol when using camel case or the letters
after the underscore when using snake case.
To narrow down the search results, you can use the following wildcard
characters:
\list
\li To match any number of any or no characters, enter \c{*}.
\li To match a single instance of any character, enter \c{?}.
\endlist
\section1 Using Locator Filters
The locator enables you to browse not only files, but any items defined by
\b{locator filters}. The filters that are available depend on the file type:
\list
\li Locating any open document (\c {o})
\li Locating files anywhere on your file system (\c {f})
\li Locating files belonging to your project (\c {p}), such as source,
header, resource, and \c {.ui} files, or to any project (\c {a})
\if defined(qtcreator)
\li Locating bookmarks (\c {b}).
For more information, see \l{Using Bookmarks}.
\li Locating class (\c {c}), enum, and function (\c {m}) definitions in
your project or anywhere referenced from your project (\c {:})
\endif
\li Locating QML methods (\c {m})
\li Locating symbols in the current document (\c {.})
\li Locating a specific line and column in the document displayed in
your editor (\c {l <line_number>:<column_number>})
\li Opening help topics, including Qt documentation (\c {?})
\li Performing web searches (\c {r})
\if defined(qtcreator)
\li Running text editing macros that you record and save (\c {rm}). For
more information, see \l{Using Text Editing Macros}
\endif
\li Executing JavaScript (\c {=}), especially useful for calculations.
For more information, see \l{Executing JavaScript}.
\li Executing shell commands (\c {!})
\li Executing version control system commands (\c {git}).
\if defined(qtcreator)
For more information, see \l{Using Version Control Systems}
\else
For more information, see \l{Using Git}
\endif
\li Triggering menu items from the main menu (\c {t})
\li Searching for issues from the \l{https://bugreports.qt.io/}
{Qt Project Bug Tracker} (\c bug).
\if defined(qtcreator)
\li Running external tools (\c x)
\li Using CMake to build the project for the current run configuration
(\c {cm}). For more information, see \l {Setting up CMake}.
\li Opening the CMakeLists.txt file for the current run configuration in
the editor (\c {cmo}). This is the same build target as when you
select \uicontrol Build > \uicontrol {Build for Run Configuration}.
\endif
\endlist
To use a specific locator filter, type the assigned prefix followed by
\key Space. The prefix is usually a single character. Then type the search
string (typically, a filename or class name) or the command to execute.
You can also double-click a locator filter in the filter list to use it. You
can use the up and down arrow keys or the \key Ctrl+P and \key Ctrl+N
keyboard shortcuts to move up and down the list, and then press \key Enter
to use the selected filter.
\if defined(qtcreator)
For example, to locate symbols matching QDataStream:
\list 1
\li Activate the locator.
\li Enter a colon (:) followed by a space and the upper case letters in
the symbol name (QDataStream):
\code
: qds
\endcode
The locator lists the results.
\image qtcreator-locator-example.png "List of files matching the locator filter"
\endlist
Filters locating files also accept paths, such as \c {tools/*main.cpp}.
Filters locating class and function definitions also accept namespaces,
such as \c {Utils::*View}.
\endif
For example, to create a new file and open it in the editor, type \c f
followed by \key Space, followed by path and file name, and then press
\key Enter.
You can use the filter that triggers menu commands to open sessions. Enter
\c {t yoursess} or \c {t sess yoursess} to trigger \uicontrol File >
\uicontrol Sessions > \e yoursessionname.
By default, the following filters are enabled and you do not need to use
their prefixes explicitly:
\list
\li Going to a line and column in the current file (\c {l}).
\li Going to an open file (\c {o}).
\li Going to a file in any open project (\c {a}).
\endlist
If locator does not find some files, you can add them to the \c DISTFILES
variable in the \c .pro file to include them into the distribution tarball
of your project and thus make them known to \QC as well.
\section1 Configuring Locator Filters
If the default filters do not match your use case, you can check whether you
can change them. For all filters, you can change the filter prefix and
restrict the search to items that match the filter.
To configure a locator filter:
\list 1
\li In the locator, click \inlineimage magnifier.png
(\uicontrol Options) and select \uicontrol Configure to open the
\uicontrol Locator options.
\li Select a filter, and then select \uicontrol Edit.
\li Specify the prefix string.
\li To implicitly include the filter even when not typing a prefix as a
part of the search string, select \uicontrol {Include by default}.
\li Specify other available options. For more information, see
\l{Adding Web Search Engines}.
\endlist
\section2 Adding Web Search Engines
You can use the \uicontrol {Web Search (r)} locator filter to perform
web searches. URLs and search commands for Bing, Google, Yahoo! Search,
cplusplus.com, and Wikipedia are configured by default.
To find out the format of the search command to use for your favorite
web search engine, perform a search in your browser and copy the resulting
URL to the locator filter configuration. Replace the search term with the
variable \c {%1}.
To add URLs and search commands to the list:
\list 1
\li Select \uicontrol Tools > \uicontrol Options >
\uicontrol Environment > \uicontrol Locator >
\uicontrol {Web Search (prefix: r)} > \uicontrol Edit.
\li Select \uicontrol Add to add a new entry to the list.
\image qtcreator-add-online-doc.png "List of URLs in Filter Configuration dialog"
\li Double-click the new entry to specify a URL and a search command.
For example, \c {http://www.google.com/search?q=%1}.
\li Click \uicontrol OK.
\endlist
\section1 Creating Locator Filters
You can create custom locator filters for finding in a directory structure
or on the web.
To quickly access files not directly mentioned in your project, you can
create your own directory filters. That way you can locate files in a
directory structure you have defined.
To create custom locator filters:
\list 1
\li In the locator, select \uicontrol Options >
\uicontrol Configure to open the \uicontrol Locator options.
\image qtcreator-locator-customize.png "Locator options tab"
\li Select \uicontrol Add > \uicontrol {Files in Directories} to add
a directory filter or \uicontrol {URL Template} to add a URL
filter. The settings to specify depend on the filter type.
\image qtcreator-locator-generic-directory-filter.png "Filter Configuration dialog"
\li In the \uicontrol Name field, enter a name for your filter.
\li In the \uicontrol Directories field, select at least one
directory. The locator searches directories recursively.
\li In the \uicontrol {File pattern} field, specify file patterns to
restrict the search to files that match the pattern.
Use a comma separated list. For example, to search for all
\c {.qml} and \c {.ui.qml} files, enter \c{*.qml,*.ui.qml}
\li In the \uicontrol {Exclusion pattern} field, specify file
patterns to omit files from the search.
\li In the \uicontrol Prefix field, specify the prefix string.
To implicitly include the filter even when not typing a prefix
as a part of the search string, select
\uicontrol {Include by default}.
\li Select \uicontrol OK.
\endlist
\section1 Configuring Locator Cache
The locator searches the files matching your file pattern in the directories
you have selected and caches that information. The cache for all default
filters is updated as you write your code. By default, \QC updates the
filters created by you once an hour.
To update the cached information manually, select \uicontrol Options >
\uicontrol Refresh in the locator.
To set a new cache update time:
\list 1
\li Select \uicontrol Tools > \uicontrol Options >
\uicontrol Environment > \uicontrol Locator.
\li In \uicontrol {Refresh interval}, define new time in minutes.
\endlist
\section1 Executing JavaScript
The locator provides access to a JavaScript interpreter, that can be used to
perform calculations.
Beside simple mathematical operations, like ((1 + 2) * 3), the following
built-in functions exist:
\table
\header
\li Function
\li Purpose
\row
\li abs(x)
\li Returns the absolute value of x
\row
\li acos(x)
\li Returns the arccosine of x, in radians
\row
\li asin(x)
\li Returns the arcsine of x, in radians
\row
\li atan(x)
\li Returns the arctangent of x, in radians
\row
\li atan2(x, y)
\li Returns the arctangent of the quotient of its arguments
\row
\li bin(x)
\li Returns the binary representation of x
\row
\li ceil(x)
\li Returns the value of x rounded up to the next integer
\row
\li cos(x)
\li Returns the cosine of x (x is in radians)
\row
\li exp(x)
\li Returns the value of E to the power of x
\row
\li e()
\li Returns Euler's number E (2.71828...)
\row
\li floor(x)
\li Returns the value of x rounded down to the next integer
\row
\li hex(x)
\li Returns the hexadecimal representation of x
\row
\li log(x)
\li Returns the natural logarithm (base E) of x
\row
\li max([value1[, value2[, ...]]])
\li Returns the highest value of the given numbers
\row
\li min([value1[, value2[, ...]]])
\li Returns the lowest value of the given numbers
\row
\li oct(x)
\li Returns the octal representation of x
\row
\li pi()
\li Returns PI (3.14159...)
\row
\li pow(x, y)
\li Returns the value of x to the power of y
\row
\li random()
\li Returns a random number between 0 and 1
\row
\li round(x)
\li Returns the value of x rounded to the next integer
\row
\li sin(x)
\li Returns the sine of x (x is in radians)
\row
\li sqrt(x)
\li Returns the square root of x
\row
\li tan(x)
\li Returns the tangent of x (x is in radians)
\endtable
*/
|