Queries regarding adding a new 'typewriter' annotation tool to the toolbar

[Tobias Deiminger]

Hi Dileep,

that's quite a lot. I don't have enough continuous time to answer all at 
once, so I just start with the first two questions.
@all: Everybody is very welcome to join discussion and answering:)

Am 18.05.2018 17:04 schrieb Dileep Sankhla:
> I have few things to ask before getting it done and it would be nice
> if you can reply to any of the queries with your own suggestions.
> 
> 1. In tree/ui/data/tools.xml, we have decided to append new
> "typewriter" annotation tool at <tool id="10"> without muddling
> others. Now should I give <shortcut>0</shortcut> to this tool or
> should I ommit the <shortcut> tag completely for this one?
> Giving shortcut 0 makes sense as 0 is the key next to 9 on the
> keyboard but having shortcut 0 for the tool at the lowest end in the
> annotation toolbar doesn't make sense.

Imho either 0 or none would both make sense. Users can configure the 
toolbar and shortcuts themselves anyway.

> 2. My mentor remarked that tools.xml doesn't solely determine the
> order in the toolbar. It is just the initial default, but the
> "okularpartrc" file, if present, takes precedence.
> It is located at ~/.config/okularpartrc on my system containing the
> content similar to tools.xml. I need to know when it is being created
> and read by okular and how do I append typewriter tool entry in it for
> every system installing okular? I have no idea.

When toolbar accesses Okular::Settings::annotationTools, values are 
already in memory. But you'll ask, how and when have they come there?

class Okular::Settings is defined in <cmake-project-dir>/settings.cpp. 
You must know that settings.{cpp,h} is autogenerated during project 
build by kconfig_compiler_kf5 out of conf/okular.kcfg. Please read [0] 
to learn about this. The responsible macro is in okular/CMakeLists.txt 
kconfig_add_kcfg_files(okularpart_SRCS conf/settings.kcfgc).

Data for Okular::Settings is initialized once in 
Okular::Settings::Settings Ctor. There the file tools.xml is read, as 
coded into the <entry key="AnnotationTools" 
type="StringList"><code>...</code></entry> element from okular.kcfg.

Data for Okular::Settings is also loaded and saved via a KSharedConfig 
config object. KSharedConfig derives from KConfig, and 
KConfig::reparseConfiguration [1] loads data from 
~/.config/okularpartrc.

Sadly there are several KSharedConfig instances in Okular, so if we want 
to watch it in gdb, we have to figure out during runtime which 
KSharedConfig is responsible for ~/.config/okularpartrc.

Be sure to have libKF5ConfigCore debug symbols around (on Ubuntu: 
apt-get install libkf5configcore5-dbgsym).

$ gdb okular

(gdb) set breakpoint pending on
(gdb) break Okular::Settings::Settings

Next set a specific breakpoint to filter for the interesting 
KSharedConfig object. We know that if KSharedConfig Ctor is called 
inside Okular::Settings::instance, it is the one responsible for 
~/.config/okularpartrc. So break only in this condition.

(gdb) break Okular::Settings::instance
command 1
   tb KSharedConfig::KSharedConfig
   c
end

Run the program.

(gdb) r

When hit, we know the KSharedConfig object of interest.
#0  KSharedConfig::KSharedConfig (this=0x55555588f310, fileName=..., 
flags=..., resType=QStandardPaths::GenericConfigLocation)
     at ./src/core/ksharedconfig.cpp:124

It is at 0x55555588f310. Now we can set another conditional breakpoint 
to catch the KConfig::reparseConfiguration calls of interest.

(gdb) break KConfig::reparseConfiguration if this=0x55555588f310

That's it.
Everytime you hit Okular::Settings::Settings, Okular reads from 
tools.xml.
Everytime you hit this KConfig::reparseConfiguration, Okular reads from 
~/.config/okularpartrc.

Can you share your observations?

To gain even more convidence in your debugging it's sometimes good to 
observe the value of QStrings. KDE provides nice tools for this:

$ git clone git://anongit.kde.org/kde-dev-scripts.git
$ cp kde-dev-scripts/kde-devel-gdb ~/.gdbinit
$ gdb okular

Break somewhere. Now you can use the printq5string function to print the 
content of a QString:

Thread 1 "okular" hit Breakpoint 2, Okular::Settings::instance 
(cfgfilename=...) at ./obj-x86_64-linux-gnu/settings.cpp:189
189     ./obj-x86_64-linux-gnu/settings.cpp: Datei oder Verzeichnis 
nicht gefunden.

(gdb) printq5string cfgfilename
/home/tobias/.config/okularpartrc

Cheers
Tobias

[0] https://api.kde.org/frameworks/kconfig/html/kconfig_compiler.html
[1] 
https://api.kde.org/frameworks/kconfig/html/classKConfig.html#a46f2e340c44261c2b58496bc64b31106