Ctl32 ScrollableContainer


ctl32_scontainer: overview
By Carlos Alloatti and Malcolm Greene
Overview
This class provides a Scrollable Container control that can be used in VFP 9.
This class is not a replacement for a Grid! It may be viewed as a replacement for a Pageframe, where instead of having N pages one on top of the other, you have N pages one after the other, and you can only view one page at a time.
So, for the same reasons that you will not have a Pageframe with N pages as N records in a table, you should not have a ctl32_scontainer displaying N records from a table one after the other.
If you think that a Pageframe with N pages as records in a table is OK, please do not ask me how to achieve that with the ctl32_scontainer, I don't know.
It uses the Windows API to create true Windows common controls Scrollbars, full Themes compliance, just a couple of class files to add to your project, No DLLs, no FLLs, no OCXs.
This class uses BINDEVENT with the new features only available in VFP9. It will not work in previous versions of VFP. If you are using a previous version of VFP, you should really upgrade to take advantage of the many new features, and to support VFP.
Properties, Events & Methods
You can find a complete reference to all properties, events & methods of the class here.
Main Features
  • Visual design, drop control in a form, add a child control to it.
  • Supports mouse wheel vertical and horizontal scrolling, also mouse wheel zoom in/out in contained image control.
  • Supports click and drag scrolling.
  • Active control auto-scrolling, with configurable vertical and horizontal margin, when a control gets focus it scrolls into view.
  • Transparently participates in the form's normal tab order
  • Fully configurable behaviour: smallchange, largechange, wheelchange, always display scrollbars, display one, both or no scrollbars.
  • Scrollbars dissapear or get disabled when not needed.
  • Scroll boxes correctly report position and size of the visible area within the total contained control area.
  • Windows XP and Vista theme compliance.
  • Events and methods to implement your own scrolling controls.
  • Client control can be loaded dinamically using the class AddObject() or NewObject() methods.
Uses
  • Paning large images.
  • Create Explorer, Taskpane and other modern GUI interfaces.
  • Anywhere a general purpose container needs to scroll due to form or screen size.
Pictures

A scrollable container with a container control inside. You can tab thru the controls and get automatic scroll.

A scrollable container with an image control inside. You can zoom the image in/out with CTRL-MouseWheel.
Quick Start
If you want a ctl32_scontainer on a form, drag the ctl32_scontainer control from the Project Manager window and drop it into the Form.
How to add controls to the scrollable container:
Do not add multiple controls inside the scrollable container!
The scrollable container supports only one client control. Add a container or an image control.
For SIMPLE nested containers (or when working with an image control): make the scrollable container large, add a container with controls, or an image control, align it to the left and top of the scrollable container, then shrink the scrollable container to size.
For large or complex nested containers, create another container in a form, or as a class, and add your controls to that container. Then insert your container with controls into the scrollable container. If you used a Form, copy the container from that form, then control-click on the scrollable container and paste it. If you created a container class, control-click on the scrollable container, then drag and drop the container class from your project window (there are many other ways to do this)
Think of the scrollable container as a PageFrame that can have only one page, and of your own container as a Page. The hierarchy level for your controls will be the same as in a PageFrame-Page scenario.
The scrollable container will use the first control it contains, ignoring any other controls added to it, that is why is crucial that you use a container control, or just a single image control.
Using the PageFrame-Page analogy again, you can't also add controls directly to a PageFrame in VFP.
Videos

This is a quick flash video with no sound, to see how you can use the class.
Sample Project
See the sample project included in the Sample folder to see examples of how to use the control and what can be done.
BindEvent
This class does Bindevents to the following windows and window messages:
Thisform.HWnd, WM_KEYUP
Thisform.HWnd, WM_CAPTURECHANGED
Thisform.HWnd, WM_LBUTTONUP
If you hook to those same window/event pairs in some other part of your code, recall what the Help file says:
"When binding to Windows message (Win Msg) events, only one hWnd to Windows message pairing can exist."
Bugs
20060928
The sunken border will not display in versions of Windows previous to XP. This is due to a bug in the themes handling code in ctl32_SetTheme(). This is fixed in version 20061001
Known Problems
There is a bug in the way VFP draws the border of sunken frames when no theme is active:

This is the border of a VFP textbox.

This is the border of a VFP container, SpecialEffect set to Sunken. The colors of the border are mixed up.

At normal 100% view you can hardly notice, but I do! (Off Site Link)
There is a bug in VFP with PageFrames inside a Container control. Since the ctl32_scontainer is based on the VFP Container control class, it inherites this bug. The workaround is not to use a PageFrame control inside a ctl32_scontainer control. Anyway, the whole point of having a scrollable container is so you will not be forced to use a PageFrame when things don't fit in a form.

Page tabs of PageFrame control bleed thru when inside a Container
ActiveX components will have the same problems, they should not be used inside a scrollable container.
Remarks:
MouseWeel scrolls the client container up/down. Shift + MouseWheel scrolls the client container left/right.
If the client container is an image control, Ctrl + MouseWheel will zoom in/out on the image.
Double Click on the image will restore it to the original size.
I need help with the code to keep the image centered when zoomin in/out, that part is not finished yet.
Properties
 ctlAbout
Value Type: Character
Default Value: class name and author(s).
R/W: Read
Returns the name of the class and the name(s) of the programmer(s) that wrote it.

 ctlActiveScrollBars
Value Type: Numeric
Default Value: 0
R/W: Read
Specifies whether scrollbars are needed. It does not indicate if the scrollbars are visible. Can be used to control an optional scroll control
0 None
1 Horizontal
2 Vertical
3 Both

 ctlAutoCenter
Value Type: Logical
Default Value: .T.
R/W: Read/Write
Specifies whether the child control should be centered in the scrollable container when the scrollable container is bigger that the child control.

 ctlAutoScroll
Value Type: Logical
Default Value: .T.
R/W: Read/Write
Specifies if the control will autoscroll when contained controls get focus and are out of view.

 ctlBackColor
Value Type: Numeric
Default Value: -1
R/W: Read/Write
Specifies the background color. A value of -1 means to use default background color of textboxes.

 ctlBackStyle
Value Type: Numeric
Default Value: 1
R/W: Read/Write
Specifies if the background is transparent or opaque
0: Transparent
1: Opaque (Default)

 ctlBorderColor
Value Type: Numeric
Default Value: -1
R/W: Read/Write
Specifies the border color. A value of -1 means to use default border color of textboxes.

 ctlBorderStyle
Value Type: Numeric
Default Value: 1
R/W: Read/Write
Specifies if the control has a border:
0: No border
1: Border (Default)

 ctlForceScrollBars
Value Type: Numeric
Default Value: 0
R/W: Read/Write
Specifies whether scrollbars should be always visible. Visible scrollbars will be disabled when not needed.
0: None
1: Horizontal
2: Vertical
3: Both

 ctlHEnabled
Value Type: Logical
Default Value: .F.
R/W: Read
Specifies if the horizontal scrollbar is enabled or required.

 ctlHHWnd
Value Type: Numeric
Default Value: 0
R/W: Read
Returns a handle to the horizontal scrollbar control window.

 ctlHLargeChange
Value Type: Numeric
Default Value: -1
R/W: Read/Write
Specifies the increment an horizontal scrollbar scrolls when you click on the scrollbar track.
The Default Value of -1 means the viewport Width. If set to a value beetwen 0 and 1, the value represents a percentage of the viewport Width. When set to a value 1 or larger, the value is in pixels or foxels (see ScaleMode in VFP help).
Example: A value of 0.25 will scroll a distance equal to 25% of the viewport width.

 ctlHMargin
Value Type: Numeric
Default Value: 5
R/W: Read/Write
Specifies the horizontal margin to use when autoscrolling to the active control. The value is in pixels or foxels (see ScaleMode in VFP help).

 ctlHSmallChange
Value Type: Numeric
Default Value: 20
R/W: Read/Write
Specifies the increment an horizontal scrollbar scrolls when you click on a scroll arrow. The value is in pixels or foxels (see ScaleMode in VFP help).

 ctlHValue
Value Type: Numeric
Default Value: 0
R/W: Read/Write
Sets or returns the actual horizontal scroll value of the client control.

 ctlHVisible
Value Type: Logical
Default Value: .F.
R/W: Read
Specifies if the horizontal scrollbar is visible.

 ctlHWheelChange
Value Type: Numeric
Default Value: 40
R/W: Read/Write
Specifies the increment an horizontal scrollbar scrolls when you use the mouse wheel. The value is in pixels or foxels (see ScaleMode in VFP help).

 ctlScrollBars
Value Type: Numeric
Default Value: 3
R/W: Read/Write
Specifies which scrollbars should be visible if needed.
0: None
1: Horizontal
2: Vertical
3: Both

 ctlVersion
Value Type: Character
Default Value: class version information
R/W: Read
Returns version information about the class.

 ctlVEnabled
Value Type: Logical
Default Value: .F.
R/W: Read
Specifies if the vertical scrollbar is enabled or required.

 ctlVcxCommon 2006XXXX
Value Type: Character
Default Value: ctl32_common.vcx
R/W: Read/Write
Specifies the location and file name of the ctl32_common vcx file

 ctlVcxStructs 2006XXXX
Value Type: Character
Default Value: ctl32_structs.vcx
R/W: Read/Write
Specifies the location and file name of the ctl32_sctrucs vcx file

 ctlVersion
Value Type: Numeric
Default Value: Version number.
R/W: Read
Returns the version number of the class in the format YYYYMMDD, for example 20060925.

 ctlVHWnd
Value Type: Numeric
Default Value: 0
R/W: Read
Returns a handle to the horizontal scrollbar control window.

 ctlVLargeChange
Value Type: Numeric
Default Value: -1
R/W: Read/Write
Specifies the increment a vertical scrollbar scrolls when you click on the scrollbar track.
The Default Value of -1 means the viewport Height. If set to a value beetwen 0 and 1, the value represents a percentage of the viewport Height. When set to a value 1 or larger, the value is in pixels or foxels (see ScaleMode in VFP help).
Example: A value of 0.5 will scroll a distance equal to 50% of the viewport height.

 ctlVMargin
Value Type: Numeric
Default Value: 5
R/W: Read/Write
Specifies the vertical margin to use when autoscrolling to the active control. The value is in pixels or foxels (see ScaleMode in VFP help).

 ctlVSmallChange
Value Type: Numeric
Default Value: 20
Specifies the increment a vertical scrollbar scrolls when you click on a scroll arrow. The value is in pixels or foxels (see ScaleMode in VFP help).
Read/Write.

 ctlVValue
Value Type: Numeric
Default Value: 0
R/W: Read/Write
Sets or returns the actual vertical scroll value of the client control.

 ctlVVisible
Value Type: Logical
Default Value: .F.
R/W: Read
Specifies if the vertical scrollbar is visible.

 ctlVWheelChange
Value Type: Numeric
Default Value: 40
R/W: Read/Write
Specifies the increment a vertical scrollbar scrolls when you use the mouse wheel. The value is in pixels or foxels (see ScaleMode in VFP help).
 ctlZoom 2006XXXX
Value Type: Numeric
Default Value: 100
R/W: Read
Specifies the amount of present zoom a client image container has, as a percentage. 100% is normal size. The cient image size can be changed with Ctrl + MouseWheel.
Events

 ctlScrolled
Parameters: nDirection
Occurs when the client control is scrolled.
0: Up arrow on vertical scroll bar.
1: Down arrow on vertical scroll bar.
2: Vertical scroll bar in area above the scroll box.
3: Vertical scroll bar in area below the scroll box
4: Thumb has finished moving on vertical scroll bar.
5: Thumb is been draged on vertical scroll bar.
6: Top selected in context menu on vertical scroll bar.
7: Bottom selected in context menu on vertical scroll bar.
10: Left arrow on horizontal scroll bar.
11: Right arrow on horizontal scroll bar.
12: Horizontal scroll bar in area to the left of the scroll box.
13: Horizontal scroll bar in area to the right of the scroll box.
14: Thumb has finished moving on horizontal scroll bar.
15: Thumb is been draged on horizontal scroll bar.
16: Left border selected in context menu on horizontal scroll bar.
17: Right border selected in context menu on horizontal scroll bar.
Methods
 ctlDoScroll
Parameters: nDirection
0 Scroll Line up SmallChange
1 Scroll Line down SmallChange
2 Scroll Page up LargeChange
3 Scroll Page down LargeChange
4 No action
5 No action
6 Scroll Top
7 Scroll Bottom

10 Scroll Line left SmallChange
11 Scroll Line right SmallChange
12 Scroll Page left LargeChange
13 Scroll Page right LargeChange
14 No action
15 No action
16 Scroll Left
17 Scroll Right
The nDirection parameter is set up this way so it matches the nDirection parameter used in the Scrolled event.

 ctlRestoreSize 20061010
If the client control is an image control, this method will restore it to the original size, if the size has been changed by using the Ctrl-MouseWheel key combination. This method is fired by double-clicking in the client image control.
Note
All properties and methods with a name that starts with "ctl32_" are only for internal use by the class itself.



Change Log
2006XXXX
Now client controls can be added dinamically. Added code to AddObject() and NewObject() to remove actual client control when adding new object. Also added a BINDEVENT to EvtHandler_This_NewObject() This method is binded to AddObject and NewObject, and setups the environment for the new client control.
Changed the _ThemeStatus, _HostHWnd, _FormType functions in _util of ctl32_common. Eliminated all references to ThisForm, now the form is determined from the control that is passed as a parameter to this functions.
Changed the way _Util object is added to control, from newobject to addproperty, so it will not count as another control.
Added ctlVcxStructs and ctlVcxCommon, they specify the name/location of the ctl32_structs and ctl32_common classes.
Added a ctlZoom property that indicates the amount of zoom of the client image control. 100% is normal view.
The zoom routine has been changed to a nicer curve, from 0.1% to 3199.99% (maximum allowed by image control) The values are stored in ctl32_SetZoomLevels()
Still missing a decent routine for centering the image after zoom in/out
Set as hidden some methods that where public by mistake.
20061010
ctlOS() method removed, moved to _util of ctl32_common
Added ctlRestoreSize() method, restores image size to default size after size change by ctrl-mousewheel. Fired by double click on image.
20061001

Added ctlTheme() and ctlOS() methods. Bugs fixed.

No comments:

Post a Comment

Subscribe to: Posts (Atom)