MessageBox Class Reference
[FLTK widgets and functions]

Standard dialog. More...

#include <edelib/MessageBox.h>

List of all members.

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

Generated on 7 May 2013 for edelib by  doxygen 1.6.1