Download

Support

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.

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 callback which should also be placed on the entry widget.

 ewl_callback_append(w, EWL_CALLBACK_DND_DATA, 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
const 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_drop (Ewl_Widget *w)
 Tells the widget to start dragging.
void ewl_dnd_drag_start (Ewl_Widget *w)
 Tells the widget to start dragging.
void ewl_dnd_drag_widget_clear (void)
 Clears the current DND widget.
Ewl_Widgetewl_dnd_drag_widget_get (void)
 Retrieves the current DND widget.
void ewl_dnd_enable (void)
 Enables DND.
int ewl_dnd_init (void)
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

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

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_INT, and EWL_WIDGET_TYPE.

Referenced by ewl_embed_dnd_data_received_feed(), ewl_embed_dnd_drop_feed(), and ewl_embed_dnd_position_feed().

const 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

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_PTR, and EWL_WIDGET_TYPE.

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

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, ewl_embed_dnd_aware_remove(), ewl_embed_dnd_aware_set(), ewl_embed_widget_find(), EWL_FLAG_PROPERTY_DND_TARGET, EWL_FLAGS_PROPERTY_MASK, EWL_OBJECT, ewl_object_flags_add(), ewl_object_flags_remove(), EWL_WIDGET_TYPE, IF_FREE, REALIZED, and REVEALED.

Referenced by ewl_colorpicker_init(), and ewl_entry_init().

void ewl_dnd_disable ( void   ) 

Disables DND.

Returns:
Returns no value

References DENTER_FUNCTION, DLEAVE_FUNCTION, and DLEVEL_STABLE.

void ewl_dnd_drag_drop ( Ewl_Widget w  ) 

Tells the widget to start dragging.

Parameters:
w,: The widget to start dragging
Returns:
Returns no value

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, DRETURN, ewl_embed_widget_find(), ewl_engine_embed_dnd_drag_drop(), and EWL_WIDGET_TYPE.

Referenced by ewl_widget_cb_mouse_up().

void ewl_dnd_drag_widget_clear ( void   ) 

Clears the current DND widget.

Returns:
Returns no value.

References DENTER_FUNCTION, DLEAVE_FUNCTION, and DLEVEL_STABLE.

Referenced by ewl_embed_dnd_drop_feed().

Ewl_Widget* ewl_dnd_drag_widget_get ( void   ) 

Retrieves the current DND widget.

Returns:
Returns the current DND widget

References DENTER_FUNCTION, DLEVEL_STABLE, and DRETURN_PTR.

void ewl_dnd_enable ( void   ) 

Enables DND.

Returns:
Returns no value

References DENTER_FUNCTION, DLEAVE_FUNCTION, and DLEVEL_STABLE.

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

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_INT, and EWL_WIDGET_TYPE.

Referenced by ewl_embed_dnd_data_request_feed().

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

References DCHECK_PARAM_PTR_RET, DCHECK_TYPE_RET, DENTER_FUNCTION, DLEVEL_STABLE, DRETURN_PTR, and EWL_WIDGET_TYPE.

Referenced by ewl_dnd_drag_start().

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

References DCHECK_PARAM_PTR, DCHECK_TYPE, DENTER_FUNCTION, DLEAVE_FUNCTION, DLEVEL_STABLE, EWL_FLAG_PROPERTY_DND_SOURCE, EWL_FLAGS_PROPERTY_MASK, EWL_OBJECT, ewl_object_flags_add(), ewl_object_flags_remove(), EWL_WIDGET_TYPE, and IF_FREE.

void ewl_dnd_shutdown ( void   ) 

int ewl_dnd_status_get ( void   ) 

Retrieves the current DND status.

Returns:
Returns the current DND status

References DENTER_FUNCTION, DLEVEL_STABLE, and DRETURN_INT.


Variable Documentation

Data request event

Referenced by ewl_dnd_init(), and ewl_embed_dnd_data_request_feed().

unsigned int EWL_CALLBACK_DND_DROP

Drop event

Referenced by ewl_dnd_init(), and ewl_embed_dnd_drop_feed().

unsigned int EWL_CALLBACK_DND_ENTER

On enter of a widget

Referenced by ewl_dnd_init(), and ewl_embed_dnd_position_feed().

unsigned int EWL_CALLBACK_DND_LEAVE

On exit of a widget

Referenced by ewl_dnd_init(), and ewl_embed_dnd_position_feed().

A DND position event

Referenced by ewl_dnd_init(), ewl_embed_dnd_position_feed(), and ewl_entry_init().


Copyright © Enlightenment.org

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