docshell/base/nsIScrollable.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is the Mozilla browser.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications, Inc.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Travis Bogard <travis@netscape.com>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41
  42 /**
  43  * The nsIScrollable is an interface that can be implemented by a control that
  44  * supports scrolling.  This is a generic interface without concern for the
  45  * type of content that may be inside.  It simply deals blindly with scroll
  46  * position as a composite of the lowest possible scroll position, the highest
  47  * possible position and the current position lying somewhere between the
  48  * min and the max.
  49  *
  50  * XXXroc in our tree, only get/setDefaultScrollbarPreferences and
  51  * getScrollbarVisibility are actually used externally. We should gut
  52  * the rest. nsDocShell is using twips for all these coordinates
  53  * which is going to confuse people anyway...
  54  */
  55
  56 [scriptable, uuid(919e792a-6490-40b8-bba5-f9e9ad5640c8)]
  57 interface nsIScrollable : nsISupports
  58 {
  59         /*
  60         Constants declaring the two scroll orientations a scroll bar can be in.
  61         ScrollOrientation_X - Horizontal scrolling.  When passing this
  62                 in to a scroll position method you are requesting or
  63                 setting the positions for the horizontal scroll bar.
  64         ScrollOrientation_Y - Vertical scrolling.  When passing this
  65                 in to a scroll position you are requesting or setting
  66                 the positions for the vertical scroll bar.
  67         */
  68         const long ScrollOrientation_X = 1;
  69         const long ScrollOrientation_Y = 2;
  70
  71         /*
  72         Retrieves or Sets the current thumb position to the curPos passed in for the
  73         scrolling orientation passed in.  curPos should be between minPos and maxPos.
  74
  75         @return NS_OK - Setting or Getting completed successfully.
  76                                 NS_ERROR_INVALID_ARG - returned when curPos is not within the
  77                                         minPos and maxPos.
  78         */
  79         long getCurScrollPos(in long scrollOrientation);
  80         void setCurScrollPos(in long scrollOrientation, in long curPos);
  81
  82         /*
  83         This function atomizes the ability to scroll in two dimensions at the same
  84         time.
  85         */
  86         void setCurScrollPosEx(in long curHorizontalPos, in long curVerticalPos);
  87
  88         /*
  89         Retrieves or Sets the valid ranges for the thumb.  When maxPos is set to
  90         something less than the current thumb position, curPos is set = to maxPos.
  91
  92         @return NS_OK - Setting or Getting completed successfully.
  93                                 NS_ERROR_INVALID_ARG - returned when curPos is not within the
  94                                         minPos and maxPos.
  95         */
  96         void getScrollRange(in long scrollOrientation, out long minPos, out long maxPos);
  97         void setScrollRange(in long scrollOrientation, in long minPos, in long maxPos);
  98
  99         /*
 100         This function atomizes the ability to set the ranges in two dimensions at
 101         the same time.
 102         */
 103         void setScrollRangeEx(in long minHorizontalPos, in long maxHorizontalPos,
 104                 in long minVerticalPos, in long maxVerticalPos);
 105
 106         /*
 107         Constants declaring the states of the scroll bars.
 108         ScrollPref_Auto - bars visible only when needed.
 109         ScrollPref_Never - bars never visible, even when scrolling still possible.
 110         ScrollPref_Always - bars always visible, even when scrolling is not possible
 111         */
 112         const long Scrollbar_Auto = 1;
 113         const long Scrollbar_Never = 2;
 114         const long Scrollbar_Always = 3;
 115
 116         /*
 117         Retrieves or Set the preferences for the scroll bar.
 118         current is 'scrolling preference for this document'
 119         default is 'scrolling preference for all documents in this shell'
 120         resetScrollbarPreferences resets current to default
 121         */
 122         long getDefaultScrollbarPreferences(in long scrollOrientation);
 123         void setDefaultScrollbarPreferences(in long scrollOrientation, in long scrollbarPref);
 124
 125         /*
 126         Get information about whether the vertical and horizontal scrollbars are
 127         currently visible.  nsnull is a valid argument.  If you are only interested
 128         in one of the visibility settings pass nsnull in for the one you aren't
 129         interested in.
 130         */
 131         void getScrollbarVisibility(out boolean verticalVisible,
 132                 out boolean horizontalVisible);
 133 };