NAME

pEFL - Perl binding to the Enlightenment Foundation Libraries

SYNOPSIS

use pEFL;
use strict;
use warnings;

use pEFL::Elm;

pEFL::Elm::init($#ARGV, \@ARGV);

pEFL::Elm::policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);

my $win = pEFL::Elm::Win->util_standard_add("hello", "Hello");
$win->smart_callback_add("delete,request",\&on_done, undef);

my $box = pEFL::Elm::Box->add($win);
$box->horizontal_set(1);
$win->resize_object_add($box);
$box->show();

my $lab = pEFL::Elm::Label->add($win);
$lab->text_set("Hello out there, World\n");
$box->pack_end($lab);
$lab->show();

my $btn = pEFL::Elm::Button->add($win);
$btn->text_set("OK");
$box->pack_end($btn);
$btn->show();
$btn->smart_callback_add("clicked", \&on_done, undef);

$win->show();

pEFL::Elm::run();

pEFL::Elm::shutdown();

sub on_done {
	print "Exiting \n";
	pEFL::Elm::exit();
}

DESCRIPTION

This module provides a nice object-oriented interface to the Enlightenment Foundation Libraries (EFL). Apart from that the API is deliberately kept close to the Elementary C API. The Perl method names generally remove the prefix at the beginning of the C functions. Therefore applying the C documentation should be no problem.

For the documentation in detail please study the single modules and the C documentation

SPECIFICS OF THE BINDING

Perl specific variants of methods (_pv, "Perl Value"-methods)

If a method returns an Eina_List there usually is a version with the suffix _pv (for Perl Value) that returns a Perl array (for example in pEFL::Elm::List the method items_get_pv()). It is recommended to use these Perl adjusted methods. If you find a method, where the adaption is missing, please open an issue on github.

Sometimes a method returns an EvasObject which can be any Elm Widget Type (e.g. $nav->item_pop(), $object->content_get, $object_item->content_get()). In this case there will be a "Perl Value"-version that tries to bless the returned variable to the appropriate Perl class, too (e.g. $naviframe->item_pop_pv(), $object->[part_]content_get_pv(), $object_item->[part_]content_get_pv()).

Starting with version 0.77, it is possible to trigger Ecore events directly from Perl using $pEFL::Ecore::Event->add_pv($type, $event_info). To get the perl value of $event_info in the event handler, see pEFL::ev_info2pv($event_info).

Output Parameters

pEFL sometimes uses output parameters. See for example void elm_calendar_min_max_year_get(Evas_Object *obj,int *min,int *max), where you have to pass in C a pointer to max and min. In Perl this is translated to my ($min, $max) = $calendar->min_max_year_get(). Sometimes the C function returns a status or similar as in Eina_Bool elm_entry_cursor_geometry_get(Evas_Object *obj,int *x,int *y,int *w,int *h). In Perl this status variable is given, too. So the function elm_entry_cursor_geometry_get for example is translated into my ($status,$x,$y,$w,$h) = $entry->cursor_geometry_get.

FUNCTIONS IN EFL

The pEFL module gives you the following functions:

pEFL::ev_info2s($event_info)

if $event_info contains the address to a C string, this function converts the addressed C void pointer to a Perl string.

pEFL::ev_info2obj($event_info, "pEFL::Evas::Event::MouseUp")

if $event_info contains the address to a C struct, this function converts the addressed void pointer to a Perl scalar, that is blessed to the given class. The Perl class gives the necessary methods to get the members of the struct. At the moment the following C structs are (among others) supported:

• Elm_Entry_Anchor_Info (aka pEFL::Elm::EntryAnchorInfo)

• Elm_Entry_Change_Info (aka pEFL::Elm::EntryChangeInfo)

• Elm_Image_Progress (aka pEFL::Elm::ImageProgress)

• Elm_Panel_Scroll_Info (aka pEFL::Elm::PanelScrollInfo)

• Evas_Coord_Rectangle (aka pEFL::Evas::Coord::Rectangle)

• Evas_Event_Mouse_Down (aka pEFL::Evas::Event::MouseDown)

• Evas_Event_Mouse_Up (aka pEFL::Evas::Event::MouseUp)

• Evas_Event_Mouse_In (aka pEFL::Evas::Event::MouseIn)

• Evas_Event_Mouse_Out (aka pEFL::Evas::Event::MouseOut)

• Evas_Event_Mouse_Move (aka pEFL::Evas::Event::MouseMove)

• Evas_Event_Mouse_Wheel (aka pEFL::Evas::Event::MouseWheel)

• Ecore_Event_Key (aka pEFL::Ecore::Event::Key)

• Ecore_Event_MouseButton (aka pEFL::Ecore::Event::MouseButton)

• Ecore_Event_MouseMove (aka pEFL::Ecore::Event::MouseMove)

• Ecore_Event_MouseWheel (aka pEFL::Ecore::Event::MouseWheel)

• Ecore_Event_Signal_Exit (aka pEFL::Ecore::Event::SignalExit)

• Ecore_Event_Signal_Realtime (aka pEFL::Ecore::Event::SignalRealtime)

• Ecore_Event_Signal_User (aka pEFL::Ecore::Event::SignalUser)

• Evas_Textblock_Rectangle (aka pEFL::Evas::TextblockRectangle)

• and more...

pEFL::ev_info2pv($event_info)

Starting with version 0.77, it is possible to trigger events directly from Perl using $pEFL::Ecore::Event->add_pv($type, $event_info). Of course, only a Perl variable can be passed as $event_info (i.e., an SV * in Perl XS). pEFL stores this scalar in a struct PerlEvent (accessible in Perl via the pEFL::Ecore::Event::PerlEvent module). The pEFL::ev_info2pv function is intended as a shortcut for retrieving the Perl variable from $event_info.

Some events pass an Elementary Widget or an Evas Object as $event_info. Of course you can use ev_info2obj() to convert these pointers to a appropiate blessed Perl scalar, too. See for instance examples/colorselector.pl, where the Elm Widget Item Elm_Colorselector_Palette_Item is passed as $event_info. This must converted by pEFL::ev_info2obj($ev_info, "pEFL::Elm::ColorselectorPaletteItem");

The provision of Perl classes for event_info C structs is work in progress. If you need a specific binding for a C struct that is not supported at the moment, please send an issue report.

STATE OF THE BINDING

Of course, the integration of a set of libraries is always a work in progress and never truly complete. Although some features are certainly still missing (in particular, creating SmartClasses in Perl is not yet possible), the Perl binding is now stable, well-tested and mature. Don't expect any major changes to the API, too (especially since the binding is deliberately modeled closely after the C API and translates the corresponding C calls with as little “magic” as possible to ensure a low-maintenance interface). Minor changes, fixes, and adjustments are, of course, still possible, but we hardly try to avoid them.

If you miss something or find issues, please report it to Github.

WHY THE NAME "pEFL"

Originally the name of the distribution was Efl. Unfortunately there was a conflict with the existing distribution EFL which isn't maintained any more and can't be compiled with newer versions of efl. Therefore the name pEFL was chosen whereby the "p" stands for "perl".

SEE ALSO

Enlightenment Foundation Libraries

Perl-EFL Github Repository

Caecilia.pl - a ABC notation editor using pEFL

AUTHOR

Maximilian Lika (perlmax@cpan.org)

COPYRIGHT AND LICENSE

Copyright (C) 2022 by Maximilian Lika

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.28.1 or, at your option, any later version of Perl 5 you may have available.

cpanm pEFL

perl -MCPAN -e shell
install pEFL