18.1.1.1. Gtk2::Actions

An Gtk2::Action object represents an action that the user can take using an application user interface. It contains information used by proxy UI elements (for example, Gtk2::MenuItems or Gtk2::Toolbar items) to present the action to the user.There are two subclasses of Gtk2::Action:

For example, the standard File->Quit menu item can be represented with an icon, mnemonic text and accelerator. When activated, the menu item triggers a callback that could exit the application. Likewise a Gtk2::Toolbar Quit button could share the icon, mnemonic text and callback. Both of these UI elements could be proxies of the same Gtk2::Action.

Although it is possible to create an instance of Gtk2::Action, or its subclasses, we use the available methods of Gtk2::ActionGroup to create and add the Gtk2::Action instances to a Gtk2::ActionGroup instance. This is because we will use the Gtk2::Action instances mostly as part of a Gtk2::ActionGroup. We also have the ability to extract required Gtk2::Action's from a Gtk2::ActionGroup.

18.1.1.2. Gtk2::ActionGroups

Gtk2::Action objects should be part of an Gtk2::ActionGroup to provide common control over their visibility and sensitivity. For example, in a text processing application the menu items and toolbar buttons for specifying the text justification could be contained in an Gtk2::ActionGroup. A user interface is expected to have multiple Gtk2::ActionGroup objects that cover various aspects of the application. For example, global actions like creating new documents, opening and saving a document and quitting the application likely form one Gtk2::ActionGroup while actions such as modifying the view of the document would form another.

18.1.1.3. Adding Actions to an Actiongroup

The following sections will deal with ways to add the three action types to an Gtk2::ActionGroup.

18.1.1.3.1. Plain Jane actions

When we want to add actions, we need to declare an array first. This array will contain list elements. The data in those list elements will be used to create the actions in the Gtk2::ActionGroup. In the following snippet of code we supply the data for two action items. Please see the comments on what each field of the list elements in the array represent.

my @actions_plain = (
	# name,      stock id,  label,    accelerator,  tooltip, callback
	["FileMenu",	 	#name of the action. Must be specified.
	
	undef,			#stock id for the action. Optional, default 
				#value of undef if a label is specified.
				
	"_File",		#label for the action.Optional, default 
				#value of undef if a stock id is specified.
				
	undef,			#accelerator for the action
	undef,			#tooltip for the action. Optional, default value of undef.
	
	undef,			#callback invoked when the action is activated.
				#Optional, default value of undef.
	],
	
	#same as above, just in one line :)
	[ "New",    'gtk-new',  "_New",   "<control>N", "Create a new file", \&activate_action ],
);

The order of items in the array does not matter, since the structure of where which item will eventually be displayed will be determined by the UI XML descriptions added to the Gtk2::UIManager. It makes sense though to keep them more or less logically grouped. The name field must be unique, and will be used in the XML descriptions to indicate which Gtk2::Action we want to tie to the XML element.

To create the Gtk2::Action instances, and add it to the Gtk2::ActionGroup we use the 'add_actions' method referencing our array of items. Optionally we can supply a second argument with user data.

$action_group->add_actions(\@actions_plain, undef);

my @toggle_actions = (
	 
	["Show_hidden", 	#name of the action. Must be specified.
	
	undef,			#stock id for the action. Optional, default 
				#value of undef if a label is specified.
				
	"_Show hidden files",	#label for the action.Optional, default 
				#value of undef if a stock id is specified.
				
	undef,			#accelerator for the action
	undef,			#tooltip for the action. Optional, default value of undef.
	
	undef,			#callback invoked when the action is activated.
				#Optional, default value of undef.
				
	TRUE,			#is active. Optional, default value is FALSE
	],
	
);

$action_group->add_toggle_actions(\@toggle_actions, undef);

use constant COLOR_RED   => 0;
use constant COLOR_GREEN => 1;
use constant COLOR_BLUE  => 2;

my @color_entries = (
  # name,    stock id, label,    accelerator,  tooltip, value 
  [ "Red",   undef,    "_Red",   "<control>R", "Blood", COLOR_RED   ],
  [ "Green", undef,    "_Green", "<control>G", "Grass", COLOR_GREEN ],
  [ "Blue",  undef,    "_Blue",  "<control>B", "Sky",   COLOR_BLUE  ],
);

$actions->add_radio_actions (\@color_entries, COLOR_RED,
                                   \&activate_radio_action);

my ($action, $current) = @_;

18.1.1.4. Managing actions.

The Gtk2::ActionGroup class has a methods to control the sensitivity and visibility of all the Gtk2::Actions in it. They are the 'set_sensitive' and 'set_visible' methods respectively.

The above methods are also available on a "per action" instance. You can get actions from a Gtk2::ActionGroup by using the 'get_action' method. You may also want to remove actions by using the 'remove_action' method. Consult the man page for more detail.

18.1.3.1. The Screenshot.

18.1.3.2. The Code.

The program can be found here: 'gtk2_uimanager.pl'

 #! /usr/bin/perl -w
 
 use strict;
 use Gtk2 '-init';
 use Glib qw/TRUE FALSE/; 
 
 #===========================================================
 #Declare all the data first, to keep it away from the part 
 #containing the widgets.
 
 #--------------------------
 my @entries = (
   #Fields for each action item:
   #[name, stock_id, value, label, accelerator, tooltip, callback]
   
   #file menus  
   [ "FileMenu",undef,"_File"],
   [ "New",    'gtk-new',  "_New",   "<control>N", "Create a new file", \&activate_action ],
   [ "Open",   'gtk-open', "_Open",  "<control>O", "Open a file",       \&activate_action ],
   [ "Quit",   'gtk-quit', "_Quit",  "<control>Q", "Quit",              \&activate_action ],
   
   #Media menus
   [ "Media",undef,"_Media"],
   [ "media_optical",'gtk-cdrom', "_Optical"],
   
 );
 #--------------------------
 
 use constant CD_R_M   	=> 0;
 use constant CD_R_P   	=> 1;
 use constant CD_RW_M	=> 3;
 use constant CD_RW_P	=> 4;
 
 my @cd_types = (
 
   #Fields for each radio-action item:
   #[name, stock_id, value, label, accelerator, tooltip, value]
 
 [ "cd_r_m",   undef, "CD-R",  undef, "CD-R media", CD_R_M  ],
 [ "cd_r_p",   undef, "CD+R",  undef, "CD+R media", CD_R_P  ],
 [ "cd_rw_m",   undef, "CD-RW",  undef, "CD-RW media", CD_RW_M  ],
 [ "cd_rw_p",   undef, "CD+RW",  undef, "CD+RW media", CD_RW_P  ],
 
 );
 #--------------------------
 
 use constant DVD_R_M   	=> 5;
 use constant DVD_R_P   	=> 6;
 use constant DVD_RW_M	=> 7;
 use constant DVD_RW_P	=> 8;
 
 my @dvd_types = (
 
 [ "dvd_r_m",   undef, "DVD-R",  undef, "DVD-R media", DVD_R_M  ],
 [ "dvd_r_p",   undef, "DVD+R",  undef, "DVD+R media", DVD_R_P  ],
 [ "dvd_rw_m",   undef, "DVD-RW",  undef, "DVD-RW media", DVD_RW_M  ],
 [ "dvd_rw_p",   undef, "DVD+RW",  undef, "DVD+RW media", DVD_RW_P  ],
 
 );
 #--------------------------
 #
 #===========================================================
 #Declare the two XML structures, one contains the basics
 #the other one contains the elements for the DVD
 
 my $ui_basic = "<ui>
   <menubar name='MenuBar'>
     <menu action='FileMenu'> 
      <menuitem action='New' position='top'/>
      <menuitem action='Open' position='top'/>
      <separator/>
      <menuitem action='Quit'/>
     </menu>
     <menu action='Media'> 
      <menu action='media_optical'>
      		<menuitem  action='cd_r_m'/>
       		<menuitem action='cd_r_p'/>
       		<menuitem  action='cd_rw_m'/>
       		<menuitem  action='cd_rw_p'/>
       	</menu>
     </menu>
    </menubar>
    <toolbar name='Toolbar'>
    	<placeholder name='optical'>
 		<separator/>
       		<toolitem  action='cd_r_m'/>
       		<toolitem action='cd_r_p'/>
       		<toolitem  action='cd_rw_m'/>
       		<toolitem  action='cd_rw_p'/>
       </placeholder>   
    </toolbar>
 </ui>";
 
 my $ui_dvd = "<ui>
   <menubar name='MenuBar'>
     <menu action='Media'> 
      <menu action='media_optical'>
      		<menuitem  action='dvd_r_m'/>
       		<menuitem action='dvd_r_p'/>
       		<menuitem  action='dvd_rw_m'/>
       		<menuitem  action='dvd_rw_p'/>
       </menu>
     </menu>
    </menubar>
    <toolbar name='Toolbar'>
       <placeholder name='optical'>
       		<toolitem  action='dvd_r_m'/>
       		<toolitem action='dvd_r_p'/>
       		<toolitem  action='dvd_rw_m'/>
       		<toolitem  action='dvd_rw_p'/>
       </placeholder>
    </toolbar>
 </ui>";
 #===========================================================
 
 #standard window creation, placement, and signal connecting
 my $window = Gtk2::Window->new('toplevel');
 $window->signal_connect('delete_event' => sub { Gtk2->main_quit; });
 $window->set_border_width(5);
 $window->set_position('center_always');
 
 #this vbox will return the bulk of the gui
 my $vbox = &ret_vbox();
 
 #add and show the vbox
 $window->add($vbox);
 $window->show();
 
 #our main event-loop
 Gtk2->main();
 
 sub ret_vbox {
 
 #Flag indicating if the DVD was added or not
 my $merge_flag = 0;
 
 my $vbox = Gtk2::VBox->new(FALSE,5);
 $vbox->set_size_request (600, 200);
 
 #===========================================================
 #This part has to do with the Gtk2::UIManager:
 
 	# Create a Gtk2::UIManager instance	
 	my $uimanager = Gtk2::UIManager->new;
 	
 	#________
 		#extract the accelgroup and add it to the window
 		my $accelgroup = $uimanager->get_accel_group;
   		$window->add_accel_group($accelgroup);
 		
 	#________
 		# Create the basic Gtk2::ActionGroup instance
 		#and fill it with Gtk2::Action instances
 		my $actions_basic = Gtk2::ActionGroup->new ("actions_basic");
 		$actions_basic->add_actions (\@entries, undef);
 	
 	# Add the actiongroup to the uimanager	
 	$uimanager->insert_action_group($actions_basic,0);
 	
 	#________	
 		# Create the CD Gtk2::ActionGroup instance
 		#and fill it with Gtk2::RadioAction instances
 		my $actions_media_cd = Gtk2::ActionGroup->new ("media_cd");
 		$actions_media_cd->add_radio_actions(\@cd_types,CD_R_M,undef);
 		
 		#get the group, this will be needed when we add radio actions
 		my $group = ($actions_media_cd->get_action('cd_r_m'))->get_group;
 	
 	# Add the actiongroup to the uimanager		
 	$uimanager->insert_action_group($actions_media_cd,0);
 	
 	#________	
 		# Create the DVD Gtk2::ActionGroup instance
 		#and fill it with Gtk2::RadioAction instances
 		my $actions_media_dvd = Gtk2::ActionGroup->new ("media_dvd");
 		$actions_media_dvd->add_radio_actions(\@dvd_types,CD_R_M,undef);
 	
 		#run through the DVD types list, getting each action,
 		#and set its group ans state
 		foreach my $name (@dvd_types){
 	
 			my $action = $actions_media_dvd->get_action(${$name}[0]);
 			#here we use the group :)
 			$action->set_group($group);
 			#need to specify, else we will have TWO ACTIVE radio buttons
 			$action->set_active(FALSE);
 		}
 			
 	# Add the actiongroup to the uimanager
 	$uimanager->insert_action_group($actions_media_dvd,0);
 	
 	#________
 	#add the basic XML description of the GUI
 	$uimanager->add_ui_from_string ($ui_basic);
 	
 	#________
 	#extract the menubar
 	my $menubar = $uimanager->get_widget('/MenuBar');
 	
 $vbox->pack_start($menubar,FALSE,FALSE,0);
 
 	#________
 	#extract the toolbar
 	my $toolbar = $uimanager->get_widget('/Toolbar');
 	$toolbar->set_show_arrow(FALSE);
 	
 	#Create a menu tool button and set its menu to the opticals.
 		my $t_mbtn_optical = Gtk2::MenuToolButton->new_from_stock('gtk-cdrom');
 		$t_mbtn_optical->set_label('Optical');
 			
 			#the UIManager created an Gtk2::ImageMenuItem, we extract it and
 			#use its 'get_submenu' to get its attached menu widget :)
 			my $menu_item = $uimanager->get_widget('/MenuBar/Media/media_optical');
 		$t_mbtn_optical->set_menu ($menu_item->get_submenu);
 								
 	$toolbar->insert($t_mbtn_optical,0);
 	$toolbar->insert(Gtk2::SeparatorToolItem->new,1);
 #===========================================================
 	
 $vbox->pack_start($toolbar,FALSE,FALSE,0);
 
 	my $h_bb = Gtk2::HButtonBox->new;
 	$h_bb->set_layout('edge');
 	
 		my $cb_sensitive = Gtk2::CheckButton->new('CD Sensitive');
 		$cb_sensitive->set_active(TRUE);
 		$cb_sensitive->signal_connect('toggled' =>sub{
 			#sets the sensitivity of the CD menus
 			$actions_media_cd->set_sensitive($cb_sensitive->get_active);
 		});
 		
 	$h_bb->pack_start_defaults($cb_sensitive);
 	
 		my $cb_visible = Gtk2::CheckButton->new('CD Visible');
 		$cb_visible->set_active(TRUE);
 		$cb_visible->signal_connect('toggled' =>sub{
 			#set the visibility of the CD menus
 			$actions_media_cd->set_visible($cb_visible->get_active);
 		});
 		
 	$h_bb->pack_start_defaults($cb_visible);
 	
 		my $cb_dvd = Gtk2::CheckButton->new('Add a DVD Writer');
 		$cb_dvd->signal_connect('toggled' =>sub {
 		#this will add or remove the DVD ui descriptions
 		#it returns a number greater than 0 if successful
 			if ($merge_flag){
 				$uimanager->remove_ui($merge_flag);
 				$merge_flag = 0;
 			}else{
 				$merge_flag = $uimanager->add_ui_from_string ($ui_dvd);
 			}
 		});
 		
 	$h_bb->pack_start_defaults($cb_dvd);
 
 $vbox->pack_end($h_bb,FALSE,FALSE,0);	
 $vbox->show_all();
 return $vbox;
 }

18.1.3.3. Points of interest.

• It is good practice to keep the data separate from the rest of the code. In our program we start of declaring data that will be used to generate the Gtk2::Action instances in various Gtk2::ActionGroups later in the program.

• We also declare two XML structures which will be used by our program. A basic one and one that will merge with the basic one when we simulate the addition of a DVD Writer.

  When two XML structures merge, the one added last's elements will be added as siblings to the first one's elements. You can force position and grouping of widgets by making use of the position attribute, as well as the placeholder element.

  The position attribute will normally be used to keep certain Gtk2::MenuItems at the top, or buttom. The placeholder element can be used to group together Gtk2::RadioToolButton items in a Gtk2::Toolbar.

• The widget hierarchy created using a UI description is very similar to the XML element hierarchy except that placeholder elements are merged into their parents.

  A widget in the hierarchy created by a UI description can be accessed using its path which is composed of the name of the widget element and its ancestor elements joined by slash ("/") characters.

  This is used as a argument to the get_widget method of Gtk2::UIManager:

  211 		#the UIManager created an Gtk2::ImageMenuItem, we extract it and
  212 		#use its 'get_submenu' to get its attached menu widget :)
  213 		my $menu_item = $uimanager->get_widget('/MenuBar/Media/media_optical');
  214 	$t_mbtn_optical->set_menu ($menu_item->get_submenu);

  Remember to include placeholder elements in the path! We use the XML element hierarchy, and NOT the widget hierarchy as a path for the get_widget method.

• Remember to extract the group of a Gtk2::RadioAction instance if you later want to append items to that group of Gtk2::RadioAction's.

  166 	#get the group, this will be needed when we add radio actions
  167 	my $group = ($actions_media_cd->get_action('cd_r_m'))->get_group;

  Make sure when you append to set the active attribute of each new addition to FALSE, else you can end up with a set of radio buttons containing two active ones at the same time!

  178 	#run through the DVD types list, getting each action,
  179 	#and set its group ans state
  180 	foreach my $name (@dvd_types){
  181 	
  182 		my $action = $actions_media_dvd->get_action(${$name}[0]);
  183 		#here we use the group :)
  184 		$action->set_group($group);
  185 		#need to specify, else we will have TWO ACTIVE radio buttons
  186 		$action->set_active(FALSE);
  187 	}

• You can disable the option to the user to select certain items in the gui using various ways. In the sample program we used three different ways. ( Visibility, sensitivity, and the merging / removing of XML UI descriptions.) When to use which method is for the programmer to decide.

• Methods used to add a XML UI description returns an integer value. This value can be used again when you want to remove the XML UI description.

  247 	if ($merge_flag){
  248 		$uimanager->remove_ui($merge_flag);
  249 		$merge_flag = 0;
  250 	}else{
  251 		$merge_flag = $uimanager->add_ui_from_string ($ui_dvd);
  252 	}

• The widgets that you extract from the Gtk2::UIManager instance is standard, and can be used in any normal way. In the demo program, we added a Gtk2::MenuToolButton and Gtk2::SeparatorToolItem to it.