Clarion Community Help

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.

---

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 &amp;= BarStyle.GetFont()          ! Get the font from style Zone.SetFont (ZoneFont)                ! Set the clone of font to zone ZoneFont &amp;= 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.