Evas.Object: New convenience props, size_hint_expand and size_hint_fill

Also added some docs for size hints usage

doc/evas/class-object.rst

@@ -3,32 +3,5 @@
 :class:`efl.evas.Object` Class
 ==============================
 
-.. _Evas_Keys:
-
-Key Input Functions
-===================
-
-Functions which feed key events to the canvas.
-
-As explained in :ref:`evas_main_intro_not_evas`, Evas is **not** aware of input
-systems at all. Then, the user, if using it crudely (evas_new()),
-will have to feed it with input events, so that it can react
-somehow. If, however, the user creates a canvas by means of the
-Ecore_Evas wrapper, it will automatically bind the chosen display
-engine's input events to the canvas, for you.
-
-This group presents the functions dealing with the feeding of key
-events to the canvas. On most of them, one has to reference a given
-key by a name (``keyname`` argument). Those are
-**platform dependent** symbolic names for the keys. Sometimes
-you'll get the right ``keyname`` by simply using an ASCII
-value of the key name, but it won't be like that always.
-
-Typical platforms are Linux frame buffer (Ecore_FB) and X server
-(Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
-to your display engine's documentation when using evas through an
-Ecore helper wrapper when you need the ``keyname``'s.
-
-
 .. autoclass:: efl.evas.Object
     :inherited-members:

doc/evas/evas.rst

@@ -167,6 +167,56 @@ display logic, but does very little high-level logic such as
 scrollbars, sliders, push buttons etc.
 
 
+.. _evas-size-hints:
+
+Size Hints
+----------
+
+Evas :class:`Object` may carry hints, so that another object that acts as a
+manager may know how to properly position and resize its subordinate objects.
+
+The Size Hints provide a common interface that is recommended as the
+protocol for such information.
+
+For example, box objects use alignment hints to align its lines/columns
+inside its container, padding hints to set the padding between each
+individual child, etc.
+
+Size Hints are controlled using various :class:`Object` properties:
+
+ * :attr:`~Object.size_hint_weight` (also called :attr:`~Object.size_hint_expand`)
+ * :attr:`~Object.size_hint_align` (also called :attr:`~Object.size_hint_fill`)
+ * :attr:`~Object.size_hint_min`
+ * :attr:`~Object.size_hint_max`
+ * :attr:`~Object.size_hint_aspect`
+ * :attr:`~Object.size_hint_padding`
+ * :attr:`~Object.size_hint_display_mode`
+ * :attr:`~Object.size_hint_request`
+
+The **weight** and the **align** are quite special, they are also used to
+express the **expand** and the **fill** property of the object. For this
+reason some helper are provided:
+
+ * ``EVAS_HINT_EXPAND`` = -1.0 (to be used with **weight** or **expand**)
+ * ``EVAS_HINT_FILL`` = 1.0 (to be used with **align** or **fill**)
+
+And also:
+
+ * ``EXPAND_BOTH``  = EVAS_HINT_EXPAND, EVAS_HINT_EXPAND
+ * ``EXPAND_HORIZ`` = EVAS_HINT_EXPAND, 0.0
+ * ``EXPAND_VERT``  = 0.0, EVAS_HINT_EXPAND
+ * ``FILL_BOTH``  = EVAS_HINT_FILL, EVAS_HINT_FILL
+ * ``FILL_HORIZ`` = EVAS_HINT_FILL, 0.5
+ * ``FILL_VERT``  = 0.5, EVAS_HINT_FILL
+
+You can also build your own as needed, for example you can define:
+
+ * ``FILL_AND_ALIGN_TOP`` = EVAS_HINT_FILL, 0.0
+ * ``FILL_AND_ALIGN_RIGHT`` = 1.0, EVAS_HINT_FILL
+
+and so on...
+
+
 Next Steps
 ----------
 

efl/evas/efl.evas_object.pxi

@@ -851,15 +851,17 @@ cdef class Object(Eo):
         This is not an enforcement, just a hint that can be used by
         other objects like Edje, boxes, tables and others.
 
-        Accepted values are in the 0.0 to 1.0 range, with the special
-        value -1.0 used to specify"justify" or "fill" by some users.
-        See documentation of possible users.
+        Accepted values are in the 0.0 to 1.0 range, with the special value
+        -1.0 (EVAS_HINT_FILL) used to specify "justify" or "fill" by some
+        users.
 
         When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS
         will be emitted.
 
         :type: (double **x**, double **y**)
 
+        .. seealso:: :ref:`evas-size-hints`
+
         """
         def __get__(self):
             cdef double x, y
@@ -877,6 +879,37 @@ cdef class Object(Eo):
     def size_hint_align_set(self, float x, float y):
         evas_object_size_hint_align_set(self.obj, x, y)
 
+    property size_hint_fill:
+        """Hint about fill.
+
+        This is just a convenience property to make it easier to understand
+        that **align** is also used for **fill** properties (as fill is mutually
+        exclusive to align).
+        This is **exactly** the same as using :attr:`size_hint_align`
+
+        :type: (double **x**, double **y**)
+
+        .. seealso:: :ref:`evas-size-hints`
+
+        .. versionadded:: 1.13
+
+        """
+        def __get__(self):
+            cdef double x, y
+            evas_object_size_hint_fill_get(self.obj, &x, &y)
+            return (x, y)
+
+        def __set__(self, spec):
+            x, y = spec
+            evas_object_size_hint_fill_set(self.obj, x, y)
+
+    def size_hint_fill_get(self):
+        cdef double x, y
+        evas_object_size_hint_fill_get(self.obj, &x, &y)
+        return (x, y)
+    def size_hint_fill_set(self, float x, float y):
+        evas_object_size_hint_fill_set(self.obj, x, y)
+
     property size_hint_weight:
         """Hint about weight.
 
@@ -890,6 +923,8 @@ cdef class Object(Eo):
 
         :type: (double **x**, double **y**)
 
+        .. seealso:: :ref:`evas-size-hints`
+
         """
         def __get__(self):
             cdef double x, y
@@ -907,6 +942,36 @@ cdef class Object(Eo):
     def size_hint_weight_set(self, float x, float y):
         evas_object_size_hint_weight_set(self.obj, x, y)
 
+    property size_hint_expand:
+        """Hint about expand.
+
+        This is just a convenience property to make it easier to understand
+        that **weight** is also used for **expand** properties.
+        This is **exactly** the same as using :attr:`size_hint_weight`
+
+        :type: (double **x**, double **y**)
+
+        .. seealso:: :ref:`evas-size-hints`
+
+        .. versionadded:: 1.13
+
+        """
+        def __get__(self):
+            cdef double x, y
+            evas_object_size_hint_expand_get(self.obj, &x, &y)
+            return (x, y)
+
+        def __set__(self, spec):
+            x, y = spec
+            evas_object_size_hint_expand_set(self.obj, x, y)
+
+    def size_hint_expand_get(self):
+        cdef double x, y
+        evas_object_size_hint_expand_get(self.obj, &x, &y)
+        return (x, y)
+    def size_hint_expand_set(self, float x, float y):
+        evas_object_size_hint_expand_set(self.obj, x, y)
+
     property size_hint_padding:
         """Hint about padding.
 

include/efl.evas.pxd

@@ -702,8 +702,12 @@ cdef extern from "Evas.h":
     void evas_object_size_hint_aspect_set(Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h)
     void evas_object_size_hint_align_get(const Evas_Object *obj, double *x, double *y)
     void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y)
+    void evas_object_size_hint_fill_get(const Evas_Object *obj, double *x, double *y)
+    void evas_object_size_hint_fill_set(Evas_Object *obj, double x, double y)
     void evas_object_size_hint_weight_get(const Evas_Object *obj, double *x, double *y)
     void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y)
+    void evas_object_size_hint_expand_get(const Evas_Object *obj, double *x, double *y)
+    void evas_object_size_hint_expand_set(Evas_Object *obj, double x, double y)
     void evas_object_size_hint_padding_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b)
     void evas_object_size_hint_padding_set(Evas_Object *obj, Evas_Coord l, Evas_Coord r, Evas_Coord t, Evas_Coord b)