dfsstatusbar.txt

透明按钮 透明按钮 透明按钮

TDFSStatusBar v1.01

A status bar that provides many common specialized panels.  The main features
are key lock indicators (caps, num, scroll), gauges, images, ellipsis text, and
date/time.  Also, the status bar can own other components (i.e. you can drop
something on it in the IDE).


Documentation:
--------------

TDFSStatusBar:

  procedure InvalidatePanel(Index: integer);
    This method causes only the specific panel identified by Index to be
    redrawn.
  property UseMonitorDLL: boolean;
    This property indicates whether the indicator keys (Caps, Num & Scroll lock)
    should be monitored system wide or in the app only.  If set to true, your
    app will require the DFSKbMon.DLL to be present.  See the Implementation
    Notes section for more information, including how to rename the DLL.


TDFSStatusPanel:

  procedure Invalidate(RefreshNow: boolean);
    This method causes the panel to be invalidated. RefreshNow indicates whether
    the repaint should take place immediately or later when the next WM_PAINT
    message is processed.

  property StatusBar: TDFSStatusBar;
    The TDFSStatusBar that owns this panel.

  property PanelType: TDFSStatusPanelType;
    sptNormal - Nothing special, same as a regular TStatusPanel.
    sptCapsLock - Caps lock indicator.  Normal color if on, gray if off.
    sptNumLock - Num lock indicator.  Normal color if on, gray if off.
    sptScrollLock - Scroll lock indicator.  Normal color if on, gray if off.
    sptDate - Current date.  Uses DateFormat property for format of text.
    sptTime - Current time.  Uses TimeFormat property for format of text.
    sptDateTime - Current date and time.  Uses DateFormat and TimeFormat
        properties for format of text.
    sptEllipsisText - Shorten text at the end with '...' when it won't fit.
    sptEllipsisPath - Shorten by removing path info with '...' when it won't fit.
    sptGlyph - Displays a TPicture object in the panel.
    sptGauge - A progress meter.  Use GaugeAttrs to customize it.
    sptOwnerDraw - Same as the old TStatusPanel.Style = psOwnerDraw.

  property GaugeAttrs: TDFSGaugeAttrs;
    property Style: TDFSGaugeStyle;
      gsPercent - Your basic progress meter.
      gsIndeterminate - A progress indicator where the min/max are not known.
        That is, you want to show something going on, but don't know how long
        it will take.  Same concept as the Netscape status panel gauge when you
        are connecting to a site.  Use the Enabled property to start and stop
        the gauge.
    property Position: TPercent;
      A value from 0 to 100 indicating the current percentage to display for
      sptGauge panel types when the Style is gsPercent.  It the Text property
      is blank, this value will be displayed within the gauge (i.e. "51%").
      If Text is not blank, it's value will be drawn inside the gauge.  If you
      don't want any text within the gauge, just set Text to a space character.
      This property has no meaning for any other panel types.

  property AutoFit: boolean;
    Automatically adjust the width of the panel to be wide enough to display
    the information.  Note that this property has no meaning to some panel
    types, and setting it will likely result in the panel's width becoming very
    small.  For example, sptGauge has no idea how big you would want it to
    automatically become.

  property Glyph: TPicture;
    The image to show on the panel for sptGlyph panel types.  This property has
    no meaning for any other panel type.

  property DateFormat: string;
    For use with sptDate and sptDateTime PanelTypes.  This property has no
    meaning for any other panel types.  Use the same format as described in the
    Delphi Help, FormatDateTime function.  You can leave this property blank,
    and the user's short date format setting will be used.

  property TimeFormat: string;
    For use with sptTime and sptDateTime PanelTypes.  This property has no
    meaning for any other panel types.  Use the same format as described in the
    Delphi Help, FormatDateTime function.  You can leave this property blank,
    and the user's long time format setting will be used.

  property Enabled: boolean;
    Whether the panel should be enabled or not.  Disabled panels are blank.  The
    one exception to this is sptOwnerDraw.  The OnDrawPanel event fires
    regardless of the Enabled state, that way you can draw it however you like
    based on the Enabled property.

  property Hint: string;
    Hint text to be displayed for the panel.  If blank, the hint text displayed
    will be the bar's hint (if any).  For sptEllipsisText and sptEllipsisPath
    panels, the hint will be the full value of Text if this value is set to
    '...'.  You can override the value of this property by using the OnHintText
    event (see below).
    
  property OnDrawPanel: TDFSDrawPanelEvent;
    This event fires when the panel needs to be redrawn, and PanelType is
    sptOwnerDraw.  Note that TDFSStatusBar also has this event and it fires for
    any panel that needs to be drawn.  This event is intended for seperating out
    owner drawing code into events tied to a single panel, rather than having
    one big event that has to know how to draw every panel.

  property OnHintText: TDFSPanelHintTextEvent;
    This event fires when hint text is being retrieved for the panel.  When the
    event handler is entered, the current hint text, if any, will be in the
    HintText parameter.


Implementation Notes:
---------------------
  * For owner draw panels (sptOwnerDraw PanelType), the status bar's OnDrawPanel
    event fires first, and then the individual panels' OnDrawPanel events are
    fired.  You can paint the panels in whichever handler you prefer.

  * The lock indicators (caps, scroll, num) operate by using a windows hook
    (SetWindowsHookEx).  Every effort has been made to reduce the impact this
    will have on the user's system.  The hook is only active if it is needed
    (there are indicator panels), and only if the panels are enabled.  If
    multiple indicators exist (even across multiple status bars), there is still
    only one hook installed, not one hook for each.  The hook is active for the
    thread that contains the status bar, not system wide, if UseMonitorDLL is
    false; otherwise, the hook is system wide.  Setting UseMonitorDLL to false
    will lessen the impact on the user's system, but it has the side effect of
    causing the indicators to function only within the thread.  That is, if you
    switch to another app and change the Num Lock, it will not be reflected
    until you switch back. Also, if UseMonitorDLL is set to true, the
    DFSKbMon.DLL is required to be present on the system.

  * If you will be using the UseMonitorDLL property, you must include the
    monitoring DLL with your application.  It is strongly suggested that you
    rename the DLL to something specific to your app so as not to conflict with
    any others that may be on the users' system.  If you do rename the DLL, you
    need to add a line of code to your main form's or project source (DPR) file
    like this:

      DFSKbDLLName := 'MyMonitorDLL.DLL';

    You will also need the DFSKb unit in the uses clause for this to compile.
    You can include path information, but it is not necessary if the DLL will
    be in the system path or in the app's directory (suggested).  If
    UseMonitorDLL will never be set to true, you can ignore this DLL and it will
    NOT be needed by applications using TDFSStatusBar.

  * The sptDate, sptTime, sptDateTime, and sptGauge (GaugeAttrs.Style =
    gsIndeterminate only) panels require the use of a timer.  Every effort has
    been made to be conservative with the resources, however.  The timer is only
    created when there is a panel that needs it, and then only if the panel is
    enabled.  The timer is shared across all panels on a status bar that need
    it, so if you have a sptDate, sptTime and sptIndeterminateGauge on a status
    bar, there is still only one timer active.  Also, the interval of the timer
    event firing is adjusted according to what kind of panels need it.  That is,
    if you have a sptTime and a sptDate panel, the timer will fire once per
    second.  But, if you have only a sptDate (or you disable sptTime), the timer
    interval is adjusted to fire less often.

  * Collection properties (i.e. TDFSStatusPanels) don't have a built-in Object
    Inspector interface in Delphi 2 or C++Builder 1.   I'm really screwed here
    because I DON'T want to write a big monster property editor for all of the
    TDFSStatusPanel class just for D2/C1.  During beta testing, no one
    complained about this, so I have decided not to do it.  If enough people
    ask for a D2/C1 version, I will reconsider.


Known Issues:
-------------
  * Key lock indicators don't get updated correctly when they are changed from
    outside the app.  That is, if you change the state of the caps lock from
    Notepad and then switch to the app with the statusbar, it does not update to
    show the new state.  As best I can tell, this is a problem at the Windows
    API level; more a design flaw than a bug.  GetKeyState (which is used to
    find the toggled state of the indicator keys) is only updated as a thread
    reads key messages from its queue, it does not actually go out and find out
    what the real state is.  GetAsyncKeyState will go find the real state of
    the key at the time of the call, but it will not return any information
    about they toggled state; only up/down state and whether it has changed
    since the last time it was called.  I experimented with using
    GetAsyncKeyState when the app was deactivated and activated and checking to
    see if the key state had changed, but there are problems with that as well.
    GetAsyncKeyState seems to be system-wide, so it's only going to tell you if
    the key state has changed since the last time ANYTHING called it, not just
    your app.  The best I can do is force the indicator panels to update when
    a key is pressed after the app is deactivaed and then activated again.  The
    really strange part of all this is that it only happens if you use Alt-Tab
    to task switch.  If you switch apps using the mouse, it works fine.  In my
    defense, I offer this:  MS WordPad has this same bug.  :)  This only applies
    if UseMonitorDLL is false.  If using the system wide hook (the DLL), the
    indicators are monitored in every process, so the problem does not occur.


Revision History:
-----------------

1.01: + Right aligned text would draw right up to a panel's shadow.  It now
        keeps a 1 pixel border between the text and the shadow.
1.00: + Initial public release