Tizen Native API  5.0
External plug/socket infrastructure for remote canvases

These functions allow 1 process to create a "socket" was pluged into which another process can create a "plug" remotely to plug into. Socket can provide content for several plugs. This is best for small sized objects (about the size range of a small icon up to a few large icons). Since the plug is actually an image object, you can fetch the pixel data

Since (EFL) :
1.2

Functions

Ecore_Evas * ecore_evas_extn_socket_new (int w, int h)
 Creates a new Ecore_Evas canvas for the new external ecore evas socket.
Eina_Bool ecore_evas_extn_socket_listen (Ecore_Evas *ee, const char *svcname, int svcnum, Eina_Bool svcsys)
 Creates a socket to provide the service for external ecore evas socket.
void ecore_evas_extn_socket_events_block_set (Ecore_Evas *ee, Eina_Bool events_block)
 Sets the blocking about mouse events to Ecore Evas.
Eina_Bool ecore_evas_extn_socket_events_block_get (Ecore_Evas *ee)
 Gets the blocking about mouse events to Ecore Evas.
void ecore_evas_extn_plug_object_data_lock (Evas_Object *obj)
 Locks the pixel data so the socket cannot change it.
void ecore_evas_extn_plug_object_data_unlock (Evas_Object *obj)
 Unlocks the pixel data so the socket can change it again.
Evas_Objectecore_evas_extn_plug_new (Ecore_Evas *ee_target)
 Creates a new external ecore evas plug.
Eina_Bool ecore_evas_extn_plug_connect (Evas_Object *obj, const char *svcname, int svcnum, Eina_Bool svcsys)
 Connects an external ecore evas plug to service provided by external ecore evas socket.
Eina_Bool ecore_evas_obscured_get (const Ecore_Evas *ee)
 Query if the ecore evas is obscured or unobscured.
void ecore_evas_pointer_xy_get (const Ecore_Evas *ee, Evas_Coord *x, Evas_Coord *y)
 Retrieves the coordinates of the default mouse pointer.
Eina_Bool ecore_evas_pointer_warp (const Ecore_Evas *ee, Evas_Coord x, Evas_Coord y)
 Sets the coordinates of the mouse pointer.
void ecore_evas_pointer_device_xy_get (const Ecore_Evas *ee, const Efl_Input_Device *pointer, Evas_Coord *x, Evas_Coord *y)
 Retrieves the coordinates of the mouse pointer.
void * ecore_evas_pixmap_visual_get (const Ecore_Evas *ee)
 Retrieves the Visual used for pixmap creation.
unsigned long ecore_evas_pixmap_colormap_get (const Ecore_Evas *ee)
 Retrieves the Colormap used for pixmap creation.
int ecore_evas_pixmap_depth_get (const Ecore_Evas *ee)
 Retrieves the depth used for pixmap creation.

Function Documentation

Eina_Bool ecore_evas_extn_plug_connect ( Evas_Object obj,
const char *  svcname,
int  svcnum,
Eina_Bool  svcsys 
)

Connects an external ecore evas plug to service provided by external ecore evas socket.

Parameters:
objThe Ecore_Evas containing the canvas in which the new image object will live.
svcnameThe service name to connect to set up by the socket.
svcnumThe service number to connect to (set up by socket).
svcsysBoolean to set if the service is a system one or not (set up by socket).
Returns:
EINA_TRUE if creation is successful, EINA_FALSE if it does not.
See also:
ecore_evas_extn_plug_new()
Since (EFL) :
1.2
Evas_Object* ecore_evas_extn_plug_new ( Ecore_Evas *  ee_target)

Creates a new external ecore evas plug.

Parameters:
ee_targetThe Ecore_Evas containing the canvas in which the new image object will live.
Returns:
An evas image object that will contain the image output of a socket.

This creates an image object that will contain the output of another processes socket canvas when it connects. All input will be sent back to this process as well, effectively swallowing or placing the socket process in the canvas of the plug process in place of the image object. The image object by default is created to be filled (equivalent of evas_object_image_filled_add() on creation) so image content will scale to fill the image unless otherwise reconfigured. The Ecore_Evas size of the plug is the master size and determines size in pixels of the plug canvas. You can change the size with something like:

 Eina_Bool res = EINA_FALSE;
 Evas_Object *obj = ecore_evas_extn_plug_new(ee);

 res = ecore_evas_extn_plug_connect("svcname", 1, EINA_FALSE);
 if (!res) return;
 ecore_evas_resize(ee, 240, 400);
See also:
ecore_evas_extn_socket_new()
ecore_evas_extn_plug_connect()
Since (EFL) :
1.2

Locks the pixel data so the socket cannot change it.

Parameters:
objThe image object returned by ecore_evas_extn_plug_new() to lock

You may need to get the image pixel data with evas_object_image_data_get() from the image object, but need to ensure that it does not change while you are using the data. This function lets you set an advisory lock on the image data so the external plug process will not render to it or alter it.

You should only hold the lock for just as long as you need to read out the image data or otherwise deal with it, and then unlock it with ecore_evas_extn_plug_object_data_unlock(). Keeping a lock over more than 1 iteration of the main ecore loop will be problematic, so avoid it. Also forgetting to unlock may cause the socket process to freeze and thus create odd behaviors.

See also:
ecore_evas_extn_plug_new()
ecore_evas_extn_plug_object_data_unlock()
Since (EFL) :
1.2

Unlocks the pixel data so the socket can change it again.

Parameters:
objThe image object returned by ecore_evas_extn_plug_new() to unlock

This unlocks after an advisor lock has been taken by ecore_evas_extn_plug_object_data_lock().

See also:
ecore_evas_extn_plug_new()
ecore_evas_extn_plug_object_data_lock()
Since (EFL) :
1.2

Gets the blocking about mouse events to Ecore Evas.

Parameters:
eeThe Ecore_Evas.
Returns:
The blocking about mouse events.
See also:
ecore_evas_extn_socket_events_block_set()
Since (EFL) :
1.15
void ecore_evas_extn_socket_events_block_set ( Ecore_Evas *  ee,
Eina_Bool  events_block 
)

Sets the blocking about mouse events to Ecore Evas.

Parameters:
eeThe Ecore_Evas.
events_blockThe blocking about mouse events.
See also:
ecore_evas_extn_socket_events_block_get()
Since (EFL) :
1.15
Eina_Bool ecore_evas_extn_socket_listen ( Ecore_Evas *  ee,
const char *  svcname,
int  svcnum,
Eina_Bool  svcsys 
)

Creates a socket to provide the service for external ecore evas socket.

Parameters:
eeThe Ecore_Evas.
svcnameThe name of the service to be advertised. ensure that it is unique (when combined with svcnum) otherwise creation may fail.
svcnumA number (any value, 0 being the common default) to differentiate multiple instances of services with the same name.
svcsysA boolean that if true, specifies to create a system-wide service all users can connect to, otherwise the service is private to the user ide that created the service.
Returns:
EINA_TRUE if creation is successful, EINA_FALSE if it does not.

This creates socket specified by svcname, svcnum and svcsys. If creation is successful, EINA_TRUE is returned or EINA_FALSE if creation fails.

See also:
ecore_evas_extn_socket_new()
ecore_evas_extn_plug_new()
ecore_evas_extn_plug_object_data_lock()
ecore_evas_extn_plug_object_data_unlock()
Since (EFL) :
1.2
Ecore_Evas* ecore_evas_extn_socket_new ( int  w,
int  h 
)

Creates a new Ecore_Evas canvas for the new external ecore evas socket.

Parameters:
wThe width of the canvas, in pixels
hThe height of the canvas, in pixels
Returns:
A new Ecore_Evas instance, or NULL on failure

This creates a new extn_socket canvas wrapper, with image data array bound to the ARGB format, 8 bits per pixel.

If creation is successful, an Ecore_Evas handle is returned or NULL if creation fails. Also focus, show, hide etc. callbacks will also be called if the plug object is shown, or already visible on connect, or if it is hidden later, focused or unfocused.

This function has to be followed by ecore_evas_extn_socket_listen(), for starting ecore ipc service.

 Eina_Bool res = EINA_FALSE;
 Ecore_Evas *ee = ecore_evas_extn_socket_new(1, 1);

 res = ecore_evas_extn_socket_listen("svcname", 1, EINA_FALSE);
 if (!res) return;
 ecore_evas_resize(ee, 240, 400);

or

 Eina_Bool res = EINA_FALSE;
 Ecore_Evas *ee = ecore_evas_extn_socket_new(240, 400);

 res = ecore_evas_extn_socket_listen("svcname", 1, EINA_FALSE);
 if (!res) return;

When a client(plug) connects, you will get the ECORE_EVAS_EXTN_CLIENT_ADD event in the ecore event queue, with event_info being the image object pointer passed as a void pointer. When a client disconnects you will get the ECORE_EVAS_EXTN_CLIENT_DEL event.

You can set up event handles for these events as follows:

 static Eina_Bool client_add_cb(void *data, int event, void *event_info)
 {
    Ecore_Evas *ee = event_info;
    printf("client is connected to external socket %p\n", ee);
    return ECORE_CALLBACK_PASS_ON;
 }

 static Eina_Bool client_del_cb(void *data, int event, void *event_info)
 {
    Ecore_Evas *ee = event_info;
    printf("client is disconnected from external socket %p\n", ee);
    return ECORE_CALLBACK_PASS_ON;
 }

 void setup(void)
 {
    ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_ADD,
                           client_add_cb, NULL);
    ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_DEL,
                           client_del_cb, NULL);
 }

Note that events come in later after the event happened. You may want to be careful as data structures you had associated with the image object may have been freed after deletion, but the object may still be around awaiting cleanup and thus still be valid.You can change the size with something like:

See also:
ecore_evas_extn_socket_listen()
ecore_evas_extn_plug_new()
ecore_evas_extn_plug_object_data_lock()
ecore_evas_extn_plug_object_data_unlock()
Since (EFL) :
1.2
Eina_Bool ecore_evas_obscured_get ( const Ecore_Evas *  ee)

Query if the ecore evas is obscured or unobscured.

Parameters:
eeThe Ecore_Evas
Returns:
EINA_TRUE if the ecore evas is obscured, EINA_FALSE unobscured.
Warning:
Support for this depends on the underlying windowing system.
Since (EFL) :
1.16
unsigned long ecore_evas_pixmap_colormap_get ( const Ecore_Evas *  ee)

Retrieves the Colormap used for pixmap creation.

Parameters:
eeThe Ecore_Evas containing the pixmap
Returns:
The Colormap which was used when creating the pixmap
Warning:
If and when this function is called depends on the underlying windowing system. This function should only be called if the Ecore_Evas was created using ecore_evas_software_x11_pixmap_new or ecore_evas_gl_x11_pixmap_new
Since (EFL) :
1.8
int ecore_evas_pixmap_depth_get ( const Ecore_Evas *  ee)

Retrieves the depth used for pixmap creation.

Parameters:
eeThe Ecore_Evas containing the pixmap
Returns:
The depth which was used when creating the pixmap
Warning:
If and when this function is called depends on the underlying windowing system. This function should only be called if the Ecore_Evas was created using ecore_evas_software_x11_pixmap_new or ecore_evas_gl_x11_pixmap_new
Since (EFL) :
1.8
void* ecore_evas_pixmap_visual_get ( const Ecore_Evas *  ee)

Retrieves the Visual used for pixmap creation.

Parameters:
eeThe Ecore_Evas containing the pixmap
Returns:
The Visual which was used when creating the pixmap
Warning:
If and when this function is called depends on the underlying windowing system. This function should only be called if the Ecore_Evas was created using ecore_evas_software_x11_pixmap_new or ecore_evas_gl_x11_pixmap_new
Since (EFL) :
1.8
void ecore_evas_pointer_device_xy_get ( const Ecore_Evas *  ee,
const Efl_Input_Device *  pointer,
Evas_Coord *  x,
Evas_Coord *  y 
)

Retrieves the coordinates of the mouse pointer.

Parameters:
eeThe Ecore_Evas containing the pointer
pointerThe pointer device, use NULL for the default pointer.
xPointer to integer to store horizontal coordinate. May be NULL.
yPointer to integer to store vertical coordinate. May be NULL.
Since (EFL) :
1.19
Eina_Bool ecore_evas_pointer_warp ( const Ecore_Evas *  ee,
Evas_Coord  x,
Evas_Coord  y 
)

Sets the coordinates of the mouse pointer.

Parameters:
eeThe Ecore_Evas containing the pointer
xThe horizontal coordinate to move the pointer to
yThe vertical coordinate to move the pointer to
Returns:
EINA_TRUE on success, EINA_FALSE on failure.
Since (EFL) :
1.8
Since :
3.0
void ecore_evas_pointer_xy_get ( const Ecore_Evas *  ee,
Evas_Coord *  x,
Evas_Coord *  y 
)

Retrieves the coordinates of the default mouse pointer.

Parameters:
eeThe Ecore_Evas containing the pointer
xPointer to integer to store horizontal coordinate. May be NULL.
yPointer to integer to store vertical coordinate. May be NULL.
See also:
ecore_evas_pointer_device_xy_get
Since (EFL) :
1.8
Since :
3.0

Variable Documentation

this event is received when a plug has connected to an extn socket

Since (EFL) :
1.2

this event is received when a plug has disconnected from an extn socket

Since (EFL) :
1.2