Chapter 47. Notebooks

Inheritance Hierarchy

Object
   +--- Widget
         +--- Container
               +--- Notebook
         

The NoteBook Widget is a collection of "pages" that overlap each other, each page contains different information with only one page visible at a time. This widget has become more common lately in GUI programming, and it is a good way to show blocks of similar information that warrant separation in their display.

The first function call you will need to know, as you can probably guess by now, is used to create a new notebook widget.

$notebook = new Gtk::Notebook();

Once the notebook has been created, there are a number of functions that operate on the notebook widget. Let's look at them individually.

The first one we will look at is how to position the page indicators. These page indicators or "tabs" as they are referred to, can be positioned in four ways: top, bottom, left, or right.

$notebook->set_tab_pos( $position );

Where $position will be one of the following, which are pretty self explanatory:

'left'
'right'
'top'
'bottom'

The default is 'top' .

Next we will look at how to add pages to the notebook. There are three ways to add pages to the NoteBook. Let's look at the first two together as they are quite similar.

$notebook->append_page( $child, $tab_label );

$notebook->prepend_page( $child, $tab_label );

These functions add pages to the notebook by inserting them from the back of the notebook (append), or the front of the notebook (prepend). $child is the widget that is placed within the notebook page, and $tab_label is the label for the page being added. The $child widget must be created separately, and is typically a set of options setup within one of the other container widgets, such as a packing box or table.

The final function for adding a page to the notebook contains all of the properties of the previous two, but it allows you to specify what position you want the page to be in the notebook.

$notebook->insert_page( $child, $tab_label, $position );

The parameters are the same as append() and prepend() except it contains an extra parameter, $position. This parameter is used to specify what place this page will be inserted into, with the first page having a position of zero.

Now that we know how to add a page, lets see how we can remove a page from the notebook.

$notebook->remove_page( $page_num );

This function takes the page specified by $page_num and removes it from the notebook.

To find out what the current page is in a notebook use the function:

$notebook->get_current_page();

And to find out what page number a page is, use:

$notebook->page_num( $child );

This function will return a -1 if $child isn't a page in $notebook.

If you want to change a child's page number, you may do so with:

$notebook->reorder_child( $child, $position );

These next two functions are simple calls to move the notebook page forward or backward. Simply provide the respective function call with the notebook widget you wish to operate on. Note: When the NoteBook is currently on the last page, and next_page() is called, the notebook will wrap back to the first page. Likewise, if the NoteBook is on the first page, and prev_page() is called, the notebook will wrap to the last page.

$notebook->next_page();

$notebook->prev_page();

This next function sets the "active" page. If you wish the notebook to be opened to page 5 for example, you would use this function. Without using this function, the notebook defaults to the first page.

$notebook->set_page( $page_num );

The next two functions add or remove the notebook page tabs and the notebook border respectively.

$notebook->set_show_tabs( $show_tabs );

$notebook->set_show_border( $show_border );

The next function is useful when the you have a large number of pages, and the tabs don't fit on the page. It allows the tabs to be scrolled through using two arrow buttons.

$notebook->set_scrollable( $scrollable );

The border width around the bookmarks may be set using:

$notebook->set_tab_border( $border_width );

Also, you can decide whether all the tabs are the same size or not using:

$notebook->set_homogeneous_tabs( $homogeneous );

Where $homogeneous may be a true or false value.

47.1. Notebook Example

Now let's look at an example, it is expanded from the testgtk.c code that comes with the GTK distribution. This small program creates a window with a notebook and six buttons. The notebook contains 11 pages, added in three different ways, appended, inserted, and prepended. The buttons allow you to rotate the tab positions, add/remove the tabs and border, remove a page, change pages in both a forward and backward manner, and exit the program.

Notebook Example Source

      
#!/usr/bin/perl -w

use 
Gtk
;
use 
strict
;

set_locale Gtk;
init Gtk;


my
 $false = 0;

my
 $true = 1;


my
 $window;

my
 $button;

my
 $table;

my
 $notebook;

my
 $frame;

my
 $label;

my
 $checkbutton;


my
 $bufferf;

my
 $bufferl;


# Create the window
$window = new Gtk::Window( "toplevel" );
$window->signal_connect( "delete_event", 
sub
 { Gtk->
exit
( 0 ); } );
$window->border_width( 10 );

$table = new Gtk::Table( 3, 6, $false );
$window->add( $table );

# Create a new notebook, place the position of the tabs
$notebook = new Gtk::Notebook();
$notebook->set_tab_pos( 'top' );
$table->attach_defaults( $notebook, 0, 6, 0, 1 );
$notebook->show();

# Let's append a bunch of pages to the notebook

for
 
my
 $i ( 0..4 )
{
   $bufferf = "Append Frame " . ( $i + 1 );
   $bufferl = "Page " . ( $i + 1 );

   $frame = new Gtk::Frame( $bufferf );
   $frame->border_width( 10 );
   $frame->set_usize( 100, 75 );
   $frame->show();

   $label = new Gtk::Label( $bufferf );
   $frame->add( $label );
   $label->show();

   $label = new Gtk::Label( $bufferl );
   $notebook->append_page( $frame, $label );
}

# Now let's add a page to a specific spot
$checkbutton = new Gtk::CheckButton( "Check me please!" );
$checkbutton->set_usize( 100, 75 );
$checkbutton->show();

$label = new Gtk::Label( "Add Page" );
$notebook->insert_page( $checkbutton, $label, 2 );

# Now finally let's prepend pages to the notebook

for
 
my
 $i ( 0..4 )
{
   $bufferf = "Prepend Frame " . ( $i + 1 );
   $bufferl = "Page " . ( $i + 1 );

   $frame = new Gtk::Frame( $bufferf );
   $frame->border_width( 10 );
   $frame->set_usize( 100, 75 );
   $frame->show();

   $label = new Gtk::Label( $bufferf );
   $frame->add( $label );
   $label->show();

   $label = new Gtk::Label( $bufferl );
   $notebook->prepend_page( $frame, $label );
}

# Set what page to start at (page 4)
$notebook->set_page( 3 );

# Create a bunch of buttons
$button = new Gtk::Button( "Close" );
$button->signal_connect( "clicked", 
sub
 { Gtk->
exit
( 0 ); } );
$table->attach_defaults( $button, 0, 1, 1, 2 );
$button->show();

$button = new Gtk::Button( "Next Page" );
$button->signal_connect( "clicked", 
sub
 { $notebook->next_page(); } );
$table->attach_defaults( $button, 1, 2, 1, 2 );
$button->show();

$button = new Gtk::Button( "Prev Page" );
$button->signal_connect( "clicked", 
sub
 { $notebook->prev_page(); } );
$table->attach_defaults( $button, 2, 3, 1, 2 );
$button->show();

$button = new Gtk::Button( "Tab Position" );
$button->signal_connect( "clicked", \&rotate_book, $notebook );
$table->attach_defaults( $button, 3, 4, 1, 2 );
$button->show();

$button = new Gtk::Button( "Tabs/Border On/Off" );
$button->signal_connect( "clicked", \&tabsborder_book, $notebook );
$table->attach_defaults( $button, 4, 5, 1, 2 );
$button->show();

$button = new Gtk::Button( "Remove Page" );
$button->signal_connect( "clicked", \&remove_book, $notebook );
$table->attach_defaults( $button, 5, 6, 1, 2 );
$button->show();

$table->show();
$window->show();
main Gtk;

exit
( 0 );



### Subroutines


# This function rotates the position of the tabs


sub
 
rotate_book

{
   
my
 ( $button, $notebook ) = @_;

   
my
 %rotate = ( top    => 'right',
		  right  => 'bottom',
		  bottom => 'left',
		  left   => 'top' );

   $notebook->set_tab_pos( $rotate{ $notebook->tab_pos } );
}


# Add/Remove the page tabs and the borders


sub
 
tabsborder_book

{
   
my
 ( $button, $notebook ) = @_;

   
my
 $tval = $false;
   
my
 $bval = $false;

   
if
 ( $notebook->show_tabs == 0 )
   {
      $tval = $true;
   }
   
if
 ( $notebook->show_border == 0 )
   {
      $bval = $true;
   }

   $notebook->set_show_tabs( $tval );
   $notebook->set_show_border( $bval );
}


# Remove a page from the notebook


sub
 
remove_book

{
   
my
 ( $button, $notebook ) = @_;

   
my
 $page;

   $page = $notebook->get_current_page();
   $notebook->remove_page( $page );

   # Need to refresh the widget -- This forces the widget to redraw itself.
   $notebook->draw( undef );
}



# END EXAMPLE PROGRAM
      
   

Notebook Example Screenshot