PyGobject（三十四）布局容器之Assistant

Gtk.Assistant

Gtk.Assistant 用来表示多个步骤的引导页面，常用来在软件安装过程中的参数设置，或者收集某些问卷信息等等。

Gtk.Assistant的设计原理是，根据它所知道的页顺序和每一页的类型中，来控制显示什么按钮和按钮是否可点击。

如果这些还不满足你的要求，你可以自定义按钮，使用Gtk.AssistantPageType.CUSTOM页面类型并自己处理button的事件。

继承关系

Gtk.Assistant是Gtk.Window的直接子类

Methods

方法修饰词	方法名及参数
static	new ()
	add_action_widget (child)
	append_page (page)
	commit ()
	get_current_page ()
	get_n_pages ()
	get_nth_page (page_num)
	get_page_complete (page)
	get_page_has_padding (page)
	get_page_header_image (page)
	get_page_side_image (page)
	get_page_title (page)
	get_page_type (page)
	insert_page (page, position)
	next_page ()
	prepend_page (page)
	previous_page ()
	remove_action_widget (child)
	remove_page (page_num)
	set_current_page (page_num)
	set_forward_page_func (page_func, *data)
	set_page_complete (page, complete)
	set_page_has_padding (page, has_padding)
	set_page_header_image (page, pixbuf)
	set_page_side_image (page, pixbuf)
	set_page_title (page, title)
	set_page_type (page, type)
	update_buttons_state ()

Virtual Methods

do_apply ()
do_cancel ()
do_close ()
do_prepare (page)

Properties

Name	Type	Flags	Short Description
use-header-bar	int	r/w/co	Use Header Bar for actions.

Signals

Name	Short Description
apply	“apply”按钮点击的时候发送此信号.
cancel	“cancel” 按钮点击的时候发送此信号
close	“close”按钮点击的时候或者 Gtk.AssistantPageType.CONFIRM 页并且是最后一页中的”apply”按钮点击的时候发送此信号.
escape
prepare	当新的一页设置成将要显示的页，但是还没有显示时，发送此信号

例子

代码：

#!/usr/bin/env python3
# Created by xiaosanyu at 16/7/17
# section 040
# 
# author: xiaosanyu
# website: yuxiaosan.tk \
#          http://blog.youkuaiyun.com/a87b01c14
# created: 16/7/17

TITLE = "Assistant"
DESCRIPTION = """
A Gtk.Assistant is a widget used to represent a generally complex operation splitted in several steps,
guiding the user through its pages and controlling the page flow to collect the necessary data.
"""
import gi

gi.require_version("Gtk", "3.0")
from gi.repository import Gtk, GLib


class AssistantWindow(Gtk.Assistant):
    def __init__(self):
        Gtk.Assistant.__init__(self, title="Assistant Example")
        self.set_size_request(-1, 300)
        self.set_border_width(10)
        self.create_page1()
        self.create_page2()
        self.create_page3()
        self.create_page4()
        self.show_all()
        Gtk.main()

    def create_page1(self):
        box = Gtk.Box(spacing=12)
        box.set_border_width(12)

        label = Gtk.Label("You must fill out this entry to continue:")
        box.pack_start(label, False, False, 0)

        entry = Gtk.Entry()
        entry.set_activates_default(True)
        entry.set_valign(Gtk.Align.CENTER)
        box.pack_start(entry, True, True, 0)
        entry.connect("changed", self.on_entry_changed)

        box.show_all()
        self.append_page(box)
        self.set_page_title(box, "Page 1")
        self.set_page_type(box, Gtk.AssistantPageType.INTRO)

    def create_page2(self):
        box = Gtk.Box(spacing=12)
        box.set_border_width(12)

        checkbutton = Gtk.CheckButton.new_with_label("This is optional data, you may continue "
                                                     "even if you do not check this")
        box.pack_start(checkbutton, False, False, 0)

        box.show_all()
        self.append_page(box)
        self.set_page_title(box, "Page 2")
        self.set_page_complete(box, True)

    def create_page3(self):
        box = Gtk.Box(spacing=12)
        box.set_border_width(12)

        label = Gtk.Label("This is a confirmation page, press 'Apply' to apply changes")
        box.pack_start(label, False, False, 0)

        box.show_all()
        self.append_page(box)
        self.set_page_title(box, "Confirmation")
        self.set_page_complete(box, True)
        self.set_page_type(box, Gtk.AssistantPageType.CONFIRM)

    def create_page4(self):
        self.progress_bar = Gtk.ProgressBar()
        self.progress_bar.set_halign(Gtk.Align.CENTER)
        self.progress_bar.set_valign(Gtk.Align.CENTER)

        self.progress_bar.show()
        self.append_page(self.progress_bar)
        self.set_page_title(self.progress_bar, "Applying changes")
        self.set_page_type(self.progress_bar, Gtk.AssistantPageType.PROGRESS)
        # This prevents the assistant window from being
        # closed while we're "busy" applying changes.
        self.set_page_complete(self.progress_bar, False)

    def on_entry_changed(self, widget):

        page_number = self.get_current_page()
        current_page = self.get_nth_page(page_number)
        text = widget.get_text()

        if text:
            self.set_page_complete(current_page, True)
        else:
            self.set_page_complete(current_page, False)

    def do_apply(self):
        # Start a timer to simulate changes taking a few seconds to apply.
        self.timeout = GLib.timeout_add(100, self.apply_changes_gradually)

    def do_prepare(self, page):
        current_page = self.get_current_page()
        n_pages = self.get_n_pages()

        title = "Sample assistant (%d of %d)" % (current_page + 1, n_pages)
        self.set_title(title)

        # The fourth page (counting from zero) is the progress page.  The
        # user clicked Apply to get here so we tell the assistant to commit,
        # which means the changes up to this point are permanent and cannot
        # be cancelled or revisited. */
        if current_page == 3:
            self.commit()

    def apply_changes_gradually(self):
        fraction = self.progress_bar.get_fraction()
        fraction += 0.05

        if fraction < 1.0:
            self.progress_bar.set_fraction(fraction)
            return GLib.SOURCE_CONTINUE
        else:
            # Close automatically once changes are fully applied. 
            GLib.Source.remove(self.timeout)
            self.destroy()
            Gtk.main_quit()

    def do_destroy(self):
        self.destroy()

    def do_delete_event(self, event):
        self.destroy()
        Gtk.main_quit()

    def do_cancel(self):
        self.destroy()
        Gtk.main_quit()


def main():
    win = AssistantWindow()


if __name__ == "__main__":
    main()

代码解析
自定义AssistantWindow类继承自Gtk.Assistant，
在初始化函数中添加第一个页面

self.create_page1()

在create_page1方法中，创建一个Gtk.Box，添加一个Gtk.Label和一个Gtk.Entry

box = Gtk.Box(spacing=12)
box.set_border_width(12)

label = Gtk.Label("You must fill out this entry to continue:")
box.pack_start(label, False, False, 0)

entry = Gtk.Entry()
entry.set_activates_default(True)
entry.set_valign(Gtk.Align.CENTER)
box.pack_start(entry, True, True, 0)
entry.connect("changed", self.on_entry_changed)

box.show_all()

将box添加到Assistant中，作为一页

self.append_page(box)

设置页标题

self.set_page_title(box, "Page 1")

设置页类型为Gtk.AssistantPageType.INTRO

self.set_page_type(box, Gtk.AssistantPageType.INTRO)

当entry中有输入内容是，页面状态变为”complete“，可以点击”Forward“到下一页

def on_entry_changed(self, widget):

        page_number = self.get_current_page()
        current_page = self.get_nth_page(page_number)
        text = widget.get_text()

        if text:
            self.set_page_complete(current_page, True)
        else:
            self.set_page_complete(current_page, False)

同理，添加第二页

self.create_page2()

不同的是第二页类型为没有设置，默认为Gtk.AssistantPageType.CONTENT
并且设置页面可以直接进入下一页

self.set_page_complete(box, True)

同理添加第三页

self.create_page3()

不同的是设置页面类型为Gtk.AssistantPageType.CONFIRM并且设置页面可以直接进入下一页

self.set_page_complete(box, True)
self.set_page_type(box, Gtk.AssistantPageType.CONFIRM)

第四页有点不一样了，里面显示一个Gtk.ProgressBar
设置页面类型为Gtk.AssistantPageType.PROGRESS

当第三页中的”apply“按钮点击时，运行do_apply方法

self.timeout = GLib.timeout_add(100, self.apply_changes_gradually)

启动一个定时器

def apply_changes_gradually(self):
        fraction = self.progress_bar.get_fraction()
        fraction += 0.05

        if fraction < 1.0:
            self.progress_bar.set_fraction(fraction)
            return GLib.SOURCE_CONTINUE
        else:
            # Close automatically once changes are fully applied. 
            GLib.Source.remove(self.timeout)
            self.destroy()
            Gtk.main_quit()

改变进度条的进度。当进度条满后，移除定时器，退出应用程序。

附录

Gtk.AssistantPageType

class Gtk.AssistantPageType
Bases: GObject.GEnum
每一个非”committed”状态的页都有一个”cancel”按钮

CONTENT = 0

显示普通内容页面.显示”Back” 和 “forward” 按钮

INTRO = 1

简介内容. 只显示” Forward “按钮(如果有下一页).

CONFIRM = 2

确认页面.显示”Back”和”Apply” 按钮.

SUMMARY = 3

通知用户设置生效.只显示”Close” 按钮.

PROGRESS = 4

进度条页面，用来执行耗时任务，会锁定Assistant直到任务完成
只会显示”back” 按钮

CUSTOM = 5

自定义页面，不显示任何按钮。可以使用Gtk.Assistant.add_action_widget(child)方法来添加按钮.

代码下载地址：http://download.youkuaiyun.com/detail/a87b01c14/9594728