FLTK 1.3.4: Safe widget deletion support functions

FLTK 1.3.4

Functions
Safe widget deletion support functions

These functions, declared in <FL/Fl.H>, support deletion of widgets inside callbacks. More...

## Functions
static void | Fl::clear_widget_pointer (Fl_Widget const *w)
| Clears a widget pointer in the watch list. More...
static void | Fl::delete_widget (Fl_Widget *w)
| Schedules a widget for deletion at the next call to the event loop. More...
static void | Fl::do_widget_deletion ()
| Deletes widgets previously scheduled for deletion. More...
static void | Fl::release_widget_pointer (Fl_Widget *&w)
| Releases a widget pointer from the watch list. More...
static void | Fl::watch_widget_pointer (Fl_Widget *&w)
| Adds a widget pointer to the widget watch list. More...

## Detailed Description

These functions, declared in <FL/Fl.H>, support deletion of widgets inside callbacks.

Fl::delete_widget() should be called when deleting widgets or complete widget trees (Fl_Group, Fl_Window, ...) inside callbacks.

The other functions are intended for internal use. The preferred way to use them is by using the helper class Fl_Widget_Tracker.

The following is to show how it works ...

There are three groups of related methods:

1. scheduled widget deletion
   - Fl::delete_widget() schedules widgets for deletion
   - Fl::do_widget_deletion() deletes all scheduled widgets
2. widget watch list ("smart pointers")
   - Fl::watch_widget_pointer() adds a widget pointer to the watch list
   - Fl::release_widget_pointer() removes a widget pointer from the watch list
   - Fl::clear_widget_pointer() clears a widget pointer in the watch list
3. the class Fl_Widget_Tracker:
   - the constructor calls Fl::watch_widget_pointer()
   - the destructor calls Fl::release_widget_pointer()
   - the access methods can be used to test, if a widget has been deleted
     See also
       Fl_Widget_Tracker.

## Function Documentation

## § clear_widget_pointer()

void Fl::clear_widget_pointer | ( | Fl_Widget const * | w | ) |
| static

Clears a widget pointer in the watch list.

This is called when a widget is destroyed (by its destructor). You should never call this directly.

Note
  Internal use only !

This method searches the widget watch list for pointers to the widget and clears each pointer that points to it. Widget pointers can be added to the widget watch list by calling Fl::watch_widget_pointer() or by using the helper class Fl_Widget_Tracker (recommended).

See also
  Fl::watch_widget_pointer()
  class Fl_Widget_Tracker

## § delete_widget()

void Fl::delete_widget | ( | Fl_Widget * | wi | ) |
| static

Schedules a widget for deletion at the next call to the event loop.

Use this method to delete a widget inside a callback function.

To avoid early deletion of widgets, this function should be called toward the end of a callback and only after any call to the event loop (Fl::wait(), Fl::flush(), Fl::check(), fl_ask(), etc.).

When deleting groups or windows, you must only delete the group or window widget and not the individual child widgets.

Since
  FLTK 1.3.4 the widget will be hidden immediately, but the actual destruction will be delayed until the event loop is finished. Up to FLTK 1.3.3 windows wouldn't be hidden before the event loop was done, hence you had to hide() a window in your window close callback if you called Fl::delete_widget() to destroy (and hide) the window.
  FLTK 1.3.0 it is not necessary to remove widgets from their parent groups or windows before calling this, because it will be done in the widget's destructor, but it is not a failure to do this nevertheless.

Note
  In FLTK 1.1 you must remove widgets from their parent group (or window) before deleting them.

See also
  Fl_Widget::~Fl_Widget()

## § do_widget_deletion()

void Fl::do_widget_deletion | ( |  | ) |
| static

Deletes widgets previously scheduled for deletion.

This is for internal use only. You should never call this directly.

Fl::do_widget_deletion() is called from the FLTK event loop or whenever you call Fl::wait(). The previously scheduled widgets are deleted in the same order they were scheduled by calling Fl::delete_widget().

See also
  Fl::delete_widget(Fl_Widget *wi)

## § release_widget_pointer()

void Fl::release_widget_pointer | ( | Fl_Widget *& | w | ) |
| static

Releases a widget pointer from the watch list.

This is used to remove a widget pointer that has been added to the watch list with Fl::watch_widget_pointer(), when it is not needed anymore.

Note
  Internal use only, please use class Fl_Widget_Tracker instead.

See also
  Fl::watch_widget_pointer()

## § watch_widget_pointer()

void Fl::watch_widget_pointer | ( | Fl_Widget *& | w | ) |
| static

Adds a widget pointer to the widget watch list.

Note
  Internal use only, please use class Fl_Widget_Tracker instead.

This can be used, if it is possible that a widget might be deleted during a callback or similar function. The widget pointer must be added to the watch list before calling the callback. After the callback the widget pointer can be queried, if it is NULL. If it is NULL, then the widget has been deleted during the callback and must not be accessed anymore. If the widget pointer is not NULL, then the widget has not been deleted and can be accessed safely.

After accessing the widget, the widget pointer must be released from the watch list by calling Fl::release_widget_pointer().

Example for a button that is clicked (from its handle() method):

Fl_Widget *wp = this; // save 'this' in a pointer variable
Fl::watch_widget_pointer(wp); // add the pointer to the watch list
set_changed(); // set the changed flag
do_callback(); // call the callback
if (!wp) { // the widget has been deleted
// DO NOT ACCESS THE DELETED WIDGET !
} else { // the widget still exists
clear_changed(); // reset the changed flag
}
Fl::release_widget_pointer(wp); // remove the pointer from the watch list

This works, because all widgets call Fl::clear_widget_pointer() in their destructors.

See also
  Fl::release_widget_pointer()
  Fl::clear_widget_pointer()

An easier and more convenient method to control widget deletion during callbacks is to use the class Fl_Widget_Tracker with a local (automatic) variable.

See also
  class Fl_Widget_Tracker

- © 1998-2016 by Bill Spitzak and others.