path: root/src/lib/elementary/efl_ui_widget.eo

function @beta Efl.Ui.Scrollable_On_Show_Region {
   [[Function pointer for on show region hook]]
   params {
      @in obj: Efl.Canvas.Object; [[Canvas object]]
      @in region: Eina.Rect; [[Showed region]]
   }
};

struct Efl.Ui.Widget_Focus_State {
   [[All relevant fields needed for the current state of focus registration]]
   manager : Efl.Ui.Focus.Manager; [[The manager where the widget is registered in]]
   parent : Efl.Ui.Focus.Object; [[The parent the widget is using as logical parent]]
   logical : bool; [[$true if this is registered as logical currently]]
}

abstract Efl.Ui.Widget extends Efl.Canvas.Group implements Efl.Access.Object,
                        Efl.Access.Component, Efl.Part, Efl.Ui.Focus.Object,
                        Efl.Ui.L10n,
                        Efl.Ui.Selection, Efl.Ui.Dnd,
                        Efl.Ui.Property_Bind, Efl.Ui.View
{
   [[Efl UI widget abstract class]]
   //eo_prefix: efl_ui_widget;
   event_prefix: efl_ui_widget;
   data: Efl_Ui_Widget_Data;
   methods {
      @property cursor @beta {
         [[The cursor to be shown when mouse is over the object

           This is the cursor that will be displayed when mouse is over the
           object. The object can have only one cursor set to it so if
           @.cursor.set is called twice for an object, the previous set
           will be unset.

           If using X cursors, a definition of all the valid cursor names
           is listed on Elementary_Cursors.h. If an invalid name is set
           the default cursor will be used.
         ]]
         set {
            [[Sets or unsets the current cursor.

              If $cursor is $null this function will reset the cursor
              to the default one.
            ]]
            return: bool; [[$true if successful.]]
         }
         get {
            [[Returns the current cursor name.]]
         }
         values {
            cursor: string @nullable; [[The cursor name, defined either
                                        by the display system or the theme.]]
         }
      }
      @property cursor_style @beta {
         [[A different style for the cursor.

           This only makes sense if theme cursors are used.
           The cursor should be set with @.cursor.set first before
           setting its style with this property.
         ]]
         set {
            [[Sets a style for the current cursor. Call after @.cursor.set.]]
            return: bool; [[$true if successful.]]
         }
         get {
            [[Returns the current cursor style name.]]
         }
         values {
            style: string; [[A specific style to use, eg. default,
                             transparent, ....]]
         }
      }
      @property cursor_theme_search_enabled @beta {
         [[Whether the cursor may be looked in the theme or not.

           If $false, the cursor may only come from the render engine,
           i.e. from the display manager.
         ]]
         set {
            [[Enables or disables theme cursors.]]
            return: bool; [[$true if successful.]]
         }
         get {
            [[Returns the current state of theme cursors search.]]
         }
         values {
            allow: bool(true); [[Whether to use theme cursors.]]
         }
      }
      @property resize_object @protected {
         [[This is the internal canvas object managed by a widget.

           This property is protected as it is meant for widget implementations
           only, to set and access the internal canvas object. Do use this
           function unless you're implementing a widget.
         ]]
         set {
            [[Sets the new resize object for this widget.]]
         }
         values {
            sobj: Efl.Canvas.Object @nullable;
               [[A canvas object (often a @Efl.Canvas.Layout object).]]
         }
      }
      @property disabled {
         [[Whether the widget is enabled (accepts and reacts to user inputs).

           The property works counted, this means, whenever n-caller set the value to $true, n-caller have to set it to $false in order to get it out of the disabled state again.

           Each widget may handle the disabled state differently, but overall
           disabled widgets shall not respond to any input events. This is
           $false by default, meaning the widget is enabled.
         ]]
         set {
            [[Enables or disables this widget.

              Disabling a widget will disable all its children recursively,
              but only this widget will be marked as disabled internally.
            ]]
         }
         get {
            [[Returns whether the widget is disabled.

              This will return $true if any widget in the parent hierarchy
              is disabled. Re-enabling that parent may in turn change the
              disabled state of this widget.
            ]]
         }
         values {
            disabled: bool(false); [[$true if the widget is disabled.]]
         }
      }
      @property style {
         [[The widget style to use.

           Styles define different look and feel for widgets, and may provide
           different parts for layout-based widgets. Styles vary from widget
           to widget and may be defined by other themes by means of extensions
           and overlays.

           The style can only be set before @Efl.Object.finalize, which means
           at construction time of the object (inside $efl_add in C).
         ]]
         set @protected {
            [[Can only be called during construction, before finalize.]]
            return: Eina.Error;
               [[Whether the style was successfully applied or not, see
                 the values of Efl.Ui.Theme.Apply_Error for more information.]]
         }
         get {
            [[Returns the current style of a widget.]]
         }
         values {
            style: string;
               [[Name of the style to use. Refer to each widget's documentation
                 for the available style names, or to the themes in use.]]
         }
      }
      widget_input_event_handler @protected {
         [[Virtual function handling input events on the widget.

           This method should return $true if the event has been processed.
           Only key down, key up and pointer wheel events will be propagated
           through this function.

           It is common for the event to be also marked as processed as in
           @Efl.Input.Event.processed, if this operation was successful. This
           makes sure other widgets will not also process this input event.
         ]]
         params {
            @cref eo_event: Efl.Event;
               [[EO event struct with an Efl.Input.Event as info.]]
            @in source: Efl.Canvas.Object;
               [[Source object where the event originated. Often same as this.]]
         }
         return: bool; [[$true on success, $false otherwise]]
      }
      // FIXME: focus_allow? can_focus? focusable?
      @property focus_allow {
         [[The ability for a widget to be focused.

           Unfocusable objects do nothing when programmatically focused. The
           nearest focusable parent object the one really getting focus. Also,
           when they receive mouse input, they will get the event, but not take
           away the focus from where it was previously.

           Note: Objects which are meant to be interacted with by input events
           are created able to be focused, by default. All the others are not.

           This property's default value depends on the widget (eg. a box is
           not focusable, but a button is).
         ]]
         set {
         }
         get {
         }
         values {
            can_focus: bool; [[Whether the object is focusable.]]
         }
      }
      @property widget_parent @protected {
         [[The internal parent of this widget.

           @Efl.Ui.Widget objects have a parent hierarchy that may differ slightly
           from their @Efl.Object or @Efl.Canvas.Object hierarchy. This is
           meant for internal handling.
         ]]
         set {
         }
         get {
         }
         values {
            parent: Efl.Ui.Widget @nullable; [[Widget parent object]]
         }
      }

      /* Accessibility */
      @property access_info @beta {
         [[Accessibility information.

           This is a replacement string to be read by the accessibility
           text-to-speech engine, if accessibility is enabled by configuration.
           This will take precedence over the default text for this object,
           which means for instance that the label of a button won't be read
           out loud, instead $txt will be read out.
         ]]
         values {
            txt: string @nullable; [[Accessibility text description.]]
         }
      }
      on_access_activate @protected @beta {
         [[Hook function called when widget is activated through accessibility.

           This meant to be overridden by subclasses to support accessibility.
           This is an unstable API.
         ]]
         params {
            @in act: Efl.Ui.Activate; [[Type of activation.]]
         }
         return: bool; [[$true on success, $false otherwise]]
      }
      on_access_update @protected @beta {
         [[Hook function called when accessibility is changed on the widget.

           This meant to be overridden by subclasses to support accessibility.
           This is an unstable API.
         ]]
         params {
            @in enable: bool; [[$true if accessibility is enabled.]]
         }
      }

      /* Internal hooks. */
      widget_sub_object_add @protected {
         [[Virtual function customizing sub objects being added.

           When a widget is added as a sub-object of another widget (like list
           elements inside a list container, for example) some of its properties
           are automatically adapted to the parent's current values (like focus,
           access, theme, scale, mirror, scrollable child get, translate,
           display mode set, tree dump).
           Override this method if you want to customize differently sub-objects
           being added to this object.

           Sub objects can be any canvas object, not necessarily widgets.

           See also @.widget_parent.
         ]]
         params {
            @in sub_obj: Efl.Canvas.Object;
               [[Sub object to be added. Not necessarily a widget itself.]]
         }
         return: bool; [[Indicates if the operation succeeded.]]
      }
      widget_sub_object_del @protected {
         [[Virtual function customizing sub objects being removed.

           When a widget is removed as a sub-object from another widget
           (@Efl.Pack.unpack, @Efl.Content.content_unset, for example) some of
           its properties are automatically adjusted.(like focus, access, tree dump)
           Override this method if you want to customize differently sub-objects
           being removed to this object.

           Sub objects can be any canvas object, not necessarily widgets.

           See also @.widget_parent and @.widget_sub_object_add.
         ]]
         params {
            @in sub_obj: Efl.Canvas.Object;
               [[Sub object to be removed. Should be a child of this widget.]]
         }
         return: bool; [[Indicates if the operation succeeded.]]
      }
      theme_apply @protected {
         [[Virtual function called when the widget needs to re-apply its theme.

           This may be called when the object is first created, or whenever
           the widget is modified in any way that may require a reload of the
           theme. This may include but is not limited to scale, theme, or
           mirrored mode changes.

           Note: even widgets not based on layouts may override this method
           to handle widget updates (scale, mirrored mode, etc...).
         ]]
         return: Eina.Error; [[Indicates success, and if the current
                                       theme or default theme was used.]]
      }

      /* FIXME: Scroll API. Not sure how those APIs should be exposed with
       * the new scrollable API. */
      scroll_hold_push @beta {
         [[Push scroll hold]]
      }
      scroll_hold_pop @beta {
         [[Pop scroller hold]]
      }
      scroll_freeze_push @beta {
         [[Push scroller freeze]]
      }
      scroll_freeze_pop @beta {
         [[Pop scroller freeze]]
      }

      /* Region of interest */
      @property interest_region @protected {
         [[Region of interest inside this widget, that should be given
           priority to be visible inside a scroller.

           When this widget or one of its subwidgets is given focus, this
           region should be shown, which means any parent scroller should
           attempt to display the given area of this widget. For instance, an
           entry given focus should scroll to show the text cursor if that
           cursor moves. In this example, this region defines the relative
           geometry of the cursor within the widget.

           Note: The region is relative to the top-left corner of the widget,
           i.e. X,Y start from 0,0 to indicate the top-left corner of the
           widget. W,H must be greater or equal to 1 for this region to be
           taken into account, otherwise it is ignored.
         ]]
         get {
         }
         values {
            region: Eina.Rect;
               [[The relative region to show. If width or height is <= 0 it
                 will be ignored, and no action will be taken.]]
         }
      }
      /* Focus highlight (visual focus rectangle) properties */
      @property focus_highlight_geometry @protected {
         [[The rectangle region to be highlighted on focus.

           This is a rectangle region where the focus highlight should be
           displayed.
         ]]
         get {
            [[This is a read-only property.]]
         }
         values {
            region: Eina.Rect; [[The rectangle area.]]
         }
      }
      @property focus_move_policy @beta {
         [[The widget's focus move policy.]]
         values {
            policy: Efl.Ui.Focus.Move_Policy; [[Focus move policy]]
         }
      }
      @property focus_move_policy_automatic @beta {
         [[Control the widget's focus_move_policy mode setting.

           @since 1.18]]
         values {
            automatic: bool; [[$true to follow system focus move policy change,
                               $false otherwise]]
         }
      }
      focus_state_apply @protected {
         [[Apply a new focus state on the widget.

          This method is called internally by @Efl.Ui.Widget. Override it to change how a widget interacts with its focus manager.
          If a widget desires to change the applied configuration, it has to modify $configured_state in addition to any internal changes.

          The default implementation (when this method is not overridden) applies $configured_state using the $manager contained inside.
         ]]
         params {
            @in current_state : Efl.Ui.Widget_Focus_State;
               [[The current focus configuration of the widget.]]
            @inout configured_state : Efl.Ui.Widget_Focus_State;
               [[The new configuration being set on the widget.]]
            @in redirect : Efl.Ui.Widget;
               [[A redirect object if there is any]]
         }
         return: bool; [[Returns $true if the widget is registered in the focus manager, $false if not.]]
      }
   }
   parts {
      shadow: Efl.Ui.Widget_Part_Shadow;
      background: Efl.Ui.Widget_Part_Bg;
   }
   implements {
      class.constructor;
      Efl.Object.constructor;
      Efl.Object.finalize;
      Efl.Object.invalidate;
      Efl.Object.destructor;
      Efl.Object.provider_find;
      Efl.Object.debug_name_override;
      Efl.Gfx.Color.color { set; }
      Efl.Gfx.Entity.visible { set; }
      Efl.Gfx.Entity.position { set; }
      Efl.Gfx.Entity.size { set; }
      Efl.Gfx.Entity.scale { set; get; }
      Efl.Canvas.Object.clipper { set; }
      Efl.Canvas.Object.no_render { set; }
      Efl.Canvas.Group.group_calculate;
      Efl.Canvas.Group.group_member_remove;
      Efl.Canvas.Group.group_member_add;
      Efl.Access.Object.i18n_name { get; }
      Efl.Access.Object.state_set { get; }
      Efl.Access.Object.access_children { get; }
      Efl.Access.Object.attributes { get; }
      Efl.Access.Component.focus_grab;
      Efl.Ui.Focus.Object.focus_manager { get; }
      Efl.Ui.Focus.Object.focus_parent { get; }
      Efl.Ui.Focus.Object.focus_geometry { get; }
      Efl.Ui.Focus.Object.focus { set; }
      Efl.Ui.I18n.mirrored { get; set; }
      Efl.Ui.I18n.mirrored_automatic { get; set; }
      Efl.Ui.Focus.Object.on_focus_update;
      Efl.Ui.L10n.translation_update; [[This implements the calls to $gettext() and $text_set().]]
      Efl.Part.part_get; [[Returns @Efl.Ui.Widget_Part.]]
      Efl.Ui.View.model { get; set; }
      Efl.Ui.Property_Bind.property_bind;
   }
   constructors {
      .style @optional;
   }
   events {
      language,changed: void; [[Called when widget language changed]]
      access,changed @beta: void; [[Called when accessibility changed]]
   }
}