FLTK 1.4.4: Fl_Multi_Label Struct Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Multi_Label Struct Reference

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
FL_IMAGE_LABEL
#define FL_IMAGE_LABEL
Draws an image (Fl_Image) as the label.
Definition Enumerations.H:922
FL_NORMAL_LABEL
@ FL_NORMAL_LABEL
draws the text (0)
Definition Enumerations.H:836
Fl_Pixmap
The Fl_Pixmap class supports caching and drawing of colormap (pixmap) images, including transparency.
Definition Fl_Pixmap.H:36
Fl_Multi_Label
Allows a mixed text and/or graphics label to be applied to an Fl_Menu_Item or Fl_Widget.
Definition Fl_Multi_Label.H:76
Fl_Multi_Label::typea
uchar typea
Holds the "type" of labela.
Definition Fl_Multi_Label.H:89
Fl_Multi_Label::labelb
const char * labelb
Holds the "rightmost" of the two elements in the composite label.
Definition Fl_Multi_Label.H:84
Fl_Multi_Label::labela
const char * labela
Holds the "leftmost" of the two elements in the composite label.
Definition Fl_Multi_Label.H:80
Fl_Multi_Label::typeb
uchar typeb
Holds the "type" of labelb.
Definition Fl_Multi_Label.H:94

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.

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.

The documentation for this struct was generated from the following files:

- Fl_Multi_Label.H
- Fl_Multi_Label.cxx