O que é o widget de cabeçalho preto em alguns programas?

Em alguns programas do ubuntu (painel de controle do ubuntu, configurações do sistema), mas não no banshee, a parte superior da janela contém elementos em tom escuro (com o tema Ambiente). Mas não consigo encontrar um widget padrão que faça isso automaticamente.

Essas cores estão todas definidas manualmente (em vez de widget + tema padrão)? E se eles são definidos manualmente, de onde eles vêm no tema (quais são os parâmetros em gtk_widget_modify_bg (widget, GTK_STATE_NORMAL e cor))?

EDIT: Não parece ser um simples Gtk.Toolbar. Se eu executar o seguinte código:

from gi.repository import Gtk
window = Gtk.Window()
window.set_default_size(200, -1)
window.connect("destroy", lambda q: Gtk.main_quit())
toolbar = Gtk.Toolbar()
window.add(toolbar)
toolbutton = Gtk.ToolButton(stock_id=Gtk.STOCK_NEW)
toolbar.add(toolbutton)
window.show_all()
Gtk.main()

Recebo uma janela como esta: que não possui um tom sombrio para a barra de ferramentas.

EDIT2: Embora a resposta 'barra de ferramentas com contexto especial' de j-johan-edwards seja verdadeira na maioria dos programas, não é o caso no painel de controle do ubuntuone. Este programa possui um GtkVBox que pode incluir qualquer gama de widgets (diferente da barra de ferramentas). Ainda não consigo determinar como o tema gtk sabe como pintar essa parte da janela.

Mas enfim: por enquanto uma barra de ferramentas é suficiente para mim ...

Você quer dizer isso?

Eles são apenas Gtk.Toolbars. A razão pela qual alguns aplicativos como o Banshee não os usam é que ainda não foram portados para o GTK + 3 e receberam os novos recursos de temas que permitem barras de ferramentas como essa.

Para portar seu próprio aplicativo Python para o GTK + 3, você precisa usar o PyGObject em vez do PyGTK. A partir de 12.04, o Quickly irá gerar projetos PyGObject por padrão.

Você também precisa adicionar primary-toolbarao contexto de estilo da barra de ferramentas. Igual a:

toolbar = Gtk.Toolbar()
context = toolbar.get_style_context()
context.add_class(Gtk.STYLE_CLASS_PRIMARY_TOOLBAR)

A aplicação desse contexto ao exemplo da pergunta resulta no seguinte:

Com relação à segunda parte da sua pergunta, que foi "Como adicionar o VBox à barra de ferramentas", tudo o que você precisa fazer é envolvê-lo dentro de um Gtk.ToolItem, por exemplo :.

...
self.toolbar = Gtk.Toolbar()
self.box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
tool_item = Gtk.ToolItem()
tool_item.add(self.box)
self.toolbar.insert(tool_item, 0)
...

Você pode simplificá-lo criando uma função auxiliar ou estendendo o Gtk.Toolbar, por exemplo:

custom_toolbar.py

from gi.repository import Gtk

class CustomToolbar(Gtk.Toolbar):
    def __init__(self):
        super(CustomToolbar, self).__init__()
        ''' Set toolbar style '''
        context = self.get_style_context()
        context.add_class(Gtk.STYLE_CLASS_PRIMARY_TOOLBAR)

    def insert(self, item, pos):
        ''' If widget is not an instance of Gtk.ToolItem then wrap it inside one '''
        if not isinstance(item, Gtk.ToolItem):
            widget = Gtk.ToolItem()
            widget.add(item)
            item = widget

        super(CustomToolbar, self).insert(item, pos)
        return item

Ele simplesmente verifica se o objeto que você tenta inserir é um ToolItem e, se não, ele o envolve dentro de um. Exemplo de uso:

main.py

#!/usr/bin/python
from gi.repository import Gtk
from custom_toolbar import CustomToolbar

class MySongPlayerWindow(Gtk.Window):
    def __init__(self):
        super(MySongPlayerWindow, self).__init__(title="My Song Player")
        self.set_size_request(640, 480)

        layout = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6)
        self.add(layout)

        status_bar = Gtk.Statusbar()
        layout.pack_end(status_bar, False, True, 0)

        big_button = Gtk.Button(label="Play music")
        layout.pack_end(big_button, True, True, 0)

        ''' Create a custom toolbar '''
        toolbar = CustomToolbar()
        toolbar.set_style(Gtk.ToolbarStyle.BOTH)        
        layout.pack_start(toolbar, False, True, 0)

        ''' Add some standard toolbar buttons '''
        play_button = Gtk.ToggleToolButton(stock_id=Gtk.STOCK_MEDIA_PLAY)
        toolbar.insert(play_button, -1)

        stop_button = Gtk.ToolButton(stock_id=Gtk.STOCK_MEDIA_STOP)
        toolbar.insert(stop_button, -1)

        ''' Create a vertical box '''
        playback_info = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, margin_top=5, margin_bottom=5, margin_left=10, margin_right=10)

        ''' Add some children... '''
        label_current_song = Gtk.Label(label="Artist - Song Name", margin_bottom=5)
        playback_info.pack_start(label_current_song, True, True, 0)

        playback_progress = Gtk.ProgressBar(fraction=0.6)
        playback_info.pack_start(playback_progress, True, True, 0)

        '''
        Add the vertical box to the toolbar. Please note, that unlike Gtk.Toolbar.insert,
        CustomToolbar.insert returns a ToolItem instance that we can manipulate
        '''
        playback_info_item = toolbar.insert(playback_info, -1)
        playback_info_item.set_expand(True)        

        ''' Add another custom item '''       
        search_entry = Gtk.Entry(text='Search')
        search_item = toolbar.insert(search_entry, -1)
        search_item.set_vexpand(False)
        search_item.set_valign(Gtk.Align.CENTER)

win = MySongPlayerWindow()
win.connect("delete-event", Gtk.main_quit)
win.show_all()
Gtk.main()

Deve olhar como este