Xfce Foundation Classes
 « Main Page | Index

Labels


Labels are used a lot in XFC, and are relatively simple. A label displays a small amount of text. As the name implies, most labels are used to label another widget such as a Button or a MenuItem. Labels are 'no window' widgets so they do not receive widget signals. If you need to catch signals, or do clipping, place it inside a Gtk::EventBox widget.

To create a new label, use one of the following constructors:

Label();

Label(const String& str, bool use_underline = false);

The first constructor creates an empty label. The second constructor creates a label that displays the specified character string. If 'use_underline' is true the string is parsed for an underscore preceding the mnemonic character.

After construction you can change the label's text by calling one of the following methods:

void set_text(const String& str);
 
void set_text_with_mnemonic(const String& str);

The sole argument to both is the new string to display. The second method, set_text_with_mnemonic(), parses the string for the mnemonic character (i.e. the character that is preceded by an underscore). The space needed for the new string will be automatically adjusted if needed. You can produce multi-line labels by putting line breaks in the label string.

To retrieve the current string use:

String get_text() const;

The label text can be justified using:

void set_justify(Gtk::Justification jtype);

The 'jtype' argument can be one of the values from the Gtk::Justification enum:
  • JUSTIFY_LEFT
  • JUSTIFY_RIGHT
  • JUSTIFY_CENTER (the default)
  • JUSTIFY_FILL
The label widget is also capable of line wrapping the text automatically. This can be activated using:

void set_line_wrap(bool wrap);

The 'wrap' argument takes a true or false value.

If you want your label underlined, then you can set a pattern on the label:

void set_pattern(const String& pattern);

The 'pattern' argument indicates how the underlining should look. It consists of a string of underscore and space characters. An underscore indicates that the corresponding character in the label should be underlined. For example, the string "__ __" would underline the first two characters and eight and ninth characters. If you simply want to have an underlined accelerator (mnemonic) in your label, you should use set_text_with_mnemonic(), not set_pattern().

Label Example

This short example illustrates the use of labels. It makes use of the Frame widget to demonstrate each label's style. In XFC, label texts can contain markup for font and other text attribute changes, and labels may be selectable (for copy-and-paste). These advanced features won't be explained here but are covered in the Gtk::Label API reference.

The header file for Label is <label.hh>

#include <xfc/main.hh>
#include <xfc/gtk/window.hh>

using namespace Xfc;

class LabelWindow : public Gtk::Window
{
public:
    LabelWindow();
    ~LabelWindow();
};

and the source file is <label.cc>:

#include "label.hh"
#include <xfc/gtk/box.hh>
#include <xfc/gtk/frame.hh>
#include <xfc/gtk/label.hh>

LabelWindow::LabelWindow()
{
    set_title("Label");
    Gtk::VBox *vbox = new Gtk::VBox(false, 5);
    Gtk::HBox *hbox = new Gtk::HBox(false, 5);
    add(*hbox);
    hbox->pack_start(*vbox, false,false);
    set_border_width(5);

    Gtk::Frame *frame = new Gtk::Frame("Normal Label");
    Gtk::Label *label = new Gtk::Label("This is a Normal label");
    frame->add(*label);
    vbox->pack_start(*frame, false,false);

    frame = new Gtk::Frame("Multi-line Label");
    label = new Gtk::Label("This is a Multi-line label.\nSecond line\nThird line");
    frame->add(*label);
    vbox->pack_start(*frame, false,false);

    frame = new Gtk::Frame("Left Justified Label");
    label = new Gtk::Label("This is a Left-Justified\n Multi-line label.\nThird line");
    label->set_justify(Gtk::JUSTIFY_LEFT);
    frame->add(*label);
    vbox->pack_start(*frame, false,false);

    frame = new Gtk::Frame("Right Justified Label");
    label = new Gtk::Label("This is a Right-Justified\nMulti-line label.\nFourth line, (j/k)");
    label->set_justify(Gtk::JUSTIFY_RIGHT);
    frame->add(*label);
    vbox->pack_start(*frame, false,false);

    vbox = new Gtk::VBox(false, 5);
    hbox->pack_start(*vbox, false,false);
    frame = new Gtk::Frame("Line wrapped label");
    label = new Gtk::Label("This is an example of a line-wrapped label. It should not be taking up the "\
                           "entire           /* big space to test spacing */  width allocated to it, "\
                           "but automatically wraps the words to fit. The time has come, for all good men, "\
                           "to come to the aid of their party. The sixth sheik's six sheep's sick.\n"\
                           "     It supports multiple paragraphs correctly,  and   correctly      adds "\
                           "      many          extra  spaces. ");
    label->set_line_wrap(true);
    frame->add(*label);
    vbox->pack_start(*frame, false,false);

    frame = new Gtk::Frame("Filled, wrapped label");
    label = new Gtk::Label("This is an example of a line-wrapped, filled label. " \
                           "It should be taking "\
                           "up the entire              width allocated to it.  " \
                           "Here is a sentence to prove "\
                           "my point.  Here is another sentence. "\
                           "Here comes the sun, do de do de do.\n"\
                           "    This is a new paragraph.\n"\
                           "    This is another newer, longer, better " \
                           "paragraph.  It is coming to an end, "\
                           "unfortunately.");
    label->set_justify(Gtk::JUSTIFY_FILL);
    label->set_line_wrap(true);
    frame->add(*label);
    vbox->pack_start(*frame, false,false);

    frame = new Gtk::Frame("Underlined label");
    label = new Gtk::Label("This label is underlined!\n"
                           "This one is underlined in quite a funky fashion");
    label->set_justify(Gtk::JUSTIFY_LEFT);
    label->set_pattern("_________________________ _ _________ _ ______     __ _______ ___");
    frame->add(*label);
    vbox->pack_start(*frame, false,false);
    show_all();
}

LabelWindow::~LabelWindow()
{
}

int main (int argc, char *argv[])
{
    using namespace Main;

    init(&argc, &argv);

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

    run();
    return 0;
}

Compiling Label

If you compiled and installed XFC yourself, you will find the source code for Label in the <examples/label> 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/label> 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 Label, add the following lines to a new text file and save it using the name "Makefile":

CC = g++

CFLAGS = -Wall -O2

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

clean:
    rm -f *.o label

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:



Copyright © 2004-2005 The XFC Development Team Top
 XFC 4.4