KDevelop4 API questions

Hi,

 We've been starting/continuing to work on integrating
Quanta with 
KDevelop4 and while we've been looking to the new API some
questions 
have been arisen. I would like to ask for comments and help
for anybody 
knowing this classes.

1. KDevProjectController
There are methods called
projectsDirectory/setProjectsDirectory and 
projectDirectory. This is dangerous, as one might easily
make a mistake 
by putting or not putting that "s" there. Aside
of that it is not clear 
the meaning and the difference of the above two. What are
the 
"projects" method for? The assumption is that
the project file can be 
at a different place than the project content and the
"projects" method 
are for the content itself. Is this true? BTW, we didn't
really saw an 
example of their usage, only something in the konsole plugin
which is 
also a strange code.
If anyway there is a need for both, we suggest to rename the

projectDirectory to "globalFileDirectory" as
actually it refers to the 
place where the globalFile (project file) is. Or something
like that.

KDevProjectController::openProject: the open dialog has
hardcoded 
information about KDevelop4 project files. This one should
be 
configurable in some way. Ideas are welcome.

2. KDevProject

This one also has a projectDirectory() thing. What is the
difference 
between this and the above? Does it point to the same 
"globalFileDirectory" or should point to the
directory where the 
project content is? In any case, why is it here as well and
in the 
controller? I'd suggest to keep it only here.

inProject method in KDevProject: the implementation is
completely wrong 
and we have no idea why it is implemented here at all.
KDevProject has 
pure virtual methods, so this should be pure virtual as well
and the 
implementation removed from the lib.

absoluteUrl: in the implementation there is a call to KUrl
with the 
KUrl(KUrl, QString) constructor to combine an absolute url
with a 
relative path. The problem is that the docs for KUrl clearly
say that 
one should not use a *path* for the second argument, but an
encoded 
string. And here a path is used, so this looks wrong to me
and possibly 
will fail in some cases.

3. KDevFileManager

As we understood in order to open a project, add/remove
files to the 
project there is a need to implement a KDevFileManager
class. What we 
like to know is how did you imagine handling of files that
were added 
to a project. The addFile returns a pointer to a
KDevProjectFileItem. 
When a file is removed/renamed do you expect that this very
same 
pointer is passed to remove/renameFile method? Or one could
just create 
a new KDevProjectFileItem pointing to the same URL and pass
this to 
removeFile? I understand that this is up to our FileManager
class, but 
I think there is a need to have a standard behavior,
otherwise 3rd 
party plugins wanting to access and modify the project
structure could 
be coded based on different assumptions.
So can we agree on one behavior and document it?
Unfortunately none of 
the currently written importers have this methods
implemented.

4. KDevProjectFileItem

This is a dark area for us. We will study it a little bit
more, but 
right now it is unclear of the relation between all those
KDev*Item 
classes and the inheritance diagram (like why the FileItem
is derived 
from a collection, the difference between collection and
group, etc.). 
If anyone has a clear overview about this and could share
with us, we 
would be happy. 

5. 


That is for now, hopefully you could help us. 

Andras

-- 
Quanta Plus developer - http://quanta.kdewebdev.o
rg
K Desktop Environment - http://www.kde.org
_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

On Wednesday 16 August 2006 06:12, Andras Mantia wrote:
> Hi,
>
>  We've been starting/continuing to work on integrating
Quanta with
> KDevelop4 and while we've been looking to the new API
some questions
> have been arisen. I would like to ask for comments and
help for anybody
> knowing this classes.
>
> 1. KDevProjectController
> There are methods called
projectsDirectory/setProjectsDirectory and
> projectDirectory. This is dangerous, as one might
easily make a mistake
> by putting or not putting that "s" there.
Aside of that it is not clear
> the meaning and the difference of the above two. What
are the
> "projects" method for? The assumption is
that the project file can be
> at a different place than the project content and the
"projects" method
> are for the content itself. Is this true? BTW, we
didn't really saw an
> example of their usage, only something in the konsole
plugin which is
> also a strange code.
> If anyway there is a need for both, we suggest to
rename the
> projectDirectory to "globalFileDirectory"
as actually it refers to the
> place where the globalFile (project file) is. Or
something like that.
>

are they actually used anywhere? If not, then we can remove
them and if we 
need them later, then add them then.


> KDevProjectController::openProject: the open dialog has
hardcoded
> information about KDevelop4 project files. This one
should be
> configurable in some way. Ideas are welcome.
>

If the file dialog is created here, shouldn't this be made
virtual so that 
others can provide their own impl?


> 2. KDevProject
>
> This one also has a projectDirectory() thing. What is
the difference
> between this and the above? Does it point to the same
> "globalFileDirectory" or should point to
the directory where the
> project content is? In any case, why is it here as well
and in the
> controller? I'd suggest to keep it only here.
>

This is definately the project directory for the currently
open project. 

> inProject method in KDevProject: the implementation is
completely wrong
> and we have no idea why it is implemented here at all.
KDevProject has
> pure virtual methods, so this should be pure virtual as
well and the
> implementation removed from the lib.
>

KDevProject should not be completely pure virtual. inProject
is supposed to 
query the file manager and determine if the file is part of
the project that 
way.

> absoluteUrl: in the implementation there is a call to
KUrl with the
> KUrl(KUrl, QString) constructor to combine an absolute
url with a
> relative path. The problem is that the docs for KUrl
clearly say that
> one should not use a *path* for the second argument,
but an encoded
> string. And here a path is used, so this looks wrong to
me and possibly
> will fail in some cases.
>

absoluteUrl probably needs to go away. The file managers
should already be 
using absolute URLs, so I'm not sure where this would be
needed at all. 

> 3. KDevFileManager
>
> As we understood in order to open a project, add/remove
files to the
> project there is a need to implement a KDevFileManager
class. What we
> like to know is how did you imagine handling of files
that were added
> toza project. The addFile returns a pointer to a
KDevProjectFileItem.
> When a file is removed/renamed do you expect that this
very same
> pointer is passed to remove/renameFile method? 

Yes, that same pointer would need to be passed to
removeFile/renameFile. 
However, I would imagine that this would automatically taken
care of by the 
GUI when it's fleshed out a bit more.  I would imagine that
we don't need 
those functions to return a KDevProjectFileItem anymore,
since they should be 
added to their respective folder/target/whatever it was
added to.

> Or one could just create 
> a new KDevProjectFileItem pointing to the same URL and
pass this to
> removeFile? 

It's not supposed to work this way, ideally. As mentioned
above, the only use 
case for this so far is if removal is done via the GUI.
However, if you have 
other use cases, we can make changes to accomdate.

> I understand that this is up to our FileManager class,
but 
> I think there is a need to have a standard behavior,
otherwise 3rd
> party plugins wanting to access and modify the project
structure could
> be coded based on different assumptions.

It's not really up to the file manager implementation, but
rather the project 
manager implementation really. At least that's how it
should work when it 
comes to calling addFile, removeFile, renameFile, etc.

> So can we agree on one behavior and document it?
Unfortunately none of
> the currently written importers have this methods
implemented.
>

Indeed.

> 4. KDevProjectFileItem
>
> This is a dark area for us. We will study it a little
bit more, but
> right now it is unclear of the relation between all
those KDev*Item
> classes and the inheritance diagram (like why the
FileItem is derived
> from a collection, the difference between collection
and group, etc.).
> If anyone has a clear overview about this and could
share with us, we
> would be happy. 
>

Welcome to KDevelop's probably overengineered model/view
stuff.  That's
all 
the *Item classes are for. However, somebody removed the
actual use of the Qt 
model view stuff from those classes for reasons I still
don't understand. /me 
glances at manyoso.

>
> That is for now, hopefully you could help us.
>

Hopefully this helps
--
Matt

_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

On Wednesday 16 August 2006 8:14 pm, Matt Rogers wrote:
> On Wednesday 16 August 2006 06:12, Andras Mantia wrote:
> > Hi,
> >
> >  We've been starting/continuing to work on
integrating Quanta with
> > KDevelop4 and while we've been looking to the new
API some questions
> > have been arisen. I would like to ask for comments
and help for anybody
> > knowing this classes.
> >
> > 1. KDevProjectController
> > There are methods called
projectsDirectory/setProjectsDirectory and
> > projectDirectory. This is dangerous, as one might
easily make a mistake
> > by putting or not putting that "s"
there. Aside of that it is not clear
> > the meaning and the difference of the above two.
What are the
> > "projects" method for? The assumption
is that the project file can be
> > at a different place than the project content and
the "projects" method
> > are for the content itself. Is this true? BTW, we
didn't really saw an
> > example of their usage, only something in the
konsole plugin which is
> > also a strange code.
> > If anyway there is a need for both, we suggest to
rename the
> > projectDirectory to
"globalFileDirectory" as actually it refers to
the
> > place where the globalFile (project file) is. Or
something like that.
>
> are they actually used anywhere? If not, then we can
remove them and if we
> need them later, then add them then.

Please don't.  I know I need to document them, but they do
have a purpose...

projectDirectory == the dir where the current project file
is located.

projectsDirectory == the dir where the user holds all of his
project 
folders ... perhaps this can be renamed to better illustrate
what it is.

Both of them are useful though, please don't remove.

> > KDevProjectController::openProject: the open
dialog has hardcoded
> > information about KDevelop4 project files. This
one should be
> > configurable in some way. Ideas are welcome.

All it has is the extension.  We can easily make an API for
setting this 
extension.

> If the file dialog is created here, shouldn't this be
made virtual so that
> others can provide their own impl?

Why would this be made virtual?  How many ways are you going
to open a project 
file?

Adam

_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

On Wednesday 16 August 2006 20:14, Adam Treat wrote:
> On Wednesday 16 August 2006 8:14 pm, Matt Rogers wrote:
> > On Wednesday 16 August 2006 06:12, Andras Mantia
wrote:
> > > Hi,
> > >
> > >  We've been starting/continuing to work on
integrating Quanta with
> > > KDevelop4 and while we've been looking to
the new API some questions
> > > have been arisen. I would like to ask for
comments and help for anybody
> > > knowing this classes.
> > >
> > > 1. KDevProjectController
> > > There are methods called
projectsDirectory/setProjectsDirectory and
> > > projectDirectory. This is dangerous, as one
might easily make a mistake
> > > by putting or not putting that
"s" there. Aside of that it is not clear
> > > the meaning and the difference of the above
two. What are the
> > > "projects" method for? The
assumption is that the project file can be
> > > at a different place than the project content
and the "projects" method
> > > are for the content itself. Is this true?
BTW, we didn't really saw an
> > > example of their usage, only something in the
konsole plugin which is
> > > also a strange code.
> > > If anyway there is a need for both, we
suggest to rename the
> > > projectDirectory to
"globalFileDirectory" as actually it refers to
the
> > > place where the globalFile (project file) is.
Or something like that.
> >
> > are they actually used anywhere? If not, then we
can remove them and if
> > we need them later, then add them then.
>
> Please don't.  I know I need to document them, but
they do have a
> purpose...
>
> projectDirectory == the dir where the current project
file is located.
>
> projectsDirectory == the dir where the user holds all
of his project
> folders ... perhaps this can be renamed to better
illustrate what it is.
>
> Both of them are useful though, please don't remove.
>

But not all project folders are in the same place, so I
still don't see the 
point of either of these functions since projectDirectory is
duplicated from 
KDevProject and well, right now, projectsDirectory doesn't
make sense to me.

> > > KDevProjectController::openProject: the open
dialog has hardcoded
> > > information about KDevelop4 project files.
This one should be
> > > configurable in some way. Ideas are welcome.
>
> All it has is the extension.  We can easily make an API
for setting this
> extension.
>
> > If the file dialog is created here, shouldn't
this be made virtual so
> > that others can provide their own impl?
>
> Why would this be made virtual?  How many ways are you
going to open a
> project file?
>
> Adam
>

I dunno. That's why I asked the question.  If it
doesn't need to be virtual 
and we can provide API that says "use this extension
(or even better, 
mimetype) when looking for project files to open" then
that's fine too
--
Matt

_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

On Thursday 17 August 2006 04:14, Adam Treat wrote:

> Please don't.  I know I need to document them, but
they do have a
> purpose...
>
> projectDirectory == the dir where the current project
file is
> located.
>
> projectsDirectory == the dir where the user holds all
of his project
> folders ... perhaps this can be renamed to better
illustrate what it
> is.

Yes, this is what I imagined. To avoid confusion this is why
I suggest 
renaming the methods:
- projectDirectory => projectFileDirectory or
globalFileDirectory, as in 
the API the project file is called global file
- projectsDirectory => projectDirectory. I'm not a
native speaker and I 
could imagine the name comes from "project's
directory", but I find it 
strange. 

The question about having a projectDirectory in KDevProject
remains. If 
that is the same as projectsDirectory here, why do we need
it in two 
places?

> Both of them are useful though, please don't remove.
>
> > > KDevProjectController::openProject: the open
dialog has hardcoded
> > > information about KDevelop4 project files.
This one should be
> > > configurable in some way. Ideas are welcome.
>
> All it has is the extension.  We can easily make an API
for setting
> this extension.

I like this better than subclassing. 


Andras
-- 
Quanta Plus developer - http://quanta.kdewebdev.o
rg
K Desktop Environment - http://www.kde.org
_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

On Thursday 17 August 2006 03:14, Matt Rogers wrote:
Hi and thanks for the answers!

> > inProject method in KDevProject: the
implementation is completely
> > wrong and we have no idea why it is implemented
here at all.
> > KDevProject has pure virtual methods, so this
should be pure
> > virtual as well and the implementation removed
from the lib.
>
> KDevProject should not be completely pure virtual.
inProject is
> supposed to query the file manager and determine if the
file is part
> of the project that way.

It already has pure virtual methods, so the class is pure
virtual.  I 
don't mind having the inProject implemented there, but than
it should 
be implemented for real.  

> > absoluteUrl: in the implementation there is a call
to KUrl with the
> > KUrl(KUrl, QString) constructor to combine an
absolute url with a
> > relative path. The problem is that the docs for
KUrl clearly say
> > that one should not use a *path* for the second
argument, but an
> > encoded string. And here a path is used, so this
looks wrong to me
> > and possibly will fail in some cases.
>
> absoluteUrl probably needs to go away. The file
managers should
> already be using absolute URLs, so I'm not sure where
this would be
> needed at all.

Right now it is only used in the bogus inProject
implementation...

> > 3. KDevFileManager
> >
> > As we understood in order to open a project,
add/remove files to
> > the project there is a need to implement a
KDevFileManager class.
> > What we like to know is how did you imagine
handling of files that
> > were added toza project. The addFile returns a
pointer to a
> > KDevProjectFileItem. When a file is
removed/renamed do you expect
> > that this very same pointer is passed to
remove/renameFile method?
>
> Yes, that same pointer would need to be passed to
> removeFile/renameFile. However, I would imagine that
this would
> automatically taken care of by the GUI when it's
fleshed out a bit
> more.  I would imagine that we don't need those
functions to return a
> KDevProjectFileItem anymore, since they should be added
to their
> respective folder/target/whatever it was added to.

so you mean that they should take a KUrl and all the other
thing is done 
inside the filemanager? I support this idea.

> > I understand that this is up to our FileManager
class, but
> > I think there is a need to have a standard
behavior, otherwise 3rd
> > party plugins wanting to access and modify the
project structure
> > could be coded based on different assumptions.
>
> It's not really up to the file manager implementation,
but rather the
> project manager implementation really. At least that's
how it should
> work when it comes to calling addFile, removeFile,
renameFile, etc.

Well yes, they work together, but both can be called
independently from 
3rd party plugins.

Andras
-- 
Quanta Plus developer - http://quanta.kdewebdev.o
rg
K Desktop Environment - http://www.kde.org
_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

> > > are they actually used anywhere? If not, then
we can remove them and if
> > > we need them later, then add them then.
> >
> > Please don't.  I know I need to document them,
but they do have a
> > purpose...
> >
> > projectDirectory == the dir where the current
project file is located.
> >
> > projectsDirectory == the dir where the user holds
all of his project
> > folders ... perhaps this can be renamed to better
illustrate what it is.
> >
> > Both of them are useful though, please don't
remove.
>
> But not all project folders are in the same place, so I
still don't see the
> point of either of these functions since
projectDirectory is duplicated
> from KDevProject and well, right now, projectsDirectory
doesn't make sense
> to me.

Oh that is new for me. I thought that project files and
folders must have a 
common base folder? But the project file can be at an
arbitrary location 
where also the hidden .kde4 folder is created. Am I wrong
here?


> > > > KDevProjectController::openProject: the
open dialog has hardcoded
> > > > information about KDevelop4 project
files. This one should be
> > > > configurable in some way. Ideas are
welcome.
> >
> > All it has is the extension.  We can easily make
an API for setting this
> > extension.
> >
> > > If the file dialog is created here,
shouldn't this be made virtual so
> > > that others can provide their own impl?
> >
> > Why would this be made virtual?  How many ways are
you going to open a
> > project file?
> >
> > Adam
>
> I dunno. That's why I asked the question.  If it
doesn't need to be
> virtual and we can provide API that says "use
this extension (or even
> better, mimetype) when looking for project files to
open" then that's fine
> too --

Or simply read it from the configuration file with a default
for the current 
value. We could just provide a different value in Quanta's
configuration file 
then. I think an API would be too much.

Jens

_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

On Thursday, 17. August 2006 08:36, Andras Mantia wrote:
> On Thursday 17 August 2006 04:14, Adam Treat wrote:
> > Please don't.  I know I need to document them,
but they do have a
> > purpose...
> >
> > projectDirectory == the dir where the current
project file is
> > located.
> >
> > projectsDirectory == the dir where the user holds
all of his project
> > folders ... perhaps this can be renamed to better
illustrate 100what it
> > is.
>
> Yes, this is what I imagined. To avoid confusion this
is why I suggest
> renaming the methods:
> - projectDirectory => projectFileDirectory or
globalFileDirectory, as in
> the API the project file is called global file
> - projectsDirectory => projectDirectory. I'm not a
native speaker and I
> could imagine the name comes from "project's
directory", but I find it
> strange.

I find this more confusing than the original version.
For me, it's much more logical to have a distinction
1. where the current project is
2. where the projectS are, usually (not always)
The s in projects is really a plural, doesn't relate to the
genitive at all.

Maybe something like currentProjectDirectory and
defaultProjectDirectory?

Just my 2 cent,
  Jakob

_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

On Thursday 17 August 2006 11:30, Jakob Petsovits wrote:
> I find this more confusing than the original version.
> For me, it's much more logical to have a distinction
> 1. where the current project is
> 2. where the projectS are, usually (not always)
> The s in projects is really a plural, doesn't relate
to the genitive
> at all.

How can we have multiple projects? I don't really think
this is about a 
common project place. I don't see why we should have
something like 
that.

Andras
-- 
Quanta Plus developer - http://quanta.kdewebdev.o
rg
K Desktop Environment - http://www.kde.org
_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel

On Thursday 17 August 2006 01:36, Andras Mantia wrote:
> On Thursday 17 August 2006 04:14, Adam Treat wrote:
> > Please don't.  I know I need to document them,
but they do have a
> > purpose...
> >
> > projectDirectory == the dir where the current
project file is
> > located.
> >
> > projectsDirectory == the dir where the user holds
all of his project
> > folders ... perhaps this can be renamed to better
illustrate what it
> > is.
>
> Yes, this is what I imagined. To avoid confusion this
is why I suggest
> renaming the methods:
> - projectDirectory => projectFileDirectory or
globalFileDirectory, as in
> the API the project file is called global file
> - projectsDirectory => projectDirectory. I'm not a
native speaker and I
> could imagine the name comes from "project's
directory", but I find it
> strange.
>
> The question about having a projectDirectory in
KDevProject remains. If
> that is the same as projectsDirectory here, why do we
need it in two
> places?
>

both of these functions are going away. projectsDirectory
will be removed, and 
projectDirectory will be removed in favor of
KDevProject::projectDirectory.

> > Both of them are useful though, please don't
remove.
> >
> > > > KDevProjectController::openProject: the
open dialog has hardcoded
> > > > information about KDevelop4 project
files. This one should be
> > > > configurable in some way. Ideas are
welcome.
> >
> > All it has is the extension.  We can easily make
an API for setting
> > this extension.
>
> I like this better than subclassing. 
>
>
> Andras

_______________________________________________
KDevelop-devel mailing list
KDevelop-develbarney.cs.uni-potsdam.de
http://barney.cs.uni-potsdam.de/mailman/listinfo/
kdevelop-devel