Etk
Main Page Object Hierarchy Data Structures Related Pages
Etk

Etk_Dialog


Detailed Description

A dialog is a window with buttons in its bottom area to allow the user to respond to a request.

dialog.png
The dialog's window is split vertically in two areas: the top-area, called "main-area", is made of an Etk_VBox where you can pack any type of widgets; and the bottom-area, called "action-area", which is an Etk_HBox where you can pack any type of widgets, but mostly buttons. Those buttons can be associated to a response id, which will be passed when the button is clicked through the "response" signal of the dialog.

You can pack widgets in the main-area with etk_dialog_pack_in_main_area().
You can pack widgets in the action-area with etk_dialog_pack_widget_in_action_area(), etk_dialog_pack_button_in_action_area(), etk_dialog_button_add() and etk_dialog_button_add_from_stock().

Here is a small code that shows how to treat the events when a button of the dialog is clicked:
 //Called when one of the buttons of the dialog is clicked
 void dialog_response_cb(Etk_Dialog *dialog, int response_id, void *data)
 {
    switch (response_id)
    {
       case ETK_RESPONSE_OK:
          printf("Ok has been clicked\n");
          break;
       case ETK_RESPONSE_APPLY:
          printf("Apply has been clicked\n");
          break;
       case ETK_RESPONSE_CLOSE:
          printf("Close has been clicked\n");
          break;
       default:
          break;
    }
    etk_widget_hide(ETK_WIDGET(dialog));
 }

 //Creation of the dialog
 Etk_Dialog *dialog;

 dialog = ETK_DIALOG(etk_dialog_new());
 etk_dialog_pack_in_main_area(dialog, main_widget, ETK_BOX_START, ETK_BOX_EXPAND_FILL, 0);
 etk_dialog_button_add_from_stock(dialog, ETK_STOCK_DIALOG_OK, ETK_RESPONSE_OK);
 etk_dialog_button_add_from_stock(dialog, ETK_STOCK_DIALOG_APPLY, ETK_RESPONSE_APPLY);
 etk_dialog_button_add_from_stock(dialog, ETK_STOCK_DIALOG_CLOSE, ETK_RESPONSE_CLOSE);
 etk_signal_connect("response", ETK_OBJECT(dialog), ETK_CALLBACK(dialog_response_cb), NULL);

Object Hierarchy:
  • Etk_Object
    • Etk_Widget
      • Etk_Container
        • Etk_Bin
          • Etk_Toplevel
            • Etk_Window
              • Etk_Dialog
Signals:
  • "response": Emitted when a button of the action-area of the dialog is clicked.
    • Callback: void callback(Etk_Dialog *dialog, int response_id, void *data)
      • dialog: the dialog connected to the callback
      • response_id: the response id of the button that has been clicked
      • data: the user data set when the callback has been connected to the signal
Properties:
  • "has-separator": Whether or not the horizontal separator is visible
    • Type: Boolean
    • Access: Read/Write
    • Default Value: ETK_TRUE
  • "action-area-homogeneous": Whether or not the widgets of the action-area have all the same size
    • Type: Boolean
    • Access: Read/Write
    • Default Value: ETK_TRUE
  • "action-area-align": The horizontal alignment of the widgets in the action-area, from 0.0 (left) to 1.0 (right)
    • Type: Float
    • Access: Read/Write
    • Default Value: 0.5


Data Structures

struct  Etk_Dialog
 [Widget] A window with buttons in its bottom area to allow the user to respond to a request More...

Defines

#define ETK_DIALOG_TYPE   (etk_dialog_type_get())
#define ETK_DIALOG(obj)   (ETK_OBJECT_CAST((obj), ETK_DIALOG_TYPE, Etk_Dialog))
#define ETK_IS_DIALOG(obj)   (ETK_OBJECT_CHECK_TYPE((obj), ETK_DIALOG_TYPE))

Enumerations

enum  Etk_Dialog_Response_ID {
  ETK_RESPONSE_NONE = -1,
  ETK_RESPONSE_REJECT = -2,
  ETK_RESPONSE_ACCEPT = -3,
  ETK_RESPONSE_DELETE_EVENT = -4,
  ETK_RESPONSE_OK = -5,
  ETK_RESPONSE_CANCEL = -6,
  ETK_RESPONSE_CLOSE = -7,
  ETK_RESPONSE_YES = -8,
  ETK_RESPONSE_NO = -9,
  ETK_RESPONSE_APPLY = -10,
  ETK_RESPONSE_HELP = -11
}
 Some common response IDs to use with an Etk_Dialog. More...

Functions

Etk_Widget * etk_dialog_new (void)
 Creates a new dialog.
void etk_dialog_pack_in_main_area (Etk_Dialog *dialog, Etk_Widget *widget, Etk_Box_Group group, Etk_Box_Fill_Policy fill_policy, int padding)
 Packs a widget into the dialog's main-area (above the buttons and the separator). The widget will be appended in the main-area's vbox (see etk_box_append()).
void etk_dialog_pack_widget_in_action_area (Etk_Dialog *dialog, Etk_Widget *widget, Etk_Box_Group group, Etk_Box_Fill_Policy fill_policy, int padding)
 Packs a widget into the dialog's action-area (at the bottom of the dialog). The widget will be appended in the action-area's hbox (see etk_box_append()).
void etk_dialog_pack_button_in_action_area (Etk_Dialog *dialog, Etk_Button *button, int response_id, Etk_Box_Group group, Etk_Box_Fill_Policy fill_policy, int padding)
 Packs a pre-created button into the dialog's action-area (at the bottom of the dialog). The button will be appended in the action-area's hbox (see etk_box_append()).
Etk_Widget * etk_dialog_button_add (Etk_Dialog *dialog, const char *label, int response_id)
 Creates and packs a button to the dialog's action-area. The button will be packed in the start-group of the action-area's hbox, and will use the ETK_BOX_FILL fill-policy.
Etk_Widget * etk_dialog_button_add_from_stock (Etk_Dialog *dialog, int stock_id, int response_id)
 Creates and packs a button to the dialog's action-area. The button is created from the given stock-id, will be packed in the start-group of the action-area's hbox, and will use the ETK_BOX_FILL fill-policy.
void etk_dialog_action_area_homogeneous_set (Etk_Dialog *dialog, Etk_Bool homogeneous)
 Sets whether or not the action-area's hbox is homogeneous, i.e whether or not all the widgets of the action-area should have the same size.
Etk_Bool etk_dialog_action_area_homogeneous_get (Etk_Dialog *dialog)
 Gets whether or not the action-area's hbox is homogeneous.
void etk_dialog_action_area_alignment_set (Etk_Dialog *dialog, float align)
 Sets the horizontal alignment of the widget in the dialog's action-area.
float etk_dialog_action_area_alignment_get (Etk_Dialog *dialog)
 Gets the alignment of the widgets in the dialog's action-area.
Etk_Widget * etk_dialog_main_area_vbox_get (Etk_Dialog *dialog)
 Gets the vbox of the dialog's main-area. It might be useful if you want more control on the way the widgets are packed.
Etk_Widget * etk_dialog_action_area_hbox_get (Etk_Dialog *dialog)
 Gets the hbox of the dialog's action-area. It might be useful if you want more control on the way the widgets are packed.
void etk_dialog_button_response_id_set (Etk_Dialog *dialog, Etk_Button *button, int response_id)
 Associates a response-id to the button. This way, when the button will be clicked, the "response" signal of the dialog will be emitted with this response-id. This function might be useful if you pack the button yourself, without using etk_dialog_pack_button_in_action_area() or etk_dialog_button_add().
int etk_dialog_button_response_id_get (Etk_Button *button)
 Gets the response-id associated to the button.
void etk_dialog_has_separator_set (Etk_Dialog *dialog, Etk_Bool has_separator)
 Sets whether or not there is a horizontal separator between the main-area and the action-area of the dialog.
Etk_Bool etk_dialog_has_separator_get (Etk_Dialog *dialog)
 Gets whether or not the horizontal separator of the dialog is visible.


Define Documentation

#define ETK_DIALOG_TYPE   (etk_dialog_type_get())

Gets the type of a dialog

#define ETK_DIALOG ( obj   )     (ETK_OBJECT_CAST((obj), ETK_DIALOG_TYPE, Etk_Dialog))

Casts the object to an Etk_Dialog

#define ETK_IS_DIALOG ( obj   )     (ETK_OBJECT_CHECK_TYPE((obj), ETK_DIALOG_TYPE))

Checks if the object is an Etk_Dialog


Enumeration Type Documentation

enum Etk_Dialog_Response_ID

Some common response IDs to use with an Etk_Dialog.

Enumerator:
ETK_RESPONSE_NONE  Response: None
ETK_RESPONSE_REJECT  Response: Reject
ETK_RESPONSE_ACCEPT  Response: Accept
ETK_RESPONSE_DELETE_EVENT  Response: Delete Event
ETK_RESPONSE_OK  Response: Ok
ETK_RESPONSE_CANCEL  Response: Cancel
ETK_RESPONSE_CLOSE  Response: Close
ETK_RESPONSE_YES  Response: Yes
ETK_RESPONSE_NO  Response: No
ETK_RESPONSE_APPLY  Response: Apply
ETK_RESPONSE_HELP  Response: Help


Function Documentation

Etk_Widget * etk_dialog_new ( void   ) 

Creates a new dialog.

Returns:
Returns the new dialog widget

void etk_dialog_pack_in_main_area ( Etk_Dialog *  dialog,
Etk_Widget *  widget,
Etk_Box_Group  group,
Etk_Box_Fill_Policy  fill_policy,
int  padding 
)

Packs a widget into the dialog's main-area (above the buttons and the separator). The widget will be appended in the main-area's vbox (see etk_box_append()).

Parameters:
dialog a dialog
widget the widget to pack
group the box-group where to pack the child (ETK_BOX_START or ETK_BOX_END)
fill_policy the fill-policy of the child, it indicates how it should fill its cell
padding the amount of free space on the two sides of the child, in pixels
See also:
etk_box_append()

void etk_dialog_pack_widget_in_action_area ( Etk_Dialog *  dialog,
Etk_Widget *  widget,
Etk_Box_Group  group,
Etk_Box_Fill_Policy  fill_policy,
int  padding 
)

Packs a widget into the dialog's action-area (at the bottom of the dialog). The widget will be appended in the action-area's hbox (see etk_box_append()).

Parameters:
dialog a dialog
widget the widget to pack
group the box-group where to pack the child (ETK_BOX_START or ETK_BOX_END)
fill_policy the fill-policy of the child, it indicates how it should fill its cell
padding the amount of free space on the two sides of the child, in pixels
See also:
etk_box_append()

void etk_dialog_pack_button_in_action_area ( Etk_Dialog *  dialog,
Etk_Button *  button,
int  response_id,
Etk_Box_Group  group,
Etk_Box_Fill_Policy  fill_policy,
int  padding 
)

Packs a pre-created button into the dialog's action-area (at the bottom of the dialog). The button will be appended in the action-area's hbox (see etk_box_append()).

Parameters:
dialog a dialog
button the button to pack
response_id the response-id to associate to the button (see Etk_Dialog_Response_ID for common IDs). The response-id will be passed to the "response" callbacks when the button is clicked
group the box-group where to pack the child (ETK_BOX_START or ETK_BOX_END)
fill_policy the fill-policy of the child, it indicates how it should fill its cell
padding the amount of free space on the two sides of the child, in pixels
See also:
etk_box_append()

Etk_Widget * etk_dialog_button_add ( Etk_Dialog *  dialog,
const char *  label,
int  response_id 
)

Creates and packs a button to the dialog's action-area. The button will be packed in the start-group of the action-area's hbox, and will use the ETK_BOX_FILL fill-policy.

Parameters:
dialog a dialog
label the button's label
response_id the response-id to associate to the button (see Etk_Dialog_Response_ID for common IDs). The response-id will be passed to the "response" callbacks when the button is clicked
Returns:
Returns the newly added button
Note:
The new button will be automatically shown

Etk_Widget * etk_dialog_button_add_from_stock ( Etk_Dialog *  dialog,
int  stock_id,
int  response_id 
)

Creates and packs a button to the dialog's action-area. The button is created from the given stock-id, will be packed in the start-group of the action-area's hbox, and will use the ETK_BOX_FILL fill-policy.

Parameters:
dialog a dialog
stock_id the button's stock id
response_id the response-id to associate to the button (see Etk_Dialog_Response_ID for common IDs). The response-id will be passed to the "response" callbacks when the button is clicked
Returns:
Returns the newly added button
Note:
The new button will be automatically shown

void etk_dialog_action_area_homogeneous_set ( Etk_Dialog *  dialog,
Etk_Bool  homogeneous 
)

Sets whether or not the action-area's hbox is homogeneous, i.e whether or not all the widgets of the action-area should have the same size.

Parameters:
dialog a dialog
homogeneous ETK_TRUE to make the action-area's hbox homogeneous, ETK_FALSE otherwise

Etk_Bool etk_dialog_action_area_homogeneous_get ( Etk_Dialog *  dialog  ) 

Gets whether or not the action-area's hbox is homogeneous.

Parameters:
dialog a dialog
Returns:
Returns ETK_TRUE if the action-area's hbox is homogeneous, ETK_FALSE otherwise

void etk_dialog_action_area_alignment_set ( Etk_Dialog *  dialog,
float  align 
)

Sets the horizontal alignment of the widget in the dialog's action-area.

Parameters:
dialog a dialog
align the horizontal alignment (0.0 = left, 0.5 = center, 1.0 = right, ...)

float etk_dialog_action_area_alignment_get ( Etk_Dialog *  dialog  ) 

Gets the alignment of the widgets in the dialog's action-area.

Parameters:
dialog a dialog
Returns:
Returns the horizontal alignment of the action-area

Etk_Widget * etk_dialog_main_area_vbox_get ( Etk_Dialog *  dialog  ) 

Gets the vbox of the dialog's main-area. It might be useful if you want more control on the way the widgets are packed.

Parameters:
dialog a dialog
Returns:
Returns the vbox of the dialog's main-area

Etk_Widget * etk_dialog_action_area_hbox_get ( Etk_Dialog *  dialog  ) 

Gets the hbox of the dialog's action-area. It might be useful if you want more control on the way the widgets are packed.

Parameters:
dialog a dialog
Returns:
Returns the hbox of the dialog's action-area

void etk_dialog_button_response_id_set ( Etk_Dialog *  dialog,
Etk_Button *  button,
int  response_id 
)

Associates a response-id to the button. This way, when the button will be clicked, the "response" signal of the dialog will be emitted with this response-id. This function might be useful if you pack the button yourself, without using etk_dialog_pack_button_in_action_area() or etk_dialog_button_add().

Parameters:
dialog a dialog
button the button to associate to the dialog and to the response-id
response_id the response-id to associate to the button
Note:
The button doesn't have to be packed in the dialog

int etk_dialog_button_response_id_get ( Etk_Button *  button  ) 

Gets the response-id associated to the button.

Parameters:
button a button
Returns:
Returns the response-id associated to the button, or ETK_RESPONSE_NONE if the button is not packed in a dialog

void etk_dialog_has_separator_set ( Etk_Dialog *  dialog,
Etk_Bool  has_separator 
)

Sets whether or not there is a horizontal separator between the main-area and the action-area of the dialog.

Parameters:
dialog a dialog
has_separator ETK_TRUE to make the separator visible, ETK_FALSE to hide it

Etk_Bool etk_dialog_has_separator_get ( Etk_Dialog *  dialog  ) 

Gets whether or not the horizontal separator of the dialog is visible.

Parameters:
dialog a dialog
Returns:
Returns ETK_TRUE if the horizontal separator of the dialog is visible, ETK_FALSE otherwise