davemds pushed a commit to branch master. http://git.enlightenment.org/enlightenment/modules/edgar.git/commit/?id=36c8e39c344fc5d3c48f3b0fac65c5d3cf0e1892
commit 36c8e39c344fc5d3c48f3b0fac65c5d3cf0e1892 Author: davemds <[email protected]> Date: Sat Aug 30 12:11:30 2014 +0200 Some doc to help writing your own gadget --- README | 19 ++++++++++ python/e.py | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 123 insertions(+), 10 deletions(-) diff --git a/README b/README index b039070..96a5903 100644 --- a/README +++ b/README @@ -53,3 +53,22 @@ The led-clock gadget Usage tips: * click on the first led column to trigger fancy animations. + + +How to write your own gadget +============================ + +I suggest to start from the ruler gadget, just copy it's folder and +start hacking, a minimal gadget require: + +base_folder/ (need to have the same name as the gadget) + Makefile (the provided makefile should work for you) + __init__.py (the gadget python script) + gadget.edc (the gadget edje file) + images/ + ... + fonts/ + ... + +Look at the e.py file (in the python/ folder in sources) for more +documentation. diff --git a/python/e.py b/python/e.py index 2e88c84..43adeac 100644 --- a/python/e.py +++ b/python/e.py @@ -1,47 +1,141 @@ # This python file use the following encoding: utf-8 from eapi import ( - theme_edje_object_set # (edje_object, 'gadget_name', 'group_name') + theme_edje_object_set ) +""" theme_edje_object_set(edje_obj, gadget_name, group_name) + +You must use this function to load additional groups from your +edje file. This function will search the group first in the E theme +and then in your local edje file. + +Args: + obj: the edje object where the group will be loaded + gadget_name: the name of your gadget + group_name: the name of the edje group to load + +""" class Gadget(object): - """ Class doc """ + """ The gadgets base class. + + This is the base class for all gadgets, all of them MUST inherit from + this base. Note that your class need to be called 'Gadget'. + + """ def __init__(self): - """ Class initialiser """ + """ Class initialiser. + + This is called as soon as one instance of the gadget is required. + Here you can initialize the stuff needed for your gadget to work. + + Don't forget to call the super of the base using: + super().__init__() + + """ self._instances = list() self._popups = list() def instance_created(self, obj, site): - """ TODO DOC """ + """ A new instance of the gadget has been created. + + When a gadget is placed in a container (a shelf, the desktop, etc..) + edgar automatically create a new edje object using the group + e/gadgets/name/main provided in the gadget edje file. + This function is called just after the creation of the object so + that you can fill it as required. + + The default implementation put the object in the _instances list, so + don't forget to call the super() function. + + Args: + obj: the created edje object + site: the place where the gadget has been created, can be one + of the E_GADCON_SITE_* definition. + + """ self._instances.append(obj) def instance_destroyed(self, obj): - """ TODO DOC """ + """ An instance of the gadget has been removed. + + This is called when a gadget is removed from a site. + You can use this function to cleanup your stuff relative to this + instance. + The edje object will be automatically deleted by edgar just after + this call, you dont need to delete it yourself. + + The default implementation remove the object in the _instances list, so + don't forget to call the super() function. + + Args: + obj: the edje object that will be deleted + + """ self._instances.remove(obj) def instance_orient(self, obj, generic, specific): - """ TODO DOC """ + """ The gadget need to be oriented. + + This function is needed to correctly orient the gadget, it will be + called once on gadget initialization and also when the user change the + orientation. + + Args: + obj: the edje object of the gadget + generic: The new orientation in a generic fashion, can be one of: + E_GADCON_ORIENT_[ FLOAT / HORIZ / VERT ] + specific: The new orientaion, can be one of: + E_GADCON_ORIENT_* + + """ pass def popup_created(self, obj): - """ TODO DOC """ + """ A new popup for the gadget has been created. + + Edgar automatically create the popup for the gadget, using the group + provided in the edje file (e/gadgets/name/popup). + Once the popup has been created this function is called so that you + can fill it's content as required. + + The default implementation put the object in the _popups list, so + don't forget to call the super() function. + + Args: + obj: the created edje object that you can fill + + """ self._popups.append(obj) def popup_destroyed(self, obj): - """ TODO DOC """ + """ The popup has been dismissed. + + When a popup id destroyed this function is called so that you can + clean your stuff related to this popup. + The edje object will be automatically deleted by edgar just after + this call, you dont need to delete it yourself. + + The default implementation remove the object in the _popups list, so + don't forget to call the super() function. + + Args: + obj: the popup edje object + + """ self._popups.remove(obj) -""" TODO DOC """ +""" E_Gadcon_Site """ E_GADCON_SITE_UNKNOWN = 0 E_GADCON_SITE_SHELF = 1 E_GADCON_SITE_DESKTOP = 2 E_GADCON_SITE_TOOLBAR = 3 E_GADCON_SITE_EFM_TOOLBAR = 4 -""" TODO DOC """ +""" E_Gadcon_Orient """ E_GADCON_ORIENT_FLOAT = 0 E_GADCON_ORIENT_HORIZ = 1 E_GADCON_ORIENT_VERT = 2 --
