summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKavindra Devi Palaraja <kavindra.palaraja@nokia.com>2009-05-12 16:18:29 (GMT)
committerKavindra Devi Palaraja <kavindra.palaraja@nokia.com>2009-05-12 16:20:48 (GMT)
commitefad5df3ee7dea6cb587aacd27010e15a69f4320 (patch)
tree6a640857cca06a9542e2c90ea1eec4110bfaaebe
parent8a4934d8b97b55b80b2709dba04346e068251906 (diff)
downloadQt-efad5df3ee7dea6cb587aacd27010e15a69f4320.zip
Qt-efad5df3ee7dea6cb587aacd27010e15a69f4320.tar.gz
Qt-efad5df3ee7dea6cb587aacd27010e15a69f4320.tar.bz2
Doc - cleaning up the documentation of QUiLoader.
Also mentioned an important point: If you subclass QUiLoader and reimplement either createAction(), createActionGroup(), createLayout(), or createWidget() -- you must call the original implementation first, within your implementation. Reviewed-by: João Abecasis <joao@abecasis.name>
-rw-r--r--tools/designer/src/uitools/quiloader.cpp194
1 files changed, 105 insertions, 89 deletions
diff --git a/tools/designer/src/uitools/quiloader.cpp b/tools/designer/src/uitools/quiloader.cpp
index 67bd29c..106e641 100644
--- a/tools/designer/src/uitools/quiloader.cpp
+++ b/tools/designer/src/uitools/quiloader.cpp
@@ -572,53 +572,52 @@ void QUiLoaderPrivate::setupWidgetMap() const
\class QUiLoader
\inmodule QtUiTools
- \brief The QUiLoader class allows standalone applications dynamically
- create user interfaces at run-time using the information stored in
- .ui files or specified plugin paths.
+ \brief enables standalone applications to dynamically create user
+ interfaces at run-time using the information stored in .ui files or
+ specified in plugin paths.
- In addition, you can customize of creating an user interface by
+ In addition, you can customize or create your own user interface by
deriving your own loader class.
- If you have a custom component or an application that embeds Qt
- Designer, you can also use the QFormBuilder class provided by the
- QtDesigner module to create user interfaces from .ui files.
+ If you have a custom component or an application that embeds \QD, you can
+ also use the QFormBuilder class provided by the QtDesigner module to create
+ user interfaces from \c{.ui} files.
- The QUiLoader class provides a collection of functions that allows
- you to create widgets based on the information stored in \c .ui
- files (created with Qt Designer) or available in the specified
- plugin paths. The specified plugin paths can be retrieved using
- the pluginPaths() function. You can retrieve the contents of an \c
- .ui file using the load() function. For example:
+ The QUiLoader class provides a collection of functions allowing you to
+ create widgets based on the information stored in \c .ui files (created
+ with \QD) or available in the specified plugin paths. The specified plugin
+ paths can be retrieved using the pluginPaths() function. Similarly, the
+ contents of a \c{.ui} file can be retrieved using the load() function. For
+ example:
\snippet doc/src/snippets/quiloader/mywidget.cpp 0
- By including the user interface in the form's resources (\c myform.qrc),
- we ensure that it will be present at run-time:
+ By including the user interface in the form's resources (\c myform.qrc), we
+ ensure that it will be present at run-time:
\quotefile doc/src/snippets/quiloader/mywidget.qrc
- The availableWidgets() function returns a QStringList with the
- class names of the widgets available in the specified plugin
- paths. You can create any of these widgets using the
- createWidget() function. For example:
+ The availableWidgets() function returns a QStringList with the class names
+ of the widgets available in the specified plugin paths. To create these
+ widgets, simply use the createWidget() function. For example:
\snippet doc/src/snippets/quiloader/main.cpp 0
- You can make a custom widget available to the loader using the
- addPluginPath() function, and you can remove all the available widgets
- by calling the clearPluginPaths() function.
+ To make a custom widget available to the loader, you can use the
+ addPluginPath() function; to remove all available widgets, you can call
+ the clearPluginPaths() function.
- The createAction(), createActionGroup(), createLayout() and
- createWidget() functions are used internally by the QUiLoader class
- whenever it has to create an action, action group, layout or
- widget respectively. For that reason, you can subclass the QUiLoader
- class and reimplement these functions to intervene the process of
- constructing an user interface. For example, you might want to
- create a list of the actions created when loading a form or
- creating a custom widget.
+ The createAction(), createActionGroup(), createLayout(), and createWidget()
+ functions are used internally by the QUiLoader class whenever it has to
+ create an action, action group, layout, or widget respectively. For that
+ reason, you can subclass the QUiLoader class and reimplement these
+ functions to intervene the process of constructing a user interface. For
+ example, you might want to have a list of the actions created when loading
+ a form or creating a custom widget. However, in your reimplementation, you
+ must call QUiLoader's original implementation of these functions first.
- For a complete example using the QUiLoader class, see the \l
- {designer/calculatorbuilder}{Calculator Builder} example.
+ For a complete example using the QUiLoader class, see the
+ \l{Calculator Builder Example}.
\sa QtUiTools, QFormBuilder
*/
@@ -653,8 +652,8 @@ QUiLoader::~QUiLoader()
}
/*!
- Loads a form from the given \a device and creates a new widget with the given
- \a parentWidget to hold its contents.
+ Loads a form from the given \a device and creates a new widget with the
+ given \a parentWidget to hold its contents.
\sa createWidget()
*/
@@ -668,8 +667,8 @@ QWidget *QUiLoader::load(QIODevice *device, QWidget *parentWidget)
}
/*!
- Returns a list naming the paths the loader searches when locating
- custom widget plugins.
+ Returns a list naming the paths in which the loader will search when
+ locating custom widget plugins.
\sa addPluginPath(), clearPluginPaths()
*/
@@ -680,7 +679,7 @@ QStringList QUiLoader::pluginPaths() const
}
/*!
- Clears the list of paths the loader searches when locating
+ Clears the list of paths in which the loader will search when locating
plugins.
\sa addPluginPath(), pluginPaths()
@@ -692,7 +691,7 @@ void QUiLoader::clearPluginPaths()
}
/*!
- Adds the given \a path to the list of paths the loader searches
+ Adds the given \a path to the list of paths in which the loader will search
when locating plugins.
\sa pluginPaths(), clearPluginPaths()
@@ -704,17 +703,17 @@ void QUiLoader::addPluginPath(const QString &path)
}
/*!
- Creates a new widget with the given \a parent and \a name
- using the class specified by \a className. You can use this
- function to create any of the widgets returned by the
- availableWidgets() function.
+ Creates a new widget with the given \a parent and \a name using the class
+ specified by \a className. You can use this function to create any of the
+ widgets returned by the availableWidgets() function.
- The function is also used internally by the QUiLoader class whenever
- it has to create a widget. For that reason, you can subclass the
- QUiLoader class and reimplement this function to intervene in the
- process of constructing a user interface or widget.
+ The function is also used internally by the QUiLoader class whenever it
+ creates a widget. Hence, you can subclass QUiLoader and reimplement this
+ function to intervene process of constructing a user interface or widget.
+ However, in your implementation, ensure that you call QUiLoader's version
+ first.
- \sa availableWidgets(), load()
+ \sa availableWidgets(), load()
*/
QWidget *QUiLoader::createWidget(const QString &className, QWidget *parent, const QString &name)
{
@@ -723,13 +722,14 @@ QWidget *QUiLoader::createWidget(const QString &className, QWidget *parent, cons
}
/*!
- Creates a new layout with the given \a parent and \a name
- using the class specified by \a className.
+ Creates a new layout with the given \a parent and \a name using the class
+ specified by \a className.
- The function is used internally by the QUiLoader class whenever it
- has to create a layout. For that reason, you can subclass the
- QUiLoader class and reimplement this function to intervene the
- process of constructing an user interface or widget.
+ The function is also used internally by the QUiLoader class whenever it
+ creates a widget. Hence, you can subclass QUiLoader and reimplement this
+ function to intervene process of constructing a user interface or widget.
+ However, in your implementation, ensure that you call QUiLoader's version
+ first.
\sa createWidget(), load()
*/
@@ -742,10 +742,11 @@ QLayout *QUiLoader::createLayout(const QString &className, QObject *parent, cons
/*!
Creates a new action group with the given \a parent and \a name.
- The function is used internally by the QUiLoader class whenever it
- has to create an action group. For that reason, you can subclass
- the QUiLoader class and reimplement this function to intervene the
- process of constructing an user interface or widget.
+ The function is also used internally by the QUiLoader class whenever it
+ creates a widget. Hence, you can subclass QUiLoader and reimplement this
+ function to intervene process of constructing a user interface or widget.
+ However, in your implementation, ensure that you call QUiLoader's version
+ first.
\sa createAction(), createWidget(), load()
*/
@@ -758,10 +759,11 @@ QActionGroup *QUiLoader::createActionGroup(QObject *parent, const QString &name)
/*!
Creates a new action with the given \a parent and \a name.
- The function is used internally by the QUiLoader class whenever it
- has to create an action. For that reason, you can subclass the
- QUiLoader class and reimplement this function to intervene the
- process of constructing an user interface or widget.
+ The function is also used internally by the QUiLoader class whenever it
+ creates a widget. Hence, you can subclass QUiLoader and reimplement this
+ function to intervene process of constructing a user interface or widget.
+ However, in your implementation, ensure that you call QUiLoader's version
+ first.
\sa createActionGroup(), createWidget(), load()
*/
@@ -772,9 +774,9 @@ QAction *QUiLoader::createAction(QObject *parent, const QString &name)
}
/*!
- Returns a list naming the available widgets that can be built
- using the createWidget() function, i.e all the widgets specified
- within the given plugin paths.
+ Returns a list naming all available widgets that can be built using the
+ createWidget() function, i.e all the widgets specified within the given
+ plugin paths.
\sa pluginPaths(), createWidget()
@@ -795,11 +797,11 @@ QStringList QUiLoader::availableWidgets() const
/*!
- Returns a list naming the available layouts that can be built
- using the createLayout() function
+ \since 4.5
+ Returns a list naming all available layouts that can be built using the
+ createLayout() function
\sa createLayout()
- \since 4.5
*/
QStringList QUiLoader::availableLayouts() const
@@ -816,9 +818,9 @@ QStringList QUiLoader::availableLayouts() const
}
/*!
- Sets the working directory of the loader to \a dir. The loader
- looks for other resources, such as icons and resource files,
- in paths relative to this directory.
+ Sets the working directory of the loader to \a dir. The loader will look
+ for other resources, such as icons and resource files, in paths relative to
+ this directory.
\sa workingDirectory()
*/
@@ -842,9 +844,13 @@ QDir QUiLoader::workingDirectory() const
}
/*!
- Sets whether the execution of scripts is enabled to \a enabled.
- \since 4.3
\internal
+ \since 4.3
+
+ If \a enabled is true, the loader will be able to execute scripts.
+ Otherwise, execution of scripts will be disabled.
+
+ \sa isScriptingEnabled()
*/
void QUiLoader::setScriptingEnabled(bool enabled)
@@ -854,10 +860,12 @@ void QUiLoader::setScriptingEnabled(bool enabled)
}
/*!
- Returns whether the execution of scripts is enabled.
- \sa setScriptingEnabled()
- \since 4.3
- \internal
+ \internal
+ \since 4.3
+
+ Returns true if execution of scripts is enabled; returns false otherwise.
+
+ \sa setScriptingEnabled()
*/
bool QUiLoader::isScriptingEnabled() const
@@ -867,11 +875,13 @@ bool QUiLoader::isScriptingEnabled() const
}
/*!
- Sets whether user interfaces loaded by this loader automatically
- retranslate themselves upon receiving a language change event or not,
- depending on \a enabled.
-
\since 4.5
+
+ If \a enabled is true, user interfaces loaded by this loader will
+ automatically retranslate themselves upon receiving a language change
+ event. Otherwise, the user interfaces will not be retranslated.
+
+ \sa isLanguageChangeEnabled()
*/
void QUiLoader::setLanguageChangeEnabled(bool enabled)
@@ -881,9 +891,12 @@ void QUiLoader::setLanguageChangeEnabled(bool enabled)
}
/*!
- Returns whether dynamic retranslation on language change is enabled.
- \sa setLanguageChangeEnabled()
- \since 4.5
+ \since 4.5
+
+ Returns true if dynamic retranslation on language change is enabled;
+ returns false otherwise.
+
+ \sa setLanguageChangeEnabled()
*/
bool QUiLoader::isLanguageChangeEnabled() const
@@ -894,11 +907,14 @@ bool QUiLoader::isLanguageChangeEnabled() const
/*!
\internal
+ \since 4.5
+
+ If \a enabled is true, user interfaces loaded by this loader will be
+ translated. Otherwise, the user interfaces will not be translated.
- Sets whether user interfaces loaded by this loader are translated
- at all. Note that this is orthogonal to languageChangeEnabled.
+ \note This is orthogonal to languageChangeEnabled.
- \since 4.5
+ \sa isLanguageChangeEnabled(), setLanguageChangeEnabled()
*/
void QUiLoader::setTranslationEnabled(bool enabled)
@@ -909,11 +925,11 @@ void QUiLoader::setTranslationEnabled(bool enabled)
/*!
\internal
+ \since 4.5
- Returns whether translation is enabled.
- \sa setTranslationEnabled()
+ Returns true if translation is enabled; returns false otherwise.
- \since 4.5
+ \sa setTranslationEnabled()
*/
bool QUiLoader::isTranslationEnabled() const