edelib  2.1.0
Public Member Functions | Static Public Member Functions | Related Functions | List of all members
MessageBox Class Reference

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:

* // 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:

* 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:

* 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
* 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

Constructor which initialize internal data

Parameters
tis 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
bis already allocated button
btis 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
lis button label
btis button type
cbis callback for button
paramis data sent to callback
void clear ( MessageBoxType  t = MSGBOX_PLAIN)

Clears dialog and prepare internal data for next one.

Parameters
tis 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
centerif 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
centerif 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
pathis 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
tis 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
nameis 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
msgis icon for message()
alertis icon for alert()
askis icon for ask()
inputis icon for input()
passwordis 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
msgis icon for message()
alertis icon for alert()
askis icon for ask()
inputis icon for input()
passwordis icon for password()
Deprecated:
with MessageBox::set_themed_icons()

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