Projects/Games/Porting to libkdegames v5: Difference between revisions
(completed porting guide for KGameDifficulty -> KgDifficulty) |
|||
| Line 5: | Line 5: | ||
* '''KgSound''' provides a simple API for playback of short event sounds. Low latency is achieved through the use of OpenAL, with a Phonon fallback if the required libraries are not available. | * '''KgSound''' provides a simple API for playback of short event sounds. Low latency is achieved through the use of OpenAL, with a Phonon fallback if the required libraries are not available. | ||
Also, multiple new components have been added which replace existing components. These can be identified by the common class name prefix "Kg". See [[#Reworked components|]] for details. | Also, multiple new components have been added which replace existing components. These can be identified by the common class name prefix "Kg". See [[#Reworked components|Reworked components]] for details. | ||
== Removed components == | == Removed components == | ||
| Line 20: | Line 20: | ||
=== Difficulty === | === Difficulty === | ||
'''KGameDifficulty''' has been replaced by the '''KgDifficulty''' and '''KgDifficultyLevel''' classes. KgDifficulty stores the current level by itself, and allows for multiple KgDifficulty instances at the same time, although a singleton is provided by the Kg::difficulty() function. The following table shows how to port KGameDifficulty | '''KGameDifficulty''' has been replaced by the '''KgDifficulty''' and '''KgDifficultyLevel''' classes. KgDifficulty stores the current level by itself, and allows for multiple KgDifficulty instances at the same time, although a singleton is provided by the Kg::difficulty() function. The following table shows how to port common uses of KGameDifficulty to this singleton: | ||
{| border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width:100%;" | {| border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width:100%;" | ||
| Line 27: | Line 27: | ||
! ...by this | ! ...by this | ||
! Comment | ! Comment | ||
|- | |- style="border:gray solid 1px; border-collapse: collapse;" | ||
| style="white-space:nowrap" | <tt>KGameDifficulty::standardLevel</tt> | | style="white-space:nowrap" | <tt>KGameDifficulty::standardLevel</tt> | ||
| style="white-space:nowrap" | <tt>KgDifficultyLevel::StandardLevel</tt> | | style="white-space:nowrap" | <tt>KgDifficultyLevel::StandardLevel</tt> | ||
| | | | ||
|- | |- style="border:gray solid 1px; border-collapse: collapse;" | ||
| style="white-space:nowrap" | <tt>KGameDifficulty::Medium etc.</tt> | | style="white-space:nowrap" | <tt>KGameDifficulty::Medium etc.</tt> | ||
| style="white-space:nowrap" | <tt>KgDifficultyLevel::Medium etc.</tt> | | style="white-space:nowrap" | <tt>KgDifficultyLevel::Medium etc.</tt> | ||
| | | | ||
|- | |- style="border:gray solid 1px; border-collapse: collapse;" | ||
| style="white-space:nowrap" | <tt>KGameDifficulty::addStandardLevel</tt> | | style="white-space:nowrap" | <tt>KGameDifficulty::addStandardLevel(level)</tt> | ||
| style="white-space:nowrap" | <tt>Kg::difficulty()->addStandardLevel</tt> | | style="white-space:nowrap" | <tt>Kg::difficulty()->addStandardLevel(level)</tt> | ||
| As a convenience, consider to use the new <tt>addStandardLevelRange</tt> method. | | As a convenience, consider to use the new <tt>addStandardLevelRange()</tt> method. | ||
|- style="border:gray solid 1px; border-collapse: collapse;" | |||
| rowspan="2" style="white-space:nowrap" | <tt>KGameDifficulty::init<br/>(window, receiver, slot)</tt> | |||
| style="white-space:nowrap" | <tt>KgDifficultyGUI::init(window);</tt> | |||
| | |||
|- style="border:gray solid 1px; border-collapse: collapse;" | |||
| style="white-space:nowrap" | <tt>QObject::connect(Kg::difficulty(),<br/>SLOT(currentLevelChanged(const KgDifficultyLevel*)),<br/>receiver, slot);</tt> | |||
| Change the slot to the new signature. The old signature contained a standard level argument: Use the "standardLevel" property of the new argument instead. | |||
|- style="border:gray solid 1px; border-collapse: collapse;" | |||
| style="white-space:nowrap" | <tt>KGameDifficulty::level()</tt> | |||
| style="white-space:nowrap" | <tt>Kg::difficultyLevel()</tt> | |||
| | |||
|- style="border:gray solid 1px; border-collapse: collapse;" | |||
| style="white-space:nowrap" | <tt>KGameDifficulty::setLevel(level)</tt> | |||
| style="white-space:nowrap" | <tt>Kg::difficulty()->select(level)</tt> | |||
| If used to restore the selected difficulty from the config file, delete the whole call and your custom config key. KgDifficulty remembers the level selection by itself. Please refer to the APIDOX for details, e.g. how to specify a default difficulty for the first run. | |||
|- style="border:gray solid 1px; border-collapse: collapse;" | |||
| style="white-space:nowrap" | <tt>KGameDifficulty::levelWeights(),<br />KGameDifficulty::localizedLevelStrings(),</tt><br/>etc. while setting up a KScoreDialog | |||
| style="white-space:nowrap" | <tt>dialog->initFromDifficulty(Kg::difficulty());</tt> | |||
| If you need the QMaps from these KGameDifficulty functions, you can construct them by iterating over the <tt>KgDifficultyLevel</tt>s. <tt>levelWeights</tt> maps <tt>hardness->key</tt> and <tt>localizedLevelStrings</tt> maps <tt>key->title</tt>. | |||
|- style="border:gray solid 1px; border-collapse: collapse;" | |||
| style="white-space:nowrap" | <tt>KGameDifficulty::setRestartOnChange(roc)</tt> | |||
| rowspan="2" style="white-space:nowrap" | <tt>Kg::difficulty()->setGameRunning(roc && running)</tt> | |||
| rowspan="2" | These two properties of KGameDifficulty are redundant: If both are true, the user will be asked for confirmation before the level is changed. If you do not want this, just do not use the <tt>setGameRunning</tt> method. | |||
|- style="border:gray solid 1px; border-collapse: collapse;" | |||
| style="white-space:nowrap" | <tt>KGameDifficulty::setRunning(running)</tt> | |||
|} | |} | ||
TODO: finish table, commit the functions in namespace Kg | TODO: finish table, commit the functions in namespace Kg | ||
Revision as of 19:55, 7 March 2012
This document describes the changes introduced with libkdegames v5, which first appeared in the KDE 4.9 release.
New components
- KgSound provides a simple API for playback of short event sounds. Low latency is achieved through the use of OpenAL, with a Phonon fallback if the required libraries are not available.
Also, multiple new components have been added which replace existing components. These can be identified by the common class name prefix "Kg". See Reworked components for details.
Removed components
- The KGGZ framework has been removed completely.
- KGameLCD — Use QLCDNumber instead.
- KGameMisc — Instead of a random name, we advise to use generic names where appropriate.
- KGameProgress — Use QProgressBar instead.
- KGameSvgDigits — If you need SVG digits, include them in your own SVG theme.
- KGrid2D — You'll need to do the math yourself.
Reworked components
Difficulty
KGameDifficulty has been replaced by the KgDifficulty and KgDifficultyLevel classes. KgDifficulty stores the current level by itself, and allows for multiple KgDifficulty instances at the same time, although a singleton is provided by the Kg::difficulty() function. The following table shows how to port common uses of KGameDifficulty to this singleton:
| Replace this... | ...by this | Comment |
|---|---|---|
| KGameDifficulty::standardLevel | KgDifficultyLevel::StandardLevel | |
| KGameDifficulty::Medium etc. | KgDifficultyLevel::Medium etc. | |
| KGameDifficulty::addStandardLevel(level) | Kg::difficulty()->addStandardLevel(level) | As a convenience, consider to use the new addStandardLevelRange() method. |
| KGameDifficulty::init (window, receiver, slot) |
KgDifficultyGUI::init(window); | |
| QObject::connect(Kg::difficulty(), SLOT(currentLevelChanged(const KgDifficultyLevel*)), receiver, slot); |
Change the slot to the new signature. The old signature contained a standard level argument: Use the "standardLevel" property of the new argument instead. | |
| KGameDifficulty::level() | Kg::difficultyLevel() | |
| KGameDifficulty::setLevel(level) | Kg::difficulty()->select(level) | If used to restore the selected difficulty from the config file, delete the whole call and your custom config key. KgDifficulty remembers the level selection by itself. Please refer to the APIDOX for details, e.g. how to specify a default difficulty for the first run. |
| KGameDifficulty::levelWeights(), KGameDifficulty::localizedLevelStrings(), etc. while setting up a KScoreDialog |
dialog->initFromDifficulty(Kg::difficulty()); | If you need the QMaps from these KGameDifficulty functions, you can construct them by iterating over the KgDifficultyLevels. levelWeights maps hardness->key and localizedLevelStrings maps key->title. |
| KGameDifficulty::setRestartOnChange(roc) | Kg::difficulty()->setGameRunning(roc && running) | These two properties of KGameDifficulty are redundant: If both are true, the user will be asked for confirmation before the level is changed. If you do not want this, just do not use the setGameRunning method. |
| KGameDifficulty::setRunning(running) |
TODO: finish table, commit the functions in namespace Kg