Interface Progression

  • All Known Implementing Classes:
    DefaultProgression, SubProgressionModel

    public interface Progression
    An object that permits to indicates the progression of a task. The progression of the value is always ascendent.
    Version:
    17.0 2020-01-04 14:41:38
    Author:
    Stéphane GALLAND
    Maven Group Id:
    org.arakhne.afc.core
    Maven Artifact Id:
    util
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addProgressionListener​(ProgressionListener listener)
      Add a listener on this model.
      void end()
      Force this progression task to end its indicator.
      void ensureNoSubTask()
      Ensure that there is no opened subtask.
      String getComment()
      Replies the comment associated to the currect task.
      int getMaximum()
      Returns the model's maximum.
      int getMinimum()
      Returns the minimum acceptable value.
      double getPercent()
      Returns the model's current value in percent of pregression.
      double getProgressionFactor()
      Returns the model's current value in percent of pregression.
      Progression getSubTask()
      Replies the current subtask of this task model.
      Progression getSuperTask()
      Replies the super task of this task model.
      int getTaskDepth()
      Replies the depth level of this task.
      int getValue()
      Returns the model's current value.
      void increment()
      Increment the current value by 1.
      void increment​(int amount)
      Increment the current value by the given amount.
      void increment​(int amount, String comment)
      Increment the current value by the given amount.
      void increment​(String comment)
      Increment the current value by 1.
      boolean isAdjusting()
      Returns true if the current changes to the value property are part of a series of changes.
      boolean isIndeterminate()
      Returns the value of the indeterminate property.
      boolean isRootModel()
      Replies if is task model is a root model.
      void removeProgressionListener​(ProgressionListener listener)
      Remove a listener on this model.
      void setAdjusting​(boolean adjusting)
      This attribute indicates that any upcoming changes to the value of the model should be considered a single event.
      void setComment​(String comment)
      Set the comment associated to the currect task.
      void setIndeterminate​(boolean newValue)
      Sets the indeterminate property of the task progression, which determines whether the progression is in determinate or indeterminate mode.
      void setMaximum​(int newMaximum)
      Sets the model's maximum to newMaximum.
      void setMinimum​(int newMinimum)
      Sets the model's minimum to newMinimum.
      void setProperties​(int value, int min, int max, boolean adjusting)
      This method sets all of the model's data with a single method call.
      void setProperties​(int value, int min, int max, boolean adjusting, String comment)
      This method sets all of the model's data with a single method call.
      void setValue​(int newValue)
      Sets the model's current value to newValue if newValue satisfies the model's constraints.
      void setValue​(int newValue, String comment)
      Sets the model's current value to newValue if newValue satisfies the model's constraints.
      Progression subTask​(int extent)
      Enter into a subtask.
      Progression subTask​(int extent, boolean overwriteComment)
      Enter into a subtask.
      Progression subTask​(int extent, int min, int max)
      Enter into a subtask.
      Progression subTask​(int extent, int min, int max, boolean overwriteComment)
      Enter into a subtask.
    • Method Detail

      • addProgressionListener

        void addProgressionListener​(ProgressionListener listener)
        Add a listener on this model.
        Parameters:
        listener - is the listener to add.
      • removeProgressionListener

        void removeProgressionListener​(ProgressionListener listener)
        Remove a listener on this model.
        Parameters:
        listener - is the listener to remove.
      • getMinimum

        int getMinimum()
        Returns the minimum acceptable value.
        Returns:
        the value of the minimum property
        See Also:
        setMinimum(int)
      • setMinimum

        void setMinimum​(int newMinimum)
        Sets the model's minimum to newMinimum. The other properties may be changed as well, to ensure that:
         minimum <= value <= maximum
         
        Parameters:
        newMinimum - the model's new minimum
        See Also:
        getMinimum()
      • getMaximum

        int getMaximum()
        Returns the model's maximum.
        Returns:
        the value of the maximum property.
        See Also:
        setMaximum(int)
      • setMaximum

        void setMaximum​(int newMaximum)
        Sets the model's maximum to newMaximum. The other properties may be changed as well, to ensure that
         minimum <= value <= maximum
         
        Parameters:
        newMaximum - the model's new maximum
        See Also:
        getMaximum()
      • getValue

        int getValue()
        Returns the model's current value. Note that the upper limit on the model's value is maximum and the lower limit is minimum.
        Returns:
        the model's value
        See Also:
        setValue(int)
      • getPercent

        double getPercent()
        Returns the model's current value in percent of pregression.
        Returns:
        the model's value between 0 and 100
        See Also:
        getValue(), getProgressionFactor()
      • getProgressionFactor

        double getProgressionFactor()
        Returns the model's current value in percent of pregression.
        Returns:
        the model's value between 0 and 1
        See Also:
        getValue(), getPercent()
      • setValue

        void setValue​(int newValue)
        Sets the model's current value to newValue if newValue satisfies the model's constraints. Those constraints are:
         minimum <= value <= maximum
         
        Otherwise, if newValue is less than minimum it's set to minimum, if its greater than maximum then it's set to maximum.
        Parameters:
        newValue - the model's new value
        See Also:
        getValue()
      • setValue

        void setValue​(int newValue,
                      String comment)
        Sets the model's current value to newValue if newValue satisfies the model's constraints. Those constraints are:
         minimum <= value <= maximum
         
        Otherwise, if newValue is less than minimum it's set to minimum, if its greater than maximum then it's set to maximum.
        Parameters:
        newValue - the model's new value
        comment - is the comment to display.
        See Also:
        getValue()
      • setAdjusting

        void setAdjusting​(boolean adjusting)
        This attribute indicates that any upcoming changes to the value of the model should be considered a single event. This attribute will be set to true at the start of a series of changes to the value, and will be set to false when the value has finished changing. Normally this allows a listener to only take action when the final value change in committed, instead of having to do updates for all intermediate values.
        Parameters:
        adjusting - true if the upcoming changes to the value property are part of a series
        See Also:
        subTask(int)
      • isAdjusting

        boolean isAdjusting()
        Returns true if the current changes to the value property are part of a series of changes.
        Returns:
        the valueIsAdjustingProperty.
        See Also:
        setAdjusting(boolean)
      • setProperties

        void setProperties​(int value,
                           int min,
                           int max,
                           boolean adjusting,
                           String comment)
        This method sets all of the model's data with a single method call. The method results in a single change event being generated. This is convenient when you need to adjust all the model data simultaneously and do not want individual change events to occur.
        Parameters:
        value - an int giving the current value
        min - an int giving the minimum value
        max - an int giving the maximum value
        adjusting - a boolean, true if a series of changes are in progress
        comment - is the comment associated to the current task, or null
        See Also:
        setValue(int), setMinimum(int), setMaximum(int), setComment(String), setAdjusting(boolean)
      • setProperties

        void setProperties​(int value,
                           int min,
                           int max,
                           boolean adjusting)
        This method sets all of the model's data with a single method call. The method results in a single change event being generated. This is convenient when you need to adjust all the model data simultaneously and do not want individual change events to occur.
        Parameters:
        value - an int giving the current value
        min - an int giving the minimum value
        max - an int giving the maximum value
        adjusting - a boolean, true if a series of changes are in progress
        See Also:
        setValue(int), setMinimum(int), setMaximum(int), setComment(String), setAdjusting(boolean)
      • setIndeterminate

        void setIndeterminate​(boolean newValue)
        Sets the indeterminate property of the task progression, which determines whether the progression is in determinate or indeterminate mode. For example an indeterminate progress bar continuously displays animation indicating that an operation of unknown length is occurring.
        Parameters:
        newValue - true if the progress bar should change to indeterminate mode; false if it should revert to normal.
        See Also:
        isIndeterminate()
      • isIndeterminate

        boolean isIndeterminate()
        Returns the value of the indeterminate property.
        Returns:
        the value of the indeterminate property
        See Also:
        setIndeterminate(boolean)
      • setComment

        void setComment​(String comment)
        Set the comment associated to the currect task.

        If the given string is null or empty, the current task is assumed to not have a comment.

        Parameters:
        comment - is the comment for the current task.
      • getComment

        String getComment()
        Replies the comment associated to the currect task.
        Returns:
        the comment for the current task or null if the current task has not any comment.
      • subTask

        Progression subTask​(int extent,
                            int min,
                            int max)
        Enter into a subtask. When a sub task is created, it will progress as a sub part of the main task.

        The minimum value of the subtask in its parent will correspond to the current value of the main task. The maximum value of the sub task in its parent will correspond to the current value of the main task plus the given extend.

        If the extend plus the current value is exceeding the maximum value, it will be bounded to the maximum.

        Parameters:
        extent - is the size of the sub task inside the main task.
        min - is the minimum value inside the subtask.
        max - is the maximum value inside the subtask.
        Returns:
        the subtask progression
      • subTask

        Progression subTask​(int extent)
        Enter into a subtask. When a sub task is created, it will progress as a sub part of the main task.

        The minimum value of the subtask in its parent will correspond to the current value of the main task. The maximum value of the sub task in its parent will correspond to the current value of the main task plus the given extend.

        If the extend plus the current value is exceeding the maximum value, it will be bounded to the maximum.

        The minimum and maximum values of the subtask should be manually set the the caller.

        Parameters:
        extent - is the size of the sub task inside the main task.
        Returns:
        the subtask progression
      • subTask

        Progression subTask​(int extent,
                            int min,
                            int max,
                            boolean overwriteComment)
        Enter into a subtask. When a sub task is created, it will progress as a sub part of the main task.

        The minimum value of the subtask in its parent will correspond to the current value of the main task. The maximum value of the sub task in its parent will correspond to the current value of the main task plus the given extend.

        If the extend plus the current value is exceeding the maximum value, it will be bounded to the maximum.

        Parameters:
        extent - is the size of the sub task inside the main task.
        min - is the minimum value inside the subtask.
        max - is the maximum value inside the subtask.
        overwriteComment - indicates if the comment of this task model may be overwritten by the comment of the subtask when it is disconnected.
        Returns:
        the subtask progression
      • subTask

        Progression subTask​(int extent,
                            boolean overwriteComment)
        Enter into a subtask. When a sub task is created, it will progress as a sub part of the main task.

        The minimum value of the subtask in its parent will correspond to the current value of the main task. The maximum value of the sub task in its parent will correspond to the current value of the main task plus the given extend.

        If the extend plus the current value is exceeding the maximum value, it will be bounded to the maximum.

        The minimum and maximum values of the subtask should be manually set the the caller.

        Parameters:
        extent - is the size of the sub task inside the main task.
        overwriteComment - indicates if the comment of this task model may be overwritten by the comment of the subtask when it is disconnected.
        Returns:
        the subtask progression
      • getSubTask

        Progression getSubTask()
        Replies the current subtask of this task model.
        Returns:
        the current subtask or null this task was not decomposed.
      • ensureNoSubTask

        void ensureNoSubTask()
        Ensure that there is no opened subtask. If a subtask is existing, it is ended().
      • getSuperTask

        Progression getSuperTask()
        Replies the super task of this task model.
        Returns:
        the super task or null this task was not a decomposition of a super task.
      • end

        void end()
        Force this progression task to end its indicator.
      • isRootModel

        boolean isRootModel()
        Replies if is task model is a root model.

        isRootMode() == (getTaskDepth()==0)

        Returns:
        true if this model is a root model, otherwise false
      • getTaskDepth

        int getTaskDepth()
        Replies the depth level of this task. The root task (ie. a task without parent task) has always a depth of 0. A subtask of the root task has a depth of 1. A subtask of this subtask has a depth of 2, etc.

        isRootMode() == (getTaskDepth()==0)

        Returns:
        the depth of the task.
      • increment

        void increment​(int amount)
        Increment the current value by the given amount.

        This function is equivalent to:

        
         this.setValue(this.getValue()+amount);
         
        Parameters:
        amount - is the amount to add to the current value.
        Since:
        11.0
      • increment

        void increment​(int amount,
                       String comment)
        Increment the current value by the given amount.

        This function is equivalent to:

        
         this.setValue(this.getValue()+amount, comment);
         
        Parameters:
        amount - is the amount to add to the current value.
        comment - is the comment to display.
        Since:
        11.0
      • increment

        void increment()
        Increment the current value by 1.

        This function is equivalent to:

        
         this.setValue(this.getValue()+1);
         
        Since:
        11.0
      • increment

        void increment​(String comment)
        Increment the current value by 1.

        This function is equivalent to:

        
         this.setValue(this.getValue()+1, comment);
         
        Parameters:
        comment - is the comment to display.
        Since:
        11.0