1 /*******************************************************************************

     2  * Copyright (c) 2000, 2007 IBM Corporation and others.

     3  * Portion Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     4  * All rights reserved. This program and the accompanying materials

     5  * are made available under the terms of the Eclipse Public License v1.0

     6  * which accompanies this distribution, and is available at

     7  * http://www.eclipse.org/legal/epl-v10.html

     8  *

     9  * Contributors:

    10  *     IBM Corporation - initial API and implementation

    11  *     Nokia Corporation - Qt implementation

    12  *******************************************************************************/

    13 package org.eclipse.swt.widgets;

    14 

    15 import org.eclipse.swt.SWT;

    16 import org.eclipse.swt.internal.qt.OS;

    17 import org.eclipse.swt.internal.qt.WidgetState;

    18 import org.eclipse.swt.events.SelectionListener;

    19 

    20 /**

    21  * Instances of this class are selectable user interface objects that represent

    22  * a range of positive, numeric values.

    23  * <p>

    24  * At any given moment, a given slider will have a single 'selection' that is

    25  * considered to be its value, which is constrained to be within the range of

    26  * values the slider represents (that is, between its <em>minimum</em> and

    27  * <em>maximum</em> values).

    28  * </p>

    29  * <p>

    30  * Typically, sliders will be made up of five areas:

    31  * <ol>

    32  * <li>an arrow button for decrementing the value</li>

    33  * <li>a page decrement area for decrementing the value by a larger amount</li>

    34  * <li>a <em>thumb</em> for modifying the value by mouse dragging</li>

    35  * <li>a page increment area for incrementing the value by a larger amount</li>

    36  * <li>an arrow button for incrementing the value</li>

    37  * </ol>

    38  * Based on their style, sliders are either <code>HORIZONTAL</code> (which have

    39  * a left facing button for decrementing the value and a right facing button for

    40  * incrementing it) or <code>VERTICAL</code> (which have an upward facing button

    41  * for decrementing the value and a downward facing buttons for incrementing

    42  * it).

    43  * </p>

    44  * <p>

    45  * On some platforms, the size of the slider's thumb can be varied relative to

    46  * the magnitude of the range of values it represents (that is, relative to the

    47  * difference between its maximum and minimum values). Typically, this is used

    48  * to indicate some proportional value such as the ratio of the visible area of

    49  * a document to the total amount of space that it would take to display it. SWT

    50  * supports setting the thumb size even if the underlying platform does not, but

    51  * in this case the appearance of the slider will not change.

    52  * </p>

    53  * <dl>

    54  * <dt><b>Styles:</b></dt>

    55  * <dd>HORIZONTAL, VERTICAL</dd>

    56  * <dt><b>Events:</b></dt>

    57  * <dd>Selection</dd>

    58  * </dl>

    59  * <p>

    60  * Note: Only one of the styles HORIZONTAL and VERTICAL may be specified.

    61  * </p>

    62  * <p>

    63  * IMPORTANT: This class is <em>not</em> intended to be subclassed.

    64  * </p>

    65  * 

    66  * @see ScrollBar

    67  */

    68 public class Slider extends Control {

    69 

    70     /**

    71      * This is used for storing the latest value that user has set the Slider

    72      * using setSelection(). If user changes the value of the Slider with

    73      * keys/mouse we get valueChanged() signal in which we send a

    74      * SelectionEvent. However, we get the same signal also after user sets the

    75      * selection using setSelection(). In that case we must not send a selection

    76      * event.

    77      */

    78     int     value          = -1;

    79 

    80     /**

    81      * QSlider does not have thumb support, so we emulate the API behavior in

    82      * Java side.

    83      */

    84     int     thumb          = 1;

    85 

    86     /**

    87      * This is used to store the information about key/mouse action that may

    88      * cause Slider value to change.

    89      */

    90     int     selectionCause = 0;

    91 

    92     /**

    93      * This is set to true when a DRAG event occurs, so that we can send a drag

    94      * end event when user releases the mouse.

    95      */

    96     boolean dragOccurred   = false;

    97 

    98     /**

    99      * Constructs a new instance of this class given its parent and a style

   100      * value describing its behavior and appearance.

   101      * <p>

   102      * The style value is either one of the style constants defined in class

   103      * <code>SWT</code> which is applicable to instances of this class, or must

   104      * be built by <em>bitwise OR</em>'ing together (that is, using the

   105      * <code>int</code> "|" operator) two or more of those <code>SWT</code>

   106      * style constants. The class description lists the style constants that are

   107      * applicable to the class. Style bits are also inherited from superclasses.

   108      * </p>

   109      * 

   110      * @param parent a composite control which will be the parent of the new

   111      *               instance (cannot be null)

   112      * @param style the style of control to construct

   113      * 

   114      * @exception IllegalArgumentException <ul>

   115      *                <li>ERROR_NULL_ARGUMENT - if the parent is null</li> 

   116      *                </ul>

   117      * @exception SWTException <ul>

   118      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>

   119      *                <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>

   120      *                </ul>

   121      * 

   122      * @see SWT#HORIZONTAL

   123      * @see SWT#VERTICAL

   124      * @see Widget#checkSubclass

   125      * @see Widget#getStyle

   126      */

   127     public Slider(Composite parent, int style) {

   128         super(parent, checkStyle(style));

   129     }

   130 

   131     /**

   132      * Adds the listener to the collection of listeners who will be notified

   133      * when the user changes the receiver's value, by sending it one of the

   134      * messages defined in the <code>SelectionListener</code> interface.

   135      * <p>

   136      * When <code>widgetSelected</code> is called, the event object detail field

   137      * contains one of the following values: <code>SWT.NONE</code> - for the end

   138      * of a drag. <code>SWT.DRAG</code>. <code>SWT.HOME</code>.

   139      * <code>SWT.END</code>. <code>SWT.ARROW_DOWN</code>.

   140      * <code>SWT.ARROW_UP</code>. <code>SWT.PAGE_DOWN</code>.

   141      * <code>SWT.PAGE_UP</code>. <code>widgetDefaultSelected</code> is not

   142      * called.

   143      * </p>

   144      * 

   145      * @param listener the listener which should be notified when the user changes

   146      *                 the receiver's value

   147      * 

   148      * @exception IllegalArgumentException <ul>

   149      *                <li>ERROR_NULL_ARGUMENT - if the listener is null</li>

   150      *                </ul>

   151      * @exception SWTException  <ul>

   152      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   153      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   154      *                </ul>

   155      * 

   156      * @see SelectionListener

   157      * @see #removeSelectionListener

   158      * @see SelectionEvent

   159      */

   160     public void addSelectionListener(SelectionListener listener) {

   161         checkWidget();

   162         if (listener == null) error(SWT.ERROR_NULL_ARGUMENT);

   163         TypedListener typedListener = new TypedListener(listener);

   164         addListener(SWT.Selection, typedListener);

   165         addListener(SWT.DefaultSelection, typedListener);

   166     }

   167 

   168     static int checkStyle(int style) {

   169         return checkBits(style, SWT.HORIZONTAL, SWT.VERTICAL, 0, 0, 0, 0);

   170     }

   171 

   172     void createHandle_pp(int index) {

   173         state |= WidgetState.HANDLE;

   174         topHandle = handle = OS.QSlider_new();

   175 

   176         if ((style & SWT.VERTICAL) != 0) {

   177             OS.QSlider_setOrientation(handle, OS.QT_VERTICAL);

   178         } else {

   179             OS.QSlider_setOrientation(handle, OS.QT_HORIZONTAL);

   180         }

   181     }

   182 

   183     void hookEvents_pp() {

   184         int signalProxy = OS.SignalHandler_new(handle, display,

   185                 OS.QSIGNAL_SLIDER_CHANGED);

   186         OS.QObject_connectOrThrow(handle, "valueChanged(int)", signalProxy,

   187                 "widgetSignal(int)", OS.QT_AUTOCONNECTION);

   188     }

   189 

   190     /**

   191      * Returns the amount that the receiver's value will be modified by when the

   192      * up/down (or right/left) arrows are pressed.

   193      * 

   194      * @return the increment

   195      * 

   196      * @exception SWTException <ul>

   197      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   198      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   199      *                </ul>

   200      */

   201     public int getIncrement() {

   202         checkWidget();

   203         return OS.QSlider_singleStep(handle);

   204     }

   205 

   206     /**

   207      * Returns the maximum value which the receiver will allow.

   208      * 

   209      * @return the maximum

   210      * 

   211      * @exception SWTException <ul>

   212      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   213      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   214      *                </ul>

   215      */

   216     public int getMaximum() {

   217         checkWidget();

   218         return OS.QSlider_maximum(handle);

   219     }

   220 

   221     /**

   222      * Returns the minimum value which the receiver will allow.

   223      * 

   224      * @return the minimum

   225      * 

   226      * @exception SWTException <ul>

   227      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   228      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   229      *                </ul>

   230      */

   231     public int getMinimum() {

   232         checkWidget();

   233         return OS.QSlider_minimum(handle);

   234     }

   235 

   236     /**

   237      * Returns the amount that the receiver's value will be modified by when the

   238      * page increment/decrement areas are selected.

   239      * 

   240      * @return the page increment

   241      * 

   242      * @exception SWTException <ul>

   243      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   244      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   245      *                </ul>

   246      */

   247     public int getPageIncrement() {

   248         checkWidget();

   249         return OS.QSlider_pageStep(handle);

   250     }

   251 

   252     /**

   253      * Returns the 'selection', which is the receiver's value.

   254      * 

   255      * @return the selection

   256      * 

   257      * @exception SWTException <ul>

   258      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   259      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   260      *                </ul>

   261      */

   262     public int getSelection() {

   263         checkWidget();

   264         return OS.QSlider_value(handle);

   265     }

   266 

   267     /**

   268      * Returns the size of the receiver's thumb relative to the difference

   269      * between its maximum and minimum values.

   270      * 

   271      * @return the thumb value

   272      * 

   273      * @exception SWTException <ul>

   274      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   275      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   276      *                </ul>

   277      */

   278     public int getThumb() {

   279         checkWidget();

   280         return thumb;

   281     }

   282 

   283     /**

   284      * Removes the listener from the collection of listeners who will be

   285      * notified when the user changes the receiver's value.

   286      * 

   287      * @param listener the listener which should no longer be notified

   288      * 

   289      * @exception IllegalArgumentException <ul>

   290      *                <li>ERROR_NULL_ARGUMENT - if the listener is null</li>

   291      *                </ul>

   292      * @exception SWTException <ul>

   293      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   294      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   295      *                </ul>

   296      * 

   297      * @see SelectionListener

   298      * @see #addSelectionListener

   299      */

   300     public void removeSelectionListener(SelectionListener listener) {

   301         checkWidget();

   302         if (listener == null) error(SWT.ERROR_NULL_ARGUMENT);

   303         if (eventTable == null) return;

   304         eventTable.unhook(SWT.Selection, listener);

   305         eventTable.unhook(SWT.DefaultSelection, listener);

   306     }

   307 

   308     /**

   309      * Sets the amount that the receiver's value will be modified by when the

   310      * up/down (or right/left) arrows are pressed to the argument, which must be

   311      * at least one.

   312      * 

   313      * @param value the new increment (must be greater than zero)

   314      * 

   315      * @exception SWTException <ul>

   316      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   317      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   318      *                </ul>

   319      */

   320     public void setIncrement(int value) {

   321         checkWidget();

   322         if (value < 1) {

   323             return;

   324         }

   325         OS.QSlider_setSingleStep(handle, value);

   326     }

   327 

   328     /**

   329      * Sets the maximum. If this value is negative or less than or equal to the

   330      * minimum, the value is ignored. If necessary, first the thumb and then the

   331      * selection are adjusted to fit within the new range.

   332      * 

   333      * @param value the new maximum, which must be greater than the current

   334      *              minimum

   335      * 

   336      * @exception SWTException <ul>

   337      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   338      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   339      *                </ul>

   340      */

   341     public void setMaximum(int value) {

   342         checkWidget();

   343         int minimum = OS.QSlider_minimum(handle);

   344 

   345         if (value >= 0 && value > minimum) {

   346             thumb = Math.min(thumb, value - minimum);

   347             setValue(Math.min(OS.QSlider_value(handle), value - thumb));

   348             OS.QSlider_setMaximum(handle, value);

   349         }

   350     }

   351 

   352     /**

   353      * Sets the minimum value. If this value is negative or greater than or

   354      * equal to the maximum, the value is ignored. If necessary, first the thumb

   355      * and then the selection are adjusted to fit within the new range.

   356      * 

   357      * @param value the new minimum

   358      * 

   359      * @exception SWTException <ul>

   360      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   361      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   362      *                </ul>

   363      */

   364     public void setMinimum(int value) {

   365         checkWidget();

   366         if (value < 0) {

   367             return;

   368         }

   369 

   370         int maximum = OS.QSlider_maximum(handle);

   371         if (value >= maximum) {

   372             return;

   373         }

   374         this.thumb = Math.min(thumb, maximum - value);

   375         setValue(Math.max(OS.QSlider_value(handle), value));

   376         OS.QSlider_setMinimum(handle, value);

   377     }

   378 

   379     /**

   380      * Sets the amount that the receiver's value will be modified by when the

   381      * page increment/decrement areas are selected to the argument, which must

   382      * be at least one.

   383      * 

   384      * @param value the page increment (must be greater than zero)

   385      * 

   386      * @exception SWTException <ul>

   387      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   388      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   389      *                </ul>

   390      */

   391     public void setPageIncrement(int value) {

   392         checkWidget();

   393         if (value < 1) {

   394             return;

   395         }

   396         OS.QSlider_setPageStep(handle, value);

   397     }

   398 

   399     /**

   400      * Sets the 'selection', which is the receiver's value, to the argument

   401      * which must be greater than or equal to zero.

   402      * 

   403      * @param value the new selection (must be zero or greater)

   404      * 

   405      * @exception SWTException <ul>

   406      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   407      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   408      *                </ul>

   409      */

   410     public void setSelection(int value) {

   411         checkWidget();

   412         // Adjust the selection to range [minimum, maximum-thumb]

   413         setValue(Math.max(Math.min(value, OS.QSlider_maximum(handle) - thumb),

   414                 OS.QSlider_minimum(handle)));

   415     }

   416 

   417     /**

   418      * Sets the size of the receiver's thumb relative to the difference between

   419      * its maximum and minimum values. This new value will be ignored if it is

   420      * less than one, and will be clamped if it exceeds the receiver's current

   421      * range.

   422      * 

   423      * @param value the new thumb value, which must be at least one and not larger

   424      *              than the size of the current range

   425      * 

   426      * @exception SWTException <ul>

   427      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   428      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   429      *                </ul>

   430      */

   431     public void setThumb(int value) {

   432         checkWidget();

   433         if (value < 1) {

   434             return;

   435         }

   436 

   437         int selection = OS.QSlider_value(handle);

   438         int maximum = OS.QSlider_maximum(handle);

   439         value = Math.min(value, maximum - OS.QSlider_minimum(handle));

   440 

   441         this.thumb = value;

   442         setValue(Math.min(selection, maximum - value));

   443     }

   444 

   445     /**

   446      * Sets the receiver's selection, minimum value, maximum value, thumb,

   447      * increment and page increment all at once.

   448      * <p>

   449      * Note: This is similar to setting the values individually using the

   450      * appropriate methods, but may be implemented in a more efficient fashion

   451      * on some platforms.

   452      * </p>

   453      * 

   454      * @param selection the new selection value

   455      * @param minimum the new minimum value

   456      * @param maximum the new maximum value

   457      * @param thumb the new thumb value

   458      * @param increment the new increment value

   459      * @param pageIncrement the new pageIncrement value

   460      * 

   461      * @exception SWTException <ul>

   462      *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

   463      *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

   464      *                </ul>

   465      */

   466     public void setValues(int selection, int minimum, int maximum, int thumb,

   467             int increment, int pageIncrement) {

   468         checkWidget();

   469         if (minimum < 0) return;

   470         if (maximum < 0) return;

   471         if (thumb < 1) return;

   472         if (increment < 1) return;

   473         if (pageIncrement < 1) return;

   474         thumb = Math.min(thumb, maximum - minimum);

   475         this.thumb = thumb;

   476         OS.QSlider_setMaximum(handle, maximum);

   477         OS.QSlider_setMinimum(handle, minimum);

   478         OS.QSlider_setSingleStep(handle, increment);

   479         OS.QSlider_setPageStep(handle, pageIncrement);

   480         setValue(Math.min(Math.max(selection, minimum), maximum - thumb));

   481     }

   482 

   483     void setValue(int value) {

   484         this.value = value;

   485         OS.QSlider_setValue(handle, value);

   486     }

   487 

   488     boolean qt_event_mouseButtonRelease_pp(int widgetHandle, int button, 

   489             int x, int y, int state, int buttons) {

   490         this.selectionCause = SWT.NONE;

   491 

   492         /**

   493          * If user was dragging (i.e. we have sent drag events), send a drag end

   494          * when mouse button is released

   495          */

   496         if (this.dragOccurred) {

   497             this.dragOccurred = false;

   498             sendSliderSelectionEvent(this.selectionCause);

   499         }

   500 

   501         return super.qt_event_mouseButtonRelease_pp(widgetHandle, button, x,

   502                 y, state, buttons);

   503     }

   504 

   505     boolean qt_event_mouseMove(int widgetHandle, int button, int x,

   506             int y, int state, int buttons) {

   507         this.selectionCause = SWT.DRAG;

   508         return super

   509                 .qt_event_mouseMove(widgetHandle, button, x, y, state, buttons);

   510     }

   511 

   512     boolean qt_event_keypress_pp(int widgetHandle, int key, int modifier, int character, int nativeScanCode) {

   513     

   514         /**

   515          * The following keys can cause Slider selection to change, save the key

   516          * code here so that we can use it later when creating the selection

   517          * event.

   518          */

   519         switch (key) {

   520             case OS.QT_KEY_LEFT:

   521             case OS.QT_KEY_RIGHT:

   522             case OS.QT_KEY_UP:

   523             case OS.QT_KEY_DOWN:

   524             case OS.QT_KEY_HOME:

   525             case OS.QT_KEY_END:

   526             case OS.QT_KEY_PAGEUP:

   527             case OS.QT_KEY_PAGEDOWN:

   528                 this.selectionCause = Display.translateKey(key, false);

   529                 break;

   530             default:

   531                 this.selectionCause = SWT.NONE;

   532                 break;

   533         }

   534         

   535         return super.qt_event_keypress_pp(widgetHandle, key, modifier, character, nativeScanCode);

   536     }

   537     

   538     void setTraversalFlags_pp(int type, int key, int modifier,

   539             int character) {

   540         traverseDoit = true;

   541         traverseCancel = true;

   542 

   543         /**

   544          * The following keys cause the slider value to change, so those keys

   545          * cannot be used for traversing by default: - Left/right moves a

   546          * horizontal slider by one step - Up/down moves a vertical slider by

   547          * one step - Page up/down moves by one page - Home/end moves to

   548          * beginning/end of the slider

   549          */

   550         switch (key) {

   551             case OS.QT_KEY_LEFT:

   552             case OS.QT_KEY_RIGHT:

   553                 if ((style & SWT.HORIZONTAL) != 0) {

   554                     traverseDoit = false;

   555                 }

   556                 traverseCancel = false;

   557                 break;

   558             case OS.QT_KEY_UP:

   559             case OS.QT_KEY_DOWN:

   560                 if ((style & SWT.VERTICAL) != 0) {

   561                     traverseDoit = false;

   562                 }

   563                 traverseCancel = false;

   564                 break;

   565             case OS.QT_KEY_PAGEUP:

   566             case OS.QT_KEY_PAGEDOWN:

   567             case OS.QT_KEY_HOME:

   568             case OS.QT_KEY_END:

   569                 traverseDoit = false;

   570                 traverseCancel = false;

   571                 break;

   572             default:

   573                 break;

   574         }

   575 

   576     }

   577 

   578     void qt_signal_slider_changed(int value) {

   579         /**

   580          * If Slider value has changed without the user calling some Slider API

   581          * function that causes the value to change, conclude that user

   582          * interaction has caused the slider value to change and send a

   583          * selection event.

   584          */

   585         if (this.value != value) {

   586             this.value = value;

   587 

   588             if (this.selectionCause == SWT.DRAG) {

   589                 this.dragOccurred = true;

   590             }

   591 

   592             sendSliderSelectionEvent(this.selectionCause);

   593         }

   594     }

   595 

   596     void sendSliderSelectionEvent(int detail) {

   597         Event event = new Event();

   598         event.widget = this;

   599         event.detail = detail;

   600 

   601         sendEvent(SWT.Selection, event, true);

   602     }

   603 

   604 }