This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex] 

Documentation Team » Tasks » DeveloperDocs »

/!\ This page is historical. Please see the developer documentation project for a list of issues and tasks instead! /!\

Beginner Gtk+ Course

Contents

  1. Beginner Gtk+ Course
  2. Resources and References
    1. Developer
    2. Mallard
    3. GIT
    4. IRC
  3. Samples needed
  4. Tutorials/topics needed
  5. Contributing to the Samples and Tutorials
    1. A. Get Started
    2. B. Editing existing pages
    3. C. Creating new pages
    4. D. Create a .patch file
    5. E. Create a Bugzilla account and file a new bug
    6. F. Update your local repository with everyone else's changes
    7. G. Undo mistakes

This was a planning page about the development of Tutorials and Code Samples for beginners. This is not in use anymore in 2023!

This was an OPW Summer 2012 Project.

Resources and References

Developer

C

Vala

JavaScript

Python

Mallard

GIT

IRC

Samples needed

Display widgets

C

JS

Vala

Python

{*} Image — A widget displaying an image

(./)

(./)

(./)

(./)

{*} Label — A widget which displays text

(./)

(./)

(./)

(./)

ProgressBar — A widget which indicates progress visually

(./)

(./)

(./)

(./)

Spinner — A spinner animation

(./)

(./)

(./)

(./)

Statusbar — Report messages of minor importance to the user

(./)

(./)

(./)

(./)

Button and toggles

C

JS

Vala

Python

{*} Button — A widget which emits a signal when clicked

(./)

(./)

(./)

(./)

CheckButton — Create widgets with a discrete toggle button

(./)

(./)

(./)

(./)

RadioButton — A choice from multiple check buttons

(./)

(./)

(./)

(./)

ToggleButton — Create buttons which retain their state

(./)

(./)

(./)

(./)

LinkButton — Create buttons bound to a URL

(./)

(./)

(./)

(./)

Switch — A "light switch" style toggle

(./)

(./)

(./)

(./)

MenuButton* — A widget that shows a menu when clicked on

(./)

(./)

(./)

(./)

Numeric and text data entry

C

JS

Vala

Python

{*} Entry — A single line text entry field

(./)

(./)

(./)

(./)

Scale — A slider widget for selecting a value from a range

(./)

(./)

(./)

(./)

SpinButton — Retrieve an integer or floating-point number from the user

(./)

(./)

(./)

(./)

Multiline Text Editor

C

JS

Vala

Python

TextView - Widget that displays a GtkTextBuffer

(./)

(./)

(./)

(./)

Windows

C

JS

Vala

Python

Window - Toplevel window which can contain other widgets

(./)

(./)

(./)

(./)

{*} MessageDialog - A message window

(./)

(./)

(./)

(./)

Dialog - A popup window

(./)

(./)

(./)

(./)

AboutDialog - Display information about an application

(./)

(./)

(./)

(./)

{*} ApplicationWindow — GtkWindow subclass with GtkApplication support

(./)

(./)

(./)

(./)

Menu, combo box and toolbar widgets

C

JS

Vala

Python

{*} GMenu

(./)

(./)

(./)

(./)

{*} ComboBox — A widget used to choose from a list of items

(./)

(./)

(./)

(./)

Multi-column ComboBox (optional)

(./)

(./)

MenuBar — A subclass of GtkMenuShell which holds GtkMenuItem widgets

(./)

(./)

(./)

{*} Toolbar — A bar of buttons and other widgets

(./)

(./)

(./)

(./)

{*} Toolbar using Glade & GtkBuilder

(./)

(./)

File selectors

C

JS

Vala

Python

FileChooserDialog — A dialog suitable for "File/Open" or "File/Save" commands

(./)

(./)

Font selectors

C

JS

Vala

Python

FontChooserWidget — A widget for selecting fonts

(./)

(./)

(./)

Color selectors

C

JS

Vala

Python

ColorButton — A button to launch a color selection dialog

(./)

(./)

(./)

Layout containers

C

JS

Vala

Python

{*} Grid — Pack widgets in rows and columns

(./)

(./)

(./)

(./)

ButtonBox — A container for arranging buttons ?

(./)

(./)

Paned — A widget with two adjustable panes

(./)

(./)

(./)

(./)

GtkStack — a stacking container

GtkListBox — a list container

Treeview

C

JS

Vala

Python

{*} TreeView with simple ListView

(./)

(./)

(./)

TreeView with Advanced ListView

(./)

TreeView with TreeStore

(./)

TreeView with CellRendererToggle

(./)

Ornaments

C

JS

Vala

Python

GtkSeparator — A separator widget

(./)

(./)

(./)

Scrolling

C

JS

Vala

Python

Scrollbar — A Scrollbar

{*} ScrolledWindow — Adds scrollbars to its child widget

(./)

(./)

(./)

(./)

Miscellaneous

C

JS

Vala

Python

GtkStatusIcon - Put an icon in the system tray

GtkTooltip — Add tips to your widgets

(./)

(./)

(./)

(./)

Custom Widget - Create your own widget

* GtkMenuButton is a brand new widget. For it to work, you either need to jhbuild, or be running Gnome 3.5 or later.

Tutorials/topics needed

Contributing to the Samples and Tutorials

A. Get Started

1) install git

2) setup git: 

$ git config --global user.email yourname@somewhere.com

$ git config --global user.name "Your Name"

3) Get the latest version of the gnome-devel-docs from the git repository: 

$ git clone git://git.gnome.org/gnome-devel-docs

4) Go into the directory which contains the Mallard files (.page files) by typing: 

$ cd gnome-devel-docs/platform-demos/C/

To view the current state of the beginner tutorials/samples and platform from the index page type: 

$ yelp index.page

B. Editing existing pages

1) To view the Mallard source and/or make changes to existing pages you can use a text editor (like Gedit): 

$ gedit <filename>.page

* Do not include the angle brackets.

* If you are using Gedit, you should install the gedit-trim-trailing-whitespace-before-saving-plugin

* If you are editing the source code, please edit it in in the C/samples/ file matching the mallard page name first. Make sure it compiles and runs as expected, then copy/paste the code into the mallard file.

2) To view your changes using the help viewer: 

$ yelp <filename>.page

If the page doesn't show up in yelp, there may be a problem with the Mallard markup. If this happens, check the terminal output for errors (the error and line number of the error will be output to the terminal).

C. Creating new pages

1) install yelp-tools

2) To create a new topic page name <newtopic> with <Title> type: 

$ yelp-new task <taskname> "<Page Title>"

* Do not include the angle brackets. <taskname> becomes the name of the .page file.

You will notice the new page already has your name inserted as the author. Delete any of the boiler-plate markup or paragraphs which you do not need.

* Note: If you are creating a new sample page, the pages named widget.<language>.page pages are templates for sample pages. You can copy them into a new page, and make the appropriate changes to the page id, links, title, etc. Place any source code into the C/samples directory. Compile and run the code to make sure all is happy. Then copy and paste the code into the Mallard page file.

3) Add the new page to git: 

$ git add <newfile>.page

* Make sure you add each new page you create. If you forget, it will not be included in the .patch file, and your hard work may get lost. So if you also created a new file in samples/ and took a screenshot of the program run (which you should place into the /media folder and give it the same name as the source code file and mallard file), then you should: 

$git add <newfile>.page samples/<newfile>.<language-extention> media/<newfile>.png

4) Validate the new pages: You will need to have yelp-tools installed. To install yelp-tools, type 

$ su -c "yum install yelp-tools"

if you're on Fedora, or 

$ sudo apt-get install yelp-tools

if you're on Ubuntu. Check your distro's package manager otherwise.

Once yelp-tools is installed, to validate the page you just wrote type 

$ yelp-check validate <filename>.page

You can use *.page instead, if you want to validate every file in the directory. If the pages in question validate properly, this command will produce no output. It will only notify you if it finds a mistake.

This method of validating pages requires you to be connected to the Internet, and for projectmallard.org to be up at the moment. For a method of validating pages offline on your own, see Tiffany Antopolski's blog post.

D. Create a .patch file

1) Add the files to git:

When you are happy with your topics, in the Terminal, type 

$ git add <file>

Make sure you add each file you wish to include in the commit. You could also add each file in one 'git add' command: 

$ git add <file1> <file2> <file2>

You may need to give a relative path for a file if the file you are adding is not in your current directory.

2) Commit the files: 

$ git commit -m "tutorials <language>: <A commit message goes here explaining what your changes are.>"

The commit message should be less than 50 characters, but informative.

If you need more room to describe your commit, up to a few short paragraphs, then instead of the above type 

$ git commit

A text editor will open and let you write a longer message. This may be a console-mode editor which works entirely inside the terminal, and uses commands that you may not be familiar with. If you'd rather use gedit, GNOME's default text editor, type 

$ git config --global core.editor "gedit -w -s"

Like with git init, you only have to type that once. You'll still be able to write short commit messages using git commit -a -m if you like.

2) Once your changes are commited type: 

$ git format-patch HEAD^

This will create a .patch file in your current directory (the filename will start with 0001-)

Attach this file to a bug in Bugzilla. If this .patch is a new change or a new page, you will need to create a new bug. If you do not have a bugzilla account, see section E. below.

Attach your patch to the bug asking for a review.

NOTE: You can make many commits, and then make all the patch files at the same time. So for example, if you made 3 commits, you could then create all 3 patches at the same time by typing: 

$ git format-patch HEAD^^^

Your 3 patch files will then be consecutively numbered.

If you are working along and want to see a log of the commits, you can type: 

$ git log

Press 'q' to exit the log and return to the terminal.

E. Create a Bugzilla account and file a new bug

1) This page has information about how to create an account on Bugzilla, as well as how to create a new bug against the gnome-devel-docs. Once you have created a Bugzilla account, you can click here to file a new bug directly. Be sure to file it against platform-demos if you are creating a new code sample.

Once your patch is attached to a bug, a member of the Gnome Documentation Team will get back to you with comments, suggestions and edits, and we can work together on finalising the topics you wrote. They will then be added to the Desktop Help.

F. Update your local repository with everyone else's changes

1) When you run git clone to get started, it will bring you the contents of the gnome-devel-docs repository as they exist when you run it. It won't automatically update the files on your computer to match the files in the repository as other people work on them, though.

Every day when working on the documentation, as well as whenever you need to while working closely with someone else, type 

$ git pull --rebase

If you have changes you haven't committed yet, then before doing that type 

$ git stash

And afterwards type 

$ git stash pop

These commands store and retrieve the changes you're making, so that they aren't overwritten when you bring in the new code.

G. Undo mistakes

If you realize you made a mistake in your last commit, just make the needed changes, then type 

$ git add (the changed files)
$ git commit --amend

You will see the last commit message you wrote. You don't have to change it unless you have changed the commit itself enough that it needs a new description. Save the commit message, then format a new patch as normal.

If you need to go back multiple commits, type 

$ git reset --soft HEAD^

Add an additional ^ for each commit you want to undo. Make the changes, then do a new commit and create a new patch.

If you've already submitted a patch that includes a mistake to Bugzilla, go back to the page for the bug report you created, scroll down below the "Additional Comments" form to the box that says "Attachments", then click "Add an attachment". On the attachment form, mark that it's a patch, and mark that it obsoletes the previous one you submitted.

CategoryDocumentationProject

2024-10-23 11:04