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