FLTK 1.4.1: Fl_Grid Class Reference

Fl_Grid is a container (layout) widget with multiple columns and rows. More...

#include <Fl_Grid.H>

Inheritance diagram for Fl_Grid:

Classes
class	Cell

Public Member Functions
Fl_Grid::Cell *	cell (Fl_Widget *widget) const
	Get the grid cell of widget `widget`. More...

Fl_Grid::Cell *	cell (int row, int col) const
	Get the grid cell of row `row` and column `col`. More...

virtual void	clear_layout ()
	Reset the layout w/o removing widgets. More...

void	col_gap (const int *value, size_t size)
	Set more than one column gaps at once. More...

int	col_gap (int col) const

void	col_gap (int col, int value)
	Set the gap of column `col`. More...

void	col_weight (const int *value, size_t size)
	Set the weight of more than one column. More...

int	col_weight (int col) const

void	col_weight (int col, int value)
	Set the weight of a column. More...

void	col_width (const int *value, size_t size)
	Set minimal widths of more than one column. More...

int	col_width (int col) const

void	col_width (int col, int value)
	Set the minimal width of a column. More...

short	cols () const

int	computed_col_width (int col) const

int	computed_row_height (int row) const

void	debug (int level=127)
	Output layout information of this Fl_Grid to stderr. More...

	Fl_Grid (int X, int Y, int W, int H, const char *L=0)
	Create a new Fl_Grid widget. More...

void	gap (int row_gap, int col_gap) const
	Get the default gaps for rows and columns. More...

virtual void	gap (int row_gap, int col_gap=-1)
	Set default gaps for rows and columns. More...

virtual void	layout ()
	Calculate the grid layout and resize and position all widgets. More...

virtual void	layout (int rows, int cols, int margin=-1, int gap=-1)
	Set the basic layout parameters of the Fl_Grid widget. More...

int	margin (int left, int top, int right, int bottom) const
	Returns all outside margin sizes of the grid. More...

virtual void	margin (int left, int top=-1, int right=-1, int bottom=-1)
	Set all margins (left, top, right, bottom). More...

bool	need_layout () const
	Return whether layout calculation is required.

void	need_layout (int set)
	Request or reset the request to calculate the layout of children. More...

virtual void	resize (int X, int Y, int W, int H) FL_OVERRIDE
	Recalculate the layout and position and resize all widgets. More...

void	row_gap (const int *value, size_t size)
	Set more than one row gaps at once. More...

int	row_gap (int row) const

void	row_gap (int row, int value)
	Set the gap of row `row`. More...

void	row_height (const int *value, size_t size)
	Set the minimal row height of more than one row. More...

int	row_height (int row) const

void	row_height (int row, int value)
	Set the minimal row height of row `row`. More...

void	row_weight (const int *value, size_t size)
	Set the weight of more than one row. More...

int	row_weight (int row) const

void	row_weight (int row, int value)
	Set the row weight of row `row`. More...

short	rows () const

void	show_grid (int set)
	Enable or disable drawing of the grid helper lines for visualization. More...

void	show_grid (int set, Fl_Color col)
	Enable or disable drawing of the grid helper lines for visualization. More...

Fl_Grid::Cell *	widget (Fl_Widget *wi, int row, int col, Fl_Grid_Align align=FL_GRID_FILL)
	Assign a widget to a grid cell and set its alignment. More...

Fl_Grid::Cell *	widget (Fl_Widget *wi, int row, int col, int rowspan, int colspan, Fl_Grid_Align align=FL_GRID_FILL)
	Assign a widget to a grid cell and set cell spanning and alignment. More...

Public Member Functions inherited from Fl_Group
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. More...

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. More...

void	begin ()
	Sets the current group so you can build the widget tree by just constructing the widgets. More...

Fl_Widget *	child (int n) const
	Returns the n'th child. More...

int	children () const
	Returns how many child widgets the group has.

void	clear ()
	Deletes all child widgets from memory recursively. More...

unsigned int	clip_children ()
	Returns the current clipping mode. More...

void	clip_children (int c)
	Controls whether the group widget clips the drawing of child widgets to its bounding box. More...

virtual int	delete_child (int n)
	Removes the widget at `index` from the group and deletes it. More...

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

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. More...

	Fl_Group (int, int, int, int, const char *=0)
	Creates a new Fl_Group widget using the given position, size, and label string. More...

void	focus (Fl_Widget *W)

void	forms_end ()
	This is for forms compatibility only.

int	handle (int) FL_OVERRIDE
	Handles the specified event. More...

void	init_sizes ()
	Resets the internal array of widget sizes and positions. More...

void	insert (Fl_Widget &, int i)
	The widget is removed from its current group (if any) and then inserted into this group. More...

void	insert (Fl_Widget &o, Fl_Widget *before)
	This does insert(w, find(before)). More...

void	remove (Fl_Widget &)
	Removes a widget from the group but does not delete it. More...

void	remove (Fl_Widget *o)
	Removes the widget `o` from the group. More...

void	remove (int index)
	Removes the widget at `index` from the group but does not delete it. More...

Fl_Widget *	resizable () const
	Returns the group's resizable widget. More...

void	resizable (Fl_Widget &o)
	Sets the group's resizable widget. More...

void	resizable (Fl_Widget *o)
	The resizable widget defines both the resizing box and the resizing behavior of the group and its children. More...

void	resize (int, int, int, int) FL_OVERRIDE
	Resizes the Fl_Group widget and all of its children. More...

virtual	~Fl_Group ()
	The destructor also deletes all the children. More...

Public Member Functions inherited from Fl_Widget
void	_clear_fullscreen ()

void	_set_fullscreen ()

void	activate ()
	Activates the widget. More...

unsigned int	active () const
	Returns whether the widget is active. More...

int	active_r () const
	Returns whether the widget and all of its parents are active. More...

Fl_Align	align () const
	Gets the label alignment. More...

void	align (Fl_Align alignment)
	Sets the label alignment. More...

long	argument () const
	Gets the current user data (long) argument that is passed to the callback function. More...

void	argument (long v)
	Sets the current user data (long) argument that is passed to the callback function. More...

virtual class Fl_Gl_Window *	as_gl_window ()
	Returns an Fl_Gl_Window pointer if this widget is an Fl_Gl_Window. More...

virtual class Fl_Gl_Window const *	as_gl_window () const

virtual Fl_Group *	as_group ()
	Returns an Fl_Group pointer if this widget is an Fl_Group. More...

virtual Fl_Group const *	as_group () const

virtual Fl_Window *	as_window ()
	Returns an Fl_Window pointer if this widget is an Fl_Window. More...

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. More...

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. More...

void	bind_image (Fl_Image *img)
	Sets the image to use as part of the widget label when in the active state. More...

void	bind_image (int f)
	Bind the image to the widget, so the widget will delete the image when it is no longer needed. More...

Fl_Boxtype	box () const
	Gets the box type of the widget. More...

void	box (Fl_Boxtype new_box)
	Sets the box type for the widget. More...

Fl_Callback_p	callback () const
	Gets the current callback function for the widget. More...

void	callback (Fl_Callback *cb)
	Sets the current callback function for the widget. More...

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. More...

void	callback (Fl_Callback cb, void p)
	Sets the current callback function and data for the widget. More...

void	callback (Fl_Callback0 *cb)
	Sets the current callback function for the widget. More...

void	callback (Fl_Callback1 *cb, long p=0)
	Sets the current callback function for the widget. More...

unsigned int	changed () const
	Checks if the widget value changed since the last callback. More...

void	clear_active ()
	Marks the widget as inactive without sending events or changing focus. More...

void	clear_changed ()
	Marks the value of the widget as unchanged. More...

void	clear_damage (uchar c=0)
	Clears or sets the damage flags. More...

void	clear_output ()
	Sets a widget to accept input. More...

void	clear_visible ()
	Hides the widget. More...

void	clear_visible_focus ()
	Disables keyboard focus navigation with this widget. More...

Fl_Color	color () const
	Gets the background color of the widget. More...

void	color (Fl_Color bg)
	Sets the background color of the widget. More...

void	color (Fl_Color bg, Fl_Color sel)
	Sets the background and selection color of the widget. More...

Fl_Color	color2 () const
	For back compatibility only. More...

void	color2 (unsigned a)
	For back compatibility only. More...

int	contains (const Fl_Widget *w) const
	Checks if w is a child of this widget. More...

void	copy_label (const char *new_label)
	Sets the current label. More...

void	copy_tooltip (const char *text)
	Sets the current tooltip text. More...

uchar	damage () const
	Returns non-zero if draw() needs to be called. More...

void	damage (uchar c)
	Sets the damage bits for the widget. More...

void	damage (uchar c, int x, int y, int w, int h)
	Sets the damage bits for an area inside the widget. More...

int	damage_resize (int, int, int, int)
	Internal use only.

void	deactivate ()
	Deactivates the widget. More...

Fl_Image *	deimage ()
	Gets the image that is used as part of the widget label when in the inactive state. More...

const Fl_Image *	deimage () const
	Gets the image that is used as part of the widget label when in the inactive state. More...

void	deimage (Fl_Image &img)
	Sets the image to use as part of the widget label when in the inactive state. More...

void	deimage (Fl_Image *img)
	Sets the image to use as part of the widget label when in the inactive state. More...

int	deimage_bound () const
	Returns whether the inactive image is managed by the widget. More...

void	do_callback (Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
	Calls the widget callback function with default arguments. More...

void	do_callback (Fl_Widget *widget, long arg, Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
	Calls the widget callback function with arbitrary arguments. More...

void	do_callback (Fl_Widget widget, void arg=0, Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
	Calls the widget callback function with arbitrary arguments. More...

virtual void	draw ()=0
	Draws the widget. More...

void	draw_label (int, int, int, int, Fl_Align) const
	Draws the label in an arbitrary bounding box with an arbitrary alignment. More...

int	h () const
	Gets the widget height. More...

virtual int	handle (int event)
	Handles the specified event. More...

virtual void	hide ()
	Makes a widget invisible. More...

int	horizontal_label_margin ()
	Get the spacing between the label and the horizontal edge of the widget. More...

void	horizontal_label_margin (int px)
	Set the spacing between the label and the horizontal edge of the widget. More...

Fl_Image *	image ()
	Gets the image that is used as part of the widget label when in the active state. More...

const Fl_Image *	image () const
	Gets the image that is used as part of the widget label when in the active state. More...

void	image (Fl_Image &img)
	Sets the image to use as part of the widget label when in the active state. More...

void	image (Fl_Image *img)
	Sets the image to use as part of the widget label when in the active state. More...

int	image_bound () const
	Returns whether the image is managed by the widget. More...

int	inside (const Fl_Widget *wgt) const
	Checks if this widget is a child of `wgt`. More...

int	is_label_copied () const
	Returns whether the current label was assigned with copy_label(). More...

const char *	label () const
	Gets the current label text. More...

void	label (const char *text)
	Sets the current label pointer. More...

void	label (Fl_Labeltype a, const char *b)
	Shortcut to set the label text and type in one call. More...

int	label_image_spacing ()
	Return the gap size between the label and the image. More...

void	label_image_spacing (int gap)
	Set the gap between the label and the image in pixels. More...

Fl_Color	labelcolor () const
	Gets the label color. More...

void	labelcolor (Fl_Color c)
	Sets the label color. More...

Fl_Font	labelfont () const
	Gets the font to use. More...

void	labelfont (Fl_Font f)
	Sets the font to use. More...

Fl_Fontsize	labelsize () const
	Gets the font size in pixels. More...

void	labelsize (Fl_Fontsize pix)
	Sets the font size in pixels. More...

Fl_Labeltype	labeltype () const
	Gets the label type. More...

void	labeltype (Fl_Labeltype a)
	Sets the label type. More...

void	measure_label (int &ww, int &hh) const
	Sets width ww and height hh accordingly with the label size. More...

bool	needs_keyboard () const
	Returns whether this widget needs a keyboard. More...

void	needs_keyboard (bool needs)
	Sets whether this widget needs a keyboard. More...

unsigned int	output () const
	Returns if a widget is used for output only. More...

Fl_Group *	parent () const
	Returns a pointer to the parent widget. More...

void	parent (Fl_Group *p)
	Internal use only - "for hacks only". More...

void	position (int X, int Y)
	Repositions the window or widget. More...

void	redraw ()
	Schedules the drawing of the widget. More...

void	redraw_label ()
	Schedules the drawing of the label. More...

virtual void	resize (int x, int y, int w, int h)
	Changes the size or position of the widget. More...

Fl_Color	selection_color () const
	Gets the selection color. More...

void	selection_color (Fl_Color a)
	Sets the selection color. More...

void	set_active ()
	Marks the widget as active without sending events or changing focus. More...

void	set_changed ()
	Marks the value of the widget as changed. More...

void	set_output ()
	Sets a widget to output only. More...

void	set_visible ()
	Makes the widget visible. More...

void	set_visible_focus ()
	Enables keyboard focus navigation with this widget. More...

int	shortcut_label () const
	Returns whether the widget's label uses '&' to indicate shortcuts. More...

void	shortcut_label (int value)
	Sets whether the widget's label uses '&' to indicate shortcuts. More...

virtual void	show ()
	Makes a widget visible. More...

void	size (int W, int H)
	Changes the size of the widget. More...

int	take_focus ()
	Gives the widget the keyboard focus. More...

unsigned int	takesevents () const
	Returns if the widget is able to take events. More...

int	test_shortcut ()
	Returns true if the widget's label contains the entered '&x' shortcut. More...

const char *	tooltip () const
	Gets the current tooltip text. More...

void	tooltip (const char *text)
	Sets the current tooltip text. More...

Fl_Window *	top_window () const
	Returns a pointer to the top-level window for the widget. More...

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. More...

uchar	type () const
	Gets the widget type. More...

void	type (uchar t)
	Sets the widget type. More...

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. More...

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. More...

void	vertical_label_margin (int px)
	Set the spacing between the label and the vertical edge of the widget. More...

unsigned int	visible () const
	Returns whether a widget is visible. More...

unsigned int	visible_focus () const
	Checks whether this widget has a visible focus. More...

void	visible_focus (int v)
	Modifies keyboard focus navigation. More...

int	visible_r () const
	Returns whether a widget and all its parents are visible. More...

int	w () const
	Gets the widget width. More...

Fl_When	when () const
	Returns the conditions under which the callback is called. More...

void	when (uchar i)
	Sets the flags used to decide when a callback is called. More...

Fl_Window *	window () const
	Returns a pointer to the nearest parent window up the widget hierarchy. More...

int	x () const
	Gets the widget position in its window. More...

int	y () const
	Gets the widget position in its window. More...

virtual	~Fl_Widget ()
	Destroys the widget. More...

Protected Member Functions
Cell *	add_cell (int row, int col)

virtual void	draw () FL_OVERRIDE
	Draws the Fl_Grid widget and all children. More...

virtual void	draw_grid ()
	Draws the grid helper lines for design and debugging purposes. More...

void	init ()

void	on_remove (int) FL_OVERRIDE
	Fl_Group calls this method when a child widget is about to be removed. More...

void	remove_cell (int row, int col)

Protected Member Functions inherited from Fl_Group
Fl_Rect *	bounds ()
	Returns the internal array of widget sizes and positions. More...

void	draw () FL_OVERRIDE
	Draws the widget. More...

void	draw_child (Fl_Widget &widget) const
	Forces a child to redraw. More...

void	draw_children ()
	Draws all children of the group. More...

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. More...

virtual int	on_move (int, int)
	Allow derived groups to act when a widget is moved within the group. More...

virtual void	on_remove (int)
	Allow derived groups to act when a child widget is removed from the group. More...

int *	sizes ()
	Returns the internal array of widget sizes and positions. More...

void	update_child (Fl_Widget &widget) const
	Draws a child only if it needs it. More...

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. More...

void	draw_focus (Fl_Boxtype t, int X, int Y, int W, int H) const
	Draws a focus rectangle around the widget. More...

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. More...

void	draw_label () const
	Draws the widget's label at the defined label position. More...

void	draw_label (int, int, int, int) const
	Draws the label in an arbitrary bounding box. More...

	Fl_Widget (int x, int y, int w, int h, const char *label=0L)
	Creates a widget at the given position and size. More...

unsigned int	flags () const
	Gets the widget flags mask.

void	h (int v)
	Internal use only. More...

void	set_flag (unsigned int c)
	Sets a flag in the flags mask.

void	w (int v)
	Internal use only. More...

void	x (int v)
	Internal use only. More...

void	y (int v)
	Internal use only. More...

Protected Attributes
bool	draw_grid_

Fl_Color	grid_color

Friends
class	Fl_Grid_Type

Additional Inherited Members
Static Public Member Functions inherited from Fl_Group
static Fl_Group *	current ()
	Returns the currently active group. More...

static void	current (Fl_Group *g)
	Sets the current group. More...

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. More...

static unsigned int	label_shortcut (const char *t)
	Returns the Unicode value of the '&x' shortcut in a given text. More...

static int	test_shortcut (const char *, const bool require_alt=false)
	Returns true if the given text `t` contains the entered '&x' shortcut. More...

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

Fl_Grid is a container (layout) widget with multiple columns and rows.

This container widget features very flexible layouts in columns and rows w/o the need to position each child widget in x/y coordinates.

Widgets are assigned to grid cells (column, row) with their minimal sizes in w() and h(). The x() and y() positions are ignored and can be (0, 0). Fl_Grid calculates widget positions and resizes the widgets to fit into the grid. It is possible to create a single row or column of widgets with Fl_Grid.

You should design your grid with the smallest possible sizes of all widgets in mind. Fl_Grid will automatically assign additional space to cells according to some rules (described later) when resizing the Fl_Grid widget.

Hint: You should set a minimum window size to make sure the Fl_Grid is never resized below its minimal sizes. Resizing below the given widget sizes results in undefined behavior.

Fl_Grid and other container widgets (e.g. Fl_Group) can be nested. One main advantage of this usage is that widget coordinates in embedded Fl_Group widgets become relative to the group and will be positioned as expected.

Todo:: This (relative group coordinates of nested groups of Fl_Grid) needs explanation and maybe an example.

Fl_Grid child widgets are handled by its base class Fl_Group but Fl_Grid stores additional data corresponding to each widget in internal grid cells.

Fl_Grid children are allowed to span multiple columns and rows like HTML <table> cells. Individual children can have fixed sizes or be aligned inside their cells (left, right, top, bottom, and more) and/or follow their cell sizes when the Fl_Grid container is resized.

Note to resizing: since Fl_Grid uses its own layout algorithm the normal Fl_Group::resizable() widget is ignored (if set). Calling init_sizes() is not necessary.

Note: Fl_Grid is, as of FLTK 1.4.1, still in experimental state and should be used with caution. The API can still be changed although it is assumed to be almost stable - as stable as possible for a first release.

Example: Simple 3x3 Fl_Grid with five buttons:

#include <FL/Fl.H>
#include <FL/Fl_Double_Window.H>
#include <FL/Fl_Grid.H>
#include <FL/Fl_Button.H>
 
int main(int argc, char **argv) {
  Fl_Double_Window *win = new Fl_Double_Window(320, 180, "3x3 Fl_Grid with Buttons");
  // create the Fl_Grid container with five buttons
  Fl_Grid *grid = new Fl_Grid(0, 0, win->w(), win->h());
  grid->layout(3, 3, 10, 10);
  grid->color(FL_WHITE);
  Fl_Button *b0 = new Fl_Button(0, 0, 0, 0, "New");
  Fl_Button *b1 = new Fl_Button(0, 0, 0, 0, "Options");
  Fl_Button *b3 = new Fl_Button(0, 0, 0, 0, "About");
  Fl_Button *b4 = new Fl_Button(0, 0, 0, 0, "Help");
  Fl_Button *b6 = new Fl_Button(0, 0, 0, 0, "Quit");
  // assign buttons to grid positions
  grid->widget(b0, 0, 0);
  grid->widget(b1, 0, 2);
  grid->widget(b3, 1, 1);
  grid->widget(b4, 2, 0);
  grid->widget(b6, 2, 2);
  grid->show_grid(0);     // 1 to display grid helper lines
  grid->end();
  win->end();
  win->resizable(grid);
  win->size_range(300, 100);
  win->show(argc, argv);
  return Fl::run();
}

Constructor & Destructor Documentation

◆ Fl_Grid()

Fl_Grid::Fl_Grid	(	int	X,
		int	Y,
		int	W,
		int	H,
		const char *	L = `0`
	)

Create a new Fl_Grid widget.

Todo:: More documentation of Fl_Grid constructor?

Member Function Documentation

◆ cell() [1/2]

Fl_Grid::Cell * Fl_Grid::cell ( Fl_Widget * widget ) const

Get the grid cell of widget widget.

The pointer to the cell can be used for further assignment of properties like alignment etc.

Hint: If you know the row and column index of the cell you should use Fl_Grid::cell(int row, int col) instead because it is much faster.

Please see Fl_Grid::cell(int row, int col) for details and the validity of cell pointers.

Parameters

[in] widget widget whose cell is requested

Return values

NULL	if `widget` is not assigned to a cell

◆ cell() [2/2]

Fl_Grid::Cell * Fl_Grid::cell	(	int	row,
		int	col
	)		const

Get the grid cell of row row and column col.

Widgets and other attributes are organized in cells (Fl_Grid::Cell).

This cell is an opaque structure (class) with some public methods. Don't assume anything about grid cell sizes and ordering in memory. These are implementation details that can be changed without notice.

The validity of an Fl_Grid::Cell pointer is limited. It will definitely be invalidated when the overall grid layout is changed, for instance by calling layout(int, int).

Adding new cells beyond the current layout limits will also invalidate cell pointers but this is not (yet) implemented. Attempts to assign widgets to out-of-bounds cells are currently ignored.

The only well-defined usage of cell pointers is to set one or more properties like widget alignment of a cell after retrieving the cell pointer. Don't store cell pointers in your program for later reference.

Parameters

[in]	row	row index
[in]	col	column index

Returns: pointer to cell

Return values

NULL	if `row` or `col` is out of bounds or no widget was assigned

◆ clear_layout()

void Fl_Grid::clear_layout ( )

virtual

Reset the layout w/o removing widgets.

Removes all cells and sets rows and cols to zero. Existing widgets are kept as children of the Fl_Group (base class) but are hidden.

This method should be rarely used. You may want to call Fl_Grid::clear() to remove all widgets and reset the layout to zero rows and columns.

You must call layout(int rows, int cols, ...) to set a new layout, allocate new cells, and assign widgets to new cells.

Todo:: Fl_Grid::clear() needs to be implemented as documented above!

◆ col_gap() [1/2]

void Fl_Grid::col_gap	(	const int *	value,
		size_t	size
	)

Set more than one column gaps at once.

See also: Fl_Grid::col_weight(const int *value, size_t size) for handling of the value array and size.

◆ col_gap() [2/2]

void Fl_Grid::col_gap	(	int	col,
		int	value
	)

Set the gap of column col.

Note that the gap is right of each column except the last one which is ignored. Use margin() for the right most column.

Parameters

[in]	col	column
[in]	value	gap size after the column

◆ col_weight() [1/2]

void Fl_Grid::col_weight	(	const int *	value,
		size_t	size
	)

Set the weight of more than one column.

The values are taken from the array value and assigned sequentially to columns, starting from column 0. If the array size is too large extraneous values are ignored.

Negative values in the array are not assigned to their columns, i.e. the existing value for the corresponding column is not changed.

Example:

int val[] = { 0, 0, 50, -1, -1, 50, 0 };

grid->col_weight(val, sizeof(val)/sizeof(val[0]));

Parameters

[in]	value	an array of column weights
[in]	size	the size of the array (number of values)

◆ col_weight() [2/2]

void Fl_Grid::col_weight	(	int	col,
		int	value
	)

Set the weight of a column.

Column and row weights are used to distribute additional space when the grid is resized beyond its defined (minimal) size. All weight values are relative and can be chosen freely. Suggested weights are in the range {0 .. 100}, 0 (zero) disables resizing of the column.

How does it work?

Whenever additional space (say: SPACE in pixels) is to be distributed to a set of columns the weights of all columns are added to a value SUM, then every single column width is increased by the value (in pseudo code):

col.width += SPACE * col.weight / SUM

Resulting pixel values are rounded to the next integer and rounding differences are added to or subtracted from the column with the highest weight. If more columns have the same weight one of them is chosen.

Note: If none of the columns considered for resizing have weights > 0 then Fl_Grid assigns the remaining space to an arbitrary column or to all considered columns evenly. This is implementation defined and can be changed without notice. You can avoid this situation by designing your grid with sensible sizes and weights.

Parameters

[in]	col	column number (counting from 0)
[in]	value	weight, must be >= 0

◆ col_width() [1/2]

void Fl_Grid::col_width	(	const int *	value,
		size_t	size
	)

Set minimal widths of more than one column.

The values are taken from the array value and assigned sequentially to columns, starting from column 0. If the array size is too large extraneous values are ignored.

Negative values in the array are not assigned to their columns, i.e. the existing value for the corresponding column is not changed.

Example:

int widths[] = { 0, 0, 50, -1, -1, 50, 0 };

grid->col_width(widths, sizeof(width)/sizeof(width[0]));

Parameters

[in]	value	an array of column widths
[in]	size	the size of the array (number of values)

◆ col_width() [2/2]

void Fl_Grid::col_width	(	int	col,
		int	value
	)

Set the minimal width of a column.

Column widths are calculated by using the maximum of all widget widths in that column and the given column width. After calculating the width additional space is added when resizing according to the weight of the column.

You can set one or more column widths in one call by using Fl_Grid::col_width(const int *value, size_t size).

Parameters

[in]	col	column number (counting from 0)
[in]	value	minimal column width, must be >= 0

See also: Fl_Grid::col_width(const int *value, size_t size)

◆ debug()

void Fl_Grid::debug ( int level = 127 )

Output layout information of this Fl_Grid to stderr.

Parameter level will be used to define the amount of output.

0 = nothing
127 = everything
other values not yet defined

Note: It is not yet defined which kind of values level will have, either a numerical value (127 = maximum, 0 = nothing) or a bit mask that determines what to output.

Todo:

Add more information about cells and children.

Control output by using level.

Parameters

[in] level not yet used (0-127, default = 127)

◆ draw()

void Fl_Grid::draw ( void )

protectedvirtual

Draws the Fl_Grid widget and all children.

If the layout has been changed layout() is called before the widget is drawn so all children are arranged as designed.

See also: layout(); need_layout()

Implements Fl_Widget.

◆ draw_grid()

void Fl_Grid::draw_grid ( )

protectedvirtual

Draws the grid helper lines for design and debugging purposes.

This method is protected so it can be modified in subclasses.

◆ gap() [1/2]

void Fl_Grid::gap	(	int *	row_gap,
		int *	col_gap
	)		const

Get the default gaps for rows and columns.

Parameters

[out]	row_gap	pointer to int to receive column gap, may be NULL
[out]	col_gap	pointer to int to receive column gap, may be NULL

◆ gap() [2/2]

void Fl_Grid::gap	(	int	row_gap,
		int	col_gap = `-1`
	)

virtual

Set default gaps for rows and columns.

All gaps are positioned below the rows and right of their columns.

The bottom row and the right-most column don't have a gap, i.e. the gap sizes of these columns and rows are ignored. You can use a right or bottom margin instead.

You have to specify at least one argument, col_gap is optional. If you don't specify an argument or use a negative value (e.g. -1) then that margin is not affected.

You can also initialize the default gaps with layout(int, int, int, int).

Parameters

[in]	row_gap	default gap for all rows
[in]	col_gap	default gap for all columns

See also: Fl_Grid::layout(int rows, int cols, int margin, int gap)

◆ layout() [1/2]

void Fl_Grid::layout ( )

virtual

Calculate the grid layout and resize and position all widgets.

This is called automatically when the Fl_Grid is resized. You need to call it once after you added widgets or moved widgets between cells.

Calling it once after all modifications are completed is enough.

Todo:: Document when and why to call layout() w/o args. See Fl_Flex::layout()

See also: Fl_Grid::layout(int rows, int cols, int margin, int gap)

◆ layout() [2/2]

void Fl_Grid::layout	(	int	rows,
		int	cols,
		int	margin = `-1`,
		int	gap = `-1`
	)

virtual

Set the basic layout parameters of the Fl_Grid widget.

You need to specify at least rows and cols to define a layout before you can add widgets to the grid.

Parameters margin and gap are optional.

You can call layout(int rows, int cols, int margin, int gap) again to change the layout but this is inefficient since all cells are reallocated if the layout changed.

Calling this with the same values of rows and cols is fast and can be used to change margin and gap w/o reallocating the cells.

margin sets all margins (left, top, right, bottom) to the same value. Negative values (e.g. -1) don't change the established margins. The default value set by the constructor is 0.

gap sets row and column gaps to the same value. Negative values (e.g. -1) do not affect the established gaps. The default value set by the constructor is 0.

After you added all widgets you must call layout() once without arguments to calculate the actual layout and to position and resize all widgets.

Todo:: Document when and why to call layout() w/o args. See Fl_Flex::layout()

Parameters

[in]	rows	number of rows
[in]	cols	number of columns
[in]	margin	margin size inside the Fl_Grid's border
[in]	gap	gap size between cells

See also: Fl_Grid::layout()

◆ margin() [1/2]

int Fl_Grid::margin	(	int *	left,
		int *	top,
		int *	right,
		int *	bottom
	)		const

Returns all outside margin sizes of the grid.

All margin sizes are returned in the given arguments. If any argument is NULL the respective value is not returned.

Parameters

[out]	left	returns left margin if not `NULL`
[out]	top	returns top margin if not `NULL`
[out]	right	returns right margin if not `NULL`
[out]	bottom	returns bottom margin if not `NULL`

Returns: whether all margins are equal

Return values

1	all margins have the same size
0	at least one margin has a different size

◆ margin() [2/2]

void Fl_Grid::margin	(	int	left,
		int	top = `-1`,
		int	right = `-1`,
		int	bottom = `-1`
	)

virtual

Set all margins (left, top, right, bottom).

All margins are measured in pixels inside the box borders. You need to specify at least one argument, all other arguments are optional. If you don't specify an argument or use a negative value (e.g. -1) then that particular margin is not affected.

Parameters

[in]	left	left margin
[in]	top	top margin
[in]	right	right margin
[in]	bottom	bottom margin

◆ need_layout()

void Fl_Grid::need_layout ( int set )

inline

Request or reset the request to calculate the layout of children.

If called with true (1) this calls redraw() to schedule a full draw(). When draw is eventually called, the layout is (re)calculated before actually drawing the widget.

Parameters

[in] set 1 to request layout calculation,
0 to reset the request

◆ on_remove()

void Fl_Grid::on_remove ( int index )

protectedvirtual

Fl_Group calls this method when a child widget is about to be removed.

Make sure that the widget is also removed from our internal list of children.

Reimplemented from Fl_Group.

◆ resize()

void Fl_Grid::resize	(	int	X,
		int	Y,
		int	W,
		int	H
	)

virtual

Recalculate the layout and position and resize all widgets.

This method overrides Fl_Group::resize() and calculates all positions and sizes of its children according to its own rules.

Parameters

[in]	X,Y	new widget position
[in]	W,H	new widget size

Reimplemented from Fl_Widget.

◆ row_gap() [1/2]

void Fl_Grid::row_gap	(	const int *	value,
		size_t	size
	)

Set more than one row gaps at once.

See also: Fl_Grid::col_weight(const int *value, size_t size) for handling of the value array and size.

◆ row_gap() [2/2]

void Fl_Grid::row_gap	(	int	row,
		int	value
	)

Set the gap of row row.

Note that the gap is below each row except the last one which is ignored. Use margin() for the bottom row.

Parameters

[in]	row	row
[in]	value	gap size below the row

◆ row_height() [1/2]

void Fl_Grid::row_height	(	const int *	value,
		size_t	size
	)

Set the minimal row height of more than one row.

Parameters

[in]	value	array of height values
[in]	size	size of array `value`

See also: Fl_Grid::col_weight(const int *value, size_t size) for handling of the value array and size.

◆ row_height() [2/2]

void Fl_Grid::row_height	(	int	row,
		int	value
	)

Set the minimal row height of row row.

Parameters

[in]	row	row
[in]	value	minimal height of the row

◆ row_weight() [1/2]

void Fl_Grid::row_weight	(	const int *	value,
		size_t	size
	)

Set the weight of more than one row.

Parameters

[in]	value	array of height values
[in]	size	size of array `value`

See also: Fl_Grid::col_weight(const int *value, size_t size) for handling of the value array and size.

◆ row_weight() [2/2]

void Fl_Grid::row_weight	(	int	row,
		int	value
	)

Set the row weight of row row.

Parameters

[in]	row	row
[in]	value	weight of the row

◆ show_grid() [1/2]

void Fl_Grid::show_grid ( int set )

inline

Enable or disable drawing of the grid helper lines for visualization.

Use this method during the design stage of your Fl_Grid widget or for debugging if widgets are not positioned as intended.

The default is a light green color but you can change it for better contrast if needed, see show_grid(int set, Fl_Color col).

Note: You can define the environment variable FLTK_GRID_DEBUG=1 to set show_grid(1) for all Fl_Grid widgets at construction time. This enables you to debug the grid layout w/o changing code.

Parameters

[in] set 1 (true) = draw, 0 = don't draw the grid

See also: show_grid(int set, Fl_Color col)

◆ show_grid() [2/2]

void Fl_Grid::show_grid	(	int	set,
		Fl_Color	col
	)

inline

Enable or disable drawing of the grid helper lines for visualization.

This method also sets the color used for the helper lines.

The default is a light green color but you can change it to any color for better contrast if needed.

Parameters

[in]	set	1 (true) = draw, 0 = don't draw the grid
[in]	col	color to use for the grid helper lines

See also: show_grid(int set)

◆ widget() [1/2]

Fl_Grid::Cell * Fl_Grid::widget	(	Fl_Widget *	wi,
		int	row,
		int	col,
		Fl_Grid_Align	align = `FL_GRID_FILL`
	)

Assign a widget to a grid cell and set its alignment.

This short form sets row and column spanning attributes to (1, 1).

For more information see Fl_Grid::widget(Fl_Widget *wi, int row, int col, int rowspan, int colspan, Fl_Grid_Align align)

Parameters

[in]	wi	widget to be assigned to the cell
[in]	row	row
[in]	col	column
[in]	align	widget alignment inside the cell

Returns: assigned cell

Return values

NULL	if `row` or `col` is out of bounds

See also: Fl_Grid::widget(Fl_Widget *wi, int row, int col, int rowspan, int colspan, Fl_Grid_Align align)

◆ widget() [2/2]

Fl_Grid::Cell * Fl_Grid::widget	(	Fl_Widget *	wi,
		int	row,
		int	col,
		int	rowspan,
		int	colspan,
		Fl_Grid_Align	align = `FL_GRID_FILL`
	)

Assign a widget to a grid cell and set cell spanning and alignment.

Default alignment is FL_GRID_FILL which stretches the widget in horizontal and vertical directions to fill the whole cell(s) given by colspan and rowspan.

You can use this method to move a widget from one cell to another; it is automatically removed from its old cell. If the new cell is already assigned to another widget that widget is deassigned but kept as a child of the group.

Before you can assign a widget to a cell it must have been created as a child of the Fl_Grid widget (i.e. its Fl_Group).

Parameters

[in]	wi	widget to be assigned to the cell
[in]	row	row
[in]	col	column
[in]	rowspan	vertical span in cells, default 1
[in]	colspan	horizontal span in cells, default 1
[in]	align	widget alignment inside the cell

Returns: assigned cell

Return values

NULL	if `row` or `col` is out of bounds or `wi` is not a child

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

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Fl_Grid()

Member Function Documentation

◆ cell() [1/2]

◆ cell() [2/2]

◆ clear_layout()

◆ col_gap() [1/2]

◆ col_gap() [2/2]

◆ col_weight() [1/2]

◆ col_weight() [2/2]

◆ col_width() [1/2]

◆ col_width() [2/2]

◆ debug()

◆ draw()

◆ draw_grid()

◆ gap() [1/2]

◆ gap() [2/2]

◆ layout() [1/2]

◆ layout() [2/2]

◆ margin() [1/2]

◆ margin() [2/2]

◆ need_layout()

◆ on_remove()

◆ resize()

◆ row_gap() [1/2]

◆ row_gap() [2/2]

◆ row_height() [1/2]

◆ row_height() [2/2]

◆ row_weight() [1/2]

◆ row_weight() [2/2]

◆ show_grid() [1/2]

◆ show_grid() [2/2]

◆ widget() [1/2]

◆ widget() [2/2]