API-Q: What is the "root" ProjectItem?

[sberic]

For some background, my specific goal is to access a file I previously imported into the Project and add it to a target Track at a specified time. The insertOrAppend example function identifies a "first" child ProjectItem found in the Project's "rootItem" ProjectItem. The type of the rootItem is 3, which corresponds to ROOT. There is no explanation of what the "root" is or how the various types interact. I have some assumptions but would prefer an explanation as assumptions tend to lead to lots of lost time

[andymees@aje]

I suspect your assumption is already correct steric, and the best I can do is personally is tell you what I believe it to be : the 'rootItem' is the project's index as an object...  in the sense of the UI, I think of the 'rootItem' as being the Project Panel, whereby the children of that root item are the items displayed in the project panel.

Thats my interpretation anyway.

Hope it helps

Andy

[Edited for clarity]

[e_d_]

Every project has a tree hierarchy, with projectItems being an array-like structure as its children. The index is being incremented with every item being added to the project itself. In Bruce's example, the script assumes the first (0) item to be a clip (projectItemType = 1) (maybe a file (4) would work as well...).

What leads you top the assumption that your projectItem is a rootItem (read: what was the first item you have added to the project)? If there are no items in the project, there is no return result.

[sberic]

Thanks, folks, for the responses! Some follow-ups:

andymees@aje wrote

the 'rootItem' is the project's index as an object...  in the sense of the UI, I think of the 'rootItem' as being the Project Panel, whereby the children of that root item are the items displayed in the project panel.

Yeah, that's a bit of what I'd assumed. I was hoping to hear more about the specific ProjectItem types and their interrelations. Perhaps Bruce Bullis​ can do a quick rundown of the types?

One assumption I'm starting to develop is that the ROOT is also a BIN for some purposes, as, for example, you can use the creation functions with it. So in a way, the ROOT type seems like a specialized version of BIN...

e.d.  wrote

Every project has a tree hierarchy, with projectItems being an array-like structure as its children. The index is being incremented with every item being added to the project itself. In Bruce's example, the script assumes the first (0) item to be a clip (projectItemType = 1) (maybe a file (4) would work as well...).

What leads you top the assumption that your projectItem is a rootItem (read: what was the first item you have added to the project)? If there are no items in the project, there is no return result.

I'm only assuming that my "projectItem is a rootItem" because I'm accessing it through the standard app.project.rootItem approach. I'm trying to get a better understanding of the project hierarchy - What are each of the node types? What ProjectItem APIs work with which types? How is the ROOT type different/related to the other types?

I know I can fumble around with the APIs available and see what works and what doesn't. It would be much faster to have some sort of explanation to help set some expectations as we dive into development...

[e_d_]

I'm only assuming that my "projectItem is a rootItem" because I'm accessing it through the standard app.project.rootItem approach. I'm trying to get a better understanding of the project hierarchy - What are each of the node types? What ProjectItem APIs work with which types? How is the ROOT type different/related to the other types?

Now I get it.

rootItem is a special projectItemObject, the difference being it only exists once (and I would think it must only exist once) in a project's hierarchchy. But basically any projectItem has the same set of methods and properties, only with different results (for instance, for a bin canChangeMediaPath = false, for a clip it's true). The only difference between a clip and a bin is a bin can have child items, whereas a clip doesn't.

So in terms of development, I can only give you the unasked-for advice of double checking (programmatically) the object you're currently accessing is really what you think it should be before performing further actions.

[sberic]

e.d.  wrote

rootItem is a special projectItemObject, the difference being it only exists once (and I would think it must only exist once) in a project's hierarchchy. But basically any projectItem has the same set of methods and properties, only with different results (for instance, for a bin canChangeMediaPath = false, for a clip it's true). The only difference between a clip and a bin is a bin can have child items, whereas a clip doesn't.

That's not the only difference. See:

• ProjectItem.createBin/deleteBin probably don't work on ProjectItems with type CLIP or FILE.
• ProjectItem.createSubClip probably only works on ProjectItems with type CLIP.
• ProjectItem.setOverridePixelAspectRatio probably only works on ProjectItems with type CLIP. Also, this is probably restricted to video clips.
• ProjectItem.children is, according to the documentation, "only valid for bins". That said, it is also valid for the ROOT ProjectItem.

e.d. wrote

So in terms of development, I can only give you the unasked-for advice of double checking (programmatically) the object you're currently accessing is really what you think it should be before performing further actions.

Given the structure, this is the only real valid way of handling things (e.g. ProjectItem.type checks before making use of the APIs listed above). I guess I wish that there was more documentation on what each type represented and then better documentation for each of the ProjectItem APIs for which types were supported for any given function/property...

[e_d_]

sberic  schrieb

• ProjectItem.createBin/deleteBin probably don't work on ProjectItems with type CLIP or FILE.
• ProjectItem.createSubClip probably only works on ProjectItems with type CLIP.
• ProjectItem.setOverridePixelAspectRatio probably only works on ProjectItems with type CLIP. Also, this is probably restricted to video clips.
• ProjectItem.children is, according to the documentation, "only valid for bins". That said, it is also valid for the ROOT ProjectItem.

Well this doesn't counter what I have said, does it? 😉

My (incomplete) test run makes me think all projectItems are created equal but depending on their type some methods and properties will not be available, or return false or null (undefined).

[sberic]

e.d. wrote

Well this doesn't counter what I have said, does it? 😉

Haha! Weeeeellllll, if we're being pedantic about it, you did mention the parent/child relationship. Clips can have sub-clips, I guess... although, I've honestly no idea at all how that works out within the ProjectItem hierarchy... 😜

e.d. wrote

My (incomplete) test run makes me think all projectItems are created equal but depending on their type some methods and properties will not be available, or return false or null (undefined).

Yeah. Some documentation on the APIs as to which work with which type would save everyone from having to conduct the same tests 😜

Thanks for the help!

[Bruce Bullis · Accepted solution]

app.project.rootItem = the root of the project. Is also a bin.

Which projectItem methods work with which types of project items, general guideline = if it's a bin, you can use the bin management functions.

Per Erik's (valid) distinctions:

Yes, you cannot create footage using createBin(), nor can you delete non-Bin projectItems using deleteBin(). They're not bins.

Yes, createSubClip() only works on projectItems which can provide footage, which means they are not Bins.

Yes, setOverridePixelAspectRatio() only works on projectItems which are not Bins.

Yes, the .children member is only valid for Bins, like the root item.

[sberic]

Thanks Bruce Bullis​! Very clear summary!

(Special shout-out to e.d.​ for the further help and distinctions!)