GroupControl

Introduction

CGroupControl is a CButton-derived class which assists with the use of group boxes (i.e., buttons with the BS_GROUPBOX style). The CGroupControl makes it easy to enable/disable, show/hide, or move a group. No code is required in the group's parent, as this is done automatically whenever the group control itself is enabled/disabled, shown/hidden, or moved. The control also includes a mechanism to allow you to perform any action on each control in a group.

How to use it

Using the CGroupControl class is very straightforward. Follow the steps below to add one to an existing project.

1. After putting the source files (GroupControl.cpp and GroupControl.h) into the directory you wish to use them from, add the files to your Visual Studio project.
2. In the resource editor, add a group-box where you wish, and give it an ID other than its default IDC_STATIC.
3. In Class Wizard, add a member variable for your group-box control, selecting "Control" from the "Category" list, and selecting "CGroupControl" from the "Variable Type" list. (If CGroupControl does not appear in the list, you may need to delete your class wizard file (.clw) and regenerate it.)
4. That's all you have to do to take advantage of the enabling, showing, and moving functionality.

Documentation

The control has one function which iterates round its siblings to see if they lie within the boundary of the group box control. These are the items then acted upon by use of a callback function. The functionality included is for the handlers for WM_ENABLE, WM_SHOWWINDOW, and WM_WINDOWPOSCHANGING, but this can easily be extended to perform any action. The method of determining whether a control belongs to a group is described below, followed by a description of the callback mechanism.

Iteration

To determine whether a control belongs to a group, the group control iterates around its siblings, getting their positions, and simply testing to see if they lie within the boundary of the group box. There are a couple of options concerning this:

• Whether to include controls that are only partially within the group, i.e., overlapping.
• Whether to look at all controls, or only those whose tab order places them after the group box.

By default, the control will not include overlapped controls, and will look at all siblings. In order to change this behaviour, the following two functions may be used:

    void SetAllowOverlap(BOOL bAllowOverlap = TRUE);
void SetUseTabOrder(BOOL bUseTabOrder = TRUE);

If the UseTabOrder option is set, then the group will start by looking at its first sibling and stops iteration when it finds the first control not within its boundary. This will be slightly faster, but relies on having set the tab order correctly.

Control Actions

The callback function signature is:

    BOOL GroupControlActionFunc(CWnd*, LPARAM);

This is typedef'd to GROUPCONTROLACTIONFUNC.

The function used to iterate around the controls is:

    BOOL DoGroupControlAction(GROUPCONTROLACTIONFUNC pfnGCAF, LPARAM lParam = 0)

Calling this function, passing in the address of the callback function, will iterate around the group's controls and call the callback function for each of the controls, passing in a CWnd pointer to the control, and the lParam passed to DoGroupControlAction. The lParam is used to pass any relevant information to the callback functions.

As an example, the following code is the callback function used to implement the enabling/disabling of the group's controls:

static BOOL GroupControlActionFunc_Enable(CWnd* pCtrl, LPARAM lParam)
{
if (pCtrl == NULL)
return TRUE;
BOOL bEnable = (BOOL)lParam;
pCtrl->EnableWindow(bEnable);
return TRUE;
}

This is invoked by the following call to DoGroupControlAction:

    DoGroupControlAction(GroupControlActionFunc_Enable, bEnable);

Here, the lParam is simply used to specify whether to enable or disable the controls.

It is possible to set the group control to ignore its controls and not carry out any action on them, by calling the IgnoreControls() function, passing in TRUE. This causes the group control to act as a normal group control. This is especially useful if other child controls move all their siblings, as with Peter Mares' CKCSideBannerWnd banner control.

Functions

The public functions in the class are as follows:

• CGroupControl();

  Standard empty constructor

• BOOL Create(LPCTSTR lpszCaption, DWORD dwStyle, const RECT &rect, CWnd *pParentWnd, UINT nID);

  Creates the control. This is identical to CButton::Create() with the addition of checking that the style is correct for a group box.

• BOOL IsInGroup(CWnd* pCtrl, BOOL& bOverlapped);

  Can be used to determine if any control belongs to a group. The function returns TRUE if any part of the control is within the boundary of the group. If only part of the control is within the group, then bOverlapped is set to TRUE.

• BOOL DoGroupControlAction(GROUPCONTROLACTIONFUNC pfnGCAF, LPARAM lParam = 0);

  This function can be used to iterate around the group's controls, and perform an action on each item. pfnGCAF is a callback function called for each item, passing it a CWnd pointer representing the control. lParam is an application defined value passed into the callback function. Note that calling this function has no effect on the controls if the group control is set to ignore its controls.

• void SetUseTabOrder(BOOL bUseTabOrder = TRUE);

  If bUseTabOrder is TRUE, this causes the group to iterate around controls, starting from the first sibling after the group, and ending with the last control which is within the group's boundary. If bUseTabOrder is FALSE, the group will look at all sibling controls.

• void SetAllowOverlap(BOOL bAllowOverlap = TRUE);

  If bAllowOverlap is TRUE, then the group will consider a control as belonging to the group if any part of the control is within the group's boundary. If bAllowOverlap is FALSE, the whole control must lie inside the group's boundary to belong to the group. This only applies when iterating around the controls.

• BOOL GetUseTabOrder();

  Returns whether iteration uses the control tab order.

• BOOL GetAllowOverlap();

  Returns whether overlapping controls are considered to belong to the group.

• void IgnoreControls(BOOL bIgnore = TRUE);

  Causes the group to act as a normal group box, and not do actions on controls within the group. Note that this has no effect on the behaviour of the IsInGroup() function.

• BOOL ControlsIgnored() const;

  Returns whether the group is set to ignore its controls.

History

• Version 1.1 - 17 Feb 2005
  • Added method "IgnoreControls" to allow the group box to be moved/sized etc. without the controls within the group doing the same, i.e., causes the group control to act as a normal group control. This is useful if other child controls move all their siblings as with Peter Mares' CKCSideBannerWnd banner control.
• Version 1 - 24 Jul 2002 - First version.