Allows a mixed text and/or graphics label to be applied to an Fl_Menu_Item or Fl_Widget. More...

#include <Fl_Multi_Label.H>

Public Member Functions
void	label (Fl_Menu_Item *)
	Associate an Fl_Multi_Label with an Fl_Menu_Item.

void	label (Fl_Widget *)
	Associate an Fl_Multi_Label with an Fl_Widget.

Public Attributes
const char *	labela
	Holds the "leftmost" of the two elements in the composite label.

const char *	labelb
	Holds the "rightmost" of the two elements in the composite label.

uchar	typea
	Holds the "type" of labela.

uchar	typeb
	Holds the "type" of labelb.

Detailed Description

Allows a mixed text and/or graphics label to be applied to an Fl_Menu_Item or Fl_Widget.

Most regular FLTK widgets now support the ability to associate both images and text with a label but some special cases, notably the non-widget Fl_Menu_Item objects, do not. Fl_Multi_Label may be used to create menu items that have an icon and text, which would not normally be possible for an Fl_Menu_Item. For example, Fl_Multi_Label is used in the New->Code submenu in fluid, and others.

Menu items with icons using Fl_Multi_Label

Each Fl_Multi_Label holds two elements, labela and labelb; each may hold either a text label (const char*) or an image (Fl_Image*). When displayed, labela is drawn first and labelb is drawn immediately to its right.

More complex labels can be constructed by setting labelb as another Fl_Multi_Label and thus chaining up a series of label elements.

When assigning a label element to one of labela or labelb, they should be explicitly cast to (const char*) if they are not of that type already.

Note: An Fl_Multi_Label object and all its components (label text, images, chained Fl_Multi_Label's and their linked objects) must exist during the lifetime of the widget or menu item they are assigned to. It is the responsibility of the user's code to release these linked objects if necessary after the widget or menu is deleted.

Example Use: Fl_Menu_Bar

Fl_Pixmap *image = new Fl_Pixmap(..);     // image for menu item; any Fl_Image based widget
Fl_Menu_Bar *menu = new Fl_Menu_Bar(..);  // can be any Fl_Menu_ oriented widget (Fl_Choice, Fl_Menu_Button..)
 
// Create a menu item
int i = menu->add("File/New", ..);
Fl_Menu_Item *item = (Fl_Menu_Item*)&(menu->menu()[i]);
 
// Create a multi label, assign it an image + text
Fl_Multi_Label *ml = new Fl_Multi_Label;
 
// Left side of label is an image
ml->typea  = FL_IMAGE_LABEL;
ml->labela = (const char*)image;           // any Fl_Image widget: Fl_Pixmap, Fl_PNG_Image, etc..
 
// Right side of label is label text
ml->typeb  = FL_NORMAL_LABEL;
ml->labelb = item->label();
 
// Assign the multilabel to the menu item
// ml->label(item); // deprecated since 1.4.0; backwards compatible with 1.3.x
item->label(ml);    // new method since 1.4.0

See also: Fl_Label and Fl_Labeltype and examples/howto-menu-with-images.cxx

Member Function Documentation

◆ label() [1/2]

void Fl_Multi_Label::label ( Fl_Menu_Item * o )

Associate an Fl_Multi_Label with an Fl_Menu_Item.

This uses Fl_Menu_Item::label(Fl_Labeltype a, const char *b) internally to set the label and the label type of the menu item, i.e. it stores a pointer to the Fl_Multi_Label object (this). An existing label (pointer) will be overwritten.

This sets the type of the menu item's label to _FL_MULTI_LABEL - note the leading underscore ('_').

There is no way to use a method like Fl_Widget::copy_label() that transfers ownership of the Fl_Multi_Label and its linked objects (images, text, and chained Fl_Multi_Label's) to the menu item.

The Fl_Multi_Label and all linked images, text labels, or chained Fl_Multi_Label objects must exist during the lifetime of the menu and will not be released when the menu item is destroyed.

Note: The user's code is responsible for releasing the Fl_Multi_Label and all linked objects (images, text, chained Fl_Multi_Label's) after the menu has been deleted. This may cause memory leaks if Fl_Multi_Label is used and reassigned w/o releasing the objects assigned to it.

Deprecated:: since 1.4.0: please use Fl_Menu_Item::label(Fl_Multi_Label *)

See also: Fl_Menu_Item::label(Fl_Multi_Label *)

◆ label() [2/2]

void Fl_Multi_Label::label ( Fl_Widget * o )

Associate an Fl_Multi_Label with an Fl_Widget.

This method uses Fl_Widget::label(Fl_Labeltype, const char *) internally to set the label of the widget, i.e. it stores a pointer to the Fl_Multi_Label object (this). An existing label that has been set using Fl_Widget::copy_label() will be released prior to the assignment of the new label.

This sets the type of the widget's label to _FL_MULTI_LABEL - note the leading underscore ('_').

There is no way to use a method like Fl_Widget::copy_label() that transfers ownership of the Fl_Multi_Label and its linked objects (images, text, and chained Fl_Multi_Label's) to the widget.

The Fl_Multi_Label and all linked images, text labels, or chained Fl_Multi_Label objects must exist during the lifetime of the widget and will not be released when the widget is destroyed.

Note: The user's code is responsible for releasing the Fl_Multi_Label and all linked objects (images, text, chained Fl_Multi_Label's) after the widget has been deleted. This may cause memory leaks if Fl_Multi_Label is used and reassigned w/o releasing the objects assigned to it.

Member Data Documentation

◆ labela

const char* Fl_Multi_Label::labela

Holds the "leftmost" of the two elements in the composite label.

Typically this would be assigned either a text string (const char*), a (Fl_Image*) or a (Fl_Multi_Label*).

◆ labelb

const char* Fl_Multi_Label::labelb

Holds the "rightmost" of the two elements in the composite label.

Typically this would be assigned either a text string (const char*), a (Fl_Image*) or a (Fl_Multi_Label*).

◆ typea

uchar Fl_Multi_Label::typea

Holds the "type" of labela.

Typically this is set to FL_NORMAL_LABEL for a text label, FL_IMAGE_LABEL for an image (based on Fl_image) or FL_MULTI_LABEL if "chaining" multiple Fl_Multi_Label elements together.

◆ typeb

uchar Fl_Multi_Label::typeb

Holds the "type" of labelb.