Table of Contents
Navigation: Language Reference > 9 - Window and Report Attributes > Window and Report Attributes >STATUS INTERFACES | |
(Coming in a future release)
The Status bar implementation exposes a set of 3 interfaces:
IStatusZone: gives access to the properties of a particular zone; there are 3 extended interfaces derived from it for Text, Image and Progress zones - ITextZone, IImageZone and IProgressZone
IStatusStyle: represents an instance of the style for the Status bar
IStatusBar: represents an instance of the Status bar object
The Status bar object manages the list of zones. The style can be applied to a status bar to change its appearance.
Supported Properties:
1) PROP:StatusInterface - is used to get a reference to the WINDOW's status bar object
2) PROP:StatusStyle - a SYSTEM property to get the reference to the default status style object
Both properties are read-only but the returned objects can be modified.
When the Status bar object is created because of OPENing a WINDOW with the STATUS attribute, or by setting the PROP:Status property to a WINDOW without a Status bar, the current default style is used to set up the bar's appearance. The Status bar uses its own copy of the style data. Therefore changes in the default style do not affect existing status bars automatically. The current bar's style can be changed by a call to the IStatusBar.ApplyStyle method.
Because one instance of the status bar object can be shared by more than one WINDOW, there is no method to destroy an instance of the IStatusBar interface. For backward compatibility, the status bar of a WINDOW can be destroyed by specifying a zero width for the first zone using the PROP:Status property:
Window {PROP:Status, 1} = 0
The initial state of the default status Style object mimics the traditional Status bar's appearance. The only visual difference are the use of different RGB values for the colors used to draw the Status bar's upper border and the zones bevels.
All of the Status bar interfaces can be found in the file CWSTATUS.INT located in the LIBSRC\WIN Folder.
Interfaces
IStatusZone INTERFACE,COM
GetKind PROCEDURE(),SIGNED
Returns numeric value of zone's type as they are listed in the StatusZoneKind ITEMIZE structure
StatusZoneKind ITEMIZE(0),PRE(STATUSZONE)
TEXT EQUATE
IMAGE EQUATE
PROGRESS EQUATE
END
GetWidth PROCEDURE(BOOLEAN),SIGNED
Changes the unadjusted width of the zone. Rules are the same as for value passed to the PROP:Status property. The unadjusted width is given in zone's dialog units and does not include zone margins and the optional separator.
If the value is negative, the zone is expandable with minimum width (in dlu's) equal to the absolute value of the passed number. By default, when A zone is created its unadjusted width is set equal to -1. For text zones dialog units are determined by the font used to draw text in that zone. For zones of other kinds,dialog units are determined by the font from the Status bar's style.
HasBevel PROCEDURE(),BOOLEAN
Returns TRUE if a bevel is present around the content part of the zone, and FALSE if no bevel is present.
SetBevel PROCEDURE(SIGNED) ! Parameter: StatusFlagValue
Modifies zone's flag controlling the drawing of the bevel around content area. The passed parameter must be one of the values listed in the StatusFlagValue ITEMIZE structure:
- STATUSFLAG:OFF - do not draw the bevel
- STATUSFLAG:ON - draw the bevel
- STATUSFLAG:DEFAULT - drawing of the bevel is determined by the Status bar's Style
Default value is STATUSFLAG:DEFAULT.
HasSeparator PROCEDURE(),BOOLEAN
Returns TRUE if separator is drawing at the far edge of the zone and FALSE if no separator is drawn
SetSeparator PROCEDURE(SIGNED) ! Parameter: StatusFlagValue
Modifies zone's flag controlling the drawing of the separator. Passed parameter must be one of values listed in the StatusFlagValue ITEMIZE structure:
- STATUSFLAG:OFF - do not draw the separator
- STATUSFLAG:ON - draw the separator
- STATUSFLAG:DEFAULT - drawing of the separator is determined by the Status bar's style.
Default value is STATUSFLAG:DEFAULT.
If the last zone has the separator flag equal to STATUSFLAG:DEFAULT, the separator is not drawn regardless of the style settings.
ITextZone INTERFACE(IStatusZone),COM
GetText PROCEDURE(),STRING
Returns the current text of the zone. The returned value can be passed to the ToString function to convert it to a STRING type.
SetText PROCEDURE(<;STRING>)
Changes the text displayed in the zone. Default value is an empty string.
GetAlignment PROCEDURE(),SIGNED ! Result: StatusAlignValue
Returns the numeric value of text alignment as they are listed in the StatusAlignValue ITEMIZE structure. The STATUSALIGN:DEFAULT and STATUSALIGN:LEFT values are
equivalent.
! Alignment of text in text zones
StatusAlignValue ITEMIZE(0),PRE(STATUSALIGN)
DEFAULT EQUATE
LEFT EQUATE
RIGHT EQUATE
CENTER EQUATE
END
SetAlignment PROCEDURE(SIGNED) ! Parameter: StatusAlignValue
Changes the text alignment in the zone content area. Default value is STATUSALIGN:DEFAULT
GetIndent PROCEDURE(),SIGNED
Returns the value of text indentation in pixels relative to the base point determined by current alignment.
SetIndent PROCEDURE(SIGNED)
Changes text indent value to the passed value, counted in pixels. Default value is 0.
GetFont PROCEDURE(),*IFontProperties
Returns an instance of the IFontProperties interface allowing to modify parameters of the font used to draw text in the zone. A NULL result means that the zone is using the font specified by the Status bar's style.
SetFont PROCEDURE(<;*IFontProperties>)
Changes the font used to draw text in the zone.Default value is NULL, indicating to use the font from the Status bar's style.
* Notes: The IFontDescription interface does not have public methods to clone and destroy instances. ITextZone.SetFont automatically releases the previous zone's font (unless it is NULL), clones the passed font (unless it is NULL) and assigns it to the zone. The expected flow of work with a zone's font is as follows: ZoneFont &= BarStyle.GetFont() ! Get the font from style Zone.SetFont (ZoneFont) ! Set the clone of font to zone ZoneFont &= Zone.GetFont() ! Get the reference to cloned font …. code to modify font … Zone.FontChanged() ! Notify zone that font changed GetTextColor PROCEDURE(),COLORREF Returns the color used to draw text in the zone. If the zone has its own font, the returned value is equal to result of call to IFontProperties.FontColor() for this font. If the zone is using the default font from the bar's style, the text color can be changed separately. In this case, GetTextColor() returns that color value. SetTextColor PROCEDURE(COLORREF) Sets/changes color used for drawing text. If the zone has its own font, this function has the same effect as a call to the font's IFontProperties.FontColor(newcolor) method. If the zone is using the default font from the bar's style, this function can be used to change text color in the zone while retaining all other characteristics of the default font. FontChanged PROCEDURE() This method must be called to notify the zone that its font has been changed by calls to methods of the IFontPropertiesinterface returned by the GetFont function. —- IImageZone INTERFACE(IStatusZone),COM GetImage PROCEDURE(),STRING Returns the name of the image drawn in the zone. Returned value can be passed to the ToString function to convert it to STRING type. SetImage PROCEDURE(<;STRING>) Sets/changes the image displayed in the zone. Default value is NULL which means that zone remains blank. * Notes:
If the width of zone is greater than the width of the image, the image is drawn left aligned in the the zone content rectangle (right-aligned in case of right-to-left window layout). If width of the zone is less or equal to the width of the image, the image is drawn centered in the zone content rectangle.
GetDrawMode PROCEDURE(),SIGNED ! Result: StatusImageMode
Returns the numeric value of the image drawing mode as they are listed in the StatusImageMode ITEMIZE structure.
! Modes of drawing images in image zones
StatusImageMode ITEMIZE(0),PRE(STATUSIMAGE)
NORMAL EQUATE
DISABLED EQUATE
GRAYED EQUATE
END
SetDrawMode PROCEDURE(SIGNED) ! Parameter: StatusImageMode
Changes the mode to draw zone image. Parameter must be one of values listed in the StatusImageMode ITEMIZE structure. Default value is STATUSIMAGE:NORMAL.
IProgressZone INTERFACE(IStatusZone),COM
GetValue PROCEDURE(),LONG
Returns the current progress value.
SetValue PROCEDURE(LONG)
Changes the current progress value.
GetMin PROCEDURE(),LONG
Returns the lower bound for progress value.
GetMax PROCEDURE(),LONG
Returns the upper bound for progress value.
SetRange PROCEDURE(LONG lo, LONG hi)
Changes the lower and upper bounds for the progress value. Default range is 0..100
GetColor PROCEDURE(),COLORREF
Returns the color used to draw the progress bar.
SetColor PROCEDURE(COLORREF)
Changes the color to draw the progress bar.
* Notes: If the progress zone has a bevel, the bevel is used as the frame for the progress bar. If the zone does not have a bevel, additional lines are drawn to show the unfilled part of the progress bar. —- Clone PROCEDURE(),*IStatusStyle Returns a cloned copy of the style object. Destroy PROCEDURE() Destroys the style object. The Destroy method mustbe called for all style objects returned from calls to IStatusStyle.Clone methods. CreateBar PROCEDURE(*WINDOW),*IStatusBar Creates the status bar object for the passed WINDOW using the style determining by SELF. The previous WINDOW's status bar object is disposed. It is not recommended to use this function for the active MDI child window. Created status bar has no zones and is frozen. Apply PROCEDURE(<;*IStatusStyle>) Copies information from one style object to another. Can be used for “atomic” changing of the system default status style. GetMetric PROCEDURE(SIGNED),SIGNED ! Parameter: StatusMetric Returns the value for the given style metric. Parameter must be one of values listed in the StatusMetric ITEMIZE structure. Supported metrics are: STATUS:HMARGIN - margin from the status bar edge to the first zone and if the resize gripper is drawn, from the last zone to the status bar edge. Default value is 4. STATUS:ZONEHMARGIN - Horizontal margins around the zone content rectangle. Default value is 4. STATUS:ZONEVMARGIN - Vertical margins above and below the zone content rectangle. Default value is 2. STATUS:TEXTHMARGIN - Horizontal margins around the text bounding rectangle in text zones. Default value is 2. STATUS:TEXTVMARGIN - Vertical margins above and below the text bounding rectangle in text zones. Default value is 0. STATUS:TEXTINDENT - indentation of text relatively the base point (determined by text alignment) in the text bounding rectangle. Default value is 0. STATUS:SEPMARGIN - margins above and below the zones' separator line. Default value is 2. *Notes: All returned values are in pixels.
SetMetric PROCEDURE(SIGNED, SIGNED) ! 1st Parameter: StatusMetric
Changes the given style metric. The first parameter must be one of values listed in the StatusMetric ITEMIZE structure.
GetHeight PROCEDURE(BOOLEAN = FALSE),SIGNED
Returns the height in pixels of the status bar determined by the style. If the parameter value is FALSE, the function returns the value set by last call to the SetHeight method. If parameter is TRUE, the function returns adjusted height value. Adjusted height is maximum of GetHeight(FALSE)
and height calculated from the style's font and metrics.
SetHeight PROCEDURE(SIGNED)
Changes the unadjusted height for styled status bars. Passed value must be in pixels. Default value is 0, i.e. the adjusted height is determined by the font and metrics.
BkgndBrush PROCEDURE(),*IBrush
Returns the instance of the IBrush interface used to draw the Status bar's background. If IBrush.Type is CWBrush_Null (default), the background is painted using the COLOR:BTNFACE color.
GetFont PROCEDURE(),*IFontProperties
Returns the instance of the IFontProperties interface used as the default font for Text zones.
SetFont PROCEDURE(<;*IFontProperties>)
Sets/changes the style's default font. If the passed parameter is NULL (default), the font specified by SYSTEM properties is used.
GetTextColor PROCEDURE(),COLORREF
Returns the default color used to draw text in Text zones.
SetTextColor PROCEDURE(COLORREF)
Changes the default color used to draw text in Text zones. If the passed value is COLOR:None, the color returned by
SYSTEM{PROP:FontColor + PROP:StatusFont} is used.
GetProgressColor PROCEDURE(),COLORREF
Returns the default color used to draw Progress bars in progress zones.
SetProgressColor PROCEDURE(COLORREF)
Changes the color used to draw Progress bars in progress zones.
GetSeparatorColor PROCEDURE(),COLORREF
Returns the color used to draw flat separator lines.
SetSeparatorColor PROCEDURE(COLORREF)
Sets/changes the color used to draw flat separator lines.
HasZoneBevel PROCEDURE(SIGNED),BOOLEAN ! Parameter: ZoneKind
Returns the default value of the flag to draw a bevel around the content rectangle for zones of a given kind.
SetZoneBevel PROCEDURE(SIGNED, BOOLEAN) ! 1st Parameter: ZoneKind
Changes default value of the flag to draw the bevel around the content rectangle for zones of the kind given by the first parameter.
Default value is TRUE for text zones and FALSE for image and progress zones.
GetFlag PROCEDURE(SIGNED),BOOLEAN ! Parameter: StatusStyleFlag
Returns value of the style flag corresponding to passed parameter. Parameter must be one of the values listed in the StausStyleFlag ITEMIZE structure:
STATUS:THEMED - if TRUE, and themes are available for the program (has a manifest), some metrics and visual aspects are determined by the visual theme rather than by values set in the style. If the flag is FALSE, the style does not use the visual theme.
STATUS:SEPARATOR - if TRUE, the separator line is drawn after every zone except the last one by default. If the flag is FALSE (default), separators are not drawn unless this setting is overridden in a particular zone.
STATUS:GRIPPER - If TRUE, the resize gripper is drawn in the lower-far corner of status bars owned by resizable not-maximized WINDOWs. If flag is FALSE (default), the gripper is not drawn.
STATUS:BORDER3D - If TRUE, the status bar's upper edge is drawn using a bevel. If the flag is FALSE, a flat border is drawn. The flag only affects un-themed status bars using solid colors to paint the bar's background. The flat border is drawn in all other cases.
STATUS:SEPARATOR3D - If TRUE, separator lines are drawn using a bevel. If the flag is FALSE, the separator line is drawn flat. The flag is ignored for themed status bars.
SetFlag PROCEDURE(SIGNED, BOOLEAN) ! 1st Parameter: StatusStyleFlag
Changes the value of the style flag corresponding to the passed first parameter. This parameter must have one of values listed in the StatusStyleFlag ITEMIZE structure.
IStatusBar INTERFACE,COM
ApplyStyle PROCEDURE(<;*IStatusStyle>)
Applies parameters of the passed style to the status bar.
The interfaces are planned to be available in a future release
NumZones PROCEDURE(),UNSIGNED
Returns the number of zones in the status bar.
GetZone PROCEDURE(UNSIGNED idx),*IStatusZone
Returns a reference to an object representing the zone with the passed index. The index value is 1-based. If the passed index is 0 or greater than the total number of zones, a NULL reference is returned.
AddZone PROCEDURE(UNSIGNED idx, SIGNED),*IStatusZone ! 2nd Parameter: ZoneKind
Creates the object implementing the zone of given kind and inserts it at position specified by first parameter. If position parameter is out of range 1..<;number of zones>, the created zone is appending to the end of list of zones. The position value is 1-based.
DeleteZones PROCEDURE(UNSIGNED start, UNSIGNED cnt = 1)
Destroys the number of zones equal to the second parameter starting from the position given by the first parameter. By default, the only zone is creating. If second parameter is 0, all zones after the passed position are destroyed.
* Notes: DeleteZone can be used to delete all zones from the status bar. This leaves an empty status bar. Freeze PROCEDURE() Freezes the status bar to avoid multiple redrawings on multiple changes to zones. Unfreeze PROCEDURE() Unfreezes previously frozen status bar. More than one level of freezing is possible, therefore the number of calls to Unfreeze must be equal to number of calls to Freeze. SetClickCallback PROCEDURE(<;StatusClickCallback>, LONG param = 0)**
Sets a callback function that is invoked if the mouse is clicked or double clicked within content rectangle of any zone. The 1-based index of clicked zone is passed to the callback function as a parameter. The KEYCODE() function can be used to determine which mouse button has been clicked.