PHP Archive

Adding, Moving, and Removing Notebook Pages

Each page of a notebook has two elements: the tab and the content. The page tab is usually a string that describes the contents of the page. The tab is the main method by which a user will select a page. The content of the page can be anything. Usually, the content that is added directly to the page is some sort of container.

A page can be added at the beginning of a notebook, at the end of a notebook, or anywhere in between using the methods prepend_page, append_page, and insert_page, respectively. All require a widget for the page body and a widget for the page tab. In Listing 6-6, several pages are appended to the notebook. Each page is added in turn to the back of the notebook with append_page. The pages could have just as easily been added to the front of the notebook with prepend_page. To insert a page in any arbitrary position, use insert_page, passing the body widget, the tab widget, and the page position. Pages are indexed starting from 0, so the first page in the notebook is actually page 0.

When a page is added to a GtkNotebook widget, its page index is returned. The value returned from append_page is always the total number of pages minus one. The return value from prepend_page is always 0. The return value from insert_page is not always the same as the position passed to it. If a page is inserted with a position of 12 but there are only eight pages in the notebook, the new page will be added as the last page. The page indexes are always collapsed. For example, the newly inserted page may be inserted in position 12, but it will immediately be moved to position 8. If no position value is passed to insert_page, the position will default to -1, which means the page should be appended to the back of the notebook. The value that will be returned will be the same as if append_page were used.

Knowing the page index is useful because you can use it to retrieve a page from the notebook. Listing 6-6 uses the get_nth_page method to return the page body widget after it has been added to the notebook. This is done to make accessing the page contents easier later on.

Once the page is found, it can then be used to grab the label or the label text. get_tab_label takes a notebook child, usually returned by get_nth_page, and returns the tab widget. get_tab_label_text will return just the text string for the same page if passed the same child widget. Just as you can get a tab label or its text, you can set a tab label or its text. set_tab_label and set_tab_label_text work in much same way as their get counterparts. Each expects a widget that has already been prepended, appended, or inserted into the notebook as the first argument and either a tab widget or a string of text to be set as the tab label. The index of a page is the key to being able to make changes.

Tip To get the total number of pages, use get_n_pages. Keep in mind that this is the total number of pages, not the index of the last page. The index of the last page is get_n_pages() - 1.

While the index of a page is the key to accessing the page, the index may change. If a new page is prepended or inserted in front of a given page, the index will be incremented. If a page in front of a given page is removed or moved to the back of the notebook, the page's index will be decremented. To get the index of a specific child, use the page_num method. page_num takes a widget as the only argument and returns the page index. Regrabbing the index this way comes in handy when pages in the notebook are moved.

You can reorder pages by using the reorder_child method. reorder_child takes the child given as the first argument and puts it in the position given by the second argument. The page that previously occupied the position will be moved backward in the notebook. If the position passed to reorder_child is greater than the total number of pages, the page will be moved to the back of the notebook.

You can also remove pages from the notebook. To do this, call remove_page and pass the page index.

Whenever either the reorder_child or remove_page method is called, the pages are rein-dexed. This means, for example, that the page that was previously in position 5 may now be in position 4, 5, or 6, even though that particular page was never moved. Because of this reindexing, the code in Listing 6-6 uses a separate array with associative keys to keep track of the pages. Without this separate array, finding a particular page may require cycling through all the pages in the notebook.