Ewl_Dnd: The files containing DND functions

Detailed Description

Tutorial

In order to make DND handling easier for the end programmer, we've added a simplification API to EWL. It currently supports receiving drops and some limited dragging of widgets. Getting started is fairly simple, even for some rather complicated widgets. As an example, I'll run through the DND support added to the entry widget.

The first step to setup DND support on a widget is to decide which MIME types are allowed and understood by the widget. The entry displays text, so accepting the type "text/plain" is a safe choice. A NULL terminated list of type strings is passed to the ewl_dnd_accepted_types_set, which enables DND responses for the widget and helps to negotiate whether a drop will be accepted at a given position.

 const char *text_types[] = { "text/plain", NULL };

 ewl_dnd_accepted_types_set(EWL_WIDGET(e), text_types);

One key feature for DND support in the entry widget was to allow dragging text to arbitrary positions within the visible text area. This is accomplished by registering a callback for the EWL_CALLBACK_DND_POSITION event on the entry widget.

 ewl_callback_append(w, EWL_CALLBACK_DND_POSITION, ewl_entry_cb_dnd_position, NULL);

When the mouse moves during a DND event over the specified entry w the ewl_entry_cb_dnd_position function will be called. This function prototype looks like all other EWL callback prototypes:

 void ewl_entry_cb_dnd_position(Ewl_Widget *w, void *ev, void *data);

In this case, the void *ev parameter points to a Ewl_Event_Dnd_Position struct, which contains more detailed information about the event. We can use the coordinates from the event to position the cursor within our entry to receive the dropped data. Since the entry widget inherits from the text widget, the text calls are used directly on the widget to alter the entry contents. The code to accomplish this is rather small when the extra debugging information is removed:

 void
 ewl_entry_cb_dnd_position(Ewl_Widget *w, void *ev, void *data)
 {
         Ewl_Event_Dnd_Position *event;
         Ewl_Text *txt;

         event = ev;
         txt = EWL_TEXT(w);

         if (EWL_ENTRY(w)->editable && !DISABLED(w)) {
                 ewl_widget_focus_send(w);
                 ewl_text_cursor_position_set(txt, ewl_text_coord_index_map(txt, event->x, event->y));
        }
 }

Once the cursor has been positioned, the only event we care about is receiving the data from the drop. This is accomplished by using the EWL_CALLBACK_DND_DATA_RECEIVED callback which should also be placed on the entry widget.

 ewl_callback_append(w, EWL_CALLBACK_DND_DATA_RECEIVED, ewl_entry_cb_dnd_data, NULL);

The function prototype for ewl_entry_cb_dnd_data is identical to ewl_entry_cb_dnd_position, but the void *ev parameter is of type Ewl_Event_Dnd_Data. Since we only registered to receive plain text data dropped on the entry, we can insert the event data directly into the entry at the current cursor position.

 void
 ewl_entry_cb_dnd_data(Ewl_Widget *w, void *ev, void *data)
 {
         Ewl_Event_Dnd_Data *event;
         Ewl_Text *txt;

         event = ev;
         txt = EWL_TEXT(w);

         if (EWL_ENTRY(w)->editable && !DISABLED(w)) {
                 ewl_text_text_insert(txt, event->data,
                                         ewl_text_cursor_position_get(txt));
         }
 }

Considering the complicated nature of the Xdnd protocol, we are able to accomplish a considerable amount of work in very few lines of code. While some flexibility is sacrificed to achieve this, almost all of the protocol events are available for widgets to override as they please.

Check back for followup information to handle drag events on widgets.


Functions
int	ewl_dnd_accepted_types_contains (Ewl_Widget w, char type)
	: Verifies the specified widget accepts the given mimetype
char **	ewl_dnd_accepted_types_get (Ewl_Widget *w)
	: Gets the mimetypes the designated widget can accept for DND
void	ewl_dnd_accepted_types_set (Ewl_Widget w, const char *types)
	: Sets the mimetypes the designated widget can accept for DND
void	ewl_dnd_disable (void)
	Disables DND.
void	ewl_dnd_drag_data_send (Ewl_Embed emb, void handle, void *data, int len)
void	ewl_dnd_drag_drop (Ewl_Widget *w)
	Tells the widget to drop its data.
void	ewl_dnd_drag_widget_clear (void)
	Clears the current DND widget.
Ewl_Widget *	ewl_dnd_drag_widget_get (void)
	Retrieves the current DND widget.
void	ewl_dnd_enable (void)
	Enables DND.
void	ewl_dnd_external_drag_start (Ewl_Widget *w)
	Creates the proper condition for external dragging.
int	ewl_dnd_init (void)
void	ewl_dnd_internal_drag_start (Ewl_Widget *w)
	Creates the proper condition for internal dragging.
int	ewl_dnd_provided_types_contains (Ewl_Widget w, char type)
	: Verifies the specified widget provides the given mimetype
char **	ewl_dnd_provided_types_get (Ewl_Widget *w)
	: Gets the mimetypes the designated widget can provide for DND
void	ewl_dnd_provided_types_set (Ewl_Widget w, const char *types)
	: Sets the mimetypes the designated widget can provide for DND
void	ewl_dnd_shutdown (void)
int	ewl_dnd_status_get (void)
	Retrieves the current DND status.
Variables
unsigned int	EWL_CALLBACK_DND_DATA_RECEIVED
unsigned int	EWL_CALLBACK_DND_DATA_REQUEST
unsigned int	EWL_CALLBACK_DND_DROP
unsigned int	EWL_CALLBACK_DND_ENTER
unsigned int	EWL_CALLBACK_DND_LEAVE
unsigned int	EWL_CALLBACK_DND_POSITION
unsigned int	EWL_CALLBACK_SELECTION_CLEAR

Function Documentation

int ewl_dnd_accepted_types_contains	(	Ewl_Widget *	w,
		char *	type
	)

: Verifies the specified widget accepts the given mimetype

Parameters:

	w,:	The widget to test for an accepted type
	type,:	The mimetype to test for acceptance on a specific widget

Returns:: Returns TRUE if the widget accepts the given type, FALSE otherwise

char** ewl_dnd_accepted_types_get ( Ewl_Widget * w )

: Gets the mimetypes the designated widget can accept for DND

Parameters:

w,:

The widget to retrieve accepted types

Returns:: Returns a NULL terminated array of mimetypes widget accepts for DND

void ewl_dnd_accepted_types_set	(	Ewl_Widget *	w,
		const char **	types
	)

: Sets the mimetypes the designated widget can accept for DND

Parameters:

	w,:	The widget to set accepted types
	types,:	A NULL terminated array of mimetypes widget accepts for DND

Returns:: Returns no value

void ewl_dnd_disable ( void )

Disables DND.

Returns:: Returns no value

void ewl_dnd_drag_data_send	(	Ewl_Embed *	emb,
		void *	handle,
		void *	data,
		int	len
	)

Parameters:

	emb,:	Embed to send to
	handle,:	Handle to the window
	data,:	Data to send
	len,:	The size of the data

void ewl_dnd_drag_drop ( Ewl_Widget * w )

Tells the widget to drop its data.

Parameters:

w,:

The widget to stop dragging

Returns:: Returns no value

void ewl_dnd_drag_widget_clear ( void )

Clears the current DND widget.

Returns:: Returns no value.

Ewl_Widget* ewl_dnd_drag_widget_get ( void )

Retrieves the current DND widget.

Returns:: Returns the current DND widget

void ewl_dnd_enable ( void )

Enables DND.

Returns:: Returns no value

void ewl_dnd_external_drag_start ( Ewl_Widget * w )

Creates the proper condition for external dragging.

Parameters:

w,:

The widget to start dragging

Returns:: Returns no value

int ewl_dnd_init ( void )

void ewl_dnd_internal_drag_start ( Ewl_Widget * w )

Creates the proper condition for internal dragging.

Parameters:

w,:

The widget to start dragging

Returns:: Returns no value

int ewl_dnd_provided_types_contains	(	Ewl_Widget *	w,
		char *	type
	)

: Verifies the specified widget provides the given mimetype

Parameters:

	w,:	The widget to test for an provided type
	type,:	The mimetype to test for provideance on a specific widget

Returns:: Returns TRUE if the types contains the given type, FALSE otherwise

char** ewl_dnd_provided_types_get ( Ewl_Widget * w )

: Gets the mimetypes the designated widget can provide for DND

Parameters:

w,:

The widget to retrieve provided types

Returns:: Returns a NULL terminated array of mimetypes widget provides for DND

void ewl_dnd_provided_types_set	(	Ewl_Widget *	w,
		const char **	types
	)

: Sets the mimetypes the designated widget can provide for DND

Parameters:

	w,:	The widget to set provided types
	types,:	A NULL terminated array of mimetypes widget provides for DND

Returns:: Returns no value

void ewl_dnd_shutdown ( void )

int ewl_dnd_status_get ( void )

Retrieves the current DND status.

Returns:: Returns the current DND status

Variable Documentation

unsigned int EWL_CALLBACK_DND_DATA_RECEIVED

Data received event

unsigned int EWL_CALLBACK_DND_DATA_REQUEST

Data request event

unsigned int EWL_CALLBACK_DND_DROP

Drop event

unsigned int EWL_CALLBACK_DND_ENTER

On enter of a widget

unsigned int EWL_CALLBACK_DND_LEAVE

On exit of a widget

unsigned int EWL_CALLBACK_DND_POSITION

A DND position event

unsigned int EWL_CALLBACK_SELECTION_CLEAR

Selection clear event

Ewl_Dnd: The files containing DND functions

Detailed Description

Tutorial

Functions

Variables

Function Documentation

Variable Documentation