|
KTutorial
0.5.1
|
Main class of KTutorial. More...
#include <KTutorial.h>
Public Member Functions | |
| virtual | ~KTutorial () |
| Destroys this KTutorial. | |
| bool | registerWaitForMetaObject (const QMetaObject &waitForMetaObject, const QString &typeName=QString()) |
| Registers a WaitFor type to create instances of it in scripted tutorials. | |
| void | setup (KXmlGuiWindow *window) |
| Sets up everything for KTutorial to work with the default customization. | |
| void | setup (KTutorialCustomization *ktutorialCustomization) |
| Sets up everything for KTutorial to work with the given customization. | |
| bool | registerTutorial (Tutorial *tutorial) |
| Registers the Tutorial. | |
| QWidget * | mainApplicationWindow () const |
| Returns the main window of the application. | |
| template<typename T > | |
| T | findObject (const QString &name) const |
| Returns the object with the specified name, if any. | |
Static Public Member Functions | |
| static KTutorial * | self () |
| Returns the only instance of this class. | |
Main class of KTutorial.
This class is used to setup KTutorial, register WaitFor classes to be created from scripts, register new Tutorials embedded in the application and find objects in the Tutorials. It uses a Singleton design pattern.
When using KTutorial and no customization is needed, KTutorial::setup(KxmlGuiWindow*) must be called to set up everything needed for KTutorial to work. It needs to know the main window of the application.
If a KTutorial customization is needed, KTutorial::setup(KTutorialCustomization*) must be called instead providing the desired customization.
The setup method will be the first one to be called, but when custom WaitFor objects are used in scripts. In that case, all the needed WaitFor classes must be registered using registerWaitForMetaObject(const QMetaObject&) before calling setup(KXmlGuiWindow*), as that method creates and registers all the valid scripted tutorials.
Once KTutorial is set up, Tutorials embedded in the application can be added. Just use KTutorial::registerTutorial(Tutorial*) so it is registered in the system. Only registered tutorial are seen by the user.
Note, however, that when a customization is used, the WaitFor classes and the tutorials embedded in the application can be registered during the customization setup itself.
When no customization is used, the TutorialManagerDialog is shown as modal through the "tutorials" action in the "Help" menu. This action will be automatically disabled whenever a tutorial is being executed.
Finally, no matter whether a customization is used or not, any of the children objects of the main window of the application (which will usually be at least all widgets) can be got with KTutorial::findObject(const QString&), provided the looked for object has its object name set.
Definition at line 77 of file KTutorial.h.
| T ktutorial::KTutorial::findObject | ( | const QString & | name | ) | const [inline] |
Returns the object with the specified name, if any.
Objects are searched in the children of the main window of the application.
When the name of the desired object is not unique the name of some ancestor must be included. Ancestor names are separated using a "/". That is, "Ancestor name/The object with a repeated name". As many ancestor names as desired can be included, not just one. The name of the ancestors does not need to be unique either; what has to be unique is the full path to the object to find. For example, "Ancestor name not unique/The object to find" is valid if, among all the objects called "Ancestor name not unique", there is only one that has a descendant called "The object to find".
In some cases it may be possible that a unique name can not be provided, even using ancestor names. In those cases there are some rules to resolve the ambiguity. Between two or more objects with the same name, the selected one is: -A direct child of the base object. -A nested child without named ancestors between it and the base object. -If there is more than one, the one nearer to the base object (that is, with the lesser number of intermediate ancestors). -A nested child with named or unnamed ancestors between it and the base object. -If there is more than one, the one nearer to the base object (that is, with the lesser number of intermediate ancestors).
If the ambiguous name contains ancestor names the rules are applied for each component of the name. Each component is searched for only from the already selected previous components. That is, if the ambiguous name is "Ancestor name/The object", the rules are applied to find the objects named "Ancestor name" using the main window as base object. Then, the rules are applied to find "The object" using the "Ancestor name" objects as base, so "The object" is searched only in the children of the "Ancestor name" objects previously found. Note that, even with the ambiguity resolving rules, it may be searched for from several "Ancestor name" if, for example, there are several "Ancestor name" child of the main window. However, if there were other "Ancestor name" objects that were not direct children of the main window they will not be used in the search, as the direct children would have taken precedence.
If after applying the rules there is still more than one object that matches, the first one is selected.
| name | The name of the object to find. |
Definition at line 198 of file KTutorial.h.
Referenced by ktutorial::UsingKTutorial::tearDown().
| QWidget * ktutorial::KTutorial::mainApplicationWindow | ( | ) | const |
Returns the main window of the application.
Definition at line 95 of file KTutorial.cpp.
References ktutorial::KTutorialCustomization::mainApplicationWindow(), and ktutorial::KTutorialPrivate::mCustomization.
Referenced by setup().
| bool ktutorial::KTutorial::registerTutorial | ( | Tutorial * | tutorial | ) |
Registers the Tutorial.
Only Tutorials with a identifier not added yet can be added. If the Tutorial couldn't be added, false is returned.
The Tutorial is reparented and thus deleted when needed.
| tutorial | The Tutorial to register. |
Definition at line 91 of file KTutorial.cpp.
References ktutorial::KTutorialPrivate::mTutorialmanager, and ktutorial::TutorialManager::registerTutorial().
| bool ktutorial::KTutorial::registerWaitForMetaObject | ( | const QMetaObject & | waitForMetaObject, |
| const QString & | typeName = QString() |
||
| ) |
Registers a WaitFor type to create instances of it in scripted tutorials.
Any WaitFor class has to be registered before calling setup(KXmlGuiWindow*).
| waitForMetaObject | The QMetaObject to create instances of. |
| typeName | A specific name to be used for the QMetaObject. |
Definition at line 61 of file KTutorial.cpp.
References registerWaitForMetaObject(), and self().
Referenced by registerWaitForMetaObject().
| KTutorial * ktutorial::KTutorial::self | ( | ) | [static] |
Returns the only instance of this class.
Definition at line 53 of file KTutorial.cpp.
Referenced by registerWaitForMetaObject(), ktutorial::UsingKTutorial::tearDown(), and ktutorial::WaitForWindow::WaitForWindow().
| void ktutorial::KTutorial::setup | ( | KXmlGuiWindow * | window | ) |
Sets up everything for KTutorial to work with the default customization.
If no customization is needed, this is usually the first method that must be called when using KTutorial in an application. However, if any WaitFor class has to be registered, it must be done before calling this method.
It adds the Tutorials action and the menu entry for it in Help menu and loads the scripted tutorials from the application standard directories.
| window | The main window of the application. |
Definition at line 67 of file KTutorial.cpp.
| void ktutorial::KTutorial::setup | ( | KTutorialCustomization * | ktutorialCustomization | ) |
Sets up everything for KTutorial to work with the given customization.
After setting up the customization, it loads the scripted tutorials from the application standard directories.
| ktutorialCustomization | The customization to use. |
Definition at line 73 of file KTutorial.cpp.
References ktutorial::scripting::ScriptManager::loadTutorials(), mainApplicationWindow(), ktutorial::KTutorialPrivate::mCustomization, ktutorial::KTutorialPrivate::mObjectFinder, ktutorial::KTutorialPrivate::mTutorialmanager, ktutorial::editorsupport::EditorSupport::setObjectFinder(), ktutorial::KTutorialCustomization::setup(), and ktutorial::editorsupport::EditorSupport::setup().
1.8.0