src/lib/elm_button.h

   1    /**
   2     * @defgroup Button Button
   3     *
   4     * @image html img/widget/button/preview-00.png
   5     * @image latex img/widget/button/preview-00.eps
   6     * @image html img/widget/button/preview-01.png
   7     * @image latex img/widget/button/preview-01.eps
   8     * @image html img/widget/button/preview-02.png
   9     * @image latex img/widget/button/preview-02.eps
  10     *
  11     * This is a push-button. Press it and run some function. It can contain
  12     * a simple label and icon object and it also has an autorepeat feature.
  13     *
  14     * This widgets emits the following signals:
  15     * @li "clicked": the user clicked the button (press/release).
  16     * @li "repeated": the user pressed the button without releasing it.
  17     * @li "pressed": button was pressed.
  18     * @li "unpressed": button was released after being pressed.
  19     * In all three cases, the @c event parameter of the callback will be
  20     * @c NULL.
  21     *
  22     * Also, defined in the default theme, the button has the following styles
  23     * available:
  24     * @li default: a normal button.
  25     * @li anchor: Like default, but the button fades away when the mouse is not
  26     * over it, leaving only the text or icon.
  27     * @li hoversel_vertical: Internally used by @ref Hoversel to give a
  28     * continuous look across its options.
  29     * @li hoversel_vertical_entry: Another internal for @ref Hoversel.
  30     *
  31     * Default contents parts of the button widget that you can use for are:
  32     * @li "icon" - An icon of the button
  33     *
  34     * Default text parts of the button widget that you can use for are:
  35     * @li "default" - Label of the button
  36     *
  37     * Follow through a complete example @ref button_example_01 "here".
  38     * @{
  39     */
  40
  41    /**
  42     * Add a new button to the parent's canvas
  43     *
  44     * @param parent The parent object
  45     * @return The new object or NULL if it cannot be created
  46     */
  47    EAPI Evas_Object *elm_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  48
  49    /**
  50     * Set the label used in the button
  51     *
  52     * The passed @p label can be NULL to clean any existing text in it and
  53     * leave the button as an icon only object.
  54     *
  55     * @param obj The button object
  56     * @param label The text will be written on the button
  57     * @deprecated use elm_object_text_set() instead.
  58     */
  59    EINA_DEPRECATED EAPI void         elm_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
  60
  61    /**
  62     * Get the label set for the button
  63     *
  64     * The string returned is an internal pointer and should not be freed or
  65     * altered. It will also become invalid when the button is destroyed.
  66     * The string returned, if not NULL, is a stringshare, so if you need to
  67     * keep it around even after the button is destroyed, you can use
  68     * eina_stringshare_ref().
  69     *
  70     * @param obj The button object
  71     * @return The text set to the label, or NULL if nothing is set
  72     * @deprecated use elm_object_text_set() instead.
  73     */
  74    EINA_DEPRECATED EAPI const char  *elm_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  75
  76    /**
  77     * Set the icon used for the button
  78     *
  79     * Setting a new icon will delete any other that was previously set, making
  80     * any reference to them invalid. If you need to maintain the previous
  81     * object alive, unset it first with elm_button_icon_unset().
  82     *
  83     * @param obj The button object
  84     * @param icon The icon object for the button
  85     * @deprecated use elm_object_part_content_set() instead.
  86     */
  87    EINA_DEPRECATED EAPI void         elm_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
  88
  89    /**
  90     * Get the icon used for the button
  91     *
  92     * Return the icon object which is set for this widget. If the button is
  93     * destroyed or another icon is set, the returned object will be deleted
  94     * and any reference to it will be invalid.
  95     *
  96     * @param obj The button object
  97     * @return The icon object that is being used
  98     *
  99     * @deprecated use elm_object_part_content_get() instead
 100     */
 101    EINA_DEPRECATED EAPI Evas_Object *elm_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 102
 103    /**
 104     * Remove the icon set without deleting it and return the object
 105     *
 106     * This function drops the reference the button holds of the icon object
 107     * and returns this last object. It is used in case you want to remove any
 108     * icon, or set another one, without deleting the actual object. The button
 109     * will be left without an icon set.
 110     *
 111     * @param obj The button object
 112     * @return The icon object that was being used
 113     * @deprecated use elm_object_part_content_unset() instead.
 114     */
 115    EINA_DEPRECATED EAPI Evas_Object *elm_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 116
 117    /**
 118     * Turn on/off the autorepeat event generated when the button is kept pressed
 119     *
 120     * When off, no autorepeat is performed and buttons emit a normal @c clicked
 121     * signal when they are clicked.
 122     *
 123     * When on, keeping a button pressed will continuously emit a @c repeated
 124     * signal until the button is released. The time it takes until it starts
 125     * emitting the signal is given by
 126     * elm_button_autorepeat_initial_timeout_set(), and the time between each
 127     * new emission by elm_button_autorepeat_gap_timeout_set().
 128     *
 129     * @param obj The button object
 130     * @param on  A bool to turn on/off the event
 131     */
 132    EAPI void         elm_button_autorepeat_set(Evas_Object *obj, Eina_Bool on) EINA_ARG_NONNULL(1);
 133
 134    /**
 135     * Get whether the autorepeat feature is enabled
 136     *
 137     * @param obj The button object
 138     * @return EINA_TRUE if autorepeat is on, EINA_FALSE otherwise
 139     *
 140     * @see elm_button_autorepeat_set()
 141     */
 142    EAPI Eina_Bool    elm_button_autorepeat_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 143
 144    /**
 145     * Set the initial timeout before the autorepeat event is generated
 146     *
 147     * Sets the timeout, in seconds, since the button is pressed until the
 148     * first @c repeated signal is emitted. If @p t is 0.0 or less, there
 149     * won't be any delay and the even will be fired the moment the button is
 150     * pressed.
 151     *
 152     * @param obj The button object
 153     * @param t   Timeout in seconds
 154     *
 155     * @see elm_button_autorepeat_set()
 156     * @see elm_button_autorepeat_gap_timeout_set()
 157     */
 158    EAPI void         elm_button_autorepeat_initial_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
 159
 160    /**
 161     * Get the initial timeout before the autorepeat event is generated
 162     *
 163     * @param obj The button object
 164     * @return Timeout in seconds
 165     *
 166     * @see elm_button_autorepeat_initial_timeout_set()
 167     */
 168    EAPI double       elm_button_autorepeat_initial_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 169
 170    /**
 171     * Set the interval between each generated autorepeat event
 172     *
 173     * After the first @c repeated event is fired, all subsequent ones will
 174     * follow after a delay of @p t seconds for each.
 175     *
 176     * @param obj The button object
 177     * @param t   Interval in seconds
 178     *
 179     * @see elm_button_autorepeat_initial_timeout_set()
 180     */
 181    EAPI void         elm_button_autorepeat_gap_timeout_set(Evas_Object *obj, double t) EINA_ARG_NONNULL(1);
 182
 183    /**
 184     * Get the interval between each generated autorepeat event
 185     *
 186     * @param obj The button object
 187     * @return Interval in seconds
 188     */
 189    EAPI double       elm_button_autorepeat_gap_timeout_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 190
 191    /**
 192     * @}
 193     */
 194