Xfce Foundation Classes

You can retrieve the selection_data as a vector of supported targets. This can be used to interpret the results of getting the standard "TARGETS" target that is always supplied for any selection.

bool
get_targets(std::vector<Gdk::Atom>& targets) const;

 

bool get_targets(std::vector<String>& targets) const;

The first get_targets() function retrieves the targets as a vector of Gdk::Atom. The second retrieves the target names as a vector of String.

The following function returns true if the length of the selection data is greater than 0.

bool is_valid() const;

You can connect directly to the "selection_received" signal with the following code:

widget->signal_selection_received().connect(sigc::mem_fun(this,
&MyClass::selection_received_handler));

where the "selection_received" signal handler has the following prototype:

void
MyClass::selection_received_handler(const
Gtk::SelectionData& selection_data, unsigned int time);

Supplying the selection

Being the owner of a selection is a bit more complicated and only makes sense when there is data for transmission. Data can exist in a variety of formats so first you have to define the targets that correspond to these formats. You are free to come up with target names yourself but this is only useful within the same application. Therefore, a number of standard targets have been agreed upon. A list of targets and information on their use can be found in the ICCCM. The targets MULTIPLE, TARGETS and TIMESTAMP are defined by
X11 architecture as mandatory and are automatically provided by GTK+.

To define the supported target(s) for a certain selection and widget use one of the following Gtk::Widget methods:

void selection_add_target(Gdk::Atom
selection, Gdk::Atom target, unsigned int info);

 

void selection_add_target(Gdk::Atom selection, const
Gtk::TargetEntry& entry);

 

void selection_add_targets(Gdk::Atom selection, const
std::vector<Gtk::TargetEntry>& targets);

The 'selection' argument is the atom corresponding to the selection for which the target(s) will be registered, the 'target' argument is the atom corresponding to the target name you want to register and the 'info' argument is a unique integer id that will be passed back through signals later on. The first two methods register a single target. The second method takes a Gtk::TargetEntry rather than separate target and info arguments. The last method lets you register multiple targets at once by passing a vector of Gtk::TargetEntry.

You can create a new TargetEntry object with one of the following constructors:

TargetEntry();

 

TargetEntry(const String& target_name, unsigned int unique_id,
Gtk::TargetFlagsField drag_flags = 0);

The first constructor creates an empty TargetEntry. The second constructor creates a target entry with the specified name and unique id. The 'target_name' argument is a string corresponding to the target atom and 'unique_id' is the unique integer id. The 'drag_flags' argument is only used when implementing Drag and Drop. It restricts the validity of the corresponding target to the same application or the same widget.

If you create an empty TargetEntry, you can set its target_name and unique_id by calling the Gtk::TargetEntry method:

void set(const String& target_name,
unsigned int unique_id, Gtk::TargetFlagsField drag_flags = 0);

The 'target_name' is the string corresponding to the target atom and unique_id is the unique integer id. The 'drag_flags' argument is used to restrict the validity of the corresponding target and can either be Gtk::TARGET_SAME_APP or Gtk::TARGET_SAME_WIDGET.

Now the targets have been registered, when prompted by the user you need to take ownership of a certain selection. This is done with the following Gtk::Widget method:

bool selection_owner_set(Gdk::Atom
selection, unsigned int time, const Gdk::Display *display = 0);

The 'selection' argument is the atom corresponding the selection for which the owner should be changed, 'time' is a timestamp with which to claim the selection, or GDK_CURRENT_TIME. The 'display' is the Gdk::Display where the selection is set, or null for the default display. If the return value is true the calling widget owns the selection.

If you need to check whether a widget owns a certain selection you can call the Gtk::Widget accessor:

bool selection_owner_get(Gdk::Atom
selection);

The 'selection' is an interned atom representing the selection to check. The return value is true if the calling widget owns the specified selection.

To be able to respond to a Gtk::Widget::selection_convert() request, you must either connect to the "selection_get" signal or derive a new class for the selection widget and override the Gtk::WidgetSignals::on_selection_get() virtual signal handler.

To connect to the "selection_get" signal, use the following code:

widget->signal_selection_get().connect(sigc::mem_fun(this,
&MyClass::selection_get_handler));

The selection_get handler has the following prototype:

void
MyClass::selection_get_handler(Gtk::SelectionData& selection_data,
unsigned int info, unsigned int time);

The 'selection_data' is the SelectionData object to be filled in, 'info' is the info integer that was set when the target was registered, and 'time' is the time of the conversion request as set by the requestor with Gtk::Widget::selection_convert().

When the "selection_get" signal returns, the widget requesting the selection will receive the selection_data. You must call the following Gtk::SelectionData methods to set the selection_data fields:

void set(Gdk::Atom type, int format,
const void *data, int length);

      

bool set_text(const String& str);

These methods should only be called from a selection handler callback. The 'type' argument is an atom that describes the 'data' provided and the 'format' is the number of bits required to store one element of the target type. Usually it will be 8 for a character or 32 for an integer. The most commonly used target types are: ATOM, COMPOUND_TEXT, INTEGER and STRING. This method takes care of properly making a copy of the data so that you don't have to worry about keeping it around. The length argument is the data length. The data should be null-terminated.

For convenience, the set_text() method sets the contents of the selection from a UTF-8 encoded string. The string is converted to the form determined by the target and true is returned if the selection was successfully set.

If another application claims ownership of the selection, you will receive a "selection_clear_event" signal. To explicitly release ownership of a selection call the following Gtk::Widget method:

bool selection_owner_unset(Gdk::Atom
selection, unsigned int time, const Gdk::Display *display = 0);

The 'selection' argument is an interned atom representing the selection to release, 'time' is a timestamp, or GDK_CURRENT_TIME and 'display' is the Gdk::Display where the selection is set, or null for the default display. True is returned if the operation succeeded.

Selection Example

In the following example, we retrieve the special target "TARGETS", which is a list of all targets into which the selection can be converted.

The header file for the selection example is <selection.hh>:

#include <xfc/main.hh>

#include <xfc/gtk/entry.hh>

#include <xfc/gtk/selection.hh>

#include <xfc/gtk/togglebutton.hh>

#include <xfc/gtk/togglebuttonsignals.hh>

#include <xfc/gtk/invisible.hh>

#include <xfc/gtk/widgetsignals.hh>

#include <xfc/gtk/dialog.hh>

      

using namespace Xfc;

      

// RetrieveSelectionButton

      

class RetrieveSelectionButton : public Gtk::Button, protected
Gtk::WidgetSignals

{

protected:

    void on_get_target(Gtk::Entry *entry);

    virtual void on_selection_received(const
Gtk::SelectionData& selection_data, unsigned int time);

      

public:

    RetrieveSelectionButton(Gtk::Entry *entry);

    virtual ~RetrieveSelectionButton();

};

      

// SupplySelectionButton

      

class SupplySelectionButton : public Gtk::ToggleButton, protected
Gtk::ToggleButtonSignals

{

    static std::vector<Gtk::TargetEntry>
target_entries;

    

    Gtk::Invisible *selection_widget;

    String target_string;

      

protected:

    virtual void on_toggled();

    void selection_get(Gtk::SelectionData&
selection_data, unsigned int info, unsigned int time);

    bool selection_clear_event(const
Gdk::EventSelection& event);

      

public:

    SupplySelectionButton();

    virtual ~SupplySelectionButton();

};

      

// SelectionTest

      

class SelectionTest : public Gtk::Dialog

{

public:

    SelectionTest();

    virtual ~SelectionTest();

};

and the source file is <selection.cc>:

#include "selection.hh"

#include <xfc/gtk/box.hh>

#include <xfc/gtk/buttonbox.hh>

#include <xfc/gtk/label.hh>

#include <iostream>

      

std::vector<Gtk::TargetEntry>
SupplySelectionButton::target_entries;

      

enum

{

    STRING,

    LENGTH

};

      

// RetrieveSelectionButton

      

RetrieveSelectionButton::RetrieveSelectionButton(Gtk::Entry *entry)

: Gtk::WidgetSignals(this)

{

    set_label("Retrieve Selection");

  
 signal_clicked().connect(sigc::bind(sigc::mem_fun(this,
&RetrieveSelectionButton::on_get_target), entry));

}

      

RetrieveSelectionButton::~RetrieveSelectionButton()

{

}

      

void

RetrieveSelectionButton::on_get_target(Gtk::Entry *entry)

{

    // Get the atom corresponding to the target string
entered into the entry widget.

    Gdk::Atom target_atom =
gdk_atom_intern(entry->get_text().c_str(), FALSE);

        

    // And request the target for the primary selection.

    selection_convert(GDK_SELECTION_PRIMARY,
target_atom);

}

      

void

RetrieveSelectionButton::on_selection_received(const
Gtk::SelectionData& selection_data, unsigned int time)

{

    using namespace std;

      

    // Print out the values of the selection_data
members.

    cout << endl << "The values returned by
the Gtk::SelectionData members are..." << endl;

    cout << " * selection() = " <<
selection_data.get_selection() << endl;

    cout << " * target() = " <<
selection_data.get_target() << endl;

    cout << " * type() = " <<
selection_data.get_type() << endl;

    cout << " * format() = " <<
selection_data.format() << endl;

    cout.setf(ios_base::hex, ios_base::basefield);

    cout << " * data() = 0x" <<
reinterpret_cast<unsigned int>(selection_data.data()) <<
endl;

    cout.setf(ios_base::dec, ios_base::basefield);

    cout << " * length() = " <<
selection_data.length() << endl << endl;

    

    // IMPORTANT - Check to see if any data was returned.

    if (!selection_data.is_valid())

    {

        cout << "Couldn't get the
target's data." << endl;

        return;

    }

      

    if (selection_data.get_target() == "TARGETS")

    {

        cout << "The targets
supported by the \"" << selection_data.get_selection();

        cout << "\" selection
are..." << endl;

      

        // Retrieve the target names as a
vector of String

        std::vector<String>
atom_names;

        if
(!selection_data.get_targets(atom_names))

            return;

      

        // Print out the names

        int count = atom_names.size();

        for (int i = 0; i < count; i++)

        {

            cout <<
" * " << atom_names[i] << endl;

        }

    }

    else if (selection_data.get_target() == "STRING")

    {

        cout << "The 'STRING' data
= " << selection_data.data() << endl;

    }

    else if (selection_data.get_target() == "LENGTH")

    {

        cout << "The 'LENGTH' data
= " << static_cast<int>(*selection_data.data()) <<
endl;

    }

}

      

// SupplySelectionButton

      

SupplySelectionButton::SupplySelectionButton()

: Gtk::ToggleButtonSignals(this)

{

    set_label("Supply Selection");

      

    // Add STRING and LENGTH targets to the primary
selection.

    target_entries.push_back(Gtk::TargetEntry("STRING",
STRING));

    target_entries.push_back(Gtk::TargetEntry("LENGTH",
LENGTH));

      

    // Create the widget that will be used as the
selection owner;

    selection_widget = new Gtk::Invisible;

    selection_widget->realize();

  
 selection_widget->signal_selection_get().connect(sigc::mem_fun(this,
&SupplySelectionButton::selection_get));

  
 selection_widget->signal_selection_clear_event().connect(sigc::mem_fun(this,
&SupplySelectionButton::selection_clear_event));

  
 selection_widget->selection_add_targets(GDK_SELECTION_PRIMARY,
target_entries);

      

    // Define the content the STRING target's data.

    target_string = "This is the data of the STRING
target.";

}

      

SupplySelectionButton::~SupplySelectionButton()

{

}

      

void

SupplySelectionButton::on_toggled()

{

    using namespace std;

      

    if (get_active())

    {

        if
(selection_widget->selection_owner_set(GDK_SELECTION_PRIMARY,
GDK_CURRENT_TIME))

            cout
<< "SUCCESSFULLY GOT OWNERSHIP." << endl;

          else

        {

            // If unable
to claim ownership of selection return button to out state.

            cout
<< "FAILED TO GET OWNERSHIP." << endl;

          
 set_active(false);

        }

    }

    else

    {

    // Before clearing the selection by calling
selection_owner_unset(),

        // we check if we are the
actual owner.

        if
(selection_widget->selection_owner_get(GDK_SELECTION_PRIMARY))

        {

          
 selection_owner_unset(GDK_SELECTION_PRIMARY, GDK_CURRENT_TIME);

            cout <<
"SUCCESSFULLY CLEARED OWNERSHIP." << endl;

        }

    }

}

      

void

SupplySelectionButton::selection_get(Gtk::SelectionData&
selection_data, unsigned int info, unsigned int time)

{

      

    using namespace std;

      

    cout << "Got request for the '" <<
selection_data.get_target() << "' target." << endl;

      

    // Set the target data for our registered targets.

    switch (info)

    {

    case STRING:

        selection_data.set

        (

          
 gdk_atom_intern("STRING", TRUE), // type

          
 8,                              
// format

          
 target_string.c_str(),          
// data

          
 target_string.size()            
// data length

        );

        break;

      

    case LENGTH:

        {

            int length =
target_string.size();

          
 selection_data.set(gdk_atom_intern("INTEGER", TRUE), 32,
&length, sizeof(length));

        }

        break;

    }

      

}

      

bool

SupplySelectionButton::selection_clear_event(const
Gdk::EventSelection& event)

{

    if (get_active())

    {

        set_active(false);

        std::cout << "FORCEFULLY
CLEARED OWNERSHIP." << std::endl;

    }

    return false;

}

      

// SelectionTest

      

SelectionTest::SelectionTest()

{

    set_title("Selection Test");

    set_border_width(5);

    set_has_separator(false);

    set_resizable(false);

      

    // Add label

    Gtk::VBox *vbox = new Gtk::VBox;

    Gtk::HBox *hbox = new Gtk::HBox;

    Gtk::Label *label = new Gtk::Label("Enter target
name");

    label->set_justify(Gtk::JUSTIFY_LEFT);

    hbox->pack_start(*label, false, false);

    vbox->pack_start(*hbox);

      

    // Add entry widget

    Gtk::Entry *entry = new Gtk::Entry;

    entry->set_text("TARGETS");

    vbox->pack_start(*entry);

    client_area()->pack_start(*vbox, true, true, 5);

    client_area()->show_all();

      

    // Create a button the user can click to get
selection targets

    RetrieveSelectionButton *retrieve_button = new
RetrieveSelectionButton(entry);

    action_area()->pack_end(*retrieve_button, false,
false);

    retrieve_button->show();

      

    // Add a button the user can toggle to claim
ownership of the selection

    SupplySelectionButton *supply_button = new
SupplySelectionButton;

    action_area()->pack_end(*supply_button, false,
false);

    supply_button->show();

      

    // Add a button to end the program.

    Gtk::Button *button = new Gtk::Button("Quit");

    action_area()->pack_end(*button, false, false);

  
 button->signal_clicked().connect(sigc::mem_fun(this,
&SelectionTest::dispose));

    button->show();

}

      

SelectionTest::~SelectionTest()

{

}

      

int main (int argc, char *argv[])

{

    using namespace Main;

      

    init(&argc, &argv);

      

    SelectionTest window;

  
 window.signal_destroy().connect(sigc::ptr_fun(&Xfc::Main::quit));

    window.show();

      

    run();

    return 0;

}

Compiling Selection

If you compiled and installed XFC yourself, you will find the source code for Selection in the <examples/selection> source directory along with a Makefile. If XFC came pre-installed, or you installed it from an RPM package, you will find the source code in the </usr/share/doc/xfcui-X.X/examples/selection> subdirectory. In this case you will have to create the Makefile yourself (replace X.X with the version number of the libXFCui library you have installed).

To create a Makefile for Selection, add the following lines to a new text file and save it using the name "Makefile":

CC = g++

      

CFLAGS = -Wall -O2

      

spinbutton: spinbutton.cc spinbutton.hh 

    $(CC) spinbutton.cc -o spinbutton $(CFLAGS)
`pkg-config xfcui-X.X --cflags --libs`

      

clean: 

    rm -f *.o spinbutton

If you cut and paste these lines make sure the whitespace before $(CC) and rm is a tab character. When you compile and run this program you will see the following window appear:

When the "Retrieve Selection" button is pressed, the data of the target is requested from the PRIMARY selection. When the Gtk::SelectionData class has been received by the on_selection_received() handler the values of all the class data members are printed to the standard output. Note, if the PRIMARY selection is not owned by any client the type() will be null, the format and data() 0, and the length() -1.

Run the program from a shell. When the dialog is first displayed the entry widget displays the text "TARGETS". The text is highlighted, which means the entry widget is the current owner of the PRIMARY selection. When the "Retrieve Selection" button is pressed the targets returned are printed to the standard output. These will be the three mandatory ones: TIMESTAMP, TARGETS and MULTIPLE, plus those registered by the Entry widget: UTF8_STRING, STRING, TEXT and COMPOUND_TEXT.

The "Supply Selection" button registers two targets - STRING and LENGTH. When toggled in, the "Supply Selection" button takes ownership of the primary selection. Entering STRING or LENGTH into the entry widget and pressing the "Retrieve Selection" button prints the values returned by the Gtk::SelectionData class, including the target's data, to the standard output. For STRING, this data is the arbitrary string "This is the data of the STRING target." and for LENGTH the data is 38 - the number of characters in the STRING data.

For convenience, the widget requesting the selection "RetrieveSelectionButton" and the widget supplying the selection "SupplySelectionButton" are in the same application, but they could have been in different applications as in the GTK+ selection example.

Data Selections

Table of Contents

Overview

Retrieving the selection

Supplying the selection

Selection Example

Compiling Selection