summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKai Huuhko <kai.huuhko@gmail.com>2015-03-12 19:39:29 +0200
committerKai Huuhko <kai.huuhko@gmail.com>2015-03-12 19:39:29 +0200
commit4b9a44d2fc8ccff2efc8b5217890b95df8a9d135 (patch)
tree6926f5394407b2b1c958b1acb965bdf1268cfaeb
parentdd5b35ef8fc034ff7b23c708fa63e164b5aa2782 (diff)
Evas.Object: Add more documentation for size hints from C headers
-rw-r--r--efl/evas/efl.evas_object.pxi159
1 files changed, 113 insertions, 46 deletions
diff --git a/efl/evas/efl.evas_object.pxi b/efl/evas/efl.evas_object.pxi
index a38f7e1..b981854 100644
--- a/efl/evas/efl.evas_object.pxi
+++ b/efl/evas/efl.evas_object.pxi
@@ -1180,18 +1180,25 @@ cdef class Object(Eo):
1180 #################### 1180 ####################
1181 1181
1182 property size_hint_min: 1182 property size_hint_min:
1183 """Hint about minimum size. 1183 """Hints for an object's minimum size.
1184 1184
1185 This is not an enforcement, just a hint that can be used by 1185 This is not an enforcement, just a hint that can be used by
1186 other objects like Edje, boxes, tables and others. 1186 other objects like Edje, boxes, tables and others.
1187 1187
1188 Value 0 is disabled. 1188 Values ``0`` will be treated as unset hint components, when queried
1189 by managers.
1189 1190
1190 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS 1191 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS
1191 will be emitted. 1192 will be emitted.
1192 1193
1193 :type: (int **w**, int **h**) 1194 :type: (int **w**, int **h**)
1194 1195
1196 .. note::
1197
1198 Smart objects (such as elementary) can have their own size hint
1199 policy. So calling this API may or may not affect the size of smart
1200 objects.
1201
1195 """ 1202 """
1196 def __get__(self): 1203 def __get__(self):
1197 cdef int w, h 1204 cdef int w, h
@@ -1210,18 +1217,25 @@ cdef class Object(Eo):
1210 evas_object_size_hint_min_set(self.obj, w, h) 1217 evas_object_size_hint_min_set(self.obj, w, h)
1211 1218
1212 property size_hint_max: 1219 property size_hint_max:
1213 """Hint about maximum size. 1220 """The hints for an object's maximum size.
1214 1221
1215 This is not an enforcement, just a hint that can be used by 1222 This is not an enforcement, just a hint that can be used by other
1216 other objects like Edje, boxes, tables and others. 1223 objects like Edje, boxes, tables and others.
1217 1224
1218 Value -1 is disabled. 1225 Values ``-1`` will be treated as unset hint components, when queried by
1226 managers.
1219 1227
1220 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS 1228 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be
1221 will be emitted. 1229 emitted.
1222 1230
1223 :type: (int **w**, int **h**) 1231 :type: (int **w**, int **h**)
1224 1232
1233 .. note::
1234
1235 Smart objects(such as elementary) can have their own size hint
1236 policy. So calling this API may or may not affect the size of smart
1237 objects.
1238
1225 """ 1239 """
1226 def __get__(self): 1240 def __get__(self):
1227 cdef int w, h 1241 cdef int w, h
@@ -1246,7 +1260,9 @@ cdef class Object(Eo):
1246 used whenever appropriate. This mode can be used objects display mode 1260 used whenever appropriate. This mode can be used objects display mode
1247 like compress or expand. 1261 like compress or expand.
1248 1262
1249 :type: Evas_Display_Mode 1263 This can be used for objects display mode like compress or expand.
1264
1265 :type: :ref:`Evas_Display_Mode`
1250 1266
1251 """ 1267 """
1252 def __get__(self): 1268 def __get__(self):
@@ -1262,18 +1278,24 @@ cdef class Object(Eo):
1262 evas_object_size_hint_display_mode_set(self.obj, dispmode) 1278 evas_object_size_hint_display_mode_set(self.obj, dispmode)
1263 1279
1264 property size_hint_request: 1280 property size_hint_request:
1265 """Hint about request size. 1281 """The hints for an object's optimum size.
1266 1282
1267 This is not an enforcement, just a hint that can be used by 1283 This is not an enforcement, just a hint that can be used by other
1268 other objects like Edje, boxes, tables and others. 1284 objects like Edje, boxes, tables and others.
1269 1285
1270 Value 0 is disabled. 1286 Value 0 is disabled.
1271 1287
1272 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS 1288 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be
1273 will be emitted. 1289 emitted.
1274 1290
1275 :type: (int **w**, int **h**) 1291 :type: (int **w**, int **h**)
1276 1292
1293 .. note::
1294
1295 Smart objects(such as elementary) can have their own size hint
1296 policy. So calling this API may or may not affect the size of smart
1297 objects.
1298
1277 """ 1299 """
1278 def __get__(self): 1300 def __get__(self):
1279 cdef int w, h 1301 cdef int w, h
@@ -1292,17 +1314,27 @@ cdef class Object(Eo):
1292 evas_object_size_hint_request_set(self.obj, w, h) 1314 evas_object_size_hint_request_set(self.obj, w, h)
1293 1315
1294 property size_hint_aspect: 1316 property size_hint_aspect:
1295 """Hint about aspect. 1317 """The hints for an object's aspect ratio.
1296 1318
1297 This is not an enforcement, just a hint that can be used by 1319 This is not an enforcement, just a hint that can be used by other
1298 other objects like Edje, boxes, tables and others. 1320 objects like Edje, boxes, tables and others.
1299 1321
1300 Aspect EVAS_ASPECT_CONTROL_NONE is disabled. 1322 Aspect EVAS_ASPECT_CONTROL_NONE is disabled.
1301 1323
1302 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS 1324 If any of the given aspect ratio terms are ``0``, the object's
1303 will be emitted. 1325 container will ignore the aspect and scale the object to occupy the
1326 whole available area, for any given policy.
1327
1328 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be
1329 emitted.
1304 1330
1305 :type: (Evas_Aspect_Control **aspect**, int **w**, int **h**) 1331 :type: (:ref:`Evas_Aspect_Control` **aspect**, int **w**, int **h**)
1332
1333 .. note::
1334
1335 Smart objects (such as elementary) can have their own size hint
1336 policy. So calling this API may or may not affect the size of smart
1337 objects.
1306 1338
1307 """ 1339 """
1308 def __get__(self): 1340 def __get__(self):
@@ -1327,19 +1359,29 @@ cdef class Object(Eo):
1327 w, h) 1359 w, h)
1328 1360
1329 property size_hint_align: 1361 property size_hint_align:
1330 """Hint about alignment. 1362 """The hints for an object's alignment.
1331 1363
1332 This is not an enforcement, just a hint that can be used by 1364 This is not an enforcement, just a hint that can be used by other
1333 other objects like Edje, boxes, tables and others. 1365 objects like Edje, boxes, tables and others.
1334 1366
1335 Accepted values are in the 0.0 to 1.0 range, with the special value 1367 These are hints on how to align an object **inside the boundaries of a
1336 -1.0 (EVAS_HINT_FILL) used to specify "justify" or "fill" by some 1368 container/manager**. Accepted values are in the ``0.0`` to ``1.0``
1337 users. 1369 range, with the special value :attr:`EVAS_HINT_FILL` used to specify
1370 "justify" or "fill" by some users. In this case, maximum size hints
1371 should be enforced with higher priority, if they are set. Also, any
1372 padding hint set on objects should add up to the alignment space on the
1373 final scene composition.
1338 1374
1339 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS 1375 For the horizontal component, ``0.0`` means to the left, ``1.0`` means
1340 will be emitted. 1376 to the right. Analogously, for the vertical component, ``0.0`` to the
1377 top, ``1.0`` means to the bottom.
1378
1379 .. note:: Default alignment hint values are 0.5, for both axis.
1380
1381 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be
1382 emitted.
1341 1383
1342 :type: (double **x**, double **y**) 1384 :type: (float **x**, float **y**)
1343 1385
1344 .. seealso:: :ref:`evas-size-hints` 1386 .. seealso:: :ref:`evas-size-hints`
1345 1387
@@ -1357,7 +1399,7 @@ cdef class Object(Eo):
1357 cdef double x, y 1399 cdef double x, y
1358 evas_object_size_hint_align_get(self.obj, &x, &y) 1400 evas_object_size_hint_align_get(self.obj, &x, &y)
1359 return (x, y) 1401 return (x, y)
1360 def size_hint_align_set(self, float x, float y): 1402 def size_hint_align_set(self, double x, double y):
1361 evas_object_size_hint_align_set(self.obj, x, y) 1403 evas_object_size_hint_align_set(self.obj, x, y)
1362 1404
1363 property size_hint_fill: 1405 property size_hint_fill:
@@ -1368,7 +1410,7 @@ cdef class Object(Eo):
1368 exclusive to align). 1410 exclusive to align).
1369 This is **exactly** the same as using :attr:`size_hint_align` 1411 This is **exactly** the same as using :attr:`size_hint_align`
1370 1412
1371 :type: (double **x**, double **y**) 1413 :type: (float **x**, float **y**)
1372 1414
1373 .. seealso:: :ref:`evas-size-hints` 1415 .. seealso:: :ref:`evas-size-hints`
1374 1416
@@ -1388,21 +1430,36 @@ cdef class Object(Eo):
1388 cdef double x, y 1430 cdef double x, y
1389 evas_object_size_hint_fill_get(self.obj, &x, &y) 1431 evas_object_size_hint_fill_get(self.obj, &x, &y)
1390 return (x, y) 1432 return (x, y)
1391 def size_hint_fill_set(self, float x, float y): 1433 def size_hint_fill_set(self, double x, double y):
1392 evas_object_size_hint_fill_set(self.obj, x, y) 1434 evas_object_size_hint_fill_set(self.obj, x, y)
1393 1435
1394 property size_hint_weight: 1436 property size_hint_weight:
1395 """Hint about weight. 1437 """Hint about weight.
1396 1438
1397 This is not an enforcement, just a hint that can be used by 1439 This is not an enforcement, just a hint that can be used by other
1398 other objects like Edje, boxes, tables and others. 1440 objects like Edje, boxes, tables and others.
1399 1441
1400 Value 0.0 is disabled. 1442 This is a hint on how a container object should **resize** a given
1443 child within its area. Containers may adhere to the simpler logic of
1444 just expanding the child object's dimensions to fit its own (see the
1445 :attr:`EVAS_HINT_EXPAND` helper weight macro) or the complete one of
1446 taking each child's weight hint as real **weights** to how much of its
1447 size to allocate for them in each axis. A container is supposed to,
1448 after **normalizing** the weights of its children (with weight hints),
1449 distribute the space it has to layout them by those factors -- most
1450 weighted children get larger in this process than the least ones.
1401 1451
1402 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS 1452 Accepted values are zero or positive values. Some users might use this
1403 will be emitted. 1453 hint as a boolean, but some might consider it as a **proportion**, see
1454 documentation of possible users, which in Evas are the :class:`Box` and
1455 :class:`Table` smart objects.
1456
1457 .. note:: Default weight hint values are ``0.0``, for both axis.
1458
1459 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be
1460 emitted.
1404 1461
1405 :type: (double **x**, double **y**) 1462 :type: (float **x**, float **y**)
1406 1463
1407 .. seealso:: :ref:`evas-size-hints` 1464 .. seealso:: :ref:`evas-size-hints`
1408 1465
@@ -1420,7 +1477,7 @@ cdef class Object(Eo):
1420 cdef double x, y 1477 cdef double x, y
1421 evas_object_size_hint_weight_get(self.obj, &x, &y) 1478 evas_object_size_hint_weight_get(self.obj, &x, &y)
1422 return (x, y) 1479 return (x, y)
1423 def size_hint_weight_set(self, float x, float y): 1480 def size_hint_weight_set(self, double x, double y):
1424 evas_object_size_hint_weight_set(self.obj, x, y) 1481 evas_object_size_hint_weight_set(self.obj, x, y)
1425 1482
1426 property size_hint_expand: 1483 property size_hint_expand:
@@ -1430,7 +1487,7 @@ cdef class Object(Eo):
1430 that **weight** is also used for **expand** properties. 1487 that **weight** is also used for **expand** properties.
1431 This is **exactly** the same as using :attr:`size_hint_weight` 1488 This is **exactly** the same as using :attr:`size_hint_weight`
1432 1489
1433 :type: (double **x**, double **y**) 1490 :type: (float **x**, float **y**)
1434 1491
1435 .. seealso:: :ref:`evas-size-hints` 1492 .. seealso:: :ref:`evas-size-hints`
1436 1493
@@ -1450,20 +1507,30 @@ cdef class Object(Eo):
1450 cdef double x, y 1507 cdef double x, y
1451 evas_object_size_hint_expand_get(self.obj, &x, &y) 1508 evas_object_size_hint_expand_get(self.obj, &x, &y)
1452 return (x, y) 1509 return (x, y)
1453 def size_hint_expand_set(self, float x, float y): 1510 def size_hint_expand_set(self, double x, double y):
1454 evas_object_size_hint_expand_set(self.obj, x, y) 1511 evas_object_size_hint_expand_set(self.obj, x, y)
1455 1512
1456 property size_hint_padding: 1513 property size_hint_padding:
1457 """Hint about padding. 1514 """The hints for an object's padding space.
1458 1515
1459 This is not an enforcement, just a hint that can be used by 1516 This is not an enforcement, just a hint that can be used by other
1460 other objects like Edje, boxes, tables and others. 1517 objects like Edje, boxes, tables and others.
1461 1518
1462 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS 1519 Padding is extra space an object takes on each of its delimiting
1463 will be emitted. 1520 rectangle sides, in canvas units. This space will be rendered
1521 transparent.
1522
1523 When this property changes, EVAS_CALLBACK_CHANGED_SIZE_HINTS will be
1524 emitted.
1464 1525
1465 :type: (int **l**, int **r**, int **t**, int **b**) 1526 :type: (int **l**, int **r**, int **t**, int **b**)
1466 1527
1528 .. note::
1529
1530 Smart objects(such as elementary) can have their own size hint
1531 policy. So calling this API may or may not affect the size of smart
1532 objects.
1533
1467 """ 1534 """
1468 def __get__(self): 1535 def __get__(self):
1469 cdef int l, r, t, b 1536 cdef int l, r, t, b