tooltip.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: tooltip.hpp,v $
 * PRODUCTION Revision 1000.1  2004/06/01 19:52:39  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.4
 * PRODUCTION
 * ===========================================================================
 */

#ifndef __GUI_WIDGETS_FL___TOOLTIP__HPP
#define __GUI_WIDGETS_FL___TOOLTIP__HPP

/*  $Id: tooltip.hpp,v 1000.1 2004/06/01 19:52:39 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Authors:  Andrey Yazhuk
 *
 * File Description:
 *  Tooltips service implementation.  
 */

#include <corelib/ncbistd.hpp>
#include <gui/gui.hpp>

#include <FL/Fl.H>
#include <FL/Fl_Widget.H>
#include <FL/Fl_Menu_Window.H>

/** @addtogroup GUI_FltkWidgets
 *
 * @{
 */

BEGIN_NCBI_SCOPE

class CTooltipWidget;

////////////////////////////////////////////////////////////////////////////////
/// ITooltipClient - client interface for CTooltip class.
/// This interface is used by "active" CTooltip, it is not required for "passive"
/// mode.  

class NCBI_GUIWIDGETS_FL_EXPORT ITooltipClient
{
public:
    /// returns "true" if client wants to dispaly a tooltip. "x" and "y"  are 
    /// cordinates of the mouse pointer
    virtual bool    TC_NeedTooltip(int x, int y) = 0;  
    
    /// Retruns tooltip string and coordinates for area tootlip associated with.  
    /// Client may choose not modify x, y, w, z, in that case tooltip will be 
    /// associated with current mouse position.
    virtual string  TC_GetTooltip(int& x, int& y, int& w, int& h) = 0;
};

////////////////////////////////////////////////////////////////////////////////
/// CTooltip - class providing tooltip service.
///
/// To enable tooltips a client needs to create an instance of CTooltip, set-up it
/// and to pass events to CTooltip::Handle() method.
///
/// CTooltip can be used in "active" or "passive" manner. "Passive" tooltip is 
/// similar to FLTK-style tooltips, it requires client to handle FL_MOVE events
/// and to activate/deactivate tooltip. "Passive" tooltips does not require client 
/// to implement ITooltipClient interface.
///
/// "Active" tooltip handles events and activates/deactivates itself when needed.
/// Client for "active" tooltip must implement ITooltipClient interfaces, but does
/// not need to handle any events or perform any calls to CTooltip instance. When 
/// "Active" tooltip needs to perform hit testing or show/hide tooltip window it
/// calls ITooltipClient functions.

class NCBI_GUIWIDGETS_FL_EXPORT CTooltip
{
public:
    /// Tooltip mode - controls behavior of tooltip window. Can be used with both 
    /// "active" and passive" tooltips.
    enum EMode {
        eHideOnMove,  /// if mouse moves tooltip hides and reappears only after delay
        eTrackOnMove, /// if mouse moves tooltip reappears immediatly in a new position
        eStayOnMove   /// if tooltip area and text remain the same - tooltip will remain on screen
        /// and will not move
    };

    CTooltip();
    virtual ~CTooltip();

    /// @name Attributes access
    /// @{
    void    SetMode(EMode mode);
    EMode   GetMode() const;
    
    float   GetDelay()  const;
    void    SetDelay(float f);

    int     IsEnabled()   const;
    void    Enable(bool b_en = true);
    void    Disable();

    int     GetFont()   const;
    void    SetFont(int font);
    
    int     GetFontSize()   const;    
    void    SetFontSize(int size);

    Fl_Color GetColor()  const;
    void    SetColor(Fl_Color color);
    
    Fl_Color  GetTextColor() const;
    void SetTextColor(Fl_Color color);
    
    const string&   GetText()   const;
    /// @}

    Fl_Widget* current();

    /// @name "Passive" tooltip interface.
    /// @{

    /// Activates tooltip for "client" widget and specifis tooltip text. 
    /// Tooltip will be active as long as mouse pointer remains in the rectangle
    /// specified by x, y, w and h (in client's coordinates).
    void    Activate(Fl_Widget* client, const string& text, int x, int y, int w = 1, int h = 1);
    
    /// Deactivates and hides tooltip, if "b_reset" is true then tooltip will reappear
    /// no sooner the after "m_Delay"
    void    Deactivate(bool b_reset = true);    
    /// @}

    /// @name "Active" tooltip interface
    /// @{

    bool    EnableActiveMode(ITooltipClient* client);
    void    DisableActiveMode();
    /// @}    

    /// Event handler - Client needs to pass events to this function.
    int     Handle(int event);
    
protected:
    bool    x_IsTooltipVisible();
    void    x_Activate(Fl_Widget* client, int x, int y, int w, int h, 
                       const string& text);    
    /// callback for timer event showing tooltip
    static void ShowTooltipTimeout(void* ptr);

    /// callback for timer event reseting "recent" flag
    static void ClearRecentTimeout(void* ptr);

    enum    ETooltipCmd    {
        eDoNothing,
        eUpdate,        
        eUpdateAndMove,
        eShowDelayed        
    };

    void    x_UpdateTooltipWidget(ETooltipCmd cmd);
    void    x_AskClientAndUpdate();    

protected:
    bool    m_bActiveMode;
    EMode   m_Mode;
    float   m_Delay; /// delay between last mouse move and the moment tooltip appears
    bool    m_bEnabled;
    
    Fl_Widget*      m_Widget;
    ITooltipClient* m_IClient;

    // attributes
    Fl_Color  m_Color;
    Fl_Color  m_TextColor;
    int   m_Font;
    int   m_FontSize;
    
    string  m_Text;    
    
    int m_X, m_Y, m_W, m_H; /// rectangular area associated with tooltip
    int m_MouseX, m_MouseY;

    CTooltipWidget* m_TooltipWidget;

    bool    m_bRecentTooltip;
    bool    m_bRecursion;
};

////////////////////////////////////////////////////////////////////////////////
/// CTooltipWidget

/// CTooltipWidget is a widget appearing as a tooltip window. It is automatically 
/// created and managed by CTooltip. Not intended for using directly.
class CTooltipWidget  : public Fl_Menu_Window 
{
public:
    CTooltipWidget(CTooltip* tooltip);
    
    /// Sets tooltip's origin in screen coordinates
    void    SetOrigin(int x, int y);

    virtual void draw();
    virtual void layout();
    virtual void show();
    virtual int     handle(int event);

private:
    CTooltip*   m_Tooltip;    
    int m_OrigX, m_OrigY;
};

END_NCBI_SCOPE

/* @} */

/*
 * ===========================================================================
 * $Log: tooltip.hpp,v $
 * Revision 1000.1  2004/06/01 19:52:39  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.4
 *
 * Revision 1.4  2004/05/11 18:55:14  dicuccio
 * Added doxygen modules info
 *
 * Revision 1.3  2004/05/03 12:47:08  dicuccio
 * Added #include for gui/gui.hpp.  gui/utils ->gui/objutils where needed.
 *
 * Revision 1.2  2004/01/08 19:46:49  yazhuk
 * Implemented "active" tooltips; refactored code, added comments
 *
 * Revision 1.1  2003/12/29 21:11:43  yazhuk
 * Initial revision
 *
 * ===========================================================================
 */

#endif