FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Group Class Reference

The Fl_Group class is the main FLTK container widget. More...

`#include <Fl_Group.H>`

Inheritance diagram for Fl_Group:

## Public Member Functions
Fl_Widget *& | _ddfdesign_kludge ()
| This is for forms compatibility only.
void | add (Fl_Widget &)
| The widget is removed from its current group (if any) and then added to the end of this group.
void | add (Fl_Widget *o)
| See void Fl_Group::add(Fl_Widget &w).
void | add_resizable (Fl_Widget &o)
| Adds a widget to the group and makes it the resizable widget.
Fl_Widget *const * | array () const
| Returns a pointer to the array of children.
Fl_Group const * | as_group () const FL_OVERRIDE
Fl_Group * | as_group () FL_OVERRIDE
| Returns an Fl_Group pointer if this widget is an Fl_Group.
void | begin ()
| Sets the current group so you can build the widget tree by just constructing the widgets.
Fl_Widget * | child (int n) const
| Returns the n'th child.
int | children () const
| Returns how many child widgets the group has.
void | clear ()
| Deletes all child widgets from memory recursively.
unsigned int | clip_children ()
| Returns the current clipping mode.
void | clip_children (int c)
| Controls whether the group widget clips the drawing of child widgets to its bounding box.
virtual int | delete_child (int n)
| Removes the widget at `index` from the group and deletes it.
void | end ()
| Exactly the same as current(this->parent()).
int | find (const Fl_Widget &o) const
| See int Fl_Group::find(const Fl_Widget *w) const.
int | find (const Fl_Widget *) const
| Searches the child array for the widget and returns the index.
| Fl_Group (int, int, int, int, const char *=0)
| Creates a new Fl_Group widget using the given position, size, and label string.
void | focus (Fl_Widget *W)
void | forms_end ()
| This is for forms compatibility only.
int | handle (int) FL_OVERRIDE
| Handles the specified event.
void | init_sizes ()
| Resets the internal array of widget sizes and positions.
void | insert (Fl_Widget &, int i)
| The widget is removed from its current group (if any) and then inserted into this group.
void | insert (Fl_Widget &o, Fl_Widget *before)
| This does insert(w, find(before)).
void | remove (Fl_Widget &)
| Removes a widget from the group but does not delete it.
void | remove (Fl_Widget *o)
| Removes the widget `o` from the group.
void | remove (int index)
| Removes the widget at `index` from the group but does not delete it.
Fl_Widget * | resizable () const
| Returns the group's resizable widget.
void | resizable (Fl_Widget &o)
| Sets the group's resizable widget.
void | resizable (Fl_Widget *o)
| The resizable widget defines both the resizing box and the resizing behavior of the group and its children.
void | resize (int, int, int, int) FL_OVERRIDE
| Resizes the Fl_Group widget and all of its children.
virtual | ~Fl_Group ()
| The destructor also deletes all the children.
Public Member Functions inherited from Fl_Widget
void | _clear_fullscreen ()
void | _set_fullscreen ()
void | activate ()
| Activates the widget.
unsigned int | active () const
| Returns whether the widget is active.
int | active_r () const
| Returns whether the widget and all of its parents are active.
Fl_Align | align () const
| Gets the label alignment.
void | align (Fl_Align alignment)
| Sets the label alignment.
long | argument () const
| Gets the current user data (long) argument that is passed to the callback function.
void | argument (long v)
| Sets the current user data (long) argument that is passed to the callback function.
virtual class Fl_Gl_Window * | as_gl_window ()
| Returns an Fl_Gl_Window pointer if this widget is an Fl_Gl_Window.
virtual class Fl_Gl_Window const * | as_gl_window () const
virtual Fl_Window * | as_window ()
| Returns an Fl_Window pointer if this widget is an Fl_Window.
virtual Fl_Window const * | as_window () const
void | bind_deimage (Fl_Image *img)
| Sets the image to use as part of the widget label when in the inactive state.
void | bind_deimage (int f)
| Bind the inactive image to the widget, so the widget will delete the image when it is no longer needed.
void | bind_image (Fl_Image *img)
| Sets the image to use as part of the widget label when in the active state.
void | bind_image (int f)
| Bind the image to the widget, so the widget will delete the image when it is no longer needed.
Fl_Boxtype | box () const
| Gets the box type of the widget.
void | box (Fl_Boxtype new_box)
| Sets the box type for the widget.
Fl_Callback_p | callback () const
| Gets the current callback function for the widget.
void | callback (Fl_Callback *cb)
| Sets the current callback function for the widget.
void | callback (Fl_Callback *cb, Fl_Callback_User_Data *p, bool auto_free)
| Sets the current callback function and managed user data for the widget.
void | callback (Fl_Callback *cb, void *p)
| Sets the current callback function and data for the widget.
void | callback (Fl_Callback0 *cb)
| Sets the current callback function for the widget.
void | callback (Fl_Callback1 *cb, long p=0)
| Sets the current callback function for the widget.
unsigned int | changed () const
| Checks if the widget value changed since the last callback.
void | clear_active ()
| Marks the widget as inactive without sending events or changing focus.
void | clear_changed ()
| Marks the value of the widget as unchanged.
void | clear_damage (uchar c=0)
| Clears or sets the damage flags.
void | clear_output ()
| Sets a widget to accept input.
void | clear_visible ()
| Hides the widget.
void | clear_visible_focus ()
| Disables keyboard focus navigation with this widget.
Fl_Color | color () const
| Gets the background color of the widget.
void | color (Fl_Color bg)
| Sets the background color of the widget.
void | color (Fl_Color bg, Fl_Color sel)
| Sets the background and selection color of the widget.
Fl_Color | color2 () const
| For back compatibility only.
void | color2 (unsigned a)
| For back compatibility only.
int | contains (const Fl_Widget *w) const
| Checks if w is a child of this widget.
void | copy_label (const char *new_label)
| Sets the current label.
void | copy_tooltip (const char *text)
| Sets the current tooltip text.
uchar | damage () const
| Returns non-zero if draw() needs to be called.
void | damage (uchar c)
| Sets the damage bits for the widget.
void | damage (uchar c, int x, int y, int w, int h)
| Sets the damage bits for an area inside the widget.
int | damage_resize (int, int, int, int)
| Internal use only.
void | deactivate ()
| Deactivates the widget.
Fl_Image * | deimage ()
| Gets the image that is used as part of the widget label when in the inactive state.
const Fl_Image * | deimage () const
| Gets the image that is used as part of the widget label when in the inactive state.
void | deimage (Fl_Image &img)
| Sets the image to use as part of the widget label when in the inactive state.
void | deimage (Fl_Image *img)
| Sets the image to use as part of the widget label when in the inactive state.
int | deimage_bound () const
| Returns whether the inactive image is managed by the widget.
void | do_callback (Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
| Calls the widget callback function with default arguments.
void | do_callback (Fl_Widget *widget, long arg, Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
| Calls the widget callback function with arbitrary arguments.
void | do_callback (Fl_Widget *widget, void *arg=0, Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
| Calls the widget callback function with arbitrary arguments.
void | draw_label (int, int, int, int, Fl_Align) const
| Draws the label in an arbitrary bounding box with an arbitrary alignment.
int | h () const
| Gets the widget height.
virtual void | hide ()
| Makes a widget invisible.
int | horizontal_label_margin ()
| Get the spacing between the label and the horizontal edge of the widget.
void | horizontal_label_margin (int px)
| Set the spacing between the label and the horizontal edge of the widget.
Fl_Image * | image ()
| Gets the image that is used as part of the widget label when in the active state.
const Fl_Image * | image () const
| Gets the image that is used as part of the widget label when in the active state.
void | image (Fl_Image &img)
| Sets the image to use as part of the widget label when in the active state.
void | image (Fl_Image *img)
| Sets the image to use as part of the widget label when in the active state.
int | image_bound () const
| Returns whether the image is managed by the widget.
int | inside (const Fl_Widget *wgt) const
| Checks if this widget is a child of `wgt`.
int | is_label_copied () const
| Returns whether the current label was assigned with copy_label().
const char * | label () const
| Gets the current label text.
void | label (const char *text)
| Sets the current label pointer.
void | label (Fl_Labeltype a, const char *b)
| Shortcut to set the label text and type in one call.
int | label_image_spacing ()
| Return the gap size between the label and the image.
void | label_image_spacing (int gap)
| Set the gap between the label and the image in pixels.
Fl_Color | labelcolor () const
| Gets the label color.
void | labelcolor (Fl_Color c)
| Sets the label color.
Fl_Font | labelfont () const
| Gets the font to use.
void | labelfont (Fl_Font f)
| Sets the font to use.
Fl_Fontsize | labelsize () const
| Gets the font size in pixels.
void | labelsize (Fl_Fontsize pix)
| Sets the font size in pixels.
Fl_Labeltype | labeltype () const
| Gets the label type.
void | labeltype (Fl_Labeltype a)
| Sets the label type.
void | measure_label (int &ww, int &hh) const
| Sets width ww and height hh accordingly with the label size.
bool | needs_keyboard () const
| Returns whether this widget needs a keyboard.
void | needs_keyboard (bool needs)
| Sets whether this widget needs a keyboard.
unsigned int | output () const
| Returns if a widget is used for output only.
Fl_Group * | parent () const
| Returns a pointer to the parent widget.
void | parent (Fl_Group *p)
| Internal use only - "for hacks only".
void | position (int X, int Y)
| Repositions the window or widget.
void | redraw ()
| Schedules the drawing of the widget.
void | redraw_label ()
| Schedules the drawing of the label.
Fl_Color | selection_color () const
| Gets the selection color.
void | selection_color (Fl_Color a)
| Sets the selection color.
void | set_active ()
| Marks the widget as active without sending events or changing focus.
void | set_changed ()
| Marks the value of the widget as changed.
void | set_output ()
| Sets a widget to output only.
void | set_visible ()
| Makes the widget visible.
void | set_visible_focus ()
| Enables keyboard focus navigation with this widget.
int | shortcut_label () const
| Returns whether the widget's label uses '&' to indicate shortcuts.
void | shortcut_label (int value)
| Sets whether the widget's label uses '&' to indicate shortcuts.
virtual void | show ()
| Makes a widget visible.
void | size (int W, int H)
| Changes the size of the widget.
int | take_focus ()
| Gives the widget the keyboard focus.
unsigned int | takesevents () const
| Returns if the widget is able to take events.
int | test_shortcut ()
| Returns true if the widget's label contains the entered '&x' shortcut.
const char * | tooltip () const
| Gets the current tooltip text.
void | tooltip (const char *text)
| Sets the current tooltip text.
Fl_Window * | top_window () const
| Returns a pointer to the top-level window for the widget.
Fl_Window * | top_window_offset (int &xoff, int &yoff) const
| Finds the x/y offset of the current widget relative to the top-level window.
uchar | type () const
| Gets the widget type.
void | type (uchar t)
| Sets the widget type.
int | use_accents_menu ()
| Returns non zero if MAC_USE_ACCENTS_MENU flag is set, 0 otherwise.
void * | user_data () const
| Gets the user data for this widget.
void | user_data (Fl_Callback_User_Data *v, bool auto_free)
| Sets the user data for this widget.
void | user_data (void *v)
| Sets the user data for this widget.
int | vertical_label_margin ()
| Get the spacing between the label and the vertical edge of the widget.
void | vertical_label_margin (int px)
| Set the spacing between the label and the vertical edge of the widget.
unsigned int | visible () const
| Returns whether a widget is visible.
unsigned int | visible_focus () const
| Checks whether this widget has a visible focus.
void | visible_focus (int v)
| Modifies keyboard focus navigation.
int | visible_r () const
| Returns whether a widget and all its parents are visible.
int | w () const
| Gets the widget width.
Fl_When | when () const
| Returns the conditions under which the callback is called.
void | when (uchar i)
| Sets the flags used to decide when a callback is called.
Fl_Window * | window () const
| Returns a pointer to the nearest parent window up the widget hierarchy.
int | x () const
| Gets the widget position in its window.
int | y () const
| Gets the widget position in its window.
virtual | ~Fl_Widget ()
| Destroys the widget.

## Static Public Member Functions
static Fl_Group * | current ()
| Returns the currently active group.
static void | current (Fl_Group *g)
| Sets the current group.
Static Public Member Functions inherited from Fl_Widget
static void | default_callback (Fl_Widget *widget, void *data)
| The default callback for all widgets that don't set a callback.
static unsigned int | label_shortcut (const char *t)
| Returns the Unicode value of the '&x' shortcut in a given text.
static int | test_shortcut (const char *, const bool require_alt=false)
| Returns true if the given text `t` contains the entered '&x' shortcut.

## Protected Member Functions
Fl_Rect * | bounds ()
| Returns the internal array of widget sizes and positions.
void | draw () FL_OVERRIDE
| Draws the widget.
void | draw_child (Fl_Widget &widget) const
| Forces a child to redraw.
void | draw_children ()
| Draws all children of the group.
void | draw_outside_label (const Fl_Widget &widget) const
| Parents normally call this to draw outside labels of child widgets.
virtual int | on_insert (Fl_Widget *, int)
| Allow derived groups to act when a widget is added as a child.
virtual int | on_move (int, int)
| Allow derived groups to act when a widget is moved within the group.
virtual void | on_remove (int)
| Allow derived groups to act when a child widget is removed from the group.
int * | sizes ()
| Returns the internal array of widget sizes and positions.
void | update_child (Fl_Widget &widget) const
| Draws a child only if it needs it.
Protected Member Functions inherited from Fl_Widget
void | clear_flag (unsigned int c)
| Clears a flag in the flags mask.
void | draw_backdrop () const
| If FL_ALIGN_IMAGE_BACKDROP is set, the image or deimage will be drawn.
void | draw_box () const
| Draws the widget box according its box style.
void | draw_box (Fl_Boxtype t, Fl_Color c) const
| Draws a box of type t, of color c at the widget's position and size.
void | draw_box (Fl_Boxtype t, int x, int y, int w, int h, Fl_Color c) const
| Draws a box of type t, of color c at the position X,Y and size W,H.
void | draw_focus () const
| Draws a focus rectangle around the widget.
void | draw_focus (Fl_Boxtype t, int X, int Y, int W, int H) const
| Draws a focus rectangle around the widget.
void | draw_focus (Fl_Boxtype t, int x, int y, int w, int h, Fl_Color bg) const
| Draws a focus box for the widget at the given position and size.
void | draw_label () const
| Draws the widget's label at the defined label position.
void | draw_label (int, int, int, int) const
| Draws the label in an arbitrary bounding box.
| Fl_Widget (int x, int y, int w, int h, const char *label=0L)
| Creates a widget at the given position and size.
unsigned int | flags () const
| Gets the widget flags mask.
void | h (int v)
| Internal use only.
void | set_flag (unsigned int c)
| Sets a flag in the flags mask.
void | w (int v)
| Internal use only.
void | x (int v)
| Internal use only.
void | y (int v)
| Internal use only.

## Additional Inherited Members
Protected Types inherited from Fl_Widget
enum | { INACTIVE = 1<<0 , INVISIBLE = 1<<1 , OUTPUT = 1<<2 , NOBORDER = 1<<3 , FORCE_POSITION = 1<<4 , NON_MODAL = 1<<5 , SHORTCUT_LABEL = 1<<6 , CHANGED = 1<<7 , OVERRIDE = 1<<8 , VISIBLE_FOCUS = 1<<9 , COPIED_LABEL = 1<<10 , CLIP_CHILDREN = 1<<11 , MENU_WINDOW = 1<<12 , TOOLTIP_WINDOW = 1<<13 , MODAL = 1<<14 , NO_OVERLAY = 1<<15 , GROUP_RELATIVE = 1<<16 , COPIED_TOOLTIP = 1<<17 , FULLSCREEN = 1<<18 , MAC_USE_ACCENTS_MENU = 1<<19 , NEEDS_KEYBOARD = 1<<20 , IMAGE_BOUND = 1<<21 , DEIMAGE_BOUND = 1<<22 , AUTO_DELETE_USER_DATA = 1<<23 , MAXIMIZED = 1<<24 , POPUP = 1<<25 , USERFLAG3 = 1<<29 , USERFLAG2 = 1<<30 , USERFLAG1 = 1<<31 }
| flags possible values enumeration. More...

## Detailed Description

The Fl_Group class is the main FLTK container widget.

It maintains an array of child widgets. These children can themselves be any widget including Fl_Group. The most important subclass of Fl_Group is Fl_Window, however groups can also be used to control radio buttons or to enforce resize behavior.

The tab and arrow keys are used to move the focus between widgets of this group, and to other groups. The only modifier grabbed is shift (for shift-tab), so that ctrl-tab, alt-up, and such are free for the app to use as shortcuts.

To remove a widget from the group and destroy it, in 1.3.x (and up) you can simply use:

delete some_widget;

..and this will trigger proper scheduling of the widget's removal from its parent group.

If used as a child of `Fl_Tabs`, setting `when(FL_WHEN_CLOSED)` will enable the Close button in the corresponding tab. If the user clicks the Close button, the callback of this group will be called with the callback reason `FL_REASON_CLOSED`.

## Constructor & Destructor Documentation

## ◆ Fl_Group()

Fl_Group::Fl_Group | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H,
|  | const char * | l = 0 )

Creates a new Fl_Group widget using the given position, size, and label string.

The default boxtype is FL_NO_BOX.

## ◆ ~Fl_Group()

Fl_Group::~Fl_Group | ( |  | ) |
| virtual

The destructor also deletes all the children.

This allows a whole tree to be deleted at once, without having to keep a pointer to all the children in the user code.

It is allowed that the Fl_Group and all of its children are automatic (local) variables, but you must declare the Fl_Group first, so that it is destroyed last.

If you add static or automatic (local) variables to an Fl_Group, then it is your responsibility to remove (or delete) all such static or automatic child widgets before destroying the group - otherwise the group will attempt to call delete operator on them leading to undefined behavior!

## Member Function Documentation

## ◆ array()

Fl_Widget *const * Fl_Group::array | ( |  | ) | const

Returns a pointer to the array of children.

Note
  This pointer is only valid until the next time a child is added or removed.

## ◆ as_group() [1/2]

Fl_Group const * Fl_Group::as_group | ( |  | ) | const
| inline virtual

Reimplemented from Fl_Widget.

## ◆ as_group() [2/2]

Fl_Group * Fl_Group::as_group | ( |  | ) |
| inline virtual

Returns an Fl_Group pointer if this widget is an Fl_Group.

Use this method if you have a widget (pointer) and need to know whether this widget is derived from Fl_Group. If it returns non-NULL, then the widget in question is derived from Fl_Group, and you can use the returned pointer to access its children or other Fl_Group-specific methods.

Example:

void my_callback (Fl_Widget *w, void *) {
Fl_Group *g = w->as_group();
if (g)
printf ("This group has %d children\n", g->children());
else
printf ("This widget is not a group!\n");
}
Fl_Group::children
int children() const
Returns how many child widgets the group has.
Definition Fl_Group.H:98
Fl_Widget::w
void w(int v)
Internal use only.
Definition Fl_Widget.H:154

Return values

  NULL | if this widget is not derived from Fl_Group.

Note
  This method is provided to avoid dynamic_cast.

See also
  Fl_Widget::as_window(), Fl_Widget::as_gl_window()

Reimplemented from Fl_Widget.

## ◆ begin()

void Fl_Group::begin | ( |  | ) |

Sets the current group so you can build the widget tree by just constructing the widgets.

begin() is automatically called by the constructor for Fl_Group (and thus for Fl_Window as well). begin() is exactly the same as current(this). Don't forget to end() the group or window!

## ◆ bounds()

Fl_Rect * Fl_Group::bounds | ( |  | ) |
| protected

Returns the internal array of widget sizes and positions.

If the bounds() array does not exist, it will be allocated and filled with the current widget sizes and positions.

The bounds() array stores the initial positions of widgets as Fl_Rect's. The size of the array is children() + 2.

- The first Fl_Rect is the group,
- the second is the resizable (clipped to the group),
- the rest are the children.

This is a convenient order for the resize algorithm.

If the group and/or the resizable() is a Fl_Window (or subclass) then the x() and y() coordinates of their respective Fl_Rect's are zero.

Note
  You should never need to use this protected method directly, unless you have special needs to rearrange the children of a Fl_Group. Fl_Tile uses this to rearrange its widget positions. The returned array should be considered read-only. Do not change its contents. If you need to rearrange children in a group, do so by resizing the children and call init_sizes().

#include <FL/Fl_Rect.H> if you want to access the bounds() array in your derived class. Fl_Rect.H is intentionally not included by Fl_Group.H to avoid unnecessary dependencies.

Returns
  Array of Fl_Rect's with widget positions and sizes. The returned array is only valid until init_sizes() is called or widgets are added to or removed from the group.

See also
  init_sizes()

Since
  FLTK 1.4.0

## ◆ child()

Fl_Widget * Fl_Group::child | ( | int | n | ) | const
| inline

Returns the n'th child.

Returns `NULL` if `n` is out of range (since FLTK 1.4.0).

No range checking was done in FLTK 1.3 and older versions!

Parameters

  [in] | n | index of child (0 .. children() - 1)

Returns
  pointer to the n'th child or NULL if out of range

## ◆ clear()

void Fl_Group::clear | ( | void |  | ) |

Deletes all child widgets from memory recursively.

This method differs from the remove() method in that it affects all child widgets and deletes them from memory.

The resizable() widget of the Fl_Group is set to the Fl_Group itself.

## ◆ clip_children() [1/2]

unsigned int Fl_Group::clip_children | ( |  | ) |
| inline

Returns the current clipping mode.

Returns
  true, if clipping is enabled, false otherwise.

See also
  void Fl_Group::clip_children(int c)

## ◆ clip_children() [2/2]

void Fl_Group::clip_children | ( | int | c | ) |
| inline

Controls whether the group widget clips the drawing of child widgets to its bounding box.

Set `c` to 1 if you want to clip the child widgets to the bounding box.

The default is to not clip (0) the drawing of child widgets.

## ◆ current() [1/2]

Fl_Group * Fl_Group::current | ( |  | ) |
| static

Returns the currently active group.

The Fl_Widget constructor automatically does current()->add(widget) if this is not null. To prevent new widgets from being added to a group, call Fl_Group::current(0).

## ◆ current() [2/2]

void Fl_Group::current | ( | Fl_Group * | g | ) |
| static

Sets the current group.

See also
  Fl_Group::current()

## ◆ delete_child()

int Fl_Group::delete_child | ( | int | index | ) |
| virtual

Removes the widget at `index` from the group and deletes it.

This method does nothing if `index` is out of bounds.

This method differs from the remove() method in that it deletes the widget from memory. Since this method is virtual it can be reimplemented in subclasses with additional requirements and consequences. See the documentation of subclasses.

Many subclasses don't need to reimplement this method.

Note
  This method may refuse to remove and delete the widget if it is an essential part of the Fl_Group, for instance a scrollbar in an Fl_Scroll group. In this case the widget is neither removed nor deleted.

This method does not call init_sizes() or redraw(). This is left to user code if necessary.

Returns 0 if the widget was removed and deleted. Return values > 0 are reserved for use by FLTK core widgets. Return values < 0 are free to be used by user defined widgets.

Todo
  Reimplementation of Fl_Group::delete_child(int) in more FLTK subclasses. This is not yet complete.

Parameters

  [in] | index | index of child to be removed

Returns
  success (0) or error code

Return values

  0 | success
  1 | index out of range
  2 | widget not allowed to be removed (see note)
  >2 | reserved for FLTK use

Since
  FLTK 1.4.0

Reimplemented in Fl_Scroll.

## ◆ draw()

void Fl_Group::draw | ( |  | ) |
| protected virtual

Draws the widget.

Never call this function directly. FLTK will schedule redrawing whenever needed. If your widget must be redrawn as soon as possible, call redraw() instead.

Override this function to draw your own widgets.

If you ever need to call another widget's draw method from within your own draw() method, e.g. for an embedded scrollbar, you can do it (because draw() is virtual) like this:

Fl_Widget *s = &scrollbar; // scrollbar is an embedded Fl_Scrollbar
s->draw(); // calls Fl_Scrollbar::draw()

Implements Fl_Widget.

Reimplemented in Fl_Help_View, Fl_Input_Choice, Fl_Pack, Fl_Scroll, Fl_Spinner, Fl_Table, Fl_Tabs, Fl_Terminal, Fl_Text_Display, Fl_Tree, Fl_Window, and Fl_Wizard.

## ◆ draw_child()

void Fl_Group::draw_child | ( | Fl_Widget & | widget | ) | const
| protected

Forces a child to redraw.

This draws a child widget, if it is not clipped. The damage bits are cleared after drawing.

## ◆ draw_children()

void Fl_Group::draw_children | ( |  | ) |
| protected

Draws all children of the group.

This is useful, if you derived a widget from Fl_Group and want to draw a special border or background. You can call draw_children() from the derived draw() method after drawing the box, border, or background.

## ◆ end()

void Fl_Group::end | ( |  | ) |

Exactly the same as current(this->parent()).

Any new widgets added to the widget tree will be added to the parent of the group.

## ◆ find()

int Fl_Group::find | ( | const Fl_Widget * | o | ) | const

Searches the child array for the widget and returns the index.

Returns children() if the widget is NULL or not found.

## ◆ focus()

void Fl_Group::focus | ( | Fl_Widget * | W | ) |
| inline

Deprecated
  This is for backwards compatibility only. You should use W->take_focus() instead.

See also
  Fl_Widget::take_focus();

## ◆ handle()

int Fl_Group::handle | ( | int | event | ) |
| virtual

Handles the specified event.

You normally don't call this method directly, but instead let FLTK do it when the user interacts with the widget.

When implemented in a widget, this function must return 0 if the widget does not use the event or 1 otherwise.

Most of the time, you want to call the inherited handle() method in your overridden method so that you don't short-circuit events that you don't handle. In this last case you should return the callee retval.

One exception to the rule in the previous paragraph is if you really want to override the behavior of the base class. This requires knowledge of the details of the inherited class.

In rare cases you may want to return 1 from your handle() method although you don't really handle the event. The effect would be to filter event processing, for instance if you want to dismiss non-numeric characters (keypresses) in a numeric input widget. You may "ring the bell" or show another visual indication or drop the event silently. In such a case you must not call the handle() method of the base class and tell FLTK that you consumed the event by returning 1 even if you didn't do anything with it.

Parameters

  [in] | event | the kind of event received

Return values

  0 | if the event was not used or understood
  1 | if the event was used and can be deleted

See also
  Fl_Event

Reimplemented from Fl_Widget.

Reimplemented in Fl_Help_View, Fl_Scroll, Fl_Spinner, Fl_Table, Fl_Table_Row, Fl_Tabs, Fl_Terminal, Fl_Text_Display, Fl_Text_Editor, Fl_Tile, Fl_Tree, and Fl_Window.

## ◆ init_sizes()

void Fl_Group::init_sizes | ( |  | ) |

Resets the internal array of widget sizes and positions.

The Fl_Group widget keeps track of the original widget sizes and positions when resizing occurs so that if you resize a window back to its original size the widgets will be in the correct places. If you rearrange the widgets in your group, call this method to register the new arrangement with the Fl_Group that contains them.

If you add or remove widgets, this will be done automatically.

Note
  The internal array of widget sizes and positions will be allocated and filled when the next resize() occurs. For more information on the contents and structure of the bounds() array see bounds().

See also
  bounds()
  sizes() (deprecated)

## ◆ insert() [1/2]

void Fl_Group::insert | ( | Fl_Widget & | o,
|  | int | index )

The widget is removed from its current group (if any) and then inserted into this group.

It is put at index n - or at the end, if n >= children(). This can also be used to rearrange the widgets inside a group.

## ◆ insert() [2/2]

void Fl_Group::insert | ( | Fl_Widget & | o,
|  | Fl_Widget * | before )
| inline

This does insert(w, find(before)).

This will append the widget if `before` is not in the group.

## ◆ on_insert()

int Fl_Group::on_insert | ( | Fl_Widget * | candidate,
|  | int | index )
| protected virtual

Allow derived groups to act when a widget is added as a child.

Widgets derived from Fl_Group may store additional data for their children. Overriding this method will allow derived classes to generate these data structures just before the child is added.

This method usually returns the same index that was given in the parameters. By setting a new index, the position of other widgets in the child pointer array can be preserved (e.g. Fl_Scroll keeps its scroll bars as the last two children).

By returning -1, Fl_Group::insert will not add the child to array_. This is not recommended, but Fl_Table does something similar to forward children to a hidden group.

Parameters

  candidate | the candidate will be added to the child array_ after this method returns.
  index | add the child at this position in the array_

Returns
  index to position the child as planned
  a new index to force the child to a different position
  -1 to keep the group from adding the candidate

Reimplemented in Fl_Scroll, Fl_Tabs, and Fl_Tile.

## ◆ on_move()

int Fl_Group::on_move | ( | int | oldIndex,
|  | int | newIndex )
| protected virtual

Allow derived groups to act when a widget is moved within the group.

Widgets derived from Fl_Group may store additional data for their children. Overriding this method will allow derived classes to move these data structures just before the child itself is moved.

This method usually returns the new index that was given in the parameters. By setting a different destination index, the position of other widgets in the child pointer array can be preserved.

By returning -1, Fl_Group::insert will not move the child.

Parameters

  oldIndex | the current index of the child that will be moved
  newIndex | the new index of the child

Returns
  `newIndex` to position the child as planned
  a different index to force the child to a different position
  -1 to keep the group from moving the child

Reimplemented in Fl_Scroll, Fl_Tabs, and Fl_Tile.

## ◆ on_remove()

void Fl_Group::on_remove | ( | int | index | ) |
| protected virtual

Allow derived groups to act when a child widget is removed from the group.

Widgets derived from Fl_Group may store additional data for their children. Overriding this method will allow derived classes to remove these data structures just before the child is removed.

Parameters

  index | remove the child at this position in the array_

Reimplemented in Fl_Flex, Fl_Grid, Fl_Tabs, and Fl_Tile.

## ◆ remove() [1/3]

void Fl_Group::remove | ( | Fl_Widget & | o | ) |

Removes a widget from the group but does not delete it.

This method does nothing if the widget is not a child of the group.

This method differs from the clear() method in that it only affects a single widget and does not delete it from memory.

Note
  If you have the child's index anyway, use remove(int index) instead, because this doesn't need a child lookup in the group's table of children. This can be much faster, if there are lots of children.

## ◆ remove() [2/3]

void Fl_Group::remove | ( | Fl_Widget * | o | ) |
| inline

Removes the widget `o` from the group.

See also
  void remove(Fl_Widget&)

## ◆ remove() [3/3]

void Fl_Group::remove | ( | int | index | ) |

Removes the widget at `index` from the group but does not delete it.

This method does nothing if `index` is out of bounds.

This method differs from the clear() method in that it only affects a single widget and does not delete it from memory.

Since
  FLTK 1.3.0

## ◆ resizable() [1/3]

Fl_Widget * Fl_Group::resizable | ( |  | ) | const
| inline

Returns the group's resizable widget.

See void Fl_Group::resizable(Fl_Widget *o)

## ◆ resizable() [2/3]

void Fl_Group::resizable | ( | Fl_Widget & | o | ) |
| inline

Sets the group's resizable widget.

See void Fl_Group::resizable(Fl_Widget *o)

## ◆ resizable() [3/3]

void Fl_Group::resizable | ( | Fl_Widget * | o | ) |
| inline

The resizable widget defines both the resizing box and the resizing behavior of the group and its children.

If the resizable is NULL the group's size is fixed and all of the widgets in the group remain a fixed size and distance from the top-left corner. This is the default for groups derived from Fl_Window and Fl_Pack.

The resizable may be set to the group itself, in which case all of the widgets that are its direct children are resized proportionally. This is the default value for Fl_Group.

The resizable widget defines the resizing box for the group, which could be the group itself or one of the group's direct children. When the group is resized it calculates a new size and position for all of its children. Widgets that are horizontally or vertically inside the dimensions of the box are scaled to the new size. Widgets outside the box are moved.

Note
  The resizable of a group must be one of
  - NULL
  - the group itself
  - a direct child of the group.
  If you set any other widget that is not a direct child of the group as its resizable then the behavior is undefined. This is not checked by Fl_Group for historical reasons.

In these examples the gray area is the resizable:

It is possible to achieve any type of resize behavior by using an invisible Fl_Box as the resizable and/or by using a hierarchy of Fl_Group widgets, each with their own resizing strategies.

See the How Does Resizing Work? chapter for more examples and detailed explanation.

Note
  The resizable() widget of a window can also affect the window's resizing behavior if Fl_Window::size_range() is not called. Please see Fl_Window::default_size_range() for more information on how the default size range is calculated.

See also
  Fl_Window::size_range()
  Fl_Window::default_size_range()

## ◆ resize()

void Fl_Group::resize | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H )
| virtual

Resizes the Fl_Group widget and all of its children.

The Fl_Group widget first resizes itself, and then it moves and resizes all its children according to the rules documented for Fl_Group::resizable(Fl_Widget*)

See also
  Fl_Group::resizable(Fl_Widget*)
  Fl_Group::resizable()
  Fl_Widget::resize(int,int,int,int)

Reimplemented from Fl_Widget.

Reimplemented in Fl_Help_View, Fl_Input_Choice, Fl_Overlay_Window, Fl_Pack, Fl_Scroll, Fl_Spinner, Fl_Table, Fl_Tabs, Fl_Terminal, Fl_Text_Display, Fl_Tile, Fl_Tree, and Fl_Window.

## ◆ sizes()

int * Fl_Group::sizes | ( |  | ) |
| protected

Returns the internal array of widget sizes and positions.

For backward compatibility with FLTK versions before 1.4.

The sizes() array stores the initial positions of widgets as (left, right, top, bottom) quads. The first quad is the group, the second is the resizable (clipped to the group), and the rest are the children. If the group and/or the resizable() is a Fl_Window, then the first (left) and third (top) entries of their respective quads (x,y) are zero.

Deprecated
  Deprecated since 1.4.0. Please use bounds() instead.

Note
  This method will be removed in a future FLTK version (1.5.0 or higher).

Returns
  Array of int's with widget positions and sizes. The returned array is only valid until init_sizes() is called or widgets are added to or removed from the group.

Note
  Since FLTK 1.4.0 the returned array is a read-only and re-ordered copy of the internal bounds() array. Do not change its contents. If you need to rearrange children in a group, do so by resizing the children and call init_sizes().

See also
  bounds()

## ◆ update_child()

void Fl_Group::update_child | ( | Fl_Widget & | widget | ) | const
| protected

Draws a child only if it needs it.

This draws a child widget, if it is not clipped and if any damage() bits are set. The damage bits are cleared after drawing.

See also
  Fl_Group::draw_child(Fl_Widget& widget) const

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

- Fl_Group.H
- Fl_Group.cxx
- forms_compatibility.cxx