| **Navigation:**  [[introduction.htm|Language Reference]] > 9 -  Window and Report Attributes > Window and Report Attributes >STATUS INTERFACES | [[status set status bar .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[std set standard behavior .htm|{{btn_next_n.gif|Next page}}]] | | || ===== (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.