scroller.cpp

Go to the documentation of this file.

//----------------------------------------------------------------------------
// ObjectWindows
// Copyright (c) 1991, 1996 by Borland International, All Rights Reserved
//
/// \file
/// Implementation of class TScroller.
/// Including bug fixes by Rich Goldstein
//----------------------------------------------------------------------------
#include <owl/pch.h>
#include <owl/scroller.h>
#include <owl/window.h>
#include <owl/dc.h>
#include <stdlib.h>
 
#include <algorithm>
 
namespace owl {
 
OWL_DIAGINFO;
 
namespace
{
 
//
// Guards the scroll bar synchronization of a scroller against re-entry [bugs:#623].
// Showing or hiding a scroll bar changes the client area, and Windows then sends WM_SIZE
// synchronously, from within SetScrollInfo. The resulting nested calls to SetPageSize and
// SetSBarRange must be ignored, since the outer call will take the new client area into account.
//
// The state is kept in a window property, rather than in the scroller, to keep the class layout
// unchanged (ABI compatibility). Since a window belongs to a single thread, this is thread-safe.
//
const TCHAR SyncPropertyName[] = _T("OWL_TScroller_SyncScrollBars");
 
auto IsSyncing(const TWindow& w) -> bool
{
  return ::GetProp(w.GetHandle(), SyncPropertyName) != nullptr;
}
 
class TSyncGuard
{
public:
  explicit TSyncGuard(const TWindow& w)
    : Window(w.GetHandle()), Entered(!::GetProp(Window, SyncPropertyName))
  {
    if (Entered) ::SetProp(Window, SyncPropertyName, reinterpret_cast<HANDLE>(1));
  }
 
  ~TSyncGuard()
  {
    if (Entered) ::RemoveProp(Window, SyncPropertyName);
  }
 
  auto IsReentry() const -> bool { return !Entered; }
 
private:
  HWND Window;
  bool Entered;
 
  TSyncGuard(const TSyncGuard&); // Not implemented.
  TSyncGuard& operator =(const TSyncGuard&); // Not implemented.
};
 
//
// Page and scroll bar properties for one direction.
//
struct TBarMetrics
{
  int Page; ///< Scroller page (TScroller::XPage or YPage), in scroll units.
  int ScrollPage; ///< Scroll bar page (SCROLLINFO::nPage).
  int ScrollMax; ///< Scroll bar range maximum (SCROLLINFO::nMax); the minimum is always zero.
 
  //
  // Returns true if the scroll bar is needed, i.e. if the page does not cover the whole range.
  //
  auto IsScrollable() const -> bool { return ScrollMax > 0 && ScrollPage <= ScrollMax; }
};
 
//
// Calculates the page properties for the given client extent (in device units).
// If the extent or the unit is not positive, the given fallback page values are used.
//
// The page is the number of units that are fully visible. Previously, the page was one unit less
// than that (in most cases), so that a scroll bar was shown, and could be scrolled, one unit before
// the content exceeded the client area [bugs:#623].
//
auto CalculateBarMetrics(int extent, int unit, long range, long totalUnits, int scrollMax, int page, int scrollPage) -> TBarMetrics
{
  if (extent > 0 && unit > 0)
  {
    page = std::max(1, extent / unit);
    scrollPage = (totalUnits && totalUnits > extent) ?
      static_cast<int>(static_cast<long long>(extent) * range / totalUnits) :
      page;
  }
  const TBarMetrics m = {page, scrollPage, scrollMax};
  return m;
}
 
auto CalculateScrollMax(long range) -> int
{
  return static_cast<int>(std::max(0L, std::min(range - 1, static_cast<long>(INT_MAX))));
}
 
} // namespace
 
//
/// Constructs a TScroller object with window as the owner window, and xUnit, yUnit,
/// xRange, and yRange as xUnit, yUnit, xRange and yRange, respectively. Initializes
/// data members to default values. HasHScrollBar and HasVScrollBar are set
/// according to the scroll bar attributes of the owner window.
//
TScroller::TScroller(TWindow* window,
                     int      xUnit,
                     int      yUnit,
                     long     xRange,
                     long     yRange)
{
  Window = window;
  XPos = YPos = 0;
  XUnit = xUnit;
  YUnit = yUnit;
  XRange = xRange;
  YRange = yRange;
  XTotalUnits = 0;
  YTotalUnits = 0;
  XLine = 1;  YLine = 1;
  XPage = 1;  YPage = 1;
  AutoMode = true;
  TrackMode = true;
  AutoOrg = true;
  HasHScrollBar = ToBool(Window && (Window->GetWindowAttr().Style&WS_HSCROLL));
  HasVScrollBar = ToBool(Window && (Window->GetWindowAttr().Style&WS_VSCROLL));
}
 
//
/// Destructs a TScroller object. Sets owning window's Scroller number variable to 0.
//
TScroller::~TScroller()
{
  if (Window && Window->GetScroller() == this)
    Window->SetScroller(0);
}
 
//
/// Sets the XPage and YPage data members (amount by which to scroll on a page
/// scroll request) to the width and height (in XUnits and
/// YUnits) of the owner window's client area.
///
/// The client area used is the one that results after the scroll bars have been
/// shown or hidden as needed, and the scroll bars are updated accordingly (see
/// SetSBarRange). The scroll position is then clamped to the new page size.
//
void
TScroller::SetPageSize()
{
  PRECONDITION(Window);
  PRECONDITION(Window->GetHandle());
 
  if (Window && Window->GetHandle()) {
    if (IsSyncing(*Window)) return; // Nested call; see TSyncGuard.
 
    // Call the base implementation explicitly, since an override of SetSBarRange may only update
    // the ranges, while the page sizes and scroll bar visibility must be updated here.
    //
    TScroller::SetSBarRange();
    ScrollTo(XPos, YPos);
  }
}
 
//
/// Sets the xRange and yRange of the TScroller to the parameters specified. Then
/// calls SetSBarRange to synchronize the range of the owner window's scroll bars.
//
void
TScroller::SetRange(long xRange, long yRange)
{
  XRange = xRange;
  YRange = yRange;
  SetSBarRange();
  ScrollTo(XPos, YPos);
}
 
//
// Sets the total units of the window
//
void
TScroller::SetTotalRangeOfUnits(long xTotalUnits, long yTotalUnits)
{
  XTotalUnits = xTotalUnits;
  YTotalUnits = yTotalUnits;
  SetSBarRange();
  ScrollTo(XPos, YPos);
}
 
//
/// Sets the XUnit and YUnit data members to TheXUnit and TheYUnit, respectively.
/// Updates XPage and YPage by calling SetPageSize.
//
void
TScroller::SetUnits(int xUnit, int yUnit)
{
  XUnit = xUnit;
  YUnit = yUnit;
  SetPageSize();
}
 
//
/// Sets the range of the owner window's scroll bars to match the range of the
/// TScroller and repaints as necessary.
///
/// The page sizes and the visibility of the scroll bars are updated as well, since showing or
/// hiding a scroll bar changes the client area of the window [bugs:#623]:
///
/// - The visibility of both scroll bars is decided up front, based on the client area without
///   any of the scroller's scroll bars, accounting for the space each scroll bar takes from the
///   other direction. The page sizes are then calculated for the resulting client area.
/// - A scroll bar that is not needed is hidden by an empty range. Windows clamps the stored page
///   to the size of the range, so with the actual range, the page stored for a hidden scroll bar
///   is just large enough to hide it, and any increase of the range would show the scroll bar
///   before the new page could be applied, making it flash. Hence, the need for a scroll bar is
///   decided from XRange and YRange, never from the range stored in the scroll bar.
/// - For a visible scroll bar, range and page are applied in an order that keeps it visible.
/// - If the client area still changed, e.g. due to inaccurate scroll bar metrics, the process is
///   repeated (at most three passes).
//
void
TScroller::SetSBarRange()
{
  PRECONDITION(Window);
  PRECONDITION(Window->GetHandle());
 
  if (!Window || !Window->GetHandle()) return;
  const TSyncGuard guard(*Window);
  if (guard.IsReentry()) return;
 
  const auto isShown = [&](uint32 style) { return (Window->GetStyle() & style) != 0; };
  const auto apply = [&](int bar, const TBarMetrics& m)
  {
    int curMin, curMax;
    GetScrollRange(bar, curMin, curMax);
    if (!m.IsScrollable())
    {
      // Hide the scroll bar by an empty range (see above). The page is irrelevant.
      //
      if (curMin != 0 || curMax != 0)
        SetScrollRange(bar, 0, 0, true);
      return;
    }
 
    // Keep the scroll bar visible in between: Apply the range first, unless the current page
    // does not fit within the new range, in which case the new page is applied first.
    //
    const auto curPage = GetScrollPage(bar);
    const auto rangeChanged = curMin != 0 || curMax != m.ScrollMax;
    const auto pageChanged = curPage != m.ScrollPage;
    const auto rangeFirst = curPage <= m.ScrollMax;
    if (rangeChanged && rangeFirst)
      SetScrollRange(bar, 0, m.ScrollMax, true);
    if (pageChanged)
      SetScrollPage(bar, m.ScrollPage, true);
    if (rangeChanged && !rangeFirst)
      SetScrollRange(bar, 0, m.ScrollMax, true);
  };
 
  const auto xMax = HasHScrollBar ? CalculateScrollMax(XRange) : 0;
  const auto yMax = HasVScrollBar ? CalculateScrollMax(YRange) : 0;
  const auto maxPassCount = 3;
  auto pass = 0;
  for (; pass != maxPassCount; ++pass)
  {
    const auto client = Window->GetClientRect().Size();
    const auto hShown = HasHScrollBar && isShown(WS_HSCROLL);
    const auto vShown = HasVScrollBar && isShown(WS_VSCROLL);
    const auto barHeight = ::GetSystemMetrics(SM_CYHSCROLL);
    const auto barWidth = ::GetSystemMetrics(SM_CXVSCROLL);
    const auto full = TSize(client.cx + (vShown ? barWidth : 0), client.cy + (hShown ? barHeight : 0));
    TBarMetrics h, v;
    const auto calculate = [&](bool needH, bool needV)
    {
      // If the visibility is unchanged, use the actual client area, rather than relying on metrics.
      //
      const auto unchanged = needH == hShown && needV == vShown;
      const auto width = unchanged ? client.cx : full.cx - (needV ? barWidth : 0);
      const auto height = unchanged ? client.cy : full.cy - (needH ? barHeight : 0);
      h = CalculateBarMetrics(width, XUnit, XRange, XTotalUnits, xMax, XPage, XPage);
      v = CalculateBarMetrics(height, YUnit, YRange, YTotalUnits, yMax, YPage, YPage);
    };
 
    // Determine which scroll bars are needed. Since a scroll bar only reduces the space available
    // in the other direction, the need for a scroll bar can only arise, never go away, as we
    // iterate. Hence this loop terminates after at most three iterations.
    //
    auto needH = false;
    auto needV = false;
    calculate(needH, needV);
    for (;;)
    {
      const auto nh = needH || (HasHScrollBar && h.IsScrollable());
      const auto nv = needV || (HasVScrollBar && v.IsScrollable());
      if (nh == needH && nv == needV) break;
      needH = nh;
      needV = nv;
      calculate(needH, needV);
    }
 
    XPage = h.Page;
    YPage = v.Page;
    if (HasHScrollBar) apply(SB_HORZ, h);
    if (HasVScrollBar) apply(SB_VERT, v);
 
    if (Window->GetClientRect().Size() == client) break;
  }
  WARN(pass == maxPassCount, _T("TScroller::SetSBarRange: Scroll bar layout did not settle."));
}
 
//
/// If TScroller_AutoOrg is true (default condition), BeginView automatically
/// offsets the origin of the logical coordinates of the client area by XPos, YPos
/// during a paint operation. If AutoOrg is false (for example, when the scroller is
/// larger than 32,767 units), you must set the offset manually.
//
void
TScroller::BeginView(TDC& dc, TRect& rect)
{
  long  xOrg = XPos * XUnit;
  long  yOrg = YPos * YUnit;
 
  if (AutoOrg && xOrg <= INT_MAX && yOrg <= INT_MAX) {
    TPoint offset(int(-xOrg), int(-yOrg));
    dc.SetViewportOrg(offset);
    rect -= offset;
  }
}
 
//
/// Updates the position of the owner window's scroll bars to be coordinated with
/// the position of the TScroller.
//
void
TScroller::EndView()
{
  if (Window) {
    if (HasHScrollBar) {
      int newPos = XPos;
      if (newPos != GetScrollPos(SB_HORZ))
        SetScrollPos(SB_HORZ, newPos, true);
    }
 
    if (HasVScrollBar) {
      int newPos = YPos;
      if (newPos != GetScrollPos(SB_VERT))
        SetScrollPos(SB_VERT, newPos, true);
    }
  }
}
 
//
/// Responds to the specified vertical scrollEvent by calling ScrollBy or ScrollTo.
/// The type of scroll event is identified by the corresponding SB_ constants.
/// The 16-bit thumbPos argument is ignored. The function retrieves the 32-bit value
/// directly from the scroll bar instead.
//
void
TScroller::VScroll(uint scrollEvent, int)
{
  switch (scrollEvent) {
    case SB_LINEDOWN:
      ScrollBy(0, YLine);
      break;
 
    case SB_LINEUP:
      ScrollBy(0, -YLine);
      break;
 
    case SB_PAGEDOWN:
      ScrollBy(0, YPage);
      break;
 
    case SB_PAGEUP:
      ScrollBy(0, -YPage);
      break;
 
    case SB_TOP:
      ScrollTo(XPos, 0);
      break;
 
    case SB_BOTTOM:
      ScrollTo(XPos, YRange);
      break;
 
    case SB_THUMBPOSITION:
      ScrollTo(XPos, GetScrollTrackPos(SB_VERT));
      break;
 
    case SB_THUMBTRACK:
    {
      int thumbPos32 = GetScrollTrackPos(SB_VERT);
      if (TrackMode)
        ScrollTo(XPos, thumbPos32);
      if (Window && HasVScrollBar)
        SetScrollPos(SB_VERT, thumbPos32, true);
      break;
    }
  }
}
 
//
/// Responds to the specified horizontal scrollEvent by calling ScrollBy or ScrollTo.
/// The type of scroll event is identified by the corresponding SB_ constants.
/// The 16-bit thumbPos argument is ignored. The function retrieves the 32-bit value
/// directly from the scroll bar instead.
//
void
TScroller::HScroll(uint scrollEvent, int)
{
  switch (scrollEvent) {
    case SB_LINEDOWN:
      ScrollBy(XLine, 0);
      break;
 
    case SB_LINEUP:
      ScrollBy(-XLine, 0);
      break;
 
    case SB_PAGEDOWN:
      ScrollBy(XPage, 0);
      break;
 
    case SB_PAGEUP:
      ScrollBy(-XPage, 0);
      break;
 
    case SB_TOP:
      ScrollTo(0, YPos);
      break;
 
    case SB_BOTTOM:
      ScrollTo(XRange, YPos);
      break;
 
    case SB_THUMBPOSITION:
      ScrollTo(GetScrollTrackPos(SB_HORZ), YPos);
      break;
 
    case SB_THUMBTRACK:
    {
      int thumbPos32 = GetScrollTrackPos(SB_HORZ);
      if (TrackMode)
        ScrollTo(thumbPos32, YPos);
      if (Window && HasHScrollBar)
        SetScrollPos(SB_HORZ, thumbPos32, true);
      break;
    }
  }
}
 
//
/// Scrolls the rectangle to the position specified in x and y after checking boundary conditions.
/// Causes a WM_PAINT message to be sent
///
/// First scrolls the contents of the client area, if a portion of the client
/// area will remain visible
//
void
TScroller::ScrollTo(long x, long y)
{
  PRECONDITION(Window);
  PRECONDITION(Window->GetHandle());
 
  if (Window && Window->GetHandle()) {
    long  newXPos = std::max(0L, std::min(x, long(XRange - XPage)));
    long  newYPos = std::max(0L, std::min(y, long(YRange - YPage)));
 
    if (newXPos != XPos || newYPos != YPos) {
      //
      // scaling isn't needed here. if condition is met, ScrollWindow()
      // will succeed since XPage and YPage are ints
      //
      // if condition isn't met, ScrollWindow() is called in EndScroll()
      // as a result of calling UpdateWindow()
      //
      // EndScroll() performs the necessary scaling
      //
      if (AutoOrg || (abs(YPos-newYPos) < YPage && abs(XPos-newXPos) < XPage))
        Window->ScrollWindow(static_cast<int>(XPos - newXPos) * XUnit,
                static_cast<int>(YPos - newYPos) * YUnit, nullptr, nullptr);
 
      else
        Window->Invalidate();
 
      XPos = newXPos;
      YPos = newYPos;
      Window->UpdateWindow();
    }
  }
}
 
//
/// IsAutoMode is true if automatic scrolling is activated.
//
bool
TScroller::IsAutoMode()
{
  return AutoMode;
}
 
//
/// Performs "auto-scrolling" (dragging the mouse from within the client
/// client area of the Window to without results in auto-scrolling when
/// the AutoMode data member of the Scroller is true)
///
/// Scrolls the owner window's display in response to the mouse being dragged from
/// inside to outside the window. The direction and the amount by which the display
/// is scrolled depend on the current position of the mouse.
//
void
TScroller::AutoScroll()
{
  PRECONDITION(Window);
  PRECONDITION(Window->GetHandle());
 
  if (AutoMode && Window) {
    TRect  clientRect;
    TPoint cursorPos;
    long  dx = 0, dy = 0;
 
    GetCursorPos(&cursorPos);
    Window->ScreenToClient(cursorPos);
    Window->GetClientRect(clientRect);
 
    if (cursorPos.y < 0)
      dy = std::min(static_cast<long>(-YLine), std::max(static_cast<long>(-YPage), long(cursorPos.y / 10 * YLine)));
 
    else if (cursorPos.y > clientRect.bottom)
      dy = std::max(static_cast<long>(YLine), std::min(static_cast<long>(YPage), long((cursorPos.y-clientRect.bottom)/10 * YLine)));
 
    if (cursorPos.x < 0)
      dx = std::min(static_cast<long>(-XLine), std::max(static_cast<long>(-XPage), long(cursorPos.x / 10 * XLine)));
 
    else if (cursorPos.x > clientRect.right)
      dx = std::max(static_cast<long>(XLine), std::min(static_cast<long>(XPage), (cursorPos.x-clientRect.right)/10 * XLine));
 
    ScrollBy(dx, dy);
  }
}
 
 
IMPLEMENT_STREAMABLE(TScroller);
 
#if OWL_PERSISTENT_STREAMS
 
//
// reads an instance of TScroller from the passed ipstream
//
void*
TScroller::Streamer::Read(ipstream& is, uint32 /*version*/) const
{
  TScroller* o = GetObject();
  is >> o->XPos >> o->YPos >>
      o->XUnit >> o->YUnit >>
      o->XRange >> o->YRange >>
      o->XLine >> o->YLine >>
      o->XPage >> o->YPage >>
      o->AutoMode >> o->TrackMode >>
      o->AutoOrg >>
      o->HasHScrollBar >> o->HasVScrollBar;
 
  o->Window = 0;
  return o;
}
 
//
// writes the TScroller to the passed opstream
//
void
TScroller::Streamer::Write(opstream& os) const
{
  TScroller* o = GetObject();
  os << o->XPos << o->YPos <<
      o->XUnit << o->YUnit <<
      o->XRange << o->YRange <<
      o->XLine << o->YLine <<
      o->XPage << o->YPage <<
      o->AutoMode << o->TrackMode <<
      o->AutoOrg <<
      o->HasHScrollBar << o->HasVScrollBar;
}
 
 
#endif
 
} // OWL namespace
 
/* ========================================================================== */