edelib: MessageBox Class Reference

edelib 1.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Related Functions | List of all members
MessageBox Class Reference
FLTK widgets and functions

Standard dialog. More...

`#include <edelib/MessageBox.h>`

Inheritance diagram for MessageBox:

## Public Member Functions
| MessageBox (MessageBoxType t=MSGBOX_PLAIN)
| ~MessageBox ()
void | set_text (const char *t)
bool | set_icon (const char *path)
bool | set_theme_icon (const char *name)
void | set_xpm_icon (const char *const *arr)
void | set_icon_from_type (MessageBoxIconType type)
const char * | get_input (void)
void | set_input (const char *txt)
void | focus_button (int b)
void | add_button (Fl_Button *b, MessageBoxButtonType bt=MSGBOX_BUTTON_PLAIN)
void | add_button (const char *l, MessageBoxButtonType bt=MSGBOX_BUTTON_PLAIN, Fl_Callback cb=0, void *param=0)
void | clear (MessageBoxType t=MSGBOX_PLAIN)
void | run_plain (bool center=true)
int | run (bool center=true)

## Static Public Member Functions
static void | set_themed_icons (const char *msg, const char *alert=0, const char *ask=0, const char *input=0, const char *password=0)
static void | clear_themed_icons (void)

## Related Functions
(Note that these are not member functions.)
void | themed_dialog_icons (const char *msg, const char *alert=0, const char *ask=0, const char *input=0, const char *password=0)
void | message (const char *fmt,...)
void | alert (const char *fmt,...)
int | ask (const char *fmt,...)
const char * | input (const char *fmt, const char *deflt=0,...)
const char * | password (const char *fmt, const char *deflt=0,...)

## Detailed Description

Standard dialog.

MessageBox is class for quickly building ordianary dialogs with applied layout. This means following: it will resize to fit larger text input or it will resize added buttons (to fit their labels), applying that to whole window too.

This class is not meant to be used to construct complicated dialogs nor to construct dialogs with different elements or layout.

So how to be used? MessageBox is by default MSGBOX_PLAIN, which means that is ordianary dialog without any input. And here is the code:

MessageBox mb;
// add some message
mb.set_text("This is sample text");
// add button
mb.add_button("&Close");
// show dialog
mb.run_plain();

This sample will run dialog with provided text and one 'Close' button. By default, this button will not have any callback attached to it, so adding is done like:

...
mb.add_button("&Close", MSGBOX_BUTTON_PLAIN, some_callback_func);
...

Now, clicking on 'Close' button, it will call some_callback_func. Passing data to callback function is done via fltk style, like:

...
// send 'some_param' to callback
mb.add_button("&Close", MSGBOX_BUTTON_PLAIN, some_callback_func, some_param);
...

add_button() can accept previously declared Fl_Button with already set callback or properties so you can add it like:

...
Fl_Button* b = new Fl_Button(...);
b->callback(...);
mb.add_button(b);

If you want to add Fl_Return_Button (button with 'enter' as shortcut), using MSGBOX_BUTTON_RETURN parameter will do the job, like:

...
mb.add_button("&Close", MSGBOX_BUTTON_RETURN, ...);
// or already pre-allocated
Fl_Return_Button* b = new Fl_Return_Button(...);
mb.add_button(b, MSGBOX_BUTTON_RETURN);

Note
  If you added pre-allocated Fl_Button or Fl_Return_Button, make sure it is not deleted somewhere in the code since MessageBox will do that. What this means ? This means that added Fl_Button or Fl_Return_Button must not be inside begin()/end() functions, nor added to some group via add() or data will be deleted twice, crashing program probably.

Adding more buttons is done via calling add_button() multiple times. You can add max 4 buttons to dialog. This is dialog with 'Yes' and 'No' buttons:

MessageBox mb;
mb.set_text("Would you like to quit");
mb.add_button("&No", ...);
mb.add_button("&Yes", ...);
mb.run_plain();

When multiple buttons are added, they should be added in reverse order, which means that first added button will be at right edge of dialog and any further added will be placed toward left edge.

If you want dialog with input field (max. 1 input field is allowed), this is how:

MessageBox mb(MSGBOX_INPUT);
mb.set_text("Please input something");
mb.add_button("&Close me", ...);
mb.run_plain();
// when dialog is closed, getting input is like
printf("You entered %s\n", mb.get_input());

get_input() will return NULL if nothing was entered or if MSGBOX_PLAIN was set.

Here is full sample of dialog requesting some password, where typed data is hidden with asterisks:

void close_cb(Fl_Widget*, void* b) {
MessageBox* mb = (MessageBox*)b;
b->hide();
}
// somewhere in the code
MessageBox mb(MSGBOX_INPUT_SECRET);
mb.set_text("Please enter password");
mb.add_button("&Close", MSGBOX_BUTTON_PLAIN, close_cb, &mb);
mb.run_plain();
const char* ret = mb.get_input();
if(ret)
printf("You entered %s\n", ret);
else
printf("Nothing was entered");

Setting callbacks each time just to get some status can be cumbersome, so there is a run() function which is a shortcut for run_plain() with callbacks attached to each button. This function will close dialog and return number of pressed button (starting from most right and 0); in case dialog was closed without pressing on any button (like calling hide() or closing it via window manager) it will return -1.

## Constructor & Destructor Documentation

MessageBox | ( | MessageBoxType | t = `MSGBOX_PLAIN` | ) |

Constructor which initialize internal data

Parameters

  t | is MessageBoxType type

~MessageBox | ( |  | ) |

Clears internal data

## Member Function Documentation

void add_button | ( | Fl_Button * | b,
|  | MessageBoxButtonType | bt = `MSGBOX_BUTTON_PLAIN`
| ) |  |

Add button to dialog.

Parameters

  b | is already allocated button
  bt | is button type

void add_button | ( | const char * | l,
|  | MessageBoxButtonType | bt = `MSGBOX_BUTTON_PLAIN`,
|  | Fl_Callback | cb = `0`,
|  | void * | param = `0`
| ) |  |

Add button to dialog.

Parameters

  l | is button label
  bt | is button type
  cb | is callback for button
  param | is data sent to callback

void clear | ( | MessageBoxType | t = `MSGBOX_PLAIN` | ) |

Clears dialog and prepare internal data for next one.

Parameters

  t | is parameter telling how to prepare internal data for next dialog

static void clear_themed_icons | ( | void |  | ) |
| static

Clear icon names used by IconTheme.

void focus_button | ( | int | b | ) |

Focus a button. If number is greater than added buttons, it will to nothing.

const char* get_input | ( | void |  | ) |

Returns value from input field. Returned pointer points to internal storage and that storage is available during MessageBox instance life or untill clear() is called.

Returned pointer value can be NULL when nothing was entered or MessageBox is type of MSGBOX_PLAIN.

int run | ( | bool | center = `true` | ) |

Runs dialog until pressed some of it's buttons or was called hide() on dialog.

Returns
  -1 if nothing was pressed (but window was closed) or number of pressed button, starting from 0. Also, buttons are counted from right (most right, if pressed will be 0, second will be 1 and so).

Parameters

  center | if set, dialog will be centered at the screen

void run_plain | ( | bool | center = `true` | ) |

Runs dialog until called hide() or dialog was closed in normal way (clicking X in titlebar).

Parameters

  center | if set, dialog will be centered at the screen

bool set_icon | ( | const char * | path | ) |

Set icon giving absolute path

Returns
  true if icon was able to set

Parameters

  path | is full path to icon

void set_icon_from_type | ( | MessageBoxIconType | type | ) |

Set icon using one of MessageBoxIconType values. By default it will use icons from current icon theme and if not found, it will fallback to internal ones.

void set_input | ( | const char * | txt | ) |

Set default value to input field. Does nothing if dialog is MSGBOX_PLAIN type.

void set_text | ( | const char * | t | ) |

Set message text

Parameters

  t | is message text

bool set_theme_icon | ( | const char * | name | ) |

Set icon using loaded theme. Given icon name should not have an extension, nor should have path in it's name.

Returns
  true if icon was found

Parameters

  name | is icon name (without path and extension)

static void set_themed_icons | ( | const char * | msg,
|  | const char * | alert = `0`,
|  | const char * | ask = `0`,
|  | const char * | input = `0`,
|  | const char * | password = `0`
| ) |  |
| static

Set icon names used by IconTheme.

Parameters

  msg | is icon for message()
  alert | is icon for alert()
  ask | is icon for ask()
  input | is icon for input()
  password | is icon for password()

void set_xpm_icon | ( | const char *const * | arr | ) |

Set XPM icon. Parameter should be pointer to XPM array.

## Friends And Related Function Documentation

void alert | ( | const char * | fmt,
|  |  | ...
| ) |  |
| related

Display dialog with alert message; in printf form.

int ask | ( | const char * | fmt,
|  |  | ...
| ) |  |
| related

Display question dialog. Return 1 if user clicked 'Yes' or 0 if user clicked 'No' or closed dialog.

const char * input | ( | const char * | fmt,
|  | const char * | deflt = `0`,
|  |  | ...
| ) |  |
| related

Display dialog with input field with 'OK' and 'Cancel' buttons. If 'OK' is pressed (but input field is not empty), it will return pointer to that data. Pointer is pointing to static memory and must not be freed.

If 'Cancel' was pressed (or dialog closed without pressing any buttons) it will return NULL.

void message | ( | const char * | fmt,
|  |  | ...
| ) |  |
| related

Display message dialog in printf form.

const char * password | ( | const char * | fmt,
|  | const char * | deflt = `0`,
|  |  | ...
| ) |  |
| related

Same as input(), but typed characters are hidden with asterisks.

void themed_dialog_icons | ( | const char * | msg,
|  | const char * | alert = `0`,
|  | const char * | ask = `0`,
|  | const char * | input = `0`,
|  | const char * | password = `0`
| ) |  |
| related

Set icon names used by IconTheme.

Parameters

  msg | is icon for message()
  alert | is icon for alert()
  ask | is icon for ask()
  input | is icon for input()
  password | is icon for password()

Deprecated:
  with MessageBox::set_themed_icons()

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

- edelib/MessageBox.h