Ewl_Widget: The Parent Widget Class Common to All Widgets

Detailed Description

Defines the Ewl_Widget class and it's accessor/modifier functions.

The Ewl_Widget extends the Ewl_Object to provide the basic facilities necessary for widgets to interact with the end user. This includes basic callbacks for input events, window information changes, and drawing to the display.

Remarks:: Inherits from Ewl_Object.

Tutorial

Small as small can be (originally at http://everburning.com/news/small-as-small-can-be)

Whats the minimum amount of work you need to do to create your own EWL widget? Just want something you can build on but dont know where to start?

Well, hopefully this should give you the base for starting your widget. Assuming you're creating a widget called My_Widget, the EWL convention is to have a my_widget.c and my_widget.h files. There are only a couple things you need to implement to get a working widget.

First, my_widget.h.

     #ifndef MY_WIDGET_H
     #define MY_WIDGET_H

     #include <Ewl.h>

     #define MY_WIDGET(w) ((My_Widget *)w)
     #define MY_WIDGET_TYPE "my_widget"

     typedef struct My_Widget My_Widget;
     struct My_Widget
     {
         Ewl_Widget widget;
     };

     Ewl_Widget *my_widget_new(void);
     int my_widget_init(My_Widget *w);

     #endif

That wasn't so bad. What have we got? Well, the MY_WIDGET(w) define gives us a simple macro to cast other widgets to our widget. The second define, MY_WIDGET_TYPE, is a simple macro containing the type name of the widget. Well use that a bit later (and in any type checking we add to our widget.)

We then create the widget structure. In this case were inheriting from Ewl_Widget so its the first item in our struct (and not a pointer, thats important). This is how EWLs inhertiance works. The widget you're inheriting from is the first item in the struct and not a pointer. You will now be able to call any of the methods of the inherited class on the new class.

We then declare two methods. The convention in EWL is that the _new() function always takes no parameters (void). There is also always a _init() function that takes the widget as its only parameter and returns an int, if the initialization succeeded or failed.

With that out of the way, lets take a look at my_widget.c.

     #include "my_widget.h"

     Ewl_Widget *
     my_widget_new(void)
     {
         Ewl_Widget *w;

         w = calloc(1, sizeof(My_Widget)));
         if (!w) return NULL;

         if (!my_widget_init(MY_WIDGET(w)))
         {
                 free(w);
                 return NULL;
         }
         return w;
     }

     int
     my_widget_init(My_Widget *w)
     {
          if (!ewl_widget_init(EWL_WIDGET(w)))
                 return 0;

         ewl_widget_appearance_set(EWL_WIDGET(w), MY_WIDGET_TYPE);
         ewl_widget_inherit(EWL_WIDGET(w), MY_WIDGET_TYPE);

         return 1;
     }

Thats pretty simple. We create a new widget, initialize it and thats about it. In my_widget_init() we make sure we call ewl_widget_init() as thats the widget we are inheriting from and we then set our inheritance and appearance strings (notice the use of our type define from earlier).

With that you've got a simple widget. It doesn't do much, but it exists. Build on as you will.


Data Structures
struct	Ewl_Attach_List
	A list of things attached to a widget. More...
struct	Ewl_Callback_Chain
	The callback chain contains the length, mask and information on the list. More...
struct	Ewl_Color_Set
	Contains an RGBA set of colours. More...
struct	Ewl_Pair
	Contains a key and a value pair. More...
struct	Ewl_Pair_List
	Contains a list of key value pairs. More...
struct	Ewl_Widget
	Inherits from Ewl_Object and extends to provide appearance, parent, and callback capabilities. More...
Defines
#define	CONFIGURED(o)
#define	DESTROYED(o)
#define	DISABLED(o) (ewl_widget_applied_state_has(EWL_WIDGET(o), EWL_STATE_DISABLED))
#define	EWL_PAIR(p) ((Ewl_Pair *)p)
#define	EWL_WIDGET(widget) ((Ewl_Widget *) widget)
	Typecast a pointer to an Ewl_Widget pointer.
#define	ewl_widget_flags_get(o, mask) (EWL_WIDGET(o)->flags & mask)
	Retrieves the current setting of the widget flags for o.
#define	ewl_widget_flags_has(o, check_flags, mask) (!!(EWL_WIDGET(o)->flags & ((check_flags) & mask)))
	Determines if widget has the requested flags set.
#define	ewl_widget_flags_has_all(o, check_flags, mask) ((EWL_WIDGET(o)->flags & ((check_flags) & mask)) == ((check_flags) & mask))
	Determines if widget has all of the requested flags set.
#define	ewl_widget_in_tab_list_get(o) (ewl_widget_flags_get(o, EWL_FLAG_PROPERTY_IN_TAB_LIST))
	Retrieves the current setting of the in tab list flag for o.
#define	ewl_widget_in_tab_list_set(o, val)
	Changes the tab list flag value to match val.
#define	EWL_WIDGET_IS(w) (ewl_widget_type_is(EWL_WIDGET(w), EWL_WIDGET_TYPE))
#define	ewl_widget_queued_add(o, queued) ewl_widget_flags_add(o, queued, EWL_FLAGS_QUEUED_MASK)
#define	ewl_widget_queued_get(o, queued) ewl_widget_flags_get(o, queued, EWL_FLAGS_QUEUED_MASK)
#define	ewl_widget_queued_has(o, queued) ewl_widget_flags_has(o, queued, EWL_FLAGS_QUEUED_MASK)
#define	ewl_widget_queued_remove(o, queued) ewl_widget_flags_remove(o, queued, EWL_FLAGS_QUEUED_MASK)
#define	ewl_widget_recursive_get(o) (ewl_widget_flags_get(o, EWL_FLAG_PROPERTY_RECURSIVE))
	Retrieves the current setting of the recursive flag for o.
#define	ewl_widget_recursive_set(o, val)
	Changes the recursive flag value to match val.
#define	ewl_widget_toplevel_get(o) (ewl_widget_flags_get(o, EWL_FLAG_PROPERTY_TOPLEVEL))
	Retrieves the current setting of the top level flag for o.
#define	ewl_widget_toplevel_set(o, val)
	Changes the top level flag value to match val.
#define	EWL_WIDGET_TYPE "widget"
#define	ewl_widget_visible_add(o, visible) ewl_widget_flags_add(o, visible, EWL_FLAGS_VISIBLE_MASK)
#define	ewl_widget_visible_get(o, visible) ewl_widget_flags_get(o, visible, EWL_FLAGS_VISIBLE_MASK)
#define	ewl_widget_visible_has(o, visible) ewl_widget_flags_has(o, visible, EWL_FLAGS_VISIBLE_MASK)
#define	ewl_widget_visible_remove(o, visible) ewl_widget_flags_remove(o, visible, EWL_FLAGS_VISIBLE_MASK)
#define	HIDDEN(o) (!(EWL_WIDGET(o)->flags & EWL_FLAG_VISIBLE_SHOWN))
#define	REALIZED(o) (EWL_WIDGET(o)->flags & EWL_FLAG_VISIBLE_REALIZED)
#define	RECURSIVE(o) (EWL_WIDGET(o)->flags & EWL_FLAG_PROPERTY_RECURSIVE)
#define	REVEALED(o) (EWL_WIDGET(o)->flags & EWL_FLAG_VISIBLE_REVEALED)
#define	TOPLAYERED(w) (EWL_WIDGET(w)->flags & EWL_FLAG_PROPERTY_TOPLAYERED)
#define	UNMANAGED(w) (EWL_WIDGET(w)->flags & EWL_FLAG_PROPERTY_UNMANAGED)
#define	VISIBLE(o) (EWL_WIDGET(o)->flags & EWL_FLAG_VISIBLE_SHOWN)
Typedefs
typedef Ewl_Attach_List	Ewl_Attach_List
typedef Ewl_Callback_Chain	Ewl_Callback_Chain
typedef Ewl_Color_Set	Ewl_Color_Set
typedef Ewl_Pair	Ewl_Pair
typedef Ewl_Pair_List	Ewl_Pair_List
typedef Ewl_Widget	Ewl_Widget
Functions
const char *	ewl_widget_appearance_get (Ewl_Widget *w)
	Retrieve the appearance key of the widget.
const char *	ewl_widget_appearance_part_text_get (Ewl_Widget w, const char part)
	Retrieve a copy of a parts current text.
void	ewl_widget_appearance_part_text_set (Ewl_Widget w, const char part, const char *text)
	Change the text of the given theme part of a widget.
int	ewl_widget_appearance_path_copy (Ewl_Widget w, char buf, int size)
char *	ewl_widget_appearance_path_get (Ewl_Widget *w)
	Retrieve the appearance path key of the widget.
int	ewl_widget_appearance_path_size_get (Ewl_Widget *w)
void	ewl_widget_appearance_set (Ewl_Widget w, const char appearance)
	Change the appearance of the specified widget.
const char *	ewl_widget_appearance_text_get (Ewl_Widget *w)
	Retrieve the text of the given theme part of a widget.
void	ewl_widget_appearance_text_set (Ewl_Widget w, const char text)
	Change the text of the given theme part of a widget.
unsigned int	ewl_widget_applied_state_has (Ewl_Widget *w, Ewl_State state)
void	ewl_widget_cb_configure (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_hide (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_mouse_down (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_mouse_move (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_mouse_up (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_obscure (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_realize (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_reparent (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_reveal (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_show (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_cb_unrealize (Ewl_Widget w, void ev_data, void *user_data)
void	ewl_widget_color_get (Ewl_Widget w, unsigned int r, unsigned int g, unsigned int b, unsigned int *a)
	Gets the colour settings of the widget.
void	ewl_widget_color_set (Ewl_Widget *w, unsigned int r, unsigned int g, unsigned int b, unsigned int a)
	sets the colour of the widget
void	ewl_widget_configure (Ewl_Widget *widget)
	Initiate configuring of the specified widget.
void	ewl_widget_custom_state_set (Ewl_Widget w, const char cst, Ewl_Durability dur)
	Update the appearance of the widget to a state.
void *	ewl_widget_data_del (Ewl_Widget w, void k)
	Remove the specified key / value pair from the widget and return the value.
void *	ewl_widget_data_get (Ewl_Widget w, void k)
	retrieve the specified key / value pair from the widget
void	ewl_widget_data_set (Ewl_Widget w, void k, void *v)
	Attach the specified key / value pair to the widget.
void	ewl_widget_destroy (Ewl_Widget *widget)
	Destroy the specified widget.
void	ewl_widget_disable (Ewl_Widget *w)
	Prevent a widget from receiving any events.
void	ewl_widget_enable (Ewl_Widget *w)
	Re-enable a disabled widget.
void	ewl_widget_flags_add (Ewl_Widget *o, unsigned int flags, unsigned int mask)
	Add the set of flags specified in flags to w.
void	ewl_widget_flags_remove (Ewl_Widget *o, unsigned int flags, unsigned int mask)
	Removes the set of state flags specified in flags from w.
void	ewl_widget_focus_send (Ewl_Widget *w)
	Changes the keyboard focus to the widget w.
unsigned int	ewl_widget_focusable_get (Ewl_Widget *w)
	Checks the focusable state of the widget.
void	ewl_widget_focusable_set (Ewl_Widget *w, unsigned int val)
	Set if the given widget is focusable or not.
Ewl_Widget *	ewl_widget_focused_get (void)
	Retrieve the currently focused widget.
void	ewl_widget_free (Ewl_Widget *w)
void	ewl_widget_hide (Ewl_Widget *widget)
	Mark a widget as invisible.
unsigned int	ewl_widget_ignore_focus_change_get (Ewl_Widget *w)
	Get if the widget is ignoring focus changes.
void	ewl_widget_ignore_focus_change_set (Ewl_Widget *w, unsigned int val)
	Set if the widget should ignore focus changes.
void	ewl_widget_inherit (Ewl_Widget widget, const char type)
	Appends the given inheritance to this widgets inheritance string.
void	ewl_widget_inherited_state_add (Ewl_Widget *w, Ewl_State state)
unsigned int	ewl_widget_inherited_state_has (Ewl_Widget *w, Ewl_State state)
void	ewl_widget_inherited_state_remove (Ewl_Widget *w, Ewl_State state)
int	ewl_widget_init (Ewl_Widget *w)
	Initialize a widget to default values and callbacks.
unsigned int	ewl_widget_internal_is (Ewl_Widget *w)
void	ewl_widget_internal_set (Ewl_Widget *w, unsigned int val)
int	ewl_widget_layer_priority_get (Ewl_Widget *w)
	Retrieve a widgets layer relative to it's parent.
void	ewl_widget_layer_priority_set (Ewl_Widget *w, int layer)
	Set the relative layer to it's parent.
int	ewl_widget_layer_top_get (Ewl_Widget *w)
	Returns if the widget will be drawn above all the others.
void	ewl_widget_layer_top_set (Ewl_Widget *w, int top)
	set the widget to be layered above all other widgets
Ewl_Widget *	ewl_widget_name_find (const char *name)
	Find a widget identified by a name.
const char *	ewl_widget_name_get (Ewl_Widget *w)
	Get the name for the specified widget.
void	ewl_widget_name_set (Ewl_Widget w, const char name)
	Name the specified widget.
Ewl_Widget *	ewl_widget_new (void)
	Allocate a new widget.
void	ewl_widget_obscure (Ewl_Widget *w)
	Indicate a widget is obscured.
unsigned int	ewl_widget_onscreen_is (Ewl_Widget *widget)
	Checks if the given widget is currently on screen.
Ewl_Widget *	ewl_widget_parent_get (Ewl_Widget *w)
	Retrieves the parent of the given widget.
int	ewl_widget_parent_of (Ewl_Widget c, Ewl_Widget w)
	Determine if a widget is a parent of another widget.
void	ewl_widget_parent_set (Ewl_Widget w, Ewl_Widget p)
	change the parent of the specified widget
void	ewl_widget_print (Ewl_Widget *w)
	Prints info for debugging a widget's state information.
void	ewl_widget_print_verbose (Ewl_Widget *w)
	Prints verbose info for debugging a widget's state information.
void	ewl_widget_realize (Ewl_Widget *widget)
	Realize the specified widget.
void	ewl_widget_realize_force (Ewl_Widget *widget)
	Forces a widget to be realized (in normal use use ewl_widget_realize). Used to immediately generate the widget sizing values.
void	ewl_widget_reparent (Ewl_Widget *widget)
	initiate reparent of the specified widget
void	ewl_widget_reveal (Ewl_Widget *w)
	Indicate a widget is revealed.
void	ewl_widget_show (Ewl_Widget *widget)
	mark a widget as visible
void	ewl_widget_state_add (Ewl_Widget *w, Ewl_State state)
unsigned int	ewl_widget_state_has (Ewl_Widget *w, Ewl_State state)
void	ewl_widget_state_remove (Ewl_Widget *w, Ewl_State state)
void	ewl_widget_tab_order_append (Ewl_Widget *w)
	Changes the order in the embed so w receives focus first on tab.
void	ewl_widget_tab_order_insert (Ewl_Widget *w, unsigned int idx)
	Changes the order in the embed so w receives focus first on tab.
void	ewl_widget_tab_order_insert_after (Ewl_Widget w, Ewl_Widget after)
	Insert the given widget into the tab order after the after widget.
void	ewl_widget_tab_order_insert_before (Ewl_Widget w, Ewl_Widget before)
	Inserts the widget into the tab order before the before widget.
void	ewl_widget_tab_order_prepend (Ewl_Widget *w)
	Changes the order in the embed so w receives focus first on tab.
void	ewl_widget_tab_order_remove (Ewl_Widget *w)
	Remove the widget from the tab order.
void	ewl_widget_theme_path_set (Ewl_Widget w, const char path)
	Change the path of the specified widget.
void	ewl_widget_tree_print (Ewl_Widget *w)
	Prints to stdout the tree of widgets that are parents of a widget.
unsigned int	ewl_widget_type_is (Ewl_Widget widget, const char type)
	Determine if the widget w has inherited from the type t.
unsigned int	ewl_widget_unmanaged_is (Ewl_Widget *w)
void	ewl_widget_unmanaged_set (Ewl_Widget *w, unsigned int val)
void	ewl_widget_unrealize (Ewl_Widget *w)
	Unrealize the specified widget.

Define Documentation

#define CONFIGURED ( o )

Value:

(ewl_widget_queued_has(EWL_WIDGET(o), \
                                        EWL_FLAG_QUEUED_SCHEDULED_CONFIGURE) \
                        || ewl_widget_queued_has(EWL_WIDGET(o), \
                                        EWL_FLAG_QUEUED_PROCESS_CONFIGURE))

Used to determine if a widget is scheduled for configure

#define DESTROYED ( o )

Value:

(ewl_widget_queued_has(EWL_WIDGET(o), \
                                        EWL_FLAG_QUEUED_SCHEDULED_DESTROY) \
                        || ewl_widget_queued_has(EWL_WIDGET(o), \
                                        EWL_FLAG_QUEUED_PROCESS_DESTROY))

Used to determine if a widget has been destroyed

#define DISABLED ( o ) (ewl_widget_applied_state_has(EWL_WIDGET(o), EWL_STATE_DISABLED))

Used to determine if a widget is disabled

#define EWL_PAIR ( p ) ((Ewl_Pair *)p)

Typedcasts a pointer to an Ewl_Pair pointer

#define EWL_WIDGET ( widget ) ((Ewl_Widget *) widget)

Typecast a pointer to an Ewl_Widget pointer.

#define ewl_widget_flags_get	(	o,
		mask		)	(EWL_WIDGET(o)->flags & mask)

Retrieves the current setting of the widget flags for o.

Parameters:

	o,:	the parameter to retrieve the current value of widget flags
	mask,:	get only the flags specified in mask

Returns:: Returns the current setting of the widget flags for o.

#define ewl_widget_flags_has	(	o,
		check_flags,
		mask	)	(!!(EWL_WIDGET(o)->flags & ((check_flags) & mask)))

Determines if widget has the requested flags set.

Parameters:

	o,:	the widget to check for a specified flags
	check_flags,:	the bitmask of flags to check on the widget
	mask,:	get only the flags specified in mask

Returns:: Returns TRUE if any of the specified flags are set, FALSE otherwise.

#define ewl_widget_flags_has_all	(	o,
		check_flags,
		mask	)	((EWL_WIDGET(o)->flags & ((check_flags) & mask)) == ((check_flags) & mask))

Determines if widget has all of the requested flags set.

Parameters:

	o,:	the widget to check for a specified flags
	check_flags,:	the bitmask of flags to check on the widget
	mask,:	get only the flags specified in mask

Returns:: Returns TRUE if the specified flags are set, FALSE otherwise.

#define ewl_widget_in_tab_list_get ( o ) (ewl_widget_flags_get(o, EWL_FLAG_PROPERTY_IN_TAB_LIST))

Retrieves the current setting of the in tab list flag for o.

Parameters:

o,:

the parameter to retrieve the current value of the in tab list flag

Returns:: Returns the current setting of the in tab list flag for o.

#define ewl_widget_in_tab_list_set	(	o,
		val		)

Value:

(val ? ewl_widget_flags_add(o, EWL_FLAG_PROPERTY_IN_TAB_LIST, \
                                    EWL_FLAGS_PROPERTY_MASK) : \
         ewl_widget_flags_remove(o, EWL_FLAG_PROPERTY_IN_TAB_LIST, \
                                    EWL_FLAGS_PROPERTY_MASK));

Changes the tab list flag value to match val.

Parameters:

	o,:	the widget to change the in tab list
	val,:	a boolean indicating the value of the tab list flag

Returns:: Returns no value.

#define EWL_WIDGET_IS ( w ) (ewl_widget_type_is(EWL_WIDGET(w), EWL_WIDGET_TYPE))

Returns TRUE if the widget is an Ewl_Widget, FALSE otherwise

#define ewl_widget_queued_add	(	o,
		queued		)	ewl_widget_flags_add(o, queued, EWL_FLAGS_QUEUED_MASK)

Parameters:

	o,:	The widget to work with
	queued,:	Add the given queue flag to the widget Adds the given queue flag queued to the widget o

#define ewl_widget_queued_get	(	o,
		queued		)	ewl_widget_flags_get(o, queued, EWL_FLAGS_QUEUED_MASK)

Retrieve the value for the queued queue flag

#define ewl_widget_queued_has	(	o,
		queued		)	ewl_widget_flags_has(o, queued, EWL_FLAGS_QUEUED_MASK)

Determine if the o widget has the queued flag set

#define ewl_widget_queued_remove	(	o,
		queued		)	ewl_widget_flags_remove(o, queued, EWL_FLAGS_QUEUED_MASK)

Remove the queued flag from the o widget

#define ewl_widget_recursive_get ( o ) (ewl_widget_flags_get(o, EWL_FLAG_PROPERTY_RECURSIVE))

Retrieves the current setting of the recursive flag for o.

Parameters:

o,:

the parameter to retrieve the current value of recursive flag

Returns:: Returns the current setting of the recursive flag for o.

#define ewl_widget_recursive_set	(	o,
		val		)

Value:

(val ? ewl_widget_flags_add(o, EWL_FLAG_PROPERTY_RECURSIVE, \
                                    EWL_FLAGS_PROPERTY_MASK) : \
         ewl_widget_flags_remove(o, EWL_FLAG_PROPERTY_RECURSIVE, \
                                    EWL_FLAGS_PROPERTY_MASK));

Changes the recursive flag value to match val.

Parameters:

	o,:	the widget to change the recursive flag
	val,:	a boolean indicating the value of the recursive flag

Returns:: Returns no value.

#define ewl_widget_toplevel_get ( o ) (ewl_widget_flags_get(o, EWL_FLAG_PROPERTY_TOPLEVEL))

Retrieves the current setting of the top level flag for o.

Parameters:

o,:

the parameter to retrieve the current value of top level flag

Returns:: Returns the current setting of the top level flag for o.

#define ewl_widget_toplevel_set	(	o,
		val		)

Value:

(val ? ewl_widget_flags_add(o, EWL_FLAG_PROPERTY_TOPLEVEL, \
                                    EWL_FLAGS_PROPERTY_MASK) : \
         ewl_widget_flags_remove(o, EWL_FLAG_PROPERTY_TOPLEVEL, \
                                    EWL_FLAGS_PROPERTY_MASK));

Changes the top level flag value to match val.

Parameters:

	o,:	the widget to change the top level flag
	val,:	a boolean indicating the value of the top level flag

Returns:: Returns no value.

#define EWL_WIDGET_TYPE "widget"

The type name for the Ewl_Widget widget

#define ewl_widget_visible_add	(	o,
		visible		)	ewl_widget_flags_add(o, visible, EWL_FLAGS_VISIBLE_MASK)

Add the visible flag to the widget o

#define ewl_widget_visible_get	(	o,
		visible		)	ewl_widget_flags_get(o, visible, EWL_FLAGS_VISIBLE_MASK)

Retrieves the visble flag from the widget o

#define ewl_widget_visible_has	(	o,
		visible		)	ewl_widget_flags_has(o, visible, EWL_FLAGS_VISIBLE_MASK)

Check if the visible flag is set in the widget o

#define ewl_widget_visible_remove	(	o,
		visible		)	ewl_widget_flags_remove(o, visible, EWL_FLAGS_VISIBLE_MASK)

Remove the visible flag from the widget o

#define HIDDEN ( o ) (!(EWL_WIDGET(o)->flags & EWL_FLAG_VISIBLE_SHOWN))

Used to determine if a widget is hidden.

#define REALIZED ( o ) (EWL_WIDGET(o)->flags & EWL_FLAG_VISIBLE_REALIZED)

Used to test if a widget has been realized.

#define RECURSIVE ( o ) (EWL_WIDGET(o)->flags & EWL_FLAG_PROPERTY_RECURSIVE)

Used to test if a widget is recursive, aka. an Ewl_Container

#define REVEALED ( o ) (EWL_WIDGET(o)->flags & EWL_FLAG_VISIBLE_REVEALED)

Used to determine if a widget is marked as revealed.

#define TOPLAYERED ( w ) (EWL_WIDGET(w)->flags & EWL_FLAG_PROPERTY_TOPLAYERED)

#define UNMANAGED ( w ) (EWL_WIDGET(w)->flags & EWL_FLAG_PROPERTY_UNMANAGED)

#define VISIBLE ( o ) (EWL_WIDGET(o)->flags & EWL_FLAG_VISIBLE_SHOWN)

Used to test if a widget is visible.

Typedef Documentation

typedef struct Ewl_Attach_List Ewl_Attach_List

The attachment list

typedef struct Ewl_Callback_Chain Ewl_Callback_Chain

Callback chain contains a list and bitmask of chain properties.

typedef struct Ewl_Color_Set Ewl_Color_Set

A set of colours

typedef struct Ewl_Pair Ewl_Pair

A key/value pair set

typedef struct Ewl_Pair_List Ewl_Pair_List

A list of key value pairs

typedef struct Ewl_Widget Ewl_Widget

The class that all widgets should inherit. Provides reference to a parent widget/container, callbacks, and appearance information.

Function Documentation

const char* ewl_widget_appearance_get ( Ewl_Widget * w )

Retrieve the appearance key of the widget.

Parameters:

w,:

the widget to retrieve the appearance key

Returns:: Returns a pointer to the appearance key string on success, NULL on failure.

const char* ewl_widget_appearance_part_text_get	(	Ewl_Widget *	w,
		const char *	part
	)

Retrieve a copy of a parts current text.

Parameters:

	w,:	the widget whose text to retrieve
	part,:	the theme part name whose text to retrieve

Returns:: Returns NULL on failure, a copy of the current text on success.

Get the text of a given Edje-define TEXT part. This is for widgets whose Edje appearance defines TEXT parts, and enables each of those text parts to be retrieved independently.

The returned string will only be valid until the next time text is set on this part.

void ewl_widget_appearance_part_text_set	(	Ewl_Widget *	w,
		const char *	part,
		const char *	text
	)

Change the text of the given theme part of a widget.

Parameters:

	w,:	the widget whose text to change
	part,:	the theme part name whose text to change
	text,:	the new text to change to

Returns:: Returns no value.

Changes the text of a given Edje-define TEXT part. This is for widgets whose Edje appearance defines TEXT parts, and enables each of those text parts to be changed independently. The text value is recorded in a hash and reapplied if the theme is reloaded for this widget.

int ewl_widget_appearance_path_copy	(	Ewl_Widget *	w,
		char *	buf,
		int	size
	)

char* ewl_widget_appearance_path_get ( Ewl_Widget * w )

Retrieve the appearance path key of the widget.

Parameters:

w,:

the widget to retrieve the full appearance key

Returns:: Returns a pointer to the full appearance path string on success, NULL on failure.

int ewl_widget_appearance_path_size_get ( Ewl_Widget * w )

void ewl_widget_appearance_set	(	Ewl_Widget *	w,
		const char *	appearance
	)

Change the appearance of the specified widget.

Parameters:

	w,:	the widget to change the appearance
	appearance,:	the new key for the widgets appearance

Returns:: Returns no value.

Changes the key associated with the widgets appearance and calls the theme update callback to initiate the change.

const char* ewl_widget_appearance_text_get ( Ewl_Widget * w )

Retrieve the text of the given theme part of a widget.

Parameters:

w,:

the widget whose text to retrieve

Returns:: Returns the current text on success, NULL on failure.

Note:: The returned value will only be valid until the next time ewl_widget_appearance_text_set() is called on this widget.

void ewl_widget_appearance_text_set	(	Ewl_Widget *	w,
		const char *	text
	)

Change the text of the given theme part of a widget.

Parameters:

	w,:	the widget whose text to change
	text,:	the new text to change to

Returns:: Returns no value.

Changes the text of an Edje-define TEXT part. This is for widgets whose Edje appearance defines a TEXT part, and identifies it with with a data item called "/WIDGET/textpart". The text value is recorded in a hash and reapplied if the theme is reloaded for this widget.

unsigned int ewl_widget_applied_state_has	(	Ewl_Widget *	w,
		Ewl_State	state
	)

void ewl_widget_cb_configure	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_hide	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_mouse_down	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_mouse_move	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_mouse_up	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_obscure	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_realize	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_reparent	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_reveal	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_show	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_cb_unrealize	(	Ewl_Widget *	w,
		void *	ev_data,
		void *	user_data
	)

void ewl_widget_color_get	(	Ewl_Widget *	w,
		unsigned int *	r,
		unsigned int *	g,
		unsigned int *	b,
		unsigned int *	a
	)

Gets the colour settings of the widget.

Parameters:

	w,:	The widget to get the colour from
	r,:	Where to put the red value
	g,:	Where to put the green value
	b,:	Where to put the blue value
	a,:	Where to put the alpha value

Returns:: Returns no value

void ewl_widget_color_set	(	Ewl_Widget *	w,
		unsigned int	r,
		unsigned int	g,
		unsigned int	b,
		unsigned int	a
	)

sets the colour of the widget

Parameters:

	w,:	The widget to set the color of
	r,:	The red value
	g,:	The green value
	b,:	The blue value
	a,:	The alpha value

Returns:: Returns no value

void ewl_widget_configure ( Ewl_Widget * w )

Initiate configuring of the specified widget.

Parameters:

w,:

the widget to configure

Returns:: Returns no value.

The configure callback is triggered for the specified widget, this should adjust the widgets size and position.

void ewl_widget_custom_state_set	(	Ewl_Widget *	w,
		const char *	state,
		Ewl_Durability	flag
	)

Update the appearance of the widget to a state.

Parameters:

	w,:	the widget to update the appearance
	state,:	the new state of the widget
	flag,:	the flag for the state e.g. EWL_TRANSIENT

Returns:: Returns no value.

Changes the appearance of the widget depending on the state string passed by the state parameter.

void* ewl_widget_data_del	(	Ewl_Widget *	w,
		void *	k
	)

Remove the specified key / value pair from the widget and return the value.

Parameters:

	w,:	the widget that owns the key value pair
	k,:	the key that is associated with the data

Returns:: Returns the deleted value.

Removes a key / value pair with k as the key from the specified widget w and return the value. NULL is returned if there is no stored data or if an error occurs.

void* ewl_widget_data_get	(	Ewl_Widget *	w,
		void *	k
	)

retrieve the specified key / value pair from the widget

Parameters:

	w,:	the widget that owns the key value pair
	k,:	the key that is associated with the data

Returns:: Returns the value associated with k on success, NULL on failure.

Retrieves a key / value pair with k as the key from the specified widget w.

void ewl_widget_data_set	(	Ewl_Widget *	w,
		void *	k,
		void *	v
	)

Attach the specified key / value pair to the widget.

Parameters:

	w,:	the widget to own the key value pair
	k,:	the key that is associated with the data
	v,:	the data that is to be tracked

Returns:: Returns no value.

Assigns a key / value pair with k as the key and v as the value to the specified widget w.

void ewl_widget_destroy ( Ewl_Widget * w )

Destroy the specified widget.

Parameters:

w,:

the widget to be destroyed

Returns:: Returns no value.

The widget calls it's destroy callback to do any clean up necessary and then free's the widget.

void ewl_widget_disable ( Ewl_Widget * w )

Prevent a widget from receiving any events.

Parameters:

w,:

the widget to disable

Returns:: Returns no value. Disables a specified widget.

This prevents that widget from receiving any user input events.

void ewl_widget_enable ( Ewl_Widget * w )

Re-enable a disabled widget.

Parameters:

w,:

the widget to re-enable

Returns:: Returns no value.

Re-enables a previously disabled widget.

void ewl_widget_flags_add	(	Ewl_Widget *	w,
		unsigned int	flags,
		unsigned int	mask
	)

Add the set of flags specified in flags to w.

Parameters:

	w,:	the widget to set the specified widget flags
	flags,:	a bitmask of new flags to be set in the widget
	mask,:	a bitmask limiting added flags to a certain set

Returns:: Returns no value.

void ewl_widget_flags_remove	(	Ewl_Widget *	w,
		unsigned int	flags,
		unsigned int	mask
	)

Removes the set of state flags specified in flags from w.

Parameters:

	w,:	the widget to remove specified state flags
	flags,:	a bitmask of flags to be removed from the widget
	mask,:	a bitmask limiting removed flags to a certain set

Returns:: Returns no value.

void ewl_widget_focus_send ( Ewl_Widget * w )

Changes the keyboard focus to the widget w.

Parameters:

w,:

the widget to receive keyboard focus

Returns:: Returns no value.

This function will send the keyboard focus to the given widget.

Note:: Since the focus handling is done by the embed, this function will only work proper if the widget has already an embed (in most cases a window) as an (indirect) parent.

unsigned int ewl_widget_focusable_get ( Ewl_Widget * w )

Checks the focusable state of the widget.

Parameters:

w,:

The widget to get the focusable state from

Returns:: Returns TRUE if the widget is focusable, FALSE otherwise

void ewl_widget_focusable_set	(	Ewl_Widget *	w,
		unsigned int	val
	)

Set if the given widget is focusable or not.

Parameters:

	w,:	The widget to set the focusable values
	val,:	The focusable value to set

Returns:: Returns no value

Ewl_Widget* ewl_widget_focused_get ( void )

Retrieve the currently focused widget.

Returns:: Returns the currnetly focused widget.

void ewl_widget_free ( Ewl_Widget * w )

void ewl_widget_hide ( Ewl_Widget * w )

Mark a widget as invisible.

Parameters:

w,:

the widget to be marked as invisible

Returns:: Returns no value.

Marks the widget as invisible so that it will not be displayed the next time through the rendering loop.

unsigned int ewl_widget_ignore_focus_change_get ( Ewl_Widget * w )

Get if the widget is ignoring focus changes.

Parameters:

w,:

The widget to check if it blocks tab focus

Returns:: Returns TRUE if the widget blocks tab focus, FALSE otherwise.

void ewl_widget_ignore_focus_change_set	(	Ewl_Widget *	w,
		unsigned int	val
	)

Set if the widget should ignore focus changes.

Parameters:

	w,:	The widget to set if it accepts or blocks focus changes
	val,:	TRUE or FALSE on if this widget blocks tabbing off

Returns:: Returns no value.

void ewl_widget_inherit	(	Ewl_Widget *	widget,
		const char *	inherit
	)

Appends the given inheritance to this widgets inheritance string.

Parameters:

	widget,:	the widget to set the inheritance on
	inherit,:	the string to append to the inheritance

Returns:: Returns no value.

void ewl_widget_inherited_state_add	(	Ewl_Widget *	w,
		Ewl_State	state
	)

unsigned int ewl_widget_inherited_state_has	(	Ewl_Widget *	w,
		Ewl_State	state
	)

void ewl_widget_inherited_state_remove	(	Ewl_Widget *	w,
		Ewl_State	state
	)

int ewl_widget_init ( Ewl_Widget * w )

Initialize a widget to default values and callbacks.

Parameters:

w,:

the widget to initialize

Returns:: Returns TRUE on success, FALSE on failure.

The widget w is initialized to default values and is assigned the default callbacks.

unsigned int ewl_widget_internal_is ( Ewl_Widget * w )

void ewl_widget_internal_set	(	Ewl_Widget *	w,
		unsigned int	val
	)

int ewl_widget_layer_priority_get ( Ewl_Widget * w )

Retrieve a widgets layer relative to it's parent.

Parameters:

w,:

the widget to retrieve current relative layer

Returns:: Returns a widgets current layer relative to it's parent.

void ewl_widget_layer_priority_set	(	Ewl_Widget *	w,
		int	layer
	)

Set the relative layer to it's parent.

Parameters:

	w,:	the widget to change relative layers
	layer,:	the new relative layer of the widget

Returns:: Returns no value.

Changes the current layer of w relative to it's parent. The default value is 0.

int ewl_widget_layer_top_get ( Ewl_Widget * w )

Returns if the widget will be drawn above all the others.

Parameters:

w,:

the widget to get the top value

Returns:: Returns TRUE or FALSE

void ewl_widget_layer_top_set	(	Ewl_Widget *	w,
		int	top
	)

set the widget to be layered above all other widgets

Parameters:

	w,:	the widget to set the top value
	top,:	TRUE or FALSE

Returns:: Returns no value.

This set the widget to be layered above all other widgets.

Ewl_Widget* ewl_widget_name_find ( const char * name )

Find a widget identified by a name.

Parameters:

name,:

the name of the widget to retrieve

Returns:: Returns an pointer a matched widget on success.

const char* ewl_widget_name_get ( Ewl_Widget * w )

Get the name for the specified widget.

Parameters:

w,:

the widget to retrieve the name

Returns:: Returns an pointer to an allocated name string on success.

void ewl_widget_name_set	(	Ewl_Widget *	w,
		const char *	name
	)

Name the specified widget.

Parameters:

	w,:	the widget to name
	name,:	the new name for the widget

Returns:: Returns no value.

Ewl_Widget* ewl_widget_new ( void )

Allocate a new widget.

Returns:: Returns a newly allocated widget on success, NULL on failure.

Do not use this function unless you know what you are doing! It is only intended to easily create custom widgets that are not containers.

void ewl_widget_obscure ( Ewl_Widget * w )

Indicate a widget is obscured.

Parameters:

w,:

the widget to mark as obscured

Returns:: Returns no value.

unsigned int ewl_widget_onscreen_is ( Ewl_Widget * w )

Checks if the given widget is currently on screen.

Parameters:

w,:

The widget to check

Returns:: Returns TRUE if the widget is onscreen

Ewl_Widget* ewl_widget_parent_get ( Ewl_Widget * w )

Retrieves the parent of the given widget.

Parameters:

w,:

The widget to get the parent from

Returns:: Returns the parent of the given widget, or NULL if none set

int ewl_widget_parent_of	(	Ewl_Widget *	c,
		Ewl_Widget *	w
	)

Determine if a widget is a parent of another widget.

Parameters:

	c,:	the widget to compare against
	w,:	the widget to check parentage

Returns:: Returns TRUE if c is a parent of w, otherwise returns FALSE.

void ewl_widget_parent_set	(	Ewl_Widget *	w,
		Ewl_Widget *	p
	)

change the parent of the specified widget

Parameters:

	w,:	the widget to change the parent
	p,:	the new parent of the widget

Returns:: Returns no value.

Changes the parent of the widget w, to the container p. The reparent callback is triggered to notify children of w of the change in parent.

void ewl_widget_print ( Ewl_Widget * w )

Prints info for debugging a widget's state information.

Parameters:

w,:

the widget to print info

Returns:: Returns no value.

void ewl_widget_print_verbose ( Ewl_Widget * w )

Prints verbose info for debugging a widget's state information.

Parameters:

w,:

the widget to print verbose info

Returns:: Returns no value.

void ewl_widget_realize ( Ewl_Widget * w )

Realize the specified widget.

Parameters:

w,:

The widget to realize

Returns:: Returns no value.

The specified widget is realized, ie. actually displayed to the screen.

void ewl_widget_realize_force ( Ewl_Widget * w )

Forces a widget to be realized (in normal use use ewl_widget_realize). Used to immediately generate the widget sizing values.

Parameters:

w,:

The widget to realize

Returns:: Returns no value.

void ewl_widget_reparent ( Ewl_Widget * w )

initiate reparent of the specified widget

Parameters:

w,:

the widget to reparent

Returns:: Returns no value.

The reparent callback is triggered for the specified widget, this should adjust the widgets attributes based on the new parent.

void ewl_widget_reveal ( Ewl_Widget * w )

Indicate a widget is revealed.

Parameters:

w,:

the widget to mark as revealed

Returns:: Returns no value.

void ewl_widget_show ( Ewl_Widget * w )

mark a widget as visible

Parameters:

w,:

the widget to be marked as visible

Returns:: Returns no value.

Marks the widget as visible so that it will be displayed the next time through the rendering loop. Note that the show callback may be delayed until the widget has been realized.

void ewl_widget_state_add	(	Ewl_Widget *	w,
		Ewl_State	state
	)

unsigned int ewl_widget_state_has	(	Ewl_Widget *	w,
		Ewl_State	state
	)

void ewl_widget_state_remove	(	Ewl_Widget *	w,
		Ewl_State	state
	)

void ewl_widget_tab_order_append ( Ewl_Widget * w )

Changes the order in the embed so w receives focus first on tab.

Parameters:

w,:

the widget to be moved to the front of the focus list

Returns:: Returns no value.

This moves the widget w to the end of the tab order list in the embed that holds it.

void ewl_widget_tab_order_insert	(	Ewl_Widget *	w,
		unsigned int	idx
	)

Changes the order in the embed so w receives focus first on tab.

Parameters:

	w,:	the widget to be moved to the front of the focus list
	idx,:	The index to insert the tab into

Returns:: Returns no value.

This moves the widget w to the given index in the tab order list in the embed that holds it.

void ewl_widget_tab_order_insert_after	(	Ewl_Widget *	w,
		Ewl_Widget *	after
	)

Insert the given widget into the tab order after the after widget.

Parameters:

	w,:	The widget to insert into the tab order
	after,:	The widget to insert after

Returns:: Returns no value.

void ewl_widget_tab_order_insert_before	(	Ewl_Widget *	w,
		Ewl_Widget *	before
	)

Inserts the widget into the tab order before the before widget.

Parameters:

	w,:	The widget to be inserted into the tab order
	before,:	The widget we are to be inserted before

Returns:: Returns no value.

void ewl_widget_tab_order_prepend ( Ewl_Widget * w )

Changes the order in the embed so w receives focus first on tab.

Parameters:

w,:

the widget to be moved to the front of the focus list

Returns:: Returns no value.

This moves the widget w to the front of the tab order list in the embed that holds it.

void ewl_widget_tab_order_remove ( Ewl_Widget * w )

Remove the widget from the tab order.

Parameters:

w,:

The widget to remove from the tab order

Returns:: Returns no value.

void ewl_widget_theme_path_set	(	Ewl_Widget *	w,
		const char *	path
	)

Change the path of the specified widget.

Parameters:

	w,:	the widget to change the theme path
	path,:	the new path to find the theme file for the widget's appearance

Returns:: Returns no value.

Sets and applies the theme path for the given widget. This will also change the theme of possible children. If the path is NULL, the default path will be used instead.

void ewl_widget_tree_print ( Ewl_Widget * w )

Prints to stdout the tree of widgets that are parents of a widget.

Parameters:

w,:

the widget to display ancestry tree

Returns:: Returns no value.

unsigned int ewl_widget_type_is	(	Ewl_Widget *	widget,
		const char *	type
	)

Determine if the widget w has inherited from the type t.

Parameters:

	widget,:	the widget to determine if a type is inherited
	type,:	the type to check for inheritance in the widget

Returns:: Returns TRUE if w inherited the type t, otherwise FALSE.

unsigned int ewl_widget_unmanaged_is ( Ewl_Widget * w )

void ewl_widget_unmanaged_set	(	Ewl_Widget *	w,
		unsigned int	val
	)

void ewl_widget_unrealize ( Ewl_Widget * w )

Unrealize the specified widget.

Parameters:

w,:

The widget to unrealize

Returns:: Returns no value.

The specified widget is unrealized, ie. no longer displayed to the screen.

Ewl_Widget: The Parent Widget Class Common to All Widgets

Detailed Description

Tutorial

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation