CGCStatusIndicator

Version 1.1

May 11, 2001

Developed By: George Chastain

All rights reserved.

Download Visual C++ 6.0 Project (Self-Extracting Exe)

I finally had time to finish this thing!

The CGCStatusIndicator is a CStatic-derived class is an excellent class for creating status indicators.  It allows the client to control the background color, the text color, whether or not a colored frame is placed around the control (and control the color of the frame), the font used for text in the control, and the point size of the text.

But it also supports the concept of an "on" or "set" state and an "off" or "unset" state to facilitate the use of the control as a status indicator.  Further, it supplies a set of flashing capabilities because many status indicators have different flash requirements.  

Specifically, CGCStatusIndicator provides the following capabilities:

• Define an On and an Off state. This class allows the client to create a static field of a specific color that never changes, or the client can define an ON/SET and and OFF/UNSET state by calling different interfaces to define different colors for the two states.
• Specify the color to be used for the background in the On/Set state.
• Specify the color to be used for the background in the Off/Unset state.
• Specify the color to be used for the text in the On/Set state.
• Specify the color to be used for the text in the Off/Unset state.
• Specify a bitmap pattern to use for the background's On/Set state.
• Specify a bitmap pattern to use for the background's Off/Unset state.
• Specify a hatch pattern to use for the background.
• Define the font to use for the text.
• Bold face text.
• Italic text.
• Underline text.
• Symmetrical Background Flashing of the Background color between ON/SET and OFF/UNSET states (on and off background color). This flash mode makes the duration of the "off" state the same as the duration of the "on" state -- hence the name "symmetrical flashing".
• Asymmetrical Background Flashing of the Background color between ON/SET and OFF/UNSET states.  This flash mode allows the client to set the duration of the "on" and "off" states to different time lengths. For example, the control can remain in the "ON" state for 2 seconds and off 1 second. Any duration may be defined by the client for either state.
• Pulsed Background Flashing of the Background color between ON/SET and OFF/UNSET states.  This flash mode allows the client to set a sequence of symmetrical flashes of a specified duration, followed by a steady "on" state for a client-specified amount of time. For example, the client could have the control flash 4 quick times followed by a longer, "on" state, followed by 4 more quick flashes, and so on.
• Text Only Flashing between between ON and OFF states (on and off text colors).  Flashing text is mutually exclusive of flashing background.  
• Display a colored frame around the control.
• Specify the color of the colored frame when using one.
  

Remember that the background has two states "on" and "off" and the text has two states "on" and "off".  Each state of the background may have a different color associated with it and each state of the text may have a different text color associated with it.  When using either of the following flash modes:

• Symmetrical-Background Flashing
• Asymmetrical-Background Flashing
• Pulsed-Background Flashing

the text state will be forced to be synchronized with the background state.  So when the background is displaying the "on" state the text is displaying the "on" state.  Similarly, when the background is displaying the "off" state, the text is displaying the "off" state.   This is per design in keeping with the concept of a status or state indicator that can distinguish between different states or conditions.

The "Text Only Flashing" mode allows the client to depart from the behavior described above.  The client can flash the text only between its "on" and "off" state without affect the state of the background.  The background will continue to indicate the state it was in when the text flashing was initiated.

With all types of flashing, the client may specify the final state desired when the flashing is terminated. In many cases with status indicators, it is desired that the indicator flash for some period of time and then remain in a specific state. This class provides a convenient way of ensuring that it is left in either the "on" or "off" state as specified by the client when flashing was initiated.

If the client is using the Symmetrical-, Asymmetrical- or Pulsed-Background Flashing modes, and the final state specifies that the control is to be left in the "ON" state, then when flashing is terminated, the background will indicate the "ON" state and the text will indicate its "ON" state.  Similarly, if the final state specifies that the control is to be left in the "OFF" state, then the background will indicate the "OFF" state and the text will indicate its "OFF" state when the flashing is terminated.  When using the Text Only Flashing mode, the text will be left in the appropriate state and the background will continue to indicate the state that it was in before the text flashing was initiated.

When using a colored frame, the client may specify a color for use with the frame that is independent of the other colors used by the control.

The CGCStatusIndicator control class also supports the creation of a status control in various shapes:

• Rectangle
• Rounded Rectangle
• Ellipse
• Triangle
• Left-Pointing Triangle
• Right-Pointing Triangle
• Inverted Triangle
• Upward-pointing Arrow
• Downward-pointing Arrow
• Left-pointing Arrow
• Right-pointing Arrow
• Diamond
• Octagon

All capabilities for controlling colors and states described above are available when using either of the shapes.

The text, if used, may be displayed in the typical, horizontal orientation, or it may be rotated to left 90 degrees or to the right 90 degrees.

The client may also specify a brush pattern to use for the background.  Separate patterns may be specified for the "on" and "off" states or the client may use a pattern for one state and a solid color for the other.  The choice is yours.

The class provides the following public color definitions:

• DEFAULT_BACKGROUND_ON_COLOR -- Default background ON state.
• DEFAULT_BACKGROUND_OFF_COLOR -- Default background OFF color.
• DEFAULT_TEXT_ON_COLOR -- Default text ON color.
• DEFAULT_TEXT_OFF_COLOR -- Default text OFF color.
• DEFAULT_COLOR_FRAME_COLOR -- Default color frame color.
  

The class provides the following style constants:

• GC_RECTANGLE
• GC_ROUNDED_RECTANGLE
• GC_ELLIPSE
• GC_OCTAGON
• GC_DIAMOND
• GC_TRIANGLE
• GC_INV_TRIANGLE
• GC_LEFT_TRIANGLE
• GC_RIGHT_TRIANGLE
• GC_LEFT_ARROW
• GC_RIGHT_ARROW
• GC_UP_ARROW
• GC_DOWN_ARROW

The class defines the following text orientation constants:

• GC_LEVEL
• GC_LEFT_90_DEGREES
• GC_RIGHT_90_DEGREES

Public Methods

BOOL Style(const GC_STYLE_TYPE style, 
           const GC_ORIENTATION_TYPE TextOrientation);

Style() allows the client to change the shape and text orientation of the status indicator by combining styles as appropriate.

BOOL ShowFrame(const BOOL bOn,
               int Width,
               COLORREF FrameColor);

ShowFrame() allows the client to use a colored frame around the control, specifying the width and the frame color.

BOOL SetOn(const BOOL bOn = TRUE);

If bOn is TRUE, sets the control's background color to the
background's ON color (as specified by a call to SetBackgroundOnColor()),
and the text color to the text's ON color (as specified by a call
to SetTextOnColor()).
If bOn is FALSE, it sets the control's background color to the
background's OFF color (as specified by a call to SetBackgroundOffColor()),
and the text color to the text's OFF color (as specified by a call to
SetTextOffColor()).
Returns previous state.

COLORREF SetBackgroundOnColor(const COLORREF backColor = DEFAULT_BACKGROUND_ON_COLOR);

SetBackgroundOnColor() -- Sets new background color. Returns previous 
background color. This color is used as the "on" color when flashing 
the background. If the previous "on" color was a pattern, then 
DEFAULT_BACKGROUND_ON_COLOR is returned as the previous color.

COLORREF SetBackgroundOffColor(const COLORREF offColor = DEFAULT_BACKGROUND_OFF_COLOR);

SetBackgroundOffColor() -- Used to define the "off" color used 
when flashing the background color of the control. Returns the 
previous "off" color. If the previous "off" color was a pattern, then 
DEFAULT_BACKGROUND_OFF_COLOR is returned as the previous
color.

COLORREF SetBackgroundOnPattern(CBitmap* pattern);

SetBackgroundOnPattern() -- Used to set the "on" background color to 
the specified pattern. Returns the previous color. If the previous 
"on" background color was a pattern,then DEFAULT_BACKGROUND_ON_COLOR
is returned as the previous color.

COLORREF SetBackgroundOffPattern(CBitmap* pattern);

SetBackgroundOffPattern() -- Used to set the "off" background color to 
the specified pattern. Returns the previous color. If the previous 
"off" background color was a pattern,then DEFAULT_BACKGROUND_OFF_COLOR
is returned as the previous color.

BOOL SetHatch(const BOOL bOn = TRUE, 
              const UINT HatchType = HS_VERTICAL);

SetHatch() -- Sets the control the use a Hatch Pattern.
The control will utilize the color set by a call to 
SetBackgroundOnColor() as the color of the hatch pattern. 
The color set by a call to SetBackgroundOffColor()
is used to fill in the area between the lines in the hatch pattern.
The HatchType parameter may be set to any of these Windows-defined patterns:

HS_BDIAGONAL Downward hatch (left to right) at 45 degrees
HS_CROSS Horizontal and vertical crosshatch
HS_DIAGCROSS Crosshatch at 45 degrees
HS_FDIAGONAL Upward hatch (left to right) at 45 degrees
HS_HORIZONTAL Horizontal hatch
HS_VERTICAL Vertical hatch

COLORREF SetTextOnColor(const COLORREF textColor = DEFAULT_TEXT_ON_COLOR);

SetTextOnColor() -- Sets new text color. Returns previous text color.

COLORREF SetTextOffColor(const COLORREF offColor = DEFAULT_TEXT_OFF_COLOR);

SetTextOffColor() -- Set the text's OFF color.

COLORREF GetBackgroundOnColor() const;

GetBackgroundOnColor() -- Returns the current background ON 
color as a COLORREF value.
If the current background "on" color is a pattern, the returned color
will be black (0).

void GetBackgroundOnColor(BYTE& Red, BYTE& Green, BYTE& Blue) const;

GetBackgroundOnColor() -- Returns current background ON color as 
separate red, green and blue components.
If the current background "on" color is a pattern, the returned color
will be black (0,0,0).

COLORREF GetBackgroundOffColor() const;

GetBackgroundOffColor() -- Returns the current background OFF 
color as a COLORREF value.
If the current background "off" color is a pattern, the returned color
will be black (0).

void GetBackgroundOffColor(BYTE& Red, BYTE& Green, BYTE& Blue) const;

GetBackgroundOffColor() -- Returns current background OFF color as 
separate red, green and blue components.
If the current background "off" color is a pattern, the returned color
will be black (0,0,0).

void SetWindowText( LPCTSTR lpszString );

SetWindowText() -- Used to set/change the text displayed in the control.
See comments to this override in the implementation for details on why
this was overridden.

COLORREF GetTextOnColor() const;

GetTextOnColor() -- Returns the current text color as a COLORREF value.

COLORREF GetTextOffColor() const;

GetTextOffColor() -- Returns the OFF color for the text.

void GetTextOffColor(BYTE& Red, BYTE& Green, BYTE& Blue) const;

GetTextOffColor() -- Returns the OFF color for the text as separate red, 
green, and blue components.

void GetTextOnColor(BYTE& Red, BYTE& Green, BYTE& Blue) const;

GetTextOnColorRGB() -- Returns the current text color as separate RGB values.

BOOL TextOn(const BOOL bOn = TRUE);

TextOn() -- Allows manual setting of the text to the ON or OFF state.
If bOn == TRUE, text is displayed in the text's "ON" color. If bOn == FALSE,
the text is displayed in the text's "OFF" color.
Returns previous state.

Note using this interface places the on/off state of the text and 
the on/off state of the background out of sync. If the client does not 
need an "on"/"off" condition, this is ok.  Note however, that when 
the FlashBackground() or the FlashText() methods are called, 
the on/off states are resynced automatically by those methods.

BOOL FlashBackground(const BOOL bFlash, 
                     const BOOL bFinalState = TRUE,
                     const float duration = 1.0); // Default 1 second

FlashBackground() -- Flashes the background of the static text field.
bFlash -- TRUE if you want to flash it. FALSE to stop it.
duration -- Interval of flash in seconds that you want to flash it. 
If you want to flash at a rate of say once every half-second,
set duration to 0.5.
bFinalState -- When turning the flash off (that is, when bFlash is FALSE), 
this flag forces the background to be left in the desired 
"on" (TRUE) or "off" (FALSE) state. The default is to leave it "on".
This also forces the text to be in the same state, keeping
the on/off state of the text in sync with the on/off state of 
the background.
The color specified by a call to SetBackgroundOnColor() is used as 
the "on" state color. The "off" state color is set by a call to 
SetBackgroundOffColor(). Returns TRUE if successful.
 
Flashing the background does NOT affect the hatch color if the control 
has been set to Hatch Mode by a call to the SetHatch() method. The 
hatch pattern will ALWAYS utilize the background's ON color. When the 
background flashes, as the background changes to the ON state, it will 
appear as if the hatch pattern vanishes and then reappears as the control's 
background transitions to the OFF state.

BOOL FlashBackgroundAsym(const BOOL bFlash, 
                         const BOOL bFinalState = TRUE,
                         const float OnDuration = 1.0, // Default 1 second
                         const float OffDuration = 0.5); // Default 0.5 second

FlashBackgroundAsym() -- Flashes the background of the static text field
asymmetrically. That is, the client may specify an "ON" time and and "OFF" 
time. The background will flash with the "ON" state displayed for OnDuration
time followed by the "OFF" state for the OffDuration time. Both OnDuration
and OffDuration parameters are specified in seconds. The bFinalState parameter
is used in exactly the same way as for the FlashBackground() method above.
The colors are treated in the same manner as for FlashBackground() 
defined above.
 
Flashing the background does NOT affect the hatch color if the control 
is been set to Hatch Mode by a call to the SetHatch() method. The 
hatch pattern will ALWAYS utilize the background's ON color. When the 
background flashes, as the background changes to the ON state, it will 
appear as if the hatch pattern vanishes and then reappears as the 
control's background transitions to the OFF state.

BOOL FlashBackgroundPulsed(const BOOL bFlash, 
                           const BOOL bFinalState = TRUE,
                           const float pulseDuration = 0.5, 
                           const int pulseRep = 4, 
                           const float onDuration = 2.0);

FlashBackgroundPulsed() -- Used to Pulse Flash the background of the 
static control. For example, you could flash the background 4 quick times 
and then hold in the "on" state for a longer period of time then flash 4 
quick times again and so on.
 
bFlash -- TRUE if you want to flash it. FALSE to stop it.
pulseDuration -- Interval of flash in seconds at which you wish to 
flash the pulsed sequence. 
If you want to pulse-flash at a rate of say once every 
half-second, set duration to 0.5.
pulseRep -- The number of times (repititions) at which you want 
the pulse flash to occur.
onDuration -- The number of seconds the control is to remain in 
the "on" state before repeating the pulse sequence.
bFinalState -- When turning the flash off (that is, when bFlash is FALSE), 
this flag forces the background to be left in the desired 
"on" (TRUE) or "off" (FALSE) state. The default is to 
leave it "on". This also forces the text to be in the 
same state, keeping the on/off state of the text in 
sync with the on/off state of the background.

The color specified by a call to SetBackgroundOnColor() is used as the 
"on" state color. The "off" state color is set by a call to 
SetBackgroundOffColor(). Returns TRUE if successful.

Flashing the background does NOT affect the hatch color if the control 
is been set to Hatch Mode by a call to the SetHatch() method. The 
hatch pattern will ALWAYS utilize the background's ON color. When the 
background flashes, as the background changes to the ON state, it will 
appear as if the hatch pattern vanishes and then reappears as the control's 
background transitions to the OFF state.

BOOL FlashText(const BOOL bFlash, 
               const BOOL bFinalState = FALSE,
               const float duration = 1.0); // Default 1 second.

FlashText() -- Flashes the text between the text's ON color and its OFF color.
You could make the OFF color of the text the same as the currently displayed
color of the background (typically the ON color) and the text would flash
on/off screen.
Returns TRUE if successful. Note that, unlike the bFinalState parameter 
used by the FlashBackground() and FlashBackgroundAsym() methods, the
value of bFinaState here applies ONLY to the final state of the text.
That is, the text could be left in the "ON" state while the background is
in the "OFF" state if that is what is desired. 
Flashing of the text has no affect on the background color or the background's
hatch pattern if the control was set to Hatch Mode by a call to the 
SetHatch() method.

void GetStates(BOOL& bBackgroundState, BOOL& bTextState) const;

GetStates() -- Gets the current state of the background and the text.
If bBackgroundState == TRUE, the background color is set to its
"ON" or "SET" color state.
If bTextState == TRUE, the text color is set to its
"ON" or "SET" color state.
 
Note that since the FlashText() method allows the
client to get the on/off state of the text color
out of sync with the background color, it is possible for
GetStates() to return different states for the background and
the text if FlashText() has been in use.
The client can call SetOn() with the appropriate flag to
resync the on/off states of the text and background colors.
Further, calling FlashBackground(), FlashBackgroundAsym(),
or FlashBackgroundPulsed() will also resync the background
and text color states.

void SetBold(const BOOL On = TRUE);

SetBold() -- Sets the text to boldface or normal. Not, the font weight is
set to 400 (normal) if On = FALSE or to 700 (bold) if On = TRUE.
All other font attributes are unchanged.

void SetItalic(const BOOL On = TRUE);

SetItalic() -- Sets the text to italic.  All other font attributes are unchanged.

void SetUnderline(const BOOL On = TRUE);

SetUnderline() -- Sets the text to underline.  All other font attributes are unchanged.

BOOL SetPointFont(const int PointSize, const LPCTSTR fontname);

SetPointFont() -- Allows the client to set the font for the control 
by specifying the point size and the font name.
Returns TRUE if successful.  With this method, previous settings for Underline, 
Italics and Text Orientation are maintained. 

BOOL SetFontIndirect(const LOGFONT* lpLogFont);

SetFontIndirect() sets the static control to use the specified font.
For a description of how to use the input parameter, refer to the 
MFC documentation for CFont::CreateFontIndirect().
Returns TRUE if successful.  With this method, all settings within the logical font structure override
the control's current settings.  For example, if the control's text is currently
underlined but the LOGFONT structure passed in does not specify underlining, 
then the control will no longer be underlined.

LOGFONT GetLogFont() const;

GetLogFont() -- Returns the current font for the control as a LOGFONT structure.

BOOL SetFontWeight(const int Weight);

SetFontWeight() -- More control that SetBold(). Use to set the font weight
from 1 to 1000. The actual affect of this call depends on the font in use.
Returns TRUE if successful.