src/lib/elm_panes.h

   1 /**
   2  * @defgroup Panes Panes
   3  * @ingroup Elementary
   4  *
   5  * @image html panes_inheritance_tree.png
   6  * @image latex panes_inheritance_tree.eps
   7  *
   8  * @image html img/widget/panes/preview-00.png
   9  * @image latex img/widget/panes/preview-00.eps width=\textwidth
  10  *
  11  * @image html img/panes.png
  12  * @image latex img/panes.eps width=\textwidth
  13  *
  14  * The panes widget adds a draggable bar between two contents. When dragged
  15  * this bar will resize contents' size.
  16  *
  17  * Panes can be displayed vertically or horizontally, and contents
  18  * size proportion can be customized (homogeneous by default).
  19  *
  20  * This widget inherits from the @ref Layout one, so that all the
  21  * functions acting on it also work for panes objects.
  22  *
  23  * This widget emits the following signals, besides the ones sent from
  24  * @ref Layout:
  25  * - @c "press" - The panes has been pressed (button wasn't released yet).
  26  * - @c "unpressed" - The panes was released after being pressed.
  27  * - @c "clicked" - The panes has been clicked>
  28  * - @c "clicked,double" - The panes has been double clicked
  29  *
  30  * Available styles for it:
  31  * - @c "default"
  32  *
  33  * Default content parts of the panes widget that you can use are:
  34  * @li "left" - A leftside content of the panes
  35  * @li "right" - A rightside content of the panes
  36  *
  37  * If panes are displayed vertically, left content will be displayed on
  38  * top.
  39  *
  40  * Supported elm_object common APIs.
  41  * @li @ref elm_object_part_content_set
  42  * @li @ref elm_object_part_content_get
  43  * @li @ref elm_object_part_content_unset
  44  *
  45  * Here is an example on its usage:
  46  * @li @ref panes_example
  47  */
  48
  49 /**
  50  * @addtogroup Panes
  51  * @{
  52  */
  53
  54 /**
  55  * Add a new panes widget to the given parent Elementary
  56  * (container) object.
  57  *
  58  * @param parent The parent object.
  59  * @return a new panes widget handle or @c NULL, on errors.
  60  *
  61  * This function inserts a new panes widget on the canvas.
  62  *
  63  * @ingroup Panes
  64  */
  65 EAPI Evas_Object                 *elm_panes_add(Evas_Object *parent);
  66
  67 /**
  68  * Set whether the left and right panes resize homogeneously or not.
  69  *
  70  * @param obj The panes object.
  71  * @param fixed Use @c EINA_TRUE to make @p obj to be
  72  * resize the left and right panes @b homogeneously.
  73  * Use @c EINA_FALSE to make use of the values specified in
  74  * elm_panes_content_left_size_set() and
  75  * elm_panes_content_right_size_set()
  76  * to resize the left and right panes.
  77  *
  78  * By default panes are resized homogeneously.
  79  *
  80  * @see elm_panes_fixed_get()
  81  * @see elm_panes_content_left_size_set()
  82  * @see elm_panes_content_right_size_set()
  83  *
  84  * @ingroup Panes
  85  */
  86 EAPI void                         elm_panes_fixed_set(Evas_Object *obj, Eina_Bool fixed);
  87
  88 /**
  89  * Retrieve the resize mode for the panes of a given panes widget.
  90  *
  91  * @param obj The panes object.
  92  * @return @c EINA_TRUE, if @p obj is set to be resized @b homogeneously,
  93  *
  94  * @see elm_panes_fixed_set() for more details.
  95  * @see elm_panes_content_left_size_get()
  96  * @see elm_panes_content_right_size_get()
  97  *
  98  * @ingroup Panes
  99  */
 100 EAPI Eina_Bool                    elm_panes_fixed_get(const Evas_Object *obj);
 101
 102 /**
 103  * Get the size proportion of panes widget's left side.
 104  *
 105  * @param obj The panes object.
 106  * @return float value between 0.0 and 1.0 representing size proportion
 107  * of left side.
 108  *
 109  * @see elm_panes_content_left_size_set() for more details.
 110  *
 111  * @ingroup Panes
 112  */
 113 EAPI double                       elm_panes_content_left_size_get(const Evas_Object *obj);
 114
 115 /**
 116  * Set the size proportion of panes widget's left side.
 117  *
 118  * @param obj The panes object.
 119  * @param size Value between 0.0 and 1.0 representing size proportion
 120  * of left side.
 121  *
 122  * By default it's homogeneous, i.e., both sides have the same size.
 123  *
 124  * If something different is required, it can be set with this function.
 125  * For example, if the left content should be displayed over
 126  * 75% of the panes size, @p size should be passed as @c 0.75.
 127  * This way, right content will be resized to 25% of panes size.
 128  *
 129  * If displayed vertically, left content is displayed at top, and
 130  * right content at bottom.
 131  *
 132  * @note This proportion will change when user drags the panes bar.
 133  *
 134  * @see elm_panes_content_left_size_get()
 135  *
 136  * @ingroup Panes
 137  */
 138 EAPI void                         elm_panes_content_left_size_set(Evas_Object *obj, double size);
 139
 140 /**
 141  * Get the size proportion of panes widget's right side.
 142  *
 143  * @param obj The panes object.
 144  * @return float value between 0.0 and 1.0 representing size proportion
 145  * of right side.
 146  *
 147  * @see elm_panes_content_right_size_set() for more details.
 148  *
 149  * @ingroup Panes
 150  */
 151 EAPI double                       elm_panes_content_right_size_get(const Evas_Object *obj);
 152
 153 /**
 154  * Set the size proportion of panes widget's right side.
 155  *
 156  * @param obj The panes object.
 157  * @param size Value between 0.0 and 1.0 representing size proportion
 158  * of right side.
 159  *
 160  * By default it's homogeneous, i.e., both sides have the same size.
 161  *
 162  * If something different is required, it can be set with this function.
 163  * For example, if the right content should be displayed over
 164  * 75% of the panes size, @p size should be passed as @c 0.75.
 165  * This way, left content will be resized to 25% of panes size.
 166  *
 167  * If displayed vertically, left content is displayed at top, and
 168  * right content at bottom.
 169  *
 170  * @note This proportion will change when user drags the panes bar.
 171  *
 172  * @see elm_panes_content_right_size_get()
 173  *
 174  * @ingroup Panes
 175  */
 176 EAPI void                         elm_panes_content_right_size_set(Evas_Object *obj, double size);
 177
 178
 179 /**
 180  * Set the orientation of a given panes widget.
 181  *
 182  * @param obj The panes object.
 183  * @param horizontal Use @c EINA_TRUE to make @p obj to be
 184  * @b horizontal, @c EINA_FALSE to make it @b vertical.
 185  *
 186  * Use this function to change how your panes is to be
 187  * disposed: vertically or horizontally.
 188  *
 189  * By default it's displayed horizontally.
 190  *
 191  * @see elm_panes_horizontal_get()
 192  *
 193  * @ingroup Panes
 194  */
 195 EAPI void                         elm_panes_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 196
 197 /**
 198  * Retrieve the orientation of a given panes widget.
 199  *
 200  * @param obj The panes object.
 201  * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
 202  * @c EINA_FALSE if it's @b vertical (and on errors).
 203  *
 204  * @see elm_panes_horizontal_set() for more details.
 205  *
 206  * @ingroup Panes
 207  */
 208 EAPI Eina_Bool                    elm_panes_horizontal_get(const Evas_Object *obj);
 209
 210 /**
 211  * @}
 212  */