Commit e7fdaf47dfdf5e2f6056aa5d5b4644e74a05492a

kavindra
Mon Apr 27 16:32:35 CEST 2009

Tree SHA1: 772e167
Parent SHA1: c1ba514 (Ensure that QFontDialog::getFont() works on Mac OS X.)
raw diff | raw patch

Doc - cleaning up some documentation for QFileDialog and obsolete
documentation.

getOpenFileNames() and getExistingDirectory() mentioned that the dir
parameter was ignored. This is no longer the case. This bit was reviewed
by nrc, the other fixes were just cleanups.

Task-number: 252223
Reviewed-by: nrc

Diff rendering mode:
inline
side by side


1538	1538	#endif
1539	1539
1540	1540	/*!
1541		This is a convenience static function that returns an existing file
1542		selected by the user. If the user presses Cancel, it returns a null
1543		string.
	1541	This is a convenience static function that returns an existing file
	1542	selected by the user. If the user presses Cancel, it returns a null string.
1544	1543
1545		\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 8
	1544	\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 8
1546	1545
1547		The function creates a modal file dialog with the given \a parent widget.
1548		If the parent is not 0, the dialog will be shown centered over the
1549		parent widget.
	1546	The function creates a modal file dialog with the given \a parent widget.
	1547	If \a parent is not 0, the dialog will be shown centered over the parent
	1548	widget.
1550	1549
1551		The file dialog's working directory will be set to \a dir. If \a
1552		dir includes a file name, the file will be selected. Only files
1553		that match the given \a filter are shown. The filter selected is
1554		set to \a selectedFilter. The parameters \a dir, \a
1555		selectedFilter, and \a filter may be empty strings. If you want
1556		multiple filters, separate them with ';;', for example:
	1550	The file dialog's working directory will be set to \a dir. If \a dir
	1551	includes a file name, the file will be selected. Only files that match the
	1552	given \a filter are shown. The filter selected is set to \a selectedFilter.
	1553	The parameters \a dir, \a selectedFilter, and \a filter may be empty
	1554	strings. If you want multiple filters, separate them with ';;', for
	1555	example:
1557	1556
1558		\code
	1557	\code
1559	1558	"Images (.png .xpm .jpg);;Text files (.txt);;XML files (*.xml)"
1560		\endcode
	1559	\endcode
1561	1560
1562		The \a options argument holds various
1563		options about how to run the dialog, see the QFileDialog::Option enum for
1564		more information on the flags you can pass.
	1561	The \a options argument holds various options about how to run the dialog,
	1562	see the QFileDialog::Option enum for more information on the flags you can
	1563	pass.
1565	1564
1566		The dialog's caption is set to \a caption. If \a caption is not
1567		specified then a default caption will be used.
	1565	The dialog's caption is set to \a caption. If \a caption is not specified
	1566	then a default caption will be used.
1568	1567
1569		Under Windows and Mac OS X, this static function will use the native
1570		file dialog and not a QFileDialog.
	1568	On Windows and Mac OS X, this static function will use the native file
	1569	dialog and not a QFileDialog.
1571	1570
1572		Note that on Windows the dialog will spin a blocking modal event loop
1573		that will not dispatch any QTimers, and if parent is not 0 then it will
1574		position the dialog just under the parent's title bar.
	1571	On Windows the dialog will spin a blocking modal event loop that will not
	1572	dispatch any QTimers, and if \a parent is not 0 then it will position the
	1573	dialog just below the parent's title bar.
1575	1574
1576		Under Unix/X11, the normal behavior of the file dialog is to resolve
1577		and follow symlinks. For example, if \c{/usr/tmp} is a symlink to
1578		\c{/var/tmp}, the file dialog will change to \c{/var/tmp} after
1579		entering \c{/usr/tmp}. If \a options includes DontResolveSymlinks,
1580		the file dialog will treat symlinks as regular directories.
	1575	On Unix/X11, the normal behavior of the file dialog is to resolve and
	1576	follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
	1577	the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If
	1578	\a options includes DontResolveSymlinks, the file dialog will treat
	1579	symlinks as regular directories.
1581	1580
1582		\warning Do not delete \a parent during the execution of the dialog.
1583		If you want to do this, you should create the dialog
1584		yourself using one of the QFileDialog constructors.
	1581	\warning Do not delete \a parent during the execution of the dialog. If you
	1582	want to do this, you should create the dialog yourself using one of the
	1583	QFileDialog constructors.
1585	1584
1586		\sa getOpenFileNames(), getSaveFileName(), getExistingDirectory()
	1585	\sa getOpenFileNames(), getSaveFileName(), getExistingDirectory()
1587	1586	*/
1588	1587	QString QFileDialog::getOpenFileName(QWidget *parent,
1589	1588	const QString &caption,
…	…
1625	1625	}
1626	1626
1627	1627	/*!
1628		This is a convenience static function that will return one or more
1629		existing files selected by the user.
	1628	This is a convenience static function that will return one or more existing
	1629	files selected by the user.
1630	1630
1631		\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 9
	1631	\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 9
1632	1632
1633		This function creates a modal file dialog with the given \a parent
1634		widget. If the parent is not 0, the dialog will be shown centered
1635		over the parent widget.
	1633	This function creates a modal file dialog with the given \a parent widget.
	1634	If \a parent is not 0, the dialog will be shown centered over the parent
	1635	widget.
1636	1636
1637		The file dialog's working directory will be set to \a dir. If \a
1638		dir includes a file name, the file will be selected. The filter
1639		is set to \a filter so that only those files which match the filter
1640		are shown. The filter selected is set to \a selectedFilter. The parameters
1641		\a dir, \a selectedFilter and \a filter may be empty strings. If you
1642		need multiple filters, separate them with ';;', for instance:
	1637	The file dialog's working directory will be set to \a dir. If \a dir
	1638	includes a file name, the file will be selected. The filter is set to
	1639	\a filter so that only those files which match the filter are shown. The
	1640	filter selected is set to \a selectedFilter. The parameters \a dir,
	1641	\a selectedFilter and \a filter may be empty strings. If you need multiple
	1642	filters, separate them with ';;', for instance:
1643	1643
1644		\code
	1644	\code
1645	1645	"Images (.png .xpm .jpg);;Text files (.txt);;XML files (*.xml)"
1646		\endcode
	1646	\endcode
1647	1647
1648		The dialog's caption is set to \a caption. If \a caption is not
1649		specified then a default caption will be used.
	1648	The dialog's caption is set to \a caption. If \a caption is not specified
	1649	then a default caption will be used.
1650	1650
1651		Under Windows and Mac OS X, this static function will use the native
1652		file dialog and not a QFileDialog. On Mac OS X, the \a dir argument
1653		is ignored, the native dialog always displays the last visited directory.
	1651	On Windows and Mac OS X, this static function will use the native file
	1652	dialog and not a QFileDialog.
1654	1653
1655		Note that on Windows the dialog will spin a blocking modal event loop
1656		that will not dispatch any QTimers, and if parent is not 0 then it will
1657		position the dialog just under the parent's title bar.
	1654	On Windows the dialog will spin a blocking modal event loop that will not
	1655	dispatch any QTimers, and if \a parent is not 0 then it will position the
	1656	dialog just below the parent's title bar.
1658	1657
1659		Under Unix/X11, the normal behavior of the file dialog is to resolve
1660		and follow symlinks. For example, if \c{/usr/tmp} is a symlink to
1661		\c{/var/tmp}, the file dialog will change to \c{/var/tmp} after
1662		entering \c{/usr/tmp}. The \a options argument holds various
1663		options about how to run the dialog, see the QFileDialog::Option enum for
1664		more information on the flags you can pass.
	1658	On Unix/X11, the normal behavior of the file dialog is to resolve and
	1659	follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
	1660	the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}.
	1661	The \a options argument holds various options about how to run the dialog,
	1662	see the QFileDialog::Option enum for more information on the flags you can
	1663	pass.
1665	1664
1666		Note that if you want to iterate over the list of files, you should
1667		iterate over a copy. For example:
	1665	\note If you want to iterate over the list of files, you should iterate
	1666	over a copy. For example:
1668	1667
1669	1668	\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 10
1670	1669
1671		\warning Do not delete \a parent during the execution of the dialog.
1672		If you want to do this, you should create the dialog
1673		yourself using one of the QFileDialog constructors.
	1670	\warning Do not delete \a parent during the execution of the dialog. If you
	1671	want to do this, you should create the dialog yourself using one of the
	1672	QFileDialog constructors.
1674	1673
1675		\sa getOpenFileName(), getSaveFileName(), getExistingDirectory()
	1674	\sa getOpenFileName(), getSaveFileName(), getExistingDirectory()
1676	1675	*/
1677	1676	QStringList QFileDialog::getOpenFileNames(QWidget *parent,
1678	1677	const QString &caption,
…	…
1715	1715	}
1716	1716
1717	1717	/*!
1718		This is a convenience static function that will return a file name
1719		selected by the user. The file does not have to exist.
	1718	This is a convenience static function that will return a file name selected
	1719	by the user. The file does not have to exist.
1720	1720
1721		It creates a modal file dialog with the given \a parent widget. If the
1722		parent is not 0, the dialog will be shown centered over the parent
1723		widget.
	1721	It creates a modal file dialog with the given \a parent widget. If
	1722	\a parent is not 0, the dialog will be shown centered over the parent
	1723	widget.
1724	1724
1725		\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 11
	1725	\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 11
1726	1726
1727		The file dialog's working directory will be set to \a dir. If \a
1728		dir includes a file name, the file will be selected. Only files that
1729		match the \a filter are shown. The filter selected is set to
1730		\a selectedFilter. The parameters \a dir, \a selectedFilter, and
1731		\a filter may be empty strings. Multiple filters are separated with ';;'.
1732		For instance:
	1727	The file dialog's working directory will be set to \a dir. If \a dir
	1728	includes a file name, the file will be selected. Only files that match the
	1729	\a filter are shown. The filter selected is set to \a selectedFilter. The
	1730	parameters \a dir, \a selectedFilter, and \a filter may be empty strings.
	1731	Multiple filters are separated with ';;'. For instance:
1733	1732
1734		\code
	1733	\code
1735	1734	"Images (.png .xpm .jpg);;Text files (.txt);;XML files (*.xml)"
1736		\endcode
	1735	\endcode
1737	1736
1738		The \a options argument holds various
1739		options about how to run the dialog, see the QFileDialog::Option enum for
1740		more information on the flags you can pass.
	1737	The \a options argument holds various options about how to run the dialog,
	1738	see the QFileDialog::Option enum for more information on the flags you can
	1739	pass.
1741	1740
1742		The default filter can be chosen by setting \a selectedFilter to the desired value.
	1741	The default filter can be chosen by setting \a selectedFilter to the
	1742	desired value.
1743	1743
1744		The dialog's caption is set to \a caption. If \a caption is not
1745		specified then a default caption will be used.
	1744	The dialog's caption is set to \a caption. If \a caption is not specified,
	1745	a default caption will be used.
1746	1746
1747		Under Windows and Mac OS X, this static function will use the native
1748		file dialog and not a QFileDialog.
	1747	On Windows and Mac OS X, this static function will use the native file
	1748	dialog and not a QFileDialog.
1749	1749
1750		Note that on Windows the dialog will spin a blocking modal event loop
1751		that will not dispatch any QTimers, and if parent is not 0 then it will
1752		position the dialog just under the parent's title bar.
1753		On Mac OS X, the filter argument is ignored.
	1750	On Windows the dialog will spin a blocking modal event loop that will not
	1751	dispatch any QTimers, and if \a parent is not 0 then it will position the
	1752	dialog just below the parent's title bar. On Mac OS X, with its native file
	1753	dialog, the filter argument is ignored.
1754	1754
1755		Under Unix/X11, the normal behavior of the file dialog is to resolve
1756		and follow symlinks. For example, if \c{/usr/tmp} is a symlink to
1757		\c{/var/tmp}, the file dialog will change to \c{/var/tmp} after
1758		entering \c{/usr/tmp}. If \a options includes DontResolveSymlinks,
1759		the file dialog will treat symlinks as regular directories.
	1755	On Unix/X11, the normal behavior of the file dialog is to resolve and
	1756	follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
	1757	the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If
	1758	\a options includes DontResolveSymlinks the file dialog will treat symlinks
	1759	as regular directories.
1760	1760
1761		\warning Do not delete \a parent during the execution of the dialog.
1762		If you want to do this, you should create the dialog
1763		yourself using one of the QFileDialog constructors.
	1761	\warning Do not delete \a parent during the execution of the dialog. If you
	1762	want to do this, you should create the dialog yourself using one of the
	1763	QFileDialog constructors.
1764	1764
1765		\sa getOpenFileName(), getOpenFileNames(), getExistingDirectory()
	1765	\sa getOpenFileName(), getOpenFileNames(), getExistingDirectory()
1766	1766	*/
1767	1767	QString QFileDialog::getSaveFileName(QWidget *parent,
1768	1768	const QString &caption,
…	…
1808	1808	}
1809	1809
1810	1810	/*!
1811		This is a convenience static function that will return an existing
1812		directory selected by the user.
	1811	This is a convenience static function that will return an existing
	1812	directory selected by the user.
1813	1813
1814		\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 12
	1814	\snippet doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp 12
1815	1815
1816		This function creates a modal file dialog with the given \a parent
1817		widget. If the parent is not 0, the dialog will be shown centered over
1818		the parent widget.
	1816	This function creates a modal file dialog with the given \a parent widget.
	1817	If \a parent is not 0, the dialog will be shown centered over the parent
	1818	widget.
1819	1819
1820		The dialog's working directory is set to \a dir, and the caption is
1821		set to \a caption. Either of these may be an empty string in which case
1822		the current directory and a default caption will be used
1823		respectively.
	1820	The dialog's working directory is set to \a dir, and the caption is set to
	1821	\a caption. Either of these may be an empty string in which case the
	1822	current directory and a default caption will be used respectively.
1824	1823
1825		The \a options argument holds various
1826		options about how to run the dialog, see the QFileDialog::Option enum for
1827		more information on the flags you can pass. Note that \l{QFileDialog::}{ShowDirsOnly}
1828		must be set to ensure a native file dialog.
	1824	The \a options argument holds various options about how to run the dialog,
	1825	see the QFileDialog::Option enum for more information on the flags you can
	1826	pass. To ensure a native file dialog, \l{QFileDialog::}{ShowDirsOnly} must
	1827	be set.
1829	1828
1830		Under Windows and Mac OS X, this static function will use the native
1831		file dialog and not a QFileDialog. On Mac OS X, the \a dir argument
1832		is ignored, the native dialog always displays the last visited directory.
1833		On Windows CE, if the device has no native file dialog, a QFileDialog
1834		will be used.
	1829	On Windows and Mac OS X, this static function will use the native file
	1830	dialog and not a QFileDialog. On Windows CE, if the device has no native
	1831	file dialog, a QFileDialog will be used.
1835	1832
1836		Under Unix/X11, the normal behavior of the file dialog is to resolve
1837		and follow symlinks. For example, if \c{/usr/tmp} is a symlink to
1838		\c{/var/tmp}, the file dialog will change to \c{/var/tmp} after
1839		entering \c{/usr/tmp}. If \a options includes DontResolveSymlinks,
1840		the file dialog will treat symlinks as regular directories.
	1833	On Unix/X11, the normal behavior of the file dialog is to resolve and
	1834	follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
	1835	the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If
	1836	\a options includes DontResolveSymlinks, the file dialog will treat
	1837	symlinks as regular directories.
1841	1838
1842		Note that on Windows the dialog will spin a blocking modal event loop
1843		that will not dispatch any QTimers, and if parent is not 0 then it will
1844		position the dialog just under the parent's title bar.
	1839	On Windows the dialog will spin a blocking modal event loop that will not
	1840	dispatch any QTimers, and if \a parent is not 0 then it will position the
	1841	dialog just below the parent's title bar.
1845	1842
1846		\warning Do not delete \a parent during the execution of the dialog.
1847		If you want to do this, you should create the dialog
1848		yourself using one of the QFileDialog constructors.
	1843	\warning Do not delete \a parent during the execution of the dialog. If you
	1844	want to do this, you should create the dialog yourself using one of the
	1845	QFileDialog constructors.
1849	1846
1850		\sa getOpenFileName(), getOpenFileNames(), getSaveFileName()
	1847	\sa getOpenFileName(), getOpenFileNames(), getSaveFileName()
1851	1848	*/
1852	1849	QString QFileDialog::getExistingDirectory(QWidget *parent,
1853	1850	const QString &caption,

Commit e7fdaf47dfdf5e2f6056aa5d5b4644e74a05492a

Gitorious