amarok/HACKING/kconfig_guidelines.txt

0001 Usage of Amarok::config()
0002 -------------------------
0003 We provide this method for convenience, but it is important to use it properly. By
0004 inspection, we can see that we may produce very obscure bugs in the wrong case:
0005
0006  | KConfig
0007  | *config( const QString &group )
0008  | {
0009  |    //Slightly more useful config() that allows setting the group simultaneously
0010  |    KGlobal::config()->setGroup( group );
0011  |    return KGlobal::config();
0012  | }
0013
0014 Take the following example:
0015
0016  | void
0017  | f1()
0018  | {
0019  |    KConfig *config = Amarok::config( "Group 2" );
0020  |    config->writeEntry( "Group 2 Variable", true );
0021  | }
0022  |
0023  | void
0024  | doStuff()
0025  | {
0026  |   KConfig *config = Amarok::config( "Group 1" );
0027  |   f1();
0028  |   config->writeEntry( "Group 1 Variable", true );
0029  | }
0030
0031 We would expect the following results:
0032
0033  | [Group 1]
0034  | Group 1 Variable = true
0035  |
0036  | [Group 2]
0037  | Group 2 Variable = true
0038
0039 However because the config group is changed before writing the entry:
0040  | [Group 1]
0041  |
0042  | [Group 2]
0043  | Group 1 Variable = true
0044  | Group 2 Variable = true
0045
0046 Which is clearly incorrect. And hard to see when your wondering why f1() is not
0047 working. So do not store a value of Amarok::config, make it a habit to just
0048 always call writeEntry or readEntry directly.
0049
0050 Correct:
0051  | amarok::config( "Group 1" )->writeEntry( "Group 1 Variable", true );