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 Ewl_MVC	Ewl_MVC
typedef Ewl_Selection	Ewl_Selection
typedef Ewl_Selection_Idx	Ewl_Selection_Idx
typedef Ewl_Selection_Range	Ewl_Selection_Range
Functions
void	ewl_mvc_cb_clicked_multi (Ewl_Widget w, void ev, void *data)
void	ewl_mvc_cb_clicked_single (Ewl_Widget w, void ev, void *data)
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_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_Model *	ewl_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_private_data_get (Ewl_MVC *mvc)
	Retrieves the data set into the MVC widget.
void	ewl_mvc_private_data_set (Ewl_MVC mvc, void data)
	Sets the given data data into the MVC widget mvc.
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_Idx *	ewl_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_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.
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_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.
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_View *	ewl_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.
Variables
unsigned int	EWL_CALLBACK_MVC_CLICKED

Define Documentation

#define EWL_MVC ( mvc ) ((Ewl_MVC *)mvc)

Typecasts a pointer to an Ewl_MVC pointer.

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

Returns TRUE if the widget is an Ewl_Mvc, FALSE otherwise

#define EWL_MVC_TYPE "mvc"

The type name for the Ewl_MVC widget

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

Typecast a pointer to an Ewl_Selection pointer

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

Typecast a pointer to an Ewl_Selection_Idx pointer

#define EWL_SELECTION_RANGE ( x ) ((Ewl_Selection_Range *)x)

Typecasts a pointer to an Ewl_Selection_Range

Typedef Documentation

typedef struct Ewl_MVC Ewl_MVC

A simple mvc base class

typedef struct Ewl_Selection Ewl_Selection

Ewl_Selection

typedef struct Ewl_Selection_Idx Ewl_Selection_Idx

Ewl_Selection_Idx

typedef struct Ewl_Selection_Range Ewl_Selection_Range

Ewl_Selection_Range

Function Documentation

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

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

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.

Parameters:

mvc,:

The MVC to work with

Returns:: Returns the data set onto the MVC widget

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

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

void ewl_mvc_dirty_set	(	Ewl_MVC *	mvc,
		unsigned int	dirty
	)

Sets the dirty status of the MVC widget mvc to the dirty state.

Parameters:

	mvc,:	The MVC widget to work with
	dirty,:	The dirty status to set

Returns:: Returns no value.

void ewl_mvc_highlight	(	Ewl_MVC *	mvc,
		Ewl_Container *	c,
		Ewl_Widget ()(Ewl_MVC mvc, void data, unsigned int row, unsigned int column)	widget
	)

int ewl_mvc_init ( Ewl_MVC * mvc )

Initializes an MVC widget ot default values.

Parameters:

mvc,:

The MVC to initialize

Returns:: Returns TRUE on success or FALSE if unsuccessful

const Ewl_Model* ewl_mvc_model_get ( Ewl_MVC * mvc )

Retrieves the model set into the MVC widget.

Parameters:

mvc,:

The MVC to work with

Returns:: Returns the current 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.

Parameters:

	mvc,:	The MVC to work with
	model,:	The model to set

Returns:: Returns no value

void* ewl_mvc_private_data_get ( Ewl_MVC * mvc )

Retrieves the data set into the MVC widget.

Parameters:

mvc,:

The MVC to work with

Returns:: Returns the data set onto the MVC widget

void ewl_mvc_private_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 private data to set on the MVC

Returns:: Returns no value

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

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

unsigned int ewl_mvc_selected_count_get ( Ewl_MVC * mvc )

Retrives the number of items selected in the widget.

Parameters:

mvc,:

The MVC widget to work with

Returns:: Returns the number of items selected in the 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

Variable Documentation

unsigned int EWL_CALLBACK_MVC_CLICKED

This event is triggered when an item a cell or a row of the mvc is clicked

Ewl_MVC: The base model-view-controller framework

Detailed Description

Tutorial

Concepts

Data Structures

Defines

Typedefs

Functions

Variables

Define Documentation

Typedef Documentation

Function Documentation

Variable Documentation