Things I would like to see in the developer documentation

[0xfalafel]

Hello,

Since Dan has talk about improving the documentation in G+, I have made a list of what I have try to learn when getting started with Vala. But in one month, I haven't find the time to create proper bugs reports, and I will have even less time the next 2 month, so, even if it isn't awesome I am just gonna put it here.

A little background here : I am in my last year of college, really passionate about Gnu/Linux in general, and more particularly elementary. I have try 3 or 4 time to build a simple 3rd party elementary app, and eventually give up each time because it took me really a long time to find how to do Gtk stuff, and the best source was understanding other 3rd party elementary apps.

Vala isn't too hard to pick up. I was already familiar with object oriented programming, so I have build a Game, and an IA for this game as a student project in a month or two.

The hard part IMO, is getting started with GTK and GLib libraries. I have to say that I am not really familiar with the creation of interfaces (well, I had a course about QT, but I didn't do much). And blog post about creation of Gtk interfaces in Vala are really hard to found.

Down here, a list of things I have search about, and that I would love to see into the documentation :

Common layouts :

• [x] How to do a Headerbar
  • [x] add a Popover
  • [x] add a Menu
  • [ ] change the color to set a brand
• [ ] Welcome View
• [ ] Stack and Stack Switcher
• [ ] How to do a Sidebar (classic, with sourceview, only with big icons)
• [ ] Cover view (the list of albums in noise)
• [ ] TreeView (second view in Noise)
• [x] #194
• [ ] Pantheon mail list (that list of mails, I never figure out how to do it)

Playing with Text :

• [ ] Text View
• [ ] Customising Text (bold, size, color)
• [ ] Text Editing
• [ ] WebKitView

Playing with media :

• [ ] Displaying an Image
• [ ] Playing some audio
• [ ] Playing a Video

Storing Data :

• [x] Gsettings
• [ ] SQL db
• [ ] "Open a File" Dialog
• [ ] Getting Data from a Rest API
• [ ] Reading data from JSON

Pro tips :

• [x] Keyboard Shortcuts
• [x] Right Click

Integration with elementary :

• ~~Notifications~~
• [x] Number above icons in Plank
• ~~Contractor~~

Again, sorry for just putting that here and not doing a propers bugs reports.

[danirabbit]

Contractor documentation is being tracked at elementary/docs#15 Notifications documentation is being tracked at elementary/website#935

[Philip-Scott]

We already have a "Getting Started" guide with the basics.... I feel that we should maybe make a new page with these more "advanced/level 2" features; if not, i feel that the current guide could quickly fall out of scope

[gitzain]

Having a separate page along the "advanced/level 2" idea makes a lot of sense. If the page existed I'd be happy to start to populate.

[lewisgoddard]

This should be broken down into multiple issues, it will make it more likely to be worked on.

[RippieUK]

I would like to add to this as well, i also agree that perhaps a level 2 page that teach:

• [ ] The use of namespaces

• [ ] Split out from a single Application.vala file using multiple classes

• [x] Create a header bar using HeaderBar.vala

• [ ] Implement dark/light mode switch in either headerbar or a popup menu which is saved in gsettings.

I think introducing these next topics would lay a really good foundation for any new programmer to learn on his/her own after the guide is completed.

[danirabbit]

@RippieUK Can you please file new issue reports for each new section you would like to see please? That would make it much easier to track

[danirabbit]

We can cross a few more off this list with https://docs.elementary.io/develop/writing-apps/popovers