Download

Support

Ewl_MVC: The base model-view-controller framework


Detailed Description

Defines a widget to base MVC widgets off of

Remarks:
Inherits from Ewl_Box.

Tutorial

The Model-View-Controller (MVC) design pattern is commonly used to separate display, data and control code. The MVC concepts are used in Ewl for several widgets including Ewl_Tree, Ewl_List and Ewl_Combo. This makes it a lot easier to update and store the data for those lists as the Ewl widget doesn't care about the internal representation.

Concepts

The basic MVC idea in Ewl is that we don't care what your data is. We don't care how it's stored, how it's sorted or when you load it. When your data changes you signal the MVC widget as dirty and it will redraw. As the widget is re-drawn it will ask you to give it information for each row/column as needed.

This can add a bit of extra work on the application end but provides for a lot of flexibility. We've also created a few helper functions to generate common models and views for you so you don't necessarily have to create these on your own.

There are two classes, along with the Ewl widget you're interested in, that you need to deal with when working with MVC widgets. These are:

* Ewl_Model

* Ewl_View

These classes will provide the pointers to the functions to call when the containers require information.

   Ewl_Widget *list;
   Ewl_Model *model;
   Ewl_View *view;
 
   model = ewl_model_ecore_list_instance();
   view = ewl_label_view_get();
 
   list = ewl_list_new();
   ewl_mvc_model_set(EWL_MVC(list), model);
   ewl_mvc_view_set(EWL_MVC(list), view);
   ewl_mvc_data_set(EWL_MVC(list), ecore_list_new());

In this example we're creating a simple Ewl_List widget and using a helper method to create a model to work with Ecore_List data. In this case our list is storing string objects so we can use the provided ewl_label_view_get() to get a pre-created view object.


Data Structures

struct  Ewl_MVC
 Inherits from Ewl_Box and extends to provide mvc functionality. More...
struct  Ewl_Selection
 Structure to store information on selections. More...
struct  Ewl_Selection_Idx
 Structure to store information on a single index selection. More...
struct  Ewl_Selection_Range
 Structure to store a range of selected cells. More...

Defines

#define EWL_MVC(mvc)   ((Ewl_MVC *)mvc)
#define EWL_MVC_IS(w)   (ewl_widget_type_is(EWL_WIDGET(w), EWL_MVC_TYPE))
#define EWL_MVC_TYPE   "mvc"
#define EWL_SELECTION(x)   ((Ewl_Selection *)x)
#define EWL_SELECTION_IDX(x)   ((Ewl_Selection_Idx *)x)
#define EWL_SELECTION_RANGE(x)   ((Ewl_Selection_Range *)x)

Typedefs

typedef struct Ewl_MVC Ewl_MVC
typedef struct Ewl_Selection Ewl_Selection
typedef struct Ewl_Selection_Idx Ewl_Selection_Idx
typedef struct Ewl_Selection_Range Ewl_Selection_Range

Functions

void ewl_mvc_cb_data_unref (Ewl_Widget *w, void *ev, void *data)
void ewl_mvc_cb_destroy (Ewl_Widget *w, void *ev, void *data)
void * ewl_mvc_data_get (Ewl_MVC *mvc)
 Retrieves the data set into the MVC widget.
void ewl_mvc_data_set (Ewl_MVC *mvc, void *data)
 Sets the given data data into the MVC widget mvc.
unsigned int ewl_mvc_dirty_get (Ewl_MVC *mvc)
 Retrieves the dirty status of the MVC widget.
void ewl_mvc_dirty_set (Ewl_MVC *mvc, unsigned int dirty)
 Sets the dirty status of the MVC widget mvc to the dirty state.
void ewl_mvc_handle_click (Ewl_MVC *mvc, const Ewl_Model *model, void *data, unsigned int row, unsigned int column)
void ewl_mvc_highlight (Ewl_MVC *mvc, Ewl_Container *c, Ewl_Widget *(*widget)(Ewl_MVC *mvc, void *data, unsigned int row, unsigned int column))
int ewl_mvc_init (Ewl_MVC *mvc)
 Initializes an MVC widget ot default values.
const Ewl_Modelewl_mvc_model_get (Ewl_MVC *mvc)
 Retrieves the model set into the MVC widget.
void ewl_mvc_model_set (Ewl_MVC *mvc, const Ewl_Model *model)
 Sets the given model into the tree.
void ewl_mvc_selected_add (Ewl_MVC *mvc, const Ewl_Model *model, void *data, unsigned int row, unsigned int column)
 Adds the given index to the selected list.
void ewl_mvc_selected_change_cb_set (Ewl_MVC *mvc, void(*cb)(Ewl_MVC *mvc))
void ewl_mvc_selected_clear (Ewl_MVC *mvc)
 clears the selection list
unsigned int ewl_mvc_selected_count_get (Ewl_MVC *mvc)
 Retrives the number of items selected in the widget.
Ewl_Selection_Idxewl_mvc_selected_get (Ewl_MVC *mvc)
 Retrieves the last selected item. Return must be free'd.
unsigned int ewl_mvc_selected_is (Ewl_MVC *mvc, void *data, unsigned int row, unsigned int column)
 Checks if the given index is selected or not.
Ecore_List * ewl_mvc_selected_list_get (Ewl_MVC *mvc)
 Retrieves the list of selected indicies. DO NOT remove or change items in this list.
void ewl_mvc_selected_list_set (Ewl_MVC *mvc, Ecore_List *list)
 Sets the list of items to select. This will remove any items it needs from the list.
void ewl_mvc_selected_range_add (Ewl_MVC *mvc, const Ewl_Model *model, void *data, unsigned int srow, unsigned int scolumn, unsigned int erow, unsigned int ecolumn)
 Sets the given range, inclusive, as selected in the mvc.
void ewl_mvc_selected_rm (Ewl_MVC *mvc, void *data, unsigned int row, unsigned int column)
 Removes the given index from the list of selected indices.
void ewl_mvc_selected_set (Ewl_MVC *mvc, const Ewl_Model *model, void *data, unsigned int row, unsigned int column)
 Sets the given index as selected.
Ewl_Selectionewl_mvc_selection_index_new (const Ewl_Model *model, void *data, unsigned int row, unsigned int column)
 Creates a new index selection based on given values.
Ewl_Selection_Mode ewl_mvc_selection_mode_get (Ewl_MVC *mvc)
 Retrieves the selection mode of the widget.
void ewl_mvc_selection_mode_set (Ewl_MVC *mvc, Ewl_Selection_Mode mode)
 Sets the selection capabilities of the mvc widget.
Ewl_Selectionewl_mvc_selection_range_new (const Ewl_Model *model, void *data, unsigned int srow, unsigned int scolumn, unsigned int erow, unsigned int ecolumn)
 Creates a new range selection based on given values.
void ewl_mvc_view_change_cb_set (Ewl_MVC *mvc, void(*cb)(Ewl_MVC *mvc))
 This callback will be called whenever the ewl_mvc_view_set routine is called to notify the inheriting widget that the view has changed.
const Ewl_Viewewl_mvc_view_get (Ewl_MVC *mvc)
 Retrives the current view set on the MVC.
void ewl_mvc_view_set (Ewl_MVC *mvc, const Ewl_View *view)
 Sets the given view onto the MVC.

Define Documentation

#define EWL_MVC_IS (  )     (ewl_widget_type_is(EWL_WIDGET(w), EWL_MVC_TYPE))

Returns TRUE if the widget is an Ewl_Mvc, FALSE otherwise

#define EWL_SELECTION (  )     ((Ewl_Selection *)x)

Typecast a pointer to an Ewl_Selection pointer

Referenced by ewl_filelist_selected_file_get().

#define EWL_SELECTION_IDX (  )     ((Ewl_Selection_Idx *)x)


Typedef Documentation

typedef struct Ewl_MVC Ewl_MVC

A simple mvc base class


Function Documentation

void ewl_mvc_cb_data_unref ( Ewl_Widget w,
void *  ev,
void *  data 
)

void ewl_mvc_cb_destroy ( Ewl_Widget w,
void *  ev,
void *  data 
)

void ewl_mvc_data_set ( Ewl_MVC mvc,
void *  data 
)

Sets the given data data into the MVC widget mvc.

Parameters:
mvc,: The MVC to work with
data,: The data to set on the MVC
Returns:
Returns no value

References data, DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, ewl_mvc_dirty_set(), ewl_mvc_selected_clear(), and EWL_MVC_TYPE.

Referenced by ewl_filelist_directory_set(), and ewl_filepicker_init().

unsigned int ewl_mvc_dirty_get ( Ewl_MVC mvc  ) 

Retrieves the dirty status of the MVC widget.

Parameters:
mvc,: The MVC widget use
Returns:
Returns the dirty status of the MVC widget

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, dirty, DLEVEL_STABLE, DRETURN_INT, and EWL_MVC_TYPE.

Referenced by ewl_combo_cb_decrement_clicked(), ewl_list_cb_configure(), and ewl_tree_cb_configure().

const Ewl_Model* ewl_mvc_model_get ( Ewl_MVC mvc  ) 

void ewl_mvc_model_set ( Ewl_MVC mvc,
const Ewl_Model model 
)

Sets the given model into the tree.

Parameters:
mvc,: The MVC to work with
model,: The model to set
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, ewl_mvc_dirty_set(), EWL_MVC_TYPE, and model.

Referenced by ewl_filepicker_init().

void ewl_mvc_selected_add ( Ewl_MVC mvc,
const Ewl_Model model,
void *  data,
unsigned int  row,
unsigned int  column 
)

Adds the given index to the selected list.

Parameters:
mvc,: The MVC to work with
model,: The model to work with. If NULL the model from the MVC will be used
data,: The parent data containing the index selection
row,: The row to add
column,: The column to add
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, ewl_mvc_model_get(), EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, and selection_mode.

Referenced by ewl_mvc_handle_click(), and ewl_mvc_selected_set().

void ewl_mvc_selected_change_cb_set ( Ewl_MVC mvc,
void(*)(Ewl_MVC *mvc)  cb 
)

void ewl_mvc_selected_clear ( Ewl_MVC mvc  ) 

clears the selection list

Parameters:
mvc,: The mvc to clear
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, and selection_mode.

Referenced by ewl_filelist_selected_file_set(), ewl_mvc_data_set(), and ewl_tree_selection_type_set().

unsigned int ewl_mvc_selected_count_get ( Ewl_MVC mvc  ) 

Ewl_Selection_Idx* ewl_mvc_selected_get ( Ewl_MVC mvc  ) 

Retrieves the last selected item. Return must be free'd.

Parameters:
mvc,: The MVC to get the data from
Returns:
Returns the last selected item. Return must be free'd If there should not be any selection or an error occured (e.g. the selection mode is set to EWL_SELECTION_MODE_NONE) it will return NULL.

References Ewl_Selection_Range::column, Ewl_Selection_Idx::column, Ewl_Selection::data, DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_PTR, EWL_MVC_TYPE, EWL_SELECTION_IDX, EWL_SELECTION_MODE_NONE, EWL_SELECTION_RANGE, EWL_SELECTION_TYPE_INDEX, Ewl_Selection::model, NEW, Ewl_Selection_Range::row, Ewl_Selection_Idx::row, Ewl_Selection_Idx::sel, selected, selection_mode, Ewl_Selection_Range::start, and Ewl_Selection::type.

Referenced by ewl_filelist_selected_file_get().

unsigned int ewl_mvc_selected_is ( Ewl_MVC mvc,
void *  data,
unsigned int  row,
unsigned int  column 
)

Checks if the given index is selected or not.

Parameters:
mvc,: The MVC to work with
data,: UNUSED
row,: The row to check for
column,: The column to check for
Returns:
Returns TRUE if the index is selected, FALSE otherwise

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_INT, EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, and selection_mode.

Referenced by ewl_mvc_handle_click().

Ecore_List* ewl_mvc_selected_list_get ( Ewl_MVC mvc  ) 

Retrieves the list of selected indicies. DO NOT remove or change items in this list.

Parameters:
mvc,: The MVC to get the list from
Returns:
Returns the list of selected indices

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_PTR, EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, selected, and selection_mode.

Referenced by ewl_filelist_selected_files_get().

void ewl_mvc_selected_list_set ( Ewl_MVC mvc,
Ecore_List *  list 
)

Sets the list of items to select. This will remove any items it needs from the list.

Parameters:
mvc,: The MVC to work with
list,: The list of items to set selected.
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, ewl_mvc_selected_count_get(), EWL_MVC_TYPE, EWL_SELECTION_MODE_MULTI, EWL_SELECTION_MODE_NONE, and selection_mode.

Referenced by ewl_filelist_selected_files_set().

void ewl_mvc_selected_range_add ( Ewl_MVC mvc,
const Ewl_Model model,
void *  data,
unsigned int  srow,
unsigned int  scolumn,
unsigned int  erow,
unsigned int  ecolumn 
)

Sets the given range, inclusive, as selected in the mvc.

Parameters:
mvc,: The MVC to set the list into
model,: The model to use for this data. If NULL the model from the MVC will be used
data,: The parent data containing the index selection
srow,: The start row
scolumn,: The start column
erow,: The end row
ecolumn,: The end column
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, ewl_mvc_model_get(), ewl_mvc_selection_range_new(), EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, EWL_SELECTION_MODE_SINGLE, and selection_mode.

Referenced by ewl_mvc_handle_click().

void ewl_mvc_selected_rm ( Ewl_MVC mvc,
void *  data,
unsigned int  row,
unsigned int  column 
)

Removes the given index from the list of selected indices.

Parameters:
mvc,: The MVC to work with
data,: The parent data containing the index selection
row,: The row to remove
column,: The column to remove
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, EWL_SELECTION_RANGE, EWL_SELECTION_TYPE_INDEX, selected, selection_mode, and Ewl_Selection::type.

Referenced by ewl_mvc_handle_click().

void ewl_mvc_selected_set ( Ewl_MVC mvc,
const Ewl_Model model,
void *  data,
unsigned int  row,
unsigned int  column 
)

Sets the given index as selected.

Parameters:
mvc,: The MVC to work with
model,: The model to work with the data. If NULL the model from the MVC will be used
data,: The parent data containing the index selection
row,: The row to set
column,: The column to set
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, ewl_mvc_selected_add(), EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, and selection_mode.

Referenced by ewl_combo_cell_cb_clicked(), ewl_filelist_selected_file_set(), ewl_filepicker_filter_add(), ewl_filepicker_filter_set(), ewl_filepicker_init(), and ewl_mvc_handle_click().

Ewl_Selection* ewl_mvc_selection_index_new ( const Ewl_Model model,
void *  data,
unsigned int  row,
unsigned int  column 
)

Creates a new index selection based on given values.

Parameters:
model,: The model to work with this data
data,: The parent data containing the index selection
row,: The row to create the index selection for
column,: The column to create the index for
Returns:
Returns a new Ewl_Selection_Idx based on the row and column

References Ewl_Selection_Idx::column, Ewl_Selection::data, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_PTR, EWL_SELECTION_TYPE_INDEX, Ewl_Selection::model, NEW, Ewl_Selection_Idx::row, Ewl_Selection_Idx::sel, and Ewl_Selection::type.

Referenced by ewl_filelist_selected_files_set().

Ewl_Selection_Mode ewl_mvc_selection_mode_get ( Ewl_MVC mvc  ) 

Retrieves the selection mode of the widget.

Parameters:
mvc,: The MVC widget to use
Returns:
Returns the selection mode of the mvc widget

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_INT, EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, and selection_mode.

Referenced by ewl_list_cb_item_clicked(), and ewl_mvc_handle_click().

void ewl_mvc_selection_mode_set ( Ewl_MVC mvc,
Ewl_Selection_Mode  mode 
)

Sets the selection capabilities of the mvc widget.

Parameters:
mvc,: The MVC widget to use
mode,: The selection mode to set
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, EWL_MVC_TYPE, EWL_SELECTION_MODE_NONE, IF_FREE_LIST, selected, and selection_mode.

Referenced by ewl_filelist_multiselect_set(), and ewl_mvc_init().

Ewl_Selection* ewl_mvc_selection_range_new ( const Ewl_Model model,
void *  data,
unsigned int  srow,
unsigned int  scolumn,
unsigned int  erow,
unsigned int  ecolumn 
)

Creates a new range selection based on given values.

Parameters:
model,: The model to work with this data
data,: The data that we're working with
srow,: The start row
scolumn,: The start column
erow,: The end row
ecolumn,: The end column
Returns:
Returns a new Ewl_Selection_Range based on given values

References Ewl_Selection_Range::column, Ewl_Selection::data, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_PTR, Ewl_Selection_Range::end, EWL_SELECTION_TYPE_RANGE, Ewl_Selection::model, NEW, Ewl_Selection_Range::row, Ewl_Selection_Range::sel, Ewl_Selection_Range::start, and Ewl_Selection::type.

Referenced by ewl_mvc_selected_range_add().

void ewl_mvc_view_change_cb_set ( Ewl_MVC mvc,
void(*)(Ewl_MVC *mvc)  cb 
)

This callback will be called whenever the ewl_mvc_view_set routine is called to notify the inheriting widget that the view has changed.

Parameters:
mvc,: The MVC to work with
cb,: The callback to set
Returns:
Returns no value

References cb, DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, EWL_MVC_TYPE, and view_change.

const Ewl_View* ewl_mvc_view_get ( Ewl_MVC mvc  ) 

Retrives the current view set on the MVC.

Parameters:
mvc,: The MVC to work with
Returns:
Returns the current view set on the MVC

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_PTR, EWL_MVC_TYPE, and view.

Referenced by ewl_combo_cb_decrement_clicked(), ewl_list_cb_configure(), and ewl_tree_node_expand().

void ewl_mvc_view_set ( Ewl_MVC mvc,
const Ewl_View view 
)

Sets the given view onto the MVC.

Parameters:
mvc,: The MVC to work with
view,: The view to set
Returns:
Returns no value

References cb, DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, ewl_mvc_dirty_set(), EWL_MVC_TYPE, view, and view_change.

Referenced by ewl_filepicker_init().


Copyright © Enlightenment.org

Enlightened Widget Library Documentation Generated: Sat May 17 16:51:10 2008